@hviana/sema 0.9.1 → 0.9.2

package/dist/src/mind/traverse.js

@@ -7,13 +7,15 @@
 // project) live in match.ts — the elementary match-and-project operation.
 import { cosine } from "../vec.js";
 import { gistOf, read } from "./primitives.js";
-import { canonicalWindows, leafIdPrefix, leafIdRun } from "./canonical.js";
+import { canonicalWindows, chainReach, leafIdPrefix, leafIdRun, } from "./canonical.js";
 // Imported at the TOP, where every other import is.  They used to sit 800 lines
 // down under a note claiming the position mattered ("before trace module is
 // loaded") — it does not: an ES module's static imports are HOISTED, so the
 // file's line order never decides load order.  The note described an intention
 // the runtime does not honour; the imports move and the claim goes.
 import { decodeText } from "./rationale.js";
+import { latin1 } from "../bytes.js";
+import { windowIndex, witness } from "./evidence.js";
 //
 // Budgeted on the same terms as the reach memo below (caches.md): these three
 // maps are cleared on every write, but a long read-only session over a large
@@ -599,8 +601,10 @@ export function guidedNext(ctx, node) {
         ctx._edgeChoice.set(node, pick ?? -1);
     return pick;
 }
-/** Disambiguate among a node's learnt continuations by distributional
- *  support.  NOTE the `guide` contract: its VALUE is deliberately unused —
+/** Disambiguate among a node's learnt continuations: first by the question's
+ *  own witness of an establishing context (the exact tier, see
+ *  {@link askedContinuations}), then by distributional support.  NOTE the
+ *  `guide` contract: its VALUE is deliberately unused —
  *  only its PRESENCE gates disambiguation (a null guide means no query is in
  *  flight, so structural walkers keep plain first-edge behaviour).  The
  *  gist-cosine of short answer candidates against a query guide is dominated
@@ -621,13 +625,30 @@ export function chooseNext(ctx, id, guide) {
         return undefined;
     if (nx.length === 1 || !guide)
         return nx[0];
+    // THE EXACT TIER — the continuation the QUESTION names.  Every other
+    // disambiguation below reads popularity, and is right to refuse the gist (see
+    // the doc above); but the corpus also wrote down, for each continuation,
+    // WHICH QUESTIONS IT ANSWERS — its establishing contexts — and a question is
+    // not a gist.  When one of them is witnessed by the asker's bytes plus the
+    // node's own, that continuation is the one being asked for.  Measured on the
+    // 31.7M-node store: `Who is the father of Frederick II?` answered the
+    // citizenship fact (the most-poured of eight) while `Frederick II father` —
+    // one of the father fact's own establishing contexts — lay wholly inside the
+    // question.  Exact, so it ranks first (exact-vs-approximate.md); when nothing
+    // is witnessed the ladder below decides exactly as before.
+    const asked = ctx._edgeAsked;
+    const named = asked === null ? null : askedContinuations(ctx, id, nx, asked);
+    if (named !== null && named.length === 1)
+        return named[0];
     // Cap candidates at √N — the same bound the original chooseAmong used.
     // A hub context can accumulate thousands of continuations; the best-fit
     // one is among the first √N by insertion order (edges are never deleted,
     // so the oldest are the most established).  A strongly-supported edge
     // inserted beyond the cap is invisible here — the deliberate trade
-    // against paying O(fan-out) count reads on every disambiguation.
-    const capped = nx; // already the hub-capped prefix, by the read above
+    // against paying O(fan-out) count reads on every disambiguation.  Several
+    // continuations named EQUALLY by the question are told apart by the same
+    // ladder, over them alone.
+    const capped = named ?? nx; // already the hub-capped prefix, by the read above
     // Distributional-evidence disambiguation, consulting BOTH read-outs of the
     // evidence the training poured:
     //   1. prevCount — how many DISTINCT contexts predict this candidate (one
@@ -691,6 +712,184 @@ export function chooseNext(ctx, id, guide) {
     }
     return best;
 }
+/** The response canonicalizer's reading of `bytes` when it keeps every offset
+ *  — so a window found in the canonical bytes sits at the same place in the
+ *  asker's — else the bytes themselves.  Text canon is offset-preserving on
+ *  ASCII without interior whitespace runs; where it is not, the raw bytes are
+ *  read and a case-variant window simply does not match. */
+export function offsetCanon(ctx, bytes) {
+    if (ctx.canon === null)
+        return bytes;
+    const c = ctx.canon(bytes);
+    return c.length === bytes.length ? c : bytes;
+}
+/** The continuations of `id` that `asked` NAMES (see {@link
+ *  askedContinuations}) — for a caller holding material other than the whole
+ *  question: the multi-hop walk asks with what of the question no product has
+ *  restated yet.  null when none is named. */
+export function namedContinuations(ctx, id, asked) {
+    const nx = ctx.store.nextFirst(id, hubBound(ctx));
+    return nx.length === 0 ? null : askedContinuations(ctx, id, nx, asked);
+}
+/** The continuations of `id` (among `nx`) that the question NAMES: one of
+ *  their establishing contexts — a predecessor other than `id` itself — is
+ *  wholly witnessed by the question plus `id`'s own bytes (evidence.ts), with
+ *  the question supplying at least one window the node does not.  Ranked by
+ *  how much of the question witnesses it; null when none is named.
+ *
+ *  THE NODE'S OWN BYTES ARE MATERIAL because a derivation stands on them.  On
+ *  the second hop of `Where was the place of death of the director of film
+ *  Beat Girl?` the node is `Edmond T. Gréville` — reached, never written — and
+ *  its fact's establishing context `Edmond T. Gréville place of death` is held
+ *  by neither the question nor the node, only by both.  Measured over 5,236
+ *  held-out 2Wiki questions: such a context is wholly witnessed by the
+ *  question alone 69 times, by the question and the first hop 2,153 times.
+ *
+ *  BOUNDED: predecessor reads share one √N budget across the candidates (see
+ *  the loop below), asked cheapest first; past it the tier abstains for the
+ *  rest, metered, and the ladder decides as before.
+ *  Each form is read at most to the material's length — a form longer than
+ *  everything at hand cannot be wholly witnessed without repeating it. */
+function askedContinuations(ctx, id, nx, asked) {
+    return askedEntry(ctx, id, nx, asked).named;
+}
+/** The question spans that NAMED `pick` among `id`'s continuations — the
+ *  evidence a projection through that pick stands on, so a mechanism can
+ *  account for what the question said about it (mechanism-market.md:
+ *  evidence travels).  Empty when the question names no continuation of `id`
+ *  or names others. */
+export function askedEvidence(ctx, id, pick) {
+    const asked = ctx._edgeAsked;
+    if (asked === null)
+        return [];
+    const nx = ctx.store.nextFirst(id, hubBound(ctx));
+    const entry = askedEntry(ctx, id, nx, asked);
+    return entry.named?.includes(pick) ? entry.spans.get(pick) ?? [] : [];
+}
+function askedEntry(ctx, id, nx, asked) {
+    let memo = askedMemo.get(asked);
+    if (memo === undefined)
+        askedMemo.set(asked, memo = new Map());
+    const hit = memo.get(id);
+    if (hit !== undefined && !ctx.trace)
+        return hit;
+    const entry = askedContinuationsImpl(ctx, id, nx, asked);
+    memo.set(id, entry);
+    return entry;
+}
+/** One pick per node per question — every mechanism of a response asks the
+ *  same node about the same question (the guided-pick memo's own reason). */
+const askedMemo = new WeakMap();
+function askedContinuationsImpl(ctx, id, nx, asked) {
+    const none = { named: null, spans: new Map() };
+    const W = ctx.space.maxGroup;
+    // A SATURATED READ IS NOT A CANDIDATE SET.  When the continuations came back
+    // at the √N cap the read may have cut the named one off, so "none of these is
+    // named" and "this is the named one" are both unfounded — and this is exactly
+    // where witnessing would read most.  The tier abstains, metered, and the
+    // distributional ladder decides as it always has.
+    if (nx.length >= hubBound(ctx)) {
+        if (ctx.meter)
+            ctx.meter.askedReadsSaturated++;
+        return none;
+    }
+    const cache = getStructCache(ctx);
+    const ownCap = asked.bytes.length * W;
+    const own = offsetCanon(ctx, read(ctx, id, ownCap));
+    const ownIndex = windowIndex(own, W);
+    // Naming needs the question to say at least one window the node does not:
+    // when the node already holds every window of the question (the question IS
+    // this context, or a piece of it), nothing can be named, and nothing is read.
+    let beyond = false;
+    for (const key of asked.index.keys()) {
+        if (!ownIndex.has(key)) {
+            beyond = true;
+            break;
+        }
+    }
+    if (!beyond)
+        return none;
+    const indexes = [asked.index, ownIndex];
+    const formCap = asked.bytes.length + own.length;
+    // BOUNDED READS (bounded-reads.md): the decision reads at most √N
+    // establishing contexts — floored at the write side's own arity `chainReach(W)`
+    // so a store too small for √N to cover one fact's questions still decides.
+    // Candidates are asked CHEAPEST FIRST (fewest establishing contexts): a common
+    // reply established by hundreds of contexts would otherwise spend the whole
+    // allowance alone.  The order changes what is READ, never what wins: scores
+    // are compared afterwards in the continuations' own order.
+    let budget = Math.max(hubBound(ctx), chainReach(W));
+    const order = nx
+        .map((n, at) => ({ n, at, support: cachedPrevCount(ctx, n, cache) }))
+        .filter((c) => c.support >= 2) // only `id` establishes the rest
+        .sort((a, b) => a.support - b.support || a.at - b.at);
+    const scored = [];
+    for (const { n, at, support } of order) {
+        if (support > budget) {
+            if (ctx.meter)
+                ctx.meter.askedReadsSaturated++;
+            break;
+        }
+        budget -= support;
+        if (ctx.meter)
+            ctx.meter.askedPredecessorReads += support;
+        let score = 0;
+        let by = -1;
+        let spans = [];
+        for (const c of ctx.store.prevFirst(n, support)) {
+            if (c === id)
+                continue;
+            // The form's FIRST window decides most refusals: one short prefix read
+            // before the whole form is reconstructed (a conversation-length
+            // predecessor would otherwise be read in full to fail on its opening).
+            const head = offsetCanon(ctx, read(ctx, c, W));
+            if (head.length < W)
+                continue;
+            if (!indexes.some((ix) => ix.has(latin1(head))))
+                continue;
+            const form = read(ctx, c, formCap + 1);
+            if (form.length < W || form.length > formCap)
+                continue;
+            const w = witness(offsetCanon(ctx, form), indexes, W);
+            if (!w.complete || w.bytes < W)
+                continue;
+            if (w.bytes > score) {
+                score = w.bytes;
+                by = c;
+                spans = w.spans;
+            }
+        }
+        if (score > 0)
+            scored.push({ n, at, score, by, spans });
+    }
+    scored.sort((a, b) => a.at - b.at);
+    let best = [];
+    let bestBytes = 0;
+    let witnessed = null;
+    for (const { n, score, by } of scored) {
+        if (score > bestBytes) {
+            best = [n];
+            bestBytes = score;
+            witnessed = by;
+        }
+        else if (score === bestBytes)
+            best.push(n);
+    }
+    if (best.length === 0)
+        return none;
+    if (ctx.meter)
+        ctx.meter.askedContinuations++;
+    if (ctx.trace && witnessed !== null) {
+        ctx.trace.step("askedContinuation", [rItemShort(ctx, id, "node"), rItemShort(ctx, witnessed, "asked")], best.map((n) => rItemShort(ctx, n, "named")), `${nx.length} continuations — the question witnesses ` +
+            `${best.length === 1 ? "one's" : `${best.length}'`} own establishing ` +
+            `context (${bestBytes} question byte(s) beyond the node)`);
+    }
+    const evidence = new Map();
+    for (const c of scored)
+        if (best.includes(c.n))
+            evidence.set(c.n, c.spans);
+    return { named: best, spans: evidence };
+}
 /** The perceived gist of a candidate node, through the session gist cache.
  *  Re-gisting a candidate is a full river fold of its bytes — the measured
  *  recall bottleneck (a hub context offers up to √N continuations, EACH
@@ -776,6 +975,84 @@ export function allWindowsAreScaffolding(ctx, query) {
     }
     return sawOne;
 }
+/** Per offset of `bytes`: 1 when the W-window there is a stored form contained
+ *  in more than √N places (corpus-global scaffolding; see the floor below),
+ *  else 0.  Memoised per
+ *  byte array for the life of the store's read-only response. */
+export function hubWindows(ctx, bytes) {
+    const hit = hubWindowMemo.get(bytes);
+    if (hit !== undefined)
+        return hit;
+    const W = ctx.space.maxGroup;
+    // Floored at the write side's arity: inside ONE deposit's fold a window is
+    // already contained by up to `chainReach(W)` chunks and branches, so on a
+    // store of a few facts the √N reading would call every window frame — that
+    // is fold structure, not corpus commonality.
+    const bound = Math.max(hubBound(ctx), chainReach(W));
+    const hub = new Uint8Array(Math.max(0, bytes.length - W + 1));
+    for (let o = 0; o < hub.length; o++) {
+        const ids = leafIdRun(ctx, bytes, o, o + W);
+        const id = ids === null ? null : ctx.store.findBranch(ids);
+        if (id !== null && ctx.store.containersSlice(id, bound, 1).length > 0) {
+            hub[o] = 1;
+        }
+    }
+    hubWindowMemo.set(bytes, hub);
+    return hub;
+}
+const hubWindowMemo = new WeakMap();
+/** The query's SCAFFOLDING CORE, as spans: the bytes every W-window over which
+ *  is a hub (see {@link hubWindows}) — what is nothing but frame, where
+ *  {@link scaffoldExtents} is what a frame window reaches. */
+export function scaffoldSpans(ctx, query) {
+    const W = ctx.space.maxGroup;
+    const hub = hubWindows(ctx, query);
+    const n = hub.length;
+    if (n <= 0)
+        return [];
+    const spans = [];
+    let start = -1;
+    for (let i = 0; i < query.length; i++) {
+        let all = true;
+        for (let o = Math.max(0, i - W + 1); o <= Math.min(i, n - 1); o++) {
+            if (!hub[o]) {
+                all = false;
+                break;
+            }
+        }
+        if (all && start < 0)
+            start = i;
+        if (!all && start >= 0) {
+            spans.push([start, i]);
+            start = -1;
+        }
+    }
+    if (start >= 0)
+        spans.push([start, query.length]);
+    return spans;
+}
+/** The EXTENTS of the query's SCAFFOLDING windows, merged: every byte some
+ *  W-window reaches that is a stored form contained in more than √N places —
+ *  corpus-global commonality (commonality.md), the same "hub" reading as
+ *  {@link allWindowsAreScaffolding} and the bridge's `explainedSpan`.  A window
+ *  the store never saw is NOT scaffolding.  The extent, not the core, is what
+ *  a coverage test needs: a span that still holds one hub window can be
+ *  "carried" by any fact that holds that window. */
+export function scaffoldExtents(ctx, query) {
+    const W = ctx.space.maxGroup;
+    const hub = hubWindows(ctx, query);
+    const spans = [];
+    for (let o = 0; o < hub.length; o++) {
+        if (!hub[o])
+            continue;
+        const last = spans[spans.length - 1];
+        if (last !== undefined && o <= last[1])
+            last[1] = o + W;
+        else
+            spans.push([o, o + W]);
+    }
+    return spans;
+}
 // ── THE PREFIX SUPPLY ───────────────────────────────────────────────────────
 //
 // A RETRIEVAL capability, not a grounding one: "which trained forms does this

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

@@ -7,6 +7,7 @@ import type { MindConfig } from "../config.js";
 import type { Meter } from "../meter.js";
 import type { GraphSearch, Leaf, Seg, Site } from "./graph-search.js";
 import type { Rationale } from "./rationale.js";
+import type { WindowIndex } from "./evidence.js";
 import type { ContentFold, Grid } from "../geometry.js";
 /** One {@link MindContext._depositTrees} entry — see that field's doc.
  *
@@ -370,6 +371,14 @@ export interface MindContext extends GraphSearchHost {
      *  ordinary respond() and for the first turn of a conversation. */
     currentTurnStart: number;
     _edgeGuide: Vec | null;
+    /** The question currently being answered, as the material `chooseNext`'s
+     *  exact tier witnesses a continuation's establishing contexts against —
+     *  its bytes (canonical when the response's canon preserves offsets) and
+     *  their window index.  Set and cleared with `_edgeGuide`. */
+    _edgeAsked: {
+        bytes: Uint8Array;
+        index: WindowIndex;
+    } | null;
     _edgeChoice: Map<number, number>;
     _prevSeen: Set<number> | null;
     /** Session cache of node-id → perceived gist, for candidate scoring

package/docs/INDEX.md

@@ -19,24 +19,25 @@ proof in `test/` (pins that fail when the law is broken).
 | Change vector search        | `docs/architecture/exact-vs-approximate.md` + `docs/architecture/bounded-reads.md` | Scores propose, bytes dispose; ANN is bounded by `hubBound`                           |
 | Profile or bound work       | `docs/architecture/meter.md` + `docs/architecture/bounded-reads.md`                | `meter.ts` is write-only; counters are product, phases are hints                      |
 
-## Architecture laws (14)
+## Architecture laws (15)
 
-| Law | File                                        | Summary                                                                                                                                                | Pins                                         |
-| --- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
-| 1   | `docs/architecture/determinism.md`          | No `Math.random`/`Date.now` in behaviour; seed-derived randomness; corpus-determined tie-breaks                                                        | `test/20`                                    |
-| 2   | `docs/architecture/thresholds.md`           | Every decision cutoff derived in `geometry.ts` over D/W/N; no tunable knobs                                                                            | `test/40`, `test/64`                         |
-| 3   | `docs/architecture/exact-vs-approximate.md` | Vector scores rank only; identity via content-addressed lookup; five graded ladders                                                                    | `test/51`                                    |
-| 4   | `docs/architecture/cost-model.md`           | Single ladder `MICRO`/`STEP`/`CONCEPT`/`PASS`; weight `moves + PASS·unaccounted`; `STEP`-grade compare                                                 | `test/04`, `test/55`                         |
-| 5   | `docs/architecture/match-project.md`        | Shared `match.ts` family (`locate`/`alignGraded`/`frameSlots`/`project`); voicing gates belong to consumers                                            | `test/24`, `test/76`                         |
-| 6   | `docs/architecture/mechanism-market.md`     | `PipelineMechanism` (`floor`/`run`/`parse`); admissible-floor pruning, investment discipline, run-ahead bounds                                         | `test/01`, `test/04`, `test/153`             |
-| 7   | `docs/architecture/commonality.md`          | Three: global (`reachOf`+`dominates`), weave-local (`depth[]`), window rarity                                                                          | `test/17`, `test/34`                         |
-| 8   | `docs/architecture/bounded-reads.md`        | No per-query read grows with N; `hubBound=√N` enforced at store via LIMIT/probe/prefix caps                                                            | `test/77`, `test/90`                         |
-| 9   | `docs/architecture/store.md`                | `AbstractStore` owns dedup/indexing/batch; `store-sqlite.ts` is thin wrappers; canon index optional                                                    | `test/08`                                    |
-| 10  | `docs/architecture/fold-contract.md`        | `perceiveDeposit` and `perceive` agree; the read side names a branch as `intern` does; `contentLevels` is single boundary rule; no W/offset dependence | `test/59`, `test/63`, `test/148`, `test/152` |
-| 11  | `docs/architecture/memoization.md`          | `Precomputed` is per-response lazy cache (promise-cached async); `beginResponse`/`endResponse` lifecycle                                               | `test/42`                                    |
-| 12  | `docs/architecture/saturation.md`           | Every walk names a deciding saturation beside its cap; cap is safety net, not decision                                                                 | `test/27`, `test/16`                         |
-| 13  | `docs/architecture/meter.md`                | `meter.ts` is write-only work accounting; counts are exact, phases nest                                                                                | `test/55`                                    |
-| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law, one engine walks the layers           | `test/133`–`151`                             |
+| Law | File                                        | Summary                                                                                                                                                                                                                                                            | Pins                                         |
+| --- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| 1   | `docs/architecture/determinism.md`          | No `Math.random`/`Date.now` in behaviour; seed-derived randomness; corpus-determined tie-breaks                                                                                                                                                                    | `test/20`                                    |
+| 2   | `docs/architecture/thresholds.md`           | Every decision cutoff derived in `geometry.ts` over D/W/N; no tunable knobs                                                                                                                                                                                        | `test/40`, `test/64`                         |
+| 3   | `docs/architecture/exact-vs-approximate.md` | Vector scores rank only; identity via content-addressed lookup; six graded ladders                                                                                                                                                                                 | `test/51`                                    |
+| 4   | `docs/architecture/cost-model.md`           | Single ladder `MICRO`/`STEP`/`CONCEPT`/`PASS`; weight `moves + PASS·unaccounted`; `STEP`-grade compare                                                                                                                                                             | `test/04`, `test/55`                         |
+| 5   | `docs/architecture/match-project.md`        | Shared `match.ts` family (`locate`/`alignGraded`/`frameSlots`/`project`); voicing gates belong to consumers                                                                                                                                                        | `test/24`, `test/76`                         |
+| 6   | `docs/architecture/mechanism-market.md`     | `PipelineMechanism` (`floor`/`run`/`parse`); admissible-floor pruning, investment discipline, run-ahead bounds                                                                                                                                                     | `test/01`, `test/04`, `test/153`             |
+| 7   | `docs/architecture/commonality.md`          | Three: global (`reachOf`+`dominates`), weave-local (`depth[]`), window rarity                                                                                                                                                                                      | `test/17`, `test/34`                         |
+| 8   | `docs/architecture/bounded-reads.md`        | No per-query read grows with N; `hubBound=√N` enforced at store via LIMIT/probe/prefix caps                                                                                                                                                                        | `test/77`, `test/90`                         |
+| 9   | `docs/architecture/store.md`                | `AbstractStore` owns dedup/indexing/batch; `store-sqlite.ts` is thin wrappers; canon index optional                                                                                                                                                                | `test/08`                                    |
+| 10  | `docs/architecture/fold-contract.md`        | `perceiveDeposit` and `perceive` agree; the read side names a branch as `intern` does; `contentLevels` is single boundary rule; no W/offset dependence                                                                                                             | `test/59`, `test/63`, `test/148`, `test/152` |
+| 11  | `docs/architecture/memoization.md`          | `Precomputed` is per-response lazy cache (promise-cached async); `beginResponse`/`endResponse` lifecycle                                                                                                                                                           | `test/42`                                    |
+| 12  | `docs/architecture/saturation.md`           | Every walk names a deciding saturation beside its cap; cap is safety net, not decision                                                                                                                                                                             | `test/27`, `test/16`                         |
+| 13  | `docs/architecture/meter.md`                | `meter.ts` is write-only work accounting; counts are exact, phases nest                                                                                                                                                                                            | `test/55`                                    |
+| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law, one engine walks the layers                                                                                                                       | `test/133`–`151`                             |
+| 15  | `docs/architecture/evidence.md`             | A stored form is identified when the material at hand (question ∪ the node a derivation stands on) witnesses every byte of it, order-free; the question NAMES a continuation through its establishing context; a step it did not name pays from what is still owed | `test/154`                                   |
 
 ## Mechanisms (8)
 

package/docs/INVARIANTS.md

@@ -16,3 +16,4 @@
 | 12 | Meter contracts                      | `src/meter.ts:Meter,PhaseCost,time` `src/mind/pipeline-mechanism.ts:Precomputed.shared`                                                                                | `test/55`                      | `meter.md`                |
 | 13 | Saturation                           | `traverse.ts:edgeAncestors,types.ts:SaturationReason` `src/mind/junction.ts:junctionContainersFrom` `src/mind/resonance.ts:pivotInto`                                  | `test/27` `test/16`            | `saturation.md`           |
 | 14 | Closure                              | `src/mind/derivation.ts:admissible,advance,closeOver`                                                                                                                  | `test/133`–`151`               | `closure.md`              |
+| 15 | Witnessed evidence                   | `src/mind/evidence.ts:witness,windowIndex` `src/mind/traverse.ts:chooseNext,askedEvidence,namedContinuations,scaffoldExtents`                                          | `test/154`                     | `evidence.md`             |

package/docs/architecture/evidence.md

@@ -0,0 +1,113 @@
+# Witnessed Evidence — The Question Names the Step
+
+> **Law:** a stored form is identified by the material at hand when every one of
+> its bytes lies in a W-window that material holds — in any order, at any place,
+> and wherever each piece of the material came from. A step the question did not
+> name has to be paid for by material the question still owes.
+
+## The operation — `src/mind/evidence.ts`
+
+`witness(form, indexes, W)` reads one form against a list of window indexes
+(`windowIndex`). It is the order-free reading of correspondence, beside
+`alignRuns` (which produces runs) and `junctionContainersFrom(…, unordered)`
+(which finds containers). It is exact, deterministic and linear: one index per
+source and one probe per window of the form. A window is credited to the LAST
+source that holds it, so source 0 (the question) is credited only with what
+nothing else at hand supplies. A form shorter than W is never witnessed.
+
+## Where the material comes from
+
+The corpus records, for every continuation, the questions that establish it: its
+predecessors. A 2Wiki fact `The father of Frederick II is Peter III of
+Aragon.`
+is established by `Frederick II` and by `Frederick II father`. The asker's
+question rarely repeats either one byte for byte, but it often holds every byte
+of one of them.
+
+The derivation stands on more than the question. The node it is following is
+material too. On the second hop of
+`Where was the place of death of the
+director of film Beat Girl?` the node is
+`Edmond T. Gréville`, which the first hop reached and the asker never wrote. The
+establishing question `Edmond T.
+Gréville place of death` is held by neither the
+question nor the first hop's fact, only by both. Measured over 5,236 held-out
+2WikiMultihopQA compositional questions, such a context is wholly witnessed by
+the question alone 69 times, and by the question plus the first hop 2,153 times.
+
+## Its consumers
+
+| Where                             | What it decides                                                                                                                                                                                                                                                                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `chooseNext` (traverse.ts)        | **The exact tier.** It names the continuation one of whose establishing contexts (other than the node) is witnessed by the question plus the node, with the question supplying at least one window the node does not. It ranks first among the readings; the distributional ladder decides only when nothing is named, or among continuations named equally. |
+| `askedEvidence` (traverse.ts)     | The question spans that named a pick. A mechanism projecting through the pick accounts for them, because evidence travels (mechanism-market.md). Recall's argument binding uses this.                                                                                                                                                                        |
+| `preConsumed` (pipeline.ts)       | When a grounding does not declare `used`, what it spoke for is the forms inside its answer that the question already holds. The entity the answer added stays pivotable.                                                                                                                                                                                     |
+| The walk (reasoning.ts)           | A pivot is NAMED when one of its continuation's establishing contexts is witnessed by what of the question no product has said yet, plus the pivot. A named pivot MOVES. An unnamed one is offered only while the derivation still owes something, and the law then decides by carrying.                                                                     |
+| Cover sites (mechanisms/cover.ts) | A FRAGMENT is a form that sits inside other forms, has several continuations, and leaves at least one window of the question beyond it. It answers other questions, so it leads somewhere for this question only when the question names one of its continuations.                                                                                           |
+
+A cover span made of nothing but scaffolding (every window a hub,
+`scaffoldSpans`) is not accounted. The form recognised there, such as the song
+`What` in the trained store, is one of thousands the bytes could name. This is
+measured only on the trained store (`What country is Jerry Bock a citizen of?`
+was won by `The performer of What is Melinda Marx.` glued onto the right fact).
+A synthetic fixture could not reproduce that regime, because content addressing
+folds every filler's `What` into a handful of shared nodes, so no suite test
+pins this rule.
+
+## What the question owes
+
+The derivation is born owing only its discriminative material. The bytes a
+corpus-global scaffolding window reaches (`scaffoldExtents`, the same "hub"
+reading as `allWindowsAreScaffolding` and the bridge's `explainedSpan`) are
+nobody's debt. Otherwise a step could claim to pay `Who is the` by restating
+`is`, which every fact holds. Pricing is untouched: the ladder still charges
+every unexplained byte, because for a question made only of scaffolding,
+covering those bytes is the evidence. Making scaffolding free in the market was
+measured and refused, because it changed dialogue answers
+(`How are you
+today?`).
+
+The hub reading behind `scaffoldExtents` is floored at `chainReach(W)`
+containers. Inside one deposit's fold, a window is already contained by up to
+that many chunks and branches, so on a store of a few facts the √N reading would
+call every window frame. That count measures fold structure, not corpus
+commonality (`test/22`'s two-fact chains are exactly that regime).
+
+## Bounds
+
+The exact tier reads at most √N establishing contexts per decision, floored at
+`chainReach(W)`. It asks the cheapest candidates first and compares scores
+afterwards in the continuations' own order. It abstains, metered as
+`askedReadsSaturated`, in two cases: the continuation read came back at the √N
+cap, or the question holds no window the node lacks. One short prefix read
+refuses most predecessors before a whole form is reconstructed. Picks are
+memoized per node per question.
+
+## Measured
+
+| Measure                                                                                | Before | After  |
+| -------------------------------------------------------------------------------------- | ------ | ------ |
+| 2Wiki held-out fixture (300 rows, deposited as `wiki2.ts` does), compositional correct | 13/133 | 47/133 |
+| Same fixture, pivot steps                                                              | 3      | 90+    |
+| Same fixture, inference correct                                                        | 8/37   | 6/37   |
+
+The inference drop is real. Two hops of `father` from a question that says
+`father` once, as in `paternal grandfather`, used to be reached by
+over-extension and are no longer. The store holds no evidence that `grandfather`
+composes `father` twice.
+
+On the 31.7M-node store's 116-query battery, two answers became correct
+(`What country is Jerry Bock a citizen of?` and
+`What is the country of citizenship of Frederick II?`), two lost a junk
+composition, three changed between wrong answers, and no correct answer was
+lost. CPU was 150 s against two baseline runs of 139 s and 166 s, inside the
+noise. The deterministic read counters rose about 20% (`bytesRead`,
+`nodeRecords`), with ANN queries unchanged.
+
+## Pins
+
+- `test/154` — witnessing semantics. The named continuation beats the
+  most-poured one. The second hop is named by the question plus the introduced
+  entity, whatever grounded the first hop. A question that names no further step
+  is not extended. A fragment voices none of its continuations unless the
+  question names one. Each assertion was verified by mutation.

package/docs/architecture/exact-vs-approximate.md

@@ -1,4 +1,4 @@
-# Exact vs Approximate — The Law and Its Five Ladders
+# Exact vs Approximate — The Law and Its Six Ladders
 
 Vector scores (`resonate` / `resonateHalo`) are RaBitQ **estimates**. They rank
 candidates and gate broad regions; they never decide identity. Identity is
@@ -15,17 +15,18 @@ thresholds gate breadth, not truth.
 
 ## Graded evidence ladders
 
-Five subsystems share one shape — **exact → distributional → geometric** — with
+Six subsystems share one shape — **exact → distributional → geometric** — with
 earlier tiers strictly preferred. Never reorder tiers; never let an approximate
 tier override an exact one.
 
-| # | Site               | Ladder (strong → weak)                                                                                                   | File                                      |
-| - | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
-| 1 | `resolve`          | exact content-addressed fold → `canonResolve` (equivalence class, hash-then-verify)                                      | `mind/primitives.ts`                      |
-| 2 | `locate`           | exact bytes → halo role → gist                                                                                           | `mind/match.ts`                           |
-| 3 | `alignGraded`      | literal W-gram runs → halo-matched sites + climb proposals (weave)                                                       | `mind/match.ts` / `pipeline-mechanism.ts` |
-| 4 | `bridge`           | junction containers → edge → synonym → whole-gist                                                                        | `mind/resonance.ts`                       |
-| 5 | `crossRegionVotes` | exact containers → single synonym → double → `structuralResonance` (synthetic gist, gated hardest — no byte containment) | `mind/attention.ts`                       |
+| # | Site               | Ladder (strong → weak)                                                                                                                        | File                                      |
+| - | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| 1 | `resolve`          | exact content-addressed fold → `canonResolve` (equivalence class, hash-then-verify)                                                           | `mind/primitives.ts`                      |
+| 2 | `locate`           | exact bytes → halo role → gist                                                                                                                | `mind/match.ts`                           |
+| 3 | `alignGraded`      | literal W-gram runs → halo-matched sites + climb proposals (weave)                                                                            | `mind/match.ts` / `pipeline-mechanism.ts` |
+| 4 | `bridge`           | junction containers → edge → synonym → whole-gist                                                                                             | `mind/resonance.ts`                       |
+| 5 | `crossRegionVotes` | exact containers → single synonym → double → `structuralResonance` (synthetic gist, gated hardest — no byte containment)                      | `mind/attention.ts`                       |
+| 6 | `chooseNext`       | an establishing context witnessed by the question ∪ the node (evidence.md) → distributional support (prevCount, poured mass) → first-inserted | `mind/traverse.ts`                        |
 
 ## Asymmetries (attention)
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@hviana/sema",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "repository": {
     "type": "git",

package/src/meter.ts

@@ -265,6 +265,19 @@ export class Meter {
   /** Times the reasoner pivoted on a span its answer contains and stepped
    *  across that fact. */
   pivotSteps = 0;
+  /** `chooseNext` picks the question NAMED — a continuation one of whose own
+   *  establishing contexts the question (plus the node) wholly witnesses
+   *  (traverse.ts, the exact tier). */
+  askedContinuations = 0;
+  /** Predecessor rows that exact tier read, against its shared √N budget. */
+  askedPredecessorReads = 0;
+  /** Times the tier abstained on a read it could not trust: the continuations
+   *  came back at the √N cap, or its predecessor budget ran out before every
+   *  continuation was asked about — the distributional ladder decided. */
+  askedReadsSaturated = 0;
+  /** Cover sites dropped as FRAGMENTS whose several continuations the question
+   *  names none of (mechanisms/cover.ts). */
+  unaskedFragments = 0;
   /** Canon probes REFUSED because the canon budget ran out — the one thing the
    *  budget does that nothing could see.  The budget itself is derived
    *  (`bytes.length · chainReach(W)²`, recognition.ts), and the cheap exact route