@hviana/sema 0.8.3 → 0.8.6

package/AGENTS.md

@@ -55,14 +55,15 @@ Five invariants. Violate one and the system degrades silently — tests pin them
 | 4 | One cost currency                   | Single ladder `MICRO`/`STEP`/`CONCEPT`/`PASS`; `weight = moves + PASS·unaccounted`; compare at `STEP` grade                                            | `docs/architecture/cost-model.md` → `src/mind/graph-search.ts`, `src/derive/`               |
 | 5 | Bounded reads                       | No per-query read grows with N; cap is `hubBound = √N` enforced at the store via `LIMIT` reads, existence probes, and `bytesPrefix` caps               | `docs/architecture/bounded-reads.md` → `src/store.ts`, `src/mind/traverse.ts`               |
 
-Cross-cutting contracts (single-definition, import everywhere): `contentLevels`
-in `src/geometry.ts` is the one boundary rule; `src/mind/canonical.ts` is the
-write/read contract for canonical segmentation; `src/mind/junction.ts` is the
-shared content-addressed ascent; `Precomputed` in
-`src/mind/pipeline-mechanism.ts` is the per-response lazy memo; `src/meter.ts`
-is the write-only work accounting surface. See `docs/INDEX.md` for the full
-contract table and `docs/architecture/factored-machinery.md` for ownership.
-Tie-breaks are corpus-determined, but not interchangeable (`determinism.md`).
+Cross-cutting contracts (single-definition, imported everywhere):
+`contentLevels` in `src/geometry.ts` is the one boundary rule;
+`src/mind/derivation.ts` is the closure law; `src/mind/canonical.ts` is the
+canonical segmentation contract; `src/mind/junction.ts` is the shared
+content-addressed ascent; `Precomputed` in `src/mind/pipeline-mechanism.ts` is
+the per-response memo; `src/meter.ts` is the write-only work accounting surface.
+See `docs/INDEX.md` and `factored-machinery.md` for the contract table and
+ownership. Tie-breaks are corpus-determined, not interchangeable
+(`determinism.md`).
 
 ## 3. Where things live
 
@@ -97,8 +98,8 @@ methods; `mind.ts` is a thin assembly.
 ### Add a grounding mechanism or extension
 
 Implement `PipelineMechanism` (`floor` → admissible bound or `null`; `run` →
-candidates with `bytes`/`accounted`/`moves`/`unexplained` + optional
-`scaffolding`/`complete`/`used`). Register via
+candidates with `bytes`/`accounted`/`moves` + optional
+`scaffolding`/`complete`/`used`/`provenance`). Register via
 `new Mind({ mechanismFactories: [host => yourMechanism(host)] })`. Verify the
 four market constraints (decoupled, declared competence, visible budget,
 evidence travels). → `docs/architecture/mechanism-market.md`

package/README.md

@@ -179,39 +179,16 @@ in the same pass — reasons onward to a separate fact about that painter. Nothi
 in the reply but the painter's own name comes from the question.
 
 ```ts
-// demo.ts — one short session that drives the WHOLE pipeline from one memory.
-
-import { Mind } from "../src/index.js";
-import { SQliteStore } from "../src/store-sqlite.js";
-
-async function main(): Promise<void> {
-  const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
-  const ask = async (q: string) => (await mind.respondText(q)).trim();
-
-  // ── Jot down what we know. Each line is just (context → what follows). ──
-  await mind.ingest([
-    // One relation, shown three times — a pattern taught purely by example:
-    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
-    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
-    [
-      "The Night Watch was painted by Rembrandt van Rijn.",
-      "Rembrandt van Rijn",
-    ],
-    // One stray fact, keyed on a name none of the examples mention:
-    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
-  ]);
-
-  // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
-  //    the painter, then keep going into what is known about him.
-  console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
-
-  // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
-  console.log(await ask("a museum charges 12*4 for a family ticket"));
-
-  await mind.store.close();
-}
-
-main();
+// demo.ts — a corpus goes in, and the memory is read back out.
+
+import { Mind, SQliteStore } from "../src/index.js";
+
+const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
+await mind.ingest(CORPUS); // (context -> what follows) notes, the deposit shape
+
+mind.sampleCorpus(4); // what the memory HOLDS
+mind.searchCorpusText("Pablo Picasso"); // which notes a question REACHES
+await mind.respond("The Weeping Woman was painted by Pablo Picasso.");
 ```
 
 ```text
@@ -224,7 +201,7 @@ Ask for the receipt instead of the text, and each answer says how it was reached
 the route, and, on request, the complete replayable trace behind it:
 
 ```text
-"The Weeping Woman was painted by Pablo Picasso."  →  provenance: cast
+"The Weeping Woman was painted by Pablo Picasso."  →  provenance: cover
     ( structure carried across the three worked examples )
 
 "a museum charges 12*4 for a family ticket"        →  provenance: cover
@@ -233,10 +210,12 @@ the route, and, on request, the complete replayable trace behind it:
 
 > [!NOTE]
 > This is **[example/demo.ts](example/demo.ts)** — run it with `npm run demo`.
-> The first question names a painting Sema was never shown, and asks nothing
-> explicit; what comes back is a fact about Cubism that appears **nowhere** in
-> it. The second is exact, not a plausible-looking guess. Every step traces back
-> to the four notes above.
+> It reads the memory back two ways: `sampleCorpus` browses what it holds, and
+> `searchCorpusText` reports which stored notes a question reaches — exactly, so
+> a question overlapping nothing is answered with a note saying so, never with
+> an invention. The first answer names a painting Sema was never shown and still
+> returns a fact about Cubism that appears **nowhere** in it; the second is
+> computed. Every step traces back to the five notes above.
 
 ---
 

package/dist/example/demo.js

@@ -1,39 +1,90 @@
-// demo.ts — one short session that drives the WHOLE pipeline from one memory.
+// demo.ts — a corpus goes in, and the memory is read back out.
 //
-// We give Sema a handful of plain notes, then ask things that no single note
-// answers. The headline query is the third one: from three worked examples Sema
-// learns the shape of "X was painted by Y", lifts the painter out of a sentence
-// it has NEVER seen, and then — in the same pass — reasons forward to a separate
-// fact about that painter. The reply contains no word from the question. That is
-// retrieval, generalization, and reasoning composing as a single act, with every
-// step traceable back to the notes behind it.
-import { Mind } from "../src/index.js";
-import { SQliteStore } from "../src/store-sqlite.js";
+// Sema is given a small corpus of plain notes, each one the shape every deposit
+// has: a context, and what follows it. Then the memory is read two ways — what
+// it HOLDS (`sampleCorpus`), and which of its notes a question REACHES
+// (`searchCorpusText`). Both run through the same content-addressed machinery an
+// answer uses (src/mind/corpus.ts); nothing is indexed and nothing is written.
+//
+// The search addresses content EXACTLY, not by keyword: a question reaches a
+// note when it shares chunk-aligned content with it, so a question with no such
+// overlap is reported as exactly that — a STATE, rendered by the text layer
+// (`CorpusTextResult.note`), never as prose the engine invented.
+//
+// The last act is two ordinary answers, each with its derivation streamed as it
+// unfolds, the PROVENANCE that names the route it grounded on, and the work it
+// cost read off the meter: the rationale and the meter ARE the explanation
+// surface (AGENTS.md §6).
+import { decodeText, formatReport, Mind, SQliteStore } from "../src/index.js";
+// One relation shown three times — a pattern taught purely by example — plus a
+// stray fact keyed on a name none of the examples mention.
+const CORPUS = [
+    ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
+    ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
+    [
+        "The Night Watch was painted by Rembrandt van Rijn.",
+        "Rembrandt van Rijn",
+    ],
+    ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
+    ["The Weeping Woman was painted by Pablo Picasso.", "Pablo Picasso"],
+];
+// Questions the corpus can address, and one it cannot — the honest miss.
+const QUERIES = [
+    "The Mona Lisa was painted by Leonardo da Vinci.",
+    "Pablo Picasso",
+    "xylophone",
+];
+// One question answered by composing across the notes, and one answered by
+// computing: the two routes the corpus search does not take.
+const ASKS = [
+    "The Weeping Woman was painted by Pablo Picasso.",
+    "a museum charges 12*4 for a family ticket",
+];
 async function main() {
-    const mind = new Mind({ store: new SQliteStore({ path: ":memory:" }) });
-    const ask = async (q) => (await mind.respondText(q)).trim();
-    // ── Jot down what we know. Each line is just (context → what follows). ──
-    await mind.ingest([
-        // One relation, shown three times — a pattern taught purely by example:
-        ["The Mona Lisa was painted by Leonardo da Vinci.", "Leonardo da Vinci"],
-        ["The Starry Night was painted by Vincent van Gogh.", "Vincent van Gogh"],
-        [
-            "The Night Watch was painted by Rembrandt van Rijn.",
-            "Rembrandt van Rijn",
-        ],
-        // One stray fact, keyed on a name none of the examples mention:
-        ["Pablo Picasso", "Pablo Picasso co-founded the Cubist movement"],
-    ]);
-    // 1) GENERALIZE — apply the learned pattern to an unseen sentence and read out
-    //    the painter. "Pablo Picasso" was never given as an answer; Sema locates it
-    //    by analogy to the three examples.
-    console.log(await ask("The Weeping Woman was painted by Pablo Picasso."));
-    // → "Pablo Picasso co-founded the Cubist movement"
-    //   …and, having found the painter, it KEEPS GOING: the name bridges into the
-    //   one fact it holds about him. The answer appears in no word of the question.
-    // 2) COMPUTE — exact arithmetic, grounded right where the notes go silent.
-    console.log(await ask("a museum charges 12*4 for a family ticket"));
-    // → "48"
+    const mind = new Mind({
+        store: new SQliteStore({ path: ":memory:" }),
+        profile: true,
+    });
+    await mind.ingest(CORPUS);
+    // 1) WHAT THE MEMORY HOLDS — real pairs, browsed, no query and no random draw.
+    console.log("— the corpus, as the memory holds it —");
+    for (const p of mind.sampleCorpus(4).pairs) {
+        console.log(`  ${decodeText(p.context)}  →  ${decodeText(p.continuation)}`);
+    }
+    // 2) SEARCH — which stored notes does a question reach? A question that
+    //    addresses the corpus answers with pairs; one that shares nothing with it
+    //    answers with a note saying so.
+    for (const q of QUERIES) {
+        const r = mind.searchCorpusText(q, 3);
+        console.log(`\n— "${q}" —  ${r.resolved} resolved / ${r.reached} reached`);
+        if (r.note !== undefined)
+            console.log(`  ${r.note}`);
+        for (const p of r.pairs) {
+            console.log(`  ${p.context}  →  ${p.continuation}  (${p.matchedBytes} matched)`);
+        }
+    }
+    // 3) ANSWERS, WITH THEIR DERIVATION — the same pipeline, read as data. Steps
+    //    repeat (recognise re-enters under every mechanism that needs it), so each
+    //    distinct mechanism-and-note is printed once, in the order it first ran.
+    for (const q of ASKS) {
+        const seen = new Set();
+        const trace = [];
+        const r = await mind.respond(q, (s) => {
+            const line = `${s.mechanism.join(" › ")}${s.note ? ` — ${s.note}` : ""}`;
+            if (seen.has(line))
+                return;
+            seen.add(line);
+            trace.push(`${"  ".repeat(Math.max(0, s.mechanism.length - 1))}${line}`);
+        });
+        console.log(`\n— "${q}" —  ${r.provenance ?? "no answer"}`);
+        console.log(`  ${decodeText(r.bytes).trim()}`);
+        console.log("— how —");
+        for (const s of trace)
+            console.log(s);
+        if (mind.lastCost !== null) {
+            console.log(`— what it cost —\n${formatReport(mind.lastCost)}`);
+        }
+    }
     await mind.store.close();
 }
 main();

package/dist/src/geometry.d.ts

@@ -128,16 +128,6 @@ export declare function profileCapacity(D: number): number;
  *  root.
  */
 export declare function consensusFloor(N: number): number;
-/** The coverage bar for the reach (interior) index, when vector-similarity
- *  gating is used.  Returns the concept threshold — the structural midpoint
- *  (~0.5 at D=1024) where two forms are "more similar than not."
- *
- *  Currently UNUSED in the hot training path: interior nodes are indexed
- *  unconditionally (hash-cons dedup bounds the index naturally).
- *  Post-hoc structural compaction ({@link Store.compactContentIndex})
- *  replaces runtime coverage gating with a batch pass that removes
- *  structurally-isolated entries.  Derived, never tuned. */
-export declare function coverageBar(_maxGroup: number, D: number): number;
 export interface Folded {
     tree: Sema;
     /** Byte length of the subtree — carried incrementally so the stable-prefix

package/dist/src/geometry.js

@@ -167,18 +167,6 @@ export function profileCapacity(D) {
 export function consensusFloor(N) {
     return Math.log(N) + 1 / 2;
 }
-/** The coverage bar for the reach (interior) index, when vector-similarity
- *  gating is used.  Returns the concept threshold — the structural midpoint
- *  (~0.5 at D=1024) where two forms are "more similar than not."
- *
- *  Currently UNUSED in the hot training path: interior nodes are indexed
- *  unconditionally (hash-cons dedup bounds the index naturally).
- *  Post-hoc structural compaction ({@link Store.compactContentIndex})
- *  replaces runtime coverage gating with a batch pass that removes
- *  structurally-isolated entries.  Derived, never tuned. */
-export function coverageBar(_maxGroup, D) {
-    return conceptThreshold(D);
-}
 // ---- folding ----
 //
 // The river fold is a hierarchical prefix network: each level contracts

package/dist/src/meter.d.ts

@@ -199,12 +199,38 @@ export declare class Meter {
      *  not computable at all.  With it, the price of extending the answer is
      *  `reasonSteps · STEP`, the ladder's own value for following an edge. */
     reasonSteps: number;
-    /** Bytes of the grounding's UNCOVERED material the extension was justified by
-     *  — the union of the spans each step carried a `W`-window of.  The gate
-     *  already computed WHICH span carried it per step and kept only a boolean;
-     *  this is that fact, accumulated.  Read with {@link reasonSteps}: one is the
-     *  price, the other the explanation. */
+    /** Bytes the admitted steps ACCOUNTED for — the witnesses' spans, summed by the
+     *  law's own function over the tail of the state's accounting.  It is NOT what
+     *  they carried: a step admitted by `reaches` may declare spans it holds no
+     *  window of, and then it accounts without carrying and consumes nothing (see
+     *  {@link closureDrainedBytes}).  Read with {@link reasonSteps}: one is the
+     *  price, the other the accounting. */
+    reasonAccountedBytes: number;
+    /** Bytes of the QUESTION's own material an admitted step CARRIED — the windows
+     *  of the remainder its product holds, read by the law's one reading.  The
+     *  accounting may be larger (a `reaches` step declares spans it holds no window
+     *  of) and the consumption is the window of a step that also reaches, so the
+     *  three form a lattice: consumed ⊆ carried ⊆ accounted. */
     reasonCarriedBytes: number;
+    /** Times the layer OFFERED a continuation to the law.  Read with
+     *  {@link lawRejects}: the offers the law refused are the Model X contract being
+     *  exercised, and `offerRuns - lawRejects` is the accepted transitions. */
+    offerRuns: number;
+    /** Times the law REFUSED the continuation the layer offered.  A refusal is
+     *  terminal by the layer's contract, so this counts the moments the contract
+     *  mattered — zero means the walk never needed it. */
+    lawRejects: number;
+    /** Bytes of the question's REMAINDER a step CONSUMED — the drop the law's own
+     *  `advance` makes when a declared move carries the material it accounts for.
+     *  Read with {@link reasonSteps} and {@link reasonAccountedBytes}: carrying is
+     *  the engagement, this is the consumption, and before it the second was
+     *  invisible. */
+    closureDrainedBytes: number;
+    /** Bytes of the question the grounding PRICED but whose material its answer does
+     *  NOT carry, at or above one quantum — the debt the construction leaves for the
+     *  walk to pay by carrying it.  Zero means the grounding's coverage is honest:
+     *  everything it priced is either held by the answer or under the W floor. */
+    groundingWithheldBytes: number;
     /** Branch-node probes the pivot sweep actually spent looking for the learnt
      *  context an answer contains (one `resonate` per probe).  The untraced view
      *  of what the multi-hop's shortlist costs. */

package/dist/src/meter.js

@@ -209,12 +209,38 @@ export class Meter {
      *  not computable at all.  With it, the price of extending the answer is
      *  `reasonSteps · STEP`, the ladder's own value for following an edge. */
     reasonSteps = 0;
-    /** Bytes of the grounding's UNCOVERED material the extension was justified by
-     *  — the union of the spans each step carried a `W`-window of.  The gate
-     *  already computed WHICH span carried it per step and kept only a boolean;
-     *  this is that fact, accumulated.  Read with {@link reasonSteps}: one is the
-     *  price, the other the explanation. */
+    /** Bytes the admitted steps ACCOUNTED for — the witnesses' spans, summed by the
+     *  law's own function over the tail of the state's accounting.  It is NOT what
+     *  they carried: a step admitted by `reaches` may declare spans it holds no
+     *  window of, and then it accounts without carrying and consumes nothing (see
+     *  {@link closureDrainedBytes}).  Read with {@link reasonSteps}: one is the
+     *  price, the other the accounting. */
+    reasonAccountedBytes = 0;
+    /** Bytes of the QUESTION's own material an admitted step CARRIED — the windows
+     *  of the remainder its product holds, read by the law's one reading.  The
+     *  accounting may be larger (a `reaches` step declares spans it holds no window
+     *  of) and the consumption is the window of a step that also reaches, so the
+     *  three form a lattice: consumed ⊆ carried ⊆ accounted. */
     reasonCarriedBytes = 0;
+    /** Times the layer OFFERED a continuation to the law.  Read with
+     *  {@link lawRejects}: the offers the law refused are the Model X contract being
+     *  exercised, and `offerRuns - lawRejects` is the accepted transitions. */
+    offerRuns = 0;
+    /** Times the law REFUSED the continuation the layer offered.  A refusal is
+     *  terminal by the layer's contract, so this counts the moments the contract
+     *  mattered — zero means the walk never needed it. */
+    lawRejects = 0;
+    /** Bytes of the question's REMAINDER a step CONSUMED — the drop the law's own
+     *  `advance` makes when a declared move carries the material it accounts for.
+     *  Read with {@link reasonSteps} and {@link reasonAccountedBytes}: carrying is
+     *  the engagement, this is the consumption, and before it the second was
+     *  invisible. */
+    closureDrainedBytes = 0;
+    /** Bytes of the question the grounding PRICED but whose material its answer does
+     *  NOT carry, at or above one quantum — the debt the construction leaves for the
+     *  walk to pay by carrying it.  Zero means the grounding's coverage is honest:
+     *  everything it priced is either held by the answer or under the W floor. */
+    groundingWithheldBytes = 0;
     /** Branch-node probes the pivot sweep actually spent looking for the learnt
      *  context an answer contains (one `resonate` per probe).  The untraced view
      *  of what the multi-hop's shortlist costs. */

package/dist/src/mind/articulation.js

@@ -96,7 +96,7 @@ export async function articulate(ctx, answer, query) {
             s.end,
         ])),
     ]);
-    const solved = ctx.search.cover(answer.length, voicedSites, new Map(), ans.leaves, ans.splits, ans.starts, substitutions, undefined, undefined, ctx.trace ? (steps) => traceDerivation(ctx, steps) : undefined);
+    const solved = ctx.search.cover(answer.length, voicedSites, new Map(), ans.leaves, ans.splits, substitutions, undefined, undefined, ctx.trace ? (steps) => traceDerivation(ctx, steps) : undefined);
     const segs = solved && solved.segs;
     tArtCover?.done(segs === null
         ? []

package/dist/src/mind/attention.js

@@ -15,6 +15,7 @@ import { leafIdRun } from "./canonical.js";
 import { atomIsHub, corpusN, edgeAncestors, hubBound, sharedReachMemo, } from "./traverse.js";
 import { cachedRead, junctionContainersFrom, junctionSeeds, junctionSynonyms, loadJunctionSynonymSides, walkCache, } from "./junction.js";
 import { indexOf } from "../bytes.js";
+import { restates } from "./derivation.js";
 import { rItem, rNode, traceDerivation } from "./trace.js";
 function newTraceDraft(perceivedCount) {
     return {
@@ -2279,7 +2280,7 @@ async function crossRegionVotes(ctx, query, regions, rvs, k, N, reachMemo, td) {
                     const ri = indexOf(bytes, right, 0);
                     if (li >= 0 && ri >= 0) {
                         const joined = bytes.subarray(Math.min(li, ri), Math.max(li + left.length, ri + right.length));
-                        if (indexOf(query, joined, 0) >= 0) {
+                        if (restates(query, joined, 0)) {
                             if (structuralTrace)
                                 structuralTrace.selfEvidenceRejected++;
                             continue; // query says it itself

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

@@ -0,0 +1,201 @@
+/** A half-open `[start, end)` span of the asker's own bytes. */
+export type Span = readonly [number, number];
+/** The BYTE COUNT of a span list — what the currency calls `unaccounted` in
+ *  `weight = moves + PASS·unaccounted`.  ONE definition: this was four copies of
+ *  the same `reduce` before the architecture audit collapsed them. */
+export declare function unaccountedBytes(spans: ReadonlyArray<Span>): number;
+/** The `[start, end)` gaps of `[0, queryLen)` NOT covered by `accounted` — the
+ *  union-of-spans reading the ladder prices at PASS per byte, and the raw
+ *  material every closure decision measures.  Clipped to the question, sorted
+ *  and merged, so two overlapping spans account for their union once. */
+export declare function unexplainedSpans(queryLen: number, accounted: ReadonlyArray<Span>): Array<[number, number]>;
+/** THE REMAINDER: what no step has accounted for, with every span below one
+ *  river-fold quantum dropped.  `W` is the mind's own line between bridging
+ *  punctuation and a substantive phrase — the same floor `liftedScaffolding`
+ *  and the honesty-density bar use — so a remainder under it licenses nothing
+ *  and blocks nothing.  This is the law's measure. */
+export declare function remainderOf(queryLen: number, explained: ReadonlyArray<Span>, W: number): Array<[number, number]>;
+/** A WITNESS — what a transition carries, in one reading: the SPAN it accounts
+ *  for, and the WINDOW of the question the product itself holds.  The window is
+ *  present only when the product holds question material, and it is the ONLY
+ *  thing the question's remainder may be consumed by. */
+export interface Witness {
+    readonly span: Span;
+    readonly window?: Span;
+}
+/** The window of `span` that `product` holds, or null: the ONE reading of
+ *  coverage — used by {@link carries}, by the move branch, and by the GROUNDING
+ *  when it decides what its answer has actually paid for. */
+export declare function windowOf(span: Span, product: Uint8Array, query: Uint8Array, W: number): Span | null;
+/** PROGRESS, by coverage: the first member of `remainder` that `product` carries
+ *  a whole quantum of, or null when it carries none.  The window is taken from
+ *  `query`, the asker's own bytes, so the test is "this product restates a
+ *  quantum of what was left unaccounted", never a similarity score.
+ *
+ *  One witness per step, deterministically the FIRST in remainder order: the
+ *  measure stays a single member of a finite list, which is what makes the walk
+ *  reviewable — and, because the remainder is not drained, it is the walker's
+ *  cycle protection (not this) that terminates a chain. */
+export declare function carries(remainder: ReadonlyArray<Span>, product: Uint8Array, query: Uint8Array, W: number): Array<Witness> | null;
+/** Whether `bytes` RESTATES the question — says nothing the asker did not just
+ *  say — and is therefore not an answer.  This is a closure condition: a
+ *  derivation whose product is already the question has added nothing, and the
+ *  engine asks it in five places.  ONE definition, asked everywhere, with the
+ *  DIFFERENCES between those places supplied as WITNESSES by the caller — never
+ *  as a mechanism or a producer.  If this function ever needs to know who
+ *  produced the bytes to decide, the right conclusion is that a witness is
+ *  missing, not that it should dispatch.
+ *
+ *  `floor` is one river-fold quantum: below it, byte overlap is chance, not
+ *  evidence — the same line `identityBar`, the bridge's `attestedQ` and
+ *  recognition's site floor all draw.  `0` disables the floor, which is the
+ *  reading the callers that ask before any structure exists use.
+ *
+ *  THE THREE READINGS the callers need, and why each is a witness rather than a
+ *  branch here:
+ *
+ *   • `proper` — a PROPER part of the question (strictly shorter).  This is the
+ *     reading every tier that rejects a fragment uses.
+ *   • `whole` — the EQUALITY reading: only "the answer IS the question" counts,
+ *     because the caller has already handled a proper fragment elsewhere (a
+ *     recall tier's own subspan tests).
+ *   • `equate` — the response's own notion of "the same text" (whatever
+ *     `src/canon.ts` equates: case, width, whitespace).  A caller that has one
+ *     passes it; a caller that does not gets the byte-exact reading.  It is the
+ *     same fallback `resolve` already makes when an exact lookup misses.
+ *
+ *  The LITERAL EXEMPTION is deliberately NOT here: whether a span is the site's
+ *  own bytes at its own position is the CALLER's knowledge, and a caller states
+ *  it by not asking (see `segRestatesQuery` in types.ts, which returns false for
+ *  a literal span before reaching this). */
+export declare function restates(query: Uint8Array, bytes: Uint8Array, floor?: number, witnesses?: {
+    equate?: ((b: Uint8Array) => Uint8Array) | null;
+    proper?: boolean;
+    whole?: boolean;
+    /** THE POSITIONAL WITNESS: search from this offset, because the caller has
+     *  established that only material at or after it counts.  A transcript pasted
+     *  into a single response is the case that needs it — a caller's own prior
+     *  answer lies LATER in the query, after the root that would restate it — and
+     *  the reasoner's per-root `alreadyAnswered` guard asks exactly that question.
+     *  Omitted, the search starts at 0 and the reading is the plain one. */
+    from?: number;
+}): boolean;
+/** Whether the query span `[from, to)` lies inside a COMPLETED ASSISTANT TURN —
+ *  material the engine has already produced, so it is context rather than
+ *  something the asker is asserting.  Recognition and attention still see the
+ *  full transcript; what excludes these spans is the closure reading "this was
+ *  already answered", and it is a closure reading rather than a budget: a window
+ *  inside a prior reply is not a fresh constraint.
+ *
+ *  ONE definition of it.  `cursor` is the CALLER's own progress through `turns`
+ *  (they are ascending and each caller scans its candidates in ascending order),
+ *  so the amortised search is preserved exactly and a caller passes the same
+ *  holder for a whole scan: extracting the reading must not cost the scan. */
+export declare function insideAnsweredTurn(turns: ReadonlyArray<Span>, cursor: {
+    at: number;
+}, from: number, to: number): boolean;
+/** THE derivation state — the unit that crosses one inference.
+ *
+ *  Every field is read by the law or by the market's one cost ladder, and
+ *  nothing else travels.  A count of steps is a consequence (the cost), and
+ *  cycle protection belongs to the layer that walks a graph. */
+export interface DerivationState {
+    /** PRODUCT — the structure produced: what this derivation stands on. */
+    readonly product: Uint8Array;
+    /** ACCOUNTED — the asker's spans the producing transition priced.  A COST
+     *  quantity, and the producing mechanism's own judgement of what its answer
+     *  explains: cover leaves its computed spans out so the PASS-bridged bytes
+     *  they account for stay charged, while a corroborated substitution DOES
+     *  account for its span, because the mechanism paid a move for it. */
+    readonly accounted: ReadonlyArray<Span>;
+    /** REMAINDER — the asker's material no step has accounted for, each member at
+     *  or above one quantum.  Empty means the derivation is CLOSED. */
+    readonly remainder: ReadonlyArray<Span>;
+    /** COST — position on the one ladder (`graph-search.ts`'s MICRO/STEP/CONCEPT/
+     *  PASS); the market takes the lattice minimum over it. */
+    readonly cost: number;
+    /** FIXED — the producer SUPPLIED a fixed point: the query IS the context, so
+     *  no transition may consume this state.  Declared, never inferred. */
+    readonly fixed?: boolean;
+    /** USED — what the product speaks for.  An EMPTY set is itself a declaration
+     *  ("this answer voices nothing"); omitted means the layer must re-recognise
+     *  the product to decide for itself. */
+    readonly used?: ReadonlySet<number>;
+}
+/** A candidate continuation, as reported by the layer that knows the structure.
+ *  The layer says what it has; the law decides. */
+export interface Continuation {
+    /** The structure the transition would make the derivation's product. */
+    readonly product: Uint8Array;
+    /** CONTAINS — the transition's structure holds the product: a node in its
+     *  tree, or one contiguous byte run of it.  Resolved by the reporter.
+     *
+     *  SUFFICIENT FOR EVERY DECISION THIS CORE MAKES, and a boolean is the minimum:
+     *  the law reads it ONCE, as the admission gate, and that decision is binary —
+     *  may this state be consumed by this transition at all?  Every other decision
+     *  is fed by other witnesses, never by this one: the product's identity is
+     *  `resolve(product)`, progress is the window a move carries or the
+     *  `reaches` declaration, accounting is the span.  Carrying the reporter's
+     *  structure here would therefore be a dump of mechanism internals bought for
+     *  nothing.  The producers make it true by construction — a continuation is
+     *  built from the CURRENT product's own structure, never from a different one
+     *  — and test/133 pins the refusal when a reporter declares false. */
+    readonly contains: boolean;
+    /** REACHES — the transition MOVES: it reaches structure this derivation has
+     *  not consumed
+     *  (a node outside the walker's own set).  The second species of progress: a
+     *  step need not excuse itself with question material when it moves to new
+     *  structure.  Resolved by the reporter, declared by the transition — never
+     *  inferred from its producer. */
+    readonly reaches?: boolean;
+    /** What the transition accounts for, when it declares it.  A transition
+     *  taken from a CLOSED state has nothing to progress on, so it is the one
+     *  case that must say what it accounts for; a transition that carries the
+     *  remainder declares nothing and the law's own witness is used. */
+    readonly explains?: ReadonlyArray<Span>;
+    /** The transition's own moves, in ladder units. */
+    readonly cost: number;
+}
+/** CLOSED — nothing of the asker's material is left unaccounted. */
+export declare function closed(d: DerivationState): boolean;
+/** THE LAW, evaluated once.
+ *
+ *  Returns the spans the transition accounts for — the witness that lets it be
+ *  taken — or `null` when it is inadmissible.  Evaluating it once and advancing
+ *  the state with {@link advance} is the whole of a transition; asking twice for
+ *  the same pair would repeat the scan, which this module must not make anyone
+ *  do.
+ *
+ *      ¬FIXED  ∧  CONTAINS  ∧  ( CLOSED ∨ CARRIES ∨ MOVES )
+ *
+ *  Cost is not a term: it is the lattice order the market minimises over, and
+ *  neither is any budget — a cap decides with a number of work, this decides
+ *  with the remainder. */
+export declare function admissible(d: DerivationState, t: Continuation, query: Uint8Array, W: number): ReadonlyArray<Witness> | null;
+export declare function advance(d: DerivationState, t: Continuation, explains: ReadonlyArray<Witness>): DerivationState;
+/** What a layer offers the law: the next continuation of a state, or null when
+ *  it has none.  A layer OFFERS; the law disposes.
+ *
+ *  ONE OFFER, AND IT IS THE LAYER'S LAST: {@link closure} stops when the law
+ *  refuses what was offered, so a refusal is read as "no continuation exists".
+ *  A layer must not offer candidates one at a time and expect the walk to
+ *  continue after a refusal — its own fallbacks belong inside this function.
+ *  The producers do exactly that: they choose between the forward absorb and the
+ *  pivot before offering, and return null only when neither exists, which is why
+ *  the one offer the law can still refuse (a pivot without ownership, whose
+ *  material the answer does not carry) really is the last one. */
+export type Offer = (d: DerivationState) => Promise<Continuation | null>;
+/** THE CLOSURE — the walk of {@link advance} over the continuations `offer`
+ *  proposes, run until the layer has nothing further to offer or the law refuses
+ *  the one it offered.
+ *
+ *  ADMISSION is entirely the law's; TERMINATION is the layer's, and deliberately
+ *  so.  The remainder does not descend (draining it was implemented and refuted
+ *  — see the module note), so a walk cannot run forever only because the layer
+ *  offering continuations keeps its own cycle protection over a finite graph.
+ *  Nothing here counts steps, and nothing here decides admissibility. */
+export declare function closure(d: DerivationState, query: Uint8Array, W: number, offer: Offer, 
+/** Called for each step the law admits, with the state before and after. */
+onTaken?: (before: DerivationState, after: DerivationState, witnesses: ReadonlyArray<Witness>) => void, 
+/** Called when the law refused the continuation the layer offered. */
+onRefused?: (at: DerivationState) => void): Promise<DerivationState>;