@ttsc/graph 0.30.4 → 0.31.0

package/src/nativeExecutable.ts

@@ -2,6 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import type { CapturedProcessOutput } from "./CapturedProcessOutput";
+
 /**
  * Ensure a resolved native binary can be executed on POSIX installs.
  *
@@ -9,6 +11,15 @@ import path from "node:path";
  * package binaries without executable bits. The ttsc launcher already repairs
  * its native helper before spawning; @ttsc/graph has its own ttscgraph spawn
  * paths, so it must apply the same first-run repair here.
+ *
+ * @evidence contracts/common.md#principled-implementation POSIX executable access is checked before preserving existing permission bits and adding the required execution permissions.
+ * @evidence contracts/common.md#clear-and-simple-design This helper owns the native permission boundary for all graph spawn lanes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Permission repair addresses supported package installation differences; failures still reach the original spawn path.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the package-manager condition and why graph must apply its own spawn-boundary repair.
+ * @evidence contracts/performance.md#efficient-algorithms Permission repair uses constant-count access/stat/chmod operations without reading binary contents or scanning directories.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Permission is an effectful spawn precondition, not a completed producer result shared across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This precondition retains no handle, task or historical entry after synchronous filesystem calls.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows has no POSIX executable-bit requirement; other hosts use filesystem access and mode APIs rather than path spelling assumptions.
  */
 export function ensureExecutable(binary: string): void {
   if (process.platform === "win32") return;
@@ -25,15 +36,6 @@ export function ensureExecutable(binary: string): void {
   }
 }
 
-export interface CapturedProcessOutput {
-  /** Close the descriptors and remove the backing files. */
-  dispose(): void;
-  /** Read one stream's text. */
-  read(stream: "stdout" | "stderr"): string;
-  stderrFd: number;
-  stdoutFd: number;
-}
-
 /**
  * A pair of temporary files standing in for a child process's pipes.
  *
@@ -46,12 +48,27 @@ export interface CapturedProcessOutput {
  * the same answer everywhere. Reading the result back still materializes a
  * string, so V8's own maximum string length remains the outer bound — a
  * property of the runtime rather than a budget chosen here.
+ *
+ * @evidence contracts/common.md#principled-implementation Passing file descriptors avoids spawnSync's pipe-buffer limit while later UTF-8 reads preserve each output channel.
+ * @evidence contracts/common.md#clear-and-simple-design One factory transfers descriptor and directory ownership through a read/dispose handle; private helpers isolate cleanup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The capture uses supported spawn descriptors rather than patching child_process or imposing repository-sized output limits.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain file capture, heap materialization and the runtime string-length boundary; the handle documents caller disposal.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs descriptors and path.join operate on every host; storage is created beneath the resolved physical system-temp directory.
+ * @evidence contracts/performance.md#efficient-algorithms Capturing writes directly to files; reading costs linear output bytes and materializes one stream string, with no pipe-buffer copy in this heap.
+ * @evidence contracts/performance.md#reuse-equivalent-work Stdout and stderr are distinct effectful streams from one child invocation; reruns require new storage and cannot reuse a prior result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned owner disposes two descriptors and one directory; acquisition failure unwinds acquired storage and removal is best effort when foreign handles remain open.
  */
 export function captureProcessOutput(): CapturedProcessOutput {
   const directory = createCanonicalTempDirectory("ttscgraph-spawn-");
   const stdoutPath = path.join(directory, "stdout");
   const stderrPath = path.join(directory, "stderr");
-  const stdoutFd = fs.openSync(stdoutPath, "w+");
+  let stdoutFd: number;
+  try {
+    stdoutFd = fs.openSync(stdoutPath, "w+");
+  } catch (error) {
+    removeQuietly(directory);
+    throw error;
+  }
   let stderrFd: number;
   try {
     stderrFd = fs.openSync(stderrPath, "w+");
@@ -62,20 +79,18 @@ export function captureProcessOutput(): CapturedProcessOutput {
     removeQuietly(directory);
     throw error;
   }
+  let disposed = false;
   return {
     dispose(): void {
+      if (disposed) return;
+      disposed = true;
       closeQuietly(stdoutFd);
       closeQuietly(stderrFd);
       removeQuietly(directory);
     },
     read(stream): string {
       const location = stream === "stdout" ? stdoutPath : stderrPath;
-      try {
-        return fs.readFileSync(location, "utf8");
-      } catch {
-        // A spawn that never launched leaves nothing behind.
-        return "";
-      }
+      return fs.readFileSync(location, "utf8");
     },
     stderrFd,
     stdoutFd,
@@ -85,24 +100,76 @@ export function captureProcessOutput(): CapturedProcessOutput {
 /** Create capture storage beneath the frozen physical system-temp parent. */
 function createCanonicalTempDirectory(prefix: string): string {
   const physicalParent = fs.realpathSync.native(os.tmpdir());
-  if (!fs.lstatSync(physicalParent).isDirectory()) {
+  const parentIdentity = fs.lstatSync(physicalParent);
+  if (!parentIdentity.isDirectory()) {
     throw new Error(
       `@ttsc/graph: temporary directory parent is not a directory: ${physicalParent}`,
     );
   }
   const directory = fs.mkdtempSync(path.join(physicalParent, prefix));
-  if (!fs.lstatSync(directory).isDirectory()) {
-    throw new Error(
-      `@ttsc/graph: temporary directory postflight is not a directory: ${directory}`,
+  let childIdentity: fs.Stats | undefined;
+  try {
+    childIdentity = fs.lstatSync(directory);
+    if (!childIdentity.isDirectory() || childIdentity.isSymbolicLink()) {
+      throw new Error(
+        `@ttsc/graph: temporary directory postflight is not a directory: ${directory}`,
+      );
+    }
+    const physicalDirectory = fs.realpathSync.native(directory);
+    if (path.dirname(physicalDirectory) !== physicalParent) {
+      throw new Error(
+        `@ttsc/graph: temporary directory escaped its physical parent: ${physicalDirectory}`,
+      );
+    }
+    return physicalDirectory;
+  } catch (error) {
+    removeUnchangedTempDirectory(
+      directory,
+      physicalParent,
+      prefix,
+      parentIdentity,
+      childIdentity,
     );
+    throw error;
   }
-  const physicalDirectory = fs.realpathSync.native(directory);
-  if (path.dirname(physicalDirectory) !== physicalParent) {
-    throw new Error(
-      `@ttsc/graph: temporary directory escaped its physical parent: ${physicalDirectory}`,
-    );
+}
+
+/** Roll back only an unchanged direct child whose native ownership was seen. */
+function removeUnchangedTempDirectory(
+  directory: string,
+  parent: string,
+  prefix: string,
+  parentIdentity: fs.Stats,
+  childIdentity: fs.Stats | undefined,
+): void {
+  if (
+    childIdentity === undefined ||
+    !childIdentity.isDirectory() ||
+    childIdentity.isSymbolicLink() ||
+    path.dirname(directory) !== parent ||
+    !path.basename(directory).startsWith(prefix)
+  )
+    return;
+  try {
+    const currentParent = fs.lstatSync(parent);
+    const currentChild = fs.lstatSync(directory);
+    if (
+      fs.realpathSync.native(parent) !== parent ||
+      !currentParent.isDirectory() ||
+      currentParent.isSymbolicLink() ||
+      currentParent.dev !== parentIdentity.dev ||
+      currentParent.ino !== parentIdentity.ino ||
+      !currentChild.isDirectory() ||
+      currentChild.isSymbolicLink() ||
+      currentChild.dev !== childIdentity.dev ||
+      currentChild.ino !== childIdentity.ino
+    )
+      return;
+    removeQuietly(directory);
+  } catch {
+    // Failed ownership checks leave storage untouched rather than delete a
+    // replacement or an unrelated canonical target.
   }
-  return physicalDirectory;
 }
 
 /** Close a descriptor, ignoring one that is already closed. */

package/src/reduce.ts

@@ -1,3 +1,10 @@
+import type { RawDump } from "./structures/RawDump";
+import type { RawEdge } from "./structures/RawEdge";
+import type { RawNode } from "./structures/RawNode";
+import type { ViewerLink } from "./structures/ViewerLink";
+import type { ViewerNode } from "./structures/ViewerNode";
+import type { ViewerPayload } from "./structures/ViewerPayload";
+
 // Reduce a raw `ttscgraph dump` to the payload the bundled 3D viewer renders.
 // The same pure transform is copied in
 // website/src/components/graph/TtscWebsiteGraphReduce.ts and
@@ -8,56 +15,6 @@
 // before serving, so the browser viewer only ever renders a ready
 // `{ nodes, links }`.
 
-export interface RawNode {
-  id: string;
-  name: string;
-  kind: string;
-  file: string;
-  external?: boolean;
-  ignored?: boolean;
-}
-
-export interface RawEdge {
-  from: string;
-  to: string;
-  kind: string;
-}
-
-export interface RawDump {
-  project?: string;
-  nodes: RawNode[];
-  edges: RawEdge[];
-}
-
-export interface ViewerNode {
-  id: string;
-  name: string;
-  kind: string;
-  file: string;
-  degree: number;
-}
-
-export interface ViewerLink {
-  source: string;
-  target: string;
-  kind: string;
-}
-
-export interface ViewerPayload {
-  project: string;
-  counts: {
-    rawNodes: number;
-    rawEdges: number;
-    nodes: number;
-    links: number;
-    droppedExternal: number;
-    droppedIgnored: number;
-    droppedByCap: number;
-  };
-  nodes: ViewerNode[];
-  links: ViewerLink[];
-}
-
 function posix(p: string): string {
   return p.replace(/\\/g, "/");
 }
@@ -233,9 +190,25 @@ const DISPLAY_KIND: Record<string, string> = {
 };
 
 function displayKind(kind: string): string {
-  return DISPLAY_KIND[kind] ?? kind;
+  return Object.hasOwn(DISPLAY_KIND, kind) ? DISPLAY_KIND[kind]! : kind;
 }
 
+/**
+ * Project a dump into a connected viewer graph, retaining high-degree nodes.
+ *
+ * Current portable coordinates retain their spelling. Legacy absolute paths are
+ * rerooted together, and node ids and edge endpoints use the same rewrite.
+ * Boundary and cap counters explain selection; isolated nodes are not drawn.
+ *
+ * @evidence contracts/common.md#principled-implementation Boundary selection precedes induced-edge filtering and degree ranking; final edge membership and matching identity rewrites preserve the displayed subgraph.
+ * @evidence contracts/common.md#clear-and-simple-design Pure projection separates path/identity codec, degree calculation and display-family mapping through private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Paths outside the common root keep identity rather than collapse to basename; filters use producer flags and general kinds without fixture lists.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains legacy/current coordinates and selection losses; DTO members document identity, degree and each counter.
+ * @evidence contracts/performance.md#efficient-algorithms Node/edge scans and degree maps cost O(N+E); degree selection sorts at most N nodes, adding O(N log N), with temporary maps/arrays proportional to the input.
+ * @evidence contracts/performance.md#reuse-equivalent-work Within one projection, indexed live/kept id sets and degree maps serve multiple filters; callers share the resulting payload across render requests rather than repeat reduction.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Temporary arrays and indexes become unreachable after return; the caller owns only selected DTO arrays and counts, with selected populations bounded by maxNodes and induced edges.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation rewrites path strings as text (separators and common root); it never opens, stats or resolves them.
+ */
 export function reduce(
   raw: RawDump,
   {

package/src/resolveGraphBinary.ts

@@ -25,6 +25,15 @@ import path from "node:path";
  *    or an API `cwd` option), defaulting to `process.cwd()` when no project was
  *    named. A launcher started from an unrelated directory still resolves the
  *    `ttsc` installed under the target project it was asked to graph.
+ *
+ * @evidence contracts/common.md#principled-implementation Project-anchored module resolution locates the peer ttsc and then its platform binary; an explicit absolute override has precedence.
+ * @evidence contracts/common.md#clear-and-simple-design One resolver owns override and peer-package lookup for all graph launchers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Resolution uses installed package contracts rather than guessing binary paths from repository layouts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs and the ordered list explain peer placement, override precedence and target-project anchoring.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path checks and module resolution select the platform/architecture package; only Windows's required executable suffix differs explicitly.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a path string and opens no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms performs a constant number of module resolutions (ttsc, then its platform package).
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work resolves on every call and caches nothing, so a reinstall between calls is honored.
  */
 export function resolveGraphBinary(
   env: NodeJS.ProcessEnv = process.env,
@@ -37,9 +46,10 @@ export function resolveGraphBinary(
   try {
     // Anchor package lookup at the absolute project root so a relative `--cwd`
     // resolves the same way the native process interprets it.
-    const ttscPackageJson = require.resolve("ttsc/package.json", {
-      paths: [path.resolve(cwd)],
-    });
+    const fromProject = createRequire(
+      path.join(path.resolve(cwd), "package.json"),
+    );
+    const ttscPackageJson = fromProject.resolve("ttsc/package.json");
     const fromTtsc = createRequire(ttscPackageJson);
     return fromTtsc.resolve(
       `@ttsc/${process.platform}-${process.arch}/bin/${exe}`,

package/src/runGraph.ts

@@ -0,0 +1,90 @@
+import { TtscGraphLauncherArguments } from "./TtscGraphLauncherArguments";
+import { GraphProcessTrace } from "./internal/GraphProcessTrace";
+import { publishArtifacts } from "./model/publishedArtifacts";
+import { ensureExecutable } from "./nativeExecutable";
+import { resolveGraphBinary } from "./resolveGraphBinary";
+import { startServer } from "./server/startServer";
+import { runView } from "./view";
+
+// The server version reported in the MCP handshake; read from this package.
+const VERSION: string = (require("../package.json") as { version: string })
+  .version;
+
+/**
+ * Run the `@ttsc/graph` launcher.
+ *
+ * - `view`: JS-orchestrated 3D viewer (dump -> reduce -> serve -> open).
+ * - `dump`: pass through to the native `ttscgraph dump`, which prints the whole
+ *   graph as JSON for piping or the viewer.
+ * - Default: serve the MCP graph over stdio. The TypeScript server keeps a native
+ *   incremental compiler session resident, checks the disk snapshot before each
+ *   graph operation, and reuses the in-memory graph when unchanged; the agent's
+ *   MCP client speaks JSON-RPC over this process's stdin/stdout.
+ *
+ * @evidence contracts/common.md#principled-implementation The first command token selects view, native dump or stdio MCP; shared project parsing supplies the producer coordinates consistently.
+ * @evidence contracts/common.md#clear-and-simple-design The launcher owns lane dispatch while viewer, server and native dump helpers own their respective execution boundaries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing dump binary exposes only an explicitly qualified help summary; execution failures retain nonzero outcomes instead of fake graph answers.
+ * @evidence contracts/common.md#meaningful-documentation Native lane bullets explain observable CLI behavior and resident refresh ownership with a blank line before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lanes resolve the selected project's platform package and pass argv directly; stdio MCP uses Node transport APIs without shell path construction.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources starts the stdio server (owned by startServer), runs a synchronous dump child to completion or hands over to runView, and keeps no handle itself.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms dispatches on the first argv token to one lane and the lanes own the work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work runs one launcher lane per process invocation, so there is nothing to share.
+ */
+export function runGraph(
+  argv: readonly string[] = process.argv.slice(2),
+): number | void {
+  if (argv[0] === "view") return runView(argv.slice(1));
+  if (argv[0] === "dump") return runDump(argv.slice(1));
+
+  const { cwd, tsconfig } = TtscGraphLauncherArguments.project(argv);
+  void startServer({ cwd, tsconfig, version: VERSION }).catch(
+    (error: unknown) => {
+      process.stderr.write(
+        `@ttsc/graph: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      process.exit(1);
+    },
+  );
+}
+
+/**
+ * Pass `dump` through to the native binary, inheriting stdio so the JSON lands
+ * on this process's stdout. Returns the child's exit code.
+ */
+function runDump(argv: readonly string[]): number {
+  // Resolve the native binary from the target project the caller named with
+  // `--cwd`, not from wherever the launcher process happened to start.
+  const { cwd, tsconfig, artifactsSpecified } =
+    TtscGraphLauncherArguments.dump(argv);
+  const binary = resolveGraphBinary(process.env, cwd);
+  if (binary === null) {
+    // `ttscgraph` owns the flag contract, so a resolvable binary always answers
+    // `--help` itself and stays the single source of truth. It cannot answer
+    // when it is absent, and that is exactly when a caller is most likely to be
+    // asking what the command needs — so fall back to a summary that names the
+    // authority rather than making usage unreachable behind an install error.
+    const fallback = TtscGraphLauncherArguments.missingDump(argv);
+    if (fallback.stdout !== undefined) process.stdout.write(fallback.stdout);
+    if (fallback.stderr !== undefined) process.stderr.write(fallback.stderr);
+    return fallback.code;
+  }
+  ensureExecutable(binary);
+  // The same artifacts `loadGraph` and the resident session ask for, so the
+  // three ways to reach a dump answer a citation the same way. A caller that
+  // named `--artifacts` itself owns the answer and is not overridden.
+  const published = artifactsSpecified
+    ? null
+    : publishArtifacts({ cwd, tsconfig });
+  const result = GraphProcessTrace.spawnSync(
+    binary,
+    TtscGraphLauncherArguments.dumpVector(argv, published?.file ?? null),
+    {
+      stdio: "inherit",
+      windowsHide: true,
+    },
+  );
+  const completion = TtscGraphLauncherArguments.dumpCompletion(result);
+  if (completion.diagnostic !== undefined)
+    process.stderr.write(completion.diagnostic);
+  return completion.code;
+}

package/src/server/IResolvedGraphHandle.ts

@@ -0,0 +1,24 @@
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
+
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
+
+/**
+ * Exact resolved node, ambiguous candidates or an empty unknown outcome.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional node and candidates preserve the resolver's unique, ambiguous and absent states without fabricating identity.
+ * @evidence contracts/common.md#clear-and-simple-design One compact outcome is shared by direct-id, name and file-qualified resolution paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ranked candidates remain unresolved choices rather than a guessed definitive node.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments distinguish uniquely resolved identity from ranked ambiguity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface IResolvedGraphHandle {
+  /** Present when the handle identifies exactly one node. */
+  node?: ITtscGraphNode;
+
+  /** Ranked remaining choices when more than one identity matches. */
+  candidates?: ITtscGraphNode[];
+}

package/src/server/createServer.ts

@@ -12,37 +12,31 @@ import { ITtscGraphApplication } from "../structures/ITtscGraphApplication";
  * input and output schemas and its argument validator, with no hand-written
  * schema: the interface's JSDoc becomes the handshake instructions, the
  * method's becomes the tool description, and every property's becomes the
- * description of that field — including `audit`, whose JSDoc is how a caller
- * learns what the server checked before it answered.
+ * description of that field — including `audit`, whose JSDoc explains fact
+ * provenance and coverage without claiming a second compiler check.
  *
- * The registration was hand-written here for a while, because a tool that
- * declares an output schema must answer with `structuredContent` and the helper
- * also serialized the same JSON into a text block: the payload crossed the wire
- * twice, a client counted both copies against its tool-result cap, and a 30 KB
- * tour arrived as 60 KB, blew the cap, and was spilled to a file the model then
- * shelled out to read back. `@typia/mcp` 13.1.0 ships the structured result
- * once (samchon/typia#2020), so the hand-written server had nothing left to fix
- * and the library owns the registration again.
+ * The library owns registration and sends structured results once by default.
+ * Its version option identifies this graph server in the handshake without
+ * changing SDK internals after construction.
+ *
+ * @evidence contracts/common.md#principled-implementation The typed controller supplies reflected schemas and executor dispatch; the supported version option sets the MCP implementation identity at construction.
+ * @evidence contracts/common.md#clear-and-simple-design The integration delegates registration and result serialization to the library instead of maintaining another transport implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Handshake version uses the public createMcpServer option; no SDK private field or foreign method is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain schema/JSDoc reflection, structured-result ownership and public version configuration.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a server whose transport lifetime startServer owns.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms builds the MCP server once from the typia controller, with no loop of its own.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work called once per process; the schema reflection happens at compile time.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation creates an in-memory MCP server object; startServer attaches the stdio transport.
  */
 export function createServer(
   graph: TtscGraphSource,
   version: string,
 ): McpServer {
-  const server = createMcpServer(
+  return createMcpServer(
     typia.llm.controller<ITtscGraphApplication>(
       "ttsc-graph",
       new TtscGraphApplication(graph),
     ),
+    { version },
   );
-  // @typia/mcp 13.1.0 exposes no class-controller version option. The MCP SDK
-  // keeps the initialize implementation on its public inner Server, so update
-  // that already-constructed implementation before any transport connects.
-  const inner = server.server as unknown as {
-    _serverInfo?: { version: string };
-  };
-  if (inner._serverInfo === undefined) {
-    throw new Error("@ttsc/graph: MCP SDK omitted the server implementation");
-  }
-  inner._serverInfo.version = version;
-  return server;
 }

package/src/server/exportSurface.ts

@@ -21,6 +21,15 @@ import { TtscGraphMemory } from "../model/TtscGraphMemory";
  *
  * The count is a fact the compiler resolved. It reads no package.json, guesses
  * from no filename, and holds for a project that has neither.
+ *
+ * @evidence contracts/common.md#principled-implementation Counting incoming exports edges reports modules whose checker-resolved export tables publish this exact node.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate supplies the graph-derived public-surface signal to handle and tour ranking.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No package.json, file-name front-door guess or named project's expected score substitutes for export relationships.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain barrel/re-export propagation and distinguish edge count from declaring-file exported status.
+ * @evidence contracts/performance.md#efficient-algorithms The incoming index restricts counting to this node's degree instead of scanning every graph edge.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This count is a primitive over an already shared generation index; caller-owned rank computation decides any broader reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Counting borrows indexed edges and retains only a scalar local accumulator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation counts edges in an in-memory index.
  */
 export function exportFanIn(graph: TtscGraphMemory, id: string): number {
   let count = 0;
@@ -28,7 +37,20 @@ export function exportFanIn(graph: TtscGraphMemory, id: string): number {
   return count;
 }
 
-/** True when the dump carries an export surface at all. */
+/**
+ * True when the graph carries an exports edge at all.
+ *
+ * The answer is cached by immutable graph generation, including false.
+ *
+ * @evidence contracts/common.md#principled-implementation Existence of an exports edge establishes collection of at least one module surface without guessing from local declaration flags.
+ * @evidence contracts/common.md#clear-and-simple-design A WeakMap holds the generation-wide predicate result for all rankers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A false cached answer is retained as a real result rather than mistaken for a cache miss.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the edge criterion and generation-scoped caching.
+ * @evidence contracts/performance.md#efficient-algorithms The first check scans edges until a match; later lookups are map accesses.
+ * @evidence contracts/performance.md#reuse-equivalent-work The model's owned frozen facts make graph identity a stable generation key; a new generation is a different key and does not inherit the result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap entries follow graph reachability and do not retain historical graph generations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation scans in-memory edges and caches the answer per graph object.
+ */
 export function hasExportSurface(graph: TtscGraphMemory): boolean {
   const known = cache.get(graph);
   if (known !== undefined) return known;

package/src/server/formatGraphFailure.ts

@@ -0,0 +1,32 @@
+import { inspect } from "node:util";
+import { serializeCompilerError } from "ttsc";
+
+/**
+ * Render a terminal graph failure with its nested causes and aggregate members.
+ *
+ * The SDK's descriptor-based failure description preserves causes and shared
+ * references without evaluating getters. Node then displays that passive data
+ * without invoking custom inspectors. Proxy reflection retains the serializer's
+ * documented inspection limits.
+ *
+ * It is stderr text, not a serialization format or a retirement certificate.
+ *
+ * @evidence contracts/common.md#principled-implementation The SDK failure serializer preserves nested causes and aggregate members as passive data; Node inspection renders that finite description rather than projecting the outer message.
+ * @evidence contracts/common.md#clear-and-simple-design One renderer owns shutdown diagnostic text; the server continues to own its failing exit status.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Diagnostic formatting changes no cleanup result, admission state or original lifetime proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines nested diagnostics, disabled user hooks and the absence of transport or retirement authority.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This renderer observes JavaScript values and selects no OS path or process primitive.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated serialization visits distinct observed objects and owned fields; unlimited diagnostic inspection then renders that finite description. Structural work and returned text grow with the observed diagnostic graph, excluding arbitrary Proxy reflection.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each failure is rendered when reported; there is no reusable computation population.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned diagnostic string is caller-owned; no handle or retained cache is acquired.
+ */
+export function formatGraphFailure(error: unknown): string {
+  return inspect(serializeCompilerError(error), {
+    depth: null,
+    customInspect: false,
+    getters: false,
+    colors: false,
+    maxArrayLength: null,
+    maxStringLength: null,
+  });
+}