@hviana/sema 0.1.0

package/src/mind/primitives.ts

@@ -0,0 +1,201 @@
+// primitives.ts — Address + Read primitives (Section 1 of the mind).
+//
+//   Address  — bytes → node   (perceive, foldTree, resolve)
+//   Read     — node → bytes   (read)
+
+import { Vec } from "../vec.js";
+import { Sema, Space } from "../sema.js";
+import { Alphabet } from "../alphabet.js";
+import {
+  bytesToTree,
+  bytesToTreePyramid,
+  type FoldPyramid,
+  Grid,
+  gridToTree,
+  hilbertBytes,
+  stackGrids,
+} from "../geometry.js";
+import { ALL } from "./types.js";
+import type { Input, MindContext } 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. */
+function latin1Key(bytes: Uint8Array): string {
+  // 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. */
+export function perceive(
+  ctx: MindContext,
+  input: Input,
+  leafAt?: (i: number) => number | null,
+  lookup?: (ids: number[]) => number | null,
+): Sema {
+  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);
+        memo.set(key, tree);
+        return tree;
+      }
+      return bytesToTree(ctx.space, ctx.alphabet, bytes);
+    }
+    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 as Grid);
+}
+
+/** 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: MindContext, bytes: Uint8Array): Sema {
+  let prev: FoldPyramid | undefined;
+  // 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: MindContext, input: Input): Uint8Array {
+  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 as Grid);
+}
+
+/** Convenience: the gist vector of a byte span. */
+export function gistOf(ctx: MindContext, bytes: Uint8Array): Vec {
+  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: MindContext,
+  n: Sema,
+  start: number,
+  visit?: (n: Sema, start: number, end: number, node: number | null) => void,
+): { end: number; node: number | null } {
+  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);
+    return { end, node };
+  }
+  let pos = start;
+  let known = true;
+  const kids: number[] = [];
+  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);
+  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: MindContext, bytes: Uint8Array): number | null {
+  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: Sema,
+  start: number,
+  visit: (node: Sema, start: number, end: number) => void,
+): number {
+  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: MindContext,
+  id: number,
+  maxLen: number = ALL,
+): Uint8Array {
+  return ctx.store.bytesPrefix(id, maxLen);
+}

package/src/mind/rationale.ts

@@ -0,0 +1,275 @@
+// 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.
+
+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 function decodeText(bytes: Uint8Array): string {
+  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: number,
+  accounted: ReadonlyArray<[number, number]>,
+): Array<[number, number]> {
+  const sorted = accounted
+    .map(([s, e]) =>
+      [Math.max(0, s), Math.min(queryLen, e)] as [number, number]
+    )
+    .filter(([s, e]) => e > s)
+    .sort((a, b) => a[0] - b[0]);
+  const gaps: Array<[number, number]> = [];
+  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: Uint8Array,
+  accounted: ReadonlyArray<[number, number]>,
+): string {
+  const gaps = unexplainedSpans(query.length, accounted);
+  if (gaps.length === 0) return "";
+  return gaps.map(([s, e]) => decodeText(query.subarray(s, e))).join(" … ");
+}
+
+/** 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 class Rationale {
+  private 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. */
+  private readonly stack: Array<{
+    index: number;
+    name: string;
+    lastChild: number | null;
+  }> = [];
+  /** 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 = new Map<string, number>();
+
+  constructor(private readonly 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 {
+    return this.lastByName.get(name);
+  }
+
+  /** The mechanism names currently open, outermost → innermost. */
+  private path(leaf: string): string[] {
+    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. */
+  private defaultDeps(): number[] {
+    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). */
+  private reserve(name: string): number {
+    const index = this.next++;
+    const top = this.stack[this.stack.length - 1];
+    if (top) top.lastChild = index;
+    this.lastByName.set(name, index);
+    return index;
+  }
+
+  private emit(
+    index: number,
+    mechanism: string[],
+    inputs: RationaleItem[],
+    outputs: RationaleItem[],
+    deps: number[] | undefined,
+    note: string | undefined,
+  ): void {
+    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: string,
+    inputs: RationaleItem[],
+    deps?: number[],
+  ): Scope {
+    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: string,
+    inputs: RationaleItem[],
+    outputs: RationaleItem[],
+    note?: string,
+    deps?: number[],
+  ): number {
+    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/src/mind/reasoning.ts

@@ -0,0 +1,198 @@
+// 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 type { MindContext } from "./types.js";
+import { resolve } from "./primitives.js";
+import { corpusN } from "./traverse.js";
+import { follow, haloSiblings, project } from "./match.js";
+import { joinWithBridge, pivotInto } from "./resonance.js";
+import type { Precomputed } from "./pipeline-mechanism.js";
+import type { Rationale } from "./rationale.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: MindContext,
+  query: Uint8Array,
+  answer: Uint8Array,
+  preConsumed: ReadonlySet<number>,
+  pre: Precomputed,
+): Promise<Uint8Array> {
+  // 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<number>();
+  // 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: number | null) => {
+    if (id === null) return;
+    consumed.add(id);
+    for (const p of ctx.store.prevFirst(id, hubBound)) consumed.add(p);
+  };
+  const consumeAll = (id: number | null) => {
+    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: ReturnType<Rationale["enter"]> | undefined;
+  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: MindContext,
+  query: Uint8Array,
+  primary: Uint8Array,
+  pre: Precomputed,
+): Promise<Uint8Array> {
+  // 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: Array<{ start: number; bytes: Uint8Array }> = [
+    { 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";