@ttsc/graph 0.30.4 → 0.31.0

package/lib/server/pathPolicy.js

@@ -5,7 +5,18 @@ exports.isDeclarationFile = isDeclarationFile;
 exports.isSupportPath = isSupportPath;
 exports.isTestPath = isTestPath;
 exports.isPublicApiNoisePath = isPublicApiNoisePath;
-/** True for dependency declarations outside the authored project graph. */
+/**
+ * True for dependency declarations outside the authored project graph.
+ *
+ * @evidence contracts/common.md#principled-implementation Producer external status, bundled coordinates and node_modules path segments identify dependency boundaries in the graph's portable vocabulary.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate owns external selection for projections.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection follows provenance and dependency coordinates rather than named repositories.
+ * @evidence contracts/common.md#meaningful-documentation The native headline states dependency-boundary meaning; the predicate uses portable graph coordinates rather than native paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one flag read and two string tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 function isExternalNode(node) {
     return (node.external ||
         node.file.startsWith("bundled://") ||
@@ -15,11 +26,34 @@ function isExternalNode(node) {
  * True for a `.d.ts` declaration file. Every declaration such a file holds is
  * ambient by construction, so none of them carries a body the graph can walk
  * into, whether or not the `declare` keyword is written out.
+ *
+ * @evidence contracts/common.md#principled-implementation The declaration-file suffix recognizes d.ts, d.cts and d.mts ambient files under TypeScript's supported filename conventions.
+ * @evidence contracts/common.md#clear-and-simple-design One suffix predicate is reused by body and support-file policies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ambient status is not guessed from fixture names or missing written declare keywords.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains why ambient declarations are bodyless regardless of modifier spelling.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one suffix test on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation tests the suffix of a coordinate string and never touches the filesystem.
  */
 function isDeclarationFile(file) {
     return /\.d\.[cm]?ts$/.test(file);
 }
-/** True for tests, examples, fixtures, generated output, and build artifacts. */
+/**
+ * True for conventional tests, examples, fixtures, generated output and builds.
+ *
+ * This is a projection heuristic over portable graph coordinates, not proof
+ * that a source is generated or a package's manifest classification.
+ *
+ * @evidence contracts/common.md#principled-implementation Segment and suffix conventions select likely support material; declaration-file and dependency checks share the established coordinate vocabulary.
+ * @evidence contracts/common.md#clear-and-simple-design One policy combines conventional support categories for rankers rather than duplicating regexes in each runner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The heuristic uses general path categories and does not hardcode benchmark repositories or expected symbols.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states heuristic status and its provenance limitation rather than certifying generated source from naming.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms a fixed handful of string and pattern tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 function isSupportPath(file) {
     return (file === "" ||
         file.startsWith("bundled://") ||
@@ -30,12 +64,40 @@ function isSupportPath(file) {
         isDeclarationFile(file) ||
         /(^|\/)(dist|build|coverage|generated|__generated__)\//.test(file));
 }
-/** True for source files whose declarations are tests or test helpers. */
+/**
+ * True for conventional test-directory or test/spec-suffixed source paths.
+ *
+ * This identifies likely test anchors by path convention; it does not execute
+ * tests or establish their behavioral coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Complete path segments and TypeScript/JavaScript test suffixes recognize conventional test locations without substring matches on arbitrary names.
+ * @evidence contracts/common.md#clear-and-simple-design The test subset has one predicate separate from the broader support-file policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Returned test anchors follow general conventions rather than an expected benchmark answer list.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains conventional selection and its lack of behavioral verification.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms two pattern tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 function isTestPath(file) {
     return (/(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
         /\.(test|spec)\.[cm]?tsx?$/.test(file));
 }
-/** True when exported symbols are unlikely to be authored public API. */
+/**
+ * True when exported symbols are unlikely to be authored public API.
+ *
+ * Support material, ambient typings and internal directories are selection
+ * signals, not proof that a symbol cannot be imported.
+ *
+ * @evidence contracts/common.md#principled-implementation Shared support selection plus typings/internal conventions identify likely API noise while preserving actual compiler export facts elsewhere.
+ * @evidence contracts/common.md#clear-and-simple-design The API projection adds its own two exclusions to the common support predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Heuristic API visibility does not rewrite the producer's actual export table.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes likely authored API from supported importability.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms a fixed handful of pattern tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 function isPublicApiNoisePath(file) {
     return (isSupportPath(file) ||
         /(^|\/|\.)typings\.[cm]?ts$/.test(file) ||

package/lib/server/pathPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"pathPolicy.js","sourceRoot":"","sources":["../../src/server/pathPolicy.ts"],"names":[],"mappings":";;;;;;;AAEA,2EAA2E;AAC3E,wBAA+B,IAAoB;IACjD,OAAO,CACL,IAAI,CAAC,QAAQ;QACb,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAClC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CACvC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,2BAAkC,IAAY;IAC5C,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,iFAAiF;AACjF,uBAA8B,IAAY;IACxC,OAAO,CACL,IAAI,KAAK,EAAE;QACX,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAC7B,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,mGAAmG,CAAC,IAAI,CACtG,IAAI,CACL;QACD,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC;QACtC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC;QACpC,iBAAiB,CAAC,IAAI,CAAC;QACvB,uDAAuD,CAAC,IAAI,CAAC,IAAI,CAAC,CACnE,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,oBAA2B,IAAY;IACrC,OAAO,CACL,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC;QAChD,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CACvC,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,8BAAqC,IAAY;IAC/C,OAAO,CACL,aAAa,CAAC,IAAI,CAAC;QACnB,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC;QACvC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"pathPolicy.js","sourceRoot":"","sources":["../../src/server/pathPolicy.ts"],"names":[],"mappings":";;;;;;;AAKA;;;;;;;;;;;GAWG;AACH,wBAA+B,IAAoB;IACjD,OAAO,CACL,IAAI,CAAC,QAAQ;QACb,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAClC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,2BAAkC,IAAY;IAC5C,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,uBAA8B,IAAY;IACxC,OAAO,CACL,IAAI,KAAK,EAAE;QACX,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAC7B,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,mGAAmG,CAAC,IAAI,CACtG,IAAI,CACL;QACD,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC;QACtC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC;QACpC,iBAAiB,CAAC,IAAI,CAAC;QACvB,uDAAuD,CAAC,IAAI,CAAC,IAAI,CAAC,CACnE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,oBAA2B,IAAY;IACrC,OAAO,CACL,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC;QAChD,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAqC,IAAY;IAC/C,OAAO,CACL,aAAa,CAAC,IAAI,CAAC;QACnB,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC;QACvC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAC9B,CAAC;AACJ,CAAC"}

package/lib/server/resolveHandle.d.ts

@@ -1,9 +1,5 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
-export interface IResolvedGraphHandle {
-    node?: ITtscGraphNode;
-    candidates?: ITtscGraphNode[];
-}
+import type { IResolvedGraphHandle } from "./IResolvedGraphHandle";
 /**
  * Resolve a tool handle as an id, an exact symbol name, a dotted suffix, or a
  * file-qualified name.
@@ -29,5 +25,14 @@ export interface IResolvedGraphHandle {
  *   method (`db.query`, `app.listen`, `repo.save`), so the member is what it
  *   means, and the candidates come back ranked when several classes declare
  *   it.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact id/name resolution precedes suffix and file/member fallbacks; unique outcomes preserve identity while multiple matches remain candidates.
+ * @evidence contracts/common.md#clear-and-simple-design Resolution helpers each own one handle form and one shared ranker orders ambiguity consistently.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts General handle grammar and compiler export edges guide fallback, not repository-specific expected symbol lists.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe supported stale-id, file-qualified and value-receiver spellings plus preserved ambiguity.
+ * @evidence contracts/performance.md#efficient-algorithms Exact id and symbol probes use generation indexes; a dotted-suffix miss can scan V nodes and collect C matches, while ranking their indexed edge neighborhoods retains the best K in O(CK) time and O(K) additional space for the normal small cap.
+ * @evidence contracts/performance.md#reuse-equivalent-work The graph shares id, symbol and adjacency indexes across handle resolutions; each call ranks a fresh candidate set because the spelling and requested limit can differ.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate lists are request-local and returned to the caller; the resolver retains no history, handle or running task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation looks handles up in in-memory indexes; a path part of an id is matched as text.
  */
 export declare function resolveGraphHandle(graph: TtscGraphMemory, handle: string, candidateLimit?: number): IResolvedGraphHandle;

package/lib/server/resolveHandle.js

@@ -29,6 +29,15 @@ const pathPolicy_1 = require("./pathPolicy");
  *   method (`db.query`, `app.listen`, `repo.save`), so the member is what it
  *   means, and the candidates come back ranked when several classes declare
  *   it.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact id/name resolution precedes suffix and file/member fallbacks; unique outcomes preserve identity while multiple matches remain candidates.
+ * @evidence contracts/common.md#clear-and-simple-design Resolution helpers each own one handle form and one shared ranker orders ambiguity consistently.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts General handle grammar and compiler export edges guide fallback, not repository-specific expected symbol lists.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe supported stale-id, file-qualified and value-receiver spellings plus preserved ambiguity.
+ * @evidence contracts/performance.md#efficient-algorithms Exact id and symbol probes use generation indexes; a dotted-suffix miss can scan V nodes and collect C matches, while ranking their indexed edge neighborhoods retains the best K in O(CK) time and O(K) additional space for the normal small cap.
+ * @evidence contracts/performance.md#reuse-equivalent-work The graph shares id, symbol and adjacency indexes across handle resolutions; each call ranks a fresh candidate set because the spelling and requested limit can differ.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate lists are request-local and returned to the caller; the resolver retains no history, handle or running task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation looks handles up in in-memory indexes; a path part of an id is matched as text.
  */
 function resolveGraphHandle(graph, handle, candidateLimit = 12) {
     const byId = graph.node(handle);
@@ -120,15 +129,38 @@ function fileStem(file) {
 function rank(graph, resolved, candidateLimit) {
     if (resolved.candidates === undefined)
         return resolved;
-    const ranked = resolved.candidates
-        .map((node) => ({ node, score: candidateScore(graph, node) }))
-        .sort((a, b) => {
+    const candidates = resolved.candidates;
+    const cap = Math.trunc(candidateLimit);
+    const compare = (a, b) => {
         const score = b.score - a.score;
         return score !== 0 ? score : compareIdentity(a.node.id, b.node.id);
-    })
-        .slice(0, candidateLimit)
-        .map(({ node }) => node);
-    return { candidates: ranked };
+    };
+    // Large or unusual public caps retain Array.slice semantics; the normal
+    // small cap need not sort every ambiguous declaration in the project.
+    if (!Number.isFinite(cap) || cap < 0 || cap > 32) {
+        return {
+            candidates: candidates
+                .map((node) => ({ node, score: candidateScore(graph, node) }))
+                .sort(compare)
+                .slice(0, candidateLimit)
+                .map(({ node }) => node),
+        };
+    }
+    const ranked = [];
+    for (const node of candidates) {
+        const item = { node, score: candidateScore(graph, node) };
+        const position = ranked.findIndex((other) => compare(item, other) < 0);
+        if (position < 0) {
+            if (ranked.length < cap)
+                ranked.push(item);
+        }
+        else if (position < cap) {
+            ranked.splice(position, 0, item);
+            if (ranked.length > cap)
+                ranked.pop();
+        }
+    }
+    return { candidates: ranked.map(({ node }) => node) };
 }
 /** Compare position-invariant ids without locale-dependent collation. */
 function compareIdentity(left, right) {

package/lib/server/resolveHandle.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveHandle.js","sourceRoot":"","sources":["../../src/server/resolveHandle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolveHandle.js","sourceRoot":"","sources":["../../src/server/resolveHandle.ts"],"names":[],"mappings":"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"}

package/lib/server/resultAudit.d.ts

@@ -37,25 +37,28 @@
  * layer holds no `Program` and no checker, it runs one pure projection over an
  * in-memory `TtscGraphMemory`, and it selects a constant by request type
  * (#818). What is true is stronger than it sounds and is what the text now
- * says: the compiler resolved these facts when the snapshot was built, the
- * graph holds what it resolved, and this result is a projection of exactly
- * those facts that adds none of its own. A reader who checks that claim finds
- * it holds; a reader who checked the old one found a promise the code could not
- * have kept.
+ * says: the compiler resolved these declaration facts when the snapshot was
+ * built, the graph holds what it resolved, and this result is a projection of
+ * them. The text then names what is not the compiler's, because "adds none of
+ * its own" was itself too strong: the memory layer derives `file` nodes,
+ * `contains` ownership and a member's `property` kind, a trace emits
+ * `dispatches` hops, and an artifact node arrives from a lint plugin's parser.
+ * A reader who checks the claim as now written finds it holds; a reader who
+ * checked the old ones found promises the code could not have kept.
  *
  * ## Two guarantees, not one
  *
  * A returned fact and the set it was chosen from are not audited to the same
  * standard, and one audit that conflated them was dishonest. Every operation
- * resolves each fact it returns — a name, a span, an edge, a signature — to the
- * type-checked program, so a returned fact cannot be wrong for the snapshot.
- * But `lookup`, `entrypoints`, and `tour` do not answer with the structure at a
- * handle you named; they match your natural-language question, score and rank
- * the graph against it, cap hits per file, and cut to a limit. Their `score`
- * and `truncated` fields say so, while the single old audit — "matched, ranked,
- * guessed, or inferred: none" — told the reader the opposite in the same
- * payload, and told it to stop where the shortlist's coverage was exactly what
- * needed judging.
+ * resolves each declaration fact it returns — a name, a span, an edge, a
+ * signature — to the type-checked program, so a returned compiler fact cannot
+ * be wrong for the snapshot. But `lookup`, `entrypoints`, and `tour` do not
+ * answer with the structure at a handle you named; they match your
+ * natural-language question, score and rank the graph against it, cap hits per
+ * file, and cut to a limit. Their `score` and `truncated` fields say so, while
+ * the single old audit — "matched, ranked, guessed, or inferred: none" — told
+ * the reader the opposite in the same payload, and told it to stop where the
+ * shortlist's coverage was exactly what needed judging.
  *
  * So the audits split by what the reader must judge. {@link RESULT_AUDIT} covers
  * the walks from an explicit handle or structure (`trace`, `overview`): the

package/lib/server/resultAudit.js

@@ -1,6 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESULT_AUDIT_ESCAPE = exports.RESULT_AUDIT_DETAILS_CAPPED = exports.RESULT_AUDIT_DETAILS = exports.RESULT_AUDIT_SELECTION = exports.RESULT_AUDIT = void 0;
+const TtscGraphArtifactNodeKind_1 = require("../structures/TtscGraphArtifactNodeKind");
+/**
+ * What the audits say about facts the compiler did not resolve.
+ *
+ * The graph holds two kinds of fact that no compiler pass resolved, and an
+ * audit that called every fact compiler-resolved claimed more than this layer
+ * checked. The memory layer derives structure from compiler-owned declarations:
+ * `file` containers, `contains` ownership, a class member's `property` kind, a
+ * `test` role or `tests` anchor chosen by path convention, and, in a trace,
+ * `dispatches` hops built from `overrides` and `implements`. And an artifact
+ * node is published by a lint plugin that parsed a document, a data model, or
+ * an API description in a process of its own, which is exactly what the dump's
+ * `artifactProducer` records. The text names both, and lists the artifact kinds
+ * from the one vocabulary the memory layer classifies by, so a kind added there
+ * cannot be left out of what the audit disclaims.
+ */
+const NOT_COMPILER_RESOLVED = [
+    "The server adds only structure derived from those facts: `file` nodes, `contains` ownership,",
+    "`dispatches` hops, a class member's `property` kind, and the `test` role and `tests` anchors,",
+    "which it assigns from a file's conventional test location rather than from the compiler. A node whose kind is one of",
+    TtscGraphArtifactNodeKind_1.TTSC_GRAPH_ARTIFACT_NODE_KINDS.map((kind) => `\`${kind}\``).join(", ") +
+        " is not",
+    "the compiler's: a lint plugin parsed that artifact in its own process, and the graph returns its",
+    "address, kind, name, and line as that plugin reported them. Nothing else is the server's own,",
+    "so for this snapshot a compiler-resolved fact here cannot disagree with the program.",
+].join("\n");
 /**
  * The audit stamped as the first property of every
  * {@link ITtscGraphApplication.IOutput}. Because it serializes before `result`,
@@ -40,25 +66,28 @@ exports.RESULT_AUDIT_ESCAPE = exports.RESULT_AUDIT_DETAILS_CAPPED = exports.RESU
  * layer holds no `Program` and no checker, it runs one pure projection over an
  * in-memory `TtscGraphMemory`, and it selects a constant by request type
  * (#818). What is true is stronger than it sounds and is what the text now
- * says: the compiler resolved these facts when the snapshot was built, the
- * graph holds what it resolved, and this result is a projection of exactly
- * those facts that adds none of its own. A reader who checks that claim finds
- * it holds; a reader who checked the old one found a promise the code could not
- * have kept.
+ * says: the compiler resolved these declaration facts when the snapshot was
+ * built, the graph holds what it resolved, and this result is a projection of
+ * them. The text then names what is not the compiler's, because "adds none of
+ * its own" was itself too strong: the memory layer derives `file` nodes,
+ * `contains` ownership and a member's `property` kind, a trace emits
+ * `dispatches` hops, and an artifact node arrives from a lint plugin's parser.
+ * A reader who checks the claim as now written finds it holds; a reader who
+ * checked the old ones found promises the code could not have kept.
  *
  * ## Two guarantees, not one
  *
  * A returned fact and the set it was chosen from are not audited to the same
  * standard, and one audit that conflated them was dishonest. Every operation
- * resolves each fact it returns — a name, a span, an edge, a signature — to the
- * type-checked program, so a returned fact cannot be wrong for the snapshot.
- * But `lookup`, `entrypoints`, and `tour` do not answer with the structure at a
- * handle you named; they match your natural-language question, score and rank
- * the graph against it, cap hits per file, and cut to a limit. Their `score`
- * and `truncated` fields say so, while the single old audit — "matched, ranked,
- * guessed, or inferred: none" — told the reader the opposite in the same
- * payload, and told it to stop where the shortlist's coverage was exactly what
- * needed judging.
+ * resolves each declaration fact it returns — a name, a span, an edge, a
+ * signature — to the type-checked program, so a returned compiler fact cannot
+ * be wrong for the snapshot. But `lookup`, `entrypoints`, and `tour` do not
+ * answer with the structure at a handle you named; they match your
+ * natural-language question, score and rank the graph against it, cap hits per
+ * file, and cut to a limit. Their `score` and `truncated` fields say so, while
+ * the single old audit — "matched, ranked, guessed, or inferred: none" — told
+ * the reader the opposite in the same payload, and told it to stop where the
+ * shortlist's coverage was exactly what needed judging.
  *
  * So the audits split by what the reader must judge. {@link RESULT_AUDIT} covers
  * the walks from an explicit handle or structure (`trace`, `overview`): the
@@ -82,10 +111,10 @@ exports.RESULT_AUDIT_ESCAPE = exports.RESULT_AUDIT_DETAILS_CAPPED = exports.RESU
 exports.RESULT_AUDIT = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Every fact in this \`result\` — each name, span, edge, signature, and step — was resolved by
-the TypeScript compiler against the program for the snapshot this call synced to, and the
-graph holds what it resolved. This \`result\` is a projection of exactly those facts and adds
-none of its own, so for this snapshot a fact here cannot disagree with the program.
+Every declaration fact in this \`result\` — each name, span, edge, signature, and step — was
+resolved by the TypeScript compiler against the program for the snapshot this call synced to,
+and the graph holds what it resolved. This \`result\` is a projection of those facts.
+${NOT_COMPILER_RESOLVED}
 
 This is the structure the graph holds for the handles you named, not a shortlist matched
 against a natural-language question. Trust every fact it gives and re-verify none: a returned
@@ -104,11 +133,11 @@ after you edit the source.
 exports.RESULT_AUDIT_SELECTION = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Each fact in this \`result\` — every name, span, edge, and signature — was resolved by the
-TypeScript compiler against the program for the snapshot this call synced to, and the graph
-holds what it resolved. This \`result\` is a projection of exactly those facts and adds none of
-its own, so for this snapshot a fact here cannot disagree with the program: a returned span
-is the citation, not a cue to open the file to confirm it.
+Each declaration fact in this \`result\` — every name, span, edge, and signature — was resolved
+by the TypeScript compiler against the program for the snapshot this call synced to, and the
+graph holds what it resolved. This \`result\` is a projection of those facts.
+${NOT_COMPILER_RESOLVED}
+A returned span is the citation, not a cue to open the file to confirm it.
 
 What was selected is heuristic, not exhaustive. This result was matched against your
 natural-language question, scored and ranked, held to a few hits per file, and cut to a
@@ -138,10 +167,10 @@ Follow \`next\` for where that leaves the question.
 exports.RESULT_AUDIT_DETAILS = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Every fact in this \`result\` — each name, span, edge, signature, member, and value — was
-resolved by the TypeScript compiler against the program for the snapshot this call synced to,
-and the graph holds what it resolved. This \`result\` is a projection of exactly those facts
-and adds none of its own, so for this snapshot a fact here cannot disagree with the program.
+Every declaration fact in this \`result\` — each name, span, edge, signature, member, and value —
+was resolved by the TypeScript compiler against the program for the snapshot this call synced
+to, and the graph holds what it resolved. This \`result\` is a projection of those facts.
+${NOT_COMPILER_RESOLVED}
 
 This is the structure the graph holds for the handles you named. What a symbol is — its
 members, its values, its signature — is complete: trust it and do not open the file to read

package/lib/server/resultAudit.js.map

@@ -1 +1 @@
-{"version":3,"file":"resultAudit.js","sourceRoot":"","sources":["../../src/server/resultAudit.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACU,QAAA,YAAY,GAAW;;;;;;;;;;;;;;;CAenC,CAAC,IAAI,EAAE,CAAC;AAET;;;;;GAKG;AACU,QAAA,sBAAsB,GAAW;;;;;;;;;;;;;;;;;CAiB7C,CAAC,IAAI,EAAE,CAAC;AAET;;;;;;;;;;;;;;;GAeG;AACU,QAAA,oBAAoB,GAAW;;;;;;;;;;;;;;;;;CAiB3C,CAAC,IAAI,EAAE,CAAC;AAET;;;;;;;;;GASG;AACU,QAAA,2BAA2B,GAAW,QAAA,oBAAoB,CAAC,OAAO;AAC7E,2EAA2E;AAC3E,wEAAwE;AACxE,6EAA6E;AAC7E,iEAAiE;AACjE,gDAAgD,EAChD,4FAA4F;IAC1F,0FAA0F;IAC1F,0BAA0B,CAC7B,CAAC;AAEF,mEAAmE;AACtD,QAAA,mBAAmB,GAC9B,8CAA8C,CAAC"}
+{"version":3,"file":"resultAudit.js","sourceRoot":"","sources":["../../src/server/resultAudit.ts"],"names":[],"mappings":";;;AAAA,uFAAyF;AAEzF;;;;;;;;;;;;;;GAcG;AACH,MAAM,qBAAqB,GAAW;IACpC,8FAA8F;IAC9F,+FAA+F;IAC/F,sHAAsH;IACtH,0DAA8B,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACpE,SAAS;IACX,kGAAkG;IAClG,+FAA+F;IAC/F,sFAAsF;CACvF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACU,QAAA,YAAY,GAAW;;;;;;EAMlC,qBAAqB;;;;;;;;;CAStB,CAAC,IAAI,EAAE,CAAC;AAET;;;;;GAKG;AACU,QAAA,sBAAsB,GAAW;;;;;;EAM5C,qBAAqB;;;;;;;;;;;CAWtB,CAAC,IAAI,EAAE,CAAC;AAET;;;;;;;;;;;;;;;GAeG;AACU,QAAA,oBAAoB,GAAW;;;;;;EAM1C,qBAAqB;;;;;;;;;;;CAWtB,CAAC,IAAI,EAAE,CAAC;AAET;;;;;;;;;GASG;AACU,QAAA,2BAA2B,GAAW,QAAA,oBAAoB,CAAC,OAAO;AAC7E,2EAA2E;AAC3E,wEAAwE;AACxE,6EAA6E;AAC7E,iEAAiE;AACjE,gDAAgD,EAChD,4FAA4F;IAC1F,0FAA0F;IAC1F,0BAA0B,CAC7B,CAAC;AAEF,mEAAmE;AACtD,QAAA,mBAAmB,GAC9B,8CAA8C,CAAC"}

package/lib/server/resultNext.d.ts

@@ -1,5 +1,16 @@
 import { ITtscGraphNext } from "../structures/ITtscGraphNext";
-/** A runner's result structure paired with the next-step calibration for it. */
+/**
+ * A runner's result structure paired with the next-step calibration for it.
+ *
+ * @evidence contracts/common.md#principled-implementation The generic result remains its operation's typed shape while next and optional member truncation qualify how it may be used.
+ * @evidence contracts/common.md#clear-and-simple-design Shared control metadata wraps runner-specific facts without copying all result unions here.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Member caps are explicit so audits cannot silently claim completeness after omission.
+ * @evidence contracts/common.md#meaningful-documentation Native member paragraphs explain next guidance and the capped-member audit consequence.
+ * @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 IRunnerOutput<T> {
     /** The graph result structure. */
     result: T;
@@ -11,4 +22,18 @@ export interface IRunnerOutput<T> {
      */
     membersCapped?: boolean;
 }
+/**
+ * Construct a next decision, omitting the request field when none is supplied.
+ *
+ * Callers own the justification for action and any inspect request.
+ *
+ * @evidence contracts/common.md#principled-implementation Typed action/request values retain the supported decision vocabulary and optional-field semantics.
+ * @evidence contracts/common.md#clear-and-simple-design One constructor centralizes omission of absent request metadata without owning runner policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The helper does not infer question intent or add a forced follow-up operation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states caller policy ownership and conditional field omission.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a plain object and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms builds one small object.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure constructor, nothing to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation builds a plain object; no file, path or process.
+ */
 export declare function resultNext(action: ITtscGraphNext["action"], reason: string, request?: ITtscGraphNext["request"]): ITtscGraphNext;

package/lib/server/resultNext.js

@@ -1,6 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resultNext = resultNext;
+/**
+ * Construct a next decision, omitting the request field when none is supplied.
+ *
+ * Callers own the justification for action and any inspect request.
+ *
+ * @evidence contracts/common.md#principled-implementation Typed action/request values retain the supported decision vocabulary and optional-field semantics.
+ * @evidence contracts/common.md#clear-and-simple-design One constructor centralizes omission of absent request metadata without owning runner policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The helper does not infer question intent or add a forced follow-up operation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states caller policy ownership and conditional field omission.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a plain object and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms builds one small object.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure constructor, nothing to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation builds a plain object; no file, path or process.
+ */
 function resultNext(action, reason, request) {
     return {
         action,

package/lib/server/resultNext.js.map

@@ -1 +1 @@
-{"version":3,"file":"resultNext.js","sourceRoot":"","sources":["../../src/server/resultNext.ts"],"names":[],"mappings":";;;AAiBA,oBACE,MAAgC,EAChC,MAAc,EACd,OAAmC;IAEnC,OAAO;QACL,MAAM;QACN,MAAM;QACN,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"resultNext.js","sourceRoot":"","sources":["../../src/server/resultNext.ts"],"names":[],"mappings":";;;AA4BA;;;;;;;;;;;;;GAaG;AACH,oBACE,MAAgC,EAChC,MAAc,EACd,OAAmC;IAEnC,OAAO;QACL,MAAM;QACN,MAAM;QACN,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/lib/server/runDetails.d.ts

@@ -1,18 +1,40 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
 import { ITtscGraphDecorator } from "../structures/ITtscGraphDecorator";
 import { ITtscGraphDetails } from "../structures/ITtscGraphDetails";
 import { ITtscGraphDocTag } from "../structures/ITtscGraphDocTag";
 import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
 import { IRunnerOutput } from "./resultNext";
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
 /**
  * Resolve each handle to its declared shape: sourceSpan anchors, signature,
  * direct dependencies, and for containers, member outlines. It answers from the
  * graph's resolved structure instead of inlining implementation bodies.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolved handles select exact node facts, complete literal/member identities and explicitly bounded relationship slices; ambiguity is returned separately.
+ * @evidence contracts/common.md#clear-and-simple-design Shape, relationship and source-display helpers each own one projection while this function assembles the selected details envelope.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown and ambiguous handles are not converted to guessed declarations; capped members withdraw the corresponding completeness audit.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes declared shape from implementation bodies; helper documentation explains member, reference and citation limits.
+ * @evidence contracts/performance.md#efficient-algorithms Each handle uses the shared resolver, whose dotted-suffix fallback may scan V nodes; resolved relationships inspect D incident edges and retain only K ranked references in O(DK) time and O(K) temporary space, where K is at most four, while member/literal output scales with the declaration's own members.
+ * @evidence contracts/performance.md#reuse-equivalent-work The graph shares generation indexes and source-line adjudications across handles and requests; this call builds fresh caller-owned projections because request limits and selected handles differ.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Detail, ambiguity and unknown arrays live for this request and transfer to its caller; no query history or native handle is retained by this operation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation reads in-memory facts; source lines arrive through graph.source, the reader that owns file access.
  */
 export declare function runDetails(graph: TtscGraphMemory, props: ITtscGraphDetails.IRequest): IRunnerOutput<ITtscGraphDetails>;
-/** Decorator facts already captured on a node, omitted when absent. */
+/**
+ * Decorator facts already captured on a node, omitted when absent or empty.
+ *
+ * @evidence contracts/common.md#principled-implementation The adapter preserves collected decorator order and values while omitting an empty optional facet.
+ * @evidence contracts/common.md#clear-and-simple-design One accessor shares decorator projection across details, lookup and tour consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No framework-specific reinterpretation changes the collected decorator facts.
+ * @evidence contracts/common.md#meaningful-documentation The native headline states collected-fact and empty-facet behavior before the tags.
+ * @evidence contracts/performance.md#efficient-algorithms One pass copies each decorator and its arguments, costing their total population without scanning unrelated graph nodes.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This caller-owned projection performs no cross-request coordination; the graph owns the shared source facts.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned array transfers to its caller and this helper retains no state or handle.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation copies in-memory node fields; no file, path or process.
+ */
 export declare function decoratorsOf(node: ITtscGraphNode): ITtscGraphDecorator[] | undefined;
 /**
  * The declaration's documentation tags, with each text elided at the same
@@ -26,9 +48,29 @@ export declare function decoratorsOf(node: ITtscGraphNode): ITtscGraphDecorator[
  * The optional filter narrows to the tags a caller matched. It runs on the
  * node's own tags, before any elision, so a tag found by an address longer than
  * the budget is still recognized as the one that matched.
+ *
+ * @evidence contracts/common.md#principled-implementation Filtering original tags before eliding preserves matching addresses; the shared leading-token rule keeps whole citation prefixes intact.
+ * @evidence contracts/common.md#clear-and-simple-design One projection helper owns tag selection and display elision for every graph result consumer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Address matches are not re-evaluated against truncated text and long addresses are never cut into another target.
+ * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain the display budget, protected address and filter-before-elision ordering.
+ * @evidence contracts/performance.md#efficient-algorithms Filtering and mapping visit the node's tags once each; elision examines the leading address and copies at most the needed display prefix.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Selection depends on a caller predicate and returns a fresh mutable projection; this helper coordinates no reusable result.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The selected and returned arrays are request-local and no historical tags are retained here.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation copies and elides in-memory tag text; no file, path or process.
+ */
+export declare function docTagsOf(node: ITtscGraphNode, keep?: (tag: TtscGraphReadonly<ITtscGraphDocTag>) => boolean): ITtscGraphDocTag[] | undefined;
+/**
+ * Relationship evidence as public coordinates, omitted when absent.
+ *
+ * @evidence contracts/common.md#principled-implementation Copying the actual edge span preserves file and optional endpoints without inferring missing coordinates.
+ * @evidence contracts/common.md#clear-and-simple-design One coordinate mapper is shared by graph runners and node implementation evidence.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing source evidence stays absent rather than being replaced with the caller's declaration span.
+ * @evidence contracts/common.md#meaningful-documentation The native headline explains public-coordinate projection and absent evidence behavior.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Copying a fixed set of optional coordinates chooses no input-dependent processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This fixed-size projection coordinates no cross-request computation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned value transfers to its caller without a retained handle or cache.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation copies span coordinates of an in-memory edge; no file, path or process.
  */
-export declare function docTagsOf(node: ITtscGraphNode, keep?: (tag: ITtscGraphDocTag) => boolean): ITtscGraphDocTag[] | undefined;
-/** Relationship evidence as public coordinates, omitted when absent. */
 export declare function edgeEvidenceOf(edge: ITtscGraphEdge): ITtscGraphEvidence | undefined;
 /**
  * What the declaration says it is: the first sentence of the doc comment
@@ -41,18 +83,33 @@ export declare function edgeEvidenceOf(edge: ITtscGraphEdge): ITtscGraphEvidence
  * sentence above the declaration, and the compiler carries it. It is the
  * declaration's documentation, not the body of the work: an index that lists a
  * symbol with what it is for is doing an index's job.
+ *
+ * @evidence contracts/common.md#principled-implementation Provenance-gated lines are scanned immediately above the declaration for JSDoc prose, stopping before tags and returning its first sentence.
+ * @evidence contracts/common.md#clear-and-simple-design This helper owns a short documentation projection; the source reader owns immutable generation validation and caching.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing or mismatched source yields absence rather than an inferred purpose from names or implementation text.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain first-sentence purpose and distinguish declaration prose from implementation bodies.
+ * @evidence contracts/performance.md#efficient-algorithms The source reader supplies indexed, cached lines; this helper scans only the adjacent comment and joins its prose, costing the comment's lines and characters.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Source-byte validation and line splitting are shared by the reader; this pure projection does not coordinate a separate result cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Comment and prose arrays are local to this call and no history or handle is retained.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation reads lines through graph.source, the reader that owns file access, and adds none of its own.
  */
 export declare function docOf(graph: TtscGraphMemory, node: ITtscGraphNode): string | undefined;
 /**
- * The declaration signature: the head of the declaration up to and including
- * the line that opens its body (`{`), or the single declaration line when there
- * is no brace, capped so a wrapped signature cannot run away.
- *
- * It never runs past the declaration's own span. The stop used to be the brace,
- * the trailing semicolon, or the line cap, and a declaration ending in none of
- * them read its neighbors instead: an enum member ends in a comma, so `VIEW`
- * came back as itself plus the two members after it and the closing brace. The
- * span is the fact that says where the declaration ends, and it was already on
- * the node.
+ * The producer's compiler-bounded declaration head, limited to display lines.
+ *
+ * Without a producer signature, return undefined. Physical lines cannot
+ * establish where a declaration head ends: a body may share its line and a
+ * parameter or return type may itself contain braces. The source span remains
+ * available when a caller needs to read the declaration.
+ *
+ * @evidence contracts/common.md#principled-implementation Only the AST-bounded producer head establishes a declaration-only signature; limiting its lines preserves that established boundary.
+ * @evidence contracts/common.md#clear-and-simple-design The producer owns declaration syntax boundaries and this helper owns display length, with no second partial TypeScript parser.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing heads are not repaired by a line-scan heuristic that can leak implementation or neighboring declarations.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the producer requirement, missing-head absence and source-span escape path.
+ * @evidence contracts/performance.md#efficient-algorithms Splitting the producer head and selecting its first display lines costs the supplied signature's length; no source file or graph traversal occurs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The producer head is already shared on the graph node, while this display projection coordinates no repeated work.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The capped text is caller-owned and this helper retains no cache or native resource.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation cuts the producer's signature text to a few lines; no file, path or process.
  */
-export declare function signatureOf(graph: TtscGraphMemory, node: ITtscGraphNode): string | undefined;
+export declare function signatureOf(_graph: TtscGraphMemory, node: ITtscGraphNode): string | undefined;
+export {};