@hviana/sema 0.8.0 → 0.8.2

package/src/geometry.ts

@@ -349,19 +349,20 @@ function bytesToLeaves(
  *  sentences fall would be importing an assumption the architecture rejects.
  *  Random binary must, and does, behave exactly like prose.
  *
- *  Every constant is derived (§2.2): the cut mask is W, so a cut is offered once
- *  per quantum of bytes — which, composed with the minimum below, puts the
- *  expected segment at minLen + W − 1 ≈ 6 B rather than at W, deliberately (see
- *  the refutation recorded at `cutRate` in {@link contentLevels}: a segment is
- *  the flat PHRASE-scale unit the W-ary groups are built from, not a group of W
- *  children, and forcing E[len] = W costs 15 tests).  The minimum is W−1, `canonicalWindows`'s
- *  straddle neighbour and the write side's own floor for a unit; and the maximum
- *  is the KEYRING's seat count, because a segment folds as ONE flat node and
- *  `fold` has exactly that many seats to bind children into.  Capping there is
- *  what keeps the fold light: a segment of 3..seats leaves is a single node,
- *  where splitting it into W-groups plus a remainder would cost two or three
- *  and the remainders barely share (measured: partial-arity nodes 504 → 3,590,
- *  and total distinct nodes 8,142 → 9,712, when segments folded as [W][rest]). */
+ *  Every constant is derived (thresholds.md): the cut mask is W, so a cut is
+ * offered once per quantum of bytes — which, composed with the minimum below,
+ * puts the expected segment at minLen + W − 1 ≈ 6 B rather than at W,
+ * deliberately (see the refutation recorded at `cutRate` in {@link
+ * contentLevels}: a segment is the flat PHRASE-scale unit the W-ary groups are
+ * built from, not a group of W children, and forcing E[len] = W costs 15
+ * tests). The minimum is W−1, `canonicalWindows`'s straddle neighbour and the
+ * write side's own floor for a unit; and the maximum is the KEYRING's seat
+ * count, because a segment folds as ONE flat node and `fold` has exactly that
+ * many seats to bind children into. Capping there is what keeps the fold light:
+ * a segment of 3..seats leaves is a single node, where splitting it into
+ * W-groups plus a remainder would cost two or three and the remainders barely
+ * share (measured: partial-arity nodes 504 → 3,590, and total distinct nodes
+ * 8,142 → 9,712, when segments folded as [W][rest]). */
 /** {@link contentBoundaries} plus, for each cut, its LEVEL — how deep in the
  *  tree that cut reaches.
  *
@@ -622,16 +623,16 @@ export function knownPrefixLength(
  *  correct boundary.  Pass them through from `perceive`; the geometry
  *  computes the stable prefix internally.
  *
- *  `boundaries` is the CALLER-computed stable-prefix boundary set (§10.3):
- *  strictly-increasing proper byte offsets, each the length of a prefix that
- *  is already a stored whole-stream form.  When given, the fold splits into
- *  the segments between consecutive boundaries — each folded independently,
- *  exactly as it folded when it was learned — and the segment roots join
- *  LEFT-NESTED (((s₀·s₁)·s₂)…), so every learnt cumulative-context root
- *  reappears as an identical subtree (and, by hash-consing, the very same
- *  node) inside the grown stream.  This is what lets a conversation's next
- *  turn extend perception instead of refolding it: identical prefixes
- *  produce identical subtrees regardless of what follows them. */
+ *  `boundaries` is the CALLER-computed stable-prefix boundary set
+ * (fold-contract.md): strictly-increasing proper byte offsets, each the length
+ * of a prefix that is already a stored whole-stream form. When given, the fold
+ * splits into the segments between consecutive boundaries — each folded
+ * independently, exactly as it folded when it was learned — and the segment
+ * roots join LEFT-NESTED (((s₀·s₁)·s₂)…), so every learnt cumulative-context
+ * root reappears as an identical subtree (and, by hash-consing, the very same
+ * node) inside the grown stream. This is what lets a conversation's next turn
+ * extend perception instead of refolding it: identical prefixes produce
+ * identical subtrees regardless of what follows them. */
 export function bytesToTree(
   space: Space,
   alphabet: Alphabet,
@@ -962,7 +963,7 @@ function flatFold(
   return { tree: sema(gist, null, kids), len: n };
 }
 
-/** The stable-prefix segmented fold (§10.3).  Each segment between
+/* * The stable-prefix segmented fold (fold-contract.md).  Each segment between
  *  consecutive boundaries folds PLAINLY and independently; segment roots
  *  join left-nested, and only the final root is normalized (the linear-fold
  *  contract: one normalize per perception).  A segment's own inner splits

package/src/meter.ts

@@ -8,8 +8,8 @@
 // Four contracts, all load-bearing:
 //
 //   1. NEVER READ BY INFERENCE.  No counter may reach a decision, a threshold,
-//      or an ordering.  Determinism (AGENTS §2.1) survives only because the
-//      meter is write-only from the engine's point of view.
+//      or an ordering.  Determinism (determinism.md) survives
+//      only because the meter is write-only from the engine's point of view.
 //   2. OFF BY DEFAULT, AND FREE WHEN OFF.  Every call site is `meter?.x++` on
 //      a null field.  Nothing allocates, nothing is keyed, nothing is timed
 //      unless a Meter is attached (`new Mind({ profile: true })`).
@@ -79,9 +79,9 @@ export class Meter {
   nodeRecords = 0;
   /** `store.bytes` / `store.bytesPrefix` — one reconstruction request. */
   byteReads = 0;
-  /** Bytes actually handed back by those reads — the real I/O volume, and
-   *  the number that exposes an unbounded read (AGENTS §2.8) that a call
-   *  count alone hides. */
+  /* * Bytes actually handed back by those reads — the real I/O volume, and the
+   *  number that exposes an unbounded read (bounded-reads.md) that a call count
+   * alone hides. */
   bytesRead = 0;
   /** `store.contentLen`. */
   lenReads = 0;
@@ -178,10 +178,10 @@ export class Meter {
   junctionPops = 0;
   /** Ascents that ended by EXHAUSTING the expansion budget rather than by
    *  deciding — the walk abstained and the caller silently fell through to a
-   *  lower tier of the ladder (§2.13: a degradation nothing else reports).
-   *  It rises the moment a SHARED budget is drained by an earlier walk, which
-   *  is what makes "this tier answered nothing" distinguishable from "this
-   *  tier never got to look". */
+   * lower tier of the ladder — honest degradation, and nothing else reports it
+   * (INVARIANTS.md). It rises the moment a SHARED budget is drained by an
+   * earlier walk, which is what makes "this tier answered nothing"
+   * distinguishable from "this tier never got to look". */
   junctionBudgetExhausted = 0;
   /** Arbitrary byte spans whose distributional company was VSA-bundled from
    *  existing episode halos. */
@@ -206,6 +206,53 @@ 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;
+
+  // ── 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;
+
+  // ── 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>();
@@ -238,11 +285,11 @@ export class Meter {
     }
   }
 
-  /** Time one SYNCHRONOUS phase.  The sync/async seam (§2.10) is a real
-   *  contract — perception, recognition and the graph search are synchronous —
-   *  so a synchronous layer must not be wrapped in `time`'s promise just to be
-   *  measured: that would make the profiled path await where the unprofiled
-   *  one does not, and a meter never changes what a layer computes. */
+  /* * Time one SYNCHRONOUS phase.  The sync/async seam is a real contract
+   * (meter.md) — perception, recognition and the graph search are synchronous —
+   * so a synchronous layer must not be wrapped in `time`'s promise just to be
+   * measured: that would make the profiled path await where the unprofiled one
+   * does not, and a meter never changes what a layer computes. */
   timeSync<T>(phase: string, fn: () => T): T {
     const before = this.snapshot();
     const t = performance.now();

package/src/mind/attention.ts

@@ -1941,10 +1941,10 @@ export function canonicalChunkId(
   // CAST lost a point of attention it needed (test/29 D1/D2).
   //
   // So scan every offset and prefer an anchor that still discriminates: not
-  // saturated, and among those the one reaching the FEWEST contexts (§2.7,
-  // corpus-global).  Only when every window in the region saturates does the
-  // old generalising choice stand — there is then no discriminative anchor to
-  // find, and abstaining is the honest outcome.
+  // saturated, and among those the one reaching the FEWEST contexts
+  // (commonality.md, corpus-global). Only when every window in the region
+  // saturates does the old generalising choice stand — there is then no
+  // discriminative anchor to find, and abstaining is the honest outcome.
   let discId: number | null = null;
   let discReached = Infinity;
   let fallback: number | null = null;
@@ -2649,16 +2649,16 @@ async function crossRegionVotes(
   const consumed = new Set<number>();
   let probes = 0;
   // When atoms themselves are hubs (atomIsHub — a single byte reaches ≥ √N
-  // contexts, §2.8's own predicate), the corpus is large enough that the
-  // cross-region junction walks are dominated by the drift through common
-  // content's ancestry.  Each of k candidate pairs otherwise spends its own
-  // √N·W budget (profiled: 160,210 junction pops, 31% of think at
-  // N = 325,608), and a cumulative dialogue multiplies bounded work into tens
-  // of seconds.  The structural walk is therefore given ONE k·W allowance per
+  // contexts, bounded-reads.md's own predicate), the corpus is large enough
+  // that the cross-region junction walks are dominated by the drift through
+  // common content's ancestry. Each of k candidate pairs otherwise spends its
+  // own √N·W budget (profiled: 160,210 junction pops, 31% of think at N =
+  // 325,608), and a cumulative dialogue multiplies bounded work into tens of
+  // seconds. The structural walk is therefore given ONE k·W allowance per
   // evidence tier, shared across every pair — k pairs × W phrase-scale levels,
   // the minimal exact check; a pair whose container is not reached within it
-  // falls through to the resonance tier (the ANN proposes what the shallow
-  // walk no longer exhaustively scans, §2.3).
+  // falls through to the resonance tier (the ANN proposes what the shallow walk
+  // no longer exhaustively scans, exact-vs-approximate.md).
   //
   // Below atomIsHub the store is small and atoms still discriminate, so the
   // walks keep exhaustive exact traversal (per-walk √N·W) — the shared budget

package/src/mind/bridge.ts

@@ -148,23 +148,23 @@ export function dismissedKnownContent(
   return false;
 }
 
-// The seeded aligner this file used to own now lives in the shared match
-// family as {@link alignAround} — the frame reading (match.ts) reads the same
-// gaps and asks the OPPOSITE question of them (see AlignGap's own doc).  Two
-// consumers, one definition (AGENTS §2.5); the bridge's reading is unchanged.
+// The seeded aligner this file used to own now lives in the shared match family
+// as {@link alignAround} — the frame reading (match.ts) reads the same gaps and
+// asks the OPPOSITE question of them (see AlignGap's own doc). Two consumers,
+// one definition (factored-machinery.md); the bridge's reading is unchanged.
 const align = alignAround;
 
 /** Recall's corroborated-substitution bridge — see the module comment.
  *  Returns the best bridged grounding proposal, or null. */
 /** `proposed` is a THUNK, not a list: the bridge's own cheap gates (the
- *  two-quantum query floor and the O(|query|) stored-window anchor scan)
- *  decide whether ANY candidate can be aligned, and they need no proposals
- *  to do it.  Resolving the caller's proposals eagerly meant recall paid its
- *  exhaustive whole-index resonance — the most expensive single act on the
- *  refusal path — for every query, including the ones whose windows the
- *  store has never seen and which the anchor scan rejects outright.  Same
- *  investment discipline the mechanism floors follow (AGENTS §2.6): never
- *  compute a shared analysis just to discard it. */
+ *  two-quantum query floor and the O(|query|) stored-window anchor scan) decide
+ * whether ANY candidate can be aligned, and they need no proposals to do it.
+ * Resolving the caller's proposals eagerly meant recall paid its exhaustive
+ * whole-index resonance — the most expensive single act on the refusal path —
+ * for every query, including the ones whose windows the store has never seen
+ * and which the anchor scan rejects outright. Same investment discipline the
+ * mechanism floors follow (mechanism-market.md): never compute a shared
+ * analysis just to discard it. */
 export async function substitutionBridge(
   ctx: MindContext,
   query: Uint8Array,
@@ -290,12 +290,12 @@ async function bridgeImpl(
     );
     return null;
   }
-  // NO DISCRIMINATING LITERAL EVIDENCE — abstain (§2.13).  A bridge grounds
-  // through the literal spans it did NOT substitute; those anchors are the
-  // whole of its evidence.  When every one of them is SATURATED — containment
-  // clamped at the √N hub bound, i.e. the window is corpus-global scaffolding
-  // — the query's unsubstituted part discriminates nothing, and the single
-  // substituted span is carrying the entire semantic load.  That is not a
+  // NO DISCRIMINATING LITERAL EVIDENCE — abstain (INVARIANTS.md). A bridge
+  // grounds through the literal spans it did NOT substitute; those anchors are
+  // the whole of its evidence. When every one of them is SATURATED —
+  // containment clamped at the √N hub bound, i.e. the window is corpus-global
+  // scaffolding — the query's unsubstituted part discriminates nothing, and the
+  // single substituted span is carrying the entire semantic load. That is not a
   // corroborated bridge; it is a template match, and it FABRICATES.
   //
   // Measured on the trained store (hubBound 571).  "What is the capital of"
@@ -310,7 +310,8 @@ async function bridgeImpl(
   // them silent and cannot be credited for them.
   //
   // This introduces NO new threshold: `bound` is the same √N reading of "hub"
-  // the anchor scan already clamps its own containment read to (§2.2, §2.7).
+  // the anchor scan already clamps its own containment read to (thresholds.md,
+  // commonality.md).
   if (allWindowsAreScaffolding(ctx, query)) {
     ctx.trace?.step(
       "substitutionBridge",
@@ -353,8 +354,8 @@ async function bridgeImpl(
   //
   // The question every gap poses is "may the two forms differ HERE without
   // differing in what they SAY?", and that is the discriminative-vs-
-  // scaffolding question AGENTS §2.7 names, over the CORPUS-GLOBAL
-  // population.  It already has one definition — `dominates(reachOf(...), N)`,
+  // scaffolding question commonality.md names, over the CORPUS-GLOBAL
+  // population. It already has one definition — `dominates(reachOf(...), N)`,
   // the same gate confluence's filler test uses ("scaffolding never binds").
   // Nothing new is derived here; the bar is read, not invented.
   //
@@ -366,17 +367,17 @@ async function bridgeImpl(
   //     climb's own definition of non-discriminative), or it resolves to a
   //     majority of the corpus's contexts.  "the process of ", " is the ".
   //
-  // THE READING MATTERS, not just the population (AGENTS §2.7).  This
-  // deliberately does NOT go through `reachOf`, which maps BOTH "saturated"
-  // and "reaches nothing" to Infinity.  For IDF weighting those are the same
-  // thing (no usable identity evidence); for THIS question they are
-  // opposites — a window reaching nothing is novel content, the most
-  // discriminative material there is, and reading it as Infinity would call
-  // it scaffolding.  Measured: with `reachOf`, "Is water wet?" was answered
-  // with "No, heavy water is not wet." — "heav"/"eavy" occur once, reach no
-  // edge-bearing ancestor, and were written off as filler.  So an
-  // empty-rooted window is NEVER explained, and neither is an untrained one
-  // (the same principle attestedQ applies to the query side).
+  // THE READING MATTERS, not just the population — see commonality.md. This
+  // deliberately does NOT go through `reachOf`, which maps BOTH "saturated" and
+  // "reaches nothing" to Infinity. For IDF weighting those are the same thing
+  // (no usable identity evidence); for THIS question they are opposites — a
+  // window reaching nothing is novel content, the most discriminative material
+  // there is, and reading it as Infinity would call it scaffolding. Measured:
+  // with `reachOf`, "Is water wet?" was answered with "No, heavy water is not
+  // wet." — "heav"/"eavy" occur once, reach no edge-bearing ancestor, and were
+  // written off as filler. So an empty-rooted window is NEVER explained, and
+  // neither is an untrained one (the same principle attestedQ applies to the
+  // query side).
   const reachMemo = sharedReachMemo(ctx);
   const explainedSpan = (
     bytes: Uint8Array,

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",
+  };
+}