@hviana/sema 0.8.0 → 0.8.2

package/AGENTS.md

@@ -134,7 +134,28 @@ silence). A simplification that fails an existing test is wrong until the test
 is proven wrong. Sublibraries test themselves in
 `src/{alu,derive,rabitq-ivf}/test/` with zero Sema dependency.
 
-## 6. Dependencies and licensing
+## 6. Instrumentation — the meter and the rationale ARE the dev surface
+
+`src/meter.ts` (what an answer COST) and `inspectRationale` (why it was CHOSEN,
+`src/mind/rationale.ts`) are not debug helpers: they are Sema's development
+instrumentation, and the only ones. Both are read through the public path —
+`new Mind({ profile: true })` → `mind.lastCost` (`sumReports`/`formatReport`),
+and the `inspectRationale` callback on `respond`/`respondText`/`respondTurn`.
+
+When a change needs to be seen, measured, or proved, EXTEND THEM: a counter in
+`meter.ts` (the one place a counter name exists — keep its four contracts true),
+a step or note where the mechanism emits it (`src/mind/trace.ts` holds the move
+vocabulary). A gap in instrumentation is a defect IN the instrumentation: close
+it there, once, so the next person sees it too. Never add a parallel channel for
+a single investigation — no ad-hoc logging or timing probes left in `src/`
+(`performance.now()` belongs in `meter.ts`, not at a call site), no private
+per-layer counter where a `meter.ts` field belongs, and no trace channel of your
+own: a callback threaded through a call chain must FEED the rationale, the way
+`GraphSearch`'s `onDerivation` feeds `traceDerivation`. (`store.ts`'s
+`danglingReads`/`compactFailures` and the `console.warn`s that report them
+predate this and stay: session-lifetime HEALTH counters, not per-response work.)
+
+## 7. Dependencies and licensing
 
 PolyForm Noncommercial 1.0.0 with separate commercial licensing (see
 `LICENSE.md`, `COMMERCIAL-LICENSE.md`, `TRADEMARKS.md`). The library has **no

package/DATASETS.md

@@ -32,7 +32,7 @@ Two consequences follow, and both are load-bearing:
 2. **A corpus under a ShareAlike licence cannot enter the store**, because its
    copyleft would attach to the distributed artifact.
 
-Both rules are stated in [AGENTS.md](AGENTS.md) §6 and must be checked before
+Both rules are stated in [AGENTS.md](AGENTS.md) §7 and must be checked before
 any corpus is added to a trainer.
 
 ---

package/dist/example/train_base/config.js

@@ -4,8 +4,8 @@
 // the cache ceiling, the read budgets, the caps. A knob that describes ONE
 // CORPUS (which pairs of SmolSent, how many SODA dialogues, how long an Aya
 // field may be) belongs next to that corpus's adapter, together with the
-// evidence that fixed its default — see AGENTS.md §2.16: a comment carries the
-// constraint, and a constraint is only readable beside the code it constrains.
+// evidence that fixed its default — a comment carries the constraint, and a
+// constraint is only readable beside the code it constrains.
 import { join } from "node:path";
 /** Read an environment variable, or `d` when it is unset. */
 export const env = (k, d) => process.env[k] ?? d;

package/dist/example/train_base/corpora/massive.js

@@ -34,7 +34,7 @@ import { convertedParquetUnits } from "./converted-parquet.js";
 //
 // So it displaces some wrong answers and manufactures others, INCLUDING turning
 // a correct silence into a wrong answer — and honest silence is a stated
-// property of this engine (AGENTS §2.13). On the mixed-curriculum store the
+// property of this engine (INVARIANTS.md). On the mixed-curriculum store the
 // same shape produced the fragment "nus" for "wake me up at nine am".
 //
 // That evidence is four probes on toy stores and is NOT conclusive; it is,

package/dist/example/train_base/readers.js

@@ -13,7 +13,7 @@
 //
 // THE ONLY THIRD-PARTY CODE IN THIS REPOSITORY IS BELOW, and it is LAZILY
 // LOADED. Sema itself imports nothing outside `node:` — that is a product
-// property, not an accident (AGENTS.md §6) — and this trainer is an EXAMPLE,
+// property, not an accident (AGENTS.md §7) — and this trainer is an EXAMPLE,
 // not part of the library. hyparquet (+ its Snappy codec) is therefore a dev
 // dependency, and it is loaded by a dynamic import the first time a Parquet
 // corpus is actually read: a curriculum with no Parquet stage (SmolSent,

package/dist/src/config.d.ts

@@ -100,6 +100,23 @@ export interface MindConfig {
     seed: number;
     recallQueryK: number;
     haloQueryK: number;
+    /** Corpus reading (see src/mind/corpus.ts): results per call, resolved
+     *  nodes climbed from, contexts requested per climb, probes used to stride
+     *  the id space when browsing, bytes of each side a preview keeps, and the
+     *  smallest deposited note browsing will show.  Capacities and budgets only —
+     *  the one material floor (a resolved node must account for W bytes) is
+     *  derived from the geometry, not declared here. */
+    corpusLimitMax: number;
+    corpusClimbs: number;
+    corpusContextsPerClimb: number;
+    corpusSampleProbes: number;
+    corpusPreviewBytes: number;
+    corpusSampleFloorBytes: number;
+    /** Items one rationale step may ITEMISE (the whole field is still counted in
+     *  the step's note).  A capacity of the rationale, not of recall: sharing
+     *  `recallQueryK` meant `new Mind({recallQueryK: 100000})` un-bounded the very
+     *  payload the bound exists for (found by an adversarial review). */
+    rationaleSampleK: number;
     normalizeEpsilon: number;
     cosineEpsilon: number;
     alu: AluConfig;

package/dist/src/config.js

@@ -5,6 +5,13 @@ export const DEFAULT_CONFIG = {
     seed: 42,
     recallQueryK: 12,
     haloQueryK: 12,
+    rationaleSampleK: 12,
+    corpusLimitMax: 24,
+    corpusClimbs: 24,
+    corpusContextsPerClimb: 6,
+    corpusSampleProbes: 6000,
+    corpusPreviewBytes: 220,
+    corpusSampleFloorBytes: 12,
     normalizeEpsilon: 1e-12,
     cosineEpsilon: 1e-12,
     alu: {
@@ -44,6 +51,17 @@ export function resolveConfig(opts = {}) {
         seed: opts.seed ?? DEFAULT_CONFIG.seed,
         recallQueryK: opts.recallQueryK ?? DEFAULT_CONFIG.recallQueryK,
         haloQueryK: opts.haloQueryK ?? DEFAULT_CONFIG.haloQueryK,
+        rationaleSampleK: opts.rationaleSampleK ?? DEFAULT_CONFIG.rationaleSampleK,
+        corpusLimitMax: opts.corpusLimitMax ?? DEFAULT_CONFIG.corpusLimitMax,
+        corpusClimbs: opts.corpusClimbs ?? DEFAULT_CONFIG.corpusClimbs,
+        corpusContextsPerClimb: opts.corpusContextsPerClimb ??
+            DEFAULT_CONFIG.corpusContextsPerClimb,
+        corpusSampleProbes: opts.corpusSampleProbes ??
+            DEFAULT_CONFIG.corpusSampleProbes,
+        corpusPreviewBytes: opts.corpusPreviewBytes ??
+            DEFAULT_CONFIG.corpusPreviewBytes,
+        corpusSampleFloorBytes: opts.corpusSampleFloorBytes ??
+            DEFAULT_CONFIG.corpusSampleFloorBytes,
         normalizeEpsilon: opts.normalizeEpsilon ?? DEFAULT_CONFIG.normalizeEpsilon,
         cosineEpsilon: opts.cosineEpsilon ?? DEFAULT_CONFIG.cosineEpsilon,
         alu: {

package/dist/src/geometry.d.ts

@@ -140,16 +140,16 @@ export declare function knownPrefixLength(bytes: Uint8Array, leafAt: (i: number)
  *  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 declare function bytesToTree(space: Space, alphabet: Alphabet, bytes: Uint8Array, leafAt?: (i: number) => number | null, lookup?: (leafIds: number[]) => number | null, boundaries?: readonly number[]): Sema;
 /** A plain content fold's reusable state: the level-0 cut edges over the whole
  *  stream and each segment's independently-folded root.  See

package/dist/src/geometry.js

@@ -306,19 +306,20 @@ function bytesToLeaves(alphabet, bytes) {
  *  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.
  *
@@ -568,16 +569,16 @@ export function knownPrefixLength(bytes, leafAt, lookup) {
  *  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, alphabet, bytes, leafAt, lookup, boundaries) {
     if (bytes.length === 0) {
         return sema(alphabet.vecs[0], new Uint8Array(0), null);
@@ -868,7 +869,7 @@ function flatFold(space, alphabet, bytes, from, to) {
     }
     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/dist/src/meter.d.ts

@@ -48,9 +48,6 @@ export declare class Meter {
     nodeRecords: number;
     /** `store.bytes` / `store.bytesPrefix` — one reconstruction request. */
     byteReads: number;
-    /** 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. */
     bytesRead: number;
     /** `store.contentLen`. */
     lenReads: number;
@@ -131,10 +128,10 @@ export declare class Meter {
     junctionPops: number;
     /** 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: number;
     /** Arbitrary byte spans whose distributional company was VSA-bundled from
      *  existing episode halos. */
@@ -155,6 +152,31 @@ export declare class Meter {
     mechanismRuns: number;
     /** Candidates the decider weighed. */
     candidates: number;
+    /** `deriveThrough` yielded — a fact was reached through the subject the query
+     *  never named. */
+    joinFired: number;
+    /** 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: number;
+    /** Refused: the fact contains no entity that leads anywhere. */
+    joinNoEntity: number;
+    /** Times the reasoner pivoted on a span its answer contains and stepped
+     *  across that fact. */
+    pivotSteps: number;
+    /** `bridge` calls the cover makes assembling connectors (pairwise + n-ary). */
+    coverBridges: number;
+    /** 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: number;
+    /** Σ 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: number;
     private readonly _phases;
     private readonly _t0;
     /** Every work counter's current value, by name — the snapshot `time`
@@ -163,11 +185,6 @@ export declare class Meter {
     /** Charge `ms`, one call, and a counter delta to a named phase.
      *  Insertion-ordered, so a report reads in execution order. */
     charge(phase: string, ms: number, delta?: Record<string, number>): void;
-    /** 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. */
     timeSync<T>(phase: string, fn: () => T): T;
     /** Time one async phase and attribute the work done inside it.  Returns
      *  the awaited value untouched — a meter never changes what a layer

package/dist/src/meter.js

@@ -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 })`).
@@ -33,9 +33,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;
@@ -124,10 +124,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. */
@@ -149,6 +149,50 @@ export class Meter {
     mechanismRuns = 0;
     /** 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 ──────────────────────────────────────────────────────────────
     _phases = new Map();
     _t0 = performance.now();
@@ -180,11 +224,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(phase, fn) {
         const before = this.snapshot();
         const t = performance.now();

package/dist/src/mind/attention.js

@@ -1364,10 +1364,10 @@ export function canonicalChunkId(ctx, regionBytes, N, reachMemo) {
     // 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 = null;
     let discReached = Infinity;
     let fallback = null;
@@ -1849,16 +1849,16 @@ async function crossRegionVotes(ctx, query, regions, rvs, k, N, reachMemo, td) {
     const consumed = new Set();
     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/dist/src/mind/bridge.d.ts

@@ -25,13 +25,13 @@ export declare function dismissedKnownContent(ctx: MindContext, query: Uint8Arra
 /** 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 declare function substitutionBridge(ctx: MindContext, query: Uint8Array, proposed?: () => Promise<ReadonlyArray<number>>): Promise<BridgeHit | null>;
 export {};

package/dist/src/mind/bridge.js

@@ -121,22 +121,22 @@ export function dismissedKnownContent(ctx, query, spans) {
     }
     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, query, proposed = async () => []) {
     const meter = ctx.meter;
     return meter
@@ -238,12 +238,12 @@ async function bridgeImpl(ctx, query, proposed) {
         ctx.trace?.step("substitutionBridge", [rItem(query, "query")], [], "no stored query window can anchor a corroborated substitution", undefined, diagnostics);
         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"
@@ -258,7 +258,8 @@ async function bridgeImpl(ctx, query, proposed) {
     // 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", [rItem(query, "query")], [], "every query window that could anchor is corpus-global scaffolding — " +
             "no literal evidence to corroborate a substitution", undefined, diagnostics);
@@ -297,8 +298,8 @@ async function bridgeImpl(ctx, query, proposed) {
     //
     // 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.
     //
@@ -310,17 +311,17 @@ async function bridgeImpl(ctx, query, proposed) {
     //     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, from, to) => {
         if (to - from < W)

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

@@ -0,0 +1,40 @@
+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;
+}
+/** 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 declare function searchCorpus(ctx: MindContext, queryBytes: Uint8Array, limit?: number): CorpusResult;
+/** 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 declare function sampleCorpus(ctx: MindContext, limit?: number, from?: number): CorpusResult;