@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/flows/prompts.ts

@@ -0,0 +1,65 @@
+/**
+ * Flow Builder operating guide — the detailed "how to act" prompt the runtime
+ * injects into the main agent's system prompt while the flows capability is
+ * loaded (see `main-agent.ts`, gated on `loadedPlugins` containing
+ * {@link FLOWS_PLUGIN_NAME}). It is the durable counterpart to the manifest
+ * that `load_capability` returns: the manifest sells the capability at
+ * discovery time; this guide governs behaviour for the whole flow-building
+ * session.
+ *
+ * Kept here (not in the manifest `summary`) on purpose: the summary is a
+ * one-line discovery teaser shown by `list_capabilities`, while this guide is
+ * the multi-paragraph operating contract — too long for the summary, and only
+ * worth its tokens once the agent is actually building a flow.
+ */
+
+/** The plugin's registered name — single source of truth for the load gate. */
+export const FLOWS_PLUGIN_NAME = 'flows';
+
+/**
+ * The operating guide. Starts with its own `### Flow Builder mode` sub-header
+ * so it nests cleanly under the runtime's `## Custom Instructions` section
+ * wherever the composer slots it in.
+ */
+export const FLOWS_OPERATING_GUIDE = `### Flow Builder mode
+
+You have loaded the **Flow Builder** capability. Use it whenever the user wants to build, change, inspect, or fill in a flow (an automation/workflow). Follow this guide while it is loaded.
+
+**What you are:** a flow *builder*, not a runner. You author a reusable flow **template** — its steps (action blocks), the data wired between them, conditions, schedules, assignees, and forms — and you read a flow's live state. You **never** execute, run, sign, mint, enter a PIN, or hold a key. The **user runs the flow in the portal**, where signing, PINs, and any money movement happen. Never claim to have run, signed, or executed a step.
+
+**The build loop — discover → plan → confirm → build → hand off.** Don't overthink it: one discovery pass, one short plan, one confirmation, then build.
+
+1. **Discover (know the blocks before you plan).** Work out which action blocks the automation needs and look up *exactly* what each one requires before you promise anything:
+   - \`list_actions\` to find candidate blocks; \`describe_action\` on each to get its real inputs, outputs, and whether it is a form.
+   - \`requirements\` on each block to get the prerequisites the **user** must supply — e.g. a claim collection, a connected account, a template id, a recipient, an endpoint, a PIN, a funding amount. These are things you must ASK for; never invent them.
+   Do this as a quiet tool pass — not a wall of text to the user.
+
+2. **Plan (planning mode — this is the first thing the user sees).** Before writing anything, present a short, plain-language plan and STOP for approval. For each step, in one line: **"I'll use the \`<action>\` block — it <does X>"**; then how the steps connect (which output feeds which input), plus any form, schedule, assignee, or condition. End the plan with a clear bulleted list of **what you need from the user** — every \`requires\` you could not fill yourself. Keep it tight: a numbered list, not an essay.
+
+3. **Confirm.** Ask the user to confirm or adjust the plan, and wait for a yes (or their edits). Do **not** author the flow until they confirm. Ask once, as a single plan — don't drip one question at a time.
+
+4. **Build (only after confirmation).** Run \`validate_flow\` first, then:
+   - New flow → \`create_template\`. Editing the flow that is already open → the edit tools (\`add_step\`, \`update_step\`, \`remove_step\`, \`reorder_step\`, \`set_step_*\`, \`connect_steps\`). \`create_template\` makes a BRAND-NEW flow in its own room — never use it to change an existing or open flow.
+   - Set a step's literal input values with \`set_step_inputs\`; wire data between steps with \`connect_steps\` (one upstream output → one downstream input per call). Use \`list_referenceable_fields\` to see what a step can pull from upstream, and \`check_link\` / \`compatible_actions\` to verify a wire before relying on it.
+   - For a **form** step you MUST call \`set_form_schema\` to define its questions — a form with no questions cannot run. \`fill_form\` only pre-fills answers; it never submits.
+   - For a phased product journey, set each step's stable \`phase\`. Mark consequential approvals and publication \`human-only\`. Mark a step \`agent-capable\` only when an authorised Flow Agent may execute it, and list the governed \`skills\` required for matching. Never invent agent roles as a substitute for skill ids.
+   - Apply conditions, schedule, assignee, and confirmation with the matching \`set_step_*\` tool.
+
+5. **Hand off.** Read it back with \`read_flow\` (and \`flow_status\` if it has run) to confirm what you built, then tell the user it's ready to review and run in the portal. You don't run it.
+
+**Wiring & sequencing (verified — get this right):**
+- Sequence with **step order + data references.** A step that reads \`{{a.output.x}}\` is not ready until step \`a\` has produced that output — that is the real dependency, and it works for every block.
+- **Always wire step-to-step data with \`connect_steps\`, never \`set_step_inputs\`.** \`set_step_inputs\` REPLACES the step's entire inputs map — using it to add one wire silently drops every other input already configured on that step (e.g. the email block loses its recipient). \`connect_steps\` merges a single \`{{from.output.field}}\` reference into the existing inputs. Reserve \`set_step_inputs\` for setting a step's full set of values in one call.
+- **Auto-run a step when an upstream step finishes:** set that step's \`onEvent\` to \`{ fromStep: "<upstream-step-id>", event: "<event-name>" }\`. This is the ONLY thing that auto-fires a downstream block. Use \`describe_action\` to see a step's emitted events. Example: a **form** step emits \`form.submitted\` — to send an email the moment the form is submitted, set the email step's \`onEvent\` to \`{ fromStep: "<form-step>", event: "form.submitted" }\` and wire its inputs from \`{{<form-step>.output.answers.<field>}}\`.
+- **Do NOT** use \`after\` (ordering only — it does NOT auto-fire) or lifecycle hooks (e.g. \`on.sendEmail\`, which is a separate platform-email side effect, NOT a way to trigger an integration block) to auto-run a step. Only \`onEvent\` auto-fires.
+- \`set_step_trigger\` sets \`manual\` vs \`flow-start\`. \`onEvent\` is only valid when the upstream action actually emits events (\`validate_flow\` enforces this); otherwise fall back to order + data references and the user runs the step manually.
+- \`set_step_conditions\` gate on an upstream step's **configured** value, not its live runtime result.
+
+**Asking vs guessing:** STOP and ask for any \`requires\` you can't fill from context (collection ids, DIDs, recipients, connected accounts, template names, endpoints, PINs, amounts). Never fabricate them. But don't ask for things the portal collects at run time, or that you can reasonably infer.
+
+**Status is read-only.** \`flow_status\` / \`get_step\` / \`explain_step\` report the user's real runs — use them to report progress or to diagnose a failed step and fix the template. Never invent a step's state, a transaction result, or a proof.
+
+**Tools at a glance.** Discover: \`list_actions\`, \`describe_action\`, \`requirements\`, \`list_referenceable_fields\`. Inspect: \`read_flow\`, \`get_step\`, \`flow_status\`, \`explain_step\`. Author: \`validate_flow\`, \`create_template\`, \`add_step\`, \`update_step\`, \`remove_step\`, \`reorder_step\`, \`connect_steps\`, \`update_flow_meta\`. Tune: \`set_step_inputs\`, \`set_step_conditions\`, \`set_step_schedule\`, \`set_step_assignment\`, \`set_step_confirmation\`, \`set_step_trigger\`. Link: \`check_link\`, \`compatible_actions\`. Forms: \`set_form_schema\`, \`describe_form\`, \`fill_form\`.
+
+**Step ids are short everywhere.** Always use the short step id in \`onEvent.fromStep\` and in \`{{step-id.output.field}}\` references (e.g. \`{{it-request-form.output.answers.email}}\`). After configuring an \`onEvent\` trigger, report back to the user exactly what it does: which step fires, on which event, and which downstream step it triggers.
+`;

package/src/plugins/flows/read.ts

@@ -0,0 +1,392 @@
+/**
+ * Multi-source read assembler (spec §4.1). The editor stores a flow across
+ * three places and per-block props live only in the document fragment, so a
+ * single read path is lossy. `readFlowSpec` gathers from all of them:
+ *   - the `qi.flow.*` maps -> structure (nodes/order/edges/registryType)
+ *   - the `document` XmlFragment -> per-block props (inputs/conditions/trigger)
+ *   - the `runtime` map -> per-step status/error/output
+ *
+ * We read the `qi.flow.*` maps with oracle-runtime's own yjs rather than the
+ * editor package's `readCompiledFlowFromYDoc`: the editor bundles a different
+ * yjs minor, and its reader does `value instanceof Y.Map` against ITS yjs, which
+ * is false for the native nested maps in the plugin's provider doc — so it
+ * returns empty nodes cross-version. Reading the maps directly here (reading,
+ * never compiling) keeps every doc access on a single yjs instance. Per-block
+ * props + runtime are read via the editor plugin's own (same-yjs) helpers.
+ */
+import type { Doc as YDoc } from 'yjs';
+import * as Y from 'yjs';
+import {
+  collectAllBlocks,
+  extractBlockProperties,
+  readRuntimeState,
+} from './ydoc-helpers';
+import {
+  blockIdToStepId,
+  canToAction,
+  nbToFriendlyInputs,
+  parseConditionsProp,
+} from './translator';
+import type {
+  FlowSpecRead,
+  FlowStepRead,
+  StepState,
+  StepStatus,
+} from './types';
+
+const STEP_STATES: readonly StepState[] = [
+  'idle',
+  'running',
+  'completed',
+  'failed',
+  'cancelled',
+  'awaiting_readback',
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' ? value : undefined;
+}
+function asStepState(value: unknown): StepState | undefined {
+  return STEP_STATES.includes(value as StepState)
+    ? (value as StepState)
+    : undefined;
+}
+
+/** Parse a value that may be a JSON string (fragment attribute) or already an object. */
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (isRecord(value)) return value;
+  if (typeof value === 'string' && value.length > 0) {
+    try {
+      const parsed: unknown = JSON.parse(value);
+      return isRecord(parsed) ? parsed : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+interface FlowNode {
+  can: string;
+  registryType?: string;
+  title?: string;
+  description?: string;
+  phase?: string;
+}
+interface CompiledStructure {
+  meta: { title: string; goal?: string };
+  nodes: Record<string, FlowNode>;
+  order: string[];
+  blockIndex: Record<string, string>;
+}
+
+/** Read the compiled `qi.flow.*` graph natively (same yjs as the doc). */
+function readCompiledStructure(doc: YDoc): CompiledStructure | null {
+  const order = doc
+    .getArray('qi.flow.order')
+    .toArray()
+    .filter((v): v is string => typeof v === 'string');
+  if (order.length === 0) return null;
+
+  const meta = doc.getMap('qi.flow.meta');
+  const nodes: Record<string, FlowNode> = {};
+  doc.getMap('qi.flow.nodes').forEach((value, nodeId) => {
+    if (!(value instanceof Y.Map)) return;
+    const can = asString(value.get('can')) ?? '';
+    nodes[nodeId] = {
+      can,
+      registryType: asString(value.get('registryType')),
+      title: asString(value.get('title')),
+      description: asString(value.get('description')),
+      phase: asString(value.get('phase')),
+    };
+  });
+
+  const blockIndex: Record<string, string> = {};
+  doc.getMap('qi.flow.blockIndex').forEach((value, key) => {
+    if (typeof value === 'string') blockIndex[key] = value;
+  });
+
+  return {
+    meta: {
+      title: asString(meta.get('title')) ?? '',
+      goal: asString(meta.get('goal')),
+    },
+    nodes,
+    order,
+    blockIndex,
+  };
+}
+
+interface TriggerProp {
+  type?: string;
+  sourceBlockId?: string;
+  eventName?: string;
+}
+
+/** Parse the `trigger` prop (a JSON-serialized TriggerSpec) the compiler writes. */
+function parseTriggerProp(value: unknown): TriggerProp | undefined {
+  const obj = asObject(value);
+  if (!obj) return undefined;
+  return {
+    type: asString(obj.type),
+    sourceBlockId: asString(obj.sourceBlockId),
+    eventName: asString(obj.eventName),
+  };
+}
+
+/** First authorised actor from the `authorisedActors` prop (a JSON array string). */
+function firstActor(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (Array.isArray(parsed) && typeof parsed[0] === 'string')
+      return parsed[0];
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+function stringList(value: unknown): string[] {
+  if (typeof value !== 'string' || value.length === 0) return [];
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed)
+      ? parsed.filter(
+          (item): item is string => typeof item === 'string' && item.length > 0,
+        )
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/** The assignee DID from the `assignment` prop (`{ assignedActor: { did } }` JSON). */
+function assigneeFrom(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (parsed && typeof parsed === 'object') {
+      const actor = (parsed as { assignedActor?: unknown }).assignedActor;
+      if (actor && typeof actor === 'object') {
+        const did = (actor as { did?: unknown }).did;
+        if (typeof did === 'string' && did.length > 0) return did;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+/** Collect the upstream step ids this step refers to via "{{step.output.*}}" inputs. */
+function referencedSteps(
+  inputs: Record<string, unknown> | undefined,
+): string[] {
+  if (!inputs) return [];
+  const refs = new Set<string>();
+  for (const value of Object.values(inputs)) {
+    if (typeof value === 'string') {
+      const match = /^\{\{\s*([^.}\s]+)\./.exec(value);
+      if (match?.[1]) refs.add(match[1]);
+    }
+  }
+  return [...refs];
+}
+
+/** Derive a step's read-only status from its runtime entry + its dependencies' states. */
+function computeStatus(
+  runtime: Record<string, unknown> | undefined,
+  dependencies: { referenced: string[]; after: string[] },
+  stateByStepId: Map<string, StepState>,
+): StepStatus {
+  const state = asStepState(runtime?.state) ?? 'idle';
+  const status: StepStatus = { state };
+
+  const error = isRecord(runtime?.error) ? runtime.error : undefined;
+  if (error && typeof error.message === 'string') {
+    status.error = {
+      message: error.message,
+      code: asString(error.code),
+      at: asNumber(error.at),
+    };
+  }
+  const executedAt = asNumber(runtime?.executedAt);
+  if (executedAt !== undefined) status.lastRunAt = executedAt;
+
+  const blockedBy = new Set<string>();
+  for (const dep of [...dependencies.referenced, ...dependencies.after]) {
+    const depState = stateByStepId.get(dep);
+    const isReferenced = dependencies.referenced.includes(dep);
+    if (depState === 'failed' || (isReferenced && depState !== 'completed')) {
+      blockedBy.add(dep);
+    }
+  }
+  if (blockedBy.size > 0) status.blockedBy = [...blockedBy];
+
+  // Completed without a proof receipt -> flag as stale so the agent doesn't trust it.
+  if (state === 'completed') {
+    const output = isRecord(runtime?.output) ? runtime.output : {};
+    const hasProof =
+      typeof output.transactionHash === 'string' ||
+      typeof output.claimId === 'string' ||
+      typeof runtime?.claimId === 'string';
+    if (!hasProof) status.stale = true;
+  }
+  return status;
+}
+
+/**
+ * Assemble a FlowSpec from a connected flow-room Y.Doc. Returns null when the
+ * doc holds no compiled flow (caller surfaces `flow_not_found`).
+ */
+export function readFlowSpec(doc: YDoc, ref: string): FlowSpecRead | null {
+  const compiled = readCompiledStructure(doc);
+  if (!compiled) return null;
+
+  // Per-block props, keyed by block id.
+  const fragment = doc.getXmlFragment('document');
+  const propsByBlockId = new Map<string, Record<string, unknown>>();
+  for (const block of collectAllBlocks(fragment)) {
+    propsByBlockId.set(block.id, extractBlockProperties(block));
+  }
+
+  const runtimeByBlockId = readRuntimeState(doc);
+  const blockToStep = new Map<string, string>();
+  for (const [nodeId, blockId] of Object.entries(compiled.blockIndex)) {
+    blockToStep.set(blockId, nodeId);
+  }
+  const resolveStep = (blockId: string): string =>
+    blockToStep.get(blockId) ?? blockId;
+
+  // First pass: assemble each step (without status) + record raw runtime state.
+  const steps: FlowStepRead[] = [];
+  const runtimeByStep = new Map<string, Record<string, unknown> | undefined>();
+  const dependenciesByStep = new Map<
+    string,
+    { referenced: string[]; after: string[] }
+  >();
+  const stateByStepId = new Map<string, StepState>();
+
+  for (const nodeId of compiled.order) {
+    const node = compiled.nodes[nodeId];
+    if (!node) continue;
+    const blockId = compiled.blockIndex[nodeId];
+    const props = (blockId && propsByBlockId.get(blockId)) || {};
+    const runtime = blockId ? runtimeByBlockId[blockId] : undefined;
+
+    const inputs = nbToFriendlyInputs(asObject(props.inputs));
+    const conditions = parseConditionsProp(props.conditions, resolveStep);
+
+    const step: FlowStepRead = {
+      id: nodeId,
+      action: node.registryType ?? canToAction(node.can),
+    };
+    if (node.title && node.title !== node.can) step.title = node.title;
+    if (node.description) step.description = node.description;
+    if (node.phase) step.phase = node.phase;
+    if (props.flowAgentExecutionMode === 'human-only') {
+      step.execution = 'human-only';
+    } else if (
+      props.flowAgentExecutionMode === 'saved-input' ||
+      props.flowAgentExecutionMode === 'runtime-input-required'
+    ) {
+      step.execution = 'agent-capable';
+    }
+    const skills = stringList(props.requiredSkills);
+    const primarySkill = asString(props.requiredSkill);
+    if (skills.length > 0) step.skills = skills;
+    else if (primarySkill) step.skills = [primarySkill];
+    if (inputs) step.inputs = inputs;
+    if (conditions.length === 1 && conditions[0]) step.runWhen = conditions[0];
+    else if (conditions.length > 1) step.conditions = conditions;
+
+    const trigger = parseTriggerProp(props.trigger);
+    if (
+      trigger?.type === 'block.event' &&
+      trigger.sourceBlockId &&
+      trigger.eventName
+    ) {
+      // Compiled props store the BLOCK id; the agent always sees step ids.
+      step.onEvent = {
+        fromStep: blockIdToStepId(trigger.sourceBlockId),
+        event: trigger.eventName,
+      };
+    } else if (trigger?.type === 'flow.start') {
+      step.trigger = 'flow-start';
+    }
+
+    const due: { at?: string; within?: string } = {};
+    const at = asString(props.ttlAbsoluteDueDate);
+    const within = asString(props.ttlFromEnablement);
+    if (at) due.at = at;
+    if (within) due.within = within;
+    if (Object.keys(due).length > 0) step.due = due;
+    const commitTo = asString(props.ttlFromCommitment);
+    if (commitTo) step.commitTo = commitTo;
+
+    // The assignee lives in props.assignment (what the portal reads); fall back
+    // to the authorisedActors whitelist for flows authored before that split.
+    const assignTo =
+      assigneeFrom(props.assignment) ?? firstActor(props.authorisedActors);
+    if (assignTo) step.assignTo = assignTo;
+
+    if (
+      props.requiresConfirmation === 'true' ||
+      props.requiresConfirmation === true
+    ) {
+      step.requireConfirmation = true;
+    }
+
+    steps.push(step);
+    runtimeByStep.set(nodeId, runtime);
+    stateByStepId.set(nodeId, asStepState(runtime?.state) ?? 'idle');
+    dependenciesByStep.set(nodeId, {
+      referenced: referencedSteps(inputs),
+      after: [],
+    });
+  }
+
+  // Second pass: now that every step's state is known, compute status.
+  for (const step of steps) {
+    step.status = computeStatus(
+      runtimeByStep.get(step.id),
+      dependenciesByStep.get(step.id) ?? { referenced: [], after: [] },
+      stateByStepId,
+    );
+  }
+
+  const result: FlowSpecRead = { ref, title: compiled.meta.title, steps };
+  if (compiled.meta.goal) result.goal = compiled.meta.goal;
+  return result;
+}
+
+/** Read a single step (with status) from a connected doc. */
+export function readStep(
+  doc: YDoc,
+  ref: string,
+  stepId: string,
+): FlowStepRead | null {
+  const flow = readFlowSpec(doc, ref);
+  return flow?.steps.find((s) => s.id === stepId) ?? null;
+}
+
+/** Read just the per-step status (the `flow_status` projection). */
+export function readFlowStatus(
+  doc: YDoc,
+  ref: string,
+): Array<{ id: string } & StepStatus> | null {
+  const flow = readFlowSpec(doc, ref);
+  if (!flow) return null;
+  return flow.steps.map((s) => ({
+    id: s.id,
+    ...(s.status ?? { state: 'idle' as const }),
+  }));
+}

package/src/plugins/flows/references.ts

@@ -0,0 +1,66 @@
+/**
+ * Field references (spec §2.4, the `list_referenceable_fields` discovery tool).
+ * Returns the friendly output fields a step can pipe from its upstream steps,
+ * so the agent never has to guess a "{{step.output.field}}" string.
+ */
+import type { Doc as YDoc } from 'yjs';
+import { ACTION_METADATA } from './action-metadata';
+import { getActionDef, isFormAction } from './actions';
+import { formOutputFields } from './forms';
+import { readFlowSpec } from './read';
+
+export interface ReferenceableField {
+  fromStep: string;
+  field: string;
+  type: string;
+}
+
+/**
+ * Output fields available to `stepId` — gathered from every step ahead of it in
+ * the flow (their outputs may be produced before this step runs). Uses the
+ * action's output schema, enriched by the metadata overlay's output ports.
+ */
+export function listReferenceableFields(
+  doc: YDoc,
+  ref: string,
+  stepId: string,
+): ReferenceableField[] {
+  const flow = readFlowSpec(doc, ref);
+  if (!flow) {
+    return [];
+  }
+
+  const index = flow.steps.findIndex((s) => s.id === stepId);
+
+  const upstream =
+    index >= 0
+      ? flow.steps.slice(0, index)
+      : flow.steps.filter((s) => s.id !== stepId);
+
+  const out: ReferenceableField[] = [];
+  for (const step of upstream) {
+    const def = getActionDef(step.action);
+    // Form steps emit one bundled `answers` output, not a field per question.
+    // Expand to `answers`, `form.answers`, and the individual `answers.<name>`
+    // runtime paths so a downstream scalar input (e.g. a DID) can reference the
+    // single field instead of the whole object (which stringifies to
+    // "[object Object]"). The action's outputSchema only declares the bundle.
+    if (def && isFormAction(def)) {
+      const formFields = formOutputFields(doc, step.id);
+      for (const f of formFields) {
+        out.push({ fromStep: step.id, field: f.field, type: f.type });
+      }
+      continue;
+    }
+    const overlayPorts = ACTION_METADATA[step.action]?.outputPorts ?? [];
+    for (const port of overlayPorts) {
+      out.push({ fromStep: step.id, field: port.path, type: port.portType });
+    }
+    for (const field of def?.outputSchema ?? []) {
+      if (!overlayPorts.some((p) => p.path === field.path)) {
+        out.push({ fromStep: step.id, field: field.path, type: field.type });
+      }
+    }
+  }
+  return out;
+}

package/src/plugins/flows/test-support.ts

@@ -0,0 +1,165 @@
+/**
+ * Test support: build a compiled-flow Y.Doc offline (no Matrix). Used by the
+ * read/edit unit tests so they exercise the real compiled-flow shape.
+ *
+ * Why we hydrate with oracle-runtime's own yjs instead of the editor's
+ * `hydrateYDocFromCompiledFlow`: the editor bundles a different yjs minor than
+ * oracle-runtime, and inserting the editor's Y.Map/Y.XmlElement instances into
+ * a doc created here throws ("Unexpected content type"). In production the
+ * plugin never does that — flows are authored in the editor's own doc and reach
+ * the plugin's provider doc as version-agnostic binary CRDT updates, so the
+ * plugin's doc is always natively this yjs. We reproduce that native doc here.
+ *
+ * Only the trivial Y.Doc *writing* is mirrored (the layout is verified and
+ * guarded by the read round-trip + the action snapshot canary); the compiler
+ * itself is still `compileBaseUcanFlow`. Not a `*.test.ts` file.
+ */
+import * as Y from 'yjs';
+import {
+  compileBaseUcanFlow,
+  getActionByCan,
+  getAllActions,
+  typeToCan,
+} from '@ixo/editor/core';
+import type {
+  BaseUcanFlow,
+  CompiledFlow,
+  FlowNodeRuntimeState,
+} from '@ixo/editor/core';
+import { isEventCapable } from './actions';
+import { stepIdToBlockId } from './translator';
+
+/** A real registry action type with a `can`, picked dynamically so tests never hardcode a stale name. */
+export function someActionType(): string {
+  const withCan = getAllActions().find(
+    (a) => typeof typeToCan(a.type) === 'string',
+  );
+  if (!withCan) throw new Error('no action with a `can` in the registry');
+  return withCan.type;
+}
+
+/** A registry action that can source an `onEvent` trigger (event-capable, with a `can`). */
+export function someEventCapableActionType(): string {
+  const match = getAllActions().find(
+    (a) => typeof typeToCan(a.type) === 'string' && isEventCapable(a),
+  );
+  if (!match) throw new Error('no event-capable action in the registry');
+  return match.type;
+}
+
+/** A registry action that can NOT source an `onEvent` trigger, if the registry has one. */
+export function someNonEventActionType(): string | undefined {
+  return getAllActions().find(
+    (a) => typeof typeToCan(a.type) === 'string' && !isEventCapable(a),
+  )?.type;
+}
+
+function writeNodeMap(doc: Y.Doc, compiled: CompiledFlow): void {
+  const nodes = doc.getMap('qi.flow.nodes');
+  for (const nodeId of Object.keys(compiled.nodes)) {
+    const node = compiled.nodes[nodeId];
+    if (!node) continue;
+    const yNode = new Y.Map<unknown>();
+    yNode.set('id', node.id);
+    yNode.set('blockId', node.blockId);
+    yNode.set('can', node.can);
+    yNode.set('with', node.with);
+    yNode.set('registryType', node.registryType);
+    yNode.set('title', node.title);
+    yNode.set('description', node.description);
+    if (node.phase) yNode.set('phase', node.phase);
+    if (node.parallelGroup) yNode.set('parallelGroup', node.parallelGroup);
+    if (node.actor) yNode.set('actor', node.actor);
+    nodes.set(nodeId, yNode);
+  }
+}
+
+function writeFragment(doc: Y.Doc, compiled: CompiledFlow): void {
+  // Mirror documentFragment.ts `createBlockContainer`: blockGroup > blockContainer[id] >
+  // blockContent[type] with each prop as a direct attribute (no `attrs` wrapper).
+  const fragment = doc.getXmlFragment('document');
+  const blockGroup = new Y.XmlElement('blockGroup');
+  for (const block of compiled.blocks) {
+    const props = block.props as Record<string, unknown>;
+    const { backgroundColor, textColor, ...contentProps } = props;
+    const container = new Y.XmlElement('blockContainer');
+    container.setAttribute('id', block.id);
+    container.setAttribute(
+      'textColor',
+      typeof textColor === 'string' ? textColor : 'default',
+    );
+    container.setAttribute(
+      'backgroundColor',
+      typeof backgroundColor === 'string' ? backgroundColor : 'default',
+    );
+    const content = new Y.XmlElement(block.type);
+    for (const [key, value] of Object.entries(contentProps)) {
+      if (value === '' || value == null) continue;
+      content.setAttribute(
+        key,
+        typeof value === 'string' ? value : JSON.stringify(value),
+      );
+    }
+    container.insert(0, [content]);
+    blockGroup.insert(blockGroup.length, [container]);
+  }
+  fragment.insert(0, [blockGroup]);
+}
+
+/** Compile + hydrate a BaseUcanFlow plan into a standalone, natively-this-yjs Y.Doc. */
+export function hydrateFlowDoc(plan: BaseUcanFlow): Y.Doc {
+  const compiled = compileBaseUcanFlow(plan, { getActionByCan });
+  const doc = new Y.Doc();
+  doc.transact(() => {
+    const meta = doc.getMap('qi.flow.meta');
+    for (const [key, value] of Object.entries(compiled.meta)) {
+      if (value !== undefined) meta.set(key, value);
+    }
+    writeNodeMap(doc, compiled);
+
+    const edges = doc.getMap('qi.flow.edges');
+    for (const edge of compiled.edges) {
+      const yEdge = new Y.Map<unknown>();
+      yEdge.set('id', edge.id);
+      yEdge.set('source', edge.source);
+      yEdge.set('target', edge.target);
+      yEdge.set('kind', edge.kind);
+      if (edge.condition) yEdge.set('condition', edge.condition);
+      edges.set(edge.id, yEdge);
+    }
+
+    const order = doc.getArray<string>('qi.flow.order');
+    for (const nodeId of compiled.order) order.push([nodeId]);
+
+    const blockIndex = doc.getMap('qi.flow.blockIndex');
+    for (const [nodeId, blockId] of Object.entries(compiled.blockIndex))
+      blockIndex.set(nodeId, blockId);
+
+    writeFragment(doc, compiled);
+
+    const runtime = doc.getMap('runtime');
+    for (const nodeId of compiled.order) {
+      const blockId = compiled.blockIndex[nodeId];
+      if (blockId) runtime.set(blockId, { state: 'idle' });
+    }
+  });
+  return doc;
+}
+
+/** Seed a step's runtime entry (keyed by block id) to simulate a portal run. */
+export function setStepRuntime(
+  doc: Y.Doc,
+  stepId: string,
+  state: Partial<FlowNodeRuntimeState>,
+): void {
+  const runtime = doc.getMap('runtime');
+  doc.transact(() => {
+    const blockId = stepIdToBlockId(stepId);
+    const existing = runtime.get(blockId);
+    const base =
+      existing && typeof existing === 'object'
+        ? (existing as Record<string, unknown>)
+        : {};
+    runtime.set(blockId, { ...base, ...state });
+  });
+}