@ttsc/graph 0.19.2 → 0.20.0

package/src/model/TtscGraphMemory.ts

@@ -4,16 +4,19 @@ import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphSpan } from "../structures/ITtscGraphSpan";
 import { TtscGraphEdgeKind } from "../structures/TtscGraphEdgeKind";
+import { ttscGraphNodeIdPath } from "./TtscGraphNodeId";
+import { TtscGraphSourceReader } from "./TtscGraphSourceReader";
 
 /**
  * The in-memory resident graph the MCP tools answer from.
  *
  * It loads one `ttscgraph dump` — the checker-resolved fact graph — then
  * synthesizes the structural relationships the dump deliberately leaves to this
- * layer: `file` container nodes, the `contains` ownership tree, and `exports`
- * edges, plus class/interface member implementation edges and the refinement of
- * a class-member `variable` to a `property`. Every tool call is then a lookup
- * or a traversal over the indexes built here; nothing recompiles.
+ * layer: `file` container nodes and the `contains` ownership tree, plus the
+ * refinement of a class-member `variable` to a `property`. Export and member
+ * implementation relationships are checker facts already present in the dump.
+ * Every tool call is then a lookup or traversal over the indexes built here;
+ * nothing recompiles.
  */
 export class TtscGraphMemory {
   private readonly byId: Map<string, ITtscGraphNode>;
@@ -26,17 +29,21 @@ export class TtscGraphMemory {
   readonly project: string;
   /** Every node, raw plus synthesized (file containers). */
   readonly nodes: readonly ITtscGraphNode[];
-  /** Every edge, raw plus synthesized (contains, exports). */
+  /** Every edge, raw plus synthesized containment. */
   readonly edges: readonly ITtscGraphEdge[];
+  /** Provenance-gated source display facts cached for this exact snapshot. */
+  readonly source: TtscGraphSourceReader;
 
   private constructor(
     project: string,
     nodes: ITtscGraphNode[],
     edges: ITtscGraphEdge[],
+    provenance: ITtscGraphDump.IProvenance,
   ) {
     this.project = project;
     this.nodes = nodes;
     this.edges = edges;
+    this.source = new TtscGraphSourceReader(project, provenance);
 
     this.byId = new Map(nodes.map((n) => [n.id, n]));
     this.byNameIndex = new Map();
@@ -63,7 +70,7 @@ export class TtscGraphMemory {
   /** Build a model from a parsed dump, synthesizing structural relationships. */
   static from(dump: ITtscGraphDump): TtscGraphMemory {
     const { nodes, edges } = synthesize(dump);
-    return new TtscGraphMemory(dump.project, nodes, edges);
+    return new TtscGraphMemory(dump.project, nodes, edges, dump.provenance);
   }
 
   /** The node with this id, or undefined. */
@@ -113,13 +120,23 @@ function keyOf(node: ITtscGraphNode): string {
   return node.qualifiedName ?? node.name;
 }
 
-/** The owner key of a dotted key (`A.B.c` -> `A.B`), or "" for a top-level key. */
-function ownerKey(key: string): string {
-  const dot = key.lastIndexOf(".");
-  return dot >= 0 ? key.slice(0, dot) : "";
+/**
+ * The owner key derived from facts the producer serialized separately.
+ *
+ * A quoted member named `"a.b"` has Name `a.b` and QualifiedName `Box.a.b`.
+ * Cutting the qualified name at its last dot invents owner `Box.a`; removing
+ * the exact `.${name}` suffix instead preserves the producer's real boundary.
+ */
+function ownerKey(node: ITtscGraphNode): string | undefined {
+  if (node.qualifiedName === undefined || node.qualifiedName === node.name)
+    return undefined;
+  const suffix = `.${node.name}`;
+  if (!node.qualifiedName.endsWith(suffix)) return undefined;
+  const owner = node.qualifiedName.slice(0, -suffix.length);
+  return owner === "" ? undefined : owner;
 }
 
-/** A file's id and node name from its project-relative path. */
+/** A file's id and node name from its schema-v6 path coordinate. */
 function fileNodeId(file: string): string {
   return file;
 }
@@ -138,8 +155,7 @@ function spanIn(span: ITtscGraphSpan, file: string): ITtscGraphEvidence {
  * file node's id is the path itself.
  */
 function fileOfNodeId(id: string): string {
-  const hash = id.indexOf("#");
-  return hash === -1 ? id : id.slice(0, hash);
+  return ttscGraphNodeIdPath(id) ?? id;
 }
 
 function basename(file: string): string {
@@ -149,8 +165,8 @@ function basename(file: string): string {
 
 /**
  * Derive the structural layer from a dump's faithful facts: refine class-member
- * variables to properties, add a `file` node per workspace source, and connect
- * the `contains` ownership tree and `exports` surface.
+ * variables to properties, add a `file` node per workspace source, connect the
+ * `contains` ownership tree, and re-anchor compiler-owned `exports` edges.
  */
 function synthesize(dump: ITtscGraphDump): {
   nodes: ITtscGraphNode[];
@@ -207,8 +223,8 @@ function synthesize(dump: ITtscGraphDump): {
     if (!node.external) byFileKey.set(node.file + "\0" + keyOf(node), node);
   }
   const owner = (node: ITtscGraphNode): ITtscGraphNode | undefined => {
-    const parent = ownerKey(keyOf(node));
-    if (parent === "") return undefined;
+    const parent = ownerKey(node);
+    if (parent === undefined) return undefined;
     return byFileKey.get(node.file + "\0" + parent);
   };
 
@@ -250,11 +266,9 @@ function synthesize(dump: ITtscGraphDump): {
   // public, which is the fact that cannot tell a package's front door from its
   // legacy subpath.
   const structural: ITtscGraphEdge[] = [];
-  const membersByOwner = new Map<string, ITtscGraphNode[]>();
   for (const node of nodes) {
     if (node.external || node.file === "") continue;
     const parent = owner(node);
-    if (parent !== undefined) push(membersByOwner, parent.id, node);
     const container = parent ? parent.id : fileNodeId(node.file);
     structural.push({
       from: container,
@@ -263,48 +277,8 @@ function synthesize(dump: ITtscGraphDump): {
     });
   }
 
-  const synthesized = [...edges, ...structural];
-  const edgeKeys = new Set(
-    synthesized.map((edge) => `${edge.kind}\0${edge.from}\0${edge.to}`),
-  );
-  const byId = new Map(nodes.map((node) => [node.id, node]));
-  for (const edge of edges) {
-    const kind: TtscGraphEdgeKind | undefined =
-      edge.kind === "implements"
-        ? "implements"
-        : edge.kind === "extends"
-          ? "overrides"
-          : undefined;
-    if (kind === undefined) continue;
-    const derived = byId.get(edge.from);
-    const base = byId.get(edge.to);
-    if (derived === undefined || base === undefined) continue;
-    const derivedMembers = membersByOwner.get(derived.id) ?? [];
-    const baseMembers = membersByOwner.get(base.id) ?? [];
-    for (const baseMember of baseMembers) {
-      const derivedMember = derivedMembers.find(
-        (member) =>
-          member.name === baseMember.name &&
-          implementationMemberKinds.has(member.kind) &&
-          implementationMemberKinds.has(baseMember.kind),
-      );
-      if (derivedMember === undefined) continue;
-      const key = `${kind}\0${derivedMember.id}\0${baseMember.id}`;
-      if (edgeKeys.has(key)) continue;
-      edgeKeys.add(key);
-      synthesized.push({
-        from: derivedMember.id,
-        to: baseMember.id,
-        kind,
-        evidence: derivedMember.implementation ?? derivedMember.evidence,
-      });
-    }
-  }
-
   return {
     nodes: [...nodes, ...fileNodes.values()],
-    edges: synthesized,
+    edges: [...edges, ...structural],
   };
 }
-
-const implementationMemberKinds = new Set(["method", "property"]);

package/src/model/TtscGraphNodeId.ts

@@ -0,0 +1,77 @@
+/** The structured components carried by a graph symbol id. */
+export interface ITtscGraphNodeId {
+  path: string;
+  name: string;
+  kind?: string;
+}
+
+/**
+ * Decode the graph's position-invariant `path#name:kind` identity.
+ *
+ * The producer quotes `#` and `\\` inside path and name. This reader also
+ * accepts pre-codec ordinary ids, so a current package can read an older dump.
+ */
+export function parseTtscGraphNodeId(id: string): ITtscGraphNodeId | undefined {
+  const hash = graphNodeIdHash(id);
+  if (hash < 0) return undefined;
+  const tail = id.slice(hash + 1);
+  if (tail === "") return undefined;
+  const colon = tail.lastIndexOf(":");
+  if (colon === 0 || colon === tail.length - 1) return undefined;
+  return {
+    path: unescapeGraphNodeIdPart(id.slice(0, hash)),
+    name: unescapeGraphNodeIdPart(colon < 0 ? tail : tail.slice(0, colon)),
+    ...(colon < 0 ? {} : { kind: tail.slice(colon + 1) }),
+  };
+}
+
+/** Encode a symbol identity without making its component boundaries ambiguous. */
+export function writeTtscGraphNodeId(
+  path: string,
+  name: string,
+  kind: string,
+): string {
+  return `${escapeGraphNodeIdPart(path)}#${escapeGraphNodeIdPart(name)}:${kind}`;
+}
+
+/** Return the raw path component when id is a symbol identity. */
+export function ttscGraphNodeIdPath(id: string): string | undefined {
+  return parseTtscGraphNodeId(id)?.path;
+}
+
+function escapeGraphNodeIdPart(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll("#", "\\#");
+}
+
+function unescapeGraphNodeIdPart(value: string): string {
+  let result = "";
+  for (let index = 0; index < value.length; index++) {
+    const next = value[index + 1];
+    if (value[index] === "\\" && next !== undefined) {
+      if (next === "#" || (next === "\\" && !legacyUNCStart(value, index))) {
+        result += next;
+        index++;
+        continue;
+      }
+    }
+    result += value[index];
+  }
+  return result;
+}
+
+function legacyUNCStart(value: string, index: number): boolean {
+  return (
+    index === 0 && value.length > 2 && value[2] !== "\\" && value[2] !== "#"
+  );
+}
+
+function graphNodeIdHash(id: string): number {
+  for (let index = 0; index < id.length; index++) {
+    if (id[index] !== "#") continue;
+    let slashes = 0;
+    for (let slash = index - 1; slash >= 0 && id[slash] === "\\"; slash--)
+      slashes++;
+    if (slashes % 2 === 0) return index;
+  }
+  return -1;
+}

package/src/model/TtscGraphSession.ts

@@ -6,6 +6,7 @@ import { ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
 import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
 import { TtscGraphMemory } from "./TtscGraphMemory";
+import { DUMP_SCHEMA_VERSION } from "./loadGraph";
 
 /**
  * The serve protocol version this client speaks.
@@ -16,10 +17,44 @@ import { TtscGraphMemory } from "./TtscGraphMemory";
  * constant out of this file and fails if the pair drifts.
  */
 const PROTOCOL_VERSION = 1;
+const DEFAULT_REQUEST_TIMEOUT_MS = 300_000;
+const MAX_TIMER_MS = 2_147_483_647;
+const TERMINATION_GRACE_MS = 1_000;
 
 interface Pending {
+  child: NativeChild;
   resolve: (response: ITtscGraphSnapshot) => void;
   reject: (error: Error) => void;
+  timer: NodeJS.Timeout;
+  signal?: AbortSignal;
+  abort?: () => void;
+}
+
+interface NativeChild {
+  process: ChildProcessWithoutNullStreams;
+  lines: readline.Interface;
+  stderr: string;
+}
+
+/** Construction options for a resident native graph session. */
+export interface TtscGraphSessionOptions {
+  /** Project root passed to `ttscgraph serve`. */
+  cwd: string;
+  /** Project tsconfig passed to `ttscgraph serve`. */
+  tsconfig: string;
+  /** Absolute native binary path, resolved from `cwd` when omitted. */
+  binary?: string;
+  /**
+   * Maximum time for one native snapshot response. Defaults to five minutes,
+   * which is more than ten times the published 28.7-second VS Code cold index.
+   */
+  requestTimeoutMs?: number;
+}
+
+/** Per-call controls for a native graph refresh. */
+export interface TtscGraphRequestOptions {
+  /** Cancel this refresh and retire its native session. */
+  signal?: AbortSignal;
 }
 
 /**
@@ -34,19 +69,26 @@ export class TtscGraphSession {
   private readonly cwd: string;
   private readonly tsconfig: string;
   private readonly binary: string;
-  private child: ChildProcessWithoutNullStreams | undefined;
-  private stderr = "";
+  private readonly requestTimeoutMs: number;
+  private child: NativeChild | undefined;
   private nextId = 0;
   private readonly pending = new Map<number, Pending>();
   private queue: Promise<void> = Promise.resolve();
   private current: TtscGraphMemory | undefined;
   private closed = false;
 
-  public constructor(options: {
-    cwd: string;
-    tsconfig: string;
-    binary?: string;
-  }) {
+  public constructor(options: TtscGraphSessionOptions) {
+    const requestTimeoutMs =
+      options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (
+      !Number.isSafeInteger(requestTimeoutMs) ||
+      requestTimeoutMs <= 0 ||
+      requestTimeoutMs > MAX_TIMER_MS
+    ) {
+      throw new TypeError(
+        `@ttsc/graph: requestTimeoutMs must be an integer between 1 and ${String(MAX_TIMER_MS)}`,
+      );
+    }
     // Resolve the platform binary from the project this session serves, so the
     // MCP server started from an unrelated directory still finds the target's
     // installed `ttsc`.
@@ -63,21 +105,48 @@ export class TtscGraphSession {
     this.cwd = options.cwd;
     this.tsconfig = options.tsconfig;
     this.binary = binary;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
 
   /** Return a graph for the current disk snapshot, serialized per tool call. */
-  public graph(): Promise<TtscGraphMemory> {
+  public graph(
+    options: TtscGraphRequestOptions = {},
+  ): Promise<TtscGraphMemory> {
+    if (this.closed) {
+      return Promise.reject(new Error("@ttsc/graph: native session is closed"));
+    }
     let resolve!: (graph: TtscGraphMemory) => void;
     let reject!: (error: Error) => void;
+    let started = false;
+    let settled = false;
     const result = new Promise<TtscGraphMemory>((res, rej) => {
-      resolve = res;
-      reject = rej;
+      resolve = (graph) => {
+        if (settled) return;
+        settled = true;
+        res(graph);
+      };
+      reject = (error) => {
+        if (settled) return;
+        settled = true;
+        rej(error);
+      };
     });
+    const cancelQueued = () => {
+      if (!started) reject(cancelledError(options.signal));
+    };
+    if (options.signal?.aborted) {
+      reject(cancelledError(options.signal));
+      return result;
+    }
+    options.signal?.addEventListener("abort", cancelQueued, { once: true });
     this.queue = this.queue
       .catch(() => undefined)
       .then(async () => {
+        started = true;
+        options.signal?.removeEventListener("abort", cancelQueued);
+        if (settled) return;
         try {
-          resolve(await this.refresh());
+          resolve(await this.refresh(options.signal));
         } catch (error) {
           reject(asError(error));
         }
@@ -87,17 +156,17 @@ export class TtscGraphSession {
 
   /** Close the native session. Safe to call more than once. */
   public close(): void {
+    if (this.closed) return;
     this.closed = true;
-    const child = this.child;
-    this.child = undefined;
-    if (child !== undefined && !child.killed) child.stdin.end();
-    this.failPending(new Error("@ttsc/graph: native session closed"));
+    const error = new Error("@ttsc/graph: native session closed");
+    if (this.child !== undefined) this.failChild(this.child, error);
+    else this.failPending(error);
   }
 
-  private async refresh(): Promise<TtscGraphMemory> {
+  private async refresh(signal?: AbortSignal): Promise<TtscGraphMemory> {
     // The protocol version and the envelope shape were both settled in onLine,
     // before this frame was ever routed here.
-    const response = await this.request();
+    const response = await this.request(signal);
     if (response.error !== undefined) {
       throw new Error(`@ttsc/graph: ${response.error}`);
     }
@@ -117,15 +186,41 @@ export class TtscGraphSession {
     return this.current;
   }
 
-  private request(): Promise<ITtscGraphSnapshot> {
+  private request(signal?: AbortSignal): Promise<ITtscGraphSnapshot> {
+    if (signal?.aborted) throw cancelledError(signal);
     const child = this.ensureChild();
     const id = ++this.nextId;
     return new Promise<ITtscGraphSnapshot>((resolve, reject) => {
-      this.pending.set(id, { resolve, reject });
-      child.stdin.write(`${JSON.stringify({ id })}\n`, (error) => {
+      const pending: Pending = {
+        child,
+        resolve,
+        reject,
+        timer: setTimeout(() => {
+          this.failChild(
+            child,
+            new Error(
+              `@ttsc/graph: native snapshot request timed out after ${String(this.requestTimeoutMs)} ms${stderrSuffix(child)}`,
+            ),
+          );
+        }, this.requestTimeoutMs),
+        signal,
+      };
+      pending.timer.unref();
+      if (signal !== undefined) {
+        pending.abort = () =>
+          this.failChild(child, cancelledError(signal, child));
+        signal.addEventListener("abort", pending.abort, { once: true });
+      }
+      this.pending.set(id, pending);
+      if (signal?.aborted) {
+        pending.abort!();
+        return;
+      }
+      child.process.stdin.write(`${JSON.stringify({ id })}\n`, (error) => {
         if (error === null || error === undefined) return;
-        this.pending.delete(id);
-        reject(
+        if (this.pending.get(id) !== pending) return;
+        this.failChild(
+          child,
           new Error(
             `@ttsc/graph: could not request native snapshot: ${error.message}`,
           ),
@@ -134,49 +229,61 @@ export class TtscGraphSession {
     });
   }
 
-  private ensureChild(): ChildProcessWithoutNullStreams {
+  private ensureChild(): NativeChild {
     if (this.closed) {
       // A request queued behind the close must not respawn the native
       // process; an orphaned resident compiler would outlive the MCP server.
       throw new Error("@ttsc/graph: native session is closed");
     }
-    if (this.child !== undefined && this.child.exitCode === null) {
+    if (
+      this.child !== undefined &&
+      this.child.process.exitCode === null &&
+      this.child.process.signalCode === null
+    ) {
       return this.child;
     }
-    this.stderr = "";
-    const child = spawn(
+    const process = spawn(
       this.binary,
       ["serve", "--cwd", this.cwd, "--tsconfig", this.tsconfig],
       { stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
     );
+    const lines = readline.createInterface({ input: process.stdout });
+    const child: NativeChild = { process, lines, stderr: "" };
     this.child = child;
-    child.stderr.setEncoding("utf8");
-    child.stderr.on("data", (chunk: string) => {
-      this.stderr = (this.stderr + chunk).slice(-64 * 1024);
+    process.stderr.setEncoding("utf8");
+    process.stderr.on("data", (chunk: string) => {
+      child.stderr = (child.stderr + chunk).slice(-64 * 1024);
     });
-    const lines = readline.createInterface({ input: child.stdout });
-    lines.on("line", (line) => this.onLine(line));
-    child.on("error", (error) => this.failChild(child, error));
-    child.on("exit", (code, signal) => {
+    lines.on("line", (line) => this.onLine(child, line));
+    process.on("error", (error) =>
+      this.failChild(
+        child,
+        new Error(`@ttsc/graph: native session failed: ${error.message}`),
+      ),
+    );
+    process.on("exit", (code, signal) => {
       if (this.child !== child) return;
-      this.child = undefined;
-      this.failPending(
+      this.failChild(
+        child,
         new Error(
-          `@ttsc/graph: native session exited (code=${String(code)}, signal=${String(signal)})${
-            this.stderr.trim() === "" ? "" : `: ${this.stderr.trim()}`
-          }`,
+          `@ttsc/graph: native session exited (code=${String(code)}, signal=${String(signal)})${stderrSuffix(
+            child,
+          )}`,
         ),
+        false,
       );
     });
     return child;
   }
 
-  private onLine(line: string): void {
+  private onLine(child: NativeChild, line: string): void {
+    if (this.child !== child) return;
     let parsed: unknown;
     try {
       parsed = JSON.parse(line);
     } catch (error) {
-      this.failPending(
+      this.failChild(
+        child,
         new Error(
           `@ttsc/graph: native session returned invalid JSON: ${asError(error).message}`,
         ),
@@ -198,7 +305,8 @@ export class TtscGraphSession {
     if (version !== PROTOCOL_VERSION) {
       // Session-wide: a version mismatch is not one bad frame, it is the wrong
       // binary, and every request against it is equally doomed.
-      this.failPending(
+      this.failChild(
+        child,
         new Error(
           `@ttsc/graph: ttscgraph speaks serve protocol ${
             version === undefined ? "an unknown version" : `v${String(version)}`
@@ -219,30 +327,122 @@ export class TtscGraphSession {
       // envelope belongs on this side of that line.
       response = typia.assert<ITtscGraphSnapshot>(parsed);
     } catch (error) {
-      this.failPending(
+      this.failChild(
+        child,
         new Error(
           `@ttsc/graph: native session returned an unreadable response: ${asError(error).message}`,
         ),
       );
       return;
     }
+    // The envelope's version is not the body's, and only the envelope has been
+    // held to one so far. A producer can speak this protocol and still carry a
+    // dump from another schema — the two move apart the moment a node field is
+    // added without the frame around it changing — and then the facts that field
+    // holds are silently absent rather than refused. `literals` is exactly that
+    // shape: an older producer resolves no value set, so a union comes back
+    // looking like a type with no members. Hold the body to its own number too,
+    // once the frame is understood.
+    if (
+      response.dump !== undefined &&
+      response.dump.provenance.schemaVersion !== DUMP_SCHEMA_VERSION
+    ) {
+      // Session-wide, for the same reason the protocol mismatch above is: it is
+      // the wrong binary, not one bad frame.
+      this.failChild(
+        child,
+        new Error(
+          `@ttsc/graph: ttscgraph sends dump schema v${String(
+            response.dump.provenance.schemaVersion,
+          )}, this client reads v${String(DUMP_SCHEMA_VERSION)}. ` +
+            "Install a matching `ttsc` (the binary resolves from the target " +
+            "project, or from TTSC_GRAPH_BINARY).",
+        ),
+      );
+      return;
+    }
+
     const pending = this.pending.get(response.id);
-    if (pending === undefined) return;
-    this.pending.delete(response.id);
-    pending.resolve(response);
+    if (pending === undefined || pending.child !== child) return;
+    this.settlePending(response.id, pending, response);
   }
 
-  private failChild(child: ChildProcessWithoutNullStreams, error: Error): void {
-    if (this.child === child) this.child = undefined;
-    this.failPending(
-      new Error(`@ttsc/graph: native session failed: ${error.message}`),
-    );
+  private failChild(child: NativeChild, error: Error, terminate = true): void {
+    if (this.child !== child) return;
+    this.child = undefined;
+    this.current = undefined;
+    child.lines.close();
+    this.failPending(error, child);
+    if (terminate) terminateChild(child.process);
   }
 
-  private failPending(error: Error): void {
-    for (const pending of this.pending.values()) pending.reject(error);
-    this.pending.clear();
+  private failPending(error: Error, child?: NativeChild): void {
+    for (const [id, pending] of this.pending) {
+      if (child === undefined || pending.child === child) {
+        this.settlePending(id, pending, error);
+      }
+    }
   }
+
+  private settlePending(
+    id: number,
+    pending: Pending,
+    result: ITtscGraphSnapshot | Error,
+  ): void {
+    if (this.pending.get(id) !== pending) return;
+    this.pending.delete(id);
+    clearTimeout(pending.timer);
+    if (pending.signal !== undefined && pending.abort !== undefined) {
+      pending.signal.removeEventListener("abort", pending.abort);
+    }
+    if (result instanceof Error) pending.reject(result);
+    else pending.resolve(result);
+  }
+}
+
+function terminateChild(child: ChildProcessWithoutNullStreams): void {
+  if (!child.stdin.destroyed) child.stdin.destroy();
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    child.kill();
+  } catch {
+    return;
+  }
+  const force = setTimeout(() => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // The process exited between the liveness check and the signal.
+    }
+  }, TERMINATION_GRACE_MS);
+  force.unref();
+  child.once("exit", () => clearTimeout(force));
+}
+
+function cancelledError(signal?: AbortSignal, child?: NativeChild): Error {
+  const error = new Error(
+    `@ttsc/graph: native snapshot request cancelled${abortDetail(signal)}${
+      child === undefined ? "" : stderrSuffix(child)
+    }`,
+  );
+  error.name = "AbortError";
+  return error;
+}
+
+function abortDetail(signal?: AbortSignal): string {
+  const reason = signal?.reason;
+  if (reason === undefined) return "";
+  try {
+    return `: ${reason instanceof Error ? reason.message : String(reason)}`;
+  } catch {
+    return "";
+  }
+}
+
+function stderrSuffix(child: NativeChild): string {
+  const stderr = child.stderr.trim();
+  return stderr === "" ? "" : `: ${stderr}`;
 }
 
 function asError(error: unknown): Error {