Incomex AI Portal
KB-1207

P3D Birth System — B3-A2a Variant Function Equivalence Probe

11 min read Revision 1
p3d-birthb3-a2avariant-functionequivalence-proberead-onlyreport

title: P3D Birth System — B3-A2a Variant Function Equivalence Probe mainline: P3D_BIRTH_SYSTEM_COMPLETION_PACK phase: B3-A2a status: PASS verdict: SAFE_WITH_NOTE mode: READ-ONLY date: 2026-05-12 host: 38.242.240.89 db: postgres (container=postgres, db=directus)

B3-A2a — Variant Function Equivalence Probe

Read-only inspection of whether fn_birth_registry_auto_id is a safe contract sibling of fn_birth_registry_auto. No mutations were performed.

1. Function Resolution

Function OID Language Returns
public.fn_birth_registry_auto 39232 plpgsql trigger
public.fn_birth_registry_auto_id 66750 plpgsql trigger

2. Function Bodies (pg_get_functiondef)

2.1 Contract — fn_birth_registry_auto

CREATE OR REPLACE FUNCTION public.fn_birth_registry_auto()
 RETURNS trigger LANGUAGE plpgsql
AS $function$
DECLARE
  v_entity_code text; v_code_field text; v_species_code text;
  v_comp_level text; v_gov_role text; v_dot_origin text;
  v_row_json jsonb;
BEGIN
  v_row_json := to_jsonb(NEW);

  IF TG_NARGS > 0 THEN
    v_code_field := TG_ARGV[0];
    v_entity_code := v_row_json->>v_code_field;
  END IF;
  IF v_entity_code IS NULL OR v_entity_code = '' THEN
    v_entity_code := TG_TABLE_NAME || '::' || (v_row_json->>'id')::text;
  END IF;

  IF EXISTS (SELECT 1 FROM birth_registry
             WHERE entity_code = v_entity_code AND collection_name = TG_TABLE_NAME) THEN
    RETURN NEW;
  END IF;

  v_dot_origin := v_row_json->>'_dot_origin';
  IF v_dot_origin IS NULL OR v_dot_origin = '' THEN
    v_dot_origin := 'PG:trg_birth_' || TG_TABLE_NAME;
  END IF;

  SELECT scm.species_code, es.composition_level
    INTO v_species_code, v_comp_level
    FROM species_collection_map scm
    LEFT JOIN entity_species es ON es.species_code = scm.species_code
    WHERE scm.collection_name = TG_TABLE_NAME AND scm.is_primary = true
    LIMIT 1;

  SELECT governance_role INTO v_gov_role
    FROM collection_registry WHERE collection_name = TG_TABLE_NAME LIMIT 1;

  INSERT INTO birth_registry (
    entity_code, collection_name, species_code, composition_level,
    dot_origin, born_at, governance_role, certified
  ) VALUES (
    v_entity_code, TG_TABLE_NAME, v_species_code, v_comp_level,
    v_dot_origin, now(), COALESCE(v_gov_role, 'excluded'), false
  ) ON CONFLICT (entity_code) DO NOTHING;

  RETURN NEW;
END;
$function$;

2.2 Variant — fn_birth_registry_auto_id

CREATE OR REPLACE FUNCTION public.fn_birth_registry_auto_id()
 RETURNS trigger LANGUAGE plpgsql
AS $function$
DECLARE
  v_entity_code text; v_species_code text;
  v_comp_level text; v_gov_role text;
BEGIN
  v_entity_code := TG_TABLE_NAME || ':' || NEW.id::text;

  IF EXISTS (SELECT 1 FROM birth_registry WHERE entity_code = v_entity_code) THEN
    RETURN NEW;
  END IF;

  SELECT scm.species_code, es.composition_level
    INTO v_species_code, v_comp_level
    FROM species_collection_map scm
    LEFT JOIN entity_species es ON es.species_code = scm.species_code
    WHERE scm.collection_name = TG_TABLE_NAME AND scm.is_primary = true
    LIMIT 1;

  SELECT governance_role INTO v_gov_role
    FROM collection_registry WHERE collection_name = TG_TABLE_NAME LIMIT 1;

  INSERT INTO birth_registry (
    entity_code, collection_name, species_code, composition_level,
    dot_origin, born_at, governance_role, certified
  ) VALUES (
    v_entity_code, TG_TABLE_NAME, v_species_code, v_comp_level,
    'PG:trg_birth_' || TG_TABLE_NAME, now(),
    COALESCE(v_gov_role, 'governed'), false
  ) ON CONFLICT (entity_code) DO NOTHING;

  RETURN NEW;
END;
$function$;

3. Trigger Bindings

fn_birth_registry_auto (OID 39232): bound to 144 enabled triggers across 78 collections (full list captured in B3-A readiness rerun report §6).

fn_birth_registry_auto_id (OID 66750): bound to exactly 3 enabled triggers, all AFTER INSERT on the 3 IN_SCOPE variant collections.

Collection Trigger Enabled
governance_relations trg_birth_governance_relations yes
law_dot_enforcement trg_birth_law_dot_enforcement yes
law_jurisdiction trg_birth_law_jurisdiction yes

No other tables use the variant function. No use of TG_ARGV is wired on any contract binding for these 3 tables.

4. Behavioural Diff

Aspect Contract fn_birth_registry_auto Variant fn_birth_registry_auto_id Observable in the 3 variant tables?
entity_code construction TG_TABLE_NAME || '::' || id (double colon); optional column override via TG_ARGV[0] TG_TABLE_NAME || ':' || NEW.id (single colon) Yes — separator differs (:: vs :). See §5.
Dedup EXISTS scope entity_code AND collection_name entity_code only No — birth_registry_entity_code_unique UNIQUE(entity_code) makes the difference moot. ON CONFLICT(entity_code) is authoritative.
_dot_origin source Read NEW._dot_origin if present, else synthetic 'PG:trg_birth_' || TG_TABLE_NAME Always synthetic No — none of the 3 variant tables has a _dot_origin column (information_schema.columns lookup = false for all three), so contract would fall back to the same synthetic value.
governance_role default when lookup misses COALESCE(..., 'excluded') COALESCE(..., 'governed') No — collection_registry.governance_role='governed' is populated for all 3 (verified live). The COALESCE default branch is unreachable today.
species_code lookup Identical query, is_primary=true, LEFT JOIN entity_species Identical Equivalent
composition_level lookup From entity_species via LEFT JOIN Identical Equivalent
ON CONFLICT clause (entity_code) DO NOTHING (entity_code) DO NOTHING Equivalent
born_at, certified now(), false now(), false Equivalent

birth_registry_entity_code_unique confirmed via pg_constraint: UNIQUE (entity_code).

5. Sample birth_registry Evidence

Variant-emitted rows (entity_code single colon, gov='governed'):

governance_relations:11  | gov=governed | dot=PG:trg_birth_governance_relations  | species=governance_relation
governance_relations:10  | gov=governed | dot=PG:trg_birth_governance_relations  | species=governance_relation
…
law_dot_enforcement:272  | gov=governed | dot=PG:trg_birth_law_dot_enforcement   | species=law_enforcement
law_dot_enforcement:273  | gov=governed | dot=PG:trg_birth_law_dot_enforcement   | species=law_enforcement

Contract-emitted rows (entity_code double colon):

knowledge_documents::2988 | gov=observed | …
species_collection_map::169 (this session's B3-A1b insert)

Row counts in birth_registry for the 3 variant tables:

Collection Count
governance_relations 8
law_dot_enforcement 272
law_jurisdiction 43

6. Equivalence Analysis

Given current PG state, fn_birth_registry_auto_id produces functionally equivalent birth_registry rows to fn_birth_registry_auto for the 3 variant-bound collections, with one observable surface difference:

  • entity_code separator (: vs ::). New rows produced by a contract-trigger swap would write collection_name::id. Existing variant rows remain collection_name:id. Both formats coexist without UNIQUE violation, and the dedup EXISTS guard would not match across separators — so swap-time double-write is avoided per row but historical entity_codes remain in the legacy format.

All other COALESCE/default branches that diverge between the two functions are unreachable today because:

  1. _dot_origin column does not exist on the 3 variant tables → contract function's override branch returns NULL → falls back to the same synthetic dot_origin the variant uses.
  2. collection_registry.governance_role is populated ('governed') for all 3 tables → COALESCE never hits the diverging default ('excluded' vs 'governed').

No use of TG_ARGV[0] is present in the variant-bound trigger declarations, so the contract function's optional code-field feature is irrelevant to this swap.

7. Risks & Caveats

Risk Severity Mitigation
entity_code separator skew (legacy : vs new ::) LOW Acceptable since UNIQUE(entity_code) prevents collision; consumers querying by LIKE 'governance_relations:%' would still match both formats. Document in DOT registry.
Future schema change adds _dot_origin to one of the 3 tables LOW Contract function would then read the column, changing behavior — desired. Variant function would silently ignore.
Future change unsets collection_registry.governance_role LOW Contract default 'excluded' vs variant default 'governed' would diverge. Add invariant test asserting governance_role IS NOT NULL for IN_SCOPE rows.
Cross-table dedup loosening in variant function NONE (today) UNIQUE(entity_code) + ON CONFLICT(entity_code) provides identical guarantees.
Hidden TG_ARGV use on any future contract trigger NONE (today) Verified zero TG_ARGV on the 3 variant triggers.

8. Verdict

b3a2a_equivalence_verdict = SAFE_WITH_NOTE

fn_birth_registry_auto_id is a safe contract sibling of fn_birth_registry_auto for the 3 IN_SCOPE variant-bound collections in the current PG state. The sole observable divergence is the entity_code separator (: vs ::).

Two acceptable resolutions; both READ-ONLY today, no install in this phase:

  • Option A — Consolidate. Replace the 3 variant triggers with contract triggers on the same tables. New rows would adopt :: separator; historical : rows remain. Pros: single function, simpler invariant. Cons: separator skew in birth_registry over time.
  • Option B — Whitelist the variant. Formally treat fn_birth_registry_auto_id as a contract sibling in the B3-A readiness validator (whitelist OID 66750 alongside 39232). Pros: zero churn, preserves separator consistency for legacy entries. Cons: two functions to maintain; equivalence must be re-verified on every change to either.

If both functions are expected to evolve, Option A is preferred for long-term simplicity. If birth_registry consumers depend on the : separator for these 3 tables, Option B is preferred.

10. Mutation Confirmation

no_mutation_performed = true. Read-only queries only: pg_proc, pg_trigger, pg_class, pg_namespace, pg_constraint, information_schema.columns, public.collection_registry, public.species_collection_map, public.birth_registry. No INSERT/UPDATE/DELETE/DDL; no policy, trigger, or function changes.

next_recommended_action = GPT_REVIEW_B3A2A_PROBE

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/reports/p3d-birth-system-b3a2a-variant-function-equivalence-probe-report.md