@ttsc/evidence 0.30.3 → 0.31.0

package/README.md

@@ -78,7 +78,11 @@ This is a rule contributor to [`@ttsc/lint`](https://github.com/samchon/ttsc/tre
 
 ```ts
 // lint.config.ts
-import { evidence, type ITtscEvidenceGraphConfig } from "@ttsc/evidence";
+import {
+  evidence,
+  type ITtscEvidenceGraphConfig,
+  type ITtscEvidenceRules,
+} from "@ttsc/evidence";
 import type { ITtscLintConfig } from "@ttsc/lint";
 
 const graph: ITtscEvidenceGraphConfig = {
@@ -102,10 +106,10 @@ export default {
     "evidence/graph": ["error", graph],
     "evidence/review": "error",
   },
-} satisfies ITtscLintConfig;
+} satisfies ITtscLintConfig<ITtscEvidenceRules>;
 ```
 
-One claim: the components under `src` implement the docs, so every H2 and H3 under `docs` must be cited by a component. Run `npx ttsc` and the error count is the backlog.
+One claim: the components under `src` implement the docs, so every H2 and H3 under `docs` must be cited by a component. Run `npx ttsc` and the error count is the backlog. Passing `ITtscEvidenceRules` to `ITtscLintConfig` gives every Evidence rule exact option checking.
 
 [The configuration reference](https://ttsc.dev/docs/evidence/claims) has every claim option and the four rules beside `evidence/graph`.
 
@@ -113,12 +117,12 @@ One claim: the components under `src` implement the docs, so every H2 and H3 und
 
 The configuration is written once. The tags are written forever: `@evidence` cites, `@evidenceReview` verifies, and `@evidenceExclude` declines. [The tag reference](https://ttsc.dev/docs/evidence/tags) has the full grammar.
 
-A false tag removes the error, not the problem. `@evidenceReview` resolves it:
+A false tag removes the error, not the problem. `@evidenceReview` asks for a separate statement of what was verified, which a human then judges:
 
 ```ts
 /**
  * @evidence docs/discount.md#coupon-stacking States the per-issuer limit.
- * @evidenceReview docs/discount.md#coupon-stacking #a1b2c3d4e5f6
+ * @evidenceReview docs/discount.md#coupon-stacking #a1b2c3d
  *                 Verified against policy section 3.
  */
 ```
@@ -126,6 +130,10 @@ A false tag removes the error, not the problem. `@evidenceReview` resolves it:
 - Reviews match the same declaration and target.
 - The fingerprint expires when the cited content changes.
 
+Normalized Swagger operation fingerprints decode local component URI fragments before interpreting JSON Pointer tokens, including array indices. Upgrading can expire reviews of operations using encoded pointers, array elements, or malformed references that previously selected a literal property. Re-read those operations and their referenced contracts before replacing a fingerprint.
+
+Raw OpenAPI 3.1 and 3.2 schema references retain their original targets through version normalization, including pointers into schema structures the converter relocates. Foreign, missing and malformed schema references do not bind to a local schema with the same final name. Reference-shaped example, default, constant, enum and extension values remain data. Reviews affected by these earlier interpretations also need to be read again before their fingerprints are replaced.
+
 The compiler handles omissions. Humans handle falsehoods.
 
 ## Spec-Driven Development
@@ -174,7 +182,7 @@ Make them a checklist:
 }
 ```
 
-`checklist` changes the denominator from principles to functions times principles. Every selected function must answer every principle, as `CouponStackingNotice` does above.
+`checklist` changes the denominator from principles to functions times principles. Every selected function must answer every principle, with `@evidence` as `CouponStackingNotice` does for `no-hard-coding` or with `@evidenceExclude` as it does for `fix-root-causes-not-symptoms`; the two principles it leaves unanswered above would fail the build.
 
 One missing answer fails the build. Adding a principle creates a new obligation on every selected function, and `requireReview` expires every affected review when that principle changes.
 

package/lib/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./structures/index";
-export * from "./typings/index";
 /**
  * The `@ttsc/lint` contributor that checks a project's evidence graph.
  *
@@ -18,8 +17,8 @@ export * from "./typings/index";
  * - `"evidence/singular"` — one public identity per TypeScript file, named after
  *   the file. Takes no options, so it carries a bare severity.
  * - `"evidence/documented"` — a JSDoc block on every selected export, which is
- *   the only place an `@evidence` tag is ever read from. Takes an
- *   {@link ITtscEvidenceDocumentedConfig}.
+ *   the only place a TypeScript declaration's `@evidence` tag is ever read
+ *   from. Takes an {@link ITtscEvidenceDocumentedConfig}.
  * - `"evidence/todo"` — no remaining JSDoc `@todo` tag anywhere in a checked
  *   file, exported or not. Each tag is an unrealized contract reported with its
  *   own text, so the diagnostics read as the ledger of what remains to realize.

package/lib/index.js

@@ -21,7 +21,6 @@ exports.evidence = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const package_json_1 = require("../package.json");
 __exportStar(require("./structures/index"), exports);
-__exportStar(require("./typings/index"), exports);
 /**
  * The `@ttsc/lint` contributor that checks a project's evidence graph.
  *
@@ -40,8 +39,8 @@ __exportStar(require("./typings/index"), exports);
  * - `"evidence/singular"` — one public identity per TypeScript file, named after
  *   the file. Takes no options, so it carries a bare severity.
  * - `"evidence/documented"` — a JSDoc block on every selected export, which is
- *   the only place an `@evidence` tag is ever read from. Takes an
- *   {@link ITtscEvidenceDocumentedConfig}.
+ *   the only place a TypeScript declaration's `@evidence` tag is ever read
+ *   from. Takes an {@link ITtscEvidenceDocumentedConfig}.
  * - `"evidence/todo"` — no remaining JSDoc `@todo` tag anywhere in a checked
  *   file, exported or not. Each tag is an unrealized contract reported with its
  *   own text, so the diagnostics read as the ledger of what remains to realize.

package/lib/internal/canonicalDigest.js

@@ -40,12 +40,18 @@ exports.canonicalJson = canonicalJson;
  * Renders one value, refusing to descend into a container already on the path
  * above it.
  *
- * A source document can be cyclic: a YAML anchor referring to its own parent
- * loads, upgrades, and would then recurse until the stack ends. The failure
- * that produced was a diagnostic blaming an upgrade that had succeeded, so the
- * cycle is answered here with a marker instead. Two documents that differ only
- * in where a cycle closes still differ, because the marker is emitted at the
- * position the cycle closes at.
+ * A YAML anchor can create an object cycle that parsing and conversion retain.
+ * This renderer terminates such values with the string marker "[circular]". The
+ * marker aliases an authored literal string, and identifies the position where
+ * traversal stopped rather than which ancestor was reached. It is not an
+ * injective encoding of cyclic object graphs.
+ *
+ * Swagger currently resolves references before invoking this renderer. A
+ * reachable schema object cycle still fails before a declaration digest is
+ * emitted, while reference-shaped literal data is copied without dereferencing
+ * and an object cycle there is explicitly refused. This marker does not make
+ * the loader accept either kind of cycle. Finite recursive $ref strings use its
+ * separate reference guard.
  */
 const render = (value, seen) => {
     if (value === null || typeof value !== "object")

package/lib/internal/loadPrismaModels.js

@@ -35,6 +35,10 @@ const SEPARATOR = "\u0000";
  * relation identities with their doc comments and a digest of each
  * declaration's content.
  *
+ * Each local file is read from one handle with a 16MiB acquisition limit and
+ * one sentinel byte. The limit is per file, not per set or total process
+ * memory; the native cache digest and locator retain their own file reads.
+ *
  * One **set** is one request. A Prisma schema folder is several files that form
  * a single namespace — a model in one file may point at a model in another — so
  * a file cannot be parsed alone and the reuse key belongs to the ordered set.
@@ -118,13 +122,7 @@ const readSet = async (root, sources) => {
         // population resolves against the root its configuration declares rather
         // than against the project. The caller sends the paths its own walk
         // produced, so this side only resolves them the same way.
-        const location = node_path_1.default.resolve(root, source);
-        const stat = await promises_1.default.stat(location);
-        if (!stat.isFile())
-            throw new Error(`the Prisma schema source '${source}' is not a file`);
-        if (stat.size > MAX_SCHEMA_BYTES)
-            throw new Error(`the Prisma schema '${source}' exceeds the ${MAX_SCHEMA_BYTES} byte limit`);
-        const content = await promises_1.default.readFile(location);
+        const content = await readSchema(root, source);
         files.push([source, decodeUtf8(content)]);
         composite.update(source, "utf8");
         composite.update(SEPARATOR);
@@ -133,6 +131,53 @@ const readSet = async (root, sources) => {
     }
     return { files, digest: composite.digest("hex") };
 };
+/**
+ * Reads one schema through one handle, including a sentinel beyond the limit.
+ *
+ * Stat is admission, not a bound on later bytes. Each short read fills its
+ * current chunk, so retained backing allocations grow with accepted bytes
+ * rather than with the number of reads. Each acquired-handle path awaits a
+ * close attempt. A close rejection becomes a set problem and may replace a
+ * prior read error; a rejected close does not certify resource release. This is
+ * a per-file acquisition bound; decoding, parser input and native
+ * digest/location reads have separate costs, not a whole-process memory quota.
+ */
+const readSchema = async (root, source) => {
+    const handle = await promises_1.default.open(node_path_1.default.resolve(root, source), "r");
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`the Prisma schema source '${source}' is not a file`);
+        const sizeError = () => new Error(`the Prisma schema '${source}' exceeds the ${MAX_SCHEMA_BYTES} byte limit`);
+        if (stat.size > MAX_SCHEMA_BYTES)
+            throw sizeError();
+        const chunks = [];
+        let length = 0;
+        let chunk = Buffer.allocUnsafe(64 * 1024);
+        let used = 0;
+        while (true) {
+            const { bytesRead } = await handle.read(chunk, used, Math.min(chunk.length - used, MAX_SCHEMA_BYTES - length + 1), null);
+            if (bytesRead === 0) {
+                if (used > 0)
+                    chunks.push(chunk.subarray(0, used));
+                break;
+            }
+            length += bytesRead;
+            if (length > MAX_SCHEMA_BYTES)
+                throw sizeError();
+            used += bytesRead;
+            if (used === chunk.length) {
+                chunks.push(chunk);
+                chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_SCHEMA_BYTES - length + 1));
+                used = 0;
+            }
+        }
+        return Buffer.concat(chunks, length);
+    }
+    finally {
+        await handle.close();
+    }
+};
 const decodeUtf8 = (content) => new TextDecoder("utf-8", { fatal: true }).decode(content);
 /**
  * Runs the parser over one whole set and classifies what it declares.

package/lib/internal/loadSwaggerOperations.js

@@ -30,7 +30,29 @@ const METHODS = [
  * function is the narrow process boundary between them: it accepts only source
  * locations and returns operation identities, each carrying a digest of the
  * operation's content taken here because this is the only side that sees the
- * document.
+ * document, including inherited servers and authentication. Equivalent explicit
+ * overrides and security-set ordering keep that contract's digest stable.
+ *
+ * URL protocols are interpreted by the URL parser, preserving the configured
+ * source spelling in every returned inventory or problem. Local paths resolve
+ * against the supplied root and carry their raw-byte digest; remote sources
+ * carry no content-cache digest and retain normal fetch and TLS failures.
+ *
+ * Native configuration owns locator validation. The URL parser canonicalizes
+ * protocol case without changing document paths or replacing fetch and its TLS
+ * validation. Local paths retain path.resolve and raw-byte SHA256 identity;
+ * normalization and operation digests remain independent of source spelling.
+ *
+ * One source reader separates URL transport from local byte reading. The outer
+ * per-source boundary preserves original identity and collects every read or
+ * normalization problem. Remote content has no local cache digest. The matching
+ * configuration guide states scheme case and unsupported file URLs. Local reads
+ * use one handle, acquire at most 16MiB of input plus a sentinel byte, and fill
+ * bounded chunks across short reads. Every acquired-handle path awaits a close
+ * attempt. A rejected close becomes a source problem with no read digest and
+ * may replace an earlier read error; it does not certify successful resource
+ * release. UTF-8 decoding and parsing have their own costs; this byte limit is
+ * not a total process-memory quota.
  *
  * @internal
  */
@@ -41,17 +63,19 @@ const loadSwaggerOperations = async (request) => {
             const read = await readSource(request.root, source);
             digest = read.digest;
             const input = (0, yaml_1.parse)(read.text);
-            const document = (0, normalizeSwaggerDocument_1.normalizeSwaggerDocument)(input);
+            const normalized = (0, normalizeSwaggerDocument_1.normalizeSwaggerDocument)(input, componentAt);
             return {
                 source,
-                operations: operationsOf(document),
+                operations: operationsOf(normalized),
                 digest,
             };
         }
         catch (error) {
             return {
                 source,
-                message: errorMessage(error),
+                message: source.includes("://")
+                    ? redactSwaggerUrls(errorMessage(error), source)
+                    : errorMessage(error),
                 digest,
             };
         }
@@ -63,30 +87,62 @@ const loadSwaggerOperations = async (request) => {
 };
 exports.loadSwaggerOperations = loadSwaggerOperations;
 const readSource = async (root, source) => {
-    if (source.startsWith("http://") || source.startsWith("https://"))
+    if (source.includes("://")) {
+        const location = new URL(source);
+        if (location.protocol !== "http:" && location.protocol !== "https:")
+            throw new Error("only http: and https: URLs are supported");
         return { text: await readRemoteSource(source), digest: "" };
-    if (source.includes("://"))
-        throw new Error("only http: and https: URLs are supported");
+    }
     // A local document may sit anywhere on the filesystem, including above the
     // project or on an absolute path. The native decoder is what validates the
     // spelling; this side only has to resolve it the same way, which
     // `path.resolve` already does for both forms.
     const location = node_path_1.default.resolve(root, source);
-    const stat = await promises_1.default.stat(location);
-    if (!stat.isFile())
-        throw new Error("the local Swagger source is not a file");
-    if (stat.size > MAX_DOCUMENT_BYTES)
-        throw new Error(`the Swagger document exceeds the ${MAX_DOCUMENT_BYTES} byte limit`);
-    // Hashed before decoding, over the bytes as they were read. The native side
-    // hashes the file's bytes too, so the two agree by construction; hashing the
-    // decoded string instead would agree only for inputs where the round trip
-    // happens to be exact.
-    const content = await promises_1.default.readFile(location);
-    return {
-        text: decodeUtf8(content),
-        digest: (0, node_crypto_1.createHash)("sha256").update(content).digest("hex"),
-    };
+    const handle = await promises_1.default.open(location, "r");
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error("the local Swagger source is not a file");
+        if (stat.size > MAX_DOCUMENT_BYTES)
+            throw documentSizeError();
+        // The file can grow after stat. Read at most the limit plus one sentinel
+        // byte from this same handle, rather than allocating its new whole size.
+        const chunks = [];
+        let length = 0;
+        let chunk = Buffer.allocUnsafe(64 * 1024);
+        let used = 0;
+        while (true) {
+            const { bytesRead } = await handle.read(chunk, used, Math.min(chunk.length - used, MAX_DOCUMENT_BYTES - length + 1), null);
+            if (bytesRead === 0) {
+                if (used > 0)
+                    chunks.push(chunk.subarray(0, used));
+                break;
+            }
+            length += bytesRead;
+            if (length > MAX_DOCUMENT_BYTES)
+                throw documentSizeError();
+            used += bytesRead;
+            // Short reads fill the same buffer. Retaining a new 64KiB backing
+            // allocation for every one-byte read would defeat the memory bound.
+            if (used === chunk.length) {
+                chunks.push(chunk);
+                chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_DOCUMENT_BYTES - length + 1));
+                used = 0;
+            }
+        }
+        const content = Buffer.concat(chunks, length);
+        // Cache identity hashes exactly the accepted raw bytes. Invalid UTF-8 is
+        // an unreadable source and returns no read result or content-cache digest.
+        return {
+            text: decodeUtf8(content),
+            digest: (0, node_crypto_1.createHash)("sha256").update(content).digest("hex"),
+        };
+    }
+    finally {
+        await handle.close();
+    }
 };
+const documentSizeError = () => new Error(`the Swagger document exceeds the ${MAX_DOCUMENT_BYTES} byte limit`);
 const readRemoteSource = async (source) => {
     const response = await fetch(source, {
         signal: AbortSignal.timeout(REMOTE_TIMEOUT_MILLISECONDS),
@@ -118,23 +174,25 @@ const readRemoteSource = async (source) => {
     return decodeUtf8(content);
 };
 const decodeUtf8 = (content) => new TextDecoder("utf-8", { fatal: true }).decode(content);
-const operationsOf = (document) => {
+const operationsOf = (normalized) => {
+    const document = normalized.document;
     const operations = [];
-    const components = (document.components ??
-        {});
     for (const [operationPath, item] of Object.entries(document.paths ?? {})) {
         for (const method of METHODS) {
             const operation = item[method];
             if (operation !== undefined)
-                operations.push(operationOf(method, operationPath, operation, components));
+                operations.push(operationOf(method, operationPath, operation, item, normalized));
         }
         for (const [method, operation] of Object.entries(item.additionalOperations ?? {}))
-            operations.push(operationOf(method, operationPath, operation, components));
+            operations.push(operationOf(method, operationPath, operation, item, normalized));
     }
     operations.sort((left, right) => {
         const leftTarget = `${left.method}:${left.path}`;
         const rightTarget = `${right.method}:${right.path}`;
-        return leftTarget.localeCompare(rightTarget);
+        // Code-unit order, never locale order: collation treats canonically
+        // equivalent spellings as equal, which can leave two identical targets
+        // apart and hide the duplicate the next loop looks for.
+        return leftTarget < rightTarget ? -1 : leftTarget > rightTarget ? 1 : 0;
     });
     for (let index = 1; index < operations.length; index++) {
         const previous = operations[index - 1];
@@ -145,17 +203,92 @@ const operationsOf = (document) => {
     }
     return operations;
 };
-const operationOf = (method, operationPath, operation, components) => {
+const operationOf = (method, operationPath, operation, item, normalized) => {
     if (!operationPath.startsWith("/"))
         throw new Error(`OpenAPI path '${operationPath}' must start with '/' to form an operation target`);
     if (/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u.test(method) === false ||
         method.includes(":"))
         throw new Error(`OpenAPI method '${method}' cannot form a '<METHOD>:<path>' target`);
+    const document = normalized.document;
+    const servers = operation.servers ?? item.servers ?? document.servers;
+    const security = canonicalSecurity(operation.security ?? document.security ?? []);
+    const schemes = document.components?.securitySchemes ?? {};
+    const usedSchemes = Object.fromEntries([
+        ...new Set(security.flatMap((requirement) => Object.keys(requirement))),
+    ].map((name) => [name, schemes[name]]));
+    // Resolve on original holders before copying: literal-position provenance is
+    // keyed by object identity. Inheritance is represented outside the written
+    // operation so explicit equivalent overrides cannot duplicate its contract.
+    const resolved = withResolvedReferences(operation, normalized);
+    const { servers: _servers, security: _security, ...content } = resolved;
     return {
         method: method.toUpperCase(),
         path: operationPath,
-        digest: (0, canonicalDigest_1.canonicalDigest)(withResolvedReferences(operation, components)),
+        digest: (0, canonicalDigest_1.canonicalDigest)({
+            operation: content,
+            servers: literalValue(servers?.length ? servers : [{ url: "/" }]),
+            security,
+            securitySchemes: withResolvedReferences(usedSchemes, normalized),
+        }),
+    };
+};
+/**
+ * Canonicalizes only security's unordered OR alternatives and required scopes.
+ *
+ * Scheme keys within one alternative remain an AND. Empty alternatives remain
+ * distinct from removing authentication with an empty list; all other arrays,
+ * including server preference and literal payloads, retain their written
+ * order.
+ */
+const canonicalSecurity = (security) => {
+    const alternatives = new Map();
+    for (const requirement of security) {
+        const canonical = Object.fromEntries(Object.entries(requirement).map(([name, scopes]) => [
+            name,
+            [...new Set(scopes)].sort(),
+        ]));
+        alternatives.set((0, canonicalDigest_1.canonicalDigest)(canonical), canonical);
+    }
+    return [...alternatives.entries()]
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([, requirement]) => requirement);
+};
+/**
+ * Redacts remote URL presentation even when a URL is not parseable.
+ *
+ * The complete configured spelling is replaced before scanning reflected URLs.
+ * Lexical authority/query/fragment boundaries also protect malformed host and
+ * percent escapes that the URL parser would reject. This changes only error
+ * text; transport requests and returned source/cache identities stay
+ * untouched.
+ */
+const redactSwaggerUrls = (message, source) => {
+    const display = (value) => {
+        const suffix = value.search(/[?#]/u);
+        const base = suffix < 0 ? value : value.slice(0, suffix);
+        const scheme = base.indexOf("://");
+        if (scheme < 0)
+            return "<redacted URL>";
+        const start = scheme + 3;
+        const slash = base.indexOf("/", start);
+        const end = slash < 0 ? base.length : slash;
+        const user = base.lastIndexOf("@", end);
+        let authority = base.slice(start);
+        if (user >= start)
+            authority = "***@" + base.slice(user + 1);
+        else
+            try {
+                new URL(base.slice(0, end));
+            }
+            catch {
+                // A malformed authority can be truncated userinfo. It has no safe host.
+                authority = "[redacted]" + base.slice(end);
+            }
+        return base.slice(0, start) + authority + (suffix < 0 ? "" : "?[redacted]");
     };
+    return message
+        .replaceAll(source, display(source))
+        .replace(/https?:\/\/[^\s"'<>]+/giu, display);
 };
 /**
  * Replaces every local `$ref` into `components` with what it names.
@@ -176,37 +309,47 @@ const operationOf = (method, operationPath, operation, components) => {
  *
  * Siblings of a `$ref` are kept and override what it resolves to, which is what
  * OpenAPI 3.1 says they do. A reference already open on the path above is left
- * as written, so a recursive schema terminates while two operations reaching
- * one cycle by different routes still differ. An undeclared reference is left
- * as written too: a broken document is not a digest question, and inventing an
- * empty schema for it would make two different broken documents agree.
+ * as written. The guard uses the decoded pointer, so percent-encoded and plain
+ * spellings of the same recursive component stop at the same boundary. Two
+ * operations reaching one cycle by different routes can still differ. An
+ * undeclared or malformed reference is left as written too: a broken document
+ * is not a digest question, and inventing an empty schema for it would make two
+ * different broken documents agree. Normalization retains the original pointer
+ * identity behind private schema aliases, so a version converter cannot change
+ * the recursion boundary or bind an unresolved reference to an unrelated
+ * component. Literal example, default, const, enum and extension values are
+ * hashed as data, not dereferenced.
  */
-const withResolvedReferences = (value, components, open = new Set()) => {
+const withResolvedReferences = (value, normalized, open = new Set()) => {
     if (value === null || typeof value !== "object")
         return value;
     if (Array.isArray(value))
-        return value.map((element) => withResolvedReferences(element, components, open));
+        return value.map((element) => withResolvedReferences(element, normalized, open));
     const entries = Object.entries(value);
     const reference = value["$ref"];
-    if (typeof reference !== "string" || open.has(reference))
+    const preserved = typeof reference === "string"
+        ? normalized.referenceAt(reference)
+        : undefined;
+    const target = preserved?.target;
+    if (target === undefined || open.has(target.pointer))
         return Object.fromEntries(entries.map(([key, element]) => [
             key,
-            withResolvedReferences(element, components, open),
+            key === "$ref" && preserved !== undefined
+                ? preserved.reference
+                : normalized.isLiteral(value, key) || key.startsWith("x-")
+                    ? literalValue(element)
+                    : withResolvedReferences(element, normalized, open),
         ]));
-    const target = componentAt(components, reference);
-    if (target === undefined)
-        return Object.fromEntries(entries.map(([key, element]) => [
-            key,
-            withResolvedReferences(element, components, open),
-        ]));
-    open.add(reference);
+    open.add(target.pointer);
     try {
-        const resolved = withResolvedReferences(target, components, open);
+        const resolved = withResolvedReferences(target.value, normalized, open);
         const siblings = entries
             .filter(([key]) => key !== "$ref")
             .map(([key, element]) => [
             key,
-            withResolvedReferences(element, components, open),
+            normalized.isLiteral(value, key) || key.startsWith("x-")
+                ? literalValue(element)
+                : withResolvedReferences(element, normalized, open),
         ]);
         if (siblings.length === 0)
             return resolved;
@@ -218,29 +361,80 @@ const withResolvedReferences = (value, components, open = new Set()) => {
         };
     }
     finally {
-        open.delete(reference);
+        open.delete(target.pointer);
+    }
+};
+/**
+ * Copies data without interpreting `$ref`, refusing non-JSON object cycles.
+ *
+ * Each occurrence contributes its JSON value, even when YAML anchors share an
+ * acyclic child. The active path is released in finally; the allocated value
+ * lasts through hashing. This is not a total memory or depth bound.
+ */
+const literalValue = (value, open = new Set()) => {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (open.has(value))
+        throw new Error("a Swagger literal value contains an object cycle");
+    open.add(value);
+    try {
+        return Array.isArray(value)
+            ? value.map((element) => literalValue(element, open))
+            : Object.fromEntries(Object.entries(value).map(([key, element]) => [
+                key,
+                literalValue(element, open),
+            ]));
+    }
+    finally {
+        open.delete(value);
     }
 };
-const COMPONENT_REFERENCE_PREFIX = "#/components/";
-/** Reads one `#/components/<section>/<name>` pointer, or nothing. */
+const COMPONENT_REFERENCE_PREFIX = "/components/";
+/**
+ * Reads one local component URI fragment, or nothing.
+ *
+ * RFC 6901 URI decoding precedes tokenization: %2F separates pointer tokens,
+ * while ~1 names a slash inside one token. Malformed URI or tilde escapes name
+ * nothing; the caller preserves their original reference rather than selecting
+ * a literal property with invalid pointer syntax. Tokens are decoded once and
+ * remain case-sensitive, without Unicode normalization.
+ *
+ * Own object members and canonical unsigned array indices can be selected.
+ * Inherited properties, leading-zero indices, array append and absent elements
+ * cannot. The decoded pointer also identifies the recursion guard independently
+ * of percent-escape spelling. Walking costs the fragment length plus its token
+ * count and retains only this lookup's tokens and result.
+ */
 const componentAt = (components, reference) => {
-    if (!reference.startsWith(COMPONENT_REFERENCE_PREFIX))
+    if (!reference.startsWith("#"))
+        return undefined;
+    let pointer;
+    try {
+        pointer = decodeURIComponent(reference.slice(1));
+    }
+    catch {
+        return undefined;
+    }
+    if (!pointer.startsWith(COMPONENT_REFERENCE_PREFIX))
         return undefined;
-    const segments = reference
+    const tokens = pointer
         .slice(COMPONENT_REFERENCE_PREFIX.length)
-        .split("/")
-        .map((segment) => decodeURIComponent(segment).replaceAll("~1", "/").replaceAll("~0", "~"));
+        .split("/");
     let current = components;
-    for (const segment of segments) {
-        if (current === null ||
-            typeof current !== "object" ||
-            Array.isArray(current))
+    for (const token of tokens) {
+        if (/~(?:[^01]|$)/u.test(token))
+            return undefined;
+        const segment = token.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (current === null || typeof current !== "object")
+            return undefined;
+        if (Array.isArray(current) &&
+            /^(?:0|[1-9][0-9]*)$/u.test(segment) === false)
             return undefined;
-        if (!(segment in current))
+        if (!Object.hasOwn(current, segment))
             return undefined;
         current = current[segment];
     }
-    return current;
+    return current === undefined ? undefined : { pointer, value: current };
 };
 const isInventory = (value) => "operations" in value;
 const isProblem = (value) => "message" in value;