dot-iu-cutter v0.4 — DB Adapter Risk & Review Plan

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.4-db-adapter-design/dot-iu-cutter-v0.4-db-adapter-risk-review-plan-2026-05-17.md
revision: r1
date: 2026-05-17
author: Agent (Claude Code CLI, Opus 4.7 1M)
phase: v0.4 — REAL DB ADAPTER DESIGN (companion to design-master)
status: design_only_pending_gpt_review

⛔ DESIGN ONLY. No code, no connection, no execution. This is the risk framing + the review/gate ladder for the FUTURE cycles, authored now.

---

§1 — Risk Class

overall: STANDARD-HIGH
why_not_CRITICAL:
  - this phase performs NOTHING: no code, no connection, no secret, no run.
  - the live PG grant matrix is an INDEPENDENT server-side backstop: even a
    buggy future adapter cannot write outside 33+3 tuples (42501).
  - the schema is append-only with no DELETE/TRUNCATE/DDL grant to either
    cutter principal — a defect cannot erase or corrupt history, only fail
    or (at worst) add a refused/rolled-back attempt.
  - cutter_ro/Directus/RLS untouched by design; production data = 0 rows.
why_not_merely_STANDARD:
  - the credentials are now REAL and privileged-for-writes; the chief
    residual hazards are (a) secret leakage via a logging/repr/DSN mistake
    and (b) a routing bug that attempts cross-lane writes. Both are
    design-controlled here but only PROVABLY closed at code + dry-run review.
risk_posture: the design pushes every hazard behind at least two independent
  controls (code guard + server matrix; routing table + capability assert +
  PG; env-scoped secret + no-URL + no-log). Defence in depth is the stance.

§2 — Hazard Register

H-1 secret leakage (log/repr/DSN/argv/KB/git)   sev HIGH
  controls: doc2 L-4 no-leak, no-URL discrete kwargs, principal-scoped load,
  error doc §5 names-only; dry-run G-1/G-2. Residual until dry-run G-PASS.
H-2 write outside least-privilege matrix          sev HIGH
  controls: routing table + capability assert + PG 42501 backstop; error
  doc treats 42501 as STOP (no escalate-around). Residual: a routing bug —
  closed by dry-run B-1..B-6,C-1.
H-3 cross-phase / cross-principal credential reuse sev HIGH
  controls: per-principal isolated pools, construction-bound principal,
  principal-scoped secret load. Residual: closed by dry-run B-6.
H-4 partial commit / torn phase                    sev MED
  controls: one atomic txn/phase, autocommit off, conn-loss = clean abort.
  Residual: closed by dry-run E-1..E-2.
H-5 duplicate / double-apply on retry              sev MED
  controls: idempotency keys, 23505→dedup, status CAS, advisory lock.
  Residual: closed by dry-run D-1..D-3,E-3.
H-6 connection-limit exhaustion (CONN_LIMIT 2)     sev MED
  controls: per-principal pool ≤2, 53300 bounded backoff, no 3rd conn.
  Residual: closed by dry-run (53300 induced) + future-pooler DA-6.
H-7 silent work drop                               sev MED
  controls: exhaustion → escalation entry + history (NEEDS_HUMAN).
  Residual: closed by dry-run E-4.
H-8 append-only violation / physical undo          sev MED
  controls: skeleton AppendOnlyViolation + no DELETE/TRUNCATE grant;
  semantic fix = forward compensating set only. Residual: dry-run B-3,F-1.
H-9 wrong/rotated credential lockout               sev LOW-MED
  controls: 28xxx = STOP names-only, no retry; rotation = separate cycle
  no code change (doc2 L-7). Residual: dry-run G-2.
H-10 isolation/serialization anomaly on concurrent  sev MED
  same-entry phases
  controls: SERIALIZABLE on CUT/VERIFY + CAS + advisory lock; 40001 retry.
  Residual: closed by dry-run E-3 + DA-7/DA-8 resolution.

§3 — Review / Gate Ladder (the path to production)

G0  (NOW)  this design package → GPT review.            ← current gate
G1  GPT design PASS → authorize: add 4 connection keys to .env
           (separate, small, GPT-reviewable change). [B-A1/B-D1]
G2  authorize RealPostgresAdapter CODE authoring (design-bound, no
           connection, ProductionDBAdapter-replacement, dry-run-safe).
G3  GPT CODE review/PASS of RealPostgresAdapter (parity with skeleton ABC,
           no-leak grep proofs, guard tests).
G4  GPT review of the dry-run TEST PLAN (this package doc 6) + isolated-env
           runbook.
G5  authorize + RUN the PG-backed dry-run (isolated env, fake roles/secrets).
G6  GPT review of dry-run RESULT.
G7  authorize a production COMMAND-REVIEW package for runtime binding.
G8  GPT review of command-review.
G9  explicit sovereign prompt → production runtime binding / first real
           CUT/VERIFY (still its own gated cycle).
each arrow = explicit prompt + GPT PASS. NO step is self-advancing.

§4 — Blockers

before CODE authoring:
  B-A1 4 connection .env keys defined+added (separate cycle)
  B-A2 GPT design PASS of THIS package (G0)
  B-A3 DA-2/DA-3/DA-5/DA-7/DA-8/DA-12 resolved (driver/sslmode/pool/locking/
       capability-assert) — code shape depends on them
  B-A4 explicit code-authoring prompt
  B-A5 confirmation ProductionDBAdapter stays refusing until G3
before PG-BACKED DRY-RUN:
  B-D1..B-D5 (dry-run plan §6) all OPEN
before PRODUCTION binding / CUT / VERIFY / deploy:
  fully blocked behind G3..G9; out of scope of every cycle until then

§5 — Open Decisions Consolidated (for GPT)

DA-2  sslmode: require (min) vs verify-full (+CA env)         rec: require→verify-full if chain avail
DA-3  driver: psycopg3 sync vs asyncpg                        rec: psycopg3 sync (skeleton parity)
DA-4  post-connect current_user==principal assertion          rec: INCLUDE
DA-5  pool max_size default/ceiling within CONN_LIMIT 2        rec: default 1, ceiling 2
DA-6  multi-worker / external transaction pooler strategy      rec: pgbouncer-compatible, decide at G7
DA-7  advisory xact lock + CAS vs CAS only                     rec: BOTH
DA-8  SERIALIZABLE scope: CUT/VERIFY only vs all four          rec: CUT/VERIFY only
DA-9  password rotation runbook ownership                      rec: separate ops cycle, no code change
DA-10 sweep_log attempt-row persistence on rolled-back MARK    rec: persists only if own committed sweep
DA-11 re-review/re-verify replay determinism acceptance        rec: write-once, replay = no-op success
DA-12 capability-assert source: frozen inventory const vs      rec: frozen const + optional startup
      runtime information_schema cross-check                        cross-check (advisory)
DA-13 retry bounds (attempts/backoff/jitter)                   rec: 5 / 200ms / 5s cap / full jitter
DA-14 53300 disposition                                        rec: bounded retry → escalate
DA-15 VERIFY-fail escalation entry written by cutter_verify     rec: accept (SoD intact, granted)
DA-16 unknown SQLSTATE                                          rec: STOP + escalate
DA-17 production-secret-in-dry-run: forbidden unless GPT        rec: forbidden (fake roles default)
      explicitly approves

§6 — Status

risk_class: STANDARD-HIGH
this_phase: design artefacts only; no code/connection/secret/run/prod.
next: GPT review of this design package (G0).
agent_self_advance: PROHIBITED.

End of DB adapter risk & review plan (design only; no code; no connection; no execution).