@hviana/sema 0.1.7 → 0.1.9

package/dist/src/mind/primitives.js

@@ -1,184 +0,0 @@
-// primitives.ts — Address + Read primitives (Section 1 of the mind).
-//
-//   Address  — bytes → node   (perceive, foldTree, resolve)
-//   Read     — node → bytes   (read)
-import { bytesToTree, bytesToTreePyramid, gridToTree, hilbertBytes, stackGrids, } from "../geometry.js";
-import { ALL } from "./types.js";
-// ── Address: bytes → node ──────────────────────────────────────────────
-/** The content key of a byte span — one latin1 char per byte, an exact,
- *  collision-free encoding.  Spans on the perception path are query-scale
- *  (windows, regions, candidate spans), so key construction is far cheaper
- *  than the river fold it deduplicates. */
-export function latin1Key(bytes) {
-    // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
-    // potentially-large query spans, and stays well under the ~65536 arg limit.
-    const n = bytes.length;
-    let s = "";
-    for (let i = 0; i < n; i += 4096) {
-        s += String.fromCharCode(...bytes.subarray(i, Math.min(i + 4096, n)));
-    }
-    return s;
-}
-/** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree.
- *
- *  `boundaries` is an optional sorted list of proper byte offsets where the
- *  fold must split so that each prefix segment folds identically to how it
- *  folded when it was learned (§10.3 stable-prefix contract).  Only the
- *  CALLER — who assembled the multi-turn context — knows where those
- *  boundaries are; the geometry never guesses them from the bytes. */
-export function perceive(ctx, input, leafAt, lookup, boundaries) {
-    if (typeof input === "string" || input instanceof Uint8Array) {
-        const bytes = typeof input === "string"
-            ? new TextEncoder().encode(input)
-            : input;
-        if (leafAt === undefined && lookup === undefined) {
-            // Per-response memo (see MindContext.perceiveMemo): only the plain
-            // inference shape — raw bytes, no store capabilities — is memoised,
-            // keyed by CONTENT so byte-identical spans in fresh arrays still hit.
-            // The tree is shared by reference; Sema nodes are never mutated.
-            const memo = ctx.perceiveMemo;
-            if (memo) {
-                const key = latin1Key(bytes);
-                const hit = memo.get(key);
-                if (hit !== undefined)
-                    return hit;
-                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
-                memo.set(key, tree);
-                return tree;
-            }
-            return bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
-        }
-        return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
-    }
-    if (Array.isArray(input)) {
-        return gridToTree(ctx.space, ctx.alphabet, stackGrids(input));
-    }
-    return gridToTree(ctx.space, ctx.alphabet, input);
-}
-/** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
- *  perception — that structural train/inference agreement is load-bearing
- *  for exact recall), computed INCREMENTALLY via the fold's level pyramid
- *  ({@link bytesToTreePyramid}).  An accumulated context (a conversation)
- *  grows by suffixes: the previous context's pyramid is cached by CONTENT
- *  (ctx._depositTrees), and this deposit refolds only the right edge of
- *  each level — O(turn) instead of O(context) per turn.  Purely a cache:
- *  the produced tree never depends on cache state. */
-export function perceiveDeposit(ctx, bytes) {
-    let prev;
-    // Longest cached PROPER prefix first.
-    const lens = [...ctx._depositLens]
-        .filter((L) => L >= 2 && L < bytes.length)
-        .sort((a, b) => b - a);
-    for (const L of lens) {
-        const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
-        if (hit !== undefined) {
-            prev = hit;
-            break;
-        }
-    }
-    const { tree, pyramid } = bytesToTreePyramid(ctx.space, ctx.alphabet, bytes, prev);
-    if (bytes.length >= 2) {
-        // The lengths set drifts as the map evicts; past the probe budget the
-        // drift itself becomes the cost (each stale length is an O(len) key
-        // build), so both reset together — losing only warm-up on live chains.
-        if (ctx._depositLens.size > 64) {
-            ctx._depositLens.clear();
-            ctx._depositTrees.clear();
-        }
-        ctx._depositTrees.set(latin1Key(bytes), pyramid);
-        ctx._depositLens.add(bytes.length);
-    }
-    return tree;
-}
-/** The raw bytes of an input — modality-neutral conversion. */
-export function inputBytes(ctx, input) {
-    if (typeof input === "string")
-        return new TextEncoder().encode(input);
-    if (input instanceof Uint8Array)
-        return input;
-    if (Array.isArray(input))
-        return hilbertBytes(stackGrids(input));
-    return hilbertBytes(input);
-}
-/** Convenience: the gist vector of a byte span. */
-export function gistOf(ctx, bytes) {
-    return perceive(ctx, bytes).v;
-}
-/** Fold a perceived tree bottom-up against the store's content-addressed maps:
- *  every leaf is named by findLeaf, every branch by findBranch over its kids'
- *  ids (null the moment any child is unknown).  `visit`, when given, sees each
- *  node with its byte span and resolved id.  Returns the node's byte end and
- *  resolved id. */
-export function foldTree(ctx, n, start, visit) {
-    // Fast path: subtree already resolved (from a previous conversation turn
-    // or an earlier recognition pass).  The pyramid reuses prefix subtrees as
-    // identical Sema objects, so this cache turns foldTree into O(suffix)
-    // instead of O(context) for multi-turn recognition.
-    const cached = ctx._resolvedSubtrees?.get(n);
-    if (cached !== undefined) {
-        const end = start + cached.len;
-        visit?.(n, start, end, cached.id);
-        return { end, node: cached.id };
-    }
-    if (n.kids === null) {
-        const b = n.leaf ?? new Uint8Array(0);
-        const end = start + b.length;
-        const node = ctx.store.findLeaf(b);
-        visit?.(n, start, end, node);
-        if (node !== null && ctx._resolvedSubtrees) {
-            ctx._resolvedSubtrees.set(n, { id: node, len: b.length });
-        }
-        return { end, node };
-    }
-    let pos = start;
-    let known = true;
-    const kids = [];
-    for (const k of n.kids) {
-        const r = foldTree(ctx, k, pos, visit);
-        if (r.node === null)
-            known = false;
-        else if (known)
-            kids.push(r.node);
-        pos = r.end;
-    }
-    const node = known ? ctx.store.findBranch(kids) : null;
-    visit?.(n, start, pos, node);
-    if (node !== null && ctx._resolvedSubtrees) {
-        ctx._resolvedSubtrees.set(n, { id: node, len: pos - start });
-    }
-    return { end: pos, node };
-}
-/** The canonical node id of a byte span: perceive it in isolation — the way
- *  training did — and recover its root bottom-up.  Returns null if any part is
- *  unknown. */
-export function resolve(ctx, bytes) {
-    if (bytes.length === 0)
-        return null;
-    return foldTree(ctx, perceive(ctx, bytes), 0).node;
-}
-/** Walk a perceived tree in POST-ORDER with byte offsets — children before
- *  their parent, `visit(node, start, end)` for every node including leaves.
- *  Returns the byte end.  The one shared traversal the offset-carrying tree
- *  readers (recognition via foldTree's richer variant, attention's region
- *  collection, resonance's branch counting) build on, so each does not
- *  re-derive the offset bookkeeping.  (recognition.segment keeps its own
- *  walk: its flush semantics need PRE-order decisions at leaf-parents, which
- *  a post-order visitor cannot express.) */
-export function walkTree(n, start, visit) {
-    if (n.kids === null) {
-        const end = start + (n.leaf?.length ?? 0);
-        visit(n, start, end);
-        return end;
-    }
-    let pos = start;
-    for (const k of n.kids)
-        pos = walkTree(k, pos, visit);
-    visit(n, start, pos);
-    return pos;
-}
-// ── Read: node → bytes ──────────────────────────────────────────────────
-/** Reconstruct a node's byte content from the DAG, up to `maxLen` bytes. */
-export function read(ctx, id, maxLen = ALL) {
-    return ctx.store.bytesPrefix(id, maxLen);
-}

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

@@ -1,134 +0,0 @@
-import type { Vec } from "../vec.js";
-/** One element of a step's input or output vector.
- *
- *  Modality-neutral and deliberately partial: an element might be a byte span of
- *  the query, a resolved graph node, a resonance hit with its score, a spliced
- *  connector — so every descriptive field is optional and a mechanism fills only
- *  the ones that carry meaning for what it did.  `text` is always present (the
- *  human-readable rendering); the rest is provenance a debugger can lean on. */
-export interface RationaleItem {
-    /** Human-readable rendering — decoded text for a byte span, else a label like
-     *  "‹none›" or an operator name.  Always set, so a step always reads. */
-    text: string;
-    /** The graph node this element is, or resolved to, when known — the handle to
-     *  point back at the exact stored fact in the content-addressed DAG. */
-    node?: number;
-    /** The `[start, end)` span this element occupies in its step's frame of
-     *  reference (usually the query or the answer being composed). */
-    span?: [number, number];
-    /** The resonance / cosine score that selected this element, when it was chosen
-     *  by similarity rather than by exact structure. */
-    score?: number;
-    /** A short role tag — "query", "leaf", "form", "hit", "connector", "answer",
-     *  … — naming what KIND of element this is within the step. */
-    role?: string;
-    /** The gist vector, only when the element fundamentally IS a vector and a
-     *  caller asked to carry it (off by default — a D-float array per item would
-     *  bury the reasoning it is meant to explain). */
-    v?: Vec;
-}
-/** A single completed act of inference — one mechanism, run once.
- *
- *  Steps are emitted in COMPLETION order (a sub-mechanism finishes, and is
- *  reported, before the mechanism that called it), while `index` is assigned in
- *  ENTRY order (a parent reserves its index before its children run).  So a
- *  parent's `index` is always lower than its children's, and the two orderings
- *  together give a valid topological reading of the dependency graph. */
-export interface RationaleStep {
-    /** This step's index, assigned when the mechanism was ENTERED — a strict,
-     *  incremental ordering over the whole inference. */
-    index: number;
-    /** The mechanism and its enclosing mechanisms, outermost → innermost, e.g.
-     *  `["respond", "think", "recognise"]`.  The last entry is this step; the
-     *  prefix is the nest of sub-mechanisms it ran inside. */
-    mechanism: string[];
-    /** The enclosing mechanism's step index, or -1 at the root — the NESTING edge
-     *  of the dependency graph (which step this one is a part of). */
-    parent: number;
-    /** The earlier steps whose OUTPUTS became this step's inputs — the DATA-FLOW
-     *  edges of the dependency graph.  Defaults to the previous sibling (the step
-     *  run just before this one inside the same mechanism), or the parent when
-     *  this is the first sub-step; a mechanism that fuses several earlier results
-     *  names them all explicitly. */
-    dependsOn: number[];
-    /** The vector of elements handed to the mechanism (one or more). */
-    inputs: RationaleItem[];
-    /** The vector of elements the mechanism produced (one or more) — longer than
-     *  `inputs` when it decomposed, shorter when it combined. */
-    outputs: RationaleItem[];
-    /** A one-line, human account of what the mechanism did and why — the sentence
-     *  that turns the data into an explanation. */
-    note?: string;
-}
-/** The callback {@link Mind.respond} / {@link Mind.respondText} accept.  It is
- *  invoked once per completed step, AS the inference unfolds — never batched at
- *  the end — so a caller can stream the reasoning live or accumulate it. */
-export type InspectRationale = (step: RationaleStep) => void;
-/** Decode bytes to text for display, dropping the NUL padding the encoder uses
- *  (the same cleanup {@link Mind.respondText} does for its result). */
-export declare function decodeText(bytes: Uint8Array): string;
-/** The `[start, end)` gaps of `[0, queryLen)` NOT covered by `accounted` —
- *  the same union-of-spans reading think's grounding decider prices at PASS
- *  per byte, exposed here so a mechanism can turn it into a human label. */
-export declare function unexplainedSpans(queryLen: number, accounted: ReadonlyArray<[number, number]>): Array<[number, number]>;
-/** A human-readable label for the query bytes a mechanism's `accounted`
- *  spans leave unexplained — purely diagnostic (Task 2's negative evidence):
- *  it never changes a candidate's weight, only what the rationale trace
- *  says the mechanism left on the table. `""` when nothing is unexplained. */
-export declare function unexplainedLabel(query: Uint8Array, accounted: ReadonlyArray<[number, number]>): string;
-/** An open mechanism — the handle {@link Rationale.enter} returns.  Hold it for
- *  the duration of the mechanism and call {@link Scope.done} with the outputs
- *  when it finishes; that emits the step and pops the nesting. */
-export interface Scope {
-    /** The step index reserved for this mechanism at entry — pass it as an
-     *  explicit dependency of a later step that consumes this one's output. */
-    readonly index: number;
-    /** Close the mechanism: emit its step with these outputs and pop it off the
-     *  nesting stack.  Idempotent — a second call is ignored, so a `finally` that
-     *  closes after an early return is safe. */
-    done(outputs: RationaleItem[], note?: string): void;
-}
-/** The live tracer: a stack of open mechanisms over one {@link Mind.respond}.
- *
- *  Sema's inference is single-threaded and strictly sequential — every async
- *  step is awaited before the next begins, and `respond` holds no two thoughts
- *  at once — so a plain stack exactly tracks the current nesting: {@link enter}
- *  pushes, {@link Scope.done} pops, and {@link step} (a mechanism with no
- *  sub-steps) is the two fused.  The tracer never branches the control flow; it
- *  only records it. */
-export declare class Rationale {
-    private readonly sink;
-    private next;
-    /** Open mechanisms, outermost first.  Each frame remembers the last child it
-     *  has spawned so the next sibling can default its data-flow edge to it. */
-    private readonly stack;
-    /** The most recent step index emitted under each mechanism name — the handle
-     *  a later step uses to name an EARLIER mechanism as its data-flow producer
-     *  (e.g. cover depends on the latest recognise / computeExtensions).  One tracer is
-     *  built per response and inference is sequential, so "most recent" is exactly
-     *  "the one that produced the inputs I am about to consume". */
-    private readonly lastByName;
-    constructor(sink: InspectRationale);
-    /** The index of the most recent step with this mechanism name, or undefined if
-     *  none has run.  Used to wire an explicit producer edge into {@link
-     *  Scope.done} / {@link step}'s `deps`. */
-    lastIndex(name: string): number | undefined;
-    /** The mechanism names currently open, outermost → innermost. */
-    private path;
-    /** The default data-flow edge for a step entering now: the previous sibling
-     *  inside the current mechanism, else the enclosing mechanism, else nothing
-     *  (the root).  An explicit `deps` overrides this. */
-    private defaultDeps;
-    /** Reserve this step's index and register it as the current mechanism's most
-     *  recent child (so the NEXT sibling chains to it) and as the most recent step
-     *  of its own NAME (so a later mechanism can name it as a producer). */
-    private reserve;
-    private emit;
-    /** Enter a mechanism that has sub-steps.  Captures its inputs and the nesting
-     *  now; the matching {@link Scope.done} supplies the outputs when it finishes.
-     *  `deps` overrides the default data-flow edge (previous sibling / parent). */
-    enter(name: string, inputs: RationaleItem[], deps?: number[]): Scope;
-    /** Record a mechanism that has no sub-steps — its inputs and outputs are both
-     *  known at the call site.  Returns its index, for a later step to depend on. */
-    step(name: string, inputs: RationaleItem[], outputs: RationaleItem[], note?: string, deps?: number[]): number;
-}

package/dist/src/mind/rationale.js

@@ -1,162 +0,0 @@
-// rationale.ts — the inference, told as it happens.
-//
-// Sema's edge over a weight matrix is that every answer is a DERIVATION over
-// explicit facts, not a sample from an opaque distribution.  This module turns
-// that derivation into a stream a human (or a debugger) can read: as {@link
-// Mind.respond} thinks, each inference MECHANISM it runs emits a {@link
-// RationaleStep} the moment it completes — what it was handed, what it produced,
-// where it sits in the nesting of mechanisms, and which earlier steps fed it.
-//
-// Nothing here drives the inference; it only WITNESSES it.  When no
-// `inspectRationale` callback is supplied the tracer is never constructed and
-// the cost is exactly zero — every emit site in src/mind/mind.ts is guarded by `?.`, and
-// optional-chaining short-circuits its arguments, so the items are not even
-// built (see {@link Mind.respond}).
-//
-// The shape of a step mirrors how Sema reasons.  A mechanism is rarely a 1→1
-// map: {@link Mind.recognise} DECOMPOSES one query into many recognised forms;
-// the cover COMBINES many forms back into one answer; resonance fans one gist
-// out into a ranked list of hits.  So a step's `inputs` and `outputs` are each a
-// VECTOR — an ordered list of {@link RationaleItem}s, one per element — and the
-// fan-out / fan-in is visible in their lengths.
-/** Decode bytes to text for display, dropping the NUL padding the encoder uses
- *  (the same cleanup {@link Mind.respondText} does for its result). */
-export function decodeText(bytes) {
-    return new TextDecoder().decode(bytes.filter((b) => b !== 0x00));
-}
-/** The `[start, end)` gaps of `[0, queryLen)` NOT covered by `accounted` —
- *  the same union-of-spans reading think's grounding decider prices at PASS
- *  per byte, exposed here so a mechanism can turn it into a human label. */
-export function unexplainedSpans(queryLen, accounted) {
-    const sorted = accounted
-        .map(([s, e]) => [Math.max(0, s), Math.min(queryLen, e)])
-        .filter(([s, e]) => e > s)
-        .sort((a, b) => a[0] - b[0]);
-    const gaps = [];
-    let reach = 0;
-    for (const [s, e] of sorted) {
-        if (s > reach)
-            gaps.push([reach, s]);
-        if (e > reach)
-            reach = e;
-    }
-    if (reach < queryLen)
-        gaps.push([reach, queryLen]);
-    return gaps;
-}
-/** A human-readable label for the query bytes a mechanism's `accounted`
- *  spans leave unexplained — purely diagnostic (Task 2's negative evidence):
- *  it never changes a candidate's weight, only what the rationale trace
- *  says the mechanism left on the table. `""` when nothing is unexplained. */
-export function unexplainedLabel(query, accounted) {
-    const gaps = unexplainedSpans(query.length, accounted);
-    if (gaps.length === 0)
-        return "";
-    return gaps.map(([s, e]) => decodeText(query.subarray(s, e))).join(" … ");
-}
-/** The live tracer: a stack of open mechanisms over one {@link Mind.respond}.
- *
- *  Sema's inference is single-threaded and strictly sequential — every async
- *  step is awaited before the next begins, and `respond` holds no two thoughts
- *  at once — so a plain stack exactly tracks the current nesting: {@link enter}
- *  pushes, {@link Scope.done} pops, and {@link step} (a mechanism with no
- *  sub-steps) is the two fused.  The tracer never branches the control flow; it
- *  only records it. */
-export class Rationale {
-    sink;
-    next = 0;
-    /** Open mechanisms, outermost first.  Each frame remembers the last child it
-     *  has spawned so the next sibling can default its data-flow edge to it. */
-    stack = [];
-    /** The most recent step index emitted under each mechanism name — the handle
-     *  a later step uses to name an EARLIER mechanism as its data-flow producer
-     *  (e.g. cover depends on the latest recognise / computeExtensions).  One tracer is
-     *  built per response and inference is sequential, so "most recent" is exactly
-     *  "the one that produced the inputs I am about to consume". */
-    lastByName = new Map();
-    constructor(sink) {
-        this.sink = sink;
-    }
-    /** The index of the most recent step with this mechanism name, or undefined if
-     *  none has run.  Used to wire an explicit producer edge into {@link
-     *  Scope.done} / {@link step}'s `deps`. */
-    lastIndex(name) {
-        return this.lastByName.get(name);
-    }
-    /** The mechanism names currently open, outermost → innermost. */
-    path(leaf) {
-        const p = this.stack.map((f) => f.name);
-        p.push(leaf);
-        return p;
-    }
-    /** The default data-flow edge for a step entering now: the previous sibling
-     *  inside the current mechanism, else the enclosing mechanism, else nothing
-     *  (the root).  An explicit `deps` overrides this. */
-    defaultDeps() {
-        const top = this.stack[this.stack.length - 1];
-        if (!top)
-            return [];
-        return [top.lastChild ?? top.index];
-    }
-    /** Reserve this step's index and register it as the current mechanism's most
-     *  recent child (so the NEXT sibling chains to it) and as the most recent step
-     *  of its own NAME (so a later mechanism can name it as a producer). */
-    reserve(name) {
-        const index = this.next++;
-        const top = this.stack[this.stack.length - 1];
-        if (top)
-            top.lastChild = index;
-        this.lastByName.set(name, index);
-        return index;
-    }
-    emit(index, mechanism, inputs, outputs, deps, note) {
-        this.sink({
-            index,
-            mechanism,
-            parent: this.stack.length > 0
-                ? this.stack[this.stack.length - 1].index
-                : -1,
-            dependsOn: deps ?? this.defaultDeps(),
-            inputs,
-            outputs,
-            note,
-        });
-    }
-    /** Enter a mechanism that has sub-steps.  Captures its inputs and the nesting
-     *  now; the matching {@link Scope.done} supplies the outputs when it finishes.
-     *  `deps` overrides the default data-flow edge (previous sibling / parent). */
-    enter(name, inputs, deps) {
-        const mechanism = this.path(name);
-        const resolvedDeps = deps ?? this.defaultDeps();
-        const index = this.reserve(name);
-        this.stack.push({ index, name, lastChild: null });
-        let closed = false;
-        const emit = this.emit.bind(this);
-        const pop = () => {
-            // Pop down to and including this frame — tolerant of a sub-mechanism that
-            // forgot to close, so one missed `done` cannot desync the whole stack.
-            const at = this.stack.findIndex((f) => f.index === index);
-            if (at >= 0)
-                this.stack.length = at;
-        };
-        return {
-            index,
-            done: (outputs, note) => {
-                if (closed)
-                    return;
-                closed = true;
-                pop();
-                emit(index, mechanism, inputs, outputs, resolvedDeps, note);
-            },
-        };
-    }
-    /** Record a mechanism that has no sub-steps — its inputs and outputs are both
-     *  known at the call site.  Returns its index, for a later step to depend on. */
-    step(name, inputs, outputs, note, deps) {
-        const mechanism = this.path(name);
-        const resolvedDeps = deps ?? this.defaultDeps();
-        const index = this.reserve(name);
-        this.emit(index, mechanism, inputs, outputs, resolvedDeps, note);
-        return index;
-    }
-}

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

@@ -1,15 +0,0 @@
-import type { MindContext } from "./types.js";
-import type { Precomputed } from "./pipeline-mechanism.js";
-/** 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 declare function reason(ctx: MindContext, query: Uint8Array, answer: Uint8Array, preConsumed: ReadonlySet<number>, pre: Precomputed): Promise<Uint8Array>;
-/** 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 declare function fuseAttention(ctx: MindContext, query: Uint8Array, primary: Uint8Array, pre: Precomputed): Promise<Uint8Array>;

package/dist/src/mind/reasoning.js

@@ -1,162 +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";
-/** 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))) {
-                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))
-            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) {
-    // 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;
-    if (forest.length <= 1)
-        return primary;
-    const pieces = [
-        { start: forest[0].start, bytes: primary },
-    ];
-    const qv = pre.guide; // once, not per root
-    const t = ctx.trace?.enter("fuseAttention", [
-        rItem(primary, "primary"),
-        ...forest.slice(1).map((r) => rNode(ctx, r.anchor, "point", r.vote)),
-    ]);
-    for (const root of forest.slice(1)) {
-        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";