ai-workflow-logic 0.1.11 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-logic",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "private": false,
   "description": "AI workflow domain projections and pure runtime helpers with an explicit Halfcode filesystem adapter",
   "type": "module",
@@ -13,15 +13,16 @@
     "./run-freeze": "./src/run-freeze.ts"
   },
   "dependencies": {
-    "ai-workflow-contract": "0.1.9",
+    "ai-workflow-contract": "0.2.0",
+    "ajv": "8.20.0",
     "flow-step-space-contract": "0.1.1",
     "flow-step-space-logic": "0.1.1",
-    "halfcode-compiler.xnl": "0.2.9",
-    "holarchy-core-contract": "0.1.1",
+    "halfcode-compiler.xnl": "0.3.0",
+    "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.4"
+    "work-ctrl-flow-logic": "0.1.5"
   },
   "files": [
     "src"

package/src/agent-definition-selection.ts

@@ -22,6 +22,7 @@ import {
   type ResourceAuthoringTransactionPort,
 } from 'halfcode-compiler.xnl/authoring-runtime';
 import {
+  RESOURCE_ENVELOPE_VERSION,
   resolveEffectiveResourceContentIdentities,
   sha256Digest,
   type EffectiveResourceRegistry,
@@ -281,14 +282,16 @@ export async function reconcileAuthoredAIAgentDefinition(
     || input.receipt.catalogId !== proposal.catalogId
     || input.receipt.resourceId !== proposal.resourceId
     || input.receipt.kind !== proposal.kind
-    || input.receipt.apiVersion !== proposal.apiVersion
+    || input.receipt.envelopeVersion !== proposal.envelopeVersion
+    || input.receipt.writerSpecVersion !== proposal.writerSpecVersion
     || input.receipt.sourceShape !== proposal.sourceShape
     || input.receipt.documentUri !== proposal.documentUri
     || input.receipt.authorityDigestBefore !== null
     || input.receipt.authorityDigestAfter !== sha256Digest(proposal.authorityText)
     || input.receipt.registryRevisionBefore !== proposal.expected.registryRevision
     || input.receipt.kind !== 'AIAgentDefinition'
-    || resource.metadata.apiVersion !== input.receipt.apiVersion
+    || resource.metadata.envelopeVersion !== input.receipt.envelopeVersion
+    || resource.metadata.specVersion !== input.receipt.writerSpecVersion
     || resource.sourceShape !== input.receipt.sourceShape
     || resource.documentUri !== input.receipt.documentUri
     || !identity
@@ -504,7 +507,8 @@ function isValidAuthoringProposal(
       'catalogId',
       'resourceId',
       'kind',
-      'apiVersion',
+      'envelopeVersion',
+      'writerSpecVersion',
       'sourceShape',
       'documentUri',
       'authorityText',
@@ -521,7 +525,9 @@ function isValidAuthoringProposal(
       && definitionRef === resourceRef(nonEmptyString(proposal.resourceId, 'proposal.resourceId'))
       && !candidateSet.candidates.some(({ agentDefinitionRef }) => agentDefinitionRef === definitionRef)
       && nonEmptyString(proposal.catalogId, 'proposal.catalogId').length > 0
-      && nonEmptyString(proposal.apiVersion, 'proposal.apiVersion').length > 0
+      && proposal.envelopeVersion === RESOURCE_ENVELOPE_VERSION
+      && Number.isSafeInteger(proposal.writerSpecVersion)
+      && Number(proposal.writerSpecVersion) > 0
       && /^vfs:\/\/@\/.+\.xnl$/u.test(nonEmptyString(proposal.documentUri, 'proposal.documentUri'))
       && stringValue(proposal.authorityText, 'proposal.authorityText').length > 0;
   } catch {
@@ -536,7 +542,8 @@ function cloneAuthoringProposal(value: ResourceAuthoringProposal): ResourceAutho
     catalogId: value.catalogId,
     resourceId: value.resourceId,
     kind: value.kind,
-    apiVersion: value.apiVersion,
+    envelopeVersion: value.envelopeVersion,
+    writerSpecVersion: value.writerSpecVersion,
     sourceShape: value.sourceShape,
     documentUri: value.documentUri,
     authorityText: value.authorityText,
@@ -555,7 +562,8 @@ function validateReceiptShapeAndDigest(receiptValue: ResourceAuthoringReceipt):
       'catalogId',
       'resourceId',
       'kind',
-      'apiVersion',
+      'envelopeVersion',
+      'writerSpecVersion',
       'sourceShape',
       'documentUri',
       'authorityDigestBefore',
@@ -572,6 +580,9 @@ function validateReceiptShapeAndDigest(receiptValue: ResourceAuthoringReceipt):
     if (receipt.schemaVersion !== RESOURCE_AUTHORING_SCHEMA_VERSION
       || (receipt.operation !== 'create' && receipt.operation !== 'update')
       || receipt.sourceShape !== 'single-file'
+      || receipt.envelopeVersion !== RESOURCE_ENVELOPE_VERSION
+      || !Number.isSafeInteger(receipt.writerSpecVersion)
+      || Number(receipt.writerSpecVersion) <= 0
       || (receipt.authorityDigestBefore !== null && !isDigest(receipt.authorityDigestBefore))
       || !isDigest(receipt.planDigest)
       || !isDigest(receipt.authorityDigestAfter)
@@ -587,7 +598,7 @@ function validateReceiptShapeAndDigest(receiptValue: ResourceAuthoringReceipt):
       || (origin.logicalPath !== undefined && typeof origin.logicalPath !== 'string')) {
       throw new Error('invalid receipt fields');
     }
-    for (const field of ['transactionId', 'catalogId', 'resourceId', 'kind', 'apiVersion', 'documentUri'] as const) {
+    for (const field of ['transactionId', 'catalogId', 'resourceId', 'kind', 'envelopeVersion', 'documentUri'] as const) {
       nonEmptyString(receipt[field], `receipt.${field}`);
     }
     for (const field of ['layerId', 'packageId', 'documentUri'] as const) {

package/src/filesystem.ts

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

package/src/resource-resolution.ts

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

package/src/run-freeze.ts

@@ -18,7 +18,6 @@ import {
   buildResourceDependencySnapshot,
   composeLayeredResourceRegistry,
   loadResourceTree,
-  resolveEffectiveResourceContentIdentities,
   sha256Digest,
   type EffectiveResourceRegistry,
   type ResourceContentIdentity,
@@ -26,6 +25,10 @@ import {
 } from 'halfcode-compiler.xnl/resource-core';
 import { projectAIWorkflowAgentResources } from './agent-resources.js';
 import { sourceRegistryForAIWorkflowAgentResourceProjection } from './agent-resource-brand.js';
+import {
+  createResolvedAIWorkflowContentIdentityIndex,
+  resolveAIWorkflowResourceTree,
+} from './resource-resolution.js';
 
 export interface FreezeAIWorkflowRunResourcesInput {
   readonly registry: EffectiveResourceRegistry;
@@ -39,14 +42,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),
   });
 }
 
@@ -72,13 +76,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),
   });
 }