instant-ctrl-flow-logic 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instant-ctrl-flow-logic",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "description": "InstantCtrlFlow 引擎：xnl bundle 加载 → 行为树编译 → 无状态单次执行",
   "type": "module",
@@ -8,14 +8,16 @@
   "exports": {
     ".": "./src/index.ts",
     "./browser": "./src/browser.ts",
-    "./filesystem": "./src/filesystem.ts"
+    "./filesystem": "./src/filesystem.ts",
+    "./graph": "./src/graph.ts"
   },
   "dependencies": {
-    "depa-behavior-tree": "0.1.1",
+    "depa-behavior-tree": "0.1.2",
     "flow-step-space-contract": "0.1.1",
-    "flow-step-space-logic": "0.1.1",
-    "instant-ctrl-flow-contract": "0.1.2",
-    "xnl-core": "^0.1.8"
+    "flow-step-space-logic": "0.1.2",
+    "instant-ctrl-flow-contract": "0.1.3",
+    "xnl-core": "0.1.13",
+    "port-control-graph-logic": "0.1.0"
   },
   "files": [
     "src"

package/src/browser.ts

@@ -2,3 +2,4 @@ export * from './loader.js';
 export * from './compile.js';
 export * from './handlers.js';
 export * from './engine.js';
+export * from './control-options.js';

package/src/compile.ts

@@ -8,6 +8,27 @@ import {
 import type { FlowBundleSpec, FlowNodeSpec } from 'instant-ctrl-flow-contract';
 
 export type CtrlNode = BehaviorTreeNode<CtrlFlowNodeType, INodeConfig>;
+const compiledOwners = new WeakMap<CtrlNode, string>();
+
+function compiledChildren(node: CtrlNode): readonly CtrlNode[] {
+  if (String(node.Type) !== 'wf.Composite') return node.Children;
+  const config = node.Config as { bodyPlan?: CtrlNode; items?: { bodyPlan: CtrlNode }[] };
+  return [...node.Children, ...(config.bodyPlan ? [config.bodyPlan] : []), ...(config.items ?? []).map(item => item.bodyPlan)];
+}
+
+/** Generated actions retain their authored owner; consumers never infer it from a key prefix. */
+export function projectCompiledFlowInvocationOwners(root: CtrlNode): Readonly<Record<string, string>> {
+  const owners = new Map<string, string>();
+  const visit = (node: CtrlNode): void => {
+    const owner = compiledOwners.get(node);
+    if (owner) {
+      if (owners.has(node.Key) && owners.get(node.Key) !== owner) throw new FlowCompileError('ambiguous-action-owner', node.Key);
+      owners.set(node.Key, owner);
+    }
+    compiledChildren(node).forEach(visit);
+  };
+  visit(root); return Object.freeze(Object.fromEntries(owners));
+}
 
 const INTERRUPTIBLE = new Set(['ExternalJob', 'Timer', 'TaskStep']);
 const VIEW_ATTRS = new Set(['status', 'iterations', 'runStatus', 'tickNo']);
@@ -79,11 +100,30 @@ function compileStatement(
   node: FlowNodeSpec,
   extension: CompileExtension | undefined,
   path: string,
+  blockStack: readonly string[] = [],
+  inheritedOwner?: string,
 ): CtrlNode {
-  const key = node.id ?? path;
+  const compiled = compileStatementBody(spec, node, extension, path, blockStack, inheritedOwner);
+  const owner = node.id ?? inheritedOwner;
+  const assign = (current: CtrlNode): void => {
+    if (owner && !compiledOwners.has(current)) compiledOwners.set(current, owner);
+    compiledChildren(current).forEach(assign);
+  };
+  assign(compiled); return compiled;
+}
+
+function compileStatementBody(
+  spec: FlowBundleSpec,
+  node: FlowNodeSpec,
+  extension: CompileExtension | undefined,
+  path: string,
+  blockStack: readonly string[],
+  inheritedOwner?: string,
+): CtrlNode {
+  const key = blockStack.length ? `${path}:${node.id ?? node.tag}` : node.id ?? path;
   const attrs = resolvedAttrs(spec, node);
   const compileStatements = (nodes: FlowNodeSpec[], bodyKey: string) =>
-    sequence(bodyKey, nodes.map((child, index) => compileStatement(spec, child, extension, `${bodyKey}.${index}`)));
+    sequence(bodyKey, nodes.map((child, index) => compileStatement(spec, child, extension, `${bodyKey}.${index}`, blockStack, node.id ?? inheritedOwner)));
   const helpers: CompileHelpers = { meta: { key, name: node.id }, attrs, compileStatements };
 
   const extended = extension?.(spec, node, helpers);
@@ -94,6 +134,16 @@ function compileStatement(
   }
 
   switch (node.tag) {
+    case 'RunBlock': {
+      if (spec.form !== 'InstantCtrlFlow') throw new FlowCompileError('unsupported-block-profile', spec.form);
+      if (attrs.input !== undefined || attrs.config !== undefined) throw new FlowCompileError('block-context-override', 'RunBlock preserves caller context');
+      const ref = String(attrs.block ?? '');
+      const id = ref.startsWith('block://#') ? ref.slice(9) : '';
+      const body = spec.blocks?.[id];
+      if (!body) throw new FlowCompileError('unresolved-block-ref', ref);
+      if (blockStack.includes(id)) throw new FlowCompileError('recursive-block', [...blockStack, id].join(' -> '));
+      return sequence(key, body.map((child, index) => compileStatement(spec, child, extension, `${key}.block.${id}.${index}`, [...blockStack, id], node.id ?? inheritedOwner)));
+    }
     case 'Run':
       return action('flow.Run', key, { src: String(attrs.src ?? ''), config: statementConfig(attrs) });
     case 'Return':
@@ -107,7 +157,9 @@ function compileStatement(
       const ifPath = key;
       const branches = node.sections.Branches?.children ?? [];
       const choices = branches.map((branch, index) => {
-        const branchKey = branch.id ?? `${key}.branch.${index}`;
+        const branchKey = blockStack.length
+          ? `${key}.branch.${index}:${branch.id ?? branch.tag}`
+          : branch.id ?? `${key}.branch.${index}`;
         if (branch.tag === 'Otherwise') {
           return sequence(`${branchKey}.__choice`, [
             action('flow.Otherwise', `${branchKey}.__otherwise`, {
@@ -145,7 +197,9 @@ function compileStatement(
         if (strategy.tag !== 'Strategy') {
           throw new FlowCompileError('invalid-fallback-strategy', `<Fallback #${key}> contains <${strategy.tag}>`);
         }
-        const strategyKey = strategy.id ?? `${key}.strategy.${index}`;
+        const strategyKey = blockStack.length
+          ? `${key}.strategy.${index}:${strategy.id ?? strategy.tag}`
+          : strategy.id ?? `${key}.strategy.${index}`;
         return sequence(`${strategyKey}.__strategy`, [
           action('flow.StrategyStart', `${strategyKey}.__start`, { fallbackKey: key }),
           compileStatements(strategy.children, `${strategyKey}.__body`),
@@ -164,6 +218,7 @@ function compileStatement(
         src: String(attrs.when ?? ''),
         config: statementConfig(attrs),
         maxIterations: Number(attrs.maxIterations ?? 9999),
+        onExhausted: attrs.onExhausted ?? 'fail',
       };
       const initial = action('flow.UntilPredicate', `${key}.__check.initial`, { ...predicateConfig, countIteration: false });
       const repeated = action('flow.UntilPredicate', `${key}.__check.repeat`, { ...predicateConfig, countIteration: true });

package/src/control-options.ts

@@ -0,0 +1,53 @@
+import type { FlowBundleSpec, FlowNodeSpec } from 'instant-ctrl-flow-contract';
+
+function record(value: unknown, location: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError(`${location}: expected plain control options`);
+  if (Reflect.ownKeys(value).some(key => typeof key !== 'string')
+    || Object.values(Object.getOwnPropertyDescriptors(value)).some(descriptor => !Object.hasOwn(descriptor, 'value'))) throw new TypeError(`${location}: control options must contain data fields`);
+  return value as Record<string, unknown>;
+}
+
+function bounded(value: unknown, max: number, location: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > max) throw new RangeError(`${location}: expected integer 1..${max}`);
+  return value;
+}
+
+/** 纯转换：保留模板/旧运行，拒绝未知字段、控制节点和超过64项的覆盖。 */
+export function applyFlowControlOptions(spec: FlowBundleSpec, value: unknown): FlowBundleSpec {
+  const options = value === undefined ? {} : record(value, 'controlOptions');
+  if (Object.keys(options).length > 64) throw new RangeError('controlOptions: at most 64 node overrides');
+  const frozen = structuredClone(spec);
+  const nodes = new Map<string, FlowNodeSpec>();
+  function visit(node: FlowNodeSpec): void {
+    if (node.id) {
+      if (nodes.has(node.id)) throw new TypeError(`controlOptions: ambiguous node ${node.id}`);
+      nodes.set(node.id, node);
+    }
+    node.children.forEach(visit);
+    Object.values(node.sections).forEach(visit);
+  }
+  frozen.statements.forEach(visit);
+  Object.values(frozen.blocks ?? {}).forEach(statements => statements.forEach(visit));
+  for (const [id, input] of Object.entries(options)) {
+    const node = nodes.get(id);
+    const row = record(input, `controlOptions.${id}`);
+    const fields = Object.keys(row);
+    if (node?.tag === 'Until') {
+      if (!fields.length || fields.some(key => !['maxIterations', 'onExhausted'].includes(key))) throw new TypeError(`controlOptions.${id}: invalid Until fields`);
+      if (Object.hasOwn(row, 'maxIterations')) node.attrs.maxIterations = bounded(row.maxIterations, 1000, `${id}.maxIterations`);
+      if (Object.hasOwn(row, 'onExhausted')) {
+        if (row.onExhausted !== 'fail' && row.onExhausted !== 'complete') throw new TypeError(`${id}.onExhausted: expected fail or complete`);
+        node.attrs.onExhausted = row.onExhausted;
+      }
+    } else if (node?.tag === 'ForEach') {
+      if (!fields.length || fields.some(key => !['maxItems', 'concurrency'].includes(key))) throw new TypeError(`controlOptions.${id}: invalid ForEach fields`);
+      const maxItems = bounded(row.maxItems ?? node.attrs.maxItems ?? 1000, 1000, `${id}.maxItems`);
+      node.attrs.maxItems = maxItems;
+      node.attrs.concurrency = bounded(row.concurrency ?? node.attrs.concurrency ?? 1, Math.min(32, maxItems), `${id}.concurrency`);
+    } else {
+      throw new TypeError(`controlOptions.${id}: node is not an Until or ForEach`);
+    }
+  }
+  return frozen;
+}

package/src/graph.ts

@@ -0,0 +1,309 @@
+import { createHash } from "node:crypto";
+import { parseXnl, type DataElementNode } from "xnl-core";
+import {
+  lowerPortControlGraph,
+  type ControlShape,
+  type PortControlGraph,
+  type StructuredStatement,
+} from "port-control-graph-logic";
+import type { FlowBundleSpec, FlowNodeSpec } from "instant-ctrl-flow-contract";
+import { loadFlowBundleFromSources } from "./loader.js";
+
+export const CTRL_GRAPH_COMPILER = "depa.flows/port-ctrl-graph-to-tree@1";
+export interface CtrlGraphDocument {
+  readonly root: FlowNodeSpec;
+  readonly graph: PortControlGraph<FlowNodeSpec, string, string, string>;
+}
+export interface CtrlGraphCompileReceipt {
+  readonly schemaVersion: "depa.flows/ctrl-graph-receipt/v1";
+  readonly compiler: typeof CTRL_GRAPH_COMPILER;
+  readonly profile: "InstantCtrlFlow";
+  readonly sourceDigest: string;
+  readonly outputDigest: string;
+}
+export interface CompiledCtrlGraph {
+  readonly source: string;
+  readonly spec: FlowBundleSpec;
+  readonly provenance: Readonly<Record<string, string>>;
+  readonly inferredNext: readonly {
+    readonly owner: string;
+    readonly next: string;
+  }[];
+  readonly receipt: CtrlGraphCompileReceipt;
+}
+
+function isDataElement(value: unknown): value is DataElementNode {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    "kind" in value &&
+    value.kind === "DataElement",
+  );
+}
+function project(element: DataElementNode): FlowNodeSpec {
+  return {
+    tag: element.tag,
+    id: element.id
+      ? [...(element.id.namespace ?? []), element.id.name].join(".")
+      : undefined,
+    metadata: { ...element.metadata },
+    attrs: { ...element.attributes },
+    children: (element.body ?? []).filter(isDataElement).map(project),
+    sections: Object.fromEntries(
+      Object.values(element.extend?.children ?? {}).map((section) => [
+        section.tag,
+        project(section as DataElementNode),
+      ]),
+    ),
+  };
+}
+function endpoint(value: unknown): { node: string; port: string } {
+  const match =
+    typeof value === "string" && /^port:\/\/#([-\w.]+)\/([-\w.]+)$/.exec(value);
+  if (!match) throw new Error(`invalid port URI: ${String(value)}`);
+  return { node: match[1], port: match[2] };
+}
+export function parseCtrlFlowGraph(source: string): CtrlGraphDocument {
+  const parsed = parseXnl(source);
+  if (parsed.warnings?.length)
+    throw new Error(
+      `graph parser warnings: ${JSON.stringify(parsed.warnings)}`,
+    );
+  const roots = parsed.nodes.filter(isDataElement).map(project);
+  if (roots.length !== 1 || roots[0].tag !== "CtrlFlowGraph")
+    throw new Error("expected one CtrlFlowGraph root");
+  const root = roots[0];
+  if (root.attrs.targetForm !== "InstantCtrlFlow")
+    throw new Error("only InstantCtrlFlow graph profile is supported");
+  if (root.children.length || root.sections.Regions)
+    throw new Error(
+      "graph statements belong in Nodes; explicit Regions are unsupported",
+    );
+  const match = /^(?:ctrl-node:\/\/#)?([-\w.]+)$/.exec(
+    String(root.attrs.entry ?? ""),
+  );
+  if (!match) throw new Error("invalid graph entry");
+  if (!root.sections.Nodes || !root.sections.Edges)
+    throw new Error("graph requires Nodes and Edges");
+  return {
+    root,
+    graph: {
+      entry: match[1],
+      nodes: root.sections.Nodes.children,
+      edges: root.sections.Edges.children.map((edge) => {
+        if (edge.tag !== "Edge" || !edge.id)
+          throw new Error("Edges requires named Edge");
+        return {
+          id: edge.id,
+          from: endpoint(edge.attrs.from),
+          to: endpoint(edge.attrs.to),
+        };
+      }),
+    },
+  };
+}
+export const ctrlGraphRuntime = {
+  nodeId(node: FlowNodeSpec): string {
+    if (!node.id) throw new Error("graph node requires identity");
+    return node.id;
+  },
+  shape(node: FlowNodeSpec): ControlShape<string> {
+    if (node.children.length)
+      throw new Error(
+        `graph node #${node.id} cannot contain inline statements`,
+      );
+    for (const section of Object.keys(node.sections)) {
+      if (node.tag !== "If" || section !== "Ports")
+        throw new Error(
+          `unsupported graph node section ${section} #${node.id}`,
+        );
+    }
+    const base = { enter: "enter", next: "next" };
+    switch (node.tag) {
+      case "Run":
+        return { ...base, role: "step" };
+      case "Return":
+        return { ...base, role: "exit" };
+      case "Until":
+        return { ...base, role: "loop", body: "body" };
+      case "If":
+        return {
+          ...base,
+          role: "choice",
+          branches: (node.sections.Ports?.children ?? []).map((port) => {
+            if (port.tag !== "Port")
+              throw new Error(`If #${node.id} Ports requires Port`);
+            if (!port.id)
+              throw new Error(`If #${node.id} requires named ports`);
+            if (port.children.length || Object.keys(port.sections).length)
+              throw new Error(
+                `branch port #${port.id} cannot contain statements`,
+              );
+            if (
+              port.attrs.default !== undefined &&
+              typeof port.attrs.default !== "boolean"
+            )
+              throw new Error(
+                `branch port #${port.id} default must be boolean`,
+              );
+            if (port.attrs.default === true && port.attrs.when !== undefined)
+              throw new Error(
+                `default port #${port.id} cannot have a predicate`,
+              );
+            return {
+              port: port.id,
+              order:
+                typeof port.attrs.order === "number" ? port.attrs.order : NaN,
+              default: port.attrs.default === true,
+            };
+          }),
+        };
+      default:
+        throw new Error(`unsupported graph node ${node.tag} #${node.id}`);
+    }
+  },
+};
+function xnlValue(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(xnlValue).join(", ")}]`;
+  if (value && typeof value === "object") {
+    const fields = Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .map(([key, item]) => `${JSON.stringify(key)} = ${xnlValue(item)}`);
+    return `{ ${fields.join(" ")} }`;
+  }
+  return JSON.stringify(value);
+}
+export function serializeFlowNode(node: FlowNodeSpec): string {
+  const attributes = Object.entries(node.attrs)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => `${key} = ${xnlValue(value)}`)
+    .join("\n");
+  const metadata = Object.entries(node.metadata)
+    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+    .join(" ");
+  const sections = Object.values(node.sections)
+    .map(serializeFlowNode)
+    .join("\n");
+  return (
+    `<${node.tag}${node.id ? ` #${node.id}` : ""}${metadata ? ` ${metadata}` : ""}` +
+    `${attributes ? ` {\n${attributes}\n}` : ""}${sections ? ` (\n${sections}\n)` : ""}` +
+    `${node.children.length ? ` [\n${node.children.map(serializeFlowNode).join("\n")}\n]` : ""}>`
+  );
+}
+function blank(
+  tag: string,
+  id?: string,
+  attrs: Record<string, unknown> = {},
+  children: FlowNodeSpec[] = [],
+): FlowNodeSpec {
+  return { tag, id, attrs, children, metadata: {}, sections: {} };
+}
+export function ctrlGraphSourceDigest(source: string): string {
+  return `sha256:${createHash("sha256").update(source, "utf8").digest("hex")}`;
+}
+export function compileCtrlFlowGraph(
+  source: string,
+  options: { baseUri?: string } = {},
+): CompiledCtrlGraph {
+  const document = parseCtrlFlowGraph(source);
+  const result = lowerPortControlGraph(ctrlGraphRuntime, document.graph);
+  if (!result.ok) throw new Error(JSON.stringify(result.diagnostics));
+  const provenance: Record<string, string> = {};
+  const ids = new Set<string>();
+  function identity(sourceId: string, path: string): string {
+    let id = sourceId;
+    const suffix = path.replace(/[^\w]/g, "_");
+    let occurrence = 0;
+    while (ids.has(id)) id = `${sourceId}__${suffix}_${occurrence++}`;
+    ids.add(id);
+    provenance[id] = sourceId;
+    return id;
+  }
+  function lower(
+    statements: readonly StructuredStatement<FlowNodeSpec, string, string>[],
+    path: string,
+  ): FlowNodeSpec[] {
+    return statements.map((statement, index) => {
+      const location = `${path}_${index}`;
+      if (statement.kind === "block-ref") {
+        const id = identity(`${statement.source}__ref`, location);
+        provenance[id] = statement.source;
+        return blank("RunBlock", id, {
+          block: `block://#block_${statement.block}`,
+        });
+      }
+      const node: FlowNodeSpec = {
+        ...statement.node,
+        id: identity(statement.node.id!, location),
+        attrs: { ...statement.node.attrs },
+        sections: {},
+        children: [],
+      };
+      if (statement.kind === "choice") {
+        node.sections.Branches = blank(
+          "Branches",
+          undefined,
+          {},
+          statement.branches.map((branch) => {
+            const port = statement.node.sections.Ports.children.find(
+              (item) => item.id === branch.port,
+            )!;
+            const body = lower(branch.body, `${location}_${branch.port}`);
+            if (port.attrs.default === true)
+              return blank("Otherwise", undefined, {}, body);
+            return blank(
+              "Branch",
+              identity(`${statement.node.id}_${branch.port}`, location),
+              { when: port.attrs.when, config: port.attrs.config },
+              body,
+            );
+          }),
+        );
+      }
+      if (statement.kind === "loop")
+        node.children = lower(statement.body, `${location}_body`);
+      return node;
+    });
+  }
+  const root: FlowNodeSpec = {
+    ...document.root,
+    tag: "InstantCtrlFlow",
+    attrs: { title: document.root.attrs.title },
+    sections: { ...document.root.sections },
+    children: lower(result.forest.statements, "main"),
+  };
+  delete root.sections.Nodes;
+  delete root.sections.Edges;
+  root.sections.Blocks = blank(
+    "Blocks",
+    undefined,
+    {},
+    result.forest.blocks.map((block) =>
+      blank(
+        "Block",
+        `block_${block.id}`,
+        {},
+        lower(block.statements, `block_${block.id}`),
+      ),
+    ),
+  );
+  const output = serializeFlowNode(root);
+  const loaded = loadFlowBundleFromSources({ "flow.xnl": output }, options);
+  if (!loaded.spec || loaded.diagnostics.length)
+    throw new Error(
+      `invalid graph output: ${JSON.stringify(loaded.diagnostics)}`,
+    );
+  return {
+    source: output,
+    spec: loaded.spec,
+    provenance: Object.freeze(provenance),
+    inferredNext: result.forest.inferredNext,
+    receipt: Object.freeze({
+      schemaVersion: "depa.flows/ctrl-graph-receipt/v1",
+      compiler: CTRL_GRAPH_COMPILER,
+      profile: "InstantCtrlFlow",
+      sourceDigest: ctrlGraphSourceDigest(source),
+      outputDigest: ctrlGraphSourceDigest(output),
+    }),
+  };
+}

package/src/handlers.ts

@@ -51,6 +51,8 @@ type NodeConfig = {
   predicateKey?: string;
   countIteration?: boolean;
   maxIterations?: number;
+  onExhausted?: 'fail' | 'complete';
+  maxItems?: number;
   statements?: FlowNodeSpec[];
   items?: { id?: string; statements: FlowNodeSpec[] }[];
   flow?: string;
@@ -93,7 +95,7 @@ export interface FlowDecisionContext {
 export interface FlowDecisionHooks {
   begin(ifPath: string): FlowDecisionContext;
   record(decision: FlowBranchDecision): Promise<void> | void;
-  runtimeForNode?(nodeId: string, runtime: InstantCtrlFlowRuntime): InstantCtrlFlowRuntime;
+  runtimeForNode?(nodeId: string, runtime: InstantCtrlFlowRuntime, state?: FlowExecutionState): InstantCtrlFlowRuntime;
 }
 
 class FlowFunctionLoader {
@@ -104,8 +106,8 @@ class FlowFunctionLoader {
     private runtimeHooks?: FlowDecisionHooks,
   ) {}
 
-  runtimeForNode(nodeId: string, runtime: InstantCtrlFlowRuntime): InstantCtrlFlowRuntime {
-    return this.runtimeHooks?.runtimeForNode?.(nodeId, runtime) ?? runtime;
+  runtimeForNode(nodeId: string, runtime: InstantCtrlFlowRuntime, state: FlowExecutionState): InstantCtrlFlowRuntime {
+    return this.runtimeHooks?.runtimeForNode?.(nodeId, runtime, state) ?? runtime;
   }
 
   load(src: string, nodeId: string): Promise<FlowCodeFunction> {
@@ -135,7 +137,7 @@ async function callCode(ctx: Ctx, loader: FlowFunctionLoader, src: string): Prom
   const state = flowStateOf(ctx);
   const fn = await loader.load(src, ctx.node.Key);
   const runtime = (ctx.runtime ?? {}) as InstantCtrlFlowRuntime;
-  return fn(loader.runtimeForNode(ctx.node.Key, runtime), state.current, configOf(ctx).config ?? {});
+  return fn(loader.runtimeForNode(ctx.node.Key, runtime, state), state.current, configOf(ctx).config ?? {});
 }
 
 function fail(state: FlowExecutionState, error: unknown): BehaviorResult {
@@ -318,6 +320,10 @@ class UntilPredicateHandler implements ActionHandler<CtrlFlowNodeType, INodeConf
         const iterations = (state.untilIterations[key] ?? 0) + 1;
         state.untilIterations[key] = iterations;
         if (!result && iterations >= Number(config.maxIterations ?? 9999)) {
+          if (config.onExhausted === 'complete') {
+            state.untilValues[key] = true;
+            return BehaviorResult.Success;
+          }
           return fail(state, new Error(`Until node exceeded max iterations (${config.maxIterations})`));
         }
       }
@@ -391,6 +397,7 @@ class CompositeHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
       if (this.kind === 'ForEach') {
         const selected = await callCode(ctx, this.loader, String(config.src ?? configOf(ctx).src ?? ''));
         if (!Array.isArray(selected)) throw new TypeError('ForEach selector must return an array');
+        if (config.maxItems !== undefined && selected.length > config.maxItems) throw new RangeError(`ForEach #${ctx.node.Key} exceeds maxItems (${config.maxItems})`);
         const outputs: unknown[] = [];
         for (const item of selected) outputs.push(await this.executeBody(config.statements ?? [], item, runtime));
         state.current = outputs;

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './filesystem.js';
 export * from './compile.js';
 export * from './handlers.js';
 export * from './engine.js';
+export * from './control-options.js';

package/src/loader.ts

@@ -7,7 +7,7 @@ import { parseXnl } from 'xnl-core';
 import {
   assembleDefinitionStepProfile,
   createDefinitionStepSourceRuntime,
-} from 'flow-step-space-logic';
+} from 'flow-step-space-logic/browser';
 import type { DefinitionStepForest, DefinitionStepSourceCollection } from 'flow-step-space-contract';
 import type {
   FlowBundleSpec,
@@ -46,6 +46,7 @@ const LEGACY_PUBLIC_CONTROL_NODES = new Set(['Sequence', 'Selector', 'Condition'
 const LEGACY_PUBLIC_ACTION_NODES = new Set(['SetVariable', 'Log', 'Assert', 'Sleep', 'HttpCall', 'RunScript']);
 const COMMON_STATEMENTS = new Set([
   'Run',
+  'RunBlock',
   'If',
   'Require',
   'Fallback',
@@ -64,6 +65,9 @@ const PROFILE_STATEMENTS: Record<FlowForm, ReadonlySet<string>> = {
   BPCtrlFlow: new Set([...COMMON_STATEMENTS, 'ExternalJob', 'Timer', 'TaskStep']),
 };
 const CODE_REF = /^vfs:\/\/[^#\s]+#[A-Za-z_$][A-Za-z0-9_$]*$/;
+const HALF_CODE_RESOURCE_ENVELOPE_VERSION = 'halfcode.resource-envelope/v1';
+const DEPA_FLOW_SEMANTIC_API_VERSION = 'depa.flows/v1';
+const DEPA_FLOW_RESOURCE_SPEC_VERSION = 1;
 
 interface XnlEl {
   kind: string;
@@ -75,6 +79,64 @@ interface XnlEl {
   extend?: { order?: string[]; children: Record<string, XnlEl> };
 }
 
+interface FlowRootIdentityProjection {
+  apiVersion: string;
+  version: string;
+  diagnostic?: { code: string; message: string };
+}
+
+function projectFlowRootIdentity(metadata: Readonly<Record<string, unknown>>): FlowRootIdentityProjection {
+  const legacyApiVersion = typeof metadata.apiVersion === 'string' ? metadata.apiVersion : undefined;
+  const legacyVersion = typeof metadata.version === 'string' ? metadata.version : undefined;
+  const hasLegacyMetadata = metadata.apiVersion !== undefined || metadata.version !== undefined;
+  const hasResourceMetadata = metadata.envelopeVersion !== undefined || metadata.specVersion !== undefined;
+  if (hasLegacyMetadata && hasResourceMetadata) {
+    return {
+      apiVersion: '',
+      version: '',
+      diagnostic: {
+        code: 'mixed-flow-root-metadata',
+        message: 'flow root must use either depa apiVersion/version or Halfcode envelopeVersion/specVersion metadata',
+      },
+    };
+  }
+  if (hasResourceMetadata) {
+    if (metadata.envelopeVersion !== HALF_CODE_RESOURCE_ENVELOPE_VERSION) {
+      return {
+        apiVersion: '',
+        version: '',
+        diagnostic: {
+          code: 'unsupported-flow-resource-envelope',
+          message: `flow resource root requires envelopeVersion "${HALF_CODE_RESOURCE_ENVELOPE_VERSION}"`,
+        },
+      };
+    }
+    if (metadata.specVersion !== DEPA_FLOW_RESOURCE_SPEC_VERSION) {
+      return {
+        apiVersion: '',
+        version: '',
+        diagnostic: {
+          code: 'unsupported-flow-resource-spec-version',
+          message: `flow resource root requires numeric specVersion ${DEPA_FLOW_RESOURCE_SPEC_VERSION}`,
+        },
+      };
+    }
+    return {
+      apiVersion: DEPA_FLOW_SEMANTIC_API_VERSION,
+      version: String(DEPA_FLOW_RESOURCE_SPEC_VERSION),
+    };
+  }
+  if (legacyApiVersion && legacyVersion) return { apiVersion: legacyApiVersion, version: legacyVersion };
+  return {
+    apiVersion: legacyApiVersion ?? '',
+    version: legacyVersion ?? '',
+    diagnostic: {
+      code: 'container-missing-meta',
+      message: 'container missing metadata "apiVersion" or "version"',
+    },
+  };
+}
+
 const isEl = (n: unknown): n is XnlEl =>
   !!n && typeof n === 'object' && ((n as XnlEl).kind === 'DataElement' || (n as XnlEl).kind === 'TextElement');
 
@@ -276,6 +338,18 @@ function loadCtrlFlowSources(
   const statementEls = listChildren(container);
   for (const statement of statementEls) visitStatement(statement);
 
+  const blockSections = sectionChildren(container).filter(s => s.tag === 'Blocks');
+  if (blockSections.length && form !== 'InstantCtrlFlow') note('unsupported-block-profile', 'Blocks persistence is only validated for InstantCtrlFlow');
+  if (blockSections.length > 1) note('duplicate-blocks', 'only one Blocks section is allowed');
+  const blockEls = blockSections.flatMap(listChildren);
+  const blockIds = new Set<string>();
+  for (const block of blockEls) {
+    const id = idOf(block);
+    if (block.tag !== 'Block' || !id) note('invalid-block', 'Blocks requires named Block children');
+    else if (blockIds.has(id)) note('duplicate-block', `duplicate block #${id}`);
+    else blockIds.add(id);
+  }
+  const blockRefs = new Map<string, Set<string>>();
   const seenIds = new Set<string>();
   const requireCodeRef = (el: XnlEl, field: string) => {
     const value = el.attributes?.[field];
@@ -302,6 +376,14 @@ function loadCtrlFlowSources(
       else seenIds.add(id);
 
       if (node.tag === 'Run') requireCodeRef(node, 'src');
+      if (node.tag === 'RunBlock') {
+        const ref = node.attributes?.block;
+        if (typeof ref !== 'string' || !/^block:\/\/#[-\w.]+$/.test(ref) || !blockIds.has(ref.slice(9))) {
+          note('unresolved-block-ref', `<RunBlock #${id ?? ''}> requires an existing flow-local block://#id`);
+        }
+        if (listChildren(node).length) note('run-block-body', 'RunBlock cannot have an inline body');
+        if (node.attributes?.config !== undefined || node.attributes?.input !== undefined) note('block-context-override', 'RunBlock preserves caller context and accepts no input/config override');
+      }
       if (node.tag === 'Require' || node.tag === 'Until' || node.tag === 'ForEach') requireCodeRef(node, 'when');
       if (node.tag === 'Retry') requirePositiveInteger(node, 'maxAttempts', true);
       if (node.tag === 'Timeout') {
@@ -310,7 +392,20 @@ function loadCtrlFlowSources(
           note('invalid-timeout', `<Timeout #${id ?? ''}>.timeoutMs must be a non-negative number`);
         }
       }
-      if (node.tag === 'ForEach') requirePositiveInteger(node, 'concurrency');
+      if (node.tag === 'Until') {
+        requirePositiveInteger(node, 'maxIterations');
+        if (node.attributes?.onExhausted !== undefined && !['fail', 'complete'].includes(String(node.attributes.onExhausted))) {
+          note('invalid-on-exhausted', `<Until #${id ?? ''}>.onExhausted must be fail or complete`);
+        }
+      }
+      if (node.tag === 'ForEach') {
+        requirePositiveInteger(node, 'concurrency');
+        requirePositiveInteger(node, 'maxItems');
+        const maxItems = node.attributes?.maxItems;
+        if (maxItems !== undefined && (typeof maxItems !== 'number' || maxItems > 1000)) note('invalid-max-items', `<ForEach #${id ?? ''}>.maxItems must be 1..1000`);
+        const concurrency = node.attributes?.concurrency;
+        if (concurrency !== undefined && typeof concurrency === 'number' && concurrency > Math.min(32, typeof maxItems === 'number' ? maxItems : 1000)) note('invalid-concurrency', `<ForEach #${id ?? ''}>.concurrency exceeds its bounded capacity`);
+      }
       if (node.tag === 'CallFlow') {
         const target = node.attributes?.flow;
         if (typeof target !== 'string' || !/^(?:instant-ctrl-flow|work-ctrl-flow|bp-ctrl-flow):\/\/[\w.-]+$/.test(target)) {
@@ -376,6 +471,25 @@ function loadCtrlFlowSources(
     }
   };
   validateBody(statementEls);
+  const refs = (nodes: XnlEl[], result = new Set<string>()): Set<string> => {
+    for (const n of nodes) {
+      if (n.tag === 'RunBlock' && typeof n.attributes?.block === 'string') result.add(n.attributes.block.slice(9));
+      refs(listChildren(n), result); refs(sectionChildren(n), result);
+    }
+    return result;
+  };
+  for (const block of blockEls) {
+    validateBody(listChildren(block));
+    blockRefs.set(idOf(block) ?? '', refs(listChildren(block)));
+  }
+  const visited = new Set<string>(), active = new Set<string>();
+  const checkBlock = (id: string): void => {
+    if (active.has(id)) { note('recursive-block', `block reference cycle at #${id}`); return; }
+    if (visited.has(id)) return;
+    active.add(id); for (const target of blockRefs.get(id) ?? []) checkBlock(target);
+    active.delete(id); visited.add(id);
+  };
+  for (const id of blockIds) checkBlock(id);
 
   for (const name of Object.keys(facets) as FacetName[]) {
     if (!ALLOWED_FACETS[form].has(name)) {
@@ -428,16 +542,19 @@ function loadCtrlFlowSources(
     : undefined;
   const stateSeed = facets['state.seed'] ? { ...(facets['state.seed'].attributes ?? {}) } : undefined;
   const taskSpace = facets['task.space'] ? toNodeSpec(facets['task.space']) : undefined;
+  const rootIdentity = projectFlowRootIdentity(container.metadata ?? {});
+  if (rootIdentity.diagnostic) note(rootIdentity.diagnostic.code, rootIdentity.diagnostic.message);
   const spec: FlowBundleSpec = {
     form,
     fqn,
-    apiVersion: String(container.metadata?.apiVersion ?? ''),
-    version: String(container.metadata?.version ?? ''),
+    apiVersion: rootIdentity.apiVersion,
+    version: rootIdentity.version,
     title: container.attributes?.title as string | undefined,
     sourceNames,
     baseUri: options.baseUri,
     dir: options.baseUri ?? '',
     statements: statementEls.map(toNodeSpec),
+    blocks: Object.fromEntries(blockEls.filter(b => idOf(b)).map(b => [idOf(b)!, listChildren(b).map(toNodeSpec)])),
     ...(definitionStepForest ? { definitionStepForest } : {}),
     flowContract,
     config,
@@ -447,7 +564,6 @@ function loadCtrlFlowSources(
     taskSpace,
     diagnostics,
   };
-  if (!spec.apiVersion) note('container-missing-meta', 'container missing metadata "apiVersion"');
   if (!fqn.includes('.')) note('container-id-not-fqn', `container #id must be a dotted FQN, got "${fqn}"`);
   return { spec, diagnostics };
 }