Incomex AI Portal
KB-4DBA

New IU 2 — Logical Architecture (thin Subject Contract over PG/Matrix/Lego/One-Roof)

19 min read Revision 1
laws-newnew-iudesignlogical-architecturethin-contractsubject-contractthree-layeranti-islandpg-firstone-roofnon-authorizingdesign-only2026-06-21

New IU — Macro 2: Logical Architecture

Path: knowledge/dev/laws-new/new-iu/design/01-new-iu-logical-architecture.md Date: 2026-06-21 Macro: NEW_IU_1_2 — Phase 2 (logical architecture, design-only). Authority class: DESIGN-INFERENCE on top of DRAFT-NON-ENACTING direction (brief §C/§4/§9, approved as direction by approval-note, NON-AUTHORIZING_FOR_RUNTIME). This document authorizes nothing. No DDL, no migration, no schema, no construction plan, no pilot, no implementation task list. It is a logical boundary design only. Consumes: survey/01-new-iu-readonly-pg-cell-carrier-and-reuse-map.md (current-pass evidence, same macro). Builds on: approved direction — "New IU = lớp Subject Contract mỏng trên PG/Matrix/Lego/One-Roof; giữ điểm mạnh của miếng thông tin cũ nhưng không xây vương quốc IU riêng."

1. New IU logical definition

New IU is a thin Subject Contract. It is the logical statement of "this is one stable, addressable, versioned subject of knowledge, and here is the minimum needed to find it, know its current state, and reference the shared machinery that checks/promotes/governs it." It is not a storage engine, not a control plane, not a governance/birth/KG/approval/DOT/axis system.

Formally, a New IU instance is a logical record that binds (not owns):

  1. a stable logical identity (carrier-independent);
  2. a carrier reference to where the bytes actually live (PG row / collection / matrix cell / staging candidate / document section / projection);
  3. current / head / supersession semantics;
  4. a semantic payload boundary (what is inside this unit vs. the next);
  5. minimal metadata for Text-as-Code / KG / context / release;
  6. reference handles (foreign-key or verdict references) to shared IO Contract, checker, promote, owner, approval, and audit artifacts.

Everything in (6) is referenced, never re-implemented. The contract is "thin" precisely because items 1–5 are the only things New IU owns; the heavy machinery is borrowed.

Anchor in /laws-new/: Điều 38 v3 / LSL-01 — the unit (unit_version) is the SSOT subject; file / vector / KB-markdown / Qdrant are projections. New IU is the contract over that subject, not a new subject.

2. The three-layer split

The brief's §4 split, made concrete against the live carrier (survey §3–§4). Hard rule (verbatim from brief): "New IU PHẢI tham chiếu các hệ chung ở Lớp B và Lớp C; nó KHÔNG được sở hữu hay nhân đôi chúng."

Layer A — IU Subject Contract (New IU OWNS)

The only layer New IU owns. Logical fields in §4. Carried on the existing information_unit row + unit_version history + identity_profile jsonb; no new table is required to express Layer A (current-pass: the columns already exist — id, canonical_address, version_anchor_ref, content_anchor_ref, lifecycle_status, identity_profile). Repairs (not new storage): bind owner to shared ownership instead of owner_ref; bind conformance close to a checker verdict.

Layer B — Shared Matrix/Lego IO Contract (New IU REFERENCES)

  • io_contract.v0.1 = the 5-field boundary nhận · trả · schema_min · fail · rollback (Đ38 A9 thin contract; NOT Module-Contract-First — CONS-002 must pick the winner before this is built).
  • Cell/matrix placement (cell_id as an attribute of meta_catalog/collection_registry), formula/assembly interface, checker integration shape.
  • New IU stores a reference to the IO Contract record for its cell; it never defines a second contract registry.

Layer C — Shared checker / promote / governance / runtime envelope (New IU REFERENCES)

  • Verdict-only checker (PROMOTE_OK / PROMOTE_BLOCKED / ESCALATE_L3), bound by candidate_id + packet_hash.
  • Stamp ledger = birth_registry inspect_pen/stamp/gate → certified; BIRTH_STAMP/PROMOTE_STAMP are outputs at promote.
  • Atomic Promote Contract (HOLD-2 — does not exist yet), rollback, owner gate (governance_object_ownership), approval (Đ32 APR), DOT execution (dot_tools), event/issue/changelog sinks.
  • New IU stores verdict references to these; it never owns checker, promote, owner, approval, or DOT.
            ┌─────────────────────────────────────────────┐
  OWNS  →   │ Layer A: IU Subject Contract                 │  thin, logical
            │  id · carrier_ref · head/super · boundary ·  │
            │  metadata · {refs→B,C}                        │
            └───────────────┬──────────────┬───────────────┘
                            │ ref          │ ref
            ┌───────────────▼───┐   ┌──────▼───────────────────────┐
  REF   →   │ Layer B: IO Contract│  │ Layer C: checker/promote/    │
            │ (Matrix/Lego)       │  │ governance/runtime (One-Roof)│
            └─────────────────────┘  └──────────────────────────────┘
                            │              │
            ┌───────────────▼──────────────▼───────────────┐
 CARRIER →  │ PG / collection / matrix cell / staging /     │  storage owns
            │ projection  (information_unit, unit_version…) │  identity+rows+audit
            └───────────────────────────────────────────────┘

3. Carrier model

A New IU instance can be carried by any of these, chosen per instance (the carrier reference in Layer A names which one):

Carrier Live object (current-pass) When used
PG row information_unit row (+ unit_version) default for governed, addressable knowledge units (law_unit, design_doc_section live today).
Collection collection_registry / meta_catalog entry when the subject is a whole collection/kho rather than one row.
Matrix cell cell_id attribute on meta_catalog/collection_registry (NOT a new table) when the subject is a Tầng×Loài×Kho×Miền cell. Not materialized while CONS-003/CELL open.
Document section information_unit with unit_kind=design_doc_section + section_* cols live today (32 rows).
Staging candidate iu_core.iu_staging_record/payload (LIVE 15/32) pre-promote candidate; gated runtime OFF.
Generated projection render output (fn_iu_compose) / vector (iu_vector_sync_point → Qdrant) derived artifacts; never the subject, always a projection of it.

Rule: the carrier owns the bytes and the identity row; Layer A only holds a reference to the carrier plus the thin contract. No new carrier table is introduced — every role maps to a live object (survey §4).

4. Contract fields (logical level only)

Logical names; not a DDL spec, not column types, not a migration. Mapped to live carrier where a column already exists.

Logical field Meaning Live carrier mapping (current-pass) Note
subject_id stable, carrier-independent logical identity information_unit.id (uuid) reuse; do not fork.
carrier_ref where the payload lives canonical_address + unit_kind + (parent_or_container_ref) already 0-null.
head_ref current/head version pointer version_anchor_ref + content_anchor_ref already 0-null; resolver = view.
lifecycle_state draft/enacted/deprecated/retired/superseded lifecycle_status live, 4 states exercised.
supersession_ref what this supersedes / is superseded by derive from unit_version lineage + lifecycle_status needs base_version_ref for full lineage (defer).
payload_boundary semantic in/out boundary of this unit identity_profile jsonb + piece membership jsonb, no new column.
min_metadata minimal Text-as-Code/KG/context/release metadata identity_profile jsonb thin; not a metadata kingdom.
owner_ref→ reference to owner of record governance_object_ownership (target) NOT the free-text owner_ref; blocked at 0 rows (OP-B).
io_contract_ref→ reference to Layer-B IO Contract io_contract.v0.1 record id CONS-002 must resolve source.
checker_verdict_ref→ reference to last checker verdict Layer-C checker output (candidate_id+packet_hash) verdict, not owned.
conformance_ref→ conformance state bound to a verdict conformance_status (repair: bind close to verdict) today stuck open for all 219.
relation_ref→ reference to KG edges iu_relation (native, provenance) and/or shared KG projection target undecided (§7).

Owned vs referenced: subject_id, carrier_ref, head_ref, lifecycle_state, supersession_ref, payload_boundary, min_metadata are owned (Layer A). Everything ending → is a reference (Layer B/C). No owned field duplicates a shared system.

5. Lifecycle (logical level only)

Logical states, mapped to live lifecycle_status values; transition authority lives in shared promote/Đ32, not in IU:

 (INSERT)            (promote, F4)            (supersede)        (retire)
  TEMP  ──────▶  DRAFT ──────▶ ENACTED ──────▶ DEPRECATED ──────▶ RETIRED
  uncertified    review-       BIRTH_STAMP/    head moves to       no delete
  identity only  required      PROMOTE_STAMP   successor           (TTL fail-safe)
  • INSERT = TEMP (F1): permanent identifier + uncertified birth_registry record (certified=false); completeness = a TEMP stamp, not a canonical gate (L4 amendment).
  • DRAFT → ENACTED = promote (F4): only via fail-closed checker + Atomic Promote Contract + owner/Đ32 approval. Outputs BIRTH_STAMP/PROMOTE_STAMP. HOLD-2: this transaction does not exist yet — the lifecycle edge is designed, not buildable today.
  • DEPRECATED / RETIRED = supersession: fn_iu_supersede/fn_iu_retire live; "nghi ngờ thì không xóa" (no hard delete).
  • Current-pass distribution proves the live states are real (enacted 146 / draft 58 / deprecated 12 / retired 3).
  • Authority rule: New IU never self-certifies. Transition authority = shared checker + owner + Đ32. IU only records the reference to the authorizing verdict.

6. Current / head / supersession semantics

  • Current/head = head_ref (version_anchor_ref + content_anchor_ref), resolved by a read-only view/projection (e.g. v_iu_head), not a new service or table. Current-pass: HEAD is always set (0-null), so the resolver is a pure projection over existing columns.
  • Supersession = a relation + a lifecycle transition: the superseded unit moves to deprecated/retired; the successor's head_ref advances; the link is recorded as an edge (Layer-C relation reference) — not as a bespoke supersession table.
  • Immutability = unit_version is INSERT-only (the commit log); canonical_address immutable. New IU preserves this strength; it does not add a mutable history store.
  • What is intentionally deferred: full diff-base lineage (base_version_ref) and 3-way merge belong to the Text-as-Code engine (§8, Phase 5), not to this contract.

7. KG relation approach (without preselecting universal_edges)

Current-pass evidence is decisive (survey §3.3):

  • universal_edges: 0 provenance, 0 IU edges, integer-keyed (source_id integer), while information_unit.id is uuid → an identity-type impedance mismatch and an empty/unprovenanced target for IU.
  • iu_relation: uuid-keyed, all 60 rows provenance/assertion_mode/confidence-bearing, bitemporal valid_time — but only one edge type (contains).

Logical approach (no preselection):

  1. New IU references relations through a relation abstraction, not a concrete table. Layer A holds relation_ref→, resolved by a governed read-only projection.
  2. Two live candidates remain open: (a) IU-native edge = keep iu_relation (uuid + provenance) as the system-of-record and expose a governed read-only projection to the shared KG; (b) shared KG = universal_edges / Điều 39 — only after substrate verification (fact-type, provenance, owner, liveness) closes the gaps above and the uuid↔integer mapping is solved.
  3. Hard rule (anti-island §3 of brief): no second graph SoT; Điều 39 is enacted but runtime-empty and must not be assumed live or block.
  4. Decision is Owner-gated and verify-first (Owner question #8). This document does not choose; it keeps both options live and forbids preselecting universal_edges.

8. Text-as-Code capability map

What the contract enables by reference vs. what is deferred:

Capability Live today (current-pass) Class
Atomic governed birth (complete-or-nothing) fn_iu_create (gateway enforced) REUSE (wrapper)
Immutable commit history + HEAD unit_version + anchors REUSE
Edit-draft path (PR-like) fn_iu_create_edit_draft/apply_edit_draft/edit/save (require_review) REUSE (wrapper)
Enact (draft→enacted) fn_iu_enact (review_decision required) REUSE (wrapper)
Supersede / retire fn_iu_supersede/retire REUSE (wrapper)
Cut → pieces → reconstruct fn_iu_reconstruct_source, iu_piece_*, structure ops (gated off) REUSE (gated)
Compose / render fn_iu_compose/collection_render REUSE (projection)
Vector projection w/ boundary iu_vector_sync_point + Qdrant (sync off) REUSE (gated)
diff / blame / revert / patch / 3-way merge / lint / impact DESIGN-ONLY / MISSING DEFER → Phase 5
unit_proposal + review state machine DESIGN-ONLY DEFER → Phase 5

Logical stance: the contract exposes references to the live capabilities and names slots for the deferred ones — it does not build the engine. Text-as-Code expansion (Phase 5) is NO-GO until a pilot is stable.

9. Anti-island rules (binding on this design)

Carried verbatim-in-spirit from brief §9; any violation = revert to Phương án A (rejected):

  1. No own governance — One-Roof (governance_object_ownership/governance_role/governance_audit_log).
  2. No own birth — birth_registry; TEMP at INSERT, canonical at promote.
  3. No own KG — shared KG after verify; universal_edges not preselected; IU-native edge + governed projection allowed; no second graph SoT.
  4. No own registry — no new ledger unless all 5 no-new conditions proven.
  5. No own approval — Điều 32 APR.
  6. No own DOT kingdom, no second writable DOT catalog — migrate dot_iu_command_catalog→dot_tools; read-only compat view only.
  7. No hardcoded axis — open Axis Registry; no cell_id/dot_role/Species-Matrix materialization while CONS-003/CELL open; iu_three_axis_envelope = migrate-then-deprecate.
  8. No duplicate storage — PG/collection is carrier; candidate packet prefers view/projection; new store only after no-new proof + Owner.
  9. Owner-gated / non-authorizing — everything HOLD until promote via correct path; scanner list-only; KB admission ≠ runtime registration.

10. Replaceability / rollback boundary (Safety-Lock 7.1 self-check)

Each Layer-A-owned part is independently born / checked / replaced / rolled back / assembled-by-contract:

Part Born separately? Checked separately? Replaced separately? Rolled back separately? Assembled by contract?
Subject identity row ✅ fn_iu_create (TEMP) ✅ birth inspect_* ✅ supersede ✅ uncertified→discard ✅ via carrier_ref
Version/commit ✅ INSERT-only ✅ verify_invariants ✅ new version ✅ HEAD pointer move ✅ head_ref
Carrier reference ✅ per instance ✅ address discipline ✅ re-point ✅ re-point ✅ carrier_ref
Head/current resolver ✅ projection ✅ view test ✅ view swap ✅ no state ✅ read-only view
Relation reference ✅ edge row ✅ provenance ✅ projection swap ✅ edge soft-close ✅ relation_ref
Layer-B/C references ✅ by ref ✅ verdict ✅ re-reference ✅ re-reference ✅ foreign/verdict ref

All rows pass — no part is TOO_COUPLED. Anything that could not pass (e.g. a fused "IU engine") is excluded by construction.

11. What this logical design intentionally does NOT solve

  • It does not choose the KG edge target (IU-native vs universal_edges/Đ39) — verify-first, Owner-gated.
  • It does not assign owner-of-record (governance_object_ownership=0, OP-B) — Owner decision.
  • It does not resolve CONS-002 (IO Contract source) — must close before Layer-B spec.
  • It does not build / specify the Atomic Promote Contract (HOLD-2) or the fail-closed checker — separate Owner-authorized mission.
  • It does not materialize cell_id/dot_role/axis/Species-Matrix (CONS-003/CELL-003/004/007).
  • It does not build the Text-as-Code engine (diff/merge/blame/patch/lint/impact/unit_proposal) — Phase 5.
  • It does not define DDL, columns, types, indexes, triggers, migration, or a build task list.
  • It does not touch Directus / Nuxt / Qdrant / runtime — all NO-GO.

12. Gate to technical design

Technical design (NEW_IU_3) may begin only when, per /laws-new/ Default-HOLD discipline:

Governance decisions (Owner can decide — ballot):

  • OP-B owner model (assign governance_object_ownership, deprecate owner_ref).
  • DOT migration confirm (dot_iu_command_catalog→dot_tools + read-only view).
  • SB-3 axis generalization (Axis Registry; migrate-then-deprecate the 3-axis envelope).
  • CONS-002 IO Contract source winner.
  • CONS-003 + CELL-003/004/007 tier/cell source.
  • Đ32 approval routing for IU review.
  • KG-target choice after substrate verification.

Technical-readiness obligations (cannot be waived by Owner):

  • HOLD-2 Atomic Promote Contract + fail-closed checker exist and proven.
  • conformance_status close bound to checker verdict.
  • RISK-BYPASS handled (fn_auto_approve_add, fn_birth_gate warn-mode).
  • Điều 39 KG substrate verified (fact-type/provenance/owner/liveness).
  • TTL/cleanup/rollback + no-new-store proof.

Until both columns clear, Default = HOLD. Owner approval does not waive technical PASS (brief §14, RR2-03). KB admission ≠ runtime registration.