@ttsc/graph 0.30.3 → 0.31.0

package/lib/structures/ITtscGraphSnapshot.d.ts

@@ -8,6 +8,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. */
@@ -43,38 +52,115 @@ export interface ITtscGraphSnapshot {
     error?: string;
 }
 export declare 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.
+     */
     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.
+     */
     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.
+     */
     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.
+     */
     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[];
     }
     /**
@@ -86,6 +172,15 @@ export declare 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.
      */
     type Mode = "initial" | "reload" | "unchanged" | "incremental" | "rebuild" | "error";
 }

package/lib/structures/ITtscGraphSpan.d.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/lib/structures/ITtscGraphTour.d.ts

@@ -1,5 +1,16 @@
 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";
@@ -20,8 +31,17 @@ export declare 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.
      */
     interface IRequest {
         /** Discriminator for code-tour indexing. */
@@ -53,8 +73,9 @@ export declare 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
          */
@@ -66,7 +87,18 @@ export declare 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.
+     */
     interface INode {
         /** Stable node id for later graph calls. */
         id: string;
@@ -91,7 +123,18 @@ export declare namespace ITtscGraphTour {
         /** Decorators written on the declaration, when any. */
         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.
+     */
     interface IFlow {
         /** Flow start node. */
         start: ITtscGraphTour.INode;
@@ -117,6 +160,15 @@ export declare 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.
      */
     interface IReached {
         /** Stable node id for later graph calls: `file#Qualified.Name:kind`. */
@@ -126,7 +178,18 @@ export declare namespace ITtscGraphTour {
         /** 1-based declaration line, when known. */
         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.
+     */
     interface IAnchor {
         /** Why this anchor matters in the tour. */
         reason: string;
@@ -143,7 +206,18 @@ export declare namespace ITtscGraphTour {
         /** 1-based end line, when known. */
         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.
+     */
     interface ISpan {
         /** Project-relative file. */
         file: string;

package/lib/structures/ITtscGraphTrace.d.ts

@@ -1,5 +1,16 @@
 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";
@@ -9,9 +20,9 @@ export interface ITtscGraphTrace {
     direction: string;
     /** 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. */
     target?: ITtscGraphTrace.INode;
@@ -20,10 +31,11 @@ export interface ITtscGraphTrace {
      * first, `to` last), empty when `to` is unreachable.
      */
     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()`
@@ -41,7 +53,18 @@ export interface ITtscGraphTrace {
     candidates?: ITtscGraphTrace.INode[];
 }
 export declare 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.
+     */
     interface IJunction {
         /** Stable node id: trace or inspect this symbol to cross the seam. */
         id: string;
@@ -58,7 +81,18 @@ export declare namespace ITtscGraphTrace {
         /** How the target reaches it, or is reached from it. */
         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.
+     */
     interface IJunctionEdge {
         /** `calls`, `accesses`, `instantiates`, `type_ref`, ... */
         kind: string;
@@ -67,7 +101,18 @@ export declare namespace ITtscGraphTrace {
         /** Where the reference sits in source. */
         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.
+     */
     interface IRequest {
         /** Discriminator for dependency tracing. */
         type: "trace";
@@ -109,14 +154,32 @@ export declare 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
          */
@@ -129,7 +192,18 @@ export declare 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.
+     */
     interface IHop {
         /** Source node id for this traversed edge. */
         from: string;
@@ -142,7 +216,18 @@ export declare namespace ITtscGraphTrace {
         /** Source span that produced the hop: citable without opening the file. */
         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.
+     */
     interface INode {
         /** Stable node id for subsequent graph calls. */
         id: string;
@@ -160,7 +245,7 @@ export declare namespace ITtscGraphTrace {
         depth?: number;
         /** 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/lib/structures/RawDump.d.ts

@@ -0,0 +1,22 @@
+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/lib/structures/RawDump.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RawDump.js.map

package/lib/structures/RawDump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RawDump.js","sourceRoot":"","sources":["../../src/structures/RawDump.ts"],"names":[],"mappings":""}

package/lib/structures/RawEdge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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/lib/structures/RawEdge.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RawEdge.js.map

package/lib/structures/RawEdge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RawEdge.js","sourceRoot":"","sources":["../../src/structures/RawEdge.ts"],"names":[],"mappings":""}

package/lib/structures/RawNode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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/lib/structures/RawNode.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RawNode.js.map

package/lib/structures/RawNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RawNode.js","sourceRoot":"","sources":["../../src/structures/RawNode.ts"],"names":[],"mappings":""}

package/lib/structures/TtscGraphArtifactNodeKind.d.ts

@@ -19,5 +19,14 @@ export declare const TTSC_GRAPH_ARTIFACT_NODE_KINDS: readonly ["markdown_documen
  * {@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 declare function isArtifactNodeKind(kind: string): boolean;