@ttsc/graph 0.18.3 → 0.19.0

package/lib/server/startServer.js

@@ -2,20 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startServer = startServer;
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
-const loadGraph_1 = require("../model/loadGraph");
+const TtscGraphSession_1 = require("../model/TtscGraphSession");
 const createServer_1 = require("./createServer");
 /**
  * Serve the graph tools over MCP on stdio. The server answers the MCP handshake
- * immediately and builds the resident graph on the first tool call, so a large
- * project cannot make the client give up before tools are advertised.
+ * immediately and opens the resident incremental graph session on the first
+ * real tool call, so a large project cannot make the client give up before
+ * tools are advertised and an escape request still performs no graph work.
  */
 async function startServer(options) {
-    let graph;
-    const server = (0, createServer_1.createServer)(() => {
-        graph ??= (0, loadGraph_1.loadGraph)({ cwd: options.cwd, tsconfig: options.tsconfig });
-        return graph;
+    const cwd = options.cwd ?? process.cwd();
+    const tsconfig = options.tsconfig ?? "tsconfig.json";
+    let session;
+    const server = (0, createServer_1.createServer)(async () => {
+        session ??= new TtscGraphSession_1.TtscGraphSession({ cwd, tsconfig });
+        return session.graph();
     }, options.version);
     const transport = new stdio_js_1.StdioServerTransport();
+    const closeSession = () => session?.close();
+    transport.onclose = closeSession;
+    process.stdin.once("end", closeSession);
     await server.connect(transport);
 }
 //# sourceMappingURL=startServer.js.map

package/lib/server/startServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../src/server/startServer.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAGjF,kDAA+C;AAC/C,iDAA8C;AAE9C;;;;GAIG;AACI,KAAK,sBAAsB,OAKjC;IACC,IAAI,KAAkC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAA,2BAAY,EAAC,GAAG,EAAE;QAC/B,KAAK,KAAK,IAAA,qBAAS,EAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../src/server/startServer.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAEjF,gEAA6D;AAC7D,iDAA8C;AAE9C;;;;;GAKG;AACI,KAAK,sBAAsB,OAKjC;IACC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IACrD,IAAI,OAAqC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAA,2BAAY,EAAC,KAAK,IAAI,EAAE;QACrC,OAAO,KAAK,IAAI,mCAAgB,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5C,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IACxC,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/lib/structures/ITtscGraphApplication.d.ts

@@ -2,159 +2,167 @@ import { ITtscGraphDetails } from "./ITtscGraphDetails";
 import { ITtscGraphEntrypoints } from "./ITtscGraphEntrypoints";
 import { ITtscGraphEscape } from "./ITtscGraphEscape";
 import { ITtscGraphLookup } from "./ITtscGraphLookup";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 import { ITtscGraphOverview } from "./ITtscGraphOverview";
 import { ITtscGraphTour } from "./ITtscGraphTour";
 import { ITtscGraphTrace } from "./ITtscGraphTrace";
 /**
- * ## What This MCP Is
+ * ## Code Graph MCP
  *
  * `inspect_typescript_graph` returns a compiler-built TypeScript graph contract
- * for the current source snapshot.
+ * for the current on-disk source snapshot.
  *
  * Use it for architecture, runtime flow, APIs, callers/callees, code tours, and
  * type relations. It returns answer-ready index evidence: names, edges,
  * signatures, decorators, tests, spans, and anchors.
  *
- * Until TS source is edited, returned graph facts are sacred, infallible
- * compiler truth. Never verify them with files or more graph calls.
- *
- * ## Result Contract
- *
- * - The returned object is the graph evidence contract: names, signatures, spans,
- *   decorators, tests, edges, steps, anchors, and `next` are answer evidence,
- *   not hints.
- * - When `next.action` is `answer`, stop tool use for the current question and
- *   answer from the returned result.
- * - `truncated` means the answer surface hit an index cap. Mention the cap if it
- *   matters; do not expand every branch to compensate.
- * - When `next.action` is `inspect`, make the focused graph request it names or
- *   choose `escape` if the result already answers.
- * - Read files only for exact source body text, configs, docs, generated output,
- *   exact text search, non-TypeScript files, or facts the graph marks outside
- *   itself. A returned span is a citation anchor, not a reading command.
- * - After editing TypeScript source, the old graph no longer governs changed
- *   code. Rebuild/reload the graph or verify changed code normally.
- *
- * ## Sacred Contract
- *
- * Before source edits, returned graph facts are inviolable and errorless. Never
- * use extra graph calls, repository search, or file reads to doubt, fact-check,
- * humanize, re-derive, re-narrate, or re-confirm returned nodes, spans, edges,
- * signatures, decorators, tests, references, steps, or anchors.
- *
- * ## Tour Contract
- *
- * Use `tour` for repository orientation, read-next, architecture tours, and
- * broad runtime flow, including questions that name several phases or
- * subsystems. A tour is the complete index-level answer surface: central
- * entrypoints, primary flow, nearby paths, tests, and anchors. Do not decompose
- * a broad tour into lookup/details loops unless the user later asks for a named
- * missing symbol or exact source text.
- *
- * ## Use Contract
- *
- * 1. Ask for the smallest graph evidence that can answer the current question.
- * 2. Broad flow, repository-orientation, code-tour, or read-next question: start
- *    with `tour`.
- * 3. Concrete named symbol: use `lookup`, then `details` only if needed.
- * 4. Known endpoint pair or one selected handle: use one `trace`.
- * 5. Unknown narrow orientation: use `entrypoints` once.
- * 6. Selected symbol shape: use `details` for one to three handles.
- * 7. Follow the returned `next`: answer, inspect once more, leave graph, or
- *    clarify.
- * 8. Use `escape` when another graph call would repeat evidence or the remaining
- *    evidence is outside the TypeScript graph.
- *
- * Most TypeScript structure answers need one or two graph calls.
- *
- * ## Request Fields
- *
- * Fill the visible checklist, then exactly one request.
- *
- * - `question`: restate the code question being considered.
- * - `draft`: initial request type and why it seems smallest.
- * - `review`: correct a wrong, broad, stale, or duplicate draft. If graph facts
- *   already answer, if prior `next.action` was `answer`, or if the next
- *   evidence is outside the indexed TypeScript graph, say so here and make
- *   `request.type` be `escape`. If a broad flow draft is not `tour`, correct it
- *   here.
- * - `request`: final request after review.
- *
- * ## How to answer from graph evidence
- *
- * - Use returned node names, signatures, edges, references, evidence, and
- *   `sourceSpan` ranges directly.
- * - Explain the central path first, then mention important branches.
- * - For tests, impact, or reading lists, returned nodes and ranges are the answer
- *   evidence, not search keywords.
- * - A returned range is a sacred citation anchor, not permission to open the
- *   file.
+ * Every returned fact — each name, edge, signature, and span — is
+ * compiler-resolved and verified for the snapshot that call synchronized, so
+ * trust it without re-checking against files. Where an operation ranks a
+ * shortlist against your question (`lookup`, `entrypoints`, `tour`), the facts
+ * stay verified but the selection is heuristic: judge whether its coverage
+ * answers you, and a follow-up request or a read of a cited span is fair when
+ * it does not.
+ *
+ * ## Requests
+ *
+ * A request is a union: pick the single type below that best fits the question,
+ * and submit exactly that one.
+ *
+ * - `tour`: architecture, runtime flow, orientation, or a code tour. One call is
+ *   the whole answer; do not split it. Name the machinery you expect it to be
+ *   made of in its `reinterpretations`, or send none.
+ * - `entrypoints`: find where execution starts when entry points are unknown.
+ * - `lookup`: locate a named symbol.
+ * - `trace`: follow calls or data flow forward or backward from a symbol, or —
+ *   with `to` — the path between two symbols when both ends are known, which is
+ *   the one call that answers "how does A reach B".
+ * - `details`: signatures, members, and relations of named symbols — including
+ *   the classes that implement an interface, which is the one call that answers
+ *   "what actually implements this".
+ * - `overview`: project layers and folder structure.
+ * - `escape`: the answer is outside the graph (source body text, non-TypeScript
+ *   files, exact search).
+ *
+ * ## Chain of Thought
+ *
+ * Fill these fields in order before the call; each one narrows the reasoning
+ * toward the single request you submit.
+ *
+ * - `question`: the code question, in the user's own words.
+ * - `draft`: `{ reason, type }` — why the smallest request that could answer it,
+ *   then that request's `type`.
+ * - `review`: fix a broad, stale, or duplicate draft. If the graph already
+ *   answered, or the evidence is outside it, escape.
+ * - `request`: the final choice. Each branch documents its own fields; fill them
+ *   from what the branch says, not from what another branch wanted.
+ *
+ * ## What to trust
+ *
+ * Before source edits, every returned fact is compiler-resolved and verified.
+ * Never use extra graph calls, repository search, or file reads to doubt,
+ * fact-check, re-derive, re-narrate, or re-confirm a returned node, span, edge,
+ * signature, decorator, test, reference, step, or anchor. The server resolved
+ * each one to the type-checked program for the snapshot the call synced to, and
+ * `audit` says so on every result.
+ *
+ * Selection is the separate question. `lookup`, `entrypoints`, and `tour` match
+ * your question and return a scored, ranked, per-file-capped, limited
+ * shortlist; their facts are still verified, but whether the shortlist covers
+ * what you asked is yours to judge, and their `audit` says that instead of
+ * claiming completeness. A follow-up request or a read of a cited span for
+ * missed coverage is legitimate — re-confirming a fact the graph already
+ * resolved is not.
+ *
+ * ## Stop
+ *
+ * Let the result's `next` set the pace, and do not re-confirm what the graph
+ * resolved.
+ *
+ * - A span is a citation, not a cue to open the file to re-check a fact.
+ * - Follow the result's `next`: `answer` means stop and answer from it, `inspect`
+ *   means make exactly the one request it names, `outside` means escape,
+ *   `clarify` means restate the request.
+ * - For a ranked shortlist (`lookup`, `entrypoints`, `tour`), `next` and
+ *   `truncated` say whether coverage is settled; when it is not, one more
+ *   request is the right move — not a file read to re-verify facts already
+ *   given.
  */
 export interface ITtscGraphApplication {
     /**
-     * Inspect the TypeScript compiler graph contract.
+     * Answer a TypeScript question from the compiler's own index of this
+     * repository.
+     *
+     * The graph holds every symbol, call, type, decorator and test, each with its
+     * file and line, resolved from the source on disk now. Submit exactly one
+     * request:
      *
-     * Use this before repository search when an answer depends on TypeScript
-     * symbols, calls, types, decorators, references, ranges, or runtime/source
-     * relationships. For repository orientation, read-next, architecture, and
-     * broad runtime flow questions, use `tour`.
+     * - `tour`: architecture, the runtime flow from the public API to the code that
+     *   does the work, nearby paths, and the tests to read — a whole orientation
+     *   in one call
+     * - `trace`: what a symbol calls, what calls it, or the path from A to B
+     * - `details`: signatures, members, and what implements an interface
+     * - `lookup`: where a named symbol is declared
+     * - `entrypoints`: where execution starts, when the entry is unknown
+     * - `overview`: the project's layers and folder structure
      *
-     * Returned nodes, edges, signatures, spans, tests, anchors, and `next` are
-     * the answer surface. If `next.action` is `answer`, stop tool use and answer
-     * from that result. Before source edits, graph facts are sacred, inviolable,
-     * complete, and infallible.
+     * Every fact in a result is the checker's own resolution, audited before
+     * return, so no fact needs verifying; for the ranked operations (`lookup`,
+     * `entrypoints`, `tour`), judge whether the shortlist covers your question.
+     * Read a file for what the graph does not carry: a body, the text in a span.
      *
      * @param props Reasoning plus one graph request
      * @returns Matching `result` union member
      */
-    inspect_typescript_graph(props: ITtscGraphApplication.IProps): ITtscGraphApplication.IResult;
+    inspect_typescript_graph(props: ITtscGraphApplication.IProps): Promise<ITtscGraphApplication.IOutput>;
 }
 export declare namespace ITtscGraphApplication {
     /** Draft, review, then submit exactly one graph request or escape. */
     interface IProps {
         /**
-         * User's TypeScript code question.
+         * The code question, in the user's own words.
          *
-         * Restate the code question being considered. If the next evidence is a
-         * script, config, doc, generated output, exact text, non-TypeScript file,
-         * or source body text, choose `escape`.
+         * Cut a long message down to the sentences that state the ask, but keep
+         * their terms: the graph ranks against these words, so a rewrite ranks a
+         * different answer.
          */
         question: string;
-        /**
-         * Initial request plan before final arguments are filled.
-         *
-         * Name the intended request type in `type` and why it seems smallest in
-         * `reason`. Broad flow, architecture, repository-orientation, and read-next
-         * questions should normally draft `tour`; narrow named symbols can draft
-         * `lookup`, `trace`, or `details`.
-         */
+        /** The smallest request that could answer, and why. */
         draft: IDraft;
         /**
-         * Final self-review before calling.
-         *
-         * Correct a stale, broad, duplicate, or wrong draft here. If broad flow was
-         * split into search/detail steps, switch to `tour`. If graph facts already
-         * answer, or prior `next.action` was `answer`, make `request.type` be
-         * `escape`; do not call graph or read files to re-confirm returned facts.
+         * Correct the draft. Escape if the graph already answered, or the next
+         * evidence is outside the graph.
          */
         review: string;
-        /** Final graph operation chosen after review, or a no-op escape. */
+        /** Final graph request chosen after review, or a no-op escape. */
         request: ITtscGraphEntrypoints.IRequest | ITtscGraphLookup.IRequest | ITtscGraphTrace.IRequest | ITtscGraphDetails.IRequest | ITtscGraphOverview.IRequest | ITtscGraphTour.IRequest | ITtscGraphEscape.IRequest;
     }
-    /**
-     * First-pass request plan, filled before the final `request` arguments.
-     *
-     * `reason` comes before `type` so the justification is written before the
-     * choice it justifies.
-     */
+    /** First-pass plan; `reason` precedes `type` so it is written first. */
     interface IDraft {
-        /** Why this request type looks like the smallest useful next step. */
+        /** Why this is the smallest useful next step. */
         reason: string;
-        /** The request type being considered, corrected later in `review`. */
+        /** The request type being considered. */
         type: IProps["request"]["type"];
     }
     /** The selected request's output. `result.type` mirrors `request.type`. */
-    interface IResult {
+    interface IOutput {
+        /**
+         * What the server audited this result against before returning it, in its
+         * own words: every node, span, edge, signature, member, and step in it
+         * resolves to the type-checked program for the snapshot the call synced to,
+         * so opening a file it cites only returns a fact already in it.
+         *
+         * The audit is operation-aware. For the exact operations (`trace`,
+         * `details`, `overview`) it reports the result as the structure the graph
+         * holds for the handles named, bounded only where `truncated` says. For the
+         * ranked operations (`lookup`, `entrypoints`, `tour`) it adds that the
+         * selection is heuristic — matched, scored, ranked, and limited against the
+         * question — so the facts are verified but the shortlist's coverage is the
+         * caller's to judge.
+         */
+        audit: string;
+        /** What to do with `result`: answer, inspect one named request, or escape. */
+        next: ITtscGraphNext;
         /** Result branch matching the submitted `request.type`. */
         result: ITtscGraphEntrypoints | ITtscGraphLookup | ITtscGraphTrace | ITtscGraphDetails | ITtscGraphOverview | ITtscGraphTour | ITtscGraphEscape;
     }

package/lib/structures/ITtscGraphDecorator.d.ts

@@ -1,12 +1,9 @@
 /**
  * A decorator as written on a declaration, carried on the decorated
- * {@link ITtscGraphNode}'s `decorators`.
- *
- * The graph reports the decorator faithfully rather than interpreting any
- * framework's convention: the `name` is the decorator as written (`Controller`,
- * `Get`, `TypedRoute.Get`, ...), and statically resolvable literal arguments
- * are preserved so a consumer can apply its own meaning without re-parsing
- * source.
+ * {@link ITtscGraphNode}'s `decorators`. Reported faithfully, not interpreted
+ * per framework: `name` is the decorator as written (`Controller`, `Get`,
+ * `TypedRoute.Get`, ...), and statically resolvable literal arguments are
+ * preserved so a consumer applies its own meaning without re-parsing source.
  */
 export interface ITtscGraphDecorator {
     /**

package/lib/structures/ITtscGraphDetails.d.ts

@@ -1,24 +1,27 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 /**
- * The source-free facts for a few selected handles.
- *
- * This is not a file reader. It returns signatures, member outlines, direct
- * calls, direct types, implementation candidates, dependency summaries, and
- * sourceSpan citation anchors.
+ * Source-free facts for a few selected handles, not a file reader: signatures,
+ * member outlines, direct calls and types, implementation candidates,
+ * dependency summaries, and sourceSpan citation anchors.
  */
 export interface ITtscGraphDetails {
     /** Discriminator for selected symbol inspection. */
     type: "details";
     /** Selected node facts, in the same order as resolved handles when possible. */
     nodes: ITtscGraphDetails.INode[];
-    /** How to use this source-free result next. */
-    next: ITtscGraphNext;
-    /** Human-readable compatibility note mirroring `next`. */
-    guide: string;
-    /** Handles that resolved to no node, or that were ambiguous. */
+    /** Handles the graph holds no node for. */
     unknown: string[];
+    /**
+     * Handles that name more than one node, with the nodes they name.
+     *
+     * A name the graph knows twice is not a name the graph does not know: two
+     * classes called `Workbench` are two facts, and answering "unknown" to a
+     * handle the checker resolved twice sends the caller to the files for what is
+     * already here. Re-call `details` with the `id` of the one the question
+     * means.
+     */
+    ambiguous?: ITtscGraphDetails.IAmbiguity[];
 }
 export declare namespace ITtscGraphDetails {
     /** Which selected handles to inspect, and how much of each to return. */
@@ -26,56 +29,66 @@ export declare namespace ITtscGraphDetails {
         /** Discriminator for selected symbol inspection. */
         type: "details";
         /**
-         * Node ids from another tool, or dotted symbol handles such as
-         * `OrderService.create`. Pass the few handles you need for source-free
-         * details. Prefer one to three handles. Use `trace` when you need a path
-         * instead of widening this call.
+         * Node ids or dotted symbol handles (`OrderService.create`). Prefer one to
+         * three; use `trace` for a path instead of widening this call.
          */
         handles: string[];
         /**
-         * Also list each node's direct dependencies and dependents (the symbols it
-         * uses and the symbols that use it). The list is capped; raise
-         * `neighborLimit` when the first slice is truncated and the missing
-         * relation is named. This remains a relationship summary, not a file body.
+         * Also list each node's direct dependencies and dependents (symbols it uses
+         * and symbols that use it), capped. A relationship summary, not a file
+         * body.
          *
          * @default false
          */
         neighbors?: boolean;
         /**
-         * Maximum dependencies and dependents to return per side when
-         * `neighbors:true`.
-         *
-         * Prefer the default. Values above a few neighbors are usually overfetch;
-         * call `trace` for flow instead.
+         * Maximum dependencies and dependents per side when `neighbors:true`. Above
+         * a few is usually overfetch; call `trace` for flow instead.
          *
          * @default 2
          */
         neighborLimit?: number;
         /**
-         * Maximum owned members to return for a container or object literal. Raise
-         * only when the first outline is truncated and the missing member is
-         * named.
+         * Maximum owned members for a container or object literal.
          *
          * @default 6
          */
         memberLimit?: number;
         /**
-         * Maximum direct execution and type references to return per group. Raise
-         * only when the first dependency slice is truncated and the missing
-         * dependency is named.
+         * Maximum direct execution and type references per group.
          *
          * @default 1
          */
         dependencyLimit?: number;
         /**
          * Include dependency-boundary references from node_modules or bundled
-         * `.d.ts` libraries. Leave false for source-architecture answers; enable
-         * only when external type/API boundaries are the question.
+         * `.d.ts` libraries. Enable only when external type/API boundaries are the
+         * question.
          *
          * @default false
          */
         includeExternal?: boolean;
     }
+    /** One handle and the several nodes it names. */
+    interface IAmbiguity {
+        /** The handle as submitted. */
+        handle: string;
+        /** Every node the handle names, each with the id to re-call `details` on. */
+        candidates: ICandidate[];
+    }
+    /** One node a handle could mean: enough to choose, not to answer from. */
+    interface ICandidate {
+        /** Stable node id: submit this as the handle to select this one. */
+        id: string;
+        /** Qualified symbol name when available, otherwise the simple name. */
+        name: string;
+        /** Declaration kind (`class`, `method`, `function`, ...). */
+        kind: string;
+        /** Project-relative path of the file that declares this node. */
+        file: string;
+        /** 1-based declaration line, when known. */
+        line?: number;
+    }
     /** One inspected node: its declared shape and graph coordinates. */
     interface INode {
         /** Stable node id for subsequent `details` or `trace` calls. */
@@ -90,6 +103,8 @@ export declare namespace ITtscGraphDetails {
         line?: number;
         /** The declaration signature: its first line(s) up to the body. */
         signature?: string;
+        /** The first sentence of the doc comment above the declaration. */
+        doc?: string;
         /** Decorators written on this declaration, when any. */
         decorators?: ITtscGraphDecorator[];
         /** Assigned implementation span, when source comes from one. */
@@ -103,8 +118,8 @@ export declare namespace ITtscGraphDetails {
         /** String literal values from the signature. */
         literals?: string[];
         /**
-         * For a container or object-literal variable: the owned symbol or top-level
-         * property outline a consumer reaches for, without bodies.
+         * Owned symbol or top-level property outline a consumer reaches for on a
+         * container or object-literal variable, without bodies.
          */
         members?: IMember[];
         /** Declaration or implementation citation range, when known. */
@@ -142,16 +157,9 @@ export declare namespace ITtscGraphDetails {
         /** The edge kind connecting the two (`calls`, `type_ref`, ...). */
         relation: string;
         /**
-         * Source span for the expression that produced this relationship. It is
-         * repository evidence for the edge, not a file-read instruction.
+         * Source span that produced the edge: citation evidence, not a file-read
+         * cue.
          */
         evidence?: ITtscGraphEvidence;
-        /**
-         * Stable access-path aliases derived from edge evidence. For example, an
-         * edge to `Owner.member` through `obj.slot.member` may expose
-         * `Owner.slot.member` so answers can preserve both the resolved symbol and
-         * the source access path.
-         */
-        aliases?: string[];
     }
 }

package/lib/structures/ITtscGraphDump.d.ts

@@ -1,17 +1,18 @@
-import { ITtscGraphDiagnostic } from "./ITtscGraphDiagnostic";
 import { ITtscGraphEdge } from "./ITtscGraphEdge";
 import { ITtscGraphNode } from "./ITtscGraphNode";
+import { ITtscGraphSpan } from "./ITtscGraphSpan";
 /**
  * The whole-graph export `ttscgraph dump` writes and the MCP server loads — the
  * 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 it once at
- * startup (typia-validated) into an in-memory resident graph and answers every
- * tool call from that warm model; the bundled 3D viewer reduces the same dump.
+ * 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.
  *
- * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes,
- * edges, and diagnostics are project-relative.
+ * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes and
+ * edges are project-relative.
  */
 export interface ITtscGraphDump {
     /** Absolute path of the project root the graph was built for. */
@@ -19,12 +20,36 @@ export interface ITtscGraphDump {
     /** The tsconfig the program was loaded from, relative to `project`. */
     tsconfig: string;
     /** Every node the build recorded. */
-    nodes: ITtscGraphNode[];
+    nodes: ITtscGraphDump.INode[];
     /** Every edge the build resolved. */
-    edges: ITtscGraphEdge[];
+    edges: ITtscGraphDump.IEdge[];
+}
+export declare namespace ITtscGraphDump {
+    /**
+     * 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`.
+     *
+     * A node's declaration span is in the node's file, always — the path in the
+     * span was the same string a second time, once per node. It is the reader's
+     * to reconstruct, and {@link TtscGraphMemory} does, so nothing downstream of
+     * the loader sees a span without its file.
+     */
+    interface INode extends Omit<ITtscGraphNode, "evidence" | "implementation"> {
+        /** Declaration span; its file is this node's `file`. */
+        evidence?: ITtscGraphSpan;
+        /**
+         * Implementation span. This one keeps its file when it has one: an
+         * implementation genuinely can live in another file from its declaration.
+         */
+        implementation?: ITtscGraphSpan;
+    }
     /**
-     * Fused compiler and plugin diagnostics, when diagnostics were collected.
-     * Absent when the dump was built without a diagnostics pass.
+     * An edge as the builder sends it. Its span is in the file its `from` id
+     * names — the id is `path#Qualified.Name:kind` — so the path rode the wire a
+     * second time on every edge, and edges outnumber nodes several times over.
      */
-    diagnostics?: ITtscGraphDiagnostic[];
+    interface IEdge extends Omit<ITtscGraphEdge, "evidence"> {
+        /** Expression span; its file is the one embedded in `from`. */
+        evidence?: ITtscGraphSpan;
+    }
 }

package/lib/structures/ITtscGraphEdge.d.ts

@@ -1,12 +1,10 @@
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
 import { TtscGraphEdgeKind } from "./TtscGraphEdgeKind";
 /**
- * A directed relationship from one {@link ITtscGraphNode} to another, both named
- * by `id`. The triple `(from, to, kind)` is unique; a repeated relationship
- * keeps the first source-order evidence.
- *
- * Every edge is resolved by the compiler, so there is no per-edge trust flag to
- * carry — the whole graph is checker-resolved fact.
+ * A directed relationship between two {@link ITtscGraphNode}s, both named by
+ * `id`. The triple `(from, to, kind)` is unique; a repeat keeps the first
+ * source-order evidence. Every edge is compiler-resolved, so there is no
+ * per-edge trust flag: the whole graph is checker-resolved fact.
  */
 export interface ITtscGraphEdge {
     /** Node id the relationship originates from. */