metal-kompanion/docs/sync-manifest.md

E2EE Sync Manifest (Draft)

Goals

• Multi-device E2EE sync with append-only event log.
• Minimal metadata on server (sizes, hashes, timestamps).

Event Types

• item.upsert (id, namespace_id, revision, metadata, content_ref?)
• item.delete (id)
• chunk.add (chunk_id, item_id, ord, text_ref?)
• chunk.remove (chunk_id)
• embedding.add (chunk_id, model, dim, vector_ref?)

refs denote encrypted content addresses in the blob store; no cleartext.

Conflict Rules

• Items: last-writer-wins per field; later CRDT as needed.
• Deleted beats update after a window.

Keys

• Device enrollment shares wrapped keys (mechanism TBD).
• Rotation supported via manifest updates and re-wrap.

MCP Surfaces

• kom.cloud.v1.sync.push / pull
• kom.cloud.v1.backup.upload / restore
• kom.local.v1.backup.export_encrypted / import_encrypted

Open Questions

• Chunking granularity vs. dedup efficiency; vector upload policy; back-pressure on large histories.