ai-workflow-logic 0.1.0 → 0.1.2

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "ai-workflow-logic",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
-  "description": "Pure helpers for AI workflow profile descriptors, runtime contexts, and reuse policy resolution",
+  "description": "AI workflow domain projections and pure runtime helpers with an explicit Halfcode filesystem adapter",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./browser": "./src/browser.ts"
+    "./browser": "./src/browser.ts",
+    "./filesystem": "./src/filesystem.ts",
+    "./run-freeze": "./src/run-freeze.ts"
   },
   "dependencies": {
-    "ai-workflow-contract": "0.1.0"
+    "ai-workflow-contract": "0.1.2",
+    "halfcode-compiler.xnl": "0.2.2"
   },
   "files": [
     "src"
@@ -19,4 +22,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.com"
   }
-}
+}

package/src/agent-resource-brand.ts

@@ -0,0 +1,20 @@
+import type {
+  AIWorkflowAgentResourceProjection,
+  AIWorkflowResourceRegistryView,
+} from 'ai-workflow-contract';
+
+const sourceRegistryByProjection = new WeakMap<object, AIWorkflowResourceRegistryView>();
+
+export function markAIWorkflowAgentResourceProjection(
+  projection: AIWorkflowAgentResourceProjection,
+  registry: AIWorkflowResourceRegistryView,
+): AIWorkflowAgentResourceProjection {
+  sourceRegistryByProjection.set(projection, registry);
+  return projection;
+}
+
+export function sourceRegistryForAIWorkflowAgentResourceProjection(
+  projection: AIWorkflowAgentResourceProjection,
+): AIWorkflowResourceRegistryView | undefined {
+  return sourceRegistryByProjection.get(projection);
+}

package/src/agent-resources.ts

@@ -0,0 +1,505 @@
+import type {
+  AIAgentDefinitionProjection,
+  AIAgentMessageProjection,
+  AIAgentMessageRole,
+  AIWorkflowAgentResourceProjection,
+  AIWorkflowAgentResourceRelation,
+  AIWorkflowAgentTaskRef,
+  AIWorkflowDefinitionResourceKind,
+  AIWorkflowResourceProjectionDiagnostic,
+  AIWorkflowResourceRegistryView,
+  AIWorkflowTypedResourceRef,
+  MaterialBindingProjection,
+  MaterialCardinality,
+  MaterialPortProjection,
+} from 'ai-workflow-contract';
+import type {
+  ResourceDependencyEdge,
+  ResourceNode,
+  ResourceRecord,
+  ResourceValue,
+} from 'halfcode-compiler.xnl/resource-core';
+import { markAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
+import { AIWorkflowResourceProjectionError } from './errors.js';
+
+const AGENT_SUBDOMAINS = Object.freeze([
+  'Messages',
+  'InputSchemaRef',
+  'OutputSchemaRef',
+  'ToolRefs',
+  'EffectPolicyRef',
+  'MaterialPortRefs',
+]);
+
+export function projectAIWorkflowAgentResources(
+  registry: AIWorkflowResourceRegistryView,
+): AIWorkflowAgentResourceProjection {
+  const diagnostics: AIWorkflowResourceProjectionDiagnostic[] = [];
+  const resources = buildResourceIndex(registry, diagnostics);
+  const edges: ResourceDependencyEdge[] = [];
+
+  const materialPorts = recordsForKind(registry, 'MaterialPort')
+    .map((resource) => projectMaterialPort(resource, resources, edges, diagnostics))
+    .filter((value): value is MaterialPortProjection => value !== undefined);
+  const portsById = new Map(materialPorts.map((port) => [port.resource.resourceId, port]));
+
+  const agentDefinitions = recordsForKind(registry, 'AIAgentDefinition')
+    .map((resource) => projectAgentDefinition(resource, resources, edges, diagnostics))
+    .filter((value): value is AIAgentDefinitionProjection => value !== undefined);
+
+  const materialBindings = recordsForKind(registry, 'MaterialBinding')
+    .map((resource) => projectMaterialBinding(resource, resources, portsById, edges, diagnostics))
+    .filter((value): value is MaterialBindingProjection => value !== undefined);
+  validateBindingIdentity(materialBindings, diagnostics);
+
+  if (diagnostics.length > 0) throwProjectionError(diagnostics);
+  return markAIWorkflowAgentResourceProjection(Object.freeze({
+    agentDefinitions: Object.freeze(agentDefinitions),
+    materialPorts: Object.freeze(materialPorts),
+    materialBindings: Object.freeze(materialBindings),
+    dependencyEdges: Object.freeze([...edges].sort(compareEdges)),
+  }), registry);
+}
+
+function buildResourceIndex(
+  registry: AIWorkflowResourceRegistryView,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): ReadonlyMap<string, ResourceRecord> {
+  const resources = new Map<string, ResourceRecord>();
+  const records = [...registry.byKind.entries()]
+    .sort(([left], [right]) => compareCodeUnits(left, right))
+    .flatMap(([, values]) => [...values])
+    .sort(compareRecords);
+  for (const resource of records) {
+    if (resources.has(resource.resourceId)) {
+      diagnostics.push(diagnostic(
+        'AI_RESOURCE_ID_DUPLICATE',
+        resource.documentUri,
+        `Resource identity '${resource.resourceId}' occurs more than once in the registry view.`,
+      ));
+      continue;
+    }
+    resources.set(resource.resourceId, resource);
+  }
+  return resources;
+}
+
+function recordsForKind(
+  registry: AIWorkflowResourceRegistryView,
+  kind: string,
+): readonly ResourceRecord[] {
+  return [...(registry.byKind.get(kind) ?? [])].sort(compareRecords);
+}
+
+function projectMaterialPort(
+  resource: ResourceRecord,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): MaterialPortProjection | undefined {
+  validateAllowedSubdomains(resource, ['SchemaRef'], diagnostics);
+  const materialKind = canonicalString(resource.node.properties.materialKind);
+  const required = resource.node.properties.required;
+  const cardinality = resource.node.properties.cardinality;
+  let valid = true;
+  if (!materialKind) {
+    diagnostics.push(diagnostic('AI_MATERIAL_PORT_KIND_INVALID', resource.documentUri, 'MaterialPort materialKind must be an explicit non-empty string.'));
+    valid = false;
+  }
+  if (typeof required !== 'boolean') {
+    diagnostics.push(diagnostic('AI_MATERIAL_PORT_REQUIRED_INVALID', resource.documentUri, 'MaterialPort required must be an explicit boolean.'));
+    valid = false;
+  }
+  if (!isMaterialCardinality(cardinality)) {
+    diagnostics.push(diagnostic('AI_MATERIAL_PORT_CARDINALITY_INVALID', resource.documentUri, 'MaterialPort cardinality must be one or many.'));
+    valid = false;
+  }
+  const schema = projectOptionalTypedSubdomain(
+    resource,
+    'SchemaRef',
+    resources,
+    'material-port-schema',
+    edges,
+    diagnostics,
+  );
+  if (!valid || !materialKind || typeof required !== 'boolean' || !isMaterialCardinality(cardinality)) return undefined;
+  return Object.freeze({
+    kind: 'MaterialPort',
+    fqn: resource.fqn ?? resource.resourceId,
+    resource,
+    materialKind,
+    required,
+    cardinality,
+    ...(schema === undefined ? {} : { schema }),
+  });
+}
+
+function projectAgentDefinition(
+  resource: ResourceRecord,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIAgentDefinitionProjection | undefined {
+  validateAllowedSubdomains(resource, AGENT_SUBDOMAINS, diagnostics);
+  const messagesNode = requiredSubdomain(resource, 'Messages', diagnostics);
+  const toolRefsNode = requiredSubdomain(resource, 'ToolRefs', diagnostics);
+  const materialPortRefsNode = requiredSubdomain(resource, 'MaterialPortRefs', diagnostics);
+  const messages = messagesNode
+    ? projectMessages(resource, messagesNode, resources, edges, diagnostics)
+    : [];
+  const inputSchema = projectOptionalTypedSubdomain(resource, 'InputSchemaRef', resources, 'agent-input-schema', edges, diagnostics);
+  const outputSchema = projectOptionalTypedSubdomain(resource, 'OutputSchemaRef', resources, 'agent-output-schema', edges, diagnostics);
+  const tools = toolRefsNode
+    ? projectTypedRefList(resource, toolRefsNode, 'ToolRef', resources, 'agent-tool', edges, diagnostics)
+    : [];
+  const effectPolicy = projectOptionalTypedSubdomain(resource, 'EffectPolicyRef', resources, 'agent-effect-policy', edges, diagnostics);
+  const materialPorts = materialPortRefsNode
+    ? projectTypedRefList(resource, materialPortRefsNode, 'MaterialPortRef', resources, 'agent-material-port', edges, diagnostics, 'MaterialPort')
+    : [];
+
+  if (!messagesNode || !toolRefsNode || !materialPortRefsNode) return undefined;
+  return Object.freeze({
+    kind: 'AIAgentDefinition',
+    fqn: resource.fqn ?? resource.resourceId,
+    resource,
+    messages: Object.freeze(messages),
+    ...(inputSchema === undefined ? {} : { inputSchema }),
+    ...(outputSchema === undefined ? {} : { outputSchema }),
+    tools: Object.freeze(tools),
+    ...(effectPolicy === undefined ? {} : { effectPolicy }),
+    materialPorts: Object.freeze(materialPorts),
+  });
+}
+
+function projectMessages(
+  resource: ResourceRecord,
+  messagesNode: ResourceNode,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIAgentMessageProjection[] {
+  const output: AIAgentMessageProjection[] = [];
+  const ids = new Set<string>();
+  messagesNode.body.forEach((value, index) => {
+    const location = `${resource.documentUri}#Messages:${index}`;
+    if (!isResourceNode(value) || value.tag !== 'Message') {
+      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)) {
+      diagnostics.push(diagnostic('AI_AGENT_MESSAGE_ID_DUPLICATE', location, `Message id '${id}' is declared more than once.`));
+    } else {
+      ids.add(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'
+      ? projectTypedRefNode(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 }) }));
+  });
+  return output;
+}
+
+function projectTypedRefList(
+  owner: ResourceRecord,
+  list: ResourceNode,
+  childTag: string,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  relation: AIWorkflowAgentResourceRelation,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+  expectedKind?: string,
+): AIWorkflowTypedResourceRef[] {
+  const output: AIWorkflowTypedResourceRef[] = [];
+  const ids = new Set<string>();
+  const targetIds = new Set<string>();
+  list.body.forEach((value, index) => {
+    const location = `${owner.documentUri}#${list.tag}:${index}`;
+    if (!isResourceNode(value) || value.tag !== childTag) {
+      diagnostics.push(diagnostic('AI_RESOURCE_REF_NODE_INVALID', location, `${list.tag} may contain only ${childTag} nodes.`));
+      return;
+    }
+    const id = canonicalString(value.resourceId);
+    if (!id) diagnostics.push(diagnostic('AI_RESOURCE_REF_ID_MISSING', location, `${childTag} must declare an explicit #id.`));
+    else if (ids.has(id)) diagnostics.push(diagnostic('AI_RESOURCE_REF_ID_DUPLICATE', location, `${childTag} id '${id}' is declared more than once.`));
+    else ids.add(id);
+    const typedRef = projectTypedRefNode(value, resources, location, diagnostics, expectedKind);
+    if (typedRef && targetIds.has(typedRef.resource.resourceId)) {
+      diagnostics.push(diagnostic('AI_RESOURCE_REF_TARGET_DUPLICATE', location, `${childTag} target '${typedRef.resource.resourceId}' is declared more than once.`));
+      return;
+    }
+    if (!typedRef || !id) return;
+    targetIds.add(typedRef.resource.resourceId);
+    output.push(typedRef);
+    edges.push(edge(owner.resourceId, typedRef.resource.resourceId, relation));
+  });
+  return output;
+}
+
+function projectOptionalTypedSubdomain(
+  owner: ResourceRecord,
+  name: string,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  relation: AIWorkflowAgentResourceRelation,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIWorkflowTypedResourceRef | undefined {
+  const node = owner.node.subdomains[name];
+  if (!node) return undefined;
+  if (node.tag !== name) {
+    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);
+  if (typedRef) edges.push(edge(owner.resourceId, typedRef.resource.resourceId, relation));
+  return typedRef;
+}
+
+function projectMaterialBinding(
+  resource: ResourceRecord,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  portsById: ReadonlyMap<string, MaterialPortProjection>,
+  edges: ResourceDependencyEdge[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): MaterialBindingProjection | undefined {
+  validateAllowedSubdomains(resource, ['AgentTaskRef', 'PortRef', 'MaterialRef'], diagnostics);
+  const taskNode = requiredSubdomain(resource, 'AgentTaskRef', diagnostics);
+  const portNode = requiredSubdomain(resource, 'PortRef', diagnostics);
+  const materialNode = requiredSubdomain(resource, 'MaterialRef', diagnostics);
+  const task = taskNode ? projectTaskRef(taskNode, resources, `${resource.documentUri}#AgentTaskRef`, diagnostics) : undefined;
+  const portRef = portNode ? projectTypedRefNode(portNode, resources, `${resource.documentUri}#PortRef`, diagnostics, 'MaterialPort') : undefined;
+  const material = materialNode ? projectTypedRefNode(materialNode, resources, `${resource.documentUri}#MaterialRef`, diagnostics) : undefined;
+  if (portRef) edges.push(edge(resource.resourceId, portRef.resource.resourceId, 'material-binding-port'));
+  if (material) edges.push(edge(resource.resourceId, material.resource.resourceId, 'material-binding-material'));
+  const port = portRef ? portsById.get(portRef.resource.resourceId) : undefined;
+  if (portRef && !port) diagnostics.push(diagnostic('AI_MATERIAL_BINDING_PORT_PROJECTION_MISSING', resource.documentUri, `MaterialBinding port '${portRef.resource.resourceId}' has no valid MaterialPort projection.`));
+  if (!task || !port || !material) return undefined;
+  return Object.freeze({
+    kind: 'MaterialBinding',
+    fqn: resource.fqn ?? resource.resourceId,
+    resource,
+    task,
+    port,
+    material,
+  });
+}
+
+function projectTaskRef(
+  node: ResourceNode,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  location: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIWorkflowAgentTaskRef | undefined {
+  const workflowKind = node.properties.workflowKind;
+  const workflowRef = canonicalString(node.properties.workflowRef);
+  const nodeId = canonicalString(node.properties.nodeId);
+  const agentDefinitionRef = canonicalString(node.properties.agentDefinitionRef);
+  let valid = true;
+  if (!isWorkflowKind(workflowKind)) {
+    diagnostics.push(diagnostic('AI_AGENT_TASK_WORKFLOW_KIND_INVALID', location, 'AgentTaskRef workflowKind must be AICtrlWorkflow or AIDataWorkflow.'));
+    valid = false;
+  }
+  const workflow = resolveRef(workflowRef, resources, location, diagnostics);
+  if (workflow && isWorkflowKind(workflowKind) && workflow.kind !== workflowKind) {
+    diagnostics.push(diagnostic('AI_RESOURCE_REF_KIND_MISMATCH', location, `Resource '${workflow.resourceId}' has kind '${workflow.kind}', expected '${workflowKind}'.`));
+    valid = false;
+  }
+  if (!nodeId) {
+    diagnostics.push(diagnostic('AI_AGENT_TASK_NODE_ID_INVALID', location, 'AgentTaskRef nodeId must be an explicit canonical string.'));
+    valid = false;
+  }
+  const agent = resolveRef(agentDefinitionRef, resources, location, diagnostics);
+  if (agent && agent.kind !== 'AIAgentDefinition') {
+    diagnostics.push(diagnostic('AI_RESOURCE_REF_KIND_MISMATCH', location, `Resource '${agent.resourceId}' has kind '${agent.kind}', expected 'AIAgentDefinition'.`));
+    valid = false;
+  }
+  if (!valid || !isWorkflowKind(workflowKind) || !workflowRef || !resourceIdFromRef(workflowRef) || !nodeId || !agentDefinitionRef || !resourceIdFromRef(agentDefinitionRef) || !workflow || !agent) return undefined;
+  return Object.freeze({
+    workflowKind,
+    workflowRef: workflowRef as `resource://${string}`,
+    nodeId,
+    agentDefinitionRef: agentDefinitionRef as `resource://${string}`,
+  });
+}
+
+function projectTypedRefNode(
+  node: ResourceNode,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  location: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+  expectedKind?: string,
+): AIWorkflowTypedResourceRef | undefined {
+  return projectTypedValues(node.properties.kind, node.properties.ref, resources, location, diagnostics, expectedKind);
+}
+
+function projectTypedValues(
+  kindValue: ResourceValue | undefined,
+  refValue: ResourceValue | undefined,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  location: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+  expectedKind?: string,
+): AIWorkflowTypedResourceRef | undefined {
+  const kind = canonicalString(kindValue);
+  const ref = canonicalString(refValue);
+  let valid = true;
+  if (!kind || expectedKind && kind !== expectedKind) {
+    diagnostics.push(diagnostic('AI_RESOURCE_REF_KIND_INVALID', location, expectedKind ? `Typed ref kind must be '${expectedKind}'.` : 'Typed ref kind must be an explicit canonical string.'));
+    valid = false;
+  }
+  const target = resolveRef(ref, resources, location, diagnostics);
+  if (target && kind && target.kind !== kind) {
+    diagnostics.push(diagnostic('AI_RESOURCE_REF_KIND_MISMATCH', location, `Resource '${target.resourceId}' has kind '${target.kind}', expected '${kind}'.`));
+    valid = false;
+  }
+  if (!valid || !kind || !ref || !resourceIdFromRef(ref) || !target) return undefined;
+  return Object.freeze({ kind, ref: ref as `resource://${string}`, resource: target });
+}
+
+function resolveRef(
+  ref: string | undefined,
+  resources: ReadonlyMap<string, ResourceRecord>,
+  location: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): ResourceRecord | undefined {
+  const resourceId = resourceIdFromRef(ref);
+  if (!resourceId) {
+    diagnostics.push(diagnostic('AI_RESOURCE_REF_INVALID', location, 'Typed ref must use one exact non-empty resource:// identity.'));
+    return undefined;
+  }
+  const target = resources.get(resourceId);
+  if (!target) diagnostics.push(diagnostic('AI_RESOURCE_REF_TARGET_MISSING', location, `Resource '${resourceId}' does not exist in the registry view.`));
+  return target;
+}
+
+function requiredSubdomain(
+  resource: ResourceRecord,
+  name: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): ResourceNode | undefined {
+  const node = resource.node.subdomains[name];
+  if (!node) diagnostics.push(diagnostic('AI_RESOURCE_SUBDOMAIN_MISSING', resource.documentUri, `${resource.kind} '${resource.resourceId}' must declare ${name}.`));
+  else if (node.tag !== name) {
+    diagnostics.push(diagnostic('AI_RESOURCE_SUBDOMAIN_TAG_MISMATCH', `${resource.documentUri}#${name}`, `Subdomain ${name} must contain a ${name} node, got '${node.tag}'.`));
+    return undefined;
+  }
+  return node;
+}
+
+function validateAllowedSubdomains(
+  resource: ResourceRecord,
+  allowed: readonly string[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): void {
+  validateAllowedNodeSubdomains(resource.node, allowed, resource.documentUri, diagnostics);
+}
+
+function validateAllowedNodeSubdomains(
+  node: ResourceNode,
+  allowed: readonly string[],
+  location: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): void {
+  const allowedNames = new Set(allowed);
+  for (const name of Object.keys(node.subdomains)) {
+    if (!allowedNames.has(name)) diagnostics.push(diagnostic('AI_RESOURCE_SUBDOMAIN_UNSUPPORTED', `${location}#${name}`, `Subdomain '${name}' is not part of the fixed ${node.tag} contract.`));
+  }
+}
+
+function validateBindingIdentity(
+  bindings: readonly MaterialBindingProjection[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): void {
+  const keys = new Map<string, string>();
+  for (const binding of bindings) {
+    const key = `${taskKey(binding.task)}\u0000${binding.port.resource.resourceId}\u0000${binding.material.resource.resourceId}`;
+    const previous = keys.get(key);
+    if (previous) diagnostics.push(diagnostic('AI_MATERIAL_BINDING_DUPLICATE', binding.resource.documentUri, `MaterialBinding duplicates the relation declared by '${previous}'.`));
+    else keys.set(key, binding.resource.resourceId);
+  }
+}
+
+function throwProjectionError(diagnostics: AIWorkflowResourceProjectionDiagnostic[]): never {
+  throw new AIWorkflowResourceProjectionError(Object.freeze([...diagnostics].sort((left, right) =>
+    compareCodeUnits(left.location, right.location) || compareCodeUnits(left.code, right.code),
+  )));
+}
+
+function edge(fromResourceId: string, toResourceId: string, relation: AIWorkflowAgentResourceRelation): ResourceDependencyEdge {
+  return Object.freeze({ fromResourceId, toResourceId, relation, declaredBy: fromResourceId });
+}
+
+function compareEdges(left: ResourceDependencyEdge, right: ResourceDependencyEdge): number {
+  return compareCodeUnits(left.fromResourceId, right.fromResourceId)
+    || compareCodeUnits(left.toResourceId, right.toResourceId)
+    || compareCodeUnits(left.relation, right.relation)
+    || compareCodeUnits(left.declaredBy, right.declaredBy);
+}
+
+function compareRecords(left: ResourceRecord, right: ResourceRecord): number {
+  return compareCodeUnits(left.resourceId, right.resourceId) || compareCodeUnits(left.kind, right.kind);
+}
+
+function taskKey(task: AIWorkflowAgentTaskRef): string {
+  return `${task.workflowKind}\u0000${task.workflowRef}\u0000${task.nodeId}\u0000${task.agentDefinitionRef}`;
+}
+
+function resourceIdFromRef(value: string | undefined): string | undefined {
+  const prefix = 'resource://';
+  if (!value || value !== value.trim() || !value.startsWith(prefix)) return undefined;
+  const resourceId = value.slice(prefix.length);
+  return resourceId.length > 0 && !resourceId.includes('://') && resourceId === resourceId.trim()
+    ? resourceId
+    : undefined;
+}
+
+function canonicalString(value: ResourceValue | string | undefined): string | undefined {
+  return typeof value === 'string' && value.length > 0 && value === value.trim() ? value : undefined;
+}
+
+function isMessageRole(value: ResourceValue | undefined): value is AIAgentMessageRole {
+  return value === 'system' || value === 'developer' || value === 'user' || value === 'assistant';
+}
+
+function isMaterialCardinality(value: ResourceValue | undefined): value is MaterialCardinality {
+  return value === 'one' || value === 'many';
+}
+
+function isWorkflowKind(value: ResourceValue | undefined): value is AIWorkflowDefinitionResourceKind {
+  return value === 'AICtrlWorkflow' || value === 'AIDataWorkflow';
+}
+
+function isResourceNode(value: ResourceValue): value is ResourceNode {
+  return typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && typeof (value as ResourceNode).tag === 'string'
+    && Array.isArray((value as ResourceNode).body);
+}
+
+function diagnostic(code: string, location: string, message: string): AIWorkflowResourceProjectionDiagnostic {
+  return Object.freeze({ code, location, message });
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/errors.ts

@@ -0,0 +1,15 @@
+import type { AIWorkflowResourceProjectionDiagnostic } from 'ai-workflow-contract';
+
+export class AIWorkflowFoundationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AIWorkflowFoundationError';
+  }
+}
+
+export class AIWorkflowResourceProjectionError extends AIWorkflowFoundationError {
+  constructor(public readonly diagnostics: readonly AIWorkflowResourceProjectionDiagnostic[]) {
+    super(`AI workflow resource projection failed with ${diagnostics.length} diagnostic(s)`);
+    this.name = 'AIWorkflowResourceProjectionError';
+  }
+}

package/src/filesystem.ts

@@ -0,0 +1,18 @@
+import {
+  loadResourceTree,
+  type LoadResourceTreeOptions,
+} from 'halfcode-compiler.xnl/resource-core';
+import type { LoadedAIWorkflowResourcePackage } from 'ai-workflow-contract';
+import { projectAIWorkflowAppBundles } from './index.js';
+
+export async function loadAIWorkflowResourcePackage(
+  options: LoadResourceTreeOptions,
+): Promise<LoadedAIWorkflowResourcePackage> {
+  const tree = await loadResourceTree(options);
+  return Object.freeze({
+    tree,
+    appBundles: projectAIWorkflowAppBundles(tree.registry, {
+      packageResourceId: tree.manifest.resourceId,
+    }),
+  });
+}

package/src/index.ts

@@ -6,6 +6,9 @@ import {
   AI_WORKFLOW_MANUAL_NODE_DEFAULT_REUSE_POLICY,
   type AICtrlWorkflowDefinitionBinding,
   type AIDataWorkflowDefinitionBinding,
+  type AIWorkflowAppBundleProjection,
+  type AIWorkflowBindingProjection,
+  type AIWorkflowDefinitionResourceKind,
   type AIWorkflowEffectiveReusePolicy,
   type AIWorkflowEmbeddedEffectProvider,
   type AIWorkflowEffectProvider,
@@ -17,6 +20,8 @@ import {
   type AIWorkflowKind,
   type AIWorkflowNodeType,
   type AIWorkflowProfileDescriptor,
+  type AIWorkflowResourceProjectionDiagnostic,
+  type AIWorkflowResourceRegistryView,
   type AIWorkflowResourceRef,
   type AIWorkflowResourceRefScheme,
   type AIWorkflowReusePolicy,
@@ -24,14 +29,13 @@ import {
   type AIWorkflowRuntimeContext,
   type AIWorkflowStateStore,
   type AIWorkflowSubstrate,
+  type ProjectAIWorkflowAppBundlesOptions,
 } from 'ai-workflow-contract';
+import type { ResourceNode, ResourceRecord, ResourceValue } from 'halfcode-compiler.xnl/resource-core';
+import { AIWorkflowFoundationError, AIWorkflowResourceProjectionError } from './errors.js';
 
-export class AIWorkflowFoundationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'AIWorkflowFoundationError';
-  }
-}
+export { AIWorkflowFoundationError, AIWorkflowResourceProjectionError } from './errors.js';
+export { projectAIWorkflowAgentResources } from './agent-resources.js';
 
 export class AIWorkflowEffectHandlerNotFoundError extends AIWorkflowFoundationError {
   constructor(
@@ -91,6 +95,214 @@ export function defineAIDataWorkflow(
   });
 }
 
+export function projectAIWorkflowAppBundles(
+  registry: AIWorkflowResourceRegistryView,
+  options: ProjectAIWorkflowAppBundlesOptions = {},
+): readonly AIWorkflowAppBundleProjection[] {
+  const diagnostics: AIWorkflowResourceProjectionDiagnostic[] = [];
+  const workflowRecords = new Map<string, ResourceRecord>();
+  for (const kind of AI_WORKFLOW_DEFINITION_RESOURCE_KINDS) {
+    for (const resource of registry.byKind.get(kind) ?? []) {
+      workflowRecords.set(resource.resourceId, resource);
+    }
+  }
+
+  const appBundles = [...(registry.byKind.get('AIWorkflowAppBundle') ?? [])]
+    .sort((left, right) => compareCodeUnits(left.resourceId, right.resourceId))
+    .map((resource) => projectAppBundle(resource, workflowRecords, options, diagnostics));
+
+  if (diagnostics.length > 0) {
+    throw new AIWorkflowResourceProjectionError(Object.freeze(
+      diagnostics.sort((left, right) => compareCodeUnits(left.location, right.location)
+        || compareCodeUnits(left.code, right.code)),
+    ));
+  }
+
+  return Object.freeze(appBundles.filter((bundle): bundle is AIWorkflowAppBundleProjection => bundle !== undefined));
+}
+
+const AI_WORKFLOW_DEFINITION_RESOURCE_KINDS = Object.freeze([
+  'AICtrlWorkflow',
+  'AIDataWorkflow',
+] as const satisfies readonly AIWorkflowDefinitionResourceKind[]);
+
+function projectAppBundle(
+  resource: ResourceRecord,
+  workflowRecords: ReadonlyMap<string, ResourceRecord>,
+  options: ProjectAIWorkflowAppBundlesOptions,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIWorkflowAppBundleProjection | undefined {
+  const bindingsNode = resource.node.subdomains.WorkflowBindings;
+  if (!bindingsNode) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDINGS_MISSING',
+      resource.documentUri,
+      `AIWorkflowAppBundle '${resource.resourceId}' must declare WorkflowBindings.`,
+    ));
+    return undefined;
+  }
+
+  const bindingIds = new Set<string>();
+  const workflowBindings: AIWorkflowBindingProjection[] = [];
+  for (const [index, value] of bindingsNode.body.entries()) {
+    const location = `${resource.documentUri}#WorkflowBindings:${index}`;
+    if (!isResourceNode(value) || value.tag !== 'WorkflowBinding') {
+      diagnostics.push(projectionDiagnostic(
+        'AI_WORKFLOW_BINDING_NODE_INVALID',
+        location,
+        'WorkflowBindings may contain only WorkflowBinding nodes.',
+      ));
+      continue;
+    }
+    const binding = projectWorkflowBinding(value, workflowRecords, location, diagnostics);
+    if (!binding) continue;
+    if (bindingIds.has(binding.id)) {
+      diagnostics.push(projectionDiagnostic(
+        'AI_WORKFLOW_BINDING_ID_DUPLICATE',
+        location,
+        `WorkflowBinding id '${binding.id}' is declared more than once.`,
+      ));
+      continue;
+    }
+    bindingIds.add(binding.id);
+    workflowBindings.push(binding);
+  }
+
+  const entrypoints = workflowBindings.filter((binding) => binding.entrypoint);
+  if (entrypoints.length === 0) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_APP_ENTRYPOINT_MISSING',
+      resource.documentUri,
+      `AIWorkflowAppBundle '${resource.resourceId}' must declare at least one workflow entrypoint.`,
+    ));
+  }
+
+  const frozenBindings = Object.freeze(workflowBindings);
+  return Object.freeze({
+    kind: 'AIWorkflowAppBundle',
+    fqn: resource.fqn ?? resource.resourceId,
+    ...(options.packageResourceId === undefined ? {} : { packageResourceId: options.packageResourceId }),
+    resource,
+    workflowBindings: frozenBindings,
+    entrypoints: Object.freeze(entrypoints),
+  });
+}
+
+function projectWorkflowBinding(
+  node: ResourceNode,
+  workflowRecords: ReadonlyMap<string, ResourceRecord>,
+  location: string,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIWorkflowBindingProjection | undefined {
+  const id = node.resourceId;
+  const kind = asString(node.properties.kind);
+  const ref = asString(node.properties.ref);
+  const entrypoint = node.properties.entrypoint;
+  let valid = true;
+
+  if (!id) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDING_ID_MISSING',
+      location,
+      'WorkflowBinding must declare an explicit #id.',
+    ));
+    valid = false;
+  }
+  if (!isWorkflowDefinitionResourceKind(kind)) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDING_KIND_INVALID',
+      location,
+      'WorkflowBinding kind must be AICtrlWorkflow or AIDataWorkflow.',
+    ));
+    valid = false;
+  }
+  const resourceId = resourceIdFromRef(ref);
+  if (!resourceId) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDING_REF_INVALID',
+      location,
+      'WorkflowBinding ref must be a non-empty resource:// identity.',
+    ));
+    valid = false;
+  }
+  if (typeof entrypoint !== 'boolean') {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDING_ENTRYPOINT_INVALID',
+      location,
+      'WorkflowBinding entrypoint must be an explicit boolean.',
+    ));
+    valid = false;
+  }
+  if (
+    !valid
+    || !id
+    || !isWorkflowDefinitionResourceKind(kind)
+    || !resourceId
+    || typeof entrypoint !== 'boolean'
+  ) return undefined;
+
+  const target = workflowRecords.get(resourceId);
+  if (!target) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDING_TARGET_MISSING',
+      location,
+      `WorkflowBinding target '${resourceId}' does not exist in the effective resource registry.`,
+    ));
+    return undefined;
+  }
+  if (target.kind !== kind) {
+    diagnostics.push(projectionDiagnostic(
+      'AI_WORKFLOW_BINDING_TARGET_KIND_MISMATCH',
+      location,
+      `WorkflowBinding declares kind '${kind}', but target '${resourceId}' has kind '${target.kind}'.`,
+    ));
+    return undefined;
+  }
+
+  return Object.freeze({
+    id,
+    kind,
+    ref: ref as `resource://${string}`,
+    entrypoint,
+    resource: target,
+  });
+}
+
+function isWorkflowDefinitionResourceKind(value: string | undefined): value is AIWorkflowDefinitionResourceKind {
+  return value === 'AICtrlWorkflow' || value === 'AIDataWorkflow';
+}
+
+function resourceIdFromRef(value: string | undefined): string | undefined {
+  const prefix = 'resource://';
+  if (!value?.startsWith(prefix)) return undefined;
+  const resourceId = value.slice(prefix.length);
+  return resourceId.length > 0 && !resourceId.includes('://') ? resourceId : undefined;
+}
+
+function asString(value: ResourceValue | undefined): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function isResourceNode(value: ResourceValue): value is ResourceNode {
+  return typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && typeof (value as ResourceNode).tag === 'string'
+    && Array.isArray((value as ResourceNode).body);
+}
+
+function projectionDiagnostic(
+  code: string,
+  location: string,
+  message: string,
+): AIWorkflowResourceProjectionDiagnostic {
+  return Object.freeze({ code, location, message });
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
 export interface ResolveAIWorkflowReusePolicyInput {
   readonly nodeType: AIWorkflowNodeType;
   readonly explicitPolicy?: AIWorkflowReusePolicy;
@@ -273,6 +485,7 @@ function hasContainmentEscape(target: string): boolean {
   return decoded.split(/[/?#]+/).some((segment) => segment === '..');
 }
 
+/** @deprecated Compatibility helper; Halfcode owns canonical resource-reference validation. */
 export function parseAIWorkflowResourceRef(value: string): ParsedAIWorkflowResourceRef | undefined {
   const match = RESOURCE_REF_PATTERN.exec(value);
   if (!match) return undefined;
@@ -286,10 +499,12 @@ export function parseAIWorkflowResourceRef(value: string): ParsedAIWorkflowResou
   };
 }
 
+/** @deprecated Compatibility helper; use typed refs projected from Halfcode ResourceRecord facts. */
 export function isAIWorkflowResourceRef(value: string): value is AIWorkflowResourceRef {
   return parseAIWorkflowResourceRef(value) !== undefined;
 }
 
+/** @deprecated Compatibility helper; use typed refs projected from Halfcode ResourceRecord facts. */
 export function assertAIWorkflowResourceRef(value: string): AIWorkflowResourceRef {
   const parsed = parseAIWorkflowResourceRef(value);
   if (!parsed) {

package/src/run-freeze.ts

@@ -0,0 +1,270 @@
+import type {
+  AIAgentDefinitionProjection,
+  AIWorkflowAgentResourceProjection,
+  AIWorkflowAgentTaskRef,
+  AIWorkflowResourceProjectionDiagnostic,
+  AIWorkflowRunResourceFreezeReceipt,
+  MaterialBindingProjection,
+  MaterialPortProjection,
+} from 'ai-workflow-contract';
+import {
+  buildResourceDependencySnapshot,
+  sha256Digest,
+  type EffectiveResourceRegistry,
+  type ResourceContentIdentity,
+  type ResourceDependencyEdge,
+} from 'halfcode-compiler.xnl/resource-core';
+import { sourceRegistryForAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
+
+export interface FreezeAIWorkflowRunResourcesInput {
+  readonly registry: EffectiveResourceRegistry;
+  readonly projection: AIWorkflowAgentResourceProjection;
+  readonly task: AIWorkflowAgentTaskRef;
+  readonly contentIdentities: ReadonlyMap<string, ResourceContentIdentity>;
+}
+
+export class AIWorkflowRunResourceFreezeError extends Error {
+  constructor(public readonly diagnostics: readonly AIWorkflowResourceProjectionDiagnostic[]) {
+    super(`AI workflow run resource freeze failed with ${diagnostics.length} diagnostic(s)`);
+    this.name = 'AIWorkflowRunResourceFreezeError';
+  }
+}
+
+export function freezeAIWorkflowRunResources(
+  input: FreezeAIWorkflowRunResourcesInput,
+): AIWorkflowRunResourceFreezeReceipt {
+  const diagnostics: AIWorkflowResourceProjectionDiagnostic[] = [];
+  if (sourceRegistryForAIWorkflowAgentResourceProjection(input.projection) !== input.registry) {
+    diagnostics.push(diagnostic(
+      'AI_RUN_RESOURCE_PROJECTION_UNTRUSTED',
+      'run-freeze:projection',
+      'Run freeze requires the exact immutable Agent resource projection produced for this registry.',
+    ));
+    throwFreezeError(diagnostics);
+  }
+  const task = normalizeTask(input.task, diagnostics);
+  if (!task) throwFreezeError(diagnostics);
+  const workflowId = resourceIdFromRef(task.workflowRef)!;
+  const agentId = resourceIdFromRef(task.agentDefinitionRef)!;
+  const workflow = input.registry.byId.get(workflowId)?.resource;
+  if (!workflow || workflow.kind !== task.workflowKind) diagnostics.push(diagnostic('AI_RUN_WORKFLOW_MISSING', `resource://${workflowId}`, `Workflow '${workflowId}' is absent or has another kind.`));
+  const agent = input.projection.agentDefinitions.find((value) => value.resource.resourceId === agentId);
+  if (!agent) diagnostics.push(diagnostic('AI_RUN_AGENT_DEFINITION_MISSING', `resource://${agentId}`, `Agent definition '${agentId}' is absent from the domain projection.`));
+  if (diagnostics.length > 0 || !workflow || !agent) throwFreezeError(diagnostics);
+
+  const selectedBindings = input.projection.materialBindings.filter((binding) => sameTask(binding.task, task));
+  const orderedBindings = validateAndOrderBindings(
+    agent,
+    input.projection.materialPorts,
+    selectedBindings,
+    diagnostics,
+  );
+  if (diagnostics.length > 0) throwFreezeError(diagnostics);
+
+  const workflowEdges: ResourceDependencyEdge[] = [
+    edge(workflowId, agentId, 'workflow-agent-task'),
+    ...orderedBindings.map((binding) => edge(workflowId, binding.resource.resourceId, 'workflow-material-binding')),
+  ];
+  const dependencySnapshot = buildResourceDependencySnapshot({
+    registry: input.registry,
+    roots: [workflowId, agentId, ...orderedBindings.map((binding) => binding.resource.resourceId)],
+    edges: [...input.projection.dependencyEdges, ...workflowEdges],
+    contentIdentities: input.contentIdentities,
+  });
+  const frozenTask = Object.freeze({
+    workflowKind: task.workflowKind,
+    workflowRef: task.workflowRef,
+    nodeId: task.nodeId,
+    agentDefinitionRef: task.agentDefinitionRef,
+  });
+  const bindingResourceIds = Object.freeze(orderedBindings.map((binding) => binding.resource.resourceId));
+  const semanticFingerprint = semanticResourceFingerprint(
+    frozenTask,
+    agent,
+    orderedBindings,
+    dependencySnapshot.closure,
+    dependencySnapshot.edges,
+  );
+  return Object.freeze({
+    schemaVersion: 'ai-workflow.run-resource-freeze/v1',
+    task: frozenTask,
+    bindingResourceIds,
+    dependencySnapshot,
+    semanticFingerprint,
+  });
+}
+
+function validateAndOrderBindings(
+  agent: AIAgentDefinitionProjection,
+  materialPorts: readonly MaterialPortProjection[],
+  selected: readonly MaterialBindingProjection[],
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): MaterialBindingProjection[] {
+  const agentPortOrder = new Map(agent.materialPorts.map((ref, index) => [ref.resource.resourceId, index]));
+  const bindingsByPort = new Map<string, MaterialBindingProjection[]>();
+  for (const binding of selected) {
+    const portId = binding.port.resource.resourceId;
+    if (!agentPortOrder.has(portId)) {
+      diagnostics.push(diagnostic('AI_RUN_MATERIAL_PORT_FOREIGN', binding.resource.documentUri, `Port '${portId}' is not declared by Agent '${agent.resource.resourceId}'.`));
+      continue;
+    }
+    if (binding.material.resource.kind !== binding.port.materialKind) {
+      diagnostics.push(diagnostic('AI_RUN_MATERIAL_KIND_MISMATCH', binding.resource.documentUri, `Material '${binding.material.resource.resourceId}' has kind '${binding.material.resource.kind}', expected '${binding.port.materialKind}'.`));
+      continue;
+    }
+    const values = bindingsByPort.get(portId) ?? [];
+    values.push(binding);
+    bindingsByPort.set(portId, values);
+  }
+
+  const ordered: MaterialBindingProjection[] = [];
+  for (const portRef of agent.materialPorts) {
+    const port = materialPorts.find((value) => value.resource.resourceId === portRef.resource.resourceId);
+    if (!port) {
+      diagnostics.push(diagnostic('AI_RUN_MATERIAL_PORT_PROJECTION_MISSING', agent.resource.documentUri, `Agent port '${portRef.resource.resourceId}' has no projected MaterialPort.`));
+      continue;
+    }
+    const values = [...(bindingsByPort.get(port.resource.resourceId) ?? [])]
+      .sort((left, right) => compareCodeUnits(left.resource.resourceId, right.resource.resourceId));
+    if (port.required && values.length === 0) diagnostics.push(diagnostic('AI_RUN_REQUIRED_MATERIAL_MISSING', port.resource.documentUri, `Required MaterialPort '${port.resource.resourceId}' has no binding for this task.`));
+    if (port.cardinality === 'one' && values.length > 1) diagnostics.push(diagnostic('AI_RUN_MATERIAL_CARDINALITY_EXCEEDED', port.resource.documentUri, `MaterialPort '${port.resource.resourceId}' accepts at most one binding.`));
+    ordered.push(...values);
+  }
+  return ordered;
+}
+
+function semanticResourceFingerprint(
+  task: AIWorkflowAgentTaskRef,
+  agent: AIAgentDefinitionProjection,
+  bindings: readonly MaterialBindingProjection[],
+  closure: readonly { resourceId: string; kind: string; contentDigest: string }[],
+  edges: readonly ResourceDependencyEdge[],
+): `sha256:${string}` {
+  const fact = {
+    schemaVersion: 'ai-workflow-resource-semantic-hash/v1',
+    task: {
+      workflowKind: task.workflowKind,
+      workflowRef: task.workflowRef,
+      nodeId: task.nodeId,
+      agentDefinitionRef: task.agentDefinitionRef,
+    },
+    agent: {
+      resourceId: agent.resource.resourceId,
+      messages: agent.messages.map((message) => ({
+        id: message.id,
+        role: message.role,
+        prompt: [message.prompt.kind, message.prompt.resource.resourceId],
+        schema: message.schema ? [message.schema.kind, message.schema.resource.resourceId] : null,
+      })),
+      inputSchema: agent.inputSchema ? [agent.inputSchema.kind, agent.inputSchema.resource.resourceId] : null,
+      outputSchema: agent.outputSchema ? [agent.outputSchema.kind, agent.outputSchema.resource.resourceId] : null,
+      tools: agent.tools.map((ref) => [ref.kind, ref.resource.resourceId]),
+      effectPolicy: agent.effectPolicy ? [agent.effectPolicy.kind, agent.effectPolicy.resource.resourceId] : null,
+      materialPorts: agent.materialPorts.map((ref) => [ref.kind, ref.resource.resourceId]),
+    },
+    bindings: bindings.map((binding) => ({
+      resourceId: binding.resource.resourceId,
+      port: [binding.port.resource.resourceId, binding.port.materialKind, binding.port.required, binding.port.cardinality],
+      material: [binding.material.kind, binding.material.resource.resourceId],
+    })),
+    closure: closure.map((resource) => ({
+      resourceId: resource.resourceId,
+      kind: resource.kind,
+      contentDigest: resource.contentDigest,
+    })),
+    edges: edges.map((value) => ({
+      fromResourceId: value.fromResourceId,
+      toResourceId: value.toResourceId,
+      relation: value.relation,
+      declaredBy: value.declaredBy,
+    })),
+  };
+  return sha256Digest(JSON.stringify(fact));
+}
+
+function normalizeTask(
+  value: unknown,
+  diagnostics: AIWorkflowResourceProjectionDiagnostic[],
+): AIWorkflowAgentTaskRef | undefined {
+  const initialDiagnosticCount = diagnostics.length;
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    diagnostics.push(diagnostic('AI_RUN_AGENT_TASK_INVALID', 'run-freeze:task', 'Run freeze task must be a fixed four-field object.'));
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  const allowedFields = new Set([
+    'workflowKind',
+    'workflowRef',
+    'nodeId',
+    'agentDefinitionRef',
+  ]);
+  const unsupportedFields = Reflect.ownKeys(record)
+    .filter((key) => typeof key !== 'string' || !allowedFields.has(key))
+    .map((key) => typeof key === 'string' ? key : key.toString())
+    .sort(compareCodeUnits);
+  for (const field of unsupportedFields) {
+    diagnostics.push(diagnostic('AI_RUN_AGENT_TASK_FIELD_UNSUPPORTED', `run-freeze:task:${field}`, `Run freeze task field '${field}' is not part of the fixed Agent task tuple.`));
+  }
+
+  const workflowKind = ownDataValue(record, 'workflowKind');
+  const workflowRef = ownDataValue(record, 'workflowRef');
+  const nodeId = ownDataValue(record, 'nodeId');
+  const agentDefinitionRef = ownDataValue(record, 'agentDefinitionRef');
+  if (workflowKind !== 'AICtrlWorkflow' && workflowKind !== 'AIDataWorkflow') {
+    diagnostics.push(diagnostic('AI_RUN_AGENT_TASK_INVALID', 'run-freeze:task:workflowKind', 'Run freeze task workflowKind must be AICtrlWorkflow or AIDataWorkflow.'));
+  }
+  if (typeof workflowRef !== 'string' || resourceIdFromRef(workflowRef) === undefined) {
+    diagnostics.push(diagnostic('AI_RUN_AGENT_TASK_INVALID', 'run-freeze:task:workflowRef', 'Run freeze task workflowRef must be one exact resource:// identity.'));
+  }
+  if (typeof nodeId !== 'string' || nodeId.length === 0 || nodeId !== nodeId.trim()) {
+    diagnostics.push(diagnostic('AI_RUN_AGENT_TASK_INVALID', 'run-freeze:task:nodeId', 'Run freeze task nodeId must be an explicit canonical string.'));
+  }
+  if (typeof agentDefinitionRef !== 'string' || resourceIdFromRef(agentDefinitionRef) === undefined) {
+    diagnostics.push(diagnostic('AI_RUN_AGENT_TASK_INVALID', 'run-freeze:task:agentDefinitionRef', 'Run freeze task agentDefinitionRef must be one exact resource:// identity.'));
+  }
+  if (diagnostics.length !== initialDiagnosticCount
+    || workflowKind !== 'AICtrlWorkflow' && workflowKind !== 'AIDataWorkflow'
+    || typeof workflowRef !== 'string'
+    || typeof nodeId !== 'string'
+    || typeof agentDefinitionRef !== 'string') return undefined;
+  return Object.freeze({ workflowKind, workflowRef: workflowRef as `resource://${string}`, nodeId, agentDefinitionRef: agentDefinitionRef as `resource://${string}` });
+}
+
+function ownDataValue(record: Record<string, unknown>, field: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(record, field);
+  return descriptor && 'value' in descriptor ? descriptor.value : undefined;
+}
+
+function sameTask(left: AIWorkflowAgentTaskRef, right: AIWorkflowAgentTaskRef): boolean {
+  return left.workflowKind === right.workflowKind
+    && left.workflowRef === right.workflowRef
+    && left.nodeId === right.nodeId
+    && left.agentDefinitionRef === right.agentDefinitionRef;
+}
+
+function resourceIdFromRef(value: unknown): string | undefined {
+  const prefix = 'resource://';
+  if (typeof value !== 'string' || value !== value.trim() || !value.startsWith(prefix)) return undefined;
+  const resourceId = value.slice(prefix.length);
+  return resourceId.length > 0 && resourceId === resourceId.trim() && !resourceId.includes('://')
+    ? resourceId
+    : undefined;
+}
+
+function edge(fromResourceId: string, toResourceId: string, relation: string): ResourceDependencyEdge {
+  return Object.freeze({ fromResourceId, toResourceId, relation, declaredBy: fromResourceId });
+}
+
+function throwFreezeError(diagnostics: AIWorkflowResourceProjectionDiagnostic[]): never {
+  throw new AIWorkflowRunResourceFreezeError(Object.freeze([...diagnostics].sort((left, right) =>
+    compareCodeUnits(left.location, right.location) || compareCodeUnits(left.code, right.code),
+  )));
+}
+
+function diagnostic(code: string, location: string, message: string): AIWorkflowResourceProjectionDiagnostic {
+  return Object.freeze({ code, location, message });
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}