@ttsc/graph 0.30.4 → 0.31.0

package/lib/structures/ITtscGraphApplication.d.ts

@@ -16,11 +16,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.
  *
@@ -61,12 +63,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
@@ -89,37 +95,61 @@ 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): Promise<ITtscGraphApplication.IOutput>;
 }
 export declare 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.
+     */
     interface IProps {
         /**
          * The code question, in the user's own words.
@@ -139,29 +169,53 @@ export declare namespace ITtscGraphApplication {
         /** Final graph request chosen after review, or a no-op escape. */
         request: ITtscGraphEntrypoints.IRequest | ITtscGraphLookup.IRequest | ITtscGraphTrace.IRequest | ITtscGraphDetails.IRequest | ITtscGraphOverview.IRequest | ITtscGraphTour.IRequest | 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.
+     */
     interface IDraft {
         /** Why this is the smallest useful next step. */
         reason: string;
         /** The request type being considered. */
         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.
+     */
     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;
         /** What to do with `result`: answer, inspect one named request, or escape. */

package/lib/structures/ITtscGraphDecorator.d.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 {
     /**
@@ -19,6 +28,15 @@ export declare 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.
      */
     interface IArgument {
         /** The statically-resolved literal value, when the argument is a literal. */

package/lib/structures/ITtscGraphDetails.d.ts

@@ -5,6 +5,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. */
@@ -25,7 +34,18 @@ export interface ITtscGraphDetails {
     ambiguous?: ITtscGraphDetails.IAmbiguity[];
 }
 export declare 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.
+     */
     interface IRequest {
         /** Discriminator for selected symbol inspection. */
         type: "details";
@@ -72,14 +92,36 @@ export declare 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.
+     */
     interface IAmbiguity {
         /** The handle as submitted. */
         handle: string;
         /** Every node the handle names, each with the id to re-call `details` on. */
         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.
+     */
     interface ICandidate {
         /** Stable node id: submit this as the handle to select this one. */
         id: string;
@@ -92,7 +134,18 @@ export declare namespace ITtscGraphDetails {
         /** 1-based declaration line, when known. */
         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.
+     */
     interface INode {
         /** Stable node id for subsequent `details` or `trace` calls. */
         id: string;
@@ -151,7 +204,18 @@ export declare namespace ITtscGraphDetails {
         /** Symbols that use this node (incoming dependency edges). */
         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.
+     */
     interface IMember {
         /** Member name, qualified when the graph records an owner-qualified handle. */
         name: string;
@@ -164,7 +228,18 @@ export declare namespace ITtscGraphDetails {
         /** Decorators written on this member, when any. */
         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.
+     */
     interface IReference {
         /** Stable id of the neighboring node. */
         id: string;

package/lib/structures/ITtscGraphDocTag.d.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`. */
@@ -33,10 +42,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/lib/structures/ITtscGraphDump.d.ts

@@ -21,6 +21,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. */
@@ -55,6 +64,15 @@ export declare 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.
      */
     interface IProvenance {
         /**
@@ -69,11 +87,13 @@ export declare 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[];
         /** What built the snapshot. */
@@ -101,6 +121,15 @@ export declare 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.
      */
     interface IProducer {
         /** The producing binary's name, such as `ttscgraph`. */
@@ -119,6 +148,15 @@ export declare 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.
      */
     interface IUniverse {
         /**
@@ -136,14 +174,36 @@ export declare 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.
+     */
     interface IRootFile {
         /** The tsconfig that named this root, in the dump's path vocabulary. */
         config: string;
         /** The root file, in the dump's path vocabulary. */
         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.
+     */
     interface IFileDigest {
         /** In the dump's path vocabulary. */
         file: string;
@@ -158,6 +218,15 @@ export declare 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.
      */
     interface ISourceDigest {
         /** In the dump's path vocabulary. */
@@ -185,7 +254,18 @@ export declare 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.
+     */
     interface IDiagnostic {
         /** In the dump's path vocabulary. */
         file: string;
@@ -208,6 +288,15 @@ export declare 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.
      */
     interface INode extends Omit<ITtscGraphNode, "evidence" | "implementation" | "kind"> {
         /** Node kind written by the native producer. */
@@ -233,6 +322,15 @@ export declare 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.
      */
     interface IEdge extends Omit<ITtscGraphEdge, "evidence" | "kind"> {
         /** Relationship kind written by the native producer. */