ai-ctrl-workflow-logic 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-ctrl-workflow-logic",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "description": "WorkCtrlFlow-backed AI Ctrl Workflow adapter logic",
   "type": "module",
@@ -11,13 +11,14 @@
     "./filesystem": "./src/filesystem.ts"
   },
   "dependencies": {
-    "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.2",
-    "work-ctrl-flow-contract": "0.1.1",
-    "work-ctrl-flow-logic": "0.1.1"
+    "ai-ctrl-workflow-contract": "0.1.3",
+    "ai-workflow-contract": "0.1.6",
+    "ai-workflow-logic": "0.1.6",
+    "flow-step-space-logic": "0.1.1",
+    "instant-ctrl-flow-contract": "0.1.2",
+    "instant-ctrl-flow-logic": "0.1.4",
+    "work-ctrl-flow-contract": "0.1.3",
+    "work-ctrl-flow-logic": "0.1.3"
   },
   "files": [
     "src"

package/src/filesystem.ts

@@ -7,8 +7,25 @@ import type {
   FlowClosedValue,
   AIWorkflowProfileDurableState,
 } from 'ai-workflow-contract';
-import { FilesystemFlowRunCheckpointStore } from 'ai-workflow-logic/checkpoint-filesystem';
+import {
+  createFilesystemFlowRunCheckpointRuntime,
+  createFilesystemFlowRunCheckpointStore,
+  type FilesystemFlowRunCheckpointStore,
+} from 'ai-workflow-logic/checkpoint-filesystem';
+import {
+  createInitialRunStepExtensions,
+  normalizeFlowClosedValue,
+  type FlowRunProfileAuthorityPort,
+  type FlowRunProfileAuthorityRequest,
+  type FrozenFlowRunProfileAuthority,
+} from 'ai-workflow-logic';
 import { createFilesystemFlowCodeResolver, type FlowModuleImporter } from 'instant-ctrl-flow-logic/filesystem';
+import type { FlowNodeSpec } from 'instant-ctrl-flow-contract';
+import {
+  assembleDefinitionStepProfileDirectory,
+  createFilesystemDefinitionStepProfileRuntime,
+} from 'flow-step-space-logic/filesystem';
+import type { DefinitionStepAssemblyRuntime, DefinitionStepForest } from 'flow-step-space-logic';
 import {
   loadMaterializedFlowInstance,
   materializeFlowInstance,
@@ -33,15 +50,20 @@ export interface MaterializedAICtrlWorkflowControllerOptions
   readonly durableAI: AIWorkflowProfileDurableState;
   readonly projectCheckpointOutput?: (snapshot: WorkCtrlFlowSnapshot) => FlowClosedValue;
   readonly importModule?: FlowModuleImporter;
+  readonly extensionCodecs?: DefinitionStepAssemblyRuntime['extensionCodecs'];
   readonly agentEffects?: AIAgentHostEffectPort;
   readonly agentTaskProofs?: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
 }
 
 export interface MaterializedAICtrlWorkflowController extends AICtrlWorkflowController {
   readonly checkpointStore: FilesystemFlowRunCheckpointStore;
+  readonly profileAuthority: FlowRunProfileAuthorityPort;
+  readonly extensionCodecs: DefinitionStepAssemblyRuntime['extensionCodecs'];
   readonly instanceId: string;
 }
 
+const emptyExtensionCodecs = Object.freeze({ resolve: () => undefined });
+
 /** Frozen AICtrl definition plus canonical filesystem checkpoint owner. */
 export function createMaterializedAICtrlWorkflowControllerFromDirectory(
   options: MaterializedAICtrlWorkflowControllerOptions,
@@ -49,10 +71,11 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
   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 extensionCodecs = options.extensionCodecs ?? emptyExtensionCodecs;
   const instancesDir = path.join(options.storeRoot, 'instances');
   const instanceDir = path.join(instancesDir, options.instanceId);
   const validateDefinition = (definitionDir: string) => {
-    loadAICtrlBinding(definitionDir);
+    loadAICtrlBinding(definitionDir, extensionCodecs);
   };
   const instance = fs.existsSync(instanceDir)
     ? loadMaterializedFlowInstance(instanceDir, options.instanceId, validateDefinition)
@@ -68,8 +91,25 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
           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 binding = loadAICtrlBinding(instance.definitionDir, extensionCodecs);
+  const profileAuthority = createMaterializedAICtrlWorkflowProfileAuthority({
+    storeRoot: options.storeRoot,
+    extensionCodecs,
+  });
+  const frozenProfile = profileAuthority.load({
+    instanceId: options.instanceId,
+    definition: instance.descriptor.definition,
+    profileKind: 'AICtrlWorkflow',
+  });
+  const checkpointStore = createFilesystemFlowRunCheckpointStore(
+    createFilesystemFlowRunCheckpointRuntime({
+      storeRoot: options.storeRoot,
+      extensionCodecs,
+      profileAuthority,
+    }),
+    {},
+    {},
+  );
   const store = createAICtrlWorkflowCheckpointStore(
     { checkpointStore },
     {
@@ -77,6 +117,7 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
       definition: instance.descriptor.definition,
       config: options.checkpointConfig,
       ai: options.durableAI,
+      initialStepExtensions: createInitialRunStepExtensions(frozenProfile),
       ...(options.projectCheckpointOutput ? { projectOutput: options.projectCheckpointOutput } : {}),
     },
   );
@@ -89,6 +130,7 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
     durableAI: _durableAI,
     projectCheckpointOutput: _projectCheckpointOutput,
     importModule: _importModule,
+    extensionCodecs: _extensionCodecs,
     agentEffects: _agentEffects,
     agentTaskProofs: _agentTaskProofs,
     ...controllerOptions
@@ -124,19 +166,90 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
       return controller.start(treeId, startOptions);
     },
   };
-  return Object.assign(materializedController, { checkpointStore, instanceId: options.instanceId });
+  return Object.assign(materializedController, {
+    checkpointStore,
+    profileAuthority,
+    extensionCodecs,
+    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')]),
+function loadAICtrlBinding(
+  definitionDir: string,
+  extensionCodecs: DefinitionStepAssemblyRuntime['extensionCodecs'],
+) {
+  const assembled = assembleDefinitionStepProfileDirectory(
+    createFilesystemDefinitionStepProfileRuntime({ rootDir: definitionDir, extensionCodecs }),
+    {},
+    { profileRoot: 'AICtrlWorkflow' },
   );
+  if (assembled.diagnostics.length > 0) {
+    throw new Error(`AICtrlWorkflow StepSpace is invalid: ${assembled.diagnostics.map((item) => item.code).join(', ')}`);
+  }
+  const sources = Object.fromEntries((assembled.sources as readonly ({ readonly ref: string; readonly content: string } | { readonly name: string; readonly content: string })[])
+    .map((source) => ['name' in source ? source.name : source.ref, source.content]));
   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;
+  return assembled.forest
+    ? { ...loaded.binding, definition: { ...loaded.binding.definition, definitionStepForest: assembled.forest } }
+    : loaded.binding;
+}
+
+function profileAuthorityFromBinding(
+  binding: ReturnType<typeof loadAICtrlBinding>,
+): FrozenFlowRunProfileAuthority {
+  const forest = binding.definition.definitionStepForest as DefinitionStepForest | undefined;
+  const definitionStepIds: string[] = [];
+  const visit = (node: FlowNodeSpec): void => {
+    if (node.id) definitionStepIds.push(node.id);
+    node.children.forEach(visit);
+    Object.values(node.sections).forEach(visit);
+  };
+  binding.definition.statements.forEach(visit);
+  return Object.freeze({
+    profileKind: 'AICtrlWorkflow' as const,
+    definitionStepIds: Object.freeze([...definitionStepIds]),
+    extensionsByStepId: Object.freeze(Object.fromEntries((forest?.stepOrder ?? []).flatMap((stepId) => {
+      const extensions = Object.fromEntries(Object.entries(forest!.steps[stepId].extensions).map(([kind, extension]) => [kind, Object.freeze({
+        ...(extension.schemaRef === undefined ? {} : { schemaRef: extension.schemaRef }),
+        initialValue: extension.value as import('ai-workflow-contract').FlowClosedValue,
+      })]));
+      return Object.keys(extensions).length === 0 ? [] : [[stepId, Object.freeze(extensions)]];
+    }))),
+  });
+}
+
+export function createMaterializedAICtrlWorkflowProfileAuthority(
+  runtime: Pick<MaterializedAICtrlWorkflowControllerOptions, 'storeRoot' | 'extensionCodecs'>,
+): FlowRunProfileAuthorityPort {
+  const extensionCodecs = runtime.extensionCodecs ?? emptyExtensionCodecs;
+  return Object.freeze({
+    load(request: FlowRunProfileAuthorityRequest) {
+      if (request.profileKind !== 'AICtrlWorkflow') {
+        throw new Error(`AI Ctrl profile authority cannot load ${request.profileKind}.`);
+      }
+      const instanceDir = path.join(runtime.storeRoot, 'instances', request.instanceId);
+      const instance = loadMaterializedFlowInstance(instanceDir, request.instanceId, (definitionDir) => {
+        loadAICtrlBinding(definitionDir, extensionCodecs);
+      });
+      if (canonicalClosed(normalizeFlowClosedValue(instance.descriptor.definition, 'profileAuthority.instanceDefinition'))
+        !== canonicalClosed(normalizeFlowClosedValue(request.definition, 'profileAuthority.requestDefinition'))) {
+        throw new Error('AI Ctrl profile authority definition identity differs from the checkpoint.');
+      }
+      return profileAuthorityFromBinding(loadAICtrlBinding(instance.definitionDir, extensionCodecs));
+    },
+  });
+}
+
+const compareCodeUnits = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
+
+function canonicalClosed(value: import('ai-workflow-contract').FlowClosedValue): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalClosed).join(',')}]`;
+  const record = value as import('ai-workflow-contract').FlowClosedObject;
+  return `{${Object.keys(record).sort(compareCodeUnits).map((key) => (
+    `${JSON.stringify(key)}:${canonicalClosed(record[key])}`
+  )).join(',')}}`;
 }

package/src/index.ts

@@ -20,6 +20,7 @@ import type {
   FlowDefinitionArtifactIdentity,
   FlowRunCheckpointKey,
   FlowRunCheckpointRuntime,
+  FlowRunStepExtensions,
 } from 'ai-workflow-contract';
 import {
   commitFlowRunCheckpoint,
@@ -52,6 +53,8 @@ export interface AICtrlWorkflowCheckpointStoreOptions {
   readonly definition: FlowDefinitionArtifactIdentity;
   readonly config: FlowClosedValue;
   readonly ai: AIWorkflowProfileDurableState;
+  /** Frozen definition-derived initial facts; later saves preserve the canonical owner value. */
+  readonly initialStepExtensions?: FlowRunStepExtensions;
   readonly projectOutput?: (snapshot: WorkCtrlFlowSnapshot) => FlowClosedValue;
 }
 
@@ -106,6 +109,11 @@ export function createAICtrlWorkflowCheckpointStore(
         output: options.projectOutput?.(snapshot) ?? current?.output ?? null,
         controllerSidecars: ctrlControllerSidecars(durableSnapshot) as unknown as FlowClosedObject,
         nodeSidecars: ctrlNodeSidecars(durableSnapshot) as unknown as FlowClosedObject,
+        ...(current?.stepExtensions !== undefined
+          ? { stepExtensions: current.stepExtensions }
+          : options.initialStepExtensions === undefined
+            ? {}
+            : { stepExtensions: options.initialStepExtensions }),
         profile: {
           kind: 'AICtrlWorkflow',
           snapshot: durableSnapshot as unknown as FlowClosedObject,