@openapi-flow/core 0.3.0 → 0.3.1

package/README.md

@@ -2,7 +2,9 @@
 
 Zod `^4.6.5` is a required peer, shared with the host rather than installed as a separately pinned runtime copy. Development tests use 4.6.5; the strict installed-consumer check also uses the host's 4.6.7. This preserves the public schema type boundary without casts or dependency overrides.
 
-Version **0.3.0**. Canonical draft, clarification and runtime-input APIs described below are included in this release. Ajv 8.20.0 does not correctly validate a declared `properties.__proto__`; generated validation may reject valid data or omit that property's constraints. This known limitation was explicitly accepted for release, without renaming data or skipping its failing regression. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.0.md).
+Version **0.3.1**. Canonical draft, clarification and runtime-input APIs described below are included in this release. Ajv 8.20.0 does not correctly validate a declared `properties.__proto__`; generated validation may reject valid data or omit that property's constraints. This previously accepted limitation remains unchanged, without renaming data or skipping its failing regression. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.1.md).
+
+Connection planning accepts explicit current `deferredApiInputIds` derived with `collectDeferredApiInputSlots`. Missing inputs remain absent and require canonical template preflight before execution; supplied values and the full DAG are still validated. See [input deferral](https://github.com/carefreelife98/openapi-flow/blob/main/docs/deferred-connection-planning.md).
 
 canonical `gapNodes` and the separate `createWorkflowDraftCapabilityGap`,
 `inspectWorkflowDraftCapabilityGap`, `describeWorkflowDraftCapabilityGap` functions

package/dist/public-api.d.ts

@@ -184,6 +184,7 @@ export type * from './types/api-bindings.js';
 export type * from './types/api-binding-planning.js';
 export type * from './types/native-node-planning.js';
 export type * from './types/workflow-connection-planning.js';
+export type * from './types/workflow-api-input-readiness.js';
 export type * from './types/workflow-planning-materials.js';
 export type * from './types/workflow-graph-planning.js';
 export { describeWorkflowGraphPlanning } from './workflow/graphs/describe-workflow-graph-planning.js';

package/dist/schemas/workflow-api-input-deferral-schema.d.ts

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export declare const workflowDeferredApiInputIdsSchema: z.ZodArray<z.ZodString>;

package/dist/schemas/workflow-api-input-deferral-schema.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export const workflowDeferredApiInputIdsSchema = z
+    .array(z.string().refine((value) => value.trim().length > 0))
+    .refine((ids) => new Set(ids).size === ids.length, {
+    message: 'deferredApiInputIds must contain distinct current input slot IDs',
+});

package/dist/types/reviewable-workflow.d.ts

@@ -2,6 +2,7 @@ import type { ApiOperationContract } from './api-operation.js';
 import type { ApiOperationKey } from './api-catalog.js';
 import type { OutputBinding } from './api-arguments.js';
 import type { WorkflowConnectionPlanningRecord } from './workflow-connection-planning.js';
+import type { WorkflowApiInputDeferral } from './workflow-api-input-readiness.js';
 import type { WorkflowApiMaterial, WorkflowCapability, WorkflowGraphPlan, PlannedNativeNode, WorkflowPlanEdge } from './workflow-plan.js';
 export interface WorkflowReviewGap {
     id: string;
@@ -44,7 +45,7 @@ export interface ReviewableWorkflowGraphPlan extends WorkflowGraphPlan {
     /** Optional original connection-only decision and supplied-material evidence. */
     connectionPlanning?: WorkflowConnectionPlanningRecord;
 }
-export interface ReviewableWorkflowPlanningContext {
+export interface ReviewableWorkflowPlanningContext extends WorkflowApiInputDeferral {
     materials: ReviewableWorkflowApiMaterial[];
     capabilities: WorkflowCapability[];
 }

package/dist/types/workflow-api-input-readiness.d.ts

@@ -0,0 +1,8 @@
+import type { ReviewableWorkflowApiMaterial } from './reviewable-workflow.js';
+export interface WorkflowApiInputDeferral {
+    /** Exact current OAS-derived input slot IDs explicitly deferred by the caller. */
+    deferredApiInputIds?: string[];
+}
+export interface WorkflowApiInputReadinessInput extends WorkflowApiInputDeferral {
+    materials: ReviewableWorkflowApiMaterial[];
+}

package/dist/types/workflow-api-input-readiness.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-connection-planning.d.ts

@@ -2,7 +2,9 @@ import type { ReviewableWorkflowApiMaterial, ReviewableWorkflowGraphPlan, Review
 import type { PlannedNativeNode, WorkflowCapability, WorkflowPlanEdge, WorkflowPlanNodeContract } from './workflow-plan.js';
 import type { PreparedNativeNodeMaterial } from './native-node-planning.js';
 import type { WorkflowPlanningSourceEvidence } from './workflow-planning-materials.js';
-export interface WorkflowConnectionMaterialInput {
+import type { WorkflowApiInputDeferral } from './workflow-api-input-readiness.js';
+import type { DeferredApiInputSlot } from './deferred-api-inputs.js';
+export interface WorkflowConnectionMaterialInput extends WorkflowApiInputDeferral {
     materials?: ReviewableWorkflowApiMaterial[];
     capabilities?: WorkflowCapability[];
     nativeNodes?: PlannedNativeNode[];
@@ -12,13 +14,14 @@ export interface WorkflowConnectionMaterialInput {
 export interface WorkflowConnectionPlanningInput extends WorkflowConnectionMaterialInput {
     scenario: string;
 }
-export interface WorkflowConnectionMaterials {
+export interface WorkflowConnectionMaterials extends WorkflowApiInputDeferral {
     materials: ReviewableWorkflowApiMaterial[];
     capabilities: WorkflowCapability[];
     nativeNodes: PlannedNativeNode[];
     gaps: WorkflowReviewGap[];
     edges: WorkflowPlanEdge[];
     contracts: WorkflowPlanNodeContract[];
+    deferredApiInputs?: DeferredApiInputSlot[];
 }
 export interface WorkflowConnectionApiRole {
     callId: string;
@@ -39,6 +42,8 @@ export interface WorkflowConnectionPlanningContext {
     gaps: WorkflowReviewGap[];
     readyCallIds: string[];
     apiRoles: WorkflowConnectionApiRole[];
+    /** Code-derived missing values, never missing API capabilities or generated literals. */
+    deferredApiInputs?: DeferredApiInputSlot[];
 }
 export interface WorkflowConnectionPlanningSnapshot extends WorkflowConnectionMaterials {
     scenario: string;

package/dist/workflow/connections/describe-workflow-connection-planning.js

@@ -30,6 +30,7 @@ export function describeWorkflowConnectionPlanning(input) {
     const materials = captured.materials;
     const prepared = prepareWorkflowConnectionMaterials({
         materials,
+        deferredApiInputIds: input.deferredApiInputIds,
         capabilities: captured.capabilities,
         nativeNodes: captured.preparedNativeNodes,
         gaps: structuredClone((input.gaps === undefined ? [] : input.gaps).map((gap) => workflowReviewGapSchema.parse(gap))),
@@ -65,6 +66,9 @@ export function describeWorkflowConnectionPlanning(input) {
                     purpose: material.purpose,
                 },
             ]),
+        ...(prepared.deferredApiInputs === undefined
+            ? {}
+            : { deferredApiInputs: structuredClone(prepared.deferredApiInputs) }),
     };
     return {
         input: { ...prepared, scenario },

package/dist/workflow/connections/prepare-workflow-connection-materials.js

@@ -1,7 +1,7 @@
 import { createReviewableNodeContracts } from '../create-reviewable-node-contracts.js';
 import { createNativeOutputContracts } from '../create-native-output-contracts.js';
 import { validateWorkflowEdges } from '../validate-workflow-edges.js';
-import { inspectApiArgumentRequirements } from '../../arguments/clarification/inspect-api-argument-requirements.js';
+import { validateWorkflowApiInputReadiness } from '../validate-workflow-api-input-readiness.js';
 import { validateApiBindingAssignments } from '../../bindings/validate-api-binding-assignments.js';
 import { validateNativeApiResponseReferences } from '../validate-native-api-response-references.js';
 import { createNativeParameterGenerationContract } from '../../schemas/create-native-parameter-generation-contract.js';
@@ -57,17 +57,10 @@ export function prepareWorkflowConnectionMaterials(input) {
         nativeNodes,
         capabilities,
     });
-    for (const material of materials) {
-        if (material.status !== 'ready')
-            continue;
-        const args = material.arguments;
-        const validation = inspectApiArgumentRequirements({
-            operation: material.operation,
-            ...args,
-        });
-        if (args.unresolvedInputs.length || validation.status !== 'ready')
-            throw new Error(`materials[${args.callId}] has unresolved OAS request inputs or scenario-requested inputs`);
-    }
+    const deferredApiInputs = validateWorkflowApiInputReadiness({
+        materials,
+        deferredApiInputIds: input.deferredApiInputIds,
+    });
     if (materials.length)
         validateApiBindingAssignments({
             nativeOutputs,
@@ -104,5 +97,16 @@ export function prepareWorkflowConnectionMaterials(input) {
         plan,
     });
     validateWorkflowEdges({ contracts, edges });
-    return { materials, capabilities, nativeNodes, gaps, edges, contracts };
+    return {
+        materials,
+        capabilities,
+        nativeNodes,
+        gaps,
+        edges,
+        contracts,
+        ...(input.deferredApiInputIds === undefined
+            ? {}
+            : { deferredApiInputIds: [...input.deferredApiInputIds] }),
+        ...(deferredApiInputs.length ? { deferredApiInputs } : {}),
+    };
 }

package/dist/workflow/validate-reviewable-workflow-graph-plan.js

@@ -1,4 +1,4 @@
-import { inspectApiArgumentRequirements } from '../arguments/clarification/inspect-api-argument-requirements.js';
+import { validateWorkflowApiInputReadiness } from './validate-workflow-api-input-readiness.js';
 import { validateApiBindingAssignments } from '../bindings/validate-api-binding-assignments.js';
 import { validateApiBindingGaps } from '../bindings/validate-api-binding-gaps.js';
 import { createReviewableNodeContracts } from './create-reviewable-node-contracts.js';
@@ -31,20 +31,8 @@ export function validateReviewableWorkflowGraphPlan(input) {
                 item.gapIds.some((id) => !blocked.get(item.callId)?.includes(id)))
                 throw new Error(`review plan omitted blocked requirement for ${item.callId}`);
         }
-        else {
-            const args = item.arguments;
-            const result = inspectApiArgumentRequirements({
-                operation: item.operation,
-                callId: args.callId,
-                requestedInputs: args.requestedInputs,
-                values: args.values,
-                bindings: args.bindings,
-                requestMediaType: args.requestMediaType,
-            });
-            if (args.unresolvedInputs.length || result.status !== 'ready')
-                throw new Error(`review ready material ${args.callId} has unresolved request inputs`);
-        }
     }
+    validateWorkflowApiInputReadiness(input);
     if (materials.length)
         validateApiBindingAssignments({
             nativeOutputs: createNativeOutputContracts({

package/dist/workflow/validate-workflow-api-input-readiness.d.ts

@@ -0,0 +1,4 @@
+import type { DeferredApiInputSlot } from '../types/deferred-api-inputs.js';
+import type { WorkflowApiInputReadinessInput } from '../types/workflow-api-input-readiness.js';
+/** Missing literals may be planned, but only with explicit, current slot ownership. */
+export declare function validateWorkflowApiInputReadiness(input: WorkflowApiInputReadinessInput): DeferredApiInputSlot[];

package/dist/workflow/validate-workflow-api-input-readiness.js

@@ -0,0 +1,33 @@
+import { collectDeferredApiInputSlots } from '../inputs/collect-deferred-api-input-slots.js';
+import { workflowDeferredApiInputIdsSchema } from '../schemas/workflow-api-input-deferral-schema.js';
+/** Missing literals may be planned, but only with explicit, current slot ownership. */
+export function validateWorkflowApiInputReadiness(input) {
+    const ids = input.deferredApiInputIds === undefined
+        ? []
+        : workflowDeferredApiInputIdsSchema.parse(input.deferredApiInputIds);
+    const ready = input.materials.filter((material) => material.status === 'ready');
+    // This validates supplied values against their original OAS before deriving missing slots.
+    const slots = collectDeferredApiInputSlots({
+        materials: ready.map((material) => ({
+            operation: material.operation,
+            callId: material.arguments.callId,
+            values: material.arguments.values,
+            bindings: material.arguments.bindings,
+            requestMediaType: material.arguments.requestMediaType,
+            requestedInputs: material.arguments.requestedInputs,
+        })),
+    });
+    for (const id of ids)
+        if (!slots.some((slot) => slot.id === id))
+            throw new Error(`deferredApiInputIds contains unknown or stale slot ${id}`);
+    for (const slot of slots)
+        if (!ids.includes(slot.id))
+            throw new Error(`materials[${slot.callId}] has unresolved OAS request inputs or scenario-requested inputs: ${slot.targetPointer}; explicitly defer current slot ${slot.id} or supply its value`);
+    for (const material of ready) {
+        const args = material.arguments;
+        if (new Set(args.unresolvedInputs).size !== args.unresolvedInputs.length ||
+            args.unresolvedInputs.some((pointer) => !slots.some((slot) => slot.callId === args.callId && slot.targetPointer === pointer)))
+            throw new Error(`materials[${args.callId}].unresolvedInputs must name current OAS request input slots without duplicates`);
+    }
+    return slots;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "Engine-independent OpenAPI catalogs, operation contracts and typed request schemas",
   "keywords": [