ai-data-workflow-logic 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-data-workflow-logic",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "description": "EagerDataFlow-backed AI Data Workflow RunGraph helpers",
   "type": "module",
@@ -8,18 +8,19 @@
   "exports": {
     ".": "./src/index.ts",
     "./browser": "./src/browser.ts",
-    "./filesystem": "./src/filesystem.ts"
+    "./filesystem": "./src/filesystem.ts",
+    "./sources": "./src/source-loader.ts"
   },
   "dependencies": {
-    "ai-data-workflow-contract": "0.2.0",
-    "ai-workflow-contract": "0.2.0",
-    "ai-workflow-logic": "0.2.0",
+    "ai-data-workflow-contract": "0.2.1",
+    "ai-workflow-contract": "0.2.2",
+    "ai-workflow-logic": "0.2.2",
     "eager-data-flow-contract": "0.1.4",
-    "eager-data-flow-logic": "0.1.7",
-    "flow-step-space-logic": "0.1.1",
-    "task-manager-contract": "0.1.3",
-    "task-manager-logic": "0.1.6",
-    "work-ctrl-flow-logic": "0.1.5"
+    "eager-data-flow-logic": "0.1.8",
+    "flow-step-space-logic": "0.1.2",
+    "task-manager-contract": "0.1.4",
+    "task-manager-logic": "0.1.7",
+    "work-ctrl-flow-logic": "0.1.6"
   },
   "files": [
     "src"

package/src/after.ts

@@ -0,0 +1,78 @@
+import type {AIDataWorkflowAfterPolicy, AIDataWorkflowGraphPatch, AIDataWorkflowRunGraph} from 'ai-data-workflow-contract';
+import {normalizeFlowClosedObject} from 'ai-workflow-logic';
+import {canonicalOwnDataDigest} from 'task-manager-contract';
+import type {EagerDataFlowValue} from 'eager-data-flow-contract';
+import type {FlowClosedValue} from 'ai-workflow-contract';
+
+function requireThat(condition: unknown, code: string): asserts condition {
+  if (!condition) throw new Error(code);
+}
+/** 旧 Eager 合同的数组可写；只作脱离输入引用的纯值转换，不放宽合同。 */
+function eagerValue(value: FlowClosedValue): EagerDataFlowValue {
+  if (Array.isArray(value)) return value.map(eagerValue);
+  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, eagerValue(item)]));
+  return value;
+}
+function policy(value: unknown): AIDataWorkflowAfterPolicy {
+  const row = normalizeFlowClosedObject(value);
+  const keys = ['schemaVersion', 'targetNodeId', 'resultPort', 'decisionField', 'reopenValue', 'completeValue', 'maxReopens'];
+  requireThat(Object.keys(row).length === keys.length && keys.every(key => Object.hasOwn(row, key)), 'AI_DATA_AFTER_POLICY_FIELDS');
+  requireThat(row.schemaVersion === 'depa.ai-data-after/v1', 'AI_DATA_AFTER_POLICY_VERSION');
+  for (const key of ['targetNodeId', 'resultPort', 'decisionField', 'reopenValue', 'completeValue']) requireThat(typeof row[key] === 'string' && row[key].length > 0 && row[key].length <= 512 && row[key].trim() === row[key], 'AI_DATA_AFTER_POLICY_IDENTITY');
+  requireThat(typeof row.targetNodeId === 'string' && typeof row.resultPort === 'string' && typeof row.decisionField === 'string' && typeof row.reopenValue === 'string' && typeof row.completeValue === 'string', 'AI_DATA_AFTER_POLICY_IDENTITY');
+  requireThat(row.reopenValue !== row.completeValue && typeof row.maxReopens === 'number' && Number.isSafeInteger(row.maxReopens) && row.maxReopens >= 0 && row.maxReopens <= 5, 'AI_DATA_AFTER_POLICY_BUDGET');
+  return {schemaVersion: row.schemaVersion, targetNodeId: row.targetNodeId, resultPort: row.resultPort, decisionField: row.decisionField, reopenValue: row.reopenValue, completeValue: row.completeValue, maxReopens: row.maxReopens};
+}
+
+/** 纯规划；调用 owner 必须通过原 checkpoint CAS 应用返回的补丁。 */
+export function planAIDataWorkflowAfterPatch(graph: AIDataWorkflowRunGraph, sourceNodeId: string): AIDataWorkflowGraphPatch | undefined {
+  const source = graph.nodes[sourceNodeId];
+  if (!source || source.config.workflowAfter === undefined || !['Succeeded', 'Reused'].includes(source.status)) return;
+  const declared = policy(source.config.workflowAfter);
+  requireThat(source.result?.generation === source.generation && source.result.status === source.status, 'AI_DATA_AFTER_SOURCE_GENERATION');
+  const outputs = normalizeFlowClosedObject(source.result.output);
+  requireThat(Object.hasOwn(outputs, declared.resultPort), 'AI_DATA_AFTER_RESULT_PORT');
+  const report = normalizeFlowClosedObject(outputs[declared.resultPort]);
+  const decision = report[declared.decisionField];
+  if (decision === declared.completeValue) return;
+  requireThat(decision === declared.reopenValue, 'AI_DATA_AFTER_DECISION_UNSETTLED');
+  const target = graph.nodes[declared.targetNodeId];
+  requireThat(target?.tag === 'TransformNode' && target.nodeType !== 'manual' && target.config.workflowReopenable === true, 'AI_DATA_AFTER_TARGET_NOT_REOPENABLE');
+  const seen = new Set<string>();
+  const visit = (nodeId: string): void => {
+    if (seen.has(nodeId)) return;
+    seen.add(nodeId);
+    for (const parent of graph.nodes[nodeId]?.dependsOn ?? []) visit(parent);
+  };
+  visit(sourceNodeId);
+  requireThat(declared.targetNodeId !== sourceNodeId && seen.has(declared.targetNodeId), 'AI_DATA_AFTER_TARGET_NOT_PREDECESSOR');
+  const affected = new Set<string>();
+  const downstream = (nodeId: string): void => {
+    if (affected.has(nodeId)) return;
+    affected.add(nodeId);
+    for (const node of Object.values(graph.nodes)) if (node.dependsOn.includes(nodeId)) downstream(node.id);
+  };
+  downstream(declared.targetNodeId);
+  for (const nodeId of affected) {
+    const node = graph.nodes[nodeId]!;
+    requireThat(node.config.humanReview !== true && node.config.workflowReopenProtected !== true, 'AI_DATA_AFTER_PROTECTED_NODE');
+    requireThat(node.status !== 'Running' && node.result?.status !== 'Waiting', 'AI_DATA_AFTER_UNSETTLED_NODE');
+  }
+  const prefix = 'after-reopen:' + canonicalOwnDataDigest([sourceNodeId, declared]).slice('sha256:'.length) + ':';
+  const previous = graph.patchHistory.filter(receipt => receipt.patchId.startsWith(prefix));
+  requireThat(previous.length < declared.maxReopens, 'AI_DATA_AFTER_BUDGET_EXHAUSTED');
+  const outputHash = canonicalOwnDataDigest(report);
+  const patchId = prefix + source.generation + ':' + outputHash;
+  requireThat(!graph.patchHistory.some(receipt => receipt.patchId === patchId), 'AI_DATA_AFTER_ALREADY_APPLIED');
+  const nodeResults = Object.fromEntries(Object.values(graph.nodes).filter(node => node.result).map(node => [node.id, {
+    nodeId: node.id, generation: node.generation, status: node.status,
+    ...(node.result!.output === undefined ? {} : {output: node.result!.output}),
+  }]));
+  const afterFeedback = normalizeFlowClosedObject({sourceNode: sourceNodeId, sourceGeneration: source.generation, outputHash, output: report, nodeResults});
+  return {
+    patchId,
+    generation: graph.currentGeneration + 1,
+    reason: '原生 after 准入的有界整改：' + sourceNodeId,
+    operations: [{op: 'update-node', nodeId: target.id, changes: {config: Object.fromEntries(Object.entries(normalizeFlowClosedObject({...target.config, afterFeedback})).map(([key, value]) => [key, eagerValue(value)]))}}],
+  };
+}

package/src/filesystem.ts

@@ -40,6 +40,7 @@ import {
   normalizeAIWorkflowProfileDurableState,
   normalizeFlowClosedObject,
   normalizeFlowClosedValue,
+  WorkflowDelegationSuspendedError,
   type FlowRunProfileAuthorityPort,
   type FlowRunProfileAuthorityRequest,
   type FrozenFlowRunProfileAuthority,
@@ -339,7 +340,8 @@ async function executeAIDataCheckpoint(
         return commitGraph((current) => {
           const node = current.nodes[nodeId];
           if (!node) throw new Error(`AI Data Workflow node ${nodeId} does not exist in the durable graph.`);
-          if (cause instanceof AIDataChildInvocationSuspendedError
+          if (findDelegationSuspension(cause)
+            || cause instanceof AIDataChildInvocationSuspendedError
             || cause instanceof AIDataChildInvocationTerminalFailure
             || findCheckpointObserverError(cause)) return current;
           return recordAIDataWorkflowNodeResult(current, nodeId, {
@@ -351,6 +353,7 @@ async function executeAIDataCheckpoint(
       },
     });
   } catch (error) {
+    if (findDelegationSuspension(error)) return { checkpoint: accepted, graph };
     const observerError = findCheckpointObserverError(error);
     if (observerError) throw observerError.cause;
     throw error;
@@ -371,6 +374,14 @@ class AIDataChildInvocationSuspendedError extends Error {
   }
 }
 
+function findDelegationSuspension(value: unknown, seen = new Set<unknown>()): WorkflowDelegationSuspendedError | undefined {
+  if (value instanceof WorkflowDelegationSuspendedError) return value;
+  if (!value || typeof value !== 'object' || seen.has(value)) return undefined;
+  seen.add(value);
+  if ('cause' in value) return findDelegationSuspension(value.cause, seen);
+  return undefined;
+}
+
 class AIDataChildInvocationTerminalFailure extends Error {
   constructor(nodeId: string, code: string, message: string) {
     super(`AI Data child invocation ${nodeId} failed (${code}): ${message}`);

package/src/index.ts

@@ -1,3 +1,4 @@
+export {planAIDataWorkflowAfterPatch} from './after.js';
 import type {
   AIDataWorkflowGraphPatch,
   AIDataWorkflowGraphPatchNodeSpec,
@@ -20,6 +21,7 @@ import type {
   AIDataWorkflowRunProfileState,
   AIDataWorkflowRuntime,
   AIAgentHostEffectPort,
+  AIAgentProcessorRuntime,
   FrozenAIAgentTaskBinding,
   AIWorkflowAuthoredEffects,
   AIWorkflowDefinitionRef,
@@ -52,15 +54,15 @@ import type {
   EagerDataFlowValue,
   LoadEagerDataFlowOptions,
 } from 'eager-data-flow-contract';
-import { loadEagerDataFlowProfileSources, loadEagerDataFlowProfileSourcesWithRuntime } from 'eager-data-flow-logic';
-import { createDefinitionStepSourceRuntime, type DefinitionStepAssemblyRuntime } from 'flow-step-space-logic';
 import {
   createAIWorkflowRuntimeContext,
   commitFlowRunCheckpoint,
-  defineAIDataWorkflow,
   loadFlowRunCheckpoint,
   resolveAIWorkflowReusePolicy,
   bindAIAgentProcessors,
+  bindWorkflowNodeTasks,
+  bindWorkflowTaskDelegation,
+  normalizeFlowClosedObject,
 } from 'ai-workflow-logic';
 import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 
@@ -178,7 +180,7 @@ export function createAIDataWorkflowAgentNodeRuntimeBinder(
     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 = bindAIAgentProcessors({
+    const agentRuntime = {
       checkpointRuntime: options.checkpointRuntime,
       checkpointKey: { instanceId: options.flowInstanceId, runId: options.runId },
       nodeId: identity.nodeId,
@@ -189,66 +191,23 @@ export function createAIDataWorkflowAgentNodeRuntimeBinder(
       taskBinding,
       effects: options.effects,
       ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
-    });
-    return Object.freeze({ ai: Object.freeze({ ...runtime.ai, effects }) });
+    } satisfies AIAgentProcessorRuntime;
+    const effects = bindAIAgentProcessors(agentRuntime);
+    const delegation=options.effects.delegation ? bindWorkflowTaskDelegation({
+        checkpointRuntime: options.checkpointRuntime,
+        checkpointKey: { instanceId: options.flowInstanceId, runId: options.runId },
+        nodeId: identity.nodeId, invocationKey: `${identity.nodeId}#${generation}`,
+        workflowKind: 'AIDataWorkflow', workflowRef: options.workflowRef, taskBinding,
+        visit: `generation:${generation}`, generation, effects: options.effects.delegation,
+      }) : undefined;
+    return Object.freeze({ ai: Object.freeze({ ...runtime.ai, effects,
+      tasks:bindWorkflowNodeTasks(agentRuntime,delegation),
+      ...(delegation?{delegation}:{}),
+    }) });
   };
 }
 
-export function defineEagerBackedAIDataWorkflow(
-  definition: AIDataWorkflowDefinitionBinding['definition'],
-): AIDataWorkflowDefinitionBinding {
-  return defineAIDataWorkflow(definition);
-}
-
-export interface AIDataWorkflowSourceLoadResult {
-  readonly binding?: AIDataWorkflowDefinitionBinding;
-  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 = {},
-): AIDataWorkflowSourceLoadResult {
-  const loaded = loadEagerDataFlowProfileSources(sources, {
-    ...options,
-    profileRoot: 'AIDataWorkflow',
-  });
-  if (!loaded.plan || loaded.diagnostics.length > 0) {
-    return { diagnostics: loaded.diagnostics };
-  }
-  return {
-    binding: defineEagerBackedAIDataWorkflow(loaded.plan),
-    diagnostics: loaded.diagnostics,
-  };
-}
+export * from './source-loader.js';
 
 export interface CreateAIDataWorkflowRunGraphOptions {
   readonly binding: AIDataWorkflowDefinitionBinding;
@@ -329,6 +288,7 @@ function cloneNodeResult(result: AIWorkflowNodeResult): AIWorkflowNodeResult {
     ...result,
     ...(result.semanticFingerprint ? { semanticFingerprint: cloneFingerprint(result.semanticFingerprint) } : {}),
     ...(result.reusedFrom ? { reusedFrom: { ...result.reusedFrom } } : {}),
+    ...(result.waitContext===undefined?{}:{waitContext:normalizeFlowClosedObject(result.waitContext)}),
   };
 }
 
@@ -1190,6 +1150,7 @@ export function recordAIDataWorkflowNodeResult(
       `AI Data Workflow result generation ${result.generation} does not match node ${nodeId}@${node.generation}`,
     );
   }
+  if(node.result?.waitContext!==undefined&&(result.waitContext===undefined||JSON.stringify(normalizeFlowClosedObject(node.result.waitContext))!==JSON.stringify(normalizeFlowClosedObject(result.waitContext))))throw new AIDataWorkflowRunGraphError(`AI Data Workflow native wait context ${nodeId}@${node.generation} is immutable`);
   if (node.result
     && (node.result.status === 'Succeeded' || node.result.status === 'Failed' || node.result.status === 'Reused')) {
     if (JSON.stringify(node.result) === JSON.stringify(result)) return cloneGraph(graph);

package/src/source-loader.ts

@@ -0,0 +1,72 @@
+import type { AIDataWorkflowDefinitionBinding } from "ai-workflow-contract";
+import { defineAIDataWorkflow } from "ai-workflow-logic/definitions";
+import type {
+  EagerDataFlowDiagnostic,
+  EagerDataFlowSourceCollection,
+  LoadEagerDataFlowOptions,
+} from "eager-data-flow-contract";
+import {
+  loadEagerDataFlowProfileSources,
+  loadEagerDataFlowProfileSourcesWithRuntime,
+} from "eager-data-flow-logic/browser";
+import {
+  createDefinitionStepSourceRuntime,
+  type DefinitionStepAssemblyRuntime,
+} from "flow-step-space-logic/browser";
+
+export function defineEagerBackedAIDataWorkflow(
+  definition: AIDataWorkflowDefinitionBinding["definition"],
+): AIDataWorkflowDefinitionBinding {
+  return defineAIDataWorkflow(definition);
+}
+
+export interface AIDataWorkflowSourceLoadResult {
+  readonly binding?: AIDataWorkflowDefinitionBinding;
+  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 = {},
+): AIDataWorkflowSourceLoadResult {
+  const loaded = loadEagerDataFlowProfileSources(sources, {
+    ...options,
+    profileRoot: "AIDataWorkflow",
+  });
+  if (!loaded.plan || loaded.diagnostics.length > 0) {
+    return { diagnostics: loaded.diagnostics };
+  }
+  return {
+    binding: defineEagerBackedAIDataWorkflow(loaded.plan),
+    diagnostics: loaded.diagnostics,
+  };
+}