@hviana/sema 0.2.6 → 0.2.7

package/dist/src/mind/primitives.js

@@ -0,0 +1,287 @@
+// 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, stablePrefixFoldIncremental, stackGrids, } from "../geometry.js";
+import { canonHash } from "../canon.js";
+import { bytesEqual } from "../bytes.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.  A FIRST-SEEN input takes the PLAIN fold
+ *  (bit-identical to inference perception of a standalone query — that
+ *  structural train/inference agreement is load-bearing for exact recall),
+ *  computed incrementally via the fold's level pyramid
+ *  ({@link bytesToTreePyramid}).  An input that EXTENDS a previously
+ *  deposited one is a conversation context grown by one turn — the cached
+ *  prefix length IS the turn boundary (derived from the deposit sequence
+ *  itself, never from content conventions) — and takes the STABLE-PREFIX
+ *  fold over the accumulated boundaries, bit-identical to the boundary
+ *  fold query-time conversation perception uses, so the trained context
+ *  node and the query's context subtree are the SAME node.  Segment folds
+ *  reuse across deposits ({@link stablePrefixFoldIncremental}) — O(turn)
+ *  instead of O(context) per turn.  The fold state is purely a cache; the
+ *  boundary accumulation is what an evicted chain loses (falling back to
+ *  the plain fold, the pre-boundary shape — a warm replay restores it). */
+export function perceiveDeposit(ctx, bytes, conversational = false) {
+    let prev;
+    let prefixLen = 0;
+    // Cache consult (both boundary lookup and stable-prefix reuse) is scoped
+    // to conversational deposits only — a bare, unrelated fact whose bytes
+    // happen to extend an earlier deposit is NOT a conversation turn, and
+    // must keep the plain fold so it shares structure with ITS OWN prior
+    // deposits, not fragment against a coincidental byte-prefix.
+    if (conversational) {
+        // 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)));
+            // The suffix must bytes-equal the hit's OWN recorded continuation —
+            // proof this deposit is that turn's actual next turn, not a fact
+            // that coincidentally shares its byte prefix.
+            if (hit !== undefined && hit.nextBytes !== undefined &&
+                bytesEqual(hit.nextBytes, bytes.subarray(L))) {
+                prev = hit;
+                prefixLen = L;
+                break;
+            }
+        }
+    }
+    let tree;
+    let entry;
+    if (prev !== undefined) {
+        const boundaries = [...prev.boundaries, prefixLen];
+        const folded = stablePrefixFoldIncremental(ctx.space, ctx.alphabet, bytes, boundaries, prev.stable);
+        tree = folded.tree;
+        entry = { boundaries, stable: folded.fold };
+    }
+    else {
+        const plain = bytesToTreePyramid(ctx.space, ctx.alphabet, bytes);
+        tree = plain.tree;
+        entry = { boundaries: [], pyramid: plain.pyramid };
+    }
+    // Only a conversational deposit writes the cache too — otherwise a bare
+    // fact's plain fold could later be misread as a conversation's turn-zero
+    // boundary by an unrelated conversational deposit that happens to extend
+    // its bytes.
+    if (conversational && 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), entry);
+        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;
+    const exact = foldTree(ctx, perceive(ctx, bytes), 0).node;
+    if (exact !== null)
+        return exact;
+    return canonResolve(ctx, bytes);
+}
+/** Equivalence-class resolution: when the exact content-addressed lookup
+ *  misses, find a stored node whose CANONICAL key equals the span's — the
+ *  store's canon index proposes candidates by key hash, and each is verified
+ *  by re-canonicalizing its bytes (hash-then-verify, like every content
+ *  lookup).  Among verified candidates, one that leads somewhere (has a
+ *  continuation edge) is preferred; ties break to the lowest id — a corpus
+ *  property, not a seed property.  Null when the response carries no
+ *  canonicalizer, the store has no canon index, or nothing verifies. */
+export function canonResolve(ctx, bytes) {
+    const canon = ctx.canon;
+    const store = ctx.store;
+    if (canon === null || !store.canonFind)
+        return null;
+    if (bytes.length < 2)
+        return null;
+    const memo = ctx.canonMemo;
+    const memoKey = memo ? latin1Key(bytes) : "";
+    if (memo) {
+        const hit = memo.get(memoKey);
+        if (hit !== undefined)
+            return hit;
+    }
+    const set = (v) => {
+        memo?.set(memoKey, v);
+        return v;
+    };
+    const key = canon(bytes);
+    if (key.length === 0)
+        return set(null);
+    // A stored form that IS canonical is not in the index (buildCanonIndex
+    // skips identity rows) — the exact content-addressed lookup of the
+    // canonical bytes finds it directly.
+    if (key.length !== bytes.length || !bytesEqual(key, bytes)) {
+        const direct = foldTree(ctx, perceive(ctx, key), 0).node;
+        if (direct !== null)
+            return set(direct);
+    }
+    const candidates = store.canonFind(canonHash(key));
+    if (candidates.length === 0)
+        return set(null);
+    let best = null;
+    let bestLeads = false;
+    for (const id of candidates) {
+        const bytesOf = read(ctx, id);
+        const stored = canon(bytesOf);
+        if (stored.length !== key.length || !bytesEqual(stored, key))
+            continue;
+        // The index stores FLAT content twins; the id the exact path would have
+        // resolved for these bytes is their FOLD — the deposit-shaped node that
+        // carries the edges and halos.  Re-folding the candidate's bytes lands
+        // on exactly the node the canonical-case query would have found.
+        const folded = foldTree(ctx, perceive(ctx, bytesOf), 0).node;
+        const use = folded ?? id;
+        const leads = store.hasNext(use) || store.haloMass(use) > 0;
+        if (best === null || (leads && !bestLeads) ||
+            (leads === bestLeads && use < best)) {
+            best = use;
+            bestLeads = leads;
+        }
+    }
+    return set(best);
+}
+/** 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

@@ -0,0 +1,139 @@
+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;
+    /** Optional structured payload — a mechanism-specific, plain-serialisable
+     *  shape (no Map/Set/vectors/mutable internals) that carries more than the
+     *  human-readable `note` can, for a debugger or downstream tool to consume
+     *  programmatically.  Never read by inference; purely additive. */
+    data?: unknown;
+}
+/** 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, data?: unknown): 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[], data?: unknown): number;
+}

package/dist/src/mind/rationale.js

@@ -0,0 +1,163 @@
+// 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, data) {
+        this.sink({
+            index,
+            mechanism,
+            parent: this.stack.length > 0
+                ? this.stack[this.stack.length - 1].index
+                : -1,
+            dependsOn: deps ?? this.defaultDeps(),
+            inputs,
+            outputs,
+            note,
+            data,
+        });
+    }
+    /** 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, data) => {
+                if (closed)
+                    return;
+                closed = true;
+                pop();
+                emit(index, mechanism, inputs, outputs, resolvedDeps, note, data);
+            },
+        };
+    }
+    /** 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, data) {
+        const mechanism = this.path(name);
+        const resolvedDeps = deps ?? this.defaultDeps();
+        const index = this.reserve(name);
+        this.emit(index, mechanism, inputs, outputs, resolvedDeps, note, data);
+        return index;
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { MindContext } from "./types.js";
+import type { Precomputed } from "./pipeline-mechanism.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 declare function restatesQuery(query: Uint8Array, bytes: Uint8Array): boolean;
+/** 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, 
+/** 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?: boolean): Promise<Uint8Array>;