ai-workflow-contract 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-contract",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "description": "Shared AI workflow contracts over WorkCtrlFlow and EagerDataFlow substrates",
   "type": "module",
@@ -9,15 +9,14 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "eager-data-flow-contract": "0.1.0",
+    "eager-data-flow-contract": "0.1.1",
     "halfcode-compiler.xnl": "0.2.2",
-    "work-ctrl-flow-contract": "0.1.0"
+    "work-ctrl-flow-contract": "0.1.1"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.com"
+    "access": "public"
   }
 }

package/src/index.ts

@@ -5,9 +5,34 @@ import type {
   ResourceRecord,
   ResourceRegistry,
   ResourceTree,
+  ResourceValue,
   Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
-import type { FlowBundleSpec, WorkCtrlFlowRuntime } from 'work-ctrl-flow-contract';
+import type {
+  FlowBundleSpec,
+  FlowClosedObject,
+  FlowClosedValue,
+  FlowRunCheckpoint,
+  FlowRunCheckpointKey,
+  FlowRunCheckpointRuntime as GenericFlowRunCheckpointRuntime,
+  WorkCtrlFlowRuntime,
+} from 'work-ctrl-flow-contract';
+
+export {
+  FLOW_INSTANCE_SCHEMA_VERSION,
+  FLOW_RUN_CHECKPOINT_SCHEMA_VERSION,
+  type FlowClosedArray,
+  type FlowClosedObject,
+  type FlowClosedPrimitive,
+  type FlowClosedValue,
+  type FlowDefinitionArtifactIdentity,
+  type FlowDefinitionProvenance,
+  type FlowInstanceDescriptor,
+  type FlowRunCheckpoint,
+  type FlowRunCheckpointCommit,
+  type FlowRunCheckpointKey,
+  type FlowRunCheckpointStore,
+  } from 'work-ctrl-flow-contract';
 
 export type AIWorkflowKind = 'AICtrlWorkflow' | 'AIDataWorkflow';
 
@@ -144,11 +169,27 @@ export interface AIWorkflowTypedResourceRef {
   readonly resource: ResourceRecord;
 }
 
+export interface AIWorkflowMessageSchemaProjection extends AIWorkflowTypedResourceRef {
+  readonly kind: 'MessageSchema';
+  readonly schema: Readonly<Record<string, ResourceValue>>;
+}
+
+export type AIWorkflowEffectToolMode = 'declared-only' | 'none';
+
+export interface AIWorkflowEffectPolicyProjection extends AIWorkflowTypedResourceRef {
+  readonly kind: 'EffectPolicy';
+  readonly toolMode: AIWorkflowEffectToolMode;
+}
+
+export interface AIWorkflowMaterialValueProjection extends AIWorkflowTypedResourceRef {
+  readonly value: ResourceValue;
+}
+
 export interface AIAgentMessageProjection {
   readonly id: string;
   readonly role: AIAgentMessageRole;
   readonly prompt: AIWorkflowTypedResourceRef;
-  readonly schema?: AIWorkflowTypedResourceRef;
+  readonly schema?: AIWorkflowMessageSchemaProjection;
 }
 
 export interface MaterialPortProjection {
@@ -158,7 +199,7 @@ export interface MaterialPortProjection {
   readonly materialKind: string;
   readonly required: boolean;
   readonly cardinality: MaterialCardinality;
-  readonly schema?: AIWorkflowTypedResourceRef;
+  readonly schema?: AIWorkflowMessageSchemaProjection;
 }
 
 export interface AIAgentDefinitionProjection {
@@ -166,10 +207,10 @@ export interface AIAgentDefinitionProjection {
   readonly fqn: string;
   readonly resource: ResourceRecord;
   readonly messages: readonly AIAgentMessageProjection[];
-  readonly inputSchema?: AIWorkflowTypedResourceRef;
-  readonly outputSchema?: AIWorkflowTypedResourceRef;
+  readonly inputSchema?: AIWorkflowMessageSchemaProjection;
+  readonly outputSchema?: AIWorkflowMessageSchemaProjection;
   readonly tools: readonly AIWorkflowTypedResourceRef[];
-  readonly effectPolicy?: AIWorkflowTypedResourceRef;
+  readonly effectPolicy?: AIWorkflowEffectPolicyProjection;
   readonly materialPorts: readonly AIWorkflowTypedResourceRef[];
 }
 
@@ -186,7 +227,7 @@ export interface MaterialBindingProjection {
   readonly resource: ResourceRecord;
   readonly task: AIWorkflowAgentTaskRef;
   readonly port: MaterialPortProjection;
-  readonly material: AIWorkflowTypedResourceRef;
+  readonly material: AIWorkflowMaterialValueProjection;
 }
 
 export interface AIWorkflowAgentResourceProjection {
@@ -204,6 +245,15 @@ export interface AIWorkflowRunResourceFreezeReceipt {
   readonly semanticFingerprint: Sha256Digest;
 }
 
+/** In-memory proof projected only from an admitted run-resource freeze receipt. */
+export interface FrozenAIAgentTaskBinding {
+  readonly schemaVersion: 'ai-workflow.frozen-agent-task-binding/v1';
+  readonly task: AIWorkflowAgentTaskRef;
+  readonly semanticFingerprint: Sha256Digest;
+  readonly snapshotRevision: Sha256Digest;
+  readonly closureResourceIds: readonly string[];
+}
+
 export type AIWorkflowNodeType =
   | 'agent'
   | 'data'
@@ -331,6 +381,184 @@ export interface AIWorkflowRunState {
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
 
+export interface WorkCtrlFlowRunProfileState<Snapshot = FlowClosedObject> {
+  readonly kind: 'WorkCtrlFlow';
+  readonly snapshot: Snapshot;
+}
+
+export const AI_AGENT_CHECKPOINT_STATE_SCHEMA_VERSION = 'depa.ai-agent-state/v1' as const;
+
+/** Opaque identity owned by an external agent/runtime authority. */
+export interface AIWorkflowExternalRuntimeReference {
+  readonly authority: string;
+  readonly instanceId: string;
+  readonly instanceName?: string;
+  readonly sessionId?: string;
+  readonly agentDefinitionRef?: `resource://${string}`;
+  readonly metadata?: FlowClosedObject;
+}
+
+/** Audit linkage without copying external conversation or execution history. */
+export interface AIWorkflowExecutionReceipt {
+  readonly nodeId: string;
+  readonly externalRuntimeRef: string;
+  readonly metadata?: FlowClosedObject;
+}
+
+export type AIAgentSelector =
+  | { readonly byInstanceId: string; readonly byInstanceName?: never }
+  | { readonly byInstanceName: string; readonly byInstanceId?: never };
+
+export interface AIAgentInvocation<Input extends FlowClosedValue = FlowClosedValue> {
+  readonly kind: 'ai.agent';
+  readonly payload: Input;
+  readonly metadata?: FlowClosedObject;
+}
+
+export interface AIAgentEffectConfig {
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly instanceName?: string;
+  readonly materialRefs?: readonly string[];
+  readonly effectPolicy?: FlowClosedObject;
+}
+
+export interface AIAgentInstanceReference {
+  readonly authority: string;
+  readonly instanceId: string;
+  readonly instanceName?: string;
+  readonly sessionId?: string;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly metadata?: FlowClosedObject;
+}
+
+export interface AIAgentInvocationReceipt {
+  readonly invocationKey: string;
+  readonly nodeId: string;
+  readonly status: 'pending' | 'completed';
+  readonly mode: 'new' | 'targeted';
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly instanceName?: string;
+  readonly instanceId?: string;
+  readonly generation?: number;
+  readonly input: FlowClosedValue;
+  /** Exact static/invocation semantics bound to this idempotency key. */
+  readonly semanticFacts: FlowClosedObject;
+  readonly metadata?: FlowClosedObject;
+  readonly output?: FlowClosedValue;
+  readonly hostReceipt?: FlowClosedObject;
+}
+
+export interface AIAgentRunResult<Output extends FlowClosedValue = FlowClosedValue> {
+  readonly output: Output;
+  readonly instance: AIAgentInstanceReference;
+  readonly receipt: {
+    readonly invocationKey: string;
+    readonly nodeId: string;
+    readonly status: 'pending' | 'completed';
+  };
+}
+
+export interface AIAgentHostRunRequest<Input extends FlowClosedValue = FlowClosedValue> {
+  readonly invocationKey: string;
+  readonly flowInstanceId: string;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly generation?: number;
+  readonly input: Input;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly instanceName?: string;
+  readonly materialRefs?: readonly string[];
+  readonly effectPolicy?: FlowClosedObject;
+  readonly signal?: AbortSignal;
+  readonly metadata?: FlowClosedObject;
+}
+
+export interface AIAgentHostTargetedRunRequest<Input extends FlowClosedValue = FlowClosedValue>
+  extends AIAgentHostRunRequest<Input> {
+  readonly instance: AIAgentInstanceReference;
+}
+
+export interface AIAgentHostRunResult<Output extends FlowClosedValue = FlowClosedValue> {
+  readonly output: Output;
+  readonly instance: Omit<AIAgentInstanceReference, 'agentDefinitionRef'> & {
+    readonly agentDefinitionRef?: `resource://${string}`;
+  };
+  readonly hostReceipt?: FlowClosedObject;
+}
+
+/** Host-owned typed effect boundary. It is deliberately not a generic dispatcher. */
+export interface AIAgentHostEffectPort {
+  runAgent(request: AIAgentHostRunRequest): Promise<AIAgentHostRunResult>;
+  runTargetedAgent(request: AIAgentHostTargetedRunRequest): Promise<AIAgentHostRunResult>;
+}
+
+export interface AIAgentProcessorRuntime {
+  readonly checkpointRuntime: FlowRunCheckpointRuntime;
+  readonly checkpointKey: FlowRunCheckpointKey;
+  readonly nodeId: string;
+  readonly invocationKey: string;
+  readonly workflowKind: AIWorkflowDefinitionResourceKind;
+  readonly workflowRef: `resource://${string}`;
+  readonly taskBinding: AIWorkflowAgentTaskRef;
+  readonly generation?: number;
+  readonly effects: AIAgentHostEffectPort;
+  readonly signal?: AbortSignal;
+  readonly metadata?: FlowClosedObject;
+}
+
+export interface AIWorkflowAuthoredEffects {
+  runAgent<Input extends FlowClosedValue = FlowClosedValue, Output extends FlowClosedValue = FlowClosedValue>(
+    input: Input,
+    config: AIAgentEffectConfig,
+  ): Promise<AIAgentRunResult<Output>>;
+  runTargetedAgent<Input extends FlowClosedValue = FlowClosedValue, Output extends FlowClosedValue = FlowClosedValue>(
+    selector: AIAgentSelector,
+    invocation: AIAgentInvocation<Input>,
+    config: AIAgentEffectConfig,
+  ): Promise<AIAgentRunResult<Output>>;
+}
+
+/** Closed durable AI profile state stored inside the Flow checkpoint owner. */
+export interface AIWorkflowProfileDurableState {
+  readonly schemaVersion: typeof AI_AGENT_CHECKPOINT_STATE_SCHEMA_VERSION;
+  readonly instancesById: Readonly<Record<string, AIAgentInstanceReference>>;
+  readonly instanceIdByName: Readonly<Record<string, string>>;
+  readonly invocationsByKey: Readonly<Record<string, AIAgentInvocationReceipt>>;
+}
+
+/** Explicit read-only input accepted only by the one-way legacy upgrade helper. */
+export interface LegacyAIWorkflowProfileDurableState {
+  readonly externalRuntimeRefs: Readonly<Record<string, AIWorkflowExternalRuntimeReference>>;
+  readonly receipts: readonly AIWorkflowExecutionReceipt[];
+}
+
+export interface AICtrlWorkflowRunProfileState<
+  Snapshot = FlowClosedObject,
+  AIState = AIWorkflowProfileDurableState,
+> {
+  readonly kind: 'AICtrlWorkflow';
+  readonly snapshot: Snapshot;
+  readonly ai: AIState;
+}
+
+export interface AIDataWorkflowRunProfileState<
+  RunGraph = FlowClosedObject,
+  AIState = AIWorkflowProfileDurableState,
+> {
+  readonly kind: 'AIDataWorkflow';
+  readonly runGraph: RunGraph;
+  readonly ai: AIState;
+}
+
+export type FlowRunProfileState =
+  | WorkCtrlFlowRunProfileState
+  | AICtrlWorkflowRunProfileState
+  | AIDataWorkflowRunProfileState;
+
+export type AIWorkflowFlowRunCheckpoint = FlowRunCheckpoint<FlowRunProfileState>;
+
+export type FlowRunCheckpointRuntime = GenericFlowRunCheckpointRuntime<FlowRunProfileState>;
+
 export interface AIWorkflowReusableNodeResultRequest {
   readonly run: AIWorkflowRunRef;
   readonly nodeId: string;
@@ -339,15 +567,23 @@ export interface AIWorkflowReusableNodeResultRequest {
   readonly policy: AIWorkflowEffectiveReusePolicy;
 }
 
-export interface AIWorkflowStateStore {
+/** Read-only, rebuildable view over canonical FlowRunCheckpoint facts. */
+export interface AIWorkflowStateProjection {
   loadRunState(ref: AIWorkflowRunRef): Promise<AIWorkflowRunState | undefined>;
-  saveRunState(state: AIWorkflowRunState): Promise<void>;
-  appendRunEvent(ref: AIWorkflowRunRef, event: AIWorkflowRunEvent): Promise<void>;
   findReusableNodeResult?(
     request: AIWorkflowReusableNodeResultRequest,
   ): Promise<AIWorkflowNodeResult | undefined>;
 }
 
+/**
+ * @deprecated Writable legacy/derived projection compatibility only. Canonical
+ * Ctrl/Data execution writes exclusively through FlowRunCheckpointStore.
+ */
+export interface AIWorkflowStateStore extends AIWorkflowStateProjection {
+  saveRunState(state: AIWorkflowRunState): Promise<void>;
+  appendRunEvent(ref: AIWorkflowRunRef, event: AIWorkflowRunEvent): Promise<void>;
+}
+
 export interface AIWorkflowEffectRequest<Input = unknown> {
   readonly effectId: string;
   readonly operation: string;
@@ -403,25 +639,30 @@ export interface AIWorkflowEffectResult<Output = unknown> {
 }
 
 export interface AIWorkflowRuntimeContext<
-  Effects extends AIWorkflowEffectProvider = AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore = AIWorkflowStateStore,
+  Effects extends AIWorkflowEffectProvider | AIWorkflowAuthoredEffects = AIWorkflowEffectProvider,
+  Store extends AIWorkflowStateProjection = AIWorkflowStateProjection,
 > {
   readonly roots: AIWorkflowRuntimeRoots;
   readonly effects: Effects;
+  /** Historical field name; canonical runtimes expose a read-only projection here. */
   readonly stateStore: Store;
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
 
+/** Authored code surface; generic infrastructure dispatch is intentionally absent. */
+export type AIWorkflowAuthoredRuntimeContext<Store extends AIWorkflowStateProjection = AIWorkflowStateProjection> =
+  AIWorkflowRuntimeContext<AIWorkflowAuthoredEffects, Store>;
+
 export interface AICtrlWorkflowRuntime<
-  Effects extends AIWorkflowEffectProvider = AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore = AIWorkflowStateStore,
+  Effects extends AIWorkflowEffectProvider | AIWorkflowAuthoredEffects = AIWorkflowEffectProvider,
+  Store extends AIWorkflowStateProjection = AIWorkflowStateProjection,
 > extends WorkCtrlFlowRuntime {
   readonly ai: AIWorkflowRuntimeContext<Effects, Store>;
 }
 
 export interface AIDataWorkflowRuntime<
-  Effects extends AIWorkflowEffectProvider = AIWorkflowEffectProvider,
-  Store extends AIWorkflowStateStore = AIWorkflowStateStore,
+  Effects extends AIWorkflowEffectProvider | AIWorkflowAuthoredEffects = AIWorkflowEffectProvider,
+  Store extends AIWorkflowStateProjection = AIWorkflowStateProjection,
 > {
   readonly ai: AIWorkflowRuntimeContext<Effects, Store>;
 }