Back up and restore

Heliast does not back anything up for you. There is no backup job, no snapshot call and no restore tool in the product today, and no recovery target is promised. This page says what holds state, what to protect, how to restore, and the hazards that are specific to a tamper-evident ledger. The ledger hazards were checked by Heliast's engineers against a test PostgreSQL database; none of this has been run in a real estate or on a real cluster.

What to protect

Item	Where it lives	Back it up?	How
The ledger and the virtual keys	The PostgreSQL database (a single replica on a persistent volume). The ledger tables are `audit_events` and `chain_state`; the keys are `virtual_keys` and `virtual_key_events`, in the same database	Yes, together	A logical dump (`pg_dump -Fc`, restored with `pg_restore --no-owner`) or a volume snapshot. Heliast names no tool; use your own database backup
The signed anchors	The audit service's anchor directory (`AUDIT_ANCHOR_DIR`, files named `anchor-<sequence>.json`). In the chart it shares a volume with the write-ahead buffer	Yes, off the cluster, and keep every file	Copy the directory (`rsync` or `cp` of `anchor-*.json`) to storage the database's administrators cannot write to. No copy-out job exists
The anchor signing key	`AUDIT_ANCHOR_KEY`, by default `anchor.key` in the audit service's data directory	Yes, kept apart from the ledger backup	Store it in your secret store. If the file is missing when the audit service starts, it creates a new key without warning
The anchor public key	Pinned in the verifier build, or given with `SOVEREIGN_ANCHOR_PUBLIC_KEY` or `-anchor-public-key`	Record it	Get it from your Heliast contact
The write-ahead buffer	A volume on the audit service (`wal.log`, `wal.checkpoint`, and `quarantine.jsonl`)	Optional	It holds only events not yet written to the database, and is emptied once they are. It is not a backup of the ledger
Your policy	Your own Git repository	Git is the backup	Mirror the repository. A policy rollback is a Git revert (get and update Heliast)
Your catalogue records and your own models' records	Files you keep in Git; the hook reads them from a ConfigMap or directory	Git is the backup	Keep them in your repository
Secrets (database connections, the admin, query, intake and hook tokens)	Created outside the chart, in your secret store	Your secret store's backup	None of them is in Git
Helm values, and the Terraform state	Your own Git, and local to the machine that runs Terraform	Yes	Terraform's modules ship with no remote backend, so the state is local; configure your own backend
Model weights	The weights volume	No	Pull them again and check them by digest (using an admitted model). A snapshot only saves time
The licence file	Wherever you keep it	Keep the file Heliast issued	`licence-validate -file <file>` checks it offline
Compare results	The console's results directory (`UI_COMPARE_RESULTS_DIR`)	Yes, if you keep run history	Copy the directory
The vector store, if you use retrieval	Its own volume	Yes, if you use it	Use its snapshots

Virtual key secrets are not stored anywhere: only a fingerprint is kept, and the secret is shown once at issue.

Restore, in order

Put the anchor key back first. Restore anchor.key to its path before the audit service starts. Otherwise the audit service makes a new key, and its next anchor will not match the key you pinned.
Restore the database into an empty database. Then check the database roles: the audit writer role must have only the insert and select rights the ledger's schema gives it.
Restore the secrets, then start the audit service, the hook and the router. The audit service refuses to start without its intake token.
Restore the anchors directory, then verify the ledger against it:

`` audit-verify -anchor-dir <the restored anchors> -require-anchor -anchor-public-key <hex> ``

It reads the database from SOVEREIGN_DB_DSN or SOVEREIGN_AUDIT_DSN. Always give -anchor-dir and -require-anchor: without them the check passes and silently skips the anchor. Exit 0 means the chain verified. Every failure exits 2, a divergence included.

Run the reconcile job (auditd reconcile) and read the audit service's /metrics for sovereignai_audit_completeness_ratio and sovereignai_audit_wal_*.
Check the virtual keys. See the last hazard below.

Ledger hazards

A ledger that detects tampering also reports a restore as tampering. Know these before you need them.

Restoring a snapshot older than the latest anchor fails verification. If the anchor covers row 10 and you restore a database that stops at row 5, audit-verify exits 2 with "anchored row seq 10 is missing" and "ledger head seq 5 is below the anchored watermark 10: rows after the anchor were deleted". It cannot tell a restore from deletion, and it says "deleted". That is the correct and expected result. Write down that you restored, why, and the sequence numbers involved.
Only the latest anchor is ever checked, so the next anchor can hide a lost tail. If new traffic passes the old anchor's row number and the next anchor is exported, verification can turn green while the old anchor file still sits in the directory unchecked. After a restore, keep every older anchor, and check them yourself against the restored ledger.
Events that arrived after the snapshot are lost. The write-ahead buffer is emptied once events reach the database, so it cannot refill a restored database. It helps only with events not yet drained. Replaying the buffer onto a restored database does not duplicate events already present: the append is idempotent on the event id.
A lost anchor key means a new key and a refused anchor. audit-verify reports "signed by ..., not the pinned key" and exits 2.
Do not run a restored copy beside the live one. Both would hold the same anchor key and sign competing anchors. The chart runs the audit service as one replica for this reason.
Gaps lower the completeness metric. A restore that leaves gaps in the sequence trips AuditLedgerCompletenessBreach, even where audit-verify stays green, because it checks the hash links and not that the numbers are contiguous.
An older snapshot also reverts virtual keys. The keys are in the same database. A key you revoked after the snapshot becomes valid again, and keys issued after it are gone. After any restore, list the keys and revoke again what should be revoked.

Retention

The ledger's retention period is a setting (2,555 days in the reference configuration). There is no supported way to prune old rows: the database blocks deletes, and a verifier cannot start from a pruned beginning. Anchors do not help with pruning. Plan storage for the whole retention period. Heliast never deletes an anchor.

What is not covered

No recovery time or recovery point is promised. A disaster recovery design (streaming replication of the ledger database) exists on paper only; it is not built.
Where the "external" anchor destination goes, and who holds the anchor key, are decisions for you. Ask your Heliast contact how the key is held in your estate.
The audit service's anchor-export call (POST /internal/anchor) is on the intake port; keep that port reachable only from inside the cluster (network and ports).