@openapi-flow/core 0.2.0 → 0.3.0

package/dist/bindings/planning/create-api-binding-planning-record.js

@@ -0,0 +1,26 @@
+import { apiBindingCallReasonsSchema, apiBindingPlanningRecordSchema, } from '../../schemas/api-binding-planning-schema.js';
+import { describeApiBindingPlanning } from './describe-api-binding-planning.js';
+import { validateApiBindingAssignments } from '../validate-api-binding-assignments.js';
+import { validateApiBindingGaps } from '../validate-api-binding-gaps.js';
+/** Reasons belong to exact call decisions; gap descriptions already state their reasons. */
+export function createApiBindingPlanningRecord(input) {
+    const { input: snapshot, context } = describeApiBindingPlanning(input);
+    validateApiBindingAssignments({ ...snapshot, calls: input.plan.calls });
+    validateApiBindingGaps({ ...snapshot, plan: input.plan });
+    const reasons = apiBindingCallReasonsSchema.parse(input.reasons);
+    const byId = new Map(reasons.map((item) => [item.callId, item.reason]));
+    if (reasons.length !== input.plan.calls.length ||
+        byId.size !== reasons.length ||
+        input.plan.calls.some((call) => !byId.has(call.callId)))
+        throw new Error('binding planning reasons must name every planned callId exactly once');
+    return apiBindingPlanningRecordSchema.parse({
+        kind: 'proposed-bindings',
+        calls: input.plan.calls.map((call) => ({
+            callId: call.callId,
+            bindings: structuredClone(call.bindings),
+            reason: byId.get(call.callId),
+        })),
+        gaps: structuredClone(input.plan.gaps),
+        evidence: { kind: 'supplied-binding-contracts', context },
+    });
+}

package/dist/bindings/planning/describe-api-binding-planning.d.ts

@@ -0,0 +1,3 @@
+import type { ApiBindingPlanningDescription, ApiBindingPlanningInput } from '../../types/api-binding-planning.js';
+/** Snapshot only declared source data before an asynchronous model invocation. */
+export declare function describeApiBindingPlanning(input: ApiBindingPlanningInput): ApiBindingPlanningDescription;

package/dist/bindings/planning/describe-api-binding-planning.js

@@ -0,0 +1,59 @@
+import { apiBindingPlanningIdentitySchema, apiBindingMaterialRoleSchema, apiBindingPlanningOperationSchema, } from '../../schemas/api-binding-planning-schema.js';
+import { createApiBindingSourceRegistry } from '../create-api-binding-source-registry.js';
+import { listApiResponsePointers } from '../../openapi/response/list-api-response-pointers.js';
+/** Snapshot only declared source data before an asynchronous model invocation. */
+export function describeApiBindingPlanning(input) {
+    const { scenario } = apiBindingPlanningIdentitySchema.parse({
+        scenario: input.scenario,
+    });
+    createApiBindingSourceRegistry(input);
+    const materials = input.materials.map((material) => {
+        const parsedOperation = apiBindingPlanningOperationSchema.safeParse(material.operation);
+        if (!parsedOperation.success)
+            throw new Error(`binding material ${material.callId}.operation is invalid: ${parsedOperation.error.message}`);
+        const options = apiBindingMaterialRoleSchema.parse({
+            purpose: material.purpose,
+            requestMediaType: material.requestMediaType,
+        });
+        return {
+            callId: material.callId,
+            operation: structuredClone(material.operation),
+            ...(options.purpose === undefined ? {} : { purpose: options.purpose }),
+            ...(options.requestMediaType === undefined
+                ? {}
+                : { requestMediaType: options.requestMediaType }),
+        };
+    });
+    const snapshot = {
+        scenario,
+        materials,
+        ...(input.nativeOutputs === undefined
+            ? {}
+            : {
+                nativeOutputs: input.nativeOutputs.map((output) => ({
+                    nodeId: output.nodeId,
+                    schema: structuredClone(output.schema),
+                })),
+            }),
+    };
+    return {
+        input: snapshot,
+        context: {
+            scenario,
+            ...(snapshot.nativeOutputs === undefined
+                ? {}
+                : { nativeOutputs: structuredClone(snapshot.nativeOutputs) }),
+            materials: materials.map(({ operation, ...material }) => ({
+                ...material,
+                operation: structuredClone({
+                    key: operation.key,
+                    method: operation.method,
+                    path: operation.path,
+                    operation: operation.operation,
+                    effective: operation.effective,
+                }),
+                responsePointerCatalog: listApiResponsePointers(operation),
+            })),
+        },
+    };
+}

package/dist/bindings/planning/validate-api-binding-planning-record.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiBindingPlanningRecordInput } from '../../types/api-binding-planning.js';
+/** Recheck against the original planning input and actual proposed plan, not later revisions. */
+export declare function validateApiBindingPlanningRecord(input: ValidateApiBindingPlanningRecordInput): void;

package/dist/bindings/planning/validate-api-binding-planning-record.js

@@ -0,0 +1,13 @@
+import { isDeepStrictEqual } from 'node:util';
+import { apiBindingPlanningRecordSchema } from '../../schemas/api-binding-planning-schema.js';
+import { createApiBindingPlanningRecord } from './create-api-binding-planning-record.js';
+/** Recheck against the original planning input and actual proposed plan, not later revisions. */
+export function validateApiBindingPlanningRecord(input) {
+    const record = apiBindingPlanningRecordSchema.parse(input.record);
+    const expected = createApiBindingPlanningRecord({
+        ...input,
+        reasons: record.calls.map(({ callId, reason }) => ({ callId, reason })),
+    });
+    if (!isDeepStrictEqual(record, expected))
+        throw new Error('Binding planning record differs from its original scenario, roles, contracts, native sources or proposed plan');
+}

package/dist/bindings/request-container-kind.js

@@ -2,7 +2,7 @@ import { requestBindingSchemas } from './request-binding-schema.js';
 import { schemaAllowsContainer } from './schema-allows-container.js';
 /** Container identity comes from the OAS, never from a numeric property name. */
 export function requestContainerKind(material, pointer) {
-    if (['/path', '/query', '/header', '/cookie'].includes(pointer))
+    if (['/path', '/query', '/header', '/cookie', '/querystring'].includes(pointer))
         return 'object';
     const kinds = new Set();
     for (const schema of requestBindingSchemas(material, pointer)) {

package/dist/bindings/resources/create-schema-resource-context.js

@@ -4,6 +4,7 @@ import addFormats from 'ajv-formats';
 import uri from 'fast-uri';
 import { isObject } from '../../utils/is-object.js';
 import { cloneSchemaResource } from './clone-schema-resource.js';
+import { jsonValuesEqual } from '../../utils/json-values-equal.js';
 /** Keep original resources; projected values reference their original locations. */
 export function createSchemaResourceContext(schema) {
     if (typeof schema === 'boolean')
@@ -12,6 +13,10 @@ export function createSchemaResourceContext(schema) {
             reference: (value) => value,
             resolve: (value) => value,
             bundle: (value) => value,
+            bundleStaticProjections: (projections) => ({
+                projections,
+                definitions: {},
+            }),
         };
     const document = cloneSchemaResource(schema);
     if (typeof document === 'boolean')
@@ -108,6 +113,104 @@ export function createSchemaResourceContext(schema) {
             ? declaredType(resolveReference(current), visited)
             : undefined;
     }
+    function bundleStaticProjections(projections) {
+        const definitions = {};
+        const names = new WeakMap();
+        function rewrite(current) {
+            if (typeof current === 'boolean')
+                return current;
+            if (current.$dynamicRef !== undefined ||
+                current.$dynamicAnchor !== undefined ||
+                current.$recursiveRef !== undefined ||
+                current.$recursiveAnchor !== undefined)
+                throw new Error('Static schema relocation cannot change dynamic or recursive schema scope; an explicit dialect-aware bundle is required');
+            const result = cloneSchemaResource(current);
+            if (typeof result === 'boolean')
+                throw new Error('Expected a schema object');
+            // Resolution annotations are replaced by canonical locations, not validation rules.
+            delete result.$id;
+            delete result.$anchor;
+            delete result.$defs;
+            delete result.definitions;
+            // Only schema-valued positions are visited: const/enum/default/example data stay verbatim.
+            for (const key of [
+                'properties',
+                'patternProperties',
+                'dependentSchemas',
+                'dependencies',
+            ]) {
+                const children = current[key];
+                if (isObject(children))
+                    result[key] = Object.fromEntries(Object.entries(children).map(([name, child]) => [
+                        name,
+                        typeof child === 'boolean' || isObject(child)
+                            ? rewrite(child)
+                            : child,
+                    ]));
+            }
+            for (const key of [
+                'items',
+                'contains',
+                'additionalProperties',
+                'unevaluatedProperties',
+                'unevaluatedItems',
+                'propertyNames',
+                'not',
+                'if',
+                'then',
+                'else',
+            ]) {
+                const child = current[key];
+                if (typeof child === 'boolean' || isObject(child))
+                    result[key] = rewrite(child);
+            }
+            for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+                const children = current[key];
+                if (Array.isArray(children))
+                    result[key] = children.map((child) => typeof child === 'boolean' || isObject(child)
+                        ? rewrite(child)
+                        : child);
+            }
+            if (typeof current.$ref === 'string') {
+                const target = resolveReference(current);
+                if (typeof target === 'boolean') {
+                    delete result.$ref;
+                    if (!target)
+                        result.allOf = [
+                            false,
+                            ...(Array.isArray(result.allOf) ? result.allOf : []),
+                        ];
+                }
+                else {
+                    const location = locations.get(target);
+                    if (!location)
+                        throw new Error('Local schema reference target has no original resource location');
+                    let name = names.get(target);
+                    if (name === undefined) {
+                        name =
+                            'schema-' +
+                                createHash('sha256').update(location.reference).digest('hex');
+                        names.set(target, name);
+                        definitions[name] = rewrite(target);
+                    }
+                    result.$ref = '#/$defs/' + name;
+                    // Projection-owned type metadata repeats the referenced declaration exactly.
+                    // Original schema siblings are assertions and must never be discarded.
+                    if (!locations.has(current) &&
+                        Object.keys(current).every((key) => key === '$ref' || key === 'type') &&
+                        current.type !== undefined &&
+                        jsonValuesEqual(current.type, declaredType(target)))
+                        delete result.type;
+                }
+            }
+            return result;
+        }
+        const relocated = Object.fromEntries(Object.entries(projections).map(([name, projection]) => [
+            name,
+            rewrite(projection),
+        ]));
+        return { projections: relocated, definitions };
+    }
     return {
         root,
         reference: (current) => {
@@ -123,6 +226,7 @@ export function createSchemaResourceContext(schema) {
             };
         },
         resolve: resolveReference,
+        bundleStaticProjections,
         bundle: (projection) => typeof projection === 'boolean'
             ? { $defs: { resource: root }, allOf: [projection] }
             : { ...projection, $defs: { resource: root } },

package/dist/bindings/validate-api-binding-assignment.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiBindingAssignmentInput } from '../types/api-bindings.js';
+/** Validate an actual assignment without fabricating empty bindings for unrelated calls. */
+export declare function validateApiBindingAssignment(input: ValidateApiBindingAssignmentInput): void;

package/dist/bindings/validate-api-binding-assignment.js

@@ -0,0 +1,9 @@
+import { createApiBindingSourceRegistry } from './create-api-binding-source-registry.js';
+import { validateRegisteredApiBinding } from './validate-registered-api-binding.js';
+/** Validate an actual assignment without fabricating empty bindings for unrelated calls. */
+export function validateApiBindingAssignment(input) {
+    validateRegisteredApiBinding({
+        ...input,
+        registry: createApiBindingSourceRegistry(input),
+    });
+}

package/dist/bindings/validate-api-binding-assignments.js

@@ -1,32 +1,8 @@
-import { pointerTokens } from './json-pointer.js';
-import { requestBindingSchemas } from './request-binding-schema.js';
-import { responseBindingSchemas } from './response-binding-schema.js';
-import { nativeBindingSchemas } from './native-binding-schema.js';
-import { validateNativeOutputContracts } from './validate-native-output-contracts.js';
-function declaredTypes(schemas) {
-    const types = new Set();
-    for (const schema of schemas) {
-        if (typeof schema === 'boolean' || schema.type === undefined)
-            return new Set();
-        for (const type of Array.isArray(schema.type) ? schema.type : [schema.type])
-            if (typeof type === 'string')
-                types.add(type);
-        if (schema.nullable === true)
-            types.add('null');
-    }
-    return types;
-}
+import { createApiBindingSourceRegistry } from './create-api-binding-source-registry.js';
+import { validateRegisteredApiBinding } from './validate-registered-api-binding.js';
 export function validateApiBindingAssignments({ calls, materials, nativeOutputs = [], }) {
-    const byId = new Map(materials.map((material) => [material.callId, material]));
-    if (!materials.length ||
-        byId.size !== materials.length ||
-        materials.some((item) => !item.callId.trim()))
-        throw new Error('binding materials require unique non-empty callIds');
-    validateNativeOutputContracts(nativeOutputs);
-    const nativeById = new Map(nativeOutputs.map((item) => [item.nodeId, item]));
-    for (const output of nativeOutputs)
-        if (byId.has(output.nodeId))
-            throw new Error(`native output ${output.nodeId} duplicates an API callId`);
+    const registry = createApiBindingSourceRegistry({ materials, nativeOutputs });
+    const byId = registry.api;
     if (calls.length !== materials.length ||
         new Set(calls.map((call) => call.callId)).size !== materials.length)
         throw new Error('binding plan must name every material callId exactly once');
@@ -38,35 +14,12 @@ export function validateApiBindingAssignments({ calls, materials, nativeOutputs
         const pointers = [];
         dependencies.set(call.callId, []);
         for (const binding of call.bindings) {
-            if (binding.kind !== 'node-output')
-                throw new Error('bindings.kind must be node-output');
-            pointerTokens(binding.targetPointer);
-            pointerTokens(binding.sourcePointer);
-            const source = byId.get(binding.sourceNodeId);
-            const native = nativeById.get(binding.sourceNodeId);
-            if (!source && !native)
-                throw new Error(`bindings: unknown sourceNodeId ${binding.sourceNodeId}`);
-            if (binding.sourceNodeId === call.callId)
-                throw new Error(`bindings: self-reference ${call.callId}`);
+            validateRegisteredApiBinding({ callId: call.callId, binding, registry });
             if (pointers.some((pointer) => pointer === binding.targetPointer ||
                 pointer.startsWith(binding.targetPointer + '/') ||
                 binding.targetPointer.startsWith(pointer + '/')))
                 throw new Error(`bindings overlap at ${call.callId}${binding.targetPointer}`);
             pointers.push(binding.targetPointer);
-            const targets = requestBindingSchemas(target, binding.targetPointer);
-            const sources = native
-                ? nativeBindingSchemas(native, binding.sourcePointer)
-                : responseBindingSchemas(source.operation, binding.sourcePointer);
-            if (!targets.length)
-                throw new Error(`bindings: ${call.callId}${binding.targetPointer} is not declared by the request OAS`);
-            if (!sources.length)
-                throw new Error(`bindings: ${binding.sourceNodeId}${binding.sourcePointer} is not declared by the ${native ? 'native output contract' : 'response OAS'}`);
-            const from = declaredTypes(sources);
-            const to = declaredTypes(targets);
-            if (from.size &&
-                to.size &&
-                ![...from].some((type) => to.has(type) || (type === 'integer' && to.has('number'))))
-                throw new Error(`bindings: incompatible OAS types ${binding.sourceNodeId}${binding.sourcePointer} -> ${call.callId}${binding.targetPointer}`);
             dependencies.get(call.callId).push(binding.sourceNodeId);
         }
     }

package/dist/bindings/validate-registered-api-binding.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateRegisteredApiBindingInput } from '../types/binding-validation-internal.js';
+/** One declared source-to-input contract, not a whole graph/readiness assertion. */
+export declare function validateRegisteredApiBinding({ callId, binding, registry, }: ValidateRegisteredApiBindingInput): void;

package/dist/bindings/validate-registered-api-binding.js

@@ -0,0 +1,52 @@
+import { pointerTokens } from './json-pointer.js';
+import { requestBindingSchemas } from './request-binding-schema.js';
+import { responseBindingSchemas } from './response-binding-schema.js';
+import { nativeBindingSchemas } from './native-binding-schema.js';
+function declaredTypes(schemas) {
+    const types = new Set();
+    for (const schema of schemas) {
+        if (typeof schema === 'boolean' || schema.type === undefined)
+            return new Set();
+        for (const type of Array.isArray(schema.type) ? schema.type : [schema.type])
+            if (typeof type === 'string')
+                types.add(type);
+        if (schema.nullable === true)
+            types.add('null');
+    }
+    return types;
+}
+/** One declared source-to-input contract, not a whole graph/readiness assertion. */
+export function validateRegisteredApiBinding({ callId, binding, registry, }) {
+    const target = registry.api.get(callId);
+    if (!target)
+        throw new Error(`bindings: unknown target callId ${callId}`);
+    if (!binding || binding.kind !== 'node-output')
+        throw new Error('bindings.kind must be node-output');
+    if (typeof binding.targetPointer !== 'string' ||
+        typeof binding.sourcePointer !== 'string')
+        throw new Error('bindings.targetPointer and sourcePointer must be JSON Pointer strings');
+    if (typeof binding.sourceNodeId !== 'string' || !binding.sourceNodeId.trim())
+        throw new Error('bindings.sourceNodeId must be a non-empty string');
+    pointerTokens(binding.targetPointer);
+    pointerTokens(binding.sourcePointer);
+    const source = registry.api.get(binding.sourceNodeId);
+    const native = registry.native.get(binding.sourceNodeId);
+    if (!source && !native)
+        throw new Error(`bindings: unknown sourceNodeId ${binding.sourceNodeId}`);
+    if (binding.sourceNodeId === callId)
+        throw new Error(`bindings: self-reference ${callId}`);
+    const targets = requestBindingSchemas(target, binding.targetPointer);
+    const sources = native
+        ? nativeBindingSchemas(native, binding.sourcePointer)
+        : responseBindingSchemas(source.operation, binding.sourcePointer);
+    if (!targets.length)
+        throw new Error(`bindings: ${callId}${binding.targetPointer} is not declared by the request OAS`);
+    if (!sources.length)
+        throw new Error(`bindings: ${binding.sourceNodeId}${binding.sourcePointer} is not declared by the ${native ? 'native output contract' : 'response OAS'}`);
+    const from = declaredTypes(sources);
+    const to = declaredTypes(targets);
+    if (from.size &&
+        to.size &&
+        ![...from].some((type) => to.has(type) || (type === 'integer' && to.has('number'))))
+        throw new Error(`bindings: incompatible OAS types ${binding.sourceNodeId}${binding.sourcePointer} -> ${callId}${binding.targetPointer}`);
+}

package/dist/draft/approve-workflow-draft.d.ts

@@ -0,0 +1,3 @@
+import type { ApproveWorkflowDraftInput, WorkflowDraft } from '../types/workflow-draft.js';
+/** Host approval is an explicit revision-checked action, not a model field. */
+export declare function approveWorkflowDraft(input: ApproveWorkflowDraftInput): WorkflowDraft;

package/dist/draft/approve-workflow-draft.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+import { inspectDraftReadiness } from './inspect-draft-readiness.js';
+import { draftRevisionSchema } from '../schemas/workflow-draft-schema.js';
+import { validateWorkflowDraft } from './validate-workflow-draft.js';
+/** Host approval is an explicit revision-checked action, not a model field. */
+export function approveWorkflowDraft(input) {
+    const readiness = inspectDraftReadiness(input);
+    draftRevisionSchema.parse(input.expectedRevision);
+    if (input.expectedRevision !== input.draft.revision)
+        throw new Error(`Stale approval revision: expected ${input.draft.revision}, received ${input.expectedRevision}`);
+    if (!Array.isArray(input.nodeIds) ||
+        !input.nodeIds.length ||
+        new Set(input.nodeIds).size !== input.nodeIds.length)
+        throw new Error('Draft approval requires distinct nodeIds');
+    for (const id of input.nodeIds) {
+        const node = readiness.nodes.find((node) => node.nodeId === id);
+        if (!node || node.planningStatus !== 'ready')
+            throw new Error(`Cannot approve unknown or decision-blocked node ${id}`);
+    }
+    if (input.draft.revision === Number.MAX_SAFE_INTEGER)
+        throw new Error('Draft revision cannot exceed Number.MAX_SAFE_INTEGER');
+    const draft = structuredClone(input.draft);
+    draft.revision++;
+    draft.approvals.push({
+        id: randomUUID(),
+        revision: draft.revision,
+        nodeIds: [...input.nodeIds],
+        invalidatedNodeIds: [],
+    });
+    validateWorkflowDraft({ draft, context: input.context });
+    return draft;
+}

package/dist/draft/changes/apply-draft-change-set.d.ts

@@ -0,0 +1,3 @@
+import type { ApplyDraftChangeSetInput, ApplyDraftChangeSetResult } from '../../types/workflow-draft-changes.js';
+/** Commit one validated candidate; any error leaves the source draft unchanged. */
+export declare function applyDraftChangeSet(input: ApplyDraftChangeSetInput): ApplyDraftChangeSetResult;

package/dist/draft/changes/apply-draft-change-set.js

@@ -0,0 +1,75 @@
+import { draftChangeSetSchema } from '../../schemas/draft-change-set-schema.js';
+import { validateWorkflowDraft } from '../validate-workflow-draft.js';
+import { applyDraftChange } from './apply-draft-change.js';
+import { analyzeDraftChangeImpact } from '../impact/analyze-draft-change-impact.js';
+import { isDeepStrictEqual } from 'node:util';
+import { appendWorkflowDraftRequirementHistory } from '../requirements/history/append-workflow-draft-requirement-history.js';
+/** Commit one validated candidate; any error leaves the source draft unchanged. */
+export function applyDraftChangeSet(input) {
+    validateWorkflowDraft(input);
+    const changeSet = draftChangeSetSchema.parse(input.changeSet);
+    if (changeSet.baseRevision !== input.draft.revision)
+        throw new Error(`Stale draft revision: expected ${input.draft.revision}, received ${changeSet.baseRevision}`);
+    if (input.draft.revision === Number.MAX_SAFE_INTEGER)
+        throw new Error('Draft revision cannot exceed Number.MAX_SAFE_INTEGER');
+    const content = structuredClone({
+        id: input.draft.id,
+        requirements: input.draft.requirements,
+        apiCalls: input.draft.apiCalls,
+        nativeNodes: input.draft.nativeNodes,
+        ...(input.draft.gapNodes === undefined
+            ? {}
+            : { gapNodes: input.draft.gapNodes }),
+        edges: input.draft.edges,
+    });
+    const requirementHistory = structuredClone(input.draft.requirementHistory);
+    for (const change of changeSet.changes) {
+        if (change.kind === 'set-requirement' ||
+            change.kind === 'remove-requirement') {
+            const requirementId = change.kind === 'set-requirement'
+                ? change.requirement.id
+                : change.requirementId;
+            const before = content.requirements.find((item) => item.id === requirementId);
+            applyDraftChange(content, change);
+            const after = content.requirements.find((item) => item.id === requirementId);
+            if (!isDeepStrictEqual(before, after))
+                requirementHistory.push(appendWorkflowDraftRequirementHistory({
+                    draftId: input.draft.id,
+                    revision: input.draft.revision + 1,
+                    history: requirementHistory,
+                    before,
+                    after,
+                    sourceMessageIds: change.kind === 'set-requirement'
+                        ? change.requirement.sourceMessageIds
+                        : change.sourceMessageIds,
+                    messages: input.context.messages,
+                }));
+        }
+        else
+            applyDraftChange(content, change);
+    }
+    const impact = analyzeDraftChangeImpact({
+        before: input.draft,
+        after: content,
+        context: input.context,
+    });
+    if (!impact.affectedNodeIds.length && !impact.changedRequirementIds.length)
+        throw new Error('Draft change set does not change any requirement, node or connection');
+    const affected = new Set(impact.affectedNodeIds);
+    const draft = {
+        ...content,
+        revision: input.draft.revision + 1,
+        requirementHistory,
+        approvals: input.draft.approvals.map((approval) => ({
+            ...structuredClone(approval),
+            invalidatedNodeIds: [
+                ...new Set([
+                    ...approval.invalidatedNodeIds,
+                    ...approval.nodeIds.filter((id) => affected.has(id)),
+                ]),
+            ],
+        })),
+    };
+    validateWorkflowDraft({ draft, context: input.context });
+    return { draft, impact };
+}

package/dist/draft/changes/apply-draft-change.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftContent } from '../../types/workflow-draft.js';
+import type { WorkflowDraftChange } from '../../types/workflow-draft-changes.js';
+/** Mutate only an isolated candidate; callers validate the complete transaction. */
+export declare function applyDraftChange(content: WorkflowDraftContent, change: WorkflowDraftChange): void;

package/dist/draft/changes/apply-draft-change.js

@@ -0,0 +1,77 @@
+import { draftEdgeKey } from './draft-edge-key.js';
+/** Mutate only an isolated candidate; callers validate the complete transaction. */
+export function applyDraftChange(content, change) {
+    switch (change.kind) {
+        case 'add-capability-gap':
+            assertNewId(content, change.node.id);
+            if (content.gapNodes === undefined)
+                content.gapNodes = [];
+            content.gapNodes.push(structuredClone(change.node));
+            break;
+        case 'add-api-call':
+            assertNewId(content, change.call.id);
+            content.apiCalls.push(structuredClone(change.call));
+            break;
+        case 'update-api-call': {
+            const index = content.apiCalls.findIndex((call) => call.id === change.call.id);
+            if (index < 0)
+                throw new Error(`Cannot update unknown API call ${change.call.id}`);
+            content.apiCalls[index] = structuredClone(change.call);
+            break;
+        }
+        case 'add-native-node':
+            assertNewId(content, change.node.id);
+            content.nativeNodes.push(structuredClone(change.node));
+            break;
+        case 'update-native-node': {
+            const index = content.nativeNodes.findIndex((node) => node.id === change.node.id);
+            if (index < 0)
+                throw new Error(`Cannot update unknown native node ${change.node.id}`);
+            content.nativeNodes[index] = structuredClone(change.node);
+            break;
+        }
+        case 'remove-node': {
+            if (!content.apiCalls.some((call) => call.id === change.nodeId) &&
+                !content.nativeNodes.some((node) => node.id === change.nodeId) &&
+                !content.gapNodes?.some((node) => node.id === change.nodeId))
+                throw new Error(`Cannot remove unknown draft node ${change.nodeId}`);
+            content.apiCalls = content.apiCalls.filter((call) => call.id !== change.nodeId);
+            content.nativeNodes = content.nativeNodes.filter((node) => node.id !== change.nodeId);
+            if (content.gapNodes !== undefined)
+                content.gapNodes = content.gapNodes.filter((node) => node.id !== change.nodeId);
+            break;
+        }
+        case 'add-edge':
+            content.edges.push(structuredClone(change.edge));
+            break;
+        case 'remove-edge': {
+            const key = draftEdgeKey(change.edge);
+            const index = content.edges.findIndex((edge) => draftEdgeKey(edge) === key);
+            if (index < 0)
+                throw new Error('Cannot remove an undeclared draft edge');
+            content.edges.splice(index, 1);
+            break;
+        }
+        case 'set-requirement': {
+            const index = content.requirements.findIndex((item) => item.id === change.requirement.id);
+            if (index < 0)
+                content.requirements.push(structuredClone(change.requirement));
+            else
+                content.requirements[index] = structuredClone(change.requirement);
+            break;
+        }
+        case 'remove-requirement': {
+            const index = content.requirements.findIndex((item) => item.id === change.requirementId);
+            if (index < 0)
+                throw new Error(`Cannot remove unknown requirement ${change.requirementId}`);
+            content.requirements.splice(index, 1);
+            break;
+        }
+    }
+}
+function assertNewId(content, id) {
+    if (content.apiCalls.some((call) => call.id === id) ||
+        content.nativeNodes.some((node) => node.id === id) ||
+        content.gapNodes?.some((node) => node.id === id))
+        throw new Error(`Draft node ${id} already exists; use an explicit update`);
+}

package/dist/draft/changes/draft-edge-key.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowPlanEdge } from '../../types/workflow-plan.js';
+export declare function draftEdgeKey(edge: WorkflowPlanEdge): string;

package/dist/draft/changes/draft-edge-key.js

@@ -0,0 +1,3 @@
+export function draftEdgeKey(edge) {
+    return JSON.stringify([edge.from, edge.output, edge.to, edge.input]);
+}

package/dist/draft/contracts/resolve-workflow-draft-node-contracts.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftInput } from '../../types/workflow-draft.js';
+import type { WorkflowPlanNodeContract } from '../../types/workflow-plan.js';
+/** Actual implementation/OAS contracts for an already validated canonical draft. */
+export declare function resolveWorkflowDraftNodeContracts(input: WorkflowDraftInput): WorkflowPlanNodeContract[];