@polycode-projects/the-mechanical-code-talker 0.3.0 → 0.5.0

package/src/repository-interface.mjs

@@ -0,0 +1,318 @@
+// The Repository Interface — tmct's OWNED, versioned contract between "interpret
+// the query" (tmct, the brittle side) and "ask the graph for truth" (a provider,
+// the stable side). PLAN_REPOSITORY_INTERFACE.md.
+//
+// tmct defines and versions this shape; a provider (seonix, a fixture, a browser
+// page) IMPLEMENTS it over its native graph. Both sides already agree on the
+// TYPES — every Individual.class is a `tmct:` class and every Edge.predicate a
+// `tmct:` object property (ontology/tmct-core.ttl is the type dictionary) — so
+// the interface only names the OPERATIONS over those shared types.
+//
+// The error contract is the load-bearing rule: a clean miss is a first-class
+// RETURN VALUE from a small CLOSED set of reasons (MISS_REASONS), never a throw.
+// Presentation (the render* layer, the chat surface) lives on tmct's side of the
+// seam and turns these typed results into prose; the interface returns data.
+//
+// This module is pure data + tiny constructors — no fs, no graph, no LLM.
+
+/** SemVer of the interface. Additive-by-default: new services / optional args are
+ *  minor bumps; the suite for version N stays green under N+1. A breaking change
+ *  is a new MAJOR with its own suite (see the versioning policy in the plan). */
+export const INTERFACE_VERSION = "1.0.0";
+
+/** The OWL vocabulary the types are grounded in. */
+export const ONTOLOGY_IRI = "urn:tmct:core";
+
+/**
+ * The CLOSED set of miss reasons. A service that cannot answer returns
+ * `miss(reason, detail)` with `reason` drawn from exactly these — the interpreter
+ * renders the reason, never free-text error prose.
+ *
+ * - UNRESOLVED_TERM   the term named no individual in the graph.
+ * - CAPABILITY_ABSENT the provider does not implement this service (negotiated away).
+ * - TRUNCATED_GRAPH   the answer exists but the provider shipped a truncated sample.
+ * - NO_SOURCE         a source-reaching service, but the provider exposes no working tree.
+ */
+export const MISS_REASONS = Object.freeze({
+  UNRESOLVED_TERM: "UNRESOLVED_TERM",
+  CAPABILITY_ABSENT: "CAPABILITY_ABSENT",
+  TRUNCATED_GRAPH: "TRUNCATED_GRAPH",
+  NO_SOURCE: "NO_SOURCE",
+});
+
+/** The closed vocabulary of edge kinds `edges(id, kind)` traverses, each aligned
+ *  to a `tmct:` object property (ontology/tmct-core.ttl). Symbol-granular kinds
+ *  (callsSymbol/touchesSymbol) stay separate from module-coarse calls/touches. */
+export const EDGE_KINDS = Object.freeze([
+  "imports", "calls", "callsSymbol", "defines", "tests",
+  "touches", "touchesSymbol", "contains", "inherits", "cochange", "reexports",
+]);
+
+/** edge-kind → the `tmct:` object property it realizes (the OWL grounding). */
+export const EDGE_KIND_TO_TMCT = Object.freeze({
+  imports: "tmct:imports",
+  calls: "tmct:calls",
+  callsSymbol: "tmct:calls",
+  defines: "tmct:defines",
+  tests: "tmct:covers",
+  touches: "tmct:touches",
+  touchesSymbol: "tmct:touches",
+  contains: "tmct:contains",
+  inherits: "tmct:extends",
+  cochange: "tmct:dependsOn",
+  reexports: "tmct:exports",
+});
+
+/** The named services, grouped as in the plan's six-group inventory. Names are
+ *  the interface's stable identifiers; a provider advertises which it implements
+ *  as its `capabilities`. `source: true` marks the working-tree-reaching services
+ *  a graph-only provider may satisfy with an honest NO_SOURCE miss. */
+export const SERVICE_GROUPS = Object.freeze({
+  resolution: ["resolve", "describe", "members", "subclasses", "exports", "signature"],
+  traversal: ["edges", "impact"],
+  source: ["snippet", "context"],
+  aggregate: ["architecture", "untested", "stats"],
+  temporal: ["history"],
+  search: ["search", "ask"],
+});
+
+/** Flat list of every service name. */
+export const SERVICES = Object.freeze(
+  Object.values(SERVICE_GROUPS).flat(),
+);
+
+/** The subset that reaches past the graph into a working tree. */
+export const SOURCE_SERVICES = Object.freeze(new Set(SERVICE_GROUPS.source));
+
+// ---- result constructors — the honest-miss ethos as tiny values --------------
+
+/** A successful result carrying typed `value`. */
+export function hit(value) {
+  return { ok: true, value };
+}
+
+/** A first-class miss: `reason` ∈ MISS_REASONS, optional `detail` (free text for
+ *  the human render) and `term` (what was looked up). Never thrown. */
+export function miss(reason, { detail = "", term = null } = {}) {
+  if (!MISS_REASONS[reason]) {
+    throw new TypeError(`miss(): unknown reason "${reason}" (not in MISS_REASONS)`);
+  }
+  return { ok: false, miss: { reason, detail, term } };
+}
+
+export const isHit = (r) => Boolean(r && r.ok === true);
+export const isMiss = (r) => Boolean(r && r.ok === false);
+
+// ---- type projections — raw graph rows → the interface's shared shapes --------
+
+/**
+ * Project a raw graph individual to the interface `Individual`:
+ *   { id, label, class, attributes: [{ key, value, prop }] }
+ * `class` is a `tmct:` class token; `attributes[].prop` is the SEON/mgx token the
+ * value was asserted under (OWL grounding preserved). Pure; tolerant of partials.
+ * @returns {Individual|null}
+ */
+export function toIndividual(ind) {
+  if (!ind || !ind.id) return null;
+  return {
+    id: String(ind.id),
+    label: ind.label != null ? String(ind.label) : String(ind.id),
+    class: ind.class || "Entity",
+    attributes: (Array.isArray(ind.attributes) ? ind.attributes : []).map((a) => ({
+      key: a.key,
+      value: a.value,
+      prop: a.prop || null,
+    })),
+  };
+}
+
+/**
+ * Project a raw relation edge to the interface `Edge`:
+ *   { subject, object, predicate, prop, subjectLabel?, objectLabel?, weight? }
+ * The required quartet is subject/object/predicate/prop; labels/weight are
+ * additive conveniences a provider MAY carry.
+ * @returns {Edge}
+ */
+export function toEdge(rawEdge, { predicate = "", prop = null } = {}) {
+  const e = {
+    subject: rawEdge.subject,
+    object: rawEdge.object,
+    predicate,
+    prop: prop || null,
+  };
+  if (rawEdge.subjectLabel != null) e.subjectLabel = rawEdge.subjectLabel;
+  if (rawEdge.objectLabel != null) e.objectLabel = rawEdge.objectLabel;
+  if (rawEdge.weight != null) e.weight = rawEdge.weight;
+  return e;
+}
+
+// ---- capability negotiation — CAPABILITY_ABSENT as a value, not a wall --------
+
+/**
+ * Invoke a service through capability negotiation. If the provider does not
+ * advertise `service` in `svc.capabilities`, return `miss(CAPABILITY_ABSENT)`
+ * rather than throwing — the interpreter degrades the query, never errors. When
+ * present, calls `svc[service](...args)` and returns its result verbatim.
+ *
+ * This is how a host calls an interface it cannot assume is complete; the
+ * reference providers implement every service, so they never trip it.
+ */
+export function invoke(svc, service, ...args) {
+  const caps = svc && svc.capabilities;
+  const has = Array.isArray(caps) ? caps.includes(service) : caps instanceof Set ? caps.has(service) : false;
+  if (!has || typeof svc[service] !== "function") {
+    return miss(MISS_REASONS.CAPABILITY_ABSENT, { detail: `service "${service}" is not implemented by this provider` });
+  }
+  return svc[service](...args);
+}
+
+// ---- the MACHINE-READABLE SHAPE ----------------------------------------------
+// A single JSON-serializable object enumerating every service, its args, result
+// type, and possible misses. tmct OWNS and versions this; docs/repository-
+// interface.md is the prose peer and docs/repository-interface.schema.json is the
+// committed serialization (the contract suite asserts they agree — no drift).
+
+const IND = "Individual";
+const EDGE = "Edge";
+
+/** Concurrency note shared by every read service: safe across handles — the graph
+ *  is read-only truth and the only mutable state is the caller-owned session
+ *  handle, never touched here. Proven by the suite's concurrent-session cases. */
+const CONCURRENT_SAFE = "concurrent-safe: reads immutable graph truth; no shared mutable state";
+
+export const REPOSITORY_INTERFACE = Object.freeze({
+  version: INTERFACE_VERSION,
+  ontology: ONTOLOGY_IRI,
+  missReasons: Object.values(MISS_REASONS),
+  edgeKinds: [...EDGE_KINDS],
+  types: {
+    Individual: {
+      fields: {
+        id: "string (opaque provider id)",
+        label: "string (human/display name)",
+        class: "string — a tmct: class token (module|class|function|method|attribute|variable|commit|test|…)",
+        attributes: "Array<{ key: string, value: string, prop: string|null }> — prop is the SEON/mgx token grounding the value",
+      },
+    },
+    Edge: {
+      fields: {
+        subject: "string (individual id)",
+        object: "string (individual id)",
+        predicate: "string — the relation predicate",
+        prop: "string|null — the SEON/mgx property token; see edgeKinds → tmct: mapping",
+        subjectLabel: "string? (additive)",
+        objectLabel: "string? (additive)",
+        weight: "number? (additive; e.g. cochange coupling)",
+      },
+    },
+    Result: { shape: "{ ok: true, value: T } | { ok: false, miss: Miss }" },
+    Miss: { shape: "{ reason: MISS_REASONS, detail: string, term: string|null }" },
+  },
+  capabilitiesModel:
+    "A provider advertises `capabilities: string[]` (service names it implements). " +
+    "A service outside the set is negotiated away to miss(CAPABILITY_ABSENT) — never an error. " +
+    "Source services (snippet, context) may be advertised yet answer miss(NO_SOURCE) when no working tree exists.",
+  services: {
+    resolve: {
+      group: "resolution", args: { term: "string" },
+      result: `{ match: ${IND}, candidates: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The resolveSymbol seam: map a free term to an individual + runner-up candidates. Every id-taking service consumes a resolved id.",
+    },
+    describe: {
+      group: "resolution", args: { id: "string" },
+      result: `{ individual: ${IND}, out: ${EDGE}[], incoming: ${EDGE}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "Full typed portrait of one individual: its attributes and its outgoing/incoming edges.",
+    },
+    members: {
+      group: "resolution", args: { classId: "string" },
+      result: `{ methods: ${IND}[], attributes: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "A class's methods + attributes (via the contains relation) — replaces reading the class body.",
+    },
+    subclasses: {
+      group: "resolution", args: { classId: "string" },
+      result: `{ bases: ${IND}[], subclasses: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "Forward bases + the transitive reverse inheritance closure (who extends this).",
+    },
+    exports: {
+      group: "resolution", args: { moduleId: "string" },
+      result: `{ exports: ${IND}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "A module's curated public API (resolved __all__ / re-exports).",
+    },
+    signature: {
+      group: "resolution", args: { id: "string" },
+      result: "{ id, label, class, params, returns, raises, decorators, doc, selfFields, flags }",
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The compact API surface of a symbol without its body.",
+    },
+    edges: {
+      group: "traversal", args: { id: "string", kind: "EDGE_KINDS member" },
+      result: `{ kind: string, edges: ${EDGE}[] }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "Outgoing edges of one closed kind from an individual (an honest empty array is not a miss).",
+      note: "An unknown kind (outside EDGE_KINDS) is a programming error and throws TypeError, not a miss.",
+    },
+    impact: {
+      group: "traversal", args: { moduleId: "string" },
+      result: `{ total: number, levels: Array<Array<{ id, label, via, tests }>> }`,
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The transitive dependent closure the interpreter cannot compute without provider truth.",
+    },
+    snippet: {
+      group: "source", args: { id: "string" },
+      result: "{ path: string, span: { start, end }, body: string|null }",
+      misses: ["UNRESOLVED_TERM", "NO_SOURCE"], concurrency: CONCURRENT_SAFE,
+      purpose: "The exact source span of a symbol. A provider with no working tree returns miss(NO_SOURCE) honestly.",
+    },
+    context: {
+      group: "source", args: { symbol: "string", depth: "min|auto|full?" },
+      result: "{ text: string, tier: string } (a sized edit bundle)",
+      misses: ["UNRESOLVED_TERM", "NO_SOURCE"], concurrency: CONCURRENT_SAFE,
+      purpose: "The composed edit bundle (exemplar, siblings, registration, insertion region). Source-reaching.",
+    },
+    architecture: {
+      group: "aggregate", args: { package: "string?" },
+      result: "{ modules: number, packages: Array<[dir, count]>, hubs: Array<{ id, label, importers }> }",
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Package/module shape + the most-imported hub modules. Optional package prefix scopes it.",
+    },
+    untested: {
+      group: "aggregate", args: {},
+      result: `{ modules: ${IND}[] }`,
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Modules with no covering test module (via the tests relation).",
+    },
+    stats: {
+      group: "aggregate", args: {},
+      result: "{ total: number, classes: Array<{ class: string, count: number }>, truncated: boolean }",
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Per-tmct:class individual counts, read straight from the payload.",
+    },
+    history: {
+      group: "temporal", args: { id: "string" },
+      result: "{ commits: Array<{ id, label, author, date, message }> }",
+      misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
+      purpose: "The commits that touched an individual (tmct:commit individuals via tmct:touches).",
+    },
+    search: {
+      group: "search", args: { query: "string", kind: "string?", name: "string?", decorator: "string?" },
+      result: `{ results: ${IND}[] }`,
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "Lexical, provider-local locate. An empty result set is honest, not a miss.",
+    },
+    ask: {
+      group: "search", args: { query: "string" },
+      result: "{ content: string, tmct_ask: object } (the composed NL round-trip envelope)",
+      misses: [], concurrency: CONCURRENT_SAFE,
+      purpose: "The mechanical, zero-model NL query over the graph — tmct's whole reason to exist.",
+    },
+  },
+});
+
+/** Freeze-deep helper is unnecessary; REPOSITORY_INTERFACE is treated as read-only
+ *  data. Exported so the contract suite and docs generator share one source. */
+export default REPOSITORY_INTERFACE;

package/src/server.mjs

@@ -48,6 +48,7 @@ import {
   renderClassHistory,
 } from "./codegraph.mjs";
 import { ask } from "./ask.mjs";
+import { createGraphService } from "./providers/graph-service.mjs";
 
 const SNIPPET_MAX_LINES = 200;
 
@@ -66,7 +67,7 @@ export const TOOLS = [
       type: "object",
       required: ["symbol"],
       properties: {
-        symbol: { type: "string", description: "Module path (django/utils/text.py) or a sibling function/class name in it (lower)." },
+        symbol: { type: "string", description: "Module path (e.g. path/to/module) or a sibling function/class name defined in it." },
         depth: { type: "string", enum: ["min", "auto", "full"], default: "auto", description: "auto (sized to the task) | min (leanest) | full (every section)." },
       },
     },
@@ -78,7 +79,7 @@ export const TOOLS = [
       type: "object",
       required: ["symbol"],
       properties: {
-        symbol: { type: "string", description: "function/class name (slugify, Truncator), Class.method, or fn:<path>#name." },
+        symbol: { type: "string", description: "function/class name, Class.method, or fn:<path>#name." },
       },
     },
   },
@@ -110,12 +111,17 @@ async function loadGraph(config, source) {
   return graph;
 }
 
-function resolveOrThrow(graph, symbol, what) {
-  const { match, candidates } = resolveSymbol(graph, symbol);
+// Resolution + the miss→ToolError bridge, threaded through the typed service
+// object (createGraphService). The service is the named seam; tmct's own
+// presentation (render*) reads its raw graph (svc.graph) and formats. A clean
+// miss on the interface becomes the instructive ToolError the CLI/chat expect —
+// message-only, never a stack, no fabricated entity names (generic placeholder).
+function resolveOrThrow(svc, symbol, what) {
+  const { match, candidates } = resolveSymbol(svc.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.",
+        "Try a repo-relative path (e.g. path/to/module), a basename, or tmct_search for a fuzzy lookup.",
     );
   }
   return { match, candidates };
@@ -146,7 +152,8 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   // 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 svc = createGraphService(graph);
+  const { match } = resolveOrThrow(svc, 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).
@@ -256,29 +263,48 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   return { text: out.join("\n"), tier, topup };
 }
 
+// The full set of tool names dispatchTool serves (hot catalog + cold tools). Used
+// to reject an unknown tool before any graph load.
+const DISPATCH_TOOLS = new Set([
+  "tmct_context", "tmct_context_more", "tmct_describe", "tmct_snippet", "tmct_signature",
+  "tmct_impact", "tmct_search", "tmct_members", "tmct_subclasses", "tmct_architecture",
+  "tmct_exports", "tmct_untested", "tmct_ask", "tmct_tests_for", "tmct_history",
+  "tmct_callers", "tmct_callees", "tmct_cochanges", "tmct_calls",
+  "tmct_file_history", "tmct_method_history", "tmct_class_history",
+]);
+
 export async function dispatchTool(name, args, { config, source = defaultSource } = {}) {
+  // tmct_context builds (and loads) its own edit bundle — return early so we don't
+  // double-load the graph for it.
   if (name === "tmct_context") {
     return (await buildContextBundle(args, { config, source })).text;
   }
+  // Reject an unknown tool BEFORE touching the graph — preserves the original
+  // ordering (an unknown name never triggers a load).
+  if (!DISPATCH_TOOLS.has(name)) throw new ToolError(`unknown tool: ${name}`);
+  // Every other tool reads graph truth: load once and build the typed service
+  // object (the Repository Interface). dispatchTool is the presentation adapter —
+  // it delegates resolution + the miss/error contract to the service and formats
+  // the result with tmct's own render* layer (which reads svc.graph). This is the
+  // switch's operations extracted into a named, typed seam without changing bytes.
+  const graph = await loadGraph(config, source);
+  const svc = createGraphService(graph);
   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");
+    const { match } = resolveOrThrow(svc, 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");
+    const { match, candidates } = resolveOrThrow(svc, 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 { match, candidates } = resolveOrThrow(svc, symbol, "symbol");
     const site = siteOf(match);
     if (!site) {
       throw new ToolError(
@@ -308,22 +334,19 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   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");
+    const { match } = resolveOrThrow(svc, 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");
+    const { match } = resolveOrThrow(svc, 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(),
@@ -333,36 +356,30 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   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");
+    const { match } = resolveOrThrow(svc, 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");
+    const { match } = resolveOrThrow(svc, 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");
+    const { match } = resolveOrThrow(svc, 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
@@ -376,8 +393,7 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   ) {
     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");
+    const { match } = resolveOrThrow(svc, 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);

package/src/sessions.mjs

@@ -4,7 +4,7 @@
 //   .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":"turn", ts, query, via, resolvedIds, answeredIds, miss}  (one per turn, flushed)
 //     {"type":"end", ts}                                          (clean close marker)
 //
 // From the sidecar the session enters the typed graph twice:
@@ -25,7 +25,7 @@
 
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { appendUtterances } from "./memory/core.mjs";
+import { appendUtterances, CREATED_AT_PROP } from "./memory/core.mjs";
 
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
 
@@ -73,6 +73,10 @@ export function upsertSession(entities, record) {
   entities.individuals ||= [];
   entities.objectProperties ||= [];
 
+  // capture the prior copy's createdAt BEFORE we drop it — first-write-wins so
+  // mgx:createdAt records when the session was FIRST seen, not last re-appended.
+  const priorSession = entities.individuals.find((i) => i?.id === sid);
+  const priorCreatedAt = priorSession?.attributes?.find((a) => a?.prop === CREATED_AT_PROP)?.value || "";
   // 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);
@@ -111,6 +115,8 @@ export function upsertSession(entities, record) {
     id: sid, label, class: SESSION_CLASS,
     derived_from: [], mentions: [],
     attributes: [
+      // referenced via the imported constant (single-sourced from memory/core.mjs)
+      { prop: CREATED_AT_PROP, key: "createdAt", value: priorCreatedAt || started || new Date().toISOString() },
       { prop: "mgx:sessionStarted", key: "started", value: started },
       { prop: "mgx:sessionEnded", key: "ended", value: ended },
       { prop: "mgx:sessionTurns", key: "turns", value: String(turns.length) },
@@ -216,6 +222,7 @@ async function recordSessionMemory(graphFile, record, repoDirOverride = null) {
     if (t.answeredIds?.length) parsed.answeredIds = t.answeredIds;
     if (t.command) parsed.command = t.command;
     if (t.miss) parsed.miss = true;
+    if (t.via) parsed.via = t.via; // answer provenance (W1) — carried into memory
     utterances.push({
       role: "visitor", text: query, ts, sessionId: record.id, sessionStarted: record.started || "",
       ...(Object.keys(parsed).length ? { parsed } : {}),
@@ -264,6 +271,10 @@ export function parseSessionJsonl(text) {
         // conversational filler are recorded but never folded into the corpus.
         ...(rec.command ? { command: String(rec.command) } : {}),
         ...(rec.conversational ? { conversational: true } : {}),
+        // answer provenance (W1): composed|template|count|command|conversational|
+        // assert|recall|fact|corpus — carried through so the memory side-write and
+        // any re-fold keep the banding signal the Phase-5 bench reads.
+        ...(rec.via ? { via: String(rec.via) } : {}),
       });
     } else if (rec?.type === "end") ended = String(rec.ts || "") || ended;
   }

package/src/toml-config.mjs

@@ -87,6 +87,20 @@ export async function normalizeConfig(raw, { configDir } = {}) {
     cfg.outRoot = resolve(dir, String(src.out_root));
   }
 
+  // `tmct init` onboarding keys (ROADMAP Phase 8). Sparse like the rest: only a
+  // key actually present appears, so "unset" stays distinguishable from "set to
+  // the default". `graph_file` is resolved against configDir to match outRoot.
+  if (src.graph_file !== undefined) {
+    cfg.graphFile = resolve(dir, String(src.graph_file));
+  }
+  const corpus = src.corpus || {};
+  if (corpus.tier !== undefined) cfg.corpus = { tier: corpus.tier };
+  const seed = src.seed || {};
+  const seedCfg = {};
+  if (seed.enabled !== undefined) seedCfg.enabled = seed.enabled;
+  if (seed.limit !== undefined) seedCfg.limit = seed.limit;
+  if (Object.keys(seedCfg).length) cfg.seed = seedCfg;
+
   const idx = src.index || {};
   const index = {};
   if (idx.languages !== undefined) index.languages = idx.languages;

package/src/wink-model.mjs

@@ -0,0 +1,74 @@
+// wink-model.mjs — the ONE place tmct loads the wink-nlp engine + model.
+//
+// Two adapters sit on top of this leaf loader: ask-nlp.mjs (lemma/POS tier for the
+// ask engine) and prose-nlp.mjs (lemma layer for the prose index). They used to
+// each carry their own `createRequire(import.meta.url)` block — the same ~six lines
+// twice, and both Node-only. That duplication is single-sourced here, and the
+// Node-only limitation is lifted with a browser seam, WITHOUT eagerly bundling the
+// ~1 MB model into anything.
+//
+// Why a registration seam instead of a static `import "wink-nlp"`:
+//   - The whole architecture keeps the model OUT of the base/viewer bundle; a static
+//     import would drag it in. `wink-eng-lite-web-model` is already the *browser*
+//     build, so the model can run in the page — what was missing is a load path a
+//     bundler can satisfy without a Node `require`. That path is `registerWinkModel`:
+//     a browser/bundler entry imports wink with its own `import` and hands the pair
+//     in ONCE, before any lemma/POS use. Node needs nothing — it falls back to
+//     `createRequire`. This is the Phase-8 browser-mode unblocker the dependency
+//     audit called for (a wiring fix; the model was always browser-capable).
+//
+// The loader stays SYNCHRONOUS (the adapters and their callers are sync): the
+// browser host registers up front; Node resolves lazily via createRequire. Failure
+// is cached as null — a checkout without the optional deps, or a page that never
+// registered a model, simply runs adapter-less (lemma/POS tiers honestly off), it
+// never throws.
+
+import { createRequire } from "node:module";
+
+let injected; // browser/bundler-supplied `() => ({ winkNLP, model })`, or undefined
+let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+
+/** Browser/bundler seam: register a factory returning `{ winkNLP, model }` (each the
+ *  imported module) so the page's own bundler resolves wink instead of a Node
+ *  `require`. Call once before any ask/prose lemma use. Resets the cache so a late
+ *  registration still takes effect. */
+export function registerWinkModel(factory) {
+  injected = factory;
+  cached = undefined;
+}
+
+/** Load `{ winkNLP, model }` once, or null when wink isn't available. Prefers a
+ *  registered browser factory; otherwise falls back to Node module resolution. */
+export function loadWinkModel() {
+  if (cached !== undefined) return cached;
+  try {
+    const pair = injected ? injected() : nodeRequireWink();
+    cached = pair && pair.winkNLP && pair.model ? pair : null;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+/** Node fallback: resolve wink through the module system (never a guessed path),
+ *  exactly as the two adapters did inline before. CJS deps, so `createRequire`. */
+function nodeRequireWink() {
+  const require = createRequire(import.meta.url);
+  return {
+    winkNLP: require("wink-nlp"),
+    model: require("wink-eng-lite-web-model"),
+  };
+}
+
+/** Convenience: the constructed `nlp` instance (`winkNLP(model)`) or null. Both
+ *  adapters want exactly this. Not cached here — the adapters cache their own
+ *  higher-level object; constructing `nlp` is cheap next to loading the model. */
+export function winkInstance() {
+  const loaded = loadWinkModel();
+  if (!loaded) return null;
+  try {
+    return loaded.winkNLP(loaded.model);
+  } catch {
+    return null;
+  }
+}