dot-iu-cutter v0.4 — Real DB Adapter Design Report

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.4-db-adapter-design/dot-iu-cutter-v0.4-real-db-adapter-design-report-2026-05-17.md
revision: r1
date: 2026-05-17
author: Agent (Claude Code CLI, Opus 4.7 1M)
verifier: GPT (review pending — this report routes the package in)
phase: v0.4 — REAL DB ADAPTER DESIGN (rollup report)
opened_by: GPT credential-execution review = PASS + explicit User
  "v0.4 real DB adapter DESIGN ONLY" prompt.
status: design_only_pending_gpt_review

⛔ DESIGN ONLY. No code modified, no DB connection, no secret read, no .env edit, no dry-run executed, no production action, no CUT/VERIFY, no deploy, no self-advance. This report only routes the 8-doc design package to GPT.

---

§1 — Package Delivered (8 docs, this directory)

1 …-real-db-adapter-design-master-2026-05-17.md          purpose/stance/contract
2 …-connection-and-secret-loading-design-2026-05-17.md   env/secret/pool/no-leak
3 …-transaction-mapping-design-2026-05-17.md             phase→table→txn boundaries
4 …-principal-routing-design-2026-05-17.md               phase→principal/SoD/matrix
5 …-db-adapter-error-and-rollback-design-2026-05-17.md   SQLSTATE/retry/rollback
6 …-db-adapter-dry-run-test-plan-2026-05-17.md           gated plan (NOT executed)
7 …-db-adapter-risk-review-plan-2026-05-17.md            risk class + gate ladder
8 …-real-db-adapter-design-report-2026-05-17.md          this rollup
all uploaded; design-only; mutually consistent; faithful to controlling files.

§2 — Recommended Adapter Design (summary)

RealPostgresAdapter = drop-in replacement for InMemoryDryRunAdapter against
  the SAME PASSed DBAdapter ABC (CutterRuntime unchanged; only construction
  differs). psycopg3 sync; discrete connect kwargs (NO URL); autocommit OFF;
  one connection per phase txn from a small per-principal pool (≤ CONN_LIMIT
  2). Inherits skeleton guarantees: _assert_writer, append-only
  (no DELETE/TRUNCATE/DDL/GRANT), one non-nested atomic txn. Adds NO method
  the ABC lacks. ProductionDBAdapter stays refusing-to-construct until a
  future authorized code cycle implements this against a GPT-PASSed dry-run.

§3 — Recommended Env Vars & Loading Discipline

identity+password (LIVE, unchanged): DOT_CUTTER_EXEC_DB_USER,
  DOT_CUTTER_EXEC_DB_PASSWORD, DOT_CUTTER_VERIFY_DB_USER,
  DOT_CUTTER_VERIFY_DB_PASSWORD
connection params (TO BE ADDED in a separate authorized .env cycle — NOT
  now): DOT_CUTTER_DB_HOST, DOT_CUTTER_DB_PORT, DOT_CUTTER_DB_NAME,
  DOT_CUTTER_DB_SSLMODE  (shared, non-secret, no password)
discipline: read from process env only (never open .env); fail closed on any
  missing key (no defaults/fallbacks); principal-scoped load (one adapter
  never sees the other's password); password never logged/repr'd/argv/URL/
  KB/git; no DSN-with-password env key; rotatable with no code change.
NO recommended DOT_CUTTER_*_DB_DSN key (keeps password an isolated token).

§4 — Recommended Transaction Boundaries

TXN-MARK    cutter_exec   : entry+history(+dep*)(+sweep)              1 atomic txn
TXN-REVIEW  cutter_exec   : envelope+unit_block+review_decision
                            (+supersede stamp)+status+history          1 atomic txn
TXN-CUT     cutter_exec   : exec-sig+change_set(verifier_sig NULL)+
                            affected_row+status+history                1 atomic txn
TXN-VERIFY  cutter_verify : verify_result+verifier-sig
                            (+compensating+escalation on fail)+
                            status+history                             1 atomic txn
isolation   READ COMMITTED default; SERIALIZABLE for CUT & VERIFY.
guard       status CAS (UPDATE … WHERE status=expected) + xact advisory
            lock on entry_id + idempotency keys → safe for N workers,
            bounded by CONNECTION_LIMIT 2/principal.
each phase commits independently/resumably; no cross-phase txn; no nesting.

§5 — Risk Class

STANDARD-HIGH. No CRITICAL because this phase performs nothing and the live
PG grant matrix + append-only schema are independent server-side backstops.
Not merely STANDARD because credentials are now real/privileged; the chief
residual hazards (secret leak, cross-lane write) are design-controlled here
but only provably closed at code-review + dry-run gates. Defence-in-depth:
every hazard sits behind ≥2 independent controls.

§6 — Blockers

before CODE authoring:
  B-A1 add 4 connection .env keys (separate small GPT-reviewable cycle)
  B-A2 GPT design PASS of THIS package (gate G0)
  B-A3 resolve DA-2/3/5/7/8/12 (code-shape-determining decisions)
  B-A4 explicit code-authoring prompt
  B-A5 ProductionDBAdapter remains refusing until code GPT-PASS (G3)
before PG-BACKED DRY-RUN:
  B-D1 connection .env keys present
  B-D2 RealPostgresAdapter code authored
  B-D3 code GPT-PASSed
  B-D4 dry-run plan GPT-reviewed
  B-D5 isolated-env restore runbook authored
before PRODUCTION binding / CUT / VERIFY / deploy:
  fully blocked behind gates G3..G9; not in scope of any cycle until reached
ALL BLOCKERS OPEN. Nothing is runnable now.

§7 — Open Decisions for GPT (DA-1 … DA-17)

DA-1  add the 4 connection .env keys via a separate cycle — confirm shape
DA-2  sslmode require vs verify-full                         rec require→verify-full
DA-3  driver psycopg3 sync vs asyncpg                        rec psycopg3 sync
DA-4  post-connect current_user==principal assert            rec INCLUDE
DA-5  pool max default/ceiling within CONN_LIMIT 2           rec 1 / 2
DA-6  multi-worker / external pooler strategy                rec decide at G7
DA-7  advisory xact lock + CAS vs CAS only                   rec BOTH
DA-8  SERIALIZABLE scope CUT/VERIFY vs all four              rec CUT/VERIFY only
DA-9  rotation runbook ownership                             rec separate ops cycle
DA-10 rolled-back-MARK sweep_log persistence semantics       rec own-committed only
DA-11 re-review/re-verify replay determinism criteria        rec write-once no-op
DA-12 capability-assert source frozen const vs runtime check rec const + advisory check
DA-13 retry bounds                                           rec 5/200ms/5s/jitter
DA-14 53300 disposition                                      rec bounded retry→escalate
DA-15 VERIFY-fail escalation by cutter_verify                rec accept (SoD intact)
DA-16 unknown SQLSTATE                                       rec STOP+escalate
DA-17 production secrets in dry-run                           rec FORBIDDEN unless
                                                                  GPT explicit

§8 — Boundary Confirmation

performed_this_phase: authored + uploaded 8 design documents.
NOT performed: code change (689e53e untouched; ProductionDBAdapter still
  refuses), DB connection, secret read/print, .env edit, dry-run (any),
  production action, CUT, VERIFY, deploy, runtime binding, Directus/RLS/
  Qdrant change, self-advance.
next: GPT review of this design package (gate G0).
agent_self_advance: PROHIBITED.

End of real DB adapter design report (design only; package complete; next = GPT review; self-advance PROHIBITED).