ai-data-workflow-logic 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-data-workflow-logic",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "description": "EagerDataFlow-backed AI Data Workflow RunGraph helpers",
   "type": "module",
@@ -11,12 +11,13 @@
     "./filesystem": "./src/filesystem.ts"
   },
   "dependencies": {
-    "ai-data-workflow-contract": "0.1.1",
-    "ai-workflow-contract": "0.1.4",
-    "ai-workflow-logic": "0.1.4",
-    "eager-data-flow-contract": "0.1.1",
-    "eager-data-flow-logic": "0.1.2",
-    "work-ctrl-flow-logic": "0.1.1"
+    "ai-data-workflow-contract": "0.1.3",
+    "ai-workflow-contract": "0.1.6",
+    "ai-workflow-logic": "0.1.6",
+    "eager-data-flow-contract": "0.1.3",
+    "eager-data-flow-logic": "0.1.4",
+    "flow-step-space-logic": "0.1.1",
+    "work-ctrl-flow-logic": "0.1.3"
   },
   "files": [
     "src"

package/src/filesystem.ts

@@ -20,12 +20,24 @@ import {
   createFilesystemCodeResolver,
   materializeEagerDataFlowPlan,
 } from 'eager-data-flow-logic';
-import { FilesystemFlowRunCheckpointStore } from 'ai-workflow-logic/checkpoint-filesystem';
 import {
+  assembleDefinitionStepProfileDirectory,
+  createFilesystemDefinitionStepProfileRuntime,
+} from 'flow-step-space-logic/filesystem';
+import {
+  createFilesystemFlowRunCheckpointRuntime,
+  createFilesystemFlowRunCheckpointStore,
+} from 'ai-workflow-logic/checkpoint-filesystem';
+import {
+  createInitialRunStepExtensions,
   normalizeAIWorkflowProfileDurableState,
   normalizeFlowClosedObject,
   normalizeFlowClosedValue,
+  type FlowRunProfileAuthorityPort,
+  type FlowRunProfileAuthorityRequest,
+  type FrozenFlowRunProfileAuthority,
 } from 'ai-workflow-logic';
+import type { DefinitionStepAssemblyRuntime, DefinitionStepForest } from 'flow-step-space-logic';
 import {
   loadMaterializedFlowInstance,
   materializeFlowInstance,
@@ -45,6 +57,7 @@ export interface MaterializedAIDataWorkflowRuntime {
   readonly supportRoot: string;
   readonly workflow: AIDataWorkflowRuntime;
   readonly importModule: EagerDataFlowModuleImporter;
+  readonly extensionCodecs?: DefinitionStepAssemblyRuntime['extensionCodecs'];
   readonly agentEffects?: AIAgentHostEffectPort;
   readonly agentTaskProofs?: Readonly<Record<string, FrozenAIAgentTaskBinding>>;
   readonly checkpointObserver?: (event: {
@@ -81,6 +94,21 @@ export interface ContinueMaterializedAIDataWorkflowInput {
 
 export type ContinueMaterializedAIDataWorkflowConfig = Readonly<Record<never, never>>;
 
+const emptyExtensionCodecs = Object.freeze({ resolve: () => undefined });
+
+function checkpointStoreForRuntime(runtime: MaterializedAIDataWorkflowRuntime) {
+  const extensionCodecs = runtime.extensionCodecs ?? emptyExtensionCodecs;
+  return createFilesystemFlowRunCheckpointStore(
+    createFilesystemFlowRunCheckpointRuntime({
+      storeRoot: runtime.supportRoot,
+      extensionCodecs,
+      profileAuthority: createMaterializedAIDataWorkflowProfileAuthority(runtime),
+    }),
+    {},
+    {},
+  );
+}
+
 /** Runtime-first canonical Data execution from a frozen instance. */
 export async function startMaterializedAIDataWorkflow(
   runtime: MaterializedAIDataWorkflowRuntime,
@@ -89,8 +117,8 @@ export async function startMaterializedAIDataWorkflow(
 ): Promise<MaterializedAIDataWorkflowResult> {
   requireAgentTaskBindings(runtime);
   const instance = ensureAIDataInstance(runtime, input);
-  const binding = loadAIDataBinding(instance.definitionDir);
-  const checkpointStore = new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot });
+  const binding = loadAIDataBinding(instance.definitionDir, runtime.extensionCodecs ?? emptyExtensionCodecs);
+  const checkpointStore = checkpointStoreForRuntime(runtime);
   const checkpointRuntime = { checkpointStore };
   const existing = await loadAIDataWorkflowCheckpoint(checkpointRuntime, input);
   if (existing) {
@@ -118,6 +146,7 @@ export async function startMaterializedAIDataWorkflow(
     controllerSidecars: { status: 'Pending' },
     nodeSidecars: nodeStatuses(graph),
     ai: config.durableAI,
+    stepExtensions: createInitialRunStepExtensions(profileAuthorityFromBinding(binding)),
   });
   return executeAIDataCheckpoint(runtime, binding, v0);
 }
@@ -130,10 +159,11 @@ export async function continueMaterializedAIDataWorkflow(
 ): Promise<MaterializedAIDataWorkflowResult> {
   requireAgentTaskBindings(runtime);
   const instanceDir = path.join(runtime.supportRoot, 'instances', input.instanceId);
-  const instance = loadMaterializedFlowInstance(instanceDir, input.instanceId, validateAIDataDefinition);
-  const binding = loadAIDataBinding(instance.definitionDir);
+  const codecs = runtime.extensionCodecs ?? emptyExtensionCodecs;
+  const instance = loadMaterializedFlowInstance(instanceDir, input.instanceId, (definitionDir) => validateAIDataDefinition(definitionDir, codecs));
+  const binding = loadAIDataBinding(instance.definitionDir, codecs);
   const checkpoint = await loadAIDataWorkflowCheckpoint(
-    { checkpointStore: new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot }) },
+    { checkpointStore: checkpointStoreForRuntime(runtime) },
     input,
   );
   if (!checkpoint) throw new Error(`AI Data Workflow run ${input.runId} does not have a canonical checkpoint.`);
@@ -166,7 +196,7 @@ async function executeAIDataCheckpoint(
   }
   const invocationInput = checkpoint.input as Readonly<Record<string, FlowClosedValue>>;
   const checkpointRuntime = {
-    checkpointStore: new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot }),
+    checkpointStore: checkpointStoreForRuntime(runtime),
   };
   let transitionTail = Promise.resolve();
   const transition = <T>(operation: () => Promise<T>): Promise<T> => {
@@ -317,10 +347,11 @@ export async function loadMaterializedAIDataWorkflowRun(
   input: Pick<StartMaterializedAIDataWorkflowInput, 'instanceId' | 'runId'>,
 ): Promise<MaterializedAIDataWorkflowResult | undefined> {
   const instanceDir = path.join(runtime.supportRoot, 'instances', input.instanceId);
-  const instance = loadMaterializedFlowInstance(instanceDir, input.instanceId, validateAIDataDefinition);
-  const binding = loadAIDataBinding(instance.definitionDir);
+  const codecs = runtime.extensionCodecs ?? emptyExtensionCodecs;
+  const instance = loadMaterializedFlowInstance(instanceDir, input.instanceId, (definitionDir) => validateAIDataDefinition(definitionDir, codecs));
+  const binding = loadAIDataBinding(instance.definitionDir, codecs);
   const checkpoint = await loadAIDataWorkflowCheckpoint(
-    { checkpointStore: new FilesystemFlowRunCheckpointStore({ storeRoot: runtime.supportRoot }) },
+    { checkpointStore: checkpointStoreForRuntime(runtime) },
     input,
   );
   if (!checkpoint) return undefined;
@@ -340,7 +371,10 @@ function ensureAIDataInstance(
   const instancesDir = path.join(runtime.supportRoot, 'instances');
   const instanceDir = path.join(instancesDir, input.instanceId);
   if (fs.existsSync(instanceDir)) {
-    return loadMaterializedFlowInstance(instanceDir, input.instanceId, validateAIDataDefinition);
+    return loadMaterializedFlowInstance(instanceDir, input.instanceId, (definitionDir) => validateAIDataDefinition(
+      definitionDir,
+      runtime.extensionCodecs ?? emptyExtensionCodecs,
+    ));
   }
   if (!input.bundleDir || !input.source) {
     if (input.bundleDir || input.source) throw new Error('bundleDir and source identity must be provided together.');
@@ -351,33 +385,108 @@ function ensureAIDataInstance(
     instancesDir,
     instanceId: input.instanceId,
     source: input.source,
-    validateDefinition: validateAIDataDefinition,
+    validateDefinition: (definitionDir) => validateAIDataDefinition(
+      definitionDir,
+      runtime.extensionCodecs ?? emptyExtensionCodecs,
+    ),
   });
 }
 
-function validateAIDataDefinition(definitionDir: string): void {
-  loadAIDataBinding(definitionDir);
+function validateAIDataDefinition(
+  definitionDir: string,
+  extensionCodecs: DefinitionStepAssemblyRuntime['extensionCodecs'],
+): void {
+  loadAIDataBinding(definitionDir, extensionCodecs);
 }
 
-function loadAIDataBinding(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 loadAIDataBinding(
+  definitionDir: string,
+  extensionCodecs: DefinitionStepAssemblyRuntime['extensionCodecs'],
+) {
+  const assembled = assembleDefinitionStepProfileDirectory(
+    createFilesystemDefinitionStepProfileRuntime({ rootDir: definitionDir, extensionCodecs }),
+    {},
+    { profileRoot: 'AIDataWorkflow' },
   );
+  if (assembled.diagnostics.length > 0) {
+    throw new Error(`AIDataWorkflow 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 = loadAIDataWorkflowSources(sources, { baseUri: definitionDir });
   if (!loaded.binding || loaded.diagnostics.length > 0) {
     throw new Error(`AIDataWorkflow 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 loadAIDataBinding>,
+): FrozenFlowRunProfileAuthority {
+  const forest = binding.definition.definitionStepForest as DefinitionStepForest | undefined;
+  const definitionStepIds = forest?.stepOrder ?? binding.definition.declarationOrder;
+  return Object.freeze({
+    profileKind: 'AIDataWorkflow' as const,
+    definitionStepIds: Object.freeze([...definitionStepIds]),
+    binding: durableBinding(binding) as unknown as import('ai-workflow-contract').FlowClosedObject,
+    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 createMaterializedAIDataWorkflowProfileAuthority(
+  runtime: Pick<MaterializedAIDataWorkflowRuntime, 'supportRoot' | 'extensionCodecs'>,
+): FlowRunProfileAuthorityPort {
+  const extensionCodecs = runtime.extensionCodecs ?? emptyExtensionCodecs;
+  return Object.freeze({
+    load(request: FlowRunProfileAuthorityRequest) {
+      if (request.profileKind !== 'AIDataWorkflow') {
+        throw new Error(`AI Data profile authority cannot load ${request.profileKind}.`);
+      }
+      const instanceDir = path.join(runtime.supportRoot, 'instances', request.instanceId);
+      const instance = loadMaterializedFlowInstance(instanceDir, request.instanceId, (definitionDir) => {
+        validateAIDataDefinition(definitionDir, extensionCodecs);
+      });
+      if (canonicalClosed(normalizeFlowClosedValue(instance.descriptor.definition, 'profileAuthority.instanceDefinition'))
+        !== canonicalClosed(normalizeFlowClosedValue(request.definition, 'profileAuthority.requestDefinition'))) {
+        throw new Error('AI Data profile authority definition identity differs from the checkpoint.');
+      }
+      return profileAuthorityFromBinding(loadAIDataBinding(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(',')}}`;
+}
+
+function durableBinding(binding: ReturnType<typeof loadAIDataBinding>) {
+  const {
+    baseUri: _baseUri,
+    definitionStepForest: _definitionStepForest,
+    ...definition
+  } = binding.definition;
+  return { ...binding, definition };
 }
 
 function durableGraph(graph: AIDataWorkflowRunGraph): AIDataWorkflowRunGraph {
-  const { baseUri: _baseUri, ...definition } = graph.binding.definition;
   return {
     ...graph,
-    binding: { ...graph.binding, definition },
+    binding: durableBinding(graph.binding as ReturnType<typeof loadAIDataBinding>),
   };
 }
 

package/src/index.ts

@@ -38,6 +38,7 @@ import type {
   FlowRunCheckpointCommit,
   FlowRunCheckpointKey,
   FlowRunCheckpointRuntime,
+  FlowRunStepExtensions,
   FlowRunProfileState,
 } from 'ai-workflow-contract';
 import type {
@@ -48,7 +49,8 @@ import type {
   EagerDataFlowValue,
   LoadEagerDataFlowOptions,
 } from 'eager-data-flow-contract';
-import { loadEagerDataFlowProfileSources } from 'eager-data-flow-logic';
+import { loadEagerDataFlowProfileSources, loadEagerDataFlowProfileSourcesWithRuntime } from 'eager-data-flow-logic';
+import { createDefinitionStepSourceRuntime, type DefinitionStepAssemblyRuntime } from 'flow-step-space-logic';
 import {
   createAIWorkflowRuntimeContext,
   commitFlowRunCheckpoint,
@@ -70,6 +72,7 @@ export interface CreateAIDataWorkflowCheckpointInput {
   readonly controllerSidecars: FlowClosedObject;
   readonly nodeSidecars: FlowClosedObject;
   readonly ai: AIWorkflowProfileDurableState;
+  readonly stepExtensions?: FlowRunStepExtensions;
 }
 
 /** Creates the first complete Data checkpoint as one runtime-owned transition. */
@@ -91,6 +94,7 @@ export function createAIDataWorkflowCheckpoint(
       output: input.output,
       controllerSidecars: input.controllerSidecars,
       nodeSidecars: input.nodeSidecars,
+      ...(input.stepExtensions === undefined ? {} : { stepExtensions: input.stepExtensions }),
       profile: { kind: 'AIDataWorkflow', runGraph: input.graph, ai: input.ai },
     },
   });
@@ -194,6 +198,34 @@ export interface AIDataWorkflowSourceLoadResult {
   readonly diagnostics: readonly EagerDataFlowDiagnostic[];
 }
 
+export interface AIDataWorkflowSourceLoadRuntime {
+  readonly extensionCodecs: DefinitionStepAssemblyRuntime['extensionCodecs'];
+}
+
+export interface AIDataWorkflowSourceLoadInput {
+  readonly sources: EagerDataFlowSourceCollection;
+}
+
+export type AIDataWorkflowSourceLoadConfig = LoadEagerDataFlowOptions;
+
+/** Processor form for profile admission with runtime-owned extension codecs. */
+export function loadAIDataWorkflow(
+  runtime: AIDataWorkflowSourceLoadRuntime,
+  input: AIDataWorkflowSourceLoadInput,
+  config: AIDataWorkflowSourceLoadConfig = {},
+): AIDataWorkflowSourceLoadResult {
+  const loaded = loadEagerDataFlowProfileSourcesWithRuntime(
+    createDefinitionStepSourceRuntime(input.sources, runtime.extensionCodecs),
+    input.sources,
+    { ...config, profileRoot: 'AIDataWorkflow' },
+  );
+  if (!loaded.plan || loaded.diagnostics.length > 0) return { diagnostics: loaded.diagnostics };
+  return {
+    binding: defineEagerBackedAIDataWorkflow(loaded.plan),
+    diagnostics: loaded.diagnostics,
+  };
+}
+
 export function loadAIDataWorkflowSources(
   sources: EagerDataFlowSourceCollection,
   options: LoadEagerDataFlowOptions = {},