tegwick
fec4eaeb1b
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
62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# 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`.
|