@hviana/sema 0.7.9 → 0.8.1

package/dist/src/mind/learning.js

@@ -268,7 +268,8 @@ function constituentSketch(ctx, id, k) {
                     pool.push(g);
             }
         }
-        // Bottom-k by identity, then by id so ties are corpus-determined (§2.1).
+        // Bottom-k by identity, then by id so ties are corpus-determined
+        // (determinism.md).
         pool.sort((a, b) => (unitPriority(a) - unitPriority(b)) || (a - b));
         const seen = new Set();
         out = [];
@@ -331,15 +332,15 @@ function constituentSketch(ctx, id, k) {
  *  terms unique to that partner, which dilute but never mislead; the shared
  *  units contribute the signal.
  *
- *  HUBS ARE THE ONE EXCLUSION, read LIMITed as `parentsFirst(n, bound+1)` —
- *  the store's own exact hub-or-not probe (a result longer than the bound
- *  means MORE than the bound), never a fan-in-sized read.  A constituent with
- *  more than √N structural parents is scaffolding by §8.8's bound: " is ",
- *  "the ".  Superposing it would put a term shared by every deposit into every
- *  profile, ALL halos would correlate, and the concept threshold's null model
- *  (unrelated halos at 0 ± 1/√D) that §4.1's hygiene note protects would
- *  collapse.  It is still DESCENDED into — a hub chunk can contain a rare
- *  unit — but contributes nothing itself.
+ *  HUBS ARE THE ONE EXCLUSION, read LIMITed as `parentsFirst(n, bound+1)` — the
+ * store's own exact hub-or-not probe (a result longer than the bound means MORE
+ * than the bound), never a fan-in-sized read. A constituent with more than √N
+ * structural parents is scaffolding by bounded-reads.md's bound: " is ", "the
+ * ". Superposing it would put a term shared by every deposit into every
+ * profile, ALL halos would correlate, and the concept threshold's null model
+ * (unrelated halos at 0 ± 1/√D) that halo-sketch.md's hygiene note protects
+ * would collapse. It is still DESCENDED into — a hub chunk can contain a rare
+ * unit — but contributes nothing itself.
  *
  *  Byte atoms are skipped in BOTH representations (a negative id and a stored
  *  kid-less node): an atom's fan-in is the alphabet's, so it can only ever
@@ -349,32 +350,32 @@ function constituentSketch(ctx, id, k) {
  *  analogy strength 0.3636 -> 0.2004, "no halo-tier company evidence",
  *  test/29 C1).
  *
- *  A FUNCTION OF THE NODE AND THE CORPUS STATE — stated precisely, because
- *  the weaker claim is the true one.  The constituents are read from the
- *  STORE, never from the depositing tree's id map: that map holds only the
- *  nodes THIS deposit newly interned, so a partner met a second time yielded a
- *  profile missing exactly those constituents, the exact-partner case fell
- *  from cosine 1 to 1/√(1+k), and the geometry stopped meaning anything.
- *  Reading the store fixes that.  It does NOT make the profile permanent: the
- *  hub test reads fan-in against √N and both grow with training, so a partner
- *  poured early and again late can profile differently.  That residue is
- *  confined to the hub EXCLUSION — which terms are dropped as scaffolding —
- *  and never to which units are found, because the descent itself is now
- *  order-independent.  The drift is one-directional and benign: a term can
- *  only ever go from contributing to being excluded as scaffolding.  Replay of
- *  a fixed training order is bit-identical, so §2.1 holds.  What must not be
- *  claimed is that a node's profile is fixed for all time; it is fixed given
- *  the corpus that has been seen.
+ *  A FUNCTION OF THE NODE AND THE CORPUS STATE — stated precisely, because the
+ * weaker claim is the true one. The constituents are read from the STORE, never
+ * from the depositing tree's id map: that map holds only the nodes THIS deposit
+ * newly interned, so a partner met a second time yielded a profile missing
+ * exactly those constituents, the exact-partner case fell from cosine 1 to
+ * 1/√(1+k), and the geometry stopped meaning anything. Reading the store fixes
+ * that. It does NOT make the profile permanent: the hub test reads fan-in
+ * against √N and both grow with training, so a partner poured early and again
+ * late can profile differently. That residue is confined to the hub EXCLUSION —
+ * which terms are dropped as scaffolding — and never to which units are found,
+ * because the descent itself is now order-independent. The drift is
+ * one-directional and benign: a term can only ever go from contributing to
+ * being excluded as scaffolding. Replay of a fixed training order is
+ * bit-identical, so determinism.md holds. What must not be claimed is that a
+ * node's profile is fixed for all time; it is fixed given the corpus that has
+ * been seen.
  *
- *  THE NULL MODEL IS OTHERWISE UNTOUCHED (§4.1).  Every term is still a seeded
- *  function of a NODE IDENTITY, never a gist, so no byte-similarity between
- *  partners can leak content similarity into distributional similarity.  The
- *  result is normalized, so ONE episode still pours ONE unit of mass:
- *  {@link Store.haloMass} keeps counting episodes and every mass-based
- *  reading is unchanged.  Two partners sharing j of k discriminating
- *  constituents meet at j/(1+k) — graded evidence, above the 1/√D noise floor
- *  and below conceptThreshold until the overlap is most of the content, which
- *  is the semantics "same company" should have.
+ * THE NULL MODEL IS OTHERWISE UNTOUCHED (halo-sketch.md). Every term is still a
+ * seeded function of a NODE IDENTITY, never a gist, so no byte-similarity
+ * between partners can leak content similarity into distributional similarity.
+ * The result is normalized, so ONE episode still pours ONE unit of mass: {@link
+ * Store.haloMass} keeps counting episodes and every mass-based reading is
+ * unchanged. Two partners sharing j of k discriminating constituents meet at
+ * j/(1+k) — graded evidence, above the 1/√D noise floor and below
+ * conceptThreshold until the overlap is most of the content, which is the
+ * semantics "same company" should have.
  *
  *  Bounded: at most {@link PROFILE_VISITS} constituents are classified, each
  *  by ONE LIMITed structural-parent read, so a pour costs O(1) reads in the

package/dist/src/mind/match.js

@@ -934,24 +934,25 @@ export async function project(ctx, id, guide) {
 }
 // ── The span-shape family ───────────────────────────────────────────────────
 //
-// "Is this answer drawn from this context?" has TWO formally distinct
-// readings, and the pair plus the anchor classifier built on them are SHARED
-// machinery — extraction proposes span-shaped exemplars with them, the
-// shared `Precomputed.spanShapedOf` container computes them, and fusion
-// (reasoning.ts) gates on the strict one.  They lived inside
-// mechanisms/extraction.ts, so `pipeline-mechanism.ts` and `reasoning.ts`
-// both had to import back OUT of a specific mechanism — an inversion the
-// mechanism market forbids (AGENTS §2.6: the shared contract may not depend
-// on any one mechanism; §2.5: a shared matcher belongs to this family, never
-// to a mechanism's private helpers).  Deleting extraction must not break the
-// shared container, so they live here.
+// "Is this answer drawn from this context?" has TWO formally distinct readings,
+// and the pair plus the anchor classifier built on them are SHARED machinery —
+// extraction proposes span-shaped exemplars with them, the shared
+// `Precomputed.spanShapedOf` container computes them, and fusion (reasoning.ts)
+// gates on the strict one. They lived inside mechanisms/extraction.ts, so
+// `pipeline-mechanism.ts` and `reasoning.ts` both had to import back OUT of a
+// specific mechanism — an inversion the mechanism market forbids: the shared
+// contract may not depend on any one mechanism (mechanism-market.md), and a
+// shared matcher belongs to this family (match-project.md), never to a
+// mechanism's private helpers. Deleting extraction must not break the shared
+// container, so they live here.
 //
 //   • isSpanShaped  — the OPEN reading (sparse in-order embedding).
 //   • containsSpan  — the STRICT reading (contiguous run or resolved node).
 //   • skillExemplar — classify one anchor into (context, answer) using them.
 //
-// The two readings are NOT interchangeable; AGENTS §2.5 pins the distinction
-// and each function's own doc states what breaks if it is substituted.
+// The two readings are NOT interchangeable; match-project.md pins the
+// distinction and each function's own doc states what breaks if it is
+// substituted.
 /** Check whether an anchor is a span-shaped skill exemplar: it represents a
  *  fact whose context and answer together form a span-in-context pattern.
  *  If the anchor has a nextOf continuation, that is the answer and the anchor

package/dist/src/mind/mechanisms/cover.js

@@ -4,7 +4,7 @@
 // Cover consumes recognition directly (its axioms are the query's own
 // decomposition) plus the computed spans any parse()-bearing mechanism
 // contributed: computed spans MASK colliding recognised sites and enter the
-// search at zero cost ("computation always wins", §16.3) — which is also why
+// search at zero cost ("computation always wins", alu.md) — which is also why
 // cover runs FIRST in defaultMechanisms: a computed-backed cover becomes a
 // near-zero-cost incumbent that prunes the other mechanisms through the
 // ordinary admissible-floor check, with no extension special-case anywhere.
@@ -59,22 +59,23 @@ export async function resolveConnectors(ctx, sites, query) {
             return true;
         const continuations = ctx.store.nextFirst(s.payload, hubBound(ctx));
         return !continuations.some((answer) => {
-            // PREFIX-CAPPED (AGENTS §2.8): a candidate longer than the query cannot
-            // occur INSIDE it, so read one byte past the query's length — enough to
-            // detect the overflow — and reject without reconstructing the rest.
-            // The `+ 1` is what makes the test exact rather than a truncation: a
-            // result of exactly `query.length + 1` bytes is known to be too long,
-            // and anything shorter is the candidate's COMPLETE content, so the
-            // substring test below is the same test as before.  (The same overflow
-            // probe bridge.ts:256 already uses.)
+            // PREFIX-CAPPED (bounded-reads.md): a candidate longer than the query
+            // cannot occur INSIDE it, so read one byte past the query's length —
+            // enough to detect the overflow — and reject without reconstructing the
+            // rest. The `+ 1` is what makes the test exact rather than a
+            // truncation: a result of exactly `query.length + 1` bytes is known to
+            // be too long, and anything shorter is the candidate's COMPLETE
+            // content, so the substring test below is the same test as before. (The
+            // same overflow probe bridge.ts:256 already uses.)
             //
             // This loop runs up to hubBound(ctx) = √N reads PER SITE, and only on a
             // multi-turn response — `answeredSpans` is empty for a plain respond(),
-            // so the probe does not execute there.  The cap cannot reduce the read
+            // so the probe does not execute there. The cap cannot reduce the read
             // COUNT — only a semantic change to the "already answered" test could —
             // but it bounds each read by the query instead of by the corpus, which
-            // is what §2.8 asks for and what rescues a SHORT query: at 3 bytes this
-            // reads 4 bytes per candidate instead of the ~231 it averaged before.
+            // is what bounded-reads.md asks for and what rescues a SHORT query: at
+            // 3 bytes this reads 4 bytes per candidate instead of the ~231 it
+            // averaged before.
             const bytes = read(ctx, answer, query.length + 1);
             return bytes.length <= query.length && indexOf(query, bytes, 0) >= 0;
         });

package/dist/src/mind/mechanisms/prefix-completion.js

@@ -1,15 +1,15 @@
 // mechanisms/prefix-completion.ts — Grounding a query that IS the opening of a
 // trained form (Grounding V).
 //
-// A MECHANISM, NOT A TIER.  This used to run inside recall's refusal path, in
-// a fixed if-chain that first-match-wins — the shape CAST was refactored away
-// from, where placement rather than the cost ladder decided.  Its claim is
+// A MECHANISM, NOT A TIER. This used to run inside recall's refusal path, in a
+// fixed if-chain that first-match-wins — the shape CAST was refactored away
+// from, where placement rather than the cost ladder decided. Its claim is
 // maximal (every query byte literally matched, from offset zero, against a
 // trained form) at one STEP, so as a market candidate it competes honestly and
-// the decider weighs it like everything else.  It is registered LAST: recall's
+// the decider weighs it like everything else. It is registered LAST: recall's
 // exact self-match makes an IDENTITY claim about the query while this makes a
-// CONTAINMENT one, and on an exact grade tie the identity claim is the
-// stronger evidence — the same ordering §2.3's ladders use.
+// CONTAINMENT one, and on an exact grade tie the identity claim is the stronger
+// evidence — the same ordering exact-vs-approximate.md's ladders use.
 //
 // Its SUPPLY moved too, and further: `formsOpenedBy` (traverse.ts) answers a
 // question about the STORE — "which trained forms does this byte run open?" —
@@ -49,12 +49,12 @@
 //
 // So this is a RETRIEVABILITY gap, not a semantic one, and the ANN is the wrong
 // instrument for it: a proper prefix's gist cannot rank its own continuation.
-// The repair is CONTENT-ADDRESSED (§2.3) — `formsOpenedBy` (traverse.ts) reads
-// the leaf-id WINDOW index the write side already maintains and answers "which
-// trained forms does this byte run open?" in a bounded √N walk.  That is this
-// mechanism's first supply.  The response's memoised top-k `resonance()` is the
-// second, for prefixes long enough that the gist still ranks the form; it is
-// read, never re-issued.
+// The repair is CONTENT-ADDRESSED (exact-vs-approximate.md) — `formsOpenedBy`
+// (traverse.ts) reads the leaf-id WINDOW index the write side already maintains
+// and answers "which trained forms does this byte run open?" in a bounded √N
+// walk. That is this mechanism's first supply. The response's memoised top-k
+// `resonance()` is the second, for prefixes long enough that the gist still
+// ranks the form; it is read, never re-issued.
 //
 // AN EXHAUSTIVE ANN LIST IS NOT A SUPPLY HERE, AND WAS REMOVED.  This tier once
 // read `Precomputed.wideResonance()` — a full-index `resonate(guide, √N,
@@ -227,20 +227,20 @@ export const prefixMechanism = {
         return STEP;
     },
     async run(ctx, query, pre) {
-        // ONE SUPPLY PASS, not a two-tier `??`.  The window index (exact,
+        // ONE SUPPLY PASS, not a two-tier `??`. The window index (exact,
         // content-addressed) and the response's memoised top-k (approximate) are
-        // concatenated and the three guards decide ONCE over the union.  A
+        // concatenated and the three guards decide ONCE over the union. A
         // first-then-fallback chain would let the APPROXIMATE tier override the
-        // EXACT one (§2.3): when formsOpenedBy finds two continuations, guard 3
-        // returns null and the fallback re-runs the guards on resonance's top-k
-        // alone — which, seeing only one of the two forms, would voice it.  That is
-        // precisely the disagreement-suppression guard 3 exists to prevent, and it
-        // is the exact tier's ambiguity being washed away by the approximate tier.
-        // Evaluating the union means a disagreement the window index saw can never
-        // be hidden by what the ANN happens to rank.  The ANN read is the
-        // response's ONE memoised top-k (§2.11), already paid by recall's refusal
-        // path on the queries where this mechanism fires, so reading it here is not
-        // a second index scan.
+        // EXACT one (exact-vs-approximate.md): when formsOpenedBy finds two
+        // continuations, guard 3 returns null and the fallback re-runs the guards
+        // on resonance's top-k alone — which, seeing only one of the two forms,
+        // would voice it. That is precisely the disagreement-suppression guard 3
+        // exists to prevent, and it is the exact tier's ambiguity being washed away
+        // by the approximate tier. Evaluating the union means a disagreement the
+        // window index saw can never be hidden by what the ANN happens to rank. The
+        // ANN read is the response's ONE memoised top-k (memoization.md), already
+        // paid by recall's refusal path on the queries where this mechanism fires,
+        // so reading it here is not a second index scan.
         const ids = [
             ...formsOpenedBy(ctx, query),
             ...(await pre.resonance()).map((h) => h.id),

package/dist/src/mind/mechanisms/recall.js

@@ -159,24 +159,22 @@ export async function recallByResonance(ctx, query, pre) {
             }
         }
     }
-    // The query-relative grounding fraction, shared by tiers 2–4 — gated on
-    // the FRACTION OF THE QUERY the grounding explains, not the raw cosine.
-    // Root gists are unit vectors, but their magnitudes are recoverable from
-    // the byte lengths (‖·‖ = √len under the linear fold):
-    // cos = shared/√(lenQ·lenG), so shared/lenQ = cos·√(lenG/lenQ).
-    // The raw cosine punished honest containment — a query fully inside a
-    // longer grounded answer scored √(lenQ/lenG) and was refused — and let a
-    // long answer sharing only scaffolding pass; the query-relative fraction
-    // measures exactly what the reach bar means: how much of THE QUERY the
-    // store accounts for.
-    // Chance similarity survives the length conversion AMPLIFIED: the same
-    // √(lenG/lenQ) factor that converts an honest shared fraction into a
-    // query-relative one multiplies the estimator/chance floor too, so a long
-    // stored form (√(lenG/lenQ) ≈ 10 at 100×) lifted a noise-level cosine past
-    // the reach bar and grounded pure gibberish (observed).  Only the
-    // ABOVE-CHANCE part of the similarity is evidence of shared content —
-    // subtract the significance bar (3/√D, §8.3) before converting.  Derived
-    // from the existing bars; never tuned.
+    // The query-relative grounding fraction, shared by tiers 2–4 — gated on the
+    // FRACTION OF THE QUERY the grounding explains, not the raw cosine. Root
+    // gists are unit vectors, but their magnitudes are recoverable from the byte
+    // lengths (‖·‖ = √len under the linear fold): cos = shared/√(lenQ·lenG), so
+    // shared/lenQ = cos·√(lenG/lenQ). The raw cosine punished honest containment
+    // — a query fully inside a longer grounded answer scored √(lenQ/lenG) and was
+    // refused — and let a long answer sharing only scaffolding pass; the
+    // query-relative fraction measures exactly what the reach bar means: how much
+    // of THE QUERY the store accounts for. Chance similarity survives the length
+    // conversion AMPLIFIED: the same √(lenG/lenQ) factor that converts an honest
+    // shared fraction into a query-relative one multiplies the estimator/chance
+    // floor too, so a long stored form (√(lenG/lenQ) ≈ 10 at 100×) lifted a
+    // noise-level cosine past the reach bar and grounded pure gibberish
+    // (observed). Only the ABOVE-CHANCE part of the similarity is evidence of
+    // shared content — subtract the significance bar (3/√D, thresholds.md) before
+    // converting. Derived from the existing bars; never tuned.
     const sig = significanceBar(ctx.store.D);
     const reach = reachThreshold(ctx.space.maxGroup);
     const fracOfQuery = (cos, otherLen) => Math.min(1, Math.max(0, cos - sig) *
@@ -305,14 +303,14 @@ export async function recallByResonance(ctx, query, pre) {
             }
         }
     }
-    // 3b. Corroborated-substitution bridge — refusal-path only (bridge.ts).
-    // The bridge's proposal source is the response's ONE top-k read — the same
-    // list recall already ranked above — never an exhaustive √N scan.  The
-    // bridge's own candidate cap is 2·recallQueryK, so top-k proposals are
-    // exactly the budget it can consume, and every proposal is byte-verified
-    // downstream (§2.3).  Reuse the memoised `resonance()`; scanning every IVF
-    // cluster here once made every honest refusal cost hundreds of ms regardless
-    // of k.
+    // 3b. Corroborated-substitution bridge — refusal-path only (bridge.ts). The
+    // bridge's proposal source is the response's ONE top-k read — the same list
+    // recall already ranked above — never an exhaustive √N scan. The bridge's own
+    // candidate cap is 2·recallQueryK, so top-k proposals are exactly the budget
+    // it can consume, and every proposal is byte-verified downstream
+    // (exact-vs-approximate.md). Reuse the memoised `resonance()`; scanning every
+    // IVF cluster here once made every honest refusal cost hundreds of ms
+    // regardless of k.
     const wideIds = async () => (await pre.resonance()).map((h) => h.id);
     // Every gist-based tier has failed; before refusing, align the query
     // byte-for-byte against the trained contexts its own stored windows
@@ -362,12 +360,12 @@ export async function recallByResonance(ctx, query, pre) {
             // prefixCompletion runs a few lines below and carries the three guards
             // this tier lacks — unreadable-continuation veto, sub-quantum
             // continuation, and UNIQUENESS (distinct continuations ⇒ refuse), which
-            // is exactly what 4,300 competing values must trip.  So this is not a
-            // new rule and not a new threshold: it is deferring a prefix decision to
-            // the tier that owns it (§2.5, one factored machinery).  Byte-strict on
-            // purpose — a candidate differing by case or punctuation ("what is the
-            // capital of france" → "What is the capital of France?") is NOT a byte
-            // prefix, keeps grounding here, and is unaffected.
+            // is exactly what 4,300 competing values must trip. So this is not a new
+            // rule and not a new threshold: it is deferring a prefix decision to the
+            // tier that owns it (match-project.md, one factored machinery).
+            // Byte-strict on purpose — a candidate differing by case or punctuation
+            // ("what is the capital of france" → "What is the capital of France?") is
+            // NOT a byte prefix, keeps grounding here, and is unaffected.
             const strictPrefix = g !== null &&
                 cBytes.length > query.length &&
                 indexOf(cBytes, query, 0) === 0;
@@ -425,15 +423,15 @@ export async function recallByResonance(ctx, query, pre) {
             }
         }
     }
-    // The refusal/echo decision.  The echo returns a stored form's bytes AS
-    // the answer — a near-identity claim about the query — and identity-grade
+    // The refusal/echo decision. The echo returns a stored form's bytes AS the
+    // answer — a near-identity claim about the query — and identity-grade
     // decisions are never made on an estimated score ("approximate scores may
-    // rank and propose; they may never decide", §6.2): the RaBitQ estimate
-    // overshooting the reach bar echoed a WRONG-entity neighbour ("capital of
-    // Zamunda?" echoed the Armenia fact, observed).  The bytes are read
-    // anyway to be echoed, so the decision uses their EXACT fold: one river
-    // fold of the top hit, measured in the same query-relative,
-    // chance-corrected units as the tier above.
+    // rank and propose; they may never decide", exact-vs-approximate.md): the
+    // RaBitQ estimate overshooting the reach bar echoed a WRONG-entity neighbour
+    // ("capital of Zamunda?" echoed the Armenia fact, observed). The bytes are
+    // read anyway to be echoed, so the decision uses their EXACT fold: one river
+    // fold of the top hit, measured in the same query-relative, chance-corrected
+    // units as the tier above.
     const topBytes = read(ctx, top.id);
     const exact = topBytes.length > 0
         ? cosine(queryGist, gistOf(ctx, topBytes))

package/dist/src/mind/mechanisms/reference.js

@@ -2,8 +2,8 @@
 // bytes (Grounding IV).
 //
 // This file is a CONFIGURATION of the shared frame reading in match.ts, not a
-// pipeline of its own.  The three parts it configures live where §2.5 puts
-// them and are reachable by any mechanism:
+// pipeline of its own. The three parts it configures live where
+// match-project.md puts them and are reachable by any mechanism:
 //
 //   matcher     Precomputed.frames() — the frame INVENTORY: which ranked
 //               candidates read as instances of the query's own frame, and
@@ -29,10 +29,10 @@
 // candidate's continuation UNSUBSTITUTED, so admitting a slot-gap there would
 // voice the corpus's filler for the asker's referent — the misreference
 // measured live on the trained store ("How do you say 'flurbish' in French?"
-// answered "the way to say hello is \"Bonjour\"").  Nor is CAST rewired: its
+// answered "the way to say hello is \"Bonjour\""). Nor is CAST rewired: its
 // frame gate is WEAVE-local while a slot is COHORT-local, and substituting one
-// population for the other is the error §2.7 names.  The notion is made
-// AVAILABLE, never imposed.
+// population for the other is the error commonality.md names. The notion is
+// made AVAILABLE, never imposed.
 import { carriesFillers, distinct, follow, substituteAll } from "../match.js";
 import { dominates } from "../../geometry.js";
 import { bytesEqual, indexOf } from "../../bytes.js";
@@ -43,16 +43,16 @@ import { rItem, rNode, traceFail } from "../trace.js";
  *  agrees with nothing, so no carriage is attested — the same "two or no
  *  constituent" reading frame-filler's contentRuns applies.
  *
- *  THIS IS ALSO THE MECHANISM'S REACH.  Evidence comes from the shared top-k
- *  resonance, so a frame the corpus instantiates only ONCE within k is not
- *  reachable here.  Measured on the trained store: `How do you say 'flurbish'
- *  in French?` finds one instance of its frame in the top 24 — the rest are
- *  `How do you make …`, a different frame — so this abstains and recall's
- *  scaffolding-dominated tier answers with the CORPUS's filler.  That
- *  misreference is recall's, and widening the supply is not the fix: the
- *  exhaustive √N list recall's refusal path builds costs hundreds of
- *  milliseconds and this runs before it.  Abstaining on thin evidence is the
- *  honest reading (§2.13). */
+ *  THIS IS ALSO THE MECHANISM'S REACH. Evidence comes from the shared top-k
+ * resonance, so a frame the corpus instantiates only ONCE within k is not
+ * reachable here. Measured on the trained store: `How do you say 'flurbish' in
+ * French?` finds one instance of its frame in the top 24 — the rest are `How do
+ * you make …`, a different frame — so this abstains and recall's
+ * scaffolding-dominated tier answers with the CORPUS's filler. That
+ * misreference is recall's, and widening the supply is not the fix: the
+ * exhaustive √N list recall's refusal path builds costs hundreds of
+ * milliseconds and this runs before it. Abstaining on thin evidence is the
+ * honest reading (INVARIANTS.md). */
 const MIN_INSTANCES = 2;
 /** THE VOICING GATES — this mechanism's own reading of a pairing, applied here
  *  and NOT in the shared matcher.
@@ -123,7 +123,7 @@ function electFrame(inventory, W, queryLen) {
     let best = [];
     for (const group of bySignature.values()) {
         // Ties keep the FIRST group in insertion order, which is resonance rank —
-        // corpus-determined, like every other tie-break here (§2.1).
+        // corpus-determined, like every other tie-break here (determinism.md).
         if (group.length > best.length)
             best = group;
     }

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

@@ -64,13 +64,12 @@ export interface MindOptions {
     /** Factories that receive the {@link ExtensionHost} and return mechanisms. */
     mechanismFactories?: ((host: import("../extension.js").ExtensionHost) => import("./pipeline-mechanism.js").PipelineMechanism)[];
     /** Measure the computational usage of every inference call — see
-     *  src/meter.ts.  Off by default and free when off (one null check per
-     *  store read); on, each `respond`/`respondTurn` leaves a {@link
-     *  Mind.lastCost} report behind.  Counters are deterministic, so two runs
-     *  of the same query on the same store are diffable; the millisecond
-     *  fields are not.  Profiling NEVER changes an answer — but note that
-     *  attaching a RATIONALE does (traced responses bypass the ctx memos,
-     *  AGENTS §2.11), so profile without a trace. */
+     *  src/meter.ts. Off by default and free when off (one null check per store
+     * read); on, each `respond`/`respondTurn` leaves a {@link Mind.lastCost}
+     * report behind. Counters are deterministic, so two runs of the same query on
+     * the same store are diffable; the millisecond fields are not. Profiling
+     * NEVER changes an answer — but attaching a RATIONALE does: a traced response
+     * bypasses the ctx memos (memoization.md), so profile without a trace. */
     profile?: boolean;
     /** Content canonicalizer applied to EVERY response (any modality) for
      *  equivalence-class resolution — see src/canon.ts.  Text entry points

package/dist/src/mind/pipeline-mechanism.d.ts

@@ -69,14 +69,16 @@ export declare class Precomputed {
      *  ({@link FrameInstance}).  The one place the engine represents "a position
      *  whose occupant comes from the context rather than the corpus".
      *
-     *  AN INVENTORY, NOT AN ELECTION.  It reports every pairing and elects no
-     *  frame, deliberately: a slot is a property of a PAIRING, not of the query,
-     *  and different candidates put slots in different places.  Committing to one
-     *  reading here would push whichever consumer asked first onto everyone else
-     *  — the market's decoupling (§2.6) broken from inside the shared container,
-     *  and the population error §2.7 names.  Each consumer groups and commits
-     *  for its own question; reference elects the modal slot signature, and a
-     *  consumer wanting a different reading is not fighting this one.
+     * AN INVENTORY, NOT AN ELECTION. It reports every pairing and elects no
+     * frame,
+     * deliberately: a slot is a property of a PAIRING, not of the query, and
+     * different candidates put slots in different places. Committing to one
+     * reading here would push whichever consumer asked first onto everyone else —
+     * the market's decoupling (mechanism-market.md) broken from inside the shared
+     * container, and the population error commonality.md names. Each consumer
+     * groups and commits for its own question; reference elects the modal slot
+     * signature, and a consumer wanting a different reading is not fighting this
+     * one.
      *
      *  NO LICENCE EITHER.  Knowing a span is variable is safe for every consumer
      *  — it can only improve an alignment.  Knowing one may be VOICED through is

package/dist/src/mind/pipeline-mechanism.js

@@ -5,7 +5,7 @@
 // a list of PipelineMechanism objects — it never imports a mechanism-specific
 // type and never has a special-case branch for any mechanism.
 //
-// The four constraints of the free-will architecture (§14.5):
+// The four constraints of the free-will architecture (mechanism-market.md):
 //   1. DECOUPLING — mechanisms import nothing from each other or from pipeline.
 //   2. DECLARED COMPETENCE — floor() returns null when impossible, a number when
 //      possible.  Binary, auditable, no learned scores.
@@ -128,31 +128,33 @@ export class Precomputed {
     resonance() {
         return this._resonance ??= this.shared("resonance", () => this.ctx.store.resonate(this.guide, this.k));
     }
-    // REMOVED — the WIDE exhaustive-√N resonance list (`wideResonance`).  It ran
+    // REMOVED — the WIDE exhaustive-√N resonance list (`wideResonance`). It ran
     // `resonate(guide, √N, exhaustive=true)` whenever the top hit cleared
-    // conceptThreshold, so consumers could look "past the top-k".  Every consumer
+    // conceptThreshold, so consumers could look "past the top-k". Every consumer
     // only ever needed ≤ 2·recallQueryK proposals (the substitution bridge's own
     // candidate cap) or a content-addressed answer (prefix completion's
-    // formsOpenedBy), and every proposal is byte-verified downstream (§2.3), so
-    // the exhaustive scan bought recall at O(index) cost for an O(k) need —
-    // measured: 244K annVectorReads per refusing query, ~1.5 s, every answer
-    // byte-identical to a top-k read.  The two consumers now read `resonance()`
-    // (the one top-k read) and the write side's window index respectively — see
-    // recall.ts and prefix-completion.ts.
+    // formsOpenedBy), and every proposal is byte-verified downstream
+    // (exact-vs-approximate.md), so the exhaustive scan bought recall at O(index)
+    // cost for an O(k) need — measured: 244K annVectorReads per refusing query,
+    // ~1.5 s, every answer byte-identical to a top-k read. The two consumers now
+    // read `resonance()` (the one top-k read) and the write side's window index
+    // respectively — see recall.ts and prefix-completion.ts.
     _frames;
     /** THE FRAME INVENTORY — every ranked candidate that reads as an instance of
      *  the same frame as the query, each with the query spans it leaves VARIABLE
      *  ({@link FrameInstance}).  The one place the engine represents "a position
      *  whose occupant comes from the context rather than the corpus".
      *
-     *  AN INVENTORY, NOT AN ELECTION.  It reports every pairing and elects no
-     *  frame, deliberately: a slot is a property of a PAIRING, not of the query,
-     *  and different candidates put slots in different places.  Committing to one
-     *  reading here would push whichever consumer asked first onto everyone else
-     *  — the market's decoupling (§2.6) broken from inside the shared container,
-     *  and the population error §2.7 names.  Each consumer groups and commits
-     *  for its own question; reference elects the modal slot signature, and a
-     *  consumer wanting a different reading is not fighting this one.
+     * AN INVENTORY, NOT AN ELECTION. It reports every pairing and elects no
+     * frame,
+     * deliberately: a slot is a property of a PAIRING, not of the query, and
+     * different candidates put slots in different places. Committing to one
+     * reading here would push whichever consumer asked first onto everyone else —
+     * the market's decoupling (mechanism-market.md) broken from inside the shared
+     * container, and the population error commonality.md names. Each consumer
+     * groups and commits for its own question; reference elects the modal slot
+     * signature, and a consumer wanting a different reading is not fighting this
+     * one.
      *
      *  NO LICENCE EITHER.  Knowing a span is variable is safe for every consumer
      *  — it can only improve an alignment.  Knowing one may be VOICED through is
@@ -168,9 +170,10 @@ export class Precomputed {
             const capBytes = this.query.length * W;
             const out = [];
             for (const h of await this.resonance()) {
-                // REJECT BY LENGTH BEFORE RECONSTRUCTING (§2.8): `contentLen` is an
-                // indexed read, `bytesPrefix` rebuilds a subtree.  ONLY the phrase-scale
-                // cap is applied — it is a bounded-read discipline, not a judgement.
+                // REJECT BY LENGTH BEFORE RECONSTRUCTING (bounded-reads.md):
+                // `contentLen` is an indexed read, `bytesPrefix` rebuilds a subtree.
+                // ONLY the phrase-scale cap is applied — it is a bounded-read
+                // discipline, not a judgement.
                 //
                 // A LOWER bound was here too (`dominates(len, query.length)`, on the
                 // reasoning that a candidate shorter than half the query cannot supply
@@ -458,7 +461,8 @@ function computeWeave(ctx, query, pre, climb) {
     // IDF — gates the aligner has no equivalent of.
     //
     // So the climb PROPOSES the pairing (which structure, which query span) and
-    // bytes DECIDE its terms (§2.3).  Three gates, each one measured:
+    // bytes DECIDE its terms (exact-vs-approximate.md). Three gates, each one
+    // measured:
     //
     //   • it may only take query bytes NO literal run claimed.  Run inline with
     //     phase 1 this did the opposite of "exact decides" — a higher-ranked

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

@@ -38,15 +38,15 @@ export interface NarrowDecisionData {
     margin: number;
 }
 /** Structured payload of the "regimePrediction" rationale step — the R8
- *  observation exposed as data.  After the first mechanism (cover, which §2.6
- *  runs first) grounds or abstains, the market's whole outcome is already
- *  determined by the one cost ladder: the consensus climb runs exactly when
- *  `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is the cheapest
- *  mechanism that first-touches it, and confluence (3·STEP) / extraction
- *  (CONCEPT+STEP) are only reached after CAST is.  An incumbent at or below
- *  that floor prunes CAST and, with it, the climb (retrieval); anything above
- *  — or no incumbent — runs the full market and the climb (composition).
- *  Purely observational; never read by inference. */
+ *  observation exposed as data. After the first mechanism (cover, which
+ * mechanism-market.md runs first) grounds or abstains, the market's whole
+ * outcome is already determined by the one cost ladder: the consensus climb
+ * runs exactly when `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is
+ * the cheapest mechanism that first-touches it, and confluence (3·STEP) /
+ * extraction (CONCEPT+STEP) are only reached after CAST is. An incumbent at or
+ * below that floor prunes CAST and, with it, the climb (retrieval); anything
+ * above — or no incumbent — runs the full market and the climb (composition).
+ * Purely observational; never read by inference. */
 export interface RegimePredictionData {
     version: 1;
     /** retrieval | composition — the two regimes R1 measured as a ~100× cost