@ttsc/graph 0.30.4 → 0.31.0

package/lib/server/createServer.js

@@ -49,38 +49,42 @@ const TtscGraphApplication_1 = require("../TtscGraphApplication");
  * input and output schemas and its argument validator, with no hand-written
  * schema: the interface's JSDoc becomes the handshake instructions, the
  * method's becomes the tool description, and every property's becomes the
- * description of that field — including `audit`, whose JSDoc is how a caller
- * learns what the server checked before it answered.
+ * description of that field — including `audit`, whose JSDoc explains fact
+ * provenance and coverage without claiming a second compiler check.
  *
- * The registration was hand-written here for a while, because a tool that
- * declares an output schema must answer with `structuredContent` and the helper
- * also serialized the same JSON into a text block: the payload crossed the wire
- * twice, a client counted both copies against its tool-result cap, and a 30 KB
- * tour arrived as 60 KB, blew the cap, and was spilled to a file the model then
- * shelled out to read back. `@typia/mcp` 13.1.0 ships the structured result
- * once (samchon/typia#2020), so the hand-written server had nothing left to fix
- * and the library owns the registration again.
+ * The library owns registration and sends structured results once by default.
+ * Its version option identifies this graph server in the handshake without
+ * changing SDK internals after construction.
+ *
+ * @evidence contracts/common.md#principled-implementation The typed controller supplies reflected schemas and executor dispatch; the supported version option sets the MCP implementation identity at construction.
+ * @evidence contracts/common.md#clear-and-simple-design The integration delegates registration and result serialization to the library instead of maintaining another transport implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Handshake version uses the public createMcpServer option; no SDK private field or foreign method is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain schema/JSDoc reflection, structured-result ownership and public version configuration.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a server whose transport lifetime startServer owns.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms builds the MCP server once from the typia controller, with no loop of its own.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work called once per process; the schema reflection happens at compile time.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation creates an in-memory MCP server object; startServer attaches the stdio transport.
  */
 function createServer(graph, version) {
-    const server = (0, mcp_1.createMcpServer)({
+    return (0, mcp_1.createMcpServer)({
         "protocol": "class",
         "name": "ttsc-graph",
         "execute": new TtscGraphApplication_1.TtscGraphApplication(graph),
         "application": _llmApplicationFinalize_1._llmApplicationFinalize({
-            description: "## Code Graph MCP\n\n`inspect_typescript_graph` returns a compiler-built TypeScript graph contract\nfor the current on-disk source snapshot.\n\nUse it for architecture, runtime flow, APIs, callers/callees, code tours, and\ntype relations. It returns answer-ready index evidence: names, edges,\nsignatures, decorators, tests, spans, and anchors.\n\nEvery returned fact \u2014 each name, edge, signature, and span \u2014 is\ncompiler-resolved and verified for the snapshot that call synchronized, so\ntrust it without re-checking against files. Where an operation ranks a\nshortlist against your question (`lookup`, `entrypoints`, `tour`), the facts\nstay verified but the selection is heuristic: judge whether its coverage\nanswers you, and a follow-up request or a read of a cited span is fair when\nit does not.\n\n## Requests\n\nA request is a union: pick the single type below that best fits the question,\nand submit exactly that one.\n\n- `tour`: architecture, runtime flow, orientation, or a code tour. One call is\n  the whole answer; do not split it. Name the machinery you expect it to be\n  made of in its `reinterpretations`, or send none.\n- `entrypoints`: find where execution starts when entry points are unknown.\n- `lookup`: locate a named symbol, or \u2014 with a documentation target as the\n  query (`docs/pricing.md#sale`, `POST:/orders`) \u2014 the declarations whose\n  documentation cites it.\n- `trace`: follow calls or data flow forward or backward from a symbol, or \u2014\n  with `to` \u2014 the path between two symbols when both ends are known, which is\n  the one call that answers \"how does A reach B\".\n- `details`: signatures, members, and relations of named symbols \u2014 including\n  the classes that implement an interface, which is the one call that answers\n  \"what actually implements this\".\n- `overview`: project layers and folder structure.\n- `escape`: the answer is outside the graph (source body text, non-TypeScript\n  files, exact search).\n\n## Chain of Thought\n\nFill these fields in order before the call; each one narrows the reasoning\ntoward the single request you submit.\n\n- `question`: the code question, in the user's own words.\n- `draft`: `{ reason, type }` \u2014 why the smallest request that could answer it,\n  then that request's `type`.\n- `review`: fix a broad, stale, or duplicate draft. If the graph already\n  answered, or the evidence is outside it, escape.\n- `request`: the final choice. Each branch documents its own fields; fill them\n  from what the branch says, not from what another branch wanted.\n\n## What to trust\n\nBefore source edits, every returned fact is compiler-resolved and verified.\nNever use extra graph calls, repository search, or file reads to doubt,\nfact-check, re-derive, re-narrate, or re-confirm a returned node, span, edge,\nsignature, decorator, test, reference, step, or anchor. The server resolved\neach one to the type-checked program for the snapshot the call synced to, and\n`audit` says so on every result.\n\nSelection is the separate question. `lookup`, `entrypoints`, and `tour` match\nyour question and return a scored, ranked, per-file-capped, limited\nshortlist; their facts are still verified, but whether the shortlist covers\nwhat you asked is yours to judge, and their `audit` says that instead of\nclaiming completeness. A follow-up request or a read of a cited span for\nmissed coverage is legitimate \u2014 re-confirming a fact the graph already\nresolved is not.\n\n## Stop\n\nLet the result's `next` set the pace, and do not re-confirm what the graph\nresolved.\n\n- A span is a citation, not a cue to open the file to re-check a fact.\n- Follow the result's `next`: `answer` means stop and answer from it, `inspect`\n  means make exactly the one request it names, `outside` means escape,\n  `clarify` means restate the request.\n- For a ranked shortlist (`lookup`, `entrypoints`, `tour`), `next` and\n  `truncated` say whether coverage is settled; when it is not, one more\n  request is the right move \u2014 not a file read to re-verify facts already\n  given.",
+            description: "## Code Graph MCP\n\n`inspect_typescript_graph` returns a compiler-built TypeScript graph contract\nfor the current on-disk source snapshot.\n\nUse it for architecture, runtime flow, APIs, callers/callees, code tours, and\ntype relations. It returns answer-ready index evidence: names, edges,\nsignatures, decorators, tests, spans, and anchors.\n\nDeclaration facts come from the compiler for the synchronized snapshot.\nThe server derives file containers, containment, property kinds, path-convention test roles and dispatch\nhops; lint plugins supply artifact facts. The result's audit distinguishes\nthese producers. Trust compiler facts without re-checking against files.\nWhere an operation ranks a shortlist against your question (`lookup`,\n`entrypoints`, `tour`), its compiler facts retain that provenance while\nselection is heuristic: judge whether its coverage\nanswers you, and a follow-up request or a read of a cited span is fair when\nit does not.\n\n## Requests\n\nA request is a union: pick the single type below that best fits the question,\nand submit exactly that one.\n\n- `tour`: architecture, runtime flow, orientation, or a code tour. One call is\n  the whole answer; do not split it. Name the machinery you expect it to be\n  made of in its `reinterpretations`, or send none.\n- `entrypoints`: find where execution starts when entry points are unknown.\n- `lookup`: locate a named symbol, or \u2014 with a documentation target as the\n  query (`docs/pricing.md#sale`, `POST:/orders`) \u2014 the declarations whose\n  documentation cites it.\n- `trace`: follow calls or data flow forward or backward from a symbol, or \u2014\n  with `to` \u2014 the path between two symbols when both ends are known, which is\n  the one call that answers \"how does A reach B\".\n- `details`: signatures, members, and relations of named symbols \u2014 including\n  the classes that implement an interface, which is the one call that answers\n  \"what actually implements this\".\n- `overview`: project layers and folder structure.\n- `escape`: the answer is outside the graph (source body text, non-TypeScript\n  files, exact search).\n\n## Chain of Thought\n\nFill these fields in order before the call; each one narrows the reasoning\ntoward the single request you submit.\n\n- `question`: the code question, in the user's own words.\n- `draft`: `{ reason, type }` \u2014 why the smallest request that could answer it,\n  then that request's `type`.\n- `review`: fix a broad, stale, or duplicate draft. If the graph already\n  answered, or the evidence is outside it, escape.\n- `request`: the final choice. Each branch documents its own fields; fill them\n  from what the branch says, not from what another branch wanted.\n\n## What to trust\n\nBefore source edits, compiler declaration facts retain the resolution of the\nsynchronized snapshot. The server derives `file` containers, `contains`\nownership, `property` kinds, `dispatches` hops and path-convention `test`\nroles from those declarations. Lint plugins supply document, data-model and API-operation facts; `audit`\nidentifies these distinct producers. Never use extra graph calls,\nrepository search, or file reads to doubt,\nfact-check, re-derive, re-narrate, or re-confirm a returned node, span, edge,\nsignature, decorator, test, reference, step, or anchor. The result projects\nthe snapshot's facts and identifies their provenance; this server does not\nperform a second compiler verification pass.\n\nSelection is the separate question. `lookup`, `entrypoints`, and `tour` match\nyour question and return a scored, ranked, per-file-capped, limited\nshortlist; their facts are still verified, but whether the shortlist covers\nwhat you asked is yours to judge, and their `audit` says that instead of\nclaiming completeness. A follow-up request or a read of a cited span for\nmissed coverage is legitimate \u2014 re-confirming a fact the graph already\nresolved is not.\n\n## Stop\n\nLet the result's `next` set the pace, and do not re-confirm what the graph\nresolved.\n\n- A span is a citation, not a cue to open the file to re-check a fact.\n- Follow the result's `next`: `answer` means stop and answer from it, `inspect`\n  means make exactly the one request it names, `outside` means escape,\n  `clarify` means restate the request.\n- For a ranked shortlist (`lookup`, `entrypoints`, `tour`), `next` and\n  `truncated` say whether coverage is settled; when it is not, one more\n  request is the right move \u2014 not a file read to re-verify facts already\n  given.",
             config: {
                 strict: false
             },
             functions: [
                 {
-                    description: "Answer a TypeScript question from the compiler's own index of this\nrepository.\n\nThe graph holds every symbol, call, type, decorator and test, each with its\nfile and line, resolved from the source on disk now. Submit exactly one\nrequest:\n\n- `tour`: architecture, the runtime flow from the public API to the code that\n  does the work, nearby paths, and the tests to read \u2014 a whole orientation\n  in one call\n- `trace`: what a symbol calls, what calls it, or the path from A to B\n- `details`: signatures, members, and what implements an interface\n- `lookup`: where a named symbol is declared\n- `entrypoints`: where execution starts, when the entry is unknown\n- `overview`: the project's layers and folder structure\n\nEvery fact in a result is the checker's own resolution, audited before\nreturn, so no fact needs verifying; for the ranked operations (`lookup`,\n`entrypoints`, `tour`), judge whether the shortlist covers your question.\nRead a file for what the graph does not carry: a body, the text in a span.",
+                    description: "Answer a TypeScript question from the synchronized source snapshot.\nSubmit one request:\n\n- `tour`: architecture, runtime flow and nearby tests in one orientation\n- `trace`: calls, callers or the path from A to B\n- `details`: signatures, members and interface implementations\n- `lookup`: named declarations\n- `entrypoints`: where execution starts\n- `overview`: project layers and folders\n- `escape`: source bodies, span text or evidence outside the graph\n\n`audit` identifies compiler declaration facts, server-derived structure\nand plugin artifact facts; it does not claim a second compiler check.\nJudge the coverage of ranked `lookup`, `entrypoints` and `tour` shortlists.\nFollow `next`; read source for omitted body text or missed coverage.",
                     name: "inspect_typescript_graph",
                     output: {
                         type: "object",
                         properties: {
                             audit: {
                                 type: "string",
-                                description: "What the server audited this result against before returning it, in its\nown words: every node, span, edge, signature, member, and step in it\nresolves to the type-checked program for the snapshot the call synced to,\nso opening a file it cites only returns a fact already in it.\n\nThe audit is operation-aware. For the walks from a named handle (`trace`,\n`overview`) it reports the result as the structure the graph holds,\nbounded where `truncated` says. For `details` it reports the two halves of\na resolved symbol: its own shape returned whole, its fan-out returned as a\nslice with `trace` for the rest. For the ranked operations (`lookup`,\n`entrypoints`, `tour`) it adds that the selection is heuristic \u2014 matched,\nscored, ranked, and limited against the question \u2014 so the facts are\nverified but the shortlist's coverage is the caller's to judge."
+                                description: "The provenance and coverage of the returned projection. Compiler facts\nbelong to the synchronized program; file containers, containment,\nproperty kinds, path-convention test roles and dispatch hops are server-derived structure. Artifact\nfacts come from the publishing lint plugin. This text reports those\norigins without claiming a second compiler verification pass.\n\nThe audit is operation-aware. For the walks from a named handle (`trace`,\n`overview`) it reports the result as the structure the graph holds,\nbounded where `truncated` says. For `details` it reports the two halves\nof a resolved symbol: its own shape returned whole, its fan-out returned\nas a slice with `trace` for the rest. For the ranked operations\n(`lookup`, `entrypoints`, `tour`) it adds that the selection is heuristic\n\u2014 matched, scored, ranked, and limited against the question \u2014 so the\nfacts are verified but the shortlist's coverage is the caller's to\njudge."
                             },
                             next: {
                                 $ref: "#/$defs/ITtscGraphNext",
@@ -131,7 +135,7 @@ function createServer(graph, version) {
                             "result"
                         ],
                         additionalProperties: false,
-                        description: "The selected request's output. `result.type` mirrors `request.type`.",
+                        description: "The selected request's output. `result.type` mirrors `request.type`.\n\n------------------------------\n\nDescription of the current {@link ITtscGraphApplication.IOutput} type:\n\n> The selected request's output. `result.type` mirrors `request.type`.",
                         $defs: {
                             ITtscGraphDecorator: {
                                 type: "object",
@@ -469,14 +473,14 @@ function createServer(graph, version) {
                                     },
                                     text: {
                                         type: "string",
-                                        description: "Everything written after the tag name, joined into one line.\n\nAn inline link keeps the braced form it was written in (`{@link ISale}`),\nso a consumer matching a citation target sees what the author typed. The\nsame link is separately a resolved edge on the node, which is what says\n*which* `ISale` \u2014 a name can be declared twice and only the checker knows.\n\nAbsent when the tag carries no text."
+                                        description: "Everything written after the tag name, joined into one line.\n\nAn inline link keeps the braced form it was written in (`{@link ISale}`), so\na consumer matching a citation target sees what the author typed. The same\nlink is separately a resolved edge on the node, which is what says _which_\n`ISale` \u2014 a name can be declared twice and only the checker knows.\n\nAbsent when the tag carries no text."
                                     }
                                 },
                                 required: [
                                     "name"
                                 ],
                                 additionalProperties: false,
-                                description: "One documentation tag TypeScript itself does not recognize, written on a\ndeclaration and carried on its ITtscGraphNode's `docTags`.\n\nA convention attaches a declaration to something outside the type system \u2014 a\nspecification section, an API operation, a reference document \u2014 and writes\nthat attachment as a tag, because the thing on the other end is not a\nTypeScript declaration and so cannot be an edge. `@evidence\ndocs/pricing.md#sale`, `@reference https://\u2026`, and a project's own `@spec`\nare one fact in three spellings.\n\nReported faithfully, never interpreted. The graph does not say a tag's text\nresolves to anything, is covered, or is true \u2014 a target naming nothing is\ncarried exactly as written, the way ITtscGraphDecorator carries\n`@Controller` without knowing what a controller is.\n\nWhich tags arrive is the compiler's boundary, not a list kept here: these are\nthe tags the parser had no meaning for. A known tag \u2014 `@param`, `@returns`,\n`@deprecated` \u2014 has its own shape and its own meaning and is not one of\nthese.\n\nThe parser also decides where a tag begins, and that decision is reported\nrather than second-guessed. TypeScript opens a tag at an `@` wherever it sits\ninside a documentation block, so a tag name written mid-sentence arrives here\nas a tag, while a `//` comment is not documentation and contributes nothing at\nall. A convention that wants the stricter rule enforces it in its own linter,\nwhere the author gets a diagnostic; the graph reports what the compiler\nparsed."
+                                description: "One documentation tag TypeScript itself does not recognize, written on a\ndeclaration and carried on its ITtscGraphNode's `docTags`.\n\nA convention attaches a declaration to something outside the type system \u2014 a\nspecification section, an API operation, a reference document \u2014 and writes\nthat attachment as a tag, because the thing on the other end is not a\nTypeScript declaration and so cannot be an edge. `@evidence\ndocs/pricing.md#sale`, `@reference https://\u2026`, and a project's own `@spec`\nare one fact in three spellings.\n\nReported faithfully, never interpreted. The graph does not say a tag's text\nresolves to anything, is covered, or is true \u2014 a target naming nothing is\ncarried exactly as written, the way ITtscGraphDecorator carries\n`@Controller` without knowing what a controller is.\n\nWhich tags arrive is the compiler's boundary, not a list kept here: these are\nthe tags the parser had no meaning for. A known tag \u2014 `@param`, `@returns`,\n`@deprecated` \u2014 has its own shape and its own meaning and is not one of\nthese.\n\nThe parser also decides where a tag begins, and that decision is reported\nrather than second-guessed. TypeScript opens a tag at an `@` wherever it sits\ninside a documentation block, so a tag name written mid-sentence arrives here\nas a tag, while a `//` comment is not documentation and contributes nothing\nat all. A convention that wants the stricter rule enforces it in its own\nlinter, where the author gets a diagnostic; the graph reports what the\ncompiler parsed."
                             },
                             ITtscGraphEntrypoints: {
                                 type: "object",
@@ -827,7 +831,7 @@ function createServer(graph, version) {
                                     },
                                     truncated: {
                                         type: "boolean",
-                                        description: "True when a match was left out by the limit.\n\nThe audit for the ranked operations already tells a reader that\n`truncated` marks where more was left out, and this result had no such\nfield \u2014 so a cut looked exactly like a complete answer. That is tolerable\nfor a name query, where the ranking is a shortlist by design, and it is not\nfor a documentation target: those hits are an exact match on an address, so\na caller asking which code implements a specification is owed the fact that\nit did not get all of it."
+                                        description: "True when a match was left out by the limit.\n\nThe audit for the ranked operations already tells a reader that `truncated`\nmarks where more was left out, and this result had no such field \u2014 so a cut\nlooked exactly like a complete answer. That is tolerable for a name query,\nwhere the ranking is a shortlist by design, and it is not for a\ndocumentation target: those hits are an exact match on an address, so a\ncaller asking which code implements a specification is owed the fact that\nit did not get all of it."
                                     }
                                 },
                                 required: [
@@ -1371,11 +1375,11 @@ function createServer(graph, version) {
                                         items: {
                                             $ref: "#/$defs/ITtscGraphTrace.INode"
                                         },
-                                        description: "Unique nodes reached (excluding the start), each with its depth and roles."
+                                        description: "Unique nodes reached (excluding the start), each with its depth, and its roles on an impact trace."
                                     },
                                     truncated: {
                                         type: "boolean",
-                                        description: "In an open trace, true when a bound omitted an eligible node or hop."
+                                        description: "True when an open walk omitted an eligible node or hop, or an unsuccessful path search stopped on a depth or dispatch bound."
                                     },
                                     target: {
                                         $ref: "#/$defs/ITtscGraphTrace.INode",
@@ -1393,14 +1397,14 @@ function createServer(graph, version) {
                                         items: {
                                             type: "string"
                                         },
-                                        description: "Compact hop summaries preserving node names and edge evidence, capped."
+                                        description: "Hop summaries preserving names and evidence. First twelve by default; every returned hop with `complete: true`."
                                     },
                                     junctions: {
                                         type: "array",
                                         items: {
                                             $ref: "#/$defs/ITtscGraphTrace.IJunction"
                                         },
-                                        description: "Symbols both ends touch, when no call path runs between them.\n\nNothing calls across the gap because in an event-driven codebase nothing\ndoes: a handler registers a listener on an emitter, the emitter's `emit()`\nruns whatever a registration put in an array, and no call edge crosses that\narray. But both ends touch the emitter, and that is an edge, not a guess \u2014\nExcalidraw's pointer handler and its store's emit both reference\n`Store.onDurableIncrementEmitter`, which is exactly the seam the call graph\ncannot walk.\n\nA junction is not a path. It is the symbol to look at next, and the edges\nthat say why."
+                                        description: "Up to four ranked symbols both ends touch, when no call path runs between\nthem. This diagnostic summary does not change path-search completeness.\n\nNothing calls across the gap because in an event-driven codebase nothing\ndoes: a handler registers a listener on an emitter, the emitter's `emit()`\nruns whatever a registration put in an array, and no call edge crosses that\narray. But both ends touch the emitter, and that is an edge, not a guess \u2014\nExcalidraw's pointer handler and its store's emit both reference\n`Store.onDurableIncrementEmitter`, which is exactly the seam the call graph\ncannot walk.\n\nA junction is not a path. It is the symbol to look at next, and the edges\nthat say why."
                                     },
                                     candidates: {
                                         type: "array",
@@ -1559,7 +1563,7 @@ function createServer(graph, version) {
                                         items: {
                                             type: "string"
                                         },
-                                        description: "Why this node matters to an impact trace: `exported`, `test`."
+                                        description: "Why this node matters to an impact trace: `exported` (a compiler fact) or `test` (assigned by the server from a conventional test path, not by the compiler)."
                                     }
                                 },
                                 required: [
@@ -1664,7 +1668,7 @@ function createServer(graph, version) {
                             "request"
                         ],
                         additionalProperties: false,
-                        description: "Draft, review, then submit exactly one graph request or escape.",
+                        description: "Draft, review, then submit exactly one graph request or escape.\n\n------------------------------\n\nDescription of the current {@link ITtscGraphApplication.IProps} type:\n\n> Draft, review, then submit exactly one graph request or escape.",
                         $defs: {
                             "ITtscGraphApplication.IDraft": {
                                 type: "object",
@@ -1871,7 +1875,7 @@ function createServer(graph, version) {
                                     },
                                     limit: {
                                         type: "number",
-                                        description: "Central entrypoints to seed the tour. Raise only when the question names\nseveral public paths that must all appear in one answer."
+                                        description: "Central entrypoints to seed the tour, from 1 to 5. The default is the\nmaximum, so a larger value changes nothing and a smaller one narrows the\ntour."
                                     },
                                     includeTests: {
                                         type: "boolean",
@@ -1883,7 +1887,7 @@ function createServer(graph, version) {
                                     "reinterpretations"
                                 ],
                                 additionalProperties: false,
-                                description: "A broad code tour: entrypoints, primary flow, nearby paths, and tests.\n\nIt asks for no question of its own \u2014 it ranks against the `question` the\ncaller has already written, in the user's words."
+                                description: "A broad code tour: entrypoints, primary flow, nearby paths, and tests.\n\nIt uses the outer question for explicit handles and the caller's symbol\nreinterpretations for identifier alignment, alongside graph centrality."
                             },
                             "ITtscGraphTrace.IRequest": {
                                 type: "object",
@@ -1921,13 +1925,17 @@ function createServer(graph, version) {
                                         ],
                                         description: "Non-structural edge family to follow:\n\n- `execution`: runtime calls, instantiations, property access, JSX renders\n- `types`: type references and inheritance\n- `all`: the full graph\n\nFlow questions usually want `execution`, not `all`."
                                     },
+                                    complete: {
+                                        type: "boolean",
+                                        description: "Exhaust the finite graph admitted by direction, focus and external-node\npolicy, including every eligible dispatch relation. Overrides maxDepth,\nmaxNodes, hop budgets and limits on hop summaries. Path mode returns one shortest path.\n\nOutput and synchronous traversal can grow with the entire graph; there is\nno per-request cancellation or fixed response-size bound. Resource or\ntransport failures fail the request rather than return partial success."
+                                    },
                                     maxDepth: {
                                         type: "number",
-                                        description: "Hops deep to follow (open forward/reverse cap at 8, impact at 4, path\nmode at 12). Raise it to follow a runtime chain to its end in one call."
+                                        description: "Hops deep to follow. Positive finite values have no upper clamp and are\nrounded down; invalid or omitted values use 3 (12 in path mode).\nValues below one become one. Ignored with complete true."
                                     },
                                     maxNodes: {
                                         type: "number",
-                                        description: "Cap on reached nodes (open forward/reverse cap at 32, impact at 16)."
+                                        description: "Cap on unique reached nodes, excluding the start. Positive finite values\nhave no upper clamp and are rounded down; invalid or omitted values use\n12. Values below one become one. Open walks also limit hops to twice this\nbudget and withhold dispatch fanouts of twelve or more implementations.\nUse complete true to remove every traversal budget. Path mode ignores\nmaxNodes."
                                     },
                                     includeExternal: {
                                         type: "boolean",
@@ -1977,7 +1985,7 @@ function createServer(graph, version) {
                         const _io4 = input => "lookup" === input.type && _ip2(input) && _ip3(input) && _ip1(input);
                         const _io5 = input => "overview" === input.type && (undefined === input.aspect || "all" === input.aspect || "hotspots" === input.aspect || "layers" === input.aspect || "publicApi" === input.aspect);
                         const _io6 = input => "tour" === input.type && (Array.isArray(input.reinterpretations) && input.reinterpretations.every(elem => "string" === typeof elem)) && _ip3(input) && (undefined === input.includeTests || "boolean" === typeof input.includeTests);
-                        const _io7 = input => "trace" === input.type && "string" === typeof input.from && (undefined === input.to || "string" === typeof input.to) && (undefined === input.direction || "forward" === input.direction || "impact" === input.direction || "reverse" === input.direction) && (undefined === input.focus || "all" === input.focus || "execution" === input.focus || "types" === input.focus) && (undefined === input.maxDepth || "number" === typeof input.maxDepth) && (undefined === input.maxNodes || "number" === typeof input.maxNodes) && _ip1(input);
+                        const _io7 = input => "trace" === input.type && "string" === typeof input.from && (undefined === input.to || "string" === typeof input.to) && (undefined === input.direction || "forward" === input.direction || "impact" === input.direction || "reverse" === input.direction) && (undefined === input.focus || "all" === input.focus || "execution" === input.focus || "types" === input.focus) && (undefined === input.complete || "boolean" === typeof input.complete) && (undefined === input.maxDepth || "number" === typeof input.maxDepth) && (undefined === input.maxNodes || "number" === typeof input.maxNodes) && _ip1(input);
                         const _io8 = input => "escape" === input.type && _ip0(input) && (undefined === input.nextStep || "string" === typeof input.nextStep);
                         const _iu0 = input => (() => {
                             if ("details" === input.type)
@@ -2124,6 +2132,10 @@ function createServer(graph, version) {
                                 path: _path + ".focus",
                                 expected: "(\"all\" | \"execution\" | \"types\" | undefined)",
                                 value: input.focus
+                            }), undefined === input.complete || "boolean" === typeof input.complete || _report(_exceptionable, {
+                                path: _path + ".complete",
+                                expected: "(boolean | undefined)",
+                                value: input.complete
                             }), undefined === input.maxDepth || "number" === typeof input.maxDepth || _report(_exceptionable, {
                                 path: _path + ".maxDepth",
                                 expected: "(number | undefined)",
@@ -2199,15 +2211,6 @@ function createServer(graph, version) {
                 }
             ]
         })
-    });
-    // @typia/mcp 13.1.0 exposes no class-controller version option. The MCP SDK
-    // keeps the initialize implementation on its public inner Server, so update
-    // that already-constructed implementation before any transport connects.
-    const inner = server.server;
-    if (inner._serverInfo === undefined) {
-        throw new Error("@ttsc/graph: MCP SDK omitted the server implementation");
-    }
-    inner._serverInfo.version = version;
-    return server;
+    }, { version });
 }
 //# sourceMappingURL=createServer.js.map

package/lib/server/createServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"createServer.js","sourceRoot":"","sources":["../../src/server/createServer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,oCAA6C;AAC7C,kDAA0B;AAE1B,kEAAgF;AAGhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,sBACE,KAAsB,EACtB,OAAe;IAEf,MAAM,MAAM,GAAG,IAAA,qBAAe;;gBAE1B,YAAY;mBACZ,IAAI,2CAAoB,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAElC,CAAC;IACF,4EAA4E;IAC5E,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,KAAK,GAAG,MAAM,CAAC,MAEpB,CAAC;IACF,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,OAAO,CAAC;IACpC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"createServer.js","sourceRoot":"","sources":["../../src/server/createServer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,oCAA6C;AAC7C,kDAA0B;AAE1B,kEAAgF;AAGhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,sBACE,KAAsB,EACtB,OAAe;IAEf,OAAO,IAAA,qBAAe;;gBAElB,YAAY;mBACZ,IAAI,2CAAoB,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAEjC,EAAE,OAAO,EAAE,CACZ,CAAC;AACJ,CAAC"}

package/lib/server/exportSurface.d.ts

@@ -20,7 +20,29 @@ import { TtscGraphMemory } from "../model/TtscGraphMemory";
  *
  * The count is a fact the compiler resolved. It reads no package.json, guesses
  * from no filename, and holds for a project that has neither.
+ *
+ * @evidence contracts/common.md#principled-implementation Counting incoming exports edges reports modules whose checker-resolved export tables publish this exact node.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate supplies the graph-derived public-surface signal to handle and tour ranking.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No package.json, file-name front-door guess or named project's expected score substitutes for export relationships.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain barrel/re-export propagation and distinguish edge count from declaring-file exported status.
+ * @evidence contracts/performance.md#efficient-algorithms The incoming index restricts counting to this node's degree instead of scanning every graph edge.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This count is a primitive over an already shared generation index; caller-owned rank computation decides any broader reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Counting borrows indexed edges and retains only a scalar local accumulator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation counts edges in an in-memory index.
  */
 export declare function exportFanIn(graph: TtscGraphMemory, id: string): number;
-/** True when the dump carries an export surface at all. */
+/**
+ * True when the graph carries an exports edge at all.
+ *
+ * The answer is cached by immutable graph generation, including false.
+ *
+ * @evidence contracts/common.md#principled-implementation Existence of an exports edge establishes collection of at least one module surface without guessing from local declaration flags.
+ * @evidence contracts/common.md#clear-and-simple-design A WeakMap holds the generation-wide predicate result for all rankers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A false cached answer is retained as a real result rather than mistaken for a cache miss.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the edge criterion and generation-scoped caching.
+ * @evidence contracts/performance.md#efficient-algorithms The first check scans edges until a match; later lookups are map accesses.
+ * @evidence contracts/performance.md#reuse-equivalent-work The model's owned frozen facts make graph identity a stable generation key; a new generation is a different key and does not inherit the result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap entries follow graph reachability and do not retain historical graph generations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation scans in-memory edges and caches the answer per graph object.
+ */
 export declare function hasExportSurface(graph: TtscGraphMemory): boolean;

package/lib/server/exportSurface.js

@@ -23,6 +23,15 @@ exports.hasExportSurface = hasExportSurface;
  *
  * The count is a fact the compiler resolved. It reads no package.json, guesses
  * from no filename, and holds for a project that has neither.
+ *
+ * @evidence contracts/common.md#principled-implementation Counting incoming exports edges reports modules whose checker-resolved export tables publish this exact node.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate supplies the graph-derived public-surface signal to handle and tour ranking.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No package.json, file-name front-door guess or named project's expected score substitutes for export relationships.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain barrel/re-export propagation and distinguish edge count from declaring-file exported status.
+ * @evidence contracts/performance.md#efficient-algorithms The incoming index restricts counting to this node's degree instead of scanning every graph edge.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This count is a primitive over an already shared generation index; caller-owned rank computation decides any broader reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Counting borrows indexed edges and retains only a scalar local accumulator.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation counts edges in an in-memory index.
  */
 function exportFanIn(graph, id) {
     let count = 0;
@@ -31,7 +40,20 @@ function exportFanIn(graph, id) {
             count++;
     return count;
 }
-/** True when the dump carries an export surface at all. */
+/**
+ * True when the graph carries an exports edge at all.
+ *
+ * The answer is cached by immutable graph generation, including false.
+ *
+ * @evidence contracts/common.md#principled-implementation Existence of an exports edge establishes collection of at least one module surface without guessing from local declaration flags.
+ * @evidence contracts/common.md#clear-and-simple-design A WeakMap holds the generation-wide predicate result for all rankers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A false cached answer is retained as a real result rather than mistaken for a cache miss.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the edge criterion and generation-scoped caching.
+ * @evidence contracts/performance.md#efficient-algorithms The first check scans edges until a match; later lookups are map accesses.
+ * @evidence contracts/performance.md#reuse-equivalent-work The model's owned frozen facts make graph identity a stable generation key; a new generation is a different key and does not inherit the result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap entries follow graph reachability and do not retain historical graph generations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation scans in-memory edges and caches the answer per graph object.
+ */
 function hasExportSurface(graph) {
     const known = cache.get(graph);
     if (known !== undefined)

package/lib/server/exportSurface.js.map

@@ -1 +1 @@
-{"version":3,"file":"exportSurface.js","sourceRoot":"","sources":["../../src/server/exportSurface.ts"],"names":[],"mappings":";;;;AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAA4B,KAAsB,EAAE,EAAU;IAC5D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,KAAK,EAAE,CAAC;IAC5E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2DAA2D;AAC3D,0BAAiC,KAAsB;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAClE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,OAAO,EAA4B,CAAC"}
+{"version":3,"file":"exportSurface.js","sourceRoot":"","sources":["../../src/server/exportSurface.ts"],"names":[],"mappings":";;;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAA4B,KAAsB,EAAE,EAAU;IAC5D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,KAAK,EAAE,CAAC;IAC5E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,0BAAiC,KAAsB;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAClE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,OAAO,EAA4B,CAAC"}

package/lib/server/formatGraphFailure.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Render a terminal graph failure with its nested causes and aggregate members.
+ *
+ * The SDK's descriptor-based failure description preserves causes and shared
+ * references without evaluating getters. Node then displays that passive data
+ * without invoking custom inspectors. Proxy reflection retains the serializer's
+ * documented inspection limits.
+ *
+ * It is stderr text, not a serialization format or a retirement certificate.
+ *
+ * @evidence contracts/common.md#principled-implementation The SDK failure serializer preserves nested causes and aggregate members as passive data; Node inspection renders that finite description rather than projecting the outer message.
+ * @evidence contracts/common.md#clear-and-simple-design One renderer owns shutdown diagnostic text; the server continues to own its failing exit status.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Diagnostic formatting changes no cleanup result, admission state or original lifetime proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines nested diagnostics, disabled user hooks and the absence of transport or retirement authority.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This renderer observes JavaScript values and selects no OS path or process primitive.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated serialization visits distinct observed objects and owned fields; unlimited diagnostic inspection then renders that finite description. Structural work and returned text grow with the observed diagnostic graph, excluding arbitrary Proxy reflection.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each failure is rendered when reported; there is no reusable computation population.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned diagnostic string is caller-owned; no handle or retained cache is acquired.
+ */
+export declare function formatGraphFailure(error: unknown): string;

package/lib/server/formatGraphFailure.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGraphFailure = formatGraphFailure;
+const node_util_1 = require("node:util");
+const ttsc_1 = require("ttsc");
+/**
+ * Render a terminal graph failure with its nested causes and aggregate members.
+ *
+ * The SDK's descriptor-based failure description preserves causes and shared
+ * references without evaluating getters. Node then displays that passive data
+ * without invoking custom inspectors. Proxy reflection retains the serializer's
+ * documented inspection limits.
+ *
+ * It is stderr text, not a serialization format or a retirement certificate.
+ *
+ * @evidence contracts/common.md#principled-implementation The SDK failure serializer preserves nested causes and aggregate members as passive data; Node inspection renders that finite description rather than projecting the outer message.
+ * @evidence contracts/common.md#clear-and-simple-design One renderer owns shutdown diagnostic text; the server continues to own its failing exit status.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Diagnostic formatting changes no cleanup result, admission state or original lifetime proof.
+ * @evidence contracts/common.md#meaningful-documentation Native prose defines nested diagnostics, disabled user hooks and the absence of transport or retirement authority.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This renderer observes JavaScript values and selects no OS path or process primitive.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated serialization visits distinct observed objects and owned fields; unlimited diagnostic inspection then renders that finite description. Structural work and returned text grow with the observed diagnostic graph, excluding arbitrary Proxy reflection.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each failure is rendered when reported; there is no reusable computation population.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned diagnostic string is caller-owned; no handle or retained cache is acquired.
+ */
+function formatGraphFailure(error) {
+    return (0, node_util_1.inspect)((0, ttsc_1.serializeCompilerError)(error), {
+        depth: null,
+        customInspect: false,
+        getters: false,
+        colors: false,
+        maxArrayLength: null,
+        maxStringLength: null,
+    });
+}
+//# sourceMappingURL=formatGraphFailure.js.map

package/lib/server/formatGraphFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatGraphFailure.js","sourceRoot":"","sources":["../../src/server/formatGraphFailure.ts"],"names":[],"mappings":";;;AAAA,yCAAoC;AACpC,+BAA8C;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,4BAAmC,KAAc;IAC/C,OAAO,IAAA,mBAAO,EAAC,IAAA,6BAAsB,EAAC,KAAK,CAAC,EAAE;QAC5C,KAAK,EAAE,IAAI;QACX,aAAa,EAAE,KAAK;QACpB,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,KAAK;QACb,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,IAAI;KACtB,CAAC,CAAC;AACL,CAAC"}

package/lib/server/pathPolicy.d.ts

@@ -1,15 +1,80 @@
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
-/** True for dependency declarations outside the authored project graph. */
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
+/**
+ * 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.
+ */
 export declare function isExternalNode(node: ITtscGraphNode): boolean;
 /**
  * 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.
  */
 export declare function isDeclarationFile(file: string): boolean;
-/** 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.
+ */
 export declare function isSupportPath(file: string): boolean;
-/** 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.
+ */
 export declare function isTestPath(file: string): boolean;
-/** 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.
+ */
 export declare function isPublicApiNoisePath(file: string): boolean;
+export {};