@hviana/sema 0.7.9 → 0.8.1

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/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. */
@@ -163,11 +160,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. */
@@ -180,11 +180,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/graph-search.d.ts

@@ -162,14 +162,6 @@ export declare class GraphSearch {
      *  recursive completion), and chooseNext (distributional-evidence edge
      *  disambiguation when a recognised form has multiple continuations). */
     host: GraphSearchHost);
-    /** The hub bound √N (AGENTS §2.8) — the ONE fan-out cap, stated here
-     *  rather than imported from `traverse.ts` because this module is
-     *  deliberately host-based (it holds a bare Store, never a MindContext).
-     *  That is the same write/read-side duplication convention canonical.ts's
-     *  header documents: if the formula changes it must change in BOTH places.
-     *  It is stated ONCE per side, though — the expression used to be spelled
-     *  out at three call sites here, one of them inside a per-item rules
-     *  generator, and they had already drifted on the `Math.max(2, …)` floor. */
     private hubBound;
     /** Explore the Sema graph for the lightest cover of the query and return its
      *  chosen spans left-to-right — WITH the derivation's total weight (the g

package/dist/src/mind/graph-search.js

@@ -16,7 +16,7 @@
 // So this engine stays decoupled: it knows the graph's shape, never how the
 // graph was learnt.
 import { lightestDerivation, } from "../derive/src/index.js";
-import { bytesEqual, concat2, concatBytes, latin1 } from "../bytes.js";
+import { bytesEqual, concat2, concatBytes, indexOf, latin1 } from "../bytes.js";
 import { ALL } from "./types.js";
 // The cost ladder is a strict ORDERING, not tuned magic:
 //   • Coverage dominates everything: leaving one query byte unrecognised (PASS)
@@ -194,9 +194,10 @@ export class GraphSearch {
         this.maxGroup = maxGroup;
         this.host = host;
     }
-    /** The hub bound √N (AGENTS §2.8) — the ONE fan-out cap, stated here
-     *  rather than imported from `traverse.ts` because this module is
-     *  deliberately host-based (it holds a bare Store, never a MindContext).
+    /* * The hub bound √N (bounded-reads.md) — the ONE
+     *  fan-out cap, stated here rather than imported from `traverse.ts` because
+     *  this module is deliberately host-based (it holds a bare Store, never a
+     *  MindContext).
      *  That is the same write/read-side duplication convention canonical.ts's
      *  header documents: if the formula changes it must change in BOTH places.
      *  It is stated ONCE per side, though — the expression used to be spelled
@@ -779,12 +780,12 @@ export class GraphSearch {
         if (memo.has(node))
             return memo.get(node) ?? null;
         // Re-covering is how a PRODUCED node's bytes enter the search at all: the
-        // cover machinery otherwise only ever sees the QUERY's spans.  The recursion
+        // cover machinery otherwise only ever sees the QUERY's spans. The recursion
         // is allowed to nest — a chain IS nested completions — but it is bounded so
-        // the work stays the ANSWER's (AGENTS §2.8): the stack below is the cycle
-        // guard, only ACCEPTED completions recurse, and the nested solve decomposes
-        // the form by its own shape instead of re-recognising the corpus's hub forms
-        // inside it.
+        // the work stays the ANSWER's (bounded-reads.md): the stack below is the
+        // cycle guard, only ACCEPTED completions recurse, and the nested solve
+        // decomposes the form by its own shape instead of re-recognising the
+        // corpus's hub forms inside it.
         //
         // `recompleteOpen` IS the stack of the chain being built, so MEMBERSHIP is
         // the cycle guard: a node already open on this chain cannot re-enter it.
@@ -894,22 +895,34 @@ export class GraphSearch {
         // The entity candidates are the forms the fact's own bytes CONTAIN — the
         // same recogniser the query went through, so the evidence standard is the
         // query's.  A byte atom is never a subject; the fact's own node is the span
-        // itself, not an entity inside it.
-        for (const site of this.host.recogniseSpan(fact.bytes).sites) {
-            if (site.payload < 0 || site.payload === fact.node)
-                continue;
-            // The admission predicate has ONE definition — `traverse.ts`'s
-            // `leadsSomewhere` (edge or halo).  The host LENDS it when it can (Mind
-            // does, with the response-scoped struct cache); a bare host falls back to
-            // the raw-store probe, so the search stays host-based.  Same semantics
-            // either way; the hook spares the repeated probe and keeps the predicate
-            // from being redefined here.
-            const leads = this.host.leadsSomewhere !== undefined
-                ? this.host.leadsSomewhere(site.payload)
-                : this.store.hasNext(site.payload) || this.store.hasHalo(site.payload);
-            if (!leads)
-                continue;
-            const key = this.host.resolve(concat2(this.store.bytesPrefix(site.payload, ALL), tail));
+        // itself, not an entity inside it.  The admission predicate has ONE
+        // definition — `traverse.ts`'s `leadsSomewhere` (edge or halo); the host
+        // LENDS it when it can (Mind does, with the response-scoped struct cache),
+        // and a bare host falls back to the raw-store probe, so the search stays
+        // host-based.
+        const leading = this.host.recogniseSpan(fact.bytes).sites.filter((s) => s.payload >= 0 && s.payload !== fact.node &&
+            (this.host.leadsSomewhere !== undefined
+                ? this.host.leadsSomewhere(s.payload)
+                : this.store.hasNext(s.payload) || this.store.hasHalo(s.payload)));
+        // …then prefer the entity the query did NOT name, and the MAXIMAL one.  The
+        // join exists to reach the subject the query never wrote, so:
+        //   • a candidate the query already contains is the query's OWN subject, and
+        //     following its fact answers about that subject instead of the inferred
+        //     one (measured: "Gustaf Molander spouse date of death" gave Gustaf's
+        //     date of death, not his spouse's);
+        //   • a candidate contained in a longer one is not the entity the fact
+        //     introduces ("Timur" must not win over "Timur Bekmambetov").
+        // Byte work over bytes already read, and the pruning REMOVES the
+        // resolve()/nextFirst() probes these candidates would have paid.
+        const candidates = leading
+            .map((s) => ({
+            payload: s.payload,
+            bytes: this.store.bytesPrefix(s.payload, ALL),
+        }))
+            .filter((c) => indexOf(queryBytes, c.bytes, 0) < 0)
+            .filter((c, _i, all) => !all.some((o) => o.bytes.length > c.bytes.length && indexOf(o.bytes, c.bytes, 0) >= 0));
+        for (const c of candidates) {
+            const key = this.host.resolve(concat2(c.bytes, tail));
             if (key === null)
                 continue;
             const nx = this.store.nextFirst(key, 1);

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

@@ -97,7 +97,7 @@ export declare function cachedRead(ctx: MindContext, cache: WalkCache | null, id
  *     is legitimately reached across many containing structures.  Half the
  *     successful junctions would be lost.
  *
- *     REFUTED EARLY-STOP (side-cone exhaustion, §2.17's "real saturation"):
+ * REFUTED EARLY-STOP (side-cone exhaustion, saturation.md's "real saturation"):
  *     stopping the walk the moment ONE side's upward cone is emptied is wrong,
  *     in both a hub-guarded form and a hub-flagged form.  The junction test is
  *     a BYTE containment over the UNION of the two cones, and a junction can be

package/dist/src/mind/junction.js

@@ -135,7 +135,7 @@ function cachedContainers(ctx, cache, id, limit) {
  *     is legitimately reached across many containing structures.  Half the
  *     successful junctions would be lost.
  *
- *     REFUTED EARLY-STOP (side-cone exhaustion, §2.17's "real saturation"):
+ * REFUTED EARLY-STOP (side-cone exhaustion, saturation.md's "real saturation"):
  *     stopping the walk the moment ONE side's upward cone is emptied is wrong,
  *     in both a hub-guarded form and a hub-flagged form.  The junction test is
  *     a BYTE containment over the UNION of the two cones, and a junction can be
@@ -186,13 +186,13 @@ unordered = false) {
         d: 0,
     }));
     while (stack.length > 0 && out.length < bound) {
-        // BUDGET EXHAUSTION IS AN ABSTENTION, AND IT MUST BE VISIBLE (§2.13).  The
-        // walk stops with work still on the stack, the caller reads "no container"
-        // and falls through to a lower ladder rung — indistinguishable, from the
-        // outside, from a walk that looked everywhere and found nothing.  With a
-        // SHARED budget (cross-region's one k·W allowance per tier) an EARLIER
-        // pair can drain it, so a later pair's exact tier may never run at all;
-        // this counter is the only thing that says so.
+        // BUDGET EXHAUSTION IS AN ABSTENTION, AND IT MUST BE VISIBLE
+        // (INVARIANTS.md). The walk stops with work still on the stack, the caller
+        // reads "no container" and falls through to a lower ladder rung —
+        // indistinguishable, from the outside, from a walk that looked everywhere
+        // and found nothing. With a SHARED budget (cross-region's one k·W allowance
+        // per tier) an EARLIER pair can drain it, so a later pair's exact tier may
+        // never run at all; this counter is the only thing that says so.
         if (b.n-- <= 0) {
             if (ctx.meter)
                 ctx.meter.junctionBudgetExhausted++;