@ttsc/graph 0.30.3 → 0.31.0

package/src/model/TtscGraphShardStore.ts

@@ -4,9 +4,26 @@ import { createHash } from "node:crypto";
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
 import { isArtifactNodeKind } from "../structures/TtscGraphArtifactNodeKind";
+import { TtscGraphReadonly } from "./TtscGraphReadonly";
+import { copyGraphRecords } from "./copyGraphRecords";
+import { copyGraphSnapshot } from "./copyGraphSnapshot";
 import { DUMP_SCHEMA_VERSION } from "./loadGraph";
 
-/** Atomic validator and assembler for native `ttscgraph` shard transactions. */
+/**
+ * Atomic validator and assembler for native ttscgraph shard transactions.
+ *
+ * A transaction is committed only after base coordinates, digests, ownership
+ * and the complete manifest agree. Rejected transactions preserve prior state.
+ *
+ * @evidence contracts/common.md#principled-implementation Content digests and consecutive base coordinates qualify source-owned shards before cross-shard assembly and atomic state replacement.
+ * @evidence contracts/common.md#clear-and-simple-design The store owns committed generation state; private validation and assembly helpers keep wire checks outside consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Stale bases or inconsistent contents are rejected rather than merged under compensating guesses.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the commit boundary and preserved prior state; public methods describe validation and canonical hashing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms apply owns staged validation and assembly algorithms; this declaration defines committed state.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work apply establishes permission to reuse unchanged shard payloads.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources apply owns population replacement and the session owns store retirement; the class declaration performs no independent lifecycle transition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation validates and assembles in-memory shard objects; no file, path or process.
+ */
 export class TtscGraphShardStore {
   static readonly PROTOCOL_VERSION = 1;
 
@@ -16,11 +33,51 @@ export class TtscGraphShardStore {
   private tsconfig: string | undefined;
   private shards = new Map<
     string,
-    { digest: string; shard: ITtscGraphSnapshot.IShard }
+    { digest: string; shard: TtscGraphReadonly<ITtscGraphSnapshot.IShard> }
   >();
 
-  /** Validate and atomically commit one complete or base-generation delta. */
+  /**
+   * Validate and atomically commit one complete or base-generation delta.
+   *
+   * Throws on invalid coordinates, repeated changes, content/manifest mismatch
+   * or inconsistent ownership. The prior generation remains committed until
+   * full dump assembly succeeds. Retained shard records are detached and
+   * frozen; the returned dump owns mutable copies of those records.
+   *
+   * @evidence contracts/common.md#principled-implementation A staged shard map validates changes, exact manifest and generation hash before assembly establishes node/edge/config ownership and commits state together.
+   * @evidence contracts/common.md#clear-and-simple-design One operation owns transaction staging and the final state swap; helper validators do not independently mutate committed fields.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A bad delta is not retried against an invented base or partially applied to the resident store.
+   * @evidence contracts/common.md#meaningful-documentation Native prose documents rejection causes and the unchanged-state guarantee before the tags.
+   * @evidence contracts/performance.md#efficient-algorithms Map staging and manifest/ownership scans are linear in shards and facts; canonical hashes cost changed content bytes and deterministic dump sorting costs O(N log N + E log E).
+   * @evidence contracts/performance.md#reuse-equivalent-work Unchanged frozen shard payloads retain their validated digest in the staged map; only upserts are rehashed, while the generation manifest validates continued membership and mutable output copies cannot change retained facts.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The store retains only the current manifest's shards and coordinates; commit drops removed payloads and rejection leaves the prior generation intact.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation validates and assembles shard objects in memory and hashes JSON text with node:crypto; no file, path or process.
+   */
   apply(transaction: ITtscGraphSnapshot.ITransaction): ITtscGraphDump {
+    return this.applyProjection(transaction, (dump) =>
+      copyGraphRecords<ITtscGraphDump>(dump),
+    );
+  }
+
+  /**
+   * Validate a staged immutable population and commit only after projection.
+   *
+   * The callback borrows store-owned frozen facts, not caller DTOs. A thrown
+   * projection leaves every committed coordinate and shard unchanged.
+   *
+   * @evidence contracts/common.md#principled-implementation Full transaction/manifest/ownership validation precedes projection and the synchronous commit; callback failure cannot publish a partial generation.
+   * @evidence contracts/common.md#clear-and-simple-design Public mutable apply and resident immutable projection share the same staged validator and commit boundary.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Immutable borrowing does not remove any digest, universe, owner or edge check; apply still returns a detached mutable DTO.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states input ownership and callback-failure atomicity.
+   * @evidence contracts/performance.md#efficient-algorithms Changed shards are cloned/hashed once; full manifest/ownership scans and deterministic sorting remain. The resident callback avoids full nested mutable materialization.
+   * @evidence contracts/performance.md#reuse-equivalent-work Retained frozen payload identities survive staged validation, qualifying downstream reuse independently of caller-owned transactions.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Commit retains only current shards; rejected staging and callback values remain local, with prior state intact.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Hashes and validates in-memory records without filesystem or process operations.
+   */
+  applyProjection<T>(
+    transaction: ITtscGraphSnapshot.ITransaction,
+    project: (dump: TtscGraphReadonly<ITtscGraphDump>) => T,
+  ): T {
     this.assertCoordinates(transaction);
     const next = new Map(this.shards);
     const touched = new Set<string>();
@@ -50,7 +107,10 @@ export class TtscGraphShardStore {
           `@ttsc/graph: native shard ${upsert.shard.key} digest ${upsert.digest} does not match ${digest}`,
         );
       }
-      next.set(upsert.shard.key, { digest, shard: upsert.shard });
+      next.set(upsert.shard.key, {
+        digest,
+        shard: copyGraphSnapshot(upsert.shard),
+      });
     }
 
     const manifest = [...transaction.manifest];
@@ -93,15 +153,30 @@ export class TtscGraphShardStore {
     }
 
     const dump = assemble(transaction, next);
+    const projected = project(dump);
     this.sequence = transaction.sequence;
     this.generation = transaction.generation;
     this.project = transaction.project;
     this.tsconfig = transaction.tsconfig;
     this.shards = next;
-    return dump;
+    return projected;
   }
 
-  /** SHA-256 over the producer's deterministic Go JSON encoding. */
+  /**
+   * SHA-256 over the producer's deterministic Go JSON encoding.
+   *
+   * JSON-serializable wire shards use producer field order and Go's escaping
+   * for HTML-sensitive characters and Unicode line separators.
+   *
+   * @evidence contracts/common.md#principled-implementation Canonical Go-compatible JSON escaping and UTF-8 SHA-256 reproduce the producer's content witness for the supplied wire shard.
+   * @evidence contracts/common.md#clear-and-simple-design One helper shares canonical digest logic with generation verification.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest checks compare content rather than a size/time proxy or expected fixture hash.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states serializability, ordering and escaping premises needed for cross-language digest equivalence.
+   * @evidence contracts/performance.md#efficient-algorithms Serialization preserves the wire object's insertion order, escapes Go-sensitive characters in one text pass and hashes the resulting bytes once.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This digest primitive computes one shard identity; apply coordinates continued reuse of validated payloads.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The digest string transfers to its caller and the canonical buffer is local to this computation.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation hashes the canonical JSON text of one shard with node:crypto; no file, path or process.
+   */
   static shardDigest(shard: ITtscGraphSnapshot.IShard): string {
     return digest(shard);
   }
@@ -165,13 +240,13 @@ function assemble(
   transaction: ITtscGraphSnapshot.ITransaction,
   committed: ReadonlyMap<
     string,
-    { digest: string; shard: ITtscGraphSnapshot.IShard }
+    { digest: string; shard: TtscGraphReadonly<ITtscGraphSnapshot.IShard> }
   >,
-): ITtscGraphDump {
-  const nodes: ITtscGraphDump.INode[] = [];
-  const edges: ITtscGraphDump.IEdge[] = [];
-  const diagnostics: ITtscGraphDump.IDiagnostic[] = [];
-  const sources: ITtscGraphDump.ISourceDigest[] = [];
+): TtscGraphReadonly<ITtscGraphDump> {
+  const nodes: TtscGraphReadonly<ITtscGraphDump.INode>[] = [];
+  const edges: TtscGraphReadonly<ITtscGraphDump.IEdge>[] = [];
+  const diagnostics: TtscGraphReadonly<ITtscGraphDump.IDiagnostic>[] = [];
+  const sources: TtscGraphReadonly<ITtscGraphDump.ISourceDigest>[] = [];
   const nodeOwners = new Map<string, string>();
   const sourceFiles = new Set<string>();
   const configInputs = new Map<string, string>();
@@ -208,7 +283,7 @@ function assemble(
         );
       }
       sourceFiles.add(shard.source.file);
-      sources.push({ ...shard.source });
+      sources.push(shard.source);
     }
     assertShardContents(key, shard);
     for (const node of shard.nodes) {
@@ -221,8 +296,9 @@ function assemble(
       nodeOwners.set(node.id, key);
       nodes.push(node);
     }
-    edges.push(...shard.edges);
-    diagnostics.push(...shard.diagnostics);
+    for (const entryToAppend of shard.edges) edges.push(entryToAppend);
+    for (const entryToAppend of shard.diagnostics)
+      diagnostics.push(entryToAppend);
   }
   for (const [key, value] of committed) {
     for (const edge of value.shard.edges) {
@@ -269,10 +345,10 @@ function assemble(
       left.code - right.code,
   );
   sources.sort((left, right) => compareText(left.file, right.file));
-  return {
+  return Object.freeze({
     project: transaction.project,
     tsconfig: transaction.tsconfig,
-    provenance: {
+    provenance: copyGraphSnapshot({
       schemaVersion: transaction.schemaVersion,
       capabilities: [...transaction.capabilities],
       producer: { ...transaction.producer },
@@ -281,16 +357,16 @@ function assemble(
         roots: transaction.universe.roots.map((root) => ({ ...root })),
       },
       sources,
-    },
-    diagnostics,
-    nodes,
-    edges,
-  };
+    }),
+    diagnostics: Object.freeze(diagnostics),
+    nodes: Object.freeze(nodes),
+    edges: Object.freeze(edges),
+  });
 }
 
 function assertShardContents(
   key: string,
-  shard: ITtscGraphSnapshot.IShard,
+  shard: TtscGraphReadonly<ITtscGraphSnapshot.IShard>,
 ): void {
   if (shard.source !== undefined) {
     for (const node of shard.nodes) {

package/src/model/TtscGraphSourceReader.ts

@@ -9,12 +9,25 @@ type ReadFile = (file: string) => Buffer;
 /**
  * Immutable, provenance-gated source lines owned by one graph snapshot.
  *
- * Signatures and declaration docs are display facts derived from source text,
- * but the live disk is not the snapshot the checker resolved. A file becomes
- * readable here only after its current bytes hash to `diskDigest` and the
- * compiler-decoded text hashes to `checkerDigest`. Both success and failure are
- * cached, so every consumer of a `TtscGraphMemory` sees one adjudication and
- * one immutable line array.
+ * Declaration documentation is a display fact derived from source text, but the
+ * live disk is not the snapshot the checker resolved. A file becomes readable
+ * here only after its current bytes hash to `diskDigest` and the
+ * compiler-decoded text hashes to `checkerDigest`. Manifest members cache both
+ * success and failure, so every consumer of a `TtscGraphMemory` sees one
+ * adjudication and one immutable line array. Unknown names remain uncached;
+ * they have no snapshot witness to adjudicate.
+ *
+ * Marked UTF-16 files follow the compiler's Unicode scalar decoding: valid
+ * surrogate pairs remain intact and unpaired surrogates become U+FFFD.
+ *
+ * @evidence contracts/common.md#principled-implementation Raw-byte SHA-256 establishes disk identity before compiler-equivalent BOM removal and Unicode scalar decoding; decoded-text SHA-256 then establishes checker identity.
+ * @evidence contracts/common.md#clear-and-simple-design One snapshot reader owns provenance selection, decoding and per-file adjudication rather than letting consumers read disk independently.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing provenance or digest mismatch yields absence instead of mixing current source into old checker facts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the dual witnesses, immutable lines and cached failure behavior.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms lines owns hashing, decoding and splitting strategy through its private helpers.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work lines coordinates per-generation success/absence reuse; the declaration exposes that owner.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources lines controls retained per-file entries and the graph owns reader lifetime; the declaration adds no separate acquisition or release.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The type exposes a source-reading contract; lines and its helpers perform the native filesystem boundary.
  */
 export class TtscGraphSourceReader {
   private readonly project: string;
@@ -47,20 +60,27 @@ export class TtscGraphSourceReader {
 
   /**
    * Return frozen lines only when raw disk bytes and compiler-decoded text both
-   * equal the checker snapshot. A missing manifest entry, read failure, or
-   * digest mismatch is a cached absence rather than a reason to mix current
+   * equal the checker snapshot. Missing manifest entries return absence without
+   * storage or disk access. For manifest members, missing digests, read failure
+   * and digest mismatch are cached absences rather than reasons to mix current
    * disk text into old graph facts.
+   *
+   * @evidence contracts/common.md#principled-implementation Normalized file lookup, raw hash, BOM-aware decoding with the compiler's unpaired-surrogate replacement and checker-text hash establish both byte and semantic snapshot identity before freezing lines.
+   * @evidence contracts/common.md#clear-and-simple-design One path adjudicates all source display reads, with decoding/hash helpers isolated from cache ownership.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing witnesses return absence without disk access; changed bytes remain a cached absence rather than a fallback to unverified live text.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes uncached unknown names from cached adjudications of manifest members.
+   * @evidence contracts/portability.md#os-neutral-implementation Dump separators are normalized only for manifest lookup; Node path.resolve and fs read the project-native location without inferring case policy from OS.
+   * @evidence contracts/performance.md#efficient-algorithms A first read costs linear file bytes for hashes, BOM decoding and line splitting; later lookups use the per-file map.
+   * @evidence contracts/performance.md#reuse-equivalent-work Manifest-member success and absence are cached by normalized path within one immutable provenance generation; unknown names need only a map lookup and a new graph creates a new reader.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Only manifest members can enter the adjudication cache, bounding retained entries and line arrays by the snapshot source population; releasing the owning graph releases both maps.
    */
   lines(file: string): readonly string[] | undefined {
     const key = normalize(file);
     if (this.cache.has(key)) return this.cache.get(key);
 
     const expected = this.digests.get(key);
-    if (
-      expected === undefined ||
-      expected.checker === "" ||
-      expected.disk === ""
-    ) {
+    if (expected === undefined) return undefined;
+    if (expected.checker === "" || expected.disk === "") {
       this.cache.set(key, undefined);
       return undefined;
     }
@@ -95,12 +115,14 @@ function normalize(file: string): string {
   return file.replace(/\\/g, "/");
 }
 
+/** Decode complete UTF-16 units to compiler scalars; ignore a trailing byte. */
 function decodeSource(bytes: Buffer): string {
   if (bytes.length >= 2) {
     const body = bytes.subarray(2, bytes.length - ((bytes.length - 2) % 2));
-    if (bytes[0] === 0xff && bytes[1] === 0xfe) return body.toString("utf16le");
+    if (bytes[0] === 0xff && bytes[1] === 0xfe)
+      return body.toString("utf16le").toWellFormed();
     if (bytes[0] === 0xfe && bytes[1] === 0xff)
-      return Buffer.from(body).swap16().toString("utf16le");
+      return Buffer.from(body).swap16().toString("utf16le").toWellFormed();
   }
   if (
     bytes.length >= 3 &&

package/src/model/TtscLintDaemon.ts

@@ -1,12 +1,7 @@
-import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
-import readline from "node:readline";
-
-/** One plugin sidecar this daemon can be opened against. */
-export interface ITtscLintDaemonTarget {
-  binary: string;
-  manifest: string;
-  projectContext?: string;
-}
+import type { ITtscLintDaemonTarget } from "./ITtscLintDaemonTarget";
+import { TtscGraphLinePeer } from "./TtscGraphLinePeer";
+import { TtscGraphNativeArguments } from "./TtscGraphNativeArguments";
+import { TtscLintDaemonState } from "./TtscLintDaemonState";
 
 /**
  * A resident `@ttsc/lint` sidecar, kept open across the questions one graph
@@ -24,19 +19,38 @@ export interface ITtscLintDaemonTarget {
  * at all, and a daemon can die mid-session; each of those closes this one and
  * leaves the caller to spawn per verb, which is the behaviour that existed
  * before this and is still correct — only slower.
+ *
+ * @evidence contracts/common.md#principled-implementation Serialized line requests match FIFO responses; unsupported or failed daemon replies return null so callers can use the same direct verb contract.
+ * @evidence contracts/common.md#clear-and-simple-design This facade owns one sidecar's launch identity; daemon state owns FIFO replies/fallback and the shared line adapter owns its native transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed daemon is retired rather than advertised as a successful empty artifact set.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain resident amortization and the supported direct-command fallback rather than claiming all failures are empty results.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ask delegates FIFO processing and fallback to daemon state; this declaration describes the real sidecar launch identity.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ask owns continued process/configuration reuse and invalidation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ask and close own acquisition, failure and shutdown transitions; the declaration adds no independent lifecycle operation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Native invocation and termination decisions are acknowledged on ask and close together with private helpers.
  */
 export class TtscLintDaemon {
-  private child: ChildProcessWithoutNullStreams | undefined;
-  private lines: readline.Interface | undefined;
-  private readonly pending: ((reply: IReply | null) => void)[] = [];
-  private queue: Promise<unknown> = Promise.resolve();
-  private failed = false;
+  private readonly state: TtscLintDaemonState;
 
   public constructor(
     private readonly target: ITtscLintDaemonTarget,
     private readonly cwd: string,
     private readonly tsconfig: string,
-  ) {}
+  ) {
+    this.state = new TtscLintDaemonState((events) =>
+      TtscGraphLinePeer.open(
+        this.target.binary,
+        TtscGraphNativeArguments.lint(
+          this.cwd,
+          this.tsconfig,
+          this.target.manifest,
+          this.target.projectContext,
+        ),
+        events,
+        { cwd: this.cwd, stderr: "drain" },
+      ),
+    );
+  }
 
   /**
    * Ask one verb and return its raw JSON, or `null` when this daemon cannot
@@ -50,130 +64,35 @@ export class TtscLintDaemon {
    * Requests are serialized. The daemon answers one line per request in order,
    * with nothing in the reply to address it by, so a second request in flight
    * would be matched against the first one's answer.
+   *
+   * @evidence contracts/common.md#principled-implementation A promise queue admits one request at a time because the protocol orders responses without request ids; result text preserves arbitrary JSON values.
+   * @evidence contracts/common.md#clear-and-simple-design ask delegates queue admission and reply decoding to daemon state; its configured opener supplies actual native transport and supported sidecar argv.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Null explicitly requests a direct fallback; it cannot silently masquerade as no published artifacts.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain null meaning and why requests must be serialized.
+   * @evidence contracts/performance.md#efficient-algorithms Each request writes and decodes one JSON frame; queue work is linear in serialized frame bytes with one active reply.
+   * @evidence contracts/performance.md#reuse-equivalent-work The same target/project sidecar retains process, plugin load and configuration across verbs; invalidate explicitly retires warm Program facts when input generations change.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The daemon owns one child and reader; close settles pending replies and kills the child, while queued promises remain proportional to submitted caller demand.
+   * @evidence contracts/portability.md#os-neutral-implementation spawn passes executable and an argv vector directly with windowsHide, preserving spaces and native executable semantics without shell quoting.
    */
   public ask(verb: string, invalidate: boolean): Promise<string | null> {
-    const run = this.queue.then(() => this.send(verb, invalidate));
-    this.queue = run.catch(() => undefined);
-    return run;
+    return this.state.ask(verb, invalidate);
   }
 
-  /** Stop the sidecar. Safe to call more than once, and after a failure. */
-  public close(): void {
-    this.failed = true;
-    for (const settle of this.pending.splice(0)) settle(null);
-    this.lines?.close();
-    this.lines = undefined;
-    const child = this.child;
-    this.child = undefined;
-    if (child === undefined) return;
-    child.stdin.end();
-    child.kill();
-  }
-
-  private async send(
-    verb: string,
-    invalidate: boolean,
-  ): Promise<string | null> {
-    if (this.failed) return null;
-    const child = this.start();
-    if (child === undefined) return null;
-    const reply = await new Promise<IReply | null>((resolve) => {
-      this.pending.push(resolve);
-      child.stdin.write(
-        `${JSON.stringify({ invalidate, verb })}\n`,
-        (error) => {
-          if (error === null || error === undefined) return;
-          this.fail();
-        },
-      );
-    });
-    if (reply === null || reply.code !== 0) {
-      // A nonzero code is the sidecar declining, and this client cannot tell
-      // "unknown verb" from "the rule failed". Closing rather than retrying
-      // through the daemon is what makes the caller fall back to the direct
-      // command, where a real failure surfaces the same way it always did.
-      this.close();
-      return null;
-    }
-    return reply.result;
-  }
-
-  private start(): ChildProcessWithoutNullStreams | undefined {
-    if (this.child !== undefined) return this.child;
-    if (this.failed) return undefined;
-    let child: ChildProcessWithoutNullStreams;
-    try {
-      child = spawn(
-        this.target.binary,
-        [
-          "lsp-serve",
-          `--cwd=${this.cwd}`,
-          `--tsconfig=${this.tsconfig}`,
-          `--plugins-json=${this.target.manifest}`,
-          ...(this.target.projectContext === undefined
-            ? []
-            : [`--project-context-json=${this.target.projectContext}`]),
-        ],
-        { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
-      );
-    } catch {
-      this.failed = true;
-      return undefined;
-    }
-    this.child = child;
-    // The sidecar's stderr is its own diagnostic channel and is not this
-    // client's to interpret; draining it keeps a chatty plugin from filling the
-    // pipe and stalling the daemon it is talking through.
-    child.stderr.resume();
-    child.on("error", () => this.fail());
-    child.on("exit", () => this.fail());
-    this.lines = readline.createInterface({ input: child.stdout });
-    this.lines.on("line", (line) => this.onLine(line));
-    return child;
-  }
-
-  private onLine(line: string): void {
-    const settle = this.pending.shift();
-    if (settle === undefined) return;
-    let reply: IReply;
-    try {
-      reply = JSON.parse(line) as IReply;
-    } catch {
-      settle(null);
-      return;
-    }
-    settle(
-      typeof reply.code === "number"
-        ? { code: reply.code, result: rawResult(line) }
-        : null,
-    );
-  }
-
-  private fail(): void {
-    this.close();
+  /**
+   * Stop the sidecar. Safe to call more than once, and after a failure.
+   *
+   * Pending replies settle null so callers can switch to the direct command.
+   *
+   * @evidence contracts/common.md#principled-implementation Marking failed before settling requests prevents new daemon work while reader and child ownership are cleared.
+   * @evidence contracts/common.md#clear-and-simple-design One shutdown operation is shared by explicit disposal and transport failure.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown does not invent a successful reply to unblock a request.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states idempotence, failure safety and the meaning of settled null replies.
+   * @evidence contracts/performance.md#efficient-algorithms Closing visits outstanding reply callbacks once and clears the reader/child references.
+   * @evidence contracts/performance.md#reuse-equivalent-work Closure retires this target's reusable process permanently; later calls return the supported direct-fallback indication.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Both normal and failed shutdown settle pending callbacks, close readline and end/kill the owned process; the returned completion still joins stdio after process exit and rejects unknown or forced termination.
+   * @evidence contracts/portability.md#os-neutral-implementation Node stream closure and child.kill own native termination rather than platform shell commands.
+   */
+  public close(): Promise<void> {
+    return this.state.close();
   }
 }
-
-/** One `lsp-serve` reply: a verb result and the code that qualifies it. */
-interface IReply {
-  code: number;
-  result: string;
-}
-
-/**
- * The `result` member, as the JSON text this daemon's callers parse.
- *
- * A verb's result is arbitrary JSON that the caller decodes itself, so it is
- * handed back as text rather than as a value — which is what the direct command
- * hands over, and what keeps the two paths interchangeable. The text is
- * re-serialized rather than sliced out of the line: the bytes are not identical
- * to the sidecar's own, but the value they decode to is, and no caller here
- * reads anything else.
- *
- * A reply with no `result` is `"null"`, so a caller parses a value either way
- * instead of being handed the empty string.
- */
-function rawResult(line: string): string {
-  const parsed = JSON.parse(line) as { result?: unknown };
-  return parsed.result === undefined ? "null" : JSON.stringify(parsed.result);
-}