@openapi-flow/core 0.1.0 → 0.3.0

package/dist/openapi/response/list-api-response-pointers.js

@@ -0,0 +1,30 @@
+import { isObject } from '../../utils/is-object.js';
+import { normalizeOasValueSchema } from '../common/normalize-oas-value-schema.js';
+import { listDeclaredSchemaPointers } from './list-declared-schema-pointers.js';
+/** Describe finite schema declarations, not guaranteed runtime fields or a whitelist. */
+export function listApiResponsePointers(operation) {
+    const catalogs = [];
+    for (const [responseKey, response] of Object.entries(operation.operation.responses ?? {})) {
+        if (!isObject(response) || !isObject(response.content))
+            continue;
+        for (const [mediaType, media] of Object.entries(response.content)) {
+            if (!isObject(media))
+                continue;
+            const schema = media.schema;
+            if (typeof schema !== 'boolean' && !isObject(schema))
+                continue;
+            const normalized = normalizeOasValueSchema(schema, operation.openapiVersion.startsWith('3.0.')
+                ? 'openapi-3.0'
+                : 'draft-2020-12');
+            const catalog = {
+                responseKey,
+                mediaType,
+                declaredPointers: [],
+                dynamicLocations: [],
+            };
+            listDeclaredSchemaPointers(normalized, catalog);
+            catalogs.push(catalog);
+        }
+    }
+    return catalogs;
+}

package/dist/openapi/response/list-declared-schema-pointers.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../../types/api-bindings.js';
+import type { ApiResponsePointerCatalog } from '../../types/api-response-pointers.js';
+/** Visit schema-valued declarations only; never invent a dictionary key or item index. */
+export declare function listDeclaredSchemaPointers(schema: BindingSchema, catalog: ApiResponsePointerCatalog): void;

package/dist/openapi/response/list-declared-schema-pointers.js

@@ -0,0 +1,91 @@
+import { isObject } from '../../utils/is-object.js';
+function pointerToken(value) {
+    return value.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+/** Visit schema-valued declarations only; never invent a dictionary key or item index. */
+export function listDeclaredSchemaPointers(schema, catalog) {
+    const active = new Set();
+    function visit(current, pointer, location) {
+        if (current === false)
+            return;
+        function boundary(kind, suffix = '', constraint) {
+            catalog.dynamicLocations.push({
+                pointer,
+                schemaLocation: location + suffix,
+                kind,
+                ...(constraint === undefined ? {} : { constraint }),
+            });
+        }
+        if (active.has(current)) {
+            boundary('recursive-schema');
+            return;
+        }
+        catalog.declaredPointers.push({
+            pointer,
+            schemaLocation: location,
+            ...(typeof current !== 'boolean' &&
+                (typeof current.type === 'string' ||
+                    (Array.isArray(current.type) &&
+                        current.type.every((value) => typeof value === 'string')))
+                ? { type: structuredClone(current.type) }
+                : {}),
+            ...(typeof current !== 'boolean' &&
+                typeof current.description === 'string'
+                ? { description: current.description }
+                : {}),
+        });
+        if (current === true) {
+            boundary('unconstrained');
+            return;
+        }
+        active.add(current);
+        try {
+            for (const keyword of ['$ref', '$dynamicRef'])
+                if (typeof current[keyword] === 'string')
+                    boundary('reference', '/' + keyword, current[keyword]);
+            if (isObject(current.properties))
+                for (const [name, child] of Object.entries(current.properties))
+                    if (typeof child === 'boolean' || isObject(child))
+                        visit(child, pointer + '/' + pointerToken(name), location + '/properties/' + pointerToken(name));
+            const types = Array.isArray(current.type) ? current.type : [current.type];
+            if ((current.type === undefined || types.includes('object')) &&
+                current.additionalProperties !== false)
+                boundary('additional-properties', current.additionalProperties === undefined
+                    ? ''
+                    : '/additionalProperties');
+            if (isObject(current.patternProperties))
+                for (const [pattern, child] of Object.entries(current.patternProperties))
+                    if (child !== false)
+                        boundary('pattern-properties', '/patternProperties/' + pointerToken(pattern), pattern);
+            if (Array.isArray(current.prefixItems))
+                current.prefixItems.forEach((child, index) => {
+                    if (typeof child === 'boolean' || isObject(child))
+                        visit(child, pointer + '/' + index, location + '/prefixItems/' + index);
+                });
+            if ((current.type === undefined || types.includes('array')) &&
+                current.items !== false)
+                boundary('array-items', current.items === undefined ? '' : '/items');
+            for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+                const branches = current[keyword];
+                if (Array.isArray(branches))
+                    branches.forEach((child, index) => {
+                        if (typeof child === 'boolean' || isObject(child))
+                            visit(child, pointer, location + '/' + keyword + '/' + index);
+                    });
+            }
+            for (const keyword of ['then', 'else']) {
+                const child = current[keyword];
+                if (typeof child === 'boolean' || isObject(child))
+                    visit(child, pointer, location + '/' + keyword);
+            }
+            if (isObject(current.dependentSchemas))
+                for (const [name, child] of Object.entries(current.dependentSchemas))
+                    if (typeof child === 'boolean' || isObject(child))
+                        visit(child, pointer, location + '/dependentSchemas/' + pointerToken(name));
+        }
+        finally {
+            active.delete(current);
+        }
+    }
+    visit(schema, '', '');
+}

package/dist/openapi/selection/evidence/create-api-selection-explanation.d.ts

@@ -0,0 +1,3 @@
+import type { ApiSelectionExplanation, CreateApiSelectionExplanationInput } from '../../../types/api-selection-evidence.js';
+/** Code attaches sources; the model supplies only its short user-facing reason. */
+export declare function createApiSelectionExplanation(input: CreateApiSelectionExplanationInput): ApiSelectionExplanation;

package/dist/openapi/selection/evidence/create-api-selection-explanation.js

@@ -0,0 +1,29 @@
+import { apiSelectionExplanationBasisSchema } from '../../../schemas/api-selection-evidence-schema.js';
+import { planningEvidenceTextSchema } from '../../../schemas/planning-evidence-schema.js';
+import { describeApiSelectionContext } from './describe-api-selection-context.js';
+import { apiOperationKeyEquals } from '../../catalog/api-operation-key-equals.js';
+/** Code attaches sources; the model supplies only its short user-facing reason. */
+export function createApiSelectionExplanation(input) {
+    const context = describeApiSelectionContext(input.context);
+    const reason = planningEvidenceTextSchema.parse(input.reason);
+    const basis = apiSelectionExplanationBasisSchema.parse(input.basis);
+    const candidates = basis.kind === 'catalog'
+        ? context.operations
+        : basis.operations.map((key, index) => {
+            if (basis.operations
+                .slice(0, index)
+                .some((prior) => apiOperationKeyEquals(prior, key)))
+                throw new Error('API selection explanation repeats a candidate');
+            const candidate = context.operations.find((item) => apiOperationKeyEquals(item.key, key));
+            if (!candidate)
+                throw new Error(`API selection explanation references an unavailable candidate: ${key.documentId}${key.operationRef}`);
+            return candidate;
+        });
+    return {
+        reason,
+        evidence: [
+            { kind: 'scenario', text: context.scenario },
+            { kind: 'discovery', candidates },
+        ],
+    };
+}

package/dist/openapi/selection/evidence/describe-api-selection-context.d.ts

@@ -0,0 +1,3 @@
+import type { ApiSelectionContext } from '../../../types/api-selection-evidence.js';
+/** Snapshot exactly the supplied discovery boundary before an asynchronous call. */
+export declare function describeApiSelectionContext(input: ApiSelectionContext): ApiSelectionContext;

package/dist/openapi/selection/evidence/describe-api-selection-context.js

@@ -0,0 +1,12 @@
+import { apiSelectionContextSchema } from '../../../schemas/api-selection-evidence-schema.js';
+import { apiOperationKeyEquals } from '../../catalog/api-operation-key-equals.js';
+/** Snapshot exactly the supplied discovery boundary before an asynchronous call. */
+export function describeApiSelectionContext(input) {
+    const context = apiSelectionContextSchema.parse(input);
+    for (const [index, candidate] of context.operations.entries())
+        if (context.operations
+            .slice(0, index)
+            .some((prior) => apiOperationKeyEquals(prior.key, candidate.key)))
+            throw new Error(`API selection context.operations[${index}].key duplicates a discovery candidate`);
+    return context;
+}

package/dist/openapi/selection/evidence/validate-api-selection-explanation.d.ts

@@ -0,0 +1,3 @@
+import type { ValidateApiSelectionExplanationInput } from '../../../types/api-selection-evidence.js';
+/** Exact provenance is checked; semantic entailment of the reason is not proved. */
+export declare function validateApiSelectionExplanation(input: ValidateApiSelectionExplanationInput): void;

package/dist/openapi/selection/evidence/validate-api-selection-explanation.js

@@ -0,0 +1,14 @@
+import { isDeepStrictEqual } from 'node:util';
+import { apiSelectionExplanationSchema } from '../../../schemas/api-selection-evidence-schema.js';
+import { createApiSelectionExplanation } from './create-api-selection-explanation.js';
+/** Exact provenance is checked; semantic entailment of the reason is not proved. */
+export function validateApiSelectionExplanation(input) {
+    const explanation = apiSelectionExplanationSchema.parse(input.explanation);
+    const expected = createApiSelectionExplanation({
+        context: input.context,
+        basis: input.basis,
+        reason: explanation.reason,
+    });
+    if (!isDeepStrictEqual(expected, explanation))
+        throw new Error('API selection explanation evidence differs from the supplied scenario or discovery basis');
+}

package/dist/openapi/selection/resolve-api-selection-answers.d.ts

@@ -0,0 +1,2 @@
+import type { ResolveApiSelectionAnswersInput, ApiSelectionAnalysis } from '../../types/api-clarification.js';
+export declare function resolveApiSelectionAnswers(input: ResolveApiSelectionAnswersInput): Promise<ApiSelectionAnalysis>;

package/dist/openapi/selection/resolve-api-selection-answers.js

@@ -0,0 +1,32 @@
+import { apiOperationAnswersSchema } from '../../schemas/api-operation-answers-schema.js';
+import { apiOperationKeyEquals } from '../catalog/api-operation-key-equals.js';
+import { resolveApiOperations } from '../resolve-api-operations.js';
+export async function resolveApiSelectionAnswers(input) {
+    const answers = apiOperationAnswersSchema.parse(input.answers);
+    await resolveApiOperations(input.catalog, [
+        ...input.analysis.selection.operations.map((item) => item.key),
+        ...input.analysis.questions.flatMap((question) => question.candidates.map((candidate) => candidate.key)),
+    ]);
+    const operations = structuredClone(input.analysis.selection.operations);
+    const answered = new Set();
+    for (const answer of answers) {
+        const question = input.analysis.questions.find((item) => item.id === answer.questionId);
+        if (!question || answered.has(answer.questionId))
+            throw new Error(`Unknown or duplicate operation question ${answer.questionId}`);
+        const candidate = question.candidates.find((item) => apiOperationKeyEquals(item.key, answer.operation));
+        if (!candidate)
+            throw new Error(`Operation answer ${answer.questionId} does not match a current offered candidate`);
+        operations.push({
+            key: structuredClone(candidate.key),
+            purpose: question.purpose,
+        });
+        answered.add(question.id);
+    }
+    return {
+        selection: {
+            operations,
+            gaps: structuredClone(input.analysis.selection.gaps),
+        },
+        questions: input.analysis.questions.filter((question) => !answered.has(question.id)),
+    };
+}

package/dist/planning/evidence/describe-workflow-planning-context.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowPlanningContext, WorkflowPlanningContextDescription } from '../../types/planning-evidence.js';
+/** Source declarations, never placeholders or fabricated native parameters. */
+export declare function describeWorkflowPlanningContext(input: WorkflowPlanningContext): WorkflowPlanningContextDescription;

package/dist/planning/evidence/describe-workflow-planning-context.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { apiOperationKeySchema } from '../../schemas/api-operation-key-schema.js';
+import { workflowEntryPointContractSchema } from '../../schemas/planning-evidence-schema.js';
+import { describeWorkflowDraftClarification } from '../../requirements/clarification/describe-workflow-draft-clarification.js';
+import { nativeMaterialRequirementsSchema } from '../../schemas/native-material-requirements-schema.js';
+import { resolveWorkflowPlanningMessages } from './resolve-workflow-planning-messages.js';
+/** Source declarations, never placeholders or fabricated native parameters. */
+export function describeWorkflowPlanningContext(input) {
+    const messages = resolveWorkflowPlanningMessages(input);
+    const operations = input.operations === undefined ? [] : input.operations;
+    const entrypoint = workflowEntryPointContractSchema
+        .optional()
+        .safeParse(input.entrypoint);
+    if (!entrypoint.success)
+        throw new Error('planning context.entrypoint is invalid', {
+            cause: entrypoint.error,
+        });
+    const capabilities = input.capabilities === undefined ? [] : input.capabilities;
+    if (!Array.isArray(operations) || !Array.isArray(capabilities))
+        throw new Error('planning context.operations and capabilities must be arrays when supplied');
+    const keys = operations.map((operation, index) => {
+        const key = apiOperationKeySchema.safeParse(operation?.key);
+        if (!key.success)
+            throw new Error(`planning context.operations[${index}].key is invalid`, {
+                cause: key.error,
+            });
+        return JSON.stringify(key.data);
+    });
+    if (new Set(keys).size !== keys.length)
+        throw new Error('planning context.operations requires distinct operation keys and snapshots');
+    if (capabilities.some((capability) => !capability ||
+        typeof capability.name !== 'string' ||
+        !capability.name.trim() ||
+        typeof capability.description !== 'string' ||
+        !capability.description.trim()) ||
+        new Set(capabilities.map((capability) => capability.name)).size !==
+            capabilities.length)
+        throw new Error('planning context.capabilities requires distinct non-empty names and descriptions');
+    const clarification = describeWorkflowDraftClarification({
+        ...input,
+        messages,
+    });
+    return {
+        messages,
+        ...(clarification === undefined ? {} : { clarification }),
+        ...(entrypoint.data === undefined ? {} : { entrypoint: entrypoint.data }),
+        operations: structuredClone(operations),
+        capabilities: capabilities.map((capability) => {
+            try {
+                return {
+                    name: capability.name,
+                    description: capability.description,
+                    ...(capability.materialRequirements === undefined
+                        ? {}
+                        : {
+                            materialRequirements: nativeMaterialRequirementsSchema.parse(capability.materialRequirements),
+                        }),
+                    ...(capability.supportsRuntimeParameters === true
+                        ? { supportsRuntimeParameters: true }
+                        : {}),
+                    parametersSchema: z.toJSONSchema(capability.parametersSchema, {
+                        io: 'input',
+                    }),
+                };
+            }
+            catch (error) {
+                throw new Error(`Native capability ${capability.name} cannot describe its input contract`, { cause: error });
+            }
+        }),
+    };
+}

package/dist/planning/evidence/resolve-workflow-planning-messages.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowPlanningContext } from '../../types/planning-evidence.js';
+import type { WorkflowSourceMessage } from '../../types/workflow-draft.js';
+/** Audit messages remain declared; only explicitly active IDs enter model/evidence payloads. */
+export declare function resolveWorkflowPlanningMessages(context: WorkflowPlanningContext): WorkflowSourceMessage[];

package/dist/planning/evidence/resolve-workflow-planning-messages.js

@@ -0,0 +1,24 @@
+import { workflowPlanningMessagesSchema, workflowSourceMessagesSchema, } from '../../schemas/planning-evidence-schema.js';
+import { workflowPlanningMessageIdsSchema } from '../../schemas/workflow-planning-message-ids-schema.js';
+/** Audit messages remain declared; only explicitly active IDs enter model/evidence payloads. */
+export function resolveWorkflowPlanningMessages(context) {
+    const parsed = workflowSourceMessagesSchema.safeParse(context?.messages);
+    if (!parsed.success)
+        throw new Error('planning context.messages requires distinct non-empty IDs and string text', { cause: parsed.error });
+    if (context.planningMessageIds === undefined) {
+        const active = workflowPlanningMessagesSchema.safeParse(parsed.data);
+        if (!active.success)
+            throw new Error('planning context.messages requires at least one message with non-empty text when planningMessageIds is omitted', { cause: active.error });
+        return active.data;
+    }
+    const ids = workflowPlanningMessageIdsSchema.parse(context.planningMessageIds);
+    return ids.map((id) => {
+        const message = parsed.data.find((entry) => entry.id === id);
+        if (!message)
+            throw new Error(`planningMessageIds references unknown message ${id}`);
+        const selected = workflowPlanningMessagesSchema.element.safeParse(message);
+        if (!selected.success)
+            throw new Error(`planning context.messages selected message ${id} requires non-empty text`, { cause: selected.error });
+        return selected.data;
+    });
+}

package/dist/planning/evidence/validate-workflow-planning-evidence.d.ts

@@ -0,0 +1,5 @@
+import type { ValidateWorkflowPlanningEvidenceInput, WorkflowPlanningContextDescription, WorkflowPlanningEvidence } from '../../types/planning-evidence.js';
+/** Existence and exact-source checks are not proof of semantic entailment. */
+export declare function validateWorkflowPlanningEvidence(input: ValidateWorkflowPlanningEvidenceInput): void;
+/** Reuse one validated source description across a whole clarification round. */
+export declare function validateDescribedWorkflowPlanningEvidence(context: WorkflowPlanningContextDescription, supplied: WorkflowPlanningEvidence[]): void;

package/dist/planning/evidence/validate-workflow-planning-evidence.js

@@ -0,0 +1,38 @@
+import { workflowPlanningEvidenceSchema } from '../../schemas/planning-evidence-schema.js';
+import { describeWorkflowPlanningContext } from './describe-workflow-planning-context.js';
+import { apiOperationKeyEquals } from '../../openapi/catalog/api-operation-key-equals.js';
+import { pointerValue } from '../../bindings/json-pointer.js';
+/** Existence and exact-source checks are not proof of semantic entailment. */
+export function validateWorkflowPlanningEvidence(input) {
+    const context = describeWorkflowPlanningContext(input.context);
+    validateDescribedWorkflowPlanningEvidence(context, input.evidence);
+}
+/** Reuse one validated source description across a whole clarification round. */
+export function validateDescribedWorkflowPlanningEvidence(context, supplied) {
+    const evidence = workflowPlanningEvidenceSchema
+        .array()
+        .min(1)
+        .parse(supplied);
+    if (new Set(evidence.map((item) => JSON.stringify(item))).size !==
+        evidence.length)
+        throw new Error('Planning evidence must not repeat an identical source');
+    for (const item of evidence) {
+        if (item.kind === 'message') {
+            const message = context.messages.find((message) => message.id === item.messageId);
+            if (!message || !message.text.includes(item.quote))
+                throw new Error(`Planning evidence references an unknown message or fabricated quote: ${item.messageId}`);
+        }
+        else if (item.kind === 'oas') {
+            const operation = context.operations.find((operation) => apiOperationKeyEquals(operation.key, item.operation));
+            if (!operation ||
+                pointerValue(operation.operation, item.pointer) === undefined)
+                throw new Error(`Planning evidence references a stale operation or undeclared OAS pointer: ${item.operation.documentId}${item.pointer}`);
+        }
+        else if (item.kind === 'native') {
+            if (!context.capabilities.some((capability) => capability.name === item.capability))
+                throw new Error(`Planning evidence references an unavailable native capability: ${item.capability}`);
+        }
+        else if (context.entrypoint?.kind !== item.entrypoint)
+            throw new Error(`Planning evidence references an unavailable entrypoint: ${item.entrypoint}`);
+    }
+}

package/dist/planning/evidence/workflow-planning-context-fingerprint.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowPlanningContext, WorkflowPlanningContextDescription } from '../../types/planning-evidence.js';
+export declare function workflowPlanningContextFingerprint(context: WorkflowPlanningContext): string;
+export declare function workflowPlanningContextFingerprintFromDescription(described: WorkflowPlanningContextDescription): string;

package/dist/planning/evidence/workflow-planning-context-fingerprint.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+import { describeWorkflowPlanningContext } from './describe-workflow-planning-context.js';
+export function workflowPlanningContextFingerprint(context) {
+    const described = describeWorkflowPlanningContext(context);
+    return workflowPlanningContextFingerprintFromDescription(described);
+}
+export function workflowPlanningContextFingerprintFromDescription(described) {
+    return createHash('sha256').update(JSON.stringify(described)).digest('hex');
+}