ai-workflow-contract 0.1.9 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-contract",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "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.2.9",
+    "halfcode-compiler.xnl": "0.3.0",
     "task-manager-contract": "0.1.3",
     "work-ctrl-flow-contract": "0.1.3"
   },

package/src/index.ts

@@ -4,7 +4,8 @@ import type {
   ResourceDependencySnapshot,
   ResourceRecord,
   ResourceRegistry,
-  ResourceTree,
+  AuthoredResourceTree,
+  ResolvedResourceTree,
   ResourceValue,
   Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
@@ -22,6 +23,7 @@ import type {
 } from 'work-ctrl-flow-contract';
 
 export * from './holon-task.js';
+export * from './resource-kind-contracts.js';
 
 export {
   FLOW_INSTANCE_SCHEMA_VERSION,
@@ -148,7 +150,8 @@ export interface ProjectAIWorkflowAppBundlesOptions {
 }
 
 export interface LoadedAIWorkflowResourcePackage {
-  readonly tree: ResourceTree;
+  readonly authoredTree: AuthoredResourceTree;
+  readonly tree: ResolvedResourceTree;
   readonly appBundles: readonly AIWorkflowAppBundleProjection[];
 }
 

package/src/resource-kind-contracts.ts

@@ -0,0 +1,281 @@
+import {
+  digestCanonical,
+  type JsonSchema,
+  type KindReaderRegistration,
+  type KindSemanticContract,
+  type KindSpecRevision,
+  type KindSubjectOwner,
+  type PortableSpec,
+} from 'halfcode-compiler.xnl/resource-core';
+import {
+  createKindSpecRevision,
+  createKindSubjectOwner,
+} from 'halfcode-compiler.xnl/kind-definition';
+
+export const DEPA_AI_RESOURCE_KINDS = Object.freeze([
+  'AIAgentDefinition',
+  'AgentMessageSource',
+  'AgentContextPipeline',
+  'Prompt',
+  'Tool',
+  'MessageSchema',
+  'EffectPolicy',
+  'MaterialPort',
+  'MaterialBinding',
+  'RequestMaterial',
+  'ContextMaterial',
+  'AIWorkflowAppBundle',
+  'AICtrlWorkflow',
+  'AIDataWorkflow',
+] as const);
+
+export type DepaAIResourceKind = (typeof DEPA_AI_RESOURCE_KINDS)[number];
+
+export const DEPA_AI_RESOURCE_ENVELOPE_VERSION = 'halfcode.resource-envelope/v1' as const;
+export const DEPA_AI_RESOURCE_SPEC_VERSION = 1 as const;
+export const DEPA_AI_RESOURCE_KIND_OWNER_PACKAGE_ID = 'ai-workflow-contract' as const;
+export const DEPA_AI_RESOURCE_SEMANTIC_API_VERSION = 'depa.flows/v1' as const;
+
+const subjectFqnFor = (kind: DepaAIResourceKind): `Depa.Flows.KindDefinition.${DepaAIResourceKind}` =>
+  `Depa.Flows.KindDefinition.${kind}`;
+
+export const DEPA_AI_RESOURCE_KIND_OWNER_PACKAGE_FINGERPRINT = digestCanonical(Object.freeze({
+  authority: 'ai-workflow-contract/depa-ai-resource-kinds/v1',
+  ownerPackageId: DEPA_AI_RESOURCE_KIND_OWNER_PACKAGE_ID,
+  subjects: Object.freeze(DEPA_AI_RESOURCE_KINDS.map(subjectFqnFor).sort(compareCodeUnits)),
+  semanticContractVersion: DEPA_AI_RESOURCE_SEMANTIC_API_VERSION,
+}));
+
+interface KindSchemaShape {
+  readonly requiredProperties?: readonly string[];
+  readonly requiredSubdomains?: readonly string[];
+}
+
+const KIND_SCHEMA_SHAPES: Readonly<Record<DepaAIResourceKind, KindSchemaShape>> = Object.freeze({
+  AIAgentDefinition: Object.freeze({ requiredSubdomains: Object.freeze(['ToolRefs', 'MaterialPortRefs']) }),
+  AgentMessageSource: Object.freeze({ requiredSubdomains: Object.freeze(['Content']) }),
+  AgentContextPipeline: Object.freeze({ requiredSubdomains: Object.freeze(['Content']) }),
+  Prompt: Object.freeze({ requiredProperties: Object.freeze(['template']) }),
+  Tool: Object.freeze({}),
+  MessageSchema: Object.freeze({ requiredProperties: Object.freeze(['schema']) }),
+  EffectPolicy: Object.freeze({ requiredProperties: Object.freeze(['toolMode']) }),
+  MaterialPort: Object.freeze({ requiredProperties: Object.freeze(['materialKind', 'required', 'cardinality']) }),
+  MaterialBinding: Object.freeze({ requiredSubdomains: Object.freeze(['AgentTaskRef', 'PortRef', 'MaterialRef']) }),
+  RequestMaterial: Object.freeze({ requiredProperties: Object.freeze(['value']) }),
+  ContextMaterial: Object.freeze({ requiredProperties: Object.freeze(['value']) }),
+  AIWorkflowAppBundle: Object.freeze({ requiredSubdomains: Object.freeze(['WorkflowBindings']) }),
+  AICtrlWorkflow: Object.freeze({}),
+  AIDataWorkflow: Object.freeze({}),
+});
+
+const KIND_SEMANTIC_OPERATIONS: Readonly<Record<DepaAIResourceKind, readonly string[]>> = Object.freeze({
+  AIAgentDefinition: Object.freeze(['projectAIWorkflowAgentResources', 'freezeAIAgentTaskResources']),
+  AgentMessageSource: Object.freeze(['projectAIWorkflowAgentResources', 'compileAgentMessageSource']),
+  AgentContextPipeline: Object.freeze(['projectAIWorkflowAgentResources', 'compileAgentContextPipeline']),
+  Prompt: Object.freeze(['projectAIWorkflowAgentResources', 'compileAgentMessagePrefix']),
+  Tool: Object.freeze(['projectAIWorkflowAgentResources', 'freezeAIAgentTaskResources']),
+  MessageSchema: Object.freeze(['projectAIWorkflowAgentResources', 'validateExecutableMessageSchema']),
+  EffectPolicy: Object.freeze(['projectAIWorkflowAgentResources', 'validateExecutableEffectPolicy']),
+  MaterialPort: Object.freeze(['projectAIWorkflowAgentResources', 'validateMaterialPortBindings']),
+  MaterialBinding: Object.freeze(['projectAIWorkflowAgentResources', 'freezeAIAgentTaskResources']),
+  RequestMaterial: Object.freeze(['projectAIWorkflowAgentResources', 'projectMaterialValue']),
+  ContextMaterial: Object.freeze(['projectAIWorkflowAgentResources', 'projectMaterialValue']),
+  AIWorkflowAppBundle: Object.freeze(['projectAIWorkflowAppBundles']),
+  AICtrlWorkflow: Object.freeze(['loadAICtrlWorkflowSources', 'projectAIWorkflowAppBundles']),
+  AIDataWorkflow: Object.freeze(['loadAIDataWorkflowSources', 'projectAIWorkflowAppBundles']),
+});
+
+const KIND_REFERENCE_ROLES: Readonly<Record<DepaAIResourceKind, readonly string[]>> = Object.freeze({
+  AIAgentDefinition: Object.freeze([
+    'message-prompt',
+    'message-schema',
+    'message-source',
+    'context-pipeline',
+    'input-schema',
+    'output-schema',
+    'tool',
+    'effect-policy',
+    'material-port',
+  ]),
+  AgentMessageSource: Object.freeze([]),
+  AgentContextPipeline: Object.freeze([]),
+  Prompt: Object.freeze([]),
+  Tool: Object.freeze([]),
+  MessageSchema: Object.freeze([]),
+  EffectPolicy: Object.freeze([]),
+  MaterialPort: Object.freeze(['schema']),
+  MaterialBinding: Object.freeze(['agent-task', 'material-port', 'material-value']),
+  RequestMaterial: Object.freeze([]),
+  ContextMaterial: Object.freeze([]),
+  AIWorkflowAppBundle: Object.freeze(['workflow-binding']),
+  AICtrlWorkflow: Object.freeze([]),
+  AIDataWorkflow: Object.freeze([]),
+});
+
+export interface DepaAIResourceKindContract {
+  readonly kind: DepaAIResourceKind;
+  readonly subjectFqn: `Depa.Flows.KindDefinition.${DepaAIResourceKind}`;
+  readonly owner: KindSubjectOwner;
+  readonly revision: KindSpecRevision;
+  readonly reader: KindReaderRegistration<PortableSpec>;
+  readonly kindDefinitionSource: string;
+}
+
+function authoredSpecSchema(kind: DepaAIResourceKind): JsonSchema {
+  const shape = KIND_SCHEMA_SHAPES[kind];
+  const propertiesSchema = Object.freeze({
+    type: 'object',
+    ...(shape.requiredProperties && shape.requiredProperties.length > 0
+      ? { required: Object.freeze([...shape.requiredProperties]) }
+      : {}),
+  });
+  const subdomainsSchema = Object.freeze({
+    type: 'object',
+    ...(shape.requiredSubdomains && shape.requiredSubdomains.length > 0
+      ? { required: Object.freeze([...shape.requiredSubdomains]) }
+      : {}),
+  });
+  return Object.freeze({
+    type: 'object',
+    required: Object.freeze(['properties', 'body', 'subdomains']),
+    properties: Object.freeze({
+      properties: propertiesSchema,
+      body: Object.freeze({ type: 'array' }),
+      subdomains: subdomainsSchema,
+      text: Object.freeze({ type: 'string' }),
+    }),
+    additionalProperties: false,
+  });
+}
+
+function semanticContract(kind: DepaAIResourceKind): KindSemanticContract {
+  return Object.freeze({
+    semanticValidatorFingerprint: digestCanonical(Object.freeze({
+      authority: 'ai-workflow-contract/depa-ai-resource-kinds/v1',
+      kind,
+      role: 'closed-domain-semantic-validation',
+      operations: KIND_SEMANTIC_OPERATIONS[kind],
+    })),
+    referenceProjectionFingerprint: digestCanonical(Object.freeze({
+      authority: 'ai-workflow-contract/depa-ai-resource-kinds/v1',
+      kind,
+      role: 'typed-resource-reference-projection',
+      relations: KIND_REFERENCE_ROLES[kind],
+    })),
+    compilerInputFingerprint: digestCanonical(Object.freeze({
+      authority: 'ai-workflow-contract/depa-ai-resource-kinds/v1',
+      kind,
+      role: 'authored-spec-envelope-projection',
+      fields: Object.freeze(['properties', 'body', 'subdomains', 'text']),
+    })),
+  });
+}
+
+function readerRegistration(
+  kind: DepaAIResourceKind,
+  revision: KindSpecRevision,
+): KindReaderRegistration<PortableSpec> {
+  const readerId = `ai-workflow-contract.${kind}.reader.v1`;
+  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',
+      readerId,
+      kind,
+      contractFingerprint: revision.contractFingerprint,
+      operations: KIND_SEMANTIC_OPERATIONS[kind],
+      implementation: 'identity-read-of-halfcode-validated-portable-spec',
+    })),
+    compatibilityPolicy: 'exact',
+    read: (spec: PortableSpec): PortableSpec => spec,
+  });
+}
+
+function renderKindDefinition(owner: KindSubjectOwner, revision: KindSpecRevision): string {
+  return [
+    `<KindDefinition #${owner.subjectFqn} envelopeVersion="${DEPA_AI_RESOURCE_ENVELOPE_VERSION}" specVersion=1 {`,
+    '  lifecycle = "Stable"',
+    `  resourceKind = "${owner.kind}"`,
+    `  subjectFqn = "${owner.subjectFqn}"`,
+    '  sourceShapes = ["single-file"]',
+    `  documentCardinality = "${owner.sourceContract.documentCardinality}"`,
+    `  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}"`,
+    '    }>',
+    '  ]>',
+    ')>',
+    '',
+  ].join('\n');
+}
+
+function createContract(kind: DepaAIResourceKind): DepaAIResourceKindContract {
+  const subjectFqn = subjectFqnFor(kind);
+  const owner = createKindSubjectOwner({
+    kind,
+    subjectFqn,
+    ownerPackageId: DEPA_AI_RESOURCE_KIND_OWNER_PACKAGE_ID,
+    ownerPackageFingerprint: DEPA_AI_RESOURCE_KIND_OWNER_PACKAGE_FINGERPRINT,
+    sourceShapes: Object.freeze(['single-file']),
+    documentCardinality: 'one',
+  });
+  const revision = createKindSpecRevision({
+    kind,
+    subjectFqn,
+    specVersion: DEPA_AI_RESOURCE_SPEC_VERSION,
+    specSchema: authoredSpecSchema(kind),
+    semanticContract: semanticContract(kind),
+    sourceContractFingerprint: owner.sourceContract.sourceContractFingerprint,
+    stability: 'stable',
+  });
+  return Object.freeze({
+    kind,
+    subjectFqn,
+    owner,
+    revision,
+    reader: readerRegistration(kind, revision),
+    kindDefinitionSource: renderKindDefinition(owner, revision),
+  });
+}
+
+export const DEPA_AI_RESOURCE_KIND_CONTRACTS: readonly DepaAIResourceKindContract[] = Object.freeze(
+  DEPA_AI_RESOURCE_KINDS.map(createContract),
+);
+
+export const DEPA_AI_RESOURCE_KIND_OWNERS: readonly KindSubjectOwner[] = Object.freeze(
+  DEPA_AI_RESOURCE_KIND_CONTRACTS.map((contract) => contract.owner),
+);
+
+export const DEPA_AI_RESOURCE_KIND_SPEC_REVISIONS: readonly KindSpecRevision[] = Object.freeze(
+  DEPA_AI_RESOURCE_KIND_CONTRACTS.map((contract) => contract.revision),
+);
+
+export const DEPA_AI_RESOURCE_KIND_READER_REGISTRATIONS: readonly KindReaderRegistration<PortableSpec>[] = Object.freeze(
+  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]),
+);
+
+export function depaAIResourceKindContract(kind: DepaAIResourceKind): DepaAIResourceKindContract {
+  const contract = CONTRACTS_BY_KIND.get(kind);
+  if (!contract) throw new Error(`Unknown depa AI resource Kind '${kind}'.`);
+  return contract;
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}