@hviana/sema 0.2.5 → 0.2.6

package/dist/src/mind/reasoning.js

@@ -1,240 +0,0 @@
-// reasoning.ts — multi-hop reasoning + multi-topic fusion (Section 4 of the mind).
-//
-//   reason       — extend an answer forward across facts (multi-hop)
-//   fuseAttention — fuse independent points of attention (multi-topic)
-import { rItem, rNode } from "./trace.js";
-import { bytesEqual, indexOf } from "../bytes.js";
-import { resolve } from "./primitives.js";
-import { corpusN } from "./traverse.js";
-import { follow, haloSiblings, project } from "./match.js";
-import { joinWithBridge, pivotInto } from "./resonance.js";
-/** Whether `bytes` is a proper byte-subspan of `query` — already present in
- *  the question, so voicing it back only restates part of what was asked,
- *  never answers it.  The exact guard recallByResonance already applies to
- *  its OWN grounding candidates (tier 1's `restates`, tier 2's subspan
- *  check, tier 0b's argument-binding subspan check) — every mechanism that
- *  walks a LEARNT CONTINUATION EDGE past an already-vetted grounding
- *  (reason()'s own hops below, and CAST's `projectCounterfactual` seat
- *  substitution — see cast.ts) needs the same guard applied to what the
- *  walk turns up, since `follow()`/`chooseNext`/`pivotInto` know nothing of
- *  the query at all — only of what structurally continues what. */
-export function restatesQuery(query, bytes) {
-    return bytes.length < query.length && indexOf(query, bytes, 0) >= 0;
-}
-/** Extend a grounded answer forward across facts (multi-hop reasoning).
- *  Pivots on the longest unconsumed learnt context each answer contains,
- *  then follows the pivot's continuation to the next fact.  Repeats up
- *  to `cfg.recallQueryK` hops.  `preConsumed` carries node ids already
- *  spoken for by the grounding stage (cover/extract/CAST).  `pre` is the
- *  response's shared pre-computation — the post-grounding stages read the
- *  same container the mechanisms did. */
-export async function reason(ctx, query, answer, preConsumed, pre) {
-    // Echo guard: a query that is ITSELF a learnt continuation (some context's
-    // answer) is being asked back at the system — hopping forward from it would
-    // chain through the very fact that produced it and echo the conversation
-    // back.  The grounded answer alone is the honest read-out.  Deliberately a
-    // broad structural gate; pinned by test/31-audit.
-    const qId = pre.queryResolved;
-    if (qId !== null && ctx.store.prevCount(qId) > 0)
-        return answer;
-    const consumed = new Set();
-    // Consume a node and its neighbours for pivot-cycle prevention — CAPPED at
-    // the hub bound, via the store's LIMITed edge reads: a common continuation's
-    // reverse fan-in (and a hub context's forward fan-out) is corpus-sized, and
-    // no per-hop operation may grow with the corpus.  The cap follows the one
-    // convention every fan-out decision uses (first √N in the relation's own
-    // read order); a pivot suppressed only by a beyond-cap neighbour may now
-    // fire — the same visibility trade chooseNext documents.
-    const hubBound = Math.ceil(Math.sqrt(corpusN(ctx)));
-    const consumeNode = (id) => {
-        if (id === null)
-            return;
-        consumed.add(id);
-        for (const p of ctx.store.prevFirst(id, hubBound))
-            consumed.add(p);
-    };
-    const consumeAll = (id) => {
-        if (id === null)
-            return;
-        consumeNode(id);
-        for (const n of ctx.store.nextFirst(id, hubBound))
-            consumed.add(n);
-    };
-    // Pre-consume whatever the grounding stage already spoke for.  The halo
-    // sweep is one ANN query per node — cap it at haloQueryK sweeps (cover
-    // grounding can pre-consume one node per recognised site, O(query length));
-    // nodes past the cap are still consumed directly, they just skip the
-    // synonym expansion.
-    let haloSweeps = 0;
-    for (const id of preConsumed) {
-        consumeNode(id);
-        if (haloSweeps >= ctx.cfg.haloQueryK)
-            continue;
-        const h = ctx.store.halo(id);
-        if (!h)
-            continue;
-        haloSweeps++;
-        for (const sib of await haloSiblings(ctx, id, h))
-            consumeNode(sib.id);
-    }
-    let cur = answer;
-    const qv = pre.guide; // the response-wide guide IS the query's gist
-    let t;
-    const startedFrom = answer;
-    for (let hop = 0; hop < ctx.cfg.recallQueryK; hop++) {
-        const curId = resolve(ctx, cur);
-        consumeNode(curId);
-        // Forward-absorb: follow only UNCONSUMED continuations.  The gate below
-        // checks an unconsumed edge EXISTS, but follow()'s chooseNext knows
-        // nothing of `consumed` and may still walk to a consumed fixpoint —
-        // absorbing it would repeat content the grounding stage already spoke
-        // for, so a consumed fixpoint falls through to the pivot step instead.
-        if (curId !== null &&
-            ctx.store.nextFirst(curId, hubBound).some((n) => !consumed.has(n))) {
-            const fwd = await follow(ctx, curId, qv);
-            const fwdId = fwd !== null ? resolve(ctx, fwd) : null;
-            if (fwd !== null && !bytesEqual(fwd, cur) &&
-                (fwdId === null || !consumed.has(fwdId)) &&
-                !restatesQuery(query, fwd)) {
-                consumeAll(curId);
-                t ??= ctx.trace?.enter("reason", [
-                    rItem(startedFrom, "grounded"),
-                ]);
-                ctx.trace?.step("absorbForward", [rItem(cur, "answer", curId)], [rItem(fwd, "answer", resolve(ctx, fwd) ?? undefined)], "the answer is itself a learnt fact — follow its continuation to the fixpoint");
-                cur = fwd;
-                continue;
-            }
-        }
-        // Pivot: find the longest unconsumed learnt context the answer contains.
-        consumeAll(curId);
-        const pivot = await pivotInto(ctx, cur, consumed);
-        if (pivot === null)
-            break;
-        const fc = await follow(ctx, pivot, qv);
-        consumeAll(pivot);
-        if (fc === null || bytesEqual(fc, cur) || restatesQuery(query, fc))
-            break;
-        t ??= ctx.trace?.enter("reason", [rItem(startedFrom, "grounded")]);
-        ctx.trace?.step("pivotStep", [rItem(cur, "answer"), rNode(ctx, pivot, "pivot")], [rItem(fc, "answer", resolve(ctx, fc) ?? undefined)], "pivot on the shared span this answer contains, then step forward across that fact");
-        cur = fc;
-    }
-    t?.done([rItem(cur, "answer", resolve(ctx, cur) ?? undefined)], "the multi-hop chain's fixpoint");
-    return cur;
-}
-/** Fuse independent points of attention into one answer (multi-topic).
- *  When the consensus climb finds more than one dominant point, each
- *  independent point grounds its own answer; they are bridged together
- *  by any learnt connector the graph holds between them. */
-export async function fuseAttention(ctx, query, primary, pre, 
-/** True when `primary` never touched the consensus climb at all — e.g. a
- *  pure ALU computation, which has no anchor of its own.  commitVotes
- *  ALWAYS admits the dominant root regardless of its vote (attention.ts:
- *  "roots.length === 0 || …") on the assumption a lone root already IS
- *  primary's own source; that assumption is exactly backwards when
- *  primary is unclimbed.  Absent or false preserves the original
- *  behaviour exactly. */
-unclimbed = false) {
-    // When the answer is structurally drawn from the query itself
-    // (extraction), it already spans all the query's pieces — fusion
-    // would only add noise from unrelated stored contexts.  The gate is
-    // STRICT containment (resolved node in the query's tree, or a contiguous
-    // byte run): the old sparse-subsequence test was trivially satisfied by
-    // short answers over long queries, silently starving multi-topic queries
-    // of fusion.
-    if (containsSpan(ctx, query, primary))
-        return primary;
-    // The committed points of attention ARE the shared climb's roots (same
-    // query, same k, same DF mode) — read them from Precomputed instead of
-    // re-climbing, so even a traced response pays for the climb once.
-    const forest = (await pre.attention()).roots;
-    // A LONE root is ordinarily primary's own source — nothing to fuse.  But
-    // when primary is unclimbed, the lone root was never checked against
-    // anything: it is admitted by commitVotes unconditionally, so it may be
-    // genuine consensus (Attention.breadth dominates — most of the query's
-    // OWN regions corroborate it) or a coincidental echo (breadth does not
-    // dominate — see test/35-attention-confidence).  breadth is the SCALE-
-    // INVARIANT read of exactly this question: the raw IDF vote cannot serve
-    // here, since it is an absolute ln(N)-scaled quantity (a genuine root on
-    // a large store can score BELOW its own floor while a coincidental echo
-    // on a small one scores comfortably above its own, smaller, floor).
-    const lonePromotes = unclimbed && forest.length === 1 &&
-        forest[0].breadth > 0.5;
-    if (forest.length === 0 || (forest.length <= 1 && !lonePromotes)) {
-        return primary;
-    }
-    const pieces = [
-        { start: forest[0].start, bytes: primary },
-    ];
-    const qv = pre.guide; // once, not per root
-    const rest = lonePromotes ? forest : forest.slice(1);
-    const t = ctx.trace?.enter("fuseAttention", [
-        rItem(primary, "primary"),
-        ...rest.map((r) => rNode(ctx, r.anchor, "point", r.vote)),
-    ]);
-    for (const root of rest) {
-        // DISPERSION: this root's contributing regions are confined to a
-        // single cluster (see Attention.clusters) — one local neighbourhood of
-        // the query, not several separate places.  Raw region count already
-        // failed to discriminate a coincidental match from a genuine further
-        // topic (test/24 gap 3.1 vs test/35's echo); dispersion is a different
-        // question — not how MUCH evidence, but how many separate PLACES in the
-        // query corroborate it — and a coincidental match is structurally
-        // confined to one cluster no matter how strongly it resonates.
-        //
-        // EXCEPTION: crossRegionVotes' own joint conclusions (a query naming
-        // two attributes that were only ever learnt TOGETHER — test/34's own
-        // binding corpus) are inherently ONE fused context and are pooled from
-        // a single synthetic region, so they always read as one cluster even
-        // though they already, by construction, account for both original
-        // mentions.  `breadth` (dominates — the same > half-the-query bar used
-        // everywhere else) still correctly recognises these: a genuine joint
-        // binding explains the MAJORITY of the query's regions on its own,
-        // which a coincidental echo never does (verified: test/35's echo tops
-        // out at 0.40).  So a root is trusted when EITHER measure alone
-        // indicates real signal — excluded only when BOTH are weak.  Cheap and
-        // synchronous — checked before the async already-answered walk below.
-        if (root.clusters < 2 && root.breadth <= 0.5) {
-            ctx.trace?.step("singleCluster", [rNode(ctx, root.anchor, "point", root.vote)], [], "this point's evidence is confined to one local neighbourhood of the query — not trusted as an independent topic");
-            continue;
-        }
-        // ALREADY ANSWERED: this root's own learnt continuation — the same
-        // content-addressed walk reason()'s echo guard already trusts
-        // (`ctx.store.prevCount(qId) > 0`), here applied per-candidate instead
-        // of to the whole query — is VERBATIM present later in the query.  A
-        // query that embeds both an exchange's ask and its own already-given
-        // reply (a conversation's turn plus its own prior answer, concatenated
-        // raw by addTurn — or any caller pasting a transcript into one
-        // respond() call; the check is Mind-bookkeeping-free, so it treats both
-        // identically) has already spoken this root's answer — fusing it in
-        // again would only restate it.  Deliberately NOT a magnitude measure:
-        // it fires on exact content-addressed recurrence, not on how strongly
-        // the root resonates.
-        const cont = await follow(ctx, root.anchor, qv);
-        if (cont !== null && cont.length > 0 && indexOf(query, cont, root.end) >= 0) {
-            ctx.trace?.step("alreadyAnswered", [rNode(ctx, root.anchor, "point", root.vote)], [rItem(cont, "continuation")], "this point's own learnt continuation already appears later in the query — already answered, not fused");
-            continue;
-        }
-        const g = await project(ctx, root.anchor, qv);
-        if (g === null || g.length === 0)
-            continue;
-        if (pieces.some((p) => indexOf(p.bytes, g, 0) >= 0))
-            continue;
-        pieces.push({ start: root.start, bytes: g });
-    }
-    if (pieces.length === 1) {
-        t?.done([rItem(primary, "answer")], "no further independent point grounded");
-        return primary;
-    }
-    pieces.sort((a, b) => a.start - b.start);
-    let out = pieces[0].bytes;
-    for (let i = 1; i < pieces.length; i++) {
-        // An approximate-resonance miss (or a genuinely unlearnt junction) joins
-        // the pieces bare — joinWithBridge surfaces it as a bridgeMiss step.
-        out = await joinWithBridge(ctx, out, pieces[i].bytes);
-    }
-    t?.done([rItem(out, "answer", resolve(ctx, out) ?? undefined)], `fused ${pieces.length} independent points of attention into one answer`);
-    return out;
-}
-// (resonance.js is already a static dependency above — `bridge` — so the old
-// dynamic import of pivotInto guarded against a cycle that does not exist.)
-import { containsSpan } from "./mechanisms/extraction.js";

package/dist/src/mind/recognition.d.ts

@@ -1,20 +0,0 @@
-import type { MindContext, Recognition, Segment } from "./types.js";
-/** Decompose a byte stream into every stored form that leads somewhere
- *  (has a continuation edge or a halo).  Two complementary readings:
- *
- *   • structural — walk the query's own perceived tree, naming each subtree
- *     by findLeaf at the leaves and findBranch above.  Catches every form
- *     aligned to the query's segmentation.
- *
- *   • canonical — re-derive the store's segmentation directly: at each byte,
- *     the longest known leaf, chained into flat branches.  Names forms the
- *     query's own cut cannot, and records sub-leaf boundaries as `splits`.
- *
- *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
-export declare function recognise(ctx: MindContext, bytes: Uint8Array): Recognition;
-/** Segment bytes using the geometry's own groupings — leaf-parent
- *  nodes from the perceived tree, with consecutive bare leaves merged
- *  into one segment.  Each segment's gist is perceived from its bytes
- *  IN ISOLATION, so the same content has the same gist regardless of
- *  where it appears. */
-export declare function segment(ctx: MindContext, bytes: Uint8Array): Segment[];

package/dist/src/mind/recognition.js

@@ -1,390 +0,0 @@
-// recognition.ts — Section 2 of the mind:
-// Address + Read over byte streams — decompose a query into its known forms.
-//
-//   recognise — structural + canonical decomposition into every stored form
-//               that leads somewhere (has a continuation edge or a halo).
-//   segment   — leaf-parent segmentation using the geometry's own groupings.
-import { rItem } from "./trace.js";
-import { canonResolve, foldTree, gistOf, latin1Key, perceive, resolve, } from "./primitives.js";
-import { atomIsHub, corpusN, leadsSomewhere } from "./traverse.js";
-import { chainReach, leafIdAt, leafIdRun } from "./canonical.js";
-import { isChunk } from "../sema.js";
-/** Decompose a byte stream into every stored form that leads somewhere
- *  (has a continuation edge or a halo).  Two complementary readings:
- *
- *   • structural — walk the query's own perceived tree, naming each subtree
- *     by findLeaf at the leaves and findBranch above.  Catches every form
- *     aligned to the query's segmentation.
- *
- *   • canonical — re-derive the store's segmentation directly: at each byte,
- *     the longest known leaf, chained into flat branches.  Names forms the
- *     query's own cut cannot, and records sub-leaf boundaries as `splits`.
- *
- *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
-export function recognise(ctx, bytes) {
-    // Content-keyed memo — works for both single-turn respond() and multi-turn
-    // respondTurn() (where the map persists across calls).  ALWAYS consulted,
-    // regardless of tracing — matching perceive()'s own memo, which carries no
-    // trace gate at all.  This memo is NOT an optional accelerator: recogniseImpl
-    // walks the query's perceived tree via foldTree, whose subtree-resolution
-    // fast path (see primitives.ts) skips invoking `visit` — and therefore
-    // skips EMITTING SITES — for any subtree already cached in
-    // ctx._resolvedSubtrees.  A multi-turn conversation's stable-prefix fold
-    // deliberately shares node OBJECTS across turns, so by the second call on
-    // the exact same bytes, large swaths of the tree are already cached and
-    // foldTree stops short of recursing into them — a second recogniseImpl
-    // call on the SAME bytes is not idempotent; it silently finds FEWER sites
-    // than the first (observed live: 31 sites → 5 on an immediate repeat
-    // call).  Skipping this memo "only while tracing" used to mean every
-    // traced turn re-ran recogniseImpl from scratch at every one of the many
-    // call sites that recognise the same query (cover, reason, articulate...),
-    // each subsequent call silently more incomplete than the last — measurably
-    // changing which mechanism grounds the answer, not just costing time.  The
-    // trace step must still fire on every call regardless (a cache hit is not
-    // silent), so it is emitted here directly instead of only inside
-    // recogniseImpl.
-    if (ctx.recogniseMemo) {
-        const key = latin1Key(bytes);
-        const hit = ctx.recogniseMemo.get(key);
-        if (hit !== undefined) {
-            ctx.trace?.step("recognise", [rItem(bytes, "query")], hit.sites.map((s) => rItem(bytes.subarray(s.start, s.end), "form", s.payload, [
-                s.start,
-                s.end,
-            ])), `decompose the query into ${hit.sites.length} learnt form(s) that ` +
-                `lead somewhere (over ${hit.leaves.length} perceived leaves) [cached]`);
-            return hit;
-        }
-        const fresh = recogniseImpl(ctx, bytes);
-        ctx.recogniseMemo.set(key, fresh);
-        return fresh;
-    }
-    return recogniseImpl(ctx, bytes);
-}
-function recogniseImpl(ctx, bytes) {
-    const store = ctx.store;
-    const sites = [];
-    const leaves = [];
-    const splits = new Set();
-    const starts = new Set();
-    if (bytes.length === 0)
-        return { sites, leaves, splits, starts };
-    // Span-resolve memo for THIS call: the structural pass (sub-runs inside
-    // leaf-parents) and the canonical pass (leaf-id chains) probe overlapping
-    // spans, and each resolve() is a full fold of the sub-span (fresh subarray
-    // objects — the per-response perceive memo cannot see them).  Keyed
-    // numerically by (start, end); resolve is pure and the store is read-only
-    // here, so a hit is exact.
-    const spanIds = new Map();
-    const resolveSpan = (start, end) => {
-        const key = start * (bytes.length + 1) + end;
-        let id = spanIds.get(key);
-        if (id === undefined) {
-            id = resolve(ctx, bytes.subarray(start, end));
-            spanIds.set(key, id);
-        }
-        return id;
-    };
-    // Byte atoms (implicit negative-id single-byte leaves) are admitted as
-    // recognised sites only while atoms can still DISCRIMINATE at this corpus
-    // scale (see {@link atomIsHub}).  On a small store a single-letter fact
-    // ("a" → "A") is genuine learnt content and its site is essential; on a
-    // large one every letter of every query would otherwise become a
-    // "recognised form" — the bridge then finds junction connectors between
-    // bare letters, cover follows edges hanging off them, and pure noise
-    // ("qq8f3kz9…") grounds to an arbitrary learnt sentence instead of
-    // silence.  Atoms stay available as leaves (PASS-carried literals) and
-    // through exact tier-0 resolution regardless.
-    const atomsAreHubs = atomIsHub(ctx, corpusN(ctx));
-    // Distinct probes (structural exact match, canon fallback, edge trims at
-    // several offsets) can legitimately re-derive the SAME (start, end, id)
-    // site from different tree nodes — a wide edge-trim search is exactly
-    // this on purpose (see below).  Duplicate site entries are not wrong
-    // evidence, but they double the weight cover's derivation search gives
-    // that span, distorting its cost model — the same span must count once.
-    const seen = new Set();
-    const emit = (start, end, id) => {
-        if (id < 0 && atomsAreHubs)
-            return;
-        const key = start + "," + end + "," + id;
-        if (seen.has(key))
-            return;
-        seen.add(key);
-        if (leadsSomewhere(ctx, id)) {
-            sites.push({ start, end, payload: id });
-        }
-    };
-    // ── structural: the query's own perceived tree ──────────────────────
-    starts.add(0);
-    foldTree(ctx, perceive(ctx, bytes), 0, (n, start, end, node) => {
-        if (n.kids === null) {
-            leaves.push({ start, end, bytes: n.leaf ?? new Uint8Array(0), node });
-        }
-        if (node !== null)
-            emit(start, end, node);
-        // Canonical fallback: a subtree whose exact content-addressed lookup
-        // missed may still be a stored form under the response's equivalence
-        // (case, width, whitespace — whatever the injected canonicalizer says).
-        // O(subtree bytes) per miss, memoised per response; a no-op when no
-        // canonicalizer was injected or the store has no canon index.  A raw
-        // leaf (n.kids === null) is single-byte and handled by the byte-atom
-        // path above instead — canon equivalence only applies to composites.
-        else if (n.kids !== null) {
-            const cid = canonResolve(ctx, bytes.subarray(start, end));
-            if (cid !== null)
-                emit(start, end, cid);
-            // The edge-trim fallbacks below remove 1 byte from a side; the
-            // remainder must still be a composite (>= 2 bytes, the same floor
-            // n.kids !== null enforces above) rather than degenerate into
-            // single-byte-atom territory, which atomIsHub already governs
-            // separately.
-            else if (end - start - 1 >= 2) {
-                // The chunk's own boundary is drawn by content geometry, not by
-                // any notion of "form" — it can include one edge byte the query's
-                // fold happened to attach here that the trained span never had
-                // (e.g. a separator from the preceding chunk).  The core has no
-                // idea what that byte means; it only knows resolve()/canonResolve
-                // are self-verifying (hash-then-verify, same discipline as every
-                // content lookup here), so a blind one-byte-shorter guess on
-                // either edge costs nothing when wrong and is trustworthy when it
-                // hits.  Two extra probes, only on the already-failed miss path.
-                const left = resolve(ctx, bytes.subarray(start + 1, end));
-                if (left !== null)
-                    emit(start + 1, end, left);
-                const right = resolve(ctx, bytes.subarray(start, end - 1));
-                if (right !== null)
-                    emit(start, end - 1, right);
-                // A misalignment wider than one byte (e.g. more than one edge
-                // separator swallowed) is not itself geometry-quantized — the
-                // WRITE side's canonical index (canonicalWindows) interns sliding
-                // W−1/W-length windows over leaf ids at EVERY offset, not just
-                // radix-aligned ones (see canonical.ts) — so the offset that
-                // recovers a trained span can be anything, not a multiple of W.
-                // What IS bounded is how far it's worth looking: chainReach(W)=W²,
-                // the same reach the canonical pass (tryChain) trusts for a chain
-                // rebuilt off the query's own fold.  Every candidate offset is
-                // gated by store.findBranch(leafIds) first — the SAME cheap,
-                // fold-free existence check tryChain already uses — so the extra
-                // resolve() fold (the real cost) is only paid when a branch could
-                // plausibly exist there, not for every offset.  The node itself is
-                // also bounded to chunk-scale (end - start <= W²): widening this at
-                // whole-query/root scale can rediscover a smaller subtree's own
-                // content as a second, overlapping site the structural walk's own
-                // finer recursion already emits correctly on its own — a duplicate
-                // that downstream derivation can stitch into a wrong answer.
-                const W = ctx.space.maxGroup;
-                for (let k = 1; end - start <= W * W && k <= W * W && start + k < end - 1; k++) {
-                    const lIds = leafIdRun(ctx, bytes, start + k, end);
-                    if (lIds !== null && store.findBranch(lIds) !== null) {
-                        const eLeft = resolve(ctx, bytes.subarray(start + k, end));
-                        if (eLeft !== null)
-                            emit(start + k, end, eLeft);
-                    }
-                    const rIds = leafIdRun(ctx, bytes, start, end - k);
-                    if (rIds !== null && store.findBranch(rIds) !== null) {
-                        const eRight = resolve(ctx, bytes.subarray(start, end - k));
-                        if (eRight !== null)
-                            emit(start, end - k, eRight);
-                    }
-                }
-                // A REAL extra word at the left edge (a discourse connective like
-                // "And " prepended to a follow-up turn — not boundary noise, actual
-                // content the injected canonicalizer has no equivalence for) shows
-                // up as a canon-miss too big for the chunk-scale search above: the
-                // turn is its OWN segment (stable-prefix folded independently — see
-                // mind.ts's _growContext), so it can be turn/segment-scale, not
-                // chunk-scale.  Widening the size bound itself reopens the root-
-                // scale false-positive this module already fixed once (test/46);
-                // widening the SEARCH instead — trying every position up to W
-                // chunk-widths from the left edge that the query's OWN fold treats
-                // as a chunk boundary (`starts`, the same set the canonical pass
-                // privileges with full chain reach) — does not: `starts.has(p)` is
-                // fold EVIDENCE the query produced on its own (a leaf-parent chunk
-                // like "And " is visited, and its start added to `starts`, before
-                // this composite ever runs — foldTree is post-order), never a blind
-                // guess.  Bounded to W candidates, each an O(1) set lookup before
-                // paying for the real canonResolve fold — canonResolve, not
-                // resolve()/findBranch, because the gap here is often exactly the
-                // kind of equivalence (case, in the live trace) canon exists for,
-                // not just an exact-content coincidence.
-                for (let k = 1; k <= W; k++) {
-                    const p = start + k * W;
-                    if (p >= end - 1 || !starts.has(p))
-                        continue;
-                    const cid = canonResolve(ctx, bytes.subarray(p, end));
-                    if (cid !== null)
-                        emit(p, end, cid);
-                }
-            }
-        }
-        if (isChunk(n)) {
-            starts.add(start);
-            // Try every sub-span within this leaf-parent.
-            const leafOffsets = [];
-            let off = start;
-            for (const k of n.kids) {
-                leafOffsets.push(off);
-                off += k.leaf?.length ?? 0;
-            }
-            // Sub-spans starting at i > 0 begin INSIDE the chunk, at an offset the
-            // query's own fold did not itself choose as a boundary — the same
-            // opportunistic byte-atom-chain risk `tryChain`'s `boundary` gate
-            // guards below (see its comment).  Only the chunk's own left edge
-            // (i === 0, already registered in `starts` above) carries the fold's
-            // evidence; interior sub-starts are exempt from the guard only while
-            // atoms themselves still discriminate at this corpus scale.
-            for (let i = 0; i < n.kids.length; i++) {
-                if (i > 0 && atomsAreHubs)
-                    break;
-                const subIds = [];
-                for (let j = i; j < n.kids.length; j++) {
-                    const kj = n.kids[j];
-                    if (kj.kids !== null || !kj.leaf)
-                        break;
-                    const lid = store.findLeaf(kj.leaf);
-                    if (lid === null)
-                        break;
-                    subIds.push(lid);
-                    const branch = store.findBranch(subIds);
-                    if (branch === null)
-                        continue;
-                    const subEnd = leafOffsets[j] + (kj.leaf?.length ?? 0);
-                    const resolved = resolveSpan(leafOffsets[i], subEnd);
-                    if (resolved !== null)
-                        emit(leafOffsets[i], subEnd, resolved);
-                }
-            }
-        }
-    });
-    // ── canonical: longest-known-leaf re-segmentation ──────────────────
-    const W = ctx.space.maxGroup;
-    const singleLeaf = new Array(bytes.length).fill(null);
-    for (let p = 0; p < bytes.length; p++) {
-        const id = leafIdAt(ctx, bytes, p);
-        if (id !== null)
-            singleLeaf[p] = { id, end: p + 1 };
-    }
-    const leafFrom = (p) => {
-        if (p >= bytes.length)
-            return null;
-        return singleLeaf[p];
-    };
-    const chunkEnd = new Uint32Array(bytes.length);
-    const sorted = [...starts].sort((a, b) => a - b);
-    for (let si = 0; si < sorted.length; si++) {
-        const chunkStart = sorted[si];
-        const chunkLimit = si + 1 < sorted.length ? sorted[si + 1] : bytes.length;
-        for (let p = chunkStart; p < chunkLimit; p++) {
-            chunkEnd[p] = chunkLimit;
-        }
-    }
-    // A chain rebuilt from a NON-boundary offset (the query's own perceived
-    // cut, `starts`, never chose to segment here) is opportunistic: the same
-    // byte-atom coincidence the hub guard above already exists for, just
-    // spelled over 2+ leaves instead of 1.  At small corpus scale that's fine
-    // — coincidence is rare and every chain is real evidence (see `atomIsHub`).
-    // Past the scale where atoms themselves stop discriminating, the same
-    // uniform-expectation argument bounds a CHAIN'S commonality too: it is at
-    // least as rare as its rarest atom, so a store where atoms are hubs makes
-    // interior chain reconstructions no more trustworthy than the atoms they
-    // are built from ("hi" resolving out of "W[hi]ch" is exactly this: two
-    // hub-scale atoms, chained at an offset nothing in the query's own fold
-    // selected).  Chains that start ON a boundary carry the fold's own
-    // evidence instead and are exempt.
-    const tryChain = (p, maxIds, boundary) => {
-        const first = leafFrom(p);
-        if (!first)
-            return;
-        emit(p, first.end, first.id);
-        const ids = [first.id];
-        let pos = first.end;
-        let prevId = null;
-        for (let depth = 1; pos < bytes.length && ids.length <= maxIds; depth++) {
-            const nx = leafFrom(pos);
-            if (!nx)
-                break;
-            ids.push(nx.id);
-            pos = nx.end;
-            if (store.findBranch(ids) === null)
-                continue;
-            if (!boundary && atomsAreHubs)
-                continue;
-            const id = resolveSpan(p, pos);
-            if (id === null || id === prevId)
-                continue;
-            prevId = id;
-            emit(p, pos, id);
-        }
-    };
-    for (let p = 0; p < bytes.length; p++) {
-        if (starts.has(p)) {
-            tryChain(p, chainReach(W), true); // boundary start — full reach
-        }
-        else {
-            const limit = chunkEnd[p] + W;
-            tryChain(p, Math.min(limit - p, chainReach(W)), false);
-        }
-    }
-    // ── splits: a form boundary that does not fall on a leaf edge ────────
-    const leafEdges = new Set([bytes.length]);
-    for (const lf of leaves)
-        leafEdges.add(lf.start);
-    for (const s of sites) {
-        if (!leafEdges.has(s.start))
-            splits.add(s.start);
-        if (!leafEdges.has(s.end))
-            splits.add(s.end);
-    }
-    ctx.trace?.step("recognise", [rItem(bytes, "query")], sites.map((s) => rItem(bytes.subarray(s.start, s.end), "form", s.payload, [
-        s.start,
-        s.end,
-    ])), `decompose the query into ${sites.length} learnt form(s) that lead somewhere` +
-        ` (over ${leaves.length} perceived leaves)`);
-    return { sites, leaves, splits, starts };
-}
-/** Segment bytes using the geometry's own groupings — leaf-parent
- *  nodes from the perceived tree, with consecutive bare leaves merged
- *  into one segment.  Each segment's gist is perceived from its bytes
- *  IN ISOLATION, so the same content has the same gist regardless of
- *  where it appears. */
-export function segment(ctx, bytes) {
-    const tree = perceive(ctx, bytes);
-    const out = [];
-    let pendingStart = -1;
-    let pendingEnd = -1;
-    const flush = () => {
-        if (pendingStart >= 0 && pendingEnd > pendingStart) {
-            out.push({
-                start: pendingStart,
-                end: pendingEnd,
-                v: gistOf(ctx, bytes.subarray(pendingStart, pendingEnd)),
-            });
-        }
-        pendingStart = -1;
-        pendingEnd = -1;
-    };
-    const walk = (n, start) => {
-        if (n.kids === null) {
-            const end = start + (n.leaf?.length ?? 0);
-            if (pendingStart < 0)
-                pendingStart = start;
-            pendingEnd = end;
-            return end;
-        }
-        if (isChunk(n)) {
-            flush();
-            let end = start;
-            for (const c of n.kids)
-                end += c.leaf?.length ?? 0;
-            out.push({ start, end, v: gistOf(ctx, bytes.subarray(start, end)) });
-            return end;
-        }
-        flush();
-        let pos = start;
-        for (const c of n.kids)
-            pos = walk(c, pos);
-        return pos;
-    };
-    walk(tree, 0);
-    flush();
-    return out;
-}