@knitli/openapi-mcp 0.0.0

package/dist/conformance/runtime-suite.js

@@ -0,0 +1,343 @@
+import { admitManifest, CATALOG_STORE_PUBLIC_MESSAGES, verifyStoredRecord, } from "../runtime/index.js";
+async function assertPublicError(adapter, run, code, message, forbidden) {
+    let caught;
+    try {
+        await run();
+    }
+    catch (error) {
+        caught = error;
+    }
+    adapter.ok(caught);
+    const error = caught;
+    adapter.equal(error.code, code);
+    adapter.deepEqual(error.details, {});
+    adapter.equal(error.retryable, false);
+    adapter.equal(error.message, message);
+    if (forbidden !== undefined) {
+        adapter.equal(JSON.stringify(error).includes(forbidden), false);
+        adapter.equal(String(error.message).includes(forbidden), false);
+    }
+}
+function attemptMutation(run) {
+    try {
+        run();
+    }
+    catch {
+        // Frozen results may reject mutation; mutable results must be detached.
+    }
+}
+class ConformanceGenerationStore {
+    #states = new Map();
+    async get(catalogId, issuer) {
+        return this.#states.get(`${catalogId}\0${issuer}`) ?? null;
+    }
+    async accept(catalogId, issuer, transition) {
+        const key = `${catalogId}\0${issuer}`;
+        const current = this.#states.get(key) ?? null;
+        if ((current?.revision ?? null) !== transition.expectedRevision)
+            return null;
+        this.#states.set(key, transition.next);
+        return transition.next;
+    }
+}
+/** Register the transport-independent CatalogStore contract against a factory. */
+export function runRuntimeConformanceSuite(factory, options) {
+    const { testAdapter: adapter } = options;
+    const use = (name, run) => {
+        adapter.test(name, async () => {
+            const value = await factory();
+            try {
+                await run(value);
+            }
+            finally {
+                await value.dispose?.();
+            }
+        });
+    };
+    const useFault = (name, scenario, run) => {
+        adapter.test(name, async () => {
+            const value = await factory(scenario);
+            try {
+                await run(value);
+            }
+            finally {
+                await value.dispose?.();
+            }
+        });
+    };
+    use("catalog candidates are bounded, exact, and duplicate-free", async ({ store, fixture }) => {
+        adapter.deepEqual(await store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: 1,
+        }), fixture.expectedCandidates.slice(0, 1));
+        adapter.deepEqual(await store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: fixture.expectedCandidates.length,
+        }), fixture.expectedCandidates);
+    });
+    useFault("catalog rejects duplicate candidate transport rows", { fault: "duplicate-candidates" }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: fixture.expectedCandidates.length,
+        }), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.searchTransportDuplicateRows);
+    });
+    useFault("catalog rejects malformed candidate transport rows", { fault: "candidate-malformed-operation-id" }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: 1,
+        }), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.storedOperationIdentifierInvalid);
+    });
+    useFault("catalog rejects candidate transport rows with non-operation IDs", { fault: "candidate-non-operation-id" }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: 1,
+        }), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.storedOperationIdentifierInvalid);
+    });
+    useFault("catalog rejects cross-API candidate transport rows", { fault: "candidate-cross-api" }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: 1,
+        }), "RECORD_DIGEST_MISMATCH", CATALOG_STORE_PUBLIC_MESSAGES.searchTransportOutsideRequestedApi);
+    });
+    useFault("catalog rejects duplicate manifest transport rows", { fault: "duplicate-manifest" }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.getManifest(fixture.catalogId, fixture.releaseA), "MANIFEST_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.manifestTransportAbsentOrAmbiguous);
+    });
+    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 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);
+    });
+    const injectedDriverError = "conformance-private-driver-secret";
+    useFault("catalog redacts candidate driver failures", { fault: "driver-candidates", injectedDriverError }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.searchCandidates({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: 1,
+        }), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.searchExpressionInvalid, injectedDriverError);
+    });
+    useFault("catalog redacts manifest driver failures", { fault: "driver-manifest", injectedDriverError }, async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.getManifest(fixture.catalogId, fixture.releaseA), "MANIFEST_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.manifestTransportUnavailable, injectedDriverError);
+    });
+    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 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);
+    });
+    use("catalog operations bind catalog and release", async ({ store, fixture }) => {
+        adapter.deepEqual(await store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId), fixture.operationA);
+        adapter.deepEqual(await store.getOperation(fixture.catalogId, fixture.releaseB, fixture.operationId), fixture.operationB);
+        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 schemas are batched, unique, ordered, and empty-safe", async ({ store, fixture }) => {
+        const firstSchemaId = fixture.schemaIds[0];
+        if (firstSchemaId === undefined)
+            throw new Error("Conformance fixture has no schema");
+        adapter.deepEqual(await store.getSchemas(fixture.catalogId, fixture.releaseA, [...fixture.schemaIds].reverse().concat(firstSchemaId)), fixture.schemasA);
+        adapter.deepEqual(await store.getSchemas(fixture.catalogId, fixture.releaseB, [...fixture.schemaIds].reverse()), fixture.schemasB);
+        adapter.deepEqual(await store.getSchemas(fixture.catalogId, fixture.releaseA, []), []);
+    });
+    use("catalog manifests admit and authenticate logical records", async ({ store, fixture }) => {
+        const admittedA = await admitManifest(await store.getManifest(fixture.catalogId, fixture.releaseA), fixture.trust, new ConformanceGenerationStore());
+        adapter.equal(admittedA.manifest.catalogId, fixture.catalogId);
+        adapter.equal(admittedA.manifest.releaseId, fixture.releaseA);
+        const operationA = await store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId);
+        adapter.ok(operationA);
+        if (operationA === null)
+            throw new Error("Conformance operation A is absent");
+        adapter.deepEqual(await verifyStoredRecord(admittedA, operationA), {
+            ...fixture.operationA.record,
+            tags: [],
+        });
+        const schemasA = await store.getSchemas(fixture.catalogId, fixture.releaseA, fixture.schemaIds);
+        for (const [index, row] of schemasA.entries()) {
+            adapter.deepEqual(await verifyStoredRecord(admittedA, row), fixture.schemasA[index]?.record);
+        }
+        const admittedB = await admitManifest(await store.getManifest(fixture.catalogId, fixture.releaseB), fixture.trust, new ConformanceGenerationStore());
+        adapter.equal(admittedB.manifest.catalogId, fixture.catalogId);
+        adapter.equal(admittedB.manifest.releaseId, fixture.releaseB);
+        const operationB = await store.getOperation(fixture.catalogId, fixture.releaseB, fixture.operationId);
+        adapter.ok(operationB);
+        if (operationB === null)
+            throw new Error("Conformance operation B is absent");
+        adapter.deepEqual(await verifyStoredRecord(admittedB, operationB), {
+            ...fixture.operationB.record,
+            tags: [],
+        });
+    });
+    use("catalog verification rejects tampered logical content", async ({ store, fixture }) => {
+        const admitted = await admitManifest(await store.getManifest(fixture.catalogId, fixture.releaseA), fixture.trust, new ConformanceGenerationStore());
+        const operation = await store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId);
+        adapter.ok(operation);
+        if (operation === null)
+            throw new Error("Conformance operation is absent");
+        await adapter.rejects(() => verifyStoredRecord(admitted, {
+            ...operation,
+            record: { ...operation.record, summary: "tampered" },
+        }), "RECORD_DIGEST_MISMATCH");
+    });
+    use("catalog identity and absence are enforced across every record kind", async ({ store, fixture }) => {
+        const wrongCatalog = "missing-catalog";
+        const missingRelease = "missing-release";
+        const missingSchema = "schema:conformance:#/components/schemas/Missing";
+        for (const [catalogId, releaseId] of [
+            [wrongCatalog, fixture.releaseA],
+            [fixture.catalogId, missingRelease],
+        ]) {
+            await adapter.rejects(() => store.getManifest(catalogId, releaseId), "MANIFEST_INVALID");
+            adapter.equal(await store.getOperation(catalogId, releaseId, fixture.operationId), null);
+            await adapter.rejects(() => store.getSchemas(catalogId, releaseId, fixture.schemaIds), "RECORD_DIGEST_MISMATCH");
+        }
+        await adapter.rejects(() => store.getSchemas(fixture.catalogId, fixture.releaseA, [
+            missingSchema,
+        ]), "RECORD_DIGEST_MISMATCH");
+        await assertPublicError(adapter, () => store.searchCandidates({ query: '"', api: fixture.api, limit: 1 }), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.searchExpressionInvalid);
+    });
+    use("catalog rejects malformed caller identities", async ({ store, fixture }) => {
+        await assertPublicError(adapter, () => store.getOperation(fixture.catalogId, fixture.releaseA, "schema:conformance:not-an-operation"), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.operationIdentityInvalid);
+        await assertPublicError(adapter, () => store.getSchemas(fixture.catalogId, fixture.releaseA, [
+            "operation:conformance:not-a-schema",
+        ]), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.schemaIdentityInvalid);
+    });
+    use("catalog rejects non-string identity values without coercion", async ({ store, fixture }) => {
+        let coercions = 0;
+        const coercible = Object.freeze({
+            toString() {
+                coercions += 1;
+                return fixture.catalogId;
+            },
+        });
+        for (const [label, invalid] of [
+            ["number", 42],
+            ["null", null],
+            ["object", coercible],
+        ]) {
+            const attempts = [
+                [
+                    () => store.getManifest(invalid, fixture.releaseA),
+                    CATALOG_STORE_PUBLIC_MESSAGES.catalogIdentityInvalid,
+                ],
+                [
+                    () => store.getManifest(fixture.catalogId, invalid),
+                    CATALOG_STORE_PUBLIC_MESSAGES.releaseIdentityInvalid,
+                ],
+                [
+                    () => store.searchCandidates({
+                        query: fixture.searchQuery,
+                        api: invalid,
+                        limit: 1,
+                    }),
+                    CATALOG_STORE_PUBLIC_MESSAGES.catalogIdentityInvalid,
+                ],
+                [
+                    () => store.getOperation(invalid, fixture.releaseA, fixture.operationId),
+                    CATALOG_STORE_PUBLIC_MESSAGES.catalogIdentityInvalid,
+                ],
+                [
+                    () => store.getOperation(fixture.catalogId, invalid, fixture.operationId),
+                    CATALOG_STORE_PUBLIC_MESSAGES.releaseIdentityInvalid,
+                ],
+                [
+                    () => store.getOperation(fixture.catalogId, fixture.releaseA, invalid),
+                    CATALOG_STORE_PUBLIC_MESSAGES.operationIdentityInvalid,
+                ],
+                [
+                    () => store.getSchemas(invalid, fixture.releaseA, fixture.schemaIds),
+                    CATALOG_STORE_PUBLIC_MESSAGES.catalogIdentityInvalid,
+                ],
+                [
+                    () => store.getSchemas(fixture.catalogId, invalid, fixture.schemaIds),
+                    CATALOG_STORE_PUBLIC_MESSAGES.releaseIdentityInvalid,
+                ],
+                [
+                    () => store.getSchemas(fixture.catalogId, fixture.releaseA, [
+                        invalid,
+                    ]),
+                    CATALOG_STORE_PUBLIC_MESSAGES.schemaIdentityInvalid,
+                ],
+            ];
+            for (const [run, message] of attempts) {
+                await assertPublicError(adapter, run, "INPUT_INVALID", message);
+            }
+            adapter.equal(coercions, 0, `${label} was coerced`);
+        }
+    });
+    use("catalog snapshots only plain data-only search and schema requests", async ({ store, fixture }) => {
+        let searchGetterCalls = 0;
+        const changingSearch = {};
+        for (const [key, first, second] of [
+            ["query", fixture.searchQuery, '"'],
+            ["api", fixture.api, "other-api"],
+            ["limit", 1, 2],
+        ]) {
+            let current = first;
+            Object.defineProperty(changingSearch, key, {
+                enumerable: true,
+                get() {
+                    searchGetterCalls += 1;
+                    const result = current;
+                    current = second;
+                    return result;
+                },
+            });
+        }
+        const inheritedSearch = Object.create({
+            query: fixture.searchQuery,
+            api: fixture.api,
+            limit: 1,
+        });
+        for (const hostile of [changingSearch, inheritedSearch]) {
+            await assertPublicError(adapter, () => store.searchCandidates(hostile), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.searchQueryInvalid);
+        }
+        adapter.equal(searchGetterCalls, 0);
+        let iteratorCalls = 0;
+        const nonPlain = Object.setPrototypeOf([...fixture.schemaIds], Object.create(Array.prototype));
+        const sparse = new Array(fixture.schemaIds.length);
+        const extraKey = [...fixture.schemaIds];
+        extraKey.extra = "untrusted";
+        const customIterator = [...fixture.schemaIds];
+        Object.defineProperty(customIterator, Symbol.iterator, {
+            enumerable: false,
+            value: function* () {
+                iteratorCalls += 1;
+                yield* fixture.schemaIds;
+            },
+        });
+        for (const hostile of [nonPlain, sparse, extraKey, customIterator]) {
+            await assertPublicError(adapter, () => store.getSchemas(fixture.catalogId, fixture.releaseA, hostile), "INPUT_INVALID", CATALOG_STORE_PUBLIC_MESSAGES.schemaRequestInvalid);
+        }
+        adapter.equal(iteratorCalls, 0);
+    });
+    use("catalog results are detached from subsequent reads", async ({ store, fixture }) => {
+        const operation = await store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId);
+        if (operation === null)
+            throw new Error("Conformance operation is absent");
+        attemptMutation(() => {
+            operation.logicalDigest = "0".repeat(64);
+        });
+        attemptMutation(() => {
+            operation.record.summary = "mutated";
+        });
+        attemptMutation(() => {
+            operation.record.schemaIds.push("schema:conformance:#/components/schemas/Mutation");
+        });
+        const schemas = await store.getSchemas(fixture.catalogId, fixture.releaseA, fixture.schemaIds);
+        attemptMutation(() => {
+            schemas[0].logicalDigest = "0".repeat(64);
+        });
+        attemptMutation(() => {
+            const schema = schemas[0]?.record.schema;
+            schema.title = "mutated";
+        });
+        adapter.deepEqual(await store.getOperation(fixture.catalogId, fixture.releaseA, fixture.operationId), fixture.operationA);
+        adapter.deepEqual(await store.getSchemas(fixture.catalogId, fixture.releaseA, fixture.schemaIds), fixture.schemasA);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./compiler.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./compiler.js";

package/dist/load.d.ts

@@ -0,0 +1,31 @@
+export interface OpenApiOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    parameters?: unknown[];
+    requestBody?: unknown;
+    [key: string]: unknown;
+}
+export interface OpenApiDoc {
+    openapi: string;
+    servers?: Array<{
+        url: string;
+    }>;
+    paths: Record<string, Record<string, OpenApiOperation>>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        parameters?: Record<string, unknown>;
+        responses?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Reads an OpenAPI 3.x document from disk. Under Bun, YAML is parsed with
+ * Bun's native parser, which handles the 44 MB Microsoft Graph document in
+ * ~0.5s. Under Node, it falls back to the `yaml` package, which takes ~12.6s
+ * on the same document — acceptable for a compile step, and JSON specs skip
+ * YAML parsing entirely either way.
+ */
+export declare function loadSpec(path: string): Promise<OpenApiDoc>;

package/dist/load.js

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+/**
+ * Reads an OpenAPI 3.x document from disk. Under Bun, YAML is parsed with
+ * Bun's native parser, which handles the 44 MB Microsoft Graph document in
+ * ~0.5s. Under Node, it falls back to the `yaml` package, which takes ~12.6s
+ * on the same document — acceptable for a compile step, and JSON specs skip
+ * YAML parsing entirely either way.
+ */
+export async function loadSpec(path) {
+    const text = await readFile(path, "utf8");
+    const doc = (path.endsWith(".json")
+        ? JSON.parse(text)
+        : typeof Bun !== "undefined"
+            ? Bun.YAML.parse(text)
+            : (await import("yaml")).parse(text));
+    if (!doc || typeof doc !== "object" || typeof doc.paths !== "object") {
+        throw new Error(`${path}: not an OpenAPI document (no "paths" object)`);
+    }
+    return doc;
+}

package/dist/operations.d.ts

@@ -0,0 +1,27 @@
+import type { OpenApiDoc } from "./load.ts";
+import type { OperationRecord } from "./types.ts";
+/** The gatekeeper caps rendered descriptions at 600 characters. */
+export declare const MAX_SUMMARY = 600;
+/**
+ * Splits identifier-style text into lowercase words for fts indexing.
+ * fts5's unicode61 tokenizer already folds case but treats `sendMail` as one
+ * token, so `MATCH 'send mail'` misses it — this widens the indexed text with
+ * a word-split shadow so both the joined and split forms are searchable.
+ * Splits camelCase boundaries (including acronym runs: `getURLValue` →
+ * `get url value`), `. / _ - { }` separators, and whitespace, then
+ * lowercases and collapses runs of whitespace. Deduping words is not required.
+ */
+export declare function splitWords(text: string): string;
+/**
+ * Canonicalize the URI-fragment representation of an RFC 6901 pointer.
+ *
+ * The returned value is an internal, already URI-decoded physical address. It
+ * must not be fed through URI decoding a second time.
+ */
+export declare function canonicalLocalPointer(ref: string): string;
+/** Resolve an already canonicalized physical JSON Pointer address. */
+export declare function resolveCanonicalPointer(doc: unknown, pointer: string): unknown;
+/** Resolve a URI-decoded, one-pass RFC 6901 fragment through own properties only. */
+export declare function resolveLocalPointer(doc: unknown, ref: string): unknown;
+/** Extracts one thin record per operation. `$ref`s are stored, never resolved. */
+export declare function extractOperations(doc: OpenApiDoc, api: string): OperationRecord[];

package/dist/operations.js

@@ -0,0 +1,231 @@
+import { classifySafety, riskFor } from "./safety.js";
+/** The gatekeeper caps rendered descriptions at 600 characters. */
+export const MAX_SUMMARY = 600;
+/**
+ * Splits identifier-style text into lowercase words for fts indexing.
+ * fts5's unicode61 tokenizer already folds case but treats `sendMail` as one
+ * token, so `MATCH 'send mail'` misses it — this widens the indexed text with
+ * a word-split shadow so both the joined and split forms are searchable.
+ * Splits camelCase boundaries (including acronym runs: `getURLValue` →
+ * `get url value`), `. / _ - { }` separators, and whitespace, then
+ * lowercases and collapses runs of whitespace. Deduping words is not required.
+ */
+export function splitWords(text) {
+    return text
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[._/\-{}\s]+/)
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+}
+const HTTP_METHODS = new Set([
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+]);
+const FORBIDDEN_POINTER_KEYS = new Set([
+    "__proto__",
+    "prototype",
+    "constructor",
+]);
+/**
+ * Canonicalize the URI-fragment representation of an RFC 6901 pointer.
+ *
+ * The returned value is an internal, already URI-decoded physical address. It
+ * must not be fed through URI decoding a second time.
+ */
+export function canonicalLocalPointer(ref) {
+    if (ref === "")
+        return "#";
+    if (!ref.startsWith("#"))
+        throw new Error("local reference must be a JSON Pointer fragment");
+    let pointer;
+    try {
+        pointer = decodeURIComponent(ref.slice(1));
+    }
+    catch {
+        throw new Error("JSON Pointer contains an invalid URI escape");
+    }
+    if (pointer === "")
+        return "#";
+    if (!pointer.startsWith("/"))
+        throw new Error("local reference must be a JSON Pointer fragment");
+    const tokens = pointer.slice(1).split("/");
+    for (const rawToken of tokens) {
+        if (/(?:~(?:[^01]|$))/.test(rawToken))
+            throw new Error("JSON Pointer contains an invalid ~ escape");
+        const token = rawToken.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (FORBIDDEN_POINTER_KEYS.has(token))
+            throw new Error("JSON Pointer contains a forbidden prototype key");
+    }
+    return `#/${tokens.join("/")}`;
+}
+/** Resolve an already canonicalized physical JSON Pointer address. */
+export function resolveCanonicalPointer(doc, pointer) {
+    if (pointer === "#")
+        return doc;
+    if (!pointer.startsWith("#/"))
+        throw new Error("canonical pointer must be a JSON Pointer fragment");
+    let node = doc;
+    for (const rawToken of pointer.slice(2).split("/")) {
+        if (/(?:~(?:[^01]|$))/.test(rawToken)) {
+            throw new Error("JSON Pointer contains an invalid ~ escape");
+        }
+        const token = rawToken.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (FORBIDDEN_POINTER_KEYS.has(token)) {
+            throw new Error("JSON Pointer contains a forbidden prototype key");
+        }
+        if (Array.isArray(node)) {
+            if (!/^(?:0|[1-9][0-9]*)$/.test(token)) {
+                throw new Error("JSON Pointer array index is not canonical");
+            }
+            const index = Number(token);
+            if (!Number.isSafeInteger(index) ||
+                index >= node.length ||
+                !Object.hasOwn(node, index)) {
+                throw new Error("JSON Pointer array index was not found");
+            }
+            node = node[index];
+            continue;
+        }
+        if (typeof node !== "object" ||
+            node === null ||
+            !Object.hasOwn(node, token)) {
+            throw new Error("JSON Pointer target was not found");
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(node, token);
+        if (descriptor === undefined || !("value" in descriptor)) {
+            throw new Error("JSON Pointer target is not an own data property");
+        }
+        node = descriptor.value;
+    }
+    return node;
+}
+/** Resolve a URI-decoded, one-pass RFC 6901 fragment through own properties only. */
+export function resolveLocalPointer(doc, ref) {
+    return resolveCanonicalPointer(doc, canonicalLocalPointer(ref));
+}
+function collectParams(doc, pathItem, op) {
+    const raw = [
+        ...(pathItem.parameters ?? []),
+        ...(op.parameters ?? []),
+    ];
+    // OpenAPI identifies a parameter by `(name, in)` and lets the operation
+    // override the path item's. Operation entries come second, so a plain
+    // last-write-wins keyed insert gives exactly that precedence — whereas
+    // concatenating would emit both and leave the caller two conflicting
+    // schemas for one parameter.
+    const out = new Map();
+    for (const entry of raw) {
+        const p = (typeof entry === "object" && entry !== null && "$ref" in entry
+            ? resolveLocalPointer(doc, entry.$ref)
+            : entry);
+        if (!p || typeof p.name !== "string")
+            continue;
+        const where = typeof p.in === "string" ? p.in : "query";
+        out.set(`${where}:${p.name}`, {
+            name: p.name,
+            in: where,
+            required: p.required === true,
+            schema: p.schema ?? { type: "string" },
+        });
+    }
+    return [...out.values()];
+}
+const NO_BODY = { ref: null, schemaJson: null, mediaType: null };
+/**
+ * Captures an operation's request-body contract. A `$ref` is kept as a ref and
+ * resolved lazily from the schema store, which is the whole point of the thin
+ * artifact. Anything else — an inline schema, or a body under a non-JSON media
+ * type — is stored verbatim instead of dropped: a write whose body contract is
+ * missing is either unusable or, worse, executable with no validation at all.
+ */
+function bodyOf(op) {
+    const rb = op.requestBody;
+    if (!rb)
+        return NO_BODY;
+    if (typeof rb.$ref === "string") {
+        return { ref: rb.$ref, schemaJson: null, mediaType: null };
+    }
+    const content = rb.content;
+    if (!content)
+        return NO_BODY;
+    // Prefer JSON, but fall back to whatever the operation actually declares —
+    // the media type travels with the schema so the server can set Content-Type.
+    const mediaType = "application/json" in content
+        ? "application/json"
+        : Object.keys(content)[0];
+    if (mediaType === undefined)
+        return NO_BODY;
+    const schema = content[mediaType]?.schema;
+    if (schema === undefined)
+        return NO_BODY;
+    const ref = schema.$ref;
+    return typeof ref === "string"
+        ? { ref, schemaJson: null, mediaType }
+        : { ref: null, schemaJson: JSON.stringify(schema), mediaType };
+}
+/** Extracts one thin record per operation. `$ref`s are stored, never resolved. */
+export function extractOperations(doc, api) {
+    const serverUrl = doc.servers?.[0]?.url ?? "";
+    if (!serverUrl)
+        throw new Error("document declares no servers[0].url");
+    const seen = new Set();
+    const records = [];
+    for (const [path, pathItem] of Object.entries(doc.paths)) {
+        if (pathItem.servers !== undefined) {
+            throw new Error(`${path}: path-item-level "servers" overrides are not supported`);
+        }
+        for (const [method, op] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.has(method))
+                continue;
+            if (op.servers !== undefined) {
+                throw new Error(`${method.toUpperCase()} ${path}: operation-level "servers" overrides are not supported`);
+            }
+            const operationId = op.operationId;
+            if (typeof operationId !== "string" || operationId.length === 0) {
+                throw new Error(`${method.toUpperCase()} ${path}: missing operationId`);
+            }
+            const qualifiedId = `${api}:${operationId}`;
+            if (seen.has(qualifiedId)) {
+                throw new Error(`duplicate operationId: ${operationId}`);
+            }
+            seen.add(qualifiedId);
+            const upper = method.toUpperCase();
+            const body = bodyOf(op);
+            const safety = classifySafety(upper, path, operationId, api);
+            const summary = (op.summary ?? op.description ?? null)?.slice(0, MAX_SUMMARY);
+            records.push({
+                qualifiedId,
+                api,
+                operationId,
+                method: upper,
+                path,
+                safety,
+                risk: riskFor(safety, null, path),
+                operationType: typeof op["x-ms-docs-operation-type"] === "string"
+                    ? op["x-ms-docs-operation-type"]
+                    : null,
+                pageable: op["x-ms-pageable"] !== undefined,
+                deprecated: op.deprecated === true,
+                permissions: null,
+                permConfidence: null,
+                privilegeLevel: null,
+                summary: summary ?? null,
+                tags: Array.isArray(op.tags) ? op.tags.join(" ") : null,
+                paramsJson: JSON.stringify(collectParams(doc, pathItem, op)),
+                searchText: `${splitWords(operationId)} ${splitWords(path)}`,
+                bodyRef: body.ref,
+                bodySchemaJson: body.schemaJson,
+                bodyMediaType: body.mediaType,
+                serverUrl,
+            });
+        }
+    }
+    return records;
+}