@hviana/sema 0.4.0 → 0.4.2

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

@@ -1,139 +0,0 @@
-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

@@ -1,163 +0,0 @@
-// 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

@@ -1,40 +0,0 @@
-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, 
-/** The query spans `primary`'s own grounding stands on — used ONLY to place
- *  primary in the fused reading order (see below).  Resolved by the caller,
- *  which is the layer that knows how a given grounding records its evidence;
- *  fuseAttention just reads a position from it.  Empty or absent preserves
- *  the original behaviour exactly. */
-primarySpans?: ReadonlyArray<readonly [number, number]>): Promise<Uint8Array>;

package/dist/src/mind/reasoning.js

@@ -1,272 +0,0 @@
-// 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 { hubBound } from "./traverse.js";
-import { follow, haloSiblings, project } from "./match.js";
-import { joinWithBridge, pivotInto } from "./resonance.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 function restatesQuery(query, bytes) {
-    return bytes.length < query.length && indexOf(query, bytes, 0) >= 0;
-}
-/** 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 bound = hubBound(ctx);
-    const consumeNode = (id) => {
-        if (id === null)
-            return;
-        consumed.add(id);
-        for (const p of ctx.store.prevFirst(id, bound))
-            consumed.add(p);
-    };
-    const consumeAll = (id) => {
-        if (id === null)
-            return;
-        consumeNode(id);
-        for (const n of ctx.store.nextFirst(id, bound))
-            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, bound).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)) &&
-                !restatesQuery(query, fwd)) {
-                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) || restatesQuery(query, fc))
-            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, 
-/** 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 = false, 
-/** The query spans `primary`'s own grounding stands on — used ONLY to place
- *  primary in the fused reading order (see below).  Resolved by the caller,
- *  which is the layer that knows how a given grounding records its evidence;
- *  fuseAttention just reads a position from it.  Empty or absent preserves
- *  the original behaviour exactly. */
-primarySpans = []) {
-    // 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;
-    // A LONE root is ordinarily primary's own source — nothing to fuse.  But
-    // when primary is unclimbed, the lone root was never checked against
-    // anything: it is admitted by commitVotes unconditionally, so it may be
-    // genuine consensus (Attention.breadth dominates — most of the query's
-    // OWN regions corroborate it) or a coincidental echo (breadth does not
-    // dominate — see test/35-attention-confidence).  breadth is the SCALE-
-    // INVARIANT read of exactly this question: the raw IDF vote cannot serve
-    // here, since it is an absolute ln(N)-scaled quantity (a genuine root on
-    // a large store can score BELOW its own floor while a coincidental echo
-    // on a small one scores comfortably above its own, smaller, floor).
-    const lonePromotes = unclimbed && forest.length === 1 &&
-        forest[0].breadth > 0.5;
-    if (forest.length === 0 || (forest.length <= 1 && !lonePromotes)) {
-        return primary;
-    }
-    // WHERE THE QUERY ASKED FOR IT.  The sort below orders the fused pieces by
-    // query position, which is the whole point of the `start` field: a
-    // multi-topic answer should read in the order the question posed its
-    // topics.  Every ROOT carries its own start.  `primary` did not — it was
-    // given forest[0].start, the FIRST attention root's position, which is
-    // primary's own source only when primary happens to come from that root.
-    // When it does not, primary is sorted to a position it never occupied.
-    //
-    // Observed live: "What is the capital of France? And what is 2 + 2?"
-    // answered "4The capital city of France is Paris." — the ALU result, whose
-    // evidence is the "2 + 2" span near the END of the query, inherited the
-    // France root's start of 0 and sorted ahead of the France answer.  Both
-    // pieces were right; only the order was.
-    //
-    // primary's own position is the earliest query byte its grounding stands
-    // on.  `accounted` is the cost-ladder read of that and is authoritative
-    // when non-empty; when it is empty the grounding is a pure COMPUTATION,
-    // whose evidence is its computed span — the same cost-ladder-vs-coverage
-    // distinction think() already draws for the fusion remainder ("`accounted`
-    // alone undercounts this ... cover prices its computed spans at near-zero
-    // and deliberately leaves them out"), read here for position instead of
-    // for coverage.  With neither, nothing is known and the old behaviour
-    // (forest[0].start) stands.
-    const primaryStart = primarySpans.length > 0
-        ? primarySpans.reduce((m, [s]) => Math.min(m, s), Infinity)
-        : forest[0].start;
-    const pieces = [
-        { start: primaryStart, bytes: primary },
-    ];
-    const qv = pre.guide; // once, not per root
-    const rest = lonePromotes ? forest : forest.slice(1);
-    const t = ctx.trace?.enter("fuseAttention", [
-        rItem(primary, "primary"),
-        ...rest.map((r) => rNode(ctx, r.anchor, "point", r.vote)),
-    ]);
-    for (const root of rest) {
-        // DISPERSION: this root's contributing regions are confined to a
-        // single cluster (see Attention.clusters) — one local neighbourhood of
-        // the query, not several separate places.  Raw region count already
-        // failed to discriminate a coincidental match from a genuine further
-        // topic (test/24 gap 3.1 vs test/35's echo); dispersion is a different
-        // question — not how MUCH evidence, but how many separate PLACES in the
-        // query corroborate it — and a coincidental match is structurally
-        // confined to one cluster no matter how strongly it resonates.
-        //
-        // EXCEPTION: crossRegionVotes' own joint conclusions (a query naming
-        // two attributes that were only ever learnt TOGETHER — test/34's own
-        // binding corpus) are inherently ONE fused context and are pooled from
-        // a single synthetic region, so they always read as one cluster even
-        // though they already, by construction, account for both original
-        // mentions.  `breadth` (dominates — the same > half-the-query bar used
-        // everywhere else) still correctly recognises these: a genuine joint
-        // binding explains the MAJORITY of the query's regions on its own,
-        // which a coincidental echo never does (verified: test/35's echo tops
-        // out at 0.40).  So a root is trusted when EITHER measure alone
-        // indicates real signal — excluded only when BOTH are weak.  Cheap and
-        // synchronous — checked before the async already-answered walk below.
-        if (root.clusters < 2 && root.breadth <= 0.5) {
-            ctx.trace?.step("singleCluster", [rNode(ctx, root.anchor, "point", root.vote)], [], "this point's evidence is confined to one local neighbourhood of the query — not trusted as an independent topic");
-            continue;
-        }
-        // ALREADY ANSWERED: this root's own learnt continuation — the same
-        // content-addressed walk reason()'s echo guard already trusts
-        // (`ctx.store.prevCount(qId) > 0`), here applied per-candidate instead
-        // of to the whole query — is VERBATIM present later in the query.  A
-        // query that embeds both an exchange's ask and its own already-given
-        // reply (a conversation's turn plus its own prior answer, concatenated
-        // raw by addTurn — or any caller pasting a transcript into one
-        // respond() call; the check is Mind-bookkeeping-free, so it treats both
-        // identically) has already spoken this root's answer — fusing it in
-        // again would only restate it.  Deliberately NOT a magnitude measure:
-        // it fires on exact content-addressed recurrence, not on how strongly
-        // the root resonates.
-        const cont = await follow(ctx, root.anchor, qv);
-        if (cont !== null && cont.length > 0 && indexOf(query, cont, root.end) >= 0) {
-            ctx.trace?.step("alreadyAnswered", [rNode(ctx, root.anchor, "point", root.vote)], [rItem(cont, "continuation")], "this point's own learnt continuation already appears later in the query — already answered, not fused");
-            continue;
-        }
-        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 "./match.js";

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

@@ -1,20 +0,0 @@
-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[];