ai-workflow-logic 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-logic",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "description": "AI workflow domain projections and pure runtime helpers with an explicit Halfcode filesystem adapter",
   "type": "module",
@@ -10,19 +10,21 @@
     "./browser": "./src/browser.ts",
     "./checkpoint-filesystem": "./src/checkpoint-filesystem.ts",
     "./filesystem": "./src/filesystem.ts",
-    "./run-freeze": "./src/run-freeze.ts"
+    "./run-freeze": "./src/run-freeze.ts",
+    "./agent-code-execution": "./src/agent-code-execution.ts",
+    "./definitions": "./src/definitions.ts"
   },
   "dependencies": {
-    "ai-workflow-contract": "0.2.0",
+    "ai-workflow-contract": "0.2.2",
     "ajv": "8.20.0",
     "flow-step-space-contract": "0.1.1",
-    "flow-step-space-logic": "0.1.1",
-    "halfcode-compiler.xnl": "0.3.0",
+    "flow-step-space-logic": "0.1.2",
+    "halfcode-compiler.xnl": "0.3.2",
     "holarchy-core-contract": "0.2.0",
-    "task-manager-contract": "0.1.3",
-    "task-manager-logic": "0.1.6",
-    "work-ctrl-flow-contract": "0.1.3",
-    "work-ctrl-flow-logic": "0.1.5"
+    "task-manager-contract": "0.1.4",
+    "task-manager-logic": "0.1.7",
+    "work-ctrl-flow-contract": "0.1.4",
+    "work-ctrl-flow-logic": "0.1.6"
   },
   "files": [
     "src"

package/src/agent-code-brand.ts

@@ -0,0 +1,14 @@
+import type { AIAgentCodeExecutionIdentity, AIAgentCodeResourceProjection, CompiledAIAgentCodeExecution } from 'ai-workflow-contract';
+
+interface CodeExecutionAuthority {
+  readonly projection: AIAgentCodeResourceProjection;
+  readonly identity: AIAgentCodeExecutionIdentity;
+}
+const authorities = new WeakMap<object, CodeExecutionAuthority>();
+export function markAIAgentCodeExecution(value: CompiledAIAgentCodeExecution, authority: CodeExecutionAuthority): CompiledAIAgentCodeExecution {
+  authorities.set(value, Object.freeze(authority));
+  return value;
+}
+export function authorityForAIAgentCodeExecution(value: CompiledAIAgentCodeExecution): CodeExecutionAuthority | undefined {
+  return authorities.get(value);
+}

package/src/agent-code-execution.ts

@@ -0,0 +1,98 @@
+import type { AIAgentCodeResourceProjection, CompiledAIAgentCodeExecution, FlowClosedObject, FrozenAIAgentCodeArtifact } from 'ai-workflow-contract';
+import { captureCodeClosure, type CodeBinding, type CodeExecutionEnvironment } from 'halfcode-compiler.xnl/application-assembly';
+import { bindCodeClosure, type CodeClosureExecutionRuntime } from 'halfcode-compiler.xnl/authoring-runtime';
+import { digestCanonical, type ResourcePackageReadPort, type ResolvedResourceRecord, type Sha256Digest } from 'halfcode-compiler.xnl/resource-core';
+import { markAIAgentCodeExecution } from './agent-code-brand.js';
+import { isAuthenticAIAgentCodeProjection } from './agent-code-projection.js';
+import { normalizeFlowClosedObject } from './run-checkpoint.js';
+import { resolutionForAIAgentCodeProjection } from './agent-execution-resources.js';
+
+export interface LegacyAIAgentCodeBinding {
+  readonly binding: CodeBinding;
+  readonly config: FlowClosedObject;
+  readonly assets?: Readonly<Record<string, 'text' | 'json'>>;
+}
+export interface CompileAIAgentCodeRuntime extends CodeClosureExecutionRuntime {
+  readonly source: ResourcePackageReadPort;
+  readonly sourceRoot: string;
+  readonly entryPath: string;
+  readonly environment: CodeExecutionEnvironment;
+  /** Explicit host compatibility adapter, never an implementation-name switch here. */
+  readonly resolveLegacy?: (projection: Extract<AIAgentCodeResourceProjection, { mode: 'legacy' }>) => LegacyAIAgentCodeBinding;
+}
+
+export async function compileAgentContextPipeline(runtime: CompileAIAgentCodeRuntime, projection: AIAgentCodeResourceProjection): Promise<CompiledAIAgentCodeExecution> {
+  if (projection.kind !== 'AgentContextPipeline') fail('Expected AgentContextPipeline');
+  return compile(runtime, projection);
+}
+export async function compileAgentMessageSource(runtime: CompileAIAgentCodeRuntime, projection: AIAgentCodeResourceProjection): Promise<CompiledAIAgentCodeExecution> {
+  if (projection.kind !== 'AgentMessageSource') fail('Expected AgentMessageSource');
+  return compile(runtime, projection);
+}
+async function compile(runtime: CompileAIAgentCodeRuntime, projection: AIAgentCodeResourceProjection): Promise<CompiledAIAgentCodeExecution> {
+  assertProjection(projection);
+  const resourceResolution = resolutionForAIAgentCodeProjection(projection);
+  const recipe = projection.mode === 'native' ? projection : runtime.resolveLegacy?.(projection);
+  if (!recipe) fail('Legacy recipe requires an explicit builtin binding resolver');
+  const config = normalizeFlowClosedObject(recipe.config);
+  const closure = await captureCodeClosure({ source: runtime.source }, {
+    binding: recipe.binding,
+    sourceRoot: runtime.sourceRoot,
+    entryPath: runtime.entryPath,
+    assets: recipe.assets,
+    environment: runtime.environment,
+  });
+  const artifact: FrozenAIAgentCodeArtifact = Object.freeze({
+    schemaVersion: 'ai-workflow.agent-code-artifact/v1',
+    resourceId: projection.resource.resourceId,
+    resourceDigest: codeResourceDigest(projection),
+    ...(resourceResolution ? { resourceResolution } : {}),
+    config,
+    closure,
+  });
+  return restoreAIAgentCodeExecution(runtime, projection, artifact, digestCanonical(artifact));
+}
+
+/** Rebuilds an execution handle against an authentic frozen registry projection. */
+export function restoreAIAgentCodeExecution(
+  runtime: CodeClosureExecutionRuntime,
+  projection: AIAgentCodeResourceProjection,
+  input: FrozenAIAgentCodeArtifact,
+  expectedDigest: Sha256Digest,
+): CompiledAIAgentCodeExecution {
+  assertProjection(projection);
+  const closed = normalizeFlowClosedObject(input, 'agent-code-artifact');
+  if (!/^sha256:[a-f0-9]{64}$/.test(expectedDigest) || digestCanonical(closed) !== expectedDigest) fail('Artifact differs from trusted expected digest');
+  if (Object.keys(closed).some(key => !['schemaVersion', 'resourceId', 'resourceDigest', 'resourceResolution', 'config', 'closure'].includes(key))) fail('Unsupported artifact field');
+  if (closed.schemaVersion !== 'ai-workflow.agent-code-artifact/v1'
+    || closed.resourceId !== projection.resource.resourceId
+    || closed.resourceDigest !== codeResourceDigest(projection)) fail('Artifact does not belong to this exact resource recipe');
+  if (digestCanonical(closed.resourceResolution ?? null) !== digestCanonical(resolutionForAIAgentCodeProjection(projection) ?? null)) fail('Artifact reader resolution differs from the exact execution observation');
+  // Closed-data validation above detaches and freezes all arrays/maps before narrowing.
+  const artifact = closed as unknown as FrozenAIAgentCodeArtifact;
+  const config = normalizeFlowClosedObject(artifact.config);
+  if (projection.mode === 'native'
+    && (digestCanonical(artifact.closure.binding) !== digestCanonical(projection.binding)
+      || digestCanonical(config) !== digestCanonical(projection.config))) fail('Artifact binding/config differs from native resource');
+  const execute = bindCodeClosure(runtime, artifact.closure, artifact.closure.digest);
+  const handle = Object.freeze({ artifact, artifactDigest: expectedDigest, execute: (runtimeInput: unknown, inputValue: unknown) => execute(runtimeInput, inputValue, config) });
+  return markAIAgentCodeExecution(handle, {
+    projection,
+    identity: Object.freeze({ resourceId: artifact.resourceId, resourceDigest: artifact.resourceDigest, artifactDigest: expectedDigest, closureDigest: artifact.closure.digest }),
+  });
+}
+
+function assertProjection(projection: AIAgentCodeResourceProjection): void {
+  if (!isAuthenticAIAgentCodeProjection(projection)) fail('An authentic code resource projection is required');
+}
+function codeResourceDigest(projection: AIAgentCodeResourceProjection): Sha256Digest {
+  const resource = projection.resource;
+  const resolved = resource as Partial<ResolvedResourceRecord>;
+  const resourceResolution = resolutionForAIAgentCodeProjection(projection);
+  return digestCanonical({
+    resourceId: resource.resourceId, kind: resource.kind, metadata: resource.metadata, node: resource.node,
+    ...(resourceResolution ? { resourceResolution } : {}),
+    ...(resolved.stage === 'resolved' ? { readerId: resolved.readerId, readerSpecVersion: resolved.readerSpecVersion, effectiveContentDigest: resolved.effectiveContentDigest } : {}),
+  });
+}
+function fail(message: string): never { throw new Error(`AI_AGENT_CODE_EXECUTION_INVALID: ${message}`); }

package/src/agent-code-projection.ts

@@ -0,0 +1,98 @@
+import type { AIAgentCodeResourceKind, AIAgentCodeResourceProjection, AIWorkflowTypedResourceRef } from 'ai-workflow-contract';
+import type { ResourceDependencyEdge, ResourceNode, ResourceRecord, ResourceValue } from 'halfcode-compiler.xnl/resource-core';
+import { normalizeFlowClosedObject } from './run-checkpoint.js';
+
+const authenticCodeProjections = new WeakSet<object>();
+export function isAuthenticAIAgentCodeProjection(value: AIAgentCodeResourceProjection): boolean {
+  return authenticCodeProjections.has(value);
+}
+
+/** Pure projection; compiler, filesystem and runtime binding stay in the server entry. */
+export function projectAIAgentCodeResources(
+  resources: ReadonlyMap<string, ResourceRecord>,
+  edges: ResourceDependencyEdge[],
+): readonly AIAgentCodeResourceProjection[] {
+  return Object.freeze([...resources.values()]
+    .filter((resource) => resource.kind === 'AgentContextPipeline' || resource.kind === 'AgentMessageSource')
+    .sort((a, b) => a.resourceId < b.resourceId ? -1 : a.resourceId > b.resourceId ? 1 : 0)
+    .map((resource) => {
+      const kind = resource.kind as AIAgentCodeResourceKind;
+      const node = resource.node;
+      allowed(Object.keys(node.subdomains), ['Content', 'CodeBinding', 'Config', 'Assets', 'DependencyRefs']);
+      const version = resource.metadata.specVersion;
+      if (version !== 1 && version !== 2) fail(`Unsupported code spec version: ${version}`);
+      const contentNode = node.subdomains.Content;
+      const bindingNode = node.subdomains.CodeBinding;
+      if (contentNode && !bindingNode) {
+        if (Object.keys(node.subdomains).some(key => key !== 'Content')) fail('Legacy Content cannot contain native config/dependencies');
+        const content = contentNode.text;
+        if (contentNode.tag !== 'Content' || typeof content !== 'string' || content.length === 0) fail('Legacy Content must contain non-empty text');
+        return mark(Object.freeze({ kind, resource, mode: 'legacy', content, config: Object.freeze({}), assets: Object.freeze({}), dependencies: Object.freeze([]) }));
+      }
+      if (version !== 2 || !bindingNode || contentNode) fail('Native code requires spec 2 and exactly one CodeBinding');
+      leaf(bindingNode, 'CodeBinding', ['packageName', 'module', 'exportName']);
+      const packageName = text(bindingNode.properties.packageName, 'packageName');
+      const module = text(bindingNode.properties.module, 'module');
+      const exportName = text(bindingNode.properties.exportName, 'exportName');
+      if (!module.startsWith('./')) fail('CodeBinding.module must be package-relative');
+      safePath(module.slice(2));
+      if (packageName.startsWith('.') || packageName.startsWith('/') || /[\\\s]/.test(packageName)) fail('Invalid CodeBinding.packageName');
+      const binding = Object.freeze({ packageName, module, exportName, moduleSpecifier: `${packageName}/${module.slice(2)}` });
+      const configNode = node.subdomains.Config;
+      if (configNode) leaf(configNode, 'Config', ['value']);
+      const config = normalizeFlowClosedObject(configNode?.properties.value ?? {});
+      const assets: Record<string, 'text' | 'json'> = Object.create(null);
+      for (const value of list(node.subdomains.Assets, 'Assets')) {
+        leaf(value, 'Asset', ['path', 'format']);
+        const path = safePath(text(value.properties.path, 'Asset.path'));
+        const format = value.properties.format;
+        if ((format !== 'text' && format !== 'json') || Object.hasOwn(assets, path)) fail('Invalid or duplicate Asset');
+        assets[path] = format;
+      }
+      const dependencies: AIWorkflowTypedResourceRef[] = [];
+      const ids = new Set<string>();
+      const targets = new Set<string>();
+      for (const value of list(node.subdomains.DependencyRefs, 'DependencyRefs')) {
+        leaf(value, 'DependencyRef', ['kind', 'ref']);
+        const id = text(value.resourceId, 'DependencyRef.id');
+        const ref = text(value.properties.ref, 'DependencyRef.ref');
+        const targetKind = text(value.properties.kind, 'DependencyRef.kind');
+        if (!ref.startsWith('resource://') || !ref.slice(11) || /\s/.test(ref)) fail('Invalid dependency resource ref');
+        const target = resources.get(ref.slice(11));
+        if (!target || target.kind !== targetKind || ids.has(id) || targets.has(ref)) fail('Missing, mistyped or duplicate dependency');
+        ids.add(id); targets.add(ref);
+        dependencies.push(Object.freeze({ kind: targetKind, ref: ref as `resource://${string}`, resource: target }));
+        edges.push(Object.freeze({ fromResourceId: resource.resourceId, toResourceId: target.resourceId, relation: 'agent-code-dependency', declaredBy: resource.resourceId }));
+      }
+      return mark(Object.freeze({ kind, resource, mode: 'native', binding, config, assets: Object.freeze(assets), dependencies: Object.freeze(dependencies) }));
+    }));
+}
+
+function mark<T extends AIAgentCodeResourceProjection>(value: T): T { authenticCodeProjections.add(value); return value; }
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value || value.trim() !== value) fail(`Expected canonical ${label}`);
+  return value;
+}
+function safePath(value: string): string {
+  if (value.startsWith('/') || /[\\\0?#]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail('Invalid code-owned path');
+  return value;
+}
+function allowed(actual: readonly string[], expected: readonly string[]): void {
+  if (actual.some(key => !expected.includes(key))) fail('Unsupported code recipe field');
+}
+function leaf(value: ResourceNode, tag: string, properties: readonly string[]): void {
+  if (value.tag !== tag || value.body.length || Object.keys(value.subdomains).length || value.text) fail(`Invalid ${tag} node`);
+  allowed(Object.keys(value.properties), properties);
+}
+function list(value: ResourceNode | undefined, tag: string): ResourceNode[] {
+  if (!value) return [];
+  if (value.tag !== tag || Object.keys(value.properties).length || Object.keys(value.subdomains).length || value.text) fail(`Invalid ${tag} list`);
+  return value.body.map(item => {
+    if (!isNode(item)) fail(`Expected node in ${tag}`);
+    return item;
+  });
+}
+function isNode(value: ResourceValue): value is ResourceNode {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'tag' in value && 'body' in value;
+}
+function fail(message: string): never { throw new Error(`AI_AGENT_CODE_INVALID: ${message}`); }