@nestia/sdk 14.0.1 → 14.0.3

package/src/structures/ITypedHttpRouteSuccess.ts

@@ -4,6 +4,16 @@ import { MetadataSchema } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A typed success response: its type, status, content type, binary and
+ * encrypted flags, metadata, examples, and header directives.
+ *
+ * @evidence contracts/common.md#principled-implementation The header directives are the `@setHeader` and `@assignHeaders` tags, which the SDK function applies to the connection.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedHttpRouteSuccess describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedHttpRouteSuccess {
   type: IReflectType;
   status: number | null;

package/src/structures/ITypedMcpRoute.ts

@@ -1,5 +1,6 @@
 import { IJsDocTagInfo } from "typia";
 
+import { MetadataSchema } from "../internal/legacy";
 import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperation } from "./IReflectMcpOperation";
@@ -12,6 +13,12 @@ import { IReflectType } from "./IReflectType";
  * Carries everything the SDK generator needs to emit a typed client function:
  * the controller reference, accessor path, typia-derived input schema, and
  * input/output type info.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the tool operation in the form the SDK generator reads.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedMcpRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface ITypedMcpRoute {
   protocol: "mcp";
@@ -24,6 +31,11 @@ export interface ITypedMcpRoute {
   function: Function;
   input: IReflectMcpOperationParameter | null;
   returnType: IReflectType | null;
+  /** Resolved JSON wire graphs used by structural DTO cloning. */
+  inputMetadata?: MetadataSchema;
+
+  /** Absent when source-only analysis was requested without cloning. */
+  outputMetadata?: MetadataSchema;
   inputSchema: object;
   outputSchema: object | null;
   annotations: IReflectMcpOperation.IAnnotations | null;

package/src/structures/ITypedWebSocketRoute.ts

@@ -5,6 +5,16 @@ import { IReflectController } from "./IReflectController";
 import { IReflectImport } from "./IReflectImport";
 import { ITypedWebSocketRouteParameter } from "./ITypedWebSocketRouteParameter";
 
+/**
+ * A typed WebSocket route: one path with its acceptor, header, path parameters,
+ * query, and driver separated.
+ *
+ * @evidence contracts/common.md#principled-implementation The reflected operation is expanded per path and its parameters are classified.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ITypedWebSocketRoute describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface ITypedWebSocketRoute {
   protocol: "websocket";
   controller: IReflectController;

package/src/transform.ts

@@ -11,6 +11,12 @@ import type { ITtscPlugin, ITtscPluginFactoryContext } from "ttsc";
  * contributor — but only for projects that actually depend on `@nestia/sdk`. A
  * project depending on `@nestia/core` alone never links, compiles, or ships any
  * of this SDK transform code.
+ *
+ * @evidence contracts/common.md#principled-implementation The package root is resolved through `@nestia/sdk/package.json` from the consumer's project, so the source path is the installed package's, not a workspace layout, and the descriptor returns only a name and a source directory.
+ * @evidence contracts/common.md#clear-and-simple-design One function returning two properties; the transform itself is native.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The resolution goes through the package manifest, as the development rules require, and nothing is patched.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the descriptor returns.
+ * @evidence contracts/portability.md#os-neutral-implementation createRequire anchors package resolution to the consumer project's package.json; Node resolution yields the installed manifest's native pathname and path.dirname/path.resolve derive the contributor source without a workspace-specific separator or shell lookup.
  */
 export default function createTtscPlugin(
   context: ITtscPluginFactoryContext,

package/src/utils/ArrayUtil.ts

@@ -1,10 +1,39 @@
+/**
+ * Array helpers of the SDK generator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds a membership test and a sequential asynchronous map.
+ * @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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+ */
 export namespace ArrayUtil {
+  /**
+   * Reports whether the array contains every one of the items.
+   *
+   * Membership uses `includes`, so an `undefined` or `NaN` item is found when
+   * the array holds it.
+   *
+   * @evidence contracts/common.md#principled-implementation `Array.prototype.includes` compares by SameValueZero and the result is the conjunction over the items.
+   * @evidence contracts/common.md#clear-and-simple-design One `every` over `includes`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No item is special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the conjunction and the comparison.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.has operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+   */
   export function has<T>(array: T[], ...items: T[]): boolean {
-    return items.every(
-      (elem) => array.find((org) => org === elem) !== undefined,
-    );
+    return items.every((item) => array.includes(item));
   }
 
+  /**
+   * Maps the elements with an asynchronous function, one after another, and
+   * returns the results in order.
+   *
+   * @evidence contracts/common.md#principled-implementation Each call is awaited before the next starts, so the order of the results is the order of the elements and a rejection stops the mapping.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No element is skipped or retried.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the sequential order.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ArrayUtil.asyncMap operates on caller-supplied arrays and promises without resolving file identity or launching a process; callback boundaries remain the caller's responsibility.
+   */
   export async function asyncMap<X, Y>(
     array: X[],
     closure: (input: X) => Promise<Y>,
@@ -13,14 +42,4 @@ export namespace ArrayUtil {
     for (const elem of array) ret.push(await closure(elem));
     return ret;
   }
-
-  export async function asyncFilter<T>(
-    array: T[],
-    closure: (input: T) => Promise<boolean>,
-  ): Promise<T[]> {
-    const ret: T[] = [];
-    for (const elem of array)
-      if ((await closure(elem)) === true) ret.push(elem);
-    return ret;
-  }
 }

package/src/utils/EmittedJavaScriptPatcher.ts

@@ -1,14 +1,34 @@
+import { parse } from "@babel/parser";
 import fs from "fs";
 import path from "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.
+ */
 export 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.
+   */
   export const importMetaUrl = async (root: string): Promise<void> => {
     const files: string[] = await collect(root);
     await Promise.all(files.map(patch));
   };
 }
 
-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';
@@ -30,59 +50,62 @@ const collect = async (location: string): Promise<string[]> => {
 
 const patch = async (file: string): Promise<void> => {
   const before: string = await fs.promises.readFile(file, "utf8");
-  if (before.includes(TARGET) === false) return;
+  if (before.includes("import") === false) return;
 
   const after: string = replaceImportMetaUrl(before);
   if (after !== before) await fs.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: string): string => {
-  let output: string = "";
-  let cursor: number = 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;
+  const root = parse(input, {
+    sourceType: "module",
+    strictMode: false,
+    attachComment: false,
+    allowImportExportEverywhere: true,
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+  });
+  const spans: Array<{ start: number; end: number }> = [];
+  const pending: Array<{
+    type: string;
+    start?: number | null;
+    end?: number | null;
+  }> = [root];
+  while (pending.length !== 0) {
+    const node = pending.pop()! as Record<string, any>;
+    if (
+      node.type === "MemberExpression" &&
+      node.computed === false &&
+      node.property?.type === "Identifier" &&
+      node.property.name === "url" &&
+      node.object?.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: string = input[i]!;
-    const next: string | undefined = 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: string, index: number): boolean =>
-  input.startsWith(TARGET, index) &&
-  isBoundary(input[index - 1]) &&
-  isBoundary(input[index + TARGET.length]);
-
-const isBoundary = (ch: string | undefined): boolean =>
-  ch === undefined || /[^A-Za-z0-9_$]/.test(ch);
-
-const skipQuoted = (input: string, index: number, quote: string): number => {
-  let escaped: boolean = false;
-  for (let i = index + 1; i < input.length; ++i) {
-    const ch: string = 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: string[] = [];
+  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: string, index: number): number => {
-  const found: number = input.indexOf("\n", index + 2);
-  return found === -1 ? input.length : found + 1;
-};
-
-const skipBlockComment = (input: string, index: number): number => {
-  const found: number = input.indexOf("*/", index + 2);
-  return found === -1 ? input.length : found + 2;
+  pieces.push(input.slice(cursor));
+  return pieces.join("");
 };

package/src/utils/FileRetriever.ts

@@ -1,7 +1,26 @@
 import fs from "fs";
 import path from "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.
+ */
 export 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.
+   */
   export const directory =
     (name: string) =>
     (dir: string, depth: number = 0): string | null => {
@@ -11,6 +30,16 @@ export namespace FileRetriever {
       return directory(name)(path.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.
+   */
   export const file =
     (name: string) =>
     (directory: string, depth: number = 0): string | null => {

package/src/utils/HttpResponseContentTypeUtil.ts

@@ -1,4 +1,23 @@
+/**
+ * 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 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.
+   */
   export type Response =
     | "application/json"
     | "text/plain"
@@ -6,6 +25,16 @@ export namespace HttpResponseContentTypeUtil {
     | (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.
+   */
   export const isSupported = (input: string | null): input is Response =>
     input === null ||
     input === "application/json" ||
@@ -13,6 +42,18 @@ export namespace HttpResponseContentTypeUtil {
     input === "application/x-www-form-urlencoded" ||
     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.
+   */
   export const isBinary = (
     input: string | null | undefined,
   ): input is string => {

package/src/utils/MapUtil.ts

@@ -1,14 +1,79 @@
+/**
+ * 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 namespace 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.
+   */
   export function take<Key, T>(
-    dict: Map<Key, T>,
+    dict: IDictionary<Key, T>,
     key: Key,
     generator: () => T,
   ): T {
-    const oldbie: T | undefined = dict.get(key);
-    if (oldbie) return oldbie;
+    if (dict.has(key)) return dict.get(key) as T;
 
     const value: T = generator();
     dict.set(key, value);
     return value;
   }
+
+  /**
+   * 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.
+   */
+  export 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/src/utils/PathUtil.ts

@@ -1,10 +1,48 @@
+import path from "path";
+import { fileURLToPath } from "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.
+ */
 export 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.
+   */
   export const accessors = (path: string) =>
     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.
+   */
+  export const location = (str: string): string =>
+    str.startsWith("file:")
+      ? fileURLToPath(str).split(path.sep).join("/")
+      : str;
+
   const normalize = (str: string) =>
     str.split("-").join("_").split(".").join("_");
 }

package/src/utils/SdkBundlePath.ts

@@ -0,0 +1,11 @@
+import path from "path";
+
+/** The installed API bundle shared by SDK emission and source exclusion. */
+export const SDK_BUNDLE_PATH: string = path.join(
+  __dirname,
+  "..",
+  "..",
+  "assets",
+  "bundle",
+  "api",
+);

package/src/utils/SdkInputFilter.ts

@@ -0,0 +1,108 @@
+import fs from "fs";
+import path from "path";
+
+import { SDK_BUNDLE_PATH } from "./SdkBundlePath";
+import { SourceFinder } from "./SourceFinder";
+
+/**
+ * Separates authored TypeScript inputs from files owned by SDK generation.
+ *
+ * Each filter owns one output directory. Installed bundle metadata is shared;
+ * output-specific native paths are never stored in the process-wide cache.
+ *
+ * @evidence contracts/common.md#principled-implementation Source extensions are checked before generated functional descendants and exact bundled output files are excluded. Native identities and path.relative distinguish descendants from prefix-sharing siblings.
+ * @evidence contracts/common.md#clear-and-simple-design One filter factory separates source selection from controller compilation; its private helpers own bundle metadata and filesystem identity.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Exclusions come from the actual installed bundle and the generated functional directory, without fixture names or a cached caller output.
+ * @evidence contracts/common.md#meaningful-documentation The comment states filter ownership and the cache's output-independent content.
+ * @evidence contracts/portability.md#os-neutral-implementation Native real paths resolve existing ancestors and path.relative judges directory containment; neither OS names nor lowercasing assume a volume's case or link policy.
+ * efficient algorithms: Successful installed bundle entries are scanned once and each filter builds its exclusion roots once; a candidate resolves one identity and compares at most the bundle entry count plus functional root, with no recursive source scan here.
+ * reuse equivalent work: Concurrent filters share installed bundle names and kinds; a failed metadata read clears the promise so a later request can retry. Output-specific resolved roots belong to each factory call, so another output cannot reuse the first caller's paths.
+ * bound retention and release resources: The one metadata promise retains only the fixed installed bundle population. Output roots live in the returned filter closure and are released with its source-discovery call; there is no growing per-output registry.
+ */
+export namespace SdkInputFilter {
+  /**
+   * Creates the source predicate for one configuration's output, or an
+   * extension-only predicate when no SDK output is configured.
+   *
+   * @evidence contracts/common.md#principled-implementation The predicate accepts regular TypeScript source names, excludes descendants of this output's functional directory and the bundle's exact file/directory identities, and leaves same-named authored files outside that output eligible.
+   * @evidence contracts/common.md#clear-and-simple-design Output roots are prepared before discovery and captured in one returned predicate, so compilation never owns these path-selection rules.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Every configuration resolves its own output; no first-call output, substring containment or operating-system case guess substitutes for filesystem identity.
+   * @evidence contracts/common.md#meaningful-documentation The comment documents both output-bound and extension-only modes.
+   * @evidence contracts/portability.md#os-neutral-implementation The nearest existing ancestor carries actual case/link identity and nonexistent suffixes retain their native spelling; path.relative rejects sibling and cross-root locations without protocol-path comparisons.
+   * efficient algorithms: Factory preparation is linear in installed bundle entries and each predicate call scans those prepared roots after one candidate identity resolution. It reuses the discovery traversal rather than walking inputs again.
+   * reuse equivalent work: Output-independent metadata comes from one shared in-flight or successful promise; rejection clears it for retry, while each output-specific root array is computed for its own factory call and is not shared across incompatible configurations.
+   * bound retention and release resources: The predicate retains only this configuration's fixed exclusion roots and no candidate history; once SourceFinder finishes, that closure has no persistent owner.
+   */
+  export const create = async (
+    output: string | undefined,
+  ): Promise<(location: string) => Promise<boolean>> => {
+    if (output === undefined)
+      return async (location) => SourceFinder.isTypeScriptSource(location);
+    const excluded = [
+      {
+        location: identity(path.resolve(output, "functional")),
+        directory: true,
+      },
+      ...(await bundle()).map((asset) => ({
+        location: identity(path.resolve(output, asset.name)),
+        directory: asset.directory,
+      })),
+    ];
+    return async (location) => {
+      if (SourceFinder.isTypeScriptSource(location) === false) return false;
+      const file = identity(location);
+      return excluded.every((entry) =>
+        entry.directory
+          ? within(entry.location, file) === false
+          : entry.location !== file,
+      );
+    };
+  };
+}
+
+let bundlePromise: Promise<{ name: string; directory: boolean }[]> | undefined;
+const bundle = (): Promise<{ name: string; directory: boolean }[]> => {
+  if (bundlePromise === undefined)
+    bundlePromise = (async () =>
+      Promise.all(
+        (
+          await fs.promises.readdir(SDK_BUNDLE_PATH, { withFileTypes: true })
+        ).map(async (entry) => ({
+          name: entry.name,
+          directory: entry.isSymbolicLink()
+            ? (
+                await fs.promises.stat(path.join(SDK_BUNDLE_PATH, entry.name))
+              ).isDirectory()
+            : entry.isDirectory(),
+        })),
+      ))().catch((error) => {
+      bundlePromise = undefined;
+      throw error;
+    });
+  return bundlePromise;
+};
+
+const within = (directory: string, location: string): boolean => {
+  const relative = path.relative(directory, location);
+  return (
+    relative === "" ||
+    (path.isAbsolute(relative) === false &&
+      relative !== ".." &&
+      relative.startsWith(`..${path.sep}`) === false)
+  );
+};
+
+const identity = (location: string): string => {
+  const rest: string[] = [];
+  for (let current = path.resolve(location); ; ) {
+    try {
+      return path.join(fs.realpathSync.native(current), ...rest.reverse());
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const parent = path.dirname(current);
+      if (parent === current) throw error;
+      rest.push(path.basename(current));
+      current = parent;
+    }
+  }
+};