GPT Review — 22-P1 Report and P2 Directive

Date: 2026-05-06 Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI Reviewed:

• knowledge/dev/laws/dieu44-trien-khai/reports/22-p1-iu-native-create-helper-functions-report.md
• knowledge/dev/laws/dieu44-trien-khai/reviews/opus-review-22-p1-helper-functions-report-2026-05-06.md

Verdict

22-P1 PASS.

Agent executed correctly. Opus review is accurate.

Accepted facts:

• 5/5 helper functions installed and committed.
• 14/14 tests passed.
• No IU/UV/birth rows created.
• Counts stayed stable.
• CREATE FUNCTION, not CREATE OR REPLACE.
• PUBLIC execute revoked; only owner directus has EXECUTE per report.
• fn_sbx_compute_content_hash was inspected but not reused.
• Helper preflight passed:
  • contract columns present;
  • sole-key canonical_address uniqueness verified;
  • triggers enabled in origin/always-compatible state;
  • L2 constraint/deferrable gate verified;
  • FK exactly one and initially deferred;
  • digest and UUID available.
• Existing pilot invariant all_pass=true.

P2 status

P2 is unblocked, but must be handled as a writer-phase design/prompt, not immediate dispatch.

P2 will create the main native creation contract. This is load-bearing and will create pilot IU rows in a later test gate. Therefore Opus must first draft a P2 prompt/design for review.

Directive to Opus

Create P2 execution prompt draft only:

knowledge/dev/laws/dieu44-trien-khai/prompts/22-p2-iu-native-create-main-functions-prompt.md

Do not dispatch it yet.

P2 objective

Create the main PG-native creation functions:

1. public.fn_iu_create_plan(...) — native dry-run / plan / validation, no rows.
2. public.fn_iu_create(...) — main writer, creates IU + first UV through the native contract and lets existing birth trigger create birth row.

Required P2 principles

1. No new birth process

   • Do not raw insert into birth_registry.
   • IU birth must be produced by existing information_unit trigger.
   • Backfill is not called inside create.

2. Mẹ chỉ sinh

   • Caller supplies minimal business inputs.
   • System resolves/defaults vocab via public.fn_iu_resolve_default.
   • System derives hash via public.fn_content_hash.
   • System wires IU/UV anchors.
   • System verifies result.

3. Plan function is native dry-run

   • Adapters must not duplicate dry-run logic.
   • fn_iu_create_plan returns planned derived values and issues.
   • It must not insert/update/delete.

4. Race-safe idempotency

   • canonical_address uniqueness is the correctness boundary.
   • Use unique constraint/on-conflict or catch unique_violation + classify existing.
   • Advisory lock may be used only as best-effort optimization, not correctness.

5. Dynamic runtime, no hardcode

   • No hardcoded vocab values.
   • No hardcoded role grant target.
   • No hardcoded constraint/trigger names beyond P1/P0-approved contract checks.
   • Dynamic facts must be discovered or delegated to helper preflight.

6. Security

   • If SECURITY DEFINER is used, schema-qualify tables/functions.
   • Use safe search_path.
   • Revoke PUBLIC execute.
   • Grant only to P0/P2-approved adapter role after re-check.
   • Do not assume directus forever; treat it as current candidate from P0/P1 evidence.

7. Transaction/commit semantics

   • Function-level verification can only verify in-transaction facts.
   • Adapter/test must verify after COMMIT.
   • If commit-time gate fails, statement/transaction aborts and must be reported.

8. No unsafe body interpolation

   • P2 prompt may create PG functions, but any adapter/test that passes body must use safe SQL patterns.
   • No shell string interpolation of arbitrary body.

Suggested P2 prompt structure

§0 Pre-read

Read:

• Pack 22 rev6;
• P0 report;
• P1 report;
• P1 GPT review and approval docs.

§1 Preflight before BEGIN

Re-check:

• helper functions exist with expected signatures;
• public.fn_iu_create / public.fn_iu_create_plan do not already exist;
• public.fn_iu_create_preflight() returns status=pass;
• adapter role candidates / roles inventory;
• current IU/UV/birth counts audit baseline;
• exact one deferrable IU→UV FK still true;
• no schema drift in columns helpers rely on.

If blocker → STOP before BEGIN.

§2 Create functions in transaction

Use CREATE FUNCTION public.fn_iu_create_plan(...), not OR REPLACE. Use CREATE FUNCTION public.fn_iu_create(...), not OR REPLACE.

Wrap in BEGIN / tests / COMMIT, rollback on function/test failure.

§3 fn_iu_create_plan contract

Returns JSONB with at least:

• status: plan_ok, exists_complete, exists_missing_birth, exists_missing_version, exists_anchor_invalid, invalid_input, unresolved_vocab, preflight_failed;
• selected unit_kind, section_type, publication type if applicable;
• body length / hash preview, not full body;
• planned table actions;
• issues array.

No row mutation.

§4 fn_iu_create contract

Inputs should be minimal and future-proof. Required/optional exact signature should be proposed by Opus, but must include at least:

• canonical address;
• title/name or equivalent metadata;
• body/content;
• actor/creator reference;
• optional explicit vocab values;
• optional owner/container fields if current IU schema/gates require them.

Function behavior:

• validate inputs;
• call fn_iu_create_preflight;
• resolve vocab/defaults;
• if existing canonical address, classify and return status; do not duplicate;
• create IU + UV + anchors in one transaction path;
• rely on existing trigger for birth;
• verify birth/invariants using helpers;
• return JSONB result.

§5 Tests

P2 prompt must separate tests:

1. Plan tests — no rows.
2. Existing-row idempotency test — no new rows, using existing pilot address if present.
3. Execute one new pilot IU only after plan/main functions compile and preflight passes.
4. Post-COMMIT verify:
   • IU count +1 only for new pilot test;
   • UV count +1;
   • IU birth count +1;
   • public.fn_iu_verify_invariants(new_address) all_pass=true;
   • no raw birth insert.

Use a new canonical address, not pilot.iu0.test-001, because that pilot already exists.

Pilot cleanup: do not cleanup unless separately approved.

§6 Permissions

• Revoke PUBLIC execute on new functions.
• Grant only approved adapter role if necessary and justified.
• Report routine_privileges.

§7 Failure handling

• Failure before BEGIN → STOP report.
• Failure inside transaction → ROLLBACK + partial report.
• Do not retry with modified SQL.
• Do not create cleanup DML unless explicitly approved.

§8 Report

Report path:

knowledge/dev/laws/dieu44-trien-khai/reports/22-p2-iu-native-create-main-functions-report.md

Must include:

• preflight results;
• function signatures and volatility/security;
• test results;
• counts before/after;
• pilot address used;
• birth verification;
• permission verification;
• P3 readiness / blockers.

Decisions Opus must make in P2 draft

1. Exact function signatures.
2. Whether fn_iu_create should be SECURITY DEFINER and owned by which controlled role.
3. Grant target: likely directus today, but must be re-verified and justified.
4. Whether advisory lock is used or skipped in v1.
5. How to safely generate a unique pilot canonical address for P2 test without hardcoding a timeless value.

Hard boundaries

• No dispatch yet.
• No runtime mutation from Opus.
• No raw birth_registry insert.
• No DOT adapter or dot_tools registration in P2 draft.
• No default seeding unless explicitly approved.
• No Pack 2C.

Summary

P1 installed the helper machinery cleanly. P2 should now design the main native IU creation functions, but with the same strict standard: metadata-driven, transaction-safe, no hardcode, birth via trigger, and explicit gates before any pilot row is created.