ai-workflow-logic 0.1.9 → 0.2.0

package/src/agent-invocation.ts

@@ -121,8 +121,8 @@ function reserveName(ai: AIWorkflowProfileDurableState, receipt: AIAgentInvocati
 }
 
 function resolveSelector(ai: AIWorkflowProfileDurableState, selector: AIAgentSelector, config: AIAgentEffectConfig): AIAgentInstanceReference {
-  const instanceId = 'byInstanceId' in selector ? selector.byInstanceId : ai.instanceIdByName[selector.byInstanceName];
-  if (instanceId === undefined) fail('AI_AGENT_INSTANCE_NAME_NOT_FOUND', 'selector.byInstanceName', 'Named Agent instance does not exist.');
+  const instanceId = 'byId' in selector ? selector.byId : ai.instanceIdByName[selector.byName];
+  if (instanceId === undefined) fail('AI_AGENT_INSTANCE_NAME_NOT_FOUND', 'selector.byName', 'Named Agent instance does not exist.');
   const instance = ai.instancesById[instanceId];
   if (!instance) fail('AI_AGENT_INSTANCE_ID_NOT_FOUND', 'selector', 'Agent instance does not exist.');
   if (instance.instanceName !== undefined && ai.instanceIdByName[instance.instanceName] !== instance.instanceId) fail('AI_AGENT_INSTANCE_INDEX_CONFLICT', 'checkpoint.profile.ai', 'Agent instance indexes are not reciprocal.');

package/src/agent-resources.ts

@@ -1,5 +1,6 @@
 import type {
   AIAgentDefinitionProjection,
+  AIAgentMessagePrefixItemProjection,
   AIAgentMessageProjection,
   AIAgentMessageRole,
   AIWorkflowEffectPolicyProjection,
@@ -27,6 +28,8 @@ import { AIWorkflowResourceProjectionError } from './errors.js';
 
 const AGENT_SUBDOMAINS = Object.freeze([
   'Messages',
+  'MessagePrefix',
+  'ContextPipeline',
   'InputSchemaRef',
   'OutputSchemaRef',
   'ToolRefs',
@@ -144,12 +147,44 @@ function projectAgentDefinition(
   diagnostics: AIWorkflowResourceProjectionDiagnostic[],
 ): AIAgentDefinitionProjection | undefined {
   validateAllowedSubdomains(resource, AGENT_SUBDOMAINS, diagnostics);
-  const messagesNode = requiredSubdomain(resource, 'Messages', diagnostics);
+  const messagesNode = exactOptionalSubdomain(resource, 'Messages', diagnostics);
+  const messagePrefixNode = exactOptionalSubdomain(resource, 'MessagePrefix', diagnostics);
+  if (messagesNode && messagePrefixNode) {
+    diagnostics.push(diagnostic(
+      'AI_AGENT_MESSAGE_PREFIX_CONFLICT',
+      resource.documentUri,
+      'AIAgentDefinition must declare exactly one of legacy Messages or MessagePrefix.',
+    ));
+  } else if (!messagesNode && !messagePrefixNode) {
+    diagnostics.push(diagnostic(
+      'AI_AGENT_MESSAGE_PREFIX_MISSING',
+      resource.documentUri,
+      'AIAgentDefinition must declare legacy Messages or MessagePrefix.',
+    ));
+  }
   const toolRefsNode = requiredSubdomain(resource, 'ToolRefs', diagnostics);
   const materialPortRefsNode = requiredSubdomain(resource, 'MaterialPortRefs', diagnostics);
+  const projectedMessagePrefix = messagePrefixNode
+    ? projectMessagePrefix(resource, messagePrefixNode, resources, edges, diagnostics)
+    : undefined;
   const messages = messagesNode
     ? projectMessages(resource, messagesNode, resources, edges, diagnostics)
-    : [];
+    : projectedMessagePrefix
+      ? projectedMessagePrefix
+        .filter((item): item is Extract<AIAgentMessagePrefixItemProjection, { type: 'message' }> => item.type === 'message')
+        .map(({ type: _type, ...message }) => Object.freeze(message))
+      : [];
+  const messagePrefix = projectedMessagePrefix
+    ?? messages.map((message) => Object.freeze({ ...message, type: 'message' as const }));
+  const contextPipeline = projectOptionalTypedSubdomain(
+    resource,
+    'ContextPipeline',
+    resources,
+    'agent-context-pipeline',
+    edges,
+    diagnostics,
+    'AgentContextPipeline',
+  );
   const inputSchema = projectOptionalSchemaSubdomain(resource, 'InputSchemaRef', resources, 'agent-input-schema', edges, diagnostics);
   const outputSchema = projectOptionalSchemaSubdomain(resource, 'OutputSchemaRef', resources, 'agent-output-schema', edges, diagnostics);
   const tools = toolRefsNode
@@ -160,12 +195,14 @@ function projectAgentDefinition(
     ? projectTypedRefList(resource, materialPortRefsNode, 'MaterialPortRef', resources, 'agent-material-port', edges, diagnostics, 'MaterialPort')
     : [];
 
-  if (!messagesNode || !toolRefsNode || !materialPortRefsNode) return undefined;
+  if ((!messagesNode && !messagePrefixNode) || (messagesNode && messagePrefixNode) || !toolRefsNode || !materialPortRefsNode) return undefined;
   return Object.freeze({
     kind: 'AIAgentDefinition',
     fqn: resource.fqn ?? resource.resourceId,
     resource,
+    messagePrefix: Object.freeze(messagePrefix),
     messages: Object.freeze(messages),
+    ...(contextPipeline === undefined ? {} : { contextPipeline }),
     ...(inputSchema === undefined ? {} : { inputSchema }),
     ...(outputSchema === undefined ? {} : { outputSchema }),
     tools: Object.freeze(tools),
@@ -174,6 +211,67 @@ function projectAgentDefinition(
   });
 }
 
+function exactOptionalSubdomain(
+  resource: ResourceRecord,
+  name: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): ResourceNode | undefined {
+  const value = resource.node.subdomains[name];
+  if (!value) return undefined;
+  if (value.tag !== name) {
+    diagnostics.push(diagnostic(
+      'AI_RESOURCE_SUBDOMAIN_TAG_MISMATCH',
+      `${resource.documentUri}#${name}`,
+      `Subdomain ${name} must contain a ${name} node, got '${value.tag}'.`,
+    ));
+    return undefined;
+  }
+  return value;
+}
+
+function projectMessagePrefix(
+  resource: ResourceRecord,
+  prefixNode: ResourceNode,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIAgentMessagePrefixItemProjection[] {
+  const output: AIAgentMessagePrefixItemProjection[] = [];
+  const ids = new Set<string>();
+  prefixNode.body.forEach((value, index) => {
+    const location = `${resource.documentUri}#MessagePrefix:${index}`;
+    if (!isResourceNode(value) || (value.tag !== 'Message' && value.tag !== 'MessageSource')) {
+      diagnostics.push(diagnostic(
+        'AI_AGENT_MESSAGE_PREFIX_NODE_INVALID',
+        location,
+        'MessagePrefix may contain only Message or MessageSource nodes.',
+      ));
+      return;
+    }
+    const id = canonicalString(value.resourceId);
+    if (!id) {
+      diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ID_MISSING', location, `${value.tag} must declare an explicit #id.`));
+      return;
+    }
+    if (ids.has(id)) {
+      diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ID_DUPLICATE', location, `MessagePrefix id '${id}' is declared more than once.`));
+      return;
+    }
+    ids.add(id);
+    if (value.tag === 'Message') {
+      const message = projectMessageNode(resource, value, resources, edges, diagnostics, location);
+      if (message) output.push(Object.freeze({ ...message, type: 'message' }));
+      return;
+    }
+    validateAllowedNodeSubdomains(value, [], location, diagnostics);
+    const source = projectTypedValues(value.properties.kind, value.properties.ref, resources, location, diagnostics, 'AgentMessageSource');
+    if (!source) return;
+    edges.push(edge(resource.resourceId, source.resource.resourceId, 'agent-message-source'));
+    output.push(Object.freeze({ type: 'message-source', id, source }));
+  });
+  return output;
+}
+
 function projectMessages(
   resource: ResourceRecord,
   messagesNode: ResourceNode,
@@ -189,39 +287,45 @@ function projectMessages(
       diagnostics.push(diagnostic('AI_AGENT_MESSAGE_NODE_INVALID', location, 'Messages may contain only Message nodes.'));
       return;
     }
-    validateAllowedNodeSubdomains(value, ['SchemaRef'], location, diagnostics);
     const id = canonicalString(value.resourceId);
-    const role = value.properties.role;
-    if (!id) {
-      diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ID_MISSING', location, 'Message must declare an explicit #id.'));
-    } else if (ids.has(id)) {
+    if (id && ids.has(id)) {
       diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ID_DUPLICATE', location, `Message id '${id}' is declared more than once.`));
-    } else {
-      ids.add(id);
+      return;
     }
-    if (!isMessageRole(role)) {
-      diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ROLE_INVALID', location, 'Message role must be system, developer, user, or assistant.'));
+    if (id) {
+      ids.add(id);
     }
-    const prompt = projectTypedValues(
-      value.properties.promptKind,
-      value.properties.promptRef,
-      resources,
-      location,
-      diagnostics,
-    );
-    if (prompt) edges.push(edge(resource.resourceId, prompt.resource.resourceId, 'agent-message-prompt'));
-    const schemaNode = value.subdomains.SchemaRef;
-    const schema = schemaNode?.tag === 'SchemaRef'
-      ? projectMessageSchemaRefNode(schemaNode, resources, `${location}#SchemaRef`, diagnostics)
-      : undefined;
-    if (schemaNode && schemaNode.tag !== 'SchemaRef') diagnostics.push(diagnostic('AI_RESOURCE_SUBDOMAIN_TAG_MISMATCH', `${location}#SchemaRef`, `Subdomain SchemaRef must contain a SchemaRef node, got '${schemaNode.tag}'.`));
-    if (schema) edges.push(edge(resource.resourceId, schema.resource.resourceId, 'agent-message-schema'));
-    if (!id || !isMessageRole(role) || !prompt) return;
-    output.push(Object.freeze({ id, role, prompt, ...(schema === undefined ? {} : { schema }) }));
+    const message = projectMessageNode(resource, value, resources, edges, diagnostics, location);
+    if (message) output.push(message);
   });
   return output;
 }
 
+function projectMessageNode(
+  resource: ResourceRecord,
+  value: ResourceNode,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+  location: string,
+): AIAgentMessageProjection | undefined {
+  validateAllowedNodeSubdomains(value, ['SchemaRef'], location, diagnostics);
+  const id = canonicalString(value.resourceId);
+  const role = value.properties.role;
+  if (!id) diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ID_MISSING', location, 'Message must declare an explicit #id.'));
+  if (!isMessageRole(role)) diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ROLE_INVALID', location, 'Message role must be system, developer, user, or assistant.'));
+  const prompt = projectTypedValues(value.properties.promptKind, value.properties.promptRef, resources, location, diagnostics);
+  if (prompt) edges.push(edge(resource.resourceId, prompt.resource.resourceId, 'agent-message-prompt'));
+  const schemaNode = value.subdomains.SchemaRef;
+  const schema = schemaNode?.tag === 'SchemaRef'
+    ? projectMessageSchemaRefNode(schemaNode, resources, `${location}#SchemaRef`, diagnostics)
+    : undefined;
+  if (schemaNode && schemaNode.tag !== 'SchemaRef') diagnostics.push(diagnostic('AI_RESOURCE_SUBDOMAIN_TAG_MISMATCH', `${location}#SchemaRef`, `Subdomain SchemaRef must contain a SchemaRef node, got '${schemaNode.tag}'.`));
+  if (schema) edges.push(edge(resource.resourceId, schema.resource.resourceId, 'agent-message-schema'));
+  if (!id || !isMessageRole(role) || !prompt) return undefined;
+  return Object.freeze({ id, role, prompt, ...(schema === undefined ? {} : { schema }) });
+}
+
 function projectTypedRefList(
   owner: ResourceRecord,
   list: ResourceNode,
@@ -265,6 +369,7 @@ function projectOptionalTypedSubdomain(
   relation: AIWorkflowAgentResourceRelation,
   edges: ResourceDependencyEdge[],
   diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+  expectedKind?: string,
 ): AIWorkflowTypedResourceRef | undefined {
   const node = owner.node.subdomains[name];
   if (!node) return undefined;
@@ -272,7 +377,7 @@ function projectOptionalTypedSubdomain(
     diagnostics.push(diagnostic('AI_RESOURCE_SUBDOMAIN_TAG_MISMATCH', `${owner.documentUri}#${name}`, `Subdomain ${name} must contain a ${name} node, got '${node.tag}'.`));
     return undefined;
   }
-  const typedRef = projectTypedRefNode(node, resources, `${owner.documentUri}#${name}`, diagnostics);
+  const typedRef = projectTypedRefNode(node, resources, `${owner.documentUri}#${name}`, diagnostics, expectedKind);
   if (typedRef) edges.push(edge(owner.resourceId, typedRef.resource.resourceId, relation));
   return typedRef;
 }

package/src/agent-state.ts

@@ -115,13 +115,13 @@ function optionalStringArray(value: unknown, location: string): readonly string[
 }
 
 export function normalizeAIAgentSelector(value: unknown, location = 'selector'): AIAgentSelector {
-  const input = record(value, [], ['byInstanceId', 'byInstanceName'], location);
-  const hasId = Object.prototype.hasOwnProperty.call(input, 'byInstanceId');
-  const hasName = Object.prototype.hasOwnProperty.call(input, 'byInstanceName');
+  const input = record(value, [], ['byId', 'byName'], location);
+  const hasId = Object.prototype.hasOwnProperty.call(input, 'byId');
+  const hasName = Object.prototype.hasOwnProperty.call(input, 'byName');
   if (hasId === hasName) fail('AI_AGENT_SELECTOR_EXACTLY_ONE', location, 'Selector must contain exactly one supported key.');
   return Object.freeze(hasId
-    ? { byInstanceId: identity(input.byInstanceId, `${location}.byInstanceId`) }
-    : { byInstanceName: identity(input.byInstanceName, `${location}.byInstanceName`) });
+    ? { byId: identity(input.byId, `${location}.byId`) }
+    : { byName: identity(input.byName, `${location}.byName`) });
 }
 
 export function normalizeAIAgentEffectConfig(value: unknown, location = 'config'): AIAgentEffectConfig {

package/src/checkpoint-store.ts

@@ -399,7 +399,9 @@ function validateAIDataProfileTransition(
         throw new FlowRunCheckpointTransitionError(`AI Data patch operation ${operation.op} is unsupported.`);
       }
       for (const [field, expected] of Object.entries(operation.changes)) {
-        if (!sameClosedValue(candidate[field as keyof typeof candidate], expected)) {
+        const actual = (candidate as Readonly<Record<string, unknown>>)[field];
+        if (field === 'subflow' && expected === null && actual === undefined) continue;
+        if (!sameClosedValue(actual, expected)) {
           throw new FlowRunCheckpointTransitionError(`AI Data update-node ${nodeId} does not project declared ${field}.`);
         }
       }

package/src/filesystem.ts

@@ -4,12 +4,32 @@ import {
 } from 'halfcode-compiler.xnl/resource-core';
 import type { LoadedAIWorkflowResourcePackage } from 'ai-workflow-contract';
 import { projectAIWorkflowAppBundles } from './index.js';
+import {
+  resolveAIWorkflowResourceTree,
+  type AIWorkflowResourceResolutionContext,
+} from './resource-resolution.js';
+
+export {
+  AI_WORKFLOW_RESOURCE_SCHEMA_VALIDATOR,
+  DEPA_AI_RESOURCE_READER_PROFILE_ID,
+  createAIWorkflowResourceResolutionContext,
+  createResolvedAIWorkflowContentIdentityIndex,
+  resolveAIWorkflowResourceTree,
+} from './resource-resolution.js';
+export type { AIWorkflowResourceResolutionContext } from './resource-resolution.js';
+
+export interface LoadAIWorkflowResourcePackageOptions extends LoadResourceTreeOptions {
+  readonly resolutionContext?: AIWorkflowResourceResolutionContext;
+}
 
 export async function loadAIWorkflowResourcePackage(
-  options: LoadResourceTreeOptions,
+  options: LoadAIWorkflowResourcePackageOptions,
 ): Promise<LoadedAIWorkflowResourcePackage> {
-  const tree = await loadResourceTree(options);
+  const { resolutionContext, ...loadOptions } = options;
+  const authoredTree = await loadResourceTree(loadOptions);
+  const tree = resolveAIWorkflowResourceTree(authoredTree, resolutionContext);
   return Object.freeze({
+    authoredTree,
     tree,
     appBundles: projectAIWorkflowAppBundles(tree.registry, {
       packageResourceId: tree.manifest.resourceId,

package/src/index.ts

@@ -36,6 +36,21 @@ import { AIWorkflowFoundationError, AIWorkflowResourceProjectionError } from './
 
 export { AIWorkflowFoundationError, AIWorkflowResourceProjectionError } from './errors.js';
 export { projectAIWorkflowAgentResources } from './agent-resources.js';
+export {
+  AIAgentDefinitionSelectionError,
+  admitAIAgentDefinitionSelection,
+  freezeSelectedAIAgentTaskBinding,
+  normalizeAIAgentTaskRequirement,
+  projectAIAgentDefinitionCandidates,
+  reconcileAuthoredAIAgentDefinition,
+} from './agent-definition-selection.js';
+export type {
+  AIAgentDefinitionSelectionErrorCode,
+  AdmitAIAgentDefinitionSelectionInput,
+  FreezeSelectedAIAgentTaskBindingInput,
+  ProjectAIAgentDefinitionCandidatesInput,
+  ReconcileAuthoredAIAgentDefinitionInput,
+} from './agent-definition-selection.js';
 export {
   FlowRunContractValidationError,
   normalizeAIWorkflowProfileDurableState,

package/src/resource-resolution.ts

@@ -0,0 +1,121 @@
+import Ajv, { type ValidateFunction } from 'ajv';
+import {
+  DEPA_AI_RESOURCE_KIND_OWNERS,
+  DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS,
+  DEPA_AI_RESOURCE_KIND_SPEC_REVISIONS,
+} from 'ai-workflow-contract';
+import type {
+  AuthoredResourceTree,
+  JsonSchemaValidator,
+  KindSpecRevision,
+  PortableSpec,
+  ResolvedResourceTree,
+  ResourceContentIdentity,
+} from 'halfcode-compiler.xnl/resource-core';
+import { createResourceContentIdentity } from 'halfcode-compiler.xnl/resource-core';
+import {
+  CORE_KIND_READER_REGISTRATIONS,
+  CORE_KIND_SPEC_REVISIONS,
+  CORE_KIND_SUBJECT_OWNERS,
+  KindContractRegistry,
+  KindReaderRegistry,
+  SpecResolutionRegistry,
+  createReaderProfile,
+  resolveResourceTree,
+  type ReaderProfile,
+} from 'halfcode-compiler.xnl/kind-definition';
+
+export const DEPA_AI_RESOURCE_READER_PROFILE_ID = 'depa.flows.ai-resources.v1' as const;
+
+export interface AIWorkflowResourceResolutionContext {
+  readonly contracts: KindContractRegistry;
+  readonly readers: KindReaderRegistry;
+  readonly readerProfile: ReaderProfile;
+  readonly resolutions: SpecResolutionRegistry;
+  readonly validator: JsonSchemaValidator;
+}
+
+const ajv = new Ajv({ allErrors: true, strict: false, validateFormats: false });
+const compiledSchemas = new Map<string, ValidateFunction>();
+
+export const AI_WORKFLOW_RESOURCE_SCHEMA_VALIDATOR: JsonSchemaValidator = Object.freeze({
+  validate(revision: KindSpecRevision, value: PortableSpec): readonly string[] {
+    let validate = compiledSchemas.get(revision.contractFingerprint);
+    if (!validate) {
+      validate = ajv.compile(revision.specSchema);
+      compiledSchemas.set(revision.contractFingerprint, validate);
+    }
+    return validate(value)
+      ? Object.freeze([])
+      : Object.freeze((validate.errors ?? []).map((error) =>
+          `${error.instancePath || '/'} ${error.message ?? 'invalid'}`));
+  },
+});
+
+export function createAIWorkflowResourceResolutionContext(
+  validator: JsonSchemaValidator = AI_WORKFLOW_RESOURCE_SCHEMA_VALIDATOR,
+): AIWorkflowResourceResolutionContext {
+  const contracts = new KindContractRegistry();
+  for (const owner of [...CORE_KIND_SUBJECT_OWNERS, ...DEPA_AI_RESOURCE_KIND_OWNERS]) {
+    contracts.registerOwner(owner);
+  }
+  for (const revision of [...CORE_KIND_SPEC_REVISIONS, ...DEPA_AI_RESOURCE_KIND_SPEC_REVISIONS]) {
+    contracts.registerRevision(revision);
+  }
+
+  const readerRegistrations = [
+    ...CORE_KIND_READER_REGISTRATIONS,
+    ...DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS,
+  ];
+  const readers = new KindReaderRegistry();
+  for (const reader of readerRegistrations) readers.register(reader);
+  const readerProfile = createReaderProfile(
+    DEPA_AI_RESOURCE_READER_PROFILE_ID,
+    readerRegistrations.map((reader) => ({
+      readerId: reader.readerId,
+      subjectFqn: reader.subjectFqn,
+      readerSpecVersion: reader.readerSpecVersion,
+      contractFingerprint: reader.contractFingerprint,
+      readerImplementationFingerprint: reader.readerImplementationFingerprint,
+    })),
+  );
+  return Object.freeze({
+    contracts,
+    readers,
+    readerProfile,
+    resolutions: new SpecResolutionRegistry(contracts),
+    validator,
+  });
+}
+
+export function resolveAIWorkflowResourceTree(
+  tree: AuthoredResourceTree,
+  context: AIWorkflowResourceResolutionContext = createAIWorkflowResourceResolutionContext(),
+): ResolvedResourceTree {
+  return resolveResourceTree({ tree, ...context });
+}
+
+/**
+ * Projects Halfcode's exact resolved content identity into the public dependency
+ * snapshot shape. The digest is still constructed by Halfcode; depa-flows only
+ * chooses the resolved receipt identity as the authority input.
+ */
+export function createResolvedAIWorkflowContentIdentityIndex(
+  tree: ResolvedResourceTree,
+): ReadonlyMap<string, ResourceContentIdentity> {
+  const entries: Array<readonly [string, ResourceContentIdentity]> = [];
+  for (const records of tree.registry.byKind.values()) {
+    for (const record of records) {
+      entries.push([record.resourceId, createResourceContentIdentity({
+        resourceId: record.resourceId,
+        authorityDigest: record.effectiveContentDigest,
+      })]);
+    }
+  }
+  entries.sort(([left], [right]) => compareCodeUnits(left, right));
+  return new Map(entries);
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}