dot-iu-cutter v0.4 — Tier 2 Cutter-Agent DESIGN Master

document_path: knowledge/dev/laws/dieu44-trien-khai/v0.4-design/dot-iu-cutter-v0.4-cutter-agent-design-master-2026-05-16.md
revision: r1
date: 2026-05-16
author: Agent (Claude Code CLI, Opus 4.7 1M)
sovereign: User / anh Huyền
verifier: GPT (design review pending — this package is authored FOR that review)
phase: v0.4 — Tier 2 cutter-agent write-path + MARK→REVIEW→CUT→VERIFY flow DESIGN
authorization: GPT v0.3 closeout review = PASS (dot-iu-cutter-v0.3-closeout-gpt-review-2026-05-16,
  §5 next_design = cutter_agent_write_path_plus_MARK_REVIEW_CUT_VERIFY_flow) + explicit User
  prompt opening the v0.4 Tier 2 DESIGN cycle. DESIGN ONLY.
status: design_package_authored_pending_gpt_review

⛔ DESIGN ONLY — NOTHING BUILT. No code. No SQL. No data write. No production CUT. No production VERIFY. No Qdrant/vector mutation. No deploy. No Directus / RLS / role / view / grant change. No login/member binding. No schema migration. No self-advance beyond design. This package describes the intended Tier 2 runtime; it creates nothing. Every privilege, role, table-write, and harness named here is a target design, gated behind a separate explicitly-authorized cycle.

§1 — Purpose

Tier 1 is COMPLETE: 12 empty cutter_governance base tables (PK 12, FK 19, 0 rows) plus a LIVE read-observability layer (cutter_ro NOLOGIN + 12 v_*_observe views + 13 grants). The tables have no writer. This package designs the cutter-agent write path and the MARK → REVIEW → CUT → VERIFY runtime state machine that will, in a future authorized cycle, become the only sanctioned producer of rows in cutter_governance.

This master document is the index and the executive synthesis. The seven companion documents carry the detailed design.

§2 — Document Set (this package, all r1, all DESIGN ONLY)

1 design-master (this doc):
    knowledge/dev/laws/dieu44-trien-khai/v0.4-design/dot-iu-cutter-v0.4-cutter-agent-design-master-2026-05-16.md
2 write-path-design:
    .../v0.4-design/dot-iu-cutter-v0.4-cutter-agent-write-path-design-2026-05-16.md
3 mark-review-cut-verify-flow-design:
    .../v0.4-design/dot-iu-cutter-v0.4-mark-review-cut-verify-flow-design-2026-05-16.md
4 runtime-state-machine-design:
    .../v0.4-design/dot-iu-cutter-v0.4-runtime-state-machine-design-2026-05-16.md
5 credential-and-principal-strategy-design:
    .../v0.4-design/dot-iu-cutter-v0.4-credential-and-principal-strategy-design-2026-05-16.md
6 canonicalization-signing-signal-integration-plan:
    .../v0.4-design/dot-iu-cutter-v0.4-canonicalization-signing-signal-integration-plan-2026-05-16.md
7 risk-and-dry-run-test-plan:
    .../v0.4-design/dot-iu-cutter-v0.4-risk-and-dry-run-test-plan-2026-05-16.md
8 design-report:
    .../v0.4-design/dot-iu-cutter-v0.4-cutter-agent-design-report-2026-05-16.md

§3 — Grounding Facts (from controlling files; do not re-derive)

schema: cutter_governance (PG16, container postgres, db directus, sysid 7611578671664259111)
base_tables: 12 | PK: 12 | in_schema_FK: 19 | cross_schema_FK: 0 | rows: 0
read_layer_LIVE: cutter_ro (NOLOGIN, 0 memberships) + 12 v_*_observe views + 13 grants
control_plane: PostgreSQL (Directus registration of cutter_governance DEFERRED — MODEL-C)
RLS: none on any cutter_governance object (isolation = views-only grant model)
schema_frozen: TRUE — no new column/table/CHECK/trigger/DEFAULT/enum in v0.4 scope
invariant_model: app/agent-enforced (BATCH-1 GPT override: text + documented allowed
  values; NO PG enum / NO lookup FK) — the cutter-agent OWNS validation
append_only_signal: prior_* and superseded_by_* self-FKs exist on dot_pair_signature,
  review_decision, verify_result → lineage is append-only, not mutate-in-place

The 12 tables and their role in the flow:

decision_backlog_entry      : canonical work item (entry_id, kind, status, payload jsonb, emitted_at, scenario_ref)
decision_backlog_history    : append-only audit spine (history_id, FK entry_id)
decision_backlog_dependency : DAG edges between entries (from_entry_id, to_entry_id)
decision_backlog_sweep_log  : sweep-pass ledger (soft uuid refs, no hard FK)
manifest_envelope           : the planned cut manifest (envelope_id)
manifest_unit_block         : per-unit plan, composite PK (envelope_id, unit_local_id)
review_decision             : approve/reject/defer bound to manifest pair (+ prior/superseded self-FK)
cut_change_set              : an applied CUT (FK entry, executor_sig, verifier_sig)
cut_change_set_affected_row : per-row effect of a CUT (FK change_set_id)
verify_result               : independent VERIFY outcome (FK change_set, sigs, rollback, escalation, prior self-FK)
dot_pair_signature          : executor/verifier attestation chain (prior_signature_id self-FK)
canonical_address_alias     : alias resolution table — population/resolution DEFERRED to canon-lib workstream

§4 — Recommended Runtime Flow (synthesis; detail in docs 2/3/4)

external signal
   │  (signal router — placeholder, doc 6)
   ▼
[MARK]    writer txn → decision_backlog_entry (status=marked) [+ history +dependency]
   │      idempotency key derived deterministically; sweep_log records pickup
   ▼
[REVIEW]  build manifest_envelope + manifest_unit_block (plan, not effect)
   │      → review_decision (approve|reject|defer) bound to manifest pair [+ history]
   │      guard: rejected→terminal; deferred→re-enter on next sweep
   ▼
[CUT]     executor principal: cut_change_set + N×cut_change_set_affected_row
   │      + executor dot_pair_signature (DOT-991)  [+ history]   (one txn)
   │      guard: requires non-superseded APPROVE review_decision
   ▼
[VERIFY]  verifier principal (separation of duty): verify_result
   │      + verifier dot_pair_signature (DOT-992)  [+ history]   (one txn)
   ├─ pass → entry status=verified_complete   (TERMINAL SUCCESS)
   └─ fail → verify_result.rollback_change_set_id_triggered → compensating
             cut_change_set; escalation_ref → new escalation entry;
             status=verify_failed_escalated  (MANUAL ESCALATION)

Append-only on retry: a re-attempt creates a new row chained via the relevant prior_* self-FK and marks the old one via superseded_by_*; nothing is updated-in-place except decision_backlog_entry.status (the one sanctioned mutable scalar) and its mirrored history append.

§5 — Recommended Writer Principal Strategy (synthesis; detail in doc 5)

cutter_ro: READ-ONLY, NOLOGIN — MUST NOT be used for any write, ever.
target_writers (DESIGN ONLY — not created, not granted, no secret minted):
  cutter_exec  : LOGIN, least-privilege, may write MARK/REVIEW/CUT family tables
  cutter_verify: LOGIN, least-privilege, may write VERIFY family + sign DOT-992
separation_of_duty: cutter_exec ≠ cutter_verify (distinct principals, distinct
  secrets) so the VERIFY attestation is independent of the CUT actor
dot_pair_alignment: DOT-991 = executor signature lane (cutter_exec),
  DOT-992 = verifier signature lane (cutter_verify) — mirrors the established
  paired DOT-…-EXECUTOR ↔ DOT-…-EXECUTOR-VERIFY pattern in this project
privilege_target: INSERT (+ scoped UPDATE of decision_backlog_entry.status
  only) on the relevant tables; NO DELETE / TRUNCATE / DDL / GRANT; NO
  base-table privilege to anyone else; NO use of workflow_admin or the
  directus app role as the writer
secret_custody: a NEW dedicated secret in /opt/incomex/docker/.env pattern
  (not reuse) — minted only in a later authorized credential cycle

§6 — Key Risks / Blockers (synthesis; detail in doc 7)

risk_class_overall: STANDARD for the DESIGN; HIGH-risk items isolated below
blockers_before_code_authoring:
  - GPT design-review PASS of this package
  - resolution of OPEN DECISIONS §7 (idempotency-column, alias deferral,
    principal split granularity, signal source contract)
blockers_before_dry_run:
  - code authored + reviewed; dry-run CUT/VERIFY harness designed (doc 6)
    and itself reviewed; isolated ephemeral env (never prod)
blockers_before_production_CUT_VERIFY:
  - dry-run PASS + command-review + explicit sovereign prompt + the
    credential cycle (cutter_exec/cutter_verify) executed under its own review
remaining_HIGH_risk:
  - canonical_address_alias resolution semantics (DEFERRED; flagged HIGH —
    must NOT be improvised inside v0.4 flow)
  - signing-scheme cryptographic design (DEFERRED to its own workstream;
    v0.4 only reserves the dot_pair_signature integration point)
  - first non-zero write into a hitherto-empty governance schema (irreversible
    semantic content even if technically rollback-able)

§7 — Open Decisions for GPT

OD-1 idempotency-column: schema is frozen at 6 cols on decision_backlog_entry.
  Recommend the MARK idempotency key live inside payload jsonb
  (payload.idempotency_key) with scenario_ref as the human/scenario tag.
  GPT to confirm vs. an alternative (scenario_ref encodes the key).
OD-2 alias deferral: recommend canonical_address_alias is DEFERRED entirely
  from v0.4 flow (CUT neither reads nor writes aliases in v0.4). GPT to
  confirm deferral vs. requiring a read-only alias lookup stub in CUT.
OD-3 principal granularity: recommend 2 writer principals (cutter_exec,
  cutter_verify). GPT to confirm vs. 1 writer (simpler, weaker SoD) or 3
  (mark/cut/verify split).
OD-4 signal source contract: signal router is a placeholder (doc 6). GPT to
  confirm that defining the concrete upstream signal contract is a SEPARATE
  later design, not in-scope for v0.4.
OD-5 retry vs reopen: recommend append-only retry (new chained row +
  superseded_by) over status flip-back. GPT to confirm this as the
  invariant for all three signed artefacts.

§8 — Explicit Non-Scope (hard boundary)

not_in_this_package:
  - any code / script / SQL / migration
  - any data write into cutter_governance
  - any CUT or VERIFY (prod or otherwise)
  - any credential creation, role creation, GRANT, password mint
  - any Directus / RLS / view / grant / collection change
  - any Qdrant / vector / embedding work
  - any deploy / restart / login or member binding
  - any schema change (schema is frozen)
  - self-advance to DDL authoring, dry-run, command-review, or execution
the_only_next_thing: GPT review of this design package

§9 — Readiness

package_complete: 8/8 documents authored (r1)
internally_consistent: yes (flow ⇄ state machine ⇄ write path ⇄ principals cross-checked)
grounded_in_live_schema: yes (validated against v0.2/v0.3 inventories)
ready_for_gpt_review: TRUE
agent_self_advance: PROHIBITED

End of v0.4 Tier 2 cutter-agent DESIGN master (design only; nothing built; self-advance PROHIBITED).