@ttsc/graph 0.19.0 → 0.19.2

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/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/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.0",
+  "version": "0.19.2",
   "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",
@@ -39,7 +39,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "^7.0.2",
-    "ttsc": "0.19.0"
+    "ttsc": "0.19.2"
   },
   "repository": {
     "type": "git",

package/src/model/TtscGraphSession.ts

@@ -4,19 +4,21 @@ import typia from "typia";
 
 import { ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
-import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
 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 +95,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 +104,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 +117,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 +172,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 +183,49 @@ 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;
+    }
     const pending = this.pending.get(response.id);
     if (pending === undefined) return;
     this.pending.delete(response.id);

package/src/model/loadGraph.ts

@@ -11,6 +11,16 @@ 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.
+ */
+const DUMP_SCHEMA_VERSION = 1;
+
 /**
  * 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 +83,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 +102,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);
 }