Backup - API reference

Signalled when a decrypted backup container fails its fixed-width parse — a bad magic/version, a length field that overruns the buffer, trailing bytes, or an unknown member kind. It is raised BEFORE any member is dispatched, so a corrupt container never writes partial state.

Root of the backup subsystem's condition hierarchy. Every fault raised while assembling, sealing, opening, or unpacking a backup is a subtype of this, so a caller can catch the whole family in one clause without also swallowing unrelated errors.

Signalled by ASSEMBLE-BACKUP-CRITICAL when the owner seed keyfile is absent. The seed is the one member of the backup-critical set with no legitimate absent case, so it is the floor under the set: its absence is refused before anything is collected and before mercer is asked to seal, because an artifact carrying no owner seed protects nothing while reading as a success. The report names the resolved keyfile path, since the operator's real fault is nearly always a wrong data root rather than a missing file.

Signalled when a restore is asked to land into a StateDirectory whose data root already holds valis state — an owner keyfile, a store HEAD, or a pub-store block directory. A restore is all-or-nothing into a pristine target: refusing up front, before any byte is written, avoids the half-replaced state a mid-restore failure would otherwise leave — exactly the crash-loop shape (a HEAD with no keyfile or blocks) a partial restore produces.

(backup-owner-seed-keyfile condition)

Undocumented: this exported symbol needs a docstring.

(restore-target-clashes condition)

Undocumented: this exported symbol needs a docstring.

(restore-target-state-dir condition)

Undocumented: this exported symbol needs a docstring.

(assemble-backup-critical &key keyfile head-path acme-store-path)

Collect the backup-critical set — owner seed, store HEAD, the reachable store blocks, and the whole ACME store tree — into a single versioned, length-prefixed plaintext container, and return (values container member-count). Each member carries a kind tag, a length-prefixed name, and length-prefixed bytes so %unpack-container is fixed-width fail-closed. Holds NO crypto: the caller hands the container to mercer's seal-backup.

The HEAD names a content-addressed root tree; the pointer alone is useless on a fresh host. So when a HEAD is present, the same HEAD is decoded to its root entry, the block DAG it reaches is walked (collect-reachable-scores), and every referenced block is read from the store beside HEAD (pub-store/) and carried as a block member named by its hex score.

The owner seed is MANDATORY and is the floor under the whole set: when the keyfile is absent this signals BACKUP-OWNER-SEED-MISSING before collecting anything, so a seedless container never reaches seal-backup. Every other member is optional and an absent source is skipped, because those absences are real instance states rather than faults: a pre-issuance instance has no ACME store yet, and a genesis instance has no HEAD and therefore no blocks.

(backup-to-artifact passphrase out-path)

Operator backup: seal the production backup-critical set to OUT-PATH under PASSPHRASE. Returns the member count.

(default-source-locations)

The production on-disk locations a backup reads from, as (values keyfile head-path acme-store-path): the owner keyfile and the store HEAD under the valis data root, and the operator's configured ACME store (or the data-root default).

(read-backup passphrase in-path &key keyfile head-path acme-store-path)

Read the envelope at IN-PATH, open it under PASSPHRASE via mercer's open-backup — a wrong passphrase or a tampered/corrupt envelope fails closed there before any write — then unpack the container fail-closed and dispatch every member to the fresh StateDirectory: the seed via custody's 0600 write, the HEAD file, the ACME store tree, and every store block through the block store's own verified write path (rooted at pub-store/ beside the restored HEAD). The whole container is unpacked BEFORE any member is written, so a corrupt container writes no partial state. Emits a substrate restore.completed event (path + member count only). Returns the member count.

(restore-from-artifact passphrase in-path state-dir)

Operator restore: open the artifact at IN-PATH under PASSPHRASE and land its members into the fresh StateDirectory STATE-DIR, then project the plaintext owner.did and store.head witnesses into the state-dir root (the byte-faithful witnesses the restore is compared against). A restore demands a pristine target: if the state-dir data root already holds valis state (an owner keyfile, a store HEAD, or a pub-store block directory) the restore refuses UP FRONT — before the artifact is opened and before a single byte is written — signalling RESTORE-TARGET-NOT-PRISTINE, so a non-pristine node is never left half-replaced. Returns the member count.

(state-dir-locations state-dir)

The on-disk locations a restore writes into under a fresh StateDirectory, as (values keyfile head-path acme-store-path): the owner keyfile, the store HEAD under pub-store/, and the ACME custody store. A restore is given the unit's StateDirectory, which the resident treats as its XDG data-home and appends valis/ to reach its data root; restore composes its targets from that same data root so a restored node reads exactly the members a restore wrote.

(write-backup passphrase out-path &key keyfile head-path acme-store-path)

Assemble the backup-critical container, seal it under PASSPHRASE via mercer's seal-backup, and write the portable envelope to OUT-PATH. Emits a substrate backup.written event carrying only the artifact path and the member count — never key bytes. Returns the member count. Holds no crypto: the KDF and AEAD live in mercer, reached by late-resolved symbol-call.