MDBX Storage and Sync Specification

Version: MDBX-1-DRAFT

Defines container strategy, persistence rules, incremental updates, sync model, and attachment storage behavior.

1. Container strategy

MDBX should use a portable single .mdbx vault file. Preferred internal engine baseline: SQLite + custom encryption layer.

2. Storage goals

Layout MUST support:

• append-friendly writes
• partial updates
• crash recovery
• attachment metadata and content indirection
• history and conflict metadata
• migration hooks

3. Minimum logical tables

At minimum include:

• projects, entries, attachments, attachment_chunks
• commits, commit_parents, device_heads, branches
• tombstones, snapshots, settings, key_epochs

4. Project and attachment rules

• projects is mandatory.
• entries must reference project_id.
• attachments is mandatory from v1.
• attachment metadata and attachment content must be decoupled.

5. Write-path requirements

Small daily edits MUST NOT trigger logical full-vault rewrites. Typical write path should update only changed rows, append commit/oplog records, and avoid touching unrelated attachment payload.

6. History and conflicts

MDBX MUST keep Git-like history and causal metadata. Conflict detection cannot rely only on timestamps. Same-secret-field concurrent edits MUST become explicit conflicts.

7. Snapshot and recovery

Implementations MUST support recovery from sync interruption and partial corruption using replay and/or snapshots.

8. Attachment modes

Define at least:

• embedded-inline
• embedded-chunked
• external-hash-ref

9. Rejection rules

Non-compliant if design has no first-class projects/attachments, requires full-vault rewrites for tiny edits, cannot represent concurrent history, or lacks recovery explanations.