ai-ctrl-workflow-logic 0.1.2 → 0.1.3

package/package.json

@@ -1,28 +1,28 @@
 {
   "name": "ai-ctrl-workflow-logic",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "WorkCtrlFlow-backed AI Ctrl Workflow adapter logic",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./browser": "./src/browser.ts"
+    "./browser": "./src/browser.ts",
+    "./filesystem": "./src/filesystem.ts"
   },
   "dependencies": {
-    "ai-ctrl-workflow-contract": "0.1.0",
-    "ai-workflow-contract": "0.1.0",
-    "ai-workflow-logic": "0.1.0",
+    "ai-ctrl-workflow-contract": "0.1.1",
+    "ai-workflow-contract": "0.1.4",
+    "ai-workflow-logic": "0.1.4",
     "instant-ctrl-flow-contract": "0.1.0",
-    "instant-ctrl-flow-logic": "^0.1.1",
-    "work-ctrl-flow-contract": "0.1.0",
-    "work-ctrl-flow-logic": "0.1.0"
+    "instant-ctrl-flow-logic": "0.1.2",
+    "work-ctrl-flow-contract": "0.1.1",
+    "work-ctrl-flow-logic": "0.1.1"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.com"
+    "access": "public"
   }
 }

package/src/filesystem.ts

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { AICtrlWorkflowController } from 'ai-ctrl-workflow-contract';
+import type {
+  AIAgentHostEffectPort,
+  FrozenAIAgentTaskBinding,
+  FlowClosedValue,
+  AIWorkflowProfileDurableState,
+} from 'ai-workflow-contract';
+import { FilesystemFlowRunCheckpointStore } from 'ai-workflow-logic/checkpoint-filesystem';
+import { createFilesystemFlowCodeResolver, type FlowModuleImporter } from 'instant-ctrl-flow-logic/filesystem';
+import {
+  loadMaterializedFlowInstance,
+  materializeFlowInstance,
+  type FlowInstanceSourceIdentity,
+} from 'work-ctrl-flow-logic';
+import type { WorkCtrlFlowSnapshot } from 'work-ctrl-flow-contract';
+import {
+  createAICtrlWorkflowCheckpointStore,
+  createAICtrlWorkflowAgentNodeRuntimeBinder,
+  createAICtrlWorkflowController,
+  loadAICtrlWorkflowSources,
+  type CreateAICtrlWorkflowControllerOptions,
+} from './index.js';
+
+export interface MaterializedAICtrlWorkflowControllerOptions
+  extends Omit<CreateAICtrlWorkflowControllerOptions, 'binding' | 'store' | 'resolveCode'> {
+  readonly storeRoot: string;
+  readonly instanceId: string;
+  readonly bundleDir?: string;
+  readonly source?: FlowInstanceSourceIdentity;
+  readonly checkpointConfig: FlowClosedValue;
+  readonly durableAI: AIWorkflowProfileDurableState;
+  readonly projectCheckpointOutput?: (snapshot: WorkCtrlFlowSnapshot) => FlowClosedValue;
+  readonly importModule?: FlowModuleImporter;
+  readonly agentEffects?: AIAgentHostEffectPort;
+  readonly agentTaskProofs?: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
+}
+
+export interface MaterializedAICtrlWorkflowController extends AICtrlWorkflowController {
+  readonly checkpointStore: FilesystemFlowRunCheckpointStore;
+  readonly instanceId: string;
+}
+
+/** Frozen AICtrl definition plus canonical filesystem checkpoint owner. */
+export function createMaterializedAICtrlWorkflowControllerFromDirectory(
+  options: MaterializedAICtrlWorkflowControllerOptions,
+): MaterializedAICtrlWorkflowController {
+  if (options.agentEffects && (!options.agentTaskProofs || Object.keys(options.agentTaskProofs).length === 0)) {
+    throw new Error('AI_AGENT_TASK_PROOF_REQUIRED: materialized AI Ctrl Agent effects require run-freeze task proofs.');
+  }
+  const instancesDir = path.join(options.storeRoot, 'instances');
+  const instanceDir = path.join(instancesDir, options.instanceId);
+  const validateDefinition = (definitionDir: string) => {
+    loadAICtrlBinding(definitionDir);
+  };
+  const instance = fs.existsSync(instanceDir)
+    ? loadMaterializedFlowInstance(instanceDir, options.instanceId, validateDefinition)
+    : options.bundleDir && options.source
+      ? materializeFlowInstance({
+          definitionDir: options.bundleDir,
+          instancesDir,
+          instanceId: options.instanceId,
+          source: options.source,
+          validateDefinition,
+        })
+      : (() => {
+          if (options.bundleDir || options.source) throw new Error('bundleDir and source identity must be provided together.');
+          throw new Error('bundleDir and source identity are required for first admission.');
+        })();
+  const binding = loadAICtrlBinding(instance.definitionDir);
+  const checkpointStore = new FilesystemFlowRunCheckpointStore({ storeRoot: options.storeRoot });
+  const store = createAICtrlWorkflowCheckpointStore(
+    { checkpointStore },
+    {
+      instanceId: options.instanceId,
+      definition: instance.descriptor.definition,
+      config: options.checkpointConfig,
+      ai: options.durableAI,
+      ...(options.projectCheckpointOutput ? { projectOutput: options.projectCheckpointOutput } : {}),
+    },
+  );
+  const {
+    storeRoot: _storeRoot,
+    instanceId: _instanceId,
+    bundleDir: _bundleDir,
+    source: _source,
+    checkpointConfig: _checkpointConfig,
+    durableAI: _durableAI,
+    projectCheckpointOutput: _projectCheckpointOutput,
+    importModule: _importModule,
+    agentEffects: _agentEffects,
+    agentTaskProofs: _agentTaskProofs,
+    ...controllerOptions
+  } = options;
+  const controller = createAICtrlWorkflowController({
+    ...controllerOptions,
+    binding,
+    store,
+    resolveCode: createFilesystemFlowCodeResolver(options.importModule),
+    ...(options.agentEffects ? {
+      bindNodeRuntime: createAICtrlWorkflowAgentNodeRuntimeBinder({
+        flowInstanceId: options.instanceId,
+        checkpointRuntime: { checkpointStore },
+        effects: options.agentEffects,
+        workflowRef: `resource://${binding.definition.fqn}`,
+        taskProofs: options.agentTaskProofs ?? {},
+      }),
+    } : {}),
+  });
+  const materializedController: AICtrlWorkflowController = {
+    ...controller,
+    async start(treeId, startOptions) {
+      const existing = await controller.store.load(treeId);
+      if (existing) {
+        if (startOptions?.input !== undefined
+          && JSON.stringify(startOptions.input) !== JSON.stringify(existing.input)) {
+          throw new Error(`AI Ctrl Workflow run ${treeId} is already bound to different start input.`);
+        }
+        const outcome = await controller.getOutcome(treeId);
+        if (!outcome) throw new Error(`AI Ctrl Workflow run ${treeId} has no durable outcome.`);
+        return outcome;
+      }
+      return controller.start(treeId, startOptions);
+    },
+  };
+  return Object.assign(materializedController, { checkpointStore, instanceId: options.instanceId });
+}
+
+function loadAICtrlBinding(definitionDir: string) {
+  const sources = Object.fromEntries(
+    fs.readdirSync(definitionDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.xnl'))
+      .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+      .map((entry) => [entry.name, fs.readFileSync(path.join(definitionDir, entry.name), 'utf8')]),
+  );
+  const loaded = loadAICtrlWorkflowSources(sources, { baseUri: definitionDir });
+  if (!loaded.binding || loaded.diagnostics.length > 0) {
+    throw new Error(`AICtrlWorkflow definition is invalid: ${loaded.diagnostics.map((item) => item.code).join(', ')}`);
+  }
+  return loaded.binding;
+}

package/src/index.ts

@@ -5,12 +5,31 @@ import type {
 } from 'ai-ctrl-workflow-contract';
 import type {
   AICtrlWorkflowDefinitionBinding,
+  AICtrlWorkflowRunProfileState,
   AICtrlWorkflowRuntime,
+  AIAgentHostEffectPort,
+  FrozenAIAgentTaskBinding,
+  AIWorkflowAuthoredEffects,
   AIWorkflowEffectProvider,
+  AIWorkflowFlowRunCheckpoint,
+  AIWorkflowProfileDurableState,
   AIWorkflowRuntimeContext,
-  AIWorkflowStateStore,
+  AIWorkflowStateProjection,
+  FlowClosedObject,
+  FlowClosedValue,
+  FlowDefinitionArtifactIdentity,
+  FlowRunCheckpointKey,
+  FlowRunCheckpointRuntime,
 } from 'ai-workflow-contract';
-import { createAIWorkflowRuntimeContext, defineAICtrlWorkflow } from 'ai-workflow-logic';
+import {
+  commitFlowRunCheckpoint,
+  createAIWorkflowRuntimeContext,
+  defineAICtrlWorkflow,
+  loadFlowRunCheckpoint,
+  projectWorkCtrlSnapshotToCheckpointData,
+  bindAIAgentProcessors,
+} from 'ai-workflow-logic';
+import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 import type {
   FlowCodeResolver,
   FlowDiagnostic,
@@ -28,9 +47,99 @@ import type {
 } from 'work-ctrl-flow-contract';
 import { WorkCtrlFlowEngine, type WorkCtrlFlowDefinition, type WorkCtrlFlowEngineOptions } from 'work-ctrl-flow-logic';
 
+export interface AICtrlWorkflowCheckpointStoreOptions {
+  readonly instanceId: string;
+  readonly definition: FlowDefinitionArtifactIdentity;
+  readonly config: FlowClosedValue;
+  readonly ai: AIWorkflowProfileDurableState;
+  readonly projectOutput?: (snapshot: WorkCtrlFlowSnapshot) => FlowClosedValue;
+}
+
+function ctrlControllerSidecars(snapshot: WorkCtrlFlowSnapshot) {
+  return {
+    status: snapshot.status,
+    lastTickNo: snapshot.lastTickNo,
+    branchDecisions: snapshot.branchDecisions,
+    orchestration: snapshot.orchestration,
+    openWaitHandles: snapshot.openWaitHandles,
+    closedWaitHandles: snapshot.closedWaitHandles,
+    appliedResumeSignals: snapshot.appliedResumeSignals,
+  };
+}
+
+function ctrlNodeSidecars(snapshot: WorkCtrlFlowSnapshot) {
+  return {
+    nodeResults: snapshot.nodeResults,
+    waitResults: snapshot.waitResults,
+  };
+}
+
+/** Runtime-first adapter that makes the canonical checkpoint the WorkCtrl store owner. */
+export function createAICtrlWorkflowCheckpointStore(
+  runtime: FlowRunCheckpointRuntime,
+  options: AICtrlWorkflowCheckpointStoreOptions,
+): WorkCtrlFlowStore {
+  return {
+    async load(treeId) {
+      const checkpoint = await loadAICtrlWorkflowCheckpoint(runtime, {
+        instanceId: options.instanceId,
+        runId: treeId,
+      });
+      // WorkCtrlFlow mutates its working snapshot during a tick. The canonical
+      // checkpoint remains immutable; only this detached replay copy is mutable.
+      return checkpoint === undefined ? undefined : structuredClone(checkpoint.profile.snapshot);
+    },
+    async save(snapshot) {
+      const durableSnapshot = projectWorkCtrlSnapshotToCheckpointData(snapshot);
+      const key = { instanceId: options.instanceId, runId: snapshot.treeId };
+      const current = await loadAICtrlWorkflowCheckpoint(runtime, key);
+      const expectedVersion = current?.version ?? null;
+      const checkpoint: AIWorkflowFlowRunCheckpoint = {
+        schemaVersion: 'depa.flow-run-checkpoint/v1',
+        instanceId: options.instanceId,
+        runId: snapshot.treeId,
+        definition: options.definition,
+        version: current === undefined ? 0 : current.version + 1,
+        input: current?.input ?? snapshot.input as FlowClosedValue,
+        config: current?.config ?? options.config,
+        state: durableSnapshot.vars as FlowClosedValue,
+        output: options.projectOutput?.(snapshot) ?? current?.output ?? null,
+        controllerSidecars: ctrlControllerSidecars(durableSnapshot) as unknown as FlowClosedObject,
+        nodeSidecars: ctrlNodeSidecars(durableSnapshot) as unknown as FlowClosedObject,
+        profile: {
+          kind: 'AICtrlWorkflow',
+          snapshot: durableSnapshot as unknown as FlowClosedObject,
+          ai: current?.profile.kind === 'AICtrlWorkflow' ? current.profile.ai : options.ai,
+        },
+      };
+      await commitFlowRunCheckpoint(runtime, { expectedVersion, checkpoint });
+    },
+    async remove(treeId) {
+      throw new Error(`Canonical FlowRunCheckpoint removal is not supported for ${treeId}.`);
+    },
+  };
+}
+
+export async function loadAICtrlWorkflowCheckpoint(
+  runtime: FlowRunCheckpointRuntime,
+  input: FlowRunCheckpointKey,
+): Promise<
+  | (AIWorkflowFlowRunCheckpoint & { readonly profile: AICtrlWorkflowRunProfileState<WorkCtrlFlowSnapshot> })
+  | undefined
+> {
+  const checkpoint = await loadFlowRunCheckpoint(runtime, input);
+  if (checkpoint === undefined) return undefined;
+  if (checkpoint.profile.kind !== 'AICtrlWorkflow') {
+    throw new Error(`Flow run ${input.runId} is not an AI Ctrl Workflow checkpoint.`);
+  }
+  return checkpoint as AIWorkflowFlowRunCheckpoint & {
+    readonly profile: AICtrlWorkflowRunProfileState<WorkCtrlFlowSnapshot>;
+  };
+}
+
 export interface CreateAICtrlWorkflowRuntimeOptions<
   Effects extends AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore,
+  Store extends AIWorkflowStateProjection,
 > {
   readonly runtime?: WorkCtrlFlowRuntime;
   readonly ai: AIWorkflowRuntimeContext<Effects, Store>;
@@ -38,7 +147,7 @@ export interface CreateAICtrlWorkflowRuntimeOptions<
 
 export function createAICtrlWorkflowRuntime<
   Effects extends AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore,
+  Store extends AIWorkflowStateProjection,
 >(
   options: CreateAICtrlWorkflowRuntimeOptions<Effects, Store>,
 ): AICtrlWorkflowRuntime<Effects, Store> {
@@ -48,6 +157,40 @@ export function createAICtrlWorkflowRuntime<
   };
 }
 
+export interface CreateAICtrlWorkflowAgentNodeRuntimeBinderOptions {
+  readonly flowInstanceId: string;
+  readonly checkpointRuntime: FlowRunCheckpointRuntime;
+  readonly effects: AIAgentHostEffectPort;
+  readonly workflowRef: `resource://${string}`;
+  readonly taskProofs: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
+  readonly metadata?: FlowClosedObject;
+}
+
+/** Composition seam: ordinary WorkCtrl Run nodes receive the same-named bound facade. */
+export function createAICtrlWorkflowAgentNodeRuntimeBinder(
+  options: CreateAICtrlWorkflowAgentNodeRuntimeBinderOptions,
+): NonNullable<WorkCtrlFlowEngineOptions['bindNodeRuntime']> {
+  return (runtime, identity) => {
+    const workflowRuntime = runtime as AICtrlWorkflowRuntime<any, AIWorkflowStateProjection>;
+    if (!workflowRuntime.ai) throw new Error('AI Ctrl node runtime requires an AI runtime context.');
+    const proof = options.taskProofs[identity.nodeId];
+    if (!proof) throw new Error(`AI_AGENT_TASK_PROOF_REQUIRED: no frozen proof for node ${identity.nodeId}.`);
+    const taskBinding = assertFrozenAIAgentTaskBinding(proof).task;
+    const effects: AIWorkflowAuthoredEffects = bindAIAgentProcessors({
+      checkpointRuntime: options.checkpointRuntime,
+      checkpointKey: { instanceId: options.flowInstanceId, runId: identity.treeId },
+      nodeId: identity.nodeId,
+      invocationKey: identity.invocationKey,
+      workflowKind: 'AICtrlWorkflow',
+      workflowRef: options.workflowRef,
+      taskBinding,
+      effects: options.effects,
+      ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+    });
+    return Object.freeze({ ...runtime, ai: Object.freeze({ ...workflowRuntime.ai, effects }) });
+  };
+}
+
 export interface CreateAICtrlWorkflowControllerOptions
   extends Omit<WorkCtrlFlowEngineOptions, 'definition' | 'runtime' | 'expectedForm'> {
   readonly binding: AICtrlWorkflowDefinitionBinding;