ttsc 0.30.3 → 0.31.0

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

@@ -0,0 +1,331 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { type ProjectInputPathIdentityContext } from "../../../internal/pathIdentity/ProjectInputPathIdentityContext";
+import { createProjectInputPathIdentityContext } from "../../../internal/pathIdentity/createProjectInputPathIdentityContext";
+import { resolveProjectInputPath } from "../../../internal/pathIdentity/resolveProjectInputPath";
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+
+/**
+ * Content fingerprints of the files and directories whose change forces the
+ * language server to reselect plugins.
+ *
+ * `ttscserver` resolves its plugin selection before the Go LSP host starts and
+ * hands both the selection and these fingerprints to the host, which recomputes
+ * them to notice a change that landed in between. The two sides must therefore
+ * use compatible byte framing. The Windows parity test in `internal/lspserver`
+ * checks one existing directory and one missing descendant; it does not
+ * establish agreement for every native entry or failure state.
+ *
+ * @evidence contracts/common.md#principled-implementation Domain-framed content, link and topology records encode the same selection distinctions as the Go validator; physical directory identity is distinct from leaf-link identity and ordinary child content.
+ * @evidence contracts/common.md#clear-and-simple-design JavaScript capture and validation share these digest helpers; the Go peer independently implements the startup framing and must remain compatible.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unavailable reads and non-file entries use declared protocol markers; a missing marker can also represent a read failure and is not proof of absence. Native readers remain supported APIs without foreign replacement.
+ * @evidence contracts/common.md#meaningful-documentation Namespace and helper comments explain cross-host framing, raw-byte preservation and leaf identity, with separated public tags and member paragraphs following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows native paths use the shared identity resolver; POSIX reads preserve raw path and link-target bytes, and neither branch infers filesystem case from an OS label.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms This namespace groups digest operations but chooses no computation itself; its functions acknowledge their own traversal and allocation costs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The namespace retains no digest or validity state; each function supplies the current observation its caller needs.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no stored baseline, handle or running task; capture and session owners control returned observations.
+ */
+export namespace LSPProjectInputDigest {
+  /**
+   * A project-input snapshot plus the fingerprints taken when it was read.
+   *
+   * @evidence contracts/common.md#principled-implementation The intersection retains dependency declarations and attaches separate read-time file/content and directory/topology observations keyed by those declarations.
+   * @evidence contracts/common.md#clear-and-simple-design Two readonly maps add baseline evidence without copying the base dependency schema or merging distinct reload semantics.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The representation stores actual captured digests rather than a precomputed compliance boolean that could conceal changed inputs.
+   * @evidence contracts/common.md#meaningful-documentation Native type and member comments identify read-time provenance and topology versus content, using blank member lines and prose/tag separation following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Map keys preserve declared native spellings while the digest producer separately handles physical identity and link state across supported platforms.
+   *
+   * @evidenceExclude contracts/performance.md#efficient-algorithms This baseline type represents observations without choosing a traversal or hashing algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work The representation does not coordinate equivalent requests; capture and validation functions own whether a selection remains reusable.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Session callers own the baseline lifetime; declaring its maps does not allocate or retain historical snapshots independently.
+   */
+  export type InitialLSPProjectInputSnapshot = ITtscProjectInputSnapshot & {
+    /** Topology digest of each reload directory, keyed by its declared path. */
+    reloadDirectoryDigests: Readonly<Record<string, string>>;
+
+    /** Content digest of each reload file, keyed by its declared path. */
+    reloadFileDigests: Readonly<Record<string, string>>;
+  };
+
+  /**
+   * Digest of a directory's immediate topology: each child's name, kind, and
+   * link target, resolved through the directory's physical identity. Content of
+   * the children is not part of it.
+   *
+   * @evidence contracts/common.md#principled-implementation The frame combines the available directory identity and sorted immediate name/kind/link-target observations; ordinary child content is excluded. These sequential native reads are not an atomic topology snapshot.
+   * @evidence contracts/common.md#clear-and-simple-design Physical identity and immediate topology have separate private readers and combine at one documented protocol boundary.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Any failed directory listing uses the missing topology marker, without certifying absence or distinguishing permission failure; unreadable link targets have a separate marker and supported filesystem APIs remain unchanged.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph states exactly which entry facts count and excludes child contents, with separated tags following the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Windows uses native resolved spelling; POSIX passes raw physical bytes through topology enumeration, preserving backslashes and non-UTF-8 names rather than converting them into protocol separators.
+   * @evidence contracts/performance.md#efficient-algorithms Native identity setup includes path probes, ancestor spelling work and a possible Windows capability query. For E immediate entries, sorting makes O(E log E) byte comparisons whose cost depends on compared name/target lengths; record buffers, sorting references and concatenated framing coexist, with hashing proportional to framed bytes. Child trees are not recursively scanned.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each reading is a freshness observation; sharing prior topology would need an independent change witness which this digest boundary does not own.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Supported synchronous APIs own their native handles; this helper retains no cross-call state or running task. Its identity context and entry/framing buffers live through the call without an independent byte ceiling.
+   */
+  export function lspProjectInputReloadDirectoryDigest(
+    location: string,
+  ): string {
+    const identities = createProjectInputPathIdentityContext();
+    const identity = lspProjectInputPhysicalPathIdentity(location, identities);
+    return createHash("sha256")
+      .update(
+        Buffer.concat([
+          Buffer.from("directory\0"),
+          identity,
+          Buffer.from([0]),
+          Buffer.from(
+            lspProjectInputDirectoryTopologyDigest(
+              process.platform === "win32"
+                ? identities.resolve(location).path
+                : identity,
+            ),
+          ),
+        ]),
+      )
+      .digest("hex");
+  }
+
+  function lspProjectInputPhysicalPathIdentity(
+    location: string,
+    identities: ProjectInputPathIdentityContext,
+  ): Buffer {
+    if (process.platform === "win32") {
+      return Buffer.from(
+        identities.resolve(location).path.replaceAll("\\", "/"),
+        "utf8",
+      );
+    }
+    let existing = path.resolve(location);
+    const missing: Buffer[] = [];
+    while (true) {
+      try {
+        const realpath = fs.realpathSync.native ?? fs.realpathSync;
+        const physical = realpath(Buffer.from(existing), {
+          encoding: "buffer",
+        });
+        const segments: Buffer[] = [physical];
+        for (let index = missing.length - 1; index >= 0; index--) {
+          if (index !== missing.length - 1 || physical.at(-1) !== 0x2f)
+            segments.push(Buffer.from("/"));
+          segments.push(missing[index]!);
+        }
+        return Buffer.concat(segments);
+      } catch (error) {
+        if (
+          error instanceof Error &&
+          "code" in error &&
+          error.code !== "ENOENT" &&
+          error.code !== "ENOTDIR"
+        ) {
+          throw error;
+        }
+        const parent = path.dirname(existing);
+        if (parent === existing) return Buffer.from(existing);
+        missing.push(Buffer.from(path.basename(existing)));
+        existing = parent;
+      }
+    }
+  }
+
+  function lspProjectInputDirectoryTopologyDigest(
+    location: string | Buffer,
+  ): string {
+    const entries: Buffer[] = [];
+    try {
+      if (process.platform === "win32") {
+        const directory =
+          typeof location === "string" ? location : location.toString("utf8");
+        for (const entry of fs.readdirSync(directory, {
+          withFileTypes: true,
+        })) {
+          let target = Buffer.alloc(0);
+          if (entry.isSymbolicLink()) {
+            try {
+              target = Buffer.from(
+                fs.readlinkSync(path.join(directory, entry.name)),
+                "utf8",
+              );
+            } catch {
+              target = Buffer.from("<unreadable>");
+            }
+          }
+          entries.push(
+            lspProjectInputDirectoryRecord(
+              Buffer.from(entry.name),
+              entry,
+              target,
+            ),
+          );
+        }
+      } else {
+        for (const entry of fs.readdirSync(location, {
+          encoding: "buffer",
+          withFileTypes: true,
+        })) {
+          let target = Buffer.alloc(0);
+          if (entry.isSymbolicLink()) {
+            try {
+              target = fs.readlinkSync(
+                Buffer.concat([
+                  Buffer.isBuffer(location) ? location : Buffer.from(location),
+                  Buffer.from(path.sep),
+                  entry.name,
+                ]),
+                { encoding: "buffer" },
+              );
+            } catch {
+              target = Buffer.from("<unreadable>");
+            }
+          }
+          entries.push(
+            lspProjectInputDirectoryRecord(entry.name, entry, target),
+          );
+        }
+      }
+    } catch {
+      return createHash("sha256").update("missing\0").digest("hex");
+    }
+    entries.sort(Buffer.compare);
+    const serialized = Buffer.concat(
+      entries.flatMap((entry, index) =>
+        index === 0 ? [entry] : [Buffer.from([0]), entry],
+      ),
+    );
+    return createHash("sha256").update(serialized).digest("hex");
+  }
+
+  function lspProjectInputDirectoryRecord(
+    name: Buffer,
+    entry: {
+      isDirectory(): boolean;
+      isFile(): boolean;
+      isSymbolicLink(): boolean;
+    },
+    target: Buffer,
+  ): Buffer {
+    const kind = entry.isDirectory()
+      ? "directory"
+      : entry.isFile()
+        ? "file"
+        : entry.isSymbolicLink()
+          ? "symlink"
+          : "other";
+    return Buffer.concat([name, Buffer.from("\0" + kind + "\0"), target]);
+  }
+
+  /**
+   * Digest of the available observations of one entry. A symlink frame combines
+   * its raw target and reached content; failed target/content reads use
+   * markers. Regular files hash their bytes, while classification or
+   * regular-file read failure hashes the stable `missing` marker. Other entry
+   * kinds hash as `other`. The reads are sequential and do not pin the entry
+   * against change.
+   *
+   * @evidence contracts/common.md#principled-implementation File, symlink and other frames distinguish available entry observations; a symlink includes the observed target and reached bytes. Unavailable observations collapse into markers, so unchanged digests do not prove native state was unchanged.
+   * @evidence contracts/common.md#clear-and-simple-design One lstat-driven dispatch owns entry-kind framing and keeps dangling or unreadable symlink content distinct from a missing link itself.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Fixed markers encode the native wire contract's unavailable states; the function reads actual entries rather than replacing content with expected diagnostics or test values.
+   * @evidence contracts/common.md#meaningful-documentation Native prose documents each entry kind and the two symlink inputs, with tags separated according to the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Native lstat, readlink and readFile preserve host link semantics; Buffer target reads retain POSIX raw bytes while Windows supplies the native target representation consumed by the Go peer.
+   * @evidence contracts/performance.md#efficient-algorithms One native classification and at most one target/content read produce the digest. Native path work, hashing and copied framing scale with path, target and reached content bytes; whole-file buffers and concatenated frames coexist without a separate input byte ceiling. No unrelated files are enumerated.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This produces a current observation, not a cached selection; a prior digest cannot be reused without separately proving the file and link remained unchanged.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Supported synchronous APIs own their handles; this helper retains only local content/framing buffers during the call and returns digest text. It owns no cross-call history, persistent handle or running task.
+   */
+  export function lspProjectInputFileDigest(location: string): string {
+    try {
+      const info = fs.lstatSync(location);
+      if (info.isSymbolicLink()) {
+        let target = Buffer.from("<unreadable>");
+        try {
+          target = fs.readlinkSync(Buffer.from(location), {
+            encoding: "buffer",
+          });
+        } catch {
+          // Preserve the same explicit unreadable state as the Go validator.
+        }
+        let content = Buffer.from("missing\0");
+        try {
+          content = Buffer.concat([
+            Buffer.from("file\0"),
+            fs.readFileSync(location),
+          ]);
+        } catch {
+          // A dangling or unreadable target remains part of the symlink state.
+        }
+        return createHash("sha256")
+          .update(
+            Buffer.concat([
+              Buffer.from("symlink\0"),
+              target,
+              Buffer.from([0]),
+              content,
+            ]),
+          )
+          .digest("hex");
+      }
+      if (info.isFile()) {
+        return createHash("sha256")
+          .update(
+            Buffer.concat([Buffer.from("file\0"), fs.readFileSync(location)]),
+          )
+          .digest("hex");
+      }
+      return createHash("sha256").update("other\0").digest("hex");
+    } catch {
+      return createHash("sha256").update("missing\0").digest("hex");
+    }
+  }
+
+  /**
+   * Physical path of a location whose leaf may not exist yet.
+   *
+   * Both ends go through the shared spelling rule rather than `path.resolve`
+   * alone. Windows hands back extended-length paths from a native realpath, and
+   * a record written as `\?\C:\project` never matches a lookup for `C:\project`
+   * even though one file is meant — the split identity every other consumer on
+   * this branch was taught to avoid.
+   */
+  function realLSPProjectInputPath(location: string): string {
+    const absolute = resolveProjectInputPath(location);
+    let probe = absolute;
+    const suffix: string[] = [];
+    for (;;) {
+      try {
+        const resolved = resolveProjectInputPath(fs.realpathSync.native(probe));
+        return path.join(resolved, ...suffix.reverse());
+      } catch {
+        const parent = path.dirname(probe);
+        if (parent === probe) return path.normalize(absolute);
+        suffix.push(path.basename(probe));
+        probe = parent;
+      }
+    }
+  }
+
+  /**
+   * Best-effort resolved spelling of an entry's parent joined with its own
+   * basename, preserving the leaf link rather than resolving its target. Failed
+   * parent probes retain unresolved suffixes; if every probe fails, the
+   * normalized lexical spelling is returned. This does not pin identity.
+   *
+   * @evidence contracts/common.md#principled-implementation Resolving available parent ancestors and reattaching the basename preserves the leaf coordinate used by exact reload-file fingerprints. Failed resolution falls back to lexical spelling rather than certifying a physical identity.
+   * @evidence contracts/common.md#clear-and-simple-design Parent canonicalization stays with one private resolver; this public adapter expresses the leaf-preserving operation in one native join.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts All failed realpath probes are treated as unresolved, including failures other than absence. Suffixes remain beneath a resolved ancestor, or the normalized original path is returned when no ancestor resolves.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph explains why the leaf differs from its ancestors, and separated tags follow the documentation skill.
+   * @evidence contracts/portability.md#os-neutral-implementation Shared native spelling normalization handles extended Windows paths while native dirname/basename/join preserve POSIX names; no unconditional case folding is used.
+   * @evidence contracts/performance.md#efficient-algorithms The ancestor walk makes one native realpath probe per visited parent until success or root. Repeated dirname/basename/path normalization and the final join depend on path text lengths; retained suffix strings and joined spelling are local, with no directory traversal.
+   *
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Ancestor aliases may retarget between captures, so this current resolver owns no reusable validity proof or persistent canonicalization cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only local path components are retained through the synchronous walk; no handle or cross-call path history survives.
+   */
+  export function realLSPProjectInputEntryPath(location: string): string {
+    const absolute = resolveProjectInputPath(location);
+    return path.join(
+      realLSPProjectInputPath(path.dirname(absolute)),
+      path.basename(absolute),
+    );
+  }
+}

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

@@ -0,0 +1,107 @@
+import path from "node:path";
+
+import { hashHostInputPaths } from "../../../plugin/internal/load/hashHostInputPaths";
+import { realpathHostInputPaths } from "../../../plugin/internal/load/realpathHostInputPaths";
+import { GoSourceInputs } from "../../../plugin/internal/source/GoSourceInputs";
+import { collectPluginSourceDirectories } from "../../../plugin/internal/source/collectPluginSourceDirectories";
+import { collectPluginSourceFiles } from "../../../plugin/internal/source/collectPluginSourceFiles";
+import { pluginSourceStateHolds } from "../../../plugin/internal/source/pluginSourceStateHolds";
+import type { ILSPPluginSelectionInputs } from "./ILSPPluginSelectionInputs";
+import { LSPProjectInputDigest } from "./LSPProjectInputDigest";
+
+/**
+ * The inputs a `ttscserver` session's plugin selection was loaded from, which
+ * the native host watches for the life of the session, or `undefined` when one
+ * of them no longer holds the state the load proved.
+ *
+ * A session runs the sidecar binaries and the capabilities one plugin load
+ * resolved at startup. The load read the descriptors and the files they
+ * resolved (`hostInputs`), and it built each binary from the Go sources of its
+ * `pluginSources`; a change to any of them selects other plugins, or builds
+ * another binary, which only a new session loads. The host ends the session
+ * through its reload path when one changes, and the editor starts the next. The
+ * shape each travels in is `ILSPPluginSelectionInputs`.
+ *
+ * What selects the plugins is among them: the project's config chain, whose
+ * `compilerOptions.plugins` names them, and the manifests plugin discovery
+ * reads. A change there is a selection change, as `ttsc --watch` treats it,
+ * rather than only a Program refresh. Left out is a plugin's `configFile` that
+ * no descriptor read, which its plugin declares among its own project inputs.
+ *
+ * Non-deferred inputs are fingerprinted, then recorded content/target proofs
+ * and plugin-source states are checked again. Only paths with a recorded proof
+ * participate in that proof comparison. These sequential observations reject
+ * detected drift; unavailable markers or changes between reads are not a proof
+ * that the complete filesystem stayed fixed throughout capture.
+ *
+ * @param loaded The plugin load of the session.
+ * @returns The inputs, or `undefined` when the load no longer describes the
+ *   filesystem and the selection has to be loaded again.
+ * @evidence contracts/common.md#principled-implementation The manifest groups candidate/source-file digests by directory. Recorded content and physical-target proofs and all plugin-source states are compared again before return; a detected mismatch rejects capture, while sequential reads and unproven paths do not certify every post-load change.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate filtering, source enumeration and proof comparison remain separate; the private recorder owns basename insertion into prototype-free maps, including names such as __proto__.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Source omission rules come from the binary builder's shared constants; stale proofs return undefined instead of replacing a loaded selection with guessed current evidence.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain selection versus program refresh, deferred config inputs and the startup race; parameter/result documentation and separated tags follow the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path operations retain declared spellings and actual realpath observations detect symlink or junction retargeting independently of content equality; no OS name supplies filesystem case policy.
+ * @evidence contracts/performance.md#efficient-algorithms Path normalization/filtering allocates candidate arrays and an excluded set. Each source is walked for directories and again for files; file framing is followed by separate recorded content/realpath proof reads and plugin-source state validation, including its native/toolchain costs. Maps retain path keys and digests while temporary walk/read buffers coexist; directory grouping avoids repeating directory keys per file.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This capture validates a particular completed load against current filesystem state; retained plugin/binary reuse belongs to that load's owner, and cached post-load readings would miss drift.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned maps transfer to the session builder. Supported readers and source-state helpers own their native acquisition/release boundaries; this mapper stores no cross-call capture or running task, and local output has no independent population or byte ceiling.
+ */
+export function captureLSPPluginSelectionInputs(loaded: {
+  deferredHostInputs: readonly string[];
+  hostInputHashes: Readonly<Record<string, string | null>>;
+  hostInputRealpaths: Readonly<Record<string, string | null>>;
+  hostInputs: readonly string[];
+  pluginSources: Readonly<Record<string, string>>;
+}): ILSPPluginSelectionInputs | undefined {
+  const excluded = new Set(
+    loaded.deferredHostInputs.map((file) => path.resolve(file)),
+  );
+  const descriptorInputs = loaded.hostInputs
+    .map((file) => path.resolve(file))
+    .filter((file) => !excluded.has(file));
+  const descriptorFiles: Record<string, Record<string, string>> = {};
+  for (const file of descriptorInputs) record(descriptorFiles, file);
+  const sourceFiles: Record<string, Record<string, string>> = {};
+  for (const source of Object.keys(loaded.pluginSources)) {
+    for (const directory of collectPluginSourceDirectories(source))
+      sourceFiles[path.resolve(directory)] ??= Object.create(null);
+    for (const file of collectPluginSourceFiles(source))
+      record(sourceFiles, path.resolve(file));
+  }
+  const proven = descriptorInputs.filter((file) =>
+    Object.prototype.hasOwnProperty.call(loaded.hostInputHashes, file),
+  );
+  const current = hashHostInputPaths(proven);
+  if (proven.some((file) => current[file] !== loaded.hostInputHashes[file]))
+    return undefined;
+  const physicalInputs = descriptorInputs.filter((file) =>
+    Object.prototype.hasOwnProperty.call(loaded.hostInputRealpaths, file),
+  );
+  const currentRealpaths = realpathHostInputPaths(physicalInputs);
+  if (
+    physicalInputs.some(
+      (file) => currentRealpaths[file] !== loaded.hostInputRealpaths[file],
+    )
+  )
+    return undefined;
+  for (const [directory, state] of Object.entries(loaded.pluginSources))
+    if (!pluginSourceStateHolds(directory, state)) return undefined;
+  return {
+    omittedNames: GoSourceInputs.OMITTED_SOURCE_FILE_NAMES,
+    omittedSuffixes: GoSourceInputs.OMITTED_SOURCE_FILE_SUFFIXES,
+    prunedDirectoryNames: GoSourceInputs.PRUNED_SOURCE_DIRECTORY_NAMES,
+    descriptorFiles,
+    sourceFiles,
+  };
+}
+
+/** Record `file`'s digest under its directory. */
+function record(
+  directories: Record<string, Record<string, string>>,
+  file: string,
+): void {
+  (directories[path.dirname(file)] ??= Object.create(null))[
+    path.basename(file)
+  ] = LSPProjectInputDigest.lspProjectInputFileDigest(file);
+}

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

@@ -0,0 +1,41 @@
+import type { ITtscProjectInputSnapshot } from "../../../structures/internal/ITtscProjectInputSnapshot";
+import { LSPProjectInputDigest } from "./LSPProjectInputDigest";
+
+/**
+ * Capture reload-directory and reload-file fingerprints sequentially for the
+ * startup baseline. These reads do not define one atomic selection instant.
+ *
+ * Reload directory digests describe immediate topology and physical identity;
+ * reload file digests keep the leaf link while resolving its parent. The native
+ * host can validate this startup baseline before accepting watcher coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Attaching each reload input's framed digest to the unchanged declaration preserves the selection-time baseline; later validators compare against those observations instead of blessing a newly sampled state.
+ * @evidence contracts/common.md#clear-and-simple-design Two explicit lanes delegate file and directory semantics to the shared digest namespace and retain the original snapshot's other dependency fields.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Production startup uses these observations before native watcher registration; the exported helper serves that protocol rather than existing solely for parity tests.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation distinguishes topology from content and identifies the startup handoff, with separated tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation File leaves retain their entry coordinate and directory digests use available native identity observations with documented lexical/unavailable fallbacks; declared map keys are not blanket case-folded.
+ * @evidence contracts/performance.md#efficient-algorithms Both lanes process every supplied entry, including duplicates, and delegate ancestor/path probes, possible Windows capability queries, immediate topology byte comparisons/framing or whole-file reads. Returned key/digest maps grow with distinct declared paths; current digest buffers coexist with maps already built, without unrelated dependency-file traversal.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This captures a fresh baseline for a selected session; reuse without observing current reload inputs could certify an older selection and belongs to neither this mapper nor its contract.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Digest maps transfer to the returned snapshot and hold no open handle or process-wide history.
+ */
+export function fingerprintInitialLSPProjectInputSnapshot(
+  snapshot: ITtscProjectInputSnapshot,
+): LSPProjectInputDigest.InitialLSPProjectInputSnapshot {
+  const reloadDirectoryDigests: Record<string, string> = {};
+  const reloadFileDigests: Record<string, string> = {};
+  for (const directory of snapshot.reloadDirectories ?? []) {
+    reloadDirectoryDigests[directory] =
+      LSPProjectInputDigest.lspProjectInputReloadDirectoryDigest(directory);
+  }
+  for (const file of snapshot.reloadFiles ?? []) {
+    reloadFileDigests[file] = LSPProjectInputDigest.lspProjectInputFileDigest(
+      LSPProjectInputDigest.realLSPProjectInputEntryPath(file),
+    );
+  }
+  return {
+    ...snapshot,
+    reloadDirectoryDigests,
+    reloadFileDigests,
+  };
+}

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

@@ -0,0 +1,36 @@
+import { LSPProjectInputDigest } from "./LSPProjectInputDigest";
+
+/**
+ * Whether the currently available reload fingerprints equal the captured
+ * baseline. Equal digests are a startup acceptance check, not proof of an
+ * unchanged filesystem: unavailable-read markers can agree and reads are
+ * sequential.
+ *
+ * @evidence contracts/common.md#principled-implementation Universal comparison of both reload lanes refuses the snapshot on the first differing digest; comparison uses the same capture functions and declared keys that produced the baseline.
+ * @evidence contracts/common.md#clear-and-simple-design Two short-circuiting predicates keep topology and exact-file invalidation visible without duplicating digest framing or physical-path resolution.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing baselines or changed observations compare unequal rather than being replaced with a current digest to manufacture stability.
+ * @evidence contracts/common.md#meaningful-documentation The native comment states the retained selection's validity question; acknowledgment spacing follows the documentation skill and leaves digest details with their documented owner.
+ * @evidence contracts/portability.md#os-neutral-implementation Validation uses the same native topology and best-effort leaf-preserving path operations as capture, including their unresolved-path and unavailable-read fallbacks; platform names do not supply filesystem identity.
+ * @evidence contracts/performance.md#efficient-algorithms Each supplied lane entry is checked at most once, including repeated paths, and a mismatch stops further work. Delegated work includes ancestor/path probes, possible Windows capability queries, topology byte comparisons and framing or whole-file bytes; peak temporary storage belongs to the current digest call.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Fresh filesystem observation is the validity boundary; caching a previous boolean has no independent invalidation proof and would hide an intervening change.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The predicate retains neither snapshots nor handles after the call; its caller owns the baseline lifetime.
+ */
+export function initialLSPProjectInputSnapshotIsCurrent(
+  snapshot: LSPProjectInputDigest.InitialLSPProjectInputSnapshot,
+): boolean {
+  return (
+    (snapshot.reloadDirectories ?? []).every(
+      (directory) =>
+        snapshot.reloadDirectoryDigests[directory] ===
+        LSPProjectInputDigest.lspProjectInputReloadDirectoryDigest(directory),
+    ) &&
+    (snapshot.reloadFiles ?? []).every(
+      (file) =>
+        snapshot.reloadFileDigests[file] ===
+        LSPProjectInputDigest.lspProjectInputFileDigest(
+          LSPProjectInputDigest.realLSPProjectInputEntryPath(file),
+        ),
+    )
+  );
+}

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

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { createCanonicalTempDirectory } from "../../../internal/createCanonicalTempDirectory";
+
+/**
+ * Write the language server's plugin manifest to a private file the Go host can
+ * read.
+ *
+ * The file lives in its own canonical temporary directory, is created
+ * exclusively with POSIX mode 0600. Windows access follows the temporary
+ * directory's inherited ACL; that mode does not establish an ACL guarantee. The
+ * native child consumes the file and `dispose` removes the directory after the
+ * invocation. A failed disposal can be retried; forced termination can prevent
+ * either cleanup owner from running.
+ *
+ * @evidence contracts/common.md#principled-implementation A unique canonical directory and exclusive file creation bind one serialized selection to one invocation; removal belongs to both the consuming child and the launcher's final disposal boundary.
+ * @evidence contracts/common.md#clear-and-simple-design The returned path and disposer expose only the transport ownership needed by the launcher; serialization, acquisition and rollback stay together.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The real manifest is written through native filesystem APIs without environment-size truncation or a substituted payload; cleanup failure is reported rather than disguised as successful removal.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state POSIX permissions, Windows ACL limits, retry and forced-termination limits with separated acknowledgment tags following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Canonical temporary-directory creation and native path joining preserve OS-neutral paths; exclusive creation is portable but POSIX mode bits are explicitly distinguished from Windows ACLs.
+ * @evidence contracts/performance.md#efficient-algorithms JSON serialization traverses supplied properties and can invoke caller conversion before native writing, so work is not bounded only by output bytes. Canonical parent checks/directory allocation, path construction and cleanup add native costs; one transport file uses no extra per-plugin filesystem artifact.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each invocation owns a separate consumable file, so sharing a prior transport would violate lifetime and child consumption even if JSON matched.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One directory and file are owned by the returned disposer; acquisition rollback preserves both errors when removal also fails, and successful disposal marks completion only after removal so a failed cleanup remains retryable.
+ */
+export function materializeLSPPluginManifest(manifest: unknown): {
+  dispose(): void;
+  path: string;
+} {
+  const directory = createCanonicalTempDirectory("ttsc-lsp-");
+  const location = path.join(directory, "plugins.json");
+  try {
+    fs.writeFileSync(location, JSON.stringify(manifest), {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (error) {
+    try {
+      fs.rmSync(directory, { force: true, recursive: true });
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        "ttscserver: manifest creation and cleanup failed",
+      );
+    }
+    throw error;
+  }
+  let disposed = false;
+  return {
+    dispose(): void {
+      if (disposed) return;
+      fs.rmSync(directory, { force: true, recursive: true });
+      disposed = true;
+    },
+    path: location,
+  };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * `--stdio` is the only transport the native host accepts today. The launcher
+ * injects it for any nonempty invocation other than a top-level meta-command;
+ * meta-commands (`-v`, `--help`, `version`, etc.) pass through untouched so the
+ * Go binary owns the canonical banner. This mirrors
+ * `cmd/ttscserver/main.go::run`, which dispatches on `args[0]` only.
+ *
+ * @evidence contracts/common.md#principled-implementation An exact --stdio token suppresses injection anywhere in argv; empty input and first-token help/version requests also pass through. Otherwise the launcher prepends the transport flag, while actual native option acceptance remains with the Go parser.
+ * @evidence contracts/common.md#clear-and-simple-design A single predicate owns transport injection and examines top-level meta dispatch without duplicating native option parsing.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Help/version tokens are native command discriminants, not fixture exceptions; caller argv remains untouched and no foreign dispatch behavior is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the supported transport and first-token distinction with a blank line before tags according to the documentation skill.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources needsStdio acquires no handle, buffer or cache and retains nothing after it returns.
+ * @evidence contracts/performance.md#efficient-algorithms The exact-token includes scan visits up to A supplied arguments before six first-token comparisons. Cost depends on the scanned argument strings; it allocates no output argv or path structure.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This argv predicate does not coordinate requests or establish a reusable computation lifetime; the caller owns each invocation and its argument vector.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation needsStdio computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+ */
+export function needsStdio(argv: readonly string[]): boolean {
+  if (argv.length === 0) return false;
+  if (argv.includes("--stdio")) return false;
+  const head = argv[0];
+  if (
+    head === "-v" ||
+    head === "--version" ||
+    head === "version" ||
+    head === "-h" ||
+    head === "--help" ||
+    head === "help"
+  ) {
+    return false;
+  }
+  return true;
+}