fux-engine 2.0.0-alpha.7 → 2.0.0

package/README.md

@@ -1,45 +1,107 @@
-# fux-engine
+# fux-engine — the Node read plane
 
 Read a [fux](https://github.com/arpitarya/fux) index from Node. **The command
 is `fux`; the package is `fux-engine`** — `fux` was taken on npm in 2016.
 
+> **This file ships twice**, on purpose: it is the npm package's page, and
+> `fux setup` vendors it into your repository at `.fux/node/README.md`. So it is
+> written for whoever finds it, in either place.
+
+## Run it
+
+**In a repository that has a fux index, always through the shim:**
+
+```console
+$ .fux/fux find rollback
+$ .fux/fux ask "how do we roll back a release" --band
+$ .fux/fux answer "retry policy" --json
+```
+
+🔴 **`.fux/fux` is the one entry point that is correct in every shape**, which
+is why it is the only one documented. It resolves the reader in three rungs —
+the vendored bundle, then `.fux/node/node_modules/.bin/fux`, then every
+ancestor's `node_modules/.bin/fux` — because npm and Yarn hoist that binary to
+the workspace root and **pnpm and bun do not**. Naming a path instead would be
+right for half the ecosystem and silently wrong for the other half.
+
+**Without a repository, or to try it:**
+
 ```console
-$ npx fux-engine find rollback
-$ node .fux/fux.mjs find rollback     # a clone with nothing installed
+$ npx fux-engine --version
 ```
 
+**As a library:**
+
 ```js
 import { open } from 'fux-engine'
 const ix = await open('.')
 await ix.find('rollback', { top: 5 })
 ```
 
+## What is in `.fux/node/`
+
+`fux setup` writes one of two shapes, and it detects which:
+
+| | what is there | offline | how it runs |
+|---|---|---|---|
+| **the default** | `fux.mjs` (one generated file) · `package.json` · `mcp-tools.json` · this file | **yes** — nothing to install | `.fux/fux …` |
+| **a monorepo** | `package.json` only, declaring `fux-engine@<version>` | after an install | `.fux/fux …`, once your package manager has run |
+
+In the monorepo shape `.fux/node` is declared as a **workspace member** in your
+root manifest — `fux setup` adds that one line, says so, and never adds it
+twice. Run your package manager's `install` afterwards; `fux doctor` tells you
+if you have not.
+
+🔴 **`fux.mjs` is GENERATED. Do not edit it.** It is rebuilt from fux's sources
+at publish time and overwritten whenever the engine version changes. To see what
+it does, read `node/fux.mjs` and `node/src/**` in the fux repository at the
+matching tag — or regenerate it and compare bytes:
+
+```console
+$ python -m fux.store.nodebundle node node/dist
+```
+
 ## What it is
 
 A fux index is a small, plain-text index committed to git — statistics about
 your documents, never the documents. Python writes it; **Python or Node reads
 it, and the two are held byte-equal by a differential law.**
 
-- **Zero dependencies.** No `dependencies` key in `package.json` at all, and
-  no build step. A build step is a dependency.
+- **Zero dependencies, and no build step *for you*.** There is no
+  `dependencies` key in the published `package.json` at all. Fux's own release
+  pipeline has a bundler; nobody running `fux setup` does, and nothing is
+  compiled on your machine.
+- **One artefact, not a module tree.** What lands in your repository is one
+  generated file, so a fux upgrade is a one-file diff and a tampered reader is
+  detectable by rebuilding it. Before 2026-09-12 it was 47 of fux's own `.mjs`
+  files in your tree; `fux setup` deletes them when it upgrades you.
 - **It never writes and never fetches.** `ingest`, `build`, `add`, `enrich`
   and every other write verb belongs to Python fux, and typing one here tells
   you so rather than saying *unknown command*.
 - **Same answers as Python.** Same ids, same order, same locators, same band;
-  scores equal after `round(9)`, which is the sort key's own resolution
-  (ADR-RANKING decision 8a).
+  scores equal after `round(9)`, which is the sort key's own resolution.
+- **Two things it deliberately does not do.** It cannot read a document that
+  needs a decoder (a `.pdf`, a `.xlsx`, your own `.fux/decoders/*.py`), so
+  `answer` **declines** to cite one rather than quoting line numbers into text
+  the index never held; and it never touches the network.
 
 ## Two `fux` commands on one PATH
 
 Python's `fux-engine` installs a `fux` too, with a **different verb set**.
-`--version` names the runtime so no bug report is ever ambiguous:
+`--version` names the runtime, so no bug report is ever ambiguous:
 
 ```console
 $ fux --version
-fux 2.0.0-alpha.7 (node 22.9.0)
+fux 2.0.0 (node 24.13.0)
 ```
 
-## Status
+`fux doctor` (Python's) reports when a Node `fux` sits earlier on your PATH.
+
+## Verbs
+
+`find` · `ask` · `answer` · `explain` · `graph` · `path` · `mcp`
 
-**W-107 Phase 1.** `find` is implemented and pinned against Python.
-`ask` / `answer` land in Phase 2, the graph verbs and `mcp` in Phase 3.
+`fux mcp` serves the index over the Model Context Protocol on stdio —
+`fux_search`, `fux_passage`, `fux_related` — so an agent can query it with no
+glue. `verify`, `--why`, `--receipt` and `--journal` have no Node twin; they are
+Python's.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "fux-engine",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0",
   "description": "Read a fux index from Node. Ranked, cited answers from a small index committed to git — no server, no model, no Python.",
   "type": "module",
   "engines": { "node": ">=20" },
   "bin": { "fux": "./fux.mjs" },
-  "exports": { ".": "./src/index.mjs" },
-  "files": ["fux.mjs", "src", "mcp-tools.json", "README.md"],
+  "exports": { ".": "./fux.mjs" },
+  "files": ["fux.mjs", "mcp-tools.json", "README.md"],
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/arpitarya/fux.git" },
   "homepage": "https://github.com/arpitarya/fux#readme",

package/src/compat/pyfloat.mjs

@@ -1,95 +0,0 @@
-/** Python float semantics JS does not share. No Python twin — declared exempt.
- *
- * Two of them reach the sort key, so both are correctness, not cosmetics.
- */
-
-/** Python's `round(x, ndigits)` — round-HALF-EVEN on the exact binary value.
- *
- * ⚠ `Number(x.toFixed(9))` agrees on ~200 000 random doubles and **fails on
- * exact binary ties**, where `toFixed` rounds half-UP and Python rounds
- * half-even. `round(score, 9)` is the sort key's own resolution
- * ([ADR-RANKING decision 8a](../../../docs/adr/0111_ranking.md)), so a tie
- * resolved the other way is a different ORDER — the one thing
- * PRE-REGISTRATION-NODE §2 calls non-negotiable.
- *
- * The tie is detected by asking for more digits than `toFixed(9)` kept: if
- * everything past the 9th digit is exactly `5` followed by zeros, the value
- * sits on the boundary and the winner is the even neighbour.
- */
-export function pyRound9(x) {
-  if (!Number.isFinite(x)) return x;
-  const s = x.toFixed(20);                 // enough digits to see the tie exactly
-  const dot = s.indexOf(".");
-  const tail = s.slice(dot + 1 + 9);       // digits past the 9th decimal
-  const naive = Number(x.toFixed(9));
-  if (!/^50*$/.test(tail)) return naive;   // not a tie — toFixed is already right
-
-  // Exact tie: choose the even neighbour.
-  const keep = s.slice(0, dot + 1 + 9);
-  const lower = Number(keep);
-  const step = 1e-9;
-  const lastDigit = Number(keep[keep.length - 1]);
-  if (lastDigit % 2 === 0) return lower;
-  return Number((lower + (x < 0 ? -step : step)).toFixed(9));
-}
-
-/** Python's `repr(float)` layout, which differs from `String(Number)`.
- *
- * Both are shortest-round-trip, so the DIGITS always agree; the exponent
- * thresholds and the integral form do not:
- *
- *     value      Python repr     JS String
- *     2.0        "2.0"           "2"
- *     1e-5       "1e-05"         "0.00001"
- *     1e16       "1e+16"         "10000000000000000"
- *
- * Python switches to exponent when `e < -4 or e >= 16`; JS at `-6 / 21`.
- */
-export function pyRepr(x) {
-  if (Number.isNaN(x)) return "nan";
-  if (x === Infinity) return "inf";
-  if (x === -Infinity) return "-inf";
-  if (Number.isInteger(x) && Math.abs(x) < 1e16) {
-    return Object.is(x, -0) ? "-0.0" : `${x}.0`;
-  }
-  const sign = x < 0 ? "-" : "";
-  const a = Math.abs(x);
-  const e = Math.floor(Math.log10(a));
-  if (e < -4 || e >= 16) {
-    // ⚠ Python does NOT pad the mantissa here: repr(1e-5) is "1e-05", not
-    // "1.0e-05". The ".0" padding applies only to the integral form above.
-    const [mant, exp] = a.toExponential().split("e");
-    const n = Number(exp);
-    const es = (n < 0 ? "-" : "+") + String(Math.abs(n)).padStart(2, "0");
-    return `${sign}${mant}e${es}`;
-  }
-  return `${sign}${String(a)}`;
-}
-
-/** Compare two strings by CODE POINT, the way Python compares `str`.
- *
- * 🔴 **This is W-107 hazard H1, and it is why `<` is not used anywhere on a
- * doc id.** JS compares strings by UTF-16 code UNIT, so a surrogate pair
- * (anything above U+FFFF — an emoji, a rare CJK extension character) sorts
- * BELOW U+E000–U+FFFF in JS and ABOVE it in Python. The sort key ends in
- * `id`, so one such document orders differently in the two runtimes and the
- * byte-equal ordering assertion fails with nothing else wrong.
- *
- * Iterating a string with `for..of` yields code points, not units, which is
- * exactly the comparison Python makes.
- */
-export function cmpCodePoints(a, b) {
-  if (a === b) return 0;
-  const ai = a[Symbol.iterator]();
-  const bi = b[Symbol.iterator]();
-  for (;;) {
-    const x = ai.next();
-    const y = bi.next();
-    if (x.done && y.done) return 0;
-    if (x.done) return -1;
-    if (y.done) return 1;
-    const cx = x.value.codePointAt(0);
-    const cy = y.value.codePointAt(0);
-    if (cx !== cy) return cx < cy ? -1 : 1;
-  }
-}

package/src/config/root.mjs

@@ -1,16 +0,0 @@
-/** Finding the repo root. Twin of `find_root` in `src/fux/config.py`.
- *  Walk up for `fux.toml` or `.git` — the same two tells, in the same order. */
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-
-export const CONFIG_NAME = "fux.toml";
-
-export function findRoot(start = process.cwd()) {
-  let here = resolve(start);
-  for (;;) {
-    if (existsSync(join(here, CONFIG_NAME)) || existsSync(join(here, ".git"))) return here;
-    const up = dirname(here);
-    if (up === here) return null;
-    here = up;
-  }
-}

package/src/decode/markdown.mjs

@@ -1,52 +0,0 @@
-/** The ONE Markdown heading grammar, shared by ingest and the chunker.
- *  Twin of `src/fux/decode/_markdown.py`.
- *
- * **A fenced code block is content, not structure** — a `# comment` inside a
- * ``` block is not a heading, and treating it as one splits a document where
- * its author did not.
- */
-
-const HEADING_RE = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
-/** Up to three leading spaces per CommonMark; a fourth makes it an indented
- *  code block, which cannot contain a heading anyway. */
-const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
-
-/** `[lineno, line, fenced]` per line, `lineno` 1-based.
- *
- * The open fence is tracked as its DELIMITER STRING, not a boolean, so a
- * closing fence must match its opener in both character and length: ``` inside
- * a ~~~ block is content, and a shorter run of backticks does not close a
- * longer one. */
-export function* walk(markdown) {
-  let fence = null;
-  const lines = markdown.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const lineno = i + 1;
-    const match = FENCE_RE.exec(line);
-    if (fence === null) {
-      if (match) { fence = match[1]; yield [lineno, line, true]; }
-      else yield [lineno, line, false];
-      continue;
-    }
-    const closes = match !== null
-      && match[1][0] === fence[0]
-      && match[1].length >= fence.length
-      // A closing fence carries no info string.
-      && match[2].trim() === "";
-    if (closes) fence = null;
-    yield [lineno, line, true];
-  }
-}
-
-/** Every ATX heading outside a code fence, in document order.
- *  `lineno` is 1-based, matching the `path:L12-L40` citation format. */
-export function headings(markdown) {
-  const found = [];
-  for (const [lineno, line, fenced] of walk(markdown)) {
-    if (fenced) continue;
-    const match = HEADING_RE.exec(line);
-    if (match) found.push({ lineno, level: match[1].length, text: match[2].trim() });
-  }
-  return found;
-}

package/src/graph/community.mjs

@@ -1,59 +0,0 @@
-/** Label propagation, determinized. Twin of `src/fux/graph/community.py`.
- *
- * An isolated node is its own community — honest rather than tidy: it says
- * *this document stands alone*, which is a fact a reader wants, and it costs
- * one entry.
- */
-import { cmpCodePoints } from "../compat/pyfloat.mjs";
-
-export const MAX_SWEEPS = 20;
-
-/** Rename raw labels to `c0`, `c1`, … by (size desc, smallest member).
- *  Without this, a community's id is whichever node won the propagation —
- *  stable for one corpus, and liable to rename every community when a single
- *  document is added. */
-function canonicalize(labels) {
-  const members = new Map();
-  for (const [node, label] of labels) {
-    if (!members.has(label)) members.set(label, []);
-    members.get(label).push(node);
-  }
-  for (const group of members.values()) group.sort(cmpCodePoints);
-
-  const ordered = [...members.values()].sort((a, b) => {
-    if (a.length !== b.length) return b.length - a.length;
-    return cmpCodePoints(a[0], b[0]);
-  });
-  const out = new Map();
-  ordered.forEach((group, i) => { for (const node of group) out.set(node, `c${i}`); });
-  return out;
-}
-
-export function assign(graph) {
-  if (!graph.nodes.length) return new Map();
-
-  const labels = new Map(graph.nodes.map((n) => [n, n]));
-
-  for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
-    let changed = false;
-    for (const node of graph.nodes) {   // sorted: the visit order IS the determinism
-      const neighbours = graph.neighbours(node);
-      if (!neighbours.length) continue;
-      const weightByLabel = new Map();
-      for (const [neighbour, grade] of neighbours) {
-        const label = labels.get(neighbour);
-        weightByLabel.set(label, (weightByLabel.get(label) ?? 0) + grade);
-      }
-      // Heaviest label wins; ties go to the SMALLEST id, never to chance.
-      let best = null, bestWeight = -Infinity;
-      for (const [label, weight] of weightByLabel) {
-        if (weight > bestWeight || (weight === bestWeight && cmpCodePoints(label, best) < 0)) {
-          best = label; bestWeight = weight;
-        }
-      }
-      if (best !== labels.get(node)) { labels.set(node, best); changed = true; }
-    }
-    if (!changed) break;
-  }
-  return canonicalize(labels);
-}

package/src/graph/model.mjs

@@ -1,67 +0,0 @@
-/** The graph's shape. Twin of `src/fux/graph/model.py`.
- *
- * **Every accessor returns SORTED lists, and that is L3, not tidiness.**
- * Community assignment and PPR both accumulate over neighbours, and float
- * accumulation is not associative — an unsorted traversal makes the same
- * corpus produce different bytes on different runs.
- */
-import { cmpCodePoints } from "../compat/pyfloat.mjs";
-
-export const TAG_PREFIX = "tag:";
-
-/** Python sorts an `Edge` dataclass field-by-field in declaration order:
- *  `(src, kind, dst, grade)`. Strings by code point, ints numerically. */
-function cmpEdge(a, b) {
-  let c = cmpCodePoints(a.src, b.src); if (c) return c;
-  c = cmpCodePoints(a.kind, b.kind); if (c) return c;
-  c = cmpCodePoints(a.dst, b.dst); if (c) return c;
-  return a.grade - b.grade;
-}
-
-/** Python sorts a `(str, int)` tuple the same way. */
-function cmpNeighbour(a, b) {
-  const c = cmpCodePoints(a[0], b[0]);
-  return c !== 0 ? c : a[1] - b[1];
-}
-
-export class Graph {
-  constructor(edges) {
-    this.edges = [...edges].sort(cmpEdge);
-    this._out = new Map();
-    this._both = new Map();
-    const nodes = new Set();
-    for (const edge of this.edges) {
-      nodes.add(edge.src); nodes.add(edge.dst);
-      if (!this._out.has(edge.src)) this._out.set(edge.src, []);
-      this._out.get(edge.src).push(edge);
-      if (!this._both.has(edge.src)) this._both.set(edge.src, []);
-      this._both.get(edge.src).push([edge.dst, edge.grade]);
-      if (!this._both.has(edge.dst)) this._both.set(edge.dst, []);
-      this._both.get(edge.dst).push([edge.src, edge.grade]);
-    }
-    this.nodes = [...nodes].sort(cmpCodePoints);
-    for (const adjacency of this._both.values()) adjacency.sort(cmpNeighbour);
-  }
-
-  /** Outbound edges, canonically ordered. `path` and `explain` read this. */
-  outEdges(node) { return [...(this._out.get(node) ?? [])]; }
-  /** Undirected `[neighbour, grade]` pairs. Community and PPR read this. */
-  neighbours(node) { return [...(this._both.get(node) ?? [])]; }
-  /** Nodes that are documents — everything that is not a tag. */
-  documents() { return this.nodes.filter((n) => !n.startsWith(TAG_PREFIX)); }
-  get length() { return this.nodes.length; }
-}
-
-/** Lift the committed `edges` arrays into edges. They are already resolved and
- *  already dropped if dangling, so there is nothing to validate — only lift. */
-export function edgesFromRecords(records) {
-  const out = [];
-  for (const record of records) {
-    for (const edge of record.edges || []) {
-      out.push({ src: record.id, kind: edge.kind, dst: edge.dst, grade: Number(edge.grade) });
-    }
-  }
-  return out.sort(cmpEdge);
-}
-
-export { cmpEdge };

package/src/graph/plane.mjs

@@ -1,51 +0,0 @@
-/** The graph plane, rebuilt IN MEMORY. Twin of `src/fux/graph/plane.py`.
- *
- * 🔴 **Node does not read Python's `.fux/runtime/graph.json`** — it is a
- * derived file and Node's contract is the committed plane. It rebuilds the
- * same graph from the same records and **its digest must equal Python's**,
- * which is W-107's N2 gate. Reading the derived file instead would prove
- * nothing about whether the two agree.
- */
-import { createHash } from "node:crypto";
-import { Graph, edgesFromRecords } from "./model.mjs";
-import { assign } from "./community.mjs";
-import { cmpCodePoints } from "../compat/pyfloat.mjs";
-
-export const SCHEMA = "fux.graph.v1";
-export const GRAPH_NAME = "graph.json";
-
-export class GraphPlane {
-  constructor(graph, communities) { this.graph = graph; this.communities = communities; }
-  communityOf(node) { return this.communities.get(node) ?? null; }
-  members(label) {
-    return [...this.communities].filter(([, c]) => c === label).map(([n]) => n).sort(cmpCodePoints);
-  }
-}
-
-export function buildPlane(records) {
-  const graph = new Graph(edgesFromRecords(records));
-  return new GraphPlane(graph, assign(graph));
-}
-
-/** The exact bytes Python's `build_plane` writes, so the digests can be
- *  compared without either side reading the other's file.
- *
- *  A list of lists rather than a list of objects: machine-written and
- *  machine-read, and four values per edge beats four repeated keys at a
- *  million of them. */
-export function planeBytes(plane) {
-  const communities = {};
-  for (const node of [...plane.communities.keys()].sort(cmpCodePoints)) {
-    communities[node] = plane.communities.get(node);
-  }
-  const payload = {
-    schema: SCHEMA,
-    edges: plane.graph.edges.map((e) => [e.src, e.kind, e.dst, e.grade]),
-    communities,
-  };
-  return JSON.stringify(payload) + "\n";
-}
-
-export function planeDigest(plane) {
-  return createHash("sha256").update(planeBytes(plane), "utf8").digest("hex");
-}