Birth Gateway SSOT + QT-001 Repair — Canonical Design (Reconstructed)

Date: 2026-06-06 · Status: OFFICIAL — staged design, Stage 0 in execution.

0. Provenance

The Codex design package authored only 00-readme-first.md and 11-final-summary.md; detailed docs 01..10 were never written. This document reconstructs ONE executable design from those two docs + checkpoint-codex-birth-gateway-ssot-qt001-design-plan-2026-06-06.md + checkpoint-codex-birth-first-side-door-compatibility-audit-2026-06-06.md, cross-checked against live production (2026-06-06). No unknown implementation details were invented; every "CURRENT" fact below is live-verified, every "TARGET" item is carried verbatim-in-intent from the source design.

1. Problem statement (the side door)

The live birth gateway fn_birth_registry_auto() was patched (P0 remediation) to skip births for EXEMPT/DEFERRED collections (it reads collection_registry.coverage_status / BIRTH_EXEMPT). But the DOT dot-birth-trigger-setup (DOT-119) still embeds and installs an OLD version of that same function via CREATE OR REPLACE FUNCTION fn_birth_registry_auto() (its line 113) — a version that looks up only governance_role and has no coverage_status / BIRTH_EXEMPT guard. Running that DOT silently reverts the gateway to pre-fix logic across 166 triggers / 148 tables, reopening the birth/object-pollution P0 for 36 EXEMPT + 58 DEFERRED collections. dot-birth-backfill (DOT-118) independently does direct INSERT INTO birth_registry and is incompatible with 22/36 governed collections (can partially execute). This is operational SSOT drift: runtime can be overridden by stale DOT source.

2. Gateway SSOT decision

• The single source of truth for the gateway is an immutable, versioned Git migration release of the birth policy/identity/register functions — NOT a DOT-embedded heredoc.
• Runtime proof of integrity is an append-only semantic function contract registry + SHA-256 (or normalized-md5) verifier: the live function's normalized source hash must match the approved release hash, and must contain the required policy markers (coverage_status, BIRTH_EXEMPT). Any divergence is machine-detectable and fails closed.
• No tool may define the gateway by shipping its own copy of the function body.

3. Rule: dot-birth-trigger-setup must NEVER CREATE OR REPLACE FUNCTION

• dot-birth-trigger-setup is redesigned to trigger-reconcile only: it may DROP/CREATE TRIGGER ... EXECUTE FUNCTION fn_birth_registry_auto(...) to attach the already-released gateway to a collection, but it may never contain or apply a CREATE OR REPLACE FUNCTION for any fn_birth*.
• The embedded "Step 2: Creating master birth trigger function" block must be deleted from the DOT in Stage 1; the function comes only from the immutable release.
• Same rule applies to dot-schema-birth-registry-ensure (it must ensure schema/meta only, never a fn_birth* body that competes with the release).

4. Shared function architecture (TARGET — Stage 1)

Realtime birth (QT-002) and backfill (QT-001) must share ONE policy/identity/register path so they can never diverge:

Function	Responsibility
fn_birth_policy_decision	Given a collection, return BIRTH / SKIP_EXEMPT / DEFER from collection_registry.coverage_status (the exempt guard, single definition).
fn_birth_resolve_identity	Resolve entity identity (code field / birth_code_strategy / birth_identity_source) for the collection — replaces hardcoded TG_ARGV code-field maps.
fn_birth_register	Perform the birth_registry insert (idempotent, ON CONFLICT DO NOTHING), used by BOTH the realtime trigger and the QT-001 apply DOT.

CURRENT: these three functions do not exist yet. The live gateway fn_birth_registry_auto() inlines all three concerns. Stage 1 extracts them into the immutable release and rewrites the realtime trigger + QT-001 to call them.

5. QT disposition

QT	Meaning	CURRENT	TARGET
QT-001	Backfill birth for existing rows	dot-birth-backfill direct INSERT; incompatible 22/36; no permit/ledger	Paired metadata-driven plan/apply DOTs: exact preflight, batch transactions, exempt audit ledgers, uncertified births, calls fn_birth_register
QT-002	Birth-first for new entity	Live; enforced by fn_birth_registry_auto (AFTER INSERT) + fn_birth_gate (BEFORE INSERT)	Unchanged path, but trigger calls the shared release functions
QT-003	New collection registration	Soft/detect-only; dot-collection-create calls dot-birth-trigger-setup (guarded by -x)	Hard first-row gate; never redefines gateway
QT-003R	Retroactive registration (0-row tables)	Soft; >0 rows must STOP→QT-001	Hard first-row gate
QT-005	Promote/demote governance_role	Detect-only; birth records kept on demote	One orchestrated state transition preserving history
QT-006	Death / lifecycle	Absent (no death trigger)	Separate approved universal lifecycle-state program; birth fact remains immutable

6. Stage 0..5 rollout

• Stage 0 — FREEZE + GUARD (this macro). Freeze/guard accidental execution of dot-birth-trigger-setup and dot-birth-backfill; make gateway-SSOT drift machine-detectable; do not worsen any live QT path; author Stage 1 packet. Reversible; additive views only; no gateway/trigger/data mutation.
• Stage 1 — GATEWAY SSOT IMPLEMENTATION. Immutable Git release of fn_birth_policy_decision / fn_birth_resolve_identity / fn_birth_register; runtime semantic contract registry + verifier; strip CREATE OR REPLACE FUNCTION from dot-birth-trigger-setup (reconcile-only); birth admission permit + backfill ledger tables.
• Stage 2 — QT-001 plan/apply. Paired metadata-driven backfill with exact preflight, exempt audit, uncertified births; classify the 43 unclassified identity strategies first.
• Stage 3 — QT-003 / QT-003R first-row hard gate.
• Stage 4 — QT-005 governance transition (single orchestrated, history-preserving).
• Stage 5 — QT-006 universal lifecycle / death (separate approved program).

7. Forbidden DOTs until fixed

Until Stage 1 passes source-parity / preflight review, do not run: dot-birth-trigger-setup, dot-birth-backfill, and (because it invokes trigger-setup) the trigger-setup step of dot-collection-create. No CREATE OR REPLACE FUNCTION fn_birth* from any DOT. No raw SQL INSERT into birth_registry. No trigger DROP/CREATE for birth outside the reconcile-only path.

8. Rollback / no-go

• Stage 0 is reversible: every guard is an additive view (DROP VIEW rollback); any execution-path quarantine has a staged mv-back rollback (BIRTH_STAGE0_FREEZE_ROLLBACK.md).
• No-go if: live read of gateway source fails; the freeze would break a non-degrading caller; any action would mutate birth_registry, a birth trigger, or a fn_birth* body; OOM/512MB risk on heavy scans.
• Birth-neutral invariant: birth_registry count before == after for every applied DDL (anchor 1,210,834).

9. Live baseline (verified 2026-06-06)

Item	Value
birth_registry rows	1,210,834
coverage_status	BIRTH_REQUIRED 74 / BIRTH_DEFERRED_NEEDS_REVIEW 58 / EXEMPT (junction 20 + log/audit 12 + derived-cache 4 = 36)
governance_role	observed 67 / excluded 60 / governed 36 / locked 3 / law_artifact 2
BIRTH_REQUIRED identity_source	unclassified 43 / inferred_from_existing_trigger 28 / migration_seed 2 / manual 1
BIRTH_REQUIRED with native status col	54/74
BIRTH_REQUIRED without birth trigger	2 (iu_staging_payload, iu_staging_record — no PG table)
gateway fn_birth_registry_auto	GUARDED: has coverage_status + BIRTH_EXEMPT; 166 triggers / 148 tables; normalized-md5 c022f849c2c7d57a720c4cc172789d70
fn_birth_registry_auto_id	NO exempt guard; 3 BIRTH_REQUIRED tables only
danger DOT md5	trigger-setup a0b926d3fd373b8995aea2f4e8136e01; backfill f04cdbf5363a67cd837fdad9d649df2a

10. Next macro

BIRTH_STAGE1_GATEWAY_SSOT_IMPLEMENTATION — implement the immutable gateway release + runtime semantic contract registry, strip gateway-redefine from the setup DOT, and create the birth admission permit + backfill ledger. See BIRTH_STAGE1_GATEWAY_SSOT_IMPLEMENTATION_PACKET.md.

11. Stage 1 result — LIVE (2026-06-06)

Stage 1 executed PASS. What is now live (additive, reversible; rollback /opt/incomex/docs/mcp-writes/birth-stage1-2026-06-06/99_rollback_stage1.sql):

• Runtime contract registry birth_gateway_release_registry (release v1-stage1-2026-06-06, append-only by convention), seeded from live capture for 5 fns with normalized-md5 + semantic SHA-256. Views: v_birth_gateway_release_current, v_birth_gateway_release_drift_guard, v_birth_gateway_contract_integrity_dashboard (all OK). This realizes the SSOT decision (§2): there is now ONE live place to check which gateway contract is current, with machine-detectable, fail-closed semantic drift.
• Shared functions (§4) now exist: fn_birth_policy_decision(text) (EXEMPT→skip / REQUIRED→birth / DEFERRED→defer / else UNKNOWN_BLOCK; deterministic, no-write, STABLE, fail-closed); fn_birth_resolve_identity(text,jsonb) (reads birth_code_*/birth_identity_source; NULL-row = eligibility preflight; never invents identity for the 43 unclassified; no-write); fn_birth_register(text,jsonb,boolean,text) (policy→identity→idempotent ON CONFLICT (entity_code) insert; p_dry_run defaults TRUE; single-row, not bulk). Proven in BEGIN..ROLLBACK: dry-run REQUIRED→would_register, EXEMPT/DEFERRED→skipped (even non-dry), real register→registered (+1), duplicate→skipped (idempotent), unknown→blocked, ROLLBACK→net 0.
• Permit + ledger (§ packet): birth_admission_permit + birth_backfill_ledger created, empty (fail-closed; QT-001 apply will require an open permit).

What was deliberately NOT done (kept for Stage 2 / T2 review):

• The live trigger gateway fn_birth_registry_auto was NOT rewritten to call the new functions (integration Option A = parity-guard-only). Reason: preserve the QT-002 live path with zero behavior change. Parity holds for EXEMPT (both skip) and REQUIRED (both birth); for DEFERRED and UNREGISTERED the Stage 1 contract is stricter (defer/block where the live gateway still births) — i.e. the contract can only ever produce fewer births, never more (no-worse proven). Full thin-wrapper integration (Option C) and the setup-DOT CREATE OR REPLACE FUNCTION strip are staged for Stage 2 under T2 review. Live gateway norm-md5 c022f849 unchanged; tga 129; birth before==after.
• No QT-001 backfill. See BIRTH_STAGE2_QT001_METADATA_BACKFILL_REPAIR_PACKET.md.

Next macro: BIRTH_STAGE2_QT001_IDENTITY_CLASSIFICATION_AND_METADATA_BACKFILL — classify the 43 unclassified identities, resolve the 2 no-table REQUIRED collections, build paired plan/apply DOTs over fn_birth_register, open per-collection permits, dry-run→batched-apply→rerun-delta=0.

12. Stage 2 result — PARTIAL (2026-06-06)

Stage 2 executed PARTIAL (all safe branches complete; real backfill apply deliberately NOT committed — gated by independent T2 review per packet section 7 + owner permit). Additive, reversible, birth-neutral; macro net births = 0. Live fn_birth_registry_auto and all triggers unchanged (tga 129; no_go 4/4; contract all_ok).

• Identity classified 39 of 43 (resolvable 31 → 70 of 74) by mirroring each live birth trigger's TG_ARGV: 7 column (apr_action_types=action_code; checkpoint_instances, checkpoint_type_overrides, comments, table_proposals, trigger_registry, workflow_categories = code) + 32 synthetic_id (collection::id). This makes backfill entity_codes byte-identical to the realtime path → zero duplicate risk, idempotent. Classification is a collection_registry.birth_code_* metadata UPDATE, invisible to the live gateway (it does not read birth_code_*).
• 4 NEEDS_OWNER (left unclassified, action-packed): apr_request_types, binding_registry, nrm_doc_type_config (no id column + no-arg live trigger → would compute collection::NULL, violating entity_code NOT NULL → 0 births; classifying without reconciling the trigger is realtime-divergent), and nrm_approval_rules (composite PK, no single natural key). Owner must pick the identity key AND reconcile the realtime trigger arg.
• 2 no-table REQUIRED (iu_staging_payload, iu_staging_record): identity classified but no PG table → not backfillable; create-or-reclassify is owner/QT-003R scope.
• Full dry-run over 39 eligible: 137 expected new births across 5 governed collections (dot_domain_rules 67, apr_approvals 42, normative_relations 18, apr_action_types 6, field_type_equivalences 4); 34 others already covered or empty.
• Apply rehearsed in BEGIN..ROLLBACK: applied_delta=137, rerun_delta=0 (idempotent), ROLLBACK clean — committed nothing.
• Plan/apply DOT source authored (fn_dot_birth_qt001_plan read-only; sp_dot_birth_qt001_apply gated/fail-closed) but NOT deployed live; old dot-birth-backfill/dot-birth-trigger-setup stay frozen.
• 25 guard/inventory/decision views live (all green). Rollback staged 99_rollback_stage2.sql.

Next macro: T2_REVIEW_STAGE2_BEFORE_APPLY → BIRTH_STAGE2_QT001_APPLY_IF_READY; parallel BIRTH_STAGE2_METADATA_REPAIR_CONTINUE (4 needs-owner + 2 no-table). See report dir birth-stage2-qt001-identity-metadata-backfill-repair-2026-06-06.