@ttsc/graph 0.30.4 → 0.31.0

package/src/structures/ITtscGraphSnapshot.ts

@@ -9,6 +9,15 @@ import { ITtscGraphDump } from "./ITtscGraphDump";
  * 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.
+ *
+ * @evidence contracts/common.md#principled-implementation Request identity, independent protocol version and changed/error state qualify the optional full dump or shard transaction.
+ * @evidence contracts/common.md#clear-and-simple-design One transport envelope keeps response routing and computation mode outside the content payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Mode is a producer report rather than a guessed interpretation of generation counters.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain hand-maintained wire synchronization, version independence and error/changed payload semantics.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
  */
 export interface ITtscGraphSnapshot {
   /** Echoes the request's id, so a response finds its caller. */
@@ -52,41 +61,138 @@ export interface ITtscGraphSnapshot {
 }
 
 export namespace ITtscGraphSnapshot {
-  /** Versioned content-addressed transaction emitted by `ttscgraph serve`. */
+  /**
+   * Versioned content-addressed transaction emitted by `ttscgraph serve`.
+   *
+   * Sequence and generation name this commit and its optional preceding base.
+   * The complete manifest describes the resulting shard set; upserts and
+   * deletes specify the change needed to reach it.
+   *
+   * @evidence contracts/common.md#principled-implementation Base coordinates and a complete digest manifest permit atomic validation of a delta against its preceding generation.
+   * @evidence contracts/common.md#clear-and-simple-design Transaction metadata and three shard-change collections separate generation authority from fact storage.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A delta cannot silently substitute an unrelated generation; its claimed base is explicit.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains base and manifest semantics, and member comments distinguish versions, generation coordinates and payload populations.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface ITransaction {
+    /** Shard transaction protocol version. */
     protocolVersion: number;
+
+    /** Schema version of the graph facts inside the shards. */
     schemaVersion: number;
+
+    /** Producer-local absolute project locator. */
     project: string;
+
+    /** Configuration coordinate in the dump path vocabulary. */
     tsconfig: string;
+
+    /** Native binary and checker that produced the transaction. */
     producer: ITtscGraphDump.IProducer;
+
+    /** Evidence capabilities reported for this generation. */
     capabilities: string[];
+
+    /** Complete configuration and root membership inputs. */
     universe: ITtscGraphDump.IUniverse;
+
+    /** Positive consecutive transaction number within the resident session. */
     sequence: number;
+
+    /** Content-derived identity of the resulting generation. */
     generation: string;
+
+    /** Preceding transaction number, absent on the initial complete frame. */
     baseSequence?: number;
+
+    /** Preceding generation identity, absent on the initial complete frame. */
     baseGeneration?: string;
+
+    /** New or changed shard contents, qualified by their digest. */
     upserts: IShardUpsert[];
+
+    /** Keys removed from the preceding committed generation. */
     deletes: string[];
+
+    /** Complete key/digest set after applying this transaction. */
     manifest: IShardReference[];
   }
 
+  /**
+   * One replacement shard and the digest used to verify its contents.
+   *
+   * @evidence contracts/common.md#principled-implementation Pairing content with its digest lets the receiver reject a changed or incorrectly labeled shard.
+   * @evidence contracts/common.md#clear-and-simple-design The upsert contains only the payload and its content witness.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The digest qualifies actual content rather than a filename or timestamp proxy.
+   * @evidence contracts/common.md#meaningful-documentation Native member comments distinguish content witness from the replacement payload.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IShardUpsert {
+    /** Hex SHA-256 of the canonical Go JSON shard representation. */
     digest: string;
+
+    /** Complete replacement contents for the shard key inside this payload. */
     shard: IShard;
   }
 
+  /**
+   * A shard's membership and content identity in a generation manifest.
+   *
+   * @evidence contracts/common.md#principled-implementation Key and digest identify one retained shard version without requiring its content to be resent.
+   * @evidence contracts/common.md#clear-and-simple-design The manifest reference stays distinct from an upsert because unchanged entries have no payload.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A retained entry is identified by content digest rather than assumed unchanged from its key alone.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain membership key and canonical-content digest.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IShardReference {
+    /** Logical shard ownership key. */
     key: string;
+
+    /** Hex SHA-256 of the canonical Go JSON shard representation. */
     digest: string;
   }
 
-  /** One source/config or metadata-owned raw compiler fact shard. */
+  /**
+   * One source/config or metadata-owned raw compiler fact shard.
+   *
+   * Source and config attribution are mutually exclusive. With neither, this is
+   * the metadata shard for external leaves and published artifacts.
+   *
+   * @evidence contracts/common.md#principled-implementation Key plus optional input attribution defines ownership of the node, edge and diagnostic arrays validated by the shard store.
+   * @evidence contracts/common.md#clear-and-simple-design One shard carries complete owner-local facts while the transaction controls cross-shard membership.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Metadata ownership cannot be used to hide authored declarations from source attribution checks.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains mutually exclusive source/config attribution and the separate metadata role; members identify each fact population.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IShard {
+    /** Ownership coordinate shared with the generation manifest. */
     key: string;
+
+    /** Source-byte witnesses when one compiler source owns this shard. */
     source?: ITtscGraphDump.ISourceDigest;
+
+    /** Configuration-byte witness when a build configuration owns this shard. */
     config?: ITtscGraphDump.IFileDigest;
+
+    /** Raw native nodes owned by this source or metadata shard. */
     nodes: ITtscGraphDump.INode[];
+
+    /** Raw native edges whose source node this source shard owns. */
     edges: ITtscGraphDump.IEdge[];
+
+    /** Compiler findings attributed to the shard's input or metadata. */
     diagnostics: ITtscGraphDump.IDiagnostic[];
   }
 
@@ -99,6 +205,15 @@ export namespace ITtscGraphSnapshot {
    * - `incremental`: edits applied onto the reused resident program.
    * - `rebuild`: edits applied, but graph projection required a complete build.
    * - `error`: no snapshot was produced.
+   *
+   * @evidence contracts/common.md#principled-implementation Literal computation modes preserve the producer's distinction between reuse, updates, full reloads and failure.
+   * @evidence contracts/common.md#clear-and-simple-design One shared union types mode reports independently of payload availability.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The client cannot rename a rebuild incremental solely to claim better performance.
+   * @evidence contracts/common.md#meaningful-documentation Each mode's native bullet explains the producer event and whether a new snapshot exists.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
    */
   export type Mode =
     | "initial"

package/src/structures/ITtscGraphSpan.ts

@@ -11,6 +11,15 @@
  * the graph engine and the MCP results see is the whole
  * {@link ITtscGraphEvidence}. This shape exists only between the Go builder and
  * the loader.
+ *
+ * @evidence contracts/common.md#principled-implementation One-based coordinates and an optional non-derivable file preserve exact wire spans with reconstructible ordinary paths omitted.
+ * @evidence contracts/common.md#clear-and-simple-design The compact wire shape stays separate from the fully qualified memory evidence shape.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Cross-file implementations retain their explicit file instead of being forced into the owner's path.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain reconstruction ownership and member comments state coordinate units and file absence semantics.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
  */
 export interface ITtscGraphSpan {
   /**

package/src/structures/ITtscGraphTour.ts

@@ -1,6 +1,17 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 
-/** Answer-ready, source-free tour evidence for broad code-flow questions. */
+/**
+ * Answer-ready, source-free tour evidence for broad code-flow questions.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate seeds, graph flows and citation collections express a selected index tour without claiming complete runtime execution.
+ * @evidence contracts/common.md#clear-and-simple-design Each tour facet has one collection; shared coordinates avoid embedding source bodies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Truncation reports omitted extras rather than hiding a cutoff to improve tool-call metrics.
+ * @evidence contracts/common.md#meaningful-documentation Native comments distinguish flow facts, nearby/test anchors and citation-only answer anchors.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
 export interface ITtscGraphTour {
   /** Discriminator for code-tour indexing. */
   type: "tour";
@@ -28,8 +39,17 @@ export namespace ITtscGraphTour {
   /**
    * A broad code tour: entrypoints, primary flow, nearby paths, and tests.
    *
-   * It asks for no question of its own — it ranks against the `question` the
-   * caller has already written, in the user's words.
+   * It uses the outer question for explicit handles and the caller's symbol
+   * reinterpretations for identifier alignment, alongside graph centrality.
+   *
+   * @evidence contracts/common.md#principled-implementation Reinterpretations supply resolved candidate handles and identifier alignment; the outer question supplies explicit mentions, and optional limits select entries.
+   * @evidence contracts/common.md#clear-and-simple-design Caller-supplied symbol guesses remain distinct from the outer question rather than being merged into another prose query.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An empty guess list is supported; unknown or ambiguous guesses do not fabricate seeds.
+   * @evidence contracts/common.md#meaningful-documentation Separate member paragraphs explain guesses, empty input, seed allocation and defaults rather than requiring repository reconnaissance.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
    */
   export interface IRequest {
     /** Discriminator for code-tour indexing. */
@@ -63,8 +83,9 @@ export namespace ITtscGraphTour {
     reinterpretations: string[];
 
     /**
-     * Central entrypoints to seed the tour. Raise only when the question names
-     * several public paths that must all appear in one answer.
+     * Central entrypoints to seed the tour, from 1 to 5. The default is the
+     * maximum, so a larger value changes nothing and a smaller one narrows the
+     * tour.
      *
      * @default 5
      */
@@ -78,7 +99,18 @@ export namespace ITtscGraphTour {
     includeTests?: boolean;
   }
 
-  /** A compact symbol coordinate for a tour. */
+  /**
+   * A compact symbol coordinate for a tour.
+   *
+   * @evidence contracts/common.md#principled-implementation Stable identity, coordinates and optional declaration facts describe a selected symbol without implementation bodies.
+   * @evidence contracts/common.md#clear-and-simple-design One compact node is reused by entrypoints and flow starts.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional documentation remains a declaration fact rather than an inferred purpose from naming.
+   * @evidence contracts/common.md#meaningful-documentation Member comments explain one-based coordinates, declaration heads and the first doc sentence's role.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface INode {
     /** Stable node id for later graph calls. */
     id: string;
@@ -112,7 +144,18 @@ export namespace ITtscGraphTour {
     decorators?: ITtscGraphDecorator[];
   }
 
-  /** A primary flow slice from one selected entrypoint. */
+  /**
+   * A primary flow slice from one selected entrypoint.
+   *
+   * @evidence contracts/common.md#principled-implementation Start, ordered edge summaries and reached handles distinguish a selected flow slice from a complete call graph.
+   * @evidence contracts/common.md#clear-and-simple-design Prose steps serve display while reached records supply actionable identities without parsing that prose.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A truncation flag reports omitted steps; summaries cannot invent bridges between unrelated seeds.
+   * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain why reached handles accompany step text and what truncation means.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IFlow {
     /** Flow start node. */
     start: ITtscGraphTour.INode;
@@ -142,6 +185,15 @@ export namespace ITtscGraphTour {
    * three times. Across the benchmark corpus that repetition was 15% of every
    * tour, and a tour is re-sent whole on every turn of the conversation it
    * opened.
+   *
+   * @evidence contracts/common.md#principled-implementation Stable id preserves file and kind coordinates; name and optional line add presentation without losing follow-up identity.
+   * @evidence contracts/common.md#clear-and-simple-design The reached record omits coordinates already carried in the id instead of copying the full tour node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Compacting retains the actual node id rather than substituting abbreviated names.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain id grammar and one-based line units, separated from acknowledgments.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
    */
   export interface IReached {
     /** Stable node id for later graph calls: `file#Qualified.Name:kind`. */
@@ -154,7 +206,18 @@ export namespace ITtscGraphTour {
     line?: number;
   }
 
-  /** A file/line citation chosen by the graph, not source body text. */
+  /**
+   * A file/line citation chosen by the graph, not source body text.
+   *
+   * @evidence contracts/common.md#principled-implementation Required file/start line ground a citation; optional identity and kind allow node and edge anchors in one representation.
+   * @evidence contracts/common.md#clear-and-simple-design Reason and coordinates are sufficient to present an anchor without carrying the referenced body.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing node identity is represented as optional rather than fabricated for non-node citations.
+   * @evidence contracts/common.md#meaningful-documentation Member comments explain node-dependent optional fields, citation purpose and one-based endpoints.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IAnchor {
     /** Why this anchor matters in the tour. */
     reason: string;
@@ -178,7 +241,18 @@ export namespace ITtscGraphTour {
     endLine?: number;
   }
 
-  /** Source coordinates without source text. */
+  /**
+   * Source coordinates without source text.
+   *
+   * @evidence contracts/common.md#principled-implementation File and one-based endpoints express the available source range without attaching source bytes.
+   * @evidence contracts/common.md#clear-and-simple-design Three fields carry only the citation range needed by tour nodes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown end lines stay absent instead of being guessed from another declaration.
+   * @evidence contracts/common.md#meaningful-documentation Native comments state project-relative file spelling and optional endpoint meaning.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface ISpan {
     /** Project-relative file. */
     file: string;

package/src/structures/ITtscGraphTrace.ts

@@ -1,6 +1,17 @@
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
 
-/** The compact dependency or caller flow returned from a selected start symbol. */
+/**
+ * The compact dependency or caller flow returned from a selected start symbol.
+ *
+ * @evidence contracts/common.md#principled-implementation Start, reached nodes, hops and optional target/path distinguish open traversal from requested-path outcomes and ambiguity.
+ * @evidence contracts/common.md#clear-and-simple-design Optional path and junction facets extend one trace result without disguising a shared junction as a path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unreachable paths remain empty and ambiguity retains candidates rather than invented execution edges.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain breadth-first order, truncation, unreachable paths and the difference between a junction and a call path.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
 export interface ITtscGraphTrace {
   /** Discriminator for dependency tracing. */
   type: "trace";
@@ -14,10 +25,10 @@ export interface ITtscGraphTrace {
   /** Edges traversed, in breadth-first order. */
   hops: ITtscGraphTrace.IHop[];
 
-  /** Unique nodes reached (excluding the start), each with its depth and roles. */
+  /** Unique nodes reached (excluding the start), each with its depth, and its roles on an impact trace. */
   reached: ITtscGraphTrace.INode[];
 
-  /** In an open trace, true when a bound omitted an eligible node or hop. */
+  /** True when an open walk omitted an eligible node or hop, or an unsuccessful path search stopped on a depth or dispatch bound. */
   truncated: boolean;
 
   /** The resolved `to` target, when a path was requested. */
@@ -29,11 +40,12 @@ export interface ITtscGraphTrace {
    */
   path?: ITtscGraphTrace.INode[];
 
-  /** Compact hop summaries preserving node names and edge evidence, capped. */
+  /** Hop summaries preserving names and evidence. First twelve by default; every returned hop with `complete: true`. */
   steps?: string[];
 
   /**
-   * Symbols both ends touch, when no call path runs between them.
+   * Up to four ranked symbols both ends touch, when no call path runs between
+   * them. This diagnostic summary does not change path-search completeness.
    *
    * Nothing calls across the gap because in an event-driven codebase nothing
    * does: a handler registers a listener on an emitter, the emitter's `emit()`
@@ -52,7 +64,18 @@ export interface ITtscGraphTrace {
   candidates?: ITtscGraphTrace.INode[];
 }
 export namespace ITtscGraphTrace {
-  /** A symbol both ends of an unreachable path touch, and how each touches it. */
+  /**
+   * A symbol both ends of an unreachable path touch, and how each touches it.
+   *
+   * @evidence contracts/common.md#principled-implementation A resolved shared node and two directional edge descriptions establish contact, not an execution bridge.
+   * @evidence contracts/common.md#clear-and-simple-design The record pairs each endpoint's relationship with one common symbol coordinate.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Shared references do not become guessed callbacks or synthetic calls.
+   * @evidence contracts/common.md#meaningful-documentation Native members explain stable follow-up identity and which endpoint each edge describes.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IJunction {
     /** Stable node id: trace or inspect this symbol to cross the seam. */
     id: string;
@@ -76,7 +99,18 @@ export namespace ITtscGraphTrace {
     fromTarget: IJunctionEdge;
   }
 
-  /** One edge between an end of the requested path and the junction. */
+  /**
+   * One edge between an end of the requested path and the junction.
+   *
+   * @evidence contracts/common.md#principled-implementation Relation kind and outgoing distinguish endpoint-to-junction from junction-to-endpoint, with optional source evidence.
+   * @evidence contracts/common.md#clear-and-simple-design Three fields retain the direction and cause needed beside an already identified junction.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The relation is the graph edge's kind, not a guessed event-flow label.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain the directional boolean and evidence coordinates beside separate members.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IJunctionEdge {
     /** `calls`, `accesses`, `instantiates`, `type_ref`, ... */
     kind: string;
@@ -88,7 +122,18 @@ export namespace ITtscGraphTrace {
     evidence?: ITtscGraphEvidence;
   }
 
-  /** Where and how far to trace dependency flow. */
+  /**
+   * Where and how far to trace dependency flow.
+   *
+   * @evidence contracts/common.md#principled-implementation Handles, direction, edge family and depth/node bounds specify graph traversal rather than inferring execution from text.
+   * @evidence contracts/common.md#clear-and-simple-design Optional target selects path mode within the same traversal request; orthogonal options govern the inspected population.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts External inclusion and bounds are supported request choices, not agent-specific throttles.
+   * @evidence contracts/common.md#meaningful-documentation Separate member paragraphs explain ambiguity, path preference, direction/focus unions, bounds and defaults.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IRequest {
     /** Discriminator for dependency tracing. */
     type: "trace";
@@ -135,15 +180,34 @@ export namespace ITtscGraphTrace {
     focus?: "all" | "execution" | "types";
 
     /**
-     * Hops deep to follow (open forward/reverse cap at 8, impact at 4, path
-     * mode at 12). Raise it to follow a runtime chain to its end in one call.
+     * Exhaust the finite graph admitted by direction, focus and external-node
+     * policy, including every eligible dispatch relation. Overrides maxDepth,
+     * maxNodes, hop budgets and limits on hop summaries. Path mode returns one shortest path.
+     *
+     * Output and synchronous traversal can grow with the entire graph; there is
+     * no per-request cancellation or fixed response-size bound. Resource or
+     * transport failures fail the request rather than return partial success.
+     *
+     * @default false
+     */
+    complete?: boolean;
+
+    /**
+     * Hops deep to follow. Positive finite values have no upper clamp and are
+     * rounded down; invalid or omitted values use 3 (12 in path mode).
+     * Values below one become one. Ignored with complete true.
      *
      * @default 3
      */
     maxDepth?: number;
 
     /**
-     * Cap on reached nodes (open forward/reverse cap at 32, impact at 16).
+     * Cap on unique reached nodes, excluding the start. Positive finite values
+     * have no upper clamp and are rounded down; invalid or omitted values use
+     * 12. Values below one become one. Open walks also limit hops to twice this
+     * budget and withhold dispatch fanouts of twelve or more implementations.
+     * Use complete true to remove every traversal budget. Path mode ignores
+     * maxNodes.
      *
      * @default 12
      */
@@ -158,7 +222,18 @@ export namespace ITtscGraphTrace {
     includeExternal?: boolean;
   }
 
-  /** One traversed edge, with its depth from the start. */
+  /**
+   * One traversed edge, with its depth from the start.
+   *
+   * @evidence contracts/common.md#principled-implementation Original endpoints and kind preserve the graph edge; depth records traversal distance rather than altering relation identity.
+   * @evidence contracts/common.md#clear-and-simple-design A hop adds depth and optional coordinates without embedding endpoint nodes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Source evidence refers to the actual edge rather than a generated path explanation.
+   * @evidence contracts/common.md#meaningful-documentation Member comments identify depth units and distinguish source and target ids.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IHop {
     /** Source node id for this traversed edge. */
     from: string;
@@ -176,7 +251,18 @@ export namespace ITtscGraphTrace {
     evidence?: ITtscGraphEvidence;
   }
 
-  /** A node on the trace: the start, a reached node, or a candidate. */
+  /**
+   * A node on the trace: the start, a reached node, or a candidate.
+   *
+   * @evidence contracts/common.md#principled-implementation Stable coordinates identify every trace node while optional depth, signature and roles represent facts applicable to particular trace positions.
+   * @evidence contracts/common.md#clear-and-simple-design One coordinate record serves starts, candidates and reached nodes instead of duplicating nearly identical shapes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Candidate identities remain distinct; role text describes graph selection rather than certainty about a user's question.
+   * @evidence contracts/common.md#meaningful-documentation Native comments specify optional facts' contexts and one-based source coordinates with separated member documentation.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface INode {
     /** Stable node id for subsequent graph calls. */
     id: string;
@@ -202,7 +288,7 @@ export namespace ITtscGraphTrace {
     /** The node's signature, carried on path nodes so the path explains itself. */
     signature?: string;
 
-    /** Why this node matters to an impact trace: `exported`, `test`. */
+    /** Why this node matters to an impact trace: `exported` (a compiler fact) or `test` (assigned by the server from a conventional test path, not by the compiler). */
     roles?: string[];
   }
 }

package/src/structures/RawDump.ts

@@ -0,0 +1,25 @@
+import { RawEdge } from "./RawEdge";
+import { RawNode } from "./RawNode";
+
+/**
+ * Minimal graph dump accepted by the pure viewer projection.
+ *
+ * @evidence contracts/common.md#principled-implementation Node and edge arrays carry the complete input population while optional project preserves legacy dump compatibility.
+ * @evidence contracts/common.md#clear-and-simple-design The projection boundary omits provenance validation owned by parseDump and direct producer consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Reduction does not treat this minimal structural type as proof of compiler correctness.
+ * @evidence contracts/common.md#meaningful-documentation Native members explain input populations and optional project label.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface RawDump {
+  /** Project locator or display label, absent on older inputs. */
+  project?: string;
+
+  /** All nodes available before viewer selection. */
+  nodes: RawNode[];
+
+  /** All directed edges before endpoint selection. */
+  edges: RawEdge[];
+}

package/src/structures/RawEdge.ts

@@ -0,0 +1,22 @@
+/**
+ * Directed native relationship before viewer display-family grouping.
+ *
+ * @evidence contracts/common.md#principled-implementation From/to ids and native kind retain relation direction without carrying duplicate node payloads.
+ * @evidence contracts/common.md#clear-and-simple-design Three fields suffice for filtering, degree calculation and display grouping.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Endpoints remain producer identities rather than shortened display-name guesses.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments distinguish directed ids from the ungrouped relationship kind.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface RawEdge {
+  /** Native source node identity. */
+  from: string;
+
+  /** Native target node identity. */
+  to: string;
+
+  /** Producer relationship category before display-family mapping. */
+  kind: string;
+}

package/src/structures/RawNode.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal native node facts consumed by the viewer reduction.
+ *
+ * @evidence contracts/common.md#principled-implementation Stable id and declaration coordinates preserve node identity; optional external/ignored flags permit older dumps without inventing provenance.
+ * @evidence contracts/common.md#clear-and-simple-design The reducer accepts only the wire facts it needs rather than the complete MCP node model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Authored selection uses producer boundary flags instead of named consumer fixtures.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments document portable coordinates and optional producer flags.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface RawNode {
+  /** Position-invariant native identity or a published artifact address. */
+  id: string;
+
+  /** Producer's display name. */
+  name: string;
+
+  /** Native declaration or artifact category. */
+  kind: string;
+
+  /** Portable dump coordinate, or a legacy native path. */
+  file: string;
+
+  /** Dependency-boundary declaration when reported by the producer. */
+  external?: boolean;
+
+  /** Git-ignored generated source when reported by the producer. */
+  ignored?: boolean;
+}

package/src/structures/TtscGraphArtifactNodeKind.ts

@@ -29,6 +29,15 @@ export const TTSC_GRAPH_ARTIFACT_NODE_KINDS = [
  * {@link TtscGraphNodeId} assumes: a Prisma address carries no path because a
  * model name is unique across the schema folder, and an operation has no file
  * at all.
+ *
+ * @evidence contracts/common.md#principled-implementation Membership in the declared artifact-kind vocabulary distinguishes non-TypeScript addresses before symbol-id parsing.
+ * @evidence contracts/common.md#clear-and-simple-design The predicate shares the exported kind list instead of maintaining a second classification switch.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The check concerns semantic kinds, not heuristics about address punctuation or fixture paths.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why artifact identities cannot use the TypeScript id parser.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one includes test over six constant kinds.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation tests a kind name, which is not a path.
  */
 export function isArtifactNodeKind(kind: string): boolean {
   return (TTSC_GRAPH_ARTIFACT_NODE_KINDS as readonly string[]).includes(kind);