@ttsc/graph 0.30.4 → 0.31.0

package/src/structures/ITtscGraphEdge.ts

@@ -4,8 +4,20 @@ import { TtscGraphEdgeKind } from "./TtscGraphEdgeKind";
 /**
  * A directed relationship between two {@link ITtscGraphNode}s, both named by
  * `id`. The triple `(from, to, kind)` is unique; a repeat keeps the first
- * source-order evidence. Every edge is compiler-resolved, so there is no
- * per-edge trust flag: the whole graph is checker-resolved fact.
+ * source-order evidence. Every edge between declarations is compiler-resolved,
+ * apart from the `contains` ownership the memory layer derives and the
+ * trace-only `dispatches` hop, and an artifact node's `contains` parent is the
+ * one its publishing plugin named. There is no per-edge trust flag: `kind` says
+ * which of these an edge is.
+ *
+ * @evidence contracts/common.md#principled-implementation Directed endpoint identities and a relation kind express a resolved edge; optional evidence supplies coordinates without changing identity.
+ * @evidence contracts/common.md#clear-and-simple-design One record separates relation identity from its source span, with no duplicated node payload.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Relation kinds come from the shared vocabulary rather than fixture-specific relationships.
+ * @evidence contracts/common.md#meaningful-documentation Native documentation states edge uniqueness and first-source evidence semantics; member comments are visibly separated.
+ * @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 ITtscGraphEdge {
   /** Node id the relationship originates from. */

package/src/structures/ITtscGraphEntrypoints.ts

@@ -1,7 +1,18 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
 
-/** The first compact source-free handle list for a TypeScript code question. */
+/**
+ * The first compact source-free handle list for a TypeScript code question.
+ *
+ * @evidence contracts/common.md#principled-implementation Hits, explicit mentions and neighborhoods distinguish ranked selection from handle resolution and direct relationships.
+ * @evidence contracts/common.md#clear-and-simple-design The three collections share compact node records instead of inlining source or another request shape.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The result exposes truncation rather than representing a capped shortlist as complete.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments distinguish ranking, explicit mentions and capped context with separated 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 ITtscGraphEntrypoints {
   /** Discriminator for first-pass question indexing. */
   type: "entrypoints";
@@ -23,6 +34,15 @@ export namespace ITtscGraphEntrypoints {
   /**
    * First handles when the question is narrow but the symbol name is not yet
    * known.
+   *
+   * @evidence contracts/common.md#principled-implementation Query plus optional hit and neighbor limits specify first-pass indexing without requiring an already resolved symbol.
+   * @evidence contracts/common.md#clear-and-simple-design Two bounds control different result populations; the query remains the sole search input.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Bounds are caller-visible result options, not hidden agent throttling.
+   * @evidence contracts/common.md#meaningful-documentation Field comments explain the question input, limit defaults and when deeper tools should replace a wider list.
+   * @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 first-pass question indexing. */
@@ -52,7 +72,18 @@ export namespace ITtscGraphEntrypoints {
     neighbors?: number;
   }
 
-  /** A compact symbol coordinate, optionally with its declaration signature. */
+  /**
+   * A compact symbol coordinate, optionally with its declaration signature.
+   *
+   * @evidence contracts/common.md#principled-implementation Stable identity and source coordinates represent a symbol; optional signature and decorators preserve available declaration facts.
+   * @evidence contracts/common.md#clear-and-simple-design Shared node coordinates avoid duplicating the same shape across hits and neighborhoods.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Optional facts remain absent when unavailable rather than becoming fabricated declarations.
+   * @evidence contracts/common.md#meaningful-documentation Native comments state stable handles, one-based lines and signature availability beside separated members.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface INode {
     /** Stable node id for subsequent graph calls. */
     id: string;
@@ -76,13 +107,35 @@ export namespace ITtscGraphEntrypoints {
     decorators?: ITtscGraphDecorator[];
   }
 
-  /** One ranked search hit. */
+  /**
+   * One ranked search hit.
+   *
+   * @evidence contracts/common.md#principled-implementation Extending the node coordinate with a relative score separates relevance from resolved identity.
+   * @evidence contracts/common.md#clear-and-simple-design Inheritance adds only the fact unique to a ranked hit.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts A score reports ranking, not proof that this declaration answers the question.
+   * @evidence contracts/common.md#meaningful-documentation The score comment states its direction and relative meaning without implying confidence.
+   * @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 IHit extends INode {
     /** Relative relevance; higher is a better match. */
     score: number;
   }
 
-  /** A code handle written in the query, with its resolution status. */
+  /**
+   * A code handle written in the query, with its resolution status.
+   *
+   * @evidence contracts/common.md#principled-implementation The original handle and optional node or candidates distinguish successful and ambiguous resolution.
+   * @evidence contracts/common.md#clear-and-simple-design One mention record keeps submitted text beside its resolution instead of mixing it into scored hits.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Ambiguous names carry candidates rather than a guessed winner.
+   * @evidence contracts/common.md#meaningful-documentation The native comments explain the original spelling and unambiguous versus ambiguous outcomes.
+   * @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 IMention {
     /** The exact handle text found in the query. */
     handle: string;
@@ -94,7 +147,18 @@ export namespace ITtscGraphEntrypoints {
     candidates?: INode[];
   }
 
-  /** Direct dependency context around one indexed symbol. */
+  /**
+   * Direct dependency context around one indexed symbol.
+   *
+   * @evidence contracts/common.md#principled-implementation Separate outgoing and incoming lists preserve relationship direction around the indexed node.
+   * @evidence contracts/common.md#clear-and-simple-design Extending the compact node adds only its two context lists.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The lists represent direct capped context rather than inventing transitive paths.
+   * @evidence contracts/common.md#meaningful-documentation Each list documents its direction and the neighbor bound, with a blank line between members.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface INeighborhood extends INode {
     /** Symbols this node directly uses, capped by `neighbors`. */
     dependsOn: IReference[];
@@ -103,7 +167,18 @@ export namespace ITtscGraphEntrypoints {
     dependedOnBy: IReference[];
   }
 
-  /** One neighboring symbol and the relationship leading to it. */
+  /**
+   * One neighboring symbol and the relationship leading to it.
+   *
+   * @evidence contracts/common.md#principled-implementation Neighbor identity, relation kind and optional source span represent one resolved dependency without losing its cause.
+   * @evidence contracts/common.md#clear-and-simple-design Coordinates and relation are kept together so callers need no second node lookup to display context.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Evidence reports the actual reference rather than substituting a matching name.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain stable handles, coordinate units and edge evidence without source bodies.
+   * @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/ITtscGraphEscape.ts

@@ -1,4 +1,15 @@
-/** The no-op result for when graph is not the useful next evidence source. */
+/**
+ * The no-op result for when graph is not the useful next evidence source.
+ *
+ * @evidence contracts/common.md#principled-implementation Literal escape and skipped discriminators distinguish an intentional no-op from an empty graph answer.
+ * @evidence contracts/common.md#clear-and-simple-design The reason and optional next step explain the no-op without carrying graph state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Escape is an explicit caller choice, not a hidden suppression of legitimate graph requests.
+ * @evidence contracts/common.md#meaningful-documentation Field comments explain the no-op and optional follow-up; prose and tags have a blank separator.
+ * @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 ITtscGraphEscape {
   /** Discriminator for the no-op escape route. */
   type: "escape";
@@ -14,7 +25,18 @@ export interface ITtscGraphEscape {
 }
 
 export namespace ITtscGraphEscape {
-  /** Skip graph work when graph evidence is unnecessary or exhausted. */
+  /**
+   * Skip graph work when graph evidence is unnecessary or exhausted.
+   *
+   * @evidence contracts/common.md#principled-implementation The escape discriminator selects a no-op and requires the caller's reason rather than implying a graph finding.
+   * @evidence contracts/common.md#clear-and-simple-design Only the reason and optional next step are needed for the escape boundary.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The branch provides a supported escape without caps, cooldowns or forced graph use.
+   * @evidence contracts/common.md#meaningful-documentation Native comments identify non-graph evidence and explain when source spans justify reading a body.
+   * @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 the no-op escape route. */
     type: "escape";

package/src/structures/ITtscGraphEvidence.ts

@@ -4,6 +4,15 @@
  * grounding only, never identity (a node's id is position-invariant, see
  * {@link ITtscGraphNode}). Lines and columns are 1-based; MCP keeps evidence as
  * coordinates, so read the file yourself when you truly need source text.
+ *
+ * @evidence contracts/common.md#principled-implementation File plus one-based coordinates identify a source location while optional end coordinates express incomplete ranges.
+ * @evidence contracts/common.md#clear-and-simple-design The record carries coordinates only; node identity and source content remain outside this responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Positions are display evidence, never a substitute for stable symbol identity.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explicitly state coordinate units, optional endpoints and the distinction between grounding and identity.
+ * @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 ITtscGraphEvidence {
   /** Project-relative path of the file the span lives in. */

package/src/structures/ITtscGraphLookup.ts

@@ -1,7 +1,18 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphDocTag } from "./ITtscGraphDocTag";
 
-/** Targeted symbol lookup when a concrete name or handle is being resolved. */
+/**
+ * Targeted symbol lookup when a concrete name or handle is being resolved.
+ *
+ * @evidence contracts/common.md#principled-implementation A literal lookup discriminator and ranked hits represent targeted search while truncation records omitted matches.
+ * @evidence contracts/common.md#clear-and-simple-design The envelope carries one collection and its completeness indication, leaving search inputs in the request.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The omission flag prevents a bounded exact-citation match from masquerading as exhaustive coverage.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain why truncation matters for documentation targets; member blocks remain separated.
+ * @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 ITtscGraphLookup {
   /** Discriminator for targeted symbol lookup. */
   type: "lookup";
@@ -12,18 +23,29 @@ export interface ITtscGraphLookup {
   /**
    * True when a match was left out by the limit.
    *
-   * The audit for the ranked operations already tells a reader that
-   * `truncated` marks where more was left out, and this result had no such
-   * field — so a cut looked exactly like a complete answer. That is tolerable
-   * for a name query, where the ranking is a shortlist by design, and it is not
-   * for a documentation target: those hits are an exact match on an address, so
-   * a caller asking which code implements a specification is owed the fact that
+   * The audit for the ranked operations already tells a reader that `truncated`
+   * marks where more was left out, and this result had no such field — so a cut
+   * looked exactly like a complete answer. That is tolerable for a name query,
+   * where the ranking is a shortlist by design, and it is not for a
+   * documentation target: those hits are an exact match on an address, so a
+   * caller asking which code implements a specification is owed the fact that
    * it did not get all of it.
    */
   truncated?: boolean;
 }
 export namespace ITtscGraphLookup {
-  /** Find a concrete class, method, function, property, type, or dotted handle. */
+  /**
+   * Find a concrete class, method, function, property, type, or dotted handle.
+   *
+   * @evidence contracts/common.md#principled-implementation Query supports symbol search and exact documentation addresses; optional limits and external inclusion express the search boundary.
+   * @evidence contracts/common.md#clear-and-simple-design One query owns lookup semantics rather than introducing separate redundant search APIs.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Address spelling is supplied by the caller, with no repository-specific citation shortcuts.
+   * @evidence contracts/common.md#meaningful-documentation Separate paragraphs describe name lookup, citation lookup, limits and external declarations with their defaults.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+   */
   export interface IRequest {
     /** Discriminator for targeted symbol lookup. */
     type: "lookup";
@@ -62,7 +84,18 @@ export namespace ITtscGraphLookup {
     includeExternal?: boolean;
   }
 
-  /** One ranked hit with a handle to follow via `details` or `trace`. */
+  /**
+   * One ranked hit with a handle to follow via `details` or `trace`.
+   *
+   * @evidence contracts/common.md#principled-implementation Resolved coordinates and optional declaration facts ground the hit; relative score describes selection and tags explain citation matches.
+   * @evidence contracts/common.md#clear-and-simple-design A compact record combines display facts and follow-up identity without source bodies.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Matching tags are reported as written rather than certified as true or resolved specifications.
+   * @evidence contracts/common.md#meaningful-documentation Member comments explain optional tags, one-based lines and relative score separately.
+   * @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 IHit {
     /** Stable node id for subsequent graph calls. */
     id: string;

package/src/structures/ITtscGraphNext.ts

@@ -1,4 +1,15 @@
-/** What to do with a compiler-derived graph result. */
+/**
+ * What to do with a compiler-derived graph result.
+ *
+ * @evidence contracts/common.md#principled-implementation The action union represents the supported next decisions, with request identifying the operation for inspect.
+ * @evidence contracts/common.md#clear-and-simple-design Action, optional request and reason separate control choice from its explanation in one small record.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts This vocabulary carries a result decision without encoding agent-specific control hacks.
+ * @evidence contracts/common.md#meaningful-documentation The action comment describes each decision and the inspect request's conditional meaning using native member documentation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
 export interface ITtscGraphNext {
   /**
    * What to do with this result:

package/src/structures/ITtscGraphNode.ts

@@ -11,6 +11,15 @@ import { TtscGraphNodeModifier } from "./TtscGraphNodeModifier";
  * `src/order.ts#OrderService.create:method`), so inserting a line above a
  * declaration does not re-key it. Line and span live in `evidence` and are
  * never part of identity.
+ *
+ * @evidence contracts/common.md#principled-implementation Stable ids separate declaration identity from movable source positions; optional fields retain only facts the producer collected.
+ * @evidence contracts/common.md#clear-and-simple-design One node record groups identity, declaration shape and grounding while artifact parent and native flags remain optional facets.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Dynamic object members and non-enumerable types receive no fabricated outline or sampled literal set.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain stable identity, optional capability-backed facts and source-versus-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 ITtscGraphNode {
   /** Position-invariant identity (see the interface doc for the id grammar). */
@@ -123,8 +132,8 @@ export interface ITtscGraphNode {
    * interprets without re-parsing source.
    *
    * This is where a declaration says what outside the type system it answers
-   * to, and it is the only place the graph holds it: the other end of such a
-   * relation is a document section or an API operation, which is not a node.
+   * to. A plugin may also publish an artifact node for that target; the raw tag
+   * remains a declaration fact independently of whether such a node exists.
    *
    * Read it only when `provenance.capabilities` lists `docTags`. Without that
    * claim the field is absent because the producer never looked, which is a
@@ -136,13 +145,9 @@ export interface ITtscGraphNode {
    * The declaration head, cut by the producer where the compiler says the body
    * opens.
    *
-   * Absent when the producer could not bound the head, in which case a consumer
-   * falls back to reading the declaration span. That fallback is a line scan,
-   * and a physical line is not a declaration boundary: it leaks implementation
-   * text when a declaration shares its line with its body, and it stops early
-   * when the head itself contains a brace — a type-literal parameter, an object
-   * return type, a destructured parameter. Prefer this field wherever it is
-   * present.
+   * Absent when the producer could not bound the head. Consumers omit the
+   * signature rather than infer it from a physical line, which may contain an
+   * implementation body or only part of a multiline declaration head.
    */
   signature?: string;
 
@@ -156,7 +161,18 @@ export interface ITtscGraphNode {
   implementation?: ITtscGraphEvidence;
 }
 export namespace ITtscGraphNode {
-  /** One member of an enum: the name a caller writes and the value it carries. */
+  /**
+   * One member of an enum: the name a caller writes and the value it carries.
+   *
+   * @evidence contracts/common.md#principled-implementation Required name and optional folded value preserve computed enum members whose names remain known when values do not.
+   * @evidence contracts/common.md#clear-and-simple-design Two fields retain the callable spelling and value without minting a separate member node.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Unfoldable values remain absent rather than receiving expected literals.
+   * @evidence contracts/common.md#meaningful-documentation Native comments explain unqualified names and TypeScript source spelling of optional constants.
+   * @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 IEnumMember {
     /** The member's own name, unqualified (`Red` on `Colors.Red`). */
     name: string;
@@ -169,7 +185,18 @@ export namespace ITtscGraphNode {
     value?: string;
   }
 
-  /** One direct, statically named member of an object-literal variable. */
+  /**
+   * One direct, statically named member of an object-literal variable.
+   *
+   * @evidence contracts/common.md#principled-implementation Static name, data/callable kind and optional coordinates express a source-visible member rather than dynamic runtime keys.
+   * @evidence contracts/common.md#clear-and-simple-design The outline stores only declaration presentation; relationships remain on graph nodes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Spreads and unresolved computed names do not acquire invented member identities.
+   * @evidence contracts/common.md#meaningful-documentation Comments document the property/method distinction, one-based line and compiler-snapshot signature.
+   * @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 IObjectMember {
     /** The source-visible static property name. */
     name: string;

package/src/structures/ITtscGraphOverview.ts

@@ -1,4 +1,15 @@
-/** A compact, source-read-free project map for broad orientation only. */
+/**
+ * A compact, source-read-free project map for broad orientation only.
+ *
+ * @evidence contracts/common.md#principled-implementation Counts and optional facet collections describe graph structure without claiming runtime behavior.
+ * @evidence contracts/common.md#clear-and-simple-design The envelope separates totals from layers, dependency hotspots and public API projections.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Facets carry graph observations rather than repository-name-based architecture guesses.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments describe each facet's ordering and the absolute project locator.
+ * @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 ITtscGraphOverview {
   /** Discriminator for source-free project overview. */
   type: "overview";
@@ -19,7 +30,18 @@ export interface ITtscGraphOverview {
   publicApi?: ITtscGraphOverview.IPublicApi[];
 }
 export namespace ITtscGraphOverview {
-  /** Which broad architecture facets `overview` should return. */
+  /**
+   * Which broad architecture facets `overview` should return.
+   *
+   * @evidence contracts/common.md#principled-implementation The aspect union names exactly the supported structural projections and all selects their combination.
+   * @evidence contracts/common.md#clear-and-simple-design One optional selector replaces independent flags for the same mutually selectable facets.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The request explicitly selects orientation; it does not rewrite a runtime-flow question into an overview.
+   * @evidence contracts/common.md#meaningful-documentation The aspect comment states default behavior and explains which questions need other operations.
+   * @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 source-free project overview. */
     type: "overview";
@@ -40,7 +62,18 @@ export namespace ITtscGraphOverview {
     aspect?: "all" | "layers" | "hotspots" | "publicApi";
   }
 
-  /** Size of the graph by node/edge totals and per-kind node counts. */
+  /**
+   * Size of the graph by node/edge totals and per-kind node counts.
+   *
+   * @evidence contracts/common.md#principled-implementation Separate totals distinguish source containers, all nodes and all edges while the keyed record preserves per-kind counts.
+   * @evidence contracts/common.md#clear-and-simple-design Four aggregate fields carry counts without retaining the counted graph entries.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Counts include their documented structural populations rather than selected fixture totals.
+   * @evidence contracts/common.md#meaningful-documentation Comments explain which containers and structural edges contribute to each total.
+   * @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 ICounts {
     /** Number of source file container nodes. */
     files: number;
@@ -55,34 +88,74 @@ export namespace ITtscGraphOverview {
     byKind: Record<string, number>;
   }
 
-  /** One folder layer: its source files and export surface. */
+  /**
+   * One folder layer: its source files and export surface.
+   *
+   * @evidence contracts/common.md#principled-implementation A directory coordinate and distinct file/export counts represent a structural layer without inferring architectural intent.
+   * @evidence contracts/common.md#clear-and-simple-design Only the directory and its two aggregate populations are retained.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Folder names are coordinates, not hardcoded semantic layer classifications.
+   * @evidence contracts/common.md#meaningful-documentation Comments state project-relative directory spelling and what each count includes.
+   * @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 ILayer {
     /** Directory, project-relative. */
     dir: string;
+
     /** Distinct source files under it. */
     files: number;
+
     /** Exported symbols declared under it. */
     exported: number;
   }
 
-  /** A compact symbol coordinate that can be passed to deeper graph tools. */
+  /**
+   * A compact symbol coordinate that can be passed to deeper graph tools.
+   *
+   * @evidence contracts/common.md#principled-implementation Identity, name, kind and coordinates express a graph symbol while unknown line remains optional.
+   * @evidence contracts/common.md#clear-and-simple-design The common coordinate is reused by hotspots and public API entries without embedded implementation text.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The record keeps stable identity instead of guessing a symbol from its display name.
+   * @evidence contracts/common.md#meaningful-documentation Member comments identify stable follow-up handles, qualified names and one-based lines.
+   * @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 handle for `details` or `trace`. */
     id: string;
+
     /** The symbol's qualified name when available. */
     name: string;
+
     /** Its declaration kind (`class`, `interface`, `function`, ...). */
     kind: string;
+
     /** Project-relative path of the file that declares it. */
     file: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
   }
 
-  /** A high-dependency symbol with its non-structural fan-in and fan-out. */
+  /**
+   * A high-dependency symbol with its non-structural fan-in and fan-out.
+   *
+   * @evidence contracts/common.md#principled-implementation Directional non-structural edge counts express dependency connectivity instead of counting containment as usage.
+   * @evidence contracts/common.md#clear-and-simple-design Extending the common node adds only incoming and outgoing counts.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Connectivity is reported as graph structure, not a fixture-specific importance verdict.
+   * @evidence contracts/common.md#meaningful-documentation The type and member comments explicitly distinguish non-structural fan-in and fan-out.
+   * @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 IHotspot extends INode {
     /** Non-structural edges pointing at this symbol. */
     fanIn: number;
+
     /** Non-structural edges leaving this symbol. */
     fanOut: number;
   }
@@ -90,6 +163,15 @@ export namespace ITtscGraphOverview {
   /**
    * One exported public-API symbol. The list is ranked by how depended-on the
    * symbol is, excluding test, typings, and generated files.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias uses the same coordinate representation because public API membership changes selection, not node shape.
+   * @evidence contracts/common.md#clear-and-simple-design A type alias avoids duplicating the identical INode record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection exclusions concern source provenance, not named downstream projects.
+   * @evidence contracts/common.md#meaningful-documentation The native paragraph explains ranking and excluded populations rather than restating the alias.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
    */
   export type IPublicApi = INode;
 }