Incomex AI Portal
KB-72AA

IU / 4-Mothers / Event Foundation — Implementation Roadmap (DRAFT, 2026-05-27)

13 min read Revision 1
implementationroadmapiumowmotmoitmoutevent-foundationphasesdraft2026-05-27

IU / 4-Mothers / Event Foundation — Implementation Roadmap

Path: knowledge/dev/implementation/iu-4mothers-event-foundation-roadmap.md Status: DRAFT — phase plan companion to requirements + master design + law extraction plan. Date: 2026-05-27 Balance discipline: Phase 0 closes current IU gaps FIRST; later phases expand to platform. No phase skipped to grab platform vision without closing foundation.

Overview

7 phases (Phase 0 → Phase 6). Each phase has: scope, entry gate, deliverables, exit gate, dependencies. Macros named in the IU_*_NNNNX convention proven in prior work.

Phase 0 ── close current IU gaps
   │
   ▼
Phase 1 ── event foundation upgrade
   │
   ▼
Phase 2 ── MOT minimum
   │
   ▼
Phase 3 ── MOW core
   │
   ▼
Phase 4 ── MOIT / MOUT factory
   │
   ▼
Phase 5 ── governance UI
   │
   ▼
Phase 6 ── scale hardening

Drafting of the new law (§12 of law extraction plan) happens between Phase 1 and Phase 3, on a parallel track.

Phase 0 — Close current IU gaps

Goal. Finish the IU foundation outstanding from the latest IU_FOUNDATION_6000X_AXIS_COMPOSE_TRIGGER_SQL_DOT macro before expanding to platform.

Scope.

  • Wire fn_iu_post_cut_axis_materialize automatically from fn_cut_complete (or post-CUT event subscriber).
  • Survey + introduce review_decision table (if absent) to unblock fn_iu_piece_split / fn_iu_piece_merge live proof.
  • Close split/merge PARTIAL_WITH_EXACT_GAP by running real split + merge end-to-end with review_decision_id bound.
  • Healthcheck coverage: post-CUT axis materialize should appear in healthcheck surface (alongside directus_collection rows already present).
  • Verify Điều 39 IU is intact and Lifecycle ready.

Entry gate.

  • Channel proof PASS (workflow_admin write channel via SSH docker exec -i postgres psql).
  • pg_dump baseline captured.
  • IU foundation FINAL REPORT in KB.

Deliverables.

  • Migration NNN (next available; current memory shows 057 used for composer flip on 2026-05-27 — pick 058+).
  • Pre/post pg_dump diff; 15/15 forbiddens; healthcheck surface includes new gate row.
  • KB report under knowledge/dev/laws/dieu44-trien-khai/v0.6-iu-post-cut-autowire-split-merge-and-event-foundation-phase0/.

Exit gate.

  • post-CUT axis materialize runs automatically on cut_complete event.
  • split/merge can complete a full pass with a recorded review_decision_id.
  • healthcheck row added; no regressions.
  • All forbiddens preserved.

Dependencies. Hiến pháp v4.6.3, Điều 33 v2.1, Điều 35 v5.2, Điều 45 v1.0.

Recommended macro. IU_POST_CUT_AUTOWIRE_SPLIT_MERGE_AND_EVENT_FOUNDATION_PHASE0_6000X.

Phase 1 — Event foundation upgrade

Goal. Lift event 5-layer from "minimal substrate" to "operable platform" without redesigning Điều 45 core.

Scope.

  • event_type_registry hardening: schema_version (semver), schema_jsonb, owner_role, compatibility_mode (forward/backward/none), status (active|deprecated|archived).
  • Schema registry compatibility check function: fn_event_schema_validate(event_type, payload_jsonb).
  • executor_class_registry (new table) seeded with 7 classes (dot, sql, ai_agent, human, external_api, notification, render).
  • dlq_replay_request (new table) + governance flow for replay (requires approval if rows>N).
  • trace_id + correlation_id propagation contract: present on event_outbox + job_queue + workflow_run + task_run.
  • LISTEN/NOTIFY infrastructure validated; default off (gate queue.notify.enabled currently false).
  • Heartbeat caller pattern documented as a reusable PG function template.

Entry gate. Phase 0 exit gate PASS.

Deliverables.

  • Migration NNN with new tables + functions + dot_config gates.
  • DOT commands registered in dot_iu_command_catalog.
  • KB report; 15/15 forbiddens.
  • Tests: BEGIN/ROLLBACK regression for schema validate, executor registration, DLQ replay refusal without approval.

Exit gate.

  • Producers cannot emit unregistered event_type at any caller site that uses the validator.
  • Executor classes catalogued; lease + heartbeat enforced for the 2 classes used by Phase 2.
  • DLQ replay flow can be initiated by operator with audit.
  • trace_id present on at least 95% of new rows after gate enabled.

Dependencies. Phase 0; Điều 45.

Recommended macro. EVENT_FOUNDATION_UPGRADE_PHASE1_6000X.

Parallel track. Begin law extraction §12 preconditions in parallel: write law survey + draft outline.

Phase 2 — MOT minimum

Goal. Prove MOT-not-executor pattern with 2 executor classes end-to-end: dot (automated) + human (human-in-the-loop). Avoid building MOW first.

Scope.

  • task_def table (design-time).
  • tasks schema extension (executor_class, idempotency_key UNIQUE NULLS NOT DISTINCT, correlation_id, trace_id, due_at, escalation_policy_id).
  • Task state machine functions: fn_mot_create_task_run, fn_mot_assign, fn_mot_complete, fn_mot_fail, fn_mot_escalate.
  • Lease + heartbeat for executor pool (consume from job_queue; class filter).
  • Pilot: one DOT task (e.g. fn_iu_collection_render as task) and one human task (one row in tasks with a simple UI mock).
  • Idempotency proof via duplicate enqueue test.

Entry gate. Phase 1 exit gate PASS.

Deliverables.

  • Migration NNN; KB report; tests.
  • Pilot evidence: 1 DOT task lifecycle event chain; 1 human task lifecycle.

Exit gate.

  • task_def + tasks fully wired.
  • 2 executor classes operational with heartbeat.
  • No MOT code path performs the business work itself (executor pool does it).

Dependencies. Phase 1.

Recommended macro. MOT_MINIMUM_PHASE2_6000X.

Phase 3 — MOW core

Goal. Workflow registry + state machine + advance loop + proposal mode wiring.

Scope.

  • workflow_registry + workflow_step_def (new); extend workflows, workflow_steps, workflow_step_relations.
  • State machine functions: fn_mow_create_run, fn_mow_advance, fn_mow_step_complete, fn_mow_pause, fn_mow_resume, fn_mow_complete, fn_mow_fail, fn_mow_escalate.
  • Trigger types 1/2/3 + composite AND/OR engine.
  • Proposal mode wired into workflow_change_requests (existing) + new proposal_review table; approval via Điều 32.
  • One pilot workflow: Tuyển sinh (Phụ lục A sample data) — 6 steps end-to-end.
  • Sub-workflow correlation chain (one nested example).

Entry gate. Phase 2 exit gate PASS.

Deliverables.

  • Migration NNN; KB report; tests.
  • Pilot evidence: one workflow_run completed; one proposal approved and applied.

Exit gate.

  • Workflow can be created by config alone.
  • Proposal lifecycle works end-to-end (propose → review → approve → apply).
  • Long-running snapshot/resume tested with at least one pause/resume cycle.
  • Nested workflow correlation_id chain preserved.

Dependencies. Phase 2.

Recommended macro. MOW_CORE_PHASE3_6000X.

Parallel. Law draft v0.1 candidate.

Phase 4 — MOIT / MOUT factory

Goal. Field/form/output factories — config to render.

Scope.

  • field_registry, input_form_registry (new).
  • Validation rule engine (PG-side): fn_moit_validate(form_id, payload_jsonb).
  • output_table_registry, dot_function_registry (new).
  • fn_mout_resolve_query(table_id, context_jsonb, viewer_role) — assemble query at PG.
  • Permission filter functions (per output_table).
  • Nuxt component contract finalized: <MOITForm formId>, <MOUTTable tableId contextId> — zero logic.
  • One pilot each: a MOIT form fed into a MOT task; a MOUT table embedded as reference in same task.

Entry gate. Phase 3 exit gate PASS.

Deliverables.

  • Migration NNN; KB report; tests.
  • Pilot Nuxt page rendering form + table from config.

Exit gate.

  • Adding a new field/form/output table is config-only (no code deploy needed for that path).
  • Field governance refuses unregistered fields.
  • Permission filter applied at backend; tested with 2+ roles.

Dependencies. Phase 3.

Recommended macro. MOIT_MOUT_FACTORY_PHASE4_6000X.

Phase 5 — Governance UI

Goal. Problem-only surface; gateway; DLQ rescue.

Scope.

  • Realtime gateway (separate service or Nuxt server route).
  • Governance UI panels (per master design §15).
  • AI/worker-generated 1-line summary aggregator.
  • DLQ replay UI gated by approval.
  • Heartbeat panel; gate state panel.
  • Notification routes (iu_notification_event extended for governance).

Entry gate. Phase 4 exit gate PASS.

Deliverables.

  • Gateway service + Nuxt UI panels.
  • KB report; pilot smoke with 3 panels operational.

Exit gate.

  • Governance UI shows summaries first.
  • Operator can initiate DLQ replay through UI with audit.
  • Silent-worker panel surfaces Điều 45 §15.5 violations.

Dependencies. Phase 4.

Recommended macro. GOVERNANCE_UI_PROBLEM_SURFACE_PHASE5_6000X.

Phase 6 — Scale hardening

Goal. Production-ready performance + observability.

Scope.

  • Partitioning: tasks, workflows, event_outbox, iu_lifecycle_log by month or hash.
  • Indexes: per query profile.
  • Archival: retention policies (iu_core_retention_policy already present — extend per domain).
  • Observability: OpenTelemetry trace_id propagation end-to-end; metrics dashboard.
  • Performance tests: 10k workflows × 100k tasks soak.

Entry gate. Phase 5 exit gate PASS.

Deliverables.

  • Migration NNN; KB report; perf evidence.

Exit gate.

  • p95 task pickup latency under target.
  • archive automation runs.
  • DLQ growth bounded.

Dependencies. Phase 5.

Recommended macro. SCALE_HARDENING_PHASE6_6000X.

Cross-phase tracks

Track L — Law drafting (parallel)

Step Phase trigger Output
Law survey draft end of Phase 1 knowledge/dev/laws/.../readiness-survey/
Law v0.1 DRAFT end of Phase 2 candidate clauses §1–§22
Council Round 1 mid Phase 3 review verdicts
Law v0.2 patch end of Phase 3 revised
Council Round 2 mid Phase 4 revised
User approval + ENACTMENT end of Phase 4 Điều XX vX.0 BAN HÀNH

Track O — Operational readiness

  • DOT command catalog growth — every new function registered.
  • Healthcheck surface — every new gate row added.
  • Backup + pg_dump diff — captured per migration.
  • KB reports per phase — uploaded under knowledge/dev/reports/architecture/ or equivalent folder.

Track A — Agent enablement

  • Codex/Claude Code prompt updates per new pattern.
  • DOT skill packs updated.
  • Council review of any new auto-generated artifact.

Risk register

Risk Likelihood Impact Mitigation
Phase 0 expands and steals Phase 1 time medium medium strict exit gate; macro size capped at 6000x.
Event schema migration breaks existing producers medium high semver + compatibility_mode field; forward-compat default.
MOT becomes executor by accident low very high Phase 2 exit gate audit + Điều 45 §11.5 sentinel test.
Workflow state machine cannot model real long-running cases medium high snapshot + checkpoint built from Phase 3; fallback to Temporal evaluated only if needed.
Nuxt picks up business logic during Phase 5 medium high render-shell contract enforced via tests + Điều 28.
Law drafted too early medium medium Preconditions §12 strict.
Law drafted too late low medium Track L explicit per phase.

Open questions (forwarded to design + law plan)

  • Realtime gateway: Node WS service vs Nuxt server route vs Centrifugo. Decide by Phase 5 entry.
  • pg-boss / Graphile Worker adoption: profile by Phase 6 entry.
  • Temporal evaluation: only if Phase 3 state machine soak shows insufficiency.
  • Field validation cross-field engine: PG side (default) vs Nuxt side (rejected).
  • Proposal table — single generic vs per-domain. Default: generic with discriminator.

Next macro recommendation

→ IU_POST_CUT_AUTOWIRE_SPLIT_MERGE_AND_EVENT_FOUNDATION_PHASE0_6000X.

Why: closes immediate IU gaps + starts event foundation hardening; sequenced to land before MOT/MOW. Large enough for 6000x target runtime; deliverables verifiable by live evidence.

End roadmap.