instant-ctrl-flow-logic 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "instant-ctrl-flow-logic",
+  "version": "0.1.0",
+  "private": false,
+  "description": "InstantCtrlFlow 引擎：xnl bundle 加载 → 行为树编译 → 无状态单次执行",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./browser": "./src/browser.ts",
+    "./filesystem": "./src/filesystem.ts"
+  },
+  "dependencies": {
+    "xnl-core": "^0.1.8",
+    "depa-behavior-tree": "0.1.0",
+    "instant-ctrl-flow-contract": "0.1.0"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,4 @@
+export * from './loader.js';
+export * from './compile.js';
+export * from './handlers.js';
+export * from './engine.js';

package/src/compile.ts

@@ -0,0 +1,232 @@
+import {
+  BehaviorTreeNodeKind,
+  CtrlFlowDsl,
+  type BehaviorTreeNode,
+  type CtrlFlowNodeType,
+  type INodeConfig,
+} from 'depa-behavior-tree';
+import type { FlowBundleSpec, FlowNodeSpec } from 'instant-ctrl-flow-contract';
+
+export type CtrlNode = BehaviorTreeNode<CtrlFlowNodeType, INodeConfig>;
+
+const INTERRUPTIBLE = new Set(['ExternalJob', 'Timer', 'TaskStep']);
+const VIEW_ATTRS = new Set(['status', 'iterations', 'runStatus', 'tickNo']);
+
+export class FlowCompileError extends Error {
+  constructor(public code: string, message: string) {
+    super(`[${code}] ${message}`);
+  }
+}
+
+function resolveConfigValue(spec: FlowBundleSpec, value: unknown, where: string): unknown {
+  if (typeof value === 'string' && value.startsWith('config://#')) {
+    const [id, ...subpath] = value.slice('config://#'.length).split('/');
+    let current: unknown = spec.config[id];
+    if (current === undefined) throw new FlowCompileError('unresolved-config-ref', `${where}: ${value}`);
+    for (const key of subpath) {
+      if (!current || typeof current !== 'object' || !(key in current)) {
+        throw new FlowCompileError('unresolved-config-subpath', `${where}: ${value}`);
+      }
+      current = (current as Record<string, unknown>)[key];
+    }
+    return current;
+  }
+  if (Array.isArray(value)) return value.map((item) => resolveConfigValue(spec, item, where));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, resolveConfigValue(spec, item, where)]),
+    );
+  }
+  return value;
+}
+
+function resolvedAttrs(spec: FlowBundleSpec, node: FlowNodeSpec): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(node.attrs)
+      .filter(([key]) => !VIEW_ATTRS.has(key))
+      .map(([key, value]) => [key, resolveConfigValue(spec, value, `node #${node.id ?? node.tag}`)]),
+  );
+}
+
+function statementConfig(attrs: Record<string, unknown>): Readonly<Record<string, unknown>> {
+  const config = attrs.config;
+  return Object.freeze(config && typeof config === 'object' && !Array.isArray(config) ? { ...config } : {});
+}
+
+const action = (type: string, key: string, config: Record<string, unknown> = {}): CtrlNode =>
+  CtrlFlowDsl.node(type as CtrlFlowNodeType, { key }, config as INodeConfig);
+
+const sequence = (key: string, children: CtrlNode[]): CtrlNode =>
+  CtrlFlowDsl.node('Sequence' as CtrlFlowNodeType, { key }, {}, children);
+
+const selector = (key: string, children: CtrlNode[]): CtrlNode =>
+  CtrlFlowDsl.node('Selector' as CtrlFlowNodeType, { key }, {}, children);
+
+export interface CompileHelpers {
+  meta: { key: string; name?: string };
+  attrs: Record<string, unknown>;
+  compileStatements(nodes: FlowNodeSpec[], key: string): CtrlNode;
+}
+
+export type CompileExtension = (
+  spec: FlowBundleSpec,
+  node: FlowNodeSpec,
+  helpers: CompileHelpers,
+) => CtrlNode | null;
+
+function compileStatement(
+  spec: FlowBundleSpec,
+  node: FlowNodeSpec,
+  extension: CompileExtension | undefined,
+  path: string,
+): CtrlNode {
+  const key = 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}`)));
+  const helpers: CompileHelpers = { meta: { key, name: node.id }, attrs, compileStatements };
+
+  const extended = extension?.(spec, node, helpers);
+  if (extended) return extended;
+
+  if (INTERRUPTIBLE.has(node.tag)) {
+    throw new FlowCompileError('interruptible-in-instant-ctrl-flow', `<${node.tag} #${node.id}> illegal in InstantCtrlFlow`);
+  }
+
+  switch (node.tag) {
+    case 'Run':
+      return action('flow.Run', key, { src: String(attrs.src ?? ''), config: statementConfig(attrs) });
+    case 'Return':
+      return action('flow.Return', key, {
+        src: attrs.src === undefined ? undefined : String(attrs.src),
+        hasValue: Object.prototype.hasOwnProperty.call(attrs, 'value'),
+        value: attrs.value,
+        config: statementConfig(attrs),
+      });
+    case 'If': {
+      const ifPath = key;
+      const branches = node.sections.Branches?.children ?? [];
+      const choices = branches.map((branch, index) => {
+        const branchKey = branch.id ?? `${key}.branch.${index}`;
+        if (branch.tag === 'Otherwise') {
+          return sequence(`${branchKey}.__choice`, [
+            action('flow.Otherwise', `${branchKey}.__otherwise`, {
+              ifPath,
+              branchKey,
+              decisionKind: 'Otherwise',
+            }),
+            compileStatements(branch.children, `${branchKey}.__body`),
+          ]);
+        }
+        if (branch.tag !== 'Branch') {
+          throw new FlowCompileError('invalid-if-branch', `<If #${key}> contains <${branch.tag}>`);
+        }
+        const branchAttrs = resolvedAttrs(spec, branch);
+        return sequence(`${branchKey}.__choice`, [
+          action('flow.Predicate', `${branchKey}.__predicate`, {
+            ifPath,
+            branchKey,
+            src: String(branchAttrs.when ?? ''),
+            config: statementConfig(branchAttrs),
+          }),
+          compileStatements(branch.children, `${branchKey}.__body`),
+        ]);
+      });
+      if (!branches.some((branch) => branch.tag === 'Otherwise')) {
+        choices.push(action('flow.Otherwise', `${key}.__no_match`, { ifPath, decisionKind: 'NoMatch' }));
+      }
+      return sequence(key, [
+        action('flow.IfStart', `${key}.__start`, { ifPath }),
+        selector(`${key}.__branches`, choices),
+      ]);
+    }
+    case 'Fallback': {
+      const strategies = node.children.map((strategy, index) => {
+        if (strategy.tag !== 'Strategy') {
+          throw new FlowCompileError('invalid-fallback-strategy', `<Fallback #${key}> contains <${strategy.tag}>`);
+        }
+        const strategyKey = strategy.id ?? `${key}.strategy.${index}`;
+        return sequence(`${strategyKey}.__strategy`, [
+          action('flow.StrategyStart', `${strategyKey}.__start`, { fallbackKey: key }),
+          compileStatements(strategy.children, `${strategyKey}.__body`),
+        ]);
+      });
+      if (!strategies.length) throw new FlowCompileError('empty-fallback', `<Fallback #${key}> has no Strategy`);
+      return sequence(key, [
+        action('flow.FallbackStart', `${key}.__start`, { fallbackKey: key }),
+        selector(`${key}.__strategies`, strategies),
+      ]);
+    }
+    case 'Until': {
+      const predicateKey = `${key}.__predicate_value`;
+      const predicateConfig = {
+        predicateKey,
+        src: String(attrs.when ?? ''),
+        config: statementConfig(attrs),
+        maxIterations: Number(attrs.maxIterations ?? 9999),
+      };
+      const initial = action('flow.UntilPredicate', `${key}.__check.initial`, { ...predicateConfig, countIteration: false });
+      const repeated = action('flow.UntilPredicate', `${key}.__check.repeat`, { ...predicateConfig, countIteration: true });
+      const body = sequence(`${key}.__body`, [compileStatements(node.children, `${key}.__statements`), repeated]);
+      const until = CtrlFlowDsl.node(
+        'Until' as CtrlFlowNodeType,
+        { key: `${key}.__until` },
+        { expression: `getVar("__flow_execution__").untilValues[${JSON.stringify(predicateKey)}] === true` },
+        [body],
+      );
+      return sequence(key, [initial, until]);
+    }
+    case 'Require':
+      return action('flow.Require', key, {
+        src: String(attrs.when ?? ''),
+        config: statementConfig(attrs),
+      });
+    case 'Retry':
+    case 'Timeout':
+      return action(`flow.${node.tag}`, key, {
+        ...attrs,
+        config: statementConfig(attrs),
+        statements: node.children,
+      });
+    case 'ForEach':
+      return action('flow.ForEach', key, {
+        ...attrs,
+        src: String(attrs.when ?? ''),
+        config: statementConfig(attrs),
+        statements: node.children,
+      });
+    case 'Parallel': {
+      const lanes = node.sections.Lanes?.children ?? [];
+      return action('flow.Parallel', key, {
+        ...attrs,
+        items: lanes.map((lane) => ({ id: lane.id, statements: lane.children })),
+      });
+    }
+    case 'Race': {
+      const candidates = node.sections.Candidates?.children ?? [];
+      return action('flow.Race', key, {
+        ...attrs,
+        items: candidates.map((candidate) => ({ id: candidate.id, statements: candidate.children })),
+      });
+    }
+    case 'CallFlow':
+      return action('flow.CallFlow', key, {
+        flow: String(attrs.flow ?? ''),
+        config: statementConfig(attrs),
+      });
+    default:
+      throw new FlowCompileError('unknown-node-tag', `unknown statement tag <${node.tag}>`);
+  }
+}
+
+export function compileNode(spec: FlowBundleSpec, node: FlowNodeSpec, extension?: CompileExtension): CtrlNode {
+  return compileStatement(spec, node, extension, node.id ?? node.tag);
+}
+
+export function compileBundle(spec: FlowBundleSpec, extension?: CompileExtension): CtrlNode {
+  const root = sequence('__statements__', spec.statements.map((node, index) =>
+    compileStatement(spec, node, extension, `statement.${index}`),
+  ));
+  root.Kind = BehaviorTreeNodeKind.Sequence;
+  return root;
+}

package/src/engine.ts

@@ -0,0 +1,171 @@
+import {
+  ActionHandlerRegistry,
+  BehaviorTreeEngine,
+  BehaviorTreeNodeStatus,
+  evaluateExpression,
+  type BehaviorTreeData,
+  type CtrlFlowNodeType,
+  type INodeConfig,
+} from 'depa-behavior-tree';
+import type {
+  FlowBundleSpec,
+  FlowCodeResolver,
+  CtrlFlowResolver,
+  FlowNodeSpec,
+  FlowSourceCollection,
+  InstantCtrlFlowRunOptions,
+  LoadFlowSourcesOptions,
+} from 'instant-ctrl-flow-contract';
+import { compileBundle, FlowCompileError } from './compile.js';
+import { loadFlowBundleFromSources } from './loader.js';
+import {
+  createFlowExecutionState,
+  createFlowHandlers,
+  FLOW_STATE_KEY,
+} from './handlers.js';
+
+export class FlowLoadError extends Error {
+  constructor(public codes: string[], message: string) {
+    super(message);
+  }
+}
+
+export class FlowExecutionError extends Error {
+  constructor(message: string, public cause?: unknown) {
+    super(message);
+  }
+}
+
+function requireInstantCtrlFlowSpec(spec: FlowBundleSpec | undefined, diagnostics: readonly { code: string; message: string }[]): FlowBundleSpec {
+  const hard = diagnostics.filter((diagnostic) => diagnostic.code !== 'parser-warning');
+  if (!spec || hard.length) {
+    throw new FlowLoadError(
+      diagnostics.map((diagnostic) => diagnostic.code),
+      `failed to load flow: ${diagnostics.map((diagnostic) => `[${diagnostic.code}] ${diagnostic.message}`).join('; ')}`,
+    );
+  }
+  if (spec.form !== 'InstantCtrlFlow') {
+    throw new FlowLoadError(['form-mismatch'], `bundle ${spec.fqn} is a ${spec.form}, not an InstantCtrlFlow`);
+  }
+  return spec;
+}
+
+export function loadInstantCtrlFlowSources(
+  sources: FlowSourceCollection,
+  options: LoadFlowSourcesOptions = {},
+): FlowBundleSpec {
+  const result = loadFlowBundleFromSources(sources, options);
+  return requireInstantCtrlFlowSpec(result.spec, result.diagnostics);
+}
+
+export interface RunInstantCtrlFlowSpecOptions extends InstantCtrlFlowRunOptions {
+  resolveCode: FlowCodeResolver;
+  resolveFlow?: CtrlFlowResolver;
+}
+
+export interface MaterializedInstantCtrlFlow<Output = unknown> {
+  readonly spec: FlowBundleSpec;
+  run(options?: InstantCtrlFlowRunOptions): Promise<Output>;
+}
+
+export function materializeInstantCtrlFlowSpec<Output = unknown>(
+  spec: FlowBundleSpec,
+  resolveCode: FlowCodeResolver,
+  resolveFlow?: CtrlFlowResolver,
+): MaterializedInstantCtrlFlow<Output> {
+  requireInstantCtrlFlowSpec(spec, spec.diagnostics);
+  return {
+    spec,
+    run: (options = {}) => runInstantCtrlFlowSpec<Output>(spec, { ...options, resolveCode, resolveFlow }),
+  };
+}
+
+export function materializeInstantCtrlFlowSources<Output = unknown>(
+  sources: FlowSourceCollection,
+  options: LoadFlowSourcesOptions & { resolveCode: FlowCodeResolver; resolveFlow?: CtrlFlowResolver },
+): MaterializedInstantCtrlFlow<Output> {
+  return materializeInstantCtrlFlowSpec(loadInstantCtrlFlowSources(sources, options), options.resolveCode, options.resolveFlow);
+}
+
+export async function runInstantCtrlFlowSpec<Output = unknown>(
+  spec: FlowBundleSpec,
+  options: RunInstantCtrlFlowSpecOptions,
+): Promise<Output> {
+  requireInstantCtrlFlowSpec(spec, spec.diagnostics);
+  return runStatements<Output>(spec, spec.statements, options);
+}
+
+async function runStatements<Output>(
+  spec: FlowBundleSpec,
+  statements: FlowNodeSpec[],
+  options: RunInstantCtrlFlowSpecOptions & { signal?: AbortSignal },
+): Promise<Output> {
+  if (options.signal?.aborted) throw new FlowExecutionError(`InstantCtrlFlow ${spec.fqn} was cancelled`);
+  const executionSpec = statements === spec.statements ? spec : { ...spec, statements };
+  const tree = compileBundle(executionSpec);
+  const state = createFlowExecutionState(options.input ?? {});
+  const registry = new ActionHandlerRegistry<CtrlFlowNodeType, INodeConfig>();
+  const runtimeWithSignal = (runtime: Record<string, unknown>, signal?: AbortSignal) => {
+    if (!signal) return runtime;
+    const overlay = Object.create(runtime) as Record<string, unknown>;
+    overlay.abortSignal = signal;
+    return overlay;
+  };
+  const executeBody = (body: FlowNodeSpec[], input: unknown, runtime: Record<string, unknown>, signal?: AbortSignal) =>
+    runStatements(executionSpec, body, { ...options, input, runtime: runtimeWithSignal(runtime, signal), signal });
+  const executeTarget = async (reference: string, input: unknown, runtime: Record<string, unknown>, signal?: AbortSignal) => {
+    if (!options.resolveFlow) throw new FlowExecutionError(`CallFlow ${reference} requires resolveFlow`);
+    const target = await options.resolveFlow(reference, spec);
+    const match = /^([a-z-]+):\/\/([\w.-]+)$/.exec(reference);
+    const expectedScheme = target.spec.form === 'InstantCtrlFlow'
+      ? 'instant-ctrl-flow'
+      : target.spec.form === 'WorkCtrlFlow'
+        ? 'work-ctrl-flow'
+        : 'bp-ctrl-flow';
+    if (!match || match[1] !== expectedScheme || match[2] !== target.spec.fqn) {
+      throw new FlowExecutionError(`CallFlow resolver returned ${target.spec.form} #${target.spec.fqn} for ${reference}`);
+    }
+    if (target.spec.form !== 'InstantCtrlFlow') {
+      throw new FlowExecutionError(`InstantCtrlFlow cannot call suspendable ${target.spec.form} target ${reference}`);
+    }
+    return runStatements(target.spec, target.spec.statements, {
+      ...options,
+      input,
+      runtime: runtimeWithSignal(runtime, signal),
+      signal,
+      resolveCode: target.resolveCode,
+    });
+  };
+  for (const [type, handler] of Object.entries(
+    createFlowHandlers(executionSpec, options.resolveCode, undefined, executeBody, executeTarget),
+  )) {
+    registry.register(type as CtrlFlowNodeType, handler);
+  }
+  const data: BehaviorTreeData<CtrlFlowNodeType, INodeConfig> = {
+    NodeTree: tree,
+    Vars: new Map([[FLOW_STATE_KEY, state]]),
+    CmdStack: [],
+    CmdHistory: [],
+    NodeMap: new Map(),
+  };
+  const engine = new BehaviorTreeEngine(registry, evaluateExpression);
+  await engine.start(data, options.runtime ?? {});
+  while (!engine.isComplete(data)) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await engine.runPendingCommands(data, options.runtime ?? {});
+  }
+  if (options.signal?.aborted) throw new FlowExecutionError(`InstantCtrlFlow ${spec.fqn} was cancelled`);
+  if (data.NodeTree.Status !== BehaviorTreeNodeStatus.Success || state.fault) {
+    throw new FlowExecutionError(`InstantCtrlFlow ${spec.fqn} failed`, state.fault);
+  }
+  return (state.returned ? state.output : state.current) as Output;
+}
+
+export async function runInstantCtrlFlowSources<Output = unknown>(
+  sources: FlowSourceCollection,
+  options: RunInstantCtrlFlowSpecOptions & LoadFlowSourcesOptions,
+): Promise<Output> {
+  return runInstantCtrlFlowSpec<Output>(loadInstantCtrlFlowSources(sources, options), options);
+}
+
+export { FlowCompileError };

package/src/filesystem.ts

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { FlowCodeFunction, FlowCodeResolver, LoadFlowSourcesOptions } from 'instant-ctrl-flow-contract';
+import { loadFlowBundleFromSources, type LoadResult } from './loader.js';
+import { FlowLoadError, runInstantCtrlFlowSpec } from './engine.js';
+import type { InstantCtrlFlowRunOptions } from 'instant-ctrl-flow-contract';
+
+/** Filesystem convenience only; parsing and validation belong to the named-source loader. */
+export function loadFlowBundle(dir: string, options: LoadFlowSourcesOptions = {}): LoadResult {
+  const absoluteDir = path.resolve(dir);
+  const sources = fs.existsSync(absoluteDir)
+    ? fs.readdirSync(absoluteDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.xnl'))
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((entry) => ({
+          name: entry.name,
+          content: fs.readFileSync(path.join(absoluteDir, entry.name), 'utf8'),
+        }))
+    : [];
+  return loadFlowBundleFromSources(sources, { ...options, baseUri: options.baseUri ?? absoluteDir });
+}
+
+export type FlowModuleImporter = (specifier: string) => Promise<Readonly<Record<string, unknown>>>;
+
+export function createFilesystemFlowCodeResolver<Runtime = unknown>(
+  importModule: FlowModuleImporter = (specifier) => import(specifier),
+): FlowCodeResolver<Runtime> {
+  const modules = new Map<string, Promise<Readonly<Record<string, unknown>>>>();
+  return async ({ reference, baseUri, flowId, nodeId }) => {
+    const match = /^vfs:\/\/\.\/(.+)#([A-Za-z_$][A-Za-z0-9_$]*)$/.exec(reference);
+    if (!match) throw new Error(`unsupported filesystem VFS reference: ${reference}`);
+    if (!baseUri) throw new Error(`${flowId}#${nodeId} has no baseUri for ${reference}`);
+    const root = path.resolve(baseUri);
+    const file = path.resolve(root, match[1]);
+    const relative = path.relative(root, file);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${reference} escapes Flow baseUri`);
+    const specifier = pathToFileURL(file).href;
+    let loaded = modules.get(specifier);
+    if (!loaded) {
+      loaded = importModule(specifier);
+      modules.set(specifier, loaded);
+    }
+    const resolved = (await loaded)[match[2]];
+    if (typeof resolved !== 'function') throw new Error(`${reference} does not identify a function export`);
+    return resolved as FlowCodeFunction<unknown, Runtime>;
+  };
+}
+
+export function loadInstantCtrlFlowSpec(bundleDir: string) {
+  const result = loadFlowBundle(bundleDir);
+  const hard = result.diagnostics.filter((diagnostic) => diagnostic.code !== 'parser-warning');
+  if (!result.spec || hard.length) {
+    throw new FlowLoadError(
+      result.diagnostics.map((item) => item.code),
+      `failed to load InstantCtrlFlow ${bundleDir}: ${result.diagnostics.map((item) => `[${item.code}] ${item.message}`).join('; ')}`,
+    );
+  }
+  if (result.spec.form !== 'InstantCtrlFlow') {
+    throw new FlowLoadError(['form-mismatch'], `bundle ${result.spec.fqn} is a ${result.spec.form}, not an InstantCtrlFlow`);
+  }
+  return result.spec;
+}
+
+export async function runInstantCtrlFlow<Output = unknown>(
+  bundleDir: string,
+  options: InstantCtrlFlowRunOptions = {},
+): Promise<Output> {
+  return runInstantCtrlFlowSpec<Output>(loadInstantCtrlFlowSpec(bundleDir), {
+    ...options,
+    resolveCode: createFilesystemFlowCodeResolver(),
+  });
+}

package/src/handlers.ts

@@ -0,0 +1,464 @@
+import {
+  BehaviorResult,
+  type ActionHandler,
+  type CtrlFlowNodeType,
+  type ExecutionContext,
+  type INodeConfig,
+} from 'depa-behavior-tree';
+import type {
+  FlowBundleSpec,
+  FlowCodeFunction,
+  FlowCodeResolver,
+  FlowNodeSpec,
+  InstantCtrlFlowRuntime,
+} from 'instant-ctrl-flow-contract';
+
+type Ctx = ExecutionContext<CtrlFlowNodeType, INodeConfig>;
+
+export const FLOW_STATE_KEY = '__flow_execution__';
+
+export interface FlowExecutionState {
+  current: unknown;
+  returned: boolean;
+  output?: unknown;
+  fault?: unknown;
+  selections: Record<string, string>;
+  fallbackInputs: Record<string, unknown>;
+  untilIterations: Record<string, number>;
+  untilValues: Record<string, boolean>;
+}
+
+export const createFlowExecutionState = (input: unknown): FlowExecutionState => ({
+  current: input,
+  returned: false,
+  selections: {},
+  fallbackInputs: {},
+  untilIterations: {},
+  untilValues: {},
+});
+
+export const flowStateOf = (ctx: Ctx): FlowExecutionState => ctx.getVar(FLOW_STATE_KEY) as FlowExecutionState;
+
+type NodeConfig = {
+  src?: string;
+  config?: Readonly<Record<string, unknown>>;
+  hasValue?: boolean;
+  value?: unknown;
+  ifPath?: string;
+  branchKey?: string;
+  decisionKind?: FlowBranchDecisionKind;
+  fallbackKey?: string;
+  predicateKey?: string;
+  countIteration?: boolean;
+  maxIterations?: number;
+  statements?: FlowNodeSpec[];
+  items?: { id?: string; statements: FlowNodeSpec[] }[];
+  flow?: string;
+  maxAttempts?: number;
+  timeoutMs?: number;
+  concurrency?: number;
+  mode?: string;
+};
+
+export type FlowBodyExecutor = (
+  statements: FlowNodeSpec[],
+  input: unknown,
+  runtime: InstantCtrlFlowRuntime,
+  signal?: AbortSignal,
+) => Promise<unknown>;
+
+export type FlowTargetExecutor = (
+  reference: string,
+  input: unknown,
+  runtime: InstantCtrlFlowRuntime,
+  signal?: AbortSignal,
+) => Promise<unknown>;
+
+export type FlowBranchDecisionKind = 'Branch' | 'Otherwise' | 'NoMatch';
+
+export interface FlowBranchDecision {
+  ifPath: string;
+  invocationKey: string;
+  kind: FlowBranchDecisionKind;
+  branchKey?: string;
+}
+
+export interface FlowDecisionContext {
+  ifPath: string;
+  invocationKey: string;
+  decision?: FlowBranchDecision;
+}
+
+/** Optional persistence boundary used by replaying profiles; InstantCtrlFlow leaves it undefined. */
+export interface FlowDecisionHooks {
+  begin(ifPath: string): FlowDecisionContext;
+  record(decision: FlowBranchDecision): Promise<void> | void;
+}
+
+class FlowFunctionLoader {
+  private cache = new Map<string, Promise<FlowCodeFunction>>();
+  constructor(
+    private spec: FlowBundleSpec,
+    private resolveCode: FlowCodeResolver,
+  ) {}
+
+  load(src: string, nodeId: string): Promise<FlowCodeFunction> {
+    let loaded = this.cache.get(src);
+    if (!loaded) {
+      loaded = (async () => {
+        const fn = await this.resolveCode({
+          reference: src,
+          flowId: this.spec.fqn,
+          nodeId,
+          baseUri: this.spec.baseUri,
+        });
+        if (typeof fn !== 'function') throw new Error(`vfs src "${src}" does not export a function`);
+        return fn;
+      })();
+      this.cache.set(src, loaded);
+    }
+    return loaded;
+  }
+}
+
+function configOf(ctx: Ctx): NodeConfig {
+  return ctx.node.Config as NodeConfig;
+}
+
+async function callCode(ctx: Ctx, loader: FlowFunctionLoader, src: string): Promise<unknown> {
+  const state = flowStateOf(ctx);
+  const fn = await loader.load(src, ctx.node.Key);
+  return fn((ctx.runtime ?? {}) as InstantCtrlFlowRuntime, state.current, configOf(ctx).config ?? {});
+}
+
+function fail(state: FlowExecutionState, error: unknown): BehaviorResult {
+  state.fault = error;
+  return BehaviorResult.Failure;
+}
+
+class RunHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(private loader: FlowFunctionLoader) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    if (state.fault) return BehaviorResult.Failure;
+    try {
+      state.current = await callCode(ctx, this.loader, String(configOf(ctx).src ?? ''));
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+class ReturnHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(private loader: FlowFunctionLoader) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    if (state.fault) return BehaviorResult.Failure;
+    const config = configOf(ctx);
+    try {
+      const output = config.src
+        ? await callCode(ctx, this.loader, config.src)
+        : config.hasValue
+          ? config.value
+          : state.current;
+      state.current = output;
+      state.output = output;
+      state.returned = true;
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+class IfStartHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(
+    private decisionHooks: FlowDecisionHooks | undefined,
+    private activeDecisions: Map<string, FlowDecisionContext>,
+  ) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    if (state.fault) return BehaviorResult.Failure;
+    const ifPath = String(configOf(ctx).ifPath);
+    delete state.selections[ifPath];
+    if (this.decisionHooks) this.activeDecisions.set(ifPath, this.decisionHooks.begin(ifPath));
+    return BehaviorResult.Success;
+  }
+}
+
+class PredicateHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(
+    private loader: FlowFunctionLoader,
+    private decisionHooks: FlowDecisionHooks | undefined,
+    private activeDecisions: Map<string, FlowDecisionContext>,
+  ) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    if (state.fault) return BehaviorResult.Failure;
+    const config = configOf(ctx);
+    const ifPath = String(config.ifPath);
+    const branchKey = String(config.branchKey);
+    const decisionContext = this.activeDecisions.get(ifPath);
+    if (decisionContext?.decision) {
+      return decisionContext.decision.kind === 'Branch' && decisionContext.decision.branchKey === branchKey
+        ? BehaviorResult.Success
+        : BehaviorResult.Failure;
+    }
+    if (state.selections[ifPath]) return BehaviorResult.Failure;
+    try {
+      const result = await callCode(ctx, this.loader, String(config.src ?? ''));
+      if (typeof result !== 'boolean') throw new TypeError(`predicate ${config.src} must return boolean`);
+      if (!result) return BehaviorResult.Failure;
+      if (this.decisionHooks && decisionContext) {
+        const decision: FlowBranchDecision = {
+          ifPath,
+          invocationKey: decisionContext.invocationKey,
+          kind: 'Branch',
+          branchKey,
+        };
+        await this.decisionHooks.record(decision);
+        decisionContext.decision = decision;
+      }
+      state.selections[ifPath] = branchKey;
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+class OtherwiseHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(
+    private decisionHooks: FlowDecisionHooks | undefined,
+    private activeDecisions: Map<string, FlowDecisionContext>,
+  ) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    const config = configOf(ctx);
+    const ifPath = String(config.ifPath);
+    const kind = config.decisionKind ?? 'Otherwise';
+    const branchKey = config.branchKey;
+    const decisionContext = this.activeDecisions.get(ifPath);
+    if (state.fault) return BehaviorResult.Failure;
+    if (decisionContext?.decision) {
+      const selected = decisionContext.decision;
+      return selected.kind === kind && selected.branchKey === branchKey
+        ? BehaviorResult.Success
+        : BehaviorResult.Failure;
+    }
+    if (state.selections[ifPath]) return BehaviorResult.Failure;
+    if (this.decisionHooks && decisionContext) {
+      try {
+        const decision: FlowBranchDecision = {
+          ifPath,
+          invocationKey: decisionContext.invocationKey,
+          kind,
+          ...(branchKey === undefined ? {} : { branchKey }),
+        };
+        await this.decisionHooks.record(decision);
+        decisionContext.decision = decision;
+      } catch (error) {
+        return fail(state, error);
+      }
+    }
+    return BehaviorResult.Success;
+  }
+}
+
+class StrategyStartHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    const key = String(configOf(ctx).fallbackKey);
+    state.current = state.fallbackInputs[key];
+    state.fault = undefined;
+    return BehaviorResult.Success;
+  }
+}
+
+class FallbackStartHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    if (state.returned) return BehaviorResult.Success;
+    const key = String(configOf(ctx).fallbackKey);
+    state.fallbackInputs[key] = state.current;
+    state.fault = undefined;
+    return BehaviorResult.Success;
+  }
+}
+
+class UntilPredicateHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(private loader: FlowFunctionLoader) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    const config = configOf(ctx);
+    const key = String(config.predicateKey);
+    if (state.returned) {
+      state.untilValues[key] = true;
+      return BehaviorResult.Success;
+    }
+    if (state.fault) return BehaviorResult.Failure;
+    try {
+      const result = await callCode(ctx, this.loader, String(config.src ?? ''));
+      if (typeof result !== 'boolean') throw new TypeError(`predicate ${config.src} must return boolean`);
+      if (config.countIteration) {
+        const iterations = (state.untilIterations[key] ?? 0) + 1;
+        state.untilIterations[key] = iterations;
+        if (!result && iterations >= Number(config.maxIterations ?? 9999)) {
+          return fail(state, new Error(`Until node exceeded max iterations (${config.maxIterations})`));
+        }
+      }
+      state.untilValues[key] = result;
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+class RequireHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(private loader: FlowFunctionLoader) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    try {
+      const result = await callCode(ctx, this.loader, String(configOf(ctx).src ?? ''));
+      if (typeof result !== 'boolean') throw new TypeError('Require predicate must return boolean');
+      if (!result) throw new Error(`precondition failed at #${ctx.node.Key}`);
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+class CompositeHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(
+    private kind: 'Retry' | 'Timeout' | 'ForEach' | 'Parallel' | 'Race',
+    private loader: FlowFunctionLoader,
+    private executeBody: FlowBodyExecutor,
+  ) {}
+
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    const config = configOf(ctx);
+    const runtime = (ctx.runtime ?? {}) as InstantCtrlFlowRuntime;
+    try {
+      if (this.kind === 'Retry') {
+        const attempts = Math.max(1, Number(config.maxAttempts ?? 1));
+        let lastError: unknown;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+          try {
+            state.current = await this.executeBody(config.statements ?? [], state.current, runtime);
+            return BehaviorResult.Success;
+          } catch (error) {
+            lastError = error;
+          }
+        }
+        throw lastError;
+      }
+      if (this.kind === 'Timeout') {
+        const controller = new AbortController();
+        const timeoutMs = Math.max(0, Number(config.timeoutMs ?? 0));
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          state.current = await Promise.race([
+            this.executeBody(config.statements ?? [], state.current, runtime, controller.signal),
+            new Promise<never>((_, reject) => {
+              timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error(`Timeout #${ctx.node.Key} exceeded ${timeoutMs}ms`));
+              }, timeoutMs);
+            }),
+          ]);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+        return BehaviorResult.Success;
+      }
+      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');
+        const outputs: unknown[] = [];
+        for (const item of selected) outputs.push(await this.executeBody(config.statements ?? [], item, runtime));
+        state.current = outputs;
+        return BehaviorResult.Success;
+      }
+
+      const items = config.items ?? [];
+      const controllers = items.map(() => new AbortController());
+      const executions = items.map((item, index) =>
+        this.executeBody(item.statements, state.current, runtime, controllers[index].signal)
+          .then((value) => ({ id: item.id ?? String(index), value })),
+      );
+      if (this.kind === 'Parallel') {
+        const values = await Promise.all(executions);
+        state.current = Object.fromEntries(values.map(({ id, value }) => [id, value]));
+        return BehaviorResult.Success;
+      }
+
+      const mode = config.mode ?? 'first-success';
+      const winner = mode === 'first-completed'
+        ? await Promise.race(executions)
+        : await Promise.any(executions);
+      controllers.forEach((controller) => controller.abort());
+      state.current = { winner: winner.id, output: winner.value };
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+class CallFlowHandler implements ActionHandler<CtrlFlowNodeType, INodeConfig> {
+  constructor(private executeTarget?: FlowTargetExecutor) {}
+  async execute(ctx: Ctx): Promise<BehaviorResult> {
+    const state = flowStateOf(ctx);
+    try {
+      if (!this.executeTarget) throw new Error('CallFlow requires a CtrlFlow resolver');
+      state.current = await this.executeTarget(
+        String(configOf(ctx).flow ?? ''),
+        state.current,
+        (ctx.runtime ?? {}) as InstantCtrlFlowRuntime,
+      );
+      return BehaviorResult.Success;
+    } catch (error) {
+      return fail(state, error);
+    }
+  }
+}
+
+export function createFlowHandlers(
+  spec: FlowBundleSpec,
+  resolveCode: FlowCodeResolver,
+  decisionHooks?: FlowDecisionHooks,
+  executeBody?: FlowBodyExecutor,
+  executeTarget?: FlowTargetExecutor,
+): Record<string, ActionHandler<CtrlFlowNodeType, INodeConfig>> {
+  const loader = new FlowFunctionLoader(spec, resolveCode);
+  const activeDecisions = new Map<string, FlowDecisionContext>();
+  return {
+    'flow.Run': new RunHandler(loader),
+    'flow.Return': new ReturnHandler(loader),
+    'flow.IfStart': new IfStartHandler(decisionHooks, activeDecisions),
+    'flow.Predicate': new PredicateHandler(loader, decisionHooks, activeDecisions),
+    'flow.Otherwise': new OtherwiseHandler(decisionHooks, activeDecisions),
+    'flow.FallbackStart': new FallbackStartHandler(),
+    'flow.StrategyStart': new StrategyStartHandler(),
+    'flow.UntilPredicate': new UntilPredicateHandler(loader),
+    'flow.Require': new RequireHandler(loader),
+    ...(executeBody ? {
+      'flow.Retry': new CompositeHandler('Retry', loader, executeBody),
+      'flow.Timeout': new CompositeHandler('Timeout', loader, executeBody),
+      'flow.ForEach': new CompositeHandler('ForEach', loader, executeBody),
+      'flow.Parallel': new CompositeHandler('Parallel', loader, executeBody),
+      'flow.Race': new CompositeHandler('Race', loader, executeBody),
+    } : {}),
+    'flow.CallFlow': new CallFlowHandler(executeTarget),
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './loader.js';
+export * from './filesystem.js';
+export * from './compile.js';
+export * from './handlers.js';
+export * from './engine.js';

package/src/loader.ts

@@ -0,0 +1,383 @@
+/**
+ * flow bundle 加载：多文件（域按文件根 tag 发现）/ 单文件（() 内联区段）同构。
+ * 规范真源：docs/flow-dsl/spec/flow-core/{files,domains}.md。
+ * 完整 lint 由 tools/flow-dsl-check 承担；此处只做引擎必需的结构化与硬校验。
+ */
+import { parseXnl } from 'xnl-core';
+import type {
+  FlowBundleSpec,
+  CtrlFlowContract,
+  FlowDiagnostic,
+  FlowForm,
+  FlowNodeSpec,
+  FlowSourceCollection,
+  LoadFlowSourcesOptions,
+} from 'instant-ctrl-flow-contract';
+
+const FORMS = ['InstantCtrlFlow', 'WorkCtrlFlow', 'BPCtrlFlow'] as const satisfies readonly FlowForm[];
+
+const FACETS = {
+  'flow.contract': { tag: 'FlowContract', uriScheme: 'flow-contract://' },
+  'config': { tag: 'Config', uriScheme: 'config://' },
+  'config.def': { tag: 'ConfigDef', uriScheme: 'config-def://' },
+  'state.def': { tag: 'StateDef', uriScheme: 'state-def://' },
+  'state.seed': { tag: 'StateSeed', uriScheme: 'state-seed://' },
+  'task.space': { tag: 'TaskSpace', uriScheme: 'task-space://' },
+} as const;
+
+type FacetName = keyof typeof FACETS;
+
+const TAG_TO_FACET = Object.fromEntries(
+  Object.entries(FACETS).map(([name, descriptor]) => [descriptor.tag, name]),
+) as Record<string, FacetName | undefined>;
+
+const ALLOWED_FACETS: Record<FlowForm, ReadonlySet<FacetName>> = {
+  InstantCtrlFlow: new Set(['flow.contract', 'config', 'config.def']),
+  WorkCtrlFlow: new Set(['flow.contract', 'config', 'config.def', 'state.def', 'state.seed']),
+  BPCtrlFlow: new Set(['flow.contract', 'config', 'config.def', 'state.def', 'state.seed', 'task.space']),
+};
+
+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',
+  'If',
+  'Require',
+  'Fallback',
+  'Retry',
+  'Timeout',
+  'Until',
+  'ForEach',
+  'Parallel',
+  'Race',
+  'CallFlow',
+  'Return',
+]);
+const PROFILE_STATEMENTS: Record<FlowForm, ReadonlySet<string>> = {
+  InstantCtrlFlow: new Set(COMMON_STATEMENTS),
+  WorkCtrlFlow: new Set([...COMMON_STATEMENTS, 'ExternalJob', 'Timer']),
+  BPCtrlFlow: new Set([...COMMON_STATEMENTS, 'ExternalJob', 'Timer', 'TaskStep']),
+};
+const CODE_REF = /^vfs:\/\/[^#\s]+#[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+interface XnlEl {
+  kind: string;
+  tag: string;
+  id?: { namespace: string[]; name: string };
+  metadata: Record<string, unknown>;
+  attributes?: Record<string, unknown>;
+  body?: unknown[];
+  extend?: { order?: string[]; children: Record<string, XnlEl> };
+}
+
+const isEl = (n: unknown): n is XnlEl =>
+  !!n && typeof n === 'object' && ((n as XnlEl).kind === 'DataElement' || (n as XnlEl).kind === 'TextElement');
+
+const els = (arr?: unknown[]): XnlEl[] => (arr ?? []).filter(isEl);
+
+const listChildren = (el: XnlEl): XnlEl[] => els(el.body);
+
+const sectionChildren = (el: XnlEl): XnlEl[] => {
+  if (!el.extend) return [];
+  const order = el.extend.order ?? Object.keys(el.extend.children);
+  return order.map((k) => el.extend!.children[k]);
+};
+
+const idOf = (el: XnlEl): string | undefined => {
+  if (!el.id) return undefined;
+  const ns = el.id.namespace?.length ? el.id.namespace.join('.') + '.' : '';
+  return ns + el.id.name;
+};
+
+function toNodeSpec(el: XnlEl): FlowNodeSpec {
+  const sections: Record<string, FlowNodeSpec> = {};
+  for (const sec of sectionChildren(el)) sections[sec.tag] = toNodeSpec(sec);
+  return {
+    tag: el.tag,
+    id: idOf(el),
+    metadata: { ...(el.metadata ?? {}) },
+    attrs: { ...(el.attributes ?? {}) },
+    children: listChildren(el).map(toNodeSpec),
+    sections,
+  };
+}
+
+export interface LoadResult {
+  spec?: FlowBundleSpec;
+  diagnostics: FlowDiagnostic[];
+}
+
+export function loadFlowBundleFromSources(
+  sources: FlowSourceCollection,
+  options: LoadFlowSourcesOptions = {},
+): LoadResult {
+  const diagnostics: FlowDiagnostic[] = [];
+  const note = (code: string, message: string) => diagnostics.push({ code, message });
+  const noted = new Set<string>();
+  const noteOnce = (code: string, message: string) => {
+    if (noted.has(code)) return;
+    noted.add(code);
+    note(code, message);
+  };
+  const noteLegacyTag = (tag: string) => {
+    if (tag === 'Tree') {
+      noteOnce('legacy-tree-domain', 'Tree authoring is removed; product-root [] must contain statements directly');
+    } else if (tag === 'ActionTypes' || tag === 'ActionType') {
+      noteOnce('legacy-action-types-domain', 'action.types authoring is removed; code refs belong on statements');
+    } else if (tag === 'CtrlFlow') {
+      noteOnce('legacy-ctrl-flow-root', '<CtrlFlow> is removed; use product-root statements directly');
+    } else if (LEGACY_PUBLIC_CONTROL_NODES.has(tag)) {
+      noteOnce(
+        'legacy-public-control-node',
+        'public Sequence/Selector/Condition authoring is removed; use ordered statements, If, or Fallback',
+      );
+    } else if (LEGACY_PUBLIC_ACTION_NODES.has(tag) || tag.includes('.')) {
+      noteOnce(
+        'legacy-public-action-node',
+        'public behavior-tree and registered action nodes are removed; use Run with a direct vfs:// code ref',
+      );
+    }
+  };
+
+  const sourceEntries = (Array.isArray(sources)
+    ? sources.map(({ name, content }) => ({ name, content }))
+    : Object.entries(sources).map(([name, content]) => ({ name, content })))
+    .filter(({ name }) => name.endsWith('.xnl'))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const sourceNames = sourceEntries.map(({ name }) => name);
+  if (!sourceEntries.length) {
+    note('empty-bundle', `no .xnl sources in ${options.baseUri ?? 'named source collection'}`);
+    return { diagnostics };
+  }
+
+  const fileRoots: Record<string, { el: XnlEl; file: string }> = {};
+  for (const { name: f, content } of sourceEntries) {
+    let doc: { nodes: unknown[]; warnings?: { code?: string; message?: string }[] };
+    try {
+      doc = parseXnl(content) as typeof doc;
+    } catch (e) {
+      note('parse-error', `${f}: ${(e as Error).message}`);
+      continue;
+    }
+    for (const w of doc.warnings ?? []) note('parser-warning', `${f}: ${w.code ?? w.message}`);
+    for (const el of els(doc.nodes)) {
+      if (fileRoots[el.tag]) note('duplicate-file-root', `root <${el.tag}> in both ${fileRoots[el.tag].file} and ${f}`);
+      fileRoots[el.tag] = { el, file: f };
+    }
+  }
+
+  for (const tag of Object.keys(fileRoots)) noteLegacyTag(tag);
+
+  const form = FORMS.find((candidate) => fileRoots[candidate]);
+  if (!form) {
+    if (noted.size) return { diagnostics };
+    note('no-container', `no container root found in ${options.baseUri ?? 'named source collection'}`);
+    return { diagnostics };
+  }
+  const container = fileRoots[form].el;
+  const containerFile = fileRoots[form].file;
+
+  // Facet discovery is physical; toNodeSpec remains a pure XNL-to-contract projection.
+  const facets: Partial<Record<FacetName, XnlEl>> = {};
+  for (const [tag, { el, file }] of Object.entries(fileRoots)) {
+    const name = TAG_TO_FACET[tag];
+    if (!name || file === containerFile) continue;
+    if (file !== `${name}.xnl`) {
+      note(
+        'domain-file-name-mismatch',
+        `facet "${name}" (${FACETS[name].uriScheme}) root <${tag}> in ${file}, expected ${name}.xnl`,
+      );
+    }
+    facets[name] = el;
+  }
+  for (const sec of sectionChildren(container)) {
+    noteLegacyTag(sec.tag);
+
+    const name = TAG_TO_FACET[sec.tag];
+    if (!name) continue;
+    if (facets[name]) note('domain-double-definition', `facet "${name}" defined both inline and as file`);
+    else facets[name] = sec;
+  }
+
+  const visitStatement = (el: XnlEl): void => {
+    noteLegacyTag(el.tag);
+    for (const child of listChildren(el)) visitStatement(child);
+    for (const section of sectionChildren(el)) visitStatement(section);
+  };
+  const statementEls = listChildren(container);
+  for (const statement of statementEls) visitStatement(statement);
+
+  const seenIds = new Set<string>();
+  const requireCodeRef = (el: XnlEl, field: string) => {
+    const value = el.attributes?.[field];
+    if (typeof value !== 'string' || !CODE_REF.test(value)) {
+      note('invalid-code-ref', `<${el.tag} #${idOf(el) ?? ''}>.${field} must use vfs://path#Export`);
+    }
+  };
+  const requirePositiveInteger = (el: XnlEl, field: string, required = false) => {
+    const value = el.attributes?.[field];
+    if (value === undefined && !required) return;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+      note('invalid-positive-integer', `<${el.tag} #${idOf(el) ?? ''}>.${field} must be a positive integer`);
+    }
+  };
+  const validateBody = (nodes: XnlEl[]): void => {
+    for (const node of nodes) {
+      const id = idOf(node);
+      if (!PROFILE_STATEMENTS[form].has(node.tag)) {
+        note('statement-not-allowed', `<${node.tag} #${id ?? ''}> is not allowed in ${form}`);
+        continue;
+      }
+      if (!id) note('statement-missing-id', `<${node.tag}> requires #id`);
+      else if (seenIds.has(id)) note('duplicate-statement-id', `statement #${id} is duplicated`);
+      else seenIds.add(id);
+
+      if (node.tag === 'Run') requireCodeRef(node, 'src');
+      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') {
+        const timeoutMs = node.attributes?.timeoutMs;
+        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
+          note('invalid-timeout', `<Timeout #${id ?? ''}>.timeoutMs must be a non-negative number`);
+        }
+      }
+      if (node.tag === 'ForEach') requirePositiveInteger(node, 'concurrency');
+      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)) {
+          note('invalid-flow-ref', `<CallFlow #${id ?? ''}>.flow must use a product flow URI`);
+        }
+      }
+      if (node.tag === 'Return' && node.attributes?.src !== undefined) requireCodeRef(node, 'src');
+
+      if (node.tag === 'If') {
+        const sections = sectionChildren(node);
+        const branchesSection = sections.filter((section) => section.tag === 'Branches');
+        if (branchesSection.length !== 1) {
+          note('invalid-if-branches', `<If #${id ?? ''}> requires exactly one Branches section`);
+        } else {
+          const branches = listChildren(branchesSection[0]);
+          if (!branches.length) note('empty-if-branches', `<If #${id ?? ''}> requires at least one Branch`);
+          branches.forEach((branch, index) => {
+            if (branch.tag !== 'Branch' && branch.tag !== 'Otherwise') {
+              note('invalid-if-branch', `<If #${id ?? ''}> contains <${branch.tag}>`);
+              return;
+            }
+            if (branch.tag === 'Otherwise' && index !== branches.length - 1) {
+              note('otherwise-not-last', `<Otherwise> in <If #${id ?? ''}> must be last`);
+            }
+            if (branch.tag === 'Branch') requireCodeRef(branch, 'when');
+            validateBody(listChildren(branch));
+          });
+        }
+      } else if (node.tag === 'Fallback') {
+        const strategies = listChildren(node);
+        if (!strategies.length) note('empty-fallback', `<Fallback #${id ?? ''}> requires at least one Strategy`);
+        for (const strategy of strategies) {
+          if (strategy.tag !== 'Strategy') note('invalid-fallback-strategy', `<Fallback #${id ?? ''}> contains <${strategy.tag}>`);
+          else validateBody(listChildren(strategy));
+        }
+      } else if (node.tag === 'Parallel' || node.tag === 'Race') {
+        const sectionTag = node.tag === 'Parallel' ? 'Lanes' : 'Candidates';
+        const itemTag = node.tag === 'Parallel' ? 'Lane' : 'Candidate';
+        const sections = sectionChildren(node).filter((section) => section.tag === sectionTag);
+        if (sections.length !== 1) {
+          note('invalid-concurrent-domain', `<${node.tag} #${id ?? ''}> requires exactly one ${sectionTag} section`);
+        } else {
+          const items = listChildren(sections[0]);
+          if (!items.length) note('empty-concurrent-domain', `<${node.tag} #${id ?? ''}> requires at least one ${itemTag}`);
+          for (const item of items) {
+            if (item.tag !== itemTag) note('invalid-concurrent-item', `<${sectionTag}> contains <${item.tag}>`);
+            else validateBody(listChildren(item));
+          }
+        }
+        if (node.tag === 'Parallel' && node.attributes?.join !== undefined && node.attributes.join !== 'all') {
+          note('invalid-parallel-join', `<Parallel #${id ?? ''}>.join currently only supports "all"`);
+        }
+        if (
+          node.tag === 'Race'
+          && node.attributes?.mode !== 'first-success'
+          && node.attributes?.mode !== 'first-completed'
+        ) {
+          note('invalid-race-mode', `<Race #${id ?? ''}>.mode must be "first-success" or "first-completed"`);
+        }
+      } else {
+        validateBody(listChildren(node));
+      }
+    }
+  };
+  validateBody(statementEls);
+
+  for (const name of Object.keys(facets) as FacetName[]) {
+    if (!ALLOWED_FACETS[form].has(name)) {
+      noteOnce(
+        'facet-not-allowed',
+        `${form} does not allow facet "${name}" (${FACETS[name].uriScheme})`,
+      );
+    }
+  }
+
+  if (noted.size) return { diagnostics };
+
+  const config: Record<string, Record<string, unknown>> = {};
+  if (facets.config) {
+    for (const e of listChildren(facets.config).filter((e) => e.tag === 'ConfigEntry')) {
+      config[idOf(e) ?? ''] = { ...(e.attributes ?? {}) };
+    }
+  }
+
+  const configDef: Record<string, Record<string, unknown>> = {};
+  if (facets['config.def']) {
+    for (const e of listChildren(facets['config.def']).filter((e) => e.tag === 'ConfigEntryDef')) {
+      configDef[idOf(e) ?? ''] = { ...(e.attributes ?? {}) };
+    }
+  }
+
+  const fqn = idOf(container) ?? '';
+  const contractNode = facets['flow.contract'];
+  const contractId = contractNode ? idOf(contractNode) : undefined;
+  const contractAttrs = contractNode?.attributes ?? {};
+  const flowContract: CtrlFlowContract = contractNode
+    ? {
+      id: contractId ?? '',
+      ...(typeof contractAttrs.input === 'string' ? { input: contractAttrs.input } : {}),
+      ...(typeof contractAttrs.output === 'string' ? { output: contractAttrs.output } : {}),
+    }
+    : { id: fqn };
+  if (!contractNode) note('missing-flow-contract', `${form} #${fqn} requires exactly one FlowContract`);
+  if (contractNode && contractId !== fqn) note('flow-contract-id-mismatch', 'FlowContract #id must equal the enclosing flow FQN');
+  for (const field of ['input', 'output'] as const) {
+    const value = contractAttrs[field];
+    if (value !== undefined && (typeof value !== 'string' || !CODE_REF.test(value))) {
+      note('invalid-flow-contract-type-ref', `FlowContract.${field} must use vfs://path#Export`);
+    }
+  }
+  const stateDef = facets['state.def']
+    ? (Object.fromEntries(
+        Object.entries(facets['state.def'].attributes ?? {}).map(([k, v]) => [k, String(v)]),
+      ) as Record<string, string>)
+    : undefined;
+  const stateSeed = facets['state.seed'] ? { ...(facets['state.seed'].attributes ?? {}) } : undefined;
+  const taskSpace = facets['task.space'] ? toNodeSpec(facets['task.space']) : undefined;
+  const spec: FlowBundleSpec = {
+    form,
+    fqn,
+    apiVersion: String(container.metadata?.apiVersion ?? ''),
+    version: String(container.metadata?.version ?? ''),
+    title: container.attributes?.title as string | undefined,
+    sourceNames,
+    baseUri: options.baseUri,
+    dir: options.baseUri ?? '',
+    statements: statementEls.map(toNodeSpec),
+    flowContract,
+    config,
+    configDef,
+    stateDef,
+    stateSeed,
+    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 };
+}