03 — Sequential DOT Workflow Design

Goal: the operator/user remembers one correct DOT entrypoint, not the seven steps. The DOT internally sequences and guarantees a later step cannot run without the prior one. Design only.

---

0. The one entrypoint

dot-birth-admit  --collection <name> --code <CODE> --name <text> \
                 --species <SPE> --role <governed|observed|excluded> \
                 --actor <principal> [--approval <uuid>] [--payload <json>] \
                 [--dry-run | --commit]

• --dry-run is the default (BEGIN … ROLLBACK), mirroring dot-pivot-update's proven discipline.
• The operator never calls the permit table, the gate, or birth_registry directly. The DOT does the sequence; the DB enforces the sequence (so even a hand-written insert cannot skip steps for an enforced family).

Design principle (open-goal law §automation-first): the workflow must not rely on a human remembering the order. The order is encoded twice — in the DOT (convenience) and in the DB constraints (enforcement). The DB is the source of truth; the DOT is the ergonomic wrapper.

---

1. State machine

            ┌─────────────┐
            │  REQUESTED  │  validate inputs (collection policy, code shape, actor, approval)
            └──────┬──────┘
                   │ fn_pre_birth_check passes + family policy ok
            ┌──────▼──────┐
            │  VALIDATED  │
            └──────┬──────┘
                   │ fn_birth_permit_request()  (writes RESERVED permit + command log)
            ┌──────▼──────┐
            │  RESERVED   │◄──── watchdog → EXPIRED (TTL elapsed, unconsumed)
            └──────┬──────┘
                   │ INSERT into target table  → BEFORE gate consumes permit
            ┌──────▼──────┐
            │  CONSUMED   │  (permit.consumed_at set; AFTER trigger writes BORN row)
            └──────┬──────┘
                   │ COMMIT → DEFERRABLE constraint trigger asserts BORN row exists
            ┌──────▼──────┐
            │ FINALIZED   │  (permit.finalized_birth_id set; status FINALIZED)
            └──────┬──────┘
                   │ enqueue handoff (register-before-emit → event_pending/outbox)
            ┌──────▼──────┐
            │ HANDOFF_ENQ │
            └──────┬──────┘
                   ▼
            ┌─────────────┐
            │    DONE     │
            └─────────────┘

   Failure at any step ⇒ FAILED  (failure_reason set; tx ROLLBACK; permit REVOKED/EXPIRED)

State table

state	set by	invariant guaranteed
REQUESTED	DOT	inputs captured, nothing written
VALIDATED	fn_pre_birth_check + family policy	row shape + collection + code valid
RESERVED	fn_birth_permit_request	a single-use permit exists, TTL'd, audited
CONSUMED	BEFORE gate during INSERT	the insert is bound to a real reservation
FINALIZED	deferred constraint trigger at COMMIT	a BORN row exists for this exact (collection, code) — no partial state
HANDOFF_ENQ	post-commit hook	governance signal captured (never lost)
DONE	DOT	terminal success
FAILED / EXPIRED / REVOKED	watchdog / error path	no permit-less born row, no born-less permit

---

2. Fail / rollback rules

1. One transaction wraps RESERVE→INSERT→(AFTER birth)→COMMIT where the creation path is a single statement-group. The DEFERRABLE INITIALLY DEFERRED constraint trigger fires at COMMIT; if the BORN row is absent or the permit unconsumed, it RAISEs → the whole tx rolls back → no partial state.
2. If RESERVE succeeds but the INSERT is never issued, the permit stays RESERVED and the watchdog flips it to EXPIRED after TTL — visible, never silently consuming identity.
3. If the INSERT fails (any reason), the tx rolls back; the permit (written in the same tx) rolls back too. If the permit was issued in a prior tx (two-phase operator flow), the watchdog expires it.
4. Handoff enqueue failure must NOT roll back the birth (decoupling, doc 06): it is a post-commit, register-before-emit step; on failure the signal is captured to event_pending (retry/DLQ), and a handoff_dlq finding is raised. Birth stands; governance catches up via the cursor tail.

---

3. Idempotency key

request_hash = sha256( collection_name || '|' || entity_code || '|' || normalized_intent )

• Stored UNIQUE on the permit. Re-invoking dot-birth-admit with the same logical request returns the existing permit/birth instead of creating a duplicate (replay-safe).
• A different intent for the same (collection, code) while a live permit exists is rejected (UNIQUE (collection_name, entity_code) WHERE status IN ('RESERVED','CONSUMED')).

4. Retry behavior

• Safe retry = re-run the same command (same idempotency key). RESERVED-but-unconsumed → reuse; FINALIZED → no-op success; EXPIRED → issue a fresh permit under a new TTL but same key family.
• No blind retry loops: the DOT inspects permit status first (v_birth_admission_permit_status) and reports the current state rather than re-issuing.

5. Logging

• Every step writes a row via the existing fn_dot_iu_command_log(...) (same ledger the gate-token mechanism uses): command_name='dot_birth_admit', phase, status, request_hash, before/after jsonb, actor.
• Permit lifecycle transitions optionally mirror to iu_gate_transition-style records, or a dedicated birth_permit_transition if a separate audit lane is wanted (design choice; default = reuse command log).

6. Preventing partial state

• The DEFERRABLE constraint trigger is the linchpin: a committed transaction is guaranteed to leave EITHER (permit FINALIZED + BORN row) OR nothing. There is no committed "RESERVED permit with no born row" and no committed "born row with no consumed permit" for an enforced family.
• For non-enforced families, the constraint trigger is report-only (logs a permit_missing finding, does not raise) — so the rollout is incremental and never breaks the 150 ungated tables.

7. Preventing a step from running out of order

• CONSUMED requires a RESERVED permit (BEFORE gate). FINALIZED requires CONSUMED (constraint trigger). HANDOFF requires a real BORN row (cursor tail reads birth_registry). Each step's precondition is a DB fact written by the previous step — the order is structurally enforced, not procedurally assumed.

8. Exposing failed / expired permits

• v_birth_admission_permit_status (read-only): counts and tail by status; surfaces RESERVED-aging, EXPIRED, FAILED, REVOKED.
• A birth_permit_silent_gap / birth_permit_expired finding (via queue_heartbeat + system_issues) so failures are loud, not silent (open-goal law: "failed/expired permits must be visible").

---

9. Build posture

Do not build a production DOT yet. Lawful registrar (dot-dot-register) creds are ABSENT and OSPA=0. This macro produces the design + a rollback-only rehearsal plan (doc 09 Phase 1): a BEGIN … ROLLBACK prototype that issues a permit, inserts a dot_tools row, observes the gate consume + the deferred constraint finalize, then ROLLBACK — proving the sequence with zero prod mutation. The production DOT is authored only after the permit table, composite-unique fix, and registrar creds exist (Phase 3).