@openapi-flow/core 0.1.0 → 0.3.0

package/dist/schemas/native-producer-dependencies-schema.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/** Code supplies identities; model output contains only exact producer choices and optional reasons. */
+export function createNativeProducerDependenciesSchema(input) {
+    return z.strictObject({
+        sourcesByNodeId: z.strictObject(Object.fromEntries(input.targets.map((target) => [
+            target.nodeId,
+            z
+                .strictObject({
+                sourceNodeIds: (target.sourceNodeIds.length
+                    ? z.array(z.enum(target.sourceNodeIds))
+                    : z.array(z.string()).max(0))
+                    .refine((sources) => new Set(sources).size === sources.length, 'Native producer IDs must be distinct')
+                    .describe('Exact producer IDs referenced by this instance configuration. Empty means independent. Not execution edges or scheduling preferences. Future roles do not yet have output schemas.'),
+                ...(input.includeExplanations && target.sourceNodeIds.length
+                    ? {
+                        reason: z
+                            .string()
+                            .min(1)
+                            .describe('Short reason grounded in the supplied request and original role/source contracts.'),
+                    }
+                    : {}),
+            })
+                .describe(target.description),
+        ]))),
+    });
+}

package/dist/schemas/native-reference-binding-schema.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const nativeReferenceBindingSchema: z.ZodObject<{
+    nodeIdPointer: z.ZodString;
+    valuePointer: z.ZodOptional<z.ZodString>;
+    reference: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        source: z.ZodLiteral<"response">;
+        nodeId: z.ZodString;
+        pointer: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        source: z.ZodLiteral<"node-output">;
+        nodeId: z.ZodString;
+        pointer: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        source: z.ZodLiteral<"exclusive-output">;
+        nodeId: z.ZodString;
+    }, z.core.$strict>], "source">;
+}, z.core.$strict>;

package/dist/schemas/native-reference-binding-schema.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export const nativeReferenceBindingSchema = z.strictObject({
+    nodeIdPointer: z.string().min(1),
+    valuePointer: z.string().min(1).optional(),
+    reference: z.discriminatedUnion('source', [
+        z.strictObject({
+            source: z.literal('response'),
+            nodeId: z.string().min(1),
+            pointer: z.string(),
+        }),
+        z.strictObject({
+            source: z.literal('node-output'),
+            nodeId: z.string().min(1),
+            pointer: z.string(),
+        }),
+        z.strictObject({
+            source: z.literal('exclusive-output'),
+            nodeId: z.string().min(1),
+        }),
+    ]),
+});

package/dist/schemas/native-runtime-input-slot-schema.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export declare const nativeParameterValuesSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+export declare const nativeRuntimeParametersSchema: z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+    pointers: z.ZodArray<z.ZodString>;
+}, z.core.$strict>]>;
+export declare const nativeRuntimeInputSlotSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"native-parameters-input">;
+    state: z.ZodLiteral<"deferred">;
+    id: z.ZodString;
+    nodeId: z.ZodString;
+    capability: z.ZodString;
+    targetPointer: z.ZodString;
+    schema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodJSONSchema>]>;
+    description: z.ZodString;
+}, z.core.$strict>;

package/dist/schemas/native-runtime-input-slot-schema.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const nativeParameterValuesSchema = z.record(z.string(), z.json());
+export const nativeRuntimeParametersSchema = z.union([
+    z.literal(true),
+    z.strictObject({ pointers: z.array(z.string().min(1)).min(1) }),
+]);
+export const nativeRuntimeInputSlotSchema = z.strictObject({
+    kind: z.literal('native-parameters-input'),
+    state: z.literal('deferred'),
+    id: z.string().min(1),
+    nodeId: z.string().min(1),
+    capability: z.string().min(1),
+    targetPointer: z.string(),
+    schema: z.union([z.boolean(), z.record(z.string(), z.json())]),
+    description: z.string().min(1),
+});

package/dist/schemas/operation-plan-schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { Operation } from '../types/request.js';
+export declare function optionalRequestProperties(schema: unknown): unknown;
+export declare function createOperationPlanSchema(operation: Operation, openapiVersion: string, requestMediaType?: string): z.ZodObject<{
+    inputs: z.ZodObject<{
+        body?: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | undefined;
+    }, z.core.$strict>;
+}, z.core.$strict>;

package/dist/schemas/operation-plan-schema.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { isObject } from '../utils/is-object.js';
+import { createOasValueSchema } from './create-oas-value-schema.js';
+function parameterGroup(parameters, location, dialect) {
+    const fields = parameters
+        .filter((parameter) => parameter.in === location)
+        .map((parameter) => [
+        parameter.name,
+        createOasValueSchema(optionalRequestProperties(parameter.schema), dialect, `${location}.${parameter.name}`)
+            .describe(`Value explicitly stated for ${location} parameter ${parameter.name}`)
+            .optional(),
+    ]);
+    if (fields.length === 0)
+        return undefined;
+    return z.object(Object.fromEntries(fields)).strict().optional();
+}
+// The model may omit values absent from the scenario. The compiler still checks
+// the unchanged OAS schema and reports missing required request values.
+export function optionalRequestProperties(schema) {
+    if (!isObject(schema))
+        return schema;
+    const result = { ...schema };
+    delete result.required;
+    delete result.default;
+    for (const key of [
+        'properties',
+        'patternProperties',
+        '$defs',
+        'definitions',
+        'dependentSchemas',
+    ]) {
+        if (!isObject(result[key]))
+            continue;
+        result[key] = Object.fromEntries(Object.entries(result[key]).map(([name, value]) => [
+            name,
+            optionalRequestProperties(value),
+        ]));
+    }
+    for (const key of [
+        'items',
+        'additionalProperties',
+        'then',
+        'else',
+        'contains',
+        'unevaluatedProperties',
+        'propertyNames',
+    ]) {
+        if (result[key] !== undefined)
+            result[key] = optionalRequestProperties(result[key]);
+    }
+    // Predicates are not produced partial request values. Removing a required
+    // assertion from a negated predicate strengthens `not` and can reject a
+    // valid incomplete object; changing `if` can select a different branch.
+    // Keep both predicates unchanged. Complete values still use the original OAS.
+    for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+        if (Array.isArray(result[key]))
+            result[key] = result[key].map(optionalRequestProperties);
+    }
+    return result;
+}
+function requestBodySchema(operation, dialect, requestMediaType) {
+    if (!operation.body)
+        return undefined;
+    const mediaTypes = Object.entries(operation.body.mediaTypes).filter(([mediaType]) => requestMediaType === undefined || mediaType === requestMediaType);
+    if (requestMediaType !== undefined && mediaTypes.length === 0)
+        throw new Error(`operationRef ${operation.operationRef}.requestBody has no media type ${requestMediaType}`);
+    if (mediaTypes.length === 0)
+        throw new Error(`operationRef ${operation.operationRef}.requestBody.content has no media types`);
+    const schemas = mediaTypes.map(([mediaType, media]) => media.schema === undefined
+        ? z.json()
+        : createOasValueSchema(optionalRequestProperties(media.schema), dialect, `operationRef ${operation.operationRef}.requestBody.${mediaType}.schema`));
+    const body = schemas
+        .slice(1)
+        .reduce((combined, schema) => z.union([combined, schema]), schemas[0]);
+    return body
+        .describe('Request body values explicitly stated in the scenario')
+        .optional();
+}
+export function createOperationPlanSchema(operation, openapiVersion, requestMediaType) {
+    let dialect;
+    if (openapiVersion.startsWith('3.0.'))
+        dialect = 'openapi-3.0';
+    else if (openapiVersion.startsWith('3.1.') ||
+        openapiVersion.startsWith('3.2.'))
+        dialect = 'draft-2020-12';
+    else
+        throw new Error(`spec.openapi is not a supported OAS version: ${openapiVersion}`);
+    const groups = Object.fromEntries(['path', 'query', 'header', 'cookie']
+        .map((location) => [
+        location,
+        parameterGroup(operation.parameters, location, dialect),
+    ])
+        .filter(([, schema]) => schema !== undefined));
+    const body = requestBodySchema(operation, dialect, requestMediaType);
+    return z
+        .object({
+        inputs: z.object({ ...groups, ...(body ? { body } : {}) }).strict(),
+    })
+        .strict()
+        .describe('Only request values explicitly stated in the scenario');
+}

package/dist/schemas/planning-evidence-schema.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/** Independently annotated fields share validation, not an inherited metadata/reference identity. */
+export declare function createPlanningEvidenceTextSchema(): z.ZodString;
+export declare const planningEvidenceTextSchema: z.ZodString;
+export declare const workflowSourceMessagesSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>>;
+export declare const workflowPlanningMessagesSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>>;
+export declare const workflowMessageEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"message">;
+    messageId: z.ZodString;
+    quote: z.ZodString;
+}, z.core.$strict>;
+export declare const workflowEntryPointContractSchema: z.ZodObject<{
+    kind: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>;
+export declare const workflowPlanningEvidenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"message">;
+    messageId: z.ZodString;
+    quote: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"oas">;
+    operation: z.ZodObject<{
+        documentId: z.ZodString;
+        snapshotId: z.ZodString;
+        operationRef: z.ZodString;
+    }, z.core.$strict>;
+    pointer: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"native">;
+    capability: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"entrypoint">;
+    entrypoint: z.ZodString;
+}, z.core.$strict>], "kind">;

package/dist/schemas/planning-evidence-schema.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { apiOperationKeySchema } from './api-operation-key-schema.js';
+/** Independently annotated fields share validation, not an inherited metadata/reference identity. */
+export function createPlanningEvidenceTextSchema() {
+    return z.string().refine((value) => value.trim().length > 0);
+}
+export const planningEvidenceTextSchema = createPlanningEvidenceTextSchema();
+export const workflowSourceMessagesSchema = z
+    .array(z.strictObject({
+    id: planningEvidenceTextSchema,
+    text: z.string(),
+}))
+    .refine((messages) => new Set(messages.map((message) => message.id)).size === messages.length);
+export const workflowPlanningMessagesSchema = z
+    .array(z.strictObject({
+    id: planningEvidenceTextSchema,
+    text: planningEvidenceTextSchema,
+}))
+    .min(1)
+    .refine((messages) => new Set(messages.map((message) => message.id)).size === messages.length);
+export const workflowMessageEvidenceSchema = z.strictObject({
+    kind: z.literal('message'),
+    messageId: planningEvidenceTextSchema,
+    quote: planningEvidenceTextSchema,
+});
+export const workflowEntryPointContractSchema = z.strictObject({
+    kind: planningEvidenceTextSchema,
+    description: planningEvidenceTextSchema,
+});
+export const workflowPlanningEvidenceSchema = z.discriminatedUnion('kind', [
+    workflowMessageEvidenceSchema,
+    z.strictObject({
+        kind: z.literal('oas'),
+        operation: apiOperationKeySchema,
+        pointer: z.string(),
+    }),
+    z.strictObject({
+        kind: z.literal('native'),
+        capability: planningEvidenceTextSchema,
+    }),
+    z.strictObject({
+        kind: z.literal('entrypoint'),
+        entrypoint: planningEvidenceTextSchema,
+    }),
+]);

package/dist/schemas/project-literal-array-schema.d.ts

@@ -0,0 +1,4 @@
+import type { LiteralInputProjection } from '../types/api-argument-generation.js';
+import type { JsonObject } from '../types/openapi.js';
+/** Project specific array positions, never every item because one index is bound. */
+export declare function projectLiteralArraySchema(schema: JsonObject, targets: string[][], source: string): LiteralInputProjection;

package/dist/schemas/project-literal-array-schema.js

@@ -0,0 +1,61 @@
+import { isObject } from '../utils/is-object.js';
+import { projectLiteralInputSchema } from './project-literal-input-schema.js';
+/** Project specific array positions, never every item because one index is bound. */
+export function projectLiteralArraySchema(schema, targets, source) {
+    const prefix = [];
+    const original = Array.isArray(schema.prefixItems)
+        ? schema.prefixItems
+        : Array.isArray(schema.items)
+            ? schema.items
+            : [];
+    for (const child of original) {
+        if (typeof child !== 'boolean' && !isObject(child))
+            throw new Error(`${source}.prefixItems must contain schemas`);
+        prefix.push(child);
+    }
+    const rawRest = Array.isArray(schema.items)
+        ? schema.additionalItems
+        : schema.items;
+    if (rawRest !== undefined &&
+        typeof rawRest !== 'boolean' &&
+        !isObject(rawRest))
+        throw new Error(`${source}.items must be a schema`);
+    const rest = rawRest === undefined ? true : rawRest;
+    const availability = prefix.map((child) => child !== false);
+    let limit = typeof schema.maxItems === 'number' ? schema.maxItems : Infinity;
+    let ownedLimit = Infinity;
+    for (const token of new Set(targets.map(([index]) => index))) {
+        if (!/^(0|[1-9][0-9]*)$/.test(token) ||
+            !Number.isSafeInteger(Number(token)))
+            throw new Error(`${source}/${token}: binding requires an array index`);
+        const index = Number(token);
+        while (prefix.length <= index) {
+            prefix.push(structuredClone(rest));
+            availability.push(rest !== false);
+        }
+        const projected = projectLiteralInputSchema(prefix[index], targets.filter(([key]) => key === token).map((tokens) => tokens.slice(1)), `${source}/${token}`);
+        prefix[index] = projected.schema;
+        availability[index] = projected.hasLiteralValues;
+        // JSON literals cannot leave a hole for a fully bound element.
+        if (projected.schema === false) {
+            limit = Math.min(limit, index);
+            ownedLimit = Math.min(ownedLimit, index);
+        }
+    }
+    schema.prefixItems = prefix;
+    schema.items = rest;
+    delete schema.additionalItems;
+    if (Number.isFinite(limit))
+        schema.maxItems = limit;
+    if (Number.isFinite(ownedLimit))
+        // Runtime assignment cannot invent the literal prefix before its first owned index.
+        schema.minItems = ownedLimit;
+    else if (typeof schema.minItems === 'number' &&
+        targets.some(([index]) => Number(index) + 1 >= Number(schema.minItems)))
+        schema.minItems = 0;
+    return {
+        schema,
+        hasLiteralValues: availability.slice(0, limit).some(Boolean) ||
+            (rest !== false && prefix.length < limit),
+    };
+}

package/dist/schemas/project-literal-input-schema.d.ts

@@ -0,0 +1,3 @@
+import type { LiteralInputProjection, LiteralInputSchema } from '../types/api-argument-generation.js';
+/** Bound fields do not belong in the model's literal-value output schema. */
+export declare function projectLiteralInputSchema(input: LiteralInputSchema, targets: string[][], source: string): LiteralInputProjection;

package/dist/schemas/project-literal-input-schema.js

@@ -0,0 +1,135 @@
+import { isObject } from '../utils/is-object.js';
+import { projectLiteralArraySchema } from './project-literal-array-schema.js';
+/** Bound fields do not belong in the model's literal-value output schema. */
+export function projectLiteralInputSchema(input, targets, source) {
+    if (targets.some((tokens) => tokens.length === 0))
+        return { schema: false, hasLiteralValues: false };
+    if (!targets.length || input === false)
+        return {
+            schema: structuredClone(input),
+            hasLiteralValues: input !== false,
+        };
+    if (input === true)
+        return projectLiteralInputSchema({}, targets, source);
+    const schema = structuredClone(input);
+    if (Array.isArray(schema.type)) {
+        const variants = schema.type.map((type) => projectLiteralInputSchema({ ...schema, type }, targets, source));
+        return {
+            schema: { anyOf: variants.map((variant) => variant.schema) },
+            hasLiteralValues: variants.some((variant) => variant.hasLiteralValues),
+        };
+    }
+    if (typeof schema.type === 'string' &&
+        !['object', 'array'].includes(schema.type))
+        return { schema: false, hasLiteralValues: false };
+    const combinations = new Map();
+    const conjuncts = [];
+    for (const key of ['allOf', 'anyOf', 'oneOf']) {
+        if (!Array.isArray(schema[key]))
+            continue;
+        const projected = schema[key].map((child) => {
+            if (typeof child !== 'boolean' && !isObject(child))
+                throw new Error(`${source}.${key} must contain schemas`);
+            return projectLiteralInputSchema(child, targets, source);
+        });
+        const alternatives = projected.map((child) => child.schema);
+        delete schema[key];
+        // Bound discriminators distinguish completed values, not partial literals.
+        // Preserve simultaneous composition constraints in one conjunction; exact-one
+        // validation belongs to the untouched OAS after materialization.
+        if (key === 'allOf')
+            conjuncts.push(...alternatives);
+        else
+            conjuncts.push({ anyOf: alternatives });
+        combinations.set(key, projected);
+    }
+    if (combinations.size)
+        schema.allOf = conjuncts;
+    const combinationAllowsLiterals = [...combinations].every(([kind, children]) => kind === 'allOf'
+        ? children.every((child) => child.hasLiteralValues)
+        : children.some((child) => child.hasLiteralValues));
+    if (schema.type === 'array')
+        return projectLiteralArraySchema(schema, targets, source);
+    if (schema.type === 'object' ||
+        isObject(schema.properties) ||
+        isObject(schema.patternProperties) ||
+        schema.additionalProperties !== undefined) {
+        const properties = Object.create(null);
+        const availability = new Map();
+        for (const [name, child] of Object.entries(isObject(schema.properties) ? schema.properties : {})) {
+            if (typeof child !== 'boolean' && !isObject(child))
+                throw new Error(`${source}.properties.${name} must be a schema`);
+            properties[name] = child;
+            availability.set(name, child !== false);
+        }
+        const names = new Set(targets.map(([name]) => name));
+        for (const name of names) {
+            const children = targets
+                .filter(([token]) => token === name)
+                .map((tokens) => tokens.slice(1));
+            let child;
+            if (Object.hasOwn(properties, name))
+                child = properties[name];
+            else {
+                const patterns = Object.entries(isObject(schema.patternProperties) ? schema.patternProperties : {})
+                    .filter(([pattern]) => new RegExp(pattern).test(name))
+                    .map(([, value]) => value);
+                if (patterns.length)
+                    child = { allOf: patterns };
+                else {
+                    // OAS/JSON Schema permits additional properties unless explicitly closed.
+                    const additional = schema.additionalProperties;
+                    if (additional === false)
+                        return { schema: false, hasLiteralValues: false };
+                    if (additional !== undefined &&
+                        additional !== true &&
+                        !isObject(additional))
+                        throw new Error(`${source}.additionalProperties must be a schema`);
+                    child = additional === undefined ? true : additional;
+                }
+            }
+            const projected = projectLiteralInputSchema(child, children, `${source}/${name}`);
+            // A false property blocks re-entry through additionalProperties and patterns.
+            properties[name] = projected.schema;
+            availability.set(name, projected.hasLiteralValues);
+        }
+        schema.properties = properties;
+        // A required field supplied by another owner is not required in this partial value.
+        // Keep every unrelated required field; a partial native value must not hide it.
+        if (Array.isArray(schema.required))
+            schema.required = schema.required.filter((name) => typeof name !== 'string' ||
+                !names.has(name) ||
+                availability.get(name) !== false);
+        // Counts describe the completed request; preceding nodes contribute keys too.
+        if (typeof schema.minProperties === 'number')
+            schema.minProperties = Math.max(0, schema.minProperties - names.size);
+        if (typeof schema.maxProperties === 'number')
+            schema.maxProperties = Math.max(0, schema.maxProperties -
+                targets.filter((tokens) => tokens.length === 1).length);
+        const open = schema.additionalProperties !== false;
+        const patterns = isObject(schema.patternProperties)
+            ? Object.values(schema.patternProperties).some((child) => child !== false)
+            : false;
+        return {
+            schema,
+            hasLiteralValues: combinationAllowsLiterals &&
+                (open || patterns || [...availability.values()].some(Boolean)),
+        };
+    }
+    if (combinations.size)
+        return {
+            schema,
+            hasLiteralValues: combinationAllowsLiterals,
+        };
+    // An unconstrained OAS schema permits both containers. Keep every container
+    // compatible with the pointer instead of guessing whether numeric keys are arrays.
+    return projectLiteralInputSchema({
+        ...schema,
+        anyOf: [
+            { type: 'object' },
+            ...(targets.every(([token]) => /^(0|[1-9][0-9]*)$/.test(token))
+                ? [{ type: 'array' }]
+                : []),
+        ],
+    }, targets, source);
+}

package/dist/schemas/project-native-literal-parameters.d.ts

@@ -0,0 +1,4 @@
+import type { BindingSchema } from '../types/api-bindings.js';
+import type { LiteralInputProjection } from '../types/api-argument-generation.js';
+/** Expand only finite selected paths; unselected recursive contracts retain static refs. */
+export declare function projectNativeLiteralParameters(schema: BindingSchema, pointers: string[], source: string): LiteralInputProjection;