approval-engine/docs/storage-operations.md

# Storage operations

Production uses one SQLite writer on persistent `ReadWriteOnce` storage.
Production serve disables automatic migration and refuses schema drift or an
in-memory database.

```bash
approval-engine migrate --db /data/approvals.sqlite
approval-engine verify --db /data/approvals.sqlite
approval-engine backup --db /data/approvals.sqlite --output /backup/approval.sqlite
```

Migration is repeatable and sets an explicit `PRAGMA user_version`. Backup uses
SQLite's online backup API, verifies `PRAGMA integrity_check`, writes mode 0600,
and refuses to overwrite a target.

Restore is a stopped-single-writer operation:

1. Stop the StatefulSet and confirm no approval-engine or migration process has
   the PVC open.
2. Preserve the failed database and its `-wal`/`-shm` companions for analysis.
3. Copy the verified backup to a new database path with owner 10001 and mode
   0600. Do not merge a backup with old WAL files.
4. Run `verify`, then `migrate` if the release schema is newer, then `verify`
   again.
5. Start exactly one replica and prove approval/entry/outbox counts, readiness,
   claim retrieval, and idempotent audit drain before reopening callers.

Approval mutation and outbox insertion share `BEGIN IMMEDIATE` and one commit;
a failed outbox insert rolls the mutation back. Delivery occurs afterward and
does not roll back a committed mutation.

## Schema v3 — declared PDP-path intent

`GH-DEC-2026-008` added `approvals.pdp_path` (INTEGER NOT NULL DEFAULT 0).
Migration is the usual additive `ALTER TABLE`; run `approval-engine migrate`
before a production start, which refuses an unmigrated store.

Legacy rows default to `0`. Intent is **not** back-filled from a recorded
`pdp_digest`: an approval issued before the ruling was never declared for the
PDP path, and inferring the declaration from an incidental digest would
manufacture a statement nobody made. Such approvals stay usable by consumers in
this engine's own vocabulary and are simply not usable on the PDP path — which
is the ruling's intended cost, not a migration defect.

## Schema v4 — recorded approver principal type

`entries.principal_type` (TEXT, nullable) records what kind of principal bound
an approval, taken only from the verified token. Migration is the usual additive
`ALTER TABLE`; run `approval-engine migrate` before a production start, which
refuses an unmigrated store.

Legacy entries stay `NULL` and are **not** back-filled — the same reasoning as
`pdp_path` in v3. An entry written before this column existed carries no
verified statement about the principal that made it, and reading `user:`-shaped
`subject_id` values as `human` would manufacture approver evidence nobody
presented. A `NULL` here means *unclassified*, never *human*.

Downgrade is not supported: an older server refuses the store on the version
check rather than reading the column, which is the intended direction. Restore
from a v4 backup onto a v3 release requires re-pinning forward, not editing
`user_version`.


## Schema v5 — explicit human-control declaration

GH-DEC-2026-016 adds `approvals.human_control`, constrained to 0 or 1, with default
0. Existing objects remain undeclared regardless of recorded approver types;
there is no retrospective declaration or change to their five-field binding
digest. A successor inherits the declaration. Linking an existing successor with
a different declaration conflicts and rolls back the parent transition.

New human-control entries require verified type human at the engine boundary.
The declaration is retained on object/claim and audit events. Claim and consume
also refuse inconsistent persisted human evidence. Tests cover a persistent v4
upgrade and preservation, signed API refusal, quorum and outbox rollback. Take
and verify the existing backup before migration. The old v3 image must not serve
a v5 database; rollback requires the matching pre-migration backup and the
existing single-writer recovery procedure. No live database is migrated by the
source test run.


## Schema v6 — verified tenant provenance

`entries.tenant_source` is nullable TEXT, recording only the verified issuer claim
(`directory`, `registration`, or `default`). Missing claims and pre-v6 entries
stay NULL; migration never infers membership or changes bindings, quorum,
human-control declarations, or existing outbox evidence. New issuance/use
threshold evidence retains this field, including null for unknown provenance.

Migration is additive and must precede serving the v6 release. The deployed
schema-v5 image remains pinned; source changes do not migrate production.
Publish/scan and pin the same v6 artifact for both containers, take and verify
the pre-migration backup, and obtain per-change rollout approval. An old v5
server refuses a v6 store; rollback uses the verified pre-migration backup with
the matching release and the stopped single-writer restore procedure above.

## Schema v7–v9 — assurance floor, actor consumption, revoker evidence

v7 adds nullable `approvals.required_assurance`. v8 adds `approvals.actor_consumes`
(0 or 1, default 0). v9 adds nullable `revoked_by_subject`,
`revoked_by_principal_type`, `revoked_by_assurance`, and `revocation_reason`.
Migration is additive. Legacy rows stay NULL, and `actor_consumes` stays 0.
Nothing is inferred for old approvals, entries, or revocations.

A v6 server refuses a v9 store. Rollback uses the verified pre-v9 backup with
the matching v6 release and the stopped single-writer restore procedure above.
Take and verify that backup, and open an isolated copy with the new image,
before the sole pod is replaced. That rollout completed on 2026-11-07.
Receipt: `docs/evidence/2026-11-07-schema-v9-rollout.json`.