@ttsc/graph 0.19.1 → 0.19.3

package/lib/structures/ITtscGraphDetails.d.ts

@@ -42,22 +42,24 @@ export declare namespace ITtscGraphDetails {
          */
         neighbors?: boolean;
         /**
-         * Maximum dependencies and dependents per side when `neighbors:true`. Above
-         * a few is usually overfetch; call `trace` for flow instead.
+         * Dependencies and dependents per side when `neighbors:true`. A small
+         * orientation slice by default; what uses a symbol grows with its
+         * popularity, so `trace` answers the whole "who uses this".
          *
          * @default 2
          */
         neighborLimit?: number;
         /**
-         * Maximum owned members for a container or object literal.
-         *
-         * @default 6
+         * Owned members for a container or object literal. The complete outline by
+         * default — a class's members and an enum's are the symbol itself, so they
+         * are not sampled. Pass a number to cap.
          */
         memberLimit?: number;
         /**
-         * Maximum direct execution and type references per group.
+         * Direct execution and type references per group. A small orientation slice
+         * by default; `trace` follows the whole fan-out.
          *
-         * @default 1
+         * @default 2
          */
         dependencyLimit?: number;
         /**
@@ -115,7 +117,15 @@ export declare namespace ITtscGraphDetails {
         types?: IReference[];
         /** Concrete nodes that implement or override this interface/base member. */
         implementedBy?: IReference[];
-        /** String literal values from the signature. */
+        /**
+         * The complete value set a type alias or enum admits, in TypeScript source
+         * form (`"a"`, `1`, `true`, `null`) — the checker's resolved union members,
+         * not the quoted tokens that happened to fit in `signature`.
+         *
+         * Absent when the type has no enumerable value set. A `signature` is capped
+         * at the declaration head, so for a union or enum written across several
+         * lines this is the field that carries the members.
+         */
         literals?: string[];
         /**
          * Owned symbol or top-level property outline a consumer reaches for on a

package/lib/structures/ITtscGraphDump.d.ts

@@ -6,25 +6,188 @@ import { ITtscGraphSpan } from "./ITtscGraphSpan";
  * wire contract between the Go fact-builder and the TypeScript graph engine.
  *
  * It is the complete graph with none of the per-response caps the MCP tools
- * apply: every node and edge the build resolved. The server parses each changed
- * native snapshot (typia-validated) into an in-memory resident graph and reuses
- * that warm model while project inputs stay unchanged; the bundled 3D viewer
- * reduces the same dump.
+ * apply: every node and edge the build resolved, plus the `provenance` that
+ * says which program resolved them. The server parses each changed native
+ * snapshot (typia-validated) into an in-memory resident graph and reuses that
+ * warm model while project inputs stay unchanged; the bundled 3D viewer reduces
+ * the same dump.
  *
- * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes and
- * edges are project-relative.
+ * `project` is absolute. Every other path is relative to it — `tsconfig`, and
+ * the `file` fields on nodes, edges, diagnostics, and the provenance manifest.
+ *
+ * Two kinds of path fall outside the project and so cannot be relative to it: a
+ * dependency keeps its `node_modules/`-relative tail, which is what makes a
+ * dependency leaf readable, and anything else the compiler loaded keeps the
+ * identity the compiler gave it — a virtual lib stays `bundled:///…`.
  */
 export interface ITtscGraphDump {
     /** Absolute path of the project root the graph was built for. */
     project: string;
     /** The tsconfig the program was loaded from, relative to `project`. */
     tsconfig: string;
+    /** Evidence about the one program that produced everything below. */
+    provenance: ITtscGraphDump.IProvenance;
+    /**
+     * The compiler's findings for the same generation that produced the facts.
+     *
+     * Empty means the program reported none. It does not mean they were not
+     * collected — `provenance.capabilities` is what says whether they were.
+     */
+    diagnostics: ITtscGraphDump.IDiagnostic[];
     /** Every node the build recorded. */
     nodes: ITtscGraphDump.INode[];
     /** Every edge the build resolved. */
     edges: ITtscGraphDump.IEdge[];
 }
 export declare namespace ITtscGraphDump {
+    /**
+     * What a snapshot knows about its own origin.
+     *
+     * The graph's claim is that its nodes, edges, spans, and diagnostics all came
+     * from one `Program`. Without this the claim is unprovable from the response:
+     * a consumer could only re-read the disk afterwards and hope nothing moved,
+     * which is not sound — a write that lands and reverts in between is invisible
+     * to it, and a re-read proves what the disk says now, never what the checker
+     * resolved against.
+     *
+     * This carries no source text. A digest is the opposite of inlining: it is
+     * what lets a consumer prove byte-identity against text it read itself,
+     * without the graph ever shipping that text.
+     */
+    interface IProvenance {
+        /**
+         * The dump body's schema version, moved when a field is added, removed, or
+         * redefined. Independent of the serve protocol's version: a dump written to
+         * a file has a schema but never rode the protocol.
+         */
+        schemaVersion: number;
+        /**
+         * What this snapshot proves. A consumer degrades against this rather than
+         * guessing from a field's emptiness, because an empty list and an
+         * uncollected one look identical on the wire.
+         *
+         * The known members are `universe`, `sourceDigests`, `diskDigests`, and
+         * `diagnostics`. The type stays `string[]` rather than a union of those on
+         * purpose: a union would make `typia.assert` reject a newer producer for
+         * naming a capability this client has not heard of, turning "proves more
+         * than you know about" into a hard failure. An unknown capability is
+         * exactly the case a consumer should ignore.
+         */
+        capabilities: string[];
+        /** What built the snapshot. */
+        producer: IProducer;
+        /** The inputs that decide which files are in the program at all. */
+        universe: IUniverse;
+        /** One entry per file the program loaded, ordered by file. */
+        sources: ISourceDigest[];
+    }
+    /**
+     * Identifies the binary and the checker behind the facts.
+     *
+     * `tool` and `version` are separate because more than one binary can produce
+     * a dump and they do not share a version line — the shipped `ttscgraph` is
+     * stamped at release, the internal viewer tool is not versioned at all — so
+     * folding the name in would hand a consumer that parses a version a tool
+     * name.
+     */
+    interface IProducer {
+        /** The producing binary's name, such as `ttscgraph`. */
+        tool: string;
+        /**
+         * The producing binary's build version, as its `--version` prints it. A
+         * local build reports the dev placeholder; a tool that carries no version
+         * reports `""`.
+         */
+        version: string;
+        /** The TypeScript version typescript-go implements. */
+        typescript: string;
+    }
+    /**
+     * The build universe: the inputs that decide which files the program
+     * contains, as opposed to what is inside them. A change to any of them can
+     * add or drop whole files, so a consumer reusing facts across snapshots must
+     * treat a universe change as invalidating everything.
+     */
+    interface IUniverse {
+        /**
+         * The tsconfig chain — the project's config and everything it extends.
+         *
+         * It stays an input regardless of what any source contains: compiler
+         * options change the meaning of code the checker resolves without any
+         * source file changing.
+         */
+        configs: IFileDigest[];
+        /**
+         * The resolved root file set, one entry per (config, file) pair. A root a
+         * config names but that does not exist is still listed: its absence is part
+         * of the fingerprint, and creating it later changes the program.
+         */
+        roots: IRootFile[];
+    }
+    /** A root file attributed to the config that named it. */
+    interface IRootFile {
+        /** The tsconfig that named this root, project-relative. */
+        config: string;
+        /** The root file, project-relative. */
+        file: string;
+    }
+    /** A file and the hex-encoded SHA-256 of its on-disk bytes. */
+    interface IFileDigest {
+        /** Project-relative. */
+        file: string;
+        /** Hex-encoded SHA-256. */
+        digest: string;
+    }
+    /**
+     * The manifest entry for one source file the program loaded.
+     *
+     * Two digests, because "the bytes the checker read" and "the bytes on disk"
+     * are not always the same string and a consumer needs to know which one it
+     * compares against. They diverge when a source-preamble plugin injects text
+     * ahead of the file before tsgo parses it, which a real plugin project does
+     * on every build.
+     */
+    interface ISourceDigest {
+        /** Project-relative. */
+        file: string;
+        /**
+         * Hex-encoded SHA-256 of the text the checker resolved against — the ground
+         * truth for the facts. Every node, edge, and span attributed to this file
+         * was computed from these bytes.
+         */
+        checkerDigest: string;
+        /**
+         * Hex-encoded SHA-256 of the file's on-disk bytes at snapshot time, or `""`
+         * when it could not be read: it vanished mid-load, or it is a virtual
+         * source with no on-disk identity.
+         *
+         * This is the one a consumer that opens the file itself can reproduce. When
+         * it equals `checkerDigest`, a matching read proves byte-identity with the
+         * facts. When it does not, the checker saw augmented text and that proof is
+         * simply not available for this file — which is a thing to report, not to
+         * paper over.
+         *
+         * Read it only when `provenance.capabilities` lists `diskDigests`. Without
+         * that claim every one of these is empty because the producer never hashed
+         * the disk, which is a different fact from a file that could not be read.
+         */
+        diskDigest: string;
+    }
+    /** One compiler diagnostic from the generation that produced the facts. */
+    interface IDiagnostic {
+        /** Project-relative. */
+        file: string;
+        /** 1-based line. */
+        line: number;
+        /** 1-based column. */
+        column: number;
+        /** The TypeScript diagnostic code, such as 2322. */
+        code: number;
+        /** Whether the finding fails a build. */
+        category: "error" | "warning";
+        /** The diagnostic text, without the code prefix. */
+        message: string;
+    }
     /**
      * A node as the builder sends it: the graph node, minus the file paths inside
      * its spans, which the loader puts back from the node's own `file`.

package/lib/structures/ITtscGraphNode.d.ts

@@ -52,6 +52,30 @@ export interface ITtscGraphNode {
     closure?: boolean;
     /** Declaration modifiers, when the declaration pass recorded any. */
     modifiers?: TtscGraphNodeModifier[];
+    /**
+     * The complete value set of a type alias or enum whose declared type the
+     * checker resolved to literals, each in TypeScript source form (`"a"`, `1`,
+     * `true`, `null`).
+     *
+     * Present only when every constituent is enumerable, so the list is the whole
+     * type and never a sample of it: `type T = Kind | string` admits values no
+     * list can name and carries none. It is resolved from the type, not read off
+     * the declaration, so indirection (`type I = Kind | 'f'`) is followed and the
+     * answer does not depend on how the declaration is wrapped.
+     */
+    literals?: string[];
+    /**
+     * What an enum declares, in checker order: the name a caller writes and the
+     * value it carries. Absent on every other kind.
+     *
+     * `literals` says which values the enum admits, which is what a serializer
+     * asks. The code says `Colors.Red`, so the names are the other half, and
+     * without them a caller that had already named the enum still had to open the
+     * file to learn what to type. The members are not nodes — `Colors.Red` is a
+     * string a grep finds exactly — so this fills in the node the graph already
+     * holds instead of minting one per member.
+     */
+    enumMembers?: ITtscGraphNode.IEnumMember[];
     /**
      * Decorators written on this declaration, in source order: raw facts
      * (`@Controller`, `@Get`) a consumer interprets without re-parsing source.
@@ -65,3 +89,16 @@ export interface ITtscGraphNode {
      */
     implementation?: ITtscGraphEvidence;
 }
+export declare namespace ITtscGraphNode {
+    /** One member of an enum: the name a caller writes and the value it carries. */
+    interface IEnumMember {
+        /** The member's own name, unqualified (`Red` on `Colors.Red`). */
+        name: string;
+        /**
+         * The value it carries, in TypeScript source form (`"red"`, `1`). Absent
+         * for a computed member the checker could not fold to a constant; the name
+         * still stands.
+         */
+        value?: string;
+    }
+}

package/lib/structures/ITtscGraphSnapshot.d.ts

@@ -0,0 +1,55 @@
+import { ITtscGraphDump } from "./ITtscGraphDump";
+/**
+ * One response frame of the `ttscgraph serve` protocol.
+ *
+ * This is the envelope around a snapshot, mirrored by hand from `serveResponse`
+ * in `packages/ttsc/cmd/ttscgraph/serve.go`. There is no generator between the
+ * Go struct and this interface, so the two drift silently unless something
+ * checks them; `TtscGraphSession` validates every frame against this shape
+ * rather than casting it, so a drift surfaces as a precise error on the first
+ * frame instead of an `undefined` several layers downstream.
+ */
+export interface ITtscGraphSnapshot {
+    /** Echoes the request's id, so a response finds its caller. */
+    id: number;
+    /**
+     * The protocol version the server speaks.
+     *
+     * It rides every frame rather than a handshake. The binary and this package
+     * version independently — the session runs whichever `ttscgraph` the target
+     * project installed, or whatever `TTSC_GRAPH_BINARY` points at — so a
+     * mismatched pair is reachable, and before this field nothing detected it:
+     * the first symptom was a misparsed dump or a silently absent value.
+     */
+    protocolVersion: number;
+    /**
+     * What the producer did to answer this request.
+     *
+     * Required, and never absent — including on the error path, where it is
+     * `"error"`. A consumer can report `rebuild` versus `incremental` honestly
+     * because the compiler said so; no generation counter can distinguish a reuse
+     * from a full rebuild after the fact.
+     */
+    mode: ITtscGraphSnapshot.Mode;
+    /** What this server can prove about the snapshots it publishes. */
+    capabilities: string[];
+    /** Whether the graph moved since the last snapshot. */
+    changed: boolean;
+    /** The snapshot, present exactly when `changed` is true. */
+    dump?: ITtscGraphDump;
+    /** Set when the request produced no snapshot; `mode` is then `"error"`. */
+    error?: string;
+}
+export declare namespace ITtscGraphSnapshot {
+    /**
+     * The computation modes the producer reports, plus the transport's `error`.
+     *
+     * - `initial`: the session's first snapshot.
+     * - `reload`: the build universe moved, so the program was reloaded whole.
+     * - `unchanged`: nothing moved; no dump rides it and the last one still holds.
+     * - `incremental`: edits applied onto the reused resident program.
+     * - `rebuild`: edits applied, but the program could not be reused.
+     * - `error`: no snapshot was produced.
+     */
+    type Mode = "initial" | "reload" | "unchanged" | "incremental" | "rebuild" | "error";
+}

package/lib/structures/ITtscGraphSnapshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ITtscGraphSnapshot.js.map

package/lib/structures/ITtscGraphSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscGraphSnapshot.js","sourceRoot":"","sources":["../../src/structures/ITtscGraphSnapshot.ts"],"names":[],"mappings":""}

package/lib/structures/ITtscGraphTour.d.ts

@@ -56,7 +56,7 @@ export declare namespace ITtscGraphTour {
          * Central entrypoints to seed the tour. Raise only when the question names
          * several public paths that must all appear in one answer.
          *
-         * @default 4
+         * @default 5
          */
         limit?: number;
         /**

package/lib/structures/index.d.ts

@@ -11,6 +11,7 @@ export * from "./ITtscGraphOverview";
 export * from "./ITtscGraphLookup";
 export * from "./ITtscGraphNext";
 export * from "./ITtscGraphTrace";
+export * from "./ITtscGraphSnapshot";
 export * from "./ITtscGraphSpan";
 export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";

package/lib/structures/index.js

@@ -32,6 +32,7 @@ __exportStar(require("./ITtscGraphOverview"), exports);
 __exportStar(require("./ITtscGraphLookup"), exports);
 __exportStar(require("./ITtscGraphNext"), exports);
 __exportStar(require("./ITtscGraphTrace"), exports);
+__exportStar(require("./ITtscGraphSnapshot"), exports);
 __exportStar(require("./ITtscGraphSpan"), exports);
 __exportStar(require("./ITtscGraphTour"), exports);
 __exportStar(require("./TtscGraphEdgeKind"), exports);

package/lib/structures/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,gFAAgF;AAChF,6BAA6B;;;;;;;;;;;;;;;;AAE7B,0DAAwC;AACxC,wDAAsC;AACtC,mDAAiC;AACjC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,sDAAoC;AACpC,0DAAwC;AACxC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,mDAAiC;AACjC,oDAAkC;AAClC,mDAAiC;AACjC,mDAAiC;AACjC,sDAAoC;AACpC,sDAAoC;AACpC,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,gFAAgF;AAChF,6BAA6B;;;;;;;;;;;;;;;;AAE7B,0DAAwC;AACxC,wDAAsC;AACtC,mDAAiC;AACjC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,sDAAoC;AACpC,0DAAwC;AACxC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,mDAAiC;AACjC,oDAAkC;AAClC,uDAAqC;AACrC,mDAAiC;AACjC,mDAAiC;AACjC,sDAAoC;AACpC,sDAAoC;AACpC,0DAAwC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "Checker-resolved architecture graph over MCP for coding agents, backed by ttsc's in-process TypeScript-Go compiler.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -19,6 +19,9 @@
     "@typia/mcp": "13.1.0",
     "typia": "13.1.0"
   },
+  "peerDependencies": {
+    "ttsc": "0.19.3"
+  },
   "keywords": [
     "ttsc",
     "mcp",
@@ -39,7 +42,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "^7.0.2",
-    "ttsc": "0.19.1"
+    "ttsc": "0.19.3"
   },
   "repository": {
     "type": "git",

package/src/TtscGraphApplication.ts

@@ -1,6 +1,7 @@
 import { TtscGraphMemory } from "./model/TtscGraphMemory";
 import {
   RESULT_AUDIT,
+  RESULT_AUDIT_DETAILS,
   RESULT_AUDIT_ESCAPE,
   RESULT_AUDIT_SELECTION,
 } from "./server/resultAudit";
@@ -90,9 +91,11 @@ export class TtscGraphApplication implements ITtscGraphApplication {
         };
       }
       case "details": {
+        // details' identity is complete and its fan-out is a slice, which is
+        // not the walk-bounded-and-marked shape RESULT_AUDIT states.
         const r = runDetails(graph, props.request);
         return {
-          audit: RESULT_AUDIT,
+          audit: RESULT_AUDIT_DETAILS,
           next: r.next,
           result: r.result,
         };

package/src/index.ts

@@ -9,6 +9,7 @@ import { runView } from "./view";
 /** What a graph result says about where its facts came from. */
 export {
   RESULT_AUDIT,
+  RESULT_AUDIT_DETAILS,
   RESULT_AUDIT_ESCAPE,
   RESULT_AUDIT_SELECTION,
 } from "./server/resultAudit";

package/src/model/TtscGraphSession.ts

@@ -4,19 +4,22 @@ import typia from "typia";
 
 import { ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
-import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
+import { DUMP_SCHEMA_VERSION } from "./loadGraph";
 import { TtscGraphMemory } from "./TtscGraphMemory";
 
-interface SessionResponse {
-  id: number;
-  changed: boolean;
-  mode?: "initial" | "unchanged" | "incremental" | "rebuild" | "reload";
-  dump?: unknown;
-  error?: string;
-}
+/**
+ * The serve protocol version this client speaks.
+ *
+ * Keep it equal to `serveProtocolVersion` in
+ * `packages/ttsc/cmd/ttscgraph/serve.go`. The two are hand-synchronized, and
+ * `serve_protocol_version_matches_the_typescript_client_test.go` reads this
+ * constant out of this file and fails if the pair drifts.
+ */
+const PROTOCOL_VERSION = 1;
 
 interface Pending {
-  resolve: (response: SessionResponse) => void;
+  resolve: (response: ITtscGraphSnapshot) => void;
   reject: (error: Error) => void;
 }
 
@@ -93,6 +96,8 @@ export class TtscGraphSession {
   }
 
   private async refresh(): 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();
     if (response.error !== undefined) {
       throw new Error(`@ttsc/graph: ${response.error}`);
@@ -100,11 +105,10 @@ export class TtscGraphSession {
     if (response.changed) {
       if (response.dump === undefined) {
         throw new Error(
-          `@ttsc/graph: native ${response.mode ?? "changed"} response omitted its dump`,
+          `@ttsc/graph: native ${response.mode} response omitted its dump`,
         );
       }
-      const dump = typia.assert<ITtscGraphDump>(response.dump);
-      this.current = TtscGraphMemory.from(dump);
+      this.current = TtscGraphMemory.from(response.dump);
     }
     if (this.current === undefined) {
       throw new Error(
@@ -114,10 +118,10 @@ export class TtscGraphSession {
     return this.current;
   }
 
-  private request(): Promise<SessionResponse> {
+  private request(): Promise<ITtscGraphSnapshot> {
     const child = this.ensureChild();
     const id = ++this.nextId;
-    return new Promise<SessionResponse>((resolve, reject) => {
+    return new Promise<ITtscGraphSnapshot>((resolve, reject) => {
       this.pending.set(id, { resolve, reject });
       child.stdin.write(`${JSON.stringify({ id })}\n`, (error) => {
         if (error === null || error === undefined) return;
@@ -169,9 +173,9 @@ export class TtscGraphSession {
   }
 
   private onLine(line: string): void {
-    let response: SessionResponse;
+    let parsed: unknown;
     try {
-      response = JSON.parse(line) as SessionResponse;
+      parsed = JSON.parse(line);
     } catch (error) {
       this.failPending(
         new Error(
@@ -180,6 +184,75 @@ export class TtscGraphSession {
       );
       return;
     }
+
+    // Read the version before the shape, because a server speaking another
+    // version is entitled to a different shape. Asserting first would report
+    // that mismatch as a field complaint — "expected string at $input.mode" —
+    // about a contract the other side never agreed to, which is the misparse
+    // this field exists to prevent. Ask what protocol it is first, then hold it
+    // to that protocol.
+    const version: number | undefined = typia.is<{ protocolVersion: number }>(
+      parsed,
+    )
+      ? parsed.protocolVersion
+      : undefined;
+    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(
+        new Error(
+          `@ttsc/graph: ttscgraph speaks serve protocol ${
+            version === undefined ? "an unknown version" : `v${String(version)}`
+          }, this client speaks v${String(PROTOCOL_VERSION)}. ` +
+            "Install a matching `ttsc` (the binary resolves from the target " +
+            "project, or from TTSC_GRAPH_BINARY).",
+        ),
+      );
+      return;
+    }
+
+    let response: ITtscGraphSnapshot;
+    try {
+      // Validate the envelope, not just the dump it carries. The dump was
+      // typia-asserted while the envelope around it was a bare cast, so the
+      // fields the client actually branches on — the mode, and the id that
+      // routes the frame — were the unchecked ones. Anything added to the
+      // envelope belongs on this side of that line.
+      response = typia.assert<ITtscGraphSnapshot>(parsed);
+    } catch (error) {
+      this.failPending(
+        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.failPending(
+        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);

package/src/model/loadGraph.ts

@@ -11,6 +11,21 @@ import { TtscGraphMemory } from "./TtscGraphMemory";
 // buffer is raised to a ceiling no real graph reaches.
 const MAX_DUMP_BYTES = 1024 * 1024 * 1024;
 
+/**
+ * The dump schema version this client reads.
+ *
+ * Keep it equal to `DumpSchemaVersion` in
+ * `packages/ttsc/internal/graph/provenance.go`. The two are hand-synchronized,
+ * and `dump_schema_version_matches_the_typescript_client_test.go` reads this
+ * constant out of this file and fails if the pair drifts.
+ *
+ * Exported because the resident session reads the same dump body over the serve
+ * protocol and has to hold it to the same number: the envelope's version and the
+ * body's are independent, so a producer can speak this protocol and still send a
+ * body from another schema.
+ */
+export const DUMP_SCHEMA_VERSION = 3;
+
 /**
  * Build the resident {@link TtscGraphMemory} for a project by running `ttscgraph
  * dump` once and loading its JSON. This is the one-shot path for direct callers
@@ -73,6 +88,13 @@ export function loadGraph(
  * {@link ITtscGraphDump} shape so a malformed or stale dump fails loudly here
  * rather than producing wrong answers downstream, and the schema version is
  * checked so an incompatible producer is refused.
+ *
+ * The version is read before the shape: a dump from another schema is entitled
+ * to another shape, so asserting first would report the mismatch as a field
+ * complaint about a contract that producer never agreed to. A dump also
+ * outlives the process that wrote it — this is the one-shot path, and the JSON
+ * on disk may be from any build — so the version is the first question to ask
+ * of it.
  */
 function parseDump(json: string): ITtscGraphDump {
   let value: unknown;
@@ -85,5 +107,19 @@ function parseDump(json: string): ITtscGraphDump {
       }`,
     );
   }
+  const version: number | undefined = typia.is<{
+    provenance: { schemaVersion: number };
+  }>(value)
+    ? value.provenance.schemaVersion
+    : undefined;
+  if (version !== DUMP_SCHEMA_VERSION) {
+    throw new Error(
+      `@ttsc/graph: ttscgraph dump is schema ${
+        version === undefined ? "unknown" : `v${String(version)}`
+      }, 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 typia.assert<ITtscGraphDump>(value);
 }