@polycode-projects/seonix 0.7.3 → 0.9.0

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/chat-shim.mjs

@@ -0,0 +1,37 @@
+// chat-shim.mjs — `seonix chat` is now tmct's chat over seonix's graph.
+//
+// PLAN_CHAT_EXTRACTION.md, the inversion: the conversational surface belongs to tmct
+// (@polycode-projects/the-mechanical-code-talker). seonix stops running its own REPL and
+// launches tmct's, handing it graph truth through tmct's provider seam. seonix's on-disk
+// graph is interned v2, which tmct cannot read raw, so we expand it first (seonix's own
+// parseEntities does the same). The old opt-in --with-claude/--with-copilot fallback does
+// not port: tmct is no-LLM by contract.
+import { runChat } from "@polycode-projects/the-mechanical-code-talker/chat";
+import { registerProvider } from "@polycode-projects/the-mechanical-code-talker/fetchEntities";
+import { join } from "node:path";
+import { expandGraphPayload } from "./graph-format.mjs";
+import { fetchEntities } from "./source.mjs";
+import { loadConfig, DEFAULT_GRAPH_REL } from "./config.mjs";
+
+/** The seonix graph config for a repo (mirrors cli.mjs's configFor): an explicit
+ *  --repo dir points at its .seonix/graph.json; otherwise the loaded (cwd) config. */
+function seonixConfigFor(repoPath) {
+  return repoPath ? { graphFile: join(repoPath, DEFAULT_GRAPH_REL) } : loadConfig();
+}
+
+/**
+ * Run tmct's chat over seonix's native graph. Registers the (expanded) seonix graph as
+ * tmct's in-process data provider, runs the REPL, then clears the provider so nothing
+ * leaks across calls (important for tests and repeated invocations).
+ * @param {{repoPath?: string, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream,
+ *          env?: object, cwd?: string, gitRoot?: Function}} [opts]
+ */
+export async function runSeonixChat({ repoPath, input, output, env, cwd, gitRoot } = {}) {
+  const payload = expandGraphPayload(await fetchEntities(seonixConfigFor(repoPath)));
+  registerProvider(() => payload);
+  try {
+    return await runChat({ repoPath, input, output, env, cwd, gitRoot });
+  } finally {
+    registerProvider(null);
+  }
+}

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",