@polycode-projects/the-mechanical-code-talker 0.2.0

package/src/server.mjs

@@ -0,0 +1,393 @@
+// tmct tool layer — query-only tools over the deterministic typed code-graph
+// artifact (<repo>/.tmct/graph.json). The graph source is a LOCAL file
+// (src/source.mjs) and tmct_search is a LOCAL lexical lookup (no remote API,
+// no LLM, no model calls anywhere). dispatchTool is the single internal switch
+// the chat surface and the `cli <tool>` route call into.
+//
+// Tools (all query-only, bounded output): tmct_search, tmct_describe, tmct_snippet,
+// tmct_impact, plus the §9 read-replacing tools tmct_members, tmct_subclasses,
+// tmct_architecture, tmct_tests_for, tmct_untested, tmct_history, tmct_callers,
+// tmct_callees. Each answers one question in ONE compact call so the caller need not
+// Read/Grep. Errors reach the caller as clean tool errors — message only, never a stack.
+//
+// tmct_ask (hot tool): a mechanical, zero-model-call NL query over the graph —
+// collapses the search+describe+traversal composition loop a caller would
+// otherwise hand-compose into one deterministic round-trip. See ask.mjs.
+
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ToolError } from "./config.mjs";
+import * as defaultSource from "./source.mjs";
+import {
+  parseEntities,
+  resolveSymbol,
+  renderDescribe,
+  renderImpact,
+  renderSearch,
+  siteOf,
+  renderMembers,
+  renderSubclasses,
+  renderArchitecture,
+  renderTestsFor,
+  renderUntested,
+  renderHistory,
+  renderCallers,
+  renderCallees,
+  renderCochanges,
+  renderExports,
+  renderSignature,
+  contextPlan,
+  sizeBundle,
+  bundleMask,
+  trimBundleMask,
+  renderContextMore,
+  renderCalls,
+  callHint,
+  renderFileHistory,
+  renderMethodHistory,
+  renderClassHistory,
+} from "./codegraph.mjs";
+import { ask } from "./ask.mjs";
+
+const SNIPPET_MAX_LINES = 200;
+
+// Tiered tool surface: the hot tools carry full descriptions/schemas in this
+// catalog; every COLD tool (describe/members/impact/history/…) is still served
+// by dispatchTool below and is reachable via the CLI `cli <tool>` route +
+// the generated <repo>/.tmct/TOOLS.md catalog (renderToolsCatalog).
+export const TOOLS = [
+  {
+    name: "tmct_context",
+    // Lean resident schema (re-billed every turn): the minimum that still steers the agent to
+    // ONE call → write, not Read.
+    description:
+      "START HERE to add/modify code: ONE call returns a sized edit bundle (exemplar source, sibling signatures, registration, insertion region) — then write directly, don't Read.",
+    inputSchema: {
+      type: "object",
+      required: ["symbol"],
+      properties: {
+        symbol: { type: "string", description: "Module path (django/utils/text.py) or a sibling function/class name in it (lower)." },
+        depth: { type: "string", enum: ["min", "auto", "full"], default: "auto", description: "auto (sized to the task) | min (leanest) | full (every section)." },
+      },
+    },
+  },
+  {
+    name: "tmct_snippet",
+    description: "EXACT source of one function/class/Class.method by name (its line span only) + a one-line in-repo call hint. Prefer over Read for a single symbol.",
+    inputSchema: {
+      type: "object",
+      required: ["symbol"],
+      properties: {
+        symbol: { type: "string", description: "function/class name (slugify, Truncator), Class.method, or fn:<path>#name." },
+      },
+    },
+  },
+  {
+    name: "tmct_ask",
+    description:
+      "Ask a structural question in plain English: \"which functions call X\", \"what uses X\", \"where is X defined\", \"when did X change\". One call, no model. A clean miss beats a guess.",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: {
+        query: { type: "string", description: "A free-text question, e.g. \"which functions explicitly couple to logging\"." },
+      },
+    },
+  },
+];
+
+async function loadGraph(config, source) {
+  const payload = await source.fetchEntities(config);
+  const graph = parseEntities(payload);
+  if (!graph.individuals.length) {
+    // Honest miss, never a stack: a fresh repo simply has no graph yet (the chat
+    // session itself creates one as the conversation folds in).
+    throw new ToolError(
+      `the graph at ${config.graphFile} is empty — no entities to answer from yet ` +
+        "(this repo starts with no graph; the chat session folds the conversation into one).",
+    );
+  }
+  return graph;
+}
+
+function resolveOrThrow(graph, symbol, what) {
+  const { match, candidates } = resolveSymbol(graph, symbol);
+  if (!match) {
+    throw new ToolError(
+      `no entity matching ${what} "${symbol}" in the code-map graph. ` +
+        "Try a repo-relative path (e.g. django/utils/text.py), a basename, or tmct_search for a fuzzy lookup.",
+    );
+  }
+  return { match, candidates };
+}
+
+/**
+ * Build the tmct_context "edit bundle" for a symbol and return { text, tier, topup }.
+ * Shared by the tmct_context tool AND the `cli digest` arm (cli.mjs), so both
+ * benefit from the size-adaptive sizing for free. `trim:true` (B2) renders a SECONDARY,
+ * signatures-only bundle (no bodies/tails) for related-but-not-primary digest modules.
+ *
+ * Section ORDER is cache-stable (B7): the content that is identical across runs (anchor /
+ * registration / exemplar / siblings / __all__ / insertion region) comes FIRST; the more
+ * variable, history-derived tails (covering tests, co-change) come LAST, so a stable prefix
+ * maximises prompt-cache reuse.
+ */
+export async function buildContextBundle(args, { config, source = defaultSource, trim = false } = {}) {
+  const symbol = String(args?.symbol || "").trim();
+  if (!symbol) throw new ToolError("symbol is required");
+  const depth = String(args?.depth || "auto").trim().toLowerCase();
+  // Tuning-flag contract: `min` forces the LEANEST bundle (TINY mask, no top-up) regardless of
+  // exemplar length; `untuned` reproduces the earlier escalation (tuning #1 bypassed). Neither
+  // → the tuned default (sizeBundle's anchor-gated escalation).
+  const min = Boolean(args?.min);
+  const untuned = Boolean(args?.untuned);
+  // `max` forces the injection CEILING — FULL tier (every section + inlined depth-1 callee
+  // bodies) with top-up, and it OVERRIDES trim so even secondary modules get the full bundle. Used
+  // by the tmct-max arm to test whether more injection re-bloats.
+  const max = Boolean(args?.max);
+  const graph = await loadGraph(config, source);
+  const { match } = resolveOrThrow(graph, symbol, "symbol");
+  const plan = contextPlan(graph, match);
+  // #6/B1/B6: pick the section mask by depth — min forces TINY, full/max forces everything, auto
+  // runs the size classifier (lean TINY default + one-tier top-up when the edit needs it).
+  let tier;
+  let mask;
+  let topup = false;
+  if (min || depth === "min") { tier = "TINY"; mask = bundleMask("TINY"); }
+  else if (max || depth === "full") { tier = "FULL"; mask = bundleMask("FULL"); topup = true; }
+  else ({ tier, mask, topup } = sizeBundle(plan, graph, { untuned }));
+  if (trim && !max) mask = trimBundleMask(mask); // B2: secondary digest module → signatures + region only (max keeps the full bundle)
+  const repoRoot = dirname(dirname(config.graphFile));
+  let lines = null;
+  if (plan.moduleLabel) {
+    try { lines = (await readFile(join(repoRoot, plan.moduleLabel), "utf8")).split("\n"); }
+    catch { lines = null; }
+  }
+  const lineAt = (n) => (lines && lines[n - 1] != null ? lines[n - 1].trim() : "");
+  const sliceBody = (start, end) => {
+    const e = Math.min(lines.length, Math.min(end, start + SNIPPET_MAX_LINES - 1));
+    return lines.slice(start - 1, e).map((l, i) => `${start + i}\t${l}`).join("\n");
+  };
+  const out = [
+    `Edit context for ${plan.moduleLabel} [${tier}${trim ? " secondary" : ""}] — assembled from the typed graph + that file. ` +
+      "You do NOT need to Read it; write the new code directly after reviewing this.",
+  ];
+  // ---- cache-stable prefix (B7): identical across runs ----
+  if (mask.anchor && plan.anchor?.site && lines) {
+    const { start, end } = plan.anchor.site;
+    out.push(`\n## anchor: ${plan.anchor.label} (${plan.anchor.class}) @ ${plan.moduleLabel}:${start}-${end}`);
+    out.push(sliceBody(start, end));
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.registration && plan.globals.length) {
+    out.push(`\n## registration / module globals (replicate this pattern):`);
+    for (const g of plan.globals) out.push(`  ${g.label} = ${g.value}${g.site ? `  [:${g.site.start}]` : ""}`);
+  }
+  if (mask.exemplar && plan.exemplar?.site && lines) {
+    const { start, end } = plan.exemplar.site;
+    const dec = plan.exemplar.decorators ? ` @${plan.exemplar.decorators}` : "";
+    out.push(`\n## closest example (full body) — copy this style: ${plan.exemplar.label} (${plan.exemplar.class})${dec} @ ${plan.moduleLabel}:${start}-${end}`);
+    out.push(sliceBody(start, end));
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.inlinedCallees && plan.calleeBodies.length && lines) {
+    let budget = 120; // INLINE_CALLEE_LOC
+    for (const cb of plan.calleeBodies) {
+      if (budget <= 0) break;
+      const start = cb.site.start;
+      const end = Math.min(cb.site.end, start + budget - 1);
+      const fromThisFile = cb.site.path === plan.moduleLabel;
+      const bodyLines = fromThisFile && lines
+        ? lines
+        : await readFile(join(repoRoot, cb.site.path), "utf8").then((t) => t.split("\n")).catch(() => null);
+      if (!bodyLines) continue;
+      const e = Math.min(bodyLines.length, end);
+      out.push(`\n## inlined callee body (depth-1 in-repo call): ${cb.label} @ ${cb.site.path}:${start}-${cb.site.end}`);
+      out.push(bodyLines.slice(start - 1, e).map((l, i) => `${start + i}\t${l}`).join("\n"));
+      budget -= (e - start + 1);
+    }
+  }
+  if (mask.classMembers && plan.classMembers && plan.classMembers.members.length) {
+    out.push(`\n## members of ${plan.classMembers.className} (the edit likely lives INSIDE this class — copy a member's shape, do not read the class body):`);
+    for (const m of plan.classMembers.members) {
+      const short = String(m.label).split(".").pop();
+      const sig = m.params != null && m.params !== "" ? `(${m.params})${m.returns ? ` -> ${m.returns}` : ""}` : "";
+      const dec = m.decorators ? `@${m.decorators} ` : "";
+      const r = m.raises ? `  raises=${m.raises}` : "";
+      out.push(`  ${m.class} ${short}${m.site ? ` :${m.site.start}` : ""}  ${dec}${short}${sig}${r}`);
+    }
+  }
+  if (mask.siblings && plan.siblings.length) {
+    out.push(`\n## sibling symbols to copy the style of (most relevant first; ${plan.siblings.length} total):`);
+    for (const s of plan.siblings.slice(0, plan.siblingCap)) {
+      const sig = s.site ? lineAt(s.site.start) : "";
+      const dec = s.decorators ? `@${s.decorators} ` : "";
+      const r = s.raises ? `  raises=${s.raises}` : "";
+      out.push(`  ${s.class} ${s.label}${s.site ? ` :${s.site.start}` : ""}  ${dec}${sig}${r}`);
+    }
+    if (plan.siblings.length > plan.siblingCap) {
+      out.push(`  …+${plan.siblings.length - plan.siblingCap} more (use tmct_search kind=function or tmct_snippet <name> for any of them)`);
+    }
+  }
+  if (mask.allExports && plan.allExports) {
+    out.push(`\n## module __all__ — this module curates its public API; ADD your new public symbol to this list so it is importable:\n  ${plan.allExports}`);
+  }
+  if (mask.reexports && plan.exports && plan.exports.length) out.push(`\n## re-exported symbols (resolved __all__ → defining module): ${plan.exports.join(", ")}`);
+  // #2 + B4: the contiguous insertion region is part of the STABLE prefix — always present
+  // (even at TINY) so the agent never needs to Read the file to place the edit.
+  if (mask.insertionRegion && plan.insertionRegion && lines) {
+    const start = plan.insertionRegion.start;
+    const end = Math.min(lines.length, start + 40 - 1); // INSERTION_REGION_CAP
+    out.push(`\n## insertion region (write your new sibling here) — ${plan.moduleLabel}:${start}-${end}`);
+    out.push(lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join("\n"));
+  } else if (plan.insertion) {
+    out.push(`\n## insert the new sibling after line ~${plan.insertion} (end of the last top-level definition).`);
+  }
+  // ---- variable tail (B7): history-derived, kept LAST so the prefix stays cache-stable ----
+  if (mask.tests && plan.tests.length) out.push(`\n## covering tests: ${plan.tests.join(", ")}`);
+  if (mask.cochange && plan.cochange && plan.cochange.length) {
+    out.push(`\n## usually changed together (consider editing these too): ${plan.cochange.map((c) => `${c.label} (×${c.weight})`).join(", ")}`);
+  }
+  out.push(`\nYou now have the snippet, the sibling style, the registration anchor and the tests. ` +
+    `Write the new code with Edit/Write — do NOT Read ${plan.moduleLabel}.`);
+  if (tier !== "FULL") {
+    out.push(`(bundle tier ${tier}; for any omitted sections run tmct_context_more {"symbol":"${symbol}"}, or tmct_context with depth="full".)`);
+  }
+  return { text: out.join("\n"), tier, topup };
+}
+
+export async function dispatchTool(name, args, { config, source = defaultSource } = {}) {
+  if (name === "tmct_context") {
+    return (await buildContextBundle(args, { config, source })).text;
+  }
+  if (name === "tmct_context_more") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    return renderContextMore(contextPlan(graph, match));
+  }
+  if (name === "tmct_describe") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
+    return renderDescribe(graph, match, { candidates });
+  }
+  if (name === "tmct_snippet") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
+    const site = siteOf(match);
+    if (!site) {
+      throw new ToolError(
+        `"${match.label}" (${match.class || "Entity"}) has no source span in the graph — ` +
+          "it is likely a module. Use tmct_describe for its contents, then tmct_snippet one of the functions/classes it defines.",
+      );
+    }
+    // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json)
+    const repoRoot = dirname(dirname(config.graphFile));
+    const abs = join(repoRoot, site.path);
+    let text;
+    try { text = await readFile(abs, "utf8"); }
+    catch (e) { throw new ToolError(`could not read ${site.path} (${e?.code || e?.message || e})`); }
+    const lines = text.split("\n");
+    const start = Math.max(1, site.start);
+    let end = Math.min(lines.length, site.end);
+    let truncated = false;
+    if (end - start + 1 > SNIPPET_MAX_LINES) { end = start + SNIPPET_MAX_LINES - 1; truncated = true; }
+    const body = lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join("\n");
+    const span = site.end > site.start ? `${site.start}-${site.end}` : `${site.start}`;
+    const header = `${match.label} — ${match.class || "Entity"} @ ${site.path}:${span}`;
+    const note = truncated ? `\n… (truncated to ${SNIPPET_MAX_LINES} lines; full span ${span})` : "";
+    const cand = candidates.length ? `\n(other matches: ${candidates.map((c) => c.label).join(", ")})` : "";
+    const hint = callHint(graph, match); // #4: one-line "calls in-repo: …" so the agent sees in-repo deps inline
+    return `${header}\n${body}${note}${hint ? `\n${hint}` : ""}${cand}`;
+  }
+  if (name === "tmct_signature") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    return renderSignature(graph, match);
+  }
+  if (name === "tmct_impact") {
+    const module = String(args?.module || "").trim();
+    if (!module) throw new ToolError("module is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, module, "module");
+    return renderImpact(graph, match);
+  }
+  if (name === "tmct_search") {
+    const query = String(args?.query || "").trim();
+    const kind = String(args?.kind || "").trim();
+    if (!query && !kind) throw new ToolError("query is required");
+    const graph = await loadGraph(config, source);
+    return renderSearch(graph, query, {
+      kind,
+      decorator: String(args?.decorator || "").trim(),
+      name: String(args?.name || "").trim(),
+    });
+  }
+  if (name === "tmct_members") {
+    const symbol = String(args?.class || "").trim();
+    if (!symbol) throw new ToolError("class is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "class");
+    return renderMembers(graph, match);
+  }
+  if (name === "tmct_subclasses") {
+    const symbol = String(args?.class || "").trim();
+    if (!symbol) throw new ToolError("class is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "class");
+    return renderSubclasses(graph, match);
+  }
+  if (name === "tmct_architecture") {
+    const graph = await loadGraph(config, source);
+    return renderArchitecture(graph, { pkg: String(args?.package || "").trim() });
+  }
+  if (name === "tmct_exports") {
+    const module = String(args?.module || "").trim();
+    if (!module) throw new ToolError("module is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, module, "module");
+    return renderExports(graph, match);
+  }
+  if (name === "tmct_untested") {
+    const graph = await loadGraph(config, source);
+    return renderUntested(graph);
+  }
+  if (name === "tmct_ask") {
+    const query = String(args?.query || "").trim();
+    if (!query) throw new ToolError("query is required");
+    const graph = await loadGraph(config, source);
+    const { content, tmct_ask } = ask(graph, query);
+    // Every dispatchTool caller (the chat surface, the CLI fallback) expects a plain string —
+    // append the structured envelope as a delimited, machine-parseable block rather than
+    // changing that shared contract for one tool. PLAN_MECHANICAL_CHAT.md §6.2.
+    return `${content}\n\n---tmct_ask---\n${JSON.stringify(tmct_ask, null, 2)}`;
+  }
+  if (
+    name === "tmct_tests_for" || name === "tmct_history" || name === "tmct_callers" ||
+    name === "tmct_callees" || name === "tmct_cochanges" || name === "tmct_calls" ||
+    name === "tmct_file_history" || name === "tmct_method_history" || name === "tmct_class_history"
+  ) {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    if (name === "tmct_tests_for") return renderTestsFor(graph, match);
+    if (name === "tmct_history") return renderHistory(graph, match);
+    if (name === "tmct_callers") return renderCallers(graph, match);
+    if (name === "tmct_cochanges") return renderCochanges(graph, match);
+    if (name === "tmct_calls") return renderCalls(graph, match);
+    if (name === "tmct_file_history") return renderFileHistory(graph, match);
+    if (name === "tmct_method_history") return renderMethodHistory(graph, match);
+    if (name === "tmct_class_history") return renderClassHistory(graph, match);
+    return renderCallees(graph, match);
+  }
+  throw new ToolError(`unknown tool: ${name}`);
+}
+

package/src/sessions.mjs

@@ -0,0 +1,220 @@
+// sessions.mjs — chat sessions as first-class temporal graph data, like commits.
+//
+// A `tmct chat` session leaves two artifacts under the target repo:
+//   .tmct/session-<uuidv7>.log            — the human-readable transcript (chat.mjs)
+//   .tmct/sessions/session-<uuidv7>.jsonl — the STRUCTURED sidecar this module owns:
+//     {"type":"session", id, started, repo, tmctVersion}        (header line)
+//     {"type":"turn", ts, query, resolvedIds, answeredIds, miss}  (one per turn, flushed)
+//     {"type":"end", ts}                                          (clean close marker)
+//
+// From the sidecar the session enters the typed graph twice:
+//   - READ TIME (chat.mjs, per turn): appendSessionToGraph() upserts one `Session`
+//     individual (`session:<uuidv7>`) + `mgx:asksAbout` edges into graph.json —
+//     atomically (temp + rename), re-reading the file first so a re-index that
+//     happened mid-session is tolerated: edges whose targets vanished are dropped,
+//     never left dangling (honest degradation).
+//   - REBUILD (any future graph writer): readSessionRecords() + foldInSessions()
+//     re-attach every recorded session to a FRESH graph, re-resolving each recorded
+//     entity id (by id first, then by unique label derived from the id shape);
+//     unresolvable references are dropped and counted on the session node
+//     (mgx:sessionDroppedEdges) — never a guessed edge.
+//
+// Sessions are runtime observations, not source derivations: they record what a human
+// asked the graph about and which entities answered, so re-indexing re-attaches them
+// rather than re-deriving them from source.
+
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export const SESSIONS_DIR_REL = join(".tmct", "sessions");
+
+export const SESSION_CLASS = "Session";
+export const ASKS_ABOUT_PREDICATE = "asksAbout";
+export const ASKS_ABOUT_PROP = "mgx:asksAbout";
+
+const QUERIES_ATTR_CAP = 500; // joined-queries attribute cap (mirrors commitMessage's cap idea)
+
+/** Session labels mirror Commit's short-sha convention: the uuid's leading time-ordered hex. */
+const sessionLabel = (id) => String(id).slice(0, 8);
+
+/** Best-effort label a recorded entity id would carry, derived from the id shape —
+ *  the "then by label" tier of fold-in re-resolution (ids are `mod:<path>`,
+ *  `fn:<path>#<name>`, `commit:<sha>`; labels are path / name / short sha). */
+function labelFromId(id) {
+  const s = String(id);
+  if (s.startsWith("mod:")) return s.slice(4);
+  const fn = s.match(/^fn:.*#(.+)$/);
+  if (fn) return fn[1];
+  if (s.startsWith("commit:")) return s.slice(7, 19);
+  return null;
+}
+
+/** Atomic JSON write: temp file in the same directory + rename, so a concurrent
+ *  reader never sees a torn graph.json and a crash never destroys the old one. */
+async function atomicWriteJson(file, obj) {
+  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  await writeFile(tmp, JSON.stringify(obj));
+  await rename(tmp, file);
+}
+
+/**
+ * Upsert one session record into an `entities` payload (mutates; pure of I/O).
+ * Shared by the read-time append AND the re-index fold-in, so both resolve and
+ * degrade identically:
+ *   - a prior copy of the same session (per-turn re-appends) is replaced;
+ *   - every recorded ref resolves by id, else by UNIQUE label (ambiguous → drop);
+ *   - dropped refs are counted on the session node, never guessed into edges.
+ * Record shape: { id, started, ended?, turns: [{ts, query, resolvedIds, answeredIds, miss}] }.
+ * Returns { kept, dropped }.
+ */
+export function upsertSession(entities, record) {
+  const sid = `session:${record.id}`;
+  entities.individuals ||= [];
+  entities.objectProperties ||= [];
+
+  // replace any prior copy of this session (read-time appends run once per turn)
+  entities.individuals = entities.individuals.filter((i) => i?.id !== sid);
+  let group = entities.objectProperties.find((g) => g?.prop === ASKS_ABOUT_PROP);
+  if (group) {
+    group.examples = (group.examples || []).filter((e) => e?.subject !== sid);
+  } else {
+    group = { predicate: ASKS_ABOUT_PREDICATE, prop: ASKS_ABOUT_PROP, count: 0, examples: [] };
+    entities.objectProperties.push(group);
+  }
+
+  // resolve refs against the CURRENT individuals — by id, then by unique label
+  const byId = new Map();
+  const byLabel = new Map(); // label -> id, or null when ambiguous
+  for (const i of entities.individuals) {
+    if (!i?.id) continue;
+    byId.set(i.id, i);
+    if (i.label) byLabel.set(i.label, byLabel.has(i.label) ? null : i.id);
+  }
+  const turns = Array.isArray(record.turns) ? record.turns : [];
+  const refs = [...new Set(turns.flatMap((t) => [...(t?.resolvedIds || []), ...(t?.answeredIds || [])]))];
+  const targets = [];
+  let dropped = 0;
+  for (const ref of refs) {
+    if (byId.has(ref)) { targets.push(ref); continue; }
+    const cand = labelFromId(ref);
+    const viaLabel = cand ? byLabel.get(cand) : undefined;
+    if (viaLabel) { targets.push(viaLabel); continue; }
+    dropped += 1; // vanished or ambiguous — an honest drop, never a dangling/guessed edge
+  }
+
+  const started = record.started || "";
+  const ended = record.ended || turns.at(-1)?.ts || started;
+  const queries = turns.map((t) => String(t?.query || "")).filter(Boolean);
+  const label = sessionLabel(record.id);
+  entities.individuals.push({
+    id: sid, label, class: SESSION_CLASS,
+    derived_from: [], mentions: [],
+    attributes: [
+      { prop: "mgx:sessionStarted", key: "started", value: started },
+      { prop: "mgx:sessionEnded", key: "ended", value: ended },
+      { prop: "mgx:sessionTurns", key: "turns", value: String(turns.length) },
+      ...(queries.length ? [{ prop: "mgx:sessionQueries", key: "queries", value: queries.join(" | ").slice(0, QUERIES_ATTR_CAP) }] : []),
+      ...(dropped ? [{ prop: "mgx:sessionDroppedEdges", key: "dropped", value: String(dropped) }] : []),
+    ],
+  });
+  for (const t of targets) {
+    group.examples.push({ subject: sid, object: t, subjectLabel: label, objectLabel: byId.get(t)?.label || t });
+  }
+  group.count = group.examples.length;
+
+  // classes[] + vocabulary[] entries appear ONLY once a session exists, so a
+  // session-less graph stays byte-identical to what buildEntities always produced.
+  const sessions = entities.individuals.filter((i) => i.class === SESSION_CLASS);
+  if (Array.isArray(entities.classes)) {
+    let cls = entities.classes.find((c) => c?.name === SESSION_CLASS);
+    if (!cls) { cls = { name: SESSION_CLASS, count: 0, sample: [] }; entities.classes.push(cls); }
+    cls.count = sessions.length;
+    cls.sample = sessions.slice(0, 3).map((i) => i.label);
+  }
+  if (Array.isArray(entities.vocabulary) && !entities.vocabulary.some((v) => v?.prop === ASKS_ABOUT_PROP)) {
+    entities.vocabulary.push({
+      prop: ASKS_ABOUT_PROP, predicate: ASKS_ABOUT_PREDICATE,
+      note: "chat Session → entity a turn resolved/answered with; runtime observation, owned (no SEON term)",
+    });
+  }
+  return { kept: targets.length, dropped };
+}
+
+/** Read-time append (chat.mjs, once per turn): re-read graph.json FRESH (a re-index
+ *  may have replaced it mid-session), upsert, write back atomically. A MISSING
+ *  artifact is the empty-graph bootstrap: seed a minimal valid payload so the
+ *  conversation itself becomes the first graph write. Still throws on an invalid
+ *  (unparseable) artifact — the caller treats the append as best-effort. */
+export async function appendSessionToGraph(graphFile, record) {
+  let text = null;
+  try {
+    text = await readFile(graphFile, "utf8");
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+  }
+  let entities;
+  if (text === null) {
+    entities = { generated_at: "", classes: [], vocabulary: [], objectProperties: [], individuals: [], proseIndex: {} };
+    await mkdir(dirname(graphFile), { recursive: true });
+  } else {
+    entities = JSON.parse(text);
+  }
+  const res = upsertSession(entities, record);
+  await atomicWriteJson(graphFile, entities);
+  return res;
+}
+
+/** Parse one sidecar .jsonl into a session record (null if no valid header).
+ *  Torn/partial trailing lines (a killed session) are skipped, not fatal. */
+export function parseSessionJsonl(text) {
+  let header = null;
+  let ended = "";
+  const turns = [];
+  const arr = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+  for (const line of String(text).split("\n")) {
+    const s = line.trim();
+    if (!s) continue;
+    let rec;
+    try { rec = JSON.parse(s); } catch { continue; }
+    if (rec?.type === "session" && !header) header = rec;
+    else if (rec?.type === "turn") {
+      turns.push({
+        ts: String(rec.ts || ""), query: String(rec.query || ""),
+        resolvedIds: arr(rec.resolvedIds), answeredIds: arr(rec.answeredIds), miss: !!rec.miss,
+      });
+    } else if (rec?.type === "end") ended = String(rec.ts || "") || ended;
+  }
+  if (!header?.id) return null;
+  return { id: String(header.id), started: String(header.started || ""), ended, turns };
+}
+
+/** All recorded sessions under <rootDir>/.tmct/sessions/*.jsonl, oldest first
+ *  (uuidv7 filenames sort chronologically). Best-effort: no dir → []. */
+export async function readSessionRecords(rootDir) {
+  const dir = join(rootDir, SESSIONS_DIR_REL);
+  let names;
+  try { names = await readdir(dir); } catch { return []; }
+  const records = [];
+  for (const name of names.filter((n) => n.endsWith(".jsonl")).sort()) {
+    try {
+      const rec = parseSessionJsonl(await readFile(join(dir, name), "utf8"));
+      if (rec) records.push(rec);
+    } catch { /* unreadable sidecar — skip, never fail an index run */ }
+  }
+  return records;
+}
+
+/** Re-index fold-in: attach every recorded session to a FRESH entities payload.
+ *  Sessions are runtime observations, not source derivations — they are re-attached
+ *  after the source-derived build, with every reference re-resolved against the new
+ *  graph (upsertSession's id-then-label tiers; unresolvable → dropped + counted). */
+export function foldInSessions(entities, records) {
+  let kept = 0;
+  let dropped = 0;
+  for (const rec of records || []) {
+    const r = upsertSession(entities, rec);
+    kept += r.kept;
+    dropped += r.dropped;
+  }
+  return { sessions: (records || []).length, kept, dropped };
+}

package/src/source.mjs

@@ -0,0 +1,54 @@
+// Local graph source — the offline replacement for marginalia's HTTP/A2A `api`
+// layer. The tool layer takes this as an injectable dependency (so tests can
+// stub it); in production it reads the JSON artifact the deterministic indexer
+// wrote to config.graphFile. No network, no model calls.
+
+import { readFile } from "node:fs/promises";
+import { ToolError } from "./config.mjs";
+
+let cache = null; // { file, payload } — one artifact per process; cheap re-reads.
+
+export function clearCache() {
+  cache = null;
+}
+
+/** The empty-graph bootstrap payload: what a repo with no artifact "contains".
+ *  Shaped exactly like a buildEntities payload so parseEntities and the session
+ *  upsert treat it as a normal (just empty) graph. `bootstrap: true` marks it. */
+export function emptyEntities() {
+  return {
+    generated_at: "",
+    bootstrap: true,
+    classes: [],
+    vocabulary: [],
+    objectProperties: [],
+    individuals: [],
+    proseIndex: {},
+  };
+}
+
+/** Read + parse the local graph artifact. Cached per file for the process.
+ *  A MISSING artifact (ENOENT) is not an error: the chat surface starts from an
+ *  empty graph and the first session fold-in creates the file — so we return the
+ *  bootstrap payload (uncached, so the freshly written file is picked up next
+ *  fetch). Every other failure still throws a clean ToolError. */
+export async function fetchEntities(config) {
+  if (cache && cache.file === config.graphFile) return cache.payload;
+  let text;
+  try {
+    text = await readFile(config.graphFile, "utf8");
+  } catch (e) {
+    if (e?.code === "ENOENT") return emptyEntities();
+    throw new ToolError(
+      `cannot read graph artifact at ${config.graphFile} (${e?.code || e?.message || e})`,
+    );
+  }
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new ToolError(`graph artifact ${config.graphFile} is not valid JSON`);
+  }
+  cache = { file: config.graphFile, payload };
+  return payload;
+}