fux-engine 2.0.0-alpha.7

package/README.md

@@ -0,0 +1,45 @@
+# fux-engine
+
+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.
+
+```console
+$ npx fux-engine find rollback
+$ node .fux/fux.mjs find rollback     # a clone with nothing installed
+```
+
+```js
+import { open } from 'fux-engine'
+const ix = await open('.')
+await ix.find('rollback', { top: 5 })
+```
+
+## 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.
+- **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).
+
+## 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:
+
+```console
+$ fux --version
+fux 2.0.0-alpha.7 (node 22.9.0)
+```
+
+## Status
+
+**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.

package/fux.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/** `fux` — the Node read plane. Reads an index Python wrote; never writes.
+ *
+ * npm package `fux-engine`, command `fux`, vendored by `fux setup` into
+ * `.fux/fux.mjs` so a clone with no Python still answers (W-107 R1/R2).
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { findRoot } from "./src/config/root.mjs";
+import { runFind } from "./src/verbs/find.mjs";
+import { runAsk } from "./src/verbs/ask.mjs";
+import { runAnswer } from "./src/verbs/answer.mjs";
+import { runExplain, runGraph, runPath } from "./src/verbs/graph.mjs";
+import { runMcp } from "./src/verbs/mcp.mjs";
+
+const VERSION = "2.0.0-alpha.7";
+
+/** The PII gate's path, spelled here the way `cli.py` and `api.py` spell it.
+ *
+ * 🔴 **W-107 O1, ruled by Arpit 2026-09-12: Node enforces it identically.**
+ * Python refuses every non-exempt verb without `.fux/pii.toml`
+ * (ADR-PII decision 17). The gate exists because the committed index is
+ * redacted, so a Node reader that answered where Python refuses would be a
+ * divergence in the PRODUCT, not merely in the code — and this runtime cannot
+ * import the Python that carries the rule, so it carries the path itself.
+ * `tests/test_cli.py::test_the_node_reader_gates_on_the_same_file` holds this
+ * literal equal to the two Python copies. The WORDING below is a
+ * transcription of `pii.require`'s, which stays the one place it is authored.
+ */
+const PII_RULES = [".fux", "pii.toml"];
+
+/** Every verb here reads the index, so every verb is gated. There is no Node
+ *  twin of Python's `PII_EXEMPT` — `setup`, `tune`, `output` and `doctor` are
+ *  all in `WRITE_VERBS` and never reach this point. */
+function requirePiiRules(root) {
+  const path = join(root, ...PII_RULES);
+  if (existsSync(path) && statSync(path).isFile()) return true;
+  process.stderr.write(
+    `error: ${PII_RULES.join("/")} is missing, and fux will not run without it ` +
+    `(ADR-PII decision 17).\n` +
+    `       Run \`fux setup\` to write the starter, then review its rules; to redact\n` +
+    `       nothing, keep the file with no [[rule]] entries.\n`,
+  );
+  return false;
+}
+
+/** Verbs that exist in Python fux and deliberately not here. A person typing
+ *  one has a specific wrong model and deserves the specific correction. */
+const WRITE_VERBS = {
+  ingest: "writes the index", build: "writes the derived accelerator",
+  add: "writes a source line", remove: "writes a source line",
+  update: "re-fetches sources", enrich: "writes enrichment",
+  setup: "writes .fux/", doctor: "reports on a tree Node cannot fully see",
+  hooks: "installs git hooks", daemon: "runs a background re-index",
+  tune: "prints or writes tunables", output: "prints or writes output defaults",
+  verify: "not implemented until Phase 2 earns the digest path",
+};
+
+function parseArgs(argv) {
+  const out = { _: [], json: false, top: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--top") out.top = parseInt(argv[++i], 10);
+    else if (a === "--under") out.under = argv[++i];
+    else if (a === "--phrase") out.phrase = argv[++i];
+    else if (a === "--all") out.all = true;
+    else if (a === "--band") out.band = true;
+    else if (a === "--no-sections") out.sections = false;
+    else if (a === "-q") (out.q ||= []).push(argv[++i]);
+    else if (a === "--expand") out.expand = argv[++i];
+    else if (a === "--no-refer") out.noRefer = true;
+    else if (a === "--audit") out.audit = true;
+    else if (a === "--hops") out.hops = parseInt(argv[++i], 10);
+    else if (a.startsWith("--")) { out.unknown = a; }
+    else out._.push(a);
+  }
+  return out;
+}
+
+function main(argv) {
+  const [verb, ...rest] = argv;
+
+  if (verb === "--version" || verb === "-V") {
+    // 🔴 The runtime is NAMED. Python fux installs a binary called `fux` too,
+    // so on a machine with both, this one line is what makes any bug report
+    // unambiguous about which reader answered (W-107 R1a).
+    process.stdout.write(`fux ${VERSION} (node ${process.versions.node})\n`);
+    return 0;
+  }
+  if (!verb || verb === "--help" || verb === "-h") {
+    process.stdout.write(
+      `fux ${VERSION} (node ${process.versions.node}) — the read plane\n\n` +
+      `  fux find <query> [--json] [--top N] [--under DIR] [--phrase P] [--all]\n` +
+      `  fux ask|answer|explain|graph|path|mcp      (Phases 2-3)\n\n` +
+      `Reads an index Python wrote. It never writes and never fetches.\n`,
+    );
+    return verb ? 0 : 1;
+  }
+  if (verb in WRITE_VERBS) {
+    process.stderr.write(
+      `error: \`${verb}\` ${WRITE_VERBS[verb]} — this is fux-engine (node), which only reads.\n` +
+      `       Install Python fux and run \`fux ${verb}\`, or see .fux/README.md.\n`,
+    );
+    return 1;
+  }
+
+  const args = parseArgs(rest);
+  const root = findRoot(process.cwd());
+  if (root === null) {
+    process.stderr.write("error: no fux root here — no fux.toml and no .git above this directory.\n");
+    return 1;
+  }
+  // Before dispatch and before anything reads the repository, exactly where
+  // `cli.py::main` puts it, so no verb handler has to remember.
+  if (!requirePiiRules(root)) return 1;
+
+  switch (verb) {
+    case "find":
+      return runFind(root, args);
+    case "ask":
+      return runAsk(root, args);
+    case "answer":
+      return runAnswer(root, args);
+    case "explain":
+      return runExplain(root, args);
+    case "graph":
+      return runGraph(root, args);
+    case "path":
+      return runPath(root, args);
+    case "mcp":
+      return runMcp(root, args);
+    default:
+      process.stderr.write(`error: unknown verb \`${verb}\`. Try \`fux --help\`.\n`);
+      return 1;
+  }
+}
+
+process.exitCode = main(process.argv.slice(2));

package/mcp-tools.json

@@ -0,0 +1,66 @@
+{
+  "_comment": "The MCP tool descriptions, the authored text for node/src/verbs/mcp.mjs, held equal to src/fux/mcp.py's literal by tests/test_mcp.py. A description is what an agent reads to decide whether to call a tool, so two hand-maintained copies would drift into two products wearing one name. {{TOP}} is substituted with the connection's resolved [mcp] top.",
+  "tools": [
+    {
+      "name": "fux_search",
+      "description": "Search the committed index for documents relevant to a natural-language question. Returns ranked documents with content hashes and the headings that match your query -- section-level, not line-level; call fux_passage for the lines. This is the call to make first for any 'where is X' or 'why did we decide Y' question about this repository. READ THE `confidence` BLOCK BEFORE USING THE RESULTS. If `confidence.answerable` is false, do not answer from these results at all -- say what was searched and stop. If `confidence.band` is 'partial', answer but name every term in `confidence.missing`: those are words from the question that appear in no document here. If it is 'weak', the ranking could not separate the top hits, so report the candidates rather than a conclusion.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "A natural-language question."
+          },
+          "k": {
+            "type": "integer",
+            "description": "Maximum results (default {{TOP}}; this repository's .fux/output.toml may set a different default under [mcp]).",
+            "default": "{{TOP}}"
+          },
+          "expand": {
+            "type": "string",
+            "description": "OPTIONAL. Words you expect the document to use, when they differ from the question's. Scored at a lower weight than the question's own terms, and a document matching ONLY these is never returned. Use it after a search comes back `partial` with a non-empty `missing`: re-search with the vocabulary the corpus would use for the missing term."
+          }
+        },
+        "required": [
+          "query"
+        ]
+      }
+    },
+    {
+      "name": "fux_passage",
+      "description": "Read the verbatim text of a cited span, addressed as returned by fux_search. Use this instead of reading a whole file when you already have a citation: it returns only the cited lines and the hash they were read at.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "line_start": {
+            "type": "integer"
+          },
+          "line_end": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "path"
+        ]
+      }
+    },
+    {
+      "name": "fux_related",
+      "description": "The neighbourhood around a document: what it links to, what links to it, what it supersedes or is superseded by, and whether it is archived. Use when a result raises 'what else was decided with this?'",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path"
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "fux-engine",
+  "version": "2.0.0-alpha.7",
+  "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"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/arpitarya/fux.git" },
+  "homepage": "https://github.com/arpitarya/fux#readme",
+  "bugs": { "url": "https://github.com/arpitarya/fux/issues" },
+  "keywords": ["knowledge", "documentation", "search", "index", "bm25", "adr", "runbook"],
+  "publishConfig": { "access": "public", "tag": "alpha" }
+}

package/src/compat/pyfloat.mjs

@@ -0,0 +1,95 @@
+/** 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

@@ -0,0 +1,16 @@
+/** 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

@@ -0,0 +1,52 @@
+/** 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

@@ -0,0 +1,59 @@
+/** 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

@@ -0,0 +1,67 @@
+/** 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

@@ -0,0 +1,51 @@
+/** 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");
+}