@openapi-flow/core 0.3.0 → 0.3.2

package/README.md

@@ -2,7 +2,11 @@
 
 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.2**. 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.2.md).
+
+Native and fixed-material connection planning accept the optional, existing `WorkflowEntryPointContract` as `entrypoint`. Core validates and snapshots this owner-provided start alongside the other inputs; it does not infer one when absent, add a selectable trigger or let model output modify it.
+
+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/native-node-planning-record-schema.d.ts

@@ -4,6 +4,10 @@ export declare const nativeNodePlanningOptionsSchema: z.ZodObject<{
     planId: z.ZodString;
     scenario: z.ZodString;
     allowRuntimeParameters: z.ZodOptional<z.ZodBoolean>;
+    entrypoint: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const nativePlanningProposalSchema: z.ZodObject<{
     nativeNodes: z.ZodArray<z.ZodObject<{

package/dist/schemas/native-node-planning-record-schema.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
-import { planningEvidenceTextSchema } from './planning-evidence-schema.js';
+import { planningEvidenceTextSchema, workflowEntryPointContractSchema, } from './planning-evidence-schema.js';
 import { workflowDraftNativeNodeSchema } from './workflow-draft-schema.js';
 export const nativeNodePlanningOptionsSchema = z.strictObject({
     planId: planningEvidenceTextSchema,
     scenario: planningEvidenceTextSchema,
     allowRuntimeParameters: z.boolean().optional(),
+    entrypoint: workflowEntryPointContractSchema.optional(),
 });
 export const nativePlanningProposalSchema = z.strictObject({
     nativeNodes: z.array(workflowDraftNativeNodeSchema),

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/schemas/workflow-connection-planning-schema.d.ts

@@ -4,6 +4,10 @@ import type { WorkflowPlanningSourceEvidence } from '../types/workflow-planning-
 import type { WorkflowPlanNodeContract } from '../types/workflow-plan.js';
 export declare const workflowConnectionIdentitySchema: z.ZodObject<{
     scenario: z.ZodString;
+    entrypoint: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const workflowConnectionProposalSchema: z.ZodObject<{
     edges: z.ZodArray<z.ZodObject<{

package/dist/schemas/workflow-connection-planning-schema.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { planningEvidenceTextSchema } from './planning-evidence-schema.js';
+import { planningEvidenceTextSchema, workflowEntryPointContractSchema, } from './planning-evidence-schema.js';
 import { workflowDraftNativeNodeSchema, workflowDraftEdgeSchema, } from './workflow-draft-schema.js';
 import { workflowReviewGapSchema, workflowBlockedCallSchema, } from './workflow-planning-material-schema.js';
 export const workflowConnectionIdentitySchema = z.strictObject({
     scenario: planningEvidenceTextSchema,
+    entrypoint: workflowEntryPointContractSchema.optional(),
 });
 export const workflowConnectionProposalSchema = z.strictObject({
     edges: z.array(workflowDraftEdgeSchema),

package/dist/schemas/workflow-draft-edit-plan-schema.d.ts

@@ -21,13 +21,13 @@ export declare const workflowDraftEditPlanSchema: z.ZodObject<{
         decision: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
         newNodeId: z.ZodOptional<z.ZodString>;
         stages: z.ZodArray<z.ZodEnum<{
+            clarification: "clarification";
             "api-bindings": "api-bindings";
             "api-arguments": "api-arguments";
             "native-parameters": "native-parameters";
             requirements: "requirements";
             connections: "connections";
             "resolve-contracts": "resolve-contracts";
-            clarification: "clarification";
         }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/types/native-node-planning.d.ts

@@ -1,4 +1,5 @@
 import type { ApiBindingMaterial } from './api-bindings.js';
+import type { WorkflowPlanningContext } from './planning-evidence.js';
 import type { z } from 'zod';
 import type { JsonValueObject } from './api-arguments.js';
 import type { JsonObject } from './openapi.js';
@@ -8,7 +9,7 @@ import type { NativeInstanceDependencyPlan, NativeNodeConfigurationDependencies
 import type { WorkflowNativeMaterialSources, MissingWorkflowNativeMaterialRequirement, ResolveNativeMaterialSnapshotInput } from './native-material-snapshot.js';
 import type { WorkflowReviewGap } from './reviewable-workflow.js';
 import type { PlannedNativeNode, WorkflowCapability, WorkflowPlanGap, WorkflowPlanNodeContract, NativeRuntimeParameterSelection } from './workflow-plan.js';
-export interface NativeNodePlanningInput {
+export interface NativeNodePlanningInput extends Pick<WorkflowPlanningContext, 'entrypoint'> {
     planId: string;
     scenario: string;
     capabilities?: WorkflowCapability[];
@@ -38,7 +39,7 @@ export interface NativePlanningApiMaterial {
     operation: ApiBindingMaterial['operation']['operation'];
     effective: ApiBindingMaterial['operation']['effective'];
 }
-export interface NativeNodePlanningContext {
+export interface NativeNodePlanningContext extends Pick<WorkflowPlanningContext, 'entrypoint'> {
     scenario: string;
     apiMaterials: NativePlanningApiMaterial[];
     preparedNativeNodes: PreparedNativeNodeMaterial[];

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,23 +2,27 @@ 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';
+import type { WorkflowPlanningContext } from './planning-evidence.js';
+export interface WorkflowConnectionMaterialInput extends WorkflowApiInputDeferral {
     materials?: ReviewableWorkflowApiMaterial[];
     capabilities?: WorkflowCapability[];
     nativeNodes?: PlannedNativeNode[];
     gaps?: WorkflowReviewGap[];
     edges?: WorkflowPlanEdge[];
 }
-export interface WorkflowConnectionPlanningInput extends WorkflowConnectionMaterialInput {
+export interface WorkflowConnectionPlanningInput extends WorkflowConnectionMaterialInput, Pick<WorkflowPlanningContext, 'entrypoint'> {
     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;
@@ -30,7 +34,7 @@ export interface WorkflowNativeParameterReadiness {
     /** Explicit runtime ownership, not missing plan-time values or unresolved graph gaps. */
     executionInputPointers: string[];
 }
-export interface WorkflowConnectionPlanningContext {
+export interface WorkflowConnectionPlanningContext extends Pick<WorkflowPlanningContext, 'entrypoint'> {
     scenario: string;
     nodes: WorkflowPlanNodeContract[];
     nativeNodes?: PreparedNativeNodeMaterial[];
@@ -39,8 +43,10 @@ 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 {
+export interface WorkflowConnectionPlanningSnapshot extends WorkflowConnectionMaterials, Pick<WorkflowPlanningContext, 'entrypoint'> {
     scenario: string;
 }
 export interface WorkflowConnectionPlanningDescription {

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

@@ -8,9 +8,11 @@ import { createNativePlanningCapabilityMaterial } from '../planning/create-nativ
 import { prepareWorkflowConnectionMaterials } from './prepare-workflow-connection-materials.js';
 /** Capture declared data before awaiting the model; never clone opaque callbacks or forward audit metadata. */
 export function describeWorkflowConnectionPlanning(input) {
-    const { scenario } = workflowConnectionIdentitySchema.parse({
+    const identity = workflowConnectionIdentitySchema.parse({
         scenario: input.scenario,
+        ...(input.entrypoint === undefined ? {} : { entrypoint: input.entrypoint }),
     });
+    const { scenario } = identity;
     for (const field of [
         'materials',
         'capabilities',
@@ -30,13 +32,14 @@ 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))),
         edges: structuredClone((input.edges === undefined ? [] : input.edges).map((edge) => workflowDraftEdgeSchema.parse(edge))),
     });
     const context = {
-        scenario,
+        ...structuredClone(identity),
         nodes: structuredClone(prepared.contracts),
         ...(prepared.nativeNodes.length
             ? {
@@ -65,9 +68,12 @@ export function describeWorkflowConnectionPlanning(input) {
                     purpose: material.purpose,
                 },
             ]),
+        ...(prepared.deferredApiInputs === undefined
+            ? {}
+            : { deferredApiInputs: structuredClone(prepared.deferredApiInputs) }),
     };
     return {
-        input: { ...prepared, scenario },
+        input: { ...prepared, ...identity },
         context,
         sources: structuredClone({
             materials,

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/planning/describe-native-node-planning.js

@@ -10,6 +10,7 @@ export function describeNativeNodePlanning(input) {
         planId: input.planId,
         scenario: input.scenario,
         allowRuntimeParameters: input.allowRuntimeParameters,
+        ...(input.entrypoint === undefined ? {} : { entrypoint: input.entrypoint }),
     });
     const { capabilities, apiMaterials, preparedNativeNodes: prepared, } = captureWorkflowPlanningMaterials(input);
     const apiIds = apiMaterials.map((material) => material.callId);
@@ -28,6 +29,9 @@ export function describeNativeNodePlanning(input) {
         planningCapabilities,
         context: {
             scenario: options.scenario,
+            ...(options.entrypoint === undefined
+                ? {}
+                : { entrypoint: structuredClone(options.entrypoint) }),
             apiMaterials: apiMaterials.map(({ callId, operation, purpose }) => ({
                 callId,
                 ...(purpose === undefined ? {} : { purpose }),

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.2",
   "license": "MIT",
   "description": "Engine-independent OpenAPI catalogs, operation contracts and typed request schemas",
   "keywords": [