@hviana/sema 0.5.2 → 0.5.4

package/dist/src/mind/pipeline.js

@@ -1,331 +0,0 @@
-// pipeline.ts — the think pipeline (Section 5 of the mind).
-//
-// think() is the whole file's job: one lightest-derivation choice among
-// UNIFORM mechanisms.  The pipeline sees mechanisms through the
-// PipelineMechanism interface only — it never imports a mechanism-specific
-// type and never has a special-case branch for any mechanism.  Adding a
-// mechanism means registering one object; removing one means dropping it
-// from the list.  The mechanisms themselves live in mechanisms/ (one file
-// each); the shared pre-computation they exchange lives in Precomputed
-// (pipeline-mechanism.ts).
-import { PASS, STEP } from "./graph-search.js";
-import { gistOf, read, resolve } from "./primitives.js";
-import { recognise } from "./recognition.js";
-import { fuseAttention, reason } from "./reasoning.js";
-import { unexplainedSpans } from "./rationale.js";
-import { rItem } from "./trace.js";
-import { hubBound } from "./traverse.js";
-import { Precomputed } from "./pipeline-mechanism.js";
-import { coverMechanism } from "./mechanisms/cover.js";
-import { castMechanism } from "./mechanisms/cast.js";
-import { confluenceMechanism } from "./mechanisms/confluence.js";
-import { extractionMechanism } from "./mechanisms/extraction.js";
-import { recallMechanism } from "./mechanisms/recall.js";
-// Re-exports: cover's pre-resolution helpers and the ALU adapter kept
-// importable from the pipeline module (their historical home).
-export { resolveConcepts, resolveConnectors } from "./mechanisms/cover.js";
-export { aluToMechanism } from "./mechanisms/alu.js";
-// ── Extension dispatch (pre-loop parse) ─────────────────────────────────────
-async function collectComputed(ctx, mechanisms, query) {
-    const out = [];
-    const meter = ctx.meter;
-    for (const m of mechanisms) {
-        if (!m.parse)
-            continue;
-        const spans = meter
-            ? await meter.time(`${m.name}.parse`, () => m.parse(query))
-            : await m.parse(query);
-        out.push(...spans);
-    }
-    return out;
-}
-// ── Built-in mechanisms ─────────────────────────────────────────────────────
-// ORDER MATTERS, but only through the uniform floor/worthRunning pruning —
-// no mechanism is special-cased.  Cover runs FIRST: when a computed
-// extension result (e.g. ALU) exists, cover masks it in at near-zero cost
-// (see mechanisms/cover.ts), which becomes `best` before any other mechanism
-// invests in its own precomputation.  CAST's and confluence's floors (2*STEP,
-// 3*STEP) then fail `worthRunning` and are skipped by the SAME admissible-
-// floor pruning every mechanism is already subject to — not by asking
-// "is this an extension?". Grade TIES keep the earlier candidate, so this
-// order is also the tie-break priority: cover, cast, confluence, extraction,
-// recall.
-export const defaultMechanisms = [
-    coverMechanism,
-    castMechanism,
-    confluenceMechanism,
-    extractionMechanism,
-    recallMechanism,
-];
-/** Think: a single lightest-derivation exploration of the Sema graph.
- *
- *  Every answer travels the same path:
- *    1. Pre-computation — recognise, extension parse, guide; everything
- *       expensive stays lazy on Precomputed until a mechanism asks.
- *    2. Grounding — every mechanism yields candidates weighed in the one
- *       cost ladder; the lightest grounding derivation wins.
- *    3. Post-grounding — diagnostics (narrowDecision, thinGrounding),
- *       reasoning (multi-hop), fusion (multi-topic). */
-export async function think(ctx, query, mechs) {
-    if (query.length === 0)
-        return null;
-    ctx._edgeGuide = gistOf(ctx, query);
-    ctx._edgeChoice.clear();
-    const t = ctx.trace?.enter("think", [rItem(query, "query")]);
-    const done = (answer, note) => {
-        t?.done(answer
-            ? [rItem(answer, "answer", resolve(ctx, answer) ?? undefined)]
-            : [], note);
-        return answer;
-    };
-    // ── Pre-computation ──────────────────────────────────────────────────
-    const mechanisms = mechs ?? defaultMechanisms;
-    const rec = recognise(ctx, query);
-    // Phase 1: collect computed spans from mechanisms that implement parse()
-    const computed = await collectComputed(ctx, mechanisms, query);
-    if (computed.length > 0) {
-        ctx.trace?.step("computeExtensions", [rItem(query, "query")], computed.map((u) => rItem(query.subarray(u.i, u.j), "operand", undefined, [u.i, u.j])), `extensions recognised and evaluated ${computed.length} computation(s)`);
-        for (const u of computed) {
-            ctx.trace?.step("evalComputation", [rItem(query.subarray(u.i, u.j), "expression", undefined, [u.i, u.j])], [rItem(u.bytes, "result", resolve(ctx, u.bytes) ?? undefined)], "evaluate the recognised operation to its authoritative result");
-        }
-    }
-    // Phase 2: the shared pre-computation container.  Eager fields only
-    // (recognition, computed spans, guide) — every expensive analysis
-    // (consensus climb, weave, span-shape classification) is a lazily-cached
-    // method on Precomputed, first-touched by whichever mechanism's floor
-    // survives its cheap gates and the worthRunning check.  A query no
-    // mechanism climbs for (e.g. one an extension decided) never climbs.
-    const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
-    const grade = (w) => Math.floor(w / STEP);
-    const unaccounted = (spans) => unexplainedSpans(query.length, spans)
-        .reduce((sum, [s, e]) => sum + (e - s), 0);
-    const weigh = (accounted, moves) => moves + PASS * unaccounted(accounted);
-    const candidates = [];
-    let best = null;
-    const consider = (c) => {
-        if (c.bytes.length === 0)
-            return;
-        if (ctx.meter)
-            ctx.meter.candidates++;
-        candidates.push(c);
-        if (best === null) {
-            best = c;
-            return;
-        }
-        const g = grade(c.weight), gb = grade(best.weight);
-        if (g < gb) {
-            best = c;
-            return;
-        }
-        // TIE-BREAK: AT EQUAL GRADE, PREFER THE ANSWER THAT INVENTS LESS.
-        //
-        // The ladder prices what a candidate leaves UNACCOUNTED, which is the
-        // right primary question but cannot separate two candidates that leave
-        // the same bytes unaccounted — and then the winner is whichever mechanism
-        // happened to be considered first, which is not a reason.
-        //
-        // What still separates them is what they DID with those bytes.  A
-        // candidate that carries an unexplained span into its answer is passing
-        // the asker's own words back as if they were derived; one that leaves
-        // them out has made a smaller, honest claim.  Measured on test/22's
-        // two-fact chain: cover and recall both graded 11001 over 11 unexplained
-        // bytes, cover answering "The capital of France is Paris famous for" (11
-        // bytes of scaffolding) against recall's crossing of the hop (0).  Order
-        // alone decided it, and the shallower reading won.
-        //
-        // This never overrides the ladder — it only orders within one grade, so
-        // coverage and moves still dominate exactly as before.
-        if (g === gb && (c.scaffolding ?? 0) < (best.scaffolding ?? 0))
-            best = c;
-    };
-    const worthRunning = (floor) => best === null || grade(floor) < grade(best.weight);
-    // Phase 3: grounding loop
-    // Per-mechanism accounting (src/meter.ts).  The market's whole premise is
-    // that mechanisms compete on one cost scale — so the profiling read-out is
-    // also per-mechanism, uniformly: the loop never asks which one it holds.
-    const meter = ctx.meter;
-    for (const mech of mechanisms) {
-        const floor = meter
-            ? await meter.time(`${mech.name}.floor`, () => mech.floor(ctx, query, pre, worthRunning))
-            : await mech.floor(ctx, query, pre, worthRunning);
-        if (meter) {
-            if (floor === null)
-                meter.mechanismSkips++;
-            else
-                meter.mechanismFloors++;
-        }
-        if (floor === null) {
-            ctx.trace?.step("skipMechanism", [], [], `${mech.name} skipped — structural precondition failed`);
-            continue;
-        }
-        if (!worthRunning(floor)) {
-            ctx.trace?.step("skipMechanism", [], [], `${mech.name} skipped — floor ${floor} cannot beat incumbent (grade ${grade(best.weight)})`);
-            continue;
-        }
-        if (meter)
-            meter.mechanismRuns++;
-        const results = meter
-            ? await meter.time(`${mech.name}.run`, () => mech.run(ctx, query, pre))
-            : await mech.run(ctx, query, pre);
-        for (const r of results) {
-            const weight = r.weight ?? weigh(r.accounted, r.moves);
-            consider({
-                bytes: r.bytes,
-                provenance: r.provenance ?? mech.provenance,
-                weight,
-                used: r.used,
-                accounted: r.accounted,
-                unexplained: r.unexplained,
-                complete: r.complete,
-                scaffolding: r.scaffolding,
-            });
-        }
-    }
-    // (TS cannot see the closure assignments into `best` and narrows it to its
-    // initial null, so the read-back needs the assertion.)
-    const decided = best;
-    if (candidates.length > 1) {
-        // The runner-up is computed BEFORE the decideGrounding step so its grade
-        // margin can ride along in the step's structured data payload; the
-        // computation itself is pure and was always unconditional — only its
-        // position moved.
-        let runnerUp = null;
-        if (decided !== null) {
-            for (const c of candidates) {
-                if (c === decided)
-                    continue;
-                if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
-                    runnerUp = c;
-                }
-            }
-        }
-        const margin = decided !== null && runnerUp !== null
-            ? grade(runnerUp.weight) - grade(decided.weight)
-            : null;
-        ctx.trace?.step("decideGrounding", candidates.map((c) => rItem(c.bytes, `${c.provenance} (weight ${c.weight.toFixed(3)}${c.unexplained ? `, unexplained: "${c.unexplained}"` : ""})`)), decided ? [rItem(decided.bytes, decided.provenance)] : [], "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder", undefined, {
-            version: 1,
-            candidates: candidates.map((c) => ({
-                provenance: c.provenance,
-                weight: c.weight,
-                grade: grade(c.weight),
-                unexplainedBytes: unaccounted(c.accounted),
-                decided: c === decided,
-            })),
-            ...(margin !== null ? { runnerUpMargin: margin } : {}),
-        });
-        if (decided !== null && runnerUp !== null && margin !== null) {
-            if (margin <= 1) {
-                ctx.trace?.step("narrowDecision", [
-                    rItem(decided.bytes, `${decided.provenance} (weight ${decided.weight.toFixed(3)})`),
-                ], [
-                    rItem(runnerUp.bytes, `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`),
-                ], `margin ${margin} grade-unit(s) — the decision could change with one more training fact`, undefined, { version: 1, margin });
-            }
-        }
-    }
-    if (decided === null) {
-        done(null, "no mechanism grounded an answer");
-        return null;
-    }
-    // Honesty density
-    {
-        const covered = query.length - unaccounted(decided.accounted);
-        const density = query.length > 0 ? covered / query.length : 1;
-        const thinBar = 1 / ctx.space.maxGroup;
-        if (density < thinBar) {
-            ctx.trace?.step("thinGrounding", [rItem(decided.bytes, decided.provenance)], [], `grounded but thin — density ${density.toFixed(3)} is below 1/W (${thinBar.toFixed(3)})`);
-        }
-    }
-    const answer = decided.bytes;
-    const provenance = decided.provenance;
-    const castUsed = decided.used ?? new Set();
-    // ── Post-grounding, gated by provenance ──────────────────────────────
-    const preConsumed = provenance === "cast" || provenance === "join"
-        ? castUsed
-        : provenance === "recall" || provenance === "recall-echo"
-            ? new Set()
-            : new Set(recognise(ctx, answer).sites.map((s) => s.payload));
-    // A grounding that DECLARED itself complete is not extended: the answer is
-    // already a trained form's own continuation, reached through an identity
-    // claim about the query, so a multi-hop pivot could only chain past the
-    // fact that produced it (see MechanismResult.complete).
-    // WHAT THE MECHANISM WITHHELD, NOT WHAT IT VOICED.  A pivot must not
-    // re-open content a grounding deliberately kept out: comparison cites two
-    // analogs and refuses their own downstream facts, so pivoting into one is
-    // the mechanism's own refusal undone one step later (test/29 C2 pivoted
-    // through `speare` — a stored fragment of the analog `William Shakespeare`
-    // — into the biography CAST had declined).
-    //
-    // Reading the used anchors' OWN bytes here says something stronger and
-    // wrong: that nothing INSIDE what was voiced may be pivoted through.  A
-    // comparison's seat sentence legitimately contains further terms with
-    // their own unrelated facts, and C3 pins exactly that — `Mona Lisa`, inside
-    // the voiced seat `The Mona Lisa was painted by Leonardo da Vinci.`, leads
-    // on to `Mona Lisa hangs in the Louvre`, which is about neither analog.
-    // The withheld content is the used anchors' CONTINUATIONS, so that is what
-    // the containment rule reads: `speare` is contained in `Shakespeare wrote
-    // 39 plays` and stays refused, while `Mona Lisa` appears in no withheld
-    // continuation and the genuine further hop fires.
-    //
-    // Only a mechanism carrying its own `used` set (cast/join) gets this: there
-    // `preConsumed` is a deliberate, short list of the anchors the answer
-    // speaks for, so the fan-out is bounded.  For every other provenance
-    // `preConsumed` is derived by re-recognising the answer — "everything in
-    // it", not "what it voiced" — and a containment rule over that would
-    // suppress every pivot the answer legitimately contains.
-    const voiced = (provenance === "cast" || provenance === "join")
-        ? [...castUsed].flatMap((id) => ctx.store.nextFirst(id, hubBound(ctx)).map((n) => read(ctx, n)))
-        : [];
-    const reasoned = decided.complete ? answer : meter
-        ? await meter.time("reason", () => reason(ctx, query, answer, preConsumed, pre, voiced))
-        : await reason(ctx, query, answer, preConsumed, pre, voiced);
-    // Fuse only when the query has a genuine REMAINDER no mechanism's
-    // structural evidence touched at all.  `decided.accounted` alone
-    // undercounts this: it is a COST-LADDER quantity (cover.ts prices its
-    // masked/computed spans at near-zero and deliberately leaves them out of
-    // `accounted` so PASS-bridged bytes are still charged), not a coverage
-    // one — a query fully explained by one computed span plus bridged
-    // connectors can report `accounted: []` while nothing is actually left
-    // unexplained.  The genuine remainder is what NEITHER the winning
-    // candidate's accounted spans NOR any recognised extension's computed
-    // span (`pre.computed` — every mechanism's parse() output, ALU included)
-    // ever touched.  A remainder under one river-fold quantum (W, the same
-    // floor cover.ts's restatedSpan and the honesty-density bar above both
-    // use) is bridging punctuation/whitespace, never a second topic —
-    // observed: a single space between two fully-computed arithmetic spans
-    // ("2+2 3+3") registered as "unaccounted" and pulled in an unrelated
-    // corpus fact, corrupting "4 6" into "4 63".
-    const explained = [
-        ...decided.accounted,
-        ...pre.computed.map((u) => [u.i, u.j]),
-    ];
-    const remainder = unaccounted(explained);
-    // Whether the winning candidate's entire recognised substance is
-    // COMPUTED — every accounted span exactly a pre.computed span, nothing
-    // from a genuinely recognised/climbed site.  fuseAttention's lone-root
-    // shortcut assumes a single point of attention already IS primary's own
-    // source; that assumption is exactly backwards for a pure computation
-    // (an ALU result has no anchor of its own) — see fuseAttention's
-    // `unclimbed` parameter, gated there by Attention.breadth so a
-    // coincidental echo (which this flag alone cannot distinguish) is still
-    // rejected.
-    const unclimbed = decided.accounted.length > 0 &&
-        decided.accounted.every(([i, j]) => pre.computed.some((u) => u.i === i && u.j === j));
-    // Where the winning grounding stands in the query — fusion places primary
-    // by it (see fuseAttention's `primarySpans`).  `accounted` is the
-    // cost-ladder read and is authoritative when non-empty; when it is empty
-    // the grounding is a pure COMPUTATION, whose evidence is its computed span.
-    // Exactly the cost-ladder-vs-coverage distinction `explained` above draws,
-    // read here for POSITION instead of for coverage — and resolved here, where
-    // both readings are in hand, rather than inside fuseAttention.
-    const primarySpans = decided.accounted.length > 0
-        ? decided.accounted
-        : pre.computed.map((u) => [u.i, u.j]);
-    const fused = remainder < ctx.space.maxGroup
-        ? reasoned
-        : meter
-            ? await meter.time("fuse", () => fuseAttention(ctx, query, reasoned, pre, unclimbed, primarySpans))
-            : await fuseAttention(ctx, query, reasoned, pre, unclimbed, decided.accounted);
-    done(fused, "grounded, reasoned forward, fused across points of attention");
-    return { bytes: fused, provenance };
-}

package/dist/src/mind/prefix-completion.d.ts

@@ -1,59 +0,0 @@
-import type { MindContext } from "./types.js";
-/** Trained forms the query may OPEN, proposed from the write side's own
- *  leaf-id window index — the supply of last resort for {@link
- *  prefixCompletion}.
- *
- *  WHY A SECOND SUPPLY EXISTS.  The ranked list this mechanism normally reads
- *  is a resonance list, and resonance cannot rank a proper prefix: measured on
- *  the trained store, cos(prefix, form) falls from 0.9629 at a one-byte
- *  truncation to 0.6206 at three bytes, against a reachThreshold of 0.8750.
- *  Three bytes of truncation put the answer out of reach on GEOMETRY, not on a
- *  bug, so no k and no re-ranking recovers it.
- *
- *  WHY THIS ROUTE WORKS WHERE THE FOLD DOES NOT.  A query's own fold is
- *  useless here: content addressing is not phrase-position-invariant, so a
- *  standalone prefix folds to a DIFFERENT node than the same bytes sitting
- *  inside a longer deposit, and neither the prefix's own node nor its
- *  ancestors lead to the deposit (measured: the 22-byte prefix of the
- *  photosynthesis form resolves, is shared by 6 contexts, and does not have
- *  the form among its ancestors).  Leaf ids ARE position-invariant — they are
- *  content-addressed on single bytes — and `indexSubSpans` already interns a
- *  flat branch over every canonical WINDOW of a deposit's leaf-id stream, with
- *  containment edges to the chunks that window spans.  A query that is a
- *  prefix therefore shares those window nodes exactly, and reaches the deposit
- *  by climbing containment then parents.  Nothing is added to the write side;
- *  this reads an index training already built.
- *
- *  BOUNDED (§2.8), AND WITH NO NEW THRESHOLD.  The window whose containment is
- *  SMALLEST carries the most evidence, and one saturated at `hubBound` carries
- *  none — that is the same √N reading of "hub" the rest of the mind uses, not
- *  a tuned knob.  The upward walk spends a budget of `hubBound` nodes and
- *  fans out by W, so a hub query enumerates nothing and the caller stays
- *  silent rather than guessing (§2.13).  Measured on the trained store: the
- *  photosynthesis form at a one-byte truncation picks a window with 52
- *  containers, visits 446 nodes, and yields exactly ONE candidate that
- *  survives the caller's byte compare — the form itself.
- *
- *  These are PROPOSALS only.  Every candidate still faces the byte-exact
- *  prefix compare and all three guards below, so a wrong proposal costs one
- *  bounded read and can never be voiced (§2.3). */
-export declare function prefixCandidates(ctx: MindContext, query: Uint8Array): number[];
-/** A trained form the query opens, and the bytes by which it continues. */
-export interface PrefixCompletion {
-    /** The trained form whose opening the query is — the answer, voiced whole. */
-    id: number;
-    /** The form's own bytes.  The mechanism grounds a FORM, never a slice of
-     *  one: slicing at the query's end would cut at an offset the geometry has
-     *  no reason to treat as a boundary. */
-    form: Uint8Array;
-    /** The bytes past the query — carried for the rationale and for the
-     *  uniqueness comparison, not voiced on its own. */
-    continuation: Uint8Array;
-}
-/** The sole trained form the query opens — or null when no candidate opens with
- *  it, when the continuation is sub-quantum, when a candidate's continuation
- *  cannot be read through, or when the candidates disagree.
- *
- *  `ranked` must be a list the caller has ALREADY fetched; this mechanism never
- *  resonates on its own (see the header's cost note). */
-export declare function prefixCompletion(ctx: MindContext, query: Uint8Array, ranked: ReadonlyArray<number>): PrefixCompletion | null;

package/dist/src/mind/prefix-completion.js

@@ -1,270 +0,0 @@
-// prefix-completion.ts — Grounding a query that IS the opening of a trained
-// form.
-//
-// THE SHAPE.  `The capital of France is` grounds nothing, while
-// `The capital of France is Paris.` is trained and reads back byte-exact.  The
-// query is not SIMILAR to that form, it is a PROPER PREFIX of it: every query
-// byte is a literal match, in order, from offset zero.  That is the strongest
-// grounding relation in the store — stronger than the bridge's corroborated
-// substitution, which pays a CONCEPT per substituted span, and stronger than
-// resonance, which only claims an angle.  Nothing is invented: the answer IS a
-// trained form, voiced whole.
-//
-// NO NOTION OF TEXT.  This mechanism reads bytes and geometry only.  It has no
-// separator, no character class, no "word": the only structural quantity it
-// uses is W, the river's grouping window, which is the same capacity the
-// perception tree groups by and the same bar the argument-binding tier holds
-// its constituents to.  A completion shorter than one grouping window carries
-// no structure the geometry can perceive, whatever the modality — that is a
-// statement about the fold, not about punctuation.  Presentation (what is
-// "spacing", what is "case") belongs to the injected canon and to the modality
-// entry point, never here; see src/canon.ts.
-//
-// WHY THE EARLIER TIERS CANNOT DO IT.  Two independent reasons, both measured:
-//
-//   1. `resolve(prefix)` is null.  A proper prefix of a deposited stream has no
-//      branch of its own unless it was itself deposited, so the exact tiers
-//      have nothing to find.
-//   2. The form is not among the resonance candidates AT ALL.  Measured on the
-//      trained store: cos(query, that form) = 0.5752, yet the form is absent
-//      from `resonate(k)` at k = 24, 256 AND 2048 — while forms scoring LOWER
-//      (Germany 0.5670, Yemen 0.5591) are returned.  `k` only reorders WITHIN
-//      the IVF clusters already probed, exactly as Store.resonate's doc warns,
-//      so no k recovers it.  With `exhaustive` it ranks 8.
-//
-// So this is a RETRIEVABILITY gap, not a semantic one, and it is repaired by
-// reading the candidate list recall's refusal path has ALREADY fetched
-// exhaustively for the substitution bridge — never by resonating on its own.
-// Measured cost of the scan over those 570 candidates: 2.9 ms warm, 20.4 ms
-// cold, against a ~700 ms refusal path.  Issuing a FRESH exhaustive call would
-// cost 490 ms median against 13 ms non-exhaustive (36×), which is why this tier
-// takes the candidate list as an argument and adds nothing to it.
-//
-// THREE GUARDS, each falsified into existence by measurement — do not drop any:
-//
-//   1. AN UNREADABLE CONTINUATION VETOES.  Reads are bounded (a stored span can
-//      run to hundreds of kilobytes), so a candidate that opens with the query
-//      but SATURATES the read continues in a way nobody can see.  It is a
-//      standing disagreement: if any such candidate exists, nothing is grounded.
-//      It must NOT be quietly skipped, and that is not a stylistic point — the
-//      skip is what MANUFACTURES a fragment.  Measured on a one-deposit fixture
-//      whose form exceeds the cap: the query matched BOTH the whole 138-byte
-//      form (saturating) AND an interior fold node of 34 bytes (unsaturated,
-//      continuing `" Paris, an"`).  Skipping the saturated candidate removed the
-//      only evidence that disagreed, uniqueness then passed on the interior
-//      node, and a mid-form slice was voiced as an answer.  Suppressing the
-//      disagreement is what created the fabrication.
-//      (Testing instead whether a candidate is a "complete form" via the fold
-//      does NOT work and was measured: content addressing makes an interior
-//      node resolve to ITSELF, so self-resolution says nothing about
-//      completeness.)
-//   2. THE CONTINUATION MUST REACH ONE GROUPING WINDOW.  A trained
-//      `What is the capital of France??` opens with `What is the capital of
-//      France?` and continues by a single byte.  Below W the continuation is
-//      sub-quantum — the fold groups nothing from it — and voicing it produces
-//      the degenerate reply that is a known failure smell.
-//   3. UNIQUENESS.  Several trained forms may open with the query and continue
-//      differently, and then the corpus does not say which continuation the
-//      asker means.  Distinct continuations ⇒ refuse.  This is the documented
-//      PREFIX TRAP, and it is real — just not for every prefix.  Measured: of
-//      15 battery probes exactly ONE yields a unique continuation, and all
-//      three honest-silence probes yield none (including `What is the capital
-//      of Zamunda?`, whose top hit scores 0.83).
-//
-// Uniqueness is judged on the continuation BYTES, not on the candidate id: the
-// same continuation reached through two trained forms is one answer, not an
-// ambiguity.
-import { bytesEqual } from "../bytes.js";
-import { rItem } from "./trace.js";
-import { canonicalWindows, leafIdPrefix } from "./canonical.js";
-import { hubBound } from "./traverse.js";
-/** Trained forms the query may OPEN, proposed from the write side's own
- *  leaf-id window index — the supply of last resort for {@link
- *  prefixCompletion}.
- *
- *  WHY A SECOND SUPPLY EXISTS.  The ranked list this mechanism normally reads
- *  is a resonance list, and resonance cannot rank a proper prefix: measured on
- *  the trained store, cos(prefix, form) falls from 0.9629 at a one-byte
- *  truncation to 0.6206 at three bytes, against a reachThreshold of 0.8750.
- *  Three bytes of truncation put the answer out of reach on GEOMETRY, not on a
- *  bug, so no k and no re-ranking recovers it.
- *
- *  WHY THIS ROUTE WORKS WHERE THE FOLD DOES NOT.  A query's own fold is
- *  useless here: content addressing is not phrase-position-invariant, so a
- *  standalone prefix folds to a DIFFERENT node than the same bytes sitting
- *  inside a longer deposit, and neither the prefix's own node nor its
- *  ancestors lead to the deposit (measured: the 22-byte prefix of the
- *  photosynthesis form resolves, is shared by 6 contexts, and does not have
- *  the form among its ancestors).  Leaf ids ARE position-invariant — they are
- *  content-addressed on single bytes — and `indexSubSpans` already interns a
- *  flat branch over every canonical WINDOW of a deposit's leaf-id stream, with
- *  containment edges to the chunks that window spans.  A query that is a
- *  prefix therefore shares those window nodes exactly, and reaches the deposit
- *  by climbing containment then parents.  Nothing is added to the write side;
- *  this reads an index training already built.
- *
- *  BOUNDED (§2.8), AND WITH NO NEW THRESHOLD.  The window whose containment is
- *  SMALLEST carries the most evidence, and one saturated at `hubBound` carries
- *  none — that is the same √N reading of "hub" the rest of the mind uses, not
- *  a tuned knob.  The upward walk spends a budget of `hubBound` nodes and
- *  fans out by W, so a hub query enumerates nothing and the caller stays
- *  silent rather than guessing (§2.13).  Measured on the trained store: the
- *  photosynthesis form at a one-byte truncation picks a window with 52
- *  containers, visits 446 nodes, and yields exactly ONE candidate that
- *  survives the caller's byte compare — the form itself.
- *
- *  These are PROPOSALS only.  Every candidate still faces the byte-exact
- *  prefix compare and all three guards below, so a wrong proposal costs one
- *  bounded read and can never be voiced (§2.3). */
-export function prefixCandidates(ctx, query) {
-    const store = ctx.store;
-    const W = ctx.space.maxGroup;
-    const run = leafIdPrefix(ctx, query);
-    // The widest canonical window is the most discriminative one the write side
-    // ever interned; a query too short to spell one carries no window evidence.
-    const len = canonicalWindows(W)[1];
-    if (run.length < len)
-        return [];
-    const bound = hubBound(ctx);
-    let best = null;
-    let bestN = 0;
-    for (let off = 0; off + len <= run.length; off++) {
-        const wid = store.findBranch(run.slice(off, off + len));
-        if (wid === null)
-            continue;
-        const n = store.containersSlice(wid, 0, bound).length;
-        // Empty says the window spans no chunk; saturated says it is a hub, whose
-        // containment discriminates nothing.  Neither is evidence.
-        if (n === 0 || n >= bound)
-            continue;
-        if (best === null || n < bestN) {
-            best = wid;
-            bestN = n;
-        }
-    }
-    if (best === null)
-        return [];
-    let frontier = store.containersSlice(best, 0, bound);
-    const seen = new Set(frontier);
-    let budget = bound;
-    while (frontier.length > 0 && budget > 0) {
-        const next = [];
-        for (const f of frontier) {
-            if (budget-- <= 0)
-                break;
-            for (const p of store.parentsFirst(f, W)) {
-                if (seen.has(p))
-                    continue;
-                seen.add(p);
-                next.push(p);
-            }
-        }
-        frontier = next;
-    }
-    return [...seen];
-}
-/** The sole trained form the query opens — or null when no candidate opens with
- *  it, when the continuation is sub-quantum, when a candidate's continuation
- *  cannot be read through, or when the candidates disagree.
- *
- *  `ranked` must be a list the caller has ALREADY fetched; this mechanism never
- *  resonates on its own (see the header's cost note). */
-export function prefixCompletion(ctx, query, ranked) {
-    const W = ctx.space.maxGroup;
-    const t = ctx.trace?.enter("prefixCompletion", [rItem(query, "query")]);
-    const done = (hit, note, data) => {
-        t?.done(hit === null ? [] : [rItem(hit.continuation, "continuation", hit.id)], note, data);
-        return hit;
-    };
-    // Reads are bounded to phrase scale, the same bound the frame filler uses.
-    // A query with no room for a whole grouping window past its own length
-    // cannot clear guard 2, so it is not worth a single read.
-    const cap = query.length * W;
-    if (query.length === 0 || cap < query.length + W) {
-        return done(null, "no room for a perceivable continuation within the cap");
-    }
-    // Distinct continuations, each with the first form that offered it.  Held as
-    // a list, not a byte-keyed map: candidates that open with the query are few
-    // (measured: 1 on the trained store's winning query), and a linear byte
-    // compare needs no string encoding of content.  Uniqueness (guard 3) is
-    // decided over this list, so the scan cannot stop early — a second
-    // continuation IS the refusal, and finding it is the point.
-    const found = [];
-    let opened = 0;
-    let unreadable = 0;
-    let subQuantum = 0;
-    for (const id of ranked) {
-        const form = ctx.store.bytesPrefix(id, cap);
-        if (form.length <= query.length)
-            continue;
-        let opens = true;
-        for (let i = 0; i < query.length; i++) {
-            if (form[i] !== query[i]) {
-                opens = false;
-                break;
-            }
-        }
-        if (!opens)
-            continue;
-        opened++;
-        // Guard 1: a saturated read continues out of sight — a disagreement that
-        // cannot be resolved, so it ends the search rather than being skipped.
-        if (form.length >= cap) {
-            unreadable++;
-            continue;
-        }
-        const rest = form.subarray(query.length);
-        // Guard 2: below one grouping window there is no structure to voice.
-        if (rest.length < W) {
-            subQuantum++;
-            continue;
-        }
-        if (!found.some((f) => bytesEqual(f.continuation, rest))) {
-            found.push({ id, form, continuation: rest });
-        }
-    }
-    const data = {
-        candidates: ranked.length,
-        opened,
-        unreadable,
-        subQuantum,
-        distinctContinuations: found.length,
-    };
-    if (unreadable > 0 && found.length > 0) {
-        return done(null, "a form opens with this query but continues past the read bound — " +
-            "its continuation cannot be read, so none is licensed", data);
-    }
-    // Guard 2b: A SUB-QUANTUM CONTINUATION IS STILL A DISAGREEMENT.  Guard 2
-    // refuses to VOICE a below-window continuation, and rightly — there is no
-    // structure there to speak.  But dropping such a candidate from the
-    // uniqueness tally silently converts "the corpus offers many continuations,
-    // most of them unvoiceable" into "the corpus offers exactly one", and
-    // guard 3 then passes VACUOUSLY on the sole survivor.  That is precisely
-    // the failure guard 1 documents for unreadable continuations — suppressing
-    // the disagreement is what manufactures the answer — so it is answered the
-    // same way, and for the same reason.
-    //
-    // Measured on a 4,300-fact fixture of "what is the value of <i>?": the
-    // query "what is the value of" drew candidates continuing " 0?", " 4?",
-    // " 8?" (3 bytes, sub-quantum at W=4) and " 10?" (4 bytes).  The first
-    // three were dropped, leaving one survivor, and the mechanism reported
-    // "exactly one trained form" and voiced "the value of 10 is 20" — an
-    // arbitrary pick from thousands of equally-good readings, with the
-    // evidence of ambiguity discarded on the way.
-    //
-    // Note this can only ever cause SILENCE, never a different answer: it
-    // withholds a completion the corpus does not uniquely license.
-    if (subQuantum > 0 && found.length > 0) {
-        return done(null, "other trained forms open with this query but continue below one " +
-            "grouping window — the corpus offers competing readings, so no " +
-            "single completion is licensed", data);
-    }
-    // Guard 3: the corpus must agree on ONE continuation.
-    if (found.length !== 1) {
-        return done(null, found.length === 0
-            ? "no trained form opens with this query and continues perceivably"
-            : "trained forms open with this query but continue differently — " +
-                "the corpus does not say which continuation is meant", data);
-    }
-    return done(found[0], "one trained form opens with this query, and continues perceivably", data);
-}