fux-engine 2.0.0-alpha.7

package/src/verbs/answer.mjs

@@ -0,0 +1,143 @@
+/** `fux answer` — one passage, cited, with its footing stated every time.
+ *
+ * Ranks exactly as `ask` does with `top = 3`, then reads the cited documents
+ * back from the source and says whether they still say what the index thinks.
+ *
+ * 🔴 **It never fetches.** A `url:` document reads `.fux/acquired/` or the
+ * answer falls back to `source: "index"` — so this verb can emit
+ * `as-ingested` and `unverified`, and never `current` or `stale`, for a URL.
+ */
+import { runQuery } from "../query/run.mjs";
+import { recordFor } from "../store/reader.mjs";
+import { chunk } from "../refer/chunk.mjs";
+import { rescore } from "../refer/rescore.mjs";
+import { assemble, CITATION_OVERHEAD } from "../refer/assemble.mjs";
+import { Verdict } from "../refer/freshness.mjs";
+import { resolve, readLocal, fromAcquired, GIT } from "../refer/source.mjs";
+
+/** `answer` refers the top 3 — W-108. One question and no `-q`: an RRF score
+ *  would make the three incomparable. */
+export const ANSWER_TOP = 3;
+
+function obtain(root, record) {
+  const indexedSha = record.sha || "";
+  const [kind, target] = resolve(record.id);
+  if (kind === GIT) {
+    try {
+      const [raw, sha] = readLocal(root, target);
+      // Decoded documents carry no line numbers — a `.docx`'s Markdown exists
+      // nowhere on disk, so a line number would be a confident lie.
+      return { text: raw.toString("utf8"), verdict: Verdict.verify(indexedSha, sha), lineNumbers: true };
+    } catch (err) {
+      return { text: null, verdict: Verdict.unverified(indexedSha, String(err.message)), lineNumbers: true };
+    }
+  }
+  const blob = fromAcquired(root, indexedSha);
+  if (blob === null) {
+    return { text: null, verdict: Verdict.unverified(indexedSha, "node never fetches; nothing retained"), lineNumbers: false };
+  }
+  return {
+    text: blob[0].toString("utf8"),
+    verdict: Verdict.asIngested(indexedSha, blob[1], "read from .fux/acquired/"),
+    lineNumbers: false,
+  };
+}
+
+export function runAnswer(root, args) {
+  const query = args._.join(" ");
+  const { results, confidence } = runQuery(root, query, ANSWER_TOP, { wantConfidence: true });
+
+  if (!results.length) {
+    const payload = { answer: null, citation: null, source: "index" };
+    if (confidence && args.band) payload.confidence = confidence.asDict();
+    if (args.json) process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    else process.stdout.write("No confident matches.\n");
+    return 0;
+  }
+
+  // --no-refer: skip reading the source entirely. `verified` STAYS
+  // "unverified" — deliberately not upgraded, because nothing was checked.
+  if (args.noRefer) {
+    const top = results[0];
+    const record = recordFor(root, top.id);
+    const payload = {
+      answer: { passages: [{ id: top.id, loc: top.loc, heading: top.title,
+                             text: (record?.phrases || []).join("\n"), score: top.score }] },
+      citation: { id: top.id, loc: top.loc, sha: record?.sha ?? "", freshness: "unverified" },
+      source: "index",
+    };
+    if (confidence && args.band) payload.confidence = confidence.asDict();
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    return 0;
+  }
+
+  const candidates = [];
+  const verdicts = new Map();
+  for (const r of results) {
+    const record = recordFor(root, r.id);
+    if (!record) continue;
+    const got = obtain(root, record);
+    verdicts.set(r.id, got.verdict);
+    if (got.text === null) continue;
+    candidates.push([r.id, r.loc, record.sha || "",
+                     chunk(got.text, { lineNumbers: got.lineNumbers })]);
+  }
+
+  if (!candidates.length) {
+    const top = results[0];
+    const payload = {
+      answer: null, citation: { id: top.id, loc: top.loc, sha: "", freshness: "unverified" },
+      source: "index",
+    };
+    if (confidence && args.band) payload.confidence = confidence.asDict();
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    return 0;
+  }
+
+  const scored = rescore(query, candidates);
+  const bundle = assemble(scored, { overhead: CITATION_OVERHEAD });
+
+  if (!bundle.citations.length) {
+    process.stdout.write(JSON.stringify({ answer: null, citation: null, source: "refer" }, null, 2) + "\n");
+    return 0;
+  }
+
+  // The verdict of the document behind the WINNING citation, not documents[0].
+  const winner = bundle.citations[0];
+  const verdict = verdicts.get(winner.doc_id);
+  const freshness = verdict ? verdict.label : "unverified";
+
+  const payload = {
+    answer: {
+      passages: bundle.citations.map((c) => ({
+        id: c.doc_id, loc: c.locator, sha: c.sha,
+        heading: c.heading, text: c.text, score: c.score,
+      })),
+    },
+    citation: { id: winner.doc_id, loc: winner.locator, sha: winner.sha, freshness },
+    source: "refer",
+  };
+  // The band is raised to the winning document's verdict — one function, one
+  // place, because the printer and the receipt disagreed once in production.
+  if (confidence && args.band) payload.confidence = confidence.withVerified(freshness).asDict();
+  if (args.audit) {
+    payload.audit = {
+      documents: [...verdicts].map(([id, v]) => ({
+        id, freshness: v.label, indexed_sha: v.indexedSha,
+        fetched_sha: v.fetchedSha, strategy: "local", note: v.note,
+      })),
+      budget: bundle.budget, used: bundle.used, dropped: bundle.dropped,
+    };
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  } else {
+    for (const p of payload.answer.passages) {
+      process.stdout.write(`${p.loc}  [${freshness}]\n`);
+      if (p.heading) process.stdout.write(`§ ${p.heading}\n`);
+      process.stdout.write(p.text + "\n\n");
+    }
+  }
+  return 0;
+}

package/src/verbs/ask.mjs

@@ -0,0 +1,48 @@
+/** `fux ask` — a ranked list with scores, which is what you want when you are
+ *  judging the engine. A projection of `run_query`, never a second strategy. */
+import { runFused } from "../query/run.mjs";
+import { headingsFor } from "../query/headings.mjs";
+import { recordFor } from "../store/reader.mjs";
+
+export function runAsk(root, args) {
+  const query = args._.join(" ");
+  const queries = [query, ...(args.q || [])];
+  const top = args.top ?? 5;
+
+  const { results, confidence, fused } = runFused(root, queries, top, {
+    wantConfidence: true,
+  });
+
+  // Headings are display-only and are resolved AFTER ranking, exactly like the
+  // title fallback — so they can never reach a score.
+  const showSections = args.sections !== false;
+  const rows = results.map((r) => {
+    const out = { ...r };
+    if (showSections) out.headings = headingsFor(recordFor(root, r.id), query);
+    return out;
+  });
+
+  if (args.json) {
+    const payload = { results: rows };
+    // ADR-CONFIDENCE decision 11: present ONLY under --band. **Absent means
+    // NOT ASKED FOR — it is never a claim about the answer.**
+    if (confidence && args.band) payload.confidence = confidence.asDict();
+    // An RRF score and a BM25F score are not comparable, so a consumer must be
+    // told which it is holding.
+    if (fused) payload.fused = true;
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  } else {
+    if (!rows.length) {
+      process.stdout.write("No confident matches.\n");
+      return 0;
+    }
+    for (const r of rows) {
+      const tie = r.tie ? "  (tie)" : "";
+      const arch = r.archived ? " [archived]" : "";
+      process.stdout.write(`${r.score.toFixed(4)}${tie}${arch} ${r.title} (${r.loc})\n`);
+      for (const h of r.headings || []) process.stdout.write(`    § ${h}\n`);
+    }
+    if (confidence && args.band) process.stderr.write(`[${confidence.band}] ${confidence.asDict().support} scored\n`);
+  }
+  return 0;
+}

package/src/verbs/find.mjs

@@ -0,0 +1,24 @@
+/** `fux find` — ranked document locations, one per line, for pipes.
+ *  A projection of `ask`, not a second strategy: same scan, same rank(). */
+import { ask } from "../query/scan.mjs";
+import { pyRepr } from "../compat/pyfloat.mjs";
+
+export function runFind(root, args) {
+  const query = args._.join(" ");
+  const top = args.top ?? 5;
+  let results = ask(root, query, top);
+
+  if (args.under) {
+    const p = args.under.endsWith("/") ? args.under : args.under + "/";
+    results = results.filter((r) => r.loc === args.under || r.loc.startsWith(p));
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ results }, null, 2) + "\n");
+  } else {
+    for (const r of results) {
+      process.stdout.write(`${r.loc}${r.archived ? "  [archived]" : ""}\n`);
+    }
+  }
+  return 0;
+}

package/src/verbs/graph.mjs

@@ -0,0 +1,110 @@
+/** `explain` · `graph` · `path` — the group that does NOT rank.
+ *
+ * `ask`/`find`/`answer` return documents ordered by relevance; these return
+ * **relationships the documents themselves stated**. That is why they are a
+ * group rather than three more read verbs.
+ *
+ * Node rebuilds the plane in memory from the committed records; it does not
+ * read Python's derived `.fux/runtime/graph.json`.
+ */
+import { buildPlane } from "../graph/plane.mjs";
+import { iterShardPaths, rawRecordLines } from "../store/reader.mjs";
+import { ask as scanAsk } from "../query/scan.mjs";
+import { cmpCodePoints } from "../compat/pyfloat.mjs";
+
+function allRecords(root) {
+  const out = [];
+  for (const path of iterShardPaths(root)) {
+    const [, lines] = rawRecordLines(path);
+    for (const line of lines) out.push(JSON.parse(line.toString("utf8")));
+  }
+  return out;
+}
+
+/** One document's outbound edges and the community it landed in. */
+export function runExplain(root, args) {
+  const docId = args._[0];
+  if (!docId) { process.stderr.write("error: explain needs a document id\n"); return 1; }
+  const plane = buildPlane(allRecords(root));
+  const edges = plane.graph.outEdges(docId);
+  const community = plane.communityOf(docId);
+  const payload = {
+    id: docId,
+    community,
+    members: community ? plane.members(community) : [],
+    edges: edges.map((e) => ({ kind: e.kind, dst: e.dst, grade: e.grade })),
+  };
+  if (args.json) process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  else {
+    process.stdout.write(`${docId}\n  community: ${community ?? "(none)"}\n`);
+    for (const e of edges) process.stdout.write(`  ${e.kind} -> ${e.dst} (${e.grade})\n`);
+  }
+  return 0;
+}
+
+/** The neighbourhood around a query's best answers. */
+export function runGraph(root, args) {
+  const query = args._.join(" ");
+  const hops = args.hops ?? 1;
+  const plane = buildPlane(allRecords(root));
+  const seeds = scanAsk(root, query, args.top ?? 5).map((r) => r.id);
+
+  const seen = new Map(seeds.map((s) => [s, 0]));
+  let frontier = [...seeds];
+  for (let depth = 1; depth <= hops; depth++) {
+    const next = [];
+    for (const node of frontier) {
+      for (const [neighbour] of plane.graph.neighbours(node)) {
+        if (!seen.has(neighbour)) { seen.set(neighbour, depth); next.push(neighbour); }
+      }
+    }
+    frontier = next;
+  }
+  const nodes = [...seen].sort((a, b) => (a[1] - b[1]) || cmpCodePoints(a[0], b[0]))
+    .map(([id, distance]) => ({ id, distance, community: plane.communityOf(id) }));
+
+  if (args.json) process.stdout.write(JSON.stringify({ seeds, hops, nodes }, null, 2) + "\n");
+  else for (const n of nodes) process.stdout.write(`${"  ".repeat(n.distance)}${n.id}\n`);
+  return 0;
+}
+
+/** How two documents are connected, most reliable route first.
+ *  Breadth-first over the undirected graph, with the highest-grade route
+ *  preferred at equal length — a shorter route through a weak edge is not
+ *  more reliable than a longer one through strong ones. */
+export function runPath(root, args) {
+  const [from, to] = args._;
+  if (!from || !to) { process.stderr.write("error: path needs two document ids\n"); return 1; }
+  const plane = buildPlane(allRecords(root));
+  const maxHops = args.hops ?? 6;
+
+  let best = null;
+  const queue = [[from, [from], 0]];
+  const bestSeen = new Map([[from, 0]]);
+  while (queue.length) {
+    const [node, route, weight] = queue.shift();
+    if (node === to) {
+      if (best === null || route.length < best.route.length
+          || (route.length === best.route.length && weight > best.weight)) {
+        best = { route, weight };
+      }
+      continue;
+    }
+    if (route.length > maxHops) continue;
+    for (const [neighbour, grade] of plane.graph.neighbours(node)) {
+      if (route.includes(neighbour)) continue;
+      const prior = bestSeen.get(neighbour);
+      if (prior !== undefined && prior < route.length) continue;
+      bestSeen.set(neighbour, route.length);
+      queue.push([neighbour, [...route, neighbour], weight + grade]);
+    }
+  }
+
+  const payload = best
+    ? { from, to, hops: best.route.length - 1, route: best.route, weight: best.weight }
+    : { from, to, hops: null, route: [], weight: 0 };
+  if (args.json) process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  else if (best) process.stdout.write(best.route.join("\n  -> ") + "\n");
+  else process.stdout.write(`no route from ${from} to ${to} within ${maxHops} hops\n`);
+  return 0;
+}

package/src/verbs/mcp.mjs

@@ -0,0 +1,145 @@
+/** `fux mcp` — the index over the Model Context Protocol, on stdio.
+ *  Twin of `src/fux/mcp.py`'s protocol half.
+ *
+ * Newline-delimited JSON-RPC: `initialize` -> `notifications/initialized`,
+ * `tools/list`, `tools/call`, and a notification (no `id`) is never answered.
+ *
+ * ⚠ **The tool DESCRIPTIONS are the one thing that must not be transcribed.**
+ * A description is what an agent reads to decide whether to call a tool, so
+ * two hand-maintained copies would drift into two different products wearing
+ * one name. This half loads them from `mcp-tools.json`.
+ *
+ * 🔴 **`src/fux/mcp.py` does NOT read that file — it still carries its own
+ * literal, and the drift was real**: measured 2026-09-12, this side emitted
+ * `"default": "5"` (a STRING) where Python emits `5` (an integer), on a
+ * property declared `"type": "integer"`. What holds them equal is
+ * `tests/test_mcp.py::test_the_node_tool_file_matches_the_python_literal`,
+ * not a shared read — ADR-MCP decision 11 states why, and what that leaves
+ * unguarded once this file ships to npm on its own.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { ask as scanAsk } from "../query/scan.mjs";
+import { recordFor } from "../store/reader.mjs";
+import { buildPlane } from "../graph/plane.mjs";
+import { iterShardPaths, rawRecordLines } from "../store/reader.mjs";
+import { chunk } from "../refer/chunk.mjs";
+
+export const PROTOCOL_VERSION = "2024-11-05";
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+let TOOLS = null;
+function tools(top) {
+  if (TOOLS === null) {
+    TOOLS = JSON.parse(readFileSync(join(HERE, "..", "..", "mcp-tools.json"), "utf8")).tools;
+  }
+  // The only per-connection substitution: the resolved `[mcp] top` appears in
+  // the `top` property's description so an agent sees the real default.
+  //
+  // ⚠ **The QUOTED form is replaced first, and un-quoted.** `"{{TOP}}"` is a
+  // JSON *number* on the Python side (`"default": 5`); a naive `replaceAll`
+  // over the serialized text leaves it a string, which is an `inputSchema`
+  // that contradicts its own `"type": "integer"`. Found 2026-09-12 by the
+  // equality test, not by a client complaining.
+  const text = JSON.stringify(TOOLS)
+    .replaceAll('"{{TOP}}"', String(top))
+    .replaceAll("{{TOP}}", String(top));
+  return JSON.parse(text);
+}
+
+const ok = (id, result) => ({ jsonrpc: "2.0", id, result });
+const err = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+
+function allRecords(root) {
+  const out = [];
+  for (const path of iterShardPaths(root)) {
+    const [, lines] = rawRecordLines(path);
+    for (const line of lines) out.push(JSON.parse(line.toString("utf8")));
+  }
+  return out;
+}
+
+function fuxSearch(root, args, top) {
+  const results = scanAsk(root, args.query ?? "", args.top ?? top);
+  return { results: results.map((r) => ({ id: r.id, loc: r.loc, title: r.title, score: r.score, archived: r.archived })) };
+}
+
+function fuxPassage(root, args) {
+  const record = recordFor(root, args.id);
+  if (!record) return { passages: [] };
+  // Node never fetches: a `url:` document has no local bytes to chunk.
+  if (!record.id.startsWith("file:")) return { passages: [], note: "node never fetches" };
+  const { readFileSync: rf, existsSync } = { readFileSync, existsSync: (p) => { try { rf(p); return true; } catch { return false; } } };
+  let text;
+  try { text = readFileSync(join(root, record.loc), "utf8"); }
+  catch { return { passages: [], note: "not in the working tree" }; }
+  return {
+    passages: chunk(text).map((p) => ({
+      loc: p.line_start ? `${record.loc}:L${p.line_start}-L${p.line_end}` : `${record.loc}#p${p.ordinal}`,
+      heading: p.heading, text: p.text, ordinal: p.ordinal,
+    })),
+  };
+}
+
+function fuxRelated(root, args) {
+  const plane = buildPlane(allRecords(root));
+  const id = args.id;
+  const community = plane.communityOf(id);
+  return {
+    id, community,
+    members: community ? plane.members(community) : [],
+    edges: plane.graph.outEdges(id).map((e) => ({ kind: e.kind, dst: e.dst, grade: e.grade })),
+  };
+}
+
+export function handle(root, message, top) {
+  const method = message.method;
+  const id = message.id;
+  // A notification has no id and MUST NOT be answered.
+  if (id === undefined || id === null) return null;
+
+  if (method === "initialize") {
+    return ok(id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: "fux", version: "2.0.0-alpha.7" },
+    });
+  }
+  if (method === "tools/list") return ok(id, { tools: tools(top) });
+  if (method === "tools/call") {
+    const params = message.params || {};
+    const handlers = {
+      fux_search: (r, a) => fuxSearch(r, a, top),
+      fux_passage: fuxPassage,
+      fux_related: fuxRelated,
+    };
+    const handler = handlers[params.name];
+    if (handler === undefined) return err(id, -32602, `unknown tool ${JSON.stringify(params.name)}`);
+    let payload;
+    try { payload = handler(root, params.arguments || {}); }
+    catch (e) {
+      return ok(id, { content: [{ type: "text", text: String(e.message) }], isError: true });
+    }
+    return ok(id, {
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      structuredContent: payload,
+    });
+  }
+  return err(id, -32601, `unknown method ${JSON.stringify(method)}`);
+}
+
+export function runMcp(root, args) {
+  const top = args.top ?? 5;
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try { message = JSON.parse(line); }
+    catch { process.stdout.write(JSON.stringify(err(null, -32700, "parse error")) + "\n"); return; }
+    const response = handle(root, message, top);
+    if (response !== null) process.stdout.write(JSON.stringify(response) + "\n");
+  });
+  return 0;
+}