Spec 20: enterprise DB integration contract (discovery/design only)

Browse Source

Design-phase contract for moving UmbraAudio + the future UmbraTrans review UI
onto the shared enterprise PostgreSQL database without interrupting audiobook
production. No database contacted, no migration SQL, no production data written.

Verified against the real schema (infra/postgres/001_control_plane.sql, 13
tables, all identity/tenancy/audit) and the full current audio codebase.

Key findings:
- No local accounts exist to migrate; the only identity traces are the literal
  string 'user' in two review tables. One canonical enterprise user.
- No durable utterance identity: artifacts are named by mutable
  utterance_index (ch{N}/utt_{idx:04d}.wav), which spec 18 forbids as a
  durable ID. Proposes a content-addressed source_unit_key recorded at
  generation time, leaving on-disk names untouched for continuity.
- BLOCKER: umbracontrol_worker matches zero RLS rows and cannot attribute an
  audit event, so worker identities are unrepresentable. Needs
  service_identities + job_leases, not a GUC workaround.
- RLS machinery is owned by the postgres superuser because the bootstrap pipes
  the schema through psql -U postgres. FORCE ROW LEVEL SECURITY would cause
  42P17 infinite recursion; recorded as a load-bearing invariant.
- 10 verified application defects, incl. download traversal via string-prefix
  containment and raw upload filenames.

No UmbraAudio behaviour changes. Adapter boundary keeps SQLite+filesystem as
the default repository so cutover is a flag flip and always reversible.

...

This commit is contained in:

B.D. Murphy

2026-09-25 19:05:13 -07:00

parent b224c5f10f

commit e8944fcd88

1 changed files with 1856 additions and 0 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download Patch File Download Diff File Expand all files Collapse all files

1856

specs/20-enterprise-database-integration.md Normal file

File diff suppressed because it is too large Load Diff