@openapi-flow/core 0.2.0 → 0.3.0

package/dist/draft/edits/references/resolve-workflow-draft-api-response-sources.js

@@ -0,0 +1,42 @@
+import { apiOperationKeyEquals } from '../../../openapi/catalog/api-operation-key-equals.js';
+import { resolveWorkflowDraftApiMaterials } from '../../resolve-workflow-draft-api-materials.js';
+/** Selection establishes response declarations; only an explicit resolution establishes request data. */
+export function resolveWorkflowDraftApiResponseSources(input) {
+    const sources = new Map();
+    for (const material of resolveWorkflowDraftApiMaterials(input)) {
+        const request = input.content.apiCalls.find((call) => call.id === material.callId);
+        sources.set(material.callId, {
+            nodeId: material.callId,
+            operation: structuredClone(material.operation),
+            preparation: {
+                status: 'request-planned',
+                request: structuredClone(request),
+            },
+        });
+    }
+    for (const step of input.plan.steps) {
+        if (!input.pendingResolutionStepIds.includes(step.id))
+            continue;
+        const decision = step.decision;
+        if (decision.kind !== 'add-api-call' &&
+            decision.kind !== 'replace-api-operation')
+            continue;
+        const nodeId = decision.kind === 'add-api-call' ? step.newNodeId : decision.nodeId;
+        if (typeof nodeId !== 'string' || !nodeId.trim())
+            throw new Error(`Selected API response source ${step.id} requires its actual instance identity`);
+        const matches = input.context.operations.filter((operation) => apiOperationKeyEquals(operation.key, decision.operation));
+        if (matches.length !== 1)
+            throw new Error(`Selected API response source ${nodeId} requires exactly one original OAS contract and snapshot`);
+        sources.set(nodeId, {
+            nodeId,
+            operation: structuredClone(matches[0]),
+            preparation: {
+                status: 'request-pending',
+                stepId: step.id,
+                kind: decision.kind,
+                instruction: decision.instruction,
+            },
+        });
+    }
+    return [...sources.values()];
+}

package/dist/draft/edits/references/resolve-workflow-draft-source-evidence.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveWorkflowDraftSourceEvidenceInput, ResolvedWorkflowDraftSourceEvidence } from '../../../types/workflow-draft-source-evidence.js';
+/** No quote/pointer repair: canonical evidence is constructed from explicitly selected actual IDs. */
+export declare function resolveWorkflowDraftSourceEvidence(input: ResolveWorkflowDraftSourceEvidenceInput): ResolvedWorkflowDraftSourceEvidence;

package/dist/draft/edits/references/resolve-workflow-draft-source-evidence.js

@@ -0,0 +1,56 @@
+import { validateWorkflowPlanningEvidence } from '../../../planning/evidence/validate-workflow-planning-evidence.js';
+/** No quote/pointer repair: canonical evidence is constructed from explicitly selected actual IDs. */
+export function resolveWorkflowDraftSourceEvidence(input) {
+    const { decision, description } = input;
+    const messageEvidence = (id) => {
+        const message = description.messages.find((message) => message.id === id);
+        if (!message)
+            throw new Error(`Draft source evidence cites unavailable current message ${id}`);
+        return { kind: 'message', messageId: message.id, quote: message.text };
+    };
+    const sources = decision.sourceMessageIds.map(messageEvidence);
+    const explanation = decision.explanation === undefined
+        ? undefined
+        : {
+            reason: decision.explanation.reason,
+            evidence: decision.explanation.evidence.map((item) => {
+                if (item.kind === 'message')
+                    return messageEvidence(item.messageId);
+                const source = [
+                    ...description.sources.values,
+                    ...description.sources.exclusiveOutputs,
+                ].find((source) => source.nodeId === item.nodeId);
+                if (!source)
+                    throw new Error(`Draft source evidence cites unavailable source contract ${item.nodeId}`);
+                return source.kind === 'api'
+                    ? {
+                        kind: 'oas',
+                        operation: structuredClone(source.operation.key),
+                        pointer: '',
+                    }
+                    : { kind: 'native', capability: source.node.capability };
+            }),
+        };
+    // Multiple actual instances may cite one original contract; canonical contract facts are unique.
+    if (explanation)
+        explanation.evidence = [
+            ...new Map(explanation.evidence.map((item) => [JSON.stringify(item), item])).values(),
+        ];
+    const operations = [
+        ...new Map(description.sources.values.flatMap((source) => source.kind === 'api'
+            ? [[JSON.stringify(source.operation.key), source.operation]]
+            : [])).values(),
+    ];
+    const context = {
+        messages: description.messages,
+        operations,
+        capabilities: input.capabilities,
+    };
+    validateWorkflowPlanningEvidence({ context, evidence: sources });
+    if (explanation)
+        validateWorkflowPlanningEvidence({
+            context,
+            evidence: explanation.evidence,
+        });
+    return { sources, ...(explanation === undefined ? {} : { explanation }) };
+}

package/dist/draft/edits/references/validate-workflow-draft-native-reference.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateWorkflowDraftNativeReferenceInput } from '../../../types/native-reference-validation.js';
+export declare function validateWorkflowDraftNativeReference(input: ValidateWorkflowDraftNativeReferenceInput): void;

package/dist/draft/edits/references/validate-workflow-draft-native-reference.js

@@ -0,0 +1,22 @@
+import { createResponseValueSchema } from '../../../openapi/response/create-response-value-schema.js';
+import { schemasAtPointer } from '../../../bindings/schema-at-pointer.js';
+import { createSchemaResourceContext } from '../../../bindings/resources/create-schema-resource-context.js';
+export function validateWorkflowDraftNativeReference(input) {
+    const { reference, sources } = input;
+    if (reference.source === 'exclusive-output') {
+        if (!sources.exclusiveOutputs.some((source) => source.nodeId === reference.nodeId))
+            throw new Error(`Native control reference ${reference.nodeId} is not an available exclusive-output source`);
+        return;
+    }
+    const source = sources.values.find((source) => source.nodeId === reference.nodeId);
+    if (!source ||
+        source.kind !== (reference.source === 'response' ? 'api' : 'native'))
+        throw new Error(`Native parameter reference ${reference.nodeId} is not an available ${reference.source} source`);
+    if (source.kind === 'api')
+        createResponseValueSchema(source.operation, reference.pointer);
+    else {
+        const resources = createSchemaResourceContext(source.schema);
+        if (!schemasAtPointer(resources.root, reference.pointer, resources).length)
+            throw new Error(`Native parameter reference ${reference.nodeId}${reference.pointer} is not declared by its native output`);
+    }
+}

package/dist/draft/edits/references/validate-workflow-draft-native-references.d.ts

@@ -0,0 +1,2 @@
+import type { ValidateWorkflowDraftNativeReferencesInput } from '../../../types/native-reference-validation.js';
+export declare function validateWorkflowDraftNativeReferences(input: ValidateWorkflowDraftNativeReferencesInput): void;

package/dist/draft/edits/references/validate-workflow-draft-native-references.js

@@ -0,0 +1,31 @@
+import { createWorkflowNodeContracts } from '../../../workflow/create-workflow-node-contracts.js';
+import { createNativeOutputContracts } from '../../../workflow/create-native-output-contracts.js';
+import { validateWorkflowDraftNativeReference } from './validate-workflow-draft-native-reference.js';
+import { nativeMaterialSourcesFromDraftReferences } from './native-material-sources-from-draft-references.js';
+import { validateNativeMaterialSources } from '../../../workflow/validate-native-material-sources.js';
+export function validateWorkflowDraftNativeReferences(input) {
+    const [contract] = createWorkflowNodeContracts({
+        materials: [],
+        nativeNodes: [input.node],
+        capabilities: [input.capability],
+    });
+    createNativeOutputContracts({
+        nativeNodes: [input.node],
+        capabilities: [input.capability],
+    });
+    const references = [
+        ...contract.references,
+        ...Object.values(contract.inputReferences === undefined ? {} : contract.inputReferences).flat(),
+    ];
+    validateNativeMaterialSources(input.capability, references, nativeMaterialSourcesFromDraftReferences(input.sources));
+    for (const reference of references)
+        validateWorkflowDraftNativeReference({ reference, sources: input.sources });
+    if (contract.rejoinsExclusiveOutputs !== undefined)
+        validateWorkflowDraftNativeReference({
+            reference: {
+                source: 'exclusive-output',
+                nodeId: contract.rejoinsExclusiveOutputs,
+            },
+            sources: input.sources,
+        });
+}

package/dist/draft/edits/resolve-workflow-draft-edit-options.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowDraftEditOptions, ResolvedWorkflowDraftEditOptions } from '../../types/workflow-draft-edit.js';
+export declare function resolveWorkflowDraftEditOptions(input?: WorkflowDraftEditOptions): ResolvedWorkflowDraftEditOptions;

package/dist/draft/edits/resolve-workflow-draft-edit-options.js

@@ -0,0 +1,9 @@
+import { workflowDraftEditOptionsSchema } from '../../schemas/workflow-draft-edit-options-schema.js';
+export function resolveWorkflowDraftEditOptions(input) {
+    const configured = workflowDraftEditOptionsSchema.parse(input === undefined ? {} : input);
+    return {
+        includeExplanations: configured.includeExplanations === undefined
+            ? true
+            : configured.includeExplanations,
+    };
+}

package/dist/draft/edits/stage-workflow-draft-edit.d.ts

@@ -0,0 +1,3 @@
+import type { PrepareWorkflowDraftEditInput, StagedWorkflowDraftEdit } from '../../types/workflow-draft-edit-assembly.js';
+/** Re-derive completed materials, named missing results and unavailable output sources. */
+export declare function stageWorkflowDraftEdit(input: PrepareWorkflowDraftEditInput): StagedWorkflowDraftEdit;

package/dist/draft/edits/stage-workflow-draft-edit.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { resolvePreparedWorkflowDraftEdit } from './assembly/resolve-prepared-workflow-draft-edit.js';
+import { resolveWorkflowDraftApiResponseSources } from './references/resolve-workflow-draft-api-response-sources.js';
+import { describeWorkflowDraftClarificationOwnership } from './clarification/describe-workflow-draft-clarification-ownership.js';
+/** Re-derive completed materials, named missing results and unavailable output sources. */
+export function stageWorkflowDraftEdit(input) {
+    const prepared = resolvePreparedWorkflowDraftEdit(input, 'staged');
+    const apiResponseSources = resolveWorkflowDraftApiResponseSources({
+        ...input,
+        content: prepared.content,
+        pendingResolutionStepIds: prepared.pendingResolutionStepIds,
+    });
+    const blockedContracts = input.plan.steps.flatMap((step) => {
+        if (!prepared.pendingResolutionStepIds.includes(step.id))
+            return [];
+        if (step.decision.kind === 'replace-api-operation' ||
+            step.decision.kind === 'revise-native-node')
+            return [step.decision.nodeId];
+        if (step.decision.kind === 'add-api-call' ||
+            step.decision.kind === 'add-native-node')
+            return [step.newNodeId];
+        return [];
+    });
+    const nodeIds = [
+        ...prepared.content.apiCalls,
+        ...prepared.content.nativeNodes,
+    ].map((node) => node.id);
+    const blockedSourceNodeIds = [
+        ...new Set([
+            ...blockedContracts,
+            ...prepared.content.requirements.flatMap((requirement) => requirement.state === 'confirmed'
+                ? []
+                : requirement.scope.kind === 'workflow'
+                    ? nodeIds
+                    : requirement.scope.nodeIds),
+        ]),
+    ];
+    const state = {
+        planId: prepared.planId,
+        baseRevision: prepared.baseRevision,
+        content: prepared.content,
+        nodeRemovalConnections: prepared.nodeRemovalConnections,
+        pendingResolutionStepIds: prepared.pendingResolutionStepIds,
+        clarificationOwnership: describeWorkflowDraftClarificationOwnership({
+            draft: input.draft,
+            context: input.context,
+            requestMessageIds: input.requestMessageIds,
+            plan: input.plan,
+        }),
+        apiResponseSources,
+        blockedSourceNodeIds,
+        pendingRepairs: prepared.pendingRepairs,
+        deferredRequirementIds: prepared.deferredRequirementIds,
+        pendingClarificationQuestionIds: prepared.pendingClarificationQuestionIds,
+    };
+    return {
+        kind: 'unvalidated-edit-stage',
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(state))
+            .digest('hex'),
+        ...state,
+    };
+}

package/dist/draft/edits/validate-workflow-draft-edit-plan.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateWorkflowDraftEditPlanInput } from '../../types/workflow-draft-edit.js';
+/** A persisted proposal cannot silently rebase, alter stage ownership or allocate its own IDs. */
+export declare function validateWorkflowDraftEditPlan(input: ValidateWorkflowDraftEditPlanInput): void;

package/dist/draft/edits/validate-workflow-draft-edit-plan.js

@@ -0,0 +1,20 @@
+import { isDeepStrictEqual } from 'node:util';
+import { createWorkflowDraftEditPlan } from './create-workflow-draft-edit-plan.js';
+import { workflowDraftEditPlanSchema } from '../../schemas/workflow-draft-edit-plan-schema.js';
+/** A persisted proposal cannot silently rebase, alter stage ownership or allocate its own IDs. */
+export function validateWorkflowDraftEditPlan(input) {
+    const envelope = workflowDraftEditPlanSchema.safeParse(input.plan);
+    if (!envelope.success)
+        throw new Error('Draft edit plan has invalid metadata or step fields', {
+            cause: envelope.error,
+        });
+    const expected = createWorkflowDraftEditPlan({
+        draft: input.draft,
+        context: input.context,
+        requestMessageIds: input.requestMessageIds,
+        options: input.plan.options,
+        proposal: { decisions: input.plan.steps.map((step) => step.decision) },
+    });
+    if (!isDeepStrictEqual(expected, input.plan))
+        throw new Error('Draft edit plan is stale or has modified identities, context, stages or decisions');
+}

package/dist/draft/edits/values/apply-workflow-draft-api-input-edits.d.ts

@@ -0,0 +1,4 @@
+import type { ApiArgumentValues } from '../../../types/api-arguments.js';
+import type { WorkflowDraftApiInputEditMaterial } from '../../../types/workflow-draft-api-input-edit.js';
+import type { WorkflowDraftValueEdit } from '../../../types/workflow-draft-edit-assembly.js';
+export declare function applyWorkflowDraftApiInputEdits(values: ApiArgumentValues, edits: WorkflowDraftValueEdit[], material: WorkflowDraftApiInputEditMaterial): ApiArgumentValues;

package/dist/draft/edits/values/apply-workflow-draft-api-input-edits.js

@@ -0,0 +1,35 @@
+import { pointerTokens, hasPointer } from '../../../bindings/json-pointer.js';
+import { requestBindingSchemas } from '../../../bindings/request-binding-schema.js';
+import { assignRequestInputValue } from '../../../bindings/assign-request-input-value.js';
+import { applyWorkflowDraftValueEdits } from './apply-workflow-draft-value-edits.js';
+import { workflowDraftApiCallSchema } from '../../../schemas/workflow-draft-schema.js';
+import { retainRequestedApiInputsAfterEdits } from '../inputs/retain-requested-api-inputs-after-edits.js';
+export function applyWorkflowDraftApiInputEdits(values, edits, material) {
+    let result = structuredClone(values);
+    for (const edit of edits) {
+        const tokens = pointerTokens(edit.pointer);
+        if (edit.kind === 'remove' &&
+            !hasPointer(result, edit.pointer) &&
+            material.requestedInputs !== undefined &&
+            retainRequestedApiInputsAfterEdits(material.requestedInputs, [edit])
+                .length !== material.requestedInputs.length)
+            // The declared intent is the existing object being removed. There is no
+            // literal to delete; final assembly removes this metadata in the same edit.
+            continue;
+        const parameterGroup = tokens.length === 1 &&
+            material.operation.effective.parameters.some((parameter) => parameter.in === tokens[0]);
+        if (edit.kind === 'set' &&
+            !parameterGroup &&
+            !requestBindingSchemas(material, edit.pointer).length)
+            throw new Error(`Draft input edit ${material.callId}${edit.pointer} is not declared by its OAS`);
+        result =
+            edit.kind === 'set' && !hasPointer(result, edit.pointer)
+                ? assignRequestInputValue(result, edit.pointer, edit.value, material)
+                : workflowDraftApiCallSchema.shape.values.parse(applyWorkflowDraftValueEdits({
+                    value: result,
+                    edits: [edit],
+                    source: `Draft API ${material.callId}`,
+                }));
+    }
+    return result;
+}

package/dist/draft/edits/values/apply-workflow-draft-binding-edits.d.ts

@@ -0,0 +1,3 @@
+import type { OutputBinding } from '../../../types/api-arguments.js';
+import type { WorkflowDraftBindingEdit } from '../../../types/workflow-draft-edit-assembly.js';
+export declare function applyWorkflowDraftBindingEdits(bindings: OutputBinding[], edits: WorkflowDraftBindingEdit[], source: string): OutputBinding[];

package/dist/draft/edits/values/apply-workflow-draft-binding-edits.js

@@ -0,0 +1,17 @@
+export function applyWorkflowDraftBindingEdits(bindings, edits, source) {
+    const result = structuredClone(bindings);
+    for (const edit of edits) {
+        const target = edit.kind === 'set' ? edit.binding.targetPointer : edit.targetPointer;
+        const index = result.findIndex((binding) => binding.targetPointer === target);
+        if (edit.kind === 'remove') {
+            if (index < 0)
+                throw new Error(`${source}: cannot remove absent binding ${target}`);
+            result.splice(index, 1);
+        }
+        else if (index < 0)
+            result.push(structuredClone(edit.binding));
+        else
+            result[index] = structuredClone(edit.binding);
+    }
+    return result;
+}

package/dist/draft/edits/values/apply-workflow-draft-value-edits.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from '../../../types/api-arguments.js';
+import type { ApplyWorkflowDraftValueEditsInput } from '../../../types/workflow-draft-edit-assembly-internal.js';
+/** Explicit set/remove semantics. No missing parent, sparse array or value is guessed. */
+export declare function applyWorkflowDraftValueEdits(input: ApplyWorkflowDraftValueEditsInput): JsonValue;

package/dist/draft/edits/values/apply-workflow-draft-value-edits.js

@@ -0,0 +1,45 @@
+import { pointerTokens } from '../../../bindings/json-pointer.js';
+import { cloneJsonValue } from '../../../utils/clone-json-value.js';
+/** Explicit set/remove semantics. No missing parent, sparse array or value is guessed. */
+export function applyWorkflowDraftValueEdits(input) {
+    let result = cloneJsonValue(input.value);
+    for (const edit of input.edits) {
+        const tokens = pointerTokens(edit.pointer);
+        if (!tokens.length) {
+            if (edit.kind === 'remove')
+                throw new Error(`${input.source}: cannot remove the parameter root`);
+            result = cloneJsonValue(edit.value);
+            continue;
+        }
+        let parent = result;
+        for (const token of tokens.slice(0, -1)) {
+            if (parent === null ||
+                typeof parent !== 'object' ||
+                !Object.hasOwn(parent, token))
+                throw new Error(`${input.source}${edit.pointer}: missing explicit parent container`);
+            parent = Reflect.get(parent, token);
+        }
+        if (parent === null || typeof parent !== 'object')
+            throw new Error(`${input.source}${edit.pointer}: parent is not a container`);
+        const name = tokens.at(-1);
+        if (Array.isArray(parent)) {
+            if (!/^(0|[1-9][0-9]*)$/.test(name) || Number(name) > parent.length)
+                throw new Error(`${input.source}${edit.pointer}: invalid or sparse array index`);
+            if (edit.kind === 'remove') {
+                if (Number(name) === parent.length)
+                    throw new Error(`${input.source}${edit.pointer}: cannot remove an absent value`);
+                parent.splice(Number(name), 1);
+            }
+            else
+                parent[Number(name)] = cloneJsonValue(edit.value);
+        }
+        else if (edit.kind === 'remove') {
+            if (!Object.hasOwn(parent, name))
+                throw new Error(`${input.source}${edit.pointer}: cannot remove an absent value`);
+            Reflect.deleteProperty(parent, name);
+        }
+        else
+            Reflect.set(parent, name, cloneJsonValue(edit.value));
+    }
+    return result;
+}

package/dist/draft/edits/values/order-workflow-draft-value-edits.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftValueEdit } from '../../../types/workflow-draft-edit-assembly.js';
+/** Targets refer to the original object: set first, then remove descending array indices. */
+export declare function orderWorkflowDraftValueEdits(edits: WorkflowDraftValueEdit[]): WorkflowDraftValueEdit[];

package/dist/draft/edits/values/order-workflow-draft-value-edits.js

@@ -0,0 +1,25 @@
+import { pointerTokens } from '../../../bindings/json-pointer.js';
+function comparePointers(left, right) {
+    const a = pointerTokens(left);
+    const b = pointerTokens(right);
+    for (let index = 0; index < Math.min(a.length, b.length); index++) {
+        if (a[index] === b[index])
+            continue;
+        if (/^(0|[1-9][0-9]*)$/.test(a[index]) &&
+            /^(0|[1-9][0-9]*)$/.test(b[index]))
+            return Number(a[index]) - Number(b[index]);
+        return a[index] < b[index] ? -1 : 1;
+    }
+    return a.length - b.length;
+}
+/** Targets refer to the original object: set first, then remove descending array indices. */
+export function orderWorkflowDraftValueEdits(edits) {
+    return [
+        ...edits
+            .filter((edit) => edit.kind === 'set')
+            .sort((left, right) => comparePointers(left.pointer, right.pointer)),
+        ...edits
+            .filter((edit) => edit.kind === 'remove')
+            .sort((left, right) => comparePointers(right.pointer, left.pointer)),
+    ];
+}

package/dist/draft/edits/workflow-draft-edit-assembly-error.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowDraftEditAssemblyFailure } from '../../types/workflow-draft-edit-assembly.js';
+export declare class WorkflowDraftEditAssemblyError extends Error {
+    readonly failure: WorkflowDraftEditAssemblyFailure;
+    constructor(failure: WorkflowDraftEditAssemblyFailure, cause: Error);
+}

package/dist/draft/edits/workflow-draft-edit-assembly-error.js

@@ -0,0 +1,10 @@
+export class WorkflowDraftEditAssemblyError extends Error {
+    failure;
+    constructor(failure, cause) {
+        super(`Draft edit assembly failed at ${failure.stage}: ${cause.message}`, {
+            cause,
+        });
+        this.name = 'WorkflowDraftEditAssemblyError';
+        this.failure = structuredClone(failure);
+    }
+}

package/dist/draft/edits/workflow-draft-edit-stages.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftEditDecision, WorkflowDraftEditStage } from '../../types/workflow-draft-edit.js';
+/** Stage ownership follows the explicit edit kind, never a natural-language heuristic. */
+export declare function workflowDraftEditStages(decision: WorkflowDraftEditDecision): WorkflowDraftEditStage[];

package/dist/draft/edits/workflow-draft-edit-stages.js

@@ -0,0 +1,33 @@
+/** Stage ownership follows the explicit edit kind, never a natural-language heuristic. */
+export function workflowDraftEditStages(decision) {
+    switch (decision.kind) {
+        case 'add-api-call':
+        case 'replace-api-operation':
+            return [
+                'resolve-contracts',
+                'api-bindings',
+                'api-arguments',
+                'connections',
+            ];
+        case 'add-native-node':
+            return ['native-parameters', 'connections'];
+        case 'revise-api-inputs':
+            return ['api-arguments'];
+        case 'revise-api-bindings':
+            return ['api-bindings', 'api-arguments', 'connections'];
+        case 'revise-native-node':
+            return ['native-parameters', 'api-bindings', 'connections'];
+        case 'remove-node':
+        case 'report-capability-gap':
+        case 'revise-connections':
+            return ['connections'];
+        case 'revise-requirement':
+        case 'restore-requirement':
+        case 'remove-requirement':
+            return ['requirements'];
+        case 'needs-clarification':
+            return decision.owner.kind === 'semantic' ? ['clarification'] : [];
+        case 'no-change':
+            return [];
+    }
+}

package/dist/draft/gaps/create-workflow-draft-capability-gap.d.ts

@@ -0,0 +1,3 @@
+import type { CreateWorkflowDraftCapabilityGapInput, WorkflowDraftCapabilityGap } from '../../types/workflow-draft-capability-gap.js';
+/** Code owns identity, inventory receipt and unchanged original evidence. The finding remains a semantic judgment. */
+export declare function createWorkflowDraftCapabilityGap(input: CreateWorkflowDraftCapabilityGapInput): WorkflowDraftCapabilityGap;

package/dist/draft/gaps/create-workflow-draft-capability-gap.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { workflowDraftCapabilityGapSchema, workflowDraftCapabilityGapFieldsSchema, } from '../../schemas/workflow-draft-capability-gap-schema.js';
+import { describeWorkflowDraftGapInventory } from './describe-workflow-draft-gap-inventory.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+/** Code owns identity, inventory receipt and unchanged original evidence. The finding remains a semantic judgment. */
+export function createWorkflowDraftCapabilityGap(input) {
+    if (!Array.isArray(input.sourceMessageIds) ||
+        !input.sourceMessageIds.length ||
+        new Set(input.sourceMessageIds).size !== input.sourceMessageIds.length)
+        throw new Error('Capability gap sourceMessageIds must name distinct original messages');
+    const inventory = describeWorkflowDraftGapInventory(input.context);
+    const finding = workflowDraftCapabilityGapFieldsSchema.shape.finding.parse(input.finding);
+    if (finding.kind === 'api-contract-gap' &&
+        !inventory.operations.some((operation) => apiOperationKeyEquals(operation, finding.operation)))
+        throw new Error('Capability gap operation must be an actual supplied OAS operation and snapshot');
+    const sources = input.sourceMessageIds.map((messageId) => {
+        const message = input.context.messages.find((message) => message.id === messageId);
+        if (!message)
+            throw new Error(`Capability gap sourceMessageIds contains unknown message ${messageId}`);
+        return { kind: 'message', messageId, quote: message.text };
+    });
+    const fields = workflowDraftCapabilityGapFieldsSchema.parse({
+        id: input.id,
+        requestedBehavior: input.requestedBehavior,
+        finding: structuredClone(input.finding),
+        sources,
+        inventory,
+    });
+    return workflowDraftCapabilityGapSchema.parse({
+        ...fields,
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(fields))
+            .digest('hex'),
+    });
+}

package/dist/draft/gaps/describe-workflow-draft-capability-gap.d.ts

@@ -0,0 +1,3 @@
+import type { InspectWorkflowDraftCapabilityGapInput, WorkflowDraftCapabilityGapDescription } from '../../types/workflow-draft-capability-gap.js';
+/** Read-only choice context: models do not generate or need a copy of the full inventory receipt. */
+export declare function describeWorkflowDraftCapabilityGap(input: InspectWorkflowDraftCapabilityGapInput): WorkflowDraftCapabilityGapDescription;

package/dist/draft/gaps/describe-workflow-draft-capability-gap.js

@@ -0,0 +1,10 @@
+import { inspectWorkflowDraftCapabilityGap } from './inspect-workflow-draft-capability-gap.js';
+/** Read-only choice context: models do not generate or need a copy of the full inventory receipt. */
+export function describeWorkflowDraftCapabilityGap(input) {
+    return {
+        ...inspectWorkflowDraftCapabilityGap(input),
+        id: input.gap.id,
+        requestedBehavior: input.gap.requestedBehavior,
+        finding: structuredClone(input.gap.finding),
+    };
+}

package/dist/draft/gaps/describe-workflow-draft-gap-inventory.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftContext } from '../../types/workflow-draft.js';
+import type { WorkflowDraftGapInventory } from '../../types/workflow-draft-capability-gap.js';
+/** Capture actual supplied contract identities; message order and later replies are not inventory changes. */
+export declare function describeWorkflowDraftGapInventory(context: WorkflowDraftContext): WorkflowDraftGapInventory;

package/dist/draft/gaps/describe-workflow-draft-gap-inventory.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowPlanningContext } from '../../planning/evidence/describe-workflow-planning-context.js';
+import { apiOperationKeySchema } from '../../schemas/api-operation-key-schema.js';
+/** Capture actual supplied contract identities; message order and later replies are not inventory changes. */
+export function describeWorkflowDraftGapInventory(context) {
+    if (!context ||
+        !Array.isArray(context.operations) ||
+        !Array.isArray(context.capabilities) ||
+        !Array.isArray(context.messages))
+        throw new Error('Capability gap context requires explicit operations, capabilities and messages arrays');
+    const planning = describeWorkflowPlanningContext(context);
+    return {
+        operations: planning.operations
+            .map((operation) => apiOperationKeySchema.parse(operation.key))
+            .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right))),
+        capabilities: planning.capabilities
+            .map((capability) => ({
+            name: capability.name,
+            fingerprint: createHash('sha256')
+                .update(JSON.stringify(capability))
+                .digest('hex'),
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+    };
+}

package/dist/draft/gaps/inspect-workflow-draft-capability-gap.d.ts

@@ -0,0 +1,3 @@
+import type { InspectWorkflowDraftCapabilityGapInput, WorkflowDraftCapabilityGapInspection } from '../../types/workflow-draft-capability-gap.js';
+/** A retained gap is historical when inventory changes; never silently resolved or re-attributed. */
+export declare function inspectWorkflowDraftCapabilityGap(input: InspectWorkflowDraftCapabilityGapInput): WorkflowDraftCapabilityGapInspection;

package/dist/draft/gaps/inspect-workflow-draft-capability-gap.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { workflowDraftCapabilityGapSchema } from '../../schemas/workflow-draft-capability-gap-schema.js';
+import { describeWorkflowDraftGapInventory } from './describe-workflow-draft-gap-inventory.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+/** A retained gap is historical when inventory changes; never silently resolved or re-attributed. */
+export function inspectWorkflowDraftCapabilityGap(input) {
+    const currentInventory = describeWorkflowDraftGapInventory(input.context);
+    const { fingerprint, ...fields } = workflowDraftCapabilityGapSchema.parse(input.gap);
+    if (!isDeepStrictEqual(input.gap, { ...fields, fingerprint }) ||
+        createHash('sha256').update(JSON.stringify(fields)).digest('hex') !==
+            fingerprint)
+        throw new Error(`Capability gap ${fields.id} has changed finding, inventory or evidence`);
+    for (const source of fields.sources)
+        if (!input.context.messages.some((message) => message.id === source.messageId && message.text === source.quote))
+            throw new Error(`Capability gap ${fields.id} source ${source.messageId} is absent or changed`);
+    const finding = fields.finding;
+    if (finding.kind === 'api-contract-gap' &&
+        !fields.inventory.operations.some((operation) => apiOperationKeyEquals(operation, finding.operation)))
+        throw new Error(`Capability gap ${fields.id} cites an operation outside its original inventory`);
+    return {
+        inventoryCurrent: isDeepStrictEqual(fields.inventory, currentInventory),
+    };
+}

package/dist/draft/impact/analyze-draft-change-impact.d.ts

@@ -0,0 +1,2 @@
+import type { AnalyzeDraftChangeImpactInput, DraftChangeImpact } from '../../types/workflow-draft-changes.js';
+export declare function analyzeDraftChangeImpact(input: AnalyzeDraftChangeImpactInput): DraftChangeImpact;