@openapi-flow/core

0.12.0: shared workflow input planning

createWorkflowInputCatalog prepares one immutable original-message catalog for all calls in a planning revision. A source ID owns its original message and lexical region. resolveWorkflowInputSelection extracts a selected JSON value or exact unquoted text range; callers never supply a replacement value or message identity. JSON retains its original type and text remains a string.

describeWorkflowApiArgumentTargets exposes finite OAS declaration templates, including explicit array indices, dynamic keys and recursive descendants. compileWorkflowApiArguments resolves those templates and original sources, deduplicates verified inputs, and applies the existing concrete-target, assembly, binding, confirmed-input and final request checks. Type projections only narrow choices; the original OAS still decides whether a concrete assignment is valid. The result retains independently checked calls and per-call validation rejections. Missing values stay missing-input requirements.

Plans carry a code-attached fingerprint covering originals, scenario, calls, OAS, roles, bindings and confirmed inputs. validateCompiledWorkflowApiArguments replays serialized receipts against an independent current context, including semantic enum evidence. Hosts must retain only validated receipts and supply only pending calls when replanning. These APIs do not implement a retry loop or change the existing single-call APIs. They do not guarantee business intent or the availability of a model or remote API.

0.11.0: validate complete literal construction plans

resolveApiLiteralValues resolves all selected destinations before assignment, rejecting duplicate or overlapping paths. Each original source is checked against its concrete remaining OAS destination before code assembles the request. Final request and source-coverage validation remain in place. Finite selected pointers retain the original recursive/dynamic schema context; schemas are not unrolled. listApiLiteralContainerTargets identifies roots whose original OAS admits object/array construction, preserving reference context. Scalar-only roots do not expose generic descendant sources. A wrong message attribution reports exact original message IDs containing the selected complete source, as rejection facts; code never reassigns that source or substitutes another message. Text remains a string and JSON keeps its original type. No source conversion, list splitting, fabricated containers or overwrite recovery is introduced.

Unreleased: read-only workflow context for native repair

Native parameter-repair descriptions include workflowContext, a compact view of the supplied source revision's API/native roles, declared ports, entrypoint, existing edges and gaps. It excludes schemas, payloads and setting values. This view remains available when the selected value-producer list is empty, as for a Merge control node. It grants no new value-reference authority: scoped producer contracts and parameter validation remain unchanged. Source-revision ports are not a claim that intermediate repair candidates have been adopted or that future edges exist. Parameter fingerprints include the new view; regenerate candidate receipts rather than rebase stored ones. Published 0.5.1 is unchanged.

Unreleased: verified keys and shared schema resources

createApiBindingKeyCatalog verifies key/path proposals against supplied original messages, assigns scoped identities and retains original string values. It does not infer names from OAS examples or generated model explanations. Manual binding APIs retain their explicit pointer support.

deduplicateCanonicalSchemaResources retains one identical identified resource and references its original canonical URI from repeated positions. Conflicting declarations with the same URI fail explicitly. Traversal visits schema positions only, preserving literal $id fields inside data. Source schemas are not mutated. This helper is used for combined evaluation output, not OAS intake rewriting.

Unreleased: sequential schema projection and native provenance

projectNativeValueSchema({ output, steps }) reads value pointers, array items and object entries in one original schema-resource context. It bundles only the final projection, preserving source data and reference resolution. A require-array step validates array availability without replacing the selected value schema. NativeSchemaProjectionError.step identifies failed array checks. Existing projection helpers remain available.

createNativeOutputContracts also derives optional provenance from the actual registered capability and its input-reference hooks. Per-call binding discovery keeps that metadata and excludes native producers whose known lineage already requires the target API. Final graph validation remains mandatory. External contracts without provenance remain unknown. Published 0.5.1 is unchanged.

0.4.2 adds resolveWorkflowIntent, validateWorkflowIntent and formatWorkflowIntentScenario for source-bound business scope before concrete material planning. Core validates references and assigns identities; it does not infer business meaning from OAS or choose execution edges. Optional planning reasons are presentation only. Native/goal review source text is attached by code, not copied by a model. Literal-value provenance, OAS, ownership, source drift and DAG validation remain functional requirements. Review wire contracts and optional reason types change; see the 0.4.2 record.

0.4.0 contracts: constraints, explicit boundary intent, scoped outlines and source-bound review/recovery contracts. Publication is tracked in the release record. The development additions below target this version, not the older public 0.3.18.

Migration: callers of createNativeParameterGenerationContract must explicitly provide planningParametersSchema as well as the executable capability. The candidate schema describes current model choices; the executable capability keeps its original runtime validator. Do not replace one with the other. High-level native configuration APIs own this composition. No missing-schema substitution, value default or silent data repair is introduced.

0.4.0 createWorkflowConnectionOutline validates proposed work bundles and assigns identities from the actual source/session/goals and structural membership. describeWorkflowConnectionOutline reports current pending work; describeWorkflowConnectionOutlineBundle retains the global graph context plus transitive producers and crossing edges. applyWorkflowConnectionOutlineStep enforces local write ownership before the existing global patch checks. These functions do not select a model, schedule execution, infer business order or prove semantic requirement coverage. See the outline contract.

0.4.0 materialRepairStages restricts primary API repair choices to their actual OAS ownership. describeWorkflowConnectionMaterialRepairWork derives dependent literal tasks after binding changes; applyWorkflowConnectionMaterialRepairWork rechecks that work and retains its original request/pending result on receipt replay. Neither function invokes a model, fills missing values or manages host checkpoint/retry policy. See the work contract.

0.4.0 goal-coverage review preserves the original requirements separately from candidate goals/material. Core checks every fact row, actual goal references, exact quotes and source-bound review receipts, and derives acceptance from the supplied judgments. It does not prove those semantic judgments or call a model. See independent initial review.

0.4.0 initial-material recovery is available independently of an accepted connection session. describeWorkflowConnectionConflictMaterials exposes actual execution mappings and original contracts. Source-bound requests and replacements are checked by validateWorkflowConnectionSourceRepairRequest and applyWorkflowConnectionMaterialRepair, then rechecked on receipt replay with replayWorkflowConnectionMaterialRepair. OAS, requirements, identities and unrelated material stay unchanged; binding/argument field ownership is enforced. Declaration order alone is not progress, while literal-array order is preserved. These functions never invoke a model or dispatch a host stage. See the recovery contract.

inspectWorkflowConnectionMaterialRepairInputs inspects a pending replacement's actual request slots before adoption. The host can then explicitly supply the complete replacement.deferredApiInputIds policy; new slots are never approved automatically and unrelated API approvals cannot be revoked. Application and receipt replay still enforce OAS, bindings and readiness. An absent versus empty optional requested-input list alone is not execution progress. These APIs remain unreleased.

0.4.0 source adds accepted connection-session revision, explicit original-edge baseline updates, causal impact/assessment invalidation and replay validation. Material repair requests are validated against their actual owning API/native stage. Runtime registries and loop policies stay with the consumer. See the connection revision guide.

Revision descriptions inspect the current graph against replacement contracts and bind both source epochs plus the accepted session history. Rejected candidate graphs expose private typed WorkflowConnectionRevisionError.violations; public error JSON still contains only the diagnostic. This does not add a host retry loop.

Version 0.3.18 aligns with LangChain's typed per-call source decisions. Core's source-selection contracts, original OAS checks and cycle validation are unchanged. See the release record.

Version 0.3.17 adds describeApiOperationCandidate, projecting an original operation into the existing discovery contract without changing its OAS or filtering candidates. Detailed contracts remain available for later generation and validation. See the release record.

0.4.0 source adds inspectWorkflowPlanningConstraints and typed WorkflowPlanningConstraintError evidence for conflicts between selected data dependencies and proposed goals. It checks necessary ordering only, does not infer business order from OAS, and never replaces the final route/completion checks or host-owned replanning policy. These additions are not in published 0.3.18.

Version 0.3.16 adds serializable incremental connection sessions, atomic bundle application, source/revision guards, native-only extension and complete DAG finalization. Existing APIs remain compatible. See the connection guide and release status and limitations.

Version 0.3.15 adds source-owned per-call binding descriptions, source-choice and field-choice resolution, resumable-result validation and complete plan assembly. It retains original OAS validation and global dependency-cycle checks. See the binding guide and release record.

Version 0.3.14 adds source-owned structured errors and aligns the n8n adapter's fixed API result collection. Supported security updates use Scalar parser 0.29.16, fast-uri 3.1.9 and the host Zod peer below. The owner accepted the n8n adapter's unresolved upstream Zod 3 advisory for this release on 2026-10-25. This does not clear the audit finding. The existing Ajv special-key limitation below remains. See the 0.3.14 release record for actual publication and host status; preparation is not publication.

@openapi-flow/core/errors exports the browser-safe OpenApiFlowError, guard, diagnostic/code schemas and inferred types without importing Node-owned OAS code. Covered errors retain the original exception in cause; toJSON() exposes only the closed diagnostic, never private messages, stacks or model output. Existing typed errors pass through unchanged. This does not migrate every internal throw or add logging, retries, schema repair or host recovery policy.

Zod ^4.6.7 is a required peer, shared with the host rather than installed as a separately pinned runtime copy. Development tests and the strict installed-consumer check use 4.6.7. This preserves the public schema type boundary without casts or dependency overrides.

Version 0.3.13. This patch keeps Core contracts and validation unchanged while aligning the adapters' common draft-planning input fix. Optional enum interpretation from 0.3.11/0.3.12 remains source- and type-checked without automatic defaults. Canonical draft, clarification and runtime-input APIs described below are included. 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 accepted limitation remains unchanged, without renaming data or skipping its failing regression. See the release record for actual publication and host status.

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.

canonical gapNodes and the separate createWorkflowDraftCapabilityGap, inspectWorkflowDraftCapabilityGap, describeWorkflowDraftCapabilityGap functions preserve explicit unsupported roles, original evidence and supplied contract identities without inventing data outputs. See the gap contract.

requestedInputs metadata tracks scenario-required presence separately from OAS requiredness. Questions, answers, canonical calls and execution slots retain the same pointers; listMissingRequestedApiInputs shares deterministic presence checks with compiled runtimes. Original schemas and actual values remain unchanged. See requested inputs.

request-dependency intent has its own description, Zod schema and resolveWorkflowDraftApiBindingIntent receipt. Supplying that inputIntent to API binding planning restricts mappings/questions to validated selected targets and requires complete coverage. OAS literal generation and missing-required-value checks remain unchanged. See input intent.

semantic edits support explicit restoration of currently removed requirements, without copying historical replacement values. See requirement restoration.

answer-source resolution and replayable input-answer evidence are documented in the answer extraction guide.

combined graph planning adds captured source contexts, explicit prepared/additional instance assembly and verifiable planning records under workflow/graphs. Shared API/native data capture has its own schema/type modules. See the combined graph guide. A legacy executable gap report is explicitly marked unvalidated, not certified as a DAG.

connection planning has deterministic source capture, plan assembly and provenance creation/verification in workflow/connections. See the connection planning guide. These APIs do not call a model, modify fixed materials or replace full DAG validation.

native-plan contracts preserve additional instances separately from prepared materials, derive gap identities/implementation receipts, and validate optional model/code-only provenance. Empty explicit OAS inventories form real empty catalogs; supplied invalid documents still fail. See native planning ownership and records.

binding-planning records preserve actual proposed pointer mappings, per-call reasons and original supplied OAS/native context. Core snapshots only declared source data and verifies records against the original input and plan. See binding decisions and provenance.

literal-generation records distinguish original proposed literals from confirmed/bound inputs. Core snapshots data, owns the projected-contract evidence and verifies persisted records against the original generation input. No values or reasons are fabricated when no literal fields remain. See literal attribution and call roles.

request-format decisions distinguish no body, a sole declared format, explicit model choice and the approved explicit-null default policy. Core owns resolution and exact optional scenario/requestBody evidence; model reasoning does not impersonate code's default choice. Format logic is grouped in arguments/media. See request media decisions.

discovery explanation APIs snapshot and validate the actual scenario, candidate metadata and original operation identities. Code derives evidence from the selected API, offered alternatives or entire supplied inventory; models never write source quotes or contract claims here. See API selection explanations.

semantic edit questions declare an explicit owner. Independent semantic questions still block their actual scope; concerns owned by selected API/native, requirement or connection stages retain exact provenance and route only to that verified stage. They do not create duplicate workflow blockers or fabricate answers. describeWorkflowDraftClarificationOwnership describes those code-resolved owners. The wire schema also makes whole-request no-change exclusive with real edits. See question ownership.

canonical drafts require code-owned requirementHistory. Explicit revisions/withdrawals preserve prior snapshots and exact evidence, while active planning messages remain separate from the audit transcript. Typed requirement answers use a candidate context without rebasing the original plan. See requirement history and current evidence.

describeWorkflowDraftSelectedNodes and describeWorkflowDraftRequirementEdit expose selected API/native identities before request values or producer contracts are ready. The derived createWorkflowDraftRequirementAnswerSchema bounds typed human scope answers; Core re-derives that authority during staging and assembly. Missing materials still block final assembly. See requirement edits and selected scopes.

typed API binding questions use the selected OAS input/source contracts. Code owns question wording, identities, schemas and validated source choices. Explicit human answers resolve the same proposal without inventing values, repairing outputs or exposing partial bindings.

describeWorkflowClarificationAnswerRevision, reviseWorkflowClarificationAnswers and validateWorkflowClarificationAnswerRevision provide atomic typed answer replacement and question reopening without a model. Original snapshots and explicit transition receipts remain auditable; current answer evidence is separated from superseded receipts. See answer revisions.

review suggestion contracts validate the current read-only review projection, original evidence and configured budgets, then allocate stable suggestion identities. adoptWorkflowReviewSuggestion creates an explicit user-adoption receipt, never an edit or executable workflow. See review follow-ups and adoption.

selected API addition/replacement primitives derive the new request from its full original OAS key, validate actual source mappings, exclude bound/confirmed fields from literal schemas and return typed missing-input questions or explicitly enabled runtime slots. Identities, graph metadata, evidence text and validation remain code-owned; existing sibling settings are preserved.

native additions expose the actual selected implementation schema while code retains the instance ID/capability. describeWorkflowDraftNativeNodeAddition, createWorkflowDraftNativeNodeAdditionSchema and resolveWorkflowDraftNativeNodeAddition validate configuration/ownership or return questions, without automatic connections or adoption. resolveWorkflowDraftNativeNodeParameterOwnership separately derives an immutable ownership/remaining-literal contract for staged mixed-field generation. See native instance additions.

Independent native configuration accepts ordered replies containing the original code-identified question and exact user text. Core validates target/material fingerprints, original proposals and answer order without rewriting the scenario or selection. Missing plan-time literal values are handled by the value stage, not treated as missing capabilities during role selection. These receipts check consistency, not caller authenticity; see native setting replies.

resolveNativeMaterialSnapshot and draft-facing resolveWorkflowDraftNativeSnapshot bind actual producer contracts independently for each content revision. Pending references expose no previous output schema; edit staging discovers cascading consumer repairs after explicit upstream decisions. Original definitions, full schema checks and atomic DAG validation remain intact. See material snapshots.

describeWorkflowDraftNativeReferenceRepair/resolveWorkflowDraftNativeReferenceRepair derive one actual consumer task, validate implementation-owned parameter locations and construct only reference patches. Questions produce no partial repair; original settings and complete-graph validation remain authoritative. See the repair boundary and remaining composition work.

native parameter editing derives selected field types from the registered implementation, preserves unpatched settings and validates original Zod refinements and actual response/native sources. Runtime ownership is explicitly opt-in; missing choices yield scoped questions, not dummy values or partial resolutions. See the native parameter-edit contract.

describeWorkflowDraftConnectionEdit/resolveWorkflowDraftConnectionEdit derive actual staged ports/reference constraints and validate explicit connection deltas through atomic assembly. Unrelated edges are retained; incomplete contracts/repairs return visible prerequisites, not fake readiness. See the connection-edit contract.

stageWorkflowDraftEdit exposes explicit pending edit results and unavailable source contracts without pretending incomplete content is canonical. describeWorkflowDraftApiBindingEdit/resolveWorkflowDraftApiBindingEdit support source-grounded changes for an existing API or actual consumer repair; validateApiBindingAssignment shares the complete validator's declaration checks without fabricating unrelated binding lists. See the staged binding-edit boundary.

scoped API input-edit contracts derive target schemas from the selected original OAS and validate source-grounded typed values before generating precise patches. createWorkflowDraftApiInputEditContract, createWorkflowDraftApiInputEditValuesSchema and resolveWorkflowDraftApiInputEdits are usable without a model; the LangChain adapter adds separate target/value calls. See ownership, validation and pending-input semantics.

prepareWorkflowDraftEdit and assembleWorkflowDraftEdit accept explicit step results, preserve unpatched request/native values and derive consumer repair work from declared references. Final assembly returns a checked candidate revision with structural impact; it never mutates the original draft or repairs missing mappings/edges silently. These are deterministic host-to-core contracts, not generic schemas for model generation. See the scoped assembly guide.

createWorkflowDraftEditPlan, validateWorkflowDraftEditPlan and describeWorkflowDraftEditContext bind explicit semantic edits to the current draft, contracts and request messages. Code owns version fingerprints, new instance IDs and direct stage metadata; no draft mutation or implicit repair occurs. This is the analysis boundary, not a complete edit assembler. See the edit analysis contract.

native input contracts add collectNativeRuntimeInputSlots, inspectNativeRuntimeInputs and createWorkflowRuntimeInputsSchema. Capabilities declaring runtime-independent ports, references and output contracts can defer whole objects or explicitly selected field pointers while preserving other literals. Code derives identities and validates the full combined object without changing actual values; canonical drafts and API/native readiness remain separate. Export individual slot schemas to preserve independent resource scopes. Scoped edits, staged new draft-native additions and independent role/value planning support explicit field ownership. resolveNativeInstanceSelection, describeNativeNodeConfiguration and resolveNativeNodeParameters derive/validate the standalone contracts without model calls or fabricated drafts/edges. See the native runtime input contract.

requirements APIs add createWorkflowClarificationRound, resolveWorkflowClarificationReplies, explicit question-budget configuration and source checks. Questions have code-owned identities; partial/deferred answers preserve confirmed facts without automatically adopting suggestions. See the clarification contract. These additions are not in npm 0.2.0.

source additions provide inspectApiArgumentRequirements, validateApiInputAnswers, applyConfirmedApiInputs, resolveApiSelectionAnswers and createApiInputAnswersSchema. Snapshot/call-scoped confirmedInputs are excluded from literal generation and applied by code. These additions are not included in npm 0.2.0; see the conversation guide.

Engine-independent OpenAPI catalog, full operation contract lookup, OAS-derived Zod request schemas and argument validation. Version 0.2.0 is published; 0.1.0 has a different API.

createWorkflowPlanningCapabilities({ capabilities, apiCallIds }) specializes only capabilities that explicitly provide createPlanningParametersSchema(context). Existing runtime schemas and capability objects are not mutated; custom definitions without the hook retain their schema. validateNativeApiResponseReferences({ nativeNodes, capabilities, apiCallIds }) checks the API identities declared by each implementation's responseReferences and per-port inputReferences. It does not inspect arbitrary JSON field names, validate native-output identities as API IDs, infer a missing producer or repair a reference. These functions establish early planning boundaries; execution order and response contract validation remain separate.

0.4.0 source hardening: createApiInputSourceSelectionSchema exports a bounded ID grammar instead of enumerating every position in the input text. Its original Zod schema still checks membership in the exact supplied catalog. resolveApiInputSourceSelections independently reconstructs that catalog and validates identity, ordered boundaries and a single original text segment before copying values. The serialized JSON Schema alone is not a catalog-membership validator. Preserve the local Zod/core resolution step; do not trust a model-provided ID merely because it matches the wire grammar. No source text is truncated, coerced or substituted.

createApiArgumentGenerationContract({ operation, bindings, requestMediaType }) is the shared literal-generation boundary. It returns the Zod schema, its matching literalInputSchema JSON Schema, and hasLiteralInputs. Bound paths have no original value definition and are forbidden (including through open additional properties); unbound OAS-approved fields stay available. Fully bound closed nested objects have no remaining literal decision. Open objects can still accept additional scenario values, so binding every named property does not close that OAS contract. The original operation and complete runtime request schema remain unchanged.

Dynamic OAS assertions are no longer round-tripped through experimental z.fromJSONSchema. createOasValueSchema uses Zod's public refinement and metadata APIs: Scalar's JSON Schema validator checks the preserved assertions, and Zod exports those same assertions to LangChain. Type-less constraints, enum siblings and simultaneous compositions are not replaced by inferred types or weaker schemas. OAS 3.0 nullable and boolean exclusive bounds are explicitly translated to Draft 2020-12 syntax; formats, annotations and enum/example data are retained. Each embedded schema has a resource ID so fragment references keep their original scope. These IDs are schema identifiers, not inferred API input values. validateApiArguments and the complete createApiRequestSchema use the same dialect conversion; the latter retains required fields for the n8n standalone validator. Uncompileable selected schemas fail with their source before a model call. Provider-specific schema support is still an external boundary, not a reason to trim the OAS contract.

See Zod's JSON Schema and metadata APIs and the OAS 3.0 Schema Object for the conversion boundary and nullable semantics. This does not claim exhaustive support for every schema dialect or provider.

import {
  createApiCatalog,
  listApiOperations,
  resolveApiOperations,
} from '@openapi-flow/core';

The host supplies { id, spec } documents. Catalog creation requires neither deployment credentials nor a per-path effect policy. The selected full OAS contract remains available before any engine-specific conversion. Operation keys carry document ID, snapshot hash and OAS JSON Pointer; changed documents fail lookup.

createApiArgumentsSchema preserves OAS request types and excludes bound fields from model proposals. validateApiArguments checks literal constraints and returns missing-input pointers. validateApiBindingPlan checks response-to-request identities, pointers, known incompatible types and cycles. materializeApiArguments(values, bindings, responses, material) copies actual values without coercion or defaults; the OAS material determines missing container kinds. createApiRequestSchema supplies the complete final request schema for runtime validation. The /runtime entrypoint contains execution-only materialization and serializers without catalog/document intake. Core does not call an LLM, import LangChain/n8n, execute APIs or provide a server. The /internal export is an unstable adapter boundary. See the workspace guide.

listApiResponsePointers(operation) describes finite response-body declarations grouped by the original response key and media type. Each declaredPointers entry has an exact RFC 6901 body pointer, its schemaLocation, and the type/description actually declared by the schema. Empty pointer means the entire response body. Composition and conditional branch locations stay distinct; enum/example/default data are not traversed as schemas. OAS 3.0 nullable syntax is normalized without changing the operation.

dynamicLocations identifies dictionaries, pattern keys, homogeneous array items, unexpanded references, recursive schema boundaries and unconstrained values. It never invents a dictionary key or a sample item index. A tuple's explicitly declared positions can be listed, but their runtime existence is not guaranteed. This catalog is advisory, not an exhaustive schema projection, a whitelist, a schema satisfiability proof or a promise that optional/conditional fields exist. The full OAS and existing binding/runtime validators remain authoritative; missing response values still fail without substitution.

WorkflowGraphPlan describes native capability settings, named-port edges, starts and unmet requirements. validateWorkflowGraphPlan uses host-supplied capability contracts to check graph identity/ports/cycles, exclusive-branch join compatibility and API response availability on every incoming route. It does not prove scenario coverage or exhaustively validate response pointer types against every OAS schema dialect; missing fields fail in the runtime compiler. This contract is engine-independent and does not import an n8n node registry.

Our code is MIT-licensed. Core has no n8n SDK dependency. Dependency licenses remain separate; see third-party notices.

ReviewableWorkflowApiMaterial discriminates ready calls with real arguments from blocked calls with OAS identity, declared bindings and causal gap IDs, but no fabricated arguments. createReviewableWorkflowGraphPlan adds explicitly identified gaps and blocked calls to the proposed DAG, derives its actual roots, and invokes validateReviewableWorkflowGraphPlan. Topology and binding-contract validation are never skipped because of gaps. Blocked/gap nodes have ports but no available API response. validateApiBindingAssignments checks assignments independently of execution readiness; validateApiBindingGaps requires every reported gap to identify a known call and an OAS-declared request pointer. The strict validateApiBindingPlan still rejects all gaps. These contracts do not imply that review workflows may be executed.