@ttsc/graph 0.30.4 → 0.31.0

package/src/TtscGraphApplication.ts

@@ -16,6 +16,18 @@ import { runTrace } from "./server/runTrace";
 import { ITtscGraphApplication } from "./structures/ITtscGraphApplication";
 import { ITtscGraphEscape } from "./structures/ITtscGraphEscape";
 
+/**
+ * A fixed graph generation or a provider synchronizing one before each request.
+ *
+ * @evidence contracts/common.md#principled-implementation The union admits resident values and synchronous/asynchronous producers with the same graph result contract.
+ * @evidence contracts/common.md#clear-and-simple-design One provider boundary lets dispatch use fixed dumps and refreshing sessions without separate applications.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Refresh remains a supplied ownership boundary instead of foreign graph mutation.
+ * @evidence contracts/common.md#meaningful-documentation The native headline states fixed versus synchronized generation and the provider's timing.
+ * @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 type TtscGraphSource =
   | TtscGraphMemory
   | (() => TtscGraphMemory | Promise<TtscGraphMemory>);
@@ -24,7 +36,7 @@ export type TtscGraphSource =
  * The MCP tool surface as a plain class over the resident
  * {@link TtscGraphMemory}.
  *
- * Its public method is the MCP tool: `typia.llm.application` reflects
+ * Its public method is the MCP tool: `typia.llm.controller` reflects
  * {@link ITtscGraphApplication} to generate the tool's JSON schema and argument
  * validator from the signature and JSDoc, with no hand-written schema, and
  * `@typia/mcp`'s `createMcpServer` registers it (see `./server/createServer`).
@@ -35,6 +47,15 @@ export type TtscGraphSource =
  * that graph before the operation when project files changed. Output is kept
  * compact and bounded so a model can read structure without a file read, which
  * is the token win the redesign exists for.
+ *
+ * @evidence contracts/common.md#principled-implementation Exhaustive request dispatch chooses the matching graph operation and its operation-specific audit; escape bypasses graph acquisition entirely.
+ * @evidence contracts/common.md#clear-and-simple-design The class binds one graph provider to pure runners, leaving traversal and ranking with their owning functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No forced first lookup or agent-specific call suppression is introduced; legitimate escape and incomplete coverage remain explicit.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain reflected tool wiring, provider refresh and source-free result ownership.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources holds only the provider function; the session owns the resources.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms dispatches one request to its runner and the runners own the algorithms.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work each non-escape call asks the provider function for the graph, and the provider owns reuse.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation dispatches to in-memory runners; the provider function owns session and process work.
  */
 export class TtscGraphApplication implements ITtscGraphApplication {
   private readonly graph: () => TtscGraphMemory | Promise<TtscGraphMemory>;
@@ -43,6 +64,22 @@ export class TtscGraphApplication implements ITtscGraphApplication {
     this.graph = typeof source === "function" ? source : () => source;
   }
 
+  /**
+   * Synchronize the graph once and dispatch the selected request.
+   *
+   * Escape returns an explicit no-op before invoking the provider. Ranked
+   * operations report heuristic selection; details distinguishes capped members
+   * from its complete identity facts.
+   *
+   * @evidence contracts/common.md#principled-implementation Each discriminated branch returns its corresponding runner result with the audit appropriate to that operation's actual completeness.
+   * @evidence contracts/common.md#clear-and-simple-design The exhaustive switch owns only dispatch and audit choice; runners own graph semantics and the provider owns synchronization.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Escape does no indexing, and heuristic selection is not advertised as exhaustive compiler proof.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains provider timing, no-op escape and operation-specific completeness before the tags.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources keeps nothing between calls.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms a switch over seven request types that calls one runner.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work each non-escape call asks the provider function for the graph, and the provider owns reuse.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation dispatches to in-memory runners; the provider function owns session and process work.
+   */
   public async inspect_typescript_graph(
     props: ITtscGraphApplication.IProps,
   ): Promise<ITtscGraphApplication.IOutput> {

package/src/TtscGraphLauncherArguments.ts

@@ -0,0 +1,207 @@
+import type { IProjectOptions } from "./IProjectOptions";
+import {
+  PROJECT_OPTIONS,
+  nonNegativeIntegerOption,
+  parseLauncherOptions,
+  positiveIntegerOption,
+  projectOptions,
+} from "./launcherArgs";
+
+/**
+ * Project, viewer and dump argument contracts consumed by the real launchers.
+ *
+ * @evidence contracts/common.md#principled-implementation Existing explicit grammar and typed validators qualify project coordinates before real launch work; dump tokens and completion preserve the native contract.
+ * @evidence contracts/common.md#clear-and-simple-design This namespace owns launcher grammar, dump launch-vector construction and completion mapping; native process execution remains with runGraph/view.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual facades consume these operations without alternate test entrypoints, executable stand-ins or weakened grammar.
+ * @evidence contracts/common.md#meaningful-documentation Member prose identifies coordinate defaults, argv preservation and native completion ownership needed by the facades.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace groups contracts; its members own native path and process-value representation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns plain values and holds no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms groups launcher parsers and completion mappers that each do bounded work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work its members run once per launcher invocation, so nothing is shared.
+ */
+export namespace TtscGraphLauncherArguments {
+  /**
+   * Parse MCP project coordinates with the shared cwd/config defaults.
+   *
+   * @evidence contracts/common.md#principled-implementation The shared PROJECT_OPTIONS grammar rejects unknown or incomplete tokens before projectOptions supplies its supported defaults.
+   * @evidence contracts/common.md#clear-and-simple-design Only the shared project grammar is selected; startServer retains lazy native lifetime ownership.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing public flag and result contracts are used by actual facades without fixture branches or a synthetic producer.
+   * @evidence contracts/common.md#meaningful-documentation The native headline states this operation's input/result ownership and relevant absence/default meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation Project normalization delegates to Node path.resolve; selected config spelling remains intact, with no shell or separator rewriting.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms one parseLauncherOptions pass over argv plus a path.resolve.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work parses argv once per process start.
+   */
+  export function project(argv: readonly string[]): IProjectOptions {
+    return projectOptions(parseLauncherOptions(argv, PROJECT_OPTIONS));
+  }
+
+  /**
+   * Parse dump project coordinates without altering forwarded tokens.
+   *
+   * @evidence contracts/common.md#principled-implementation The original dump grammar accepts its cwd/config aliases, pretty booleans and help flags, rejecting incomplete or unknown options before resolution.
+   * @evidence contracts/common.md#clear-and-simple-design Dump validation returns coordinates and explicit artifact presence; dumpVector separately preserves the caller tokens actually sent to the producer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing public flag and result contracts are used by actual facades without fixture branches or a synthetic producer.
+   * @evidence contracts/common.md#meaningful-documentation The native headline states this operation's input/result ownership and relevant absence/default meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation Project normalization delegates to Node path.resolve; selected config spelling remains intact, with no shell or separator rewriting.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms one parseLauncherOptions pass over argv plus a path.resolve.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work parses argv once per process start.
+   */
+  export function dump(
+    argv: readonly string[],
+  ): IProjectOptions & { artifactsSpecified: boolean } {
+    const values = parseLauncherOptions(argv, DUMP_OPTIONS);
+    return {
+      ...projectOptions(values),
+      artifactsSpecified: values.has("artifacts"),
+    };
+  }
+
+  /**
+   * Parse viewer coordinates and bounded numeric options with existing
+   * defaults.
+   *
+   * @evidence contracts/common.md#principled-implementation The original viewer grammar plus safe integer validators retains port zero through 65,535 and positive maxNodes through Number.MAX_SAFE_INTEGER before graph work.
+   * @evidence contracts/common.md#clear-and-simple-design Project defaults and numeric policy share existing owners; the viewer retains build, reduction and HTTP lifetime.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing public flag and result contracts are used by actual facades without fixture branches or a synthetic producer.
+   * @evidence contracts/common.md#meaningful-documentation The native headline states this operation's input/result ownership and relevant absence/default meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation Project normalization delegates to Node path.resolve; selected config spelling remains intact, with no shell or separator rewriting.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms one parse pass over argv and up to two integer validations.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work parses argv once per process start.
+   */
+  export function view(argv: readonly string[]): IViewOptions {
+    const values = parseLauncherOptions(argv, [
+      { key: "cwd", flags: ["--cwd"], kind: "value" },
+      { key: "tsconfig", flags: ["--tsconfig", "-p"], kind: "value" },
+      { key: "port", flags: ["--port"], kind: "value" },
+      { key: "open", flags: ["--no-open"], kind: "flag" },
+      { key: "max_nodes", flags: ["--max-nodes"], kind: "value" },
+    ]);
+    return {
+      ...projectOptions(values),
+      port:
+        values.has("port") === true
+          ? nonNegativeIntegerOption(values, "port", 65_535)
+          : 0,
+      open: values.get("open") !== true,
+      maxNodes:
+        values.has("max_nodes") === true
+          ? positiveIntegerOption(values, "max_nodes", Number.MAX_SAFE_INTEGER)
+          : 1200,
+    };
+  }
+
+  /**
+   * Preserve native dump argv, adding only a present published-artifact path.
+   *
+   * @evidence contracts/common.md#principled-implementation The dump token precedes the unmodified caller vector; a null publication adds no overlay coordinate.
+   * @evidence contracts/common.md#clear-and-simple-design One vector owner is consumed by the actual dump spawn; resident serve/lint vectors remain distinct in their existing owner.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing public flag and result contracts are used by actual facades without fixture branches or a synthetic producer.
+   * @evidence contracts/common.md#meaningful-documentation The native headline states this operation's input/result ownership and relevant absence/default meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation Separate argv elements preserve path and equals-form spelling exactly for Node spawn, without shell quoting.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a fresh value and keeps no handle or state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms one parse pass over argv and a copy of it with at most two appended entries.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work builds one argv per spawn.
+   */
+  export function dumpVector(
+    argv: readonly string[],
+    artifacts: string | null,
+  ): string[] {
+    const values = parseLauncherOptions(argv, DUMP_OPTIONS);
+    return [
+      "dump",
+      ...argv,
+      ...(artifacts === null || values.has("artifacts")
+        ? []
+        : ["--artifacts", artifacts]),
+    ];
+  }
+
+  /**
+   * Map native completion to its exit code and optional owned spawn diagnostic.
+   *
+   * @evidence contracts/common.md#principled-implementation Actual spawn errors return code one with the existing owned prefix; normal status passes through exactly, and absent status remains failure one.
+   * @evidence contracts/common.md#clear-and-simple-design The actual dump facade writes only the returned diagnostic and returns this code; completion decides no process timing or retry.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing public flag and result contracts are used by actual facades without fixture branches or a synthetic producer.
+   * @evidence contracts/common.md#meaningful-documentation The native headline states this operation's input/result ownership and relevant absence/default meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation Node error and nullable numeric status are preserved as native result representations, with no platform shell exit interpretation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a small record and retains nothing.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms reads two fields of the spawn result in constant time.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work maps one spawn result once.
+   */
+  export function dumpCompletion(result: {
+    error?: Error;
+    status: number | null;
+  }): { code: number; diagnostic?: string } {
+    if (result.error)
+      return { code: 1, diagnostic: `@ttsc/graph: ${result.error.message}\n` };
+    return { code: result.status ?? 1 };
+  }
+
+  /**
+   * Answer help without a producer, or retain the missing-installation failure.
+   *
+   * This summary is a fallback: installed native dump still owns its exact
+   * flags.
+   *
+   * @evidence contracts/common.md#principled-implementation Only the three existing help spellings qualify a missing-producer success; ordinary dump remains code one with the owned installation diagnostic.
+   * @evidence contracts/common.md#clear-and-simple-design The actual unresolved-binary facade writes these channels and returns their code; this operation decides neither resolution nor child execution.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The qualified help summary names the native authority and its possible drift; no graph fact or native success is fabricated.
+   * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes missing-install help from installed authoritative help and ordinary missing-install failure.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This completion maps already parsed tokens to fixed text and numeric code, without filesystem or process operations.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a small record of strings and retains nothing.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms tests argv against three help spellings and returns a constant summary or message.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work answers once per failed binary resolution.
+   */
+  export function missingDump(argv: readonly string[]): {
+    code: 0 | 1;
+    stdout?: string;
+    stderr?: string;
+  } {
+    if (argv.some((argument) => DUMP_HELP_FLAGS.has(argument)))
+      return { code: 0, stdout: DUMP_HELP_SUMMARY };
+    return {
+      code: 1,
+      stderr:
+        "@ttsc/graph: could not resolve the ttscgraph binary. " +
+        "Install `ttsc` so its platform package is present, " +
+        "or set TTSC_GRAPH_BINARY to an absolute path.\n",
+    };
+  }
+}
+
+interface IViewOptions extends IProjectOptions {
+  port: number;
+  open: boolean;
+  maxNodes: number;
+}
+
+const DUMP_OPTIONS = [
+  { key: "artifacts", flags: ["--artifacts", "-artifacts"], kind: "string" },
+  { key: "cwd", flags: ["--cwd", "-cwd"], kind: "value" },
+  { key: "tsconfig", flags: ["--tsconfig", "-tsconfig"], kind: "value" },
+  { key: "pretty", flags: ["--pretty", "-pretty"], kind: "boolean" },
+  { key: "help", flags: ["--help", "-help", "-h"], kind: "flag" },
+] as const;
+
+/** The native help aliases mirrored only for missing-installation fallback. */
+const DUMP_HELP_FLAGS = new Set(["--help", "-help", "-h"]);
+
+/** Short fallback summary pointing to the native command's authoritative help. */
+const DUMP_HELP_SUMMARY = [
+  "Usage: ttsc-graph dump [options]",
+  "",
+  "Write the whole compiler graph as JSON to stdout: every node and edge,",
+  "none of the MCP response caps.",
+  "",
+  "Options:",
+  "  --cwd <dir>        Project root (default: current directory).",
+  "  --tsconfig <path>  Project tsconfig path (default: tsconfig.json).",
+  "  --pretty           Indent the JSON output.",
+  "",
+  "The native `ttscgraph` binary owns these flags and is not installed here,",
+  "so this summary may lag it. Install `ttsc` and rerun for the exact list.",
+  "",
+].join("\n");

package/src/TtscGraphViewSnapshot.ts

@@ -0,0 +1,46 @@
+import { parseDump } from "./model/loadGraph";
+
+/**
+ * Qualify a viewer dump before reduction or HTTP lifetime can begin.
+ *
+ * @evidence contracts/common.md#principled-implementation The actual shared dump decoder validates syntax, schema agreement and complete shape before a viewer receives facts; failures preserve the existing owned diagnostic and code one.
+ * @evidence contracts/common.md#clear-and-simple-design This namespace owns viewer validation/completion while parseDump owns schema authority and runView owns native capture, reduction and HTTP resources.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual generated validation is retained without a handwritten substitute, test-only producer or successful empty fallback.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the before-reduction/HTTP boundary; decode documents success transfer and diagnostic/code meaning.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms decode owns validation work; the namespace groups its result contract.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work No result cache is owned by the namespace; runView owns the one-shot snapshot lifetime.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The grouping acquires no process/socket; decode transfers valid facts to runView.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation validates dump JSON text that the caller already captured; no file, path or process.
+ */
+export namespace TtscGraphViewSnapshot {
+  /**
+   * Return validated facts, or the existing viewer diagnostic and failure code.
+   *
+   * @evidence contracts/common.md#principled-implementation parseDump is the sole generated schema authority; its owned messages pass through once, and an unowned exception receives the existing validation prefix.
+   * @evidence contracts/common.md#clear-and-simple-design A discriminated result keeps failure before actual reduction/server creation; runView writes only the returned diagnostic and returns its code.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed validation never supplies raw facts; no partial cast or alternate executable bypasses the real decoder.
+   * @evidence contracts/common.md#meaningful-documentation The headline explains valid-fact transfer versus failure diagnostic/code, without claiming this pure result is a process exit by itself.
+   * @evidence contracts/performance.md#efficient-algorithms Shared JSON/schema validation is linear in submitted bytes and facts, followed by constant-count diagnostic prefix handling; no historical/project scan is introduced.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each supplied dump requires actual validation; runView reuses the subsequently reduced immutable HTTP payload.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only local parsed facts or diagnostic text are created; ownership transfers to the caller and no process, reader, socket or prior dump is retained.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation parses and validates dump JSON text that the caller already captured; no file, path or process.
+   */
+  export function decode(
+    text: string,
+  ):
+    | { ok: true; raw: ReturnType<typeof parseDump> }
+    | { ok: false; code: 1; diagnostic: string } {
+    try {
+      return { ok: true, raw: parseDump(text) };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        ok: false,
+        code: 1,
+        diagnostic: message.startsWith("@ttsc/graph:")
+          ? `${message}\n`
+          : `@ttsc/graph: could not validate the graph dump: ${message}\n`,
+      };
+    }
+  }
+}

package/src/index.ts

@@ -1,17 +1,4 @@
-import { spawnSync } from "node:child_process";
-
-import {
-  PROJECT_OPTIONS,
-  parseLauncherOptions,
-  projectOptions,
-} from "./launcherArgs";
-import { publishArtifacts } from "./model/publishedArtifacts";
-import { ensureExecutable } from "./nativeExecutable";
-import { resolveGraphBinary } from "./resolveGraphBinary";
-import { startServer } from "./server/startServer";
-import { runView } from "./view";
-
-/** What a graph result says about where its facts came from. */
+/** Public graph launchers, resident sessions, audit vocabulary and viewer DTOs. */
 export {
   RESULT_AUDIT,
   RESULT_AUDIT_DETAILS,
@@ -19,152 +6,14 @@ export {
   RESULT_AUDIT_ESCAPE,
   RESULT_AUDIT_SELECTION,
 } from "./server/resultAudit";
-
-// Programmatic entry points. Each resolves its native binary from the project
-// `cwd` it is given (see `resolveGraphBinary`), so a caller that graphs a
-// project other than its own process directory names it once and the binary is
-// found under that project's installed `ttsc`.
 export { resolveGraphBinary } from "./resolveGraphBinary";
-/**
- * The viewer reduction the `view` command runs before serving a payload.
- *
- * Exported because it is one of three copies of the same pure transform — the
- * website's uploaded-dump viewer and the benchmark viewer hold the others — and
- * a shared policy that cannot be measured from outside the package drifts. It
- * already did: two of them filtered git-ignored generated code and this one did
- * not.
- */
 export { reduce } from "./reduce";
-export type { RawDump, RawEdge, RawNode, ViewerPayload } from "./reduce";
+export type { RawDump } from "./structures/RawDump";
+export type { RawEdge } from "./structures/RawEdge";
+export type { RawNode } from "./structures/RawNode";
+export type { ViewerPayload } from "./structures/ViewerPayload";
 export { DUMP_SCHEMA_VERSION, loadGraph } from "./model/loadGraph";
-export {
-  TtscGraphSession,
-  type TtscGraphRequestOptions,
-  type TtscGraphSessionOptions,
-} from "./model/TtscGraphSession";
-
-// The server version reported in the MCP handshake; read from this package.
-const VERSION: string = (require("../package.json") as { version: string })
-  .version;
-
-const DUMP_OPTIONS = [
-  { key: "cwd", flags: ["--cwd", "-cwd"], kind: "value" },
-  { key: "tsconfig", flags: ["--tsconfig", "-tsconfig"], kind: "value" },
-  { key: "pretty", flags: ["--pretty", "-pretty"], kind: "boolean" },
-  { key: "help", flags: ["--help", "-help", "-h"], kind: "flag" },
-] as const;
-
-/**
- * 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.
- */
-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 } = projectOptions(
-    parseLauncherOptions(argv, PROJECT_OPTIONS),
-  );
-  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);
-    },
-  );
-}
-
-/** The help spellings `ttscgraph` itself accepts, mirrored for the fallback. */
-const DUMP_HELP_FLAGS = new Set(["--help", "-help", "-h"]);
-
-/**
- * Print a `dump` usage summary when the native binary cannot be resolved.
- *
- * This is a fallback, not a second contract: `cmd/ttscgraph/main.go` owns these
- * flags and answers whenever it is installed. Keep this short and point at that
- * authority, so a drift degrades to a stale summary rather than a wrong
- * answer.
- */
-function printDumpHelp(): void {
-  process.stdout.write(
-    [
-      "Usage: ttsc-graph dump [options]",
-      "",
-      "Write the whole compiler graph as JSON to stdout: every node and edge,",
-      "none of the MCP response caps.",
-      "",
-      "Options:",
-      "  --cwd <dir>        Project root (default: current directory).",
-      "  --tsconfig <path>  Project tsconfig path (default: tsconfig.json).",
-      "  --pretty           Indent the JSON output.",
-      "",
-      "The native `ttscgraph` binary owns these flags and is not installed here,",
-      "so this summary may lag it. Install `ttsc` and rerun for the exact list.",
-      "",
-    ].join("\n"),
-  );
-}
-
-/**
- * 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 } = projectOptions(
-    parseLauncherOptions(argv, DUMP_OPTIONS),
-  );
-  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.
-    if (argv.some((argument) => DUMP_HELP_FLAGS.has(argument))) {
-      printDumpHelp();
-      return 0;
-    }
-    process.stderr.write(
-      "@ttsc/graph: could not resolve the ttscgraph binary. " +
-        "Install `ttsc` so its platform package is present, " +
-        "or set TTSC_GRAPH_BINARY to an absolute path.\n",
-    );
-    return 1;
-  }
-  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 = argv.includes("--artifacts")
-    ? null
-    : publishArtifacts({ cwd, tsconfig });
-  const result = spawnSync(
-    binary,
-    [
-      "dump",
-      ...argv,
-      ...(published?.file == null ? [] : ["--artifacts", published.file]),
-    ],
-    {
-      stdio: "inherit",
-      windowsHide: true,
-    },
-  );
-  if (result.error) {
-    process.stderr.write(`@ttsc/graph: ${result.error.message}\n`);
-    return 1;
-  }
-  return result.status ?? 1;
-}
+export { TtscGraphSession } from "./model/TtscGraphSession";
+export type { TtscGraphRequestOptions } from "./model/TtscGraphRequestOptions";
+export type { TtscGraphSessionOptions } from "./model/TtscGraphSessionOptions";
+export { runGraph } from "./runGraph";