@nestia/sdk 14.0.1 → 14.0.2

package/lib/utils/EmittedJavaScriptPatcher.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Patches JavaScript emitted into a temporary directory so that it loads as
+ * CommonJS.
+ *
+ * @evidence contracts/common.md#principled-implementation A compiler can keep `import.meta.url` in CommonJS output, and Node then detects the file as ESM before `require()` loads it, so the token is replaced by an expression that gives the same URL.
+ * @evidence contracts/common.md#clear-and-simple-design One public function collects emitted files and a JavaScript parser identifies import.meta.url expressions by their syntax nodes; source slices retain all unrelated text.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The patch changes only the temporary emit. The parser reads JavaScript grammar, so regular expressions after control-flow statements and property names resembling import.meta.url remain untouched; no previous-token approximation substitutes for parsing.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Entries are listed with `readdir` and joined with `path.join`; only regular `.js` and `.cjs` files, named case-insensitively, are read and rewritten as UTF-8, and symbolic links and other entry kinds are left alone. The replacement derives the file URL with `url.pathToFileURL(__filename)`, the platform's own conversion, so drive letters, UNC paths and percent-encoding follow the rules of `import.meta.url`. The text outside the token, line endings included, is preserved.
+ */
 export declare namespace EmittedJavaScriptPatcher {
+    /**
+     * Replaces every `import.meta.url` in the `.js` and `.cjs` files under a
+     * directory with `require("url").pathToFileURL(__filename).href`.
+     *
+     * @evidence contracts/common.md#principled-implementation The parser selects only a non-computed url property whose object is the import.meta meta-property, including spaced expressions and template substitutions. Literal and comment text is never an expression node, and the replacement derives the executing CommonJS file URL.
+     * @evidence contracts/common.md#clear-and-simple-design One function collects files and delegates expression detection to the JavaScript grammar parser.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It patches only files that contain the token.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the replacement and the scope.
+     * @evidence contracts/portability.md#os-neutral-implementation Files are read and rewritten concurrently without locking, one pending operation per file, so the caller must be the only writer of the directory, as it is for its own temporary emit.
+     */
     const importMetaUrl: (root: string) => Promise<void>;
 }

package/lib/utils/EmittedJavaScriptPatcher.js

@@ -13,16 +13,36 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmittedJavaScriptPatcher = void 0;
+const parser_1 = require("@babel/parser");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Patches JavaScript emitted into a temporary directory so that it loads as
+ * CommonJS.
+ *
+ * @evidence contracts/common.md#principled-implementation A compiler can keep `import.meta.url` in CommonJS output, and Node then detects the file as ESM before `require()` loads it, so the token is replaced by an expression that gives the same URL.
+ * @evidence contracts/common.md#clear-and-simple-design One public function collects emitted files and a JavaScript parser identifies import.meta.url expressions by their syntax nodes; source slices retain all unrelated text.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The patch changes only the temporary emit. The parser reads JavaScript grammar, so regular expressions after control-flow statements and property names resembling import.meta.url remain untouched; no previous-token approximation substitutes for parsing.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Entries are listed with `readdir` and joined with `path.join`; only regular `.js` and `.cjs` files, named case-insensitively, are read and rewritten as UTF-8, and symbolic links and other entry kinds are left alone. The replacement derives the file URL with `url.pathToFileURL(__filename)`, the platform's own conversion, so drive letters, UNC paths and percent-encoding follow the rules of `import.meta.url`. The text outside the token, line endings included, is preserved.
+ */
 var EmittedJavaScriptPatcher;
 (function (EmittedJavaScriptPatcher) {
+    /**
+     * Replaces every `import.meta.url` in the `.js` and `.cjs` files under a
+     * directory with `require("url").pathToFileURL(__filename).href`.
+     *
+     * @evidence contracts/common.md#principled-implementation The parser selects only a non-computed url property whose object is the import.meta meta-property, including spaced expressions and template substitutions. Literal and comment text is never an expression node, and the replacement derives the executing CommonJS file URL.
+     * @evidence contracts/common.md#clear-and-simple-design One function collects files and delegates expression detection to the JavaScript grammar parser.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It patches only files that contain the token.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the replacement and the scope.
+     * @evidence contracts/portability.md#os-neutral-implementation Files are read and rewritten concurrently without locking, one pending operation per file, so the caller must be the only writer of the directory, as it is for its own temporary emit.
+     */
     EmittedJavaScriptPatcher.importMetaUrl = (root) => __awaiter(this, void 0, void 0, function* () {
         const files = yield collect(root);
         yield Promise.all(files.map(patch));
     });
 })(EmittedJavaScriptPatcher || (exports.EmittedJavaScriptPatcher = EmittedJavaScriptPatcher = {}));
-const TARGET = "import.meta.url";
 // TypeScript can preserve this token even in CommonJS output. Node 24 then
 // syntax-detects the temporary `.js` file as ESM before require() can load it.
 const REPLACEMENT = 'require("url").pathToFileURL(__filename).href';
@@ -42,59 +62,58 @@ const collect = (location) => __awaiter(void 0, void 0, void 0, function* () {
 });
 const patch = (file) => __awaiter(void 0, void 0, void 0, function* () {
     const before = yield fs_1.default.promises.readFile(file, "utf8");
-    if (before.includes(TARGET) === false)
+    if (before.includes("import") === false)
         return;
     const after = replaceImportMetaUrl(before);
     if (after !== before)
         yield fs_1.default.promises.writeFile(file, after, "utf8");
 });
+// Parse module expressions without imposing module strictness: TypeScript may preserve
+// import.meta in otherwise CommonJS output. Top-level return is valid inside
+// Node's CommonJS wrapper. The parser, rather than token context guesses, owns
+// the distinction between regular expressions, divisions and property names.
 const replaceImportMetaUrl = (input) => {
-    let output = "";
-    let cursor = 0;
-    for (let i = 0; i < input.length;) {
-        if (isTarget(input, i)) {
-            output += input.slice(cursor, i);
-            output += REPLACEMENT;
-            i += TARGET.length;
-            cursor = i;
-            continue;
+    var _a, _b;
+    const root = (0, parser_1.parse)(input, {
+        sourceType: "module",
+        strictMode: false,
+        attachComment: false,
+        allowImportExportEverywhere: true,
+        allowReturnOutsideFunction: true,
+        allowAwaitOutsideFunction: true,
+    });
+    const spans = [];
+    const pending = [root];
+    while (pending.length !== 0) {
+        const node = pending.pop();
+        if (node.type === "MemberExpression" &&
+            node.computed === false &&
+            ((_a = node.property) === null || _a === void 0 ? void 0 : _a.type) === "Identifier" &&
+            node.property.name === "url" &&
+            ((_b = node.object) === null || _b === void 0 ? void 0 : _b.type) === "MetaProperty" &&
+            node.object.meta.name === "import" &&
+            node.object.property.name === "meta")
+            spans.push({ start: node.start, end: node.end });
+        for (const value of Object.values(node)) {
+            if (Array.isArray(value)) {
+                for (const child of value)
+                    if (child && typeof child.type === "string")
+                        pending.push(child);
+            }
+            else if (value &&
+                typeof value === "object" &&
+                typeof value.type === "string")
+                pending.push(value);
         }
-        const ch = input[i];
-        const next = input[i + 1];
-        if (ch === '"' || ch === "'")
-            i = skipQuoted(input, i, ch);
-        else if (ch === "/" && next === "/")
-            i = skipLineComment(input, i);
-        else if (ch === "/" && next === "*")
-            i = skipBlockComment(input, i);
-        else
-            ++i;
     }
-    return output + input.slice(cursor);
-};
-const isTarget = (input, index) => input.startsWith(TARGET, index) &&
-    isBoundary(input[index - 1]) &&
-    isBoundary(input[index + TARGET.length]);
-const isBoundary = (ch) => ch === undefined || /[^A-Za-z0-9_$]/.test(ch);
-const skipQuoted = (input, index, quote) => {
-    let escaped = false;
-    for (let i = index + 1; i < input.length; ++i) {
-        const ch = input[i];
-        if (escaped)
-            escaped = false;
-        else if (ch === "\\")
-            escaped = true;
-        else if (ch === quote)
-            return i + 1;
+    spans.sort((a, b) => a.start - b.start);
+    const pieces = [];
+    let cursor = 0;
+    for (const span of spans) {
+        pieces.push(input.slice(cursor, span.start), REPLACEMENT);
+        cursor = span.end;
     }
-    return input.length;
-};
-const skipLineComment = (input, index) => {
-    const found = input.indexOf("\n", index + 2);
-    return found === -1 ? input.length : found + 1;
-};
-const skipBlockComment = (input, index) => {
-    const found = input.indexOf("*/", index + 2);
-    return found === -1 ? input.length : found + 2;
+    pieces.push(input.slice(cursor));
+    return pieces.join("");
 };
 //# sourceMappingURL=EmittedJavaScriptPatcher.js.map

package/lib/utils/EmittedJavaScriptPatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"EmittedJavaScriptPatcher.js","sourceRoot":"","sources":["../../src/utils/EmittedJavaScriptPatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EmittedJavaScriptPatcher.js","sourceRoot":"","sources":["../../src/utils/EmittedJavaScriptPatcher.ts"],"names":[],"mappings":"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"}

package/lib/utils/FileRetriever.d.ts

@@ -1,4 +1,33 @@
+/**
+ * Finds a file or a directory by name, in a directory and up to three parents.
+ *
+ * @evidence contracts/common.md#principled-implementation The search checks a directory and then goes to its parent, at most three levels up, which is where a project's own files are expected.
+ * @evidence contracts/common.md#clear-and-simple-design Two curried functions with the same recursion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The limit is a fixed search depth, not a file name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Names are joined to directories with `path.join` and tested with `existsSync`, so the volume decides what a name matches and under which case policy. The parent is `path.join(dir, "..")`, which stays at a filesystem root, and the depth counter bounds the climb, so no drive letter or separator test is needed. Directories are returned as joined, not canonicalized, so equal locations reached through links or a different case may compare unequal.
+ */
 export declare namespace FileRetriever {
+    /**
+     * Returns the nearest directory, from the given one up to three parents, that
+     * contains an entry with the name, or `null`.
+     *
+     * @evidence contracts/common.md#principled-implementation The recursion is bounded by the depth counter, so it terminates at the filesystem root as well.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The bound is explicit.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation The result is the directory as the caller spelled it joined with `..` steps; the existence test of the named entry alone decides, under the filesystem's own case policy.
+     */
     const directory: (name: string) => (dir: string, depth?: number) => string | null;
+    /**
+     * Returns the path of the nearest existing entry with the name, from the
+     * given directory up to three parents, or `null`.
+     *
+     * @evidence contracts/common.md#principled-implementation The recursion is bounded by the depth counter.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The bound is explicit.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation The result is the native path of the entry as joined, found by the filesystem's own existence test and not canonicalized.
+     */
     const file: (name: string) => (directory: string, depth?: number) => string | null;
 }

package/lib/utils/FileRetriever.js

@@ -6,8 +6,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileRetriever = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Finds a file or a directory by name, in a directory and up to three parents.
+ *
+ * @evidence contracts/common.md#principled-implementation The search checks a directory and then goes to its parent, at most three levels up, which is where a project's own files are expected.
+ * @evidence contracts/common.md#clear-and-simple-design Two curried functions with the same recursion.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The limit is a fixed search depth, not a file name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Names are joined to directories with `path.join` and tested with `existsSync`, so the volume decides what a name matches and under which case policy. The parent is `path.join(dir, "..")`, which stays at a filesystem root, and the depth counter bounds the climb, so no drive letter or separator test is needed. Directories are returned as joined, not canonicalized, so equal locations reached through links or a different case may compare unequal.
+ */
 var FileRetriever;
 (function (FileRetriever) {
+    /**
+     * Returns the nearest directory, from the given one up to three parents, that
+     * contains an entry with the name, or `null`.
+     *
+     * @evidence contracts/common.md#principled-implementation The recursion is bounded by the depth counter, so it terminates at the filesystem root as well.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The bound is explicit.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation The result is the directory as the caller spelled it joined with `..` steps; the existence test of the named entry alone decides, under the filesystem's own case policy.
+     */
     FileRetriever.directory = (name) => (dir, depth = 0) => {
         const location = path_1.default.join(dir, name);
         if (fs_1.default.existsSync(location))
@@ -16,6 +35,16 @@ var FileRetriever;
             return null;
         return FileRetriever.directory(name)(path_1.default.join(dir, ".."), depth + 1);
     };
+    /**
+     * Returns the path of the nearest existing entry with the name, from the
+     * given directory up to three parents, or `null`.
+     *
+     * @evidence contracts/common.md#principled-implementation The recursion is bounded by the depth counter.
+     * @evidence contracts/common.md#clear-and-simple-design One function.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The bound is explicit.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation The result is the native path of the entry as joined, found by the filesystem's own existence test and not canonicalized.
+     */
     FileRetriever.file = (name) => (directory, depth = 0) => {
         const location = path_1.default.join(directory, name);
         if (fs_1.default.existsSync(location))

package/lib/utils/FileRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"FileRetriever.js","sourceRoot":"","sources":["../../src/utils/FileRetriever.ts"],"names":[],"mappings":";;;;;;AAAA,4CAAoB;AACpB,gDAAwB;AAExB,IAAiB,aAAa,CAkB7B;AAlBD,WAAiB,aAAa;IACf,uBAAS,GACpB,CAAC,IAAY,EAAE,EAAE,CACjB,CAAC,GAAW,EAAE,KAAK,GAAW,CAAC,EAAiB,EAAE;QAChD,MAAM,QAAQ,GAAW,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,GAAG,CAAC;aACnC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,uBAAS,CAAC,IAAI,CAAC,CAAC,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IAES,kBAAI,GACf,CAAC,IAAY,EAAE,EAAE,CACjB,CAAC,SAAiB,EAAE,KAAK,GAAW,CAAC,EAAiB,EAAE;QACtD,MAAM,QAAQ,GAAW,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACpD,IAAI,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;aACxC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,kBAAI,CAAC,IAAI,CAAC,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC;AACN,CAAC,EAlBgB,aAAa,aAAb,aAAa,GAAb,aAAa,QAkB7B"}
+{"version":3,"file":"FileRetriever.js","sourceRoot":"","sources":["../../src/utils/FileRetriever.ts"],"names":[],"mappings":";;;;;;AAAA,4CAAoB;AACpB,gDAAwB;AAExB;;;;;;;;GAQG;AACH,IAAiB,aAAa,CAsC7B;AAtCD,WAAiB,aAAa;IAC5B;;;;;;;;;OASG;IACU,uBAAS,GACpB,CAAC,IAAY,EAAE,EAAE,CACjB,CAAC,GAAW,EAAE,KAAK,GAAW,CAAC,EAAiB,EAAE;QAChD,MAAM,QAAQ,GAAW,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,GAAG,CAAC;aACnC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,uBAAS,CAAC,IAAI,CAAC,CAAC,cAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IAEJ;;;;;;;;;OASG;IACU,kBAAI,GACf,CAAC,IAAY,EAAE,EAAE,CACjB,CAAC,SAAiB,EAAE,KAAK,GAAW,CAAC,EAAiB,EAAE;QACtD,MAAM,QAAQ,GAAW,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACpD,IAAI,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;aACxC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO,kBAAI,CAAC,IAAI,CAAC,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC;AACN,CAAC,EAtCgB,aAAa,aAAb,aAAa,GAAb,aAAa,QAsC7B"}

package/lib/utils/HttpResponseContentTypeUtil.d.ts

@@ -1,5 +1,46 @@
+/**
+ * Classifies the content type of a response.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace decides which content types the SDK supports and which are binary.
+ * @evidence contracts/common.md#clear-and-simple-design One type and two predicates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is media types, not routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+ */
 export declare namespace HttpResponseContentTypeUtil {
+    /**
+     * A response content type: JSON, text, urlencoded, another string, or `null`
+     * for no body.
+     *
+     * @evidence contracts/common.md#principled-implementation The union keeps the common types visible while allowing any other string.
+     * @evidence contracts/common.md#clear-and-simple-design One union.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment names the cases.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.Response classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+     */
     type Response = "application/json" | "text/plain" | "application/x-www-form-urlencoded" | (string & {}) | null;
+    /**
+     * Reports whether the SDK supports the content type: none, JSON, plain text,
+     * urlencoded, or a binary type.
+     *
+     * @evidence contracts/common.md#principled-implementation The content type is compared exactly for the three text types and by the binary rule otherwise.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is the supported set.
+     * @evidence contracts/common.md#meaningful-documentation The comment lists the supported types.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.isSupported classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+     */
     const isSupported: (input: string | null) => input is Response;
+    /**
+     * Reports whether the content type is binary: an image, video, or audio type,
+     * an octet stream, or a PDF.
+     *
+     * Parameters and case are ignored.
+     *
+     * @evidence contracts/common.md#principled-implementation The type is the text before the first `;`, trimmed and lower-cased, as HTTP defines a media type.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is a list of media types.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the binary types and the normalization.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.isBinary classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+     */
     const isBinary: (input: string | null | undefined) => input is string;
 }

package/lib/utils/HttpResponseContentTypeUtil.js

@@ -1,13 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpResponseContentTypeUtil = void 0;
+/**
+ * Classifies the content type of a response.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace decides which content types the SDK supports and which are binary.
+ * @evidence contracts/common.md#clear-and-simple-design One type and two predicates.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is media types, not routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+ */
 var HttpResponseContentTypeUtil;
 (function (HttpResponseContentTypeUtil) {
+    /**
+     * Reports whether the SDK supports the content type: none, JSON, plain text,
+     * urlencoded, or a binary type.
+     *
+     * @evidence contracts/common.md#principled-implementation The content type is compared exactly for the three text types and by the binary rule otherwise.
+     * @evidence contracts/common.md#clear-and-simple-design One expression.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is the supported set.
+     * @evidence contracts/common.md#meaningful-documentation The comment lists the supported types.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.isSupported classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+     */
     HttpResponseContentTypeUtil.isSupported = (input) => input === null ||
         input === "application/json" ||
         input === "text/plain" ||
         input === "application/x-www-form-urlencoded" ||
         HttpResponseContentTypeUtil.isBinary(input);
+    /**
+     * Reports whether the content type is binary: an image, video, or audio type,
+     * an octet stream, or a PDF.
+     *
+     * Parameters and case are ignored.
+     *
+     * @evidence contracts/common.md#principled-implementation The type is the text before the first `;`, trimmed and lower-cased, as HTTP defines a media type.
+     * @evidence contracts/common.md#clear-and-simple-design One predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is a list of media types.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the binary types and the normalization.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation HttpResponseContentTypeUtil.isBinary classifies HTTP response metadata and MIME types, which have protocol semantics independent of the native filesystem.
+     */
     HttpResponseContentTypeUtil.isBinary = (input) => {
         if (typeof input !== "string")
             return false;

package/lib/utils/HttpResponseContentTypeUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpResponseContentTypeUtil.js","sourceRoot":"","sources":["../../src/utils/HttpResponseContentTypeUtil.ts"],"names":[],"mappings":";;;AAAA,IAAiB,2BAA2B,CA6B3C;AA7BD,WAAiB,2BAA2B;IAQ7B,uCAAW,GAAG,CAAC,KAAoB,EAAqB,EAAE,CACrE,KAAK,KAAK,IAAI;QACd,KAAK,KAAK,kBAAkB;QAC5B,KAAK,KAAK,YAAY;QACtB,KAAK,KAAK,mCAAmC;QAC7C,oCAAQ,CAAC,KAAK,CAAC,CAAC;IAEL,oCAAQ,GAAG,CACtB,KAAgC,EACf,EAAE;QACnB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAE5C,MAAM,KAAK,GAAW,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAChE,OAAO,CACL,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,KAAK,KAAK,0BAA0B;YACpC,KAAK,KAAK,iBAAiB,CAC5B,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,EA7BgB,2BAA2B,aAA3B,2BAA2B,GAA3B,2BAA2B,QA6B3C"}
+{"version":3,"file":"HttpResponseContentTypeUtil.js","sourceRoot":"","sources":["../../src/utils/HttpResponseContentTypeUtil.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAiB,2BAA2B,CA6D3C;AA7DD,WAAiB,2BAA2B;IAkB1C;;;;;;;;;OASG;IACU,uCAAW,GAAG,CAAC,KAAoB,EAAqB,EAAE,CACrE,KAAK,KAAK,IAAI;QACd,KAAK,KAAK,kBAAkB;QAC5B,KAAK,KAAK,YAAY;QACtB,KAAK,KAAK,mCAAmC;QAC7C,oCAAQ,CAAC,KAAK,CAAC,CAAC;IAElB;;;;;;;;;;;OAWG;IACU,oCAAQ,GAAG,CACtB,KAAgC,EACf,EAAE;QACnB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAE5C,MAAM,KAAK,GAAW,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAChE,OAAO,CACL,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1B,KAAK,KAAK,0BAA0B;YACpC,KAAK,KAAK,iBAAiB,CAC5B,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,EA7DgB,2BAA2B,aAA3B,2BAA2B,GAA3B,2BAA2B,QA6D3C"}

package/lib/utils/MapUtil.d.ts

@@ -1,3 +1,66 @@
+/**
+ * Helpers for maps.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the get-or-create helper.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain helper.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+ */
 export declare namespace MapUtil {
-    function take<Key, T>(dict: Map<Key, T>, key: Key, generator: () => T): T;
+    /**
+     * Returns the value of a key, creating and storing it when the key is absent.
+     *
+     * Presence is tested with `has`, so a stored falsy value is not created
+     * again. The dictionary may be a `Map` or a `WeakMap`, so a cache keyed by
+     * object identity can leave its entries to the garbage collector.
+     *
+     * @evidence contracts/common.md#principled-implementation The generator runs once per key and its result is stored as it is, in any dictionary with the three members it uses, so the retention of the entries stays the choice of the caller's dictionary.
+     * @evidence contracts/common.md#clear-and-simple-design One check, one call, and one store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The stored value is returned unchanged.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the presence rule.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.take reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+     */
+    function take<Key, T>(dict: IDictionary<Key, T>, key: Key, generator: () => T): T;
+    /**
+     * The members of a `Map` or a `WeakMap` that {@link take} reads and writes.
+     *
+     * @evidence contracts/common.md#principled-implementation The three members are the presence test, the read and the store that the get-or-create rule needs, and both `Map` and `WeakMap` provide them with these signatures.
+     * @evidence contracts/common.md#clear-and-simple-design A structural type of three members, so no wrapper or second helper is needed for a weakly keyed cache.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment names the two dictionaries it admits and the operations it needs.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+     */
+    interface IDictionary<Key, T> {
+        /**
+         * Whether the key is present, including a key whose value is `undefined`.
+         *
+         * @evidence contracts/common.md#principled-implementation Presence is a separate question from the stored value, which is what lets a stored falsy value count as present.
+         * @evidence contracts/common.md#clear-and-simple-design One member with the signature that `Map` and `WeakMap` share.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a signature and adds no runtime behavior.
+         * @evidence contracts/common.md#meaningful-documentation The comment states what the member answers or does for {@link take}.
+         * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary.has reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+         */
+        has(key: Key): boolean;
+        /**
+         * The value stored for the key, or `undefined` when it is absent.
+         *
+         * @evidence contracts/common.md#principled-implementation The read is only made after a presence test, so `undefined` here always means a stored value.
+         * @evidence contracts/common.md#clear-and-simple-design One member with the signature that `Map` and `WeakMap` share.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a signature and adds no runtime behavior.
+         * @evidence contracts/common.md#meaningful-documentation The comment states what the member answers or does for {@link take}.
+         * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary.get reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+         */
+        get(key: Key): T | undefined;
+        /**
+         * Stores the value for the key; the result is ignored.
+         *
+         * @evidence contracts/common.md#principled-implementation The store is the one effect of the get-or-create rule, and the return type is not read because `Map.set` and `WeakMap.set` return different receivers.
+         * @evidence contracts/common.md#clear-and-simple-design One member with the signature that `Map` and `WeakMap` share.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a signature and adds no runtime behavior.
+         * @evidence contracts/common.md#meaningful-documentation The comment states what the member answers or does for {@link take}.
+         * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.IDictionary.set reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+         */
+        set(key: Key, value: T): unknown;
+    }
 }

package/lib/utils/MapUtil.js

@@ -1,12 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapUtil = void 0;
+/**
+ * Helpers for maps.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the get-or-create helper.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain helper.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+ */
 var MapUtil;
 (function (MapUtil) {
+    /**
+     * Returns the value of a key, creating and storing it when the key is absent.
+     *
+     * Presence is tested with `has`, so a stored falsy value is not created
+     * again. The dictionary may be a `Map` or a `WeakMap`, so a cache keyed by
+     * object identity can leave its entries to the garbage collector.
+     *
+     * @evidence contracts/common.md#principled-implementation The generator runs once per key and its result is stored as it is, in any dictionary with the three members it uses, so the retention of the entries stays the choice of the caller's dictionary.
+     * @evidence contracts/common.md#clear-and-simple-design One check, one call, and one store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The stored value is returned unchanged.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the presence rule.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation MapUtil.take reads or initializes caller-supplied map entries; it neither interprets keys as native path identities nor owns a process boundary.
+     */
     function take(dict, key, generator) {
-        const oldbie = dict.get(key);
-        if (oldbie)
-            return oldbie;
+        if (dict.has(key))
+            return dict.get(key);
         const value = generator();
         dict.set(key, value);
         return value;

package/lib/utils/MapUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"MapUtil.js","sourceRoot":"","sources":["../../src/utils/MapUtil.ts"],"names":[],"mappings":";;;AAAA,IAAiB,OAAO,CAavB;AAbD,WAAiB,OAAO;IACtB,SAAgB,IAAI,CAClB,IAAiB,EACjB,GAAQ,EACR,SAAkB;QAElB,MAAM,MAAM,GAAkB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAE1B,MAAM,KAAK,GAAM,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAXe,QAAA,IAAI,OAWnB,CAAA;AACH,CAAC,EAbgB,OAAO,aAAP,OAAO,GAAP,OAAO,QAavB"}
+{"version":3,"file":"MapUtil.js","sourceRoot":"","sources":["../../src/utils/MapUtil.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,IAAiB,OAAO,CAqEvB;AArED,WAAiB,OAAO;IACtB;;;;;;;;;;;;OAYG;IACH,SAAgB,IAAI,CAClB,IAAyB,EACzB,GAAQ,EACR,SAAkB;QAElB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QAE7C,MAAM,KAAK,GAAM,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAVe,QAAA,IAAI,OAUnB,CAAA;AA6CH,CAAC,EArEgB,OAAO,aAAP,OAAO,GAAP,OAAO,QAqEvB"}

package/lib/utils/PathUtil.d.ts

@@ -1,3 +1,34 @@
+/**
+ * Helpers for route paths used as accessors, and for source file locations.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns a path into accessor names and a source location into a plain path.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts They are plain helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Route accessor spelling uses protocol slashes, while source file URLs are decoded with Node fileURLToPath before native separators are rendered as forward slashes. These operations do not infer filesystem identity or case policy from spelling.
+ */
 export declare namespace PathUtil {
+    /**
+     * Returns the accessor segments of a path: the segments that are not empty
+     * and not parameters, with dashes and dots replaced by underscores.
+     *
+     * @evidence contracts/common.md#principled-implementation Parameters do not name a namespace and the replaced characters are not valid in an identifier.
+     * @evidence contracts/common.md#clear-and-simple-design One pipeline.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule applies to every path.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This function processes route URL segments rather than native filesystem paths or identities.
+     */
     const accessors: (path: string) => string[];
+    /**
+     * Returns the plain path of a source location: a `file:` URL is decoded to
+     * the path it names, with forward slashes, and any other text is returned as
+     * it is.
+     *
+     * @evidence contracts/common.md#principled-implementation A file URL is percent-encoded, so a path with a space or a non-ASCII character reads back only through the URL decoder, and the platform separator is replaced so the result is the same on every platform.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional over the standard decoder.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only a `file:` location is decoded; a plain path is never altered.
+     * @evidence contracts/common.md#meaningful-documentation The comment states both inputs and the separator.
+     * @evidence contracts/portability.md#os-neutral-implementation Node fileURLToPath handles platform-specific drive and UNC URL forms and percent decoding. The resulting native separators are rendered as forward slashes for source-location metadata; plain paths keep their original spelling and no filesystem identity comparison is attempted.
+     */
+    const location: (str: string) => string;
 }

package/lib/utils/PathUtil.js

@@ -1,12 +1,50 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PathUtil = void 0;
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
+/**
+ * Helpers for route paths used as accessors, and for source file locations.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns a path into accessor names and a source location into a plain path.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts They are plain helpers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Route accessor spelling uses protocol slashes, while source file URLs are decoded with Node fileURLToPath before native separators are rendered as forward slashes. These operations do not infer filesystem identity or case policy from spelling.
+ */
 var PathUtil;
 (function (PathUtil) {
+    /**
+     * Returns the accessor segments of a path: the segments that are not empty
+     * and not parameters, with dashes and dots replaced by underscores.
+     *
+     * @evidence contracts/common.md#principled-implementation Parameters do not name a namespace and the replaced characters are not valid in an identifier.
+     * @evidence contracts/common.md#clear-and-simple-design One pipeline.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule applies to every path.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This function processes route URL segments rather than native filesystem paths or identities.
+     */
     PathUtil.accessors = (path) => path
         .split("/")
         .filter((str) => str.length && str[0] !== ":")
         .map(normalize);
+    /**
+     * Returns the plain path of a source location: a `file:` URL is decoded to
+     * the path it names, with forward slashes, and any other text is returned as
+     * it is.
+     *
+     * @evidence contracts/common.md#principled-implementation A file URL is percent-encoded, so a path with a space or a non-ASCII character reads back only through the URL decoder, and the platform separator is replaced so the result is the same on every platform.
+     * @evidence contracts/common.md#clear-and-simple-design One conditional over the standard decoder.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Only a `file:` location is decoded; a plain path is never altered.
+     * @evidence contracts/common.md#meaningful-documentation The comment states both inputs and the separator.
+     * @evidence contracts/portability.md#os-neutral-implementation Node fileURLToPath handles platform-specific drive and UNC URL forms and percent decoding. The resulting native separators are rendered as forward slashes for source-location metadata; plain paths keep their original spelling and no filesystem identity comparison is attempted.
+     */
+    PathUtil.location = (str) => str.startsWith("file:")
+        ? (0, url_1.fileURLToPath)(str).split(path_1.default.sep).join("/")
+        : str;
     const normalize = (str) => str.split("-").join("_").split(".").join("_");
 })(PathUtil || (exports.PathUtil = PathUtil = {}));
 //# sourceMappingURL=PathUtil.js.map

package/lib/utils/PathUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"PathUtil.js","sourceRoot":"","sources":["../../src/utils/PathUtil.ts"],"names":[],"mappings":";;;AAAA,IAAiB,QAAQ,CASxB;AATD,WAAiB,QAAQ;IACV,kBAAS,GAAG,CAAC,IAAY,EAAE,EAAE,CACxC,IAAI;SACD,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;SAC7C,GAAG,CAAC,SAAS,CAAC,CAAC;IAEpB,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,EAAE,CAChC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC,EATgB,QAAQ,aAAR,QAAQ,GAAR,QAAQ,QASxB"}
+{"version":3,"file":"PathUtil.js","sourceRoot":"","sources":["../../src/utils/PathUtil.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AACxB,6BAAoC;AAEpC;;;;;;;;GAQG;AACH,IAAiB,QAAQ,CAmCxB;AAnCD,WAAiB,QAAQ;IACvB;;;;;;;;;OASG;IACU,kBAAS,GAAG,CAAC,IAAY,EAAE,EAAE,CACxC,IAAI;SACD,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;SAC7C,GAAG,CAAC,SAAS,CAAC,CAAC;IAEpB;;;;;;;;;;OAUG;IACU,iBAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CAC9C,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;QACrB,CAAC,CAAC,IAAA,mBAAa,EAAC,GAAG,CAAC,CAAC,KAAK,CAAC,cAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAC9C,CAAC,CAAC,GAAG,CAAC;IAEV,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,EAAE,CAChC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC,EAnCgB,QAAQ,aAAR,QAAQ,GAAR,QAAQ,QAmCxB"}

package/lib/utils/SdkBundlePath.d.ts

@@ -0,0 +1,2 @@
+/** The installed API bundle shared by SDK emission and source exclusion. */
+export declare const SDK_BUNDLE_PATH: string;

package/lib/utils/SdkBundlePath.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_BUNDLE_PATH = void 0;
+const path_1 = __importDefault(require("path"));
+/** The installed API bundle shared by SDK emission and source exclusion. */
+exports.SDK_BUNDLE_PATH = path_1.default.join(__dirname, "..", "..", "assets", "bundle", "api");
+//# sourceMappingURL=SdkBundlePath.js.map

package/lib/utils/SdkBundlePath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SdkBundlePath.js","sourceRoot":"","sources":["../../src/utils/SdkBundlePath.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAwB;AAExB,4EAA4E;AAC/D,QAAA,eAAe,GAAW,cAAI,CAAC,IAAI,CAC9C,SAAS,EACT,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,KAAK,CACN,CAAC"}