ttsc 0.30.4 → 0.31.0

package/src/launcher/internal/runtime/withRuntimeDirectoryLock.ts

@@ -0,0 +1,92 @@
+import path from "node:path";
+
+import { resolvePhysicalPath } from "../../../internal/pathIdentity/resolvePhysicalPath";
+import { runHoldingLock } from "../../../internal/runHoldingLock";
+import { DependencyBuildLockProtocol } from "./DependencyBuildLockProtocol";
+import { acquireDependencyBuildLock } from "./acquireDependencyBuildLock";
+import { inspectDependencyBuildLock } from "./inspectDependencyBuildLock";
+import { reclaimDependencyBuildLock } from "./reclaimDependencyBuildLock";
+import { releaseDependencyBuildLock } from "./releaseDependencyBuildLock";
+
+/**
+ * Serialize a runtime-directory claim with `ttsc clean` over the same root.
+ *
+ * The existing fenced directory-lock protocol publishes a complete owner record
+ * before acquisition and retires exactly the generation it held. Its lock lives
+ * beside the runtime root, so clean can remove the root without removing the
+ * coordination point. The shared inspector selects active/abandoned states:
+ * valid owner records use conservative host/pid probes; a readable generation
+ * lacking a valid owner can also become abandoned under its stale-age policy.
+ * That latter policy is not a native certificate that a process died.
+ * Acquisition waits use the dependency-build elapsed-time policy rather than a
+ * hard completion bound on native IO, work or retirement.
+ *
+ * Retirement may separately wait for peer filesystem handles; that release path
+ * has no independent deadline. Participants must use the same stable physical
+ * namespace and valid records. A physical spelling is not a held directory
+ * handle. Native acquisition or cleanup failure can leave persisted
+ * candidate/current state; this wrapper does not roll back a failed acquisition
+ * before it returns a lease.
+ *
+ * @param runtimeRoot The runtime directory, in any filesystem spelling.
+ * @param work A synchronous claim or clean operation under the lock.
+ * @returns What `work` returned.
+ * @evidence contracts/common.md#principled-implementation Resolving the observed physical root selects the cooperative sibling lock; work executes only after a returned lease. Inspector-authorized recovery retires its observed generation, including its owner-missing stale-age policy, without claiming every abandonment decision proves native process death.
+ * @evidence contracts/common.md#clear-and-simple-design One synchronous wrapper coordinates root identity, bounded acquisition polling and finally release while delegating the fenced protocol and work/error precedence to shared owners.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper follows the actual inspector state and generation fence rather than bypassing a recognized active owner. Missing valid ownership follows the shared stale-age policy; work errors retain precedence through runHoldingLock.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the sibling coordination point, acquisition timeout and unbounded peer-handle retirement; parameters identify native root spelling and synchronous work ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation The shared filesystem identity resolver selects the native physical root and path constructs its sibling lock; retirement isolates platform rename/handle behavior without assuming case policy from an OS name.
+ * @evidence contracts/performance.md#efficient-algorithms Identity/path text and native observations precede polling. Attempts add candidate/generation/hostname record bytes, filesystem IO and inspector probes; contention waits use Atomics.wait and each attempt avoids retired-history scans. Work is caller-defined and retirement can wait independently; the wall-clock acquisition check does not bound blocking native calls or work.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Distinct claim and clean effects must serialize but cannot share a completed work result; each caller supplies its own synchronous effect.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One sleeper and a returned lease belong to the invocation; finally attempts retirement, with no independent peer-handle release deadline. Acquisition failures can leave persisted state before lease transfer. The sibling lock retains candidates/tombstones until appropriate recovery or container removal, with no historical quota here.
+ */
+export function withRuntimeDirectoryLock<T>(
+  runtimeRoot: string,
+  work: () => T,
+): T {
+  const lockDir = `${resolvePhysicalPath(path.resolve(runtimeRoot))}.lock`;
+  const startedAt = Date.now();
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  for (;;) {
+    const lease = acquireDependencyBuildLock(lockDir);
+    if (lease !== null) {
+      return runHoldingLock(
+        work,
+        () => {
+          if (!releaseDependencyBuildLock(lockDir, lease)) {
+            throw new Error(
+              `runtime directory lock was not released: ${lockDir}`,
+            );
+          }
+        },
+        (error) => {
+          process.emitWarning(
+            `runtime directory lock release failed at ${lockDir}: ${error instanceof Error ? error.message : String(error)}`,
+            { code: "TTSC_RUNTIME_DIRECTORY_LOCK_RELEASE" },
+          );
+        },
+      );
+    }
+    const now = Date.now();
+    const observed = inspectDependencyBuildLock(lockDir, now);
+    if (observed.state === "abandoned") {
+      reclaimDependencyBuildLock(lockDir, observed.fence);
+    }
+    if (
+      Date.now() - startedAt >=
+      DependencyBuildLockProtocol.DEP_BUILD_LOCK_WAIT_MS
+    ) {
+      throw new Error(
+        `runtime directory lock did not become available at ${lockDir}: ${observed.state === "active" ? observed.owner : "no holder could be observed"}`,
+      );
+    }
+    Atomics.wait(
+      sleeper,
+      0,
+      0,
+      DependencyBuildLockProtocol.DEP_BUILD_LOCK_POLL_MS,
+    );
+  }
+}

package/src/launcher/internal/runtimeCompilerArgs.ts

@@ -1,77 +1,106 @@
-import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
-import { outputText, spawnNative } from "../../compiler/internal/spawnNative";
-import { normalizeFlagToken } from "../../flags/schema";
+import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
 import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
 
 /**
- * Lower proposal syntax in ESNext runtime builds without changing the implied
- * library or module kind. TypeScript-Go preserves standard decorators at
- * ESNext, while Node cannot parse them. Its latest standard target, ES2025,
- * runs the upstream decorator transform and keeps native class-field
- * semantics.
+ * The compiler arguments of a runtime build: the caller's own, plus whatever
+ * requests decorator/JSX lowering and JavaScript emission for Node. This is not
+ * certification of every runtime API or syntax feature. The config, source, and
+ * ordinary `ttsc` output never change.
+ *
+ * Two settings hand syntax Node cannot parse to a later tool, and each is
+ * replaced only in the runtime build, after the forwarded flags so it wins over
+ * them as well as over the config:
+ *
+ * - `target: ESNext` preserves proposal decorators. The build lowers to ES2025,
+ *   TypeScript-Go's latest standard target, which runs the upstream decorator
+ *   lowering policy while retaining the standard class-field target, without
+ *   changing the implied library or module kind.
+ * - `jsx: preserve` and `jsx: react-native` keep JSX. The build compiles it with
+ *   the JSX runtime the type-check already reads.
+ *
+ * A forwarded `--noEmit` or `--emitDeclarationOnly` is switched back off as
+ * well. ttsx forwards the flags before the entry to its type-check, and the
+ * check is unchanged by them, but the runtime build is that check's emit, and
+ * without JavaScript there is nothing to run.
+ *
+ * A caller coordinating one build may supply its effective-options reader for
+ * this exact project and forwarded arguments. Null preserves the compiler's
+ * argument-rejection path; omission creates the reader here.
+ *
+ * @evidence contracts/common.md#principled-implementation Effective compiler options determine runtime-only target/JSX overrides; preserving implied module and library choices keeps the original check's meaning while producing executable syntax.
+ * @evidence contracts/common.md#clear-and-simple-design One ordered argument adapter separates runtime emit policy from project configuration and leaves invalid-argument diagnostics to the compiler.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts ES2025 and JSX discriminants reflect supported compiler transforms; no source-text patch or consumer-specific override substitutes for emission.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain decorator, JSX, library and no-emit decisions and their runtime-only scope without changing the user's project.
+ * @evidence contracts/portability.md#os-neutral-implementation Effective-option resolution delegates response-file parsing to the compiler owner and returns argument tokens rather than shell text or platform-specific paths.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned copied argv array belongs to the caller. An internally prepared effective reader is call-local; a supplied reader and its captured config/assignment records remain caller-owned. Delegated response inspection and native showConfig/capture own cleanup attempts; this adapter retains no history or process handle.
+ * @evidence contracts/performance.md#efficient-algorithms Copying A forwarded argument references and text/value queries precedes fixed policy additions. Without a supplied reader, delegated argv/response inspection, native showConfig, full output decoding and JSON parsing are additional input/native costs; the returned argv need not be short.
+ * @evidence contracts/performance.md#reuse-equivalent-work One effective reader serves this call's policy queries, and an actual reader supplied for the same project/arguments avoids preparation repeated across coordinated build adapters. The caller owns that equivalence premise; this adapter caches no historical argv result.
  */
 export function runtimeCompilerArgs(
   project: ITtscParsedProjectConfig,
   passthrough: readonly string[] = [],
   binary?: string,
+  effectiveOptions?: ReturnType<typeof readEffectiveCompilerOptions>,
 ): string[] {
-  let compilerOptions = project.compilerOptions;
-  const hasResponseFile = passthrough.some((token) => token.startsWith("@"));
-  if (hasResponseFile) {
-    // Let TypeScript-Go own response-file quoting, nesting, cwd, and ordering.
-    // Replaying just the visible flags would overwrite options inside @files.
-    const tsgo = resolveTsgo({ cwd: project.root, binary });
-    const result = spawnNative(
-      tsgo.binary,
-      ["-p", project.path, ...passthrough, "--showConfig"],
-      { cwd: project.root, encoding: "utf8" },
-    );
-    // Preserve the original compiler's diagnostic when its arguments are invalid.
-    if (result.status !== 0) return [...passthrough];
-    compilerOptions = JSON.parse(outputText(result.stdout)).compilerOptions;
+  const option =
+    effectiveOptions === undefined
+      ? readEffectiveCompilerOptions(project, passthrough, binary)
+      : effectiveOptions;
+  // Preserve the original compiler's diagnostic when its arguments are invalid.
+  if (option === null) return [...passthrough];
+  const args = [...passthrough];
+  const target = option("target", ["t"]);
+  if (typeof target === "string" && target.toLowerCase() === "esnext") {
+    args.push("--target", "es2025");
+    const module = option("module", ["m"]);
+    if (module == null || String(module).toLowerCase() === "none") {
+      // GetEmitModuleKind derives ESNext from the original target.
+      args.push("--module", "esnext");
+    }
+    const noLib = option("noLib");
+    if (option("lib") == null && noLib !== true && noLib !== "true") {
+      // The references in TypeScript-Go's lib.esnext.full.d.ts. An explicit lib
+      // (including []) or noLib keeps the user's exact library selection.
+      args.push(
+        "--lib",
+        "esnext,dom,webworker.importscripts,scripthost,dom.iterable,dom.asynciterable",
+      );
+    }
   }
-  const option = (name: string, aliases: readonly string[] = []): unknown => {
-    if (hasResponseFile) return compilerOptions[name];
-    let value = compilerOptions[name];
-    for (let i = 0; i < passthrough.length; i++) {
-      const token = passthrough[i]!;
-      if (!token.startsWith("-")) continue;
-      const normalized = normalizeFlagToken(token);
-      if (normalized !== name.toLowerCase() && !aliases.includes(normalized)) {
-        continue;
+  const jsx = option("jsx");
+  if (typeof jsx === "string" && PRESERVED_JSX.has(jsx.toLowerCase())) {
+    // A project that preserves JSX hands it to another tool, and Node is not
+    // that tool. The runtime build compiles it the way the compiler already
+    // checks it. A `jsxImportSource` makes the checker read JSX as the automatic
+    // runtime even under `preserve`, so it selects `react-jsx`. Without one, a
+    // `jsxFactory`, `jsxFragmentFactory`, or `reactNamespace` declares the
+    // classic transform, and a project that declares nothing gets the automatic
+    // runtime's default source, `react`.
+    const factories = ["jsxFactory", "jsxFragmentFactory", "reactNamespace"];
+    const automatic =
+      option("jsxImportSource") != null ||
+      factories.every((name) => option(name) == null);
+    args.push("--jsx", automatic ? "react-jsx" : "react");
+    // `preserve` accepts a factory beside an import source, and `react-jsx`
+    // rejects it (TS5089), so the factories the automatic runtime never reads
+    // are set aside for the runtime build.
+    if (automatic) {
+      for (const name of factories) {
+        if (option(name) != null) args.push(`--${name}`, "null");
       }
-      const next = passthrough[i + 1];
-      value =
-        name === "noLib" &&
-        next !== "true" &&
-        next !== "false" &&
-        next !== "null"
-          ? true
-          : next === "null"
-            ? undefined
-            : next;
     }
-    return value;
-  };
-  const target = option("target", ["t"]);
-  if (typeof target !== "string" || target.toLowerCase() !== "esnext") {
-    return [...passthrough];
-  }
-
-  const args = [...passthrough, "--target", "es2025"];
-  const module = option("module", ["m"]);
-  if (module == null || String(module).toLowerCase() === "none") {
-    // GetEmitModuleKind derives ESNext from the original target.
-    args.push("--module", "esnext");
-  }
-  const noLib = option("noLib");
-  if (option("lib") == null && noLib !== true && noLib !== "true") {
-    // The references in TypeScript-Go's lib.esnext.full.d.ts. An explicit lib
-    // (including []) or noLib keeps the user's exact library selection.
-    args.push(
-      "--lib",
-      "esnext,dom,webworker.importscripts,scripthost,dom.iterable,dom.asynciterable",
-    );
   }
+  // Unconditional, after every forwarded token: a response file can carry the
+  // flag too. Explicit false operands clear the two native boolean assignments.
+  args.push("--noEmit", "false", "--emitDeclarationOnly", "false");
   return args;
 }
+
+/**
+ * JSX modes that leave the syntax in the output for a downstream tool. Node
+ * cannot parse either, so a runtime build replaces them.
+ */
+const PRESERVED_JSX: ReadonlySet<string> = new Set([
+  "preserve",
+  "react-native",
+]);

package/src/launcher/internal/runtimeEmitProfile.ts

@@ -0,0 +1,70 @@
+import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
+import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
+import type { OwningModuleOptions } from "./runtime/OwningModuleOptions";
+import { projectModuleOptions } from "./runtime/projectModuleOptions";
+
+/**
+ * What a ttsx runtime build emits, read from the options it compiles with: the
+ * project's config and the flags forwarded before the entry, in the order the
+ * compiler applies them.
+ *
+ * Two decisions follow from the emit, and reading the config alone answered
+ * both for a build that is not the one that runs:
+ *
+ * - `moduleOptions` classify every file the build serves as CommonJS or an ES
+ *   module. `ttsx --module esnext` on a CommonJS project emitted ESM that the
+ *   runtime then served as CommonJS, and the entry never ran while the run
+ *   exited 0.
+ * - `forceRuntimeSourceMap` adds `--sourceMap` when the build would carry no map
+ *   to inline. A forwarded `--inlineSourceMap` already carries one, and forcing
+ *   `sourceMap` beside it failed the build with TS5053.
+ *
+ * @param project - The project the runtime build compiles.
+ * @param passthrough - The flags forwarded to that build, in order.
+ * @param binary - An explicit TypeScript-Go binary, for a response file.
+ * @param effectiveOptions - A reader already resolved for this exact build's
+ *   project and forwarded arguments, or null after compiler rejection.
+ * @evidence contracts/common.md#principled-implementation Reading effective options in compiler order classifies the actual emit, and the two map booleans prevent asking for conflicting external and inline maps.
+ * @evidence contracts/common.md#clear-and-simple-design The profile carries only module classification and whether a map must be requested; the local boolean reader normalizes supported true spellings.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid forwarded arguments retain the compiler's own rejection path; config fallback is provisional classification rather than silently dropping those arguments.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs and parameter comments explain emit-derived decisions and the two failure modes this boundary avoids; result members retain separate native comments.
+ * @evidence contracts/portability.md#os-neutral-implementation Native response-file interpretation stays with effective-option resolution; this adapter passes binary identity and argument tokens without shell quoting or guessed filesystem case rules.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The local option reader and its captured assignment/shown records end with the call unless supplied/retained by the caller; delegated response inspection/native capture own resource cleanup attempts. The small returned profile retains module-option values rather than process handles or history.
+ * @evidence contracts/performance.md#efficient-algorithms Without a supplied reader, effective-option preparation projects argv and may inspect/decode/hash response bytes, run native showConfig and parse its output. Profile queries also normalize option/alias/value text; the fixed outer result shape does not bound delegated input or native execution costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work One effective reader serves all profile queries; an actual reader supplied for this exact project/argument invocation avoids preparing it again. Context matching is the caller's prerequisite, not an equality or native-state proof performed by this adapter; there is no historical profile memo.
+ */
+export function runtimeEmitProfile(
+  project: ITtscParsedProjectConfig,
+  passthrough: readonly string[] = [],
+  binary?: string,
+  effectiveOptions?: ReturnType<typeof readEffectiveCompilerOptions>,
+): {
+  /** The emit-deciding options the runtime classifies served files with. */
+  moduleOptions: OwningModuleOptions;
+
+  /** Whether the build must be asked for a source map. */
+  forceRuntimeSourceMap: boolean;
+} {
+  const option =
+    effectiveOptions === undefined
+      ? readEffectiveCompilerOptions(project, passthrough, binary)
+      : effectiveOptions;
+  const compilerOptions = project.compilerOptions as Record<string, unknown>;
+  // Invalid forwarded flags fail the build on their own; the config answers
+  // until then.
+  const read = (name: string, aliases?: readonly string[]): unknown =>
+    option === null ? compilerOptions[name] : option(name, aliases);
+  return {
+    moduleOptions: projectModuleOptions({
+      module: read("module", ["m"]),
+      target: read("target", ["t"]),
+    }),
+    forceRuntimeSourceMap:
+      !isOn(read("sourceMap")) && !isOn(read("inlineSourceMap")),
+  };
+}
+
+/** Whether a config value or a forwarded flag value turns an option on. */
+function isOn(value: unknown): boolean {
+  return value === true || value === "true";
+}

package/src/launcher/internal/runtimeHookPreload.ts

@@ -1,4 +1,4 @@
-import { installRuntimeHooks } from "./runtimeHooks";
+import { installRuntimeHooks } from "./runtime/installRuntimeHooks";
 
 /**
  * `--require` target that only installs the runtime module hooks. `ttsx` puts
@@ -7,8 +7,8 @@ import { installRuntimeHooks } from "./runtimeHooks";
  * source-loading hooks, the way `ts-node` propagates through `--require
  * ts-node/register`. The preload itself is CommonJS and only registers the
  * hooks; ESM support comes from the `registerHooks` they install, not from how
- * the preload is loaded. The entry process additionally goes through the
- * bootstrap, which loads the entry itself; here we only register
+ * the preload is loaded. The entry process gets it the same way, which is what
+ * lets Node load the entry itself as its main module; here we only register
  * (idempotently).
  */
 installRuntimeHooks();

package/src/launcher/internal/runtimeOwnerPreload.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { ProcessOwnedDirectory } from "./runtime/ProcessOwnedDirectory";
+import { withRuntimeDirectoryLock } from "./runtime/withRuntimeDirectoryLock";
+
+/**
+ * Claim a ttsx run before another preload or the program can use its output.
+ *
+ * The launcher can be killed after it starts a child. The child must publish
+ * its own owner record under the lock that default clean uses, so either clean
+ * sees its live claim or the child fails before user code if clean removed the
+ * run first. NODE_OPTIONS passes this preload to descendants as well. A child
+ * without the inherited runtime manifest uses its own cache and claims no part
+ * of the parent's run.
+ */
+const directory = process.env.TTSX_RUNTIME_RUN_DIR;
+const manifest = process.env.TTSX_RUNTIME_MANIFEST;
+const runtime = process.env.TTSX_RUNTIME_CACHE_DIR;
+const runs = process.env.TTSX_RUNTIME_RUNS_DIR;
+if (
+  directory !== undefined &&
+  manifest !== undefined &&
+  manifest.length !== 0
+) {
+  if (
+    !path.isAbsolute(directory) ||
+    runtime === undefined ||
+    !path.isAbsolute(runtime) ||
+    runs === undefined ||
+    !path.isAbsolute(runs) ||
+    path.dirname(directory) !== runs
+  ) {
+    throw new Error(`ttsx: invalid runtime run directory: ${directory}`);
+  }
+  withRuntimeDirectoryLock(runtime, () => {
+    const entry = fs.lstatSync(directory);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      throw new Error(`ttsx: unsafe runtime run directory: ${directory}`);
+    }
+    ProcessOwnedDirectory.admit(directory, process.pid);
+  });
+}

package/src/launcher/internal/singleRootProjectConfig.ts

@@ -0,0 +1,38 @@
+import path from "node:path";
+
+/**
+ * Project the single-root overlay that inherits the selected owning config.
+ * Explicit empty include/exclude lists displace inherited populations. Checked
+ * overlays preserve inherited noEmitOnError; unchecked overlays clear it. The
+ * caller supplies the already selected physical volume root and owns config
+ * placement, exclusive creation, parsing, compilation and cleanup.
+ *
+ * @evidence contracts/common.md#principled-implementation The overlay retains its owning config through extends, selects the exact source and clears inherited include/exclude populations without changing the checked lane's noEmitOnError policy.
+ * @evidence contracts/common.md#clear-and-simple-design One fresh JSON-compatible object supplies the existing fixed compiler overrides and selected path values to the production writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ordinary compiler config fields own selection; no compiler output, native root inference or read result is invented or intercepted.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraph states list replacement, checked versus unchecked policy and the caller-owned filesystem/compiler boundaries.
+ * @evidence contracts/portability.md#os-neutral-implementation Only the host-native separator is replaced with config-compatible slashes in the selected config, source and volume-root strings; this operation does not resolve paths or infer a filesystem root.
+ * @evidence contracts/performance.md#efficient-algorithms Three replaceAll operations visit the supplied path text before constructing a fixed-size object and arrays; fixed property count does not bound input string bytes or delegated compilation cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This projection coordinates no completed or in-flight producer; build and cache reuse remain with its caller.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A fresh returned object transfers to the caller and no descriptor, process, history or retained cache is acquired.
+ */
+export function singleRootProjectConfig(props: {
+  tsconfig: string;
+  source: string;
+  volumeRoot: string;
+  checked: boolean;
+}) {
+  return {
+    extends: props.tsconfig.replaceAll(path.sep, "/"),
+    compilerOptions: {
+      composite: false,
+      declaration: false,
+      declarationMap: false,
+      ...(props.checked ? {} : { noEmitOnError: false }),
+      rootDir: props.volumeRoot.replaceAll(path.sep, "/"),
+    },
+    files: [props.source.replaceAll(path.sep, "/")],
+    include: [],
+    exclude: [],
+  };
+}

package/src/launcher/internal/ttscserver/ILSPPluginSelectionInputs.ts

@@ -0,0 +1,65 @@
+/**
+ * What a `ttscserver` session's plugin selection was loaded from, as the native
+ * host receives it in the plugin manifest (`selectionInputs`). Native startup
+ * and later input checks reject a changed recorded fingerprint or relevant
+ * source listing; this shape alone does not guarantee every external change
+ * will be observed or delivered to a running session.
+ *
+ * Both kinds of input travel by directory, each directory with the names of the
+ * files in it and the digest each had
+ * (`LSPProjectInputDigest.lspProjectInputFileDigest`). The descriptors' inputs
+ * can include many missing resolution candidates, and plugin sources can span
+ * many files. At construction the host indexes resolved directory identity once
+ * per directory rather than separately for every recorded basename; later
+ * checks still perform native identity and file observations. A source
+ * directory's listing is an input too, counted by the build's own rule: a
+ * residue file or a directory the build passes over changes nothing.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate descriptor candidates and source-directory listings encode different invalidation meaning; digests preserve missing candidates while shared builder omission rules define which source entries can change selection.
+ * @evidence contracts/common.md#clear-and-simple-design Directory-to-basename maps match the native observer's unit of identity resolution; omission vocabulary travels as data rather than becoming a second independently maintained source policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recorded file state comes from the selection's actual inputs, and source filters are shared builder rules rather than consumer or fixture exceptions.
+ * @evidence contracts/common.md#meaningful-documentation The interface and member comments explain directory grouping, missing candidates and listing exclusions; documented members have blank source lines and tags are separated according to the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Declared native directories and entry names travel separately so the native host resolves actual directory identity without replacing path spellings with an OS-wide case assumption.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ */
+export interface ILSPPluginSelectionInputs {
+  /**
+   * Every directory holding a non-deferred input the plugin load reported, with
+   * each recorded basename and digest: the project's config chain, the
+   * manifests plugin discovery reads, the descriptors, and what they resolved.
+   * Only those reported files count; the record does not discover undeclared
+   * external reads.
+   */
+  descriptorFiles: Record<string, Record<string, string>>;
+
+  /**
+   * Every plugin source directory an observer watches
+   * (`collectPluginSourceDirectories`), with the name of every file directly
+   * inside it that the build keys on (`collectPluginSourceFiles`) and its
+   * digest.
+   */
+  sourceFiles: Record<string, Record<string, string>>;
+
+  /**
+   * The names of files the build never keys on
+   * (`GoSourceInputs.OMITTED_SOURCE_FILE_NAMES`), whose appearance in a source
+   * directory changes nothing.
+   */
+  omittedNames: readonly string[];
+
+  /**
+   * The suffixes of files the build never keys on
+   * (`GoSourceInputs.OMITTED_SOURCE_FILE_SUFFIXES`), such as an editor's `~`
+   * backups.
+   */
+  omittedSuffixes: readonly string[];
+
+  /**
+   * The names of directories the build passes over
+   * (`GoSourceInputs.PRUNED_SOURCE_DIRECTORY_NAMES`), whose appearance changes
+   * nothing.
+   */
+  prunedDirectoryNames: readonly string[];
+}