@hviana/sema 0.1.9 → 0.2.1

package/dist/src/mind/reasoning.js

@@ -0,0 +1,162 @@
+// 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";

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

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

package/dist/src/mind/recognition.js

@@ -0,0 +1,246 @@
+// recognition.ts — Section 2 of the mind:
+// Address + Read over byte streams — decompose a query into its known forms.
+//
+//   recognise — structural + canonical decomposition into every stored form
+//               that leads somewhere (has a continuation edge or a halo).
+//   segment   — leaf-parent segmentation using the geometry's own groupings.
+import { rItem } from "./trace.js";
+import { canonResolve, foldTree, gistOf, latin1Key, perceive, resolve, } from "./primitives.js";
+import { atomIsHub, corpusN, leadsSomewhere } from "./traverse.js";
+import { chainReach, leafIdAt } from "./canonical.js";
+import { isChunk } from "../sema.js";
+/** Decompose a byte stream into every stored form that leads somewhere
+ *  (has a continuation edge or a halo).  Two complementary readings:
+ *
+ *   • structural — walk the query's own perceived tree, naming each subtree
+ *     by findLeaf at the leaves and findBranch above.  Catches every form
+ *     aligned to the query's segmentation.
+ *
+ *   • canonical — re-derive the store's segmentation directly: at each byte,
+ *     the longest known leaf, chained into flat branches.  Names forms the
+ *     query's own cut cannot, and records sub-leaf boundaries as `splits`.
+ *
+ *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
+export function recognise(ctx, bytes) {
+    // Content-keyed memo — works for both single-turn respond() and multi-turn
+    // respondTurn() (where the map persists across calls).  Skipped while
+    // tracing so every call still emits its rationale step.
+    if (ctx.recogniseMemo && !ctx.trace) {
+        const key = latin1Key(bytes);
+        const hit = ctx.recogniseMemo.get(key);
+        if (hit !== undefined)
+            return hit;
+        const fresh = recogniseImpl(ctx, bytes);
+        ctx.recogniseMemo.set(key, fresh);
+        return fresh;
+    }
+    return recogniseImpl(ctx, bytes);
+}
+function recogniseImpl(ctx, bytes) {
+    const store = ctx.store;
+    const sites = [];
+    const leaves = [];
+    const splits = new Set();
+    if (bytes.length === 0)
+        return { sites, leaves, splits };
+    // Span-resolve memo for THIS call: the structural pass (sub-runs inside
+    // leaf-parents) and the canonical pass (leaf-id chains) probe overlapping
+    // spans, and each resolve() is a full fold of the sub-span (fresh subarray
+    // objects — the per-response perceive memo cannot see them).  Keyed
+    // numerically by (start, end); resolve is pure and the store is read-only
+    // here, so a hit is exact.
+    const spanIds = new Map();
+    const resolveSpan = (start, end) => {
+        const key = start * (bytes.length + 1) + end;
+        let id = spanIds.get(key);
+        if (id === undefined) {
+            id = resolve(ctx, bytes.subarray(start, end));
+            spanIds.set(key, id);
+        }
+        return id;
+    };
+    // Byte atoms (implicit negative-id single-byte leaves) are admitted as
+    // recognised sites only while atoms can still DISCRIMINATE at this corpus
+    // scale (see {@link atomIsHub}).  On a small store a single-letter fact
+    // ("a" → "A") is genuine learnt content and its site is essential; on a
+    // large one every letter of every query would otherwise become a
+    // "recognised form" — the bridge then finds junction connectors between
+    // bare letters, cover follows edges hanging off them, and pure noise
+    // ("qq8f3kz9…") grounds to an arbitrary learnt sentence instead of
+    // silence.  Atoms stay available as leaves (PASS-carried literals) and
+    // through exact tier-0 resolution regardless.
+    const atomsAreHubs = atomIsHub(ctx, corpusN(ctx));
+    const emit = (start, end, id) => {
+        if (id < 0 && atomsAreHubs)
+            return;
+        if (leadsSomewhere(ctx, id)) {
+            sites.push({ start, end, payload: id });
+        }
+    };
+    // ── structural: the query's own perceived tree ──────────────────────
+    const starts = new Set();
+    starts.add(0);
+    foldTree(ctx, perceive(ctx, bytes), 0, (n, start, end, node) => {
+        if (n.kids === null) {
+            leaves.push({ start, end, bytes: n.leaf ?? new Uint8Array(0), node });
+        }
+        if (node !== null)
+            emit(start, end, node);
+        // Canonical fallback: a subtree whose exact content-addressed lookup
+        // missed may still be a stored form under the response's equivalence
+        // (case, width, whitespace — whatever the injected canonicalizer says).
+        // O(subtree bytes) per miss, memoised per response; a no-op when no
+        // canonicalizer was injected or the store has no canon index.
+        else if (end - start >= 2) {
+            const cid = canonResolve(ctx, bytes.subarray(start, end));
+            if (cid !== null)
+                emit(start, end, cid);
+        }
+        if (isChunk(n)) {
+            starts.add(start);
+            // Try every sub-span within this leaf-parent.
+            const leafOffsets = [];
+            let off = start;
+            for (const k of n.kids) {
+                leafOffsets.push(off);
+                off += k.leaf?.length ?? 0;
+            }
+            for (let i = 0; i < n.kids.length; i++) {
+                const subIds = [];
+                for (let j = i; j < n.kids.length; j++) {
+                    const kj = n.kids[j];
+                    if (kj.kids !== null || !kj.leaf)
+                        break;
+                    const lid = store.findLeaf(kj.leaf);
+                    if (lid === null)
+                        break;
+                    subIds.push(lid);
+                    const branch = store.findBranch(subIds);
+                    if (branch === null)
+                        continue;
+                    const subEnd = leafOffsets[j] + (kj.leaf?.length ?? 0);
+                    const resolved = resolveSpan(leafOffsets[i], subEnd);
+                    if (resolved !== null)
+                        emit(leafOffsets[i], subEnd, resolved);
+                }
+            }
+        }
+    });
+    // ── canonical: longest-known-leaf re-segmentation ──────────────────
+    const W = ctx.space.maxGroup;
+    const singleLeaf = new Array(bytes.length).fill(null);
+    for (let p = 0; p < bytes.length; p++) {
+        const id = leafIdAt(ctx, bytes, p);
+        if (id !== null)
+            singleLeaf[p] = { id, end: p + 1 };
+    }
+    const leafFrom = (p) => {
+        if (p >= bytes.length)
+            return null;
+        return singleLeaf[p];
+    };
+    const chunkEnd = new Uint32Array(bytes.length);
+    const sorted = [...starts].sort((a, b) => a - b);
+    for (let si = 0; si < sorted.length; si++) {
+        const chunkStart = sorted[si];
+        const chunkLimit = si + 1 < sorted.length ? sorted[si + 1] : bytes.length;
+        for (let p = chunkStart; p < chunkLimit; p++) {
+            chunkEnd[p] = chunkLimit;
+        }
+    }
+    const tryChain = (p, maxIds) => {
+        const first = leafFrom(p);
+        if (!first)
+            return;
+        emit(p, first.end, first.id);
+        const ids = [first.id];
+        let pos = first.end;
+        let prevId = null;
+        for (let depth = 1; pos < bytes.length && ids.length <= maxIds; depth++) {
+            const nx = leafFrom(pos);
+            if (!nx)
+                break;
+            ids.push(nx.id);
+            pos = nx.end;
+            if (store.findBranch(ids) === null)
+                continue;
+            const id = resolveSpan(p, pos);
+            if (id === null || id === prevId)
+                continue;
+            prevId = id;
+            emit(p, pos, id);
+        }
+    };
+    for (let p = 0; p < bytes.length; p++) {
+        if (starts.has(p)) {
+            tryChain(p, chainReach(W)); // boundary start — full reach
+        }
+        else {
+            const limit = chunkEnd[p] + W;
+            tryChain(p, Math.min(limit - p, chainReach(W)));
+        }
+    }
+    // ── splits: a form boundary that does not fall on a leaf edge ────────
+    const leafEdges = new Set([bytes.length]);
+    for (const lf of leaves)
+        leafEdges.add(lf.start);
+    for (const s of sites) {
+        if (!leafEdges.has(s.start))
+            splits.add(s.start);
+        if (!leafEdges.has(s.end))
+            splits.add(s.end);
+    }
+    ctx.trace?.step("recognise", [rItem(bytes, "query")], sites.map((s) => rItem(bytes.subarray(s.start, s.end), "form", s.payload, [
+        s.start,
+        s.end,
+    ])), `decompose the query into ${sites.length} learnt form(s) that lead somewhere` +
+        ` (over ${leaves.length} perceived leaves)`);
+    return { sites, leaves, splits };
+}
+/** Segment bytes using the geometry's own groupings — leaf-parent
+ *  nodes from the perceived tree, with consecutive bare leaves merged
+ *  into one segment.  Each segment's gist is perceived from its bytes
+ *  IN ISOLATION, so the same content has the same gist regardless of
+ *  where it appears. */
+export function segment(ctx, bytes) {
+    const tree = perceive(ctx, bytes);
+    const out = [];
+    let pendingStart = -1;
+    let pendingEnd = -1;
+    const flush = () => {
+        if (pendingStart >= 0 && pendingEnd > pendingStart) {
+            out.push({
+                start: pendingStart,
+                end: pendingEnd,
+                v: gistOf(ctx, bytes.subarray(pendingStart, pendingEnd)),
+            });
+        }
+        pendingStart = -1;
+        pendingEnd = -1;
+    };
+    const walk = (n, start) => {
+        if (n.kids === null) {
+            const end = start + (n.leaf?.length ?? 0);
+            if (pendingStart < 0)
+                pendingStart = start;
+            pendingEnd = end;
+            return end;
+        }
+        if (isChunk(n)) {
+            flush();
+            let end = start;
+            for (const c of n.kids)
+                end += c.leaf?.length ?? 0;
+            out.push({ start, end, v: gistOf(ctx, bytes.subarray(start, end)) });
+            return end;
+        }
+        flush();
+        let pos = start;
+        for (const c of n.kids)
+            pos = walk(c, pos);
+        return pos;
+    };
+    walk(tree, 0);
+    flush();
+    return out;
+}

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

@@ -0,0 +1,23 @@
+import type { MindContext } from "./types.js";
+/** The connector that belongs BETWEEN two adjacent results — the graded
+ *  junction ladder described in the module note above.  Returns null when
+ *  the graph holds no evidence that the two ever ran together. */
+export declare function bridge(ctx: MindContext, left: Uint8Array, right: Uint8Array, interiorAllowance?: number): Promise<Uint8Array | null>;
+/** Join two spans with the learnt connector between them, when one exists —
+ *  the composition step every out-of-search assembly (multi-topic fusion,
+ *  CAST's substitution and comparison) shares.  A miss joins the pieces BARE
+ *  and is never silent: it emits the same `bridgeMiss` trace step everywhere,
+ *  so a degraded join is visible in the rationale regardless of which
+ *  mechanism paid it.  (The in-search connector splice in graph-search.ts is
+ *  the same concept inside the deduction, where the join is a costed rule.) */
+export declare function joinWithBridge(ctx: MindContext, left: Uint8Array, right: Uint8Array): Promise<Uint8Array>;
+/** The pivot a produced answer bridges through: the longest UNCONSUMED learnt
+ *  CONTEXT (a node bearing a continuation edge) whose bytes `answer` literally
+ *  contains.  Candidates are gathered by resonating the answer's sub-regions
+ *  (breadth-first, leaves skipped, probes capped by branch count), then
+ *  confirmed by exact byte containment — a near-resonance alone never hops. */
+export declare function pivotInto(ctx: MindContext, answer: Uint8Array, consumed: ReadonlySet<number>): Promise<number | null>;
+export declare function meaningOf(ctx: MindContext, bytes: Uint8Array, anchors: ReadonlyArray<{
+    name: string;
+    form: Uint8Array;
+}>): Promise<string | null>;

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

@@ -0,0 +1,15 @@
+import type { MindContext } from "./types.js";
+import type { DerivationStep } from "./graph-search.js";
+import type { RationaleItem } from "./rationale.js";
+export declare function rItem(bytes: Uint8Array, role?: string, node?: number, span?: [number, number]): RationaleItem;
+export declare function rNode(ctx: MindContext, id: number, role?: string, score?: number): RationaleItem;
+export declare function rDeriv(ctx: MindContext, it: DerivationStep["conclusion"], role?: string): RationaleItem;
+/** The standard FALL-THROUGH closer every self-gating mechanism ends with:
+ *  close the open scope with no outputs and the reason, and return null so
+ *  the caller can `return fail("…")` in one expression.  `t` is the scope an
+ *  enclosing `ctx.trace?.enter(...)` returned (undefined when not tracing). */
+export declare function traceFail(t: {
+    done(outputs: RationaleItem[], note?: string): void;
+} | undefined): (note: string) => null;
+export declare const MOVE_NOTE: Record<string, string>;
+export declare function traceDerivation(ctx: MindContext, steps: ReadonlyArray<DerivationStep>): void;

package/dist/src/mind/trace.js

@@ -0,0 +1,73 @@
+// trace.ts — trace instrumentation + persistence (Section 9 of the mind).
+//
+//   rItem, rNode, rDeriv — build RationaleItems from bytes/nodes/derivations
+//   traceDerivation        — trace a full derivation proof tree
+//   MOVE_NOTE              — human-readable names for each derivation move
+import { read } from "./primitives.js";
+import { decodeText } from "./rationale.js";
+export function rItem(bytes, role, node, span) {
+    return {
+        text: decodeText(bytes),
+        role,
+        node: node ?? undefined,
+        span,
+    };
+}
+export function rNode(ctx, id, role, score) {
+    return {
+        text: decodeText(read(ctx, id)),
+        node: id,
+        role,
+        score,
+    };
+}
+export function rDeriv(ctx, it, role) {
+    const text = it.bytes
+        ? decodeText(it.bytes)
+        : it.node !== undefined
+            ? decodeText(read(ctx, it.node))
+            : it.kind === "cover"
+                ? `cover@${it.span[0]}`
+                : `[${it.span[0]},${it.span[1]})`;
+    return { text, role: role ?? it.kind, node: it.node, span: it.span };
+}
+/** The standard FALL-THROUGH closer every self-gating mechanism ends with:
+ *  close the open scope with no outputs and the reason, and return null so
+ *  the caller can `return fail("…")` in one expression.  `t` is the scope an
+ *  enclosing `ctx.trace?.enter(...)` returned (undefined when not tracing). */
+export function traceFail(t) {
+    return (note) => {
+        t?.done([], note);
+        return null;
+    };
+}
+export const MOVE_NOTE = {
+    "follow-edge": "follow a learned continuation edge — 'what follows what'",
+    "concept-hop": "jump a concept (halo) link — a synonym's edge",
+    "voice": "emit the asker's own wording for this form (articulation)",
+    "ground": "a chain reached its terminal answer",
+    "splice-connector": "splice a learnt connector between two rewrites",
+    "split": "cut a span at a sub-leaf form boundary so a form can be reached",
+    "fuse": "fuse adjacent fragments toward a deeper learned form",
+    "recompose": "recompose fused parts into a learned whole that leads on",
+    "bridge": "advance the cover frontier across this span",
+    "pool-vote": "pool independent regions' evidence for a shared anchor (sum, not shortest path)",
+    "axiom": "a seed: a perceived leaf, recognised form, or computed result",
+    "step": "a derivation step",
+};
+export function traceDerivation(ctx, steps) {
+    const t = ctx.trace;
+    if (!t)
+        return;
+    const indexOfOrder = new Map();
+    for (const s of steps) {
+        const note = MOVE_NOTE[s.move] ?? s.move;
+        const deps = s.producers
+            .map((o) => indexOfOrder.get(o))
+            .filter((x) => x !== undefined);
+        const premises = s.premises.map((p) => rDeriv(ctx, p));
+        const conclusion = [rDeriv(ctx, s.conclusion)];
+        const index = t.step(s.move, premises, conclusion, s.cost > 0 ? `${note} (cost ${s.cost})` : note, deps.length > 0 ? deps : undefined);
+        indexOfOrder.set(s.order, index);
+    }
+}

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

@@ -0,0 +1,113 @@
+import { Vec } from "../vec.js";
+import type { AncestorReach, MindContext } from "./types.js";
+/** Climb the structural DAG from a node to its edge-bearing ancestor contexts.
+ *  Ascent stops at hub nodes (parents > √N) — their reach is non-discriminative.
+ *  When the start node has no structural parents, climbs from containment parents
+ *  (sub-span flat branches inheriting their chunks' context).
+ *
+ *  `memo`, when given, caches whole climbs by start id for the duration of ONE
+ *  query (the store is read-only while a query is in flight, so a climb is a
+ *  pure function of the id).  The consensus pipeline climbs the SAME anchors
+ *  repeatedly — regions sharing a chunk, and canonicalChunkId probing each
+ *  chunk's prefixes — so without the memo every repeat re-pays the full
+ *  fan-out reads. */
+export declare function edgeAncestors(ctx: MindContext, id: number, contextCount: number, memo?: Map<number, AncestorReach>): AncestorReach;
+/** Convenience: forward edges of a node. */
+export declare function nextOf(ctx: MindContext, id: number): number[];
+/** Convenience: reverse edges of a node. */
+export declare function prevOf(ctx: MindContext, id: number): number[];
+/** The uniform-expectation floor on a byte atom's corpus commonality: N
+ *  learnt contexts, each at least one perception chunk of up to W of the 256
+ *  possible byte values, contain a given atom in ≥ N·W/256 contexts on
+ *  average.  An atom's TRUE containment is unmeasurable (atoms carry no
+ *  kid/contain links by construction), so this floor is the honest stand-in:
+ *  derived entirely from the corpus scale N, the perception window W, and
+ *  the alphabet size — never tuned. */
+export declare function atomReach(ctx: MindContext, contextCount: number): number;
+/** Whether a byte atom is a hub at this corpus scale — its commonality floor
+ *  {@link atomReach} exceeds the hub bound √N.  Below it (small stores) an
+ *  atom votes and is recognised exactly as any stored form; above it the
+ *  alphabet is scaffolding everywhere and abstains. */
+export declare function atomIsHub(ctx: MindContext, contextCount: number): boolean;
+/** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
+ *  The admission predicate recognition filters sites with (HOW_IT_WORKS
+ *  §15.3): a form that leads nowhere contributes nothing to any derivation.
+ *  Runs once per candidate span on the recognition hot path — `hasNext` is
+ *  cached per response (the same flat-branch ids are probed across prefix
+ *  variants by canonicalChunkId).  `hasHalo` is not cached: it's a single
+ *  indexed point probe per candidate, and the candidates that reach this
+ *  check have already been filtered by hasNext above in edgeAncestors. */
+export declare function leadsSomewhere(ctx: MindContext, id: number): boolean;
+/** The structural IDF read of ONE node: how many distinct learnt contexts
+ *  its containment/edge climb reaches, or Infinity when it reaches none or
+ *  saturates (no usable identity evidence).  The number every
+ *  discriminative-vs-scaffolding decision derives from — paired with the
+ *  half-dominance convention (geometry.dominates(reach, N)): content
+ *  reaching a corpus MINORITY of contexts discriminates (an entity, a
+ *  filler); content reaching a majority is frame scaffolding. */
+export declare function reachOf(ctx: MindContext, id: number, contextCount: number, memo?: Map<number, AncestorReach>): number;
+/** The corpus scale N — the count of DISTINCT learnt contexts, floored at 2
+ *  so its derived readings (ln N in the consensus floor, √N in the hub bound)
+ *  stay meaningful on a near-empty store.  The one definition every consumer
+ *  of "how big is this corpus?" reads. */
+export declare function corpusN(ctx: MindContext): number;
+/** The hub bound √N itself (≥ 2 always, since N is floored at 2) — for
+ *  consumers that pass it to the store's LIMITed reads instead of capping a
+ *  materialised list.  {@link hubCap} is the list-side reading of the same
+ *  convention. */
+export declare function hubBound(ctx: MindContext): number;
+/** Cap a candidate list at the hub bound √N (insertion order) — the ONE
+ *  fan-out convention every walk and disambiguation uses (see HOW_IT_WORKS
+ *  §8.6).  A node connected to more than √N others is a hub whose individual
+ *  connections carry ~no discriminative information; materialising or scoring
+ *  them all would make single decisions scale with the corpus. */
+export declare function hubCap<T>(ctx: MindContext, ids: readonly T[]): readonly T[];
+/** Whether `descendant` lies within `ancestor`'s subtree — a structural DAG
+ *  relation read off the hash-consed `kids` lists, by a bounded explicit-stack
+ *  descent.  Used by articulation to keep a voice from revoicing a fragment
+ *  OF that voice. */
+export declare function contains(ctx: MindContext, ancestor: number, descendant: number): boolean;
+/** The best-scoring item by cosine against `query`, among items scoring at
+ *  or above `threshold` — the shared arg-max every Pattern-A "which of these
+ *  resonates best" decision reduces to.  `strict` picks the tie-break a
+ *  caller needs: `true` keeps the first-seen leader on a tie (`>`), the
+ *  default lets a later equal score take it (`>=`). */
+export declare function argmaxBy<T>(items: Iterable<T>, scoreOf: (item: T) => number, threshold: number, strict?: boolean): {
+    item: T;
+    score: number;
+} | null;
+export declare function argmaxCosine<T>(query: Vec, items: Iterable<T>, vecOf: (item: T) => Vec | null | undefined, threshold: number, strict?: boolean): {
+    item: T;
+    score: number;
+} | null;
+/** The guided-or-first continuation of a node, as answer-shaped bytes source:
+ *  chooseNext under the response guide, falling back to the FIRST-inserted
+ *  edge — the one no-guide convention chooseNext, project() and the search's
+ *  formRules all share.  undefined when the node has no continuation. */
+export declare function guidedFirst(ctx: MindContext, id: number): number | undefined;
+export declare function guidedNext(ctx: MindContext, node: number): number | undefined;
+/** Disambiguate among a node's learnt continuations by distributional
+ *  support.  NOTE the `guide` contract: its VALUE is deliberately unused —
+ *  only its PRESENCE gates disambiguation (a null guide means no query is in
+ *  flight, so structural walkers keep plain first-edge behaviour).  The
+ *  gist-cosine of short answer candidates against a query guide is dominated
+ *  by accidental byte-pattern correlations, not semantic relatedness, so the
+ *  evidence consulted is structural: each candidate's reverse-edge support
+ *  count (see below).  Contrast {@link chooseAmong}, the REVERSE-direction
+ *  disambiguator, whose candidates are whole learnt contexts — long enough
+ *  that their perceived gists ARE semantically meaningful — and which
+ *  therefore scores by guide cosine.  The two directions consult different
+ *  halves of the evidence on purpose. */
+export declare function chooseNext(ctx: MindContext, id: number, guide?: Vec | null): number | undefined;
+/** The perceived gist of a candidate node, through the session gist cache.
+ *  Re-gisting a candidate is a full river fold of its bytes — the measured
+ *  recall bottleneck (a hub context offers up to √N continuations, EACH
+ *  re-perceived per pick).  A node's bytes are immutable and perception is
+ *  pure, so the cached gist is valid for the store's lifetime.  Exported for
+ *  every "score node ids against a guide" decision (chooseAmong here, the
+ *  bridge's junction pick) so they share ONE cache and one convention. */
+export declare function candidateGist(ctx: MindContext, c: number): Vec | null;
+export declare function chooseAmong(ctx: MindContext, candidates: readonly number[], guide: Vec): {
+    id: number;
+    score: number;
+};