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

Date: 2026-05-17 Cycle: v0.4 Real DB Adapter — CODE AUTHORING ONLY Authorization: GPT PASS of (a) connection-env-keys execution report and (b) real-db-adapter design. agent_revision_needed=false, rollback_required=false. Scope honoured: code authoring only in /opt/incomex/dot/iu-cutter/. No production DB connection, no real .env read, no .env/schema/role/GRANT change, no dry-run execution, no CUT/VERIFY, no deploy/restart, no self-advance.

---

1. Files changed

File	Change	Notes
iu-cutter/cutter_agent/db_adapter.py	+1232 / −2	Added RealPostgresAdapter + supporting types. Base DBAdapter got 2 additive lines only (self._phase=None; optional transaction(phase=None)); InMemory/Production behaviour byte-identical in effect.
iu-cutter/tests/test_real_postgres_adapter.py	new (+ file)	47 stdlib unittests; fake env + fake connection provider.

Existing classes preserved verbatim in behaviour: DBAdapter, InMemoryDryRunAdapter, ProductionDBAdapter (refusing __init__ unchanged), _pk_field, all existing error types.

Commit: 56d3732cb74d07546c938242180a434ed1067a9a — "feat(iu-cutter): v0.4 RealPostgresAdapter drop-in (code authoring, no prod)". Scoped git add (exactly the 2 files; 2 files changed, 1234 insertions(+), 2 deletions(-)). Repo /opt/incomex/dot, branch main, parent 689e53e. sha256 (deployed == local): db_adapter.py 2a6ca4f12869695ea42c4d9e2d8e6465bc0e59b0ec8b22ae2ae6d9280a2b4330; test file 78b48525d1d6a2162f7cd290fab65deadd79f43b86d8e3c116439a6621132741.

2. Test count / pass count

• Full suite on VPS (Python 3.12.3): Ran 92 tests … OK (45 pre-existing + 47 new, 0 failures, 0 errors).
• Locally mirrored run (Python 3.11.6) prior to deploy: 92/92 OK.
• New coverage maps 1:1 to the required matrix: fake-env success; missing/empty env fail-closed (key-named); secret redaction (repr/__str__/ConfigMissing/config); kwargs contain no dsn/conninfo/URL; principal routing + cross-principal refusal; isolation selection (RC vs SERIALIZABLE, strict default); identity (SELECT current_user) mismatch abort; full SQLSTATE table; run_phase STOP / RESUME / transient-retry-then-{exhaust,success} / backpressure-longer-backoff / reconnect-discard-and-retry; append-only + no DDL/GRANT helpers; CAS rowcount≠1; write-once supersede SoD; drop-in commit/rollback; outside-txn forbidden; autocommit-off; ProductionDBAdapter still refuses; zero-connection-without-txn; psycopg3-optional graceful.

3. Dependency note — psycopg3

• Driver: psycopg3, sync (import psycopg). Imported optionally at module load (_HAVE_PSYCOPG); not vendored.
• VPS currently has no psycopg3 (_HAVE_PSYCOPG=False) — the stdlib-only suite stays fully green, and test_psycopg_optional asserts the default provider raises a clear AdapterError install hint: pip install "psycopg[binary]" (runtime image, future authorized cycle). JSON adaptation uses psycopg.types.json.Json only when psycopg is present.

4. Proof: no production connection

• All tests inject a FakeProvider (connection-attempt counter) + fake env; RealPostgresAdapter.__init__ never connects (test_construction_does_not_connect, test_zero_connections_without_transaction: prov.count==0).
• The real _default_provider is the only psycopg call-site and is invoked only at _begin (phase-txn start), which no test reaches with a real provider. psycopg3 is absent on the VPS anyway.
• Module grep on VPS for open( / /opt/incomex/docker/.env / socket. / psycopg2 / asyncpg / postgres:// / PGPASSWORD → NONE_FOUND.
• ProductionDBAdapter() still raises ProductionAccessNotAuthorized (existing security tests + new test).

5. Proof: no secret read from real .env

• load_connection_config(principal, env) reads only the supplied Mapping (tests pass FAKE_ENV_*); default fallback is os.environ (process env, never a file). The module performs zero filesystem IO — no open(), no .env path literal anywhere (grep above).
• Principal-scoped: an cutter_exec adapter reads only DOT_CUTTER_EXEC_DB_* (+ shared keys); no single object holds both principals' passwords (test_exec_config_has_no_verify_password, test_exec_works_without_verify_keys).
• Secrets wrapped in _Secret (repr/str <redacted-secret>); connect_kwargs() reveals the password only at the would-be connect call-site; redacted_kwargs()/__repr__/ConfigMissing carry key names only (redaction tests green). No DSN/URL string is ever assembled (discrete kwargs; test_discrete_kwargs_not_dsn).

6. Conformance to ratified design

• Connection: discrete psycopg3 kwargs, autocommit OFF, fail-closed on any missing required key, no host/pw default, no localhost/no-ssl fallback, sslmode config-driven from env (live value disable per FR-1; not hardcoded), no DSN key.
• Principal routing: fixed table MARK/REVIEW/CUT→cutter_exec, VERIFY→cutter_verify; one principal per instance; cross-phase reuse refused (PrincipalCapabilityError before SQL); cutter_ro/privileged refused via inherited _assert_writer; frozen per-principal INSERT inventory (DA-12) + optional advisory cross_check_grants (not invoked this cycle).
• Transaction mapping: one BEGIN/COMMIT per phase, nested→TransactionError, isolation RC (MARK/REVIEW) / SERIALIZABLE (CUT/VERIFY), strict default for unknown phase; CAS column-scoped UPDATE(status) rowcount=1; write-once superseded_by_review_decision_id (cutter_exec only, NULL-guarded).
• Error/rollback: ratified SQLSTATE map — 42501/23503/23502/23514/22xxx/28xxx/unknown→STOP; 23505→RESUME (IdempotencyResume); 40001/40P01/55P03/57014→bounded retry; 53300/53400→bounded retry longer backoff then escalate; 08xxx→discard connection + whole-phase retry; exhaustion→PhaseRetryExhausted (escalate). Retry knobs (5/200ms/5s/jitter) env-driven + clamped. No DELETE/TRUNCATE/DDL/GRANT/COPY surface.

7. Limitations

• RealPostgresAdapter is not wired into CutterRuntime (phases.py unchanged) — runtime binding is a separate, deferred, GPT-gated cycle.
• Never exercised against a real PostgreSQL: behaviour proven via fake provider only. SERIALIZABLE retry behaviour, pg_advisory_xact_lock, and real jsonb adaptation are unverified against a live server (PG-backed dry-run not authorized).
• Advisory cross_check_grants is implemented but uncalled (no live connection in this cycle).
• psycopg3 not installed on the VPS — install is a future runtime-image concern.
• _begin issues SET TRANSACTION ISOLATION LEVEL as the first statement (server-side); only validated against the fake connection contract.

8. Next gate recommendation

Submit this code-authoring package for GPT code review. Do not self-advance. On PASS, the next separately-authorized + GPT-gated step is the PG-backed dry-run cycle (its own command-review, fresh sha backup + restore test, isolated ephemeral env, explicit sovereign prompt) — only after which any production binding may be considered. No CUT/VERIFY, no deploy, no .env/schema/role changes until then.