Incomex AI Portal
KB-1306 rev 16

Master Design Rev2 — 00 Master integration (rev3 MP-D11..MP-D15)

46 min read Revision 16

IU-Centered 4 Mothers + Event Foundation — Master Design Rev2

Path: knowledge/dev/design/v0.6-iu-4mothers-event-foundation-rev2/00-master-design-rev2.md Status: DRAFT Rev2 (DOCUMENT ONLY) — Revision 5 (MP-D23..MP-D30 industrial-birth / cross-law / object-factory final pre-approval hardening applied 2026-05-28; see NEW 10-… + 07-… §16. Revision 4 added MP-D16..MP-D22; see 09-… + 07-… §15. Revision 3 added MP-D11..MP-D15; see 07-… §14). User approved Requirement Rev2 MP1–MP6 (2026-05-27 user message "duyệt Requirement Rev2 MP1–MP6"); this Master Design Rev2 is the document-only translation of that requirement to design, per Rev2 brief §21 (MP6 final approval gate) and macro IU_4MOTHERS_EVENT_FOUNDATION_MASTER_DESIGN_REV2_DOCUMENT_ONLY_2000X. Date: 2026-05-27 (rev2) · 2026-05-28 (rev3 MP-D11..MP-D15) · 2026-05-28 (rev4 MP-D16..MP-D22) · 2026-05-28 (rev5 MP-D23..MP-D30) Authority: Requirement Rev2 brief knowledge/dev/requirements/v0.6-iu-4mothers-event-foundation-rev2/00-requirement-brief-rev2.md revision 2. All design here is bound to that brief. Where this doc diverges from Rev2 brief, Rev2 brief wins and this doc is the violator (report immediately). Companion files (in this directory):

  • 01-requirement-traceability-matrix.md — WS1; spine of all WSs.
  • 02-step-state-machine-and-workflow-ui-design.md — WS4; 9-state floor + transitions + UI.
  • 03-event-5layer-realtime-dlq-design.md — WS5; producers / broker / consumers / realtime / DLQ.
  • 04-iu-centered-4mothers-binding-design.md — WS2 + WS3; IU architecture + 4 Mothers binding.
  • 05-oss-candidate-strategy-rev2.md — WS7; 7 labels + Gate A/B verdicts.
  • 06-open-decisions-and-readiness.md — WS8; OD1..OD15 + extension registries + sequencing.
  • 07-master-design-rev2-report.md — macro report (status / paths / forbidden compliance).
  • 08-bidirectional-input-kaizen-governance-addendum.md — MP-D11..MP-D15 addendum (rev3): bidirectional flow + staging input + unified MOW T6→T1 + inline Kaizen + MOT/JFT matrix + governance-at-scale cockpit + AI/agent ops.
  • 09-governance-operability-observability-addendum.md — MP-D16..MP-D22 addendum (rev4): Điều 5 five-tier ↔ T6→T1 mapping + governance problem queue taxonomy/lifecycle + Kaizen anti-noise/duplicate lifecycle + direct-canonicalization guardrails + Minimum Observability Profile + raw PG-event OSS reconciliation + Governance Ops Survey.
  • 10-industrial-birth-cross-law-addendum.md — MP-D23..MP-D30 addendum (rev5): cross-law constitutional review + Điều 28 template binding for all 4 Mothers UI surfaces + Điều 36/0-G/29 collection-object birth protocol + 4 Mothers as governed object factories (Điều 37 factory agency) + Điều 37 jurisdiction matrix + NT14 execution-traceability matrix + assembly-first reuse decision tree + no-"đẻ rơi" (orphan/phantom) safety gates + agent self-review. Forbidden in this macro (binding): No PG mutation. No Directus mutation. No business Qdrant / vector write or reindex. No migration. No DOT command run. No law enactment / drafting. No implementation macro. No UI deployment. No final OSS tool selection. No direct raw SQL apply. No changing gates.

§0. How to read this design

Master Design Rev2 is 10 documents (7 workstream files + 3 rev3/rev4/rev5 addenda) that together form a coherent architecture for the IU-centered 4 Mothers + Event Foundation. Reading order for reviewers:

  1. This document (00-master-design-rev2.md) — top-level architecture, invariants, design tour, acceptance criteria.
  2. 01-requirement-traceability-matrix.md — verify every Rev2 brief requirement has a design landing site + PG artifact + open gap + sentinel.
  3. 04-iu-centered-4mothers-binding-design.md — IU as central assembly unit; 4 Mothers as khuôn đúc around IU.
  4. 02-step-state-machine-and-workflow-ui-design.md — 9-state floor + transitions + roll-up + workflow UI + governance UI.
  5. 03-event-5layer-realtime-dlq-design.md — event 5 layers + realtime gateway + DLQ + usage evidence.
  6. 05-oss-candidate-strategy-rev2.md — 7-label verdicts + gates A/B.
  7. 06-open-decisions-and-readiness.md — OD1..OD15 decisions + extension registries + Phase 0..7 sequencing.
  8. 07-master-design-rev2-report.md — final report.
  9. 08-bidirectional-input-kaizen-governance-addendum.md (rev3 MP-D11..MP-D15) + 09-governance-operability-observability-addendum.md (rev4 MP-D16..MP-D22) — addenda that widen + harden the design without redefining any law boundary.

Each companion file declares its scope and boundaries explicitly. No companion file redefines a law boundary.

§1. One-line design intent

Master Design Rev2 translates Requirement Rev2 into a PG-first, IU-centered, config-driven, registry-backed architecture where:

  • IU is the single central assembly unit; every workflow (2..500 step) lắp từ IU bricks / IU bundles around IU.
  • 4 Mothers (MOW / MOT / MOIT / MOUT) are khuôn đúc around IU — they shape flow / UI / IO, never own IU body or queue or approval.
  • Event 5-layer respects Điều 45 boundaries: producers emit, workers execute, queue ≠ event bus, Nuxt never reads core, DLQ + governance with Điều 32 approval.
  • 9-state floor + waiting facets + accessibility + roll-up are PG/config-driven; Nuxt zero logic.
  • OSS adoption gated by 7 labels + Gate A (state-vocab fit) + Gate B (config-first fit); no final tool pick.
  • No-double-ownership preserved; only NEW concern = 4 Mothers application layer (future Điều XX).

§2. Architecture overview

┌─────────────────────────────────────────────────────────────────────┐
│                          GOVERNANCE PLANE                           │
│  Điều 32 (approval)  ·  Điều 37 (governance org)  ·  Điều 0-G       │
└─────────────────────────────────────────────────────────────────────┘
                              │ (approvals, birth registry)
┌─────────────────────────────▼───────────────────────────────────────┐
│                       APPLICATION ASSEMBLY                          │
│  ────────────────────────────────────────────────────────────────   │
│      4 Mothers (khuôn đúc, around IU — future Điều XX)              │
│      MOW  →  IU Assembly Orchestrator   (workflow graph)            │
│      MOT  →  IU-backed Task Envelope    (4-region UI render)        │
│      MOIT →  IU-context-aware Input     (form contract refs)        │
│      MOUT →  IU-backed Output Views     (block + matrix render)     │
└──────────────────────────────▲──────────────────────────────────────┘
                               │ refs only
┌──────────────────────────────┴──────────────────────────────────────┐
│                       KNOWLEDGE PLANE                               │
│  ────────────────────────────────────────────────────────────────   │
│   Điều 38 + 39:  Information Unit (body singleton, versioned)       │
│                  IU bundles, axes, KG edges, lifecycle              │
│                  KG feedback (propose-only)                         │
└──────────────────────────────▲──────────────────────────────────────┘
                               │ usage evidence
┌──────────────────────────────┴──────────────────────────────────────┐
│                       EVENT / QUEUE / EXECUTOR                      │
│  ────────────────────────────────────────────────────────────────   │
│   Điều 45:  event_outbox (canonical ledger)                         │
│             event_subscription / event_pending  (event bus)         │
│             job_queue / job_dead_letter         (job queue)         │
│             queue_heartbeat                     (Điều 45 §15.5)     │
│             executor_class_registry             (Điều 45 §11.5)     │
│             idempotency_registry · retry_policy · dlq_replay        │
│             state_machine_registry              (Điều 45 §6.7)      │
└──────────────────────────────▲──────────────────────────────────────┘
                               │ refs, registered events
┌──────────────────────────────┴──────────────────────────────────────┐
│                   REALTIME GATEWAY (boundary)                       │
│   Backend gateway service (permission + relevance filter)           │
│   Nuxt SSE shell  ─▶  HTTP  ─▶  Backend gateway  ─▶  PG outbox tail │
│   NO direct PG / NOTIFY / outbox read from Nuxt                     │
└──────────────────────────────▲──────────────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────────┐
│                       UI (Nuxt render shell — Điều 28)              │
│   Standard Process View · Runtime Progress View ·                   │
│   Step/Task state UI (9 floor + 2 derived) ·                        │
│   Governance UI (problem-first) ·                                   │
│   Proposal mode (writes workflow_change_requests / proposal)        │
└─────────────────────────────────────────────────────────────────────┘

Boundary preservation (Điều 33 v2.1 3-layer + Điều 28):

Browser  ⇄  Nuxt (render shell, zero logic)  ⇄  Backend gateway  ⇄  PG / Directus
                  ↑
                  └── never direct PG / event_outbox / NOTIFY (Rev2 §6.4)

§3. Top-level invariants

The following invariants are binding across every WS in this design package. Violating any of them is a design-level bug.

  1. IU body singleton. information_unit.canonical_body_* (versioned by iu_version) is the only IU body SoT. Every body display routes through render_iu_body(iu_unit_id, iu_version_id, surface, context). No tasks.body / workflow_step_def.description_text / event_outbox.payload.body_text carries IU body. (Rev2 §2 D2.2 / D2.3; 04-… §2.2 / §2.3.)
  2. Uniform assembly primitive. 2-step and 500-step workflows lắp from the same primitive (workflow_step_def + workflow_step_relations + IU/bundle bindings). No long-workflow sibling schema. (Rev2 §2 D2.5; 04-… §2.5 / §3.4.)
  3. IU version pinning. Active workflow_run pins iu_version_id per step at entry. Migration of pinned versions requires Điều 32 approval. (Rev2 §2 D2.6 / OD15; 04-… §5.)
  4. No-double-ownership. Every concern has exactly one owner law: Điều 32 (approval), Điều 35 (DOT mutation), Điều 38/39 (IU + KG), Điều 45 (queue/event/state-machine/executor/heartbeat), Điều 28 (Nuxt render), Điều 33 (3-layer), Điều 0-G (birth). Only NEW concern = 4 Mothers application layer (future Điều XX). (Rev2 §11.)
  5. Register-before-emit. Every event type registered in event_type_registry with JSON schema + semver + compat_mode before any producer emit. (Rev2 §6.1; 03-… §3.1.)
  6. Refs-only payload. Event payloads carry signal/refs (IU id + version + run id + trace ids), not heavy body. Queue rows are even tighter. Worker fetches body from PG. (Rev2 §6.2 + §8; 03-… §2 invariant 4.)
  7. Queue ≠ event bus. Distinct tables, distinct delivery semantics; queue does not auto-run scripts. (Rev2 §6.2; 03-… §4.1.)
  8. W3C trace_id NOW. Every event / job / heartbeat carries W3C-shape trace_id (32 hex) + parent_span_id (16 hex) + trace_flags (2 hex) + correlation_id (uuid). Derived traceparent = "00-<trace_id>-<parent_span_id>-<trace_flags>". trace_id is the 32-hex segment only — never the full traceparent string (MP-D1). OTel later is zero-migration. (Rev2 §6.3 + §15 L1; 03-… §5.6.)
  9. Heartbeat caller. Every worker class emits heartbeat from day 1 via SECURITY DEFINER wrapper. False-heal protection per memory pattern. (Rev2 §6.3 + §7.4.6; 03-… §5.5.)
  10. Idempotency mandatory. Every executor invocation carries (namespace, key); re-invocation returns prior outcome. (Rev2 §6.3; 03-… §5.4.)
  11. Nuxt boundary. Nuxt never connects to core queue / event_outbox / NOTIFY. SSE shell calls backend gateway abstraction. Backend gateway filters permission + relevance. (Rev2 §6.4; 03-… §7.)
  12. 9-state floor + traffic-light + a11y. Step / task state machine has 9-state floor + 2 derived (paused, cancelled) per OD12. Color + icon + text triplet; WCAG 2.1 AA; tokens config-driven. (Rev2 §7.3 + MP3/MP4; 02-… §3.)
  13. Roll-up red>yellow>green. Workflow not green if mandatory active step red. Optional / skipped do not pull. Config-driven via rollup_policy_def. (Rev2 §7.2.6 MP5; 02-… §5.)
  14. KG propose-only. KG feedback writes proposals only; never auto-mutates registry. (Rev2 §9; 04-… §3.5.)
  15. OSS labels-only. No final tool pick. Adoption requires Gate A + B test, 7-label verdict, SoT-pointback row in PG, reversibility, no double ownership. (Rev2 §15; 05-….)
  16. No raw event noise in UI. Governance UI shows summary / red-flag / progress; drill-down via trace_id. No raw outbox tail surface. (Rev2 §7.4 R7.4.8; 02-… §7.7.)
  17. Reversibility. Every design extension has rollback path (Điều 30). (06-… §S20 reversibility statement.)
  18. CRS survey gate. Phase-1 design depends on no candidate_requires_survey row until survey returns verified_live. (Rev2 §17 PARTIAL; 06-… §S16.)
  19. Gate respect. dot_config runtime gates respected. Design does not assume iu_vector_sync_enabled=true. (Rev2 §12 row 21; 00-master-design-rev2.md §10.)
  20. No cross-IU vector pollution. 1 IU → ≥1 point; no body fanned across IUs in any adapter. (Rev2 §12 row 21 + §13 vector law; 03-… §3.4.)
  21. Bidirectional flow with single SoT (MP-D11). Read path = PG → Directus → Nuxt; write path = Nuxt → backend input gateway → Staging (input_submission/proposal) → Processing (direct | workflow) → PG canonical. PG is the only SoT for canonical artifacts. Directus and any staging collection are mediation only, NOT SoT. Nuxt never writes PG and never holds business logic. (08-… §3.)
  22. Staging is mediation, not SoT (MP-D11). Staging row carries raw text / audio_ref / attachments_ref + captured_context_jsonb; downstream events carry refs only (MP-D8 deny-list extends to staging-originated events). Canonicalization either writes a canonical row (direct branch) or routes to workflow_change_requests / generic proposal (workflow branch, Điều 32 gated). (08-… §3.)
  23. Unified MOW hierarchy T6→T1 (MP-D12). Single <MowHierarchyCanvas> component, six tier modes (T6 Lĩnh vực / T5 Công ty / T4 Phòng ban / T3 Chuyên môn / T2 Workflow / T1 Task; T0 Field is atomic schema, NOT a tier). Same card primitive every tier. MOW canvas is NOT the super-admin 20 000-task cockpit. (08-… §4.)
  24. Inline Kaizen stays simple (MP-D13). User flow: Đề xuất cải tiến → Thêm/Sửa/Xoá → click vị trí → comment/audio → gửi. Max 5 user-decisions per submission; no BPMN / schema / registry vocabulary surfaced to the user. Backend auto-captures full context. Complexity is backend. (08-… §5.)
  25. MOT/JFT envelope from matrix (MP-D14). Every task instance materialized from a task_template × runtime context row binding (IU/bundle, MOIT contract, MOUT contract, trigger subscription, assignee policy, deadline policy, executor class, state machine, dashboard target, permission scope, escalation policy). MOT envelope has six regions (header / input / reference / instruction / action / state-deadline-escalation). Right task / right person / right time / pushed only when actionable / disappears when done. (08-… §6.)
  26. Four separated UI surfaces (MP-D15). (1) Personal JFT Dashboard, (2) MOW Hierarchy Canvas T6→T1, (3) Governance Cockpit (problem-first, severity, SLO/SLA, 20 000+ scale), (4) AI/Agent Ops Console. MOW Canvas ≠ Governance Cockpit. Governance Cockpit is the super-admin / AI-ops surface; AI/worker summaries obey MP-D9 evidence rule; no raw event tail. (08-… §7.)
  27. Two orthogonal tier systems, never conflated (MP-D16). The Điều 5 five-tier architecture axis (Tầng 1 Hạ tầng → Tầng 5 Giám sát) and the T6→T1 business operating axis (Lĩnh vực → Task) are different axes that must not replace each other. T6→T1 content lives in Tầng 4/5 but depends on Tầng 1/2/3 readiness; no Tầng-4/5 feature may be built on a missing Tầng-1/2/3 substrate (Điều 5 §2). (09-… §3 + §3a below.)
  28. Governance problems are a typed, lifecycled operations queue (MP-D17). Every operational problem is a typed governance_problem row with class + severity + ownership + explicit lifecycle + dedupe/grouping/suppression + SLA/SLO clock. Acknowledgement ≠ resolution; mitigation ≠ verification; suppression/waiver needs policy (and Điều 32 for high/critical); auto-resolve needs a source *.resolved/*.recovered/*.healed event (MP-D9). Problems spawn changes (workflow_change_requests/proposal); a problem is never itself a change. (09-… §4.)
  29. Kaizen anti-noise lives in the backend, never in the user flow (MP-D18). The five-click Kaizen UX (08-… §5.1) is unchanged. Duplicate detection, clustering, rate-limit, spam/abuse flags, low-quality rejection, merge-with-credit, and the review lifecycle are backend/governance only. Rejections carry a friendly reason; merged duplicates still credit the contributor. (09-… §5.)
  30. Direct canonicalization is allow-listed, audited, lineaged, reversible (MP-D19). The direct branch admits a write only when all allow conditions hold (permission, allowed kind, schema-valid, size-ok, no structural/registry/IU-body/law change, no approval-required effect, idempotency key, audit, retention, PII/security classification). Any deny condition forces the workflow branch or refusal. Every direct write records lineage (staging_id ↔ canonical_target_ref) and is reversible. (09-… §6.)
  31. Minimum Observability Profile holds from day 1 (MP-D20). Every workflow/event/input/Kaizen/agent surface emits the minimum machine-metric set; humans see summary/severity/owner/affected T6→T1 path/impact/age-SLA/next-action/drill-down/evidence-backed AI summary; raw event tail / queue payload / spans / prompts / bytes are machine-only by default. Every summary carries generated_at; stale summaries are labelled; no auto-resolve without a source event. (09-… §7.)
  32. OSS tools remain adapters with SoT-pointback, never core owners (MP-D21). Every raw-PG-event-doc-suggested tool (Hasura, pg-boss/Graphile, Benthos, NATS, Redis, Temporal, Camunda, Airflow, Watermill, OTel/Jaeger/Tempo, Prometheus/Grafana/Loki/VictoriaMetrics) is reconciled to a Gate A+B verdict + adapter label with an explicit "may NOT" boundary; none owns the event plane / workflow definition / approval / state authority; each future adoption needs an external_tool_registry SoT-pointback row. No final pick. (09-… §8 + 05-… §7.)
  33. Governance Ops Survey precedes cockpit/agent-ops implementation (MP-D22). A read-only IU_4MOTHERS_GOVERNANCE_OPS_SURVEY_DOCUMENT_ONLY_*X macro surveys existing task queues / AI-task+agent-run tables / governance views/logs / heartbeat / dashboards / observability tooling before any cockpit or agent-ops build. Survey order: (1) Candidate Registry Survey (G7), (2) Tier Registry Survey, (3) Governance Ops Survey, then Phase 0/1 ordering. (09-… §9.)
  34. Every 4 Mothers UI surface is a registered Điều 28 template + product (MP-D23). Each MOW/MOT/MOIT/MOUT/Governance/AI-Ops/Kaizen/Staging/DLQ surface is one design_templates row + product-from-template record; routes resolve by registry/config (no hardcoded maps); template lifecycle draft→testing→active (8-key checklist + 5/5 tests + trg_template_lifecycle); coverage scanner target 0 outside registry. No template = no UI. Unavoidable new renderer code registers in the Custom Code Registry. (10-… §3.)
  35. Every Mother-generated object is born before it is valid (MP-D24). Every object/table/view/registry produced by a Mother has a birth_registry record (PEN/STAMP/GATE→certified) + collection_registry entry + species mapping (species_collection_map/entity_species) + governance_role + composition_level before active. No birth record = orphan = invalid. New collection via DOT-COL-REGISTER + dot-species-map + DOT+APR; never raw psql. Integrity gates HC-REG + HC-SCHEMA. (10-… §4.)
  36. The 4 Mothers are governed object factories, not free modules (MP-D25). Each is an Điều 37 governance_registry row type='factory' (output_target ∈ user/system/assembly) with governance_relations produces/owner edges; each declares can_create / can_reference / must_not_own; every child object keeps its own owner law. A Mother owns the binding/shape, never IU body / substrate / approval / birth / template lifecycle. (10-… §5.)
  37. Every Mother + output is jurisdiction-bound (MP-D26). Same UI pattern, different backend-filtered slices: staff/dept-lead/super-admin see only authorized data (Layer B = Directus role + field allowlist + Điều 32; Điều 37 does not define human roles — a human-org-role law is a flagged future need). Layer A = Điều 37 factory agency + law_jurisdiction (Phạm vi) + relations. Backend filters before Nuxt; AI-Ops never leaks prompts/payloads/outputs outside authority. (10-… §6.)
  38. NT14 execution-traceability holds for every factory object class (MP-D27). Each major surface/object is traceable requirement → PG table/registry → birth/collection/species → Directus/API exposure → Nuxt template/product → DOT/API mutation path → event/queue → approval gate → health/verify gate → rollback/retire, with no hand-waved cell. (10-… §7.)
  39. Assembly-first reuse decision tree precedes any new artifact (MP-D28). Default = reuse/extend (PG → Directus → OSS → code; Q0–Q7). Rev5 introduces no new tables — only binding rows in existing law registries. A new runtime artifact needs birth/collection/template/DOT+APR or is refused. (10-… §8.)
  40. No "đẻ rơi" (orphan/phantom/nhầm chuồng) invariant (MP-D29). No Mother creates anonymous/UNKNOWN objects; no object reaches active while any reject condition holds (missing owner law / species / collection / template / event type / permission scope / health check / rollback / traceability). Each reject maps to a live detector (DOT-ORPHAN-SCANNER/DOT-COL-ORPHAN/HC-REG/HC-SCHEMA/DOT-MISCLASS-SCANNER/DOT-template-coverage/birth_registry.certified). (10-… §9.)
  41. This design carries a machine-checkable self-review (MP-D30). The Rev5 cross-law patch records a PASS/PARTIAL/BLOCKED self-review with exact gaps; overall PARTIAL (one non-blocking gap: human-org-role/permission law, flagged for a future macro). (10-… §10.)

§3a. Điều 5 five-tier architecture vs T6→T1 operating hierarchy (MP-D16 clarification)

The design uses two distinct tier systems. They are different axes and never substitute for each other:

Axis Organizes Direction Owner
Điều 5 five-tier architecture how the system is built Tầng 1 (bottom) → Tầng 5 (top) Điều 5 (architecture law)
T6→T1 operating hierarchy how the business operates T6 (domain) → T1 (task) future Điều XX referent; MOW canvas surface (08-… §4)

Điều 5 tiers (canonical, knowledge/dev/laws/law-05-five-tiers.md): Tầng 1 Hạ tầng (VPS/Docker/PG/Directus/Nuxt/Agent Data/Qdrant) · Tầng 2 Cơ sở (registries/metadata/DOT/fields/taxonomy — incl. event_type_registry, state_machine_registry, tier_registry, governance_problem paper registry) · Tầng 3 Modules nền tảng (Table/Comment/Workflow + the 4 Mothers modules MOW/MOT/MOIT/MOUT + gateways/workers) · Tầng 4 Chuyên môn (real business workflows + T6→T1 operating content; T2/T1 of the operating hierarchy live here) · Tầng 5 Giám sát + cải tiến (Governance Cockpit, Kaizen loops, AI/Agent Ops, observability, governance_problem queue).

T6→T1 content lives mostly in Tầng 4/5 but depends on Tầng 1/2/3 readiness (Điều 5 §2: never build an upper tier on a weak lower tier). 09-… §3.3 gives the per-surface readiness matrix (required substrate → status → blocker). Current substrate status: Tầng 1/2 verified_live; Tầng 3 partial (KB_reported — state machine not yet deployed); Tầng 4 not started; Tầng 5 partial.

§4. IU-centered design tour

Why IU-centered? Rev1 placed IU as a registry reference, with workflow / task / form / output as separate systems pointing to IU. Rev2 inverts: IU is the assembly unit; everything else lắp around IU. This eliminates duplicate text invariants (D2.3) and gives one body singleton, while letting 4 Mothers govern flow / UI / IO without owning content.

Brick fields (Rev2 §3 + 04-… §3.1): 11 fields per IU exposed via iu_process_binding (paper): iu_unit_id, iu_version_id, iu_role_in_process, assembly_slot, precondition_config, postcondition_config, io_contract_refs, executor_class_ref, event_contract_ref, kg_edge_refs, governance_state.

Bundle (Rev2 §4 + 04-… §3.7): When a step needs multiple IUs, don't merge — bundle. N members + ordered slots + typed roles, versioned + governed, lắp via iu_piece_collection* reuse [VL row 26].

Version policy (04-… §5): Active workflow_run pins; new run picks per iu_pin_policy; migration requires Điều 32 approval. Default pin.

Render layer (04-… §2.3): render_iu_body(iu_unit_id, iu_version_id, surface, context) is the only IU body display path. Surfaces: task instruction / workflow doc step box / notification / MOUT inline / governance audit excerpt. Every render emits iu.rendered event.

§5. 4 Mothers binding tour

MOW — IU Assembly Orchestrator (04-… §4.1): Reuses workflows + workflow_steps + workflow_step_relations + workflow_categories + workflow_change_requests [VL rows 16, 17, 18]. Extends with workflow_step_def.binding_kind ∈ {iu, bundle, assembly_view, task_template} + iu_pin_policy + state_machine_id. Boundary: not queue owner, not IU owner, not approval owner.

MOT — IU-backed Task Envelope (04-… §4.2): 4 UI regions render from refs (header / input / reference / instruction). Reuses tasks + task_checkpoints + task_comments [VL row 19]. Extends with task_run runtime + task_def template. MOT is not an executor — it calls executor_class_registry row. MOT does not own approval.

MOIT — IU-context-aware Input (04-… §4.3): field_registry + input_form_registry are SoT (CRS rows 28-29, survey-gated). Each field MAY link IU. Form binds into task/step context. Direct vs staging by config. Nuxt <MOITForm formId contextRef /> zero logic.

MOUT — IU-backed Output Views (04-… §4.4): Output / reference / report blocks are IU-backed views of PG/Directus state. Report declares iu_id source + DOT function link. output_table_registry + dot_function_registry (CRS rows 30-31, survey-gated + OD13 naming). Inline (MOT region 2) + matrix (independent route). Realtime through gateway; permission filter backend.

Directus boundary (04-… §4.5): API/admin/staging only. Directus realtime NOT app event plane (Rev2 §15 L2/L6 + boundary).

§6. Event 5-Layer tour (Điều 45 substrate)

Five layers (Rev2 §6 + 03-…):

  1. Producers (03-… §3) — register-before-emit, capture-by-config, no execution. Producer classes: PG DML / IU axis / DOT lifecycle / cut pipeline / workflow runtime / proposal lifecycle / human decision / agent output / external API. IU event family (03-… §3.3) covers born/edited/split/merged/deprecated/linked/rendered/validated/used.
  2. Broker / Event Bus + Job Queue (03-… §4) — distinct substrates. Event bus = event_outbox + event_subscription + event_pending. Job queue = job_queue + job_dead_letter + queue_heartbeat. Queue carries refs only.
  3. Consumers / Workers / Executors (03-… §5) — executor_class_registry enumerates DOT / SQL / AI / Human / External / Notification / Render. ACK/NACK + retry policy + idempotency + heartbeat + W3C trace_id. MOT not executor.
  4. Realtime Gateway (03-… §7) — backend gateway between PG and Nuxt SSE shell. Permission + relevance filter. realtime_gateway_topic_registry declares topics. Centrifugo slot preserved (OD4).
  5. DLQ / Recovery / Governance (03-… §6) — job_dead_letter + dlq_replay_request (Điều 32-gated) + idempotency_registry + schema compat mode + vw_audit_event_timeline(trace_id). Governance UI surfaces problems only.

§7. State machine + workflow UI tour

9-state floor (02-… §3): not_started, ready, in_progress, waiting, blocked, overdue, failed, cannot_complete, completed. Each declared with state_code + semantic_class + traffic-light token + icon + label keys. Adopted derived states: paused + cancelled (02-… §4.5).

Waiting facets (02-… §3.3): waiting_dependency / waiting_human / waiting_external / waiting_time_gate as UI facet (not new state). Primary picked by ordinal; secondary as chips.

Accessibility (02-… §3.5): color + icon + text triplet; tooltip; WCAG 2.1 AA; color-blind safe shape tokens; high-contrast mode; aria-label; declare-by-config.

Transition matrix (02-… §4): Full T1..T12 transitions + rollback edges. Reopen requires Điều 32 approval. Idempotency on transitions.

Roll-up (02-… §5): Red>Yellow>Green; not green if mandatory active step red; skipped/optional don't pull; config via rollup_policy_def.

Workflow UI (02-… §6): Standard Process View + Runtime Progress View + long-workflow patterns (zoom/pan/collapse/critical path/blocked chain/search/mini-map). Same component scales 2..500 by virtualization.

Governance UI (02-… §7): Problem-first default. Categories: DLQ / silent workers / overdue / schema violations / event lag / integrity warnings / failed cuts / orphan workflows. DLQ replay needs Điều 32. Heartbeat false-heal protected. Event lag p50/p95/p99. No raw event noise.

Proposal mode (02-… §8): Workflow proposals → workflow_change_requests [VL]. Non-workflow proposals (IU split/merge, KG edge, MOT/MOIT/MOUT template) → new generic proposal table (OD2 refined).

§8. W3C trace_id adoption (NOW)

Per 05-… §3.12 verdict L1 confirmed_invariant: adopt W3C trace_id shape from day 1. Every event_outbox row, job_queue row, queue_heartbeat row, step_run / task_run row, governance audit row carries:

  • trace_id — 32 hex characters (W3C traceparent trace-id field; only the 32-hex segment).
  • parent_span_id — 16 hex characters (W3C traceparent parent-id field).
  • trace_flags — 2 hex characters (W3C traceparent trace-flags field, e.g. 01 = sampled).
  • correlation_id — uuid (business-level correlation across trace_ids).
  • Derived traceparent = "00-<trace_id>-<parent_span_id>-<trace_flags>" (concatenation; never stored as trace_id).

MP-D1 binding: Never assign the full traceparent string (00-…-…-…) to the trace_id column. The four fields are stored separately; the traceparent header is derived on the wire/log line, not in storage.

Later OTel collector + Jaeger ingestion is zero-migration. Phase 3 work item per 06-… §S20.4.

§9. OSS strategy posture (no final pick)

Per 05-oss-candidate-strategy-rev2.md §4 summary table:

  • Adopt NOW: W3C trace_id (L1).
  • Defer with adapter slot: NATS (transport, multi-host trigger), Redis Streams (multi-host trigger), Centrifugo (>1k concurrent trigger), Benthos (external mirror trigger), OTel collector (after trace_id ubiquity), Jaeger (after OTel).
  • Reject as core owner: pg-boss / Graphile Worker (state-vocab fail + config-first fail as substrate), Temporal (workflow-as-code config-first fail), Camunda (approval = Điều 32), Airflow (MOW config-first fail), Hasura subs (3-layer boundary fail), Directus realtime (app plane boundary fail).
  • Reference only: Watermill, BPMN patterns from Camunda, batch patterns from Airflow.

No version pins, no CI steps, no dockerfile lines. Every adoption requires SoT-pointback to PG.

§10. PG Maximization map (Rev2 §14 reaffirmed)

All canonical artifacts live in PG (SoT). External tools project; SoT-pointback enforced.

Artifact Live? Design site
event_outbox ✓ 03-… §3
event_type_registry + JSON schema + compat_mode ✓ + ext 03-… §3.1 + §6.3
W3C trace ids adopt NOW 03-… §5.6
idempotency_registry paper 03-… §5.4
retry_policy_registry paper 03-… §5.3
job_dead_letter ✓ 03-… §6
dlq_replay_request paper 03-… §6.2
workflow_change_requests + new proposal ✓ + paper 02-… §8 + 06-… §S2
workflows / workflow_steps / workflow_step_relations + ext ✓ + ext 04-… §4.1
tasks / task_checkpoints / task_comments + task_run ext ✓ + ext 04-… §4.2
field_registry / input_form_registry CRS 04-… §4.3 (gated 06-… §S16)
output_table_registry / dot_function_registry CRS 04-… §4.4 (gated 06-… §S16)
executor_class_registry paper 03-… §5.1
dot_iu_command_catalog / dot_iu_command_run ✓ 03-… §5.7
dot_config runtime gates ✓ this doc §10 (gate respect)
iu_lifecycle_log ✓ 04-… §6
queue_heartbeat ✓ 03-… §5.5
state_machine_registry paper 02-… §2
iu_usage_evidence paper 04-… §7 + 03-… §9
iu_piece_collection / iu_piece_membership / iu_collection_template_* ✓ 04-… §3.7

Gate respect: dot_config gates per memory snapshot 2026-05-27 — job_substrate=false, composer=true (per mig 057 same-day), iu_vector_sync_enabled=false, heartbeat=true, dlq_replay=false. Design respects these — does not assume any false gate is true.

§11. Acceptance criteria for Master Design Rev2

Master Design Rev2 PASSes if every item below holds. Where an item references a companion file, the companion file's own acceptance section must also pass.

A. Coverage

A1. Every Rev2 brief section (§0..§21, MP1–MP6) has a design landing site in this package — verified by 01-requirement-traceability-matrix.md §§1-18. A2. Every PG Maximization Map artifact (Rev2 §14) has a design site — verified 01-… §13. A3. Every Old Infrastructure Coverage row (Rev2 §12 31 rows) has a design treatment — verified 01-… §11. A4. Every Open Decision (OD1..OD15) has a kept/refined/deferred call — verified 06-… §§S1-S15.

B. Doctrine preservation

A5. IU-centered architecture preserved — 04-… §§2-3. A6. 2..500 uniform primitive — 04-… §2.5 / §3.4. A7. No duplicate text invariant — 04-… §2.2 / §2.3. A8. IU version pinning default — 04-… §5. A9. 4 Mothers boundary preserved (do not own IU body / queue / approval) — 04-… §§4.1-4.5 + §4.6.

C. Substrate compliance

A10. Event 5-layer fully reconciled with Bắt sự kiện của PG(3).docx (Rev2 §6.6 9 lessons) — 03-… §10. A11. Queue ≠ event bus; workers execute; Nuxt never connects core — 03-… §§4 + 7. A12. W3C trace_id adopted NOW — 03-… §5.6 + this doc §8. A13. Heartbeat caller for every worker class — 03-… §5.5. A14. Idempotency mandatory — 03-… §5.4. A15. DLQ replay Điều 32-gated — 03-… §6.2.

D. UI compliance

A16. 9-state floor + waiting facets (MP3) + a11y tokens (MP4) — 02-… §3. A17. Transition matrix complete + rollback edges Điều 32-gated — 02-… §4. A18. Roll-up MP5 binding rules — 02-… §5. A19. Standard + Runtime + long-workflow UI patterns — 02-… §6. A20. Governance UI problem-first + drill-down + DLQ replay + heartbeat + event lag + no raw noise + same layout backend filter — 02-… §7. A21. Proposal mode workflow_change_requests reuse + new generic proposal for non-workflow — 02-… §8 + 06-… §S2.

E. OSS posture

A22. 14 tool verdicts with Gate A + Gate B + 7-label assignment + profile triggers — 05-… §§3-4. A23. No final tool selection; no version pin; no CI step — 05-… §4 + §1.3. A24. SoT-pointback sentinel rules captured — 05-… §5.

F. Open decisions + readiness

A25. OD1..OD15 each resolved (kept/refined/deferred) — 06-… §§S1-S15. A26. Candidate registry survey gate (G7) + raw-source audit decision (Rev2 §17 PARTIAL) explicit — 06-… §§S16-S17. A27. Extension registries summary lists all new tables/functions as paper-only — 06-… §S18. A28. Gap closure plan G1..G7 + usage evidence — 06-… §S19. A29. Phase 0..7 sequencing — 06-… §S20.

G. Forbidden compliance

A30. No PG mutation in this macro. A31. No Directus mutation. A32. No business Qdrant / vector write / reindex (KB-doc upload to Incomex_KB is allowed governance channel per memory + prior Rev2 brief upload precedent). A33. No migration. A34. No DOT command run. A35. No law enactment / drafting. A36. No implementation triggered. A37. No UI deployment. A38. No final OSS tool pin. A39. No direct raw SQL apply. A40. No dot_config gate change.

§12. Forbidden compliance statement (this macro)

Per Rev2 §20 + macro authority pack:

  • No PG mutation. This design does not INSERT / UPDATE / DELETE any production PG row. The only reads were of requirements/v0.6-iu-4mothers-event-foundation-rev2/00-requirement-brief-rev2.md (local) + 01-patch-report.md (local) + a KB get of the GPT final review + rev1 master design preview. No mcp__claude_ai_Incomex_VPS__query_pg, no SSH writes were issued.
  • No Directus mutation. Zero Directus writes.
  • No business Qdrant / vector write or reindex. No iu_vector_* mutation; no iu_qdrant_collection_registry mutation; iu_vector_sync_enabled=false gate respected. KB-doc upload to Incomex_KB (for reviewer accessibility) is the same channel used by Rev2 brief (per patch report §7); it does not target business iu_vector_* substrate.
  • No migration. Zero new migration files.
  • No DOT command run. Zero dot_iu_command_run insert via this macro.
  • No law enactment / drafting. Điều XX (future framework law) is referenced as future referent only. Điều 34 only as decision path. No clause text drafted.
  • No implementation macro. Phase 0..7 sequencing in 06-… §S20 is paper-only.
  • No UI deployment. No Nuxt / Directus deploy.
  • No final OSS tool pin. 05-… strictly labels-only; zero version numbers; zero CI steps.
  • No direct raw SQL apply. Zero SQL apply.
  • No dot_config gate change. Memory snapshot of gates 2026-05-27 respected.

§13. Cross-document sentinels (single-pass verification)

Reviewer can verify these in one pass:

  1. No-double-ownership grep. Each law-owned concern (queue/event-core/state-machine/executor/heartbeat = Điều 45; IU axes/compose/split-merge = Điều 38/39; approval = Điều 32; DOT lifecycle = Điều 35; Nuxt render = Điều 28; 3-layer = Điều 33; birth = Điều 0-G; governance org = Điều 37; integrity = Điều 31; reversibility = Điều 30; vector law) referenced exactly under its own law's surface; no design WS redefines.
  2. IU body singleton. information_unit.canonical_body_* is the only IU body source. Render layer is the only consumer. Sentinel grep across design package: zero design rows allow IU body to live outside information_unit.
  3. Register-before-emit. Producer emit refused if event_type not in event_type_registry. 03-… §3.1.
  4. Heartbeat caller. Every worker class has heartbeat caller mapped to queue_heartbeat. 03-… §5.5.
  5. Backend filter. Every UI route fetches via backend gateway. 04-… §§4.3-4.4 + 03-… §7.
  6. Gate respect. dot_config runtime gates respected (this doc §10).
  7. Reversibility. Every design extension declares rollback path. 06-… §S20 reversibility statement.
  8. Survey gate (G7). Phase-1 depends on no CRS row until survey returns VL. 06-… §S16. MP-D7 strict form: no executable artifact references field_registry / input_form_registry / output_table_registry / dot_function_registry by name until VL or shape-adapter.
  9. OSS adoption sentinels. Every adopted tool has SoT-pointback row. 05-… §5.
  10. No raw event stream surface. Governance UI never surfaces raw outbox tail. 02-… §7.7.
  11. Tier-axis separation (MP-D16). No design row conflates the Điều 5 five-tier architecture axis with the T6→T1 operating axis; no Tầng-4/5 surface is scheduled on a missing Tầng-1/2/3 substrate (09-… §3.3 readiness matrix).
  12. Problem ≠ change (MP-D17). Every governance_problem row carries refs/impact only — never a mutation payload; remediation always references a separate workflow_change_requests/proposal row + approval_id. No closed without verified; no verified without a source *.resolved/*.recovered/*.healed event. 09-… §4.
  13. Observability raw stays machine-only (MP-D20). Humans see summaries + drill-down (vw_audit_event_timeline(trace_id)); raw event tail / queue payload / spans / prompts / bytes are machine-only; every summary carries generated_at; no auto-resolve without a source event. 09-… §7.
  14. Every 4 Mothers surface resolves to a template + product (MP-D23). Sentinel grep across Nuxt routes/components: zero 4 Mothers surfaces outside design_templates + product registry; zero hardcoded route maps; DOT-template-coverage=0 outside-registry for the 4 Mothers namespace; any new renderer file present in Custom Code Registry. 10-… §3.1.
  15. No factory object reaches active without birth + collection/species + owner law (MP-D24/D25/D29). Sentinel: every factory-produced object class has a birth_registry declaration + collection_registry entry + species mapping + governance_role; HC-REG/HC-SCHEMA clean; zero raw-psql create path; "đẻ rơi" (orphan/phantom/nhầm chuồng) count = 0 for the 4 Mothers namespace; each Mother is a governance_registry type='factory' row with produces edges. 10-… §4 + §5 + §9.
  16. NT14 traceability + jurisdiction completeness (MP-D26/D27). Sentinel: every object in the 10-… §7 matrix fills its PG/birth/approval/health/rollback cells (no hand-waving); every object type has a governance_owner agency + escalation_owner; every Mother surface fetches via backend gateway with a permission predicate (no Nuxt visibility logic; field allowlist enforced for cockpit/AI-ops). 10-… §6 + §7.

§14. Next macro after Master Design Rev2 approval

Per 06-… §S20.1 sequencing (rev4 adds two surveys per MP-D22):

  1. Survey macro 1 — IU_4MOTHERS_CANDIDATE_REGISTRY_SURVEY_DOCUMENT_ONLY_*X to verify field_registry / input_form_registry / output_table_registry / dot_function_registry live status + shape (G7).
  2. Survey macro 2 — IU_4MOTHERS_TIER_REGISTRY_SURVEY_DOCUMENT_ONLY_*X to confirm T6/T5/T4/T3 sources (domain/company/department/specialty — existing vs paper) before MOW canvas Phase 2 (MP-D12 + 09-… §3.3).
  3. Survey macro 3 — IU_4MOTHERS_GOVERNANCE_OPS_SURVEY_DOCUMENT_ONLY_*X to survey existing task queues / AI-task+agent-run tables / governance views/logs / heartbeat / dashboards / VPS observability tooling before cockpit + agent-ops implementation (MP-D22 + 09-… §9). 3b. Cross-law binding readiness (MP-D23..D26, rev5) — folded into the three surveys above + a design_templates / birth_registry / collection_registry / governance_registry (Điều 37 factory agency) shape check; confirms each Mother surface can be born as a template/product and each output can be born under Điều 0-G/36, before any factory implementation (10-… §3–§6, §10.2 gaps). Flags the human-org-role/permission law as a separate future macro (10-… §10.2.1). 3c. IU substrate readiness gate (Rev4 reviews Gate A) — per knowledge/dev/reports/architecture/iu-4mothers-master-design-rev4-gpt-review-iu-centered-roadmap-2026-05-28.md: do not jump into MOW/MOT/MOIT/MOUT implementation; first run IU_CORE_PROCESS_BRICK_READINESS_AND_GAP_SURVEY_DOCUMENT_ONLY_3000X + finish IU tests b–f. The 4 Mothers factory build follows IU production-readiness.
  4. Phase 0 macro — close G1 (review_decision_id for split/merge) + G2 (fn_iu_post_cut_axis_materialize autowire into fn_cut_complete).
  5. Council Round — Điều 34 decision (OD1) by Council.
  6. Phase 1 macro — substrate extensions (state_machine_registry / executor_class_registry / retry_policy_registry / idempotency_registry / dlq_replay_request / schema_change_policy + event_type_registry.compat_mode / generic proposal table + review_decision / ui_design_system_registry tokens / realtime_gateway_topic_registry + backend gateway service skeleton + governance_problem problem-queue registries per 09-… §4.7).

Each of the above is a separate macro with its own forbidden / authority pack. None of them runs in this macro.

§15. Final word

Rev2 brief established IU as the central assembly unit; Master Design Rev2 wires every architectural surface around that center while preserving every law boundary. Where Rev2 brief deferred to Master Design (state machine transition matrix, derived states above 9, IU version policy concrete shape, generic vs per-domain proposal shape, executor class ownership cross-ref, schema compat mode), Master Design Rev2 provides a default that respects no-double-ownership and stays within Hiến pháp NT13 PG-first + Điều 7 Assembly First + Điều 28 Nuxt render shell.

Master Design Rev2 is document only. Implementation requires a separate macro per Phase. Open Decisions OD1 (Điều 34) waits on Council. Survey gate (G7) must close before Phase 1.

End Master Design Rev2.