@ttsc/graph 0.19.3 → 0.20.0

package/src/server/runTrace.ts

@@ -3,7 +3,7 @@ import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphTrace } from "../structures/ITtscGraphTrace";
-import { isExternalNode, isTestPath } from "./pathPolicy";
+import { isDeclarationFile, isExternalNode, isTestPath } from "./pathPolicy";
 import { resolveGraphHandle } from "./resolveHandle";
 import { IRunnerOutput, resultNext } from "./resultNext";
 import { edgeEvidenceOf, signatureOf } from "./runDetails";
@@ -20,15 +20,23 @@ const MAX_OPEN_DEPTH = 8;
 const MAX_OPEN_NODES = 32;
 const MAX_IMPACT_DEPTH = 4;
 const MAX_IMPACT_NODES = 16;
+// Path mode walks further than an open trace because it is looking for one
+// named end, not building a picture. The cap is the one the request contract
+// publishes for path mode.
+const MAX_PATH_DEPTH = 12;
 const MAX_HOPS_PER_NODE = 2;
 const MAX_STEPS = 12;
-const EXECUTION_KINDS = new Set<string>([
-  "calls",
-  "instantiates",
-  "accesses",
-  "renders",
-]);
 const DISPATCH_KINDS = new Set<string>(["overrides", "implements"]);
+// A declaration whose kind is a type surface never carries a body, and an
+// external leaf carries one the graph deliberately does not hold.
+const BODYLESS_KINDS = new Set<string>([
+  "interface",
+  "type",
+  "external_symbol",
+]);
+// `abstract` and `declare` are the two keywords that take the body away from a
+// declaration that would otherwise have to have one.
+const BODYLESS_MODIFIERS = new Set<string>(["abstract", "declare"]);
 // An interface the codebase implements everywhere — a disposable, a listener, a
 // lifecycle hook — is not a step in one flow, and naming its implementors is a
 // dump of the codebase rather than an answer. Past this many, the declaration
@@ -143,18 +151,24 @@ export function runTrace(
         ),
       };
     }
-    const found = findPath(
+    const pathDepth = bound(props.maxDepth, MAX_PATH_DEPTH, 1, MAX_PATH_DEPTH);
+    const search = findPath(
       graph,
       start.node.id,
       target.node.id,
-      bound(props.maxDepth, 12, 1, 12),
+      pathDepth,
       focus,
       includeExternal,
     );
-    const path = found?.path ?? [];
-    const hops = found?.hops ?? [];
+    const hasPath = search.found !== undefined;
+    const path = search.found?.path ?? [];
+    const hops = search.found?.hops ?? [];
+    // Junctions explain an absence, so they are only computed once absence is
+    // established: a walk the depth bound stopped has not established one, and
+    // presenting a shared symbol as "the seam" when a direct call path may run
+    // past the bound sends the caller to a seam that is not there.
     const junctions =
-      hops.length > 0
+      hasPath || search.bounded
         ? []
         : junctionsBetween(graph, start.node.id, target.node.id, focus);
     return {
@@ -167,18 +181,23 @@ export function runTrace(
         steps: traceSteps(graph, hops),
         ...(junctions.length > 0 ? { junctions } : {}),
       },
-      // An empty path is a fact, not an answer, and the old message called it
+      // A missing path is a fact, not an answer, and the old message called it
       // one: "its path nodes and evidence ranges are what the graph holds
-      // between the two ends" — of a result that held nothing. The two ends do
-      // not call each other, which in an event-driven codebase is the common
-      // case: a pointer handler emits, an emitter's `emit()` runs listeners a
+      // between the two ends" — of a result that held nothing. `findPath` says
+      // which fact it is; zero hops is instead the valid path from a node to
+      // itself. A walk the depth bound stopped establishes nothing at all, so
+      // it reports the bound. A walk that ran out of eligible graph did
+      // establish an absence, and distinct nodes without a path do not call
+      // each other, which in an event-driven codebase is the common case: a
+      // pointer handler emits, an emitter's `emit()` runs listeners a
       // registration put in an array, and no call edge crosses that array. The
       // callers of the target are the way across, and the graph has them, so
       // say which call to make instead of handing back an empty result dressed
       // as the answer. Excalidraw's tour spent eleven calls finding this out.
-      next:
-        hops.length > 0
-          ? pathNext
+      next: hasPath
+        ? pathNext
+        : search.bounded
+          ? resultNext("inspect", boundedPathReason(pathDepth), "trace")
           : junctions.length > 0
             ? resultNext(
                 "inspect",
@@ -203,24 +222,58 @@ export function runTrace(
   while (queue.length > 0) {
     const next: Array<{ id: string; depth: number }> = [];
     for (const { id, depth } of queue) {
-      if (depth >= maxDepth) {
-        truncated = true;
-        continue;
-      }
-      const edges = orderedEdges(
+      const { edges: candidates, omitted } = traceEdges(
         graph,
-        reverse
-          ? graph.incoming(id)
-          : [...graph.outgoing(id), ...dispatchEdges(graph, id, focus)],
-        direction,
+        id,
         reverse,
+        focus,
       );
+      // A hop the hub bound withheld is omitted whatever the depth budget does
+      // next, so the flag is set before the boundary check consumes the step.
+      if (
+        !truncated &&
+        omitted.some(
+          (edge) =>
+            eligibleTraceEndpoint(
+              graph,
+              edge,
+              reverse,
+              focus,
+              includeExternal,
+            ) !== undefined,
+        )
+      )
+        truncated = true;
+      if (depth >= maxDepth) {
+        // Reaching the configured boundary does not itself omit data. The
+        // response is truncated only when the selected walk has another hop
+        // (and, for an unseen endpoint, another node) beyond the boundary.
+        if (
+          candidates.some(
+            (edge) =>
+              eligibleTraceEndpoint(
+                graph,
+                edge,
+                reverse,
+                focus,
+                includeExternal,
+              ) !== undefined,
+          )
+        )
+          truncated = true;
+        continue;
+      }
+      const edges = orderedEdges(graph, candidates, direction, reverse);
       for (const edge of edges) {
-        if (!traversable(edge.kind, focus)) continue;
-        const otherId = reverse ? edge.from : edge.to;
-        const other = graph.node(otherId);
-        if (other === undefined || other.kind === "file") continue;
-        if (!includeExternal && isExternalNode(other)) continue;
+        const endpoint = eligibleTraceEndpoint(
+          graph,
+          edge,
+          reverse,
+          focus,
+          includeExternal,
+        );
+        if (endpoint === undefined) continue;
+        const { otherId, other } = endpoint;
         const hop: ITtscGraphTrace.IHop = {
           from: edge.from,
           to: edge.to,
@@ -272,6 +325,72 @@ export function runTrace(
   };
 }
 
+interface ITraceEndpoint {
+  otherId: string;
+  other: ITtscGraphNode;
+}
+
+/**
+ * Candidate edges in the selected direction before focus and node policy,
+ * together with the dispatch hops a bound withheld.
+ *
+ * The two have to travel together. A hub-suppressed fanout used to arrive as an
+ * empty dispatch list, which reads exactly like "this declaration dispatches to
+ * nothing", and the caller then reported a complete result while eligible hops
+ * had been dropped.
+ */
+function traceEdges(
+  graph: TtscGraphMemory,
+  id: string,
+  reverse: boolean,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): { edges: readonly ITtscGraphEdge[]; omitted: readonly ITtscGraphEdge[] } {
+  const edges = reverse ? graph.incoming(id) : graph.outgoing(id);
+  const dispatched = reverse
+    ? reverseDispatchEdges(graph, id, focus)
+    : dispatchEdges(graph, id, focus);
+  // Nothing to add is the common case, and a walk visits the nodes with the
+  // largest edge lists, so hand back the stored list rather than a copy of it.
+  return {
+    edges:
+      dispatched.selected.length === 0
+        ? edges
+        : [...edges, ...dispatched.selected],
+    omitted: dispatched.omitted,
+  };
+}
+
+/** A dispatch fanout split into what the walk follows and what a bound withheld. */
+interface IDispatchSelection {
+  readonly selected: readonly ITtscGraphEdge[];
+  readonly omitted: readonly ITtscGraphEdge[];
+}
+
+// Returned by every no-dispatch path rather than allocated per call, which is
+// why the lists above are readonly: one shared value that anything could push
+// onto would leak a hop from one node's walk into another's.
+const NO_DISPATCH: IDispatchSelection = { selected: [], omitted: [] };
+
+/**
+ * The endpoint the selected open trace would represent if no result bound
+ * stopped it. The depth probe and traversal share this decision so focus,
+ * external nodes, file nodes, and direction cannot disagree about omission.
+ */
+function eligibleTraceEndpoint(
+  graph: TtscGraphMemory,
+  edge: ITtscGraphEdge,
+  reverse: boolean,
+  focus: ITtscGraphTrace.IRequest["focus"],
+  includeExternal: boolean,
+): ITraceEndpoint | undefined {
+  if (!traversable(edge.kind, focus)) return undefined;
+  const otherId = reverse ? edge.from : edge.to;
+  const other = graph.node(otherId);
+  if (other === undefined || other.kind === "file") return undefined;
+  if (!includeExternal && isExternalNode(other)) return undefined;
+  return { otherId, other };
+}
+
 function traceSteps(
   graph: TtscGraphMemory,
   hops: ITtscGraphTrace.IHop[],
@@ -289,11 +408,6 @@ function traceSteps(
   });
 }
 
-/**
- * The shortest dependency path from `startId` to `targetId` over real (non-
- * structural) forward edges, breadth-first, or null when `targetId` is not
- * reachable within maxDepth. Returns the nodes in order and the hops between.
- */
 /**
  * The symbols both ends of an unreachable path touch.
  *
@@ -382,6 +496,57 @@ function touchedBy(
   return touched;
 }
 
+/**
+ * What to say when the depth bound, not the graph, ended a path search.
+ *
+ * The caller asked a bounded question and the old answer returned a claim about
+ * the whole graph — "they touch nothing in common, so the graph holds no
+ * connection between them" — which is the worst thing an index can say wrongly:
+ * the caller stops asking and either reads files or concludes the dependency is
+ * not there. So report the boundary, and make the continuation one the caller
+ * can actually take. At the 12-hop ceiling there is no larger `maxDepth` to
+ * retry with, and a message that only invites one would be a dead end of its
+ * own; two bounded walks from opposite ends cover twice the distance and are
+ * requests the tool already answers.
+ */
+function boundedPathReason(depth: number): string {
+  return (
+    `No path was found within the requested depth of ${depth}, but the walk stopped on that bound with eligible graph still ahead of it. ` +
+    `This is a boundary, not an absence: the two ends may be connected further out, and nothing here says they are not. ` +
+    (depth < MAX_PATH_DEPTH
+      ? `Re-run the same path request with a larger \`maxDepth\` (up to ${MAX_PATH_DEPTH}).`
+      : `\`maxDepth\` is already at its ${MAX_PATH_DEPTH}-hop maximum, so close the gap from both ends: trace forward from the start, trace the target with \`direction: "reverse"\`, then request the path between a symbol both results name.`)
+  );
+}
+
+/**
+ * What a bounded shortest-path walk learned: the path when it found one, and
+ * otherwise whether the walk was stopped by the caller's depth bound or ran the
+ * eligible graph out. The two are not the same answer and the caller must not
+ * be told the second when only the first happened.
+ */
+interface IPathSearch {
+  /** The shortest eligible path and its hops, when one was found. */
+  found?: { path: ITtscGraphNode[]; hops: ITtscGraphTrace.IHop[] };
+
+  /**
+   * True when the walk stopped at `maxDepth` with an eligible, unvisited node
+   * still ahead of it, so nothing was proven about the two ends.
+   */
+  bounded: boolean;
+}
+
+/**
+ * The shortest dependency path from `startId` to `targetId` over real (non-
+ * structural) forward edges, breadth-first, within `maxDepth` hops.
+ *
+ * When no path is found, the walk reports whether the bound stopped it. A
+ * boundary is a fact about the request; absence is a fact about the graph, and
+ * a search that never reached the far side of its own bound has not established
+ * one. Eligibility is the open trace's, so a frontier made only of nodes the
+ * selected focus, the external-node policy, a file node, or an earlier visit
+ * already excluded is not a frontier and the walk is exhausted.
+ */
 function findPath(
   graph: TtscGraphMemory,
   startId: string,
@@ -389,10 +554,11 @@ function findPath(
   maxDepth: number,
   focus: ITtscGraphTrace.IRequest["focus"],
   includeExternal: boolean,
-): { path: ITtscGraphNode[]; hops: ITtscGraphTrace.IHop[] } | null {
+): IPathSearch {
   const startNode = graph.node(startId);
-  if (startNode === undefined) return null;
-  if (startId === targetId) return { path: [startNode], hops: [] };
+  if (startNode === undefined) return { bounded: false };
+  if (startId === targetId)
+    return { found: { path: [startNode], hops: [] }, bounded: false };
   const parent = new Map<
     string,
     {
@@ -402,21 +568,35 @@ function findPath(
     }
   >();
   const visited = new Set<string>([startId]);
+  let bounded = false;
   let queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
   while (queue.length > 0) {
     const next: Array<{ id: string; depth: number }> = [];
     for (const { id, depth } of queue) {
-      if (depth >= maxDepth) continue;
-      for (const edge of [
-        ...graph.outgoing(id),
-        ...dispatchEdges(graph, id, focus),
-      ]) {
-        if (!traversable(edge.kind, focus)) continue;
-        const otherId = edge.to;
-        if (visited.has(otherId)) continue;
-        const other = graph.node(otherId);
-        if (other === undefined || other.kind === "file") continue;
-        if (!includeExternal && isExternalNode(other)) continue;
+      // The forward step the open trace would take, built in one place so the
+      // two walks cannot disagree about what a step follows.
+      const { edges: candidates } = traceEdges(graph, id, false, focus);
+      if (depth >= maxDepth) {
+        if (
+          candidates.some(
+            (edge) =>
+              pathEndpoint(graph, edge, focus, includeExternal, visited) !==
+              undefined,
+          )
+        )
+          bounded = true;
+        continue;
+      }
+      for (const edge of candidates) {
+        const endpoint = pathEndpoint(
+          graph,
+          edge,
+          focus,
+          includeExternal,
+          visited,
+        );
+        if (endpoint === undefined) continue;
+        const otherId = endpoint.otherId;
         visited.add(otherId);
         const evidence = edgeEvidenceOf(edge);
         parent.set(otherId, {
@@ -452,14 +632,42 @@ function findPath(
               hop.evidence = parentEdge.evidence;
             hops.push(hop);
           }
-          return { path, hops };
+          return { found: { path, hops }, bounded };
         }
         next.push({ id: otherId, depth: depth + 1 });
       }
     }
     queue = next;
   }
-  return null;
+  return { bounded };
+}
+
+/**
+ * The node a path expansion would represent, or undefined when the selected
+ * policy or an earlier visit excludes it. The expansion and the boundary probe
+ * share this decision, so what the walk would have followed and what counts as
+ * unexplored graph beyond the bound cannot disagree.
+ *
+ * A path walk is always forward and, unlike the open trace, a node it already
+ * reached is not a continuation: the shortest path to it is already known, so a
+ * second arrival adds nothing to explore.
+ */
+function pathEndpoint(
+  graph: TtscGraphMemory,
+  edge: ITtscGraphEdge,
+  focus: ITtscGraphTrace.IRequest["focus"],
+  includeExternal: boolean,
+  visited: ReadonlySet<string>,
+): ITraceEndpoint | undefined {
+  const endpoint = eligibleTraceEndpoint(
+    graph,
+    edge,
+    false,
+    focus,
+    includeExternal,
+  );
+  if (endpoint === undefined || visited.has(endpoint.otherId)) return undefined;
+  return endpoint;
 }
 
 function orderedEdges(
@@ -544,7 +752,7 @@ function summary(
   }
   if (depth !== undefined) out.depth = depth;
   if (withSignature) {
-    const sig = signatureOf(graph.project, node);
+    const sig = signatureOf(graph, node);
     if (sig !== undefined) out.signature = sig;
   }
   if (withRoles) {
@@ -580,14 +788,36 @@ function dispatchEdges(
   graph: TtscGraphMemory,
   id: string,
   focus: ITtscGraphTrace.IRequest["focus"],
-): ITtscGraphEdge[] {
-  if (focus === "types" || hasExecutionBody(graph, id)) return [];
-  const out: ITtscGraphEdge[] = [];
+): IDispatchSelection {
+  if (focus === "types") return NO_DISPATCH;
+  // The checker relations first: almost no node has one, and reading a
+  // declaration's own facts walks its ownership chain, which is work worth
+  // doing only where there is something to dispatch to.
+  let relations: ITtscGraphEdge[] | undefined;
   for (const edge of graph.incoming(id)) {
-    if (!DISPATCH_KINDS.has(edge.kind)) continue;
+    if (DISPATCH_KINDS.has(edge.kind)) (relations ??= []).push(edge);
+  }
+  if (relations === undefined) return NO_DISPATCH;
+  const declaration = graph.node(id);
+  if (declaration === undefined || hasDeclarationBody(graph, declaration))
+    return NO_DISPATCH;
+  const out: ITtscGraphEdge[] = [];
+  // Per implementation, not per relation. A class may name one base in two
+  // heritage clauses — `class Impl extends Base implements Base` is legal — and
+  // the producer records the member pair once per clause, as `overrides` and as
+  // `implements`. That is one implementation and one crossing: emitting it
+  // twice would repeat the hop and count the same class twice against the hub
+  // cut.
+  const dispatched = new Set<string>();
+  for (const edge of relations) {
+    if (dispatched.has(edge.from)) continue;
     const implementation = graph.node(edge.from);
-    if (implementation === undefined || !hasExecutionBody(graph, edge.from))
+    if (
+      implementation === undefined ||
+      !hasDeclarationBody(graph, implementation)
+    )
       continue;
+    dispatched.add(edge.from);
     out.push({
       from: id,
       to: edge.from,
@@ -595,16 +825,122 @@ function dispatchEdges(
       ...(edge.evidence !== undefined ? { evidence: edge.evidence } : {}),
     });
   }
-  return out.length >= DISPATCH_HUB ? [] : out;
+  // Above the hub cut the fanout stops being a trace and starts being a
+  // listing, so the walk does not follow it — but the hops are real and their
+  // absence is an omission the caller has to be able to report.
+  return out.length >= DISPATCH_HUB
+    ? { selected: [], omitted: out }
+    : { selected: out, omitted: [] };
+}
+
+/**
+ * The declaration a change to this implementation is a change to.
+ *
+ * `dispatches` is one fact and both directions have to see it. Forward, a call
+ * that lands on a bodyless declaration continues in the implementation that
+ * runs; reverse, a change to that implementation is a change every caller of
+ * the declaration feels — and `impact` is the query an agent runs _before_
+ * editing a method. The checker relation is oriented implementation-to-base, so
+ * from the implementation it is an outgoing edge and a reverse walk, which only
+ * reads incoming edges, never sees it. Both halves of the path are one step
+ * away in a direction the traversal does not take.
+ *
+ * The synthetic edge is the forward one, unchanged, so eligibility, checker
+ * validity, and the hub cut cannot drift apart between the two directions: ask
+ * the base what it dispatches to, and keep the edges that land here.
+ */
+function reverseDispatchEdges(
+  graph: TtscGraphMemory,
+  id: string,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): IDispatchSelection {
+  if (focus === "types") return NO_DISPATCH;
+  const selected: ITtscGraphEdge[] = [];
+  const omitted: ITtscGraphEdge[] = [];
+  const bases = new Set<string>();
+  for (const edge of graph.outgoing(id)) {
+    if (!DISPATCH_KINDS.has(edge.kind) || bases.has(edge.to)) continue;
+    bases.add(edge.to);
+    const fanout = dispatchEdges(graph, edge.to, focus);
+    for (const dispatch of fanout.selected)
+      if (dispatch.to === id) selected.push(dispatch);
+    // The base's fanout is bounded as a whole, so a reverse walk that lands on
+    // a suppressed sibling has the same omission to report as the forward one.
+    for (const dispatch of fanout.omitted)
+      if (dispatch.to === id) omitted.push(dispatch);
+  }
+  return { selected, omitted };
+}
+
+/**
+ * Whether the declaration this node stands for has a body of its own.
+ *
+ * Having a body and naming a modeled dependency are different facts. Counting
+ * outgoing `calls`/`accesses`/`instantiates`/`renders` edges measures the
+ * second and answers as though it were the first, and it is wrong in both
+ * directions: an implementation whose body returns a literal, throws, or only
+ * moves locals around has degree zero and was refused as a dispatch target,
+ * while a concrete base method was promoted through its own override the moment
+ * its body stopped naming anything the graph models. Two graphs identical in
+ * every declaration fact then answered differently because of one statement
+ * inside a body.
+ *
+ * So read the declaration instead. A type surface has no body; `abstract` and
+ * `declare` take it away; an interface member and anything inside an ambient
+ * container never had one; a `.d.ts` declaration is ambient whether or not the
+ * keyword is written; and an external leaf has a body the graph deliberately
+ * does not hold. Everything else is a concrete declaration, which is a real
+ * destination and is never promoted through an override, whatever it calls.
+ */
+export function hasDeclarationBody(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): boolean {
+  if (BODYLESS_KINDS.has(node.kind)) return false;
+  if (isExternalNode(node)) return false;
+  if (isDeclarationFile(node.file)) return false;
+  if (hasBodylessModifier(node)) return false;
+  return !inBodylessContainer(graph, node);
 }
 
-/** Whether the declaration has a body: something it calls, reads, or renders. */
-function hasExecutionBody(graph: TtscGraphMemory, id: string): boolean {
-  for (const edge of graph.outgoing(id))
-    if (EXECUTION_KINDS.has(edge.kind)) return true;
+function hasBodylessModifier(node: ITtscGraphNode): boolean {
+  return node.modifiers?.some((m) => BODYLESS_MODIFIERS.has(m)) === true;
+}
+
+/**
+ * Whether an owner up the `contains` tree makes this declaration bodyless: an
+ * interface, or an ambient container. A member writes no keyword of its own —
+ * `declare` on a class or namespace is not repeated on what it holds — so the
+ * fact lives on the owner and the walk has to go get it.
+ */
+function inBodylessContainer(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): boolean {
+  const seen = new Set<string>([node.id]);
+  let current: ITtscGraphNode | undefined = node;
+  while (current !== undefined) {
+    const container: ITtscGraphNode | undefined = containerOf(graph, current);
+    if (container === undefined || container.kind === "file") return false;
+    if (seen.has(container.id)) return false;
+    seen.add(container.id);
+    if (container.kind === "interface" || hasBodylessModifier(container))
+      return true;
+    current = container;
+  }
   return false;
 }
 
+/** The declaration that owns this one, through the synthesized ownership tree. */
+function containerOf(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): ITtscGraphNode | undefined {
+  for (const edge of graph.incoming(node.id))
+    if (edge.kind === "contains") return graph.node(edge.from);
+  return undefined;
+}
+
 /** An edge the trace should follow: a real dependency, not a structural edge. */
 function traversable(
   kind: string,

package/src/structures/ITtscGraphDump.ts

@@ -13,19 +13,19 @@ import { ITtscGraphSpan } from "./ITtscGraphSpan";
  * warm model while project inputs stay unchanged; the bundled 3D viewer reduces
  * the same dump.
  *
- * `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:///…`.
+ * `project` is the producer-local absolute locator. Every identity-bearing path
+ * uses one schema-v6 coordinate relative to it: project files are ordinary
+ * relative paths; same-filesystem siblings use `../` segments; package files
+ * keep their full resolution context (including version/peer-store segments);
+ * and a virtual compiler source stays `bundled:///…`. Raw absolute identities
+ * are never emitted. A source on another drive or UNC share makes the producer
+ * fail unless a future contract supplies a logical root for it.
  */
 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`. */
+  /** The tsconfig the program was loaded from, in the dump's path vocabulary. */
   tsconfig: string;
 
   /** Evidence about the one program that produced everything below. */
@@ -143,16 +143,16 @@ export namespace ITtscGraphDump {
 
   /** A root file attributed to the config that named it. */
   export interface IRootFile {
-    /** The tsconfig that named this root, project-relative. */
+    /** The tsconfig that named this root, in the dump's path vocabulary. */
     config: string;
 
-    /** The root file, project-relative. */
+    /** The root file, in the dump's path vocabulary. */
     file: string;
   }
 
   /** A file and the hex-encoded SHA-256 of its on-disk bytes. */
   export interface IFileDigest {
-    /** Project-relative. */
+    /** In the dump's path vocabulary. */
     file: string;
 
     /** Hex-encoded SHA-256. */
@@ -169,7 +169,7 @@ export namespace ITtscGraphDump {
    * on every build.
    */
   export interface ISourceDigest {
-    /** Project-relative. */
+    /** In the dump's path vocabulary. */
     file: string;
 
     /**
@@ -199,7 +199,7 @@ export namespace ITtscGraphDump {
 
   /** One compiler diagnostic from the generation that produced the facts. */
   export interface IDiagnostic {
-    /** Project-relative. */
+    /** In the dump's path vocabulary. */
     file: string;
 
     /** 1-based line. */