ai-workflow-logic 0.1.11 → 0.2.1

package/src/resource-resolution.ts

@@ -0,0 +1,145 @@
+import Ajv, { type ValidateFunction } from 'ajv';
+import {
+  DEPA_AI_RESOURCE_KIND_OWNERS,
+  DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS,
+  DEPA_AI_RESOURCE_KIND_SPEC_REVISIONS,
+  DEPA_AI_RESOURCE_KIND_SPEC_RESOLUTIONS,
+} from 'ai-workflow-contract';
+import type {
+  AuthoredResourceTree,
+  JsonSchemaValidator,
+  KindSpecRevision,
+  PortableSpec,
+  ResolvedResourceTree,
+  ResourceContentIdentity,
+} from 'halfcode-compiler.xnl/resource-core';
+import { createResourceContentIdentity, digestCanonical } 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,
+  tree?: AuthoredResourceTree,
+): AIWorkflowResourceResolutionContext {
+  const contracts = new KindContractRegistry();
+  for (const owner of [...CORE_KIND_SUBJECT_OWNERS, ...DEPA_AI_RESOURCE_KIND_OWNERS]) {
+    contracts.registerOwner(owner);
+  }
+  // A package's declared revision set is an exact Halfcode admission boundary.
+  // Old packages keep their original v1 profile; new packages declare v1+v2.
+  const revisions = [...CORE_KIND_SPEC_REVISIONS, ...DEPA_AI_RESOURCE_KIND_SPEC_REVISIONS].filter(revision => {
+    const definition = tree && [...tree.registry.kindDefinitions.values()].find(item => item.subjectFqn === revision.subjectFqn);
+    return definition
+      ? definition.specRevisions.some(item => item.specVersion === revision.specVersion)
+      : revision.specVersion === 1;
+  });
+  for (const revision of revisions) {
+    contracts.registerRevision(revision);
+  }
+  const hasRevision = (subjectFqn: string, specVersion: number): boolean => revisions.some(revision =>
+    revision.subjectFqn === subjectFqn && revision.specVersion === specVersion);
+
+  const readerRegistrations = [
+    ...CORE_KIND_READER_REGISTRATIONS,
+    ...DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS,
+  ].filter(reader => hasRevision(reader.subjectFqn, reader.readerSpecVersion));
+  const readers = new KindReaderRegistry();
+  for (const reader of readerRegistrations) readers.register(reader);
+  const selectedReaders = readerRegistrations.filter(reader => !readerRegistrations.some(other =>
+    other.subjectFqn === reader.subjectFqn && other.readerSpecVersion > reader.readerSpecVersion));
+  const targets = selectedReaders.map((reader) => ({
+    readerId: reader.readerId,
+    subjectFqn: reader.subjectFqn,
+    readerSpecVersion: reader.readerSpecVersion,
+    contractFingerprint: reader.contractFingerprint,
+    readerImplementationFingerprint: reader.readerImplementationFingerprint,
+  }));
+  const readerProfile = createReaderProfile(
+    targets.some(target => target.readerSpecVersion !== 1)
+      ? `${DEPA_AI_RESOURCE_READER_PROFILE_ID}/${digestCanonical(targets)}`
+      : DEPA_AI_RESOURCE_READER_PROFILE_ID,
+    targets,
+  );
+  const resolutions = new SpecResolutionRegistry(contracts);
+  for (const resolution of DEPA_AI_RESOURCE_KIND_SPEC_RESOLUTIONS) {
+    if (hasRevision(resolution.subjectFqn, resolution.writerSpecVersion)
+      && hasRevision(resolution.subjectFqn, resolution.readerSpecVersion)) {
+      resolutions.register(resolution);
+    }
+  }
+  return Object.freeze({
+    contracts,
+    readers,
+    readerProfile,
+    resolutions,
+    validator,
+  });
+}
+
+export function resolveAIWorkflowResourceTree(
+  tree: AuthoredResourceTree,
+  context?: AIWorkflowResourceResolutionContext,
+): ResolvedResourceTree {
+  return resolveResourceTree({ tree, ...(context ?? createAIWorkflowResourceResolutionContext(undefined, tree)) });
+}
+
+/**
+ * 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;
+}

package/src/run-freeze.ts

@@ -7,6 +7,8 @@ import type {
   AIWorkflowRunResourceFreezeReceipt,
   MaterialBindingProjection,
   MaterialPortProjection,
+  CompiledAIAgentCodeExecution,
+  AIAgentCodeExecutionIdentity,
 } from 'ai-workflow-contract';
 import {
   normalizeHolonTaskTarget,
@@ -18,16 +20,25 @@ import {
   buildResourceDependencySnapshot,
   composeLayeredResourceRegistry,
   loadResourceTree,
-  resolveEffectiveResourceContentIdentities,
   sha256Digest,
+  digestCanonical,
   type EffectiveResourceRegistry,
   type ResourceContentIdentity,
   type ResourceDependencyEdge,
+  type Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
 import { projectAIWorkflowAgentResources } from './agent-resources.js';
 import { sourceRegistryForAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
+import { authorityForAIAgentCodeExecution } from './agent-code-brand.js';
+import { assertAIAgentExecutionResources, assertAIAgentFreezeRegistry, type AIAgentExecutionResourceObservation } from './agent-execution-resources.js';
+import {
+  createResolvedAIWorkflowContentIdentityIndex,
+  resolveAIWorkflowResourceTree,
+} from './resource-resolution.js';
 
 export interface FreezeAIWorkflowRunResourcesInput {
+  readonly executionResources?: AIAgentExecutionResourceObservation;
+  readonly codeExecutions?: readonly CompiledAIAgentCodeExecution[];
   readonly registry: EffectiveResourceRegistry;
   readonly projection: AIWorkflowAgentResourceProjection;
   readonly task: AIWorkflowAgentTaskRef;
@@ -39,14 +50,15 @@ export async function freezeAIWorkflowRunResourcesFromDirectory(
   rootDir: string,
   task: AIWorkflowAgentTaskRef,
 ): Promise<AIWorkflowRunResourceFreezeReceipt> {
-  const tree = await loadResourceTree({ rootDir });
+  const authoredTree = await loadResourceTree({ rootDir });
+  const tree = resolveAIWorkflowResourceTree(authoredTree);
   const layers = [{ id: 'workspace', tree }] as const;
   const registry = composeLayeredResourceRegistry({ layers });
   return freezeAIWorkflowRunResources({
     registry,
     projection: projectAIWorkflowAgentResources(registry),
     task,
-    contentIdentities: resolveEffectiveResourceContentIdentities({ registry, layers }),
+    contentIdentities: createResolvedAIWorkflowContentIdentityIndex(tree),
   });
 }
 
@@ -59,6 +71,7 @@ export class AIWorkflowRunResourceFreezeError extends Error {
 
 const authenticFreezeReceipts = new WeakSet<object>();
 const authenticTaskBindings = new WeakSet<object>();
+const receiptByTaskBinding = new WeakMap<object, AIWorkflowRunResourceFreezeReceipt>();
 const authenticHolonTargetFreezeReceipts = new WeakSet<object>();
 const authenticFrozenHolonTargets = new WeakSet<object>();
 
@@ -72,13 +85,14 @@ export async function freezeAIWorkflowHolonTaskTargetFromDirectory(
   rootDir: string,
   target: HolonTaskTarget,
 ): Promise<AIWorkflowHolonTaskTargetFreezeReceipt> {
-  const tree = await loadResourceTree({ rootDir });
+  const authoredTree = await loadResourceTree({ rootDir });
+  const tree = resolveAIWorkflowResourceTree(authoredTree);
   const layers = [{ id: 'workspace', tree }] as const;
   const registry = composeLayeredResourceRegistry({ layers });
   return freezeAIWorkflowHolonTaskTarget({
     registry,
     target,
-    contentIdentities: resolveEffectiveResourceContentIdentities({ registry, layers }),
+    contentIdentities: createResolvedAIWorkflowContentIdentityIndex(tree),
   });
 }
 
@@ -180,6 +194,7 @@ export function assertFrozenHolonTaskTarget(value: FrozenHolonTaskTarget): Froze
 export function freezeAIWorkflowRunResources(
   input: FreezeAIWorkflowRunResourcesInput,
 ): AIWorkflowRunResourceFreezeReceipt {
+  assertAIAgentFreezeRegistry(input.registry);
   const diagnostics: AIWorkflowResourceProjectionDiagnostic[] = [];
   if (sourceRegistryForAIWorkflowAgentResourceProjection(input.projection) !== input.registry) {
     diagnostics.push(diagnostic(
@@ -189,6 +204,19 @@ export function freezeAIWorkflowRunResources(
     ));
     throwFreezeError(diagnostics);
   }
+  const executionResources = input.executionResources === undefined ? undefined
+    : assertAIAgentExecutionResources(input.executionResources, input.registry);
+  if (executionResources) {
+    if (input.contentIdentities.size !== executionResources.contentIdentities.size
+      || [...executionResources.contentIdentities].some(([id, identity]) =>
+        digestCanonical(input.contentIdentities.get(id) ?? null) !== digestCanonical(identity))) {
+      throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+        diagnostic('AI_RUN_EXECUTION_CONTENT_IDENTITY_MISMATCH', 'run-freeze:identities', 'Execution observation requires its exact authored content identity facts.'),
+      ]));
+    }
+    input = { ...input, registry: executionResources.registry, projection: executionResources.projection,
+      contentIdentities: executionResources.contentIdentities };
+  }
   const task = normalizeTask(input.task, diagnostics);
   if (!task) throwFreezeError(diagnostics);
   const workflowId = resourceIdFromRef(task.workflowRef)!;
@@ -225,19 +253,34 @@ export function freezeAIWorkflowRunResources(
     agentDefinitionRef: task.agentDefinitionRef,
   });
   const bindingResourceIds = Object.freeze(orderedBindings.map((binding) => binding.resource.resourceId));
-  const semanticFingerprint = semanticResourceFingerprint(
+  const resourceFingerprint = semanticResourceFingerprint(
     frozenTask,
     agent,
     orderedBindings,
     dependencySnapshot.closure,
     dependencySnapshot.edges,
   );
+  const codeExecutions = selectedCodeExecutions(input, dependencySnapshot.closure.map(item => item.resourceId));
+  const resourceResolutions = executionResources && Object.freeze(dependencySnapshot.closure
+    .map(item => {
+      const resolution = executionResources.resolutionIdentities.get(item.resourceId);
+      if (!resolution) throw new Error(`AI_RUN_RESOURCE_RESOLUTION_MISSING: ${item.resourceId}`);
+      return resolution;
+    }).sort((a, b) => a.resourceId < b.resourceId ? -1 : a.resourceId > b.resourceId ? 1 : 0));
+  const codeFingerprint = codeExecutions.length
+    ? sha256Digest(JSON.stringify({ schemaVersion: 'ai-workflow.code-bound-semantic/v1', resourceFingerprint, codeExecutions }))
+    : resourceFingerprint;
+  const semanticFingerprint = resourceResolutions
+    ? sha256Digest(JSON.stringify({ schemaVersion: 'ai-workflow.reader-bound-semantic/v1', resourceFingerprint: codeFingerprint, resourceResolutions }))
+    : codeFingerprint;
   const receipt = Object.freeze({
     schemaVersion: 'ai-workflow.run-resource-freeze/v1',
     task: frozenTask,
     bindingResourceIds,
     dependencySnapshot,
     semanticFingerprint,
+    ...(codeExecutions.length ? { codeExecutions } : {}),
+    ...(resourceResolutions ? { resourceResolutions } : {}),
   });
   authenticFreezeReceipts.add(receipt);
   return receipt;
@@ -258,11 +301,52 @@ export function projectFrozenAIAgentTaskBinding(
     semanticFingerprint: receipt.semanticFingerprint,
     snapshotRevision: receipt.dependencySnapshot.snapshotRevision,
     closureResourceIds: Object.freeze(receipt.dependencySnapshot.closure.map((item) => item.resourceId)),
+    ...(receipt.codeExecutions ? { codeExecutions: receipt.codeExecutions } : {}),
+    ...(receipt.resourceResolutions ? { resourceResolutions: receipt.resourceResolutions } : {}),
   });
   authenticTaskBindings.add(binding);
+  receiptByTaskBinding.set(binding, receipt);
   return binding;
 }
 
+/** Retrieves the old Agent identity from the authentic freeze, not caller feedback. */
+export function frozenAIAgentTaskAgentContentDigest(binding: FrozenAIAgentTaskBinding): Sha256Digest {
+  assertFrozenAIAgentTaskBinding(binding);
+  const receipt = receiptByTaskBinding.get(binding)!;
+  const agentId = resourceIdFromRef(receipt.task.agentDefinitionRef)!;
+  const identity = receipt.dependencySnapshot.closure.find(({ resourceId }) => resourceId === agentId);
+  if (!identity) throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+    diagnostic('AI_RUN_AGENT_IDENTITY_MISSING', binding.task.agentDefinitionRef, 'Frozen Agent identity is absent.'),
+  ]));
+  if (!/^sha256:[a-f0-9]{64}$/.test(identity.contentDigest)) throw new Error('Invalid frozen Agent content digest');
+  return identity.contentDigest as Sha256Digest;
+}
+
+function selectedCodeExecutions(input: FreezeAIWorkflowRunResourcesInput, closureIds: readonly string[]): readonly AIAgentCodeExecutionIdentity[] {
+  const selected = new Set(closureIds);
+  const identities = new Map<string, AIAgentCodeExecutionIdentity>();
+  for (const execution of input.codeExecutions ?? []) {
+    const authority = authorityForAIAgentCodeExecution(execution);
+    if (!authority || !selected.has(authority.identity.resourceId)
+      || input.registry.byId.get(authority.identity.resourceId)?.resource !== authority.projection.resource
+      || !(input.projection.codeResources ?? []).includes(authority.projection)
+      || identities.has(authority.identity.resourceId)) {
+      throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+        diagnostic('AI_RUN_CODE_EXECUTION_UNTRUSTED', 'run-freeze:code', 'Code execution must be authentic, selected and belong to the exact registry projection.'),
+      ]));
+    }
+    identities.set(authority.identity.resourceId, authority.identity);
+  }
+  for (const code of input.projection.codeResources ?? []) {
+    if (code.mode === 'native' && selected.has(code.resource.resourceId) && !identities.has(code.resource.resourceId)) {
+      throw new AIWorkflowRunResourceFreezeError(Object.freeze([
+        diagnostic('AI_RUN_CODE_EXECUTION_MISSING', `resource://${code.resource.resourceId}`, 'Native code must be compiled or restored before task freeze.'),
+      ]));
+    }
+  }
+  return Object.freeze([...identities.values()].sort((a, b) => a.resourceId < b.resourceId ? -1 : a.resourceId > b.resourceId ? 1 : 0));
+}
+
 /** Runtime assertion; a structurally similar literal is not an admitted authority. */
 export function assertFrozenAIAgentTaskBinding(value: FrozenAIAgentTaskBinding): FrozenAIAgentTaskBinding {
   if (!authenticTaskBindings.has(value as object)) {