@ttsc/graph 0.19.1 → 0.19.3

package/src/resolveGraphBinary.ts

@@ -5,9 +5,15 @@ import path from "node:path";
  * Resolve the per-platform `ttscgraph` binary, or `null` when it cannot be
  * located.
  *
- * `ttsc` is a peer the user installs alongside `@ttsc/graph` (not a dependency
- * of this launcher), so resolution starts from the user's project, not from
- * this package's own tree.
+ * `ttsc` is a peer dependency pinned to this package's own version, installed
+ * alongside `@ttsc/graph` in the user's project rather than nested under this
+ * launcher, so resolution starts from the user's project, not from this
+ * package's own tree.
+ *
+ * The pin is what keeps the two halves of the graph in step. `literals` and the
+ * rest of the node facts are resolved by the Go builder and ride the dump, so a
+ * newer `@ttsc/graph` reading an older `ttscgraph` would find those fields
+ * simply absent and answer from a graph missing facts it believes are there.
  *
  * Resolution order:
  *

package/src/server/resultAudit.ts

@@ -47,14 +47,18 @@
  * payload, and told it to stop where the shortlist's coverage was exactly what
  * needed judging.
  *
- * So there are two audits. {@link RESULT_AUDIT} covers the operations that walk
- * from an explicit handle or structure (`trace`, `details`, `overview`): the
- * result is what the graph holds for what you named, bounded only where
- * `truncated` says. {@link RESULT_AUDIT_SELECTION} covers the ranked shortlists
- * (`lookup`, `entrypoints`, `tour`): it keeps the same fact-verification and
- * adds that the _selection_ is heuristic, so whether the shortlist covers the
- * question is the caller's to judge — and a follow-up request or a read of a
- * cited span is a sound next step, not a failure to trust the result.
+ * So the audits split by what the reader must judge. {@link RESULT_AUDIT}
+ * covers the walks from an explicit handle or structure (`trace`, `overview`):
+ * the result is what the graph holds for what you named, bounded where
+ * `truncated` says. {@link RESULT_AUDIT_DETAILS} covers `details`, whose result
+ * is not one bounded whole but two halves — a symbol's own shape, returned
+ * complete, and its fan-out, returned as a slice with `trace` for the rest — so
+ * it names which half to trust outright and which to follow. {@link
+ * RESULT_AUDIT_SELECTION} covers the ranked shortlists (`lookup`, `entrypoints`,
+ * `tour`): it keeps the same fact-verification and adds that the _selection_ is
+ * heuristic, so whether the shortlist covers the question is the caller's to
+ * judge — and a follow-up request or a read of a cited span is a sound next
+ * step, not a failure to trust the result.
  *
  * Keep both narrow, and keep the stop-or-continue decision with the result's
  * `next`, so neither contradicts a partial result that legitimately asks for
@@ -104,6 +108,41 @@ span is a sound next step, not a failure to trust the result.
 Follow \`next\` for where that leaves the question.
 `.trim();
 
+/**
+ * The audit for `details`, whose contract is not the other exact operations'.
+ *
+ * `trace` walks and marks where the walk was cut with `truncated`; `details`
+ * does not walk. It resolves a named handle, and its result splits in two. What
+ * a symbol *is* — its members, its values, its signature — is bounded by the
+ * declaration and returned whole, so the old "trust it, do not open the file"
+ * is finally true of it rather than contradicted by a capped member list. What
+ * a symbol *reaches or is reached by* — its calls, its type references, its
+ * implementers, its dependents — is bounded by how widely it is used, not by
+ * the symbol, so returning it whole is a `trace`/impact answer of a thousand
+ * refs in a "what is this" call. That half is a short orientation slice, and
+ * the audit has to say which half is which so the reader trusts the complete
+ * one and reaches for `trace` on the other, instead of reading the file for a
+ * member list that is already here.
+ */
+export const RESULT_AUDIT_DETAILS: string = `
+AUDITED BEFORE RETURNING. READ FIRST.
+
+The server assembled this \`result\`, then checked it: every fact in it — each name, span,
+edge, signature, member, and value — was taken back to the type-checked program for the
+snapshot this call synced to, and resolved there, so for this snapshot a fact here cannot be
+wrong.
+
+This is the structure the graph holds for the handles you named. What a symbol is — its
+members, its values, its signature — is complete: trust it and do not open the file to read
+what is already here. What a symbol reaches or is reached by — its calls, its type
+references, its implementers, and under \`neighbors\` its dependents — is a short orientation
+slice, not the whole set, because that grows with how widely a symbol is used; \`trace\`
+follows it in full.
+
+Follow \`next\`: answer from this result, and re-call the graph only when it says inspect, or
+after you edit the source.
+`.trim();
+
 /** The escape branch carries no graph facts, so it claims none. */
 export const RESULT_AUDIT_ESCAPE: string =
   "This escape carries no graph facts to audit.";

package/src/server/runDetails.ts

@@ -15,17 +15,20 @@ import { IRunnerOutput, resultNext } from "./resultNext";
 const MAX_SIGNATURE_LINES = 4;
 // A doc summary is one sentence; the rest of the comment is the file's to keep.
 const MAX_DOC_CHARS = 200;
-// Neighbor lists are a map, not a dump; keep them scannable.
+// An object literal's outline is scanned from source, so a runaway literal is
+// bounded here; the members it does find are not capped.
+const MAX_OBJECT_MEMBER_LINES = 300;
+// A symbol's fan-out — what it calls, what names it in a type, what depends on
+// it — scales with how popular it is, not with the symbol: a central type is
+// named in a thousand places, and returning all of them is a hundred thousand
+// tokens of "who uses this", which is a trace/impact question, not "what is
+// this". So fan-out is a small default slice; identity (members, literals) is
+// not, because a class's members and a union's values are the symbol itself and
+// are bounded by the declaration.
 const DEFAULT_NEIGHBORS = 2;
 const MAX_NEIGHBORS = 3;
-// A container outline can be long; default to a scannable first page.
-const DEFAULT_MEMBERS = 6;
-const MAX_MEMBERS = 8;
-// Direct dependency groups are orientation slices, not full fan-out dumps.
 const DEFAULT_DEPENDENCIES = 2;
 const MAX_DEPENDENCIES = 4;
-// Object literal outlines are navigation aids, not source excerpts.
-const MAX_OBJECT_MEMBER_LINES = 300;
 // Structural relationships are navigation, not the dependency picture details is for.
 const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
 // Kinds whose value is their member outline, not implementation text.
@@ -47,17 +50,17 @@ export function runDetails(
   graph: TtscGraphMemory,
   props: ITtscGraphDetails.IRequest,
 ): IRunnerOutput<ITtscGraphDetails> {
-  const neighborLimit = bound(
-    props.neighborLimit,
-    DEFAULT_NEIGHBORS,
-    1,
-    MAX_NEIGHBORS,
-  );
-  const memberLimit = bound(props.memberLimit, DEFAULT_MEMBERS, 1, MAX_MEMBERS);
-  const dependencyLimit = bound(
+  // Identity is the whole answer. The caller named this handle to learn what it
+  // is, and a class's members or a union's values are the symbol itself — cut
+  // them and the model reads the file for the rest, the read this index exists
+  // to remove. So `memberLimit` and `literals` default to unlimited. Fan-out
+  // does not: what names or uses a symbol is bounded by its popularity, not by
+  // it, so those stay a small slice with `trace` for the rest.
+  const memberLimit = limitOf(props.memberLimit);
+  const neighborLimit = capOf(props.neighborLimit, DEFAULT_NEIGHBORS, MAX_NEIGHBORS);
+  const dependencyLimit = capOf(
     props.dependencyLimit,
     DEFAULT_DEPENDENCIES,
-    1,
     MAX_DEPENDENCIES,
   );
   const wantNeighbors = props.neighbors === true;
@@ -101,7 +104,6 @@ export function runDetails(
     if (sig !== undefined) detail.signature = sig;
     const doc = docOf(graph.project, node);
     if (doc !== undefined) detail.doc = doc;
-    const signatureLiterals = literalSummaries(sig);
     const decorators = decoratorsOf(node);
     if (decorators !== undefined) detail.decorators = decorators;
     const implementation = evidenceCoordinatesOf(node.implementation);
@@ -150,8 +152,18 @@ export function runDetails(
       );
       if (list.length > 0) detail.members = list;
     }
-    if (signatureLiterals.length > 0)
-      detail.literals = signatureLiterals.slice(0, 6);
+    // An enum's members ride on its own node rather than on `contains` edges,
+    // because they are not nodes: the outline above finds nothing for an enum
+    // and always did. Its signature stops at the `{`, so without this the one
+    // kind whose entire content is its member list answered with none of it.
+    // Uncapped like every other identity list — the members are the enum.
+    if (node.kind === "enum") {
+      const list = enumMembers(node, memberLimit);
+      if (list.length > 0) detail.members = list;
+    }
+    if (node.literals !== undefined && node.literals.length > 0) {
+      detail.literals = node.literals;
+    }
     if (wantNeighbors) {
       detail.dependsOn = refs(
         graph,
@@ -222,6 +234,28 @@ function members(
   return out;
 }
 
+/**
+ * An enum's members, owner-qualified so the name reads the way the code writes
+ * it, with the value each carries as its signature.
+ *
+ * The name is why this exists. `literals` answers what values the enum admits,
+ * but a caller writes `Colors.Red` and never `"red"`, so an enum the graph
+ * already held sent a caller that had named it to the file for the one fact it
+ * came for (#738).
+ */
+function enumMembers(
+  node: ITtscGraphNode,
+  limit: number,
+): ITtscGraphDetails.IMember[] {
+  return (node.enumMembers ?? []).slice(0, limit).map((member) => ({
+    name: `${node.qualifiedName ?? node.name}.${member.name}`,
+    kind: "property",
+    ...(member.value !== undefined
+      ? { signature: `${member.name} = ${member.value}` }
+      : {}),
+  }));
+}
+
 function objectLiteralMembers(
   project: string,
   span: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">,
@@ -328,13 +362,11 @@ function refs(
     if (evidence !== undefined) ref.evidence = evidence;
     ranked.push({ ref, rank: refRank(ref, edge) });
   }
+  // Ranked so a caller that does throttle (the tour) keeps the strongest refs,
+  // not the ones nearest the top of a file. Uncapped, `limit` is Infinity and
+  // the sort is just a stable order.
   ranked.sort((a, b) => a.rank - b.rank);
-  const out: ITtscGraphDetails.IReference[] = [];
-  for (const item of ranked) {
-    out.push(item.ref);
-    if (out.length >= limit) break;
-  }
-  return out;
+  return ranked.map((item) => item.ref).slice(0, limit);
 }
 
 const executionKinds = new Set([
@@ -375,17 +407,7 @@ function dependencyRefs(
       rank: refRank(ref, edge),
     });
   }
-  ranked.sort((a, b) => a.rank - b.rank);
-  const out: ITtscGraphDetails.IReference[] = [];
-  const seen = new Set<string>();
-  for (const item of ranked) {
-    const key = `${item.ref.relation}:${item.ref.id}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push(item.ref);
-    if (out.length >= limit) break;
-  }
-  return out;
+  return rankedRefs(ranked, limit);
 }
 
 function incomingDependencyRefs(
@@ -416,6 +438,14 @@ function incomingDependencyRefs(
       rank: refRank(ref, edge),
     });
   }
+  return rankedRefs(ranked, limit);
+}
+
+/** Sort by rank, drop duplicate (relation, id) pairs, and cut to `limit`. */
+function rankedRefs(
+  ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }>,
+  limit: number,
+): ITtscGraphDetails.IReference[] {
   ranked.sort((a, b) => a.rank - b.rank);
   const out: ITtscGraphDetails.IReference[] = [];
   const seen = new Set<string>();
@@ -429,38 +459,26 @@ function incomingDependencyRefs(
   return out;
 }
 
-function literalSummaries(text: string | undefined): string[] {
-  if (text === undefined) return [];
-  const out: string[] = [];
-  for (const match of text.matchAll(/(["'`])((?:\\.|(?!\1).){1,80})\1/g)) {
-    const value = cleanLiteral(match[2]);
-    if (value !== undefined && !out.includes(value)) out.push(value);
-    if (out.length >= 20) break;
-  }
-  return out;
-}
-
-function cleanLiteral(value: string | undefined): string | undefined {
-  const text = value?.replace(/\s+/g, " ").trim();
-  if (
-    text === undefined ||
-    text === "" ||
-    text.length > 40 ||
-    /^[{}()[\],.:;]+$/.test(text)
-  ) {
-    return undefined;
-  }
-  return text;
+/**
+ * An identity list's cap: none by default, honored when a caller passes one.
+ * details answers a named handle's own shape in full — its members, its values —
+ * so the default is unlimited; the tour passes an explicit number to embed a
+ * compact slice of its own.
+ */
+function limitOf(value: number | undefined): number {
+  return value === undefined || !Number.isFinite(value)
+    ? Infinity
+    : Math.max(1, Math.floor(value));
 }
 
-function bound(
-  value: number | undefined,
-  fallback: number,
-  min: number,
-  max: number,
-): number {
+/**
+ * A fan-out list's cap: a small default, clamped to a ceiling. What names or
+ * uses a symbol grows with its popularity, not with the symbol, so the whole
+ * list is a trace/impact answer and details returns an orientation slice.
+ */
+function capOf(value: number | undefined, fallback: number, max: number): number {
   const n = value === undefined || !Number.isFinite(value) ? fallback : value;
-  return Math.max(min, Math.min(max, Math.floor(n)));
+  return Math.max(1, Math.min(max, Math.floor(n)));
 }
 
 /**
@@ -611,6 +629,13 @@ export function docOf(
  * The declaration signature: the head of the declaration up to and including
  * the line that opens its body (`{`), or the single declaration line when there
  * is no brace, capped so a wrapped signature cannot run away.
+ *
+ * It never runs past the declaration's own span. The stop used to be the brace,
+ * the trailing semicolon, or the line cap, and a declaration ending in none of
+ * them read its neighbors instead: an enum member ends in a comma, so `VIEW`
+ * came back as itself plus the two members after it and the closing brace. The
+ * span is the fact that says where the declaration ends, and it was already on
+ * the node.
  */
 export function signatureOf(
   project: string,
@@ -621,12 +646,12 @@ export function signatureOf(
     evidence === undefined ? undefined : fileLines(project, evidence.file);
   if (lines === undefined || evidence === undefined) return undefined;
   const start = Math.max(0, evidence.startLine - 1);
+  const last =
+    evidence.endLine === undefined
+      ? lines.length - 1
+      : Math.min(lines.length - 1, evidence.endLine - 1);
   const out: string[] = [];
-  for (
-    let i = start;
-    i < lines.length && out.length < MAX_SIGNATURE_LINES;
-    i++
-  ) {
+  for (let i = start; i <= last && out.length < MAX_SIGNATURE_LINES; i++) {
     const line = lines[i];
     if (line === undefined) break;
     out.push(line);

package/src/structures/ITtscGraphApplication.ts

@@ -169,13 +169,14 @@ export namespace ITtscGraphApplication {
      * 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.
+     * The audit is operation-aware. For the walks from a named handle (`trace`,
+     * `overview`) it reports the result as the structure the graph holds,
+     * bounded where `truncated` says. For `details` it reports the two halves of
+     * a resolved symbol: its own shape returned whole, its fan-out returned as a
+     * slice with `trace` for the rest. 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;
 

package/src/structures/ITtscGraphDetails.ts

@@ -49,24 +49,26 @@ export 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;
 
@@ -145,7 +147,15 @@ export namespace ITtscGraphDetails {
     /** 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[];
 
     /**

package/src/structures/ITtscGraphDump.ts

@@ -7,13 +7,19 @@ 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. */
@@ -22,6 +28,17 @@ export interface ITtscGraphDump {
   /** 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[];
 
@@ -30,6 +47,177 @@ export interface ITtscGraphDump {
 }
 
 export 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.
+   */
+  export 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.
+   */
+  export 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.
+   */
+  export 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. */
+  export 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. */
+  export 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.
+   */
+  export 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. */
+  export 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`.