@hviana/sema 0.1.0 → 0.1.2

package/dist/src/mind/rationale.js

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

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

@@ -0,0 +1,15 @@
+import type { MindContext } from "./types.js";
+import type { Precomputed } from "./pipeline-mechanism.js";
+/** Extend a grounded answer forward across facts (multi-hop reasoning).
+ *  Pivots on the longest unconsumed learnt context each answer contains,
+ *  then follows the pivot's continuation to the next fact.  Repeats up
+ *  to `cfg.recallQueryK` hops.  `preConsumed` carries node ids already
+ *  spoken for by the grounding stage (cover/extract/CAST).  `pre` is the
+ *  response's shared pre-computation — the post-grounding stages read the
+ *  same container the mechanisms did. */
+export declare function reason(ctx: MindContext, query: Uint8Array, answer: Uint8Array, preConsumed: ReadonlySet<number>, pre: Precomputed): Promise<Uint8Array>;
+/** Fuse independent points of attention into one answer (multi-topic).
+ *  When the consensus climb finds more than one dominant point, each
+ *  independent point grounds its own answer; they are bridged together
+ *  by any learnt connector the graph holds between them. */
+export declare function fuseAttention(ctx: MindContext, query: Uint8Array, primary: Uint8Array, pre: Precomputed): Promise<Uint8Array>;

package/dist/src/mind/reasoning.js

@@ -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,223 @@
+// 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 { foldTree, gistOf, perceive, resolve } from "./primitives.js";
+import { 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) {
+    // Per-response memo (see MindContext.recogniseMemo): think, articulate and
+    // the pre-consume pass all recognise the same byte objects; each repeat is
+    // O(n·maxGroup²) store probes.  Skipped while tracing so every call still
+    // emits its rationale step.
+    if (ctx.recogniseMemo && !ctx.trace) {
+        const hit = ctx.recogniseMemo.get(bytes);
+        if (hit !== undefined)
+            return hit;
+        const fresh = recogniseImpl(ctx, bytes);
+        ctx.recogniseMemo.set(bytes, 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;
+    };
+    const emit = (start, end, id) => {
+        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);
+        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;