ai-workflow-contract 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-contract",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "description": "Shared AI workflow contracts over WorkCtrlFlow and EagerDataFlow substrates",
   "type": "module",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "eager-data-flow-contract": "0.1.4",
-    "halfcode-compiler.xnl": "0.3.0",
+    "halfcode-compiler.xnl": "0.3.1",
     "task-manager-contract": "0.1.3",
     "work-ctrl-flow-contract": "0.1.3"
   },

package/src/agent-code.ts

@@ -0,0 +1,46 @@
+import type { CodeBinding, FrozenCodeClosure } from 'halfcode-compiler.xnl/application-assembly';
+import type { ResourceRecord, Sha256Digest } from 'halfcode-compiler.xnl/resource-core';
+import type { FlowClosedObject } from 'work-ctrl-flow-contract';
+import type { AIWorkflowTypedResourceRef } from './index.js';
+
+export type AIAgentCodeResourceKind = 'AgentContextPipeline' | 'AgentMessageSource';
+/** Closed identity derived from the actual native resolver output. */
+export interface AIAgentResolvedResourceIdentity {
+  readonly resourceId: string;
+  readonly readerId: string;
+  readonly readerSpecVersion: number;
+  readonly effectiveContentDigest: Sha256Digest;
+  readonly readerProfileId: string;
+  readonly resolutionReceiptDigest: Sha256Digest;
+}
+interface AIAgentCodeProjectionBase {
+  readonly kind: AIAgentCodeResourceKind;
+  readonly resource: ResourceRecord;
+  readonly config: FlowClosedObject;
+  readonly assets: Readonly<Record<string, 'text' | 'json'>>;
+  readonly dependencies: readonly AIWorkflowTypedResourceRef[];
+}
+export type AIAgentCodeResourceProjection = AIAgentCodeProjectionBase & (
+  | { readonly mode: 'native'; readonly binding: CodeBinding }
+  | { readonly mode: 'legacy'; readonly content: string }
+);
+export interface FrozenAIAgentCodeArtifact {
+  readonly resourceResolution?: AIAgentResolvedResourceIdentity;
+  readonly schemaVersion: 'ai-workflow.agent-code-artifact/v1';
+  readonly resourceId: string;
+  readonly resourceDigest: Sha256Digest;
+  readonly config: FlowClosedObject;
+  readonly closure: FrozenCodeClosure;
+}
+export interface AIAgentCodeExecutionIdentity {
+  readonly resourceId: string;
+  readonly resourceDigest: Sha256Digest;
+  readonly artifactDigest: Sha256Digest;
+  readonly closureDigest: string;
+}
+/** Runtime handle. Persist artifact/identity, never the callable. */
+export interface CompiledAIAgentCodeExecution {
+  readonly artifact: FrozenAIAgentCodeArtifact;
+  readonly artifactDigest: Sha256Digest;
+  readonly execute: (runtime: unknown, input: unknown) => unknown;
+}

package/src/index.ts

@@ -24,6 +24,7 @@ import type {
 
 export * from './holon-task.js';
 export * from './resource-kind-contracts.js';
+export * from './agent-code.js';
 
 export {
   FLOW_INSTANCE_SCHEMA_VERSION,
@@ -260,6 +261,7 @@ export interface MaterialBindingProjection {
 }
 
 export interface AIWorkflowAgentResourceProjection {
+  readonly codeResources?: readonly import('./agent-code.js').AIAgentCodeResourceProjection[];
   readonly agentDefinitions: readonly AIAgentDefinitionProjection[];
   readonly materialPorts: readonly MaterialPortProjection[];
   readonly materialBindings: readonly MaterialBindingProjection[];
@@ -267,6 +269,8 @@ export interface AIWorkflowAgentResourceProjection {
 }
 
 export interface AIWorkflowRunResourceFreezeReceipt {
+  readonly resourceResolutions?: readonly import('./agent-code.js').AIAgentResolvedResourceIdentity[];
+  readonly codeExecutions?: readonly import('./agent-code.js').AIAgentCodeExecutionIdentity[];
   readonly schemaVersion: 'ai-workflow.run-resource-freeze/v1';
   readonly task: AIWorkflowAgentTaskRef;
   readonly bindingResourceIds: readonly string[];
@@ -276,6 +280,8 @@ export interface AIWorkflowRunResourceFreezeReceipt {
 
 /** In-memory proof projected only from an admitted run-resource freeze receipt. */
 export interface FrozenAIAgentTaskBinding {
+  readonly resourceResolutions?: readonly import('./agent-code.js').AIAgentResolvedResourceIdentity[];
+  readonly codeExecutions?: readonly import('./agent-code.js').AIAgentCodeExecutionIdentity[];
   readonly schemaVersion: 'ai-workflow.frozen-agent-task-binding/v1';
   readonly task: AIWorkflowAgentTaskRef;
   readonly semanticFingerprint: Sha256Digest;
@@ -323,6 +329,13 @@ export interface AIAgentDefinitionAuthoringEvidence {
   readonly planDigest: Sha256Digest;
   readonly transactionId: string;
   readonly receiptDigest: Sha256Digest;
+  readonly revision?: {
+    readonly candidateRef: `resource://${string}`;
+    readonly candidateDigest: Sha256Digest;
+    readonly contentDigest: Sha256Digest;
+    readonly registryRevision: Sha256Digest;
+    readonly feedback: AIAgentDefinitionRevisionFeedback;
+  };
 }
 
 export interface AIAgentDefinitionCandidate {
@@ -363,9 +376,30 @@ export interface AuthorNewAIAgentDefinitionDecision
   readonly proposal: ResourceAuthoringProposal;
 }
 
+/** Upstream causal references, never diagnostic or publication authority. */
+export interface AIAgentDefinitionRevisionFeedback {
+  readonly observationRef: string;
+  readonly attemptRef: string;
+  readonly verificationRef: string;
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly candidateDigest: Sha256Digest;
+  readonly previousExecutionFingerprint: Sha256Digest;
+}
+
+export interface ReviseExistingAIAgentDefinitionDecision
+  extends AIAgentDefinitionSelectionDecisionBase {
+  readonly mode: 'revise-existing';
+  readonly candidateRef: `resource://${string}`;
+  readonly candidateDigest: Sha256Digest;
+  readonly feedback: AIAgentDefinitionRevisionFeedback;
+  readonly proposal: ResourceAuthoringProposal;
+}
+
 export type AIAgentDefinitionSelectionDecision =
   | SelectExistingAIAgentDefinitionDecision
-  | AuthorNewAIAgentDefinitionDecision;
+  | AuthorNewAIAgentDefinitionDecision
+  | ReviseExistingAIAgentDefinitionDecision;
 
 export type AIAgentDefinitionSelectionRejectionCode =
   | 'decision-invalid'
@@ -375,6 +409,9 @@ export type AIAgentDefinitionSelectionRejectionCode =
   | 'candidate-digest-mismatch'
   | 'candidate-incompatible'
   | 'authoring-in-progress'
+  | 'selection-owner-required'
+  | 'selection-owner-mismatch'
+  | 'revision-feedback-invalid'
   | 'authoring-proposal-invalid';
 
 export interface SelectedAIAgentDefinitionAdmission {
@@ -396,6 +433,18 @@ export interface AuthorNewAIAgentDefinitionAdmission {
   readonly reason: string;
 }
 
+export interface ReviseExistingAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'revision-request';
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly candidate: AIAgentDefinitionCandidate;
+  readonly feedback: AIAgentDefinitionRevisionFeedback;
+  readonly proposal: ResourceAuthoringProposal;
+  readonly reason: string;
+}
+
 export interface RejectedAIAgentDefinitionAdmission {
   readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
   readonly status: 'rejected';
@@ -406,6 +455,7 @@ export interface RejectedAIAgentDefinitionAdmission {
 export type AIAgentDefinitionSelectionAdmission =
   | SelectedAIAgentDefinitionAdmission
   | AuthorNewAIAgentDefinitionAdmission
+  | ReviseExistingAIAgentDefinitionAdmission
   | RejectedAIAgentDefinitionAdmission;
 
 export type AIWorkflowNodeType =

package/src/resource-kind-contracts.ts

@@ -6,6 +6,7 @@ import {
   type KindSpecRevision,
   type KindSubjectOwner,
   type PortableSpec,
+  type SpecResolutionDefinition,
 } from 'halfcode-compiler.xnl/resource-core';
 import {
   createKindSpecRevision,
@@ -148,6 +149,91 @@ function authoredSpecSchema(kind: DepaAIResourceKind): JsonSchema {
   });
 }
 
+/** Native code recipes have a separate writer contract; legacy Content stays spec 1. */
+function nativeCodeSpecSchema(): JsonSchema {
+  const string = Object.freeze({ type: 'string', minLength: 1, pattern: '^\\S(?:[\\s\\S]*\\S)?$' });
+  const emptyObject = Object.freeze({ type: 'object', properties: Object.freeze({}), additionalProperties: false });
+  const emptyBody = Object.freeze({ type: 'array', maxItems: 0 });
+  const node = (tag: string, properties: JsonSchema, body: JsonSchema = emptyBody): JsonSchema => Object.freeze({
+    type: 'object',
+    required: Object.freeze(['tag', 'metadata', 'properties', 'body', 'subdomains']),
+    properties: Object.freeze({
+      tag: Object.freeze({ const: tag }),
+      resourceId: string,
+      metadata: emptyObject,
+      properties,
+      body,
+      subdomains: emptyObject,
+    }),
+    additionalProperties: false,
+  });
+  const closedProperties = (properties: Readonly<Record<string, JsonSchema>>, required = Object.keys(properties)): JsonSchema => Object.freeze({
+    type: 'object', required: Object.freeze(required), properties: Object.freeze(properties), additionalProperties: false,
+  });
+  return Object.freeze({
+    type: 'object',
+    required: Object.freeze(['properties', 'body', 'subdomains']),
+    properties: Object.freeze({
+      properties: closedProperties({ lifecycle: string, description: Object.freeze({ type: 'string' }) }, []),
+      body: emptyBody,
+      subdomains: closedProperties({
+        CodeBinding: node('CodeBinding', closedProperties({ packageName: string, module: string, exportName: string })),
+        Config: node('Config', closedProperties({ value: Object.freeze({ type: 'object' }) })),
+        Assets: node('Assets', emptyObject, Object.freeze({
+          type: 'array',
+          items: node('Asset', closedProperties({ path: string, format: Object.freeze({ enum: Object.freeze(['text', 'json']) }) })),
+        })),
+        DependencyRefs: node('DependencyRefs', emptyObject, Object.freeze({
+          type: 'array',
+          items: node('DependencyRef', closedProperties({
+            kind: string,
+            ref: Object.freeze({ type: 'string', pattern: '^resource://\\S+$' }),
+          })),
+        })),
+      }, ['CodeBinding']),
+    }),
+    additionalProperties: false,
+  });
+}
+
+function codeRecipeSpecSchema(kind: DepaAIResourceKind): JsonSchema {
+  const legacy = authoredSpecSchema(kind) as Readonly<Record<string, unknown>>;
+  return Object.freeze({
+    oneOf: Object.freeze([
+      nativeCodeSpecSchema(),
+      Object.freeze({
+        ...legacy,
+        properties: Object.freeze({
+          ...(legacy.properties as Readonly<Record<string, unknown>>),
+          subdomains: Object.freeze({
+            type: 'object', required: Object.freeze(['Content']),
+            properties: Object.freeze({ CodeBinding: false }),
+          }),
+        }),
+      }),
+    ]),
+  });
+}
+
+function nativeCodeSemanticContract(kind: DepaAIResourceKind): KindSemanticContract {
+  const authority = 'ai-workflow-contract/depa-ai-resource-kinds/v2';
+  return Object.freeze({
+    semanticValidatorFingerprint: digestCanonical(Object.freeze({
+      authority, kind, role: 'closed-native-code-recipe-validation',
+      fields: Object.freeze(['CodeBinding', 'Config', 'Assets', 'DependencyRefs']),
+      config: 'closed-json-object', assets: 'source-root-relative-text-or-json',
+      legacy: 'exclusive-Content-requires-explicit-compatibility-resolver',
+    })),
+    referenceProjectionFingerprint: digestCanonical(Object.freeze({
+      authority, kind, role: 'typed-resource-reference-projection', relations: Object.freeze(['code-dependency']),
+    })),
+    compilerInputFingerprint: digestCanonical(Object.freeze({
+      authority, kind, role: 'native-code-binding-and-frozen-closure-projection',
+      fields: Object.freeze(['packageName', 'module', 'exportName', 'config', 'assets', 'dependencyRefs']),
+    })),
+  });
+}
+
 function semanticContract(kind: DepaAIResourceKind): KindSemanticContract {
   return Object.freeze({
     semanticValidatorFingerprint: digestCanonical(Object.freeze({
@@ -175,26 +261,26 @@ function readerRegistration(
   kind: DepaAIResourceKind,
   revision: KindSpecRevision,
 ): KindReaderRegistration<PortableSpec> {
-  const readerId = `ai-workflow-contract.${kind}.reader.v1`;
+  const readerId = `ai-workflow-contract.${kind}.reader.v${revision.specVersion}`;
   return Object.freeze({
     readerId,
     subjectFqn: revision.subjectFqn,
     readerSpecVersion: revision.specVersion,
     contractFingerprint: revision.contractFingerprint,
     readerImplementationFingerprint: digestCanonical(Object.freeze({
-      authority: 'ai-workflow-contract/depa-ai-resource-kinds/v1',
+      authority: `ai-workflow-contract/depa-ai-resource-kinds/v${revision.specVersion}`,
       readerId,
       kind,
       contractFingerprint: revision.contractFingerprint,
       operations: KIND_SEMANTIC_OPERATIONS[kind],
       implementation: 'identity-read-of-halfcode-validated-portable-spec',
     })),
-    compatibilityPolicy: 'exact',
+    compatibilityPolicy: revision.specVersion === 1 ? 'exact' : 'backward-transitive',
     read: (spec: PortableSpec): PortableSpec => spec,
   });
 }
 
-function renderKindDefinition(owner: KindSubjectOwner, revision: KindSpecRevision): string {
+function renderKindDefinition(owner: KindSubjectOwner, revisions: readonly KindSpecRevision[]): string {
   return [
     `<KindDefinition #${owner.subjectFqn} envelopeVersion="${DEPA_AI_RESOURCE_ENVELOPE_VERSION}" specVersion=1 {`,
     '  lifecycle = "Stable"',
@@ -205,16 +291,18 @@ function renderKindDefinition(owner: KindSubjectOwner, revision: KindSpecRevisio
     `  description = "Canonical depa-flows ${owner.kind} resource contract."`,
     '} (',
     '  <SpecRevisions [',
-    `    <SpecRevision #v${revision.specVersion} {`,
-    `      specVersion = ${revision.specVersion}`,
-    '      schemaRef = "vfs://./spec-v1.schema.json"',
-    `      schemaFingerprint = "${revision.schemaFingerprint}"`,
-    `      contractFingerprint = "${revision.contractFingerprint}"`,
-    `      semanticValidatorFingerprint = "${revision.semanticContract.semanticValidatorFingerprint}"`,
-    `      referenceProjectionFingerprint = "${revision.semanticContract.referenceProjectionFingerprint}"`,
-    `      compilerInputFingerprint = "${revision.semanticContract.compilerInputFingerprint}"`,
-    `      stability = "${revision.stability}"`,
-    '    }>',
+    ...revisions.flatMap((revision) => [
+      `    <SpecRevision #v${revision.specVersion} {`,
+      `      specVersion = ${revision.specVersion}`,
+      `      schemaRef = "vfs://./spec-v${revision.specVersion}.schema.json"`,
+      `      schemaFingerprint = "${revision.schemaFingerprint}"`,
+      `      contractFingerprint = "${revision.contractFingerprint}"`,
+      `      semanticValidatorFingerprint = "${revision.semanticContract.semanticValidatorFingerprint}"`,
+      `      referenceProjectionFingerprint = "${revision.semanticContract.referenceProjectionFingerprint}"`,
+      `      compilerInputFingerprint = "${revision.semanticContract.compilerInputFingerprint}"`,
+      `      stability = "${revision.stability}"`,
+      '    }>',
+    ]),
     '  ]>',
     ')>',
     '',
@@ -246,16 +334,36 @@ function createContract(kind: DepaAIResourceKind): DepaAIResourceKindContract {
     owner,
     revision,
     reader: readerRegistration(kind, revision),
-    kindDefinitionSource: renderKindDefinition(owner, revision),
+    kindDefinitionSource: renderKindDefinition(owner, [revision]),
   });
 }
 
-export const DEPA_AI_RESOURCE_KIND_CONTRACTS: readonly DepaAIResourceKindContract[] = Object.freeze(
-  DEPA_AI_RESOURCE_KINDS.map(createContract),
-);
+const LEGACY_KIND_CONTRACTS = DEPA_AI_RESOURCE_KINDS.map(createContract);
+
+export const DEPA_AI_RESOURCE_KIND_CONTRACTS: readonly DepaAIResourceKindContract[] = Object.freeze([
+  ...LEGACY_KIND_CONTRACTS,
+  ...LEGACY_KIND_CONTRACTS.filter(({ kind }) => kind === 'AgentMessageSource' || kind === 'AgentContextPipeline').map((legacy) => {
+    const { kind } = legacy;
+    const revision = createKindSpecRevision({
+      kind,
+      subjectFqn: legacy.subjectFqn,
+      specVersion: 2,
+      specSchema: codeRecipeSpecSchema(kind),
+      semanticContract: nativeCodeSemanticContract(kind),
+      sourceContractFingerprint: legacy.owner.sourceContract.sourceContractFingerprint,
+      stability: 'stable',
+    });
+    return Object.freeze({
+      ...legacy,
+      revision,
+      reader: readerRegistration(kind, revision),
+      kindDefinitionSource: renderKindDefinition(legacy.owner, [legacy.revision, revision]),
+    });
+  }),
+]);
 
 export const DEPA_AI_RESOURCE_KIND_OWNERS: readonly KindSubjectOwner[] = Object.freeze(
-  DEPA_AI_RESOURCE_KIND_CONTRACTS.map((contract) => contract.owner),
+  LEGACY_KIND_CONTRACTS.map((contract) => contract.owner),
 );
 
 export const DEPA_AI_RESOURCE_KIND_SPEC_REVISIONS: readonly KindSpecRevision[] = Object.freeze(
@@ -266,16 +374,40 @@ export const DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS: readonly KindReaderRegi
   DEPA_AI_RESOURCE_KIND_CONTRACTS.map((contract) => contract.reader),
 );
 
-const CONTRACTS_BY_KIND: ReadonlyMap<DepaAIResourceKind, DepaAIResourceKindContract> = new Map(
-  DEPA_AI_RESOURCE_KIND_CONTRACTS.map((contract) => [contract.kind, contract]),
+const CONTRACTS_BY_KIND: ReadonlyMap<string, DepaAIResourceKindContract> = new Map(
+  DEPA_AI_RESOURCE_KIND_CONTRACTS.map((contract) => [`${contract.kind}@${contract.revision.specVersion}`, contract]),
 );
 
-export function depaAIResourceKindContract(kind: DepaAIResourceKind): DepaAIResourceKindContract {
-  const contract = CONTRACTS_BY_KIND.get(kind);
-  if (!contract) throw new Error(`Unknown depa AI resource Kind '${kind}'.`);
+export function depaAIResourceKindContract(kind: DepaAIResourceKind, specVersion: number = DEPA_AI_RESOURCE_SPEC_VERSION): DepaAIResourceKindContract {
+  const contract = CONTRACTS_BY_KIND.get(`${kind}@${specVersion}`);
+  if (!contract) throw new Error(`Unknown depa AI resource Kind '${kind}' spec version '${specVersion}'.`);
   return contract;
 }
 
+export const DEPA_AI_RESOURCE_KIND_SPEC_RESOLUTIONS: readonly SpecResolutionDefinition[] = Object.freeze(
+  DEPA_AI_RESOURCE_KIND_CONTRACTS.filter((contract) => contract.revision.specVersion === 2).map((contract) => {
+    const writer = depaAIResourceKindContract(contract.kind, 1);
+    const identity = Object.freeze({
+      id: `ai-workflow-contract.${contract.kind}.v1-to-v2`,
+      subjectFqn: contract.subjectFqn,
+      ownerPackageId: contract.owner.ownerPackageId,
+      ownerPackageFingerprint: contract.owner.ownerPackageFingerprint,
+      writerSpecVersion: 1,
+      readerSpecVersion: 2,
+      writerContractFingerprint: writer.revision.contractFingerprint,
+      readerContractFingerprint: contract.revision.contractFingerprint,
+    });
+    return Object.freeze({
+      ...identity,
+      resolutionFingerprint: digestCanonical(Object.freeze({
+        ...identity,
+        implementation: 'identity-Content-preservation-requires-explicit-legacy-code-resolver',
+      })),
+      resolve: (spec: PortableSpec): PortableSpec => spec,
+    });
+  }),
+);
+
 function compareCodeUnits(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }