Backup & Restore
The recovery layer, exposed through the embedded accessor, the Node binding, and five MCP
tools — so an agent can back up and restore the engine it carries.
Backup
Takes a consistent snapshot via SQLite VACUUM INTO, which is safe under concurrent
writers. Alongside the snapshot it writes a sidecar manifest recording:
- Schema version
- Migration count
- Engine version
- Size
- A SHA-256 checksum, verified after writing
Restore
Restore is deliberately conservative. It:
- Verifies the checksum from the manifest.
- Refuses backups newer than the running binary — you cannot restore a future schema into an
older engine.
- Refuses to overwrite a non-empty target without an explicit flag.
- Refuses to replace the database the instance currently has open.
- Swaps atomically — temp file, fsync, rename.
Portable export and import
Streams a versioned JSON envelope across core commerce and finance domains. The round trip
is proven by an export → import → re-export acceptance test.
Import is content-preserving, not identity-preserving. Repository create methods mint new
IDs, so foreign keys are remapped in dependency order. For identity-preserving disaster
recovery use a backup/restore, not export/import.
Export coverage
Export covers core commerce and finance domains. Returns, invoices, payments, and bills are
export-only — their state-machine history cannot be replayed through a single create.
Coverage is documented in the module docs.
Choosing between them
