@knitli/openapi-mcp 1.3.0 → 1.4.0

package/dist/conformance/runtime-suite.js

@@ -111,6 +111,14 @@ export function runRuntimeConformanceSuite(factory, options) {
     useFault("catalog rejects duplicate operation transport rows", { fault: "duplicate-operation" }, async ({ store, fixture }) => {
         await assertPublicError(adapter, () => store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.operationRowAmbiguous);
     });
+    useFault("catalog rejects duplicate batched operation transport rows", { fault: "duplicate-operation" }, async ({ store, fixture }) => {
+        const getOperations = store.getOperations?.bind(store);
+        if (getOperations === undefined)
+            return;
+        await assertPublicError(adapter, () => getOperations(fixture.catalogId, fixture.releaseA, [
+            fixture.operationId,
+        ]), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.operationTransportTooManyRows);
+    });
     useFault("catalog rejects duplicate schema transport rows", { fault: "duplicate-schemas" }, async ({ store, fixture }) => {
         await assertPublicError(adapter, () => store.getSchemas(fixture.catalogId, fixture.releaseA, fixture.schemaIds), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.schemaTransportTooManyRows);
     });
@@ -128,6 +136,14 @@ export function runRuntimeConformanceSuite(factory, options) {
     useFault("catalog redacts operation driver failures", { fault: "driver-operation", injectedDriverError }, async ({ store, fixture }) => {
         await assertPublicError(adapter, () => store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.recordTransportUnavailable, injectedDriverError);
     });
+    useFault("catalog redacts batched operation driver failures", { fault: "driver-operation", injectedDriverError }, async ({ store, fixture }) => {
+        const getOperations = store.getOperations?.bind(store);
+        if (getOperations === undefined)
+            return;
+        await assertPublicError(adapter, () => getOperations(fixture.catalogId, fixture.releaseA, [
+            fixture.operationId,
+        ]), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.recordTransportUnavailable, injectedDriverError);
+    });
     useFault("catalog redacts schema driver failures", { fault: "driver-schemas", injectedDriverError }, async ({ store, fixture }) => {
         await assertPublicError(adapter, () => store.getSchemas(fixture.catalogId, fixture.releaseA, fixture.schemaIds), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.recordTransportUnavailable, injectedDriverError);
     });
@@ -137,6 +153,28 @@ export function runRuntimeConformanceSuite(factory, options) {
         adapter.equal(await store.getOperation(fixture.catalogId, "missing-release", fixture.operationId), null);
         adapter.equal(await store.getOperation(fixture.catalogId, fixture.releaseA, fixture.missingOperationId), null);
     });
+    use("catalog batched operations match single reads and omit absent IDs", async ({ store, fixture }) => {
+        const getOperations = store.getOperations?.bind(store);
+        if (getOperations === undefined)
+            return;
+        adapter.deepEqual(await getOperations(fixture.catalogId, fixture.releaseA, [
+            fixture.missingOperationId,
+            fixture.operationId,
+            fixture.operationId,
+        ]), [fixture.operationA]);
+        adapter.deepEqual(await getOperations(fixture.catalogId, fixture.releaseB, [
+            fixture.operationId,
+        ]), [fixture.operationB]);
+        adapter.deepEqual(await getOperations(fixture.catalogId, "missing-release", [
+            fixture.operationId,
+        ]), []);
+        adapter.deepEqual(await getOperations(fixture.catalogId, fixture.releaseA, []), []);
+        await assertPublicError(adapter, () => getOperations(fixture.catalogId, fixture.releaseA, [
+            "schema:conformance:not-an-operation",
+        ]), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.operationIdentityInvalid);
+        const sparse = new Array(1);
+        await assertPublicError(adapter, () => getOperations(fixture.catalogId, fixture.releaseA, sparse), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.operationRequestInvalid);
+    });
     use("catalog schemas are batched, unique, ordered, and empty-safe", async ({ store, fixture }) => {
         const firstSchemaId = fixture.schemaIds[0];
         if (firstSchemaId === undefined)

package/dist/runtime/runtime.js

@@ -27,6 +27,12 @@ function manifestKey(catalogId, releaseId) {
 }
 const maximumSearchReleases = 8;
 const maximumInventorySchemaBatch = 128;
+// Stores null record_json over maxRecordBytes, so one operation batch carries
+// at most 16 MiB of raw row text; rows are then verified one at a time, so
+// only one record's working copies are live at once. Sized for a Worker
+// isolate. Schema batches keep the maxSchemaClosureBytes-derived bound
+// because they serve closure resolution.
+const OPERATION_BATCH_BYTE_BUDGET = 16 * 1024 * 1024;
 // State churn may require reproof, but one search may spend no more than the
 // same eight-release compatibility envelope used for manifest authentication.
 const maximumCompleteReleaseProofs = maximumSearchReleases;
@@ -140,40 +146,86 @@ async function verifyCompleteRelease(store, authenticated, limits, searchBudget)
         }
         return bytes;
     };
-    const operationRoots = [];
-    for (const id of operationIds) {
-        chargeCompleteVerification(searchBudget, { work: 1, storeCalls: 1 });
-        const row = await store.getOperation(authenticated.manifest.catalogId, authenticated.manifest.releaseId, id);
-        if (row === null) {
-            throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "Release inventory operation is missing");
+    // Each response is bounded by its batch size times maxRecordBytes, and each
+    // request by the store's ID byte limit; one fixed JSON parameter keeps D1
+    // bindings flat.
+    const batchSizeFor = (byteBudget) => Math.max(1, Math.min(maximumInventorySchemaBatch, Math.floor(byteBudget / limits.maxRecordBytes)));
+    const operationBatchSize = batchSizeFor(OPERATION_BATCH_BYTE_BUDGET);
+    const schemaBatchSize = batchSizeFor(limits.maxSchemaClosureBytes);
+    const nextBatch = (ids, start, kind) => {
+        const batchSize = kind === "operation" ? operationBatchSize : schemaBatchSize;
+        const batch = [];
+        let requestBytes = 0;
+        for (let index = start; index < ids.length; index += 1) {
+            if (batch.length >= batchSize)
+                break;
+            const idBytes = encoder.encode(ids[index]).byteLength;
+            if (idBytes > limits.maxSchemaClosureBytes ||
+                (batch.length > 0 &&
+                    requestBytes + idBytes > limits.maxSchemaClosureBytes))
+                break;
+            batch.push(ids[index]);
+            requestBytes += idBytes;
         }
-        const operation = await verifyStoredRecord(authenticated, row, limits);
+        if (batch.length === 0) {
+            throw new OpenApiMcpError("RECORD_NOT_ADMITTED", `Release inventory ${kind} request exceeds its byte limit`);
+        }
+        return batch;
+    };
+    const operationRoots = [];
+    const admitOperation = (id, operation) => {
         if (!operation.id.startsWith("operation:") || operation.id !== id) {
             throw new OpenApiMcpError("RECORD_DIGEST_MISMATCH", "Release inventory operation identity does not match");
         }
         accountRecord(operation);
         operationRoots.push([...new Set(operation.schemaIds)].sort());
+    };
+    const missingOperation = () => new OpenApiMcpError("RECORD_NOT_ADMITTED", "Release inventory operation is missing");
+    if (store.getOperations === undefined) {
+        for (const id of operationIds) {
+            chargeCompleteVerification(searchBudget, { work: 1, storeCalls: 1 });
+            const row = await store.getOperation(authenticated.manifest.catalogId, authenticated.manifest.releaseId, id);
+            if (row === null)
+                throw missingOperation();
+            admitOperation(id, await verifyStoredRecord(authenticated, row, limits));
+        }
+    }
+    else {
+        let operationOffset = 0;
+        while (operationOffset < operationIds.length) {
+            const ids = nextBatch(operationIds, operationOffset, "operation");
+            operationOffset += ids.length;
+            chargeCompleteVerification(searchBudget, {
+                work: ids.length,
+                storeCalls: 1,
+            });
+            const result = await store.getOperations(authenticated.manifest.catalogId, authenticated.manifest.releaseId, ids);
+            const rows = snapshotRows(result, ids.length);
+            // Duplicate or unrequested rows are integrity failures, like an identity
+            // mismatch on the per-row path; absent rows are missing. Verify one row
+            // at a time: batching saves round-trips, not hashing.
+            const requested = new Set(ids);
+            const returned = new Map();
+            for (const row of rows) {
+                const record = await verifyStoredRecord(authenticated, row, limits);
+                if (!requested.has(record.id) || returned.has(record.id)) {
+                    throw new OpenApiMcpError("RECORD_DIGEST_MISMATCH", "Release inventory operation rows are ambiguous");
+                }
+                returned.set(record.id, record);
+            }
+            for (const id of ids) {
+                const operation = returned.get(id);
+                if (operation === undefined)
+                    throw missingOperation();
+                admitOperation(id, operation);
+            }
+        }
     }
-    const schemaBatchSize = Math.max(1, Math.min(maximumInventorySchemaBatch, Math.floor(limits.maxSchemaClosureBytes / limits.maxRecordBytes)));
     const schemas = new Map();
     let offset = 0;
     while (offset < schemaIds.length) {
-        const ids = [];
-        let requestBytes = 0;
-        while (offset < schemaIds.length && ids.length < schemaBatchSize) {
-            const id = schemaIds[offset];
-            const idBytes = encoder.encode(id).byteLength;
-            if (idBytes > limits.maxSchemaClosureBytes ||
-                (ids.length > 0 &&
-                    requestBytes + idBytes > limits.maxSchemaClosureBytes))
-                break;
-            ids.push(id);
-            requestBytes += idBytes;
-            offset += 1;
-        }
-        if (ids.length === 0) {
-            throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "Release inventory schema request exceeds its byte limit");
-        }
+        const ids = nextBatch(schemaIds, offset, "schema");
+        offset += ids.length;
         chargeCompleteVerification(searchBudget, {
             work: ids.length,
             storeCalls: 1,

package/dist/runtime/serialize.js

@@ -344,6 +344,13 @@ function validateSchema(schema, value, closure, depth, context) {
     if (schema === false || !isObject(schema))
         schemaFailure();
     for (const key of Object.keys(schema)) {
+        // OpenAPI Specification Extensions (`^x-`, OpenAPI 3.1 §4.9) are legal on a Schema Object and
+        // carry no validation semantics, so ignore the key and never walk its value -- Cloudflare's
+        // API document puts `x-auditable: true` on parameter schemas, and the compiler copies
+        // component schemas verbatim. Every other unknown keyword still fails: one with validation
+        // semantics (`pattern`, `contains`) must not be silently skipped.
+        if (key.startsWith("x-"))
+            continue;
         if (!supportedSchemaKeys.has(key))
             schemaFailure();
     }

package/dist/runtime/store.d.ts

@@ -28,6 +28,10 @@ export declare const CATALOG_STORE_PUBLIC_MESSAGES: Readonly<{
     recordJsonInvalid: "Stored record JSON is invalid";
     operationRowAmbiguous: "Stored operation row is ambiguous";
     operationIdentifierMismatch: "Stored operation identifier does not match request";
+    operationRequestLimitExceeded: "Operation request exceeds its limit";
+    operationRequestInvalid: "Operation request is invalid";
+    operationTransportTooManyRows: "Stored operation transport returned too many rows";
+    operationRowsInvalid: "Stored operation rows are invalid";
     schemaRequestLimitExceeded: "Schema request exceeds its limit";
     schemaRequestInvalid: "Schema request is invalid";
     schemaTransportTooManyRows: "Stored schema transport returned too many rows";
@@ -49,4 +53,4 @@ export interface D1CatalogDatabase {
     prepare(sql: string): D1CatalogPreparedStatement;
 }
 /** Construct the Worker-safe D1 implementation using only fixed SQL statements. */
-export declare function createD1CatalogStore(binding: D1CatalogDatabase, limits?: Partial<RuntimeLimits>): CatalogStore;
+export declare function createD1CatalogStore(binding: D1CatalogDatabase, limits?: Partial<RuntimeLimits>): Required<CatalogStore>;

package/dist/runtime/store.js

@@ -64,6 +64,24 @@ WHERE s.catalog_id = ? AND s.release_id = ?
   AND r.format IN (4, 5) AND r.contract = 1
 ORDER BY s.record_id COLLATE BINARY
 LIMIT ?;`;
+const GET_OPERATIONS_SQL = `WITH requested(record_id) AS (
+  SELECT DISTINCT value FROM json_each(?) WHERE typeof(value) = 'text'
+)
+SELECT
+       CASE WHEN typeof(o.record_id) = 'text' AND length(CAST(o.record_id AS BLOB)) <= ? THEN o.record_id ELSE NULL END AS record_id,
+       length(CAST(o.record_id AS BLOB)) AS record_id_bytes,
+       CASE WHEN typeof(o.logical_digest) = 'text' AND length(CAST(o.logical_digest AS BLOB)) <= ? THEN o.logical_digest ELSE NULL END AS logical_digest,
+       length(CAST(o.logical_digest AS BLOB)) AS logical_digest_bytes,
+       CASE WHEN typeof(o.record_json) = 'text' AND length(CAST(o.record_json AS BLOB)) <= ? THEN o.record_json ELSE NULL END AS record_json,
+       length(CAST(o.record_json AS BLOB)) AS record_json_bytes
+FROM requested
+JOIN operations AS o ON o.record_id = requested.record_id
+JOIN release_metadata AS r
+  ON r.catalog_id = o.catalog_id AND r.release_id = o.release_id
+WHERE o.catalog_id = ? AND o.release_id = ?
+  AND r.format IN (4, 5) AND r.contract = 1
+ORDER BY o.record_id COLLATE BINARY
+LIMIT ?;`;
 const digestPattern = /^[0-9a-f]{64}$/;
 const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const signaturePattern = /^[A-Za-z0-9_-]+$/;
@@ -104,6 +122,10 @@ export const CATALOG_STORE_PUBLIC_MESSAGES = Object.freeze({
     recordJsonInvalid: "Stored record JSON is invalid",
     operationRowAmbiguous: "Stored operation row is ambiguous",
     operationIdentifierMismatch: "Stored operation identifier does not match request",
+    operationRequestLimitExceeded: "Operation request exceeds its limit",
+    operationRequestInvalid: "Operation request is invalid",
+    operationTransportTooManyRows: "Stored operation transport returned too many rows",
+    operationRowsInvalid: "Stored operation rows are invalid",
     schemaRequestLimitExceeded: "Schema request exceeds its limit",
     schemaRequestInvalid: "Schema request is invalid",
     schemaTransportTooManyRows: "Stored schema transport returned too many rows",
@@ -400,6 +422,12 @@ function snapshotSearchQuery(value, limits) {
     }
 }
 function snapshotSchemaIds(value, limits) {
+    return snapshotRecordIds(value, limits, requestedSchemaId, CATALOG_STORE_PUBLIC_MESSAGES.schemaRequestLimitExceeded, CATALOG_STORE_PUBLIC_MESSAGES.schemaRequestInvalid);
+}
+function snapshotOperationIds(value, limits) {
+    return snapshotRecordIds(value, limits, requestedOperationId, CATALOG_STORE_PUBLIC_MESSAGES.operationRequestLimitExceeded, CATALOG_STORE_PUBLIC_MESSAGES.operationRequestInvalid);
+}
+function snapshotRecordIds(value, limits, parse, limitMessage, invalidMessage) {
     try {
         if (!Array.isArray(value) ||
             Object.getPrototypeOf(value) !== Array.prototype)
@@ -413,7 +441,7 @@ function snapshotSchemaIds(value, limits) {
             length.value < 0)
             throw new Error();
         if (length.value > limits.maxManifestRecords)
-            throw input(CATALOG_STORE_PUBLIC_MESSAGES.schemaRequestLimitExceeded);
+            throw input(limitMessage);
         const names = Object.getOwnPropertyNames(value);
         if (names.length !== length.value + 1 || !names.includes("length"))
             throw new Error();
@@ -423,10 +451,10 @@ function snapshotSchemaIds(value, limits) {
             const id = Object.getOwnPropertyDescriptor(value, String(index));
             if (!id?.enumerable || !("value" in id))
                 throw new Error();
-            const parsed = requestedSchemaId(id.value);
+            const parsed = parse(id.value);
             totalBytes += textEncoder.encode(parsed).byteLength;
             if (totalBytes > limits.maxSchemaClosureBytes)
-                throw input(CATALOG_STORE_PUBLIC_MESSAGES.schemaRequestLimitExceeded);
+                throw input(limitMessage);
             ids.push(parsed);
         }
         return ids;
@@ -434,7 +462,7 @@ function snapshotSchemaIds(value, limits) {
     catch (error) {
         if (error instanceof OpenApiMcpError)
             throw error;
-        throw input(CATALOG_STORE_PUBLIC_MESSAGES.schemaRequestInvalid);
+        throw input(invalidMessage);
     }
 }
 async function d1All(database, sql, values, errorCode) {
@@ -540,6 +568,37 @@ class D1CatalogStore {
             throw failure("RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.operationIdentifierMismatch);
         return row;
     }
+    async getOperations(catalog, release, ids) {
+        const catalogIdValue = catalogId(catalog);
+        const releaseIdValue = releaseId(release);
+        const operationIds = snapshotOperationIds(ids, this.limits);
+        if (operationIds.length === 0)
+            return [];
+        const requested = new Set(operationIds);
+        const rows = await d1All(this.database, GET_OPERATIONS_SQL, [
+            canonicalJson([...requested].sort()),
+            operationIdBytes,
+            digestBytes,
+            this.limits.maxRecordBytes,
+            catalogIdValue,
+            releaseIdValue,
+            requested.size + 1,
+        ], "RECORD_DIGEST_MISMATCH");
+        if (rows.length > requested.size)
+            throw failure("RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.operationTransportTooManyRows);
+        // Unlike getSchemas, absent IDs are omitted rather than rejected, matching
+        // getOperation's null; callers decide whether absence is fatal.
+        const records = [];
+        let previous = "";
+        for (const value of rows) {
+            const row = decodeRecord(value, "operation", this.limits);
+            if (!requested.has(row.id) || row.id <= previous)
+                throw failure("RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.operationRowsInvalid);
+            previous = row.id;
+            records.push(row);
+        }
+        return records;
+    }
     async getSchemas(catalog, release, ids) {
         const catalogIdValue = catalogId(catalog);
         const releaseIdValue = releaseId(release);

package/dist/runtime/types.d.ts

@@ -167,6 +167,13 @@ export interface CatalogStore {
     getManifest(catalogId: CatalogId, releaseId: ReleaseId): Promise<ManifestEnvelope>;
     searchCandidates(query: SearchQuery): Promise<readonly CandidateRef[]>;
     getOperation(catalogId: CatalogId, releaseId: ReleaseId, id: TypedOperationId): Promise<StoredRecord<OperationRecordV4> | null>;
+    /**
+     * Optional batched operation read used by complete-release verification.
+     * Returns the stored rows for the requested IDs; a missing ID is omitted
+     * (as `getOperation` returns null). Stores without it are read row by row.
+     * It has no response-size bound of its own; callers bound the batch.
+     */
+    getOperations?(catalogId: CatalogId, releaseId: ReleaseId, ids: readonly TypedOperationId[]): Promise<readonly StoredRecord<OperationRecordV4>[]>;
     getSchemas(catalogId: CatalogId, releaseId: ReleaseId, ids: readonly TypedSchemaId[]): Promise<readonly StoredRecord<SchemaRecordV4>[]>;
 }
 /** Immutable high-water data plus the release currently admitted for use. */

package/dist/sqlite/catalog-store.d.ts

@@ -16,5 +16,6 @@ export declare class SqliteCatalogStore implements CatalogStore {
     getManifest(catalog: CatalogId, release: ReleaseId): Promise<ManifestEnvelope>;
     searchCandidates(query: SearchQuery): Promise<readonly import("../runtime/types.ts").CandidateRef[]>;
     getOperation(catalog: CatalogId, release: ReleaseId, id: TypedOperationId): Promise<StoredRecord<OperationRecordV4> | null>;
+    getOperations(catalog: CatalogId, release: ReleaseId, ids: readonly TypedOperationId[]): Promise<readonly StoredRecord<OperationRecordV4>[]>;
     getSchemas(catalog: CatalogId, release: ReleaseId, ids: readonly TypedSchemaId[]): Promise<readonly StoredRecord<SchemaRecordV4>[]>;
 }

package/dist/sqlite/catalog-store.js

@@ -364,6 +364,9 @@ export class SqliteCatalogStore {
     async getOperation(catalog, release, id) {
         return await this.#v4Store().getOperation(catalog, release, id);
     }
+    async getOperations(catalog, release, ids) {
+        return await this.#v4Store().getOperations(catalog, release, ids);
+    }
     async getSchemas(catalog, release, ids) {
         return await this.#v4Store().getSchemas(catalog, release, ids);
     }

package/dist/stdio/search.js

@@ -30,6 +30,10 @@ export function createStdioSearchRuntime(catalogs, options) {
                     throw new OpenApiMcpError("UPSTREAM_ERROR");
                 },
             };
+            // Batch only when every source store can; otherwise keep per-row reads.
+            // Every source was just checked, so `?? []` only fails closed as missing.
+            if (ordered.every((entry) => entry.store.getOperations !== undefined))
+                store.getOperations = async (catalog, release, ids) => (await storeFor(catalog, release).getOperations?.(catalog, release, ids)) ?? [];
             return createRuntimeWithCandidateLookup({ ...options, limits, store }, async (query, tryChargeSource) => {
                 const batches = [];
                 let remaining = query.limit;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knitli/openapi-mcp",
   "private": false,
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Compile signed OpenAPI catalogs and serve verified search and authorized API calls over MCP.",
   "license": "MIT OR Apache-2.0",