GPT Review — 22-P3 Design and Creation Gateway Redirection

Date: 2026-05-06
Reviewer: GPT-5.5 Thinking / Incomex Hội đồng AI
Reviewed: knowledge/dev/laws/dieu44-trien-khai/design/22-p3-iu-native-create-adapter-scope.md

Verdict

Opus design note is useful, but P3 scope must be redirected.

The adapter-only framing is too narrow. After user clarification, P3 should become IU Creation Gateway / Single Writer Gateway design, not merely “which adapter calls fn_iu_create?”

What Opus got right

• P2 closure summary is accurate.
• P2 did not redesign birth pipeline.
• fn_iu_create is canonical write path for new IU rows.
• Direct table INSERT is non-canonical except controlled migration/import.
• Existing incomplete states are health/remediation, not success.
• DOT wrapper/Directus endpoint should not be built prematurely.
• P3 should remain design/read-only first.

What must change

1. P3 is not just adapter scope

Current design asks mostly:

Which adapter should call fn_iu_create?

The correct question is broader:

How do we make it hard or impossible for Agent/DOT/App/Directus to create IU incorrectly, and if they try, how does the system block them and point them to the correct README/canonical function?

2. Option E “SQL-only and close P3” is not enough

Option E is acceptable as a temporary caller strategy, but it does not solve the user’s core problem:

• Agents and DOTs may still insert directly.
• Directus UI/admin may still create rows.
• Legacy TAC pipeline already does direct inserts.
• Future scripts may forget the process.

So P3 cannot simply close with “SQL-only.” It must design guardrails.

3. Authoring workflow is not just vision

The user explicitly asked about AI creating pieces and not forcing humans/agents to remember the process. Therefore authoring workflow is part of the gateway policy, even if implementation is later.

P3 should define the near-term authoring rule:

• Before adapter/gateway enforcement: dual-form authoring = rendered document + IU map.
• After gateway enforcement: new IU pieces use canonical create path.
• Legacy docs remain import/cut-after.

Do not mark it as irrelevant; mark implementation as later if needed.

New P3 direction — IU Creation Gateway

Create a new or revised design note:

knowledge/dev/laws/dieu44-trien-khai/design/22-p3-iu-creation-gateway-scope.md

This note should supersede or amend the adapter-only note.

Core philosophy

No one should need to remember the IU creation process.

System behavior should be:

1. If caller uses canonical path → system creates IU correctly.
2. If caller uses wrong path → system blocks and returns README/canonical instruction.
3. If bypass still slips through → detector/auxiliary system flags health incident and remediates according to policy.

Required P3 design structure

§1. P2 closure and current capability

Summarize:

• fn_iu_create exists and passed P2.
• fn_iu_create_plan exists and passed P2.
• birth remains trigger-based.
• fn_iu_create complete-or-nothing.
• auxiliary engine remains for bypass/legacy/drift.

§2. Creation Gateway model: 4 layers

Define 4 layers:

L0 — Policy/README registry

A permanent readme/policy entry tells every caller:

• canonical function: public.fn_iu_create(...);
• plan function: public.fn_iu_create_plan(...);
• forbidden path: direct insert into information_unit;
• remediation path for existing incomplete states;
• readme path.

Do not hardcode this text in triggers. Prefer dot_config, existing registry, or a future creation_policy registry.

L1 — Permission gate

Use PG privileges:

• revoke direct INSERT/UPDATE/DELETE from non-owner/non-migration roles where safe;
• grant EXECUTE on canonical function;
• keep PUBLIC revoked;
• consider future dedicated role, but do not invent one prematurely.

L2 — Trigger guard / wrong-door blocker

Design a BEFORE INSERT/UPDATE guard for information_unit:

• fn_iu_create sets session/local flag, e.g. set_config('app.canonical_writer','fn_iu_create',true).
• guard checks current_setting('app.canonical_writer', true).
• if absent/wrong, raise exception with README path and canonical function instruction.
• message text should come from policy registry/config where feasible, not hardcoded.

Important: This is design only. Do not implement trigger yet.

L3 — Detector / auxiliary engine

For bypass that cannot be blocked:

• superuser/manual restore/migration/legacy imports;
• old TAC pipeline;
• trigger disabled/replica-only incidents;
• schema drift.

Define detection:

• IU created without canonical marker;
• missing invariants;
• orphan/ghost/phantom;
• backfill invoked for fresh object.

If auxiliary fixes a fresh object that should have gone through main path, classify as health incident.

§3. Read-only inspection needed before enforcement

Before any revoke/trigger guard, P3-P0 must inspect:

• current table privileges on information_unit and unit_version;
• roles with direct INSERT/UPDATE/DELETE;
• existing triggers on IU;
• current Directus permissions/UI write path;
• TAC direct insert paths;
• existing migration/import scripts touching IU/UV;
• best location for policy registry/readme path (dot_config, collection_registry, dot_tools, new registry later);
• feasibility of set_config/current_setting marker without breaking existing triggers.

§4. TAC pipeline decision

The current design notes TAC/P10 direct inserts. P3 must make this a first-class decision:

• Does TAC migrate to fn_iu_create?
• Does TAC remain a controlled import path with separate audit?
• If controlled import, how is it exempted from trigger guard without becoming a general bypass?

Do not answer by assumption; recommend a P3-P0 read-only inventory if evidence is insufficient.

§5. Adapter options reframed

Adapter is only one layer after gateway policy.

Compare:

A. SQL-only canonical call for now.
B. Thin CLI wrapper that only calls fn_iu_create.
C. Directus/API endpoint.
D. Creation Gateway enforcement first, adapter later.
E. Full gateway: policy + permission + guard + detector.

Recommendation should likely be staged:

1. P3-P0 read-only inspection.
2. P3-P1 policy/readme registry design.
3. P3-P2 permission plan.
4. P3-P3 trigger guard design/prompt, only after evidence.
5. Adapter later if needed.

§6. Authoring workflow policy

Include, but scope properly:

• now: dual-form authoring — rendered document + IU map;
• after gateway callable path is established: AI/Agent creates IU through canonical path;
• legacy docs: import/cut-after pipeline;
• new production IU: canonical path only.

§7. Non-goals and boundaries

For this revised P3 design:

No mutation. No revoke. No trigger creation. No DDL. No function change. No adapter implementation. No DOT registration. No cleanup. No Pack 2C.

Immediate directive to Opus

Do not ask Agent to implement anything yet.

Patch/replace the P3 design as follows:

1. Create 22-p3-iu-creation-gateway-scope.md.
2. Preserve useful sections from adapter note, but reframe under Creation Gateway.
3. Add the 4-layer model L0/L1/L2/L3.
4. Add P3-P0 read-only inspection proposal.
5. Add TAC pipeline as first-class decision.
6. Reclassify authoring workflow as near-term policy + later implementation, not irrelevant vision.
7. Recommend staged next step: P3-P0 read-only inspection prompt, not adapter execution.

Expected Opus response

Opus should return:

• new design path;
• summary of changed framing;
• explicit recommendation for P3-P0 read-only inspection;
• no dispatch yet.

Summary

P2 solved the canonical IU create function. P3 must now solve gateway governance: prevent wrong creation paths, guide offenders to README/canonical function, and detect unavoidable bypasses. Adapter choice is downstream of that gateway decision, not the main issue.