@ttsc/graph 0.30.4 → 0.31.1

package/src/structures/ITtscGraphApplication.ts

@@ -17,11 +17,13 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  * type relations. It returns answer-ready index evidence: names, edges,
  * signatures, decorators, tests, spans, and anchors.
  *
- * Every returned fact — each name, edge, signature, and span — is
- * compiler-resolved and verified for the snapshot that call synchronized, so
- * trust it without re-checking against files. Where an operation ranks a
- * shortlist against your question (`lookup`, `entrypoints`, `tour`), the facts
- * stay verified but the selection is heuristic: judge whether its coverage
+ * Declaration facts come from the compiler for the synchronized snapshot.
+ * The server derives file containers, containment, property kinds, path-convention test roles and dispatch
+ * hops; lint plugins supply artifact facts. The result's audit distinguishes
+ * these producers. Trust compiler facts without re-checking against files.
+ * Where an operation ranks a shortlist against your question (`lookup`,
+ * `entrypoints`, `tour`), its compiler facts retain that provenance while
+ * selection is heuristic: judge whether its coverage
  * answers you, and a follow-up request or a read of a cited span is fair when
  * it does not.
  *
@@ -62,12 +64,16 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  *
  * ## What to trust
  *
- * Before source edits, every returned fact is compiler-resolved and verified.
- * Never use extra graph calls, repository search, or file reads to doubt,
+ * Before source edits, compiler declaration facts retain the resolution of the
+ * synchronized snapshot. The server derives `file` containers, `contains`
+ * ownership, `property` kinds, `dispatches` hops and path-convention `test`
+ * roles from those declarations. Lint plugins supply document, data-model and API-operation facts; `audit`
+ * identifies these distinct producers. Never use extra graph calls,
+ * repository search, or file reads to doubt,
  * fact-check, re-derive, re-narrate, or re-confirm a returned node, span, edge,
- * signature, decorator, test, reference, step, or anchor. The server resolved
- * each one to the type-checked program for the snapshot the call synced to, and
- * `audit` says so on every result.
+ * signature, decorator, test, reference, step, or anchor. The result projects
+ * the snapshot's facts and identifies their provenance; this server does not
+ * perform a second compiler verification pass.
  *
  * Selection is the separate question. `lookup`, `entrypoints`, and `tour` match
  * your question and return a scored, ranked, per-file-capped, limited
@@ -90,32 +96,45 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  *   `truncated` say whether coverage is settled; when it is not, one more
  *   request is the right move — not a file read to re-verify facts already
  *   given.
+ *
+ * @evidence contracts/common.md#principled-implementation The single async tool maps the discriminated request union to graph outputs, with audit and next separated from returned facts.
+ * @evidence contracts/common.md#clear-and-simple-design One tool owns graph dispatch; request branches keep their own shapes instead of independent nearly identical tools.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The instruction retains explicit escape and permits legitimate coverage follow-ups without forced graph calls.
+ * @evidence contracts/common.md#meaningful-documentation Markdown-structured native documentation explains request choice, trust boundaries and ranked coverage before the tags.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources signature only: the implementer owns any handle or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms signature only: the implementer owns the algorithm and its cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work signature only: the implementer decides what work is shared.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation signature only: the implementer owns any path or process work.
  */
 export interface ITtscGraphApplication {
   /**
-   * Answer a TypeScript question from the compiler's own index of this
-   * repository.
-   *
-   * The graph holds every symbol, call, type, decorator and test, each with its
-   * file and line, resolved from the source on disk now. Submit exactly one
-   * request:
+   * Answer a TypeScript question from the synchronized source snapshot.
+   * Submit one request:
    *
-   * - `tour`: architecture, the runtime flow from the public API to the code that
-   *   does the work, nearby paths, and the tests to read — a whole orientation
-   *   in one call
-   * - `trace`: what a symbol calls, what calls it, or the path from A to B
-   * - `details`: signatures, members, and what implements an interface
-   * - `lookup`: where a named symbol is declared
-   * - `entrypoints`: where execution starts, when the entry is unknown
-   * - `overview`: the project's layers and folder structure
+   * - `tour`: architecture, runtime flow and nearby tests in one orientation
+   * - `trace`: calls, callers or the path from A to B
+   * - `details`: signatures, members and interface implementations
+   * - `lookup`: named declarations
+   * - `entrypoints`: where execution starts
+   * - `overview`: project layers and folders
+   * - `escape`: source bodies, span text or evidence outside the graph
    *
-   * Every fact in a result is the checker's own resolution, audited before
-   * return, so no fact needs verifying; for the ranked operations (`lookup`,
-   * `entrypoints`, `tour`), judge whether the shortlist covers your question.
-   * Read a file for what the graph does not carry: a body, the text in a span.
+   * `audit` identifies compiler declaration facts, server-derived structure
+   * and plugin artifact facts; it does not claim a second compiler check.
+   * Judge the coverage of ranked `lookup`, `entrypoints` and `tour` shortlists.
+   * Follow `next`; read source for omitted body text or missed coverage.
    *
    * @param props Reasoning plus one graph request
    * @returns Matching `result` union member
+   *
+   * @evidence contracts/common.md#principled-implementation The callable consumes the typed reasoning/request envelope and returns the typed audit, next action and result envelope asynchronously.
+   * @evidence contracts/common.md#clear-and-simple-design One method delegates branch semantics to the request union instead of duplicating parameter lists.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported method includes escape and does not require graph use for source bodies.
+   * @evidence contracts/common.md#meaningful-documentation Native prose lists request responsibilities, distinguishes ranking coverage and explains the body-text boundary with param/return tags.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources signature only: the implementer owns any handle or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms signature only: the implementer owns the algorithm and its cost.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work signature only: the implementer decides what work is shared.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation signature only: the implementer owns any path or process work.
    */
   inspect_typescript_graph(
     props: ITtscGraphApplication.IProps,
@@ -123,7 +142,18 @@ export interface ITtscGraphApplication {
 }
 
 export namespace ITtscGraphApplication {
-  /** Draft, review, then submit exactly one graph request or escape. */
+  /**
+   * Draft, review, then submit exactly one graph request or escape.
+   *
+   * @evidence contracts/common.md#principled-implementation Required question, draft, review and discriminated final request represent the public selection protocol without treating rationale as graph evidence.
+   * @evidence contracts/common.md#clear-and-simple-design The final request union owns branch-specific fields; shared selection context is stored once.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Escape remains in the union and question wording is not replaced by a hidden repository-specific prompt.
+   * @evidence contracts/common.md#meaningful-documentation Native member comments explain question preservation, draft correction and one final branch.
+   * @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 IProps {
     /**
      * The code question, in the user's own words.
@@ -154,7 +184,18 @@ export namespace ITtscGraphApplication {
       | ITtscGraphEscape.IRequest;
   }
 
-  /** First-pass plan; `reason` precedes `type` so it is written first. */
+  /**
+   * First-pass plan; `reason` precedes `type` so it is written first.
+   *
+   * @evidence contracts/common.md#principled-implementation Reason explains selection while the request-indexed type union restricts the proposed operation to a supported branch.
+   * @evidence contracts/common.md#clear-and-simple-design Two fields represent the draft without copying branch inputs before review.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The proposed operation remains caller-authored rather than a forced first call.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain the selection reason and proposed request type in separate member blocks.
+   * @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 IDraft {
     /** Why this is the smallest useful next step. */
     reason: string;
@@ -163,22 +204,35 @@ export namespace ITtscGraphApplication {
     type: IProps["request"]["type"];
   }
 
-  /** The selected request's output. `result.type` mirrors `request.type`. */
+  /**
+   * The selected request's output. `result.type` mirrors `request.type`.
+   *
+   * @evidence contracts/common.md#principled-implementation Audit, next decision and discriminated result preserve different roles: provenance report, supported follow-up and graph facts.
+   * @evidence contracts/common.md#clear-and-simple-design Shared audit/control fields wrap the existing result branches without duplicating their contents.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Ranked selection is explicitly heuristic and cannot be certified complete merely by valid node facts.
+   * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain operation-aware audit and ranked coverage; member comments define next and matching result branch.
+   * @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 IOutput {
     /**
-     * What the server audited this result against before returning it, in its
-     * own words: every node, span, edge, signature, member, and step in it
-     * resolves to the type-checked program for the snapshot the call synced to,
-     * so opening a file it cites only returns a fact already in it.
+     * The provenance and coverage of the returned projection. Compiler facts
+     * belong to the synchronized program; file containers, containment,
+     * property kinds, path-convention test roles and dispatch hops are server-derived structure. Artifact
+     * facts come from the publishing lint plugin. This text reports those
+     * origins without claiming a second compiler verification pass.
      *
      * 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.
+     * 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/ITtscGraphDecorator.ts

@@ -4,6 +4,15 @@
  * per framework: `name` is the decorator as written (`Controller`, `Get`,
  * `TypedRoute.Get`, ...), and statically resolvable literal arguments are
  * preserved so a consumer applies its own meaning without re-parsing source.
+ *
+ * @evidence contracts/common.md#principled-implementation The written name and literal arguments represent syntax without inventing framework semantics.
+ * @evidence contracts/common.md#clear-and-simple-design Name and ordered arguments are the complete decorator envelope; argument details have their own record.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No framework-specific decorator names are encoded as special cases.
+ * @evidence contracts/common.md#meaningful-documentation Native comments distinguish written names, source ordering and statically resolvable arguments in separate paragraphs.
+ * @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 ITtscGraphDecorator {
   /**
@@ -20,6 +29,15 @@ export namespace ITtscGraphDecorator {
    * One argument of an {@link ITtscGraphDecorator}. `literal` is set only when
    * the argument is a string, number, or boolean literal the producer could
    * resolve statically, so a consumer can use it without evaluating code.
+   *
+   * @evidence contracts/common.md#principled-implementation The primitive union represents resolved literals; absence represents an argument that cannot be resolved statically.
+   * @evidence contracts/common.md#clear-and-simple-design One optional value carries the argument fact without embedding expression bodies.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The representation does not evaluate an argument or substitute a guessed value.
+   * @evidence contracts/common.md#meaningful-documentation The argument comment explains absence and the literal-only boundary, with a blank line before acknowledgment tags.
+   * @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 IArgument {
     /** The statically-resolved literal value, when the argument is a literal. */

package/src/structures/ITtscGraphDetails.ts

@@ -6,6 +6,15 @@ import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
  * Source-free facts for a few selected handles, not a file reader: signatures,
  * member outlines, direct calls and types, implementation candidates,
  * dependency summaries, and sourceSpan citation anchors.
+ *
+ * @evidence contracts/common.md#principled-implementation Nodes, unknown handles and ambiguity records distinguish resolved declaration facts from unresolved or multiply resolved inputs.
+ * @evidence contracts/common.md#clear-and-simple-design The envelope keeps resolution status outside each node's declaration shape.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ambiguous names retain candidates instead of selecting a convenient declaration.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain source-free details and why ambiguity requires exact 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 ITtscGraphDetails {
   /** Discriminator for selected symbol inspection. */
@@ -29,7 +38,18 @@ export interface ITtscGraphDetails {
   ambiguous?: ITtscGraphDetails.IAmbiguity[];
 }
 export namespace ITtscGraphDetails {
-  /** Which selected handles to inspect, and how much of each to return. */
+  /**
+   * Which selected handles to inspect, and how much of each to return.
+   *
+   * @evidence contracts/common.md#principled-implementation Handles identify declarations while independent limits select member, dependency and optional neighbor projections.
+   * @evidence contracts/common.md#clear-and-simple-design One request groups projection options around the handles they inspect.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Limits are documented caller choices; complete members are the default rather than a hidden sample.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain default bounds, external inclusion and when trace should replace a wider details request.
+   * @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 selected symbol inspection. */
     type: "details";
@@ -83,7 +103,18 @@ export namespace ITtscGraphDetails {
     includeExternal?: boolean;
   }
 
-  /** One handle and the several nodes it names. */
+  /**
+   * One handle and the several nodes it names.
+   *
+   * @evidence contracts/common.md#principled-implementation Submitted handle and candidate list preserve the exact ambiguous resolution outcome.
+   * @evidence contracts/common.md#clear-and-simple-design Two fields keep the unresolved choice separate from inspected node facts.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No candidate is promoted to a resolved node solely to avoid clarification.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain submitted spelling and candidate ids for a follow-up selection.
+   * @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 IAmbiguity {
     /** The handle as submitted. */
     handle: string;
@@ -92,7 +123,18 @@ export namespace ITtscGraphDetails {
     candidates: ICandidate[];
   }
 
-  /** One node a handle could mean: enough to choose, not to answer from. */
+  /**
+   * One node a handle could mean: enough to choose, not to answer from.
+   *
+   * @evidence contracts/common.md#principled-implementation Stable id and declaration coordinates distinguish same-named candidates without claiming their bodies were inspected.
+   * @evidence contracts/common.md#clear-and-simple-design Only disambiguation facts are carried rather than a full details payload.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Candidate names do not replace exact identity when selecting one declaration.
+   * @evidence contracts/common.md#meaningful-documentation Comments state follow-up id usage, qualified names and optional one-based line.
+   * @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 ICandidate {
     /** Stable node id: submit this as the handle to select this one. */
     id: string;
@@ -110,7 +152,18 @@ export namespace ITtscGraphDetails {
     line?: number;
   }
 
-  /** One inspected node: its declared shape and graph coordinates. */
+  /**
+   * One inspected node: its declared shape and graph coordinates.
+   *
+   * @evidence contracts/common.md#principled-implementation Optional shape, relationships and literal values preserve distinct checker facts alongside stable identity and declaration coordinates.
+   * @evidence contracts/common.md#clear-and-simple-design Independent optional facets support the same node without embedding bodies or a second graph snapshot.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Documentation tags remain reported claims, and missing literal enumeration stays absent rather than guessed from signatures.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain complete literals and members versus sliced relationships, tag interpretation limits and implementation coordinates.
+   * @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 `details` or `trace` calls. */
     id: string;
@@ -187,7 +240,18 @@ export namespace ITtscGraphDetails {
     dependedOnBy?: IReference[];
   }
 
-  /** One member of a container node, with its signature but not its body. */
+  /**
+   * One member of a container node, with its signature but not its body.
+   *
+   * @evidence contracts/common.md#principled-implementation Name, kind and optional declaration facts express a container outline without evaluating a member's implementation.
+   * @evidence contracts/common.md#clear-and-simple-design The outline omits relationships and bodies owned by deeper node inspection.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional signature and decorators are available source facts rather than synthesized member content.
+   * @evidence contracts/common.md#meaningful-documentation Comments distinguish qualified member names, one-based lines and declaration signatures.
+   * @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 IMember {
     /** Member name, qualified when the graph records an owner-qualified handle. */
     name: string;
@@ -205,7 +269,18 @@ export namespace ITtscGraphDetails {
     decorators?: ITtscGraphDecorator[];
   }
 
-  /** A dependency neighbor of an inspected node and the edge that links them. */
+  /**
+   * A dependency neighbor of an inspected node and the edge that links them.
+   *
+   * @evidence contracts/common.md#principled-implementation Neighbor coordinates, relationship kind and optional edge span represent the resolved adjacency and its grounding.
+   * @evidence contracts/common.md#clear-and-simple-design Node presentation and relation cause share one compact record without repeating source bodies.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A source span is citation evidence, not an invented instruction to verify the graph's fact.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain stable handles, relation kinds and evidence as coordinates rather than file-read cues.
+   * @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 IReference {
     /** Stable id of the neighboring node. */
     id: string;

package/src/structures/ITtscGraphDocTag.ts

@@ -22,10 +22,19 @@
  * The parser also decides where a tag begins, and that decision is reported
  * rather than second-guessed. TypeScript opens a tag at an `@` wherever it sits
  * inside a documentation block, so a tag name written mid-sentence arrives here
- * as a tag, while a `//` comment is not documentation and contributes nothing at
- * all. A convention that wants the stricter rule enforces it in its own linter,
- * where the author gets a diagnostic; the graph reports what the compiler
- * parsed.
+ * as a tag, while a `//` comment is not documentation and contributes nothing
+ * at all. A convention that wants the stricter rule enforces it in its own
+ * linter, where the author gets a diagnostic; the graph reports what the
+ * compiler parsed.
+ *
+ * @evidence contracts/common.md#principled-implementation Name and optional text preserve the compiler-parsed custom tag without asserting target resolution or truth.
+ * @evidence contracts/common.md#clear-and-simple-design Parsing authority remains with the compiler; the record carries only its two reported facts.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No tag-name allowlist or consumer-specific reinterpretation replaces compiler parsing.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain unknown tags, unresolved targets, inline links and absent text rather than repeating field types.
+ * @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 ITtscGraphDocTag {
   /** The tag name without its `@`: `evidence`, `evidenceExclude`, `reference`. */
@@ -34,10 +43,10 @@ export interface ITtscGraphDocTag {
   /**
    * Everything written after the tag name, joined into one line.
    *
-   * An inline link keeps the braced form it was written in (`{@link ISale}`),
-   * so a consumer matching a citation target sees what the author typed. The
-   * same link is separately a resolved edge on the node, which is what says
-   * *which* `ISale` — a name can be declared twice and only the checker knows.
+   * An inline link keeps the braced form it was written in (`{@link ISale}`), so
+   * a consumer matching a citation target sees what the author typed. The same
+   * link is separately a resolved edge on the node, which is what says _which_
+   * `ISale` — a name can be declared twice and only the checker knows.
    *
    * Absent when the tag carries no text.
    */

package/src/structures/ITtscGraphDump.ts

@@ -22,6 +22,15 @@ import { TtscGraphDumpNodeKind } from "./TtscGraphDumpNodeKind";
  * and a virtual compiler source stays `bundled:///…`. Raw absolute identities
  * are never emitted. A source on another drive or UNC share makes the producer
  * fail unless a future contract supplies a logical root for it.
+ *
+ * @evidence contracts/common.md#principled-implementation Provenance, diagnostics and complete node/edge arrays represent one producer generation with explicit portable identity coordinates.
+ * @evidence contracts/common.md#clear-and-simple-design The wire envelope separates origin and build universe from graph facts; span paths are reconstructed by the loader.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Native output is the full graph rather than a fixture-specific capped subset.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain producer/consumer roles, generation ownership and the portable path vocabulary.
+ * @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 ITtscGraphDump {
   /** Absolute path of the project root the graph was built for. */
@@ -62,6 +71,15 @@ export namespace ITtscGraphDump {
    * 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.
+   *
+   * @evidence contracts/common.md#principled-implementation Schema, producer, universe and source digests ground one snapshot; separate artifact producer identifies facts outside its Program.
+   * @evidence contracts/common.md#clear-and-simple-design Capabilities distinguish absent evidence from collected-empty evidence without version-specific field guesses.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown capabilities remain permitted rather than rejecting a newer producer by a hardcoded list.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain digest evidence, independent versions, capability extensibility and the second producer's scope.
+   * @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 IProvenance {
     /**
@@ -77,11 +95,13 @@ export namespace ITtscGraphDump {
      * uncollected one look identical on the wire.
      *
      * The known members are `universe`, `sourceDigests`, `diskDigests`,
-     * `diagnostics`, and `docTags`. 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.
+     * `diagnostics`, `docTags`, and `artifactNodes`, which the producer lists
+     * only when it asked the project's configured plugins for artifact nodes.
+     * 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[];
 
@@ -114,6 +134,15 @@ export namespace ITtscGraphDump {
    * 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.
+   *
+   * @evidence contracts/common.md#principled-implementation Tool, build version and TypeScript version identify distinct producer facts without conflating their version schemes.
+   * @evidence contracts/common.md#clear-and-simple-design Three textual coordinates are sufficient for provenance and permit unversioned producer builds.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Empty build version remains an explicit supported producer state, not a fabricated release number.
+   * @evidence contracts/common.md#meaningful-documentation Comments explain dev placeholders, unversioned tools and the checker version independently.
+   * @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 IProducer {
     /** The producing binary's name, such as `ttscgraph`. */
@@ -135,6 +164,15 @@ export namespace ITtscGraphDump {
    * 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.
+   *
+   * @evidence contracts/common.md#principled-implementation Config digests and attributed roots represent the inputs deciding Program membership independently of source contents.
+   * @evidence contracts/common.md#clear-and-simple-design Two collections separate configuration content from root attribution instead of duplicating whole sources.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing configured root remains part of the universe rather than disappearing from invalidation evidence.
+   * @evidence contracts/common.md#meaningful-documentation Native documentation explains why compiler options and currently missing roots remain build inputs.
+   * @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 IUniverse {
     /**
@@ -154,7 +192,18 @@ export namespace ITtscGraphDump {
     roots: IRootFile[];
   }
 
-  /** A root file attributed to the config that named it. */
+  /**
+   * A root file attributed to the config that named it.
+   *
+   * @evidence contracts/common.md#principled-implementation Config and file form the attribution pair, permitting one root to be named by multiple configurations.
+   * @evidence contracts/common.md#clear-and-simple-design Two portable coordinates express attribution without repeating config content.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Root identity is not collapsed to a basename or guessed project owner.
+   * @evidence contracts/common.md#meaningful-documentation Both member comments specify the dump path vocabulary and config ownership.
+   * @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 IRootFile {
     /** The tsconfig that named this root, in the dump's path vocabulary. */
     config: string;
@@ -163,7 +212,18 @@ export namespace ITtscGraphDump {
     file: string;
   }
 
-  /** A file and the hex-encoded SHA-256 of its on-disk bytes. */
+  /**
+   * A file and the hex-encoded SHA-256 of its on-disk bytes.
+   *
+   * @evidence contracts/common.md#principled-implementation The file coordinate pairs with a content digest, distinguishing byte identity from file timestamps.
+   * @evidence contracts/common.md#clear-and-simple-design One path and digest carry exactly the input witness needed by the build universe.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The contract names content hashing rather than treating size or quiet watchers as content identity.
+   * @evidence contracts/common.md#meaningful-documentation Native comments identify path vocabulary and hexadecimal SHA-256 encoding.
+   * @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 IFileDigest {
     /** In the dump's path vocabulary. */
     file: string;
@@ -180,6 +240,15 @@ export namespace ITtscGraphDump {
    * 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.
+   *
+   * @evidence contracts/common.md#principled-implementation Separate checker and disk digests preserve the distinction between transformed compiler text and raw source bytes.
+   * @evidence contracts/common.md#clear-and-simple-design The manifest retains only file and two witnesses, leaving source text outside the wire protocol.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing raw bytes are an empty witness; augmented source does not receive a fabricated disk-equivalence claim.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain preamble divergence, capability gating and empty-digest 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 ISourceDigest {
     /** In the dump's path vocabulary. */
@@ -210,7 +279,18 @@ export namespace ITtscGraphDump {
     diskDigest: string;
   }
 
-  /** One compiler diagnostic from the generation that produced the facts. */
+  /**
+   * One compiler diagnostic from the generation that produced the facts.
+   *
+   * @evidence contracts/common.md#principled-implementation Coordinates, compiler code, severity and message describe the actual finding for the same graph generation.
+   * @evidence contracts/common.md#clear-and-simple-design A self-contained diagnostic record avoids parsing codes and severity from prose.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Diagnostic categories are explicit wire values, not inferred from expected test output.
+   * @evidence contracts/common.md#meaningful-documentation Native comments document one-based coordinates, diagnostic code and message without its code prefix.
+   * @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 IDiagnostic {
     /** In the dump's path vocabulary. */
     file: string;
@@ -239,6 +319,15 @@ export namespace ITtscGraphDump {
    * span was the same string a second time, once per node. It is the reader's
    * to reconstruct, and {@link TtscGraphMemory} does, so nothing downstream of
    * the loader sees a span without its file.
+   *
+   * @evidence contracts/common.md#principled-implementation Omit replaces memory-layer span and kind fields with native wire equivalents; parent applies only to published artifact containment.
+   * @evidence contracts/common.md#clear-and-simple-design Shared node facts are inherited while repeated declaration paths are removed from wire spans.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Implementation spans may retain another file; they are not forced into declaration coordinates for compactness.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain reconstruction, artifact parent ownership and cross-file implementation spans.
+   * @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 extends Omit<
     ITtscGraphNode,
@@ -271,6 +360,15 @@ export namespace ITtscGraphDump {
    * An edge as the builder sends it. Its span is in the file its `from` id
    * names — the id is `path#Qualified.Name:kind` — so the path rode the wire a
    * second time on every edge, and edges outnumber nodes several times over.
+   *
+   * @evidence contracts/common.md#principled-implementation Native kind and compact span replace memory fields while endpoint ids determine the expression's source file.
+   * @evidence contracts/common.md#clear-and-simple-design Omit reuses relation fields and avoids repeating the source path inside each wire edge.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Compression preserves endpoint identity and actual evidence rather than shortening ids heuristically.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain id-based path reconstruction and the producer's relationship vocabulary.
+   * @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 IEdge extends Omit<ITtscGraphEdge, "evidence" | "kind"> {
     /** Relationship kind written by the native producer. */