@hviana/sema 0.1.0

package/src/mind/pipeline-mechanism.ts

@@ -0,0 +1,326 @@
+// pipeline-mechanism.ts — the uniform grounding-mechanism interface.
+//
+// Every grounding mechanism (CAST, confluence, cover, extraction, recall, ALU,
+// user extensions) implements this ONE interface.  The pipeline (think()) sees
+// a list of PipelineMechanism objects — it never imports a mechanism-specific
+// type and never has a special-case branch for any mechanism.
+//
+// The four constraints of the free-will architecture (§14.5):
+//   1. DECOUPLING — mechanisms import nothing from each other or from pipeline.
+//   2. DECLARED COMPETENCE — floor() returns null when impossible, a number when
+//      possible.  Binary, auditable, no learned scores.
+//   3. VISIBLE BUDGET — every mechanism carries its own caps internally (√N, k).
+//   4. TRAVELING EVIDENCE — run() returns MechanismResult with accounted, moves,
+//      and unexplained.  The pipeline computes the weight.
+
+import type { AncestorReach, MindContext, Recognition } from "./types.js";
+import type { AttentionRead } from "./types.js";
+import type { ComputedSpan } from "../extension.js";
+import type { Vec } from "../vec.js";
+import { windowIds } from "./canonical.js";
+import { read, resolve } from "./primitives.js";
+import { alignGraded, type GradedRun } from "./match.js";
+import { climbAttentionAll } from "./attention.js";
+import { skillExemplar } from "./mechanisms/extraction.js";
+
+// ── Precomputed ──────────────────────────────────────────────────────────────
+//
+// Precomputed is a LAZY container for structural analyses of the query — the
+// ONE place a response's shared evidence lives, for inter-mechanism exchange
+// and for analyses future mechanisms will want.  Eager fields (rec, computed,
+// guide) are populated by the pipeline before the mechanism loop; everything
+// expensive is a lazily-cached method that computes on first access.  A
+// mechanism that never asks for an analysis pays nothing for it; two
+// mechanisms asking for the same analysis pay once.
+//
+// This design serves THREE purposes:
+//   1. SHARING — when two mechanisms need the same analysis, it's computed once
+//      (even under trace, where the ctx-level memos are deliberately bypassed).
+//   2. EXTENSIBILITY — a new analysis is one method in one file.
+//   3. DECLARATIVE COST — a mechanism's floor() checks its cheap gates and the
+//      pipeline's `worthRunning` predicate BEFORE first-touching an expensive
+//      analysis, so lazy analyses are only ever computed for a mechanism that
+//      could still win.
+
+export class Precomputed {
+  /** The response's evidence-breadth constant: how many ranked candidates the
+   *  resonance probes, the weave alignment, and the climb all consider.
+   *  Derived once from config; every consumer reads it here. */
+  readonly k: number;
+
+  constructor(
+    readonly ctx: MindContext,
+    readonly query: Uint8Array,
+    /** Recognition result (structural + canonical). */
+    readonly rec: Recognition,
+    /** Computed spans from mechanisms that implement `parse()` (e.g. ALU). */
+    readonly computed: ComputedSpan[],
+    /** The query's gist — the response-wide disambiguation guide. */
+    readonly guide: Vec,
+  ) {
+    this.k = ctx.cfg.recallQueryK * 2;
+  }
+
+  // ── Cheap lazy analyses ───────────────────────────────────────────────
+
+  private _windows?: Map<number, number>;
+  /** Content-addressed W-window identities for every position in the query
+   *  (offset → node id).  O(|query|) probes. */
+  get queryWindows(): Map<number, number> {
+    return this._windows ??= windowIds(this.ctx, this.query);
+  }
+
+  private _resolved?: number | null;
+  /** The node id of the query itself, or null when it is not a stored form.
+   *  O(|query|) probes. */
+  get queryResolved(): number | null {
+    if (this._resolved === undefined) {
+      this._resolved = resolve(this.ctx, this.query);
+    }
+    return this._resolved;
+  }
+
+  private _anchorWindows = new Map<number, Map<number, number>>();
+  /** Content-addressed W-window identities of one anchor's own bytes
+   *  (offset → node id), memoised per anchor.  Confluence intersects these;
+   *  any future identity-based mechanism reads the same cache. */
+  windowsOf(anchor: number): Map<number, number> {
+    let w = this._anchorWindows.get(anchor);
+    if (w === undefined) {
+      w = windowIds(this.ctx, read(this.ctx, anchor));
+      this._anchorWindows.set(anchor, w);
+    }
+    return w;
+  }
+
+  /** Shared memo for {@link reachOf} (structural-IDF reads): a window's
+   *  ancestor reach is a pure function of the read-only store, so one
+   *  response-scoped memo serves every mechanism that prices commonality. */
+  readonly reachMemo = new Map<number, AncestorReach>();
+
+  // ── Expensive lazy analyses ───────────────────────────────────────────
+  //
+  // Async, cached-by-promise: the first caller starts the computation, every
+  // later caller (any mechanism, any phase) awaits the same promise.  A
+  // mechanism MUST check its cheap floor gates and the pipeline's
+  // `worthRunning` predicate before first-touching one of these.
+
+  private _attention?: Promise<AttentionRead>;
+  /** The full consensus climb (roots + ranked anchors) — the query-level
+   *  evidence CAST, confluence, extraction, recall's scaffolding tier, and
+   *  fusion all share.  Computed on first access; a query no mechanism
+   *  climbs for (e.g. one an extension decided outright) never pays for it. */
+  attention(): Promise<AttentionRead> {
+    return this._attention ??= climbAttentionAll(
+      this.ctx,
+      this.query,
+      this.k,
+    );
+  }
+
+  private _weave?: Promise<WeaveInfo>;
+  /** Result of {@link alignGraded} for the first k ranked anchors —
+   *  O(k · |query| · |ctx|).  Consumed by CAST; reusable by any future
+   *  mechanism doing analogical transfer. */
+  weave(): Promise<WeaveInfo> {
+    return this._weave ??= this.attention().then((climb) =>
+      computeWeave(this.ctx, this.query, this, climb)
+    );
+  }
+
+  /** Span-shaped classification of one ranked anchor, memoised per anchor id
+   *  so repeated calls (extraction's own early-exit scan, any future
+   *  template-based mechanism) never redo the work.  Deliberately NOT an
+   *  eager all-anchors map: `skillExemplar` is the expensive part of
+   *  extraction (capped fan-out reads plus an O(|ctx|) scan), and most
+   *  queries are answered by the FIRST ranked anchor that qualifies — paying
+   *  for every ranked anchor regardless of where the scan stops would turn
+   *  an early-exit lookup into full O(k) work on every query. */
+  private _spanShaped = new Map<number, Promise<SkillInfo | null>>();
+  spanShapedOf(anchor: number): Promise<SkillInfo | null> {
+    let p = this._spanShaped.get(anchor);
+    if (p === undefined) {
+      p = skillExemplar(this.ctx, anchor, this.guide);
+      this._spanShaped.set(anchor, p);
+    }
+    return p;
+  }
+
+  /** Every ranked anchor's classification at once, sharing the same
+   *  per-anchor cache as {@link spanShapedOf} — for a mechanism that
+   *  genuinely needs the full picture (not an early-exit scan).  Mixing
+   *  access patterns across mechanisms never duplicates work: whichever
+   *  anchors an early-exit consumer already asked for are reused here, and
+   *  whichever this computes first are reused by a later early-exit scan. */
+  async spanShapedAll(): Promise<Map<number, SkillInfo | null>> {
+    const { ranked } = await this.attention();
+    const out = new Map<number, SkillInfo | null>();
+    for (const cand of ranked) {
+      if (out.has(cand.anchor)) continue;
+      out.set(cand.anchor, await this.spanShapedOf(cand.anchor));
+    }
+    return out;
+  }
+}
+
+// ── WeaveInfo ────────────────────────────────────────────────────────────────
+
+/** The weave-local structural alignment, computed once and consumed by CAST
+ *  (and any future mechanism doing analogical transfer). */
+export interface WeaveInfo {
+  /** Per-anchor alignment: context bytes, vote weight, and graded runs. */
+  points: Array<{
+    anchor: number;
+    vote: number;
+    ctx: Uint8Array;
+    runs: GradedRun[];
+  }>;
+  /** Weighted depth at each query byte — sum of alignment weights.
+   *  `depth[i]` is the total evidence that byte i is shared among the
+   *  aligned structures. */
+  depth: Float64Array;
+}
+
+function computeWeave(
+  ctx: MindContext,
+  query: Uint8Array,
+  pre: Precomputed,
+  climb: AttentionRead,
+): WeaveInfo {
+  const quantum = ctx.space.maxGroup;
+  const { ranked } = climb;
+  const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
+  const depth = new Float64Array(query.length);
+  const points: WeaveInfo["points"] = [];
+
+  // WEAVE-SCALE anchors only: CAST transfers structure between things the
+  // QUERY weaves together — query-scale structures.  A context an order of
+  // magnitude beyond the query is not woven BY the query (the query can at
+  // most quote a fragment of it, and fragment-level evidence is exactly what
+  // recognition and the cover already handle); CAST's own comparison gate
+  // demands `ctx.length ≤ query.length` before it fires, and its
+  // substitution seats sit within a quantum of a context's start.  W is the
+  // perceptual quantum — the same scale multiplier the bridge's phrase-scale
+  // contract uses.  The prefix-capped read makes an oversized anchor cost a
+  // bounded read instead of reconstructing (and then canonically
+  // recognising) a corpus-sized deposit: profiled on a 17.7M-node store,
+  // uncapped weaves spent 5–8s per query recognising conversation-length
+  // anchors that could never form a weave point.
+  const capBytes = query.length * quantum;
+  for (const cand of rankedCapped) {
+    const ctxBytes = read(ctx, cand.anchor, capBytes + 1);
+    if (ctxBytes.length === 0 || ctxBytes.length > capBytes) continue;
+    const raw = alignGraded(ctx, query, ctxBytes, pre.rec.sites);
+    if (raw.length === 0) continue;
+    for (const r of raw) {
+      for (let i = r.qs; i < r.qe; i++) depth[i] += r.weight;
+    }
+    const free: GradedRun[] = [];
+    for (const r of raw) {
+      let { qs, qe, cs, weight } = r;
+      for (const p of points) {
+        for (const o of p.runs) {
+          if (qs >= qe) break;
+          if (o.qe <= qs || o.qs >= qe) continue;
+          const left = Math.max(0, o.qs - qs);
+          const right = Math.max(0, qe - o.qe);
+          if (left >= right) qe = qs + left;
+          else {
+            cs += qe - right - qs;
+            qs = qe - right;
+          }
+        }
+      }
+      if (qe - qs >= Math.min(quantum, ctxBytes.length)) {
+        free.push({ qs, qe, cs, weight });
+      }
+    }
+    if (free.length > 0) {
+      points.push({
+        anchor: cand.anchor,
+        vote: cand.vote,
+        ctx: ctxBytes,
+        runs: free,
+      });
+    }
+  }
+  return { points, depth };
+}
+
+// ── SkillInfo ────────────────────────────────────────────────────────────────
+
+/** Span-shaped classification of one anchor — the structural information
+ *  extraction uses to decide whether a learned fact can serve as a template
+ *  for reading an analogous span out of the query. */
+export interface SkillInfo {
+  contextBytes: Uint8Array;
+  answerBytes: Uint8Array;
+}
+
+// ── MechanismResult ──────────────────────────────────────────────────────────
+
+/** Raw result from a mechanism's `run()`.  The pipeline computes the weight
+ *  from `moves` + `PASS * unaccounted(accounted)` — the mechanism does not
+ *  know about the cost ladder.
+ *
+ *  When `weight` is present, the pipeline uses it directly instead of
+ *  computing `weigh(accounted, moves)`.  This is for mechanisms whose cost
+ *  is derived externally (e.g. cover: the A*LD derivation's g-value). */
+export interface MechanismResult {
+  bytes: Uint8Array;
+  accounted: Array<[number, number]>;
+  moves: number;
+  used?: ReadonlySet<number>;
+  unexplained: string;
+  /** Explicit weight override.  When absent, weight = moves + PASS·unaccounted. */
+  weight?: number;
+  /** Override the mechanism's default provenance for this result.
+   *  When absent, the pipeline uses `mech.provenance`. */
+  provenance?: string;
+}
+
+// ── PipelineMechanism ────────────────────────────────────────────────────────
+
+export interface PipelineMechanism {
+  /** Stable identifier for trace/debug. */
+  readonly name: string;
+
+  /** Which provenance tag the pipeline attaches to this mechanism's answers. */
+  readonly provenance: string;
+
+  /** Parse authoritative spans BEFORE the grounding loop.
+   *  Only needed by computational mechanisms (e.g. ALU).  Results from ALL
+   *  mechanisms that implement this are collected into `Precomputed.computed`
+   *  before any `floor()` or `run()` is called. */
+  parse?(query: Uint8Array): Promise<ComputedSpan[]>;
+
+  /** Admissible lower bound on this mechanism's weight.
+   *  Returns `null` when the mechanism structurally cannot fire.
+   *
+   *  `worthRunning(cheapFloor)` reports whether the CURRENT incumbent
+   *  (established by mechanisms that already ran this response, cover being
+   *  first — see `defaultMechanisms`) could still be beaten by a floor no
+   *  tighter than `cheapFloor`.  THE INVESTMENT DISCIPLINE: before
+   *  first-touching an expensive shared analysis (`pre.attention()`,
+   *  `pre.weave()`, …), check `worthRunning(bound)` with this mechanism's
+   *  cheapest possible bound — and when it fails, RETURN THE BOUND rather
+   *  than null.  The bound is still admissible (it never overstates cost),
+   *  the pipeline's own check then prunes `run()` and records the truthful
+   *  "cannot beat incumbent" trace note, and no analysis was computed just
+   *  to be discarded.  This is uniform: no mechanism asks what produced the
+   *  incumbent — a computed extension result and an ordinary cheap cover
+   *  prune the same way. */
+  floor(
+    ctx: MindContext,
+    query: Uint8Array,
+    pre: Precomputed,
+    worthRunning: (floor: number) => boolean,
+  ): Promise<number | null>;
+
+  /** Produce candidate answers. */
+  run(
+    ctx: MindContext,
+    query: Uint8Array,
+    pre: Precomputed,
+  ): Promise<MechanismResult[]>;
+}

package/src/mind/pipeline.ts

@@ -0,0 +1,300 @@
+// pipeline.ts — the think pipeline (Section 5 of the mind).
+//
+// think() is the whole file's job: one lightest-derivation choice among
+// UNIFORM mechanisms.  The pipeline sees mechanisms through the
+// PipelineMechanism interface only — it never imports a mechanism-specific
+// type and never has a special-case branch for any mechanism.  Adding a
+// mechanism means registering one object; removing one means dropping it
+// from the list.  The mechanisms themselves live in mechanisms/ (one file
+// each); the shared pre-computation they exchange lives in Precomputed
+// (pipeline-mechanism.ts).
+
+import type { MindContext } from "./types.js";
+import { PASS, STEP } from "./graph-search.js";
+import type { ComputedSpan } from "../extension.js";
+import { gistOf, resolve } from "./primitives.js";
+import { recognise } from "./recognition.js";
+import { fuseAttention, reason } from "./reasoning.js";
+import { unexplainedSpans } from "./rationale.js";
+import { rItem } from "./trace.js";
+import { type PipelineMechanism, Precomputed } from "./pipeline-mechanism.js";
+import { coverMechanism } from "./mechanisms/cover.js";
+import { castMechanism } from "./mechanisms/cast.js";
+import { confluenceMechanism } from "./mechanisms/confluence.js";
+import { extractionMechanism } from "./mechanisms/extraction.js";
+import { recallMechanism } from "./mechanisms/recall.js";
+
+// Re-exports: cover's pre-resolution helpers and the ALU adapter kept
+// importable from the pipeline module (their historical home).
+export { resolveConcepts, resolveConnectors } from "./mechanisms/cover.js";
+export { aluToMechanism } from "./mechanisms/alu.js";
+
+// ── Extension dispatch (pre-loop parse) ─────────────────────────────────────
+
+async function collectComputed(
+  mechanisms: readonly PipelineMechanism[],
+  query: Uint8Array,
+): Promise<ComputedSpan[]> {
+  const out: ComputedSpan[] = [];
+  for (const m of mechanisms) {
+    if (m.parse) out.push(...await m.parse(query));
+  }
+  return out;
+}
+
+// ── Built-in mechanisms ─────────────────────────────────────────────────────
+
+// ORDER MATTERS, but only through the uniform floor/worthRunning pruning —
+// no mechanism is special-cased.  Cover runs FIRST: when a computed
+// extension result (e.g. ALU) exists, cover masks it in at near-zero cost
+// (see mechanisms/cover.ts), which becomes `best` before any other mechanism
+// invests in its own precomputation.  CAST's and confluence's floors (2*STEP,
+// 3*STEP) then fail `worthRunning` and are skipped by the SAME admissible-
+// floor pruning every mechanism is already subject to — not by asking
+// "is this an extension?".  Grade TIES keep the earlier candidate, so this
+// order is also the tie-break priority: cover, cast, confluence, extraction,
+// recall.
+export const defaultMechanisms: PipelineMechanism[] = [
+  coverMechanism,
+  castMechanism,
+  confluenceMechanism,
+  extractionMechanism,
+  recallMechanism,
+];
+
+// ── think — the main inference pipeline ─────────────────────────────────────
+
+export type Provenance =
+  | "cast"
+  | "join"
+  | "cover"
+  | "extract"
+  | "recall"
+  | "recall-echo";
+
+export interface Thought {
+  bytes: Uint8Array;
+  provenance: Provenance;
+}
+
+/** Think: a single lightest-derivation exploration of the Sema graph.
+ *
+ *  Every answer travels the same path:
+ *    1. Pre-computation — recognise, extension parse, guide; everything
+ *       expensive stays lazy on Precomputed until a mechanism asks.
+ *    2. Grounding — every mechanism yields candidates weighed in the one
+ *       cost ladder; the lightest grounding derivation wins.
+ *    3. Post-grounding — diagnostics (narrowDecision, thinGrounding),
+ *       reasoning (multi-hop), fusion (multi-topic). */
+export async function think(
+  ctx: MindContext,
+  query: Uint8Array,
+  mechs?: readonly PipelineMechanism[],
+): Promise<Thought | null> {
+  if (query.length === 0) return null;
+
+  ctx._edgeGuide = gistOf(ctx, query);
+  ctx._edgeChoice.clear();
+
+  const t = ctx.trace?.enter("think", [rItem(query, "query")]);
+  const done = (answer: Uint8Array | null, note: string) => {
+    t?.done(
+      answer
+        ? [rItem(answer, "answer", resolve(ctx, answer) ?? undefined)]
+        : [],
+      note,
+    );
+    return answer;
+  };
+
+  // ── Pre-computation ──────────────────────────────────────────────────
+  const mechanisms = mechs ?? defaultMechanisms;
+  const rec = recognise(ctx, query);
+
+  // Phase 1: collect computed spans from mechanisms that implement parse()
+  const computed = await collectComputed(mechanisms, query);
+
+  if (computed.length > 0) {
+    ctx.trace?.step(
+      "computeExtensions",
+      [rItem(query, "query")],
+      computed.map((u) =>
+        rItem(query.subarray(u.i, u.j), "operand", undefined, [u.i, u.j])
+      ),
+      `extensions recognised and evaluated ${computed.length} computation(s)`,
+    );
+    for (const u of computed) {
+      ctx.trace?.step(
+        "evalComputation",
+        [rItem(query.subarray(u.i, u.j), "expression", undefined, [u.i, u.j])],
+        [rItem(u.bytes, "result", resolve(ctx, u.bytes) ?? undefined)],
+        "evaluate the recognised operation to its authoritative result",
+      );
+    }
+  }
+
+  // Phase 2: the shared pre-computation container.  Eager fields only
+  // (recognition, computed spans, guide) — every expensive analysis
+  // (consensus climb, weave, span-shape classification) is a lazily-cached
+  // method on Precomputed, first-touched by whichever mechanism's floor
+  // survives its cheap gates and the worthRunning check.  A query no
+  // mechanism climbs for (e.g. one an extension decided) never climbs.
+  const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
+
+  // ── Grounding: ONE lightest-derivation choice among the mechanisms ────
+
+  interface Candidate {
+    bytes: Uint8Array;
+    provenance: string;
+    weight: number;
+    used?: ReadonlySet<number>;
+    accounted: ReadonlyArray<[number, number]>;
+    unexplained: string;
+  }
+  const grade = (w: number) => Math.floor(w / STEP);
+  const unaccounted = (spans: ReadonlyArray<[number, number]>): number =>
+    unexplainedSpans(query.length, spans)
+      .reduce((sum, [s, e]) => sum + (e - s), 0);
+  const weigh = (
+    accounted: ReadonlyArray<[number, number]>,
+    moves: number,
+  ): number => moves + PASS * unaccounted(accounted);
+
+  const candidates: Candidate[] = [];
+  let best: Candidate | null = null;
+  const consider = (c: Candidate) => {
+    if (c.bytes.length === 0) return;
+    candidates.push(c);
+    if (best === null || grade(c.weight) < grade(best.weight)) best = c;
+  };
+  const worthRunning = (floor: number) =>
+    best === null || grade(floor) < grade(best.weight);
+
+  // Phase 3: grounding loop
+  for (const mech of mechanisms) {
+    const floor = await mech.floor(ctx, query, pre, worthRunning);
+    if (floor === null) {
+      ctx.trace?.step(
+        "skipMechanism",
+        [],
+        [],
+        `${mech.name} skipped — structural precondition failed`,
+      );
+      continue;
+    }
+    if (!worthRunning(floor)) {
+      ctx.trace?.step(
+        "skipMechanism",
+        [],
+        [],
+        `${mech.name} skipped — floor ${floor} cannot beat incumbent (grade ${
+          grade(best!.weight)
+        })`,
+      );
+      continue;
+    }
+    const results = await mech.run(ctx, query, pre);
+    for (const r of results) {
+      const weight = r.weight ?? weigh(r.accounted, r.moves);
+      consider({
+        bytes: r.bytes,
+        provenance: r.provenance ?? mech.provenance,
+        weight,
+        used: r.used,
+        accounted: r.accounted,
+        unexplained: r.unexplained,
+      });
+    }
+  }
+
+  // (TS cannot see the closure assignments into `best` and narrows it to its
+  // initial null, so the read-back needs the assertion.)
+  const decided = best as Candidate | null;
+  if (candidates.length > 1) {
+    ctx.trace?.step(
+      "decideGrounding",
+      candidates.map((c) =>
+        rItem(
+          c.bytes,
+          `${c.provenance} (weight ${c.weight.toFixed(3)}${
+            c.unexplained ? `, unexplained: "${c.unexplained}"` : ""
+          })`,
+        )
+      ),
+      decided ? [rItem(decided.bytes, decided.provenance)] : [],
+      "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder",
+    );
+    if (decided !== null) {
+      let runnerUp: Candidate | null = null;
+      for (const c of candidates) {
+        if (c === decided) continue;
+        if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
+          runnerUp = c;
+        }
+      }
+      if (runnerUp !== null) {
+        const margin = grade(runnerUp.weight) - grade(decided.weight);
+        if (margin <= 1) {
+          ctx.trace?.step(
+            "narrowDecision",
+            [
+              rItem(
+                decided.bytes,
+                `${decided.provenance} (weight ${decided.weight.toFixed(3)})`,
+              ),
+            ],
+            [
+              rItem(
+                runnerUp.bytes,
+                `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`,
+              ),
+            ],
+            `margin ${margin} grade-unit(s) — the decision could change with one more training fact`,
+          );
+        }
+      }
+    }
+  }
+
+  if (decided === null) {
+    done(null, "no mechanism grounded an answer");
+    return null;
+  }
+
+  // Honesty density
+  {
+    const covered = query.length - unaccounted(decided.accounted);
+    const density = query.length > 0 ? covered / query.length : 1;
+    const thinBar = 1 / ctx.space.maxGroup;
+    if (density < thinBar) {
+      ctx.trace?.step(
+        "thinGrounding",
+        [rItem(decided.bytes, decided.provenance)],
+        [],
+        `grounded but thin — density ${density.toFixed(3)} is below 1/W (${
+          thinBar.toFixed(3)
+        })`,
+      );
+    }
+  }
+  const answer: Uint8Array = decided.bytes;
+  const provenance = decided.provenance as Provenance;
+  const castUsed: ReadonlySet<number> = decided.used ?? new Set();
+
+  // ── Post-grounding, gated by provenance ──────────────────────────────
+  const preConsumed = provenance === "cast" || provenance === "join"
+    ? castUsed
+    : provenance === "recall" || provenance === "recall-echo"
+    ? new Set<number>()
+    : new Set(recognise(ctx, answer).sites.map((s) => s.payload));
+  const reasoned = await reason(ctx, query, answer, preConsumed, pre);
+  const fused = provenance === "recall" || provenance === "recall-echo"
+    ? await fuseAttention(ctx, query, reasoned, pre)
+    : reasoned;
+
+  done(
+    fused,
+    "grounded, reasoned forward, fused across points of attention",
+  );
+  return { bytes: fused, provenance };
+}