@openapi-flow/core 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,144 @@
 # @openapi-flow/core
 
-Engine-independent OpenAPI catalog, full operation contract lookup, OAS-derived Zod request schemas and argument validation. This is unreleased `0.2.0` source; published `0.1.0` has a different API.
+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).
+
+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](../../docs/workflow-draft-conversation-host.md#explicit-capability-gaps).
+
+`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](../../docs/workflow-draft-api-binding-questions.md#값이-미정인-선택-입력의-요청-추적).
+
+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](../../docs/workflow-draft-api-binding-questions.md#요청-의도를-먼저-고정하는-선택-단계).
+
+semantic edits support explicit restoration of currently removed
+requirements, without copying historical replacement values. See
+[requirement restoration](../../docs/workflow-draft-requirement-restoration.md).
+
+answer-source resolution and replayable input-answer evidence are
+documented in the [answer extraction guide](../../docs/api-input-answer-extraction.md).
+
+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](../../docs/graph-planning-records.md). 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](../../docs/connection-planning-records.md). 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](../../docs/native-planning-records.md).
+
+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](../../docs/binding-planning-records.md).
+
+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](../../docs/literal-generation-records.md).
+
+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](../../docs/request-media-decisions.md).
+
+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](../../docs/api-selection-explanations.md).
+
+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](../../docs/workflow-draft-clarification-ownership.md).
+
+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](../../docs/workflow-draft-requirement-history.md).
+
+`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](../../docs/workflow-draft-requirement-edits.md).
+
+[typed API binding questions](../../docs/workflow-draft-api-binding-questions.md)
+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](../../docs/workflow-clarification-answer-revisions.md).
+
+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](../../docs/workflow-review-suggestions.md).
+
+[selected API addition/replacement primitives](../../docs/workflow-draft-api-call-planning.md)
+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](../../docs/workflow-draft-native-node-addition.md).
+
+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](../../docs/native-runtime-inputs.md#answering-a-selected-instances-questions).
+
+`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](../../docs/native-material-snapshots.md).
+
+`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](../../docs/workflow-draft-native-reference-repairs.md).
+
+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](../../docs/workflow-draft-native-parameter-edits.md).
+
+`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](../../docs/workflow-draft-connection-edits.md).
+
+`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](../../docs/workflow-draft-api-binding-edits.md).
+
+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](../../docs/workflow-draft-api-input-edits.md).
+
+`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](../../docs/workflow-draft-edit-assembly.md).
+
+`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](../../docs/workflow-draft-edit-analysis.md).
+
+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](../../docs/native-runtime-inputs.md).
+
+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](https://github.com/carefreelife98/openapi-flow/blob/main/docs/workflow-requirements-clarification.md). 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](https://github.com/carefreelife98/openapi-flow/blob/main/docs/conversational-generation.md).
+
+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.
 

package/THIRD_PARTY_NOTICES.md

@@ -3,3 +3,5 @@
 The unreleased `@openapi-flow/core@0.2.0` source depends on Scalar OpenAPI/JSON Schema libraries, Zod, Ajv, ajv-formats and fast-uri. Ajv's public schema registry and fast-uri preserve JSON Schema reference scope during native contract projection. It does not depend on `@n8n/workflow-sdk` or LangChain. This dependency boundary differs from the previously published `0.1.0` package.
 
 Other dependencies retain their own licenses. The MIT license in this package applies to openapi-flow's code only.
+
+Unreleased source also uses Microsoft's MIT-licensed `jsonc-parser` scanner to verify the boundaries of a selected user-reply literal. Its fault-tolerant JSON parser is not used; values are read with strict `JSON.parse` and validated against the supplied OAS schema.

package/dist/arguments/clarification/apply-confirmed-api-inputs.d.ts

@@ -0,0 +1,3 @@
+import type { ApplyConfirmedApiInputsInput } from '../../types/api-clarification.js';
+import type { ApiArgumentValues } from '../../types/api-arguments.js';
+export declare function applyConfirmedApiInputs(input: ApplyConfirmedApiInputsInput): ApiArgumentValues;

package/dist/arguments/clarification/apply-confirmed-api-inputs.js

@@ -0,0 +1,16 @@
+import { readConfirmedApiInputs } from './read-confirmed-api-inputs.js';
+import { assignApiInputValue } from './assign-api-input-value.js';
+import { validateApiArguments } from '../validate-api-arguments.js';
+export function applyConfirmedApiInputs(input) {
+    validateApiArguments(input);
+    const confirmed = readConfirmedApiInputs(input);
+    const values = structuredClone(input.values);
+    for (const item of confirmed)
+        assignApiInputValue(values, item.targetPointer, item.value, {
+            operation: input.operation,
+            callId: item.callId,
+            requestMediaType: input.requestMediaType,
+        });
+    validateApiArguments({ ...input, values });
+    return values;
+}

package/dist/arguments/clarification/assign-api-input-value.d.ts

@@ -0,0 +1,4 @@
+import type { ApiArgumentValues, JsonValue } from '../../types/api-arguments.js';
+import type { ApiBindingMaterial } from '../../types/api-bindings.js';
+/** No overwrites, numeric-key guessing, sparse-array filling or value coercion. */
+export declare function assignApiInputValue(values: ApiArgumentValues, pointer: string, value: JsonValue, material: ApiBindingMaterial): void;

package/dist/arguments/clarification/assign-api-input-value.js

@@ -0,0 +1,8 @@
+import { pointerTokens } from '../../bindings/json-pointer.js';
+import { assignRequestInputValue } from '../../bindings/assign-request-input-value.js';
+/** No overwrites, numeric-key guessing, sparse-array filling or value coercion. */
+export function assignApiInputValue(values, pointer, value, material) {
+    const assigned = assignRequestInputValue(values, pointer, value, material);
+    const group = pointerTokens(pointer)[0];
+    Reflect.set(values, group, Reflect.get(assigned, group));
+}

package/dist/arguments/clarification/extraction/capture-api-input-answer-context.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputAnswerContext } from '../../../types/api-input-answer-extraction.js';
+/** Capture supplied pending contracts before any asynchronous model work. */
+export declare function captureApiInputAnswerContext(input: ApiInputAnswerContext): ApiInputAnswerContext;

package/dist/arguments/clarification/extraction/capture-api-input-answer-context.js

@@ -0,0 +1,17 @@
+import { apiInputAnswerContextSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
+import { createOasValueValidator } from '../../../openapi/common/create-oas-value-validator.js';
+/** Capture supplied pending contracts before any asynchronous model work. */
+export function captureApiInputAnswerContext(input) {
+    apiInputAnswerContextSchema.parse(input);
+    const snapshot = structuredClone(input);
+    const ids = new Set();
+    for (const requirement of snapshot.requirements) {
+        if (ids.has(requirement.id))
+            throw new Error(`Duplicate API input requirementId: ${requirement.id}`);
+        ids.add(requirement.id);
+        createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
+            ? 'openapi-3.0'
+            : 'draft-2020-12', `API input requirement ${requirement.id} ${requirement.targetPointer}`);
+    }
+    return snapshot;
+}

package/dist/arguments/clarification/extraction/create-api-input-answer-extraction-record.d.ts

@@ -0,0 +1,2 @@
+import type { ApiInputAnswerExtractionRecord, CreateApiInputAnswerExtractionRecordInput } from '../../../types/api-input-answer-extraction.js';
+export declare function createApiInputAnswerExtractionRecord(input: CreateApiInputAnswerExtractionRecordInput): ApiInputAnswerExtractionRecord;

package/dist/arguments/clarification/extraction/create-api-input-answer-extraction-record.js

@@ -0,0 +1,24 @@
+import { apiInputAnswerExtractionDecisionSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
+import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
+import { resolveApiInputAnswerSources } from './resolve-api-input-answer-sources.js';
+export function createApiInputAnswerExtractionRecord(input) {
+    const evidence = captureApiInputAnswerContext({
+        reply: input.reply,
+        requirements: input.requirements,
+    });
+    const decision = structuredClone(apiInputAnswerExtractionDecisionSchema.parse(input.decision));
+    const verification = resolveApiInputAnswerSources({
+        ...evidence,
+        selections: decision.answers.map((source) => ({
+            requirementId: source.requirementId,
+            sourceFormat: source.sourceFormat,
+            sourceText: source.sourceText,
+        })),
+    });
+    return {
+        kind: 'model-extracted-api-input-answers',
+        decision,
+        evidence,
+        verification,
+    };
+}

package/dist/arguments/clarification/extraction/resolve-api-input-answer-sources.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveApiInputAnswerSourcesInput, ResolvedApiInputAnswerSources } from '../../../types/api-input-answer-extraction.js';
+/** Model-selected source text is the only value source, never a model-generated value. */
+export declare function resolveApiInputAnswerSources(input: ResolveApiInputAnswerSourcesInput): ResolvedApiInputAnswerSources;

package/dist/arguments/clarification/extraction/resolve-api-input-answer-sources.js

@@ -0,0 +1,40 @@
+import { apiInputAnswerSourcesSchema } from '../../../schemas/api-input-answer-extraction-schema.js';
+import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
+import { readApiInputLiteralSource } from '../../sources/read-api-input-literal-source.js';
+import { createOasValueValidator } from '../../../openapi/common/create-oas-value-validator.js';
+/** Model-selected source text is the only value source, never a model-generated value. */
+export function resolveApiInputAnswerSources(input) {
+    const context = captureApiInputAnswerContext({
+        reply: input.reply,
+        requirements: input.requirements,
+    });
+    const selections = apiInputAnswerSourcesSchema.parse(input.selections);
+    const answered = new Set();
+    const result = {
+        answers: [],
+        sources: [],
+        unansweredRequirementIds: [],
+    };
+    for (const selection of selections) {
+        const requirement = context.requirements.find((item) => item.id === selection.requirementId);
+        if (!requirement || answered.has(selection.requirementId))
+            throw new Error(`Unknown or duplicate requirementId: ${selection.requirementId}`);
+        const { value, occurrences } = readApiInputLiteralSource({
+            ...selection,
+            text: context.reply,
+            label: `Answer ${requirement.id}`,
+        });
+        const checked = createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
+            ? 'openapi-3.0'
+            : 'draft-2020-12', `answer ${requirement.targetPointer}`).validate(value);
+        if (!checked.valid)
+            throw new Error(`Answer ${requirement.id} violates its supplied OAS schema: ${checked.errors.map((error) => error.message).join('; ')}`);
+        answered.add(requirement.id);
+        result.answers.push({ requirementId: requirement.id, value });
+        result.sources.push({ ...selection, occurrences });
+    }
+    result.unansweredRequirementIds = context.requirements
+        .filter((item) => !answered.has(item.id))
+        .map((item) => item.id);
+    return result;
+}

package/dist/arguments/clarification/extraction/resolve-api-input-source-selections.d.ts

@@ -0,0 +1,4 @@
+import type { ApiInputAnswerSource } from '../../../types/api-input-answer-extraction.js';
+import type { ResolveApiInputSourceSelectionsInput } from '../../../types/api-input-source-selection.js';
+/** Resolve IDs against a fresh original-reply inventory, not model-provided text. */
+export declare function resolveApiInputSourceSelections(input: ResolveApiInputSourceSelectionsInput): ApiInputAnswerSource[];

package/dist/arguments/clarification/extraction/resolve-api-input-source-selections.js

@@ -0,0 +1,46 @@
+import { apiInputAnswerSelectionsSchema } from '../../../schemas/api-input-source-selection-schema.js';
+import { captureApiInputAnswerContext } from './capture-api-input-answer-context.js';
+import { describeApiInputSources } from '../../sources/describe-api-input-sources.js';
+/** Resolve IDs against a fresh original-reply inventory, not model-provided text. */
+export function resolveApiInputSourceSelections(input) {
+    const context = captureApiInputAnswerContext({
+        reply: input.reply,
+        requirements: input.requirements,
+    });
+    const catalog = describeApiInputSources(context.reply);
+    const selections = apiInputAnswerSelectionsSchema.parse(input.selections);
+    const answered = new Set();
+    return selections.map((selection) => {
+        if (!context.requirements.some((requirement) => requirement.id === selection.requirementId) ||
+            answered.has(selection.requirementId))
+            throw new Error(`Unknown or duplicate requirementId: ${selection.requirementId}`);
+        answered.add(selection.requirementId);
+        const source = selection.source;
+        if (source.kind === 'json') {
+            const candidate = catalog.json.find((item) => item.id === source.candidateId);
+            if (!candidate)
+                throw new Error(`Answer ${selection.requirementId} has an unknown JSON source candidate: ${source.candidateId}`);
+            return {
+                requirementId: selection.requirementId,
+                sourceFormat: 'json',
+                sourceText: candidate.text,
+            };
+        }
+        const segment = catalog.text.find((item) => item.tokens.some((token) => token.id === source.startTokenId));
+        const start = segment?.tokens.findIndex((token) => token.id === source.startTokenId);
+        const end = segment?.tokens.findIndex((token) => token.id === source.endTokenId);
+        if (!segment ||
+            start === undefined ||
+            end === undefined ||
+            start < 0 ||
+            end < start)
+            throw new Error(`Answer ${selection.requirementId} requires ordered text boundaries in one original unquoted segment`);
+        const first = segment.tokens[start];
+        const last = segment.tokens[end];
+        return {
+            requirementId: selection.requirementId,
+            sourceFormat: 'text',
+            sourceText: context.reply.slice(first.offset, last.offset + last.length),
+        };
+    });
+}

package/dist/arguments/clarification/extraction/validate-api-input-answer-extraction-record.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiInputAnswerExtractionRecordInput } from '../../../types/api-input-answer-extraction.js';
+/** Replay against separately supplied original context, not a record's self-asserted evidence. */
+export declare function validateApiInputAnswerExtractionRecord(input: ValidateApiInputAnswerExtractionRecordInput): void;

package/dist/arguments/clarification/extraction/validate-api-input-answer-extraction-record.js

@@ -0,0 +1,12 @@
+import { isDeepStrictEqual } from 'node:util';
+import { createApiInputAnswerExtractionRecord } from './create-api-input-answer-extraction-record.js';
+/** Replay against separately supplied original context, not a record's self-asserted evidence. */
+export function validateApiInputAnswerExtractionRecord(input) {
+    const expected = createApiInputAnswerExtractionRecord({
+        reply: input.reply,
+        requirements: input.requirements,
+        decision: input.record.decision,
+    });
+    if (!isDeepStrictEqual(expected, input.record))
+        throw new Error('API input answer extraction record differs from its original reply, pending contracts or code-resolved values');
+}

package/dist/arguments/clarification/inspect-api-argument-requirements.d.ts

@@ -0,0 +1,2 @@
+import type { InspectApiArgumentRequirementsInput, ApiArgumentRequirements } from '../../types/api-clarification.js';
+export declare function inspectApiArgumentRequirements(input: InspectApiArgumentRequirementsInput): ApiArgumentRequirements;

package/dist/arguments/clarification/inspect-api-argument-requirements.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { validateApiArguments } from '../validate-api-arguments.js';
+import { requestBindingSchemas } from '../../bindings/request-binding-schema.js';
+import { unionBindingSchemas } from '../../bindings/combine-binding-schemas.js';
+import { hasPointer, pointerTokens } from '../../bindings/json-pointer.js';
+import { listMissingRequestedApiInputs } from './list-missing-requested-api-inputs.js';
+export function inspectApiArgumentRequirements(input) {
+    if (!input.callId?.trim())
+        throw new Error('input requirements require callId');
+    const validation = validateApiArguments(input);
+    const requestedMissing = listMissingRequestedApiInputs({
+        source: `Request ${input.callId}`,
+        rootPointer: '',
+        value: input.values,
+        requestedInputs: input.requestedInputs,
+    });
+    for (const pointer of input.requestedInputs === undefined
+        ? []
+        : input.requestedInputs)
+        if (!requestBindingSchemas(input, pointer).length)
+            throw new Error(`Request ${input.callId}.requestedInputs ${pointer} is not declared by its OAS`);
+    const requestedTargets = requestedMissing
+        .filter((pointer) => !input.bindings.some((binding) => binding.targetPointer === pointer ||
+        binding.targetPointer.startsWith(pointer + '/') ||
+        pointer.startsWith(binding.targetPointer + '/')))
+        .map((pointer) => {
+        const tokens = pointerTokens(pointer);
+        const rootLength = tokens[0] === 'body' ? 1 : 2;
+        for (let length = rootLength; length <= tokens.length; length++) {
+            const prefix = '/' +
+                tokens
+                    .slice(0, length)
+                    .map((token) => token.replaceAll('~', '~0').replaceAll('/', '~1'))
+                    .join('/');
+            if (!hasPointer(input.values, prefix) &&
+                !input.bindings.some((binding) => binding.targetPointer.startsWith(prefix + '/')))
+                return prefix;
+        }
+        return pointer;
+    });
+    const missing = [
+        ...new Set([...validation.missingInputs, ...requestedTargets]),
+    ].filter((pointer, _, pointers) => !pointers.some((parent) => parent !== pointer && pointer.startsWith(parent + '/')));
+    const requirements = missing.map((targetPointer) => {
+        const schemas = requestBindingSchemas(input, targetPointer);
+        if (!schemas.length)
+            throw new Error(`Missing input ${targetPointer} has no OAS request schema`);
+        const schema = unionBindingSchemas(schemas);
+        const [location, name] = pointerTokens(targetPointer);
+        const requestedInputs = input.requestedInputs?.filter((pointer) => pointer === targetPointer || pointer.startsWith(targetPointer + '/'));
+        const requested = requestedInputs !== undefined && requestedInputs.length > 0;
+        const kind = validation.missingInputs.includes(targetPointer)
+            ? 'missing-input'
+            : 'requested-input';
+        const parameter = input.operation.effective.parameters.find((item) => item.in === location && item.name === name);
+        return {
+            kind,
+            id: createHash('sha256')
+                .update(JSON.stringify([
+                input.callId,
+                input.operation.key,
+                targetPointer,
+                schema,
+                ...(requested ? [kind, requestedInputs] : []),
+            ]))
+                .digest('hex'),
+            callId: input.callId,
+            operation: structuredClone(input.operation.key),
+            targetPointer,
+            schema: structuredClone(schema),
+            openapiVersion: input.operation.openapiVersion,
+            ...(requested ? { requestedInputs } : {}),
+            ...(typeof input.operation.operation.summary === 'string'
+                ? { operationSummary: input.operation.operation.summary }
+                : {}),
+            ...(typeof parameter?.description === 'string'
+                ? { parameterDescription: parameter.description }
+                : {}),
+            message: `Provide ${kind === 'missing-input' ? 'required request' : 'scenario-requested'} value ${targetPointer} for ${input.operation.method} ${input.operation.path}.${requested ? ' Include requested paths: ' + requestedInputs.join(', ') + '.' : ''}`,
+        };
+    });
+    return {
+        status: requirements.length ? 'needs-input' : 'ready',
+        requirements,
+    };
+}

package/dist/arguments/clarification/list-missing-requested-api-inputs.d.ts

@@ -0,0 +1,3 @@
+import type { RequestedApiInputPresenceInput } from '../../types/requested-api-inputs.js';
+/** Shared by typed answers, runtime input values and the final materialized request. */
+export declare function listMissingRequestedApiInputs(input: RequestedApiInputPresenceInput): string[];

package/dist/arguments/clarification/list-missing-requested-api-inputs.js

@@ -0,0 +1,21 @@
+import { hasPointer, pointerTokens } from '../../bindings/json-pointer.js';
+/** Shared by typed answers, runtime input values and the final materialized request. */
+export function listMissingRequestedApiInputs(input) {
+    pointerTokens(input.rootPointer);
+    if (input.requestedInputs === undefined)
+        return [];
+    if (!Array.isArray(input.requestedInputs))
+        throw new Error(`${input.source}.requestedInputs must be an array`);
+    const seen = new Set();
+    return input.requestedInputs.filter((pointer) => {
+        if (typeof pointer !== 'string' ||
+            !pointerTokens(pointer).length ||
+            seen.has(pointer))
+            throw new Error(`${input.source}.requestedInputs must contain distinct non-root JSON Pointers`);
+        seen.add(pointer);
+        if (pointer !== input.rootPointer &&
+            !pointer.startsWith(input.rootPointer + '/'))
+            throw new Error(`${input.source}.requestedInputs contains ${pointer} outside ${input.rootPointer}`);
+        return !hasPointer(input.value, pointer.slice(input.rootPointer.length));
+    });
+}

package/dist/arguments/clarification/read-confirmed-api-inputs.d.ts

@@ -0,0 +1,2 @@
+import type { ApiArgumentGenerationInput, ConfirmedApiInput } from '../../types/api-clarification.js';
+export declare function readConfirmedApiInputs(input: ApiArgumentGenerationInput): ConfirmedApiInput[];

package/dist/arguments/clarification/read-confirmed-api-inputs.js

@@ -0,0 +1,35 @@
+import { confirmedApiInputsSchema } from '../../schemas/confirmed-api-input-schema.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+import { requestBindingSchemas } from '../../bindings/request-binding-schema.js';
+import { unionBindingSchemas } from '../../bindings/combine-binding-schemas.js';
+import { checkOasValue } from '../../openapi/common/check-oas-value.js';
+import { pointerTokens } from '../../bindings/json-pointer.js';
+export function readConfirmedApiInputs(input) {
+    if (input.confirmedInputs === undefined)
+        return [];
+    const confirmed = confirmedApiInputsSchema.parse(input.confirmedInputs);
+    if (confirmed.length && (!input.callId || !input.callId.trim()))
+        throw new Error('confirmedInputs require callId');
+    const targets = input.bindings.map((binding) => binding.targetPointer);
+    for (const item of confirmed) {
+        if (item.callId !== input.callId ||
+            !apiOperationKeyEquals(item.operation, input.operation.key))
+            throw new Error(`confirmedInputs ${item.callId}${item.targetPointer} does not match callId and current OAS snapshot`);
+        const tokens = pointerTokens(item.targetPointer);
+        if (tokens[0] === 'header' &&
+            ['authorization', 'content-type', 'accept'].includes(tokens[1]?.toLowerCase()))
+            throw new Error(`confirmedInputs ${item.targetPointer} is transport/security configuration, not a request value`);
+        if (targets.some((target) => target === item.targetPointer ||
+            target.startsWith(item.targetPointer + '/') ||
+            item.targetPointer.startsWith(target + '/')))
+            throw new Error(`confirmedInputs overlap at ${item.targetPointer}`);
+        const schemas = requestBindingSchemas({ ...input, callId: item.callId }, item.targetPointer);
+        if (!schemas.length)
+            throw new Error(`confirmedInputs ${item.targetPointer} is not allowed by the OAS`);
+        checkOasValue(item.value, unionBindingSchemas(schemas), input.operation.openapiVersion.startsWith('3.0.')
+            ? 'openapi-3.0'
+            : 'draft-2020-12', `confirmedInputs ${item.callId}${item.targetPointer}`);
+        targets.push(item.targetPointer);
+    }
+    return confirmed;
+}

package/dist/arguments/clarification/validate-api-input-answers.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateApiInputAnswersInput, ApiInputAnswersResult } from '../../types/api-clarification.js';
+export declare function validateApiInputAnswers(input: ValidateApiInputAnswersInput): ApiInputAnswersResult;

package/dist/arguments/clarification/validate-api-input-answers.js

@@ -0,0 +1,65 @@
+import { apiInputAnswersSchema } from '../../schemas/confirmed-api-input-schema.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+import { createOasValueValidator } from '../../openapi/common/create-oas-value-validator.js';
+import { listMissingRequestedApiInputs } from './list-missing-requested-api-inputs.js';
+export function validateApiInputAnswers(input) {
+    if (!Array.isArray(input.requirements) || !Array.isArray(input.operations))
+        throw new Error('validateApiInputAnswers.requirements and operations must be arrays');
+    const parsed = apiInputAnswersSchema.safeParse(input.answers);
+    if (!parsed.success)
+        return {
+            status: 'invalid-answer',
+            issues: parsed.error.issues.map((issue) => ({
+                requirementId: '',
+                message: issue.message,
+            })),
+        };
+    const issues = [];
+    const confirmedInputs = [];
+    const seen = new Set();
+    for (const answer of parsed.data) {
+        const requirement = input.requirements.find((item) => item.id === answer.requirementId);
+        if (!requirement || seen.has(answer.requirementId)) {
+            issues.push({
+                requirementId: answer.requirementId,
+                message: 'Unknown or duplicate requirementId',
+            });
+            continue;
+        }
+        seen.add(answer.requirementId);
+        if (!input.operations.some((operation) => apiOperationKeyEquals(operation, requirement.operation)))
+            throw new Error(`Input requirement ${requirement.id} belongs to a stale OAS snapshot`);
+        const checked = createOasValueValidator(requirement.schema, requirement.openapiVersion.startsWith('3.0.')
+            ? 'openapi-3.0'
+            : 'draft-2020-12', `answer ${requirement.targetPointer}`).validate(answer.value);
+        if (!checked.valid) {
+            issues.push({
+                requirementId: requirement.id,
+                message: checked.errors.map((error) => error.message).join('; '),
+            });
+            continue;
+        }
+        const missing = listMissingRequestedApiInputs({
+            source: `Answer ${requirement.id}`,
+            rootPointer: requirement.targetPointer,
+            value: answer.value,
+            requestedInputs: requirement.requestedInputs,
+        });
+        if (missing.length) {
+            issues.push({
+                requirementId: requirement.id,
+                message: `Answer omits scenario-requested inputs: ${missing.join(', ')}`,
+            });
+            continue;
+        }
+        confirmedInputs.push({
+            callId: requirement.callId,
+            operation: structuredClone(requirement.operation),
+            targetPointer: requirement.targetPointer,
+            value: structuredClone(answer.value),
+        });
+    }
+    return issues.length
+        ? { status: 'invalid-answer', issues }
+        : { status: 'accepted', confirmedInputs };
+}

package/dist/arguments/generation/create-api-literal-generation-record.d.ts

@@ -0,0 +1,3 @@
+import type { CreateApiLiteralGenerationRecordInput, ApiLiteralGenerationRecord } from '../../types/api-literal-generation.js';
+/** Only literal proposals are attributed here; confirmed inputs and bindings remain code-owned. */
+export declare function createApiLiteralGenerationRecord(input: CreateApiLiteralGenerationRecordInput): ApiLiteralGenerationRecord;