coulomb/approval-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
approval-engine/docs/storage-operations.md
tegwick fec4eaeb1b Hold the pinned image against the repository's schema 
Schema v4 gave the deployment a silent drift surface: the pinned pair is
self-consistent, migrating to 3 and serving 3, while this repository has
moved to 4. That reads as healthy, which makes it worse than an error —
the failure is the assumption that the deployment records approver
principal type.

Document v4 in storage-operations, state in the deploy runbook that the
pin predates it, and add a test that requires the statement whenever the
release record's schema version differs from this repository's. Verified
to fail when the acknowledgement is removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HyybaE7DUXrWYrhbnESCTe

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1275879@bnt-lap001
Assistant-Session: eb464208-f821-41b2-bc5a-a6c33d92a8ad
2026-09-09 14:38:21 +02:00

2.9 KiB
Raw Blame History

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.

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.