P3D — Information Unit / Text-as-Code Requirements Specification

Date: 2026-05-10 Status: RE-AUTHORED 2026-05-10 — NOT the verbatim original spec from session 2792e9a0 Original spec was reportedly authored by Opus 4.7 in session 2792e9a0 but failed to upload due to MCP timeout This re-author derives from verified SSOT + outline trace + KB evidence and may differ in technical detail Workstream: P3D_INFORMATION_UNIT_TEXT_AS_CODE Author: Opus 4.7 (Claude) — re-author from SSOT Issuer of directive: GPT-5.5 Thinking / Incomex Hội đồng AI Mode: REQUIREMENTS / SPEC — no implementation, no DB mutation, no code, no vector table, no parent-child table, no Nuxt, no UI SSOT sources: p3d-iu-text-as-code-completed-state-and-remaining-work-2026-05-10.md + discrepancy-resolution-addendum + final-baseline-patch Legal frame: Đ44 Universal Method Law (BAN HÀNH) — P3D operates within Đ44 governance Path: knowledge/dev/laws/dieu44-trien-khai/requirements/p3d-information-unit-text-as-code-requirements-spec.md

§A. Strategic Purpose

Information Unit (IU) is the universal information substrate of Incomex — not a UI feature, not a vector-only store, not a document notebook. It is the text-as-code foundation for all laws, designs, processes, prompts, reports, tests, agent context packs, and release artifacts.

Text-as-code = applying proven IT techniques (version control, diff/patch, merge, code review, test coverage, dependency graph, build/release, semantic linting) to structured text managed as atomic units in PostgreSQL.

The system already has a strong runtime foundation (TAC pipeline, IU create/edit/save machinery, notification, event_outbox). The remaining work elevates this foundation to industry-standard text-as-code with Git-like operations, PR workflow, typed graph, test/lint, build/release, vector sync, and event emission.

§B. Completed Baseline — DO NOT REBUILD

These items are production runtime. Any pack that proposes rebuilding them violates Assembly Gate Q0.

B.1 TAC Pipeline

3 publications (Đ35 36u, Đ32 23u, Đ28 27u) = 86 units, 54KB, 0 content drift
4 tables: tac_publication, tac_logical_unit, tac_unit_version, tac_publication_member
render_order, generic CTE, section_types 13/17 used
/knowledge/laws listing + reader page on Nuxt

B.2 IU Native Machinery (Pack 22 CLOSED)

fn_iu_create() — SECDEF, canonical_writer marker, 5-invariant verify, complete-or-nothing
fn_iu_create_plan() — dry-run
fn_iu_verify_invariants() — 5 independent invariants
Gateway guard: trg_aa_iu_gateway_write_guard + trg_aa_uv_gateway_write_guard (BEFORE INSERT OR UPDATE)
fn_iu_gateway_write_guard() — SECDEF, fixed search_path, PUBLIC revoked
9 dot_config policy keys (iu_create.gateway.*), mode=enforced
Gateway README published

B.3 Edit/Save/Policy Runtime (Pack 23 P3B–P3C4 PASS)

P3B: schema edit draft/comment
P3B-FU: invariant generalize (all UV, not just pilot)
P3C1: safe edit draft functions (21/21 tests)
P3C2: fn_iu_apply_edit_draft, fn_iu_edit (canonical write path via gateway marker)
P3C3: fn_iu_save — AI front-door router (~30 lines, calls existing functions)
P3C4: policy switched auto_apply → require_review, agent context pack published

B.4 Notification Runtime (P3D1+P3D2 PASS)

iu_notification_event + iu_notification_read tables
fn_iu_unread(actor), fn_iu_mark_read(event_ids, actor), fn_iu_notification_board(actor)
3 trigger functions + 3 triggers: comment/draft/version auto-notify
Per-actor read state, self implicit-read, system comment suppressed, birth excluded

B.5 Universal Event Core + Display

event_outbox table (universal event substrate)
event_type_registry (active types)
tbl_event_outbox published in table_registry
/knowledge/registries/event_outbox live with filter PASS
Permission #1483: 14 metadata fields allowlist, 13 unsafe fields denylist
Generated table-map (commits 0947613, d2db418) — build verify PASS

B.6 Description Policy Tiering (Pack 2A CLOSED)

description_policy column in collection_registry (3 tier: required_detailed / structured_exempt / unclassified)
166 collections seeded
fn_description_birth_guard amended (4 changes)
H11a/H11b CRITICAL/WARNING split

B.7 Foundation Tables/Data

universal_edges 2199 rows (CAT-130): USES(1486), BELONGS_TO(431), CONTAINS(282)
collection_registry 166 collections with description_policy
entity_enrichment SSOT (57K+ entities at last report)
birth_registry + fn_birth_registry_auto v2 (70K+ records, synthetic fallback table::uuid)
DOT-119 v2 active (repair arc COMPLETE 2026-05-05), v1 backup exists

B.8 Enacted Laws

Đ44 Universal Method Law (frame for P3D)
Đ43 System Context Law v1.2 (context_pack tables, 7 dot_config keys, executor pattern)
Đ38 Normative Document v2.3
Đ35 DOT Governance v5.0, Đ36 Collection Protocol v4.0, Đ32 Approval System

§C. Current Runtime Foundations (snapshot numbers — verify before gating)

Object	Count (last report)	Note
tac_publication	3	Đ35, Đ32, Đ28
tac_logical_unit	86	All proposed/draft
tac_unit_version	86	All proposed/draft
tac_publication_member	86	render_order 0..N
information_unit (IU native)	~5	Pilot rows from Pack 22
unit_version (IU native)	~5	Pilot rows
universal_edges	2199	3 active types
collection_registry	166	With description_policy
dot_config IU keys	9 gateway + 1 policy	iu_create.gateway.* + iu_edit.policy.*
IU functions	≥10	fn_iu_create/plan/verify/classify/resolve/hash/create_edit_draft/comment/apply_edit_draft/edit/save
IU triggers	5	2 gateway + 3 notification

§D. Existing Design/Contract Foundations

Item	Status	Path
UMC 10 elements universal core (P38-XC §5.2)	DESIGN APPROVED	dieu38-trien-khai/
Đ38 P5 schema draft v0.2 (8 tables)	DESIGN APPROVED	dieu38-trien-khai/P5-schema-draft-v0-2.md
Đ38 Phụ lục 01 v7.1 FINAL (Problem)	ENACTED DESIGN	dieu38-appendix-01-objectives.md
Đ38 Phụ lục 02 — 6 PASS files (Solution)	ENACTED DESIGN	dieu38-trien-khai/ (~80KB)
23-P1 IU Edit/Merge Design rev2	GPT APPROVED	dieu44/design/23-p1-*
23-P3 Model D Hybrid Design	COUNCIL APPROVED	dieu44/design/23-p3-*
P10D Nuxt Laws Page Design Brief v0.2	PATCHED (7 GPT patches)	dieu38/P10D-*
P3D Notification Outbox Design Note rev3	APPROVED	dieu44/design/23-p3d-*
IU Front-Door Context Pack	PUBLISHED	dieu44/readme/iu-agent-front-door-context.md

§E. Remaining Capability Gaps

9 branches of text-as-code capability, current coverage ~25-30%:

#	Branch	Done	Remaining	Severity
1	Diff/Patch/Merge/Revert/Blame	create + edit (apply)	diff, 3-way merge, revert, blame	HIGH
2	PR/Proposal Workflow	Đ32 framework exists	unit_proposal table, review state, approval binding	HIGH
3	Test Coverage per IU	—	Test framework, executor pattern	MEDIUM
4	Dependency Impact Analysis	universal_edges (2199 rows)	Typed vocab expansion (3→15), traversal queries	HIGH
5	Build/Render/Release	TAC render + reader	P10D Nuxt, release bundle, build artifacts	MEDIUM
6	Package/Module System	Đ38 Phụ lục 02 catalog design	DDL + seed	MEDIUM
7	Typed Relationship Contract	3 edge types active	15 typed edges formal contract	HIGH
8	Semantic Lint	—	9 lint checks + 3 modes	MEDIUM
9	Vector Boundary + Event Emission	Rule design + event_outbox runtime	iu_vector_chunk table, IU event emission event_domain='information_unit'	HIGH

§F. TAC ↔ IU Reconciliation Requirement

Problem: TAC pipeline uses tac_logical_unit (86 production rows). IU native uses information_unit (5 pilot rows). These are separate tables with separate schemas. Before IU canonical contract can be finalized, the relationship must be resolved.

Options (to be decided in Pack 1):

F.1 Merge: migrate tac_logical_unit → information_unit (TAC becomes projection/view)
F.2 Bridge: keep both tables, create binding/edge between them
F.3 Evolve: extend information_unit to subsume tac_logical_unit schema

Acceptance criteria:

AC-F1: Decision documented with rationale and migration risk assessment
AC-F2: 86 TAC units accounted for (no data loss path)
AC-F3: render_order / publication membership preserved
AC-F4: Gateway guard applies to reconciled model
AC-F5: 0 content drift after reconciliation (re-verify round-trip)

§G. IU Canonical Contract Requirement

16-concept contract (10 UMC core + 6 extensions):

UMC 10 (P38-XC §5.2): (1) canonical_address, (2) entity_code, (3) identity_profile, (4) lifecycle_status, (5) content_hash, (6) version_seq, (7) body, (8) title, (9) description, (10) birth_record.

Extensions: (11) version_anchor_ref, (12) content_anchor_ref, (13) parent_or_container_ref, (14) unit_kind, (15) section_type, (16) review_state.

8-capability definition: address / version / diff / review / trace / vectorize / test / assemble.

Acceptance criteria:

AC-G1: 16 concepts mapped to DDL columns (existing + new)
AC-G2: unit_kind vocab framework decided (Đ24 label vs dot_config)
AC-G3: Implementation pattern decided (single-inheritance / per-kind / hybrid)
AC-G4: Birth gate hard threshold = 15 strict elements
AC-G5: Tier 0 baseline ≥ 44 contract elements (29 unit + 9 conformance + 6 DOT state)

§H. Version/Diff/Patch/Merge/Revert/Blame Requirements

Op	Status	Requirement	Acceptance
Create	✅ fn_iu_create	—	Done
Edit (apply)	✅ fn_iu_apply_edit_draft	—	Done
Save (router)	✅ fn_iu_save	—	Done
Diff	❌	`fn_iu_diff(uv_a, uv_b)` returning structured diff	AC-H1: diff two versions of same IU, return change set
3-way Merge	❌	`fn_iu_merge_proposal(base, mine, theirs)` with conflict detection	AC-H2: merge without silent data loss; conflicts surfaced
Revert	❌	Restore IU to previous version via new UV (not DELETE)	AC-H3: revert creates new version_seq, audit trail preserved
Blame	❌	Track proposed_by, applied_by, merged_at per UV	AC-H4: every UV has provenance metadata

§I. Proposal/PR/Review Workflow + Đ32 Binding

Model D Hybrid (23-P3 design approved): unit_proposal separate table, UV contains only merged content.

Component	Status	Requirement	Acceptance
unit_proposal table	❌	DDL with review_state, proposed_by, proposed_at, reviewer_ref	AC-I1: table created, birth fire
Review state machine	❌	draft→under_review→approved→merged OR rejected	AC-I2: transitions enforced
Đ32 binding	⚠️ Đ32 enacted	Bind APR workflow to IU proposal approval	AC-I3: proposal creates APR record
Stale detection	⚠️ fn_iu_apply_edit_draft has stale check	Extend to proposal context	AC-I4: stale proposals surfaced

§J. Parent-Child / Containment Requirements

Component	Status	Requirement	Acceptance
parent_or_container_ref column	✅ Exists (all NULL)	Populate + enforce	AC-J1: hierarchy queries work
Containment contract	❌	Rules: what can contain what (section→paragraph OK, paragraph→section NOT OK)	AC-J2: invalid containment rejected
Sort/ordering within parent	❌	sort_order column or convention	AC-J3: children ordered deterministically
Cascade behavior	❌	Lifecycle cascade rules (archive parent → children?)	AC-J4: documented + enforced

§K. Typed Edges / Traceability / Impact Analysis

Component	Status	Requirement	Acceptance
Current edge types	✅ 3 (USES, BELONGS_TO, CONTAINS)	Expand to 15 typed edges	AC-K1: vocab seeded
Formal contract per edge type	❌	Source/target type constraints, cardinality, metadata schema	AC-K2: contract per type
`fn_iu_impact(uv_id, depth)`	❌	Recursive CTE traversal	AC-K3: impact query returns affected IUs
DO-178C 4-layer traceability	⚠️ Design in Đ38 Phụ lục 02	Implement requirement→design→impl→test chain	AC-K4: 4 layers traceable per IU

§L. Test Coverage + Semantic Lint Requirements

Test Coverage

Component	Status	Requirement	Acceptance
Test framework	❌	`iu_test` table, executor pattern (like Đ43 health checks)	AC-L1: test per IU, pass/fail/skip
Coverage tracking	❌	Function or query returning % coverage	AC-L2: coverage report per publication

Semantic Lint (9 checks, 3 modes)

Check	Description
L1	Orphan unit (no publication membership)
L2	Dangling reference (edge target missing)
L3	Schema violation (missing required UMC fields)
L4	Stale draft (open draft older than threshold)
L5	Broken containment (child without valid parent)
L6	Hash mismatch (content_hash ≠ md5(body))
L7	Duplicate canonical_address
L8	Missing version_anchor (IU without any UV)
L9	Lifecycle inconsistency (published UV under draft IU)

Modes: gate (block on fail), warn (report only), dry-run (simulate).

§M. Build/Render/Release + Vector + Metadata + Event Emission

Build/Render

Existing: TAC render pipeline (0 drift), /knowledge/laws reader
Needed: P10D Nuxt implementation (tree+review+debug modes), release bundle (snapshot + manifest)

Vector Boundary

Rule: 1 vector chunk ⊂ 1 logical_unit_id + 1 unit_version_id (non-negotiable)
Needed: iu_vector_chunk table, boundary trigger, sync proof

Metadata Enrichment Governance

Existing: entity_enrichment (57K+ entities)
Needed: Per-field confidence, provenance, reversibility; governed enrichment lifecycle

IU Event Emission

Existing: event_outbox runtime + notification triggers (comment/draft/version)
Needed: IU events emitted with event_domain='information_unit' into event_outbox
7 event types: iu_created, iu_version_applied, iu_draft_created, iu_comment_added, iu_proposal_submitted, iu_proposal_merged, iu_reverted
Pre-condition for filter "Thông tin": non-zero IU events in DB

§N. Pack Roadmap + Open Questions

N.1 Pack Roadmap (15 packs, agreed order)

Pack	Purpose	Depends on	Acceptance
0	Completed-state + spec lock (THIS PACK)	—	Spec uploaded, SSOT verified, runtime checkpoint PASS
1	TAC↔IU reconciliation + IU canonical contract	Pack 0	AC-F1..F5 + AC-G1..G5
2	Diff/Patch/Merge/Revert/Blame	Pack 1	AC-H1..H4
3	PR/Proposal workflow + Đ32 binding	Pack 1, 2	AC-I1..I4
4	Parent-child / containment	Pack 1	AC-J1..J4
5	Typed edges + impact analysis	Pack 1, universal_edges	AC-K1..K4
6	Test coverage framework	Pack 1	AC-L1..L2
7	Semantic lint	Pack 1, 2, 5	9 checks + 3 modes
8	Build/Render/Release + P10D Nuxt	Pack 1, TAC pipeline	Release bundle + Nuxt reader modes
9	Vector boundary implementation	Pack 1	iu_vector_chunk + sync proof
10	Metadata enrichment governance	Pack 1, entity_enrichment	Confidence + provenance + reversibility
11	IU event emission → event_outbox	Pack 1, event_outbox	7 event types + event_domain='information_unit'
12	UI/filter "Thông tin"	Pack 11 (events exist)	Config-only, Assembly First
13	Governance housekeeping	All	9 OR rules S188 amended, DOT-119 v2 hard boundary maintained
14	Migration rộng (all laws)	Pack 1, 2, 8	All enacted laws → IU model

N.2 Open Questions (top 10, deferred to Pack 1 review)

#	Question	Impact
OQ-1	UMC implementation pattern: single inheritance, per-kind, or hybrid?	Pack 1 gate
OQ-2	unit_kind vocab framework: anchor to Đ24 label taxonomy or dot_config?	Pack 1 gate
OQ-3	TAC future: tac_* tables become views over IU, or co-exist with bridge?	Pack 1 gate
OQ-4	Pack 23 P3 edit functions → consolidate into Pack 2 or keep separate?	Pack 2 scope
OQ-5	Vector chunk manifest schema: what metadata per chunk?	Pack 9
OQ-6	Đ24/Đ29/Đ39 maturity: ready for typed edge integration?	Pack 5
OQ-7	Đ45 Universal Event Law: needed before Pack 11?	Pack 11
OQ-8	section_type enum: extend beyond 17 current types?	Pack 1
OQ-9	canonical_address format: immutable after creation? Migration path?	Pack 1
OQ-10	Hermes reviewer automation: defer or integrate with Pack 3 PR workflow?	Pack 3

§O. Hard Boundary Attestation

This spec does NOT:

❌ Mutate any database table
❌ Create or alter any PG object
❌ Write any Nuxt/UI code
❌ Execute DOT-119 v1 or v2
❌ Modify fn_birth_registry_auto
❌ Direct-write information_unit or unit_version
❌ Add "Thông tin" filter
❌ Start Pack 1 implementation

This spec DOES:

✅ Establish do-not-rebuild list (§B)
✅ Document current runtime baseline (§C)
✅ Define remaining gaps with acceptance criteria (§E–§M)
✅ Set pack roadmap with dependencies (§N.1)
✅ List open questions for Pack 1 review (§N.2)

§P. Đ44 Conformance

#	Check	Result
C1	Spec within Đ44 scope (Universal Method)	PASS — P3D is Đ44 workstream
C2	Assembly First (PG→Directus→Nuxt→Code)	PASS — spec is requirements, no code
C3	Fix Gốc (root cause, not patch)	PASS — spec addresses root gaps, not symptoms
C4	DOT 100% (every action via DOT)	PARTIAL — defer to Pack 1 implementation
C5	§0-AU (no hardcode)	PASS — no code in spec

§Q. Coverage Declaration (Re-author)

Section	Source	Confidence
§A Strategic purpose	SSOT + outline trace from 2792e9a0	HIGH — concept unchanged
§B Do-not-rebuild	SSOT completed-state matrix (all 3 files)	HIGH — directly from verified SSOT
§C Runtime foundations	SSOT + conversation evidence	HIGH — numbers are snapshot, verify before gating
§D Design foundations	SSOT + KB paths verified	HIGH
§E Gaps	SSOT remaining-work list + original outline severity	MEDIUM — severity ratings may differ from original
§F TAC↔IU reconciliation	SSOT item #3 + original outline	MEDIUM — options may differ in detail
§G Canonical contract	Original outline (16 concepts, 8 capabilities) + P38-XC reference	MEDIUM — acceptance criteria re-derived
§H-§M Requirements	Original outline structure + SSOT gap analysis	MEDIUM — acceptance criteria newly written from context
§N Roadmap	SSOT agreed order (16 items) + original 18 OQ (top 10 selected)	HIGH for roadmap, MEDIUM for OQ selection
§O-§P Attestation	Standard pattern	HIGH

Known differences from original 50KB spec:

Original had 18 open questions; this re-author selects top 10
Original had per-pack purpose/inputs/outputs/non-goals/risks/acceptance/executor detail for 11 packs; this re-author has condensed pack table with acceptance criteria
Original severity ratings in §E may have been more granular
Original §B-§D evidence paths may have been more specific (exact report filenames)