ai-workflow-contract 0.1.8 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-contract",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "private": false,
   "description": "Shared AI workflow contracts over WorkCtrlFlow and EagerDataFlow substrates",
   "type": "module",
@@ -9,8 +9,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "eager-data-flow-contract": "0.1.3",
-    "halfcode-compiler.xnl": "0.2.2",
+    "eager-data-flow-contract": "0.1.4",
+    "halfcode-compiler.xnl": "0.3.0",
     "task-manager-contract": "0.1.3",
     "work-ctrl-flow-contract": "0.1.3"
   },

package/src/index.ts

@@ -4,10 +4,14 @@ import type {
   ResourceDependencySnapshot,
   ResourceRecord,
   ResourceRegistry,
-  ResourceTree,
+  AuthoredResourceTree,
+  ResolvedResourceTree,
   ResourceValue,
   Sha256Digest,
 } from 'halfcode-compiler.xnl/resource-core';
+import type {
+  ResourceAuthoringProposal,
+} from 'halfcode-compiler.xnl/authoring-runtime';
 import type {
   FlowBundleSpec,
   FlowClosedObject,
@@ -19,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,
@@ -145,7 +150,8 @@ export interface ProjectAIWorkflowAppBundlesOptions {
 }
 
 export interface LoadedAIWorkflowResourcePackage {
-  readonly tree: ResourceTree;
+  readonly authoredTree: AuthoredResourceTree;
+  readonly tree: ResolvedResourceTree;
   readonly appBundles: readonly AIWorkflowAppBundleProjection[];
 }
 
@@ -156,6 +162,8 @@ export type MaterialCardinality = 'one' | 'many';
 export type AIWorkflowAgentResourceRelation =
   | 'agent-message-prompt'
   | 'agent-message-schema'
+  | 'agent-message-source'
+  | 'agent-context-pipeline'
   | 'agent-input-schema'
   | 'agent-output-schema'
   | 'agent-tool'
@@ -196,6 +204,20 @@ export interface AIAgentMessageProjection {
   readonly schema?: AIWorkflowMessageSchemaProjection;
 }
 
+export interface AIAgentStaticMessagePrefixProjection extends AIAgentMessageProjection {
+  readonly type: 'message';
+}
+
+export interface AIAgentMessageSourcePrefixProjection {
+  readonly type: 'message-source';
+  readonly id: string;
+  readonly source: AIWorkflowTypedResourceRef;
+}
+
+export type AIAgentMessagePrefixItemProjection =
+  | AIAgentStaticMessagePrefixProjection
+  | AIAgentMessageSourcePrefixProjection;
+
 export interface MaterialPortProjection {
   readonly kind: 'MaterialPort';
   readonly fqn: string;
@@ -210,7 +232,10 @@ export interface AIAgentDefinitionProjection {
   readonly kind: 'AIAgentDefinition';
   readonly fqn: string;
   readonly resource: ResourceRecord;
+  readonly messagePrefix: readonly AIAgentMessagePrefixItemProjection[];
+  /** Static compatibility view for legacy consumers during MessagePrefix adoption. */
   readonly messages: readonly AIAgentMessageProjection[];
+  readonly contextPipeline?: AIWorkflowTypedResourceRef;
   readonly inputSchema?: AIWorkflowMessageSchemaProjection;
   readonly outputSchema?: AIWorkflowMessageSchemaProjection;
   readonly tools: readonly AIWorkflowTypedResourceRef[];
@@ -258,6 +283,131 @@ export interface FrozenAIAgentTaskBinding {
   readonly closureResourceIds: readonly string[];
 }
 
+export const AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION =
+  'ai-workflow.agent-definition-selection/v1' as const;
+
+export interface AIAgentTaskRequirement {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly requirementId: string;
+  /** Audit/model evidence only. It is never a code-level routing input. */
+  readonly objective: string;
+  readonly inputSchemaRef?: `resource://${string}`;
+  readonly outputSchemaRef?: `resource://${string}`;
+  readonly requiredToolRefs: readonly `resource://${string}`[];
+  readonly requiredEffectPolicyRef?: `resource://${string}`;
+  readonly requiredToolMode?: AIWorkflowEffectToolMode;
+  readonly requiredMaterialPortRefs: readonly `resource://${string}`[];
+  readonly requiredContextPipelineRef?: `resource://${string}`;
+  readonly requiredMessageSourceRefs: readonly `resource://${string}`[];
+}
+
+export interface AIAgentTaskRequirementProjection {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly requirement: AIAgentTaskRequirement;
+  readonly requirementDigest: Sha256Digest;
+}
+
+export interface AIAgentDefinitionCandidateContract {
+  readonly inputSchemaRef?: `resource://${string}`;
+  readonly outputSchemaRef?: `resource://${string}`;
+  readonly toolRefs: readonly `resource://${string}`[];
+  readonly effectPolicyRef?: `resource://${string}`;
+  readonly effectToolMode?: AIWorkflowEffectToolMode;
+  readonly materialPortRefs: readonly `resource://${string}`[];
+  readonly contextPipelineRef?: `resource://${string}`;
+  readonly messageSourceRefs: readonly `resource://${string}`[];
+}
+
+export interface AIAgentDefinitionAuthoringEvidence {
+  readonly schemaVersion: 'ai-workflow.agent-definition-authoring-evidence/v1';
+  readonly planDigest: Sha256Digest;
+  readonly transactionId: string;
+  readonly receiptDigest: Sha256Digest;
+}
+
+export interface AIAgentDefinitionCandidate {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly contentDigest: Sha256Digest;
+  readonly registryRevision: Sha256Digest;
+  readonly contract: AIAgentDefinitionCandidateContract;
+  readonly candidateDigest: Sha256Digest;
+  readonly authoringEvidence?: AIAgentDefinitionAuthoringEvidence;
+}
+
+export interface AIAgentDefinitionCandidateSet {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly registryRevision: Sha256Digest;
+  readonly candidates: readonly AIAgentDefinitionCandidate[];
+  readonly candidateSetDigest: Sha256Digest;
+}
+
+interface AIAgentDefinitionSelectionDecisionBase {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly reason: string;
+}
+
+export interface SelectExistingAIAgentDefinitionDecision
+  extends AIAgentDefinitionSelectionDecisionBase {
+  readonly mode: 'select-existing';
+  readonly candidateRef: `resource://${string}`;
+  readonly candidateDigest: Sha256Digest;
+}
+
+export interface AuthorNewAIAgentDefinitionDecision
+  extends AIAgentDefinitionSelectionDecisionBase {
+  readonly mode: 'author-new';
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly proposal: ResourceAuthoringProposal;
+}
+
+export type AIAgentDefinitionSelectionDecision =
+  | SelectExistingAIAgentDefinitionDecision
+  | AuthorNewAIAgentDefinitionDecision;
+
+export type AIAgentDefinitionSelectionRejectionCode =
+  | 'decision-invalid'
+  | 'requirement-stale'
+  | 'candidate-set-stale'
+  | 'candidate-missing'
+  | 'candidate-digest-mismatch'
+  | 'candidate-incompatible'
+  | 'authoring-in-progress'
+  | 'authoring-proposal-invalid';
+
+export interface SelectedAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'selected';
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly candidate: AIAgentDefinitionCandidate;
+  readonly reason: string;
+}
+
+export interface AuthorNewAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'authoring-request';
+  readonly requirementDigest: Sha256Digest;
+  readonly candidateSetDigest: Sha256Digest;
+  readonly agentDefinitionRef: `resource://${string}`;
+  readonly proposal: ResourceAuthoringProposal;
+  readonly reason: string;
+}
+
+export interface RejectedAIAgentDefinitionAdmission {
+  readonly schemaVersion: typeof AI_AGENT_DEFINITION_SELECTION_SCHEMA_VERSION;
+  readonly status: 'rejected';
+  readonly code: AIAgentDefinitionSelectionRejectionCode;
+  readonly message: string;
+}
+
+export type AIAgentDefinitionSelectionAdmission =
+  | SelectedAIAgentDefinitionAdmission
+  | AuthorNewAIAgentDefinitionAdmission
+  | RejectedAIAgentDefinitionAdmission;
+
 export type AIWorkflowNodeType =
   | 'agent'
   | 'data'
@@ -410,8 +560,8 @@ export interface AIWorkflowExecutionReceipt {
 }
 
 export type AIAgentSelector =
-  | { readonly byInstanceId: string; readonly byInstanceName?: never }
-  | { readonly byInstanceName: string; readonly byInstanceId?: never };
+  | { readonly byId: string; readonly byName?: never }
+  | { readonly byName: string; readonly byId?: never };
 
 export interface AIAgentInvocation<Input extends FlowClosedValue = FlowClosedValue> {
   readonly kind: 'ai.agent';

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;
+}