work-ctrl-flow-logic 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "work-ctrl-flow-logic",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "WorkCtrlFlow 引擎：可中断可恢复的动态工作流（快照重放 + WaitHandle/ResumeSignal）",
   "type": "module",
@@ -12,15 +12,15 @@
   },
   "dependencies": {
     "depa-behavior-tree": "0.1.0",
-    "instant-ctrl-flow-logic": "0.1.0",
-    "instant-ctrl-flow-contract": "0.1.0",
-    "work-ctrl-flow-contract": "0.1.0"
+    "flow-step-space-logic": "0.1.0",
+    "instant-ctrl-flow-contract": "0.1.1",
+    "instant-ctrl-flow-logic": "0.1.3",
+    "work-ctrl-flow-contract": "0.1.2"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.com"
+    "access": "public"
   }
-}
+}

package/src/engine.ts

@@ -66,6 +66,40 @@ import type {
   WorkCtrlFlowOrchestrationFacts,
   DurableChildFlowResolver,
 } from 'work-ctrl-flow-contract';
+
+function isAsciiDigit(code: number): boolean {
+  return code >= 48 && code <= 57;
+}
+
+/** Locale-independent natural ordering for durable lane identities. */
+export function compareDurableLaneIds(left: string, right: string): number {
+  let leftIndex = 0;
+  let rightIndex = 0;
+  while (leftIndex < left.length && rightIndex < right.length) {
+    const leftCode = left.charCodeAt(leftIndex);
+    const rightCode = right.charCodeAt(rightIndex);
+    if (isAsciiDigit(leftCode) && isAsciiDigit(rightCode)) {
+      let leftEnd = leftIndex;
+      let rightEnd = rightIndex;
+      while (leftEnd < left.length && isAsciiDigit(left.charCodeAt(leftEnd))) leftEnd += 1;
+      while (rightEnd < right.length && isAsciiDigit(right.charCodeAt(rightEnd))) rightEnd += 1;
+      const leftRaw = left.slice(leftIndex, leftEnd);
+      const rightRaw = right.slice(rightIndex, rightEnd);
+      const leftValue = leftRaw.replace(/^0+(?=\d)/, '');
+      const rightValue = rightRaw.replace(/^0+(?=\d)/, '');
+      if (leftValue.length !== rightValue.length) return leftValue.length - rightValue.length;
+      if (leftValue !== rightValue) return leftValue < rightValue ? -1 : 1;
+      if (leftRaw.length !== rightRaw.length) return leftRaw.length - rightRaw.length;
+      leftIndex = leftEnd;
+      rightIndex = rightEnd;
+      continue;
+    }
+    if (leftCode !== rightCode) return leftCode - rightCode;
+    leftIndex += 1;
+    rightIndex += 1;
+  }
+  return (left.length - leftIndex) - (right.length - rightIndex);
+}
 import { WORKFLOW_SNAPSHOT_SCHEMA } from 'work-ctrl-flow-contract';
 
 type Ctx = ExecutionContext<CtrlFlowNodeType, INodeConfig>;
@@ -257,9 +291,9 @@ export class DurableCompositeScheduler implements ActionHandler<CtrlFlowNodeType
       return this.openSchedulerTimer(controller, invocationKey, attempt.nextAttemptAtMs);
     }
     if (config.primitive === 'Retry' && attempt.nextAttemptAtMs) {
-      flowStateOf(ctx).fault = undefined;
+      delete flowStateOf(ctx).fault;
       flowStateOf(ctx).current = fact.input;
-      attempt.nextAttemptAtMs = undefined;
+      delete attempt.nextAttemptAtMs;
     }
     const bodyId = config.primitive === 'Retry' ? `attempt:${attempt.attempt}` : fact.bodyId;
     const result = await controller.withinInvocationScope(
@@ -370,7 +404,7 @@ export class DurableCompositeScheduler implements ActionHandler<CtrlFlowNodeType
       const laneState = (lane.flowState ??= createFlowExecutionState(
         config.primitive === 'ForEach' ? lane.item : fact.input,
       )) as ReturnType<typeof createFlowExecutionState>;
-      laneState.fault = undefined;
+      delete laneState.fault;
       const laneController = new TickController(workingSnapshot, c.runtime);
       const laneRuntime = signal
         ? Object.assign(Object.create((ctx.runtime ?? {}) as object), { abortSignal: signal })
@@ -471,7 +505,7 @@ export class DurableCompositeScheduler implements ActionHandler<CtrlFlowNodeType
     }
     const lanes = Object.values(c.snapshot.orchestration.lanes)
       .filter((lane) => lane.invocationKey === invocationKey)
-      .sort((a, b) => a.laneId.localeCompare(b.laneId, undefined, { numeric: true }));
+      .sort((a, b) => compareDurableLaneIds(a.laneId, b.laneId));
     if (c.suspended.length > 0 || lanes.some((lane) => lane.status === 'Open')) {
       fact.status = 'Waiting';
       await this.persist(c.snapshot);
@@ -760,7 +794,7 @@ export class WaitNodeHandler implements ActionHandler<CtrlFlowNodeType, INodeCon
     if (done) {
       const closed = c.snapshot.closedWaitHandles.find((handle) => handle.invocationKey === key);
       if (done.result === 'Success') {
-        flow.fault = undefined;
+        delete flow.fault;
         flow.current = this.waitKind === 'timer' ? closed?.metadata?.input : done.payload;
       } else {
         flow.fault = new Error(`${this.waitKind} ${ctx.node.Key} finished with ${done.result}`);
@@ -792,8 +826,8 @@ export class WaitNodeHandler implements ActionHandler<CtrlFlowNodeType, INodeCon
             : cfg.timeoutMs !== undefined
               ? now + Number(cfg.timeoutMs)
               : 0,
-        assignTo: cfg.assignTo as string | undefined,
-        metadata: this.waitKind === 'timer' ? { input: flow.current } : undefined,
+        ...(typeof cfg.assignTo === 'string' ? { assignTo: cfg.assignTo } : {}),
+        ...(this.waitKind === 'timer' ? { metadata: { input: flow.current } } : {}),
       };
       c.snapshot.openWaitHandles.push(handle);
       if (handle.deadlineAtMs > 0) {
@@ -814,6 +848,11 @@ export interface WorkCtrlFlowEngineOptions {
   definition: WorkCtrlFlowDefinition;
   store: WorkCtrlFlowStore;
   runtime?: WorkCtrlFlowRuntime;
+  /** Derives the explicit Processor runtime for one ordinary node invocation. */
+  bindNodeRuntime?: (
+    runtime: WorkCtrlFlowRuntime,
+    identity: { readonly treeId: string; readonly nodeId: string; readonly invocationKey: string },
+  ) => WorkCtrlFlowRuntime;
   clock?: WorkCtrlFlowClock;
   view?: WorkCtrlFlowViewAdapter;
   /** 产品形态扩展（BPCtrlFlow 注入 TaskStep 编译与 handler） */
@@ -870,7 +909,9 @@ export class WorkCtrlFlowEngine {
       treeId,
       fqn: spec.fqn,
       status: 'Waiting',
-      vars: { ...(spec.stateSeed ?? {}) },
+      // state.seed is an immutable definition facet. Each new run receives one
+      // detached initialization copy; resume always reuses persisted vars.
+      vars: structuredClone(spec.stateSeed ?? {}),
       input: { ...(opts.input ?? {}) },
       branchDecisions: {},
       nodeResults: {},
@@ -883,6 +924,10 @@ export class WorkCtrlFlowEngine {
       updatedAtMs: this.now(),
     };
     snapshot.vars[FLOW_STATE_KEY] = createFlowExecutionState(opts.input ?? {});
+    // The initialization checkpoint is durable before any user node can run.
+    // lastTickNo=0 is the closed distinction between admitted-but-unexecuted
+    // and a checkpoint produced by an execution tick.
+    await this.options.store.save(snapshot);
     return this.tick(snapshot, spec);
   }
 
@@ -914,7 +959,10 @@ export class WorkCtrlFlowEngine {
 
     snapshot.appliedResumeSignals.push(`${handle.waitHandleId}:${signal.resumeToken}`);
     const result: TerminalResult = signal.outcome ?? 'Success';
-    snapshot.waitResults[handle.invocationKey] = { result, payload: signal.payload };
+    snapshot.waitResults[handle.invocationKey] = {
+      result,
+      ...(signal.payload === undefined ? {} : { payload: signal.payload }),
+    };
     handle.status = result === 'Cancelled' ? 'Cancelled' : 'Consumed';
     handle.closedAtMs = this.now();
     snapshot.openWaitHandles = snapshot.openWaitHandles.filter((h) => h !== handle);
@@ -1017,6 +1065,14 @@ export class WorkCtrlFlowEngine {
       new ReplayingHandler(h, controller, replayResults);
 
     const decisionHooks: FlowDecisionHooks = {
+      runtimeForNode: (nodeId, runtime) => {
+        const c = controller();
+        return this.options.bindNodeRuntime?.(runtime, {
+          treeId: c.snapshot.treeId,
+          nodeId,
+          invocationKey: c.invocationKeyFor(nodeId),
+        }) ?? runtime;
+      },
       begin: (ifPath) => {
         const c = controller();
         const invocationKey = c.invocationKeyFor(ifPath);

package/src/filesystem.ts

@@ -5,7 +5,24 @@ import {
   loadFlowBundle,
 } from 'instant-ctrl-flow-logic/filesystem';
 import { WorkCtrlFlowEngine, WorkCtrlFlowLoadError, type WorkCtrlFlowEngineOptions } from './engine.js';
-import { annotateFlowFile, materializeInstance } from './instance.js';
+import type {
+  ResumeSignal,
+  TickOutcome,
+  WorkCtrlFlowStartOptions,
+  WorkCtrlFlowStore,
+} from 'work-ctrl-flow-contract';
+import {
+  annotateFlowFile,
+  computeFlowBundleDigest,
+  FlowInstanceMaterializationError,
+  loadMaterializedFlowInstance,
+  materializeFlowInstance,
+  materializeInstance,
+  readFlowInstanceDescriptor,
+  type FlowInstanceSourceIdentity,
+} from './instance.js';
+
+export { computeFlowBundleDigest, readFlowInstanceDescriptor } from './instance.js';
 
 export interface WorkCtrlFlowDirectoryOptions
   extends Omit<WorkCtrlFlowEngineOptions, 'definition' | 'view'> {
@@ -32,3 +49,133 @@ export function createWorkCtrlFlowEngineFromDirectory(options: WorkCtrlFlowDirec
       : {}),
   });
 }
+
+export interface MaterializedWorkCtrlFlowDirectoryOptions
+  extends Omit<WorkCtrlFlowEngineOptions, 'definition'> {
+  /** Required only when the bound instance has not been admitted yet. */
+  bundleDir?: string;
+  instancesDir: string;
+  instanceId: string;
+  /** Required only for first admission; ignored by fresh recovery of an existing instance. */
+  source?: FlowInstanceSourceIdentity;
+}
+
+/**
+ * Instance-bound engine facade. Every operation builds its delegate solely
+ * from the admitted frozen definition; live bundleDir is an admission input.
+ */
+export class MaterializedWorkCtrlFlowDirectoryEngine {
+  readonly store: WorkCtrlFlowStore;
+
+  constructor(private readonly options: MaterializedWorkCtrlFlowDirectoryOptions) {
+    this.store = options.store;
+  }
+
+  get spec() {
+    return this.loadDefinition(this.requireExistingInstance().definitionDir).spec;
+  }
+
+  async start(treeId: string, options: WorkCtrlFlowStartOptions = {}): Promise<TickOutcome> {
+    const instance = this.ensureInstanceForStart();
+    const delegate = this.delegate(instance.definitionDir);
+    const existing = await this.store.load(treeId);
+    if (existing) {
+      if (options.input !== undefined && JSON.stringify(options.input) !== JSON.stringify(existing.input)) {
+        throw new WorkCtrlFlowLoadError(['tree-start-input-mismatch'], `tree ${treeId} is already bound to different start input`);
+      }
+      const outcome = await delegate.getOutcome(treeId);
+      if (!outcome) throw new WorkCtrlFlowLoadError(['tree-outcome-missing'], `tree ${treeId} has no durable outcome`);
+      return outcome;
+    }
+    return delegate.start(treeId, options);
+  }
+
+  async resume(treeId: string, signal: ResumeSignal): Promise<TickOutcome> {
+    return this.delegate(this.requireExistingInstance().definitionDir).resume(treeId, signal);
+  }
+
+  async fireDueDeadlines(treeId: string): Promise<TickOutcome> {
+    return this.delegate(this.requireExistingInstance().definitionDir).fireDueDeadlines(treeId);
+  }
+
+  async fireDueTimers(treeId: string): Promise<TickOutcome> {
+    return this.fireDueDeadlines(treeId);
+  }
+
+  async refresh(treeId: string): Promise<TickOutcome> {
+    return this.delegate(this.requireExistingInstance().definitionDir).refresh(treeId);
+  }
+
+  async getOutcome(treeId: string): Promise<TickOutcome | undefined> {
+    return this.delegate(this.requireExistingInstance().definitionDir).getOutcome(treeId);
+  }
+
+  private ensureInstanceForStart() {
+    const instanceDir = this.instanceDir();
+    if (fs.existsSync(instanceDir)) {
+      return loadMaterializedFlowInstance(instanceDir, this.options.instanceId);
+    }
+    if (!this.options.bundleDir || !this.options.source) {
+      throw new FlowInstanceMaterializationError(
+        'instance-admission-source-required',
+        'bundleDir and source identity are required to admit a new instance',
+      );
+    }
+    return materializeFlowInstance({
+      definitionDir: this.options.bundleDir,
+      instancesDir: this.options.instancesDir,
+      instanceId: this.options.instanceId,
+      source: this.options.source,
+      materializedAtMs: this.options.clock?.now(),
+    });
+  }
+
+  private requireExistingInstance() {
+    return loadMaterializedFlowInstance(this.instanceDir(), this.options.instanceId);
+  }
+
+  private instanceDir(): string {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(this.options.instanceId)
+      || this.options.instanceId === '.'
+      || this.options.instanceId === '..') {
+      throw new FlowInstanceMaterializationError('instance-id-invalid', 'instanceId must be one safe path segment');
+    }
+    const root = path.resolve(this.options.instancesDir);
+    const target = path.resolve(root, this.options.instanceId);
+    const relative = path.relative(root, target);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new FlowInstanceMaterializationError('instance-containment-invalid', 'instance path escapes instances root');
+    }
+    return target;
+  }
+
+  private delegate(definitionDir: string): WorkCtrlFlowEngine {
+    const { bundleDir: _bundleDir, instancesDir: _instancesDir, instanceId: _instanceId, source: _source, ...engineOptions } = this.options;
+    const loaded = this.loadDefinition(definitionDir);
+    return new WorkCtrlFlowEngine({
+      ...engineOptions,
+      definition: {
+        spec: loaded.spec,
+        resolveCode: createFilesystemFlowCodeResolver(),
+      },
+    });
+  }
+
+  private loadDefinition(definitionDir: string) {
+    const result = loadFlowBundle(definitionDir);
+    const hard = result.diagnostics.filter((diagnostic) => diagnostic.code !== 'parser-warning');
+    if (!result.spec || hard.length > 0) {
+      throw new WorkCtrlFlowLoadError(
+        result.diagnostics.map((item) => item.code),
+        result.diagnostics.map((item) => item.message).join('; '),
+      );
+    }
+    return { spec: result.spec };
+  }
+}
+
+export function createMaterializedWorkCtrlFlowEngineFromDirectory(
+  options: MaterializedWorkCtrlFlowDirectoryOptions,
+): MaterializedWorkCtrlFlowDirectoryEngine {
+  return new MaterializedWorkCtrlFlowDirectoryEngine(options);
+}

package/src/instance.ts

@@ -6,7 +6,17 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import type { NodeAnnotation, NodeViewStatus, TreeViewAnnotation } from 'work-ctrl-flow-contract';
+import { createHash, randomUUID } from 'node:crypto';
+import { loadFlowBundle } from 'instant-ctrl-flow-logic/filesystem';
+import { assembleDefinitionStepProfileDirectory } from 'flow-step-space-logic/filesystem';
+import {
+  FLOW_INSTANCE_SCHEMA_VERSION,
+  type FlowDefinitionProvenance,
+  type FlowInstanceDescriptor,
+  type NodeAnnotation,
+  type NodeViewStatus,
+  type TreeViewAnnotation,
+} from 'work-ctrl-flow-contract';
 
 export type { NodeAnnotation, NodeViewStatus, TreeViewAnnotation };
 
@@ -16,6 +26,596 @@ export function materializeInstance(definitionDir: string, instanceDir: string):
   fs.cpSync(definitionDir, instanceDir, { recursive: true });
 }
 
+export interface FlowInstanceSourceIdentity {
+  readonly revision: string;
+  readonly provenance: FlowDefinitionProvenance;
+  readonly expectedDigest?: `sha256:${string}`;
+}
+
+export interface MaterializeFlowInstanceOptions {
+  readonly definitionDir: string;
+  readonly instancesDir: string;
+  readonly instanceId: string;
+  readonly source: FlowInstanceSourceIdentity;
+  readonly materializedAtMs?: number;
+  /** Product-owned schema validator; WorkCtrlFlow remains the compatibility default. */
+  readonly validateDefinition?: FlowInstanceDefinitionValidator;
+}
+
+export type FlowInstanceDefinitionValidator = (definitionDir: string) => void;
+
+export interface MaterializedFlowInstance {
+  readonly instanceDir: string;
+  readonly definitionDir: string;
+  readonly descriptor: FlowInstanceDescriptor;
+  readonly created: boolean;
+}
+
+export class FlowInstanceMaterializationError extends Error {
+  constructor(public readonly code: string, message: string) {
+    super(message);
+    this.name = 'FlowInstanceMaterializationError';
+  }
+}
+
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+
+/** Closed path-independent source identity accepted before filesystem mutation. */
+export function normalizeFlowInstanceSourceIdentity(value: unknown): FlowInstanceSourceIdentity {
+  const record = exactDataRecord(value, ['revision', 'provenance'], ['expectedDigest'], 'source-identity-invalid');
+  const revision = normalizedString(dataValue(record, 'revision', 'source-identity-invalid'), 'definition revision', 'source-identity-invalid');
+  const provenance = normalizeDefinitionProvenance(
+    dataValue(record, 'provenance', 'source-identity-invalid'),
+    'source-identity-invalid',
+  );
+  const expectedDigestValue = Object.prototype.hasOwnProperty.call(record, 'expectedDigest')
+    ? dataValue(record, 'expectedDigest', 'source-identity-invalid')
+    : undefined;
+  if (expectedDigestValue !== undefined
+    && (typeof expectedDigestValue !== 'string' || !SHA256_DIGEST.test(expectedDigestValue))) {
+    throw new FlowInstanceMaterializationError('source-identity-invalid', 'expectedDigest must be a lowercase sha256 digest');
+  }
+  return deepFreeze({
+    revision,
+    provenance,
+    ...(expectedDigestValue === undefined ? {} : { expectedDigest: expectedDigestValue as `sha256:${string}` }),
+  });
+}
+
+/** Exact closed-data normalizer for the persisted instance descriptor. */
+export function normalizeFlowInstanceDescriptor(value: unknown): FlowInstanceDescriptor {
+  const record = exactDataRecord(
+    value,
+    ['schemaVersion', 'instanceId', 'definition', 'materializedAtMs'],
+    [],
+    'instance-descriptor-invalid',
+  );
+  if (dataValue(record, 'schemaVersion', 'instance-descriptor-invalid') !== FLOW_INSTANCE_SCHEMA_VERSION) {
+    throw new FlowInstanceMaterializationError('instance-descriptor-invalid', 'instance descriptor schemaVersion is invalid');
+  }
+  const instanceId = normalizedString(
+    dataValue(record, 'instanceId', 'instance-descriptor-invalid'),
+    'instanceId',
+    'instance-descriptor-invalid',
+  );
+  assertSafeInstanceId(instanceId);
+  const definitionRecord = exactDataRecord(
+    dataValue(record, 'definition', 'instance-descriptor-invalid'),
+    ['revision', 'digest', 'provenance'],
+    [],
+    'instance-descriptor-invalid',
+  );
+  const revision = normalizedString(
+    dataValue(definitionRecord, 'revision', 'instance-descriptor-invalid'),
+    'definition revision',
+    'instance-descriptor-invalid',
+  );
+  const digest = dataValue(definitionRecord, 'digest', 'instance-descriptor-invalid');
+  if (typeof digest !== 'string' || !SHA256_DIGEST.test(digest)) {
+    throw new FlowInstanceMaterializationError('instance-descriptor-invalid', 'definition digest must be a lowercase sha256 digest');
+  }
+  const provenance = normalizeDefinitionProvenance(
+    dataValue(definitionRecord, 'provenance', 'instance-descriptor-invalid'),
+    'instance-descriptor-invalid',
+  );
+  const materializedAtMs = dataValue(record, 'materializedAtMs', 'instance-descriptor-invalid');
+  if (typeof materializedAtMs !== 'number' || !Number.isSafeInteger(materializedAtMs) || materializedAtMs < 0) {
+    throw new FlowInstanceMaterializationError('instance-descriptor-invalid', 'materializedAtMs must be a non-negative safe integer');
+  }
+  return deepFreeze({
+    schemaVersion: FLOW_INSTANCE_SCHEMA_VERSION,
+    instanceId,
+    definition: { revision, digest: digest as `sha256:${string}`, provenance },
+    materializedAtMs,
+  });
+}
+
+/** Deterministic digest over relative paths, entry kinds and raw file bytes. */
+export function computeFlowBundleDigest(definitionDir: string): `sha256:${string}` {
+  const root = requireDirectory(definitionDir, 'definition-not-found');
+  const hash = createHash('sha256');
+  for (const entry of collectBundleEntries(root)) {
+    const pathBytes = Buffer.from(entry.relativePath, 'utf8');
+    const pathLength = Buffer.allocUnsafe(4);
+    pathLength.writeUInt32BE(pathBytes.length);
+    hash.update(entry.kind === 'directory' ? 'd' : 'f');
+    hash.update(pathLength);
+    hash.update(pathBytes);
+    if (entry.kind === 'file') {
+      const bytes = fs.readFileSync(entry.absolutePath);
+      const byteLength = Buffer.allocUnsafe(8);
+      byteLength.writeBigUInt64BE(BigInt(bytes.length));
+      hash.update(byteLength);
+      hash.update(bytes);
+    }
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+/**
+ * Creates a complete candidate, verifies bytes/schema/containment, then admits
+ * the immutable instance with one same-parent rename.
+ */
+export function materializeFlowInstance(options: MaterializeFlowInstanceOptions): MaterializedFlowInstance {
+  assertSafeInstanceId(options.instanceId);
+  const source = normalizeFlowInstanceSourceIdentity(options.source);
+  const materializedAtMs = nonNegativeSafeInteger(options.materializedAtMs ?? Date.now(), 'materializedAtMs');
+  const sourceRoot = requireDirectory(options.definitionDir, 'definition-not-found');
+  const requestedIdentity = requestedDefinitionIdentity(sourceRoot, source);
+  const boundary = prepareInstancesBoundary(options.instancesDir);
+  const instancesRoot = boundary.instancesRoot;
+  const instanceDir = containedChild(instancesRoot, options.instanceId);
+  assertInstancesBoundary(boundary);
+  if (fs.existsSync(instanceDir)) {
+    const admitted = loadMaterializedFlowInstance(
+      instanceDir,
+      options.instanceId,
+      options.validateDefinition,
+    );
+    if (JSON.stringify(admitted.descriptor.definition) !== JSON.stringify(requestedIdentity)) {
+      throw new FlowInstanceMaterializationError(
+        'instance-source-identity-mismatch',
+        'existing instance definition revision, digest or provenance differs from the requested source identity',
+      );
+    }
+    return admitted;
+  }
+
+  const sourceDigest = requestedIdentity.digest;
+
+  const candidateDir = containedChild(instancesRoot, `.candidate-${options.instanceId}-${randomUUID()}`);
+  const candidateDefinitionDir = path.join(candidateDir, 'definition');
+  try {
+    assertInstancesBoundary(boundary);
+    fs.mkdirSync(candidateDefinitionDir, { recursive: true });
+    assertOwnedDirectory(candidateDir, boundary.realInstancesRoot, 'instance-candidate-boundary-invalid');
+    copyBundle(sourceRoot, candidateDefinitionDir);
+    assertBundleBytesEqual(sourceRoot, candidateDefinitionDir);
+    const candidateDigest = computeFlowBundleDigest(candidateDefinitionDir);
+    if (candidateDigest !== sourceDigest) {
+      throw new FlowInstanceMaterializationError('candidate-digest-mismatch', 'candidate digest differs from source digest');
+    }
+    (options.validateDefinition ?? requireWorkCtrlFlowSchema)(candidateDefinitionDir);
+    assertTreeContained(candidateDir);
+
+    const descriptor: FlowInstanceDescriptor = deepFreeze({
+      schemaVersion: FLOW_INSTANCE_SCHEMA_VERSION,
+      instanceId: options.instanceId,
+      definition: requestedIdentity,
+      materializedAtMs,
+    });
+    assertInstancesBoundary(boundary);
+    assertOwnedDirectory(candidateDir, boundary.realInstancesRoot, 'instance-candidate-boundary-invalid');
+    fs.writeFileSync(path.join(candidateDir, 'instance.json'), `${JSON.stringify(descriptor, null, 2)}\n`);
+    const readback = readFlowInstanceDescriptor(candidateDir);
+    if (JSON.stringify(readback) !== JSON.stringify(descriptor)) {
+      throw new FlowInstanceMaterializationError('instance-readback-mismatch', 'instance descriptor readback differs');
+    }
+    assertInstancesBoundary(boundary);
+    assertOwnedDirectory(candidateDir, boundary.realInstancesRoot, 'instance-candidate-boundary-invalid');
+    if (fs.existsSync(instanceDir)) {
+      throw new FlowInstanceMaterializationError('instance-admission-conflict', 'instance target appeared during admission');
+    }
+    fs.renameSync(candidateDir, instanceDir);
+    assertInstancesBoundary(boundary);
+    assertOwnedDirectory(instanceDir, boundary.realInstancesRoot, 'instance-boundary-invalid');
+    const admitted = loadMaterializedFlowInstance(
+      instanceDir,
+      options.instanceId,
+      options.validateDefinition,
+    );
+    return Object.freeze({ ...admitted, created: true });
+  } catch (error) {
+    removeOwnedCandidate(candidateDir, boundary);
+    throw error;
+  }
+}
+
+function requestedDefinitionIdentity(
+  definitionDir: string,
+  source: FlowInstanceSourceIdentity,
+): FlowInstanceDescriptor['definition'] {
+  const sourceDigest = computeFlowBundleDigest(definitionDir);
+  if (source.expectedDigest !== undefined && source.expectedDigest !== sourceDigest) {
+    throw new FlowInstanceMaterializationError(
+      'definition-digest-mismatch',
+      `definition digest ${sourceDigest} does not match expected ${source.expectedDigest}`,
+    );
+  }
+  return deepFreeze({
+    revision: source.revision,
+    digest: sourceDigest,
+    provenance: source.provenance,
+  });
+}
+
+export function loadMaterializedFlowInstance(
+  instanceDir: string,
+  expectedInstanceId?: string,
+  validateDefinition: FlowInstanceDefinitionValidator = requireWorkCtrlFlowSchema,
+): MaterializedFlowInstance {
+  const resolved = requireOwnedInstanceDirectory(instanceDir);
+  const descriptor = readFlowInstanceDescriptor(resolved);
+  if (expectedInstanceId !== undefined && descriptor.instanceId !== expectedInstanceId) {
+    throw new FlowInstanceMaterializationError('instance-id-mismatch', 'instance descriptor identity differs from requested instance');
+  }
+  const definitionPath = path.join(resolved, 'definition');
+  let definitionStat: fs.Stats;
+  try {
+    definitionStat = fs.lstatSync(definitionPath);
+  } catch {
+    throw new FlowInstanceMaterializationError('instance-definition-not-found', 'frozen definition directory does not exist');
+  }
+  if (definitionStat.isSymbolicLink()) {
+    throw new FlowInstanceMaterializationError('bundle-link-unsupported', 'frozen definition must not be a symbolic link');
+  }
+  const definitionDir = requireDirectory(definitionPath, 'instance-definition-not-found');
+  // runs/ is mutable checkpoint support. Only the frozen definition subtree
+  // participates in instance artifact containment and digest verification.
+  assertTreeContained(definitionDir);
+  const digest = computeFlowBundleDigest(definitionDir);
+  if (digest !== descriptor.definition.digest) {
+    throw new FlowInstanceMaterializationError('instance-definition-digest-mismatch', 'frozen definition digest differs from instance descriptor');
+  }
+  validateDefinition(definitionDir);
+  return Object.freeze({ instanceDir: resolved, definitionDir, descriptor, created: false });
+}
+
+export function readFlowInstanceDescriptor(instanceDir: string): FlowInstanceDescriptor {
+  const resolved = requireOwnedInstanceDirectory(instanceDir);
+  const file = path.join(resolved, 'instance.json');
+  let value: unknown;
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('descriptor must be a regular no-link file');
+    value = JSON.parse(fs.readFileSync(file, 'utf8')) as unknown;
+  } catch (error) {
+    throw new FlowInstanceMaterializationError('instance-descriptor-invalid', `cannot read instance descriptor: ${(error as Error).message}`);
+  }
+  return normalizeFlowInstanceDescriptor(value);
+}
+
+type InstancesPhysicalBoundary = {
+  readonly supportRoot: string;
+  readonly realSupportRoot: string;
+  readonly instancesRoot: string;
+  readonly realInstancesRoot: string;
+};
+
+function prepareInstancesBoundary(value: string): InstancesPhysicalBoundary {
+  const instancesRoot = path.resolve(value);
+  const supportRoot = path.dirname(instancesRoot);
+  const realSupportRoot = requireNoLinkDirectory(supportRoot, 'instance-support-boundary-invalid');
+  if (!fs.existsSync(instancesRoot)) {
+    fs.mkdirSync(instancesRoot);
+  }
+  const realInstancesRoot = requireNoLinkDirectory(instancesRoot, 'instance-instances-boundary-invalid');
+  assertRealChild(realSupportRoot, realInstancesRoot, 'instance-instances-boundary-invalid');
+  const boundary = { supportRoot, realSupportRoot, instancesRoot, realInstancesRoot };
+  assertInstancesBoundary(boundary);
+  return boundary;
+}
+
+function assertInstancesBoundary(boundary: InstancesPhysicalBoundary): void {
+  const currentSupport = requireNoLinkDirectory(boundary.supportRoot, 'instance-support-boundary-invalid');
+  if (currentSupport !== boundary.realSupportRoot) {
+    throw new FlowInstanceMaterializationError('instance-support-boundary-invalid', 'support root identity changed during instance operation');
+  }
+  const currentInstances = requireNoLinkDirectory(boundary.instancesRoot, 'instance-instances-boundary-invalid');
+  if (currentInstances !== boundary.realInstancesRoot) {
+    throw new FlowInstanceMaterializationError('instance-instances-boundary-invalid', 'instances root identity changed during instance operation');
+  }
+  assertRealChild(boundary.realSupportRoot, currentInstances, 'instance-instances-boundary-invalid');
+}
+
+function requireOwnedInstanceDirectory(value: string): string {
+  const instanceDir = path.resolve(value);
+  const instancesRoot = path.dirname(instanceDir);
+  const supportRoot = path.dirname(instancesRoot);
+  const realSupportRoot = requireNoLinkDirectory(supportRoot, 'instance-support-boundary-invalid');
+  const realInstancesRoot = requireNoLinkDirectory(instancesRoot, 'instance-instances-boundary-invalid');
+  assertRealChild(realSupportRoot, realInstancesRoot, 'instance-instances-boundary-invalid');
+  return assertOwnedDirectory(instanceDir, realInstancesRoot, 'instance-boundary-invalid');
+}
+
+function requireNoLinkDirectory(value: string, code: string): string {
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(value);
+  } catch {
+    throw new FlowInstanceMaterializationError(code, 'required physical directory does not exist');
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new FlowInstanceMaterializationError(code, 'physical boundary must be a no-link directory');
+  }
+  return fs.realpathSync(value);
+}
+
+function assertOwnedDirectory(value: string, realParent: string, code: string): string {
+  const realValue = requireNoLinkDirectory(value, code);
+  assertRealChild(realParent, realValue, code);
+  return realValue;
+}
+
+function assertRealChild(realParent: string, realChild: string, code: string): void {
+  const relative = path.relative(realParent, realChild);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new FlowInstanceMaterializationError(code, 'physical directory escapes its owner boundary');
+  }
+}
+
+function removeOwnedCandidate(candidateDir: string, boundary: InstancesPhysicalBoundary): void {
+  if (!fs.existsSync(candidateDir)) return;
+  try {
+    assertInstancesBoundary(boundary);
+    assertOwnedDirectory(candidateDir, boundary.realInstancesRoot, 'instance-candidate-boundary-invalid');
+    fs.rmSync(candidateDir, { recursive: true, force: true });
+  } catch {
+    // Cleanup must never cross a changed physical owner boundary. A contained
+    // candidate can be recovered by a later owner after the boundary is valid.
+  }
+}
+
+type BundleEntry = {
+  readonly absolutePath: string;
+  readonly relativePath: string;
+  readonly kind: 'directory' | 'file';
+};
+
+function collectBundleEntries(root: string): BundleEntry[] {
+  const entries: BundleEntry[] = [];
+  const visit = (current: string) => {
+    for (const item of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => compareCodeUnits(left.name, right.name))) {
+      const absolutePath = path.join(current, item.name);
+      const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
+      if (!relativePath || relativePath.startsWith('../') || path.isAbsolute(relativePath)) {
+        throw new FlowInstanceMaterializationError('bundle-containment-invalid', `bundle entry escapes root: ${relativePath}`);
+      }
+      const stat = fs.lstatSync(absolutePath);
+      if (stat.isSymbolicLink()) {
+        throw new FlowInstanceMaterializationError('bundle-link-unsupported', `bundle entry must not be a symbolic link: ${relativePath}`);
+      }
+      if (stat.isDirectory()) {
+        entries.push({ absolutePath, relativePath, kind: 'directory' });
+        visit(absolutePath);
+      } else if (stat.isFile()) {
+        entries.push({ absolutePath, relativePath, kind: 'file' });
+      } else {
+        throw new FlowInstanceMaterializationError('bundle-entry-unsupported', `unsupported bundle entry: ${relativePath}`);
+      }
+    }
+  };
+  visit(root);
+  return entries.sort((left, right) => compareCodeUnits(left.relativePath, right.relativePath));
+}
+
+function copyBundle(sourceRoot: string, targetRoot: string): void {
+  for (const entry of collectBundleEntries(sourceRoot)) {
+    const target = path.join(targetRoot, ...entry.relativePath.split('/'));
+    if (entry.kind === 'directory') fs.mkdirSync(target, { recursive: true });
+    else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(entry.absolutePath, target);
+    }
+  }
+}
+
+function assertBundleBytesEqual(sourceRoot: string, targetRoot: string): void {
+  const sourceEntries = collectBundleEntries(sourceRoot);
+  const targetEntries = collectBundleEntries(targetRoot);
+  const sourceShape = sourceEntries.map(({ relativePath, kind }) => ({ relativePath, kind }));
+  const targetShape = targetEntries.map(({ relativePath, kind }) => ({ relativePath, kind }));
+  if (JSON.stringify(sourceShape) !== JSON.stringify(targetShape)) {
+    throw new FlowInstanceMaterializationError('candidate-shape-mismatch', 'candidate entries differ from source entries');
+  }
+  for (const entry of sourceEntries) {
+    if (entry.kind !== 'file') continue;
+    const target = path.join(targetRoot, ...entry.relativePath.split('/'));
+    if (!fs.readFileSync(entry.absolutePath).equals(fs.readFileSync(target))) {
+      throw new FlowInstanceMaterializationError('candidate-byte-mismatch', `candidate bytes differ for ${entry.relativePath}`);
+    }
+  }
+}
+
+function requireWorkCtrlFlowSchema(definitionDir: string): void {
+  const loaded = loadFlowBundle(definitionDir);
+  const hard = loaded.diagnostics.filter((diagnostic) => diagnostic.code !== 'parser-warning');
+  if (!loaded.spec || hard.length > 0 || loaded.spec.form !== 'WorkCtrlFlow') {
+    throw new FlowInstanceMaterializationError(
+      'definition-schema-invalid',
+      loaded.diagnostics.map((diagnostic) => `[${diagnostic.code}] ${diagnostic.message}`).join('; ') || 'definition is not a WorkCtrlFlow',
+    );
+  }
+}
+
+function assertTreeContained(root: string): void {
+  const realRoot = fs.realpathSync(root);
+  for (const entry of collectBundleEntries(realRoot)) {
+    const realEntry = fs.realpathSync(entry.absolutePath);
+    const relative = path.relative(realRoot, realEntry);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new FlowInstanceMaterializationError('bundle-containment-invalid', `entry escapes admitted root: ${entry.relativePath}`);
+    }
+  }
+}
+
+function requireDirectory(value: string, code: string): string {
+  const resolved = path.resolve(value);
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new FlowInstanceMaterializationError(code, `directory does not exist: ${resolved}`);
+  }
+  return fs.realpathSync(resolved);
+}
+
+function containedChild(root: string, segment: string): string {
+  const target = path.resolve(root, segment);
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new FlowInstanceMaterializationError('instance-containment-invalid', 'instance path escapes instances root');
+  }
+  return target;
+}
+
+function assertSafeInstanceId(value: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) || value === '.' || value === '..') {
+    throw new FlowInstanceMaterializationError('instance-id-invalid', 'instanceId must be one safe path segment');
+  }
+}
+
+function nonNegativeSafeInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) throw new FlowInstanceMaterializationError('source-identity-invalid', `${name} must be non-negative`);
+  return value;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value;
+  for (const nested of Object.values(value)) deepFreeze(nested);
+  return Object.freeze(value);
+}
+
+function normalizeDefinitionProvenance(value: unknown, code: string): FlowDefinitionProvenance {
+  const record = exactDataRecord(value, ['authority', 'artifactRef'], ['metadata'], code);
+  const authority = normalizedString(dataValue(record, 'authority', code), 'provenance authority', code);
+  const artifactRef = normalizedString(dataValue(record, 'artifactRef', code), 'provenance artifactRef', code);
+  const metadata = Object.prototype.hasOwnProperty.call(record, 'metadata')
+    ? cloneClosedObject(dataValue(record, 'metadata', code), code)
+    : undefined;
+  return deepFreeze({ authority, artifactRef, ...(metadata === undefined ? {} : { metadata }) });
+}
+
+function exactDataRecord(
+  value: unknown,
+  required: readonly string[],
+  optional: readonly string[],
+  code: string,
+): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new FlowInstanceMaterializationError(code, 'expected a plain-data object');
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new FlowInstanceMaterializationError(code, 'expected a plain-data object');
+  }
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string')) {
+    throw new FlowInstanceMaterializationError(code, 'symbol fields are not closed data');
+  }
+  const allowed = new Set([...required, ...optional]);
+  for (const key of keys as string[]) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new FlowInstanceMaterializationError(code, 'fields must be enumerable data properties');
+    }
+    if (!allowed.has(key)) throw new FlowInstanceMaterializationError(code, `unsupported field: ${key}`);
+  }
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      throw new FlowInstanceMaterializationError(code, `required field is missing: ${key}`);
+    }
+  }
+  return value as Record<string, unknown>;
+}
+
+function dataValue(record: Record<string, unknown>, field: string, code: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(record, field);
+  if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+    throw new FlowInstanceMaterializationError(code, `field must be an enumerable data property: ${field}`);
+  }
+  return descriptor.value;
+}
+
+function normalizedString(value: unknown, name: string, code: string): string {
+  if (typeof value !== 'string' || value.length === 0 || value !== value.trim()) {
+    throw new FlowInstanceMaterializationError(code, `${name} must be a non-empty canonical string`);
+  }
+  return value;
+}
+
+function cloneClosedObject(value: unknown, code: string): FlowDefinitionProvenance['metadata'] {
+  const cloned = cloneClosedValue(value, code);
+  if (typeof cloned !== 'object' || cloned === null || Array.isArray(cloned)) {
+    throw new FlowInstanceMaterializationError(code, 'metadata must be a closed plain-data object');
+  }
+  return cloned as FlowDefinitionProvenance['metadata'];
+}
+
+function cloneClosedValue(value: unknown, code: string, ancestors = new WeakSet<object>()): unknown {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new FlowInstanceMaterializationError(code, 'closed-data numbers must be finite');
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (typeof value !== 'object') throw new FlowInstanceMaterializationError(code, 'value is not closed data');
+  if (ancestors.has(value)) throw new FlowInstanceMaterializationError(code, 'closed data must not contain cycles');
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype) {
+        throw new FlowInstanceMaterializationError(code, 'closed arrays must use the standard prototype');
+      }
+      const keys = Reflect.ownKeys(value);
+      const expected = new Set<string>(['length']);
+      for (let index = 0; index < value.length; index += 1) expected.add(String(index));
+      if (keys.length !== expected.size
+        || keys.some((key) => typeof key !== 'string' || !expected.has(key))) {
+        throw new FlowInstanceMaterializationError(code, 'closed arrays must be dense without extra fields');
+      }
+      return Object.freeze(value.map((_, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+          throw new FlowInstanceMaterializationError(code, 'array entries must be enumerable data properties');
+        }
+        return cloneClosedValue(descriptor.value, code, ancestors);
+      }));
+    }
+    const record = exactClosedRecord(value, code);
+    const output: Record<string, unknown> = {};
+    for (const key of (Reflect.ownKeys(record) as string[]).sort(compareCodeUnits)) {
+      output[key] = cloneClosedValue(dataValue(record, key, code), code, ancestors);
+    }
+    return Object.freeze(output);
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function exactClosedRecord(value: object, code: string): Record<string, unknown> {
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new FlowInstanceMaterializationError(code, 'closed objects must use a plain prototype');
+  }
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string')) {
+    throw new FlowInstanceMaterializationError(code, 'symbol fields are not closed data');
+  }
+  for (const key of keys as string[]) dataValue(value as Record<string, unknown>, key, code);
+  return value as Record<string, unknown>;
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 const VIEW_ATTR_RE = /\s*(?:status|iterations|runStatus|tickNo)\s*=\s*(?:"[^"]*"|[\w.]+)/g;
 
 /** 移除既往注入的视图键（仅 manifest.xnl 使用；task.space 的 status 是真实 DSL 字段，走 replace 路径） */
@@ -87,6 +687,25 @@ export function annotateFlowFile(instanceDir: string, view: TreeViewAnnotation):
   const tmp = file + '.tmp';
   fs.writeFileSync(tmp, text);
   fs.renameSync(tmp, file);
+
+  const assembled = assembleDefinitionStepProfileDirectory(instanceDir, 'WorkCtrlFlow');
+  if (!assembled.forest || assembled.diagnostics.length > 0) return;
+  for (const stepId of assembled.forest.stepOrder) {
+    const stepFile = path.join(instanceDir, ...assembled.forest.steps[stepId].sourceRef.split('/'));
+    let stepText = stripViewAttrs(fs.readFileSync(stepFile, 'utf8'));
+    const coreOffset = stepText.indexOf('<Core');
+    const prefix = coreOffset >= 0 ? stepText.slice(0, coreOffset) : '';
+    let coreText = coreOffset >= 0 ? stepText.slice(coreOffset) : stepText;
+    for (const [id, annotation] of Object.entries(view.nodes)) {
+      const entries: Record<string, string | number> = { status: annotation.status };
+      if (annotation.iterations !== undefined) entries.iterations = annotation.iterations;
+      coreText = injectAttrs(coreText, id, entries);
+    }
+    stepText = `${prefix}${coreText}`;
+    const stepTmp = `${stepFile}.tmp`;
+    fs.writeFileSync(stepTmp, stepText);
+    fs.renameSync(stepTmp, stepFile);
+  }
 }
 
 /** BPCtrlFlow：把任务状态机现值同步进实例 task.space.xnl（替换既有 status 值；真源在 TaskSpaceStore） */