ai-workflow-contract 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-contract",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Shared AI workflow contracts over WorkCtrlFlow and EagerDataFlow substrates",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "eager-data-flow-contract": "0.1.0",
+    "halfcode-compiler.xnl": "0.2.2",
     "work-ctrl-flow-contract": "0.1.0"
   },
   "files": [
@@ -19,4 +20,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.com"
   }
-}
+}

package/src/index.ts

@@ -1,4 +1,12 @@
 import type { EagerDataFlowAuthoringPlan, EagerDataFlowValue } from 'eager-data-flow-contract';
+import type {
+  ResourceDependencyEdge,
+  ResourceDependencySnapshot,
+  ResourceRecord,
+  ResourceRegistry,
+  ResourceTree,
+  Sha256Digest,
+} from 'halfcode-compiler.xnl/resource-core';
 import type { FlowBundleSpec, WorkCtrlFlowRuntime } from 'work-ctrl-flow-contract';
 
 export type AIWorkflowKind = 'AICtrlWorkflow' | 'AIDataWorkflow';
@@ -9,8 +17,10 @@ export type AIWorkflowReusePolicy = 'semantic-hash' | 'never';
 
 export type AIWorkflowReusePolicySource = 'node' | 'node-type-default' | 'platform-default';
 
+/** @deprecated Generic resource-reference authority belongs to Halfcode. */
 export type AIWorkflowResourceRefScheme = 'vfs' | 'resource' | 'config' | 'secret';
 
+/** @deprecated Retained for 0.1.x compatibility; do not use for resource discovery. */
 export const AI_WORKFLOW_ALLOWED_RESOURCE_REF_SCHEMES = Object.freeze([
   'vfs',
   'resource',
@@ -18,8 +28,10 @@ export const AI_WORKFLOW_ALLOWED_RESOURCE_REF_SCHEMES = Object.freeze([
   'secret',
 ] as const satisfies readonly AIWorkflowResourceRefScheme[]);
 
+/** @deprecated Use normalized Halfcode ResourceRecord facts and typed domain refs. */
 export type AIWorkflowResourceRef = `${AIWorkflowResourceRefScheme}://${string}`;
 
+/** @deprecated This open vocabulary is not a Kind registry. Halfcode owns KindDefinition. */
 export type AIWorkflowResourceKind =
   | 'AIWorkflowAppBundle'
   | 'AIWorkflowCatalog'
@@ -33,6 +45,7 @@ export type AIWorkflowResourceKind =
   | 'SecretHandle'
   | (string & {});
 
+/** @deprecated Halfcode ResourceRecord owns generic resource identity and provenance. */
 export interface AIWorkflowResourceIdentity {
   readonly kind: AIWorkflowResourceKind;
   readonly fqn: string;
@@ -40,6 +53,7 @@ export interface AIWorkflowResourceIdentity {
   readonly revision?: string;
 }
 
+/** @deprecated Halfcode ResourcePackage/Catalog owns generic resource membership. */
 export interface AIWorkflowCatalogEntry {
   readonly id: string;
   readonly kind: AIWorkflowResourceKind;
@@ -47,11 +61,16 @@ export interface AIWorkflowCatalogEntry {
   readonly fqn?: string;
 }
 
+/** @deprecated Halfcode ResourcePackage/Catalog owns generic resource membership. */
 export interface AIWorkflowResourceCatalog {
   readonly id: string;
   readonly entries: readonly AIWorkflowCatalogEntry[];
 }
 
+/**
+ * @deprecated Compatibility DTO for the pre-Halfcode catalog surface.
+ * Use AIWorkflowAppBundleProjection for canonical consumers.
+ */
 export interface AIWorkflowAppBundleManifest {
   readonly kind: 'AIWorkflowAppBundle';
   readonly fqn: string;
@@ -60,6 +79,131 @@ export interface AIWorkflowAppBundleManifest {
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
 
+export type AIWorkflowDefinitionResourceKind = 'AICtrlWorkflow' | 'AIDataWorkflow';
+
+/**
+ * Minimal public Halfcode read port. ResourceTree.registry and
+ * EffectiveResourceRegistry both satisfy this shape without depa-flows owning
+ * either registry implementation.
+ */
+export type AIWorkflowResourceRegistryView = Pick<ResourceRegistry, 'byKind'>;
+
+export interface AIWorkflowBindingProjection {
+  readonly id: string;
+  readonly kind: AIWorkflowDefinitionResourceKind;
+  readonly ref: `resource://${string}`;
+  readonly entrypoint: boolean;
+  readonly resource: ResourceRecord;
+}
+
+export interface AIWorkflowAppBundleProjection {
+  readonly kind: 'AIWorkflowAppBundle';
+  readonly fqn: string;
+  readonly packageResourceId?: string;
+  readonly resource: ResourceRecord;
+  readonly workflowBindings: readonly AIWorkflowBindingProjection[];
+  readonly entrypoints: readonly AIWorkflowBindingProjection[];
+}
+
+export interface AIWorkflowResourceProjectionDiagnostic {
+  readonly code: string;
+  readonly location: string;
+  readonly message: string;
+}
+
+export interface ProjectAIWorkflowAppBundlesOptions {
+  readonly packageResourceId?: string;
+}
+
+export interface LoadedAIWorkflowResourcePackage {
+  readonly tree: ResourceTree;
+  readonly appBundles: readonly AIWorkflowAppBundleProjection[];
+}
+
+export type AIAgentMessageRole = 'system' | 'developer' | 'user' | 'assistant';
+
+export type MaterialCardinality = 'one' | 'many';
+
+export type AIWorkflowAgentResourceRelation =
+  | 'agent-message-prompt'
+  | 'agent-message-schema'
+  | 'agent-input-schema'
+  | 'agent-output-schema'
+  | 'agent-tool'
+  | 'agent-effect-policy'
+  | 'agent-material-port'
+  | 'material-port-schema'
+  | 'material-binding-port'
+  | 'material-binding-material'
+  | 'workflow-agent-task'
+  | 'workflow-material-binding';
+
+export interface AIWorkflowTypedResourceRef {
+  readonly kind: string;
+  readonly ref: `resource://${string}`;
+  readonly resource: ResourceRecord;
+}
+
+export interface AIAgentMessageProjection {
+  readonly id: string;
+  readonly role: AIAgentMessageRole;
+  readonly prompt: AIWorkflowTypedResourceRef;
+  readonly schema?: AIWorkflowTypedResourceRef;
+}
+
+export interface MaterialPortProjection {
+  readonly kind: 'MaterialPort';
+  readonly fqn: string;
+  readonly resource: ResourceRecord;
+  readonly materialKind: string;
+  readonly required: boolean;
+  readonly cardinality: MaterialCardinality;
+  readonly schema?: AIWorkflowTypedResourceRef;
+}
+
+export interface AIAgentDefinitionProjection {
+  readonly kind: 'AIAgentDefinition';
+  readonly fqn: string;
+  readonly resource: ResourceRecord;
+  readonly messages: readonly AIAgentMessageProjection[];
+  readonly inputSchema?: AIWorkflowTypedResourceRef;
+  readonly outputSchema?: AIWorkflowTypedResourceRef;
+  readonly tools: readonly AIWorkflowTypedResourceRef[];
+  readonly effectPolicy?: AIWorkflowTypedResourceRef;
+  readonly materialPorts: readonly AIWorkflowTypedResourceRef[];
+}
+
+export interface AIWorkflowAgentTaskRef {
+  readonly workflowKind: AIWorkflowDefinitionResourceKind;
+  readonly workflowRef: `resource://${string}`;
+  readonly nodeId: string;
+  readonly agentDefinitionRef: `resource://${string}`;
+}
+
+export interface MaterialBindingProjection {
+  readonly kind: 'MaterialBinding';
+  readonly fqn: string;
+  readonly resource: ResourceRecord;
+  readonly task: AIWorkflowAgentTaskRef;
+  readonly port: MaterialPortProjection;
+  readonly material: AIWorkflowTypedResourceRef;
+}
+
+export interface AIWorkflowAgentResourceProjection {
+  readonly agentDefinitions: readonly AIAgentDefinitionProjection[];
+  readonly materialPorts: readonly MaterialPortProjection[];
+  readonly materialBindings: readonly MaterialBindingProjection[];
+  readonly dependencyEdges: readonly ResourceDependencyEdge[];
+}
+
+export interface AIWorkflowRunResourceFreezeReceipt {
+  readonly schemaVersion: 'ai-workflow.run-resource-freeze/v1';
+  readonly task: AIWorkflowAgentTaskRef;
+  readonly bindingResourceIds: readonly string[];
+  readonly dependencySnapshot: ResourceDependencySnapshot;
+  readonly semanticFingerprint: Sha256Digest;
+}
+
 export type AIWorkflowNodeType =
   | 'agent'
   | 'data'