fux-engine 2.0.0-alpha.7 → 2.0.0

package/src/hash/blake2b.mjs

@@ -1,208 +0,0 @@
-/** BLAKE2b (RFC 7693), stdlib-free, at arbitrary digest sizes.
- *
- * ⚠ **`node:crypto` cannot do this job.** It exposes `blake2b512` and nothing
- * else, and **truncating a 512-bit digest is a different function**: BLAKE2b's
- * parameter block folds the digest length into `h[0]`, so `blake2b(x, 8)` and
- * `blake2b(x, 64)[:8]` disagree on every input. Fux keys its postings on
- * `blake2b(term, digest_size=8)`, so a truncation here would produce an index
- * that reads as valid and matches nothing.
- *
- * **64-bit words as 32-bit halves, never BigInt** (W-107 §6.3). Each 64-bit
- * word is two `Uint32Array` slots — lo at `2i`, hi at `2i+1`. BigInt would be
- * correct and roughly an order of magnitude slower on the hot path, and the
- * hot path is every term of every query.
- *
- * Transcribed from RFC 7693 §3.1–§3.3. Pinned in `test/blake2b.test.mjs`
- * against RFC 7693 Appendix A and against Python `hashlib` at digest sizes
- * 1, 8 and 20 — the three fux uses (shard bucket, term key, content sha).
- */
-
-// IV — RFC 7693 §2.6, the SHA-512 IV. lo, hi per word.
-const IV32 = new Uint32Array([
-  0xf3bcc908, 0x6a09e667, 0x84caa73b, 0xbb67ae85,
-  0xfe94f82b, 0x3c6ef372, 0x5f1d36f1, 0xa54ff53a,
-  0xade682d1, 0x510e527f, 0x2b3e6c1f, 0x9b05688c,
-  0xfb41bd6b, 0x1f83d9ab, 0x137e2179, 0x5be0cd19,
-]);
-
-// SIGMA — RFC 7693 §2.7, ten permutations, rounds 11/12 reuse 0/1.
-// Pre-doubled: these index the 32-bit halves directly.
-const SIGMA82 = new Uint8Array([
-  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
-  14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3,
-  11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4,
-  7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8,
-  9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13,
-  2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9,
-  12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11,
-  13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10,
-  6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5,
-  10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0,
-  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
-  14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3,
-].map((x) => x * 2));
-
-const v = new Uint32Array(32);
-const m = new Uint32Array(32);
-
-/** v[a] += v[b], 64-bit, carrying lo into hi. */
-function add64AA(dst, a, b) {
-  const o0 = dst[a] + dst[b];
-  let o1 = dst[a + 1] + dst[b + 1];
-  if (o0 >= 0x100000000) o1++;
-  dst[a] = o0;
-  dst[a + 1] = o1;
-}
-
-/** v[a] += (b1 << 32) | b0. `b0 < 0` is a sign-extended 32-bit value. */
-function add64AC(dst, a, b0, b1) {
-  let o0 = dst[a] + b0;
-  if (b0 < 0) o0 += 0x100000000;
-  let o1 = dst[a + 1] + b1;
-  if (o0 >= 0x100000000) o1++;
-  dst[a] = o0;
-  dst[a + 1] = o1;
-}
-
-function get32(arr, i) {
-  return (arr[i] ^ (arr[i + 1] << 8) ^ (arr[i + 2] << 16) ^ (arr[i + 3] << 24));
-}
-
-/** The G mixing function — RFC 7693 §3.1. Rotations 32, 24, 16, 63. */
-function g(a, b, c, d, ix, iy) {
-  const x0 = m[ix], x1 = m[ix + 1];
-  const y0 = m[iy], y1 = m[iy + 1];
-
-  add64AA(v, a, b);
-  add64AC(v, a, x0, x1);
-
-  // rotr 32 — a whole-word swap, so it is free
-  let xor0 = v[d] ^ v[a];
-  let xor1 = v[d + 1] ^ v[a + 1];
-  v[d] = xor1;
-  v[d + 1] = xor0;
-
-  add64AA(v, c, d);
-
-  // rotr 24
-  xor0 = v[b] ^ v[c];
-  xor1 = v[b + 1] ^ v[c + 1];
-  v[b] = (xor0 >>> 24) ^ (xor1 << 8);
-  v[b + 1] = (xor1 >>> 24) ^ (xor0 << 8);
-
-  add64AA(v, a, b);
-  add64AC(v, a, y0, y1);
-
-  // rotr 16
-  xor0 = v[d] ^ v[a];
-  xor1 = v[d + 1] ^ v[a + 1];
-  v[d] = (xor0 >>> 16) ^ (xor1 << 16);
-  v[d + 1] = (xor1 >>> 16) ^ (xor0 << 16);
-
-  add64AA(v, c, d);
-
-  // rotr 63
-  xor0 = v[b] ^ v[c];
-  xor1 = v[b + 1] ^ v[c + 1];
-  v[b] = (xor1 >>> 31) ^ (xor0 << 1);
-  v[b + 1] = (xor0 >>> 31) ^ (xor1 << 1);
-}
-
-/** The compression function F — RFC 7693 §3.2. */
-function compress(ctx, last) {
-  let i = 0;
-  for (i = 0; i < 16; i++) {
-    v[i] = ctx.h[i];
-    v[i + 16] = IV32[i];
-  }
-
-  // v[12,13] ^= t (the byte counter); v[14,15] ^= 0xff.. on the final block
-  v[24] = v[24] ^ ctx.t;
-  v[25] = v[25] ^ (ctx.t / 0x100000000);
-  if (last) {
-    v[28] = ~v[28];
-    v[29] = ~v[29];
-  }
-
-  for (i = 0; i < 32; i++) m[i] = get32(ctx.b, 4 * i);
-
-  for (i = 0; i < 12; i++) {
-    const s = SIGMA82.subarray(i * 16, i * 16 + 16);
-    g(0, 8, 16, 24, s[0], s[1]);
-    g(2, 10, 18, 26, s[2], s[3]);
-    g(4, 12, 20, 28, s[4], s[5]);
-    g(6, 14, 22, 30, s[6], s[7]);
-    g(0, 10, 20, 30, s[8], s[9]);
-    g(2, 12, 22, 24, s[10], s[11]);
-    g(4, 14, 16, 26, s[12], s[13]);
-    g(6, 8, 18, 28, s[14], s[15]);
-  }
-
-  for (i = 0; i < 16; i++) ctx.h[i] = ctx.h[i] ^ v[i] ^ v[i + 16];
-}
-
-/** Init — RFC 7693 §3.3. The parameter block is why truncation is wrong. */
-function init(outlen, key) {
-  if (!Number.isInteger(outlen) || outlen < 1 || outlen > 64) {
-    throw new RangeError(`blake2b digest size must be 1..64, got ${outlen}`);
-  }
-  const keylen = key ? key.length : 0;
-  if (keylen > 64) throw new RangeError("blake2b key must be <= 64 bytes");
-
-  const ctx = {
-    b: new Uint8Array(128),
-    h: new Uint32Array(16),
-    t: 0,   // bytes compressed
-    c: 0,   // bytes in the buffer
-    outlen,
-  };
-  for (let i = 0; i < 16; i++) ctx.h[i] = IV32[i];
-  // h[0] ^= 0x01010000 ^ (keylen << 8) ^ outlen
-  ctx.h[0] ^= 0x01010000 ^ (keylen << 8) ^ outlen;
-
-  if (keylen > 0) {
-    update(ctx, key);
-    ctx.c = 128;
-  }
-  return ctx;
-}
-
-function update(ctx, input) {
-  for (let i = 0; i < input.length; i++) {
-    if (ctx.c === 128) {
-      ctx.t += ctx.c;
-      compress(ctx, false);
-      ctx.c = 0;
-    }
-    ctx.b[ctx.c++] = input[i];
-  }
-  return ctx;
-}
-
-function final(ctx) {
-  ctx.t += ctx.c;
-  while (ctx.c < 128) ctx.b[ctx.c++] = 0;
-  compress(ctx, true);
-
-  const out = new Uint8Array(ctx.outlen);
-  for (let i = 0; i < ctx.outlen; i++) {
-    out[i] = (ctx.h[i >> 2] >> (8 * (i & 3))) & 0xff;
-  }
-  return out;
-}
-
-const HEX = [];
-for (let i = 0; i < 256; i++) HEX.push(i.toString(16).padStart(2, "0"));
-
-/** `blake2b(bytes, digestSize)` -> Uint8Array. */
-export function blake2b(input, digestSize = 64, key = null) {
-  return final(update(init(digestSize, key), input));
-}
-
-/** `blake2b(bytes, digestSize)` -> lowercase hex, like Python's `.hexdigest()`. */
-export function blake2bHex(input, digestSize = 64, key = null) {
-  const out = blake2b(input, digestSize, key);
-  let s = "";
-  for (let i = 0; i < out.length; i++) s += HEX[out[i]];
-  return s;
-}

package/src/index.mjs

@@ -1,38 +0,0 @@
-/** The library surface — the half of `fux-engine` that is not a CLI.
- *
- * Mirrors `fux.api` in Python method for method, argument for argument, and
- * returns the same shapes the `--json` payload carries (W-107 R3). A frontend
- * project wants this; shelling out to a binary is the fallback, not the point.
- *
- *     import { open } from 'fux-engine'
- *     const ix = await open('.')
- *     await ix.find('rollback', { top: 5 })
- */
-import { findRoot } from "./config/root.mjs";
-import { ask as scanAsk } from "./query/scan.mjs";
-
-class Index {
-  constructor(root) { this.root = root; }
-
-  /** Ranked document locations. */
-  async find(query, { top = 5 } = {}) {
-    return scanAsk(this.root, query, top);
-  }
-
-  async ask() { throw new Error("ask lands in W-107 Phase 2"); }
-  async answer() { throw new Error("answer lands in W-107 Phase 2"); }
-  async explain() { throw new Error("explain lands in W-107 Phase 3"); }
-  async graph() { throw new Error("graph lands in W-107 Phase 3"); }
-  async path() { throw new Error("path lands in W-107 Phase 3"); }
-}
-
-/** Open the index at `root`, or at the first fux root above it. */
-export async function open(root = process.cwd()) {
-  const resolved = findRoot(root);
-  if (resolved === null) {
-    throw new Error(`no fux root at or above ${root} — no fux.toml and no .git`);
-  }
-  return new Index(resolved);
-}
-
-export { Index };

package/src/ingest/priors.mjs

@@ -1,35 +0,0 @@
-/** The ranking priors' query-time half. Twin of `src/fux/ingest/priors.py`.
- *
- * Only `recencyMultiplier` and `supersededIds` have a Node twin: the git half
- * (`git_commit_times`) is an INGEST concern, and Node does not ingest. `mtime`
- * and `superseded` arrive as committed facts on the record, which is the whole
- * reason they are committed — a derivation from local filesystem state would
- * differ per machine and break L3.
- */
-
-/** A gentle exponential decay, normalised so the newest document is `1.0`.
- *
- * **Bounded to `(0, 1]` by design**: recency can demote an old document and
- * can never promote a new one past a better match. That bound is load-bearing
- * for the accelerator's block bound, not just good manners. */
-export function recencyMultiplier(mtime, newest, halfLifeDays) {
-  if (halfLifeDays <= 0 || mtime === null || mtime === undefined || newest <= 0) return 1.0;
-  const ageDays = Math.max(0.0, (newest - mtime) / 86400.0);
-  return Math.pow(0.5, ageDays / halfLifeDays);
-}
-
-/** Doc ids that some other document DECLARES it supersedes.
- *  Declared, never inferred — nothing guesses from titles, numbering or dates. */
-export function supersededIds(records) {
-  const out = new Set();
-  const known = new Set(records.map((r) => r.id));
-  for (const record of records) {
-    for (const edge of record.edges || []) {
-      if (edge.kind === "supersedes") {
-        const dst = edge.dst;
-        if (known.has(dst) && dst !== record.id) out.add(dst);
-      }
-    }
-  }
-  return out;
-}

package/src/query/analyzer.mjs

@@ -1,81 +0,0 @@
-/** Analyzer v2 — the pipeline both ingest and query run, in this order:
- *
- *     split identifiers  ->  lower  ->  stopwords  ->  stem  ->  (caller hashes)
- *
- * Twin of `src/fux/query/analyzer.py`. The order is the whole design; two
- * steps are load-bearing in a way that is easy to get backwards:
- *
- * 1. **Splitting happens BEFORE lowercasing** — case is the only signal that a
- *    boundary was there, so lowercasing first destroys `camelCase`.
- * 2. **Stemming happens BEFORE hashing**, and the hash is of the final
- *    analyzed token. A one-step divergence between the two sides produces a
- *    silent no-match: the query hashes a string the index never wrote, and
- *    there is no error to see.
- */
-
-import { stem } from "./stem.mjs";
-
-/** Matched against the ORIGINAL text, not a lowercased copy. Hyphen is absent
- *  from the class, so `kebab-case` splits here for free. */
-const WORD_RE = /[A-Za-z0-9_]+/g;
-
-/** The three places a real identifier boundary can sit:
- *    `_`                      snake_case
- *    lower/digit -> upper     getUser, bm25F
- *    upper -> upper+lower     HTTPServer
- *  A token with none of these is left whole — `sha256`, `utf8`, `k1`. */
-const BOUNDARY_RE = /_+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/;
-
-const STOPWORDS = new Set(
-  `a an and are as at be but by for from has have how i if in into is it its
-   of on or that the their then there these this to was were what when where
-   which who why will with you your we our not can may`.split(/\s+/),
-);
-
-/** The parts of one raw token, or `[]` when there is no boundary in it. */
-export function splitIdentifier(raw) {
-  const parts = raw.split(BOUNDARY_RE).filter((p) => p);
-  if (parts.length < 2) return [];
-  return parts.filter((p) => p.length > 1);
-}
-
-/** Text to final analyzed terms, in document order, WITH duplicates.
- *  Duplicates are the point: the caller counts them into a term frequency. */
-export function analyze(text) {
-  const out = [];
-  const matches = text.match(WORD_RE);
-  if (!matches) return out;
-  for (const raw of matches) {
-    for (const token of [raw, ...splitIdentifier(raw)]) {
-      const lowered = token.toLowerCase();
-      if (STOPWORDS.has(lowered)) continue;
-      out.push(stem(lowered));
-    }
-  }
-  return out;
-}
-
-/** `[surface, analyzed]` for every term `analyze` produces, same order.
- *
- *  The surface is the pre-lowercase, pre-stem token — what the user actually
- *  typed. `confidence` reports that, not the stem the index is keyed by,
- *  because *"`mtl` is not in this corpus"* is worse than saying nothing.
- *
- *  ⚠ Duplicates `analyze`'s loop deliberately, exactly as Python does, and for
- *  the same reason: `analyze` runs over every token at ingest, and allocating
- *  a pair per token to serve a per-query diagnostic is the wrong trade. */
-export function analyzePairs(text) {
-  const out = [];
-  const matches = text.match(WORD_RE);
-  if (!matches) return out;
-  for (const raw of matches) {
-    for (const token of [raw, ...splitIdentifier(raw)]) {
-      const lowered = token.toLowerCase();
-      if (STOPWORDS.has(lowered)) continue;
-      out.push([token, stem(lowered)]);
-    }
-  }
-  return out;
-}
-
-export { STOPWORDS };

package/src/query/bm25f.mjs

@@ -1,89 +0,0 @@
-/** BM25F — weight THEN saturate, once. Twin of `src/fux/query/bm25f.py`.
- *
- * Every number here appears on both sides of the same fraction, which is why
- * `Scoring` is ONE object and not three parameters: a caller that passes the
- * weights and forgets `k1` reweights half a formula.
- */
-import { TF_FIELDS } from "../store/format.mjs";
-
-export const FIELD_WEIGHTS = [1.0, 3.0, 2.0, 1.5, 1.0];
-if (FIELD_WEIGHTS.length !== TF_FIELDS.length) {
-  throw new Error("field weights must align with TF_FIELDS");
-}
-export const K1 = 1.2;
-export const B = 0.75;
-
-export class Scoring {
-  constructor(k1 = K1, b = B, weights = FIELD_WEIGHTS) {
-    this.k1 = k1; this.b = b; this.weights = weights;
-    Object.freeze(this);
-  }
-  /** True when this is the engine default, so callers can skip work. */
-  get trivial() {
-    return this.k1 === K1 && this.b === B
-      && this.weights.length === FIELD_WEIGHTS.length
-      && this.weights.every((w, i) => w === FIELD_WEIGHTS[i]);
-  }
-}
-
-export const DEFAULT_SCORING = new Scoring();
-
-/** ⚠ `Math.log` and Python's `math.log` disagree in the last ulp on ~0.7 % of
- *  inputs (Phase 0, measured on darwin and glibc). **Every difference is one
- *  ulp and none survives `round(9)`**, which is the sort key's own resolution
- *  — ADR-RANKING decision 8a. This is the tolerance Arpit ruled, option (b). */
-export function idf(df, n) { return Math.log((n - df + 0.5) / (df + 0.5) + 1); }
-
-/** The BM25F numerator for one term in one document.
- *  `tf` may be shorter than `weights` — trailing zeros are omitted on the wire,
- *  so iterating `tf` rather than `weights` makes the short form free. */
-export function weightedTf(tf, scoring = DEFAULT_SCORING) {
-  let total = 0.0;
-  const weights = scoring.weights;
-  for (let i = 0; i < tf.length; i++) {
-    const count = tf[i];
-    if (count) total += weights[i] * count;
-  }
-  return total;
-}
-
-/** The length normaliser, from committed per-field counts and live weights.
- *  **The one place this arithmetic exists** — four callers need it, and four
- *  copies is how they drift. */
-export function deriveWlen(flen, scoring = DEFAULT_SCORING) {
-  let total = 0.0;
-  const weights = scoring.weights;
-  for (let i = 0; i < flen.length; i++) {
-    const count = flen[i];
-    if (count) total += weights[i] * count;
-  }
-  return total;
-}
-
-/** Sum of each matched query term's weight-then-saturate contribution.
- *
- * ⚠ `termWeights === null` performs **no multiply at all** — not a multiply by
- * 1.0. An unexpanded query must do exactly the float arithmetic it did before
- * `--expand` existed, or the differential law picks up a last-bit difference
- * from the feature merely being present.
- */
-export function scoreRecord(
-  terms, flen, queryHashes, df, n, avgWlen,
-  scoring = DEFAULT_SCORING, termWeights = null,
-) {
-  if (n <= 0 || avgWlen <= 0) return 0.0;
-  const wlen = typeof flen === "number" ? flen : deriveWlen(flen, scoring);
-  const k1 = scoring.k1, b = scoring.b;
-  let total = 0.0;
-  for (const h of queryHashes) {
-    const tf = terms[h];
-    if (tf === undefined) continue;
-    const wtf = weightedTf(tf, scoring);
-    if (wtf === 0) continue;
-    const denom = wtf + k1 * (1 - b + b * wlen / avgWlen);
-    let contribution = idf(df[h] ?? 0, n) * wtf * (k1 + 1) / denom;
-    if (termWeights !== null) contribution *= (termWeights[h] ?? 1.0);
-    total += contribution;
-  }
-  return total;
-}

package/src/query/confidence.mjs

@@ -1,163 +0,0 @@
-/** The confidence band — what fux says out loud about its own answer.
- *  Twin of `confidence.py`.
- *
- * Four signals and two floors. **The floors arrive from the CALLER**, never
- * from this module, so a single query cannot be judged by one floor and
- * reported with another — and both are published on the block, because a
- * `grounded` judged at 0.02 is a different claim from one judged at 0.10 and
- * absent publication the difference would be invisible.
- */
-import { idf } from "./bm25f.mjs";
-import { termHash } from "../store/format.mjs";
-import { tokenizePairs } from "./tokenize.mjs";
-
-export const GROUNDED = "grounded";
-export const WEAK = "weak";
-export const PARTIAL = "partial";
-export const NONE = "none";
-
-export const SEPARATION_FLOOR = 0.10;
-/** `0.0` means the clause is OFF — a measured ruling, not an oversight. */
-export const DOC_COVERAGE_FLOOR = 0.0;
-
-function round4(x) { return Math.round(x * 1e4) / 1e4; }
-function clamp01(x) { return Math.max(0.0, Math.min(1.0, x)); }
-
-export class Confidence {
-  constructor({
-    coverage = 0.0, separation = 0.0, support = 0, verified = "unverified",
-    missing = [], docCoverage = 1.0,
-    separationFloor = SEPARATION_FLOOR, docCoverageFloor = DOC_COVERAGE_FLOOR,
-  } = {}) {
-    this.coverage = coverage;
-    this.separation = separation;
-    this.support = support;
-    this.verified = verified;
-    this.missing = missing;
-    this.docCoverage = docCoverage;
-    this.separationFloor = separationFloor;
-    this.docCoverageFloor = docCoverageFloor;
-  }
-
-  /** `grounded` · `partial` · `weak` · `none` — **first true clause wins.**
-   *
-   * `stale` demotes to `partial` rather than `weak` because stale bytes are a
-   * KNOWABLE defect a consumer can name, which is what `partial` means; `weak`
-   * is where nothing is identifiably wrong and the ranking cannot choose. */
-  get band() {
-    if (this.support === 0) return NONE;
-    if (this.missing.length || this.verified === "stale") return PARTIAL;
-    // The clause the decoy control bought: corpus-wide coverage cannot see
-    // that a question's terms are scattered across four documents while no
-    // single one discusses it, and separation cannot either — a corpus of
-    // near-misses is decisive about its best near-miss.
-    if (this.docCoverage < this.docCoverageFloor) return PARTIAL;
-    if (this.separation < this.separationFloor) return WEAK;
-    return GROUNDED;
-  }
-
-  /** **A refusal, not a low number.** An agent handed `0.3` will use it anyway
-   *  and hedge in prose; one handed `answerable: false` has nothing to hedge. */
-  get answerable() { return this.band !== NONE; }
-
-  /** The same signals with the refer plane's verdict filled in. `answer` ranks
-   *  before it fetches, so the verdict does not exist when the rest are
-   *  computed. A new object — `band` re-derives and cannot go stale. */
-  withVerified(verdict) {
-    return new Confidence({
-      coverage: this.coverage, separation: this.separation, support: this.support,
-      verified: verdict, missing: this.missing, docCoverage: this.docCoverage,
-      separationFloor: this.separationFloor, docCoverageFloor: this.docCoverageFloor,
-    });
-  }
-
-  /** The `--json` shape, declared in `output.schema.json#confidence`.
-   *  `band` and `answerable` are written out rather than left derivable — a
-   *  consumer re-implementing the band rules would be a second copy of this
-   *  policy, in another language, drifting from the day it was written. */
-  asDict() {
-    return {
-      band: this.band,
-      answerable: this.answerable,
-      coverage: this.coverage,
-      separation: this.separation,
-      separation_floor: this.separationFloor,
-      doc_coverage: this.docCoverage,
-      doc_coverage_floor: this.docCoverageFloor,
-      support: this.support,
-      verified: this.verified,
-      missing: [...this.missing],
-    };
-  }
-}
-
-/** Compute the block from what `rank()` already had in hand.
- *
- * `scores` is every score above zero, already sorted descending.
- * **`missing` reports the SURFACE form, never the analyzed one** — *"`mtl` is
- * not in this corpus"* is worse than silence; *"`mTLS` is"* is actionable.
- *
- * `support` is bounded by `--top` deliberately: a corpus-wide count would
- * differ between `--fast` and `--scan`, which is the differential-law break
- * the accelerator record exists to forbid. The law is worth more than the
- * better number. */
-export function signals(
-  pairs, queryHashes, df, n, scores,
-  {
-    verified = "unverified", topDocHashes = null,
-    separationFloor = SEPARATION_FLOOR, docCoverageFloor = DOC_COVERAGE_FLOOR,
-  } = {},
-) {
-  if (!queryHashes.length || n <= 0) {
-    return new Confidence({ verified, separationFloor, docCoverageFloor });
-  }
-
-  // First token per hash, mirroring `queryTermHashes`' de-duplication so the
-  // two lists cannot fall out of step on a repeated word.
-  const first = new Map();
-  for (const [surface, analyzed] of pairs) {
-    const h = termHash(analyzed);
-    if (!first.has(h)) first.set(h, surface);
-  }
-
-  let total = 0.0, matched = 0.0;
-  const missing = [];
-  for (const h of queryHashes) {
-    const weight = idf(df[h] ?? 0, n);
-    total += weight;
-    if ((df[h] ?? 0) > 0) matched += weight;
-    else missing.push(first.get(h) ?? h);
-  }
-  const coverage = total > 0 ? matched / total : 0.0;
-
-  // The same idf weighting, over the TOP document's own terms rather than the
-  // corpus's. Weighted, not counted: missing `the` is nothing, missing `mTLS`
-  // is the question.
-  let docCoverage;
-  if (topDocHashes === null) docCoverage = 1.0;   // not supplied — never demote on absence
-  else if (total > 0) {
-    const present = new Set(topDocHashes);
-    let s = 0.0;
-    for (const h of queryHashes) if (present.has(h)) s += idf(df[h] ?? 0, n);
-    docCoverage = s / total;
-  } else docCoverage = 1.0;
-
-  // One result separates perfectly: there is no runner-up to confuse it with.
-  let separation;
-  if (scores.length >= 2 && scores[0] > 0) separation = (scores[0] - scores[1]) / scores[0];
-  else if (scores.length === 1) separation = 1.0;
-  else separation = 0.0;
-
-  return new Confidence({
-    coverage: round4(clamp01(coverage)),
-    docCoverage: round4(clamp01(docCoverage)),
-    separation: round4(clamp01(separation)),
-    support: scores.length,
-    verified,
-    missing,
-    separationFloor,
-    docCoverageFloor,
-  });
-}
-
-export { tokenizePairs };

package/src/query/expand.mjs

@@ -1,55 +0,0 @@
-/** `--expand` — extra vocabulary the CALLER supplies. Twin of `expand.py`.
- *
- * Fux never invents terms: no model sits anywhere on the query path, so an
- * expansion arrives from whoever asked. What this module owns is the rule that
- * an expansion is a *supplement* — it may lift a document, never define one.
- */
-
-/** Every hash to score (originals first), what the user actually asked for,
- *  and at what weight. */
-export class Expansion {
-  constructor(hashes, required, weights = {}) {
-    this.hashes = hashes;
-    this.required = required;     // Set — the ORIGINAL query's hashes
-    this.weights = weights;       // hash -> multiplier, expansion-only
-    Object.freeze(this);
-  }
-  /** True when this changes nothing — the `Scoring.trivial` precedent. */
-  get trivial() { return Object.keys(this.weights).length === 0; }
-
-  /** The identity: every hash required, nothing weighted. */
-  static none(queryHashes) {
-    const hashes = [...queryHashes];
-    return new Expansion(hashes, new Set(hashes), {});
-  }
-
-  /** 🔴 The hallucinated-citation guard. A record matching ONLY expansion
-   *  terms is not a weak answer to rank low — it is an answer to a question
-   *  nobody asked, and `rank()` drops it outright. */
-  matches(terms) {
-    for (const h of this.required) if (h in terms) return true;
-    return false;
-  }
-
-  weightOf(h) { return this.weights[h] ?? 1.0; }
-}
-
-/** Combine the query's hashes with an expansion's, at `weight`.
- *
- * **A hash the original query already carries stays at 1.0**, even when the
- * expansion repeats it — otherwise a caller could quietly demote their own
- * query by mentioning one of its own words. `weight <= 0` is off, and off must
- * be reachable by configuration as well as by omission. */
-export function build(queryHashes, expansionHashes, weight) {
-  if (weight <= 0 || !expansionHashes || !expansionHashes.length) {
-    return Expansion.none(queryHashes);
-  }
-  const original = [...new Set(queryHashes)];
-  const required = new Set(original);
-  const extra = [...new Set(expansionHashes)].filter((h) => !required.has(h));
-  if (!extra.length) return Expansion.none(original);
-
-  const weights = {};
-  for (const h of extra) weights[h] = weight;
-  return new Expansion([...original, ...extra], required, weights);
-}