@hviana/sema 0.1.0 → 0.1.2

package/dist/src/mind/pipeline.js

@@ -0,0 +1,185 @@
+// pipeline.ts — the think pipeline (Section 5 of the mind).
+//
+// think() is the whole file's job: one lightest-derivation choice among
+// UNIFORM mechanisms.  The pipeline sees mechanisms through the
+// PipelineMechanism interface only — it never imports a mechanism-specific
+// type and never has a special-case branch for any mechanism.  Adding a
+// mechanism means registering one object; removing one means dropping it
+// from the list.  The mechanisms themselves live in mechanisms/ (one file
+// each); the shared pre-computation they exchange lives in Precomputed
+// (pipeline-mechanism.ts).
+import { PASS, STEP } from "./graph-search.js";
+import { gistOf, resolve } from "./primitives.js";
+import { recognise } from "./recognition.js";
+import { fuseAttention, reason } from "./reasoning.js";
+import { unexplainedSpans } from "./rationale.js";
+import { rItem } from "./trace.js";
+import { Precomputed } from "./pipeline-mechanism.js";
+import { coverMechanism } from "./mechanisms/cover.js";
+import { castMechanism } from "./mechanisms/cast.js";
+import { confluenceMechanism } from "./mechanisms/confluence.js";
+import { extractionMechanism } from "./mechanisms/extraction.js";
+import { recallMechanism } from "./mechanisms/recall.js";
+// Re-exports: cover's pre-resolution helpers and the ALU adapter kept
+// importable from the pipeline module (their historical home).
+export { resolveConcepts, resolveConnectors } from "./mechanisms/cover.js";
+export { aluToMechanism } from "./mechanisms/alu.js";
+// ── Extension dispatch (pre-loop parse) ─────────────────────────────────────
+async function collectComputed(mechanisms, query) {
+    const out = [];
+    for (const m of mechanisms) {
+        if (m.parse)
+            out.push(...await m.parse(query));
+    }
+    return out;
+}
+// ── Built-in mechanisms ─────────────────────────────────────────────────────
+// ORDER MATTERS, but only through the uniform floor/worthRunning pruning —
+// no mechanism is special-cased.  Cover runs FIRST: when a computed
+// extension result (e.g. ALU) exists, cover masks it in at near-zero cost
+// (see mechanisms/cover.ts), which becomes `best` before any other mechanism
+// invests in its own precomputation.  CAST's and confluence's floors (2*STEP,
+// 3*STEP) then fail `worthRunning` and are skipped by the SAME admissible-
+// floor pruning every mechanism is already subject to — not by asking
+// "is this an extension?".  Grade TIES keep the earlier candidate, so this
+// order is also the tie-break priority: cover, cast, confluence, extraction,
+// recall.
+export const defaultMechanisms = [
+    coverMechanism,
+    castMechanism,
+    confluenceMechanism,
+    extractionMechanism,
+    recallMechanism,
+];
+/** Think: a single lightest-derivation exploration of the Sema graph.
+ *
+ *  Every answer travels the same path:
+ *    1. Pre-computation — recognise, extension parse, guide; everything
+ *       expensive stays lazy on Precomputed until a mechanism asks.
+ *    2. Grounding — every mechanism yields candidates weighed in the one
+ *       cost ladder; the lightest grounding derivation wins.
+ *    3. Post-grounding — diagnostics (narrowDecision, thinGrounding),
+ *       reasoning (multi-hop), fusion (multi-topic). */
+export async function think(ctx, query, mechs) {
+    if (query.length === 0)
+        return null;
+    ctx._edgeGuide = gistOf(ctx, query);
+    ctx._edgeChoice.clear();
+    const t = ctx.trace?.enter("think", [rItem(query, "query")]);
+    const done = (answer, note) => {
+        t?.done(answer
+            ? [rItem(answer, "answer", resolve(ctx, answer) ?? undefined)]
+            : [], note);
+        return answer;
+    };
+    // ── Pre-computation ──────────────────────────────────────────────────
+    const mechanisms = mechs ?? defaultMechanisms;
+    const rec = recognise(ctx, query);
+    // Phase 1: collect computed spans from mechanisms that implement parse()
+    const computed = await collectComputed(mechanisms, query);
+    if (computed.length > 0) {
+        ctx.trace?.step("computeExtensions", [rItem(query, "query")], computed.map((u) => rItem(query.subarray(u.i, u.j), "operand", undefined, [u.i, u.j])), `extensions recognised and evaluated ${computed.length} computation(s)`);
+        for (const u of computed) {
+            ctx.trace?.step("evalComputation", [rItem(query.subarray(u.i, u.j), "expression", undefined, [u.i, u.j])], [rItem(u.bytes, "result", resolve(ctx, u.bytes) ?? undefined)], "evaluate the recognised operation to its authoritative result");
+        }
+    }
+    // Phase 2: the shared pre-computation container.  Eager fields only
+    // (recognition, computed spans, guide) — every expensive analysis
+    // (consensus climb, weave, span-shape classification) is a lazily-cached
+    // method on Precomputed, first-touched by whichever mechanism's floor
+    // survives its cheap gates and the worthRunning check.  A query no
+    // mechanism climbs for (e.g. one an extension decided) never climbs.
+    const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
+    const grade = (w) => Math.floor(w / STEP);
+    const unaccounted = (spans) => unexplainedSpans(query.length, spans)
+        .reduce((sum, [s, e]) => sum + (e - s), 0);
+    const weigh = (accounted, moves) => moves + PASS * unaccounted(accounted);
+    const candidates = [];
+    let best = null;
+    const consider = (c) => {
+        if (c.bytes.length === 0)
+            return;
+        candidates.push(c);
+        if (best === null || grade(c.weight) < grade(best.weight))
+            best = c;
+    };
+    const worthRunning = (floor) => best === null || grade(floor) < grade(best.weight);
+    // Phase 3: grounding loop
+    for (const mech of mechanisms) {
+        const floor = await mech.floor(ctx, query, pre, worthRunning);
+        if (floor === null) {
+            ctx.trace?.step("skipMechanism", [], [], `${mech.name} skipped — structural precondition failed`);
+            continue;
+        }
+        if (!worthRunning(floor)) {
+            ctx.trace?.step("skipMechanism", [], [], `${mech.name} skipped — floor ${floor} cannot beat incumbent (grade ${grade(best.weight)})`);
+            continue;
+        }
+        const results = await mech.run(ctx, query, pre);
+        for (const r of results) {
+            const weight = r.weight ?? weigh(r.accounted, r.moves);
+            consider({
+                bytes: r.bytes,
+                provenance: r.provenance ?? mech.provenance,
+                weight,
+                used: r.used,
+                accounted: r.accounted,
+                unexplained: r.unexplained,
+            });
+        }
+    }
+    // (TS cannot see the closure assignments into `best` and narrows it to its
+    // initial null, so the read-back needs the assertion.)
+    const decided = best;
+    if (candidates.length > 1) {
+        ctx.trace?.step("decideGrounding", candidates.map((c) => rItem(c.bytes, `${c.provenance} (weight ${c.weight.toFixed(3)}${c.unexplained ? `, unexplained: "${c.unexplained}"` : ""})`)), decided ? [rItem(decided.bytes, decided.provenance)] : [], "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder");
+        if (decided !== null) {
+            let runnerUp = null;
+            for (const c of candidates) {
+                if (c === decided)
+                    continue;
+                if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
+                    runnerUp = c;
+                }
+            }
+            if (runnerUp !== null) {
+                const margin = grade(runnerUp.weight) - grade(decided.weight);
+                if (margin <= 1) {
+                    ctx.trace?.step("narrowDecision", [
+                        rItem(decided.bytes, `${decided.provenance} (weight ${decided.weight.toFixed(3)})`),
+                    ], [
+                        rItem(runnerUp.bytes, `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`),
+                    ], `margin ${margin} grade-unit(s) — the decision could change with one more training fact`);
+                }
+            }
+        }
+    }
+    if (decided === null) {
+        done(null, "no mechanism grounded an answer");
+        return null;
+    }
+    // Honesty density
+    {
+        const covered = query.length - unaccounted(decided.accounted);
+        const density = query.length > 0 ? covered / query.length : 1;
+        const thinBar = 1 / ctx.space.maxGroup;
+        if (density < thinBar) {
+            ctx.trace?.step("thinGrounding", [rItem(decided.bytes, decided.provenance)], [], `grounded but thin — density ${density.toFixed(3)} is below 1/W (${thinBar.toFixed(3)})`);
+        }
+    }
+    const answer = decided.bytes;
+    const provenance = decided.provenance;
+    const castUsed = decided.used ?? new Set();
+    // ── Post-grounding, gated by provenance ──────────────────────────────
+    const preConsumed = provenance === "cast" || provenance === "join"
+        ? castUsed
+        : provenance === "recall" || provenance === "recall-echo"
+            ? new Set()
+            : new Set(recognise(ctx, answer).sites.map((s) => s.payload));
+    const reasoned = await reason(ctx, query, answer, preConsumed, pre);
+    const fused = provenance === "recall" || provenance === "recall-echo"
+        ? await fuseAttention(ctx, query, reasoned, pre)
+        : reasoned;
+    done(fused, "grounded, reasoned forward, fused across points of attention");
+    return { bytes: fused, provenance };
+}

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

@@ -0,0 +1,43 @@
+import { Vec } from "../vec.js";
+import { Sema } from "../sema.js";
+import type { Input, MindContext } from "./types.js";
+/** Perceive input into a content-defined tree (the river fold).
+ *  Deterministic — identical bytes always produce an identical tree. */
+export declare function perceive(ctx: MindContext, input: Input, leafAt?: (i: number) => number | null, lookup?: (ids: number[]) => number | null): Sema;
+/** The DEPOSIT-shaped perceive: the PLAIN fold (bit-identical to inference
+ *  perception — that structural train/inference agreement is load-bearing
+ *  for exact recall), computed INCREMENTALLY via the fold's level pyramid
+ *  ({@link bytesToTreePyramid}).  An accumulated context (a conversation)
+ *  grows by suffixes: the previous context's pyramid is cached by CONTENT
+ *  (ctx._depositTrees), and this deposit refolds only the right edge of
+ *  each level — O(turn) instead of O(context) per turn.  Purely a cache:
+ *  the produced tree never depends on cache state. */
+export declare function perceiveDeposit(ctx: MindContext, bytes: Uint8Array): 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;
+/** 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

@@ -0,0 +1,162 @@
+// primitives.ts — Address + Read primitives (Section 1 of the mind).
+//
+//   Address  — bytes → node   (perceive, foldTree, resolve)
+//   Read     — node → bytes   (read)
+import { bytesToTree, bytesToTreePyramid, gridToTree, hilbertBytes, stackGrids, } from "../geometry.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. */
+function latin1Key(bytes) {
+    // Batched String.fromCharCode — avoids the O(n²) cost of repeated += on
+    // potentially-large query spans, and stays well under the ~65536 arg limit.
+    const n = bytes.length;
+    let s = "";
+    for (let i = 0; i < n; i += 4096) {
+        s += String.fromCharCode(...bytes.subarray(i, Math.min(i + 4096, n)));
+    }
+    return s;
+}
+/** Perceive input into a content-defined tree (the river fold).
+ *  Deterministic — identical bytes always produce an identical tree. */
+export function perceive(ctx, input, leafAt, lookup) {
+    if (typeof input === "string" || input instanceof Uint8Array) {
+        const bytes = typeof input === "string"
+            ? new TextEncoder().encode(input)
+            : input;
+        if (leafAt === undefined && lookup === undefined) {
+            // Per-response memo (see MindContext.perceiveMemo): only the plain
+            // inference shape — raw bytes, no store capabilities — is memoised,
+            // keyed by CONTENT so byte-identical spans in fresh arrays still hit.
+            // The tree is shared by reference; Sema nodes are never mutated.
+            const memo = ctx.perceiveMemo;
+            if (memo) {
+                const key = latin1Key(bytes);
+                const hit = memo.get(key);
+                if (hit !== undefined)
+                    return hit;
+                const tree = bytesToTree(ctx.space, ctx.alphabet, bytes);
+                memo.set(key, tree);
+                return tree;
+            }
+            return bytesToTree(ctx.space, ctx.alphabet, bytes);
+        }
+        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: the PLAIN fold (bit-identical to inference
+ *  perception — that structural train/inference agreement is load-bearing
+ *  for exact recall), computed INCREMENTALLY via the fold's level pyramid
+ *  ({@link bytesToTreePyramid}).  An accumulated context (a conversation)
+ *  grows by suffixes: the previous context's pyramid is cached by CONTENT
+ *  (ctx._depositTrees), and this deposit refolds only the right edge of
+ *  each level — O(turn) instead of O(context) per turn.  Purely a cache:
+ *  the produced tree never depends on cache state. */
+export function perceiveDeposit(ctx, bytes) {
+    let prev;
+    // Longest cached PROPER prefix first.
+    const lens = [...ctx._depositLens]
+        .filter((L) => L >= 2 && L < bytes.length)
+        .sort((a, b) => b - a);
+    for (const L of lens) {
+        const hit = ctx._depositTrees.get(latin1Key(bytes.subarray(0, L)));
+        if (hit !== undefined) {
+            prev = hit;
+            break;
+        }
+    }
+    const { tree, pyramid } = bytesToTreePyramid(ctx.space, ctx.alphabet, bytes, prev);
+    if (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), pyramid);
+        ctx._depositLens.add(bytes.length);
+    }
+    return tree;
+}
+/** The raw bytes of an input — modality-neutral conversion. */
+export function inputBytes(ctx, input) {
+    if (typeof input === "string")
+        return new TextEncoder().encode(input);
+    if (input instanceof Uint8Array)
+        return input;
+    if (Array.isArray(input))
+        return hilbertBytes(stackGrids(input));
+    return hilbertBytes(input);
+}
+/** Convenience: the gist vector of a byte span. */
+export function gistOf(ctx, bytes) {
+    return perceive(ctx, bytes).v;
+}
+/** Fold a perceived tree bottom-up against the store's content-addressed maps:
+ *  every leaf is named by findLeaf, every branch by findBranch over its kids'
+ *  ids (null the moment any child is unknown).  `visit`, when given, sees each
+ *  node with its byte span and resolved id.  Returns the node's byte end and
+ *  resolved id. */
+export function foldTree(ctx, n, start, visit) {
+    if (n.kids === null) {
+        const b = n.leaf ?? new Uint8Array(0);
+        const end = start + b.length;
+        const node = ctx.store.findLeaf(b);
+        visit?.(n, start, end, node);
+        return { end, node };
+    }
+    let pos = start;
+    let known = true;
+    const kids = [];
+    for (const k of n.kids) {
+        const r = foldTree(ctx, k, pos, visit);
+        if (r.node === null)
+            known = false;
+        else if (known)
+            kids.push(r.node);
+        pos = r.end;
+    }
+    const node = known ? ctx.store.findBranch(kids) : null;
+    visit?.(n, start, pos, node);
+    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;
+    return foldTree(ctx, perceive(ctx, bytes), 0).node;
+}
+/** Walk a perceived tree in POST-ORDER with byte offsets — children before
+ *  their parent, `visit(node, start, end)` for every node including leaves.
+ *  Returns the byte end.  The one shared traversal the offset-carrying tree
+ *  readers (recognition via foldTree's richer variant, attention's region
+ *  collection, resonance's branch counting) build on, so each does not
+ *  re-derive the offset bookkeeping.  (recognition.segment keeps its own
+ *  walk: its flush semantics need PRE-order decisions at leaf-parents, which
+ *  a post-order visitor cannot express.) */
+export function walkTree(n, start, visit) {
+    if (n.kids === null) {
+        const end = start + (n.leaf?.length ?? 0);
+        visit(n, start, end);
+        return end;
+    }
+    let pos = start;
+    for (const k of n.kids)
+        pos = walkTree(k, pos, visit);
+    visit(n, start, pos);
+    return pos;
+}
+// ── Read: node → bytes ──────────────────────────────────────────────────
+/** Reconstruct a node's byte content from the DAG, up to `maxLen` bytes. */
+export function read(ctx, id, maxLen = ALL) {
+    return ctx.store.bytesPrefix(id, maxLen);
+}

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

@@ -0,0 +1,134 @@
+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;
+}
+/** 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): 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[]): number;
+}