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

Date: 2026-05-17
Reviewer: GPT
Reviewed package: 8-doc real DB adapter design package under knowledge/dev/laws/dieu44-trien-khai/v0.4-db-adapter-design/
Scope: Design review and DA-1..DA-17 decision closure. No code, connection, .env edit, dry-run, or production action authorized by this review.

---

1. Verdict

v0_4_real_DB_adapter_design: PASS
agent_revision_needed: false
DA_1_to_DA_17: closed
risk_class: STANDARD_HIGH
code_authoring_allowed_now: false
connection_env_key_cycle_may_open: true
production_connection_allowed: false
CUT_VERIFY_allowed: false

The design is accepted. It preserves the non-hardcode and scale-forward principles: no DSN-with-password, env-driven connection components, per-principal credentials, fail-closed loading, configurable pool/retry settings, and multi-worker-safe transaction guards.

---

2. Accepted Adapter Model

adapter: RealPostgresAdapter
driver: psycopg3_sync
construction: discrete_connect_kwargs_no_password_URL
autocommit: false
transaction_model: one_atomic_transaction_per_phase
principal_pools:
  cutter_exec: separate_pool
  cutter_verify: separate_pool
ProductionDBAdapter_existing_refusal: must_remain_until_code_PASS

---

3. DA-1 → DA-17 Decisions

DA_1_connection_env_keys:
  decision: add_four_shared_non_secret_connection_keys_in_separate_env_cycle
  keys:
    - DOT_CUTTER_DB_HOST
    - DOT_CUTTER_DB_PORT
    - DOT_CUTTER_DB_NAME
    - DOT_CUTTER_DB_SSLMODE

DA_2_sslmode:
  decision: require_for_v0_4
  note: verify-full may be upgraded later if CA/cert chain is available and reviewed

DA_3_driver:
  decision: psycopg3_sync
  reason: matches current synchronous skeleton, no event-loop dependency

DA_4_post_connect_identity_assertion:
  decision: include_SELECT_current_user_assertion

DA_5_pool_size:
  decision:
    default_max_size: 1
    hard_ceiling: 2
    min_size: 0
  note: must not exceed live CONNECTION LIMIT 2

DA_6_multi_worker_pooler_strategy:
  decision: keep_pgbouncer_transaction_pooler_compatible; decide deployment details at G7/runtime-binding command-review

DA_7_concurrency_guard:
  decision: use_both_status_CAS_and_pg_advisory_xact_lock

DA_8_isolation_scope:
  decision: SERIALIZABLE_for_CUT_and_VERIFY_only; READ_COMMITTED_for_MARK_and_REVIEW

DA_9_rotation_runbook:
  decision: separate_ops_cycle; no code change required for password rotation

DA_10_sweep_log_persistence:
  decision: rolled_back_MARK_sweep_log_does_not_persist; only already_committed_sweep_pass_rows_persist

DA_11_re_review_re_verify_replay:
  decision: write_once; replay_detects_existing_chain_and_returns_no_op_success

DA_12_capability_assert_source:
  decision: frozen_inventory_constants_plus_startup_advisory_cross_check
  note: cross-check mismatch stops dry-run/prod binding until reviewed

DA_13_retry_bounds:
  decision:
    max_attempts: 5
    base_backoff_ms: 200
    cap_seconds: 5
    jitter: full

DA_14_53300_backpressure:
  decision: bounded_retry_then_escalate

DA_15_VERIFY_fail_escalation_writer:
  decision: cutter_verify_writes_VERIFY_fail_escalation_entry
  reason: within granted matrix and SoD remains intact

DA_16_unknown_SQLSTATE:
  decision: STOP_and_escalate_no_retry

DA_17_production_secrets_in_dry_run:
  decision: forbidden_by_default
  exception: only_with_explicit_GPT_sovereign_prompt

---

4. Accepted Secret / Connection Discipline

secret_values:
  existing_live_keys:
    - DOT_CUTTER_EXEC_DB_USER
    - DOT_CUTTER_EXEC_DB_PASSWORD
    - DOT_CUTTER_VERIFY_DB_USER
    - DOT_CUTTER_VERIFY_DB_PASSWORD
  must_not_be_read_during_design: true
connection_component_keys:
  to_be_added_separately:
    - DOT_CUTTER_DB_HOST
    - DOT_CUTTER_DB_PORT
    - DOT_CUTTER_DB_NAME
    - DOT_CUTTER_DB_SSLMODE
forbidden:
  - DSN_with_password
  - hardcoded_host_port_db_password
  - secret_in_logs_KB_git_argv_repr_metrics
  - fallback_to_localhost
  - fallback_to_no_ssl
  - loading_other_principal_password

---

5. Accepted Transaction Mapping

MARK:
  principal: cutter_exec
  isolation: READ_COMMITTED
  txn: entry_history_dependency_sweep

REVIEW:
  principal: cutter_exec
  isolation: READ_COMMITTED
  txn: manifest_pair_review_decision_status_history

CUT:
  principal: cutter_exec
  isolation: SERIALIZABLE
  txn: executor_signature_change_set_affected_rows_status_history
  verifier_signature_id: NULL

VERIFY:
  principal: cutter_verify
  isolation: SERIALIZABLE
  txn: verify_result_verifier_signature_status_history_optional_compensation_escalation

Binding invariants:

one_phase_one_transaction: true
no_cross_phase_transaction: true
no_nested_transaction: true
no_DELETE_TRUNCATE_DDL_GRANT: true
append_only_ledger: true
idempotency_before_insert: true
status_CAS: true
advisory_xact_lock: true

---

6. Accepted Error Policy

42501: STOP_signal_no_retry_no_privilege_escalation
23505_idempotency_key: RESUME_select_existing
23503_23502_23514_22xxx: STOP_NEEDS_HUMAN
40001_40P01_55P03_57014: bounded_retry_whole_txn
53300_53400: bounded_retry_longer_backoff_then_escalate
08xxx: discard_connection_retry_whole_phase
28xxx: STOP_no_retry_names_only
missing_env: fail_closed_before_socket
semantic_verify_mismatch: designed_FAIL_path_compensate_and_escalate
unknown_SQLSTATE: STOP_escalate

---

7. Gate Effect

real_DB_adapter_design: closed_PASS
next_allowed_phase: connection_env_key_authoring_or_command_review
code_authoring: blocked_until_connection_keys_cycle_PASS_and_explicit_prompt
PG_backed_dry_run: blocked
production_binding: blocked
CUT_VERIFY: blocked

The next safest step is connection env key cycle, because code authoring depends on the four non-secret connection component keys being defined and available through the approved substrate.

---

8. Next Phase Recommendation

Open a small, separate cycle:

phase: v0_4_connection_env_keys_command_review
nature: command_review_only
purpose: add_four_non_secret_DOT_CUTTER_DB_*_keys_to_/opt/incomex/docker/.env
keys:
  DOT_CUTTER_DB_HOST: reviewed_value_only
  DOT_CUTTER_DB_PORT: reviewed_value_only
  DOT_CUTTER_DB_NAME: directus
  DOT_CUTTER_DB_SSLMODE: require

This cycle must not modify code, read password values, connect runtime code, or perform CUT/VERIFY.

---

9. Status

ready_for_connection_env_key_cycle_prompt: true
agent_self_advance: prohibited_without_explicit_prompt