@hviana/sema 0.8.0 → 0.8.1

package/dist/src/mind/traverse.js

@@ -9,11 +9,11 @@ import { cosine } from "../vec.js";
 import { gistOf, read } from "./primitives.js";
 import { canonicalWindows, leafIdPrefix, leafIdRun } from "./canonical.js";
 //
-// Budgeted on the same terms as the reach memo below (AGENTS §2.12): these
-// three maps are cleared on every write, but a long read-only session over a
-// large store converges on one entry per node per map with nothing to bound
-// it.  Past the cap all three are dropped together and re-derived, costing
-// cold structural probes and never a wrong answer.
+// Budgeted on the same terms as the reach memo below (caches.md): these three
+// maps are cleared on every write, but a long read-only session over a large
+// store converges on one entry per node per map with nothing to bound it. Past
+// the cap all three are dropped together and re-derived, costing cold
+// structural probes and never a wrong answer.
 const STRUCT_MEMO_MAX = 100_000;
 const structCaches = new WeakMap();
 // ── The shared ancestor-reach memo ──────────────────────────────────────
@@ -31,20 +31,21 @@ const structCaches = new WeakMap();
 // battery repeatedly reaches the same corpus scaffolding even when its
 // surface questions differ.
 //
-// Budgeted, not unbounded (AGENTS §2.12): past the cap the whole map is
-// dropped and re-derived, costing a cold climb and never a wrong answer.
+// Budgeted, not unbounded (caches.md): past the cap the whole map is dropped
+// and
+// re-derived, costing a cold climb and never a wrong answer.
 const REACH_MEMO_MAX = 100_000;
 const reachCaches = new WeakMap();
 /** The reach memo this ask should use — see the note above.
  *
- *  A TRACED response always gets a fresh, empty one.  `AncestorReach`'s
- *  `visited`/`maxDepth`/`saturation` fields are populated only when a trace
- *  is attached, so an entry deposited by an untraced earlier turn would
- *  silently black out the reach detail of a later traced one; and the trace's
- *  reach payload is serialised by ITERATING this map, which must therefore
- *  hold what THIS climb consulted, not the whole conversation's history.
- *  Consistent with AGENTS §2.11: a traced response is a different machine —
- *  never benchmark with a trace attached. */
+ *  A TRACED response always gets a fresh, empty one. `AncestorReach`'s
+ * `visited`/`maxDepth`/`saturation` fields are populated only when a trace is
+ * attached, so an entry deposited by an untraced earlier turn would silently
+ * black out the reach detail of a later traced one; and the trace's reach
+ * payload is serialised by ITERATING this map, which must therefore hold what
+ * THIS climb consulted, not the whole conversation's history. Consistent with
+ * memoization.md: a traced response is a different machine — never benchmark
+ * with a trace attached. */
 export function sharedReachMemo(ctx) {
     if (ctx.trace !== null || ctx.climbMemo === null)
         return new Map();
@@ -426,13 +427,14 @@ export function bearsEdge(ctx, id) {
     return cachedHasNext(ctx, id, getStructCache(ctx));
 }
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
- *  The admission predicate recognition filters sites with (HOW_IT_WORKS
- *  §15.3): a form that leads nowhere contributes nothing to any derivation.
- *  Runs once per candidate span on the recognition hot path — `hasNext` is
- *  cached per response (the same flat-branch ids are probed across prefix
- *  variants by canonicalChunkId).  `hasHalo` is not cached: it's a single
- *  indexed point probe per candidate, and the candidates that reach this
- *  check have already been filtered by hasNext above in edgeAncestors. */
+ * The admission predicate recognition filters sites with (cover.md): a form
+ * that
+ * leads nowhere contributes nothing to any derivation. Runs once per candidate
+ * span on the recognition hot path — `hasNext` is cached per response (the same
+ * flat-branch ids are probed across prefix variants by canonicalChunkId).
+ * `hasHalo` is not cached: it's a single indexed point probe per candidate, and
+ * the candidates that reach this check have already been filtered by hasNext
+ * above in edgeAncestors. */
 export function leadsSomewhere(ctx, id) {
     const memo = getStructCache(ctx);
     if (cachedHasNext(ctx, id, memo))
@@ -476,10 +478,10 @@ function boundFor(contextCount) {
     return Math.ceil(Math.sqrt(Math.max(2, contextCount)));
 }
 /** Cap a candidate list at the hub bound √N (insertion order) — the ONE
- *  fan-out convention every walk and disambiguation uses (see HOW_IT_WORKS
- *  §8.6).  A node connected to more than √N others is a hub whose individual
- *  connections carry ~no discriminative information; materialising or scoring
- *  them all would make single decisions scale with the corpus. */
+ * fan-out convention every walk and disambiguation uses (see bounded-reads.md).
+ * A node connected to more than √N others is a hub whose individual connections
+ * carry ~no discriminative information; materialising or scoring them all would
+ * make single decisions scale with the corpus. */
 export function hubCap(ctx, ids) {
     const bound = hubBound(ctx);
     return ids.length > bound ? ids.slice(0, bound) : ids;
@@ -512,16 +514,16 @@ export function contains(ctx, ancestor, descendant) {
  *  the EXACT half's veto on calling them synonyms.
  *
  *  Halos measure company, and the strongest company any two forms can keep is
- *  standing next to each other: a question and its answer co-occur in every
- *  episode that taught the pair, so their halos SHOULD be similar, and on a
- *  conversational store they are (measured on the CONV fixture: consecutive
- *  turns at 0.809 against a 0.516 concept threshold).  A gate reading halo
- *  cosine alone therefore reads adjacency as synonymy and revoices an answer
- *  in the words of the question it answers — "it hangs in madrid" spliced back
- *  into "where is it kept now".  The distributional layer cannot tell the two
- *  relations apart, because to it they are the same observation; the exact
- *  half can, for free, because it stored the edge.  §4.1's division of labour
- *  exactly: approximate proposes, exact decides.
+ * standing next to each other: a question and its answer co-occur in every
+ * episode that taught the pair, so their halos SHOULD be similar, and on a
+ * conversational store they are (measured on the CONV fixture: consecutive
+ * turns at 0.809 against a 0.516 concept threshold). A gate reading halo cosine
+ * alone therefore reads adjacency as synonymy and revoices an answer in the
+ * words of the question it answers — "it hangs in madrid" spliced back into
+ * "where is it kept now". The distributional layer cannot tell the two
+ * relations apart, because to it they are the same observation; the exact half
+ * can, for free, because it stored the edge. halo-sketch.md's division of
+ * labour exactly: approximate proposes, exact decides.
  *
  *  Read LIMITed in both directions at the hub bound — a common continuation's
  *  fan-in is corpus-sized, and no single decision may scale with it. */
@@ -645,19 +647,18 @@ export function chooseNext(ctx, id, guide) {
     // NO consensusFloor gate here (tried and reverted — see
     // test/40-choosenext-scale-guard.test.mjs): that floor is calibrated for
     // POOLED, IDF-weighted CLIMB VOTES (recallByResonance, commitVotes), where
-    // each corroborating region contributes at most ln N and the floor grows
-    // with N exactly as that per-region ceiling does (HOW_IT_WORKS.md §8.6).
-    // `bestSupport` here is a different kind of quantity — a raw prevCount of
-    // how many training contexts predicted ONE destination, bounded by how
-    // often that specific fact was retold, never by corpus size N.  Gating an
-    // N-invariant count against an N-growing threshold guarantees failure
-    // once N is large enough, discarding genuinely, structurally dominant
-    // edges (observed: a fact corroborated 2-to-1-1-1 refused at N≈325K,
-    // falling back to a noisy concept-hop).  The loop above already IS the
-    // "genuinely competing" test: a tie leaves first-inserted as the pick
-    // (test/30's own pinned behaviour); a strict winner is real evidence
-    // regardless of corpus scale.  Matches HOW_IT_WORKS.md §25's own
-    // chooseNext pseudocode, which has no such floor.
+    // each corroborating region contributes at most ln N and the floor grows with
+    // N exactly as that per-region ceiling does (thresholds.md). `bestSupport`
+    // here is a different kind of quantity — a raw prevCount of how many training
+    // contexts predicted ONE destination, bounded by how often that specific fact
+    // was retold, never by corpus size N. Gating an N-invariant count against an
+    // N-growing threshold guarantees failure once N is large enough, discarding
+    // genuinely, structurally dominant edges (observed: a fact corroborated
+    // 2-to-1-1-1 refused at N≈325K, falling back to a noisy concept-hop). The
+    // loop above already IS the "genuinely competing" test: a tie leaves
+    // first-inserted as the pick (test/30's own pinned behaviour); a strict
+    // winner is real evidence regardless of corpus scale. Matches `chooseNext`'s
+    // own pseudocode, which has no such floor.
     // Trace is built lazily — the filter + map below only execute when a
     // trace listener is attached, so the common (no-trace) path pays only
     // for the prevCount calls in the loop above, never for extra rItemShort
@@ -709,12 +710,13 @@ function rItemShort(ctx, id, role, score) {
  *  W-window it spells is contained by more places than the hub bound allows,
  *  i.e. the whole query is corpus-global scaffolding.
  *
- *  WHAT IT IS FOR.  Several mechanisms ground a query through the literal
- *  spans it did NOT explain, and those spans are the whole of their evidence.
- *  When every one of them is a hub, the query says nothing the corpus can be
- *  held to, and grounding it means picking one of thousands of continuations
- *  it gives no evidence for — a fabrication whatever the answer happens to be.
- *  Answering with silence there is the honest degradation contract (§2.13).
+ * WHAT IT IS FOR. Several mechanisms ground a query through the literal spans
+ * it
+ * did NOT explain, and those spans are the whole of their evidence. When every
+ * one of them is a hub, the query says nothing the corpus can be held to, and
+ * grounding it means picking one of thousands of continuations it gives no
+ * evidence for — a fabrication whatever the answer happens to be. Answering
+ * with silence there is the honest degradation contract (INVARIANTS.md).
  *
  *  MEASURED SEPARATION (trained store, hubBound 571) — this is categorical,
  *  not marginal, and it is why the predicate lives here rather than being
@@ -731,11 +733,11 @@ function rItemShort(ctx, id, role, score) {
  *  evidence and sit on the SAME side as the correct ones, so this predicate
  *  is not what makes them silent and cannot be credited for them.
  *
- *  NO NEW THRESHOLD (§2.2): `hubBound` is the √N reading of "hub" used
- *  everywhere, and the containment read is clamped to it exactly as every
- *  other fan-out read is (§2.8).  A query with no stored window at all is NOT
- *  scaffolding-only — it has no evidence either way, and its callers already
- *  refuse it on their own terms. */
+ *  NO NEW THRESHOLD (thresholds.md): `hubBound` is the √N reading of "hub" used
+ * everywhere, and the containment read is clamped to it exactly as every other
+ * fan-out read is (bounded-reads.md). A query with no stored window at all is
+ * NOT scaffolding-only — it has no evidence either way, and its callers already
+ * refuse it on their own terms. */
 export function allWindowsAreScaffolding(ctx, query) {
     const W = ctx.space.maxGroup;
     const bound = hubBound(ctx);
@@ -786,19 +788,19 @@ export function allWindowsAreScaffolding(ctx, query) {
  *  by climbing containment then parents.  Nothing is added to the write side;
  *  this reads an index training already built.
  *
- *  BOUNDED (§2.8), AND WITH NO NEW THRESHOLD.  The window whose containment is
- *  SMALLEST carries the most evidence, and one saturated at `hubBound` carries
- *  none — that is the same √N reading of "hub" the rest of the mind uses, not
- *  a tuned knob.  The upward walk spends a budget of `hubBound` nodes and
- *  fans out by W, so a hub query enumerates nothing and the caller stays
- *  silent rather than guessing (§2.13).  Measured on the trained store: the
- *  photosynthesis form at a one-byte truncation picks a window with 52
- *  containers, visits 446 nodes, and yields exactly ONE candidate that
- *  survives the caller's byte compare — the form itself.
+ *  BOUNDED (bounded-reads.md), AND WITH NO NEW THRESHOLD. The window whose
+ * containment is SMALLEST carries the most evidence, and one saturated at
+ * `hubBound` carries none — that is the same √N reading of "hub" the rest of
+ * the mind uses, not a tuned knob. The upward walk spends a budget of
+ * `hubBound` nodes and fans out by W, so a hub query enumerates nothing and the
+ * caller stays silent rather than guessing (INVARIANTS.md). Measured on the
+ * trained store: the photosynthesis form at a one-byte truncation picks a
+ * window with 52 containers, visits 446 nodes, and yields exactly ONE candidate
+ * that survives the caller's byte compare — the form itself.
  *
- *  These are PROPOSALS only.  Every candidate still faces the byte-exact
- *  prefix compare and all three guards below, so a wrong proposal costs one
- *  bounded read and can never be voiced (§2.3). */
+ *  These are PROPOSALS only. Every candidate still faces the byte-exact prefix
+ * compare and all three guards below, so a wrong proposal costs one bounded
+ * read and can never be voiced (exact-vs-approximate.md). */
 export function formsOpenedBy(ctx, query) {
     const store = ctx.store;
     const W = ctx.space.maxGroup;

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

@@ -250,10 +250,10 @@ export type AItem = {
 export interface MindContext extends GraphSearchHost {
     store: Store;
     /** The work accumulator for the inference call in flight, or null when
-     *  nothing is profiling — see src/meter.ts.  WRITE-ONLY from the engine's
-     *  point of view: no inference decision may read a counter, or the
-     *  determinism contract (AGENTS §2.1) is gone.  Every call site is
-     *  `ctx.meter?.x++`, so an unprofiled response allocates nothing. */
+     * nothing is profiling — see src/meter.ts. WRITE-ONLY from the engine's point
+     * of view: no inference decision may read a counter, or determinism is gone
+     * (determinism.md). Every call site is `ctx.meter?.x++`, so an unprofiled
+     * response allocates nothing. */
     meter: Meter | null;
     space: Space;
     alphabet: Alphabet;

package/dist/src/store.d.ts

@@ -701,18 +701,18 @@ export declare abstract class AbstractStore implements Store {
      *  remainders must fit the budget.  Scattered differences leave a wide
      *  middle and are rejected.
      *
-     *  Every read here is CAPPED (§2.8).  It used to open with
-     *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
-     *  full materialising `bytes()` read — on the deposit hot path, and only
-     *  then compare lengths.  So a candidate the length test was about to reject
-     *  had already been reconstructed byte for byte.  The LENGTHS decide first
-     *  instead, from the `contentLen` memo the interning order has already built
-     *  bottom-up, and the target's length is itself read under a cap: a target
-     *  longer than `la + W` is rejected without touching one of its bytes.
-     *  Same semantics — the old capped `b` read would have produced
-     *  `a.length + W + 1` here and failed the very same test — strictly fewer
-     *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
-     *  "complete reconstruction" test true, so the results still cache. */
+     *  Every read here is CAPPED (bounded-reads.md). It used to open with
+     * `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the full
+     * materialising `bytes()` read — on the deposit hot path, and only then
+     * compare lengths. So a candidate the length test was about to reject had
+     * already been reconstructed byte for byte. The LENGTHS decide first instead,
+     * from the `contentLen` memo the interning order has already built bottom-up,
+     * and the target's length is itself read under a cap: a target longer than
+     * `la + W` is rejected without touching one of its bytes. Same semantics —
+     * the old capped `b` read would have produced `a.length + W + 1` here and
+     * failed the very same test — strictly fewer byte reads. The `+ 1` on each
+     * byte cap keeps `_prefix`'s "complete reconstruction" test true, so the
+     * results still cache. */
     private differsByOneWindow;
     putLeaf(bytes: Uint8Array, gist: Vec): Promise<NodeId>;
     putBranch(kids: NodeId[], gist: Vec): Promise<NodeId>;

package/dist/src/store.js

@@ -1235,18 +1235,18 @@ export class AbstractStore {
      *  remainders must fit the budget.  Scattered differences leave a wide
      *  middle and are rejected.
      *
-     *  Every read here is CAPPED (§2.8).  It used to open with
-     *  `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the
-     *  full materialising `bytes()` read — on the deposit hot path, and only
-     *  then compare lengths.  So a candidate the length test was about to reject
-     *  had already been reconstructed byte for byte.  The LENGTHS decide first
-     *  instead, from the `contentLen` memo the interning order has already built
-     *  bottom-up, and the target's length is itself read under a cap: a target
-     *  longer than `la + W` is rejected without touching one of its bytes.
-     *  Same semantics — the old capped `b` read would have produced
-     *  `a.length + W + 1` here and failed the very same test — strictly fewer
-     *  byte reads.  The `+ 1` on each byte cap keeps `_prefix`'s
-     *  "complete reconstruction" test true, so the results still cache. */
+     *  Every read here is CAPPED (bounded-reads.md). It used to open with
+     * `bytesPrefix(k, Number.MAX_SAFE_INTEGER)` — the ALL sentinel, i.e. the full
+     * materialising `bytes()` read — on the deposit hot path, and only then
+     * compare lengths. So a candidate the length test was about to reject had
+     * already been reconstructed byte for byte. The LENGTHS decide first instead,
+     * from the `contentLen` memo the interning order has already built bottom-up,
+     * and the target's length is itself read under a cap: a target longer than
+     * `la + W` is rejected without touching one of its bytes. Same semantics —
+     * the old capped `b` read would have produced `a.length + W + 1` here and
+     * failed the very same test — strictly fewer byte reads. The `+ 1` on each
+     * byte cap keeps `_prefix`'s "complete reconstruction" test true, so the
+     * results still cache. */
     differsByOneWindow(kids, targetId, W) {
         const lens = kids.map((k) => this.contentLen(k));
         let la = 0;

package/docs/INDEX.md

@@ -1,8 +1,8 @@
 # Sema Documentation Index
 
 Sema is a single system stated three ways: the law lives in `docs/architecture/`
-(what holds), the prescription in `AGENTS.md` bootloader (what to do and where),
-and the proof in `test/` (pins that fail when the law is broken).
+(what holds), the prescription in `AGENTS.md` (what to do and where), and the
+proof in `test/` (pins that fail when the law is broken).
 
 ## Routing — what to read for each task
 

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

@@ -44,4 +44,5 @@ Two rules in `attention.ts` encode "exact decides" and must not be flattened:
 
 Add a tier to the shared family in `mind/match.ts` with a derived gate
 (`geometry.ts`), never a private `score >= k` check. A new mechanism is a
-`(matcher, direction, gate)` configuration over that family (§2.5).
+`(matcher, direction, gate)` configuration over that family
+(`docs/architecture/match-project.md`).

package/docs/architecture/fold-contract.md

@@ -84,4 +84,4 @@ any change here.
 
 See:
 `src/geometry.ts:contentLevels`/`contentBoundaries`/`contentFoldIncremental`/`stablePrefixFold`;
-`AGENTS.md` bootloader invariants.
+`AGENTS.md` §2 invariants.

package/docs/failures/tempting-but-wrong.md

@@ -76,7 +76,7 @@ not to do, why it fails, and what to do instead.
 - **WHY:** `frameSlots` reports (contracted gaps tagged
   substitution/insertion/deletion); `carriesFillers` judges;
   `Precomputed.frames` inventories — elects nothing (`AGENTS §2` Cross-cutting
-  contracts — `docs/architecture/factored-machinery.md` § Frame reading).
+  contracts — `docs/architecture/match-project.md` § Frame reading).
 - **CORRECT:** Report everything in the shared layer; apply
   `substituteAll(contA, fillersA→fillersB)==contB` and
   frame-dominance/`W`-reach/distinctness in the consumer (reference). Pinned by
@@ -88,8 +88,7 @@ not to do, why it fails, and what to do instead.
   `depth[i]`/`dominates(depth, aligned)` to decide climb/IDF.
 - **WHY:** They measure different things: global reach (minority discriminates,
   powers climb/pooling) vs weave-local depth with `MIN_WEAVE=2` (what the local
-  cohort shares, powers CAST) (`AGENTS §2` Cross-cutting contracts — Two
-  measures of commonality).
+  cohort shares, powers CAST) (`docs/architecture/commonality.md`).
 - **CORRECT:** Climb/attention uses corpus-global;
   `frame(i) ⇔ depth[i]>MIN_WEAVE ∧ dominates(depth[i],aligned)` for CAST. Pinned
   by `test/50-cast-analog-consensus-floor.test.mjs` and

package/docs/harness/gates.md

@@ -3,7 +3,7 @@
 Four executable gates. Each: run the command, check what it guards, follow its
 §.
 
-## 1 — Correctness (all 87 suites)
+## 1 — Correctness (all 90 suites)
 
 ```bash
 npm test
@@ -13,8 +13,8 @@ Guards honest silence, determinism, and every pinned contract. Silence:
 unrelated queries ground to nothing (`test/28`, `50`, `56`, `67`, `76`, `84`).
 Determinism: same seed + deposit order + query gives byte-identical answer
 (`test/20`). Every invariant is pinned — a simplification that fails a test is
-wrong until the test is shown wrong. §14–25 (pipeline), §8 (derived thresholds),
-AGENTS.md §2 invariants 1–5.
+wrong until the test is shown wrong. §14–25 (pipeline), §64 (derived
+thresholds), AGENTS.md §2 invariants 1–5.
 
 ## 2 — Work accounting (profiler)
 
@@ -27,8 +27,8 @@ Guards without trace: counters deterministic and diffable between runs; phases
 nest (not disjoint — `think` contains every mechanism phase); shared analyses
 charged to themselves, not to the first toucher; millisecond fields are
 non-deterministic hints only. With `--trace`, recognition idempotence still
-holds (`test/42`). `src/meter.ts`, `docs/architecture/meter.md`, §26, AGENTS.md
-§2 invariant meter/cost.
+holds (`test/42`). `src/meter.ts`, `docs/architecture/meter.md`, §55,
+`AGENTS.md` §6.
 
 ## 3 — Dependency footprint
 
@@ -38,7 +38,7 @@ node --test test/88-dependency-footprint.test.mjs
 
 Guards `dist/src` imports only `node:` + relative paths, and `package.json`
 declares no `dependencies` (examples use `devDependencies` lazily). The
-near-zero footprint is a product feature. AGENTS.md §6, §3 (store has one
+near-zero footprint is a product feature. AGENTS.md §7, §3 (store has one
 runtime dep: `node:sqlite`).
 
 ## 4 — Fold invariance and sublinear scaling
@@ -53,4 +53,4 @@ positional; grid regression (14.3% survival) cannot pass. `14` — inference cos
 is sublinear in corpus size (power-law exponent ≪ 1) and constant-rate in input
 length; measured on independent disjoint corpora via log–log slope.
 `src/geometry.ts` (`contentLevels`), `docs/architecture/fold-contract.md` +
-`bounded-reads.md`, §10, §29.
+`bounded-reads.md`, §59, §63.

package/example/train_base/config.ts

@@ -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";
 

package/example/train_base/corpora/massive.ts

@@ -37,7 +37,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/example/train_base/readers.ts

@@ -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/jsr.json

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

package/package.json

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

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. */
@@ -238,11 +238,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