@hviana/sema 0.8.0 → 0.8.1

package/src/mind/traverse.ts

@@ -32,11 +32,11 @@ interface StructCache {
   hasParents: Map<number, boolean>;
 }
 //
-// 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<object, StructCache>();
 
@@ -55,21 +55,22 @@ const structCaches = new WeakMap<object, StructCache>();
 // 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<object, Map<number, AncestorReach>>();
 
 /** 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: MindContext,
 ): Map<number, AncestorReach> {
@@ -481,13 +482,14 @@ export function bearsEdge(ctx: MindContext, id: number): boolean {
 }
 
 /** 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: MindContext, id: number): boolean {
   const memo = getStructCache(ctx);
   if (cachedHasNext(ctx, id, memo)) return true;
@@ -539,10 +541,10 @@ function boundFor(contextCount: number): number {
 }
 
 /** 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<T>(
   ctx: MindContext,
   ids: readonly T[],
@@ -581,16 +583,16 @@ export function contains(
  *  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. */
@@ -745,19 +747,18 @@ export function chooseNext(
   // 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
@@ -838,12 +839,13 @@ function rItemShort(
  *  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
@@ -860,11 +862,11 @@ function rItemShort(
  *  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: MindContext,
   query: Uint8Array,
@@ -916,19 +918,19 @@ export function allWindowsAreScaffolding(
  *  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: MindContext,
   query: Uint8Array,

package/src/mind/types.ts

@@ -297,10 +297,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/src/store.ts

@@ -541,16 +541,16 @@ export interface Store {
   // selected by identity hash so the choice is a property of each constituent
   // and never of where it sits in the fold.
   //
-  // DURABLE DERIVED STATE, NOT A CACHE.  §2.12 permits a cache to cost only
+  // DURABLE DERIVED STATE, NOT A CACHE. caches.md permits a cache to cost only
   // speed; this decides which terms enter a halo — a learned relation — so an
-  // eviction would change the geometry rather than slow it down.  It is
+  // eviction would change the geometry rather than slow it down. It is
   // therefore written like the canon index: computed once, kept, never
-  // budgeted.  Soundness rests on the set being INTRINSIC — minimality,
-  // `len ≥ W` and non-domination are properties of the node's own subtree and
-  // do not move as the corpus grows.  The one corpus-dependent reading, the
-  // hub exclusion, is deliberately NOT stored: it is applied by the caller at
-  // pour time over the ≤ k candidates, which is the drift companyProfile
-  // already documents as benign and one-directional.
+  // budgeted. Soundness rests on the set being INTRINSIC — minimality, `len ≥
+  // W` and non-domination are properties of the node's own subtree and do not
+  // move as the corpus grows. The one corpus-dependent reading, the hub
+  // exclusion, is deliberately NOT stored: it is applied by the caller at pour
+  // time over the ≤ k candidates, which is the drift companyProfile already
+  // documents as benign and one-directional.
   //
   // Backends that do not implement the pair leave both absent; companyProfile
   // then recomputes the sketch per pour and simply loses the amortisation.
@@ -1789,18 +1789,18 @@ export 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(
     kids: NodeId[],
     targetId: NodeId,

package/test/08-storage.test.mjs

@@ -361,7 +361,7 @@ test("a halo accumulates poured signatures and gates on mass", async () => {
 });
 
 // A multi-turn conversation is deposited as ACCUMULATED-CONTEXT episodes — the
-// pattern HOW_IT_WORKS §19a prescribes and example/train.ts uses:
+// pattern example/train.ts uses:
 //   (t0)            → t1
 //   (t0 + t1)       → t2
 //   (t0 + t1 + t2)  → t3

package/test/35-prefix-edge.test.mjs

@@ -5,7 +5,7 @@
 // parents, or (halo > 0 ∧ already an edge source).  Pure answers do
 // not qualify — they are destinations, not sources.
 //
-// All phrases verified via instrumentation first (see MISTAKES.md).
+// All phrases verified via instrumentation first.
 
 import { test } from "node:test";
 import assert from "node:assert/strict";

package/test/40-choosenext-scale-guard.test.mjs

@@ -10,23 +10,22 @@
 // already requires strict dominance; a tie leaves first-inserted as the
 // pick, exactly the "no real winner" case a floor would matter for.
 //
-// But chooseNext ALSO gated this pick on `bestSupport < consensusFloor(N)`
-// once the corpus scale crosses atomIsHub's threshold (traverse.ts:541-546)
-// — reusing the SAME ln(N)+0.5 floor recallByResonance and commitVotes use
-// for POOLED, IDF-weighted CLIMB VOTES (each region worth up to ln N, so a
-// sum exceeding ln N + 0.5 is more than any one region could say alone —
-// HOW_IT_WORKS.md §8.6).  `prevCount(candidate)` is a different kind of
-// quantity: a raw count of how many training contexts independently
-// predicted ONE destination, bounded by how many times that specific fact
-// was retold — NOT by corpus size N.  Gating an N-invariant count against
-// an N-growing threshold guarantees failure once N is large enough
-// (verified live: N≈325K gives a floor of ≈13.19, so a genuinely dominant
-// but only-doubly-attested fact like "capital of France → Paris" was
-// refused, falling back to a noisy concept-hop that produced the wrong
-// answer).  HOW_IT_WORKS.md's own canonical chooseNext pseudocode (§25)
-// has NO such floor — it's undocumented implementation drift, not a
-// deliberate design surface.  Fix: remove the gate; chooseNext's existing
-// strict-dominance loop already IS the "genuinely competing" test.
+// But chooseNext ALSO gated this pick on `bestSupport < consensusFloor(N)` once
+// the corpus scale crosses atomIsHub's threshold (traverse.ts:541-546) —
+// reusing the SAME ln(N)+0.5 floor recallByResonance and commitVotes use for
+// POOLED, IDF-weighted CLIMB VOTES (each region worth up to ln N, so a sum
+// exceeding ln N + 0.5 is more than any one region could say alone —
+// thresholds.md). `prevCount(candidate)` is a different kind of quantity: a raw
+// count of how many training contexts independently predicted ONE destination,
+// bounded by how many times that specific fact was retold — NOT by corpus size
+// N. Gating an N-invariant count against an N-growing threshold guarantees
+// failure once N is large enough (verified live: N≈325K gives a floor of
+// ≈13.19, so a genuinely dominant but only-doubly-attested fact like "capital
+// of France → Paris" was refused, falling back to a noisy concept-hop that
+// produced the wrong answer). The canonical `chooseNext` pseudocode has NO such
+// floor — it is undocumented implementation drift, not a deliberate design
+// surface. Fix: remove the gate; chooseNext's existing strict-dominance loop
+// already IS the "genuinely competing" test.
 
 import { test } from "node:test";
 import assert from "node:assert/strict";

package/test/56-bridge-identity-admission.test.mjs

@@ -3,13 +3,13 @@
 // separated from the query only by material that does not change what the
 // text SAYS, is the SAME learnt form and grounds through its own edge.
 //
-// "Material that does not change what it says" has ONE definition here, and
-// it is read from the corpus, never tuned (AGENTS §2.7, corpus-global
+// "Material that does not change what it says" has ONE definition here, and it
+// is read from the corpus, never tuned (commonality.md, corpus-global
 // population): a span is EXPLAINED when it is sub-quantum (< W — typographic
-// glue) or every W-window in it is COMMON by the store's own climb (the
-// ascent saturates, or it reaches a majority of contexts).  A window that
-// reaches NOTHING is novel content and is never explained — the reading that
-// separates a droppable "the process of " from a load-bearing "heavy ".
+// glue) or every W-window in it is COMMON by the store's own climb (the ascent
+// saturates, or it reaches a majority of contexts). A window that reaches
+// NOTHING is novel content and is never explained — the reading that separates
+// a droppable "the process of " from a load-bearing "heavy ".
 //
 // THE GAP THIS CLOSES (measured on the 17.9M-node trained store).  The query
 // `Who wrote Romeo and Juliet?` against the trained `Who wrote "Romeo and

package/test/70-prefix-completion.test.mjs

@@ -1,9 +1,10 @@
 // 70-prefix-completion.test.mjs — a query that IS the opening of one trained
 // form is completed by that form's remainder; anything less is refused.
 //
-// WHAT THE MECHANISM DOES (src/mind/prefix-completion.ts): when every other
-// tier has declined, scan the candidate list recall's refusal path has ALREADY
-// fetched and look for a trained form whose bytes literally BEGIN with the whole
+// WHAT THE MECHANISM DOES (src/mind/mechanisms/prefix-completion.ts): when
+// every other tier has declined, scan the candidate list recall's refusal path
+// has ALREADY fetched and look for a trained form whose bytes literally BEGIN
+// with the whole
 // query.  The answer is that form's own remainder — never an invention.
 //
 // WHY IT IS NEEDED, measured on the 15.7M-node trained store:

package/test/72-prefix-candidate-supply.test.mjs

@@ -98,9 +98,9 @@ test("a proper prefix reaches its trained form through the window supply", async
     "a FORM is grounded whole, never a slice cut at the query's end",
   );
 
-  // HONEST DEGRADATION (§2.13).  A query with no discriminative window must
-  // propose nothing rather than guess — silence is the correct answer, and a
-  // supply that widened until it found something would be the real defect.
+  // HONEST DEGRADATION (INVARIANTS.md). A query with no discriminative window
+  // must propose nothing rather than guess — silence is the correct answer, and
+  // a supply that widened until it found something would be the real defect.
   const hub = enc("The ");
   assert.equal(
     prefixCompletion(m, hub, formsOpenedBy(m, hub)),

package/test/73-scaffolding-only-bridge-abstains.test.mjs

@@ -2,16 +2,16 @@
 // ABSTAIN when every literal span it did not substitute is corpus-global
 // scaffolding.
 //
-// THE DEFECT THIS PINS.  A bridge grounds through the literal spans it did NOT
-// substitute; those anchors are the whole of its evidence.  The anchor scan
+// THE DEFECT THIS PINS. A bridge grounds through the literal spans it did NOT
+// substitute; those anchors are the whole of its evidence. The anchor scan
 // ranked them by containment but rejected only the ones with ZERO containers,
 // so a query made entirely of scaffolding still bridged — the single
 // substituted span carried the whole semantic load, and the answer was voiced
-// with confidence.  Measured on the trained store (hubBound 571): "What is the
+// with confidence. Measured on the trained store (hubBound 571): "What is the
 // capital of" has 19 anchors, ALL saturated ("What":572, "hat ":572, "at i":572
-// …), and answered with an unrelated trained context about an integral.  That
-// breaks honest silence (§2.13), which is worse than a gap: a gap is visible, a
-// fabrication is not.
+// …), and answered with an unrelated trained context about an integral. That
+// breaks honest silence (INVARIANTS.md), which is worse than a gap: a gap is
+// visible, a fabrication is not.
 //
 // WHY THIS IS NOT A PROBE-SHAPED PATCH.  The gate was falsified against the
 // queries the bridge answers CORRECTLY before it was written, and every one of

package/test/75-multiturn-context-optimisation.test.mjs

@@ -966,11 +966,11 @@ test("F1: every turn of a trained conversation is answered exactly", async () =>
 test("F1b: attaching a trace changes no answer — the audit layer is inert", async () => {
   // The mind's ONLY text-shaped code lives in the rationale/trace payloads:
   // attention.ts's `dec` helper decodes bytes and collapses whitespace so an
-  // audit line is readable, and frame-filler builds diagnostic strings the
-  // same way. Neither may ever reach a decision — nothing in the core knows
-  // what "whitespace" is (see canon.ts's header, and AGENTS §2.11: profile
-  // and trace must not move an answer). Asserted here rather than assumed,
-  // because the formatting sits inside the same functions that decide.
+  // audit line is readable, and frame-filler builds diagnostic strings the same
+  // way. Neither may ever reach a decision — nothing in the core knows what
+  // "whitespace" is (see canon.ts's header, and memoization.md: profile and
+  // trace must not move an answer). Asserted here rather than assumed, because
+  // the formatting sits inside the same functions that decide.
   const pairs = [
     [
       "who painted the weeping woman",

package/test/84-composed-answer-honesty.test.mjs

@@ -32,8 +32,7 @@
 //
 // TO REPRODUCE THE REAL FAILURE: build the same chain, then ingest ~6,000
 // deposits produced by the Taskmaster adapter (example/train_base/corpora/
-// taskmaster.ts) from
-// TM-2/TM-3/TM-4, and ask the two-hop question. See FINDINGS.md §A1/§A4.
+// taskmaster.ts) from TM-2/TM-3/TM-4, and ask the two-hop question.
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -93,10 +92,10 @@ test("each hop still answers on its own — the substrate is intact", async () =
 
 test("a two-hop query composes or stays silent — it never fabricates", async () => {
   // THE CONTRACT. Three outcomes are conceivable and only two are acceptable:
-  //   compose  -> the answer contains Paris
-  //   silence  -> the empty answer, which is honest (AGENTS §2.13)
-  //   fabricate-> an assembly carrying content from an unrelated deposit
-  // The third is what a store past the real-text ceiling actually does.
+  // compose -> the answer contains Paris silence -> the empty answer, which is
+  // honest (INVARIANTS.md) fabricate-> an assembly carrying content from an
+  // unrelated deposit The third is what a store past the real-text ceiling
+  // actually does.
   const mind = await storeWithDistractors();
   const answer = await mind.respondText(TWO_HOP);
 

package/test/88-dependency-footprint.test.mjs

@@ -1,6 +1,6 @@
 // 88 — the dependency footprint is a PRODUCT PROPERTY, so it is tested.
 //
-// AGENTS.md §6: "do not add runtime dependencies casually — the near-zero-
+// AGENTS.md §7: "do not add runtime dependencies casually — the near-zero-
 // dependency footprint is a product feature." A feature stated only in prose
 // erodes; this suite pins it at the two places it can actually break.
 //

package/test/89-completion-recursion.test.mjs

@@ -1,20 +1,21 @@
 // 89-completion-recursion.test.mjs — the completion recursion must be
 // OUTPUT-SENSITIVE.
 //
-// AGENTS §2.8: "No per-query read may grow with the corpus."  §2.8 enforces
-// that per READ (nextFirst, bytesPrefix, …), and every one of those caps holds.
-// What no guard covered is the NUMBER of reads: `recompleteNode`
+// bounded-reads.md: "No per-query read may grow with the corpus." That law is
+// enforced per READ (nextFirst, bytesPrefix, …), and every one of those caps
+// holds. What no guard covered is the NUMBER of reads: `recompleteNode`
 // (src/mind/graph-search.ts) re-covers a produced node by calling `solve`
-// recursively, and each nested solve builds its own agenda and chart.  Its own
+// recursively, and each nested solve builds its own agenda and chart. Its own
 // doc states the intent —
 //
 //     "its cost tracks the ANSWER's own structure, not how densely the corpus
 //      interconnects the nodes passed through"
 //
 // — but argues termination from "Distinct node ids are finite and each finished
-// completion is memoised".  Finite-in-the-corpus is exactly the bound §2.8
-// forbids, and the recursion is emitted at `cost: 0` while the nested cover's
-// own `cost` is computed and discarded, so A* has no gradient against depth.
+// completion is memoised". Finite-in-the-corpus is exactly the bound
+// bounded-reads.md forbids, and the recursion is emitted at `cost: 0` while the
+// nested cover's own `cost` is computed and discarded, so A* has no gradient
+// against depth.
 //
 // MEASURED on a trained store (18,938,834 nodes, edgeSourceCount 796,528):
 // `respond("Hi")` reached recursion depth 331 and 9.1 GB RSS in 56 s without
@@ -221,8 +222,9 @@ test("completion recursion: per-query work does not grow with the corpus", async
     } (agenda pops) — target ≪ 1 (sublinear in the corpus)`,
   );
 
-  // THE LAW.  Same answer, more corpus, so cost must not move.  k ≈ 0 is flat,
-  // k ≈ 1 is linear in the corpus — the bound §2.8 forbids outright.
+  // THE LAW. Same answer, more corpus, so cost must not move. k ≈ 0 is flat, k
+  // ≈
+  // 1 is linear in the corpus — the bound bounded-reads.md forbids outright.
   //
   // `searches` counts nested solve() calls, which is the recursion itself and
   // nothing else, so it gets 14-scaling.test.mjs's stricter 0.6 bar.  Measured
@@ -234,17 +236,18 @@ test("completion recursion: per-query work does not grow with the corpus", async
       `nested solve() builds its own agenda and chart, so this is the ` +
       `completion recursion doing work the answer never asked for`,
   );
-  // A LOOSER BAR, FOR A REASON.  `searchPops` aggregates the TOP-LEVEL cover's
+  // A LOOSER BAR, FOR A REASON. `searchPops` aggregates the TOP-LEVEL cover's
   // agenda too, and that one legitimately carries some corpus sensitivity: a
   // bigger store recognises more sites inside the same query, so more items are
-  // admissible.  Only outright linear growth is the forbidden case (§2.8), so
-  // this asserts the law itself, k < 1, rather than the stricter 0.6 that suits
-  // a counter the fix governs end to end.  Measured 1.40 unfixed, 0.54 fixed.
+  // admissible. Only outright linear growth is the forbidden case
+  // (bounded-reads.md), so this asserts the law itself, k < 1, rather than the
+  // stricter 0.6 that suits a counter the fix governs end to end. Measured 1.40
+  // unfixed, 0.54 fixed.
   assert.ok(
     kPops < 1,
     `agenda pops grew with exponent k=${kPops.toFixed(2)} in corpus size (${
       pops.join(" → ")
     }) for a byte-identical answer — k≈1 is work LINEAR in the corpus, which ` +
-      `is the bound §2.8 forbids outright`,
+      `is the bound bounded-reads.md forbids outright`,
   );
 });

package/test/90-connector-read-cap.test.mjs

@@ -7,10 +7,10 @@
 // substring search, so it needs the candidate's bytes; it used to reconstruct
 // them in FULL via `read(ctx, answer)`, whose maxLen defaults to ALL.
 //
-// AGENTS §2.8, prefix-capped reads: "a candidate that exceeds the cap is
+// bounded-reads.md, prefix-capped reads: "a candidate that exceeds the cap is
 // rejected without reconstructing it — the weave, the junction walks and the
 // bridge all read this way, and uncapped reads there cost seconds per query on
-// a large store."  This probe was the exception, and it runs hubBound(ctx) = √N
+// a large store." This probe was the exception: it runs hubBound(ctx) = √N
 // times PER SITE.
 //
 // The probe's corpus-scale cost was once claimed from a trained-store
@@ -18,14 +18,15 @@
 // prompt" — but that number was measured on a `respond()` query, where the
 // probe does NOT execute (`answeredSpans` is empty there, so the enclosing
 // guard returns first).  It is therefore not attributable to the probe and is
-// not repeated here (§2.16: a comment asserting a measurement inherits Gate 1).
+// not repeated here (a comment asserting a measurement inherits Gate 1).
 // The probe runs only on a multi-turn `respondTurn` response; its benefit there
 // is still unmeasured.
 //
-// WHAT THIS PINS.  The cap cannot reduce the read COUNT — only a semantic change
-// could (see below).  It bounds each read by the QUERY, which is what §2.8 asks
-// and what rescues a SHORT query: candidates averaged 231 B reconstructed
-// against a 3-byte prompt.  So the invariant here is per-read SIZE.
+// WHAT THIS PINS. The cap cannot reduce the read COUNT — only a semantic change
+// could (see below). It bounds each read by the QUERY, which is what
+// bounded-reads.md asks and what rescues a SHORT query: candidates averaged 231
+// B reconstructed against a 3-byte prompt. So the invariant here is per-read
+// SIZE.
 //
 // It is measured by calling `resolveConnectors` DIRECTLY and diffing the meter
 // across it.  A whole-response counter cannot express this: `bytesRead` sums
@@ -121,7 +122,8 @@ test("connector probe reads by the query, not by the learnt continuation", async
       `the connector probe averaged ${perRead.toFixed(0)} B per read for a ` +
         `${QUERY.length} B query — a candidate longer than the query cannot ` +
         `occur inside it, so it must be rejected on an overflow probe of ` +
-        `${QUERY.length + 1} B, not reconstructed in full (AGENTS §2.8)`,
+        `${QUERY.length + 1} B, not reconstructed in full ` +
+        `(bounded-reads.md)`,
     );
   } finally {
     mind.endResponse();