@openapi-flow/core 0.3.8 → 0.3.10

package/README.md

@@ -2,7 +2,7 @@
 
 Zod `^4.6.5` is a required peer, shared with the host rather than installed as a separately pinned runtime copy. Development tests use 4.6.5; the strict installed-consumer check also uses the host's 4.6.7. This preserves the public schema type boundary without casts or dependency overrides.
 
-Version **0.3.8**. Canonical draft, clarification and runtime-input APIs described below are included in this release source. Original-choice follow-ups derive their display and typed reply in Core. This patch aligns the three libraries for the new n8n response-object capability without adding a Core-specific composition path. Ajv 8.20.0 does not correctly validate a declared `properties.__proto__`; generated validation may reject valid data or omit that property's constraints. This previously accepted limitation remains unchanged, without renaming data or skipping its failing regression. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.8.md) for publication and host status.
+Version **0.3.9**. Canonical draft, clarification and runtime-input APIs described below are included in this release source. Requirement-edit schema descriptions distinguish explicit record editing from workflow behavior changes; runtime validation rules and typed human answers are unchanged. Original-choice follow-ups still derive their display and typed reply in Core. Ajv 8.20.0 does not correctly validate a declared `properties.__proto__`; generated validation may reject valid data or omit that property's constraints. This previously accepted limitation remains unchanged, without renaming data or skipping its failing regression. See the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.9.md) for publication and host status.
 
 Native and fixed-material connection planning accept the optional, existing `WorkflowEntryPointContract` as `entrypoint`. Core validates and snapshots this owner-provided start alongside the other inputs; it does not infer one when absent, add a selectable trigger or let model output modify it.
 

package/dist/openapi/common/create-oas-value-validation-cache.d.ts

@@ -0,0 +1,3 @@
+import type { OasValueValidationCache, OasValueValidationCacheOptions } from '../../types/oas-value-validation.js';
+/** Cache compilation only; every supplied value still runs the original validator. */
+export declare function createOasValueValidationCache(options: OasValueValidationCacheOptions): OasValueValidationCache;

package/dist/openapi/common/create-oas-value-validation-cache.js

@@ -0,0 +1,46 @@
+import { Buffer } from 'node:buffer';
+import { isDeepStrictEqual } from 'node:util';
+/** Cache compilation only; every supplied value still runs the original validator. */
+export function createOasValueValidationCache(options) {
+    for (const name of ['maximumEntries', 'maximumRetainedSchemaBytes'])
+        if (!Number.isSafeInteger(options[name]) || options[name] <= 0)
+            throw new Error(`OAS validator cache.${name} must be a positive safe integer`);
+    const { maximumEntries, maximumRetainedSchemaBytes } = options;
+    const entries = new Map();
+    let retainedSchemaBytes = 0;
+    return {
+        getOrCreate: (schema, dialect, compile) => {
+            const key = JSON.stringify([dialect, schema]);
+            const existing = entries.get(key);
+            // Serialization alone is not identity: undefined and non-JSON values can collide.
+            if (existing !== undefined &&
+                isDeepStrictEqual(existing.schema, schema)) {
+                entries.delete(key);
+                entries.set(key, existing);
+                return existing.validate;
+            }
+            // Neither returned schemas nor caller-owned objects can mutate the compiled resource.
+            const snapshot = structuredClone(schema);
+            const validate = compile(snapshot);
+            const bytes = Buffer.byteLength(key);
+            // Large schemas remain supported; only their optional retention is bounded.
+            if (bytes > maximumRetainedSchemaBytes)
+                return validate;
+            if (existing !== undefined) {
+                entries.delete(key);
+                retainedSchemaBytes -= existing.bytes;
+            }
+            while (entries.size >= maximumEntries ||
+                retainedSchemaBytes + bytes > maximumRetainedSchemaBytes) {
+                const oldest = entries.entries().next();
+                if (oldest.done)
+                    throw new Error('OAS validator cache retained-size invariant is invalid');
+                entries.delete(oldest.value[0]);
+                retainedSchemaBytes -= oldest.value[1].bytes;
+            }
+            entries.set(key, { schema: snapshot, validate, bytes });
+            retainedSchemaBytes += bytes;
+            return validate;
+        },
+    };
+}

package/dist/openapi/common/create-oas-value-validator.js

@@ -2,6 +2,12 @@ import { createHash } from 'node:crypto';
 import { createValidator } from '@scalar/json-schema-validator';
 import { normalizeOasValueSchema } from './normalize-oas-value-schema.js';
 import { isObject } from '../../utils/is-object.js';
+import { createOasValueValidationCache } from './create-oas-value-validation-cache.js';
+// Internal retention budgets, not limits on accepted OAS contracts or request values.
+const compiledValidators = createOasValueValidationCache({
+    maximumEntries: 64,
+    maximumRetainedSchemaBytes: 1024 * 1024,
+});
 export function createOasValueValidator(input, dialect, source) {
     if (typeof input !== 'boolean' && !isObject(input))
         throw new Error(`${source} must be an OAS schema object or boolean`);
@@ -24,7 +30,11 @@ export function createOasValueValidator(input, dialect, source) {
     };
     let validate;
     try {
-        validate = createValidator(schema);
+        validate = compiledValidators.getOrCreate(schema, dialect, (snapshot) => {
+            const compiled = createValidator(snapshot);
+            // Scalar parses string documents as YAML; encode actual string values first.
+            return (value) => compiled(typeof value === 'string' ? JSON.stringify(value) : value);
+        });
     }
     catch (error) {
         throw new Error(`${source} cannot compile its OAS value schema`, {
@@ -33,7 +43,6 @@ export function createOasValueValidator(input, dialect, source) {
     }
     return {
         schema,
-        // Scalar parses string documents as YAML; encode actual string values first.
-        validate: (value) => validate(typeof value === 'string' ? JSON.stringify(value) : value),
+        validate,
     };
 }

package/dist/schemas/create-workflow-draft-edit-proposal-schema.js

@@ -118,11 +118,15 @@ export function createWorkflowDraftEditProposalSchema(options, sources) {
         }));
     if (sources.requirementIds.length)
         for (const kind of ['revise-requirement', 'remove-requirement'])
-            decisions.push(z.strictObject({
+            decisions.push(z
+                .strictObject({
                 kind: z.literal(kind),
                 requirementId: z.enum(sources.requirementIds),
                 ...fields,
-            }));
+            })
+                .describe(kind === 'revise-requirement'
+                ? 'An explicit request to edit the existing requirement record itself: its stored statement, state or scope; not a request to change workflow behavior. API/native node, input, source and connection changes use their own decisions and do not require this bookkeeping edit. A later typed human answer supplies replacement fields.'
+                : 'An explicit request to withdraw this existing requirement record itself, not its API/native nodes or connections. Do not infer record withdrawal from workflow behavior changes.'));
     if (sources.removedRequirementIds.length)
         decisions.push(z.strictObject({
             kind: z.literal('restore-requirement'),

package/dist/types/oas-value-validation.d.ts

@@ -1,8 +1,21 @@
 import type { createValidator } from '@scalar/json-schema-validator';
 import type { JsonObject } from './openapi.js';
+import type { SchemaDialect } from './schema-dialect.js';
 export type OasValueSchema = JsonObject | boolean;
 export type OasValueValidation = ReturnType<typeof createValidator>;
 export interface OasValueValidator {
     schema: JsonObject;
     validate: OasValueValidation;
 }
+export interface OasValueValidationCacheOptions {
+    maximumEntries: number;
+    maximumRetainedSchemaBytes: number;
+}
+export interface OasValueValidationCacheEntry {
+    schema: JsonObject;
+    validate: OasValueValidation;
+    bytes: number;
+}
+export interface OasValueValidationCache {
+    getOrCreate(schema: JsonObject, dialect: SchemaDialect, compile: (schema: JsonObject) => OasValueValidation): OasValueValidation;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/core",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "license": "MIT",
   "description": "Engine-independent OpenAPI catalogs, operation contracts and typed request schemas",
   "keywords": [