@hviana/sema 0.8.1 → 0.8.3

package/src/geometry.ts

@@ -155,6 +155,27 @@ export function profileCapacity(D: number): number {
   return Math.max(1, Math.floor(Math.sqrt(D)));
 }
 
+/**
+ *  The POOLED-vote significance floor, and the derivation lives here because
+ *  its PREMISE is a property of the caller's weighting.
+ *
+ *  DERIVATION (docs/architecture/thresholds.md §2): a maximally-specific region
+ *  contributes at most `ln N` to a pooled vote, so `ln(N) + 1/2` sits half a
+ *  unit above ONE region's ceiling — it demands corroboration BEYOND a single
+ *  region, which is what makes it a consensus bar rather than a resonance bar.
+ *
+ *  PREMISE: that per-region ceiling is an IDF, `ln(N/c)` — attention.ts's
+ *  `inverse` mode, the mode every non-test caller runs.  The other two modes
+ *  weight a region by `ln(1+c)` (`direct`) or `ln(N/c) + ln(1+c)` (`combined`),
+ *  i.e. `ln N + ln(1 + 1/c)`, so they exceed the premise's ceiling by at most
+ *  `ln 2` — a DERIVED bound, not a hole: the floor stays within `ln 2` of its
+ *  own premise in every mode, and exactly on it in `inverse`.
+ *
+ *  MEASURED: the floor is read on the pooled vote (`commitVotes`, `recall`,
+ *  `cast`).  Across 27 anchors on 6 queries, 11 cleared it by the sum and NONE
+ *  by a single region's peak — gating on one region would refuse every elected
+ *  root.
+ */
 export function consensusFloor(N: number): number {
   return Math.log(N) + 1 / 2;
 }

package/src/meter.ts

@@ -206,6 +206,104 @@ export class Meter {
   /** Candidates the decider weighed. */
   candidates = 0;
 
+  // ── Graph search: the fact join (DIRECTION) ─────────────────────────────
+  //
+  // The join's outcome was observable ONLY through the rationale, and the
+  // rationale PERTURBS the search (measured: appending text to a refusal note
+  // changed a traced answer).  These four counters are the untraced view — the
+  // same surface every other work counter uses, incremented where the decision
+  // is made, never behind a trace guard.
+  /** `deriveThrough` yielded — a fact was reached through the subject the query
+   *  never named. */
+  joinFired = 0;
+  /** Refused: no key names the entity and the tail together.  (A key that
+   *  resolves but leads nowhere is not "refused" — it is not the relation, so
+   *  the scan simply moves on; there is no counter for a case the loop cannot
+   *  reach.) */
+  joinNoKey = 0;
+  /** Refused: the fact contains no entity that leads anywhere. */
+  joinNoEntity = 0;
+  /** `recompleteNode` re-covered a produced form — the descent that decomposes
+   *  a completion by ITS OWN kids.  Without this the descent is invisible: a
+   *  caller could see the chain's result but not whether the recomposition
+   *  happened, so "the recursion stopped" and "the recursion never ran" were
+   *  indistinguishable from the counters alone. */
+  recompletes = 0;
+
+  // ── Mind: the multi-hop pivot (EXTENSION) ───────────────────────────────
+  //
+  // `pivotStep` was observable only through the rationale, and the rationale
+  // perturbs the search (measured).  How far the reasoner hopped is a
+  // BEHAVIOUR, so it needs an untraced view: one counter, incremented where the
+  // step is emitted.
+  /** Times the reasoner pivoted on a span its answer contains and stepped
+   *  across that fact. */
+  pivotSteps = 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
+   *  is deliberately unbudgeted, so this counter says exactly when the expensive
+   *  route was priced out.  Counted where the fact happens (the `!canonBudget`
+   *  refusal), not where the probe is called. */
+  canonProbesDenied = 0;
+  /** The pipeline's remainder AT THE DECISION POINT, in bytes: what the grounded
+   *  answer plus the pre-computed spans left unexplained, after the same W floor
+   *  the fuse gate uses.  This is the quantity that licenses (or refuses) the
+   *  post-grounding extension and the fusion — it was computed, used, and never
+   *  published, so nothing could measure what a search had LEFT when it decided.
+   *  Read with {@link postGroundingRemainderSpans}. */
+  postGroundingRemainderBytes = 0;
+  /** How many spans that remainder consists of (each at least one W window). */
+  postGroundingRemainderSpans = 0;
+  /** Times `fuseAttention` produced a FUSED answer — not times it was called.
+   *  It is entered whenever the query has a remainder ≥ W and returns early when
+   *  there is nothing to bridge (`containsSpan`, a lone root, an empty pass), so
+   *  the call and the fact are different things and only the fact is counted.
+   *  Its own rationale step reports the fusion; this is the untraced view, and
+   *  its cost is one bridging edge: `fuseRuns · STEP`. */
+  fuseRuns = 0;
+  /** Steps the post-grounding EXTENSION took — pivots plus forward-absorbs.
+   *  `pivotSteps` counts only the former, so before this the extension's COST was
+   *  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. */
+  reasonCarriedBytes = 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. */
+  pivotProbes = 0;
+  /** Branch nodes the pivot's probe cap withheld (`branchCount − probeCap`, over
+   *  every call).  A capacity fact, not a verdict: the sweep is breadth-first,
+   *  so the probes it DOES spend are the largest regions, and recognition still
+   *  contributes every exact containment candidate regardless of the budget.
+   *  Read it with {@link pivotProbes} — one says the work, the other the
+   *  shortfall. */
+  pivotBranchesUnprobed = 0;
+
+  // ── Mind: the cover's connector assembly (LIMIT) ────────────────────────
+  //
+  // The cover's `run` is 91% of a hub query's time (`"Hello."`: 2.7 s of 3.0 s)
+  // and holds its ~270 MB peak, and none of it was countable: `searchPushes`
+  // and `candidates` do not see the connector assembly.  These two counters are
+  // the untraced view of it.
+  /** `bridge` calls the cover makes assembling connectors (pairwise + n-ary). */
+  coverBridges = 0;
+  /** Continuations a CHAIN hop offered the search.  Bounded by the question
+   *  (`ceil(queryLen / W)`) rather than by the corpus's fan-out — measured on a
+   *  hub of degree 1083, offering every continuation grew the chart to 3113 outs
+   *  and cost a 270 MB peak / 256 MB OOM for a two-word question. */
+  chainOffers = 0;
+  /** Σ byte-allowance the n-ary interior passes those bridges.  The allowance
+   *  is `middleBytes + (m + 1) * W` — every intermediate answer's bytes plus
+   *  one window of glue per joint — so it is the quantity that grows with a hub
+   *  query's answers, and the first thing to read when the peak moves. */
+  coverAllowanceBytes = 0;
+
   // ── Phases ──────────────────────────────────────────────────────────────
 
   private readonly _phases = new Map<string, PhaseCost>();

package/src/mind/attention.ts

@@ -180,6 +180,10 @@ export interface ConsensusAnchorTrace {
 
   pooledVote: number;
   idfVote: number;
+  /** The LARGEST single-region contribution behind this anchor — the bar
+   *  recall's own gate reads (mechanisms/recall.ts).  Published so the one
+   *  decision-making quantity the climb computes is not invisible. */
+  peak: number;
 
   candidateBreadth: number;
   contributingVotes: number;
@@ -1243,15 +1247,18 @@ export async function voteRegions(
       }
       contrastiveMargin = margin;
       // Scaled by what this region does NOT address — see `cov` above.
-      const noiseFloor = estimatorNoise(ctx.store.D) * (1 - cov);
-      if (margin <= noiseFloor) {
+      // The bar THIS gate applies: the estimator's noise scaled by what the
+      // region does NOT address (`cov`).  ONE definition, used by the rejection
+      // path below and by the voted payload — the trace reports the applied bar.
+      const appliedFloor = estimatorNoise(ctx.store.D) * (1 - cov);
+      if (margin <= appliedFloor) {
         recordRegion("contrastive-margin-rejection", {
           selected,
           reachNode: voterId,
           idf,
           dfWeight: wf,
           contrastiveMargin: margin,
-          contrastiveNoiseFloor: noiseFloor,
+          contrastiveNoiseFloor: appliedFloor,
           ...(contrastiveRival ? { contrastiveRival } : {}),
         });
         continue;
@@ -1305,7 +1312,12 @@ export async function voteRegions(
       ...(contrastiveMargin !== undefined
         ? {
           contrastiveMargin,
-          contrastiveNoiseFloor: estimatorNoise(ctx.store.D),
+          // THE BAR THE GATE ACTUALLY APPLIED — the same expression
+          // the rejection path's `appliedFloor` defines, inline here because
+          // this payload is built in a scope that does not carry that local.
+          // Publishing the raw estimatorNoise(D) instead made a region that
+          // PASSED look closer to its limit than it was.
+          contrastiveNoiseFloor: estimatorNoise(ctx.store.D) * (1 - cov),
           ...(contrastiveRival ? { contrastiveRival } : {}),
         }
         : {}),
@@ -1438,7 +1450,15 @@ export function poolVotes(
     },
     pool,
   };
-  lightestDerivation(system);
+  // THE SEARCH WAS THE ONE LAYER WITH NO TIME.  The climb's phases are timed
+  // (voteRegions, structuralResonance, crossRegion) but the pooled derivation
+  // was not, so any cost or gain inside it stayed invisible.
+  // `timeSync`, not `time`: the search is SYNCHRONOUS, and wrapping it in a
+  // promise only to time it would make the profiled path wait where the
+  // unprofiled one does not (meter.ts's own contract).
+  if (ctx.meter) {
+    ctx.meter.timeSync("climb.derivation", () => lightestDerivation(system));
+  } else lightestDerivation(system);
 
   const votes = new Map<number, number>();
   const votesIdf = new Map<number, number>();
@@ -1476,12 +1496,24 @@ export function poolVotes(
   // The LARGEST single region's contribution to this anchor's pooled vote.
   // The pool is a SUM (deliberately — see the pooling note above), so it says
   // how much evidence there is in total, never whether any ONE place in the
-  // query carries evidence on its own.  Consumers that hold an anchor to
-  // consensusFloor(N) = ln(N) + 1/2 need the latter: that bar prices ONE
-  // region's maximally-discriminative evidence (ln N is the IDF of content
-  // reaching a single context), so comparing a six-region sum against it is a
-  // dimensional error.  Recorded here, beside the count, because this is the
-  // only place the per-region contributions are still separable.
+  // query carries evidence on its own.  Recorded here, beside the count,
+  // because this is the only place the per-region contributions are still
+  // separable.
+  //
+  // THE BAR IS THE POOLED FLOOR, AND IT WAS ONCE CLAIMED OTHERWISE HERE.
+  // This comment used to say that holding an anchor to consensusFloor(N)
+  // "prices ONE region's evidence", so comparing a six-region sum against it
+  // was "a dimensional error".  THAT WAS FALSE.  `thresholds.md` §2 derives
+  // `consensusFloor` as the POOLED-vote significance floor ("each region
+  // contributes at most ln(N/c) <= ln(N); ln(N) + 1/2 demands ..."), and the
+  // climb weights by IDF, so the sum and the floor are in ONE dimension —
+  // which is exactly why `recall.ts` gates `forest[0].idfVote` against it and
+  // why `commitVotes` does too.  The other two weighting modes DO leave that
+  // dimension (by at most ln 2, two-sided: `direct` deflates a region and
+  // `combined` inflates it), and the gates therefore read the IDF sum, which
+  // is mode-independent; `test/55` tests 19 and 20 pin both halves — the sum
+  // as the reading the bar is derived for, and the absence of any gate
+  // inversion across the three modes.
   const regionPeak = new Map<number, number>();
   const steps: DerivationStep[] = [];
   let order = 0;
@@ -1665,6 +1697,7 @@ export function commitVotes(
         anchor,
         vote,
         peak: regionPeak.get(anchor) ?? 0,
+        idfVote: votesIdf.get(anchor) ?? 0,
         start: s.start,
         end: s.end,
         breadth: (regionSupport.get(anchor) ?? 0) / totalRegions,
@@ -1674,6 +1707,16 @@ export function commitVotes(
         ),
       };
     })
+    // THE ORDER IS NOT A PREFERENCE: with equal evidence it decides ADMISSION,
+    // through the stable sort and the first-come overlap absorption below.
+    // Measured on test/34's corpus, query "red": the two candidates (`red
+    // circle` and `red square`) carry IDENTICAL `vote` and IDENTICAL `idfVote`
+    // (1.3863 each, three seeds), so this comparator leaves them tied and the
+    // stable sort keeps the ENUMERATION order — which is corpus-determined and
+    // admits `red square`, 60/60 seeds.  Adding an id tie-break (`|| a.anchor -
+    // b.anchor`) picks `red circle` instead and makes a single region reach the
+    // JOINT context, which is the premise `test/34` exists to protect.  The
+    // gates read IDF; this line only decides who gets looked at first.
     .sort((a, b) => b.vote - a.vote);
   const overlaps = (a: Attention, b: Attention) =>
     a.start < b.end && b.start < a.end;
@@ -1719,6 +1762,13 @@ export function commitVotes(
       rank,
       pooledVote: point.vote,
       idfVote: votesIdf.get(point.anchor) ?? 0,
+      // The LARGEST single-region contribution behind this anchor — the bar
+      // recall's own gate reads (mechanisms/recall.ts: forest[0].peak > LN2),
+      // and until now the only decision-making quantity the climb computed and
+      // did not publish.  `regionPeak` reached `ranked` (see its build below)
+      // and stopped there.  Published, not recomputed: the value is the one the
+      // climb already carries.
+      peak: point.peak,
       candidateBreadth: regions.length,
       contributingVotes: regionAxioms.get(point.anchor) ?? 0,
       contributingEvidence: regionSupport.get(point.anchor) ?? 0,
@@ -1748,6 +1798,18 @@ export function commitVotes(
     let passesConsensusFloor: boolean | undefined;
     let pastLeadingSaturation: boolean | undefined;
     let tiedWithDominant: boolean | undefined;
+    // ── ONE OF THREE ADMISSIONS, AND THEY ARE NOT THE SAME READING ────────
+    // This block admits by VOTES: per-region evidence pooled, gated on the
+    // natural break and on consensusFloor, with the dominant allowed to bypass
+    // both.  `structuralResonance` admits by a MARGIN over the estimator's own
+    // noise, and `crossRegionVotes` admits by STRUCTURE (which regions may pair
+    // at all, with at least one side individually discriminative).  Read
+    // together they look like one policy written three times; they are three
+    // different measurements of the same question ("is this evidence?"), and
+    // unifying them would average three readings into one — the mistake
+    // `extraction.ts` records as "do not unify the two into one machine".
+    // What they DO share, and must keep sharing, is the discipline of deriving
+    // every bar from D/W/N rather than choosing it (thresholds.md).
     const rejectionReasons: AnchorRejectionReason[] = [];
     if (absorbed) {
       status = "overlap";
@@ -1757,9 +1819,75 @@ export function commitVotes(
       pastLeadingSaturation = pastLeading;
       const vote = votesIdf.get(point.anchor) ?? 0;
       if (roots.length === 0) {
-        // The first non-overlapping root is DOMINANT and bypasses the two
-        // vote thresholds (it always grounds) — only the leading-saturation
-        // gate still applies to it.
+        // THE DOMINANCE PRIVILEGE, AND THE TENSION IT CARRIES (measured).
+        //
+        // The first non-overlapping candidate is DOMINANT: it bypasses both
+        // vote gates below and grounds on its own; only the leading-saturation
+        // gate still applies to it.  The privilege is load-bearing — analogies,
+        // substitutions and composed contexts are precisely candidates the
+        // query does NOT contain, and the engine loses them without it.
+        //
+        // WHICH candidate receives it, though, is decided by this loop's ORDER.
+        // That order comes from `ranked`, and when two candidates carry equal
+        // evidence the stable sort preserves the ENUMERATION order, so the
+        // privilege is allocated by an ordering rather than by a rule.
+        //
+        // Measured on test/34's corpus, query "red":
+        //
+        //   0:#77 vote=1.3863 idf=1.3863 [0,3) | 1:#49 vote=1.3863 idf=1.3863 [0,3)
+        //
+        // Both candidates (`red square` #77, `red circle` #49) have IDENTICAL
+        // `vote` AND IDENTICAL `idfVote` over the SAME support span, so the
+        // comparator leaves them tied, the second is absorbed as "overlap", and
+        // the first grounds.  With this build's enumeration order that first is
+        // `red square`, 60/60 seeds, and `red circle` — the JOINT context — is
+        // never reached by "red" alone.  That is the premise test/34 exists to
+        // protect: no single region reaches the joint context, which is what
+        // makes the binding query unreachable without direct region
+        // interaction.
+        //
+        // THE TENSION: the premise therefore holds BY ENUMERATION ORDER, not by
+        // a rule, so any change to this ordering can move the privilege onto the
+        // joint context and let one region reach it.  Measured: adding
+        // `|| a.anchor - b.anchor` — the lowest-id tie-break that AGENTS.md §2
+        // sanctions as an equivalent corpus-determined tie-break — does exactly
+        // that: "red" then attends to `red circle`, test/34 fails 6/1, and the
+        // canonical suite reports 1 failure.
+        //
+        // TWO ATTEMPTS TO MAKE IT A RULE, BOTH REFUTED BY MEASUREMENT:
+        //
+        //  1. EVIDENCE SEPARATION.  Grant the privilege only when the first
+        //     candidate's evidence is separated from the next distinct
+        //     candidate's by more than the co-dominant band (sqrt(k) *
+        //     estimatorNoise(D)).  Refuted: that band exists to ADMIT the
+        //     anchors the estimator cannot separate from the dominant — its own
+        //     documented purpose — so withholding the privilege on ties removes
+        //     the very case it was written for.  Suite: 4 failures (the two
+        //     co-dominant band laws, breadth/scale invariance, test/29 D2).
+        //
+        //  2. QUERY-OWNED CONTENT.  Grant the privilege only to a candidate
+        //     that IS a recognised region's identity (regions.some(r => r.id ===
+        //     point.anchor)).  Measured: for "circle" that identity IS the
+        //     ranked candidate, so the privilege stays and `circle` grounds; for
+        //     "red" the identity is the `red` node itself while the candidates
+        //     are the conjunctions, so neither is privileged; for "red then
+        //     circle" the composed context carries idf 3.958 and clears both
+        //     gates on its own evidence.  All four control queries came out
+        //     right — and the suite: 10 failures, six of them in the
+        //     analogy/counterfactual/CAST suites ("an analogy still transfers
+        //     from a structure the query never names"; "a substitute the query
+        //     NAMES may still be voiced").  Refuted: the privilege exists to
+        //     admit what the query does NOT contain, so identity is the wrong
+        //     axis.
+        //
+        // WHAT A FUTURE ATTEMPT MUST RESPECT: whatever allocates this privilege
+        // has to (a) keep it available to candidates the query does not contain
+        // — analogies, substitutions, compositions — and (b) not depend on the
+        // estimator's ordering among anchors of equal evidence, because that
+        // ordering is not a fact about the corpus.  No lever satisfying both has
+        // been found.  Until one is, this premise rests on the enumeration order
+        // recorded above, and test/34 is the only test that notices if it
+        // moves.
         dominant = true;
         if (pastLeading) {
           status = "root";
@@ -1768,8 +1896,15 @@ export function commitVotes(
           rejectionReasons.push("leading-saturation");
         }
       } else {
-        passesNaturalBreak = vote >= rootCut;
-        passesConsensusFloor = vote >= floor;
+        // THE FLOOR AND THE BREAK READ THE IDF WEIGHTING.  `floor` is derived
+        // for pooled IDF-weighted votes, and `rootCut` comes from the IDF
+        // distribution (`idfDesc`), so gating the mode-dependent `vote` against
+        // either let a weighting mode change an admission (measured: anchor 87,
+        // inverse 2.682 admitted vs direct 1.468 refused).  Reading the IDF sum
+        // makes the verdict mode-independent, and changes nothing in the
+        // engine's own mode, where the two readings coincide.
+        passesNaturalBreak = point.idfVote >= rootCut;
+        passesConsensusFloor = point.idfVote >= floor;
         // CO-DOMINANT — an anchor the estimator cannot separate from the
         // dominant inherits the dominant's exemption, because that exemption's
         // only warrant is being TOP, and "top" is not a fact about the corpus
@@ -2467,6 +2602,13 @@ export async function structuralResonance(
     });
   };
 
+  // ── ADMISSION BY MARGIN, not by votes (see voteRegions' note) ─────────
+  // What this site measures: how far the best ANN proposal's effective score
+  // (score × semanticConfidence) stands above the runner-up's, against
+  // `estimatorNoise(D)`.  What it does NOT measure: how many regions voted,
+  // or whether the query's regions agree — that is voteRegions' question, and
+  // here a synthetic gist has already replaced them.  The two bars are both
+  // derived (thresholds.md), and neither is a tuning of the other.
   let selected: StructuralResonanceProposal | null = null;
   let selectedReach: AncestorReach | null = null;
   let selectedIdf = 0;
@@ -2582,6 +2724,15 @@ async function crossRegionVotes(
   // successfully reconstructed while probing one pair must not be read and
   // perceived again while probing another pair in the same climb.
   const siblingGistMemo = new Map<number, CachedSiblingGist>();
+  // ── ADMISSION BY STRUCTURE, not by a bar (see voteRegions' note) ──────
+  // What this site decides: WHICH regions may pair at all — a region that
+  // already voted (individually discriminative), or a KNOWN non-voting one as
+  // the weak side of a pair whose other side voted; never two non-voting
+  // regions, and never a span contained in a maximal one whose reading is
+  // exact.  The bar (the container's idf) comes later, on the candidate.  So
+  // its "rejection reasons" name structural disqualifications — a different
+  // vocabulary because it answers a different question, and the three
+  // taxonomies stay separate for the same reason the readings do.
   const votedSpans = new Set<string>();
   for (const rv of rvs.votes) votedSpans.add(`${rv.start},${rv.end}`);
   const seen = new Set<string>();

package/src/mind/canonical.ts

@@ -88,6 +88,49 @@ export function leafIdPrefix(
   return ids;
 }
 
+/** Which prefixes of `prefix ‖ tail` are STORED NODES — as lengths in the
+ *  tail's own coordinates, ascending, excluding the empty one.  This is the
+ *  candidate set a rule needs to join an already-stored prefix to a suffix it
+ *  has not stored: a key names a relation exactly when `prefix ‖ tail[0..p]` IS
+ *  a node, and a key can end strictly inside the tail without sitting on any
+ *  fold boundary (a stored member's end is the end of ITS OWN stream, and the
+ *  fold never emits a cut at a stream's end).  Measured: "stockholm mayor"
+ *  exists, leads on, and its boundary 6 is in neither the tail's cuts nor the
+ *  concatenation's.
+ *
+ *  ONE cheap content-addressed probe per offset — `leafIdPrefix` walks the bytes
+ *  once (a point probe each), `findBranch` hashes the growing kid run — and NO
+ *  `resolve`, which is what keeps this off the O(suffix) vector folds the
+ *  recognition path pays.  It stops at the first byte that was never interned,
+ *  which costs nothing real: a stored key's bytes are interned by construction. */
+export function keyEnds(
+  ctx: MindContext,
+  prefix: Uint8Array,
+  tail: Uint8Array,
+): number[] {
+  if (prefix.length === 0 || tail.length === 0) return [];
+  const joined = new Uint8Array(prefix.length + tail.length);
+  joined.set(prefix, 0);
+  joined.set(tail, prefix.length);
+  const ids = leafIdPrefix(ctx, joined);
+  if (ids.length < prefix.length) return [];
+  const ends: number[] = [];
+  // The kid run GROWS by one id per offset; `findBranch` wants an array, so the
+  // run is built once and pushed into, never re-sliced.  Re-slicing
+  // `ids.slice(0, prefix.length + p)` per offset made this O(|tail| ·
+  // (|prefix| + |tail|)) — quadratic in the tail, where the learning path this
+  // follows slices a run that SHRINKS.  Same ends, linear copying.
+  const run = ids.slice(0, prefix.length);
+  // The loop ENDS at the first byte that was never interned (`ids.length`):
+  // every later prefix contains it, so none of them can be a node either — this
+  // is where the scan stops, not a silent truncation of the answer.
+  for (let p = 1; prefix.length + p <= ids.length; p++) {
+    run.push(ids[prefix.length + p - 1]);
+    if (ctx.store.findBranch(run) !== null) ends.push(p);
+  }
+  return ends;
+}
+
 /** The canonical W-window node ids of a byte stream, offset → id — the
  *  CONTENT-ADDRESSED IDENTITY of every W-sized slice, under which any content
  *  two deposits share IS the same node (hash-consing paid the comparison at

package/src/mind/corpus.ts

@@ -0,0 +1,202 @@
+// corpus.ts — read the trained memory back out of the DAG, AS DATA.
+//
+// A trained experience pair IS one continuation edge: `src` is the context that
+// was deposited, `dst` is what the mind learnt follows it.  Reading them back
+// uses the store's own structure and its own indexes — no auxiliary index is
+// built, nothing is written, and NOTHING HERE KNOWS ABOUT TEXT: this layer takes
+// bytes and returns bytes.  The text case is one helper on the Mind
+// (`searchCorpusText`), which encodes, calls this, and decodes.
+//
+// WHERE EACH STAGE COMES FROM (ported from the demo's `explore.ts`, which
+// hand-rolled its own resolution):
+//
+//   1. PERCEIVE, CONTENT-ADDRESS and ADMIT the query — `recognise()`, the SAME
+//      machinery an answer goes through.  It returns the sites: the query spans
+//      that content-addressed to a stored node that can lead somewhere.  The
+//      demo's own recursive `findLeaf`/`findBranch` walk was a second
+//      implementation of exactly this, and it is NOT ported.
+//   2. CLIMB the structural `kid` table from each resolved site to the
+//      edge-bearing contexts above it (`edgeAncestors`, traverse.ts), weighting
+//      each context by how much query content reached it.
+//   3. READ the continuation off the edge table (`nextFirst`).
+//
+// COST is set by how much of the QUERY resolves, never by the size of the
+// store: the sites are what recognition already found, the climb is bounded by
+// the declared `corpusClimbs`/`corpusContextsPerClimb`, and every store call is
+// a point probe or a capped read.  All work is accounted by the store's own
+// meter hooks when a response's meter is open — there is no second instrument.
+//
+// WHAT THIS IS NOT.  Exact content addressing, not fuzzy keyword search: a query
+// shares results with a stored note when it shares actual chunk-aligned content
+// with it.  An arbitrary mid-word fragment resolves to nothing, and the honest
+// answer there is "nothing matched" — which is why `sampleCorpus` exists, and
+// why the miss is reported as a STATE rather than as prose (the text helper
+// turns it into words).
+
+import { recognise } from "./recognition.js";
+import { edgeAncestors } from "./traverse.js";
+import type { MindContext } from "./types.js";
+
+/** One stored experience pair, as bytes. */
+export interface CorpusPair {
+  context: Uint8Array;
+  continuation: Uint8Array;
+  contextId: number;
+  continuationId: number;
+  /** Bytes of the query this pair was matched on — 0 when browsing. */
+  matchedBytes: number;
+  /** True when the stored bytes ran past the declared preview capacity. */
+  contextTruncated: boolean;
+  continuationTruncated: boolean;
+}
+
+/** Why a search produced no pairs.  A STATE, so a caller's own layer can say it
+ *  in its own words — the byte layer does not speak. */
+export type CorpusMiss = "matched" | "nothing-resolved" | "no-continuations";
+
+export interface CorpusResult {
+  pairs: CorpusPair[];
+  /** Query subtrees that content-addressed to a real stored node. */
+  resolved: number;
+  /** Distinct edge-bearing contexts the climb reached. */
+  reached: number;
+  /** Distinct contexts that carry a learnt continuation, store-wide. */
+  totalContexts: number;
+  /** True when these are browse samples rather than search results. */
+  browsed: boolean;
+  miss: CorpusMiss;
+}
+
+/** A context node as a pair, or null when it carries no continuation. */
+function pairOf(
+  ctx: MindContext,
+  id: number,
+  matchedBytes: number,
+): CorpusPair | null {
+  const outs = ctx.store.nextFirst(id, 1);
+  if (outs.length === 0) return null;
+  const cap = ctx.cfg.corpusPreviewBytes;
+  const context = ctx.store.bytesPrefix(id, cap + 1);
+  const continuation = ctx.store.bytesPrefix(outs[0], cap + 1);
+  const contextTruncated = context.length > cap;
+  const continuationTruncated = continuation.length > cap;
+  return {
+    context: contextTruncated ? context.subarray(0, cap) : context,
+    continuation: continuationTruncated
+      ? continuation.subarray(0, cap)
+      : continuation,
+    contextId: id,
+    continuationId: outs[0],
+    matchedBytes,
+    contextTruncated,
+    continuationTruncated,
+  };
+}
+
+/** Which stored notes does this query reach?  BYTES in, BYTES out.
+ *
+ *  Exact content addressing through the machinery that already exists: the
+ *  query's recognised sites are the resolved subtrees, the climb goes up from
+ *  the biggest first, and a pair is a context that carries a continuation. */
+export function searchCorpus(
+  ctx: MindContext,
+  queryBytes: Uint8Array,
+  limit?: number,
+): CorpusResult {
+  const store = ctx.store;
+  const want = Math.max(
+    1,
+    Math.min(limit ?? ctx.cfg.corpusContextsPerClimb, ctx.cfg.corpusLimitMax),
+  );
+  // A resolved subtree must account for at least one window (W): a single
+  // character resolves against almost any store and means nothing.  W is the
+  // mind's own line between chance and evidence — derived, never declared.
+  const floor = ctx.space.maxGroup;
+  const resolved = recognise(ctx, queryBytes).sites
+    .map((s) => ({ id: s.payload, len: store.contentLen(s.payload, 512) }))
+    .filter((r) => r.len >= floor);
+  // Biggest first, lowest id breaking ties: a clause is evidence, a character is
+  // noise, and equal evidence must not be decided by iteration order.
+  const byLength = resolved
+    .sort((a, b) => b.len - a.len || a.id - b.id)
+    .slice(0, ctx.cfg.corpusClimbs);
+
+  // Weight each context by how much query content reached it.
+  const weight = new Map<number, number>();
+  for (const { id, len } of byLength) {
+    for (
+      const root of edgeAncestors(ctx, id, ctx.cfg.corpusContextsPerClimb).roots
+    ) {
+      weight.set(root, (weight.get(root) ?? 0) + len);
+    }
+  }
+
+  const pairs: CorpusPair[] = [];
+  const ranked = [...weight.entries()].sort(
+    (a, b) => b[1] - a[1] || a[0] - b[0],
+  );
+  for (const [id, w] of ranked) {
+    if (pairs.length >= want) break;
+    const pair = pairOf(ctx, id, w);
+    if (pair) pairs.push(pair);
+  }
+  return {
+    pairs,
+    resolved: byLength.length,
+    reached: weight.size,
+    totalContexts: store.edgeSourceCount(),
+    browsed: false,
+    miss: pairs.length > 0
+      ? "matched"
+      : weight.size === 0
+      ? "nothing-resolved"
+      : "no-continuations",
+  };
+}
+
+/** Browse real pairs, striding the id space so the sample is spread rather than
+ *  one local cluster.  DETERMINISTIC: `from` is the caller's own offset, so
+ *  browsing twice with different offsets shows different notes without a random
+ *  draw (the demo drew `Math.random()`, which the engine cannot do — same seed,
+ *  same order, same query must mean the same answer). */
+export function sampleCorpus(
+  ctx: MindContext,
+  limit?: number,
+  from = 0,
+): CorpusResult {
+  const store = ctx.store;
+  const want = Math.max(
+    1,
+    Math.min(limit ?? ctx.cfg.corpusContextsPerClimb, ctx.cfg.corpusLimitMax),
+  );
+  const total = store.nodeCount();
+  const probes = ctx.cfg.corpusSampleProbes;
+  const floorBytes = ctx.cfg.corpusSampleFloorBytes;
+  const pairs: CorpusPair[] = [];
+  // EACH CONTEXT AT MOST ONCE.  Striding the id space revisits ids when the
+  // store is small relative to the probe budget (measured: a 160-node store
+  // returned the SAME pair six times for `limit: 6`), and a browse that repeats
+  // itself is not a browse.  The demo had the same hole; it is invisible only on
+  // a store far larger than the probe budget.
+  const seen = new Set<number>();
+  for (let i = 0; i < probes && pairs.length < want && total > 0; i++) {
+    const slot = (i / probes + from) % 1;
+    const id = Math.floor(slot * total);
+    if (seen.has(id)) continue;
+    if (!store.has(id) || !store.hasNext(id)) continue;
+    if (store.contentLen(id, floorBytes) < floorBytes) continue;
+    const pair = pairOf(ctx, id, 0);
+    if (pair) {
+      seen.add(id);
+      pairs.push(pair);
+    }
+  }
+  return {
+    pairs,
+    resolved: 0,
+    reached: pairs.length,
+    totalContexts: store.edgeSourceCount(),
+    browsed: true,
+    miss: pairs.length > 0 ? "matched" : "no-continuations",
+  };
+}