KB-2590

Pre-Birth Pilot Rehearsal — 01 Live Verification & Entry State

7 min read Revision 1
pre-birthdot_toolsentry-statelive-verification2026-06-03

01 — Live Verification & Entry State

All facts below were read live from production directus on 2026-06-03 immediately before the rehearsal. Old reports were treated as evidence, not authority; where this differs from prior checkpoints, live wins.

1. Execution channel

Check Result
ssh contabo (root) OK
docker exec postgres OK (postgres container running)
psql user workflow_admin
rolsuper t (superuser)
transaction_read_only off (writes possible)
PostgreSQL 16.13 (Debian)
temp create/drop in rollback OK (proven in rehearsal)

Classification: EXECUTION_MODE. Rollback-only DDL/DML rehearsal in one transaction is available. No commit of schema/business change is permitted by the macro and none was made.

2. birth_registry schema & constraints

  • 22 columns. Identity columns: entity_code varchar NOT NULL, collection_name varchar NOT NULL, species_code, composition_level, governance_role, status varchar DEFAULT 'born', dot_origin, born_at, certified, jsonb_profile.
  • Constraints (only two):
    • birth_registry_pkey — PRIMARY KEY (id)
    • birth_registry_entity_code_uniqueUNIQUE (entity_code) ← the structural defect
  • Indexes: pkey, the entity_code unique, idx_birth_collection(collection_name), partial idx_birth_species (where governed), partial idx_birth_uncertified.
  • Status: no CHECK constraint; one value live — born — across 1,126,728 rows.
  • Rowcount: 1,126,728 total; 1,126,728 distinct entity_codes; 79 distinct collections.
  • Owner: directus.

3. Composite-unique feasibility (decisive)

Probe Result Meaning
entity_codes in >1 collection 0 no cross-collection code reuse exists today
(entity_code, collection_name) duplicate rows 0 composite unique is already satisfied by all 1.12M rows
null collection_name rows 0 no NULL handling needed
FK references to birth_registry(entity_code) or (id) 0 nothing breaks if single-col unique is dropped
functions referencing ON CONFLICT (entity_code) 2 (fn_birth_registry_auto, fn_birth_registry_auto_id) exactly two call sites to patch

4. Key function fingerprints (entry baseline)

Object OID md5(pg_get_functiondef)
fn_birth_registry_auto 39232 1f729b3571a74963089bb3ef388217f3
fn_birth_gate 38216 b6700aa8c2c5a5f4255f3b119d7dd673
fn_birth_registry_auto_id 3f3515dedf1d5bb0f0f66711297b5b5c

fn_birth_registry_auto — already has a composite-aware skip guard (WHERE entity_code=… AND collection_name=TG_TABLE_NAME), but its INSERT backstop is ON CONFLICT (entity_code) DO NOTHING (single column). When a code already exists in another collection, the EXISTS guard passes (false for this collection), the INSERT proceeds, then ON CONFLICT (entity_code) swallows it silently → the row is never born in this collection. That is the 5-pivot collision mechanism. 166 triggers call this function.

fn_birth_gate — advisory: kill-switch GUC app.bypass_birth_gate, skips null/empty code, runs fn_pre_birth_check, mode app.birth_gate_mode default warning (RAISE WARNING), only RAISE EXCEPTION when blocking. Currently POLICY, not ENFORCEMENT.

fn_pre_birth_check — 5 checks: (1) collection in meta_catalog managed, (2) _dot_origin non-empty, (3) code format ^[A-Z]+-[0-9]+$ (the hardcoded rule that rejects 100% of entity_species, 47% of dot_tools), (4) name uniqueness, (5) code uniqueness.

5. dot_tools (pilot family)

  • 28 columns; code field = code; 309 rows; unborn = 0; owner directus.
  • 13 triggers, including the relevant ones:
    • trg_before_birth_gate_dot_tools — BEFORE INSERT → fn_birth_gate() (advisory gate already present)
    • trg_auto_code_dot_tools — BEFORE INSERT → gen_code_dot_tools()
    • birth_trigger_dot_tools and trg_birth_dot_tools — both AFTER INSERT → fn_birth_registry_auto('code') (duplicate birth trigger; harmless due to ON CONFLICT/EXISTS guard, noted as cleanup candidate)
  • A pilot permit gate can be inserted as a second BEFORE INSERT trigger ordered after code-gen without replacing fn_birth_gate globally.

6. DEFERRABLE finalize reference pattern (live)

  • trg_iu_birth_gate_layer2 on information_unit: CREATE CONSTRAINT TRIGGER … DEFERRABLE INITIALLY DEFERRED calling fn_iu_birth_gate_layer2() — re-reads the row by id at the commit boundary, validates invariants, RAISEs on failure, returns NULL. This is the exact finalize-at-commit shape reused in Workstream E.
  • Layer1 (fn_iu_birth_gate_layer1) is the BEFORE-row companion (required-field + vocab checks). Gate-token ledger functions present: fn_iu_gate_open(p_gate_key,p_approval_id,p_actor,p_reason,p_ttl_seconds), fn_dot_iu_command_log(...).

7. Governance handoff objects (live)

Object State
event_pending table present
event_type_registryhandoff.object_born registered, active = false (captured-only, not emitted), domain governance, lane delayed
governance_candidate_state table present
governance_build_authorization (OSPA) 0 rows → NO-GO
registry_changelog 70,434 rows (the CDC tail source)

8. Safety-net & live BLOCK dims (unchanged)

  • Safety-net objects all present (v_birth_orphan, v_birth_phantom, v_birth_coverage_status, _recon_dot_fs_inventory, v_dot_fs_reconciliation, v_dot_registry_no_file, v_dot_pivot_update_status, _preflight_accepted_exceptions, fn_assert_safe_for_dot_action, …).
  • 4 BLOCK dims (live): orphan_critical_active 59 · phantom_real (REAL_MISSING) 6 · fs FILE_NO_REGISTRY 16 · dot_pivot_update 1.
  • app.bypass_birth_gate / app.birth_gate_modeunset (clean; gate runs in default warning mode, not bypassed).

9. Incidental discovery — a DDL guard is already live

During the temp-trigger rehearsal, a server-side event trigger emitted WARNING: [TRIGGER-GUARD] DDL detected: CREATE TRIGGER on …. An existing DDL-capturing event trigger is therefore already in place — relevant evidence for the drift/bypass monitor (Workstream H, doc 09): the detection substrate partly exists and can be extended rather than built from scratch.

Back to Knowledge Hub knowledge/dev/reports/architecture/pre-birth-pilot-dot-tools-permit-composite-rehearsal-2026-06-03/01-live-verification-and-entry-state.md