Incomex AI Portal
KB-7920

P3D Birth System — B2 Contract Design Rev3

11 min read Revision 1
dieu44birthb2-contractrev3design2026-05-14

P3D Birth System — B2 Contract Design Rev3

Document type: Design — contract formalization Status: RATIFIED (post-execution, reflects live state on VPS at 2026-05-14) Supersedes: Rev2 (pre-B3-ELD-EXEC; pre-B3-F1c-H) Authorizing review: knowledge/dev/laws/dieu44-trien-khai/reviews/gpt-review-b3f1c-h-trigger-b2-mode-a-pass-birth-automation-complete-2026-05-14.md Jurisdiction: NRM-LAW-35-V5P2 (note: hardcoded reference is TECH_DEBT_AFTER_BIRTH_COMPLETE, see §7)

0. Purpose

Rev3 formalizes the birth-time contract between the universal public.birth_registry table and the broader entity-living-DB enrichment surface, after:

  • B3-ELD-EXEC added three columns to birth_registry (commit verified).
  • B3-F1c-G repaired the dot-dot-health scheduler patch (commit bd2588a).
  • B3-F1c-H installed public.fn_birth_onboarding_full_scan_hc(jsonb) → boolean plus the system_health_checks row DOT-BIRTH-ONBOARD-FULLSCAN-HC.
  • B3-F1c-H Trigger B2 Mode A passed (hc_result=true, system_issues delta = 0).

Rev3 also makes explicit what is not part of birth — drawing the line between the birth insertion path and the steady-state health/enrichment path so Phase 5C2 readiness can be evaluated.

1. Column-by-Column Contract

Field Storage At-birth contract Post-birth behavior Source of truth Backfill plan
canonical_address birth_registry.canonical_address text NULL PLACEHOLDER_AT_BIRTH — column is nullable; birth triggers MAY leave NULL. Birth MUST NOT block on resolving canonical_address. DEFERRED_ENRICHMENT — populated later by an enrichment job/job-class (not yet designed). Per-collection canonical-address resolver (DEFERRED). NOT part of birth contract; tracked as separate ELD enrichment workstream.
owner birth_registry.owner text NULL PLACEHOLDER_AT_BIRTH — column is nullable; birth triggers MAY leave NULL. Birth MUST NOT block on owner resolution. DEFERRED_ENRICHMENT — populated later by an enrichment job. Per-collection ownership resolver (DEFERRED). NOT part of birth contract.
jsonb_profile birth_registry.jsonb_profile jsonb NOT NULL DEFAULT '{}'::jsonb REQUIRED_AT_BIRTH (container) — the column itself must exist and be NOT NULL. '{}'::jsonb is a valid default at birth. Birth triggers MUST NOT insert NULL. Empty object is intentional and contract-compliant. Future enrichers MAY merge structured profile data via jsonb_set / ` . Empty {}` remains a stable valid representation.
identity_profile NOT on birth_registry NOT_CENTRAL_BIRTH_REGISTRY — identity_profile is deliberately NOT a central column on birth_registry. Lives per-entity-kind on the relevant per-collection table where identity semantics differ by entity kind (e.g., humans, laws, dot_tools, normative_registry). Per-collection identity columns/sub-tables. N/A — never planned for central placement; see §3 rationale.

1.1 Existing columns (governance/audit, unchanged in Rev3)

id, sort, user_created, date_created, user_updated, date_updated, entity_code, collection_name, species_code, composition_level, dot_origin, born_at, governance_role, inspect_pen, inspect_stamp, inspect_gate, certified, certified_at, status — these 19 columns are as in Rev2, fully governed by the existing birth-triggering fan-out (fn_birth_registry_auto, fn_birth_registry_auto_id). Rev3 does NOT alter their semantics.

2. Birth Trigger Insertion Path (what is in scope)

The birth insertion path for any entity is the synchronous transaction that produces a birth_registry row when the source entity is created. Rev3 fixes this path to:

1. Source-collection INSERT  →  per-table BEFORE/AFTER trigger
                              →  fn_birth_registry_auto(...)
                              →  INSERT INTO public.birth_registry
                                  ( id, entity_code, collection_name, species_code,
                                    composition_level, dot_origin, born_at, governance_role,
                                    inspect_*, certified*, status,
                                    canonical_address := NULL,        -- placeholder
                                    owner            := NULL,         -- placeholder
                                    jsonb_profile    := '{}'::jsonb   -- container default
                                  )
  • The path MUST succeed even when canonical_address and owner cannot be resolved.
  • The path MUST NOT consult any health check, full-scan, or wrapper function.
  • The path MUST NOT call fn_birth_onboarding_full_scan_hc(...) or fn_birth_onboarding_full_scan() directly.

3. What is NOT in the Birth Insertion Path

The following are deliberately separated from birth and are NOT preconditions for inserting a birth_registry row:

Item Path Why not in birth
fn_birth_onboarding_full_scan_hc(jsonb) wrapper HEALTH path (DOT-BIRTH-ONBOARD-FULLSCAN-HC) Detect-only health rollup; runs out-of-band via dot-dot-health.dispatch_function or on-demand SELECT. Not a birth-time gate.
fn_birth_onboarding_full_scan() scanner HEALTH path Writes system_issues rows for governance gaps; not on the hot path.
Canonical-address resolution ENRICHMENT path Per-collection resolvers run async; null at birth is legal.
Owner resolution ENRICHMENT path Same as canonical_address.
Identity-profile materialization PER-ENTITY-KIND path Identity semantics differ by collection; centralizing them on birth_registry would force one-size-fits-all on heterogeneous entity kinds. Lives on per-collection tables.
description_policy collection_registry (NOT on birth_registry) Already governed at collection-row level; B3-DESC closed.

This separation is the central design choice of Rev3: birth ≠ enrichment ≠ health. They share columns where appropriate (e.g., enrichment writes to the same jsonb_profile container) but never block each other.

4. Wrapper / Full-Scan Health Path (the parallel surface)

  • Wrapper: public.fn_birth_onboarding_full_scan_hc(cfg jsonb DEFAULT '{}'::jsonb) RETURNS boolean
    • LANGUAGE plpgsql, SECURITY INVOKER, VOLATILE.
    • Comment prefix: B3-F1c-H wrapper.
    • Folds critical_count <= cfg.critical_threshold (default 0) to boolean.
    • INTENTIONAL_WRITE: inherits the scanner's system_issues writes.
  • Health-check row: system_health_checks where
    • code = DOT-BIRTH-ONBOARD-FULLSCAN-HC
    • executor_type = function, executor_ref = fn_birth_onboarding_full_scan_hc
    • is_active = true, severity_on_fail = critical
    • threshold_config = {"critical_threshold": 0}
    • order_index = 115, jurisdiction = NRM-LAW-35-V5P2
  • Dispatched by dot-dot-health cron (0 3 * * * /opt/incomex/dot/bin/dot-dot-health --local) AND on-demand via SELECT (Trigger B2 Mode A).
  • Trigger B2 Mode A executed once on 2026-05-14 → hc_result=true, no new system_issues rows.

This path exists alongside birth, not inside it.

5. Invariants

# Invariant
I-1 jsonb_profile is NOT NULL for every existing and future row of birth_registry. Live check: 0 nulls across 285,955 rows.
I-2 canonical_address and owner are nullable; a NULL value is contract-compliant at birth.
I-3 identity_profile does NOT appear as a column on birth_registry.
I-4 The birth trigger path does NOT depend on system_health_checks, the wrapper, the scanner, or dot-dot-health.
I-5 The wrapper and the scanner do NOT mutate birth_registry rows.
I-6 Triggers attached to birth_registry remain exactly: trg_birth_auto_certify, trg_birth_change_flag_matrix, trg_count_birth_registry.
I-7 Views v_entity_full_classification and v_species_matrix remain valid after the ELD column adds (planner check passes).

6. Rev2 → Rev3 Changes

Area Rev2 Rev3
canonical_address on birth_registry not present present, nullable, PLACEHOLDER_AT_BIRTH
owner on birth_registry not present present, nullable, PLACEHOLDER_AT_BIRTH
jsonb_profile on birth_registry not present present, NOT NULL DEFAULT '{}', REQUIRED_AT_BIRTH (container)
identity_profile on birth_registry proposed centrally (some drafts) explicitly NOT central — per-entity-kind only
Wrapper / full-scan in birth path unclear explicitly not in birth path; health-only
dot-dot-health cron scheduler broken (Unknown option: --local) repaired (commit bd2588a, sha256 28bc0b…b6bf2)
Health-check row for birth full-scan absent present and active

7. Known Tech-Debt Carried Forward (NOT blockers for birth completion)

  1. Hardcoded jurisdiction NRM-LAW-35-V5P2 in the wrapper comment and on the health-check row — must move to a jurisdiction-decoupling shim. TECH_DEBT_AFTER_BIRTH_COMPLETE.
  2. B3-A-DUP — 18 collections still carry duplicate birth-trigger pairs. Does not break birth; cleanup is TECH_DEBT_AFTER_BIRTH_COMPLETE.
  3. dot_tools registry drift — 5 items + 1 row mismatch. TECH_DEBT_AFTER_BIRTH_COMPLETE.
  4. system_issues rows 38781–38787 (ISS-37262..ISS-37268, severity=warning) — preserved per GPT directive, no deletion. TECH_DEBT_AFTER_BIRTH_COMPLETE.
  5. Backfill of canonical_address / owner / non-empty jsonb_profile — separate enrichment workstream. DEFERRED_ENRICHMENT.

None of these block the Rev3 contract: every birth insert succeeds with {canonical_address NULL, owner NULL, jsonb_profile {}} and contract Invariants I-1..I-7 hold.

8. Acceptance criteria (already met at the time of ratification)

  1. ELD columns landed and verified (§Verification Report §3).
  2. Wrapper present, comment prefix verified, health row active.
  3. Trigger B2 Mode A passed (hc_result=true, delta=0).
  4. Scheduler patch committed and present on VPS.
  5. Triggers and views still valid; row counts stable.

9. Outstanding work BEFORE Phase 5C2 resume

Item Class Notes
Post-ELD / B3F delta verification report REQUIRED_BEFORE_5C2 This Rev3 doc + its companion verification report jointly satisfy this once both are committed.
Optional: 03:00 UTC natural cron observation DIAGNOSTIC_ONLY Validates Trigger A path; not a blocker.
B3-DESC follow-up NOT_IN_SCOPE for birth-complete (RESOLVED at row level)
B3-A-DUP TECH_DEBT_AFTER_BIRTH_COMPLETE

After both Rev3 and the delta verification report are committed, birth automation is COMPLETE at the B3-F1c-H level and Phase 5C2 gating moves to the verification-report decision.