@ttsc/graph 0.26.2 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "Checker-resolved architecture graph over MCP for coding agents, backed by ttsc's in-process TypeScript-Go compiler.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -16,11 +16,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@typia/mcp": "13.2.0",
-    "typia": "13.2.0"
+    "@typia/mcp": "14.0.0",
+    "typia": "14.0.0"
   },
   "peerDependencies": {
-    "ttsc": "^0.26.2"
+    "ttsc": "^0.28.0"
   },
   "keywords": [
     "ttsc",
@@ -42,7 +42,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "^7.0.2",
-    "ttsc": "0.26.2"
+    "ttsc": "0.28.0"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -5,6 +5,7 @@ import {
   parseLauncherOptions,
   projectOptions,
 } from "./launcherArgs";
+import { publishArtifacts } from "./model/publishedArtifacts";
 import { ensureExecutable } from "./nativeExecutable";
 import { resolveGraphBinary } from "./resolveGraphBinary";
 import { startServer } from "./server/startServer";
@@ -35,7 +36,7 @@ export { resolveGraphBinary } from "./resolveGraphBinary";
  */
 export { reduce } from "./reduce";
 export type { RawDump, RawEdge, RawNode, ViewerPayload } from "./reduce";
-export { loadGraph } from "./model/loadGraph";
+export { DUMP_SCHEMA_VERSION, loadGraph } from "./model/loadGraph";
 export {
   TtscGraphSession,
   type TtscGraphRequestOptions,
@@ -121,7 +122,9 @@ function printDumpHelp(): void {
 function runDump(argv: readonly string[]): number {
   // Resolve the native binary from the target project the caller named with
   // `--cwd`, not from wherever the launcher process happened to start.
-  const { cwd } = projectOptions(parseLauncherOptions(argv, DUMP_OPTIONS));
+  const { cwd, tsconfig } = projectOptions(
+    parseLauncherOptions(argv, DUMP_OPTIONS),
+  );
   const binary = resolveGraphBinary(process.env, cwd);
   if (binary === null) {
     // `ttscgraph` owns the flag contract, so a resolvable binary always answers
@@ -141,10 +144,24 @@ function runDump(argv: readonly string[]): number {
     return 1;
   }
   ensureExecutable(binary);
-  const result = spawnSync(binary, ["dump", ...argv], {
-    stdio: "inherit",
-    windowsHide: true,
-  });
+  // The same artifacts `loadGraph` and the resident session ask for, so the
+  // three ways to reach a dump answer a citation the same way. A caller that
+  // named `--artifacts` itself owns the answer and is not overridden.
+  const published = argv.includes("--artifacts")
+    ? null
+    : publishArtifacts({ cwd, tsconfig });
+  const result = spawnSync(
+    binary,
+    [
+      "dump",
+      ...argv,
+      ...(published?.file == null ? [] : ["--artifacts", published.file]),
+    ],
+    {
+      stdio: "inherit",
+      windowsHide: true,
+    },
+  );
   if (result.error) {
     process.stderr.write(`@ttsc/graph: ${result.error.message}\n`);
     return 1;

package/src/model/TtscGraphMemory.ts

@@ -3,6 +3,7 @@ import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphSpan } from "../structures/ITtscGraphSpan";
+import { isArtifactNodeKind } from "../structures/TtscGraphArtifactNodeKind";
 import { TtscGraphEdgeKind } from "../structures/TtscGraphEdgeKind";
 import { ttscGraphNodeIdPath } from "./TtscGraphNodeId";
 import { TtscGraphSourceReader } from "./TtscGraphSourceReader";
@@ -24,6 +25,7 @@ export class TtscGraphMemory {
   private readonly inEdges: Map<string, ITtscGraphEdge[]>;
   private readonly byNameIndex: Map<string, ITtscGraphNode[]>;
   private readonly bySymbolIndex: Map<string, ITtscGraphNode[]>;
+  private readonly byDocTagTarget: Map<string, ITtscGraphNode[]>;
 
   /** The absolute project root the dump was built for. */
   readonly project: string;
@@ -48,6 +50,7 @@ export class TtscGraphMemory {
     this.byId = new Map(nodes.map((n) => [n.id, n]));
     this.byNameIndex = new Map();
     this.bySymbolIndex = new Map();
+    this.byDocTagTarget = new Map();
     for (const node of nodes) {
       const bucket = this.byNameIndex.get(node.name);
       if (bucket) bucket.push(node);
@@ -58,6 +61,16 @@ export class TtscGraphMemory {
           push(this.bySymbolIndex, node.qualifiedName, node);
         }
       }
+      for (const target of docTagTargetsOf(node)) {
+        const carriers = this.byDocTagTarget.get(target);
+        // The membership check is redundant today — `docTagTargetsOf`
+        // deduplicates within a node and this loop visits each node once — and
+        // it is kept because the cost is a scan of a list that holds the
+        // carriers of one address, while the failure it prevents is a
+        // declaration reported twice as implementing one specification.
+        if (carriers === undefined) this.byDocTagTarget.set(target, [node]);
+        else if (!carriers.includes(node)) carriers.push(node);
+      }
     }
     this.outEdges = new Map();
     this.inEdges = new Map();
@@ -102,6 +115,100 @@ export class TtscGraphMemory {
   exported(): ITtscGraphNode[] {
     return this.nodes.filter((n) => n.exported && !n.external);
   }
+
+  /**
+   * Every declaration whose documentation names this address — the reverse of
+   * the citation question.
+   *
+   * The forward direction costs a reader one file: the tag sits above the
+   * declaration they already found. The reverse direction is what an index is
+   * for, because the declarations implementing one specification are scattered
+   * across every file that implements it, and finding them otherwise means
+   * searching the whole repository.
+   *
+   * The address is exact and is spelled as {@link documentationTarget} decides,
+   * so a caller passes that function's output rather than a raw query. Which
+   * part of a tag's text names a thing belongs to whatever convention wrote the
+   * tag, so this is a selection rule of the consuming layer rather than a fact
+   * the producer claims.
+   */
+  citing(target: string): readonly ITtscGraphNode[] {
+    return this.byDocTagTarget.get(target) ?? [];
+  }
+}
+
+/**
+ * The address each of a node's documentation tags names, deduplicated.
+ *
+ * A braced inline link is one token including its braces (`{@link ISale}`),
+ * because that is how the author wrote the target and how a reader searching
+ * for it will spell it. Splitting on whitespace alone would key it under
+ * `{@link`, which is every link in the project.
+ */
+function docTagTargetsOf(node: ITtscGraphNode): string[] {
+  if (node.docTags === undefined) return [];
+  const targets: string[] = [];
+  for (const tag of node.docTags) {
+    const token = documentationTarget(tag.text);
+    if (token !== undefined && !targets.includes(token)) targets.push(token);
+  }
+  return targets;
+}
+
+/**
+ * The address a documentation tag's text opens with, or undefined when its
+ * first token is ordinary prose.
+ *
+ * Every unrecognized tag arrives here, and most of them are not citations:
+ * TypeScript has no AST kind for `@remarks`, `@example`, `@todo`, `@internal`,
+ * or `@default` either, so their first word reaches this function exactly as a
+ * citation target does. Indexing those turned `@todo Add caching here` into a
+ * carrier of the address `Add`, and a query opening with that word answered
+ * with it — above every real name match, and labelled a certain citation.
+ *
+ * So a token qualifies only when it carries a separator that prose does not: a
+ * path or anchor (`docs/pricing.md#sale`), a namespaced or method-prefixed
+ * address (`POST:/orders`, `prisma:Sale`), an inline link, or a URL. An English
+ * word carries none of these, and neither does a bare number, so `@default 4`
+ * and `@todo Add caching` index nothing while every address form in use does.
+ *
+ * This is a selection rule, not a claim about the source. It lives here rather
+ * than in the producer for that reason: the graph reports the tag as written
+ * and this decides only what the ranked operations will match on, which is the
+ * layer whose audit already declares its selection heuristic. A convention
+ * whose addresses look like prose is simply not indexed; nothing is lost from
+ * the tag itself, which `details` still returns in full.
+ */
+export function documentationTarget(
+  text: string | undefined,
+): string | undefined {
+  const token = leadingToken(text);
+  if (token === undefined) return undefined;
+  if (token.startsWith("{")) return token;
+  // A separator anywhere but the last position: a trailing one is sentence
+  // punctuation ("Uses the cache." ends in a dot and names nothing), while an
+  // interior one is what every address form spells.
+  return /[/#:][^\s]/u.test(token) || /\.[^\s.]/u.test(token)
+    ? token
+    : undefined;
+}
+
+/**
+ * The first whitespace-delimited token, or the whole brace group it opens.
+ *
+ * An unclosed brace group is not a token: `{@link ISale` with the brace
+ * forgotten would otherwise fall through to the whitespace split and index the
+ * address `{@link`, which every link in the project shares.
+ */
+export function leadingToken(text: string | undefined): string | undefined {
+  const trimmed = text?.trim();
+  if (trimmed === undefined || trimmed === "") return undefined;
+  if (trimmed.startsWith("{")) {
+    const close = trimmed.indexOf("}");
+    return close > 0 ? trimmed.slice(0, close + 1) : undefined;
+  }
+  const stop = trimmed.search(/\s/u);
+  return stop < 0 ? trimmed : trimmed.slice(0, stop);
 }
 
 /** Append value to the slice stored at key, creating the slice on first use. */
@@ -136,7 +243,7 @@ function ownerKey(node: ITtscGraphNode): string | undefined {
   return owner === "" ? undefined : owner;
 }
 
-/** A file's id and node name from its schema-v6 path coordinate. */
+/** A file's id and node name from its dump path coordinate. */
 function fileNodeId(file: string): string {
   return file;
 }
@@ -255,7 +362,7 @@ function synthesize(dump: ITtscGraphDump): {
     });
   };
   for (const node of nodes) {
-    if (node.external) continue;
+    if (node.external || isArtifactNodeKind(node.kind)) continue;
     addFileNode(node.file);
   }
   for (const file of moduleFiles) addFileNode(file);
@@ -269,6 +376,15 @@ function synthesize(dump: ITtscGraphDump): {
   // legacy subpath.
   const structural: ITtscGraphEdge[] = [];
   for (const node of nodes) {
+    // An artifact is contained by the artifact its producer named, and by
+    // nothing when that producer named none. It is never contained by a `file`
+    // node: a document is already its own node, a Prisma address carries no
+    // path on purpose, and an API operation has no file at all.
+    if (isArtifactNodeKind(node.kind)) {
+      if (node.parent !== undefined && node.parent !== "")
+        structural.push({ from: node.parent, to: node.id, kind: "contains" });
+      continue;
+    }
     if (node.external || node.file === "") continue;
     const parent = owner(node);
     const container = parent ? parent.id : fileNodeId(node.file);

package/src/model/TtscGraphSession.ts

@@ -7,7 +7,14 @@ import { resolveGraphBinary } from "../resolveGraphBinary";
 import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
 import { TtscGraphMemory } from "./TtscGraphMemory";
 import { TtscGraphShardStore } from "./TtscGraphShardStore";
+import { TtscLintDaemon } from "./TtscLintDaemon";
 import { DUMP_SCHEMA_VERSION } from "./loadGraph";
+import {
+  type IPublishedArtifacts,
+  artifactsAreStale,
+  publishArtifacts,
+  publishArtifactsResident,
+} from "./publishedArtifacts";
 
 /**
  * The serve protocol version this client speaks.
@@ -69,6 +76,26 @@ export class TtscGraphSession {
   private queue: Promise<void> = Promise.resolve();
   private current: TtscGraphMemory | undefined;
   private shardStore = new TtscGraphShardStore();
+  /**
+   * The artifact answer the resident child was last handed, and the state of
+   * the inputs it came from.
+   *
+   * `undefined` only before a child exists. Once one does this is always an
+   * answer, including the answer that the project publishes nothing — which
+   * still carries inputs, so that adding a publisher is something a running
+   * session can notice.
+   */
+  private artifacts: IPublishedArtifacts | undefined;
+  /**
+   * One resident `@ttsc/lint` sidecar per plugin binary, opened lazily.
+   *
+   * A republish asks two verbs of every configured publisher, and a session
+   * republishes whenever a document moves. Held open, those questions cost a
+   * request each instead of a process, a plugin load and a configuration
+   * evaluation each. Keyed by binary because that is what a daemon is: the same
+   * binary answering for the same project.
+   */
+  private readonly daemons = new Map<string, TtscLintDaemon>();
   private closed = false;
 
   public constructor(options: TtscGraphSessionOptions) {
@@ -140,6 +167,12 @@ export class TtscGraphSession {
   public close(): void {
     if (this.closed) return;
     this.closed = true;
+    // The sidecars outlive nothing. A daemon is a child process this session
+    // opened, and a session that closed without stopping them would leave one
+    // resident Program per configured publisher alive for as long as the parent
+    // ran.
+    for (const daemon of this.daemons.values()) daemon.close();
+    this.daemons.clear();
     const error = new Error("@ttsc/graph: native session closed");
     if (this.child !== undefined) this.failChild(this.child, error);
     else this.failPending(error);
@@ -148,6 +181,7 @@ export class TtscGraphSession {
   private async refresh(signal?: AbortSignal): Promise<TtscGraphMemory> {
     // The protocol version and the envelope shape were both settled in onLine,
     // before this frame was ever routed here.
+    await this.republishArtifacts(signal);
     const response = await this.request(signal);
     this.assertResponseSemantics(response);
     if (response.error !== undefined) {
@@ -206,6 +240,58 @@ export class TtscGraphSession {
     throw error;
   }
 
+  /**
+   * Re-derive the artifact set when the documents or configuration behind it
+   * moved, before the request that would otherwise answer with the old one.
+   *
+   * A resident session is invalidated by the compiler's own build universe, and
+   * none of this is in it: the documents a rule reads are not Program inputs,
+   * which is the property that keeps a Markdown edit from costing a typecheck.
+   * The cost of that property is that nothing else notices the edit at all, so
+   * this is what notices it.
+   *
+   * Only the overlay is replaced. The child is not restarted and the Program is
+   * not reloaded — the native session compares the file it is handed against
+   * the one it applied, and re-projects the resident program when they differ.
+   *
+   * Asked of sidecars this session keeps open, and awaited rather than blocking
+   * the event loop. A republish still costs the rule a Program — the daemon is
+   * told to drop its warm one, because the sources a claim activates against
+   * have been edited too — but not a process, a plugin load and a configuration
+   * evaluation per verb. An already-cancelled request does not start one.
+   */
+  private async republishArtifacts(signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) return;
+    // A child yet to be spawned publishes on the way up, so there is nothing
+    // here to keep fresh until one does.
+    if (this.child === undefined || this.artifacts === undefined) return;
+    if (!artifactsAreStale(this.artifacts)) return;
+    const next = await publishArtifactsResident(
+      { cwd: this.cwd, tsconfig: this.tsconfig },
+      (plugin) => this.daemon(plugin),
+    );
+    // The new answer is taken whatever it says, including that the project now
+    // publishes nothing. Keeping the old set on a `null` would be guessing that
+    // the publisher failed rather than that it was removed, and guessing wrong
+    // in that direction is the unrecoverable one: a session that answers with
+    // artifacts from a plugin the user deleted keeps doing so until it is
+    // restarted, while a transient failure is repaired by the next edit.
+    this.artifacts = next;
+  }
+
+  /** The open sidecar for one plugin, opened on first use. */
+  private daemon(plugin: {
+    binary: string;
+    manifest: string;
+    projectContext?: string;
+  }): TtscLintDaemon {
+    const open = this.daemons.get(plugin.binary);
+    if (open !== undefined) return open;
+    const created = new TtscLintDaemon(plugin, this.cwd, this.tsconfig);
+    this.daemons.set(plugin.binary, created);
+    return created;
+  }
+
   private request(signal?: AbortSignal): Promise<ITtscGraphSnapshot> {
     if (signal?.aborted) throw cancelledError(signal);
     const child = this.ensureChild();
@@ -228,7 +314,19 @@ export class TtscGraphSession {
         return;
       }
       child.process.stdin.write(
-        `${JSON.stringify({ id, graphSnapshotVersion: GRAPH_SNAPSHOT_PROTOCOL_VERSION })}\n`,
+        `${JSON.stringify({
+          id,
+          graphSnapshotVersion: GRAPH_SNAPSHOT_PROTOCOL_VERSION,
+          // Empty when the project publishes nothing, which withdraws whatever
+          // the server holds: a publisher the user removed must stop being
+          // answered with, and omitting the field instead would say only that
+          // this client has no opinion. Omitted only before a child exists,
+          // which no request reaches.
+          artifacts:
+            this.artifacts === undefined
+              ? undefined
+              : (this.artifacts.file ?? ""),
+        })}\n`,
         (error) => {
           if (error === null || error === undefined) return;
           if (this.pending.get(id) !== pending) return;
@@ -256,9 +354,21 @@ export class TtscGraphSession {
     ) {
       return this.child;
     }
+    const artifacts = publishArtifacts({
+      cwd: this.cwd,
+      tsconfig: this.tsconfig,
+    });
+    this.artifacts = artifacts;
     const process = spawn(
       this.binary,
-      ["serve", "--cwd", this.cwd, "--tsconfig", this.tsconfig],
+      [
+        "serve",
+        "--cwd",
+        this.cwd,
+        "--tsconfig",
+        this.tsconfig,
+        ...(artifacts.file === null ? [] : ["--artifacts", artifacts.file]),
+      ],
       { stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
     );
     const lines = readline.createInterface({ input: process.stdout });

package/src/model/TtscGraphShardStore.ts

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
+import { isArtifactNodeKind } from "../structures/TtscGraphArtifactNodeKind";
 import { DUMP_SCHEMA_VERSION } from "./loadGraph";
 
 /** Atomic validator and assembler for native `ttscgraph` shard transactions. */
@@ -323,8 +324,12 @@ function assertShardContents(
     }
     return;
   }
+  // The metadata shard carries the nodes no program source owns: external
+  // boundary leaves, and published artifacts. An artifact has no source to be
+  // owned by, so the guard that keeps authored declarations out of this shard
+  // names it rather than treating "not external" as "authored".
   for (const node of shard.nodes) {
-    if (!node.external) {
+    if (!node.external && !isArtifactNodeKind(node.kind)) {
       throw new Error(
         `@ttsc/graph: native metadata shard ${key} owns authored node ${node.id}`,
       );

package/src/model/TtscLintDaemon.ts

@@ -0,0 +1,179 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import readline from "node:readline";
+
+/** One plugin sidecar this daemon can be opened against. */
+export interface ITtscLintDaemonTarget {
+  binary: string;
+  manifest: string;
+  projectContext?: string;
+}
+
+/**
+ * A resident `@ttsc/lint` sidecar, kept open across the questions one graph
+ * session asks it.
+ *
+ * The alternative is what this replaces: a process per question. Publishing a
+ * project's artifacts asks two — `graph-nodes` and `project-inputs` — and a
+ * resident graph session asks both again every time a document moves, so the
+ * spawn, the plugin load, and the configuration evaluation were paid once per
+ * edit, forever. `@ttsc/lint` already runs `lsp-serve` for exactly this reason,
+ * and `ttscserver` already routes its own read verbs through it.
+ *
+ * Everything here degrades rather than fails. A sidecar built before these
+ * verbs joined the daemon rejects them, an older one does not know `lsp-serve`
+ * at all, and a daemon can die mid-session; each of those closes this one and
+ * leaves the caller to spawn per verb, which is the behaviour that existed
+ * before this and is still correct — only slower.
+ */
+export class TtscLintDaemon {
+  private child: ChildProcessWithoutNullStreams | undefined;
+  private lines: readline.Interface | undefined;
+  private readonly pending: ((reply: IReply | null) => void)[] = [];
+  private queue: Promise<unknown> = Promise.resolve();
+  private failed = false;
+
+  public constructor(
+    private readonly target: ITtscLintDaemonTarget,
+    private readonly cwd: string,
+    private readonly tsconfig: string,
+  ) {}
+
+  /**
+   * Ask one verb and return its raw JSON, or `null` when this daemon cannot
+   * answer it.
+   *
+   * `null` is always "ask the sidecar directly instead", never "the project has
+   * none". The two are indistinguishable downstream — an empty artifact set is
+   * the correct answer for most projects — so a daemon that cannot answer must
+   * never be allowed to look like one that answered nothing.
+   *
+   * Requests are serialized. The daemon answers one line per request in order,
+   * with nothing in the reply to address it by, so a second request in flight
+   * would be matched against the first one's answer.
+   */
+  public ask(verb: string, invalidate: boolean): Promise<string | null> {
+    const run = this.queue.then(() => this.send(verb, invalidate));
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /** Stop the sidecar. Safe to call more than once, and after a failure. */
+  public close(): void {
+    this.failed = true;
+    for (const settle of this.pending.splice(0)) settle(null);
+    this.lines?.close();
+    this.lines = undefined;
+    const child = this.child;
+    this.child = undefined;
+    if (child === undefined) return;
+    child.stdin.end();
+    child.kill();
+  }
+
+  private async send(
+    verb: string,
+    invalidate: boolean,
+  ): Promise<string | null> {
+    if (this.failed) return null;
+    const child = this.start();
+    if (child === undefined) return null;
+    const reply = await new Promise<IReply | null>((resolve) => {
+      this.pending.push(resolve);
+      child.stdin.write(
+        `${JSON.stringify({ invalidate, verb })}\n`,
+        (error) => {
+          if (error === null || error === undefined) return;
+          this.fail();
+        },
+      );
+    });
+    if (reply === null || reply.code !== 0) {
+      // A nonzero code is the sidecar declining, and this client cannot tell
+      // "unknown verb" from "the rule failed". Closing rather than retrying
+      // through the daemon is what makes the caller fall back to the direct
+      // command, where a real failure surfaces the same way it always did.
+      this.close();
+      return null;
+    }
+    return reply.result;
+  }
+
+  private start(): ChildProcessWithoutNullStreams | undefined {
+    if (this.child !== undefined) return this.child;
+    if (this.failed) return undefined;
+    let child: ChildProcessWithoutNullStreams;
+    try {
+      child = spawn(
+        this.target.binary,
+        [
+          "lsp-serve",
+          `--cwd=${this.cwd}`,
+          `--tsconfig=${this.tsconfig}`,
+          `--plugins-json=${this.target.manifest}`,
+          ...(this.target.projectContext === undefined
+            ? []
+            : [`--project-context-json=${this.target.projectContext}`]),
+        ],
+        { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+      );
+    } catch {
+      this.failed = true;
+      return undefined;
+    }
+    this.child = child;
+    // The sidecar's stderr is its own diagnostic channel and is not this
+    // client's to interpret; draining it keeps a chatty plugin from filling the
+    // pipe and stalling the daemon it is talking through.
+    child.stderr.resume();
+    child.on("error", () => this.fail());
+    child.on("exit", () => this.fail());
+    this.lines = readline.createInterface({ input: child.stdout });
+    this.lines.on("line", (line) => this.onLine(line));
+    return child;
+  }
+
+  private onLine(line: string): void {
+    const settle = this.pending.shift();
+    if (settle === undefined) return;
+    let reply: IReply;
+    try {
+      reply = JSON.parse(line) as IReply;
+    } catch {
+      settle(null);
+      return;
+    }
+    settle(
+      typeof reply.code === "number"
+        ? { code: reply.code, result: rawResult(line) }
+        : null,
+    );
+  }
+
+  private fail(): void {
+    this.close();
+  }
+}
+
+/** One `lsp-serve` reply: a verb result and the code that qualifies it. */
+interface IReply {
+  code: number;
+  result: string;
+}
+
+/**
+ * The `result` member, as the JSON text this daemon's callers parse.
+ *
+ * A verb's result is arbitrary JSON that the caller decodes itself, so it is
+ * handed back as text rather than as a value — which is what the direct command
+ * hands over, and what keeps the two paths interchangeable. The text is
+ * re-serialized rather than sliced out of the line: the bytes are not identical
+ * to the sidecar's own, but the value they decode to is, and no caller here
+ * reads anything else.
+ *
+ * A reply with no `result` is `"null"`, so a caller parses a value either way
+ * instead of being handed the empty string.
+ */
+function rawResult(line: string): string {
+  const parsed = JSON.parse(line) as { result?: unknown };
+  return parsed.result === undefined ? "null" : JSON.stringify(parsed.result);
+}

package/src/model/loadGraph.ts

@@ -5,6 +5,7 @@ import { captureProcessOutput, ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { TtscGraphMemory } from "./TtscGraphMemory";
+import { publishArtifacts } from "./publishedArtifacts";
 
 /**
  * The dump schema version this client reads.
@@ -18,8 +19,15 @@ import { TtscGraphMemory } from "./TtscGraphMemory";
  * protocol and has to hold it to the same number: the envelope's version and
  * the body's are independent, so a producer can speak this protocol and still
  * send a body from another schema.
+ *
+ * `scripts/assert-ttscgraph-release-candidate.cjs` reads this declaration out
+ * of this file with a regular expression, because it runs against a packaged
+ * binary in a workflow that has no reason to have built this package first.
+ * Rewriting the declaration — adding a type annotation, splitting the line —
+ * makes that script fail loudly rather than silently, and its message names
+ * this constant; update its pattern with any such change.
  */
-export const DUMP_SCHEMA_VERSION = 6;
+export const DUMP_SCHEMA_VERSION = 8;
 
 /**
  * Build the resident {@link TtscGraphMemory} for a project by running `ttscgraph
@@ -67,10 +75,26 @@ export function loadGraph(
   let stdout: string;
   let stderr: string;
   try {
-    result = spawnSync(binary, ["dump", "--cwd", cwd, "--tsconfig", tsconfig], {
-      stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
-      windowsHide: true,
-    });
+    // Ask the project's lint install for the artifacts a citation can name
+    // before the dump runs, so the producer can resolve a documentation target
+    // into a relation rather than leaving it a token. A project with no lint
+    // install, or none that publishes, contributes no file and no claim.
+    const artifacts = publishArtifacts({ cwd, tsconfig });
+    result = spawnSync(
+      binary,
+      [
+        "dump",
+        "--cwd",
+        cwd,
+        "--tsconfig",
+        tsconfig,
+        ...(artifacts.file === null ? [] : ["--artifacts", artifacts.file]),
+      ],
+      {
+        stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
+        windowsHide: true,
+      },
+    );
     stdout = capture.read("stdout");
     stderr = capture.read("stderr");
   } finally {