@hviana/sema 0.5.2 → 0.5.4

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

@@ -1,85 +0,0 @@
-import { Vec } from "../vec.js";
-import { Sema } from "../sema.js";
-import type { Input, MindContext } from "./types.js";
-/** The content key of a byte span — one latin1 char per byte, an exact,
- *  collision-free encoding.  Spans on the perception path are query-scale
- *  (windows, regions, candidate spans), so key construction is far cheaper
- *  than the river fold it deduplicates. */
-export declare function latin1Key(bytes: Uint8Array): string;
-/** The {@link perceive} memo key: the span's content PLUS the boundary set it
- *  was folded under.  The tree is a function of BOTH — the same bytes fold
- *  plainly with no boundaries and into a left-nested stable-prefix shape with
- *  them — so a content-only key returns whichever shape was computed first.
- *  That is exactly what happened: a conversation seeded its cumulative context
- *  under the content key, and every later plain `perceive` of those bytes was
- *  served the boundary tree instead (measured: respondTurn answered where
- *  respond() on byte-identical input did not).  NUL separates the two parts —
- *  the boundary rendering is digits and commas, so no content byte can forge
- *  the split. */
-export declare function perceiveKey(bytes: Uint8Array, boundaries?: readonly number[]): string;
-/** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree.
- *
- *  `boundaries` is an optional sorted list of proper byte offsets where the
- *  fold must split so that each prefix segment folds identically to how it
- *  folded when it was learned (§10.3 stable-prefix contract).  Only the
- *  CALLER — who assembled the multi-turn context — knows where those
- *  boundaries are; the geometry never guesses them from the bytes. */
-export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null, boundaries?: readonly number[]): Sema;
-/** The DEPOSIT-shaped perceive.  Folds over the stream's own content cuts —
- *  bit-identical to what inference computes for the same bytes.  That
- *  train/inference agreement is the whole contract: the trained context node
- *  and the node `resolve(query)` reaches must be the SAME node, and the only
- *  way to guarantee it is to give this function nothing extra to say.  It
- *  imposes no boundaries, knows nothing about turns, and reads no convention
- *  out of the bytes.
- *
- *  An input that EXTENDS a previously deposited one — a conversation context
- *  grown by a turn, or a resumed replay — reuses that deposit's already-folded
- *  content segments ({@link contentFoldIncremental}), so it costs O(new bytes)
- *  instead of O(context).  The reuse is TRANSPARENT by construction: a segment
- *  is a pure function of its own bytes, so a reused one is bit-identical to a
- *  refolded one.  Nothing has to prove that the extending deposit is "really"
- *  a next turn — a coincidental byte prefix reuses the same segments and gets
- *  the same tree it would have got anyway.  (It used to matter: while this
- *  path imposed turn BOUNDARIES, a wrong guess changed the tree, so the cache
- *  needed a continuation-bytes proof to gate it.  Nothing is imposed now, so
- *  there is nothing to gate.) */
-export declare function perceiveDeposit(ctx: MindContext, bytes: Uint8Array, conversational?: boolean): Sema;
-/** The raw bytes of an input — modality-neutral conversion. */
-export declare function inputBytes(ctx: MindContext, input: Input): Uint8Array;
-/** Convenience: the gist vector of a byte span. */
-export declare function gistOf(ctx: MindContext, bytes: Uint8Array): Vec;
-/** Fold a perceived tree bottom-up against the store's content-addressed maps:
- *  every leaf is named by findLeaf, every branch by findBranch over its kids'
- *  ids (null the moment any child is unknown).  `visit`, when given, sees each
- *  node with its byte span and resolved id.  Returns the node's byte end and
- *  resolved id. */
-export declare function foldTree(ctx: MindContext, n: Sema, start: number, visit?: (n: Sema, start: number, end: number, node: number | null) => void): {
-    end: number;
-    node: number | null;
-};
-/** The canonical node id of a byte span: perceive it in isolation — the way
- *  training did — and recover its root bottom-up.  Returns null if any part is
- *  unknown. */
-export declare function resolve(ctx: MindContext, bytes: Uint8Array): number | null;
-/** Equivalence-class resolution: when the exact content-addressed lookup
- *  misses, find a stored node whose CANONICAL key equals the span's — the
- *  store's canon index proposes candidates by key hash, and each is verified
- *  by re-canonicalizing its bytes (hash-then-verify, like every content
- *  lookup).  Among verified candidates, one that leads somewhere (has a
- *  continuation edge) is preferred; ties break to the lowest id — a corpus
- *  property, not a seed property.  Null when the response carries no
- *  canonicalizer, the store has no canon index, or nothing verifies. */
-export declare function canonResolve(ctx: MindContext, bytes: Uint8Array): number | null;
-/** Walk a perceived tree in POST-ORDER with byte offsets — children before
- *  their parent, `visit(node, start, end)` for every node including leaves.
- *  Returns the byte end.  The one shared traversal the offset-carrying tree
- *  readers (recognition via foldTree's richer variant, attention's region
- *  collection, resonance's branch counting) build on, so each does not
- *  re-derive the offset bookkeeping.  (recognition.segment keeps its own
- *  walk: its flush semantics need PRE-order decisions at leaf-parents, which
- *  a post-order visitor cannot express.) */
-export declare function walkTree(n: Sema, start: number, visit: (node: Sema, start: number, end: number) => void): number;
-/** Reconstruct a node's byte content from the DAG, up to `maxLen` bytes. */
-export declare function read(ctx: MindContext, id: number, maxLen?: number): Uint8Array;

package/dist/src/mind/primitives.js

@@ -1,333 +0,0 @@
-// primitives.ts — Address + Read primitives (Section 1 of the mind).
-//
-//   Address  — bytes → node   (perceive, foldTree, resolve)
-//   Read     — node → bytes   (read)
-import { bytesToTree, contentFoldIncremental, gridToTree, hilbertBytes, stackGrids, } from "../geometry.js";
-import { canonHash } from "../canon.js";
-import { bytesEqual } from "../bytes.js";
-import { ALL } from "./types.js";
-// ── Address: bytes → node ──────────────────────────────────────────────
-/** The content key of a byte span — one latin1 char per byte, an exact,
- *  collision-free encoding.  Spans on the perception path are query-scale
- *  (windows, regions, candidate spans), so key construction is far cheaper
- *  than the river fold it deduplicates. */
-export function latin1Key(bytes) {
-    // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
-    // potentially-large query spans, and stays well under the ~65536 arg limit.
-    const n = bytes.length;
-    let s = "";
-    for (let i = 0; i < n; i += 4096) {
-        s += String.fromCharCode(...bytes.subarray(i, Math.min(i + 4096, n)));
-    }
-    return s;
-}
-/** The {@link perceive} memo key: the span's content PLUS the boundary set it
- *  was folded under.  The tree is a function of BOTH — the same bytes fold
- *  plainly with no boundaries and into a left-nested stable-prefix shape with
- *  them — so a content-only key returns whichever shape was computed first.
- *  That is exactly what happened: a conversation seeded its cumulative context
- *  under the content key, and every later plain `perceive` of those bytes was
- *  served the boundary tree instead (measured: respondTurn answered where
- *  respond() on byte-identical input did not).  NUL separates the two parts —
- *  the boundary rendering is digits and commas, so no content byte can forge
- *  the split. */
-export function perceiveKey(bytes, boundaries) {
-    const k = latin1Key(bytes);
-    return boundaries === undefined || boundaries.length === 0
-        ? k
-        : k + "\u0000" + boundaries.join(",");
-}
-/** Perceive input into a content-defined tree (the river fold).
- *  Deterministic — identical bytes always produce an identical tree.
- *
- *  `boundaries` is an optional sorted list of proper byte offsets where the
- *  fold must split so that each prefix segment folds identically to how it
- *  folded when it was learned (§10.3 stable-prefix contract).  Only the
- *  CALLER — who assembled the multi-turn context — knows where those
- *  boundaries are; the geometry never guesses them from the bytes. */
-export function perceive(ctx, input, leafAt, lookup, boundaries) {
-    if (typeof input === "string" || input instanceof Uint8Array) {
-        const bytes = typeof input === "string"
-            ? new TextEncoder().encode(input)
-            : input;
-        if (leafAt === undefined && lookup === undefined) {
-            // Per-response memo (see MindContext.perceiveMemo): only the plain
-            // inference shape — raw bytes, no store capabilities — is memoised,
-            // keyed by CONTENT so byte-identical spans in fresh arrays still hit.
-            // The tree is shared by reference; Sema nodes are never mutated.
-            const memo = ctx.perceiveMemo;
-            if (memo) {
-                const key = perceiveKey(bytes, boundaries);
-                const hit = memo.get(key);
-                if (hit !== undefined) {
-                    if (ctx.meter)
-                        ctx.meter.perceiveHits++;
-                    return hit;
-                }
-                if (ctx.meter) {
-                    ctx.meter.perceptions++;
-                    ctx.meter.perceivedBytes += bytes.length;
-                }
-                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
-                memo.set(key, tree);
-                return tree;
-            }
-            if (ctx.meter) {
-                ctx.meter.perceptions++;
-                ctx.meter.perceivedBytes += bytes.length;
-            }
-            return bytesToTree(ctx.space, ctx.alphabet, bytes, undefined, undefined, boundaries);
-        }
-        return bytesToTree(ctx.space, ctx.alphabet, bytes, leafAt, lookup);
-    }
-    if (Array.isArray(input)) {
-        return gridToTree(ctx.space, ctx.alphabet, stackGrids(input));
-    }
-    return gridToTree(ctx.space, ctx.alphabet, input);
-}
-/** The DEPOSIT-shaped perceive.  Folds over the stream's own content cuts —
- *  bit-identical to what inference computes for the same bytes.  That
- *  train/inference agreement is the whole contract: the trained context node
- *  and the node `resolve(query)` reaches must be the SAME node, and the only
- *  way to guarantee it is to give this function nothing extra to say.  It
- *  imposes no boundaries, knows nothing about turns, and reads no convention
- *  out of the bytes.
- *
- *  An input that EXTENDS a previously deposited one — a conversation context
- *  grown by a turn, or a resumed replay — reuses that deposit's already-folded
- *  content segments ({@link contentFoldIncremental}), so it costs O(new bytes)
- *  instead of O(context).  The reuse is TRANSPARENT by construction: a segment
- *  is a pure function of its own bytes, so a reused one is bit-identical to a
- *  refolded one.  Nothing has to prove that the extending deposit is "really"
- *  a next turn — a coincidental byte prefix reuses the same segments and gets
- *  the same tree it would have got anyway.  (It used to matter: while this
- *  path imposed turn BOUNDARIES, a wrong guess changed the tree, so the cache
- *  needed a continuation-bytes proof to gate it.  Nothing is imposed now, so
- *  there is nothing to gate.) */
-export function perceiveDeposit(ctx, bytes, conversational = false) {
-    // Longest cached PROPER prefix first — the most segments to reuse.
-    let prev;
-    const lens = [...ctx._depositLens]
-        .filter((L) => L >= 2 && L < bytes.length)
-        .sort((a, b) => b - a);
-    for (const L of lens) {
-        const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
-        if (hit !== undefined) {
-            prev = hit.content;
-            break;
-        }
-    }
-    const folded = contentFoldIncremental(ctx.space, ctx.alphabet, bytes, prev);
-    // Only a CONVERSATIONAL deposit writes the cache: reuse is sound for any
-    // deposit, but the budget is 8 entries and a corpus of unrelated facts would
-    // evict the live chains for nothing.  Purely a cost decision now, not a
-    // correctness one.
-    if (conversational && bytes.length >= 2) {
-        // The lengths set drifts as the map evicts; past the probe budget the
-        // drift itself becomes the cost (each stale length is an O(len) key
-        // build), so both reset together — losing only warm-up on live chains.
-        if (ctx._depositLens.size > 64) {
-            ctx._depositLens.clear();
-            ctx._depositTrees.clear();
-        }
-        ctx._depositTrees.set(latin1Key(bytes), { content: folded.fold });
-        ctx._depositLens.add(bytes.length);
-    }
-    return folded.tree;
-}
-/** The raw bytes of an input — modality-neutral conversion. */
-export function inputBytes(ctx, input) {
-    if (typeof input === "string")
-        return new TextEncoder().encode(input);
-    if (input instanceof Uint8Array)
-        return input;
-    if (Array.isArray(input))
-        return hilbertBytes(stackGrids(input));
-    return hilbertBytes(input);
-}
-/** Convenience: the gist vector of a byte span. */
-export function gistOf(ctx, bytes) {
-    return perceive(ctx, bytes).v;
-}
-/** Fold a perceived tree bottom-up against the store's content-addressed maps:
- *  every leaf is named by findLeaf, every branch by findBranch over its kids'
- *  ids (null the moment any child is unknown).  `visit`, when given, sees each
- *  node with its byte span and resolved id.  Returns the node's byte end and
- *  resolved id. */
-export function foldTree(ctx, n, start, visit) {
-    // Subtree already resolved (from a previous conversation turn or an earlier
-    // recognition pass).  The pyramid reuses prefix subtrees as identical Sema
-    // objects, so a conversation's prefix is warm from its second turn on.
-    // Without a visitor that makes foldTree O(suffix) instead of O(context);
-    // with one it stays O(context) and saves the per-node store probes instead
-    // (see below for why the distinction is not negotiable).
-    //
-    // WHAT THE CACHE KNOWS, AND WHAT IT DOES NOT.  An entry records this
-    // subtree's id and byte length — nothing about its DESCENDANTS' spans.
-    // Returning here therefore emits ONE visit() where a cold walk emits one per
-    // node, and `visit` is not instrumentation: recognise() emits its sites from
-    // it (recognition.ts) and attention's collectRegions votes over what it
-    // yields (attention.ts).  Skipping the descent silently shrinks the evidence
-    // those mechanisms see, purely because the cache happened to be warm.
-    //
-    // That is not hypothetical and not an edge case — it is every conversation
-    // turn after the first.  `contentFoldIncremental` deliberately shares prefix
-    // segment OBJECTS across turns (~99% reuse), so by turn 2 the prefix is
-    // warm; meanwhile recogniseMemo/climbMemo are keyed on exact query BYTES,
-    // which a growing context never repeats.  Warm subtrees + missed memos is
-    // the unprotected quadrant.  Measured over real trained conversations,
-    // recognising the same context with a warm prefix lost 67-92% of its leaves
-    // (772->204, 589->47, 872->291, 377->37) with `sites` unchanged, so the loss
-    // is invisible to the coarse counts; a direct foldTree probe on identical
-    // bytes and an identical tree object fired visit() 661 times cold and 37
-    // warm.  respond() is immune only because it never sets _resolvedSubtrees
-    // (mind.ts) — the degradation was unique to the multi-turn API.
-    //
-    // So the fast path is taken only when NOBODY IS WATCHING.  With a visitor
-    // present we still walk, and the cache degrades to the thing it soundly is:
-    // an elision of the store probes (findLeaf/findBranch) at each node, not an
-    // elision of the traversal.  Ids still come from the cache, so a warm walk
-    // is cheaper than a cold one; it is no longer *different* from one.
-    const cached = ctx._resolvedSubtrees?.get(n);
-    if (cached !== undefined && visit === undefined) {
-        return { end: start + cached.len, node: cached.id };
-    }
-    if (n.kids === null) {
-        const b = n.leaf ?? new Uint8Array(0);
-        const end = start + b.length;
-        const node = cached !== undefined ? cached.id : ctx.store.findLeaf(b);
-        visit?.(n, start, end, node);
-        if (node !== null && ctx._resolvedSubtrees) {
-            ctx._resolvedSubtrees.set(n, { id: node, len: b.length });
-        }
-        return { end, node };
-    }
-    let pos = start;
-    let known = true;
-    const kids = [];
-    for (const k of n.kids) {
-        const r = foldTree(ctx, k, pos, visit);
-        if (r.node === null)
-            known = false;
-        else if (known)
-            kids.push(r.node);
-        pos = r.end;
-    }
-    // Same store-probe elision as the leaf case: a cached entry already names
-    // this subtree, so the descent above was for `visit`'s benefit alone and the
-    // id need not be re-derived.  Using it also keeps a warm walk's ids
-    // bit-identical to a cold walk's rather than re-deriving them from children
-    // that may themselves have come from cache.
-    const node = cached !== undefined
-        ? cached.id
-        : known
-            ? ctx.store.findBranch(kids)
-            : null;
-    visit?.(n, start, pos, node);
-    if (node !== null && ctx._resolvedSubtrees) {
-        ctx._resolvedSubtrees.set(n, { id: node, len: pos - start });
-    }
-    return { end: pos, node };
-}
-/** The canonical node id of a byte span: perceive it in isolation — the way
- *  training did — and recover its root bottom-up.  Returns null if any part is
- *  unknown. */
-export function resolve(ctx, bytes) {
-    if (bytes.length === 0)
-        return null;
-    if (ctx.meter)
-        ctx.meter.resolves++;
-    const exact = foldTree(ctx, perceive(ctx, bytes), 0).node;
-    if (exact !== null)
-        return exact;
-    return canonResolve(ctx, bytes);
-}
-/** Equivalence-class resolution: when the exact content-addressed lookup
- *  misses, find a stored node whose CANONICAL key equals the span's — the
- *  store's canon index proposes candidates by key hash, and each is verified
- *  by re-canonicalizing its bytes (hash-then-verify, like every content
- *  lookup).  Among verified candidates, one that leads somewhere (has a
- *  continuation edge) is preferred; ties break to the lowest id — a corpus
- *  property, not a seed property.  Null when the response carries no
- *  canonicalizer, the store has no canon index, or nothing verifies. */
-export function canonResolve(ctx, bytes) {
-    const canon = ctx.canon;
-    const store = ctx.store;
-    if (canon === null || !store.canonFind)
-        return null;
-    if (bytes.length < 2)
-        return null;
-    const memo = ctx.canonMemo;
-    const memoKey = memo ? latin1Key(bytes) : "";
-    if (memo) {
-        const hit = memo.get(memoKey);
-        if (hit !== undefined)
-            return hit;
-    }
-    const set = (v) => {
-        memo?.set(memoKey, v);
-        return v;
-    };
-    const key = canon(bytes);
-    if (key.length === 0)
-        return set(null);
-    // A stored form that IS canonical is not in the index (buildCanonIndex
-    // skips identity rows) — the exact content-addressed lookup of the
-    // canonical bytes finds it directly.
-    if (key.length !== bytes.length || !bytesEqual(key, bytes)) {
-        const direct = foldTree(ctx, perceive(ctx, key), 0).node;
-        if (direct !== null)
-            return set(direct);
-    }
-    if (ctx.meter)
-        ctx.meter.canonLookups++;
-    const candidates = store.canonFind(canonHash(key));
-    if (candidates.length === 0)
-        return set(null);
-    let best = null;
-    let bestLeads = false;
-    for (const id of candidates) {
-        const bytesOf = read(ctx, id);
-        const stored = canon(bytesOf);
-        if (stored.length !== key.length || !bytesEqual(stored, key))
-            continue;
-        // The index stores FLAT content twins; the id the exact path would have
-        // resolved for these bytes is their FOLD — the deposit-shaped node that
-        // carries the edges and halos.  Re-folding the candidate's bytes lands
-        // on exactly the node the canonical-case query would have found.
-        const folded = foldTree(ctx, perceive(ctx, bytesOf), 0).node;
-        const use = folded ?? id;
-        const leads = store.hasNext(use) || store.haloMass(use) > 0;
-        if (best === null || (leads && !bestLeads) ||
-            (leads === bestLeads && use < best)) {
-            best = use;
-            bestLeads = leads;
-        }
-    }
-    return set(best);
-}
-/** Walk a perceived tree in POST-ORDER with byte offsets — children before
- *  their parent, `visit(node, start, end)` for every node including leaves.
- *  Returns the byte end.  The one shared traversal the offset-carrying tree
- *  readers (recognition via foldTree's richer variant, attention's region
- *  collection, resonance's branch counting) build on, so each does not
- *  re-derive the offset bookkeeping.  (recognition.segment keeps its own
- *  walk: its flush semantics need PRE-order decisions at leaf-parents, which
- *  a post-order visitor cannot express.) */
-export function walkTree(n, start, visit) {
-    if (n.kids === null) {
-        const end = start + (n.leaf?.length ?? 0);
-        visit(n, start, end);
-        return end;
-    }
-    let pos = start;
-    for (const k of n.kids)
-        pos = walkTree(k, pos, visit);
-    visit(n, start, pos);
-    return pos;
-}
-// ── Read: node → bytes ──────────────────────────────────────────────────
-/** Reconstruct a node's byte content from the DAG, up to `maxLen` bytes. */
-export function read(ctx, id, maxLen = ALL) {
-    return ctx.store.bytesPrefix(id, maxLen);
-}

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

@@ -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;
-}