Skip to main content
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.
A backup is only a backup once you have restored it somewhere:
Restore refuses to replace the database the instance currently has open, so you cannot verify a backup by restoring it over the live engine — that is the guard working, not a bug. Verify into a fresh path, as above. A backup nobody has restored is a file, not a recovery plan.

​
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.

​
Proving recovery works

A backup you have restored once is a recovery plan. A backup you restore on every release is evidence. The drill does the second:
It writes artifacts/operations-recovery/evidence.json with a summary and hash-bound logs — a restore actually performed, not a claim that one would work.
Local output from the drill is diagnostic only. Release evidence has to link the immutable CI run and its retained artifact: a hash you produced on your own machine proves the script ran there, not that the shipped build recovers. Run it locally to debug; cite the CI run to attest.

​
Choosing between them

​
Next steps

API hardening

Defaults that changed, and what refuses to start.

Embedded engine

The engine these maintenance calls run against.

Admin console

Operating the engine day to day.

iCommerce CLI

The same operations from the command line.
Last modified on August 29, 2026