@polycode-projects/seonix 0.8.0 → 0.9.0

package/bin/cli.mjs

@@ -353,6 +353,10 @@ async function main() {
         extraIgnores = compileGlobs([...(toml.index.exclude || []), ...(toml.index.secretExclude || [])]);
         tomlLanguages = toml.index.languages;
       }
+      // [interfaces] → gated route↔handler `serves` edges (PLAN_UNTYPED_INTERFACES.md). Only read
+      // from a repo's seonix.toml, so config:false (the bench-immunity flag) keeps it null; a bench
+      // arm opts in via the SEONIX_INTERFACES env instead (resolved in extract.mjs assembleAndWrite).
+      const tomlInterfaces = toml && toml.interfaces ? toml.interfaces : null;
       // A7: `"sync":true` on a multi_root routes through the SAME incremental-sync code
       // path as `cli sync` — fingerprint the estate, re-extract only changed members.
       if (args.multi_root && args.sync === true) {
@@ -373,7 +377,7 @@ async function main() {
       };
 
       if (args.repo_path) {
-        const { graphFile, counts, summary } = await indexRepository(args.repo_path, { ignores: args.ignores !== false, historyDepth, extraIgnores, languages: tomlLanguages });
+        const { graphFile, counts, summary } = await indexRepository(args.repo_path, { ignores: args.ignores !== false, historyDepth, extraIgnores, languages: tomlLanguages, interfaces: tomlInterfaces });
         emitSummary(graphFile, counts, "");
         // A1: the human summary MD goes to STDOUT (bench ignores index stdout — safe;
         // the machine-readable counts stay on stderr above).
@@ -408,6 +412,7 @@ async function main() {
         historyDepth,
         extraIgnores,
         languages: tomlLanguages,
+        interfaces: tomlInterfaces,
         skipped: skippedRows,
         log: (line) => process.stderr.write(`seonix: ${line}\n`),
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "SEONIX — a deterministic, offline, $0 code-graph tool that makes a cheap coding agent edit like an expensive one. Indexes a repo with Python ast + git (zero model calls) and renders a bounded edit-digest.",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@polycode-projects/the-mechanical-code-talker": "^0.6.0",
+    "@polycode-projects/the-mechanical-code-talker": "^0.8.0",
     "cytoscape": "^3.30.0",
     "smol-toml": "^1.7.0",
     "tree-sitter": "^0.21.1",

package/src/browser.mjs

@@ -45,6 +45,7 @@ const PROP_KIND = {
   "mgx:reexports": "reexports",
   "mgx:touchessymbol": "touchesSymbol",
   "mgx:callssymbol": "callsSymbol",
+  "mgx:serves": "serves", // un-typed interfaces (gated); inert on a default graph
 };
 
 const pathOfId = (id) => {

package/src/codegraph.mjs

@@ -1,6 +1,7 @@
 import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
 import { cosine } from "./embed.mjs";
 import { expandGraphPayload } from "./graph-format.mjs";
+import { isTestLabel, isNonProdLabel, NONPROD_DEMOTE, hubDemote } from "./paths.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
 // deterministic indexer writes to <repo>/.seonix/graph.json (shape produced by
@@ -58,7 +59,7 @@ export function parseEntities(payload) {
     truncated,
     generatedAt: payload?.generated_at || null,
     // Second pass (PLAN_PROSE_INDEX.md): word -> [individual ids], passed through
-    // byte-identical from the payload so ask.mjs's resolveObject can consult it as a
+    // byte-identical from the payload so tmct's resolveObject can consult it as a
     // fallback tier without reaching back into the raw payload itself. {} when the
     // build had prose disabled or the payload predates this field.
     proseIndex: payload?.proseIndex || {},
@@ -88,6 +89,9 @@ const PROP_KIND = {
   // closure (module-coarse) is unchanged.
   "mgx:touchessymbol": "touchesSymbol",
   "mgx:callssymbol": "callsSymbol",
+  // un-typed interfaces (PLAN_UNTYPED_INTERFACES.md) — route→handler; only present when the
+  // gated [interfaces] feature emitted serves edges, so this key is inert on a default graph.
+  "mgx:serves": "serves",
   // legacy tokens (pre-realign graphs) — kept so a stale artifact still classifies
   "seon:usescomplextype": "imports",
   "seon:invokesmethod": "calls",
@@ -428,15 +432,8 @@ const SYM_MATCH_CAP = 4;   // only the top-K highest-IDF symbol-COMPONENT hits c
                            // bag-of-symbols module (e.g. db/backends features) can't accrete noise
 const PROX_FRAC = 0.2;     // import-adjacency bonus = this × the strongest matched neighbour …
 const PROX_CAP_FRAC = 0.35; //  … capped at this × the module's own score (a nudge — hubs can't run away)
-const isTestLabel = (s) => /(^|\/)tests?\//.test(s) || /(^|\/)test_[^/]*\.py$/.test(s) || /\.tests(\.|$)/.test(s);
-// B016 R1a (opt-in via demoteNonProd): non-production paths — examples, fixtures, sample/demo
-// apps, and test-* harness packages — share path/symbol vocabulary with the production module
-// and shadow it in locate (B015: js-express injected examples/route-middleware/index.js at
-// rank 1; java-gson's TOP2 slot 2 was a test-shrinker fixture). DEMOTED, not excluded: none of
-// the B015 truths live under these paths (checked corpus/instances-*/…/spec.json 2026-07-02),
-// but a future task whose truth IS a test/example file must stay reachable.
-const NONPROD_DEMOTE = 0.15;
-const isNonProdLabel = (s) => /(^|\/)(examples?|fixtures?|samples?|demos?|benchmarks?|test-[^/]+)(\/|$)/.test(s);
+// isTestLabel / isNonProdLabel / NONPROD_DEMOTE now live in ./paths.mjs (shared with summary.mjs
+// so the two hub-ranking sites can't drift); imported at the top of this module.
 // B016 E1a (opt-in via callAdjacency): resolved-call adjacency, same bounded-nudge shape as the
 // import-proximity bonus. Python graphs carry call edges (django: 993 calls / 23,596 callsSymbol);
 // the syntax-level C#/Java extractors emit ~none today, so this flag is Python-value only.
@@ -1141,7 +1138,7 @@ export function selectRankedModules(ranked, { top_k = 2, scoreGapK = null } = {}
   return picked;
 }
 
-export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "" } = {}) {
+export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", decorator = "", name = "", page = 0 } = {}) {
   const tokens = String(query || "").toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
   const wantKind = String(kind || "").trim().toLowerCase();
   const decFilter = String(decorator || "").trim().toLowerCase();
@@ -1159,12 +1156,24 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
   if (!scored.length) {
     return `no module matches "${query}". Try broader keywords, or seonix_describe <path> if you know where it lives.`;
   }
-  const hits = scored.slice(0, limit);
-  const lines = [`${scored.length} module(s) match "${query}" (top ${hits.length}):`];
-  for (const { ind, defineCount, matching } of hits) {
+  const renderRows = (rows) => rows.map(({ ind, defineCount, matching }) => {
     const m = matching.length ? ` — matching: ${capJoin([...new Set(matching)], SEARCH_SYMBOLS_SHOWN)}` : "";
-    lines.push(`- ${ind.label} (defines ${defineCount} symbol(s))${m}`);
+    return `- ${ind.label} (defines ${defineCount} symbol(s))`.concat(m);
+  });
+  // C3 (copilot-UX): opt-in pagination. `page` absent (0) → today's "top N" output, byte-identical.
+  // page>=1 → a stable window + a "call again with page N+1" trailer for large result sets.
+  if (page >= 1) {
+    const pages = Math.max(1, Math.ceil(scored.length / limit));
+    const p = Math.min(page, pages);
+    const hits = scored.slice((p - 1) * limit, p * limit);
+    const lines = [`${scored.length} module(s) match "${query}" (page ${p}/${pages}, showing ${hits.length}):`, ...renderRows(hits)];
+    lines.push(p < pages
+      ? `… ${scored.length - p * limit} more — call seonix_search again with page: ${p + 1}.`
+      : "Then seonix_describe <path> for the full sibling list + typed edges, or seonix_impact <path> for dependents.");
+    return lines.join("\n");
   }
+  const hits = scored.slice(0, limit);
+  const lines = [`${scored.length} module(s) match "${query}" (top ${hits.length}):`, ...renderRows(hits)];
   lines.push("Then seonix_describe <path> for the full sibling list + typed edges, or seonix_impact <path> for dependents.");
   return lines.join("\n");
 }
@@ -1176,7 +1185,7 @@ export function renderSearch(graph, query, { limit = SEARCH_LIMIT, kind = "", de
 /** All edges whose relation classifies to `kind`, flattened across relation groups. */
 /** All edges of a classified relation kind (imports/calls/defines/tests/touches/inherits/
  *  cochange/reexports/callsSymbol/touchesSymbol/contains — see relationKind/PROP_KIND above),
- *  flattened across every raw relation group that classifies to it. Exported for ask.mjs's
+ *  flattened across every raw relation group that classifies to it. Exported for tmct's
  *  mechanical NL-query engine (PLAN_MECHANICAL_CHAT.md) to orchestrate rather than duplicate. */
 export function edgesOfKind(graph, kind) {
   const out = [];
@@ -1344,9 +1353,13 @@ export function renderArchitecture(graph, { pkg = "" } = {}) {
   const inDeg = new Map();
   for (const e of edgesOfKind(graph, "imports")) inDeg.set(e.object, (inDeg.get(e.object) || 0) + 1);
   const modSet = new Set(modules.map((m) => m.id));
+  // Sort by importer count DOWN-WEIGHTED for test/non-prod paths (0.8.1) so a shared test harness
+  // or fixtures package can't dominate the hub view — the wh estate's E2E harness was the top
+  // "hub" purely as a test-import sink. The displayed count stays the raw importer total.
   const hubs = [...inDeg.entries()]
     .filter(([id]) => modSet.has(id))
-    .sort((a, b) => b[1] - a[1])
+    .map(([id, n]) => [id, n, n * hubDemote(graph.byId.get(id)?.label || id)])
+    .sort((a, b) => b[2] - a[2])
     .slice(0, ARCH_HUB_CAP)
     .map(([id, n]) => `${graph.byId.get(id)?.label || id} (${n} importers)`);
   const pkgs = [...pkgCount.entries()].sort((a, b) => b[1] - a[1]);

package/src/extract.mjs

@@ -27,6 +27,7 @@ import { loadIgnores } from "./walk.mjs";
 import { attachProseTokens, buildProseIndex } from "./prose.mjs";
 import { ingestSchemaDocs } from "./schema-docs.mjs";
 import { foldInSessions, readSessionRecords } from "./sessions.mjs";
+import { extractServes, interfaceOpts } from "./interfaces.mjs";
 import { encodeGraphV2 } from "./graph-format.mjs";
 import { buildSummary, writeSummaryArtifacts } from "./summary.mjs";
 import { fingerprintRepo, readManifest, writeManifest, diffManifest } from "./manifest.mjs";
@@ -216,7 +217,7 @@ async function runGitLogHunks(repoPath, depth = historySymbolDepth()) {
 /** Build the `entities` payload from the parsed modules + git history.
  *  `symbolHistory` (optional) is the runGitLogHunks() output — per-commit changed
  *  line ranges, intersected with symbol spans to emit mgx:touchesSymbol edges. */
-export function buildEntities(modules, commits, { generatedAt = "", symbolHistory = [], prose = true } = {}) {
+export function buildEntities(modules, commits, { generatedAt = "", symbolHistory = [], prose = true, interfaces = null } = {}) {
   const modById = new Map();         // path -> module record
   const dottedToPath = new Map();    // dotted module name -> path
   const nameToPaths = new Map();     // top-level symbol name -> Set<path> (for call resolution)
@@ -538,9 +539,16 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   const countClass = (c) => fnIndividuals.filter((i) => i.class === c).length;
   const sampleClass = (c) => fnIndividuals.filter((i) => i.class === c).slice(0, 3).map((i) => i.label);
 
+  // Un-typed interfaces (PLAN_UNTYPED_INTERFACES.md, GATED): route→handler `serves` edges + Route
+  // individuals, ONLY when [interfaces] is enabled. Disabled → empty arrays → every spread below is
+  // a no-op → byte-identical graph.json/summary.json (the measurement contract).
+  const serves = interfaces?.enabled
+    ? extractServes(modules, { fnId, opts: interfaceOpts(interfaces) })
+    : { edges: [], routes: [], vocab: [] };
+
   // Second pass (PLAN_PROSE_INDEX.md) — see the returned `proseIndex` field's comment below.
   const allIndividuals = attachProseTokens(
-    [...moduleIndividuals, ...fnIndividuals, ...commitIndividuals], { enabled: prose },
+    [...moduleIndividuals, ...fnIndividuals, ...serves.routes, ...commitIndividuals], { enabled: prose },
   );
   const proseIndex = prose ? buildProseIndex(allIndividuals) : {};
 
@@ -581,9 +589,14 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
       { prop: "seon:subKind", note: "type flavour on a Class define when not a plain class (interface/enum/struct/record); kind stays class" },
       { prop: "seon:hasAccessModifier", note: "visibility from leading underscore (private/protected); public omitted" },
       { prop: "seon:hasDoc", note: "first docstring line (capped) — one-line purpose without the body" },
+      // GATED (PLAN_UNTYPED_INTERFACES.md): the un-typed-interface vocab is built in interfaces.mjs
+      // and spread here (empty when OFF → byte-identical; the prop tokens are scoped to that module,
+      // outside the core extract.mjs schema drift guard).
+      ...serves.vocab,
     ],
     classes: [
       { name: "Module", count: moduleIndividuals.length, sample: moduleIndividuals.slice(0, 3).map((i) => i.label) },
+      ...(serves.routes.length ? [{ name: "Route", count: serves.routes.length, sample: serves.routes.slice(0, 3).map((i) => i.label) }] : []),
       { name: "Class", count: countClass("Class"), sample: sampleClass("Class") },
       { name: "Function", count: countClass("Function"), sample: sampleClass("Function") },
       { name: "Method", count: countClass("Method"), sample: sampleClass("Method") },
@@ -603,6 +616,9 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
       rel("inherits", "seon:hasSuperType", inheritsEdges),
       rel("cochange", "mgx:changeCoupledWith", cochangeEdges),
       rel("reexports", "mgx:reExports", reExportEdges),
+      // GATED (PLAN_UNTYPED_INTERFACES.md): emitted ONLY when the interfaces feature produced
+      // edges, so the default graph never carries a zero-count `serves` group → byte-identical.
+      ...(serves.edges.length ? [rel("serves", "mgx:serves", serves.edges)] : []),
     ],
     individuals: allIndividuals,
     // Second pass (PLAN_PROSE_INDEX.md): word -> [individual ids], inverted from the
@@ -775,8 +791,15 @@ async function extractRepo(repoPath, { python = DEFAULT_PYTHON(), ignores = true
 
 /** Assemble entities from (possibly merged) extractions and write the artifacts
  *  (<rootDir>/.seonix/graph.json + TOOLS.md). Shared by both index modes. */
-async function assembleAndWrite(rootDir, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions = [] }) {
-  const entities = buildEntities(modules, commits, { generatedAt, symbolHistory, prose: proseEnabled });
+async function assembleAndWrite(rootDir, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions = [], interfaces = null }) {
+  // Un-typed interfaces gate (PLAN_UNTYPED_INTERFACES.md): SEONIX_INTERFACES env wins both ways,
+  // else the seonix.toml [interfaces].enabled flag; default OFF → byte-identical. Same precedence
+  // shape as SEONIX_STORE / SEONIX_GRAPH_FORMAT below.
+  const interfacesEnabled = process.env.SEONIX_INTERFACES === "1" ? true
+    : process.env.SEONIX_INTERFACES === "0" ? false
+    : !!(interfaces && interfaces.enabled);
+  const interfacesCfg = interfacesEnabled ? { ...(interfaces || {}), enabled: true } : null;
+  const entities = buildEntities(modules, commits, { generatedAt, symbolHistory, prose: proseEnabled, interfaces: interfacesCfg });
   // Schema self-documentation (schema-docs.mjs): static, repo-independent — merges in
   // SchemaClass/SchemaPredicate individuals + backfills entities.classes[].description
   // and entities.vocabulary[].note, so "what does cochange mean" is answerable by the
@@ -855,7 +878,7 @@ function buildCounts(entities, { modules, languages, commits, proseEnabled, base
  * symbol-history (line-range) pass so the latter can be kept within the ≤10% budget.
  * @returns {Promise<{graphFile, counts}>}
  */
-export async function indexRepository(repoPath, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, historyDepth, extraIgnores = null, languages } = {}) {
+export async function indexRepository(repoPath, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, historyDepth, extraIgnores = null, languages, interfaces = null } = {}) {
   // Second pass (PLAN_PROSE_INDEX.md): on by default; SEONIX_PROSE_INDEX=0 disables it
   // (mirrors SEONIX_HISTORY_SYMBOL_DEPTH=0's disable convention above).
   const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
@@ -863,7 +886,7 @@ export async function indexRepository(repoPath, { python = DEFAULT_PYTHON(), gen
   const { modules, perLang, commits, symbolHistory, baseMs, historyMs, gitErrors } = r;
   warnGitErrors(gitErrors, repoPath); // surface any history-pass failure immediately (never fatal)
   const sessions = await readSessionRecords(repoPath); // recorded chat sessions (.seonix/sessions/*.jsonl), [] when none
-  const { entities, graphFile, graphBytes } = await assembleAndWrite(repoPath, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions });
+  const { entities, graphFile, graphBytes } = await assembleAndWrite(repoPath, { modules, commits, symbolHistory, generatedAt, proseEnabled, sessions, interfaces });
   // A1 post-index summary: SUMMARY.md + summary.json next to graph.json (NEW files; the
   // graph.json bytes are untouched). The rendered MD is also printed to stdout by cli.mjs.
   const summary = buildSummary(entities, {
@@ -976,7 +999,7 @@ export async function discoverRepos(multiRoot) {
  * `log` (optional) receives one progress line per repo.
  * @returns {Promise<{graphFile, outRoot, repos, counts}>}
  */
-export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, outRoot = "", log = () => {}, historyDepth, skipped = [], extraIgnores = null, languages: languageAllow } = {}) {
+export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, outRoot = "", log = () => {}, historyDepth, skipped = [], extraIgnores = null, languages: languageAllow, interfaces = null } = {}) {
   const paths = [...new Set((repoPaths || []).map((p) => resolve(p)))];
   if (!paths.length) throw new Error("indexRepositories requires at least one repo path");
   const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
@@ -1014,7 +1037,7 @@ export async function indexRepositories(repoPaths, { python = DEFAULT_PYTHON(),
   // yet — their recorded ids would need the same repo-name prefixing as modules to
   // re-resolve against the merged graph. Deferred; single-path fold-in is the contract.
   const { entities, graphFile, graphBytes } = await assembleAndWrite(root, {
-    modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled,
+    modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled, interfaces,
   });
   // A1 post-index summary (merged): per-repo rows (name = prefix) + any discovery
   // `skipped` rows threaded through by the cli. NEW files next to graph.json.
@@ -1094,7 +1117,7 @@ async function discoverSyncRepos(root) {
  * `log` receives one line per re-extracted repo (and the "N unchanged" no-op line).
  * @returns {Promise<{graphFile, outRoot, noop, added, changed, removed, reextracted, unchanged, summary?, counts?}>}
  */
-export async function syncRepositories(multiRoot, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, historyDepth, log = () => {} } = {}) {
+export async function syncRepositories(multiRoot, { python = DEFAULT_PYTHON(), generatedAt = "", ignores = true, historyDepth, log = () => {}, interfaces = null } = {}) {
   const root = resolve(multiRoot);
   const artifactDir = join(root, ".seonix");
   const proseEnabled = process.env.SEONIX_PROSE_INDEX !== "0";
@@ -1186,7 +1209,7 @@ export async function syncRepositories(multiRoot, { python = DEFAULT_PYTHON(), g
 
   // ONE buildEntities over the union (cached + fresh) → the exact full-re-index graph.
   const { entities, graphFile, graphBytes } = await assembleAndWrite(root, {
-    modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled,
+    modules: allModules, commits: allCommits, symbolHistory: allSymbolHistory, generatedAt, proseEnabled, interfaces,
   });
   const summary = buildSummary(entities, { mode: "multi", repos: repoRows, skipped: [], languages, graphBytes });
   await writeSummaryArtifacts(dirname(graphFile), summary);

package/src/interfaces.mjs

@@ -0,0 +1,171 @@
+// Un-typed interface extraction (PLAN_UNTYPED_INTERFACES.md, 0.9.0) — the `serves` predicate:
+// route-declaration → handler-symbol. These are the HTTP boundaries a syntax-only AST graph misses
+// entirely: the route STRING (`[HttpGet("api/orders/{id}")]` / `app.get('/orders/:id', …)`) is not a
+// node or an edge target anywhere in the base graph, and a handler passed by reference at
+// registration is not a call/import edge — so "what serves GET api/orders" is otherwise unanswerable.
+//
+// GATED: buildEntities only calls this when the [interfaces] feature is enabled, and only emits the
+// `serves` group / route individuals when there is at least one edge, so the DEFAULT graph is
+// byte-identical (the measurement contract). Pure — no fs, no process, deterministic order.
+
+// HTTP verbs we recognise on an attribute / a router-registration call.
+const VERBS = ["get", "post", "put", "delete", "patch", "head", "options"];
+
+/** Resolve the effective knobs, arg > toml > default. `enabled` is decided by the caller. */
+export function interfaceOpts(cfg = {}) {
+  return {
+    frameworks: cfg.frameworks && cfg.frameworks.length ? cfg.frameworks.map((s) => String(s).toLowerCase()) : ["aspnet", "express"],
+    verbs: cfg.verbs && cfg.verbs.length ? cfg.verbs.map((s) => String(s).toLowerCase()) : VERBS,
+    combineControllerPrefix: cfg.combineControllerPrefix !== false, // default true
+    prefixStrip: (cfg.prefixStrip || []).map((s) => normPath(String(s))),
+    // Forward-compat: the confidence threshold the future callsHttp client↔route matcher will tune.
+    matchThreshold: typeof cfg.matchThreshold === "number" ? cfg.matchThreshold : 0.5,
+  };
+}
+
+/** Collapse duplicate/edge slashes and a trailing slash; keep a single leading slash off. */
+function normPath(p) {
+  return String(p || "").replace(/\\/g, "/").replace(/\/{2,}/g, "/").replace(/^\/|\/$/g, "");
+}
+
+/** Join a controller-level route prefix with a method-level suffix into one normalised path. */
+function joinRoute(prefix, suffix) {
+  const a = normPath(prefix), b = normPath(suffix);
+  if (!a) return b;
+  if (!b) return a;
+  return `${a}/${b}`;
+}
+
+/** Substitute ASP.NET route tokens: [controller] → controller name sans "Controller", [action] → method. */
+function subTokens(path, controller, action) {
+  return path
+    .replace(/\[controller\]/gi, controller)
+    .replace(/\[action\]/gi, action);
+}
+
+/** The quoted first string argument of an attribute/call text, e.g. `HttpGet("api/x")` → "api/x". */
+function firstStringArg(text) {
+  const m = /["'`]([^"'`]*)["'`]/.exec(String(text || ""));
+  return m ? m[1] : "";
+}
+
+/** From a C# attribute one-liner (`HttpGet("x")`, `Route("api/[controller]")`, `ApiController`)
+ *  return {verb|null, path}. A bare `[Route("…")]` has verb=null (a prefix, not a mapping). */
+function parseCsAttr(attr) {
+  const name = /^([A-Za-z]+)/.exec(String(attr || "").trim());
+  if (!name) return null;
+  const id = name[1].toLowerCase();
+  if (id.startsWith("http")) {
+    const verb = id.slice(4); // httpget → get
+    if (VERBS.includes(verb)) return { verb, path: firstStringArg(attr) };
+  }
+  if (id === "route") return { verb: null, path: firstStringArg(attr) };
+  return null;
+}
+
+/** C# controller routes from a module's defines[] (Roslyn emits `[Http*]`/`[Route]` in decorators).
+ *  Methods are named "Class.Method"; the class-level [Route] prefix is combined per opts. */
+function csRoutes(mod, opts) {
+  const out = [];
+  const defines = mod.defines || [];
+  // class name → { prefix, isController } from class-level [Route]/[ApiController]
+  const classInfo = new Map();
+  for (const d of defines) {
+    if (d.kind !== "class") continue;
+    let prefix = "", isController = /controller$/i.test(d.name);
+    for (const a of d.decorators || []) {
+      const p = parseCsAttr(a);
+      if (p && p.verb === null && p.path) prefix = p.path;
+      if (/^apicontroller/i.test(String(a).trim())) isController = true;
+    }
+    classInfo.set(d.name, { prefix, isController });
+  }
+  for (const d of defines) {
+    if (d.kind !== "method") continue;
+    const dot = d.name.lastIndexOf(".");
+    const className = dot >= 0 ? d.name.slice(0, dot) : "";
+    const methodName = dot >= 0 ? d.name.slice(dot + 1) : d.name;
+    const info = classInfo.get(className);
+    const controller = className.replace(/Controller$/i, "");
+    for (const a of d.decorators || []) {
+      const p = parseCsAttr(a);
+      if (!p || p.verb === null) continue;               // only [Http*] maps a method to a verb
+      if (!opts.verbs.includes(p.verb)) continue;
+      const prefix = opts.combineControllerPrefix ? (info?.prefix || "") : "";
+      let path = subTokens(joinRoute(prefix, p.path), controller, methodName);
+      path = stripPrefixes(path, opts.prefixStrip);
+      out.push({ verb: p.verb.toUpperCase(), path, handler: d.name });
+    }
+  }
+  return out;
+}
+
+/** JS/TS routes come pre-structured from the extractor as `mod.routes: [{verb, path, handler}]`
+ *  (Express/Koa/Fastify `app.get('/x', handler)`), so we only normalise + filter here. */
+function jsRoutes(mod, opts) {
+  const out = [];
+  for (const r of mod.routes || []) {
+    const verb = String(r.verb || "").toLowerCase();
+    if (!opts.verbs.includes(verb)) continue;
+    if (!r.handler) continue;
+    out.push({ verb: verb.toUpperCase(), path: stripPrefixes(normPath(r.path), opts.prefixStrip), handler: r.handler });
+  }
+  return out;
+}
+
+function stripPrefixes(path, prefixes) {
+  let p = normPath(path);
+  for (const pre of prefixes) {
+    if (pre && (p === pre || p.startsWith(pre + "/"))) { p = p.slice(pre.length).replace(/^\//, ""); break; }
+  }
+  return p;
+}
+
+const isCs = (p) => /\.cs$/i.test(p || "");
+const isJsTs = (p) => /\.(m?[jt]sx?)$/i.test(p || "");
+
+/**
+ * Build the `serves` edges + `Route` individuals for a set of modules.
+ * @param modules  the same module records buildEntities consumes (path, defines[], routes[]).
+ * @param fnId     the id-builder buildEntities uses: (path, symbolName) → "fn:path#name".
+ * @param opts     from interfaceOpts().
+ * @returns { edges, routes } — edges are {subject,object,subjectLabel,objectLabel}; routes are
+ *          Route individuals. Both deterministically ordered; empty when nothing matched.
+ */
+export function extractServes(modules, { fnId, opts }) {
+  const routeById = new Map();     // route id → individual (deduped across modules/methods)
+  const edgeSet = new Set();       // dedupe subject|object
+  const edges = [];
+  for (const mod of modules || []) {
+    let routes = [];
+    if (isCs(mod.path) && opts.frameworks.includes("aspnet")) routes = csRoutes(mod, opts);
+    else if (isJsTs(mod.path) && opts.frameworks.includes("express")) routes = jsRoutes(mod, opts);
+    for (const r of routes) {
+      const label = `${r.verb} ${r.path}`;
+      const rid = `route:${label}`;
+      if (!routeById.has(rid))
+        routeById.set(rid, {
+          id: rid, label, class: "Route", derived_from: [], mentions: [],
+          attributes: [
+            { prop: "mgx:httpVerb", key: "verb", value: r.verb },
+            { prop: "mgx:routePath", key: "path", value: r.path },
+          ],
+        });
+      const object = fnId(mod.path, r.handler);
+      const key = `${rid}|${object}`;
+      if (edgeSet.has(key)) continue;
+      edgeSet.add(key);
+      edges.push({ subject: rid, object, subjectLabel: label, objectLabel: r.handler });
+    }
+  }
+  edges.sort((a, b) => (a.subject < b.subject ? -1 : a.subject > b.subject ? 1 : a.object < b.object ? -1 : a.object > b.object ? 1 : 0));
+  const routes = [...routeById.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  // Vocabulary notes for the emitted tokens, built HERE (not in extract.mjs) so the un-typed-interface
+  // props stay scoped to this gated feature module — the core schema drift guard documents the always
+  // -on extract.mjs props; these opt-in props are self-documented inline until they earn a
+  // PREDICATE_DOCS/SchemaPredicate entry (see PLAN_UNTYPED_INTERFACES.md follow-up #4).
+  const vocab = [];
+  if (edges.length) vocab.push({ prop: "mgx:serves", predicate: "serves", note: "route-declaration→handler-symbol; the HTTP boundary a syntax-only AST misses (un-typed interface)" });
+  if (routes.length) vocab.push({ prop: "mgx:httpVerb", note: "HTTP verb of a Route individual" }, { prop: "mgx:routePath", note: "normalised path template of a Route individual" });
+  return { edges, routes, vocab };
+}

package/src/jsts_tsc.mjs

@@ -23,6 +23,9 @@ import ts from "typescript";
 import { walk, relPath } from "./walk.mjs";
 
 const EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+// HTTP verbs recognised on an Express/Koa/Fastify router registration (`.use`/`.all` excluded —
+// they are middleware, not a verb→route mapping). Used for un-typed-interface `serves` extraction.
+const ROUTE_VERBS = new Set(["get", "post", "put", "delete", "patch", "head", "options"]);
 const stripExt = (p) => p.replace(/\.(tsx?|jsx?|mjs|cjs)$/i, "");
 
 function scriptKind(path) {
@@ -223,7 +226,11 @@ export async function extractFile(absPath, root) {
     }
   }
 
-  // module-level coarse calls (whole file)
+  // module-level coarse calls (whole file) + un-typed-interface route registrations
+  // (PLAN_UNTYPED_INTERFACES.md): `<obj>.get|post|…('/path', …, handler)` → a {verb,path,handler}
+  // record consumed downstream ONLY when the gated [interfaces] feature is on. Emitted as an
+  // optional `routes` field, so a module with no routes is byte-identical to before.
+  const routes = [];
   const visit = (n) => {
     if (ts.isCallExpression(n)) {
       const t = n.expression;
@@ -231,6 +238,14 @@ export async function extractFile(absPath, root) {
       if (ts.isIdentifier(t)) name = t.text;
       else if (ts.isPropertyAccessExpression(t)) name = t.getText(sf);
       if (name) calls.add(name.slice(0, 80));
+      if (ts.isPropertyAccessExpression(t) && ROUTE_VERBS.has(t.name.text.toLowerCase()) && n.arguments.length >= 2) {
+        const a0 = n.arguments[0];
+        if (ts.isStringLiteralLike(a0)) {
+          const last = n.arguments[n.arguments.length - 1];
+          const handler = ts.isIdentifier(last) ? last.text : ts.isPropertyAccessExpression(last) ? last.name.text : "";
+          if (handler) routes.push({ verb: t.name.text.toLowerCase(), path: a0.text, handler });
+        }
+      }
     }
     ts.forEachChild(n, visit);
   };
@@ -239,6 +254,7 @@ export async function extractFile(absPath, root) {
   return {
     path, dotted: stripExt(path),
     imports: [...imports].sort(), defines, calls: [...calls].sort(), exports: [...exports].sort(),
+    ...(routes.length ? { routes } : {}),
   };
 }
 

package/src/paths.mjs

@@ -0,0 +1,31 @@
+// Path/label classification shared by the locate scorer (codegraph.mjs), the architecture
+// digest (codegraph.mjs renderArchitecture), and the post-index summary (summary.mjs). Kept in
+// its own leaf module so summary.mjs can reuse the canonical regexes without importing the large
+// codegraph query module (and so the two never drift). Pure, no IO.
+
+// A module label under a test directory / a python test_*.py / a *.tests.* namespace.
+export const isTestLabel = (s) =>
+  /(^|\/)tests?\//.test(s) || /(^|\/)test_[^/]*\.py$/.test(s) || /\.tests(\.|$)/.test(s);
+
+// B016 R1a: non-production paths — examples, fixtures, sample/demo apps, and test-* harness
+// packages — share path/symbol vocabulary with the production module and shadow it in locate
+// (B015: js-express injected examples/route-middleware/index.js at rank 1; java-gson's TOP2 slot 2
+// was a test-shrinker fixture). DEMOTED, not excluded: a future task whose truth IS a
+// test/example file must stay reachable.
+export const isNonProdLabel = (s) =>
+  /(^|\/)(examples?|fixtures?|samples?|demos?|benchmarks?|test-[^/]+)(\/|$)/.test(s);
+
+// Locate/summary demote weights. Non-prod is the harshest (0.15, B016 R1a); a plain test dir is
+// milder (0.4, the locate test-demote).
+export const NONPROD_DEMOTE = 0.15;
+export const TEST_DEMOTE = 0.4;
+
+/** Hub-ranking sort multiplier for a module label: down-weight test/non-prod so a shared test
+ *  harness or fixtures package can't dominate the "hub modules" view (0.8.1, from wh dogfooding).
+ *  Non-prod < test < prod; the displayed importer/degree count stays the raw value. */
+export const hubDemote = (label) => {
+  const s = String(label || "");
+  if (isNonProdLabel(s)) return NONPROD_DEMOTE;
+  if (isTestLabel(s)) return TEST_DEMOTE;
+  return 1;
+};

package/src/prose.mjs

@@ -124,7 +124,7 @@ export function buildProseIndex(individuals) {
 
 /** Consumer-facing lookup: individual ids whose prose tokens overlap `query` (free text,
  *  tokenized the same way as a docstring), ranked by overlap count (most shared words
- *  first). This is the integration point for ask.mjs's resolveObject (fuzzy object-term
+ *  first). This is the integration point for tmct's resolveObject (fuzzy object-term
  *  resolution beyond exact/substring match) and codegraph.mjs's scoreModules (a lexical
  *  boost source) — see PLAN_PROSE_INDEX.md for the exact call-site recommendation; not
  *  wired into either file here to avoid colliding with concurrent work on them.
@@ -148,7 +148,7 @@ export function lookupByProseTokens(proseIndex, query, { limit = 10 } = {}) {
  *  build is unchanged — this only READS the layers the pre-pass already wrote). Given a query
  *  `token`, return the individual ids reachable through the NORMALISED prose layers
  *  (spell-corrected / canonical-schema-term / stem / lemma) stored under
- *  `proseIndex["seonix:layers"]` — the same normalised layers ask.mjs's resolveObject consults,
+ *  `proseIndex["seonix:layers"]` — the same normalised layers tmct's resolveObject consults,
  *  here surfaced for the locate SCORER so a task-text word that only overlaps a module via a
  *  normalised form still resolves.
  *
@@ -158,7 +158,7 @@ export function lookupByProseTokens(proseIndex, query, { limit = 10 } = {}) {
  *  A posting may be a plain id array or `{ ids: [...] }` — both are tolerated. The raw query
  *  token is looked up directly against every layer's keys, so a token whose surface form is
  *  already a canonical/stem/lemma/spell-corrected key hits; the accessor never itself normalises
- *  the query (it owns no normaliser — those live in the concurrent ask/prose-nlp surface), so it
+ *  the query (it owns no normaliser — those live in tmct's ask surface), so it
  *  can never disagree with the build's normalisation, only under-fire safely.
  *
  *  Returns { ids, via }: `ids` a deduped, sorted (stable/deterministic) id list; `via` the

package/src/schema-docs.mjs

@@ -201,7 +201,7 @@ const classIndividual = ({ name, description }) => ({
 const predicateIndividual = ({ prop, kind, description }) => ({
   id: `schema:predicate:${prop}`,
   // The label is the human-facing relation name (what a user would actually type — "what
-  // does cochange mean" — matching ask-vocab.mjs's VERB_TO_KIND/kind vocabulary), not the
+  // does cochange mean" — matching tmct's verb-to-kind vocabulary), not the
   // raw prop token; the token is kept as a separate attribute for exact lookup.
   label: kind,
   class: "SchemaPredicate",

package/src/server.mjs

@@ -12,7 +12,7 @@
 //
 // seonix_ask (PLAN_MECHANICAL_CHAT.md, hot tool): a mechanical, zero-model-call NL query
 // over the graph — collapses the search+describe+traversal composition loop an agent would
-// otherwise hand-compose into one deterministic round-trip. See ask.mjs.
+// otherwise hand-compose into one deterministic round-trip (now tmct's ask engine).
 
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -97,6 +97,7 @@ export const TOOLS = [
       required: ["query"],
       properties: {
         query: { type: "string", description: "A free-text question, e.g. \"which functions explicitly couple to logging\"." },
+        strict: { type: "boolean", description: "Fail fast on an ambiguous query (error naming the candidates) instead of returning multiple interpretations, so you can re-ask tighter. Default false." },
       },
     },
   },
@@ -260,7 +261,41 @@ export async function buildContextBundle(args, { config, source = defaultSource,
   return { text: out.join("\n"), tier, topup };
 }
 
+// C3 (copilot-UX): per-tool accepted argument keys, so a typo'd/unknown key gets a clear error
+// instead of the silent "X is required" the estate session hit. Deliberately generous (a superset of
+// each tool's read keys) so a valid call is never rejected; unlisted tools skip the check.
+const KNOWN_ARGS = {
+  seonix_context: ["symbol", "module", "depth", "min", "untuned", "max"],
+  seonix_context_more: ["symbol"],
+  seonix_describe: ["symbol"],
+  seonix_snippet: ["symbol"],
+  seonix_signature: ["symbol"],
+  seonix_impact: ["module", "depth"],
+  seonix_search: ["query", "kind", "decorator", "name", "page", "limit"],
+  seonix_members: ["class"],
+  seonix_subclasses: ["class"],
+  seonix_architecture: ["package"],
+  seonix_exports: ["module"],
+  seonix_untested: [],
+  seonix_ask: ["query", "strict"],
+  seonix_tests_for: ["symbol"], seonix_history: ["symbol"], seonix_callers: ["symbol"],
+  seonix_callees: ["symbol"], seonix_cochanges: ["symbol"], seonix_calls: ["symbol"],
+  seonix_file_history: ["symbol"], seonix_method_history: ["symbol"], seonix_class_history: ["symbol"],
+};
+// CLI/routing keys the cli.mjs entry always injects into `args` but no tool reads — never flagged.
+const BENIGN_ARGS = new Set(["repo_path", "repo_paths", "out_root", "multi_root", "modules", "config", "ignores", "sync", "history_depth"]);
+
 export async function dispatchTool(name, args, { config, source = defaultSource } = {}) {
+  const allowed = KNOWN_ARGS[name];
+  if (allowed && args && typeof args === "object" && !Array.isArray(args)) {
+    const unknown = Object.keys(args).filter((k) => !allowed.includes(k) && !BENIGN_ARGS.has(k));
+    if (unknown.length) {
+      throw new ToolError(
+        `unknown argument(s) for ${name}: ${unknown.join(", ")}` +
+          (allowed.length ? `. Valid: ${allowed.join(", ")}.` : " (this tool takes no arguments)."),
+      );
+    }
+  }
   if (name === "seonix_context") {
     return (await buildContextBundle(args, { config, source })).text;
   }
@@ -319,19 +354,28 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   if (name === "seonix_impact") {
     const module = String(args?.module || "").trim();
     if (!module) throw new ToolError("module is required");
+    // C1 (copilot-UX): optional `depth` bounds the reverse closure. Absent → renderImpact's default
+    // (full closure, maxDepth 8) → byte-unchanged. `depth:1` = direct dependents/importers only —
+    // the "who imports this, one hop" the copilot estate session asked for.
+    const depth = Number.isInteger(args?.depth) && args.depth > 0 ? args.depth : undefined;
     const graph = await loadGraph(config, source);
     const { match } = resolveOrThrow(graph, module, "module");
-    return renderImpact(graph, match);
+    return renderImpact(graph, match, depth ? { maxDepth: depth } : undefined);
   }
   if (name === "seonix_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);
+    // C3 (copilot-UX): opt-in paging for large result sets. Absent → today's "top N" output.
+    const page = Number.isInteger(args?.page) && args.page > 0 ? args.page : 0;
+    const limit = Number.isInteger(args?.limit) && args.limit > 0 ? args.limit : undefined;
     return renderSearch(graph, query, {
       kind,
       decorator: String(args?.decorator || "").trim(),
       name: String(args?.name || "").trim(),
+      ...(page ? { page } : {}),
+      ...(limit ? { limit } : {}),
     });
   }
   if (name === "seonix_members") {
@@ -371,6 +415,16 @@ export async function dispatchTool(name, args, { config, source = defaultSource
     // Repository Interface over seonix's graph. The `---seonix_ask---` delimited envelope is preserved
     // so every dispatchTool caller (this MCP handler, the CLI fallback) is unchanged.
     const { content, tmct_ask } = makeSeonixProvider(graph, { sourceAccess: false }).ask(query).value;
+    // C2 (copilot-UX): `strict:true` fails fast on an ambiguous query — return an error naming the
+    // candidate interpretations so the agent re-asks tighter, instead of paging a multi-interpretation
+    // body. Default (strict absent/false) → today's envelope, byte-unchanged.
+    if (args?.strict === true && tmct_ask?.ambiguous === true) {
+      const cands = (tmct_ask.matches || []).map((m) => `${m.label}${m.module ? ` (${m.module})` : ""}`).join(", ");
+      throw new ToolError(
+        `ambiguous query "${query}" — ${(tmct_ask.matches || []).length} candidate interpretation(s)` +
+          `${cands ? `: ${cands}` : ""}. Re-ask with a more specific query.`,
+      );
+    }
     return `${content}\n\n---seonix_ask---\n${JSON.stringify(tmct_ask, null, 2)}`;
   }
   if (

package/src/sessions.mjs

@@ -1,14 +1,14 @@
 // sessions.mjs — chat sessions as first-class temporal graph data, like commits.
 //
 // A `seonix chat` session leaves two artifacts under the target repo:
-//   .seonix/session-<uuidv7>.log            — the human-readable transcript (chat.mjs)
+//   .seonix/session-<uuidv7>.log            — the human-readable transcript (the chat shim)
 //   .seonix/sessions/session-<uuidv7>.jsonl — the STRUCTURED sidecar this module owns:
 //     {"type":"session", id, started, repo, seonixVersion}        (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`
+//   - READ TIME (the chat shim, 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,
@@ -141,7 +141,7 @@ export function upsertSession(entities, record) {
   return { kept: targets.length, dropped };
 }
 
-/** Read-time append (chat.mjs, once per turn): re-read graph.json FRESH (a re-index
+/** Read-time append (the chat shim, once per turn): re-read graph.json FRESH (a re-index
  *  may have replaced it mid-session), upsert, write back atomically. Throws on a
  *  missing/invalid artifact — the caller treats the append as best-effort. */
 export async function appendSessionToGraph(graphFile, record) {

package/src/source.mjs

@@ -19,12 +19,25 @@ export function clearCache() {
  *  source JSON can't be stat'd. node:sqlite is imported LAZILY here, so a gate-off load
  *  never touches sqlite (no ExperimentalWarning, no store.mjs sqlite import). */
 async function fetchFromStore(config) {
+  const { readPayload, storeFileFor } = await import("./store.mjs");
+  const dbPath = config.storeFile || storeFileFor(config.graphFile);
   let expectStat;
   try { expectStat = await stat(config.graphFile); }
-  catch { return null; } // no source JSON to verify against → let the JSON path emit its own error
+  catch {
+    // graph.json is gone. If a built store IS on disk, the freshness check has nothing to verify
+    // against and the JSON path below would ENOENT with a generic "no graph artifact" message —
+    // confusing when a usable graph.db sits right there. Give the real diagnosis instead. (A1)
+    let hasStore = false;
+    try { await stat(dbPath); hasStore = true; } catch { /* no store either */ }
+    if (hasStore)
+      throw new ToolError(
+        `graph.db present but graph.json is gone (${config.graphFile}) — the store's freshness ` +
+          `check needs graph.json, so re-index this repo: ` +
+          `\`seonix cli index_repository '{"repo_path":"<abs>"}'\`.`,
+      );
+    return null; // no store either → let the JSON path emit its own "run index_repository" error
+  }
   try {
-    const { readPayload, storeFileFor } = await import("./store.mjs");
-    const dbPath = config.storeFile || storeFileFor(config.graphFile);
     return await readPayload(dbPath, { expectStat });
   } catch (e) {
     process.stderr.write(`seonix: sqlite store unavailable (${e?.name || e?.code || e?.message || e}); using graph.json\n`);

package/src/summary.mjs

@@ -15,6 +15,7 @@
 
 import { writeFile, rename, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { hubDemote } from "./paths.mjs";
 
 // V8's hard maximum string length (chars). A graph.json larger than this can't be
 // JSON.parse'd back into one string — the failure mode the wh estate hit at 80%.
@@ -69,10 +70,13 @@ export function hubModules(entities, { prefix = "", top = 5 } = {}) {
   const rows = [];
   for (const [id, deg] of degree) {
     if (!id.startsWith(want)) continue;
-    rows.push({ id, label: labelById.get(id) ?? id.slice(4), degree: deg });
+    const label = labelById.get(id) ?? id.slice(4);
+    // Sort weight down-weights test/non-prod hubs (0.8.1) so a shared test harness can't dominate
+    // SUMMARY.md's hub list (the wh estate symptom); the reported `degree` stays the raw value.
+    rows.push({ id, label, degree: deg, weight: deg * hubDemote(label) });
   }
-  rows.sort((a, b) => (b.degree - a.degree) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  return rows.slice(0, top);
+  rows.sort((a, b) => (b.weight - a.weight) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return rows.slice(0, top).map(({ id, label, degree }) => ({ id, label, degree }));
 }
 
 /**

package/src/toml-config.mjs

@@ -123,6 +123,19 @@ export async function normalizeConfig(raw, { configDir } = {}) {
   const tel = src.telemetry || {};
   if (tel.enabled !== undefined) cfg.telemetry = { enabled: tel.enabled };
 
+  // [interfaces] — un-typed interface (route↔handler) indexing (PLAN_UNTYPED_INTERFACES.md).
+  // OFF by default; enabled emits gated `serves` edges + Route individuals. The matcher knobs
+  // (frameworks/verbs/combine_controller_prefix/prefix_strip/match_threshold) are tunable.
+  const ifc = src.interfaces || {};
+  const interfaces = {};
+  if (ifc.enabled !== undefined) interfaces.enabled = ifc.enabled;
+  if (ifc.frameworks !== undefined) interfaces.frameworks = ifc.frameworks;
+  if (ifc.verbs !== undefined) interfaces.verbs = ifc.verbs;
+  if (ifc.combine_controller_prefix !== undefined) interfaces.combineControllerPrefix = ifc.combine_controller_prefix;
+  if (ifc.prefix_strip !== undefined) interfaces.prefixStrip = ifc.prefix_strip;
+  if (ifc.match_threshold !== undefined) interfaces.matchThreshold = ifc.match_threshold;
+  if (Object.keys(interfaces).length) cfg.interfaces = interfaces;
+
   const unwired = [];
   for (const [a, b] of UNWIRED_KEYS) {
     if (src[a] && src[a][b] !== undefined) unwired.push(`${a}.${b}`);

package/src/uuid.mjs

@@ -1,5 +1,5 @@
 // uuid.mjs — RFC 9562 UUIDv7 (node:crypto ships v4 only). Lifted verbatim from
-// chat.mjs so the chat session id, the telemetry invocation id, and the bench
+// the chat session id, the telemetry invocation id, and the bench
 // per-run stamp all share ONE time-sortable implementation (no second copy, no dep).
 
 import { randomBytes } from "node:crypto";

package/src/viz.mjs

@@ -26,8 +26,8 @@ import { loadConfig } from "./config.mjs";
 import * as source from "./source.mjs";
 import { buildTemporalGraph, buildBrowserData, gitCommitOrder, gitCommitParents, renderBrowserHtml } from "./browser.mjs";
 import { extractTimeline, renderTimelineHtml } from "./timeline.mjs";
-// The wink lemma tier is gone (PLAN_CHAT_EXTRACTION.md Stage 6): the ask panel runs tmct's engine
-// adapter-less, so there is no ~4 MB browser model to build. `--nlp` is now a no-op.
+// The ask panel runs tmct's engine bundled for the browser (see askSource() below), adapter-less —
+// there is no wink lemma tier or ~4 MB browser model.
 
 // Portable single-file gate: above this serialized graph size, embedding the
 // full raw graph inline yields an unopenable multi-hundred-MB HTML, so the
@@ -213,24 +213,12 @@ const inlineJson = (v) => JSON.stringify(v).replace(/</g, "\\u003c");
  * silently produce incomplete answers, which this project's honesty contract
  * doesn't allow (see the file-level comment's "ONE viewer, three data channels" —
  * this is a fourth, for the same one-viewer-many-modes reason).
- *
- * The OPTIONAL wink-nlp lemma tier (ask-nlp.mjs's browser twin, from nlp-bundle.mjs)
- * reaches the chat two ways: `nlpInline` inlines the ~4 MB bundle as its own <script>
- * so it registers `window.__seonixNlp` at page load (portable `viz --nlp`); `nlpPath`
- * points the page at a same-origin sibling asset the chat LAZY-loads on first ask
- * (the SITE build). Neither is present in the default local single-file — that viewer
- * stays lemma-off and fetches nothing, exactly as before, preserving its
- * no-external-fetch guarantee. ask() picks up whatever `window.__seonixNlp` is set,
- * or degrades to the adapter-less tiers when it's absent.
  */
-export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null, dataPath = null, askData = null, askDataPath = null, nlpInline = null, nlpPath = null } = {}) {
+export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null, dataPath = null, askData = null, askDataPath = null } = {}) {
   const embedded = embedData ? `<script type="application/json" id="seonix-data">${inlineJson(embedData)}</script>\n` : "";
   const askEmbedded = askData ? `<script type="application/json" id="seonix-ask-data">${inlineJson(askData)}</script>\n` : "";
-  const cfgObj = { ...(dataPath ? { data: dataPath } : {}), ...(askDataPath ? { ask: askDataPath } : {}), ...(nlpPath ? { nlp: nlpPath } : {}) };
+  const cfgObj = { ...(dataPath ? { data: dataPath } : {}), ...(askDataPath ? { ask: askDataPath } : {}) };
   const cfg = Object.keys(cfgObj).length ? `<script type="application/json" id="seonix-cfg">${inlineJson(cfgObj)}</script>\n` : "";
-  // Inline bundle: escape any literal </script inside the wink model data so the
-  // block can't be closed early (harmless inside JS strings, impossible outside them).
-  const nlpEmbedded = nlpInline ? `<script>${String(nlpInline).replace(/<\/script/gi, "<\\/script")}</script>\n` : "";
   return `<!doctype html><html><head><meta charset="utf-8"><title>seon code-map</title>
 <!-- generated by: seonix viz (see packages/seonix/src/viz.mjs) — one viewer, data loaded at runtime -->
 <style>
@@ -308,7 +296,7 @@ export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null,
 </div>
 ${embedded}${askEmbedded}${cfg}<script>${cytoscape}</script>
 <script>${askEngine}</script>
-${nlpEmbedded}<script>
+<script>
 // Type palette (see the CVD note in viz.mjs) — viewer styling, identical for every repo.
 const COLORS={Module:'#3987e5',Class:'#c98500',Function:'#008300',Method:'#d55181',Attribute:'#9085e9',GlobalVariable:'#d95926',Commit:'#199e70'};
 const $=id=>document.getElementById(id);
@@ -351,29 +339,6 @@ function loadAskData(){
   })();
   return _askGraphPromise;
 }
-// The OPTIONAL wink-nlp lemma adapter (window.__seonixNlp — see nlp-bundle.mjs).
-// An inlined bundle registers it at page load; the site build ships it as a
-// same-origin sibling this injects LAZILY on the first ask (never at boot), so the
-// ~4 MB model is only paid for when the chat is actually used. With neither present
-// (the default local single-file) this resolves to undefined and the chat runs
-// adapter-less — ask() then falls back to its curated + fuzzy tiers, exactly as
-// before, and NOTHING is fetched, keeping the no-external-fetch guarantee intact.
-let _nlpPromise=null;
-function loadNlp(){
-  if(window.__seonixNlp) return Promise.resolve(window.__seonixNlp);
-  if(_nlpPromise) return _nlpPromise;
-  const cfgEl=document.getElementById('seonix-cfg');
-  const url=cfgEl?JSON.parse(cfgEl.textContent).nlp:null;
-  if(!url) return Promise.resolve(undefined);
-  _nlpPromise=new Promise(res=>{
-    const s=document.createElement('script');
-    s.src=url;
-    s.onload=()=>res(window.__seonixNlp);
-    s.onerror=()=>res(undefined); // a failed asset degrades to lemma-off, never a broken chat
-    document.head.appendChild(s);
-  });
-  return _nlpPromise;
-}
 function init(G){
   document.title='seon code-map — '+G.focusLabel;
   $('focuslabel').textContent=G.focusLabel;
@@ -616,10 +581,9 @@ function init(G){
       return;
     }
     out.textContent='thinking…';
-    // Load the graph and (if configured) the wink lemma adapter together, then run
-    // the mechanical ask. An undefined nlp makes ask() degrade to its adapter-less tiers.
-    Promise.all([loadAskData(),loadNlp()]).then(([askGraph,nlp])=>{
-      const {content,seonix_ask}=ask(askGraph,query,{contextId:selId,nlp});
+    // Lazy-load the graph, then run the mechanical ask over it.
+    loadAskData().then((askGraph)=>{
+      const {content,seonix_ask}=ask(askGraph,query,{contextId:selId});
       const total=(seonix_ask.matches||[]).length;
       const shown=total?highlightAsk(seonix_ask.matches.map(m=>m.id)):0;
       out.classList.toggle('miss',!!seonix_ask.miss);
@@ -709,12 +673,10 @@ function resolveFocus(graph, focusArg) {
  * code browser rides along at `/code-browser.html` (alias `/browser`) with a live
  * temporal payload — the local equivalent of the site's browser section.
  */
-export async function startVizServer({ values, cytoscape, askEngine = "", nlpBundle = null, log = () => {} }) {
+export async function startVizServer({ values, cytoscape, askEngine = "", log = () => {} }) {
   const port = Math.max(0, parseInt(values.port, 10) || 0);
   const repoUrl = values["repo-url"] || (await repoUrlFromGit(process.cwd()));
-  // With --nlp the local live view gets the same lemma tier as the site: the bundle
-  // is served in-process at /seonix-nlp.js and the viewer lazy-loads it on first ask.
-  const viewer = renderViewerHtml({ cytoscape, askEngine, nlpPath: nlpBundle ? "/seonix-nlp.js" : null });
+  const viewer = renderViewerHtml({ cytoscape, askEngine });
   const browserPage = await renderBrowserHtml({ cytoscape });
   // nav = the routes this server itself serves; injected into every payload/page
   const nav = { home: "/", graph: "/seonix-graph.html", browser: "/code-browser.html", timeline: "/timeline.html" };
@@ -815,9 +777,6 @@ export async function startVizServer({ values, cytoscape, askEngine = "", nlpBun
         res.writeHead(500, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: String(err.message || err) }));
       }
-    } else if (path === "/seonix-nlp.js" && nlpBundle) {
-      res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
-      res.end(nlpBundle);
     } else {
       res.writeHead(404, { "content-type": "text/plain" });
       res.end("not found");
@@ -856,11 +815,6 @@ export async function runVizCli(argv) {
       // truncation ("newest N of M commits"). See src/timeline.mjs.
       limit: { type: "string", default: "100" },
       scope: { type: "string", default: "product" },
-      // Include the OPTIONAL wink-nlp lemma tier in the chat (see nlp-bundle.mjs).
-      // Site mode (--data-out): written as a same-origin sibling the page lazy-loads.
-      // Portable/serve mode: inlined (single-file) / served in-process. Off by default,
-      // so the local single-file stays lean and lemma-off exactly as before.
-      nlp: { type: "boolean", default: false },
       // Portable branch only: embed the full graph inline even past the size gate
       // (INLINE_ASKDATA_MAX_BYTES). Off by default — over-threshold graphs write
       // sidecars instead of an unopenable multi-hundred-MB single file.
@@ -870,11 +824,8 @@ export async function runVizCli(argv) {
   });
   const cytoscape = await cytoscapeSource();
   const askEngine = await askSource();
-  // The wink lemma tier was removed in Stage 6 (the panel runs tmct's engine adapter-less), so there
-  // is never a bundle to wire. `--nlp` is accepted but inert; the downstream null-guards no-op.
-  const nlpBundle = null;
   if (values.serve) {
-    await startVizServer({ values, cytoscape, askEngine, nlpBundle, log: (s) => process.stderr.write(s) });
+    await startVizServer({ values, cytoscape, askEngine, log: (s) => process.stderr.write(s) });
     return; // keeps serving until Ctrl-C
   }
   const { config, graph, raw, graphBytes } = await loadGraph(values);
@@ -926,32 +877,22 @@ export async function runVizCli(argv) {
     const rel = relative(dirname(out), dataOut) || "seonix-graph-data.json";
     const askDataOut = resolve(dirname(out), "seonix-ask-data.json");
     const askRel = relative(dirname(out), askDataOut) || "seonix-ask-data.json";
-    // The wink lemma bundle rides the same sibling-asset convention as the data
-    // files — a same-origin ./seonix-nlp.js the page lazy-loads on first ask.
-    let nlpPath = null;
-    if (nlpBundle) {
-      const nlpOut = resolve(dirname(out), "seonix-nlp.js");
-      await writeFile(nlpOut, nlpBundle);
-      nlpPath = "./seonix-nlp.js";
-    }
     await Promise.all([writeFile(dataOut, JSON.stringify(data)), writeFile(askDataOut, JSON.stringify(raw))]);
     await writeFile(out, renderViewerHtml({
       cytoscape, askEngine,
       dataPath: rel === "seonix-graph-data.json" ? null : rel,
       askDataPath: askRel === "seonix-ask-data.json" ? null : askRel,
-      nlpPath,
     }));
-    return { dataOut, askDataOut, nlpPath };
+    return { dataOut, askDataOut };
   };
   if (values["data-out"]) {
     // site mode: viewer page + sibling data file (data updates don't touch the page).
     // The chat panel's full-graph channel rides the same sibling-file convention,
     // written next to the display data file rather than embedded in the page.
-    const { dataOut, askDataOut, nlpPath } = await writeSplitViewer(resolve(values["data-out"]));
+    const { dataOut, askDataOut } = await writeSplitViewer(resolve(values["data-out"]));
     process.stderr.write(
       `seonix viz: ${subgraph.nodes.length} nodes, ${subgraph.edges.length} edges around "${focus.label}" ` +
-        `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out} + ${dataOut} + ${askDataOut}` +
-        `${nlpPath ? ` + ${resolve(dirname(out), "seonix-nlp.js")} (wink lemma tier)` : ""}\n`,
+        `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out} + ${dataOut} + ${askDataOut}\n`,
     );
   } else if (graphBytes > inlineAskDataMaxBytes() && !values["force-inline"]) {
     // portable mode, but the graph is too big to embed: an estate-scale full-graph
@@ -970,9 +911,8 @@ export async function runVizCli(argv) {
         `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out} + ${dataOut} + ${askDataOut}\n`,
     );
   } else {
-    // portable mode: one self-contained file, both channels embedded (+ inline wink
-    // bundle when --nlp; otherwise lemma-off, no external fetch, exactly as before)
-    await writeFile(out, renderViewerHtml({ cytoscape, askEngine, embedData: data, askData: raw, nlpInline: nlpBundle }));
+    // portable mode: one self-contained file, both data channels embedded, no external fetch.
+    await writeFile(out, renderViewerHtml({ cytoscape, askEngine, embedData: data, askData: raw }));
     process.stderr.write(
       `seonix viz: ${subgraph.nodes.length} nodes, ${subgraph.edges.length} edges around "${focus.label}" ` +
         `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out}\n`,