Branch E — 70 Inline-Step → IU Reference Migration Plan

Backlog (measured live): 70/70 workflow_steps are inline (0 have step_iu_ref — the column does not yet exist pre-commit). No mutation performed; read-only sampling done.

---

1. Read-only sampling result (complexity estimate)

Signal	Value
Steps total	70 (WF-001: 10, WF-002: 60)
Steps with description	70/70 (max 67 chars, avg 42)
Steps with trigger_in_text / trigger_out_text	10 / 10 (WF-001 only)
Steps with config jsonb	10 (WF-001)
Steps with long inline text (>256)	0
step_type	action 34, condition 11, human_checkpoint 9, agent_call 9, wait_for_event 4, parallel 3
actor_type	human 29, system 16, ai_agent 8, null 8, manager 8, claude_ai 1

Key finding: inline content is short labels + structured config, not long prose. WF-001 descriptions are mostly auto-generated placeholders ([active] Phân tử ND-000X trong workflow_steps) with semantic substance living in config (render_as, source_bpmn_id, role, reviewer, condition, result). WF-002's 60 steps carry description only. → Migration is low-risk; the hard part is authoring real IU content, not moving bytes.

2. Classification of inline text types

Type	Where	Disposition
A. Short label (title, ≤67-char description)	all 70	Keep as title; promote a real description into the step IU body. Placeholder [active] Phân tử… descriptions are discarded, not migrated.
B. Trigger semantics (trigger_in_text/trigger_out_text)	10	Convert to structured event refs (event_domain_ref/event_type_ref) where they map to event_type_registry; residual prose → step guide IU.
C. Render/semantic config (config jsonb: render_as, source_bpmn_id, role, reviewer, condition, result)	10	Keep in config — it is structured, not prose; not an IU candidate. source_bpmn_id links back to workflows.bpmn_xml.
D. Workflow narrative (workflows.bpmn_xml 7993 chars WF-001; narrative empty)	2	Becomes the design IU (workflows.design_iu_ref) — one per workflow.

3. Conversion model: one IU per step + one design IU per workflow (hybrid)

• design_iu_ref (workflow level): 1 IU per workflow holding the overall design narrative/intent (source: BPMN/narrative). → 2 design IUs.
• step_iu_ref (step level): 1 IU per step holding the step's semantic definition (what it does, pre/post conditions). → up to 70 step IUs.
• guide_iu_ref (step level, optional): operator guidance; created only where guidance text exists (mostly the 10 WF-001 steps). Reuse, do not duplicate.
• Bundle exception: trivial structural steps (start/end events, pure gateways) may share a small set of canonical "structural" IUs rather than minting one each — dedupe (see §4).

Rule: one IU per meaningful step; bundle/share canonical IUs for structural boilerplate. Never inline long text once an IU ref exists (Điều 38, no second SoT).

4. Dedupe policy

• Hash the normalized semantic body (type+role+condition) before mint; if an identical canonical IU exists (e.g. generic "approval gateway", "start event"), reference it instead of minting.
• Placeholder descriptions ([active] Phân tử ND-…) are treated as empty → no IU minted for the placeholder; only real authored content mints.
• Expected mint estimate: ~2 design IUs + ~40–55 distinct step IUs (after structural dedupe) + ~10 guide IUs. (Upper bound 70+2+10=82; realistic ~55–67.)

5. Versioning

• Each step IU and design IU is versioned in information_unit (existing IU versioning). workflow_steps.step_version and workflows.active_design_version pin which IU version the design references.
• Binding sets the ref to a specific IU version; re-authoring mints a new IU version and the bind DOT re-points (forward-only).

6. Rollback

• Binding is reversible: dot_mow_design_bind_step_iu set→prior value or NULL. Pre-validation, refs are NULL; un-bind = set NULL.
• Minted IUs are governed by IU lifecycle (soft-retire, Điều 30) — never hard-deleted once referenced.
• Per-batch: wrap each batch in BEGIN…COMMIT after in-tx verify; a failed batch rolls back without touching prior batches.

7. Migration batch plan

Batch	Scope	Steps	Gate
B0	Mint 2 design IUs (WF-001 from BPMN, WF-002 from description) + bind design_iu_ref	2 wf	structure_ops (design)
B1	WF-001 10 steps: mint step IUs + guide IUs, bind step_iu_ref/guide_iu_ref, map triggers→event refs, bind dot_ref where a DOT applies	10	per-step, human-reviewed
B2–B7	WF-002 60 steps in 6 batches of 10 (by step_type cluster)	60	per-batch
BV	After all bound + clean: VALIDATE CONSTRAINT the 4 IU FKs + dot/event FKs (doc 02 §7)	—	off-peak

Each batch: dry-run (compute mints/binds, no write) → human review of the IU bodies → apply in one tx → in-tx verify → commit.

8. Validation (per batch + final)

• Every targeted step ends with step_iu_ref resolvable in information_unit (FK will enforce post-VALIDATE).
• dot_ref (if set) ∈ dot_iu_command_catalog.command_name.
• (event_domain_ref,event_type_ref) (if set) ∈ event_type_registry.
• bound_step_count rises monotonically; 0 dangling refs (doc 06 harness checks).
• Acceptance: v_mow_design_workflow.bound_step_count = step_count for migrated workflows.

9. Human review points

• IU body authoring (B0–B7) — a human/author confirms each minted IU's content is real, not placeholder.
• Trigger→event mapping (B1) — human confirms semantic mapping to event_type_registry.
• Pre-VALIDATE sign-off — confirm 0 dangling refs.
• No batch auto-applies; agent proposes, human approves (doc 07).

10. DOT automation plan

• dot_mow_design_bind_step_iu / _bind_dot / _bind_event / _bind_iu perform the binds idempotently.
• A batch driver calls the bind DOTs per step from a reviewed manifest; dot_mow_design_validate after each batch; dot_mow_design_audit records the run.
• Minting step IUs reuses the existing IU create path (fn_iu_create) — design IUs are ordinary IUs with a design publication type.

11. Acceptance test

-- after migration of a workflow, expect bound == total and 0 dangling
SELECT w.id, sc.step_count, sc.bound,
       (sc.bound = sc.step_count) AS fully_bound,
       (SELECT count(*) FROM workflow_steps s WHERE s.workflow_id=w.id
          AND s.dot_ref IS NOT NULL AND NOT EXISTS (SELECT 1 FROM dot_iu_command_catalog c WHERE c.command_name=s.dot_ref)) AS dangling_dot
FROM workflows w
JOIN (SELECT workflow_id, count(*) step_count, count(*) FILTER (WHERE step_iu_ref IS NOT NULL) bound
      FROM workflow_steps GROUP BY workflow_id) sc ON sc.workflow_id=w.id;
-- PASS: fully_bound=true, dangling_dot=0 for migrated workflows

12. Migration plan verdict

Actionable. Inline content classified, conversion model (hybrid one-IU-per-step + per-workflow design IU) defined, dedupe/versioning/rollback/batch/validation/human-review/DOT-automation/acceptance all specified. Risk is low (0 long-text rows; content is short labels + structured config); the real cost is authoring genuine IU bodies, gated by human review. No mutation performed.