@hviana/sema 0.8.2 → 0.8.3

package/AGENTS.md

@@ -2,8 +2,8 @@
 
 The working manual for anyone (human or AI agent) changing Sema. For pattern
 detail, see `docs/INDEX.md` → `docs/architecture/*.md`. You should be able to
-develop against this document and docs/ alone; read the theory in
-`docs/architecture/` when you need why a pattern holds, not to get work done.
+develop against this document and docs/ alone; read `docs/architecture/` for why
+a pattern holds.
 
 ## 1. Orientation
 
@@ -14,7 +14,7 @@ accelerators), and a cost-based search that composes answers from stored facts
 the only runtime dependency.
 
 ```bash
-npm install        # dev tooling + parquet reader used by one example
+npm install        # dev tooling + parquet reader for one example
 npm run build      # tsc → dist/
 npm test           # tsc && node --test test/**/*.test.mjs
 npm run demo       # example/demo.ts — the four-note README demo
@@ -62,6 +62,7 @@ shared content-addressed ascent; `Precomputed` in
 `src/mind/pipeline-mechanism.ts` is the per-response lazy memo; `src/meter.ts`
 is the write-only work accounting surface. See `docs/INDEX.md` for the full
 contract table and `docs/architecture/factored-machinery.md` for ownership.
+Tie-breaks are corpus-determined, but not interchangeable (`determinism.md`).
 
 ## 3. Where things live
 
@@ -89,7 +90,7 @@ contract table and `docs/architecture/factored-machinery.md` for ownership.
 | Sublibraries (own READMEs)           | `src/derive/`, `src/alu/`, `src/rabitq-ivf/`                                                       |
 
 Mind functions are free functions over `MindContext` (`src/mind/types.ts`), not
-methods — `mind.ts` is a thin assembly that delegates.
+methods; `mind.ts` is a thin assembly.
 
 ## 4. Recipes
 
@@ -97,7 +98,7 @@ methods — `mind.ts` is a thin assembly that delegates.
 
 Implement `PipelineMechanism` (`floor` → admissible bound or `null`; `run` →
 candidates with `bytes`/`accounted`/`moves`/`unexplained` + optional
-`scaffolding`/`complete`). Register via
+`scaffolding`/`complete`/`used`). Register via
 `new Mind({ mechanismFactories: [host => yourMechanism(host)] })`. Verify the
 four market constraints (decoupled, declared competence, visible budget,
 evidence travels). → `docs/architecture/mechanism-market.md`
@@ -125,14 +126,13 @@ Run the full suite with your store substituted. → `docs/architecture/store.md`
 ## 5. Testing norms
 
 Tests are `node:test` suites in `test/*.test.mjs`, numbered by theme, run
-against built `dist/` (`npm test`; single suite:
-`node --test test/22-multihop.test.mjs` after `tsc`). New behaviour ⇒ test in
-the matching numbered suite or a new one. Many tests pin contracts that look
-like implementation details (ladder order, span-shape readings,
-`MechanismResult.complete`, fold invariance, recognition idempotence, honest
-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.
+against built `dist/` (`npm test`; one suite:
+`node --test test/22-multihop.test.mjs`). New behaviour ⇒ a test in the matching
+numbered suite. Many tests pin contracts that look like implementation details
+(ladder order, span-shape readings, `MechanismResult.complete`, fold invariance,
+recognition idempotence, honest 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. Instrumentation — the meter and the rationale ARE the dev surface
 
@@ -143,17 +143,17 @@ instrumentation, and the only ones. Both are read through the public path —
 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.)
+`meter.ts` (the one place a counter name exists), 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 stay:
+session-lifetime HEALTH counters, not per-response work.)
 
 ## 7. Dependencies and licensing
 
@@ -161,8 +161,8 @@ PolyForm Noncommercial 1.0.0 with separate commercial licensing (see
 `LICENSE.md`, `COMMERCIAL-LICENSE.md`, `TRADEMARKS.md`). The library has **no
 runtime dependencies** — pinned by `test/88-dependency-footprint.test.mjs`
 (`dist/src` may import only `node:` builtins and relative paths; `package.json`
-has no `dependencies`). Examples may use dev dependencies lazily via dynamic
-import only on the code path that needs them (`example/train_base` + `hyparquet`
-is the reference). Training corpora: a store retains text verbatim, so upstream
-licences apply in full — NonCommercial and ShareAlike corpora cannot enter a
-trainer; see `DATASETS.md`.
+has no `dependencies`). Examples may use dev dependencies via dynamic import
+only where needed (`example/train_base` + `hyparquet` is the reference).
+Training corpora: a store retains text verbatim, so upstream licences apply in
+full — NonCommercial and ShareAlike corpora cannot enter a trainer; see
+`DATASETS.md`.

package/TRADEMARKS.md

@@ -6,7 +6,6 @@ The following are not licensed under the software license:
 
 - redistribute its algorithmic logic: that is, how algorithms and mathematical
   techniques are combined to develop its machinery;
-- visual identity;
 - project name;
 - logos;
 - icons;

package/dist/src/config.d.ts

@@ -100,6 +100,17 @@ export interface MindConfig {
     seed: number;
     recallQueryK: number;
     haloQueryK: number;
+    /** Branch nodes the pivot sweep may PROBE looking for the learnt context an
+     *  answer contains — the pivot's own shortlist capacity, separate from
+     *  `recallQueryK` because they are different quantities: this one bounds a
+     *  MECHANICAL sweep over the answer's tree (breadth-first, largest regions
+     *  first, so an exhausted allowance drops the far ones and never the near
+     *  ones), while `recallQueryK` bounds the bridge's candidate reads.  Sharing
+     *  one number for both meant that tightening either silently starved the
+     *  other — measured: at `recallQueryK: 1` the pivot cannot find a pivot at
+     *  all.  (`rationaleSampleK` was split out of `recallQueryK` for the same
+     *  reason, found by an adversarial review.) */
+    pivotProbeK: number;
     /** Corpus reading (see src/mind/corpus.ts): results per call, resolved
      *  nodes climbed from, contexts requested per climb, probes used to stride
      *  the id space when browsing, bytes of each side a preview keeps, and the

package/dist/src/config.js

@@ -5,6 +5,7 @@ export const DEFAULT_CONFIG = {
     seed: 42,
     recallQueryK: 12,
     haloQueryK: 12,
+    pivotProbeK: 12,
     rationaleSampleK: 12,
     corpusLimitMax: 24,
     corpusClimbs: 24,
@@ -51,6 +52,7 @@ export function resolveConfig(opts = {}) {
         seed: opts.seed ?? DEFAULT_CONFIG.seed,
         recallQueryK: opts.recallQueryK ?? DEFAULT_CONFIG.recallQueryK,
         haloQueryK: opts.haloQueryK ?? DEFAULT_CONFIG.haloQueryK,
+        pivotProbeK: opts.pivotProbeK ?? DEFAULT_CONFIG.pivotProbeK,
         rationaleSampleK: opts.rationaleSampleK ?? DEFAULT_CONFIG.rationaleSampleK,
         corpusLimitMax: opts.corpusLimitMax ?? DEFAULT_CONFIG.corpusLimitMax,
         corpusClimbs: opts.corpusClimbs ?? DEFAULT_CONFIG.corpusClimbs,

package/dist/src/geometry.d.ts

@@ -106,6 +106,27 @@ export declare function dominates(partLen: number, wholeLen: number): boolean;
  *  Consumer: `companyProfile` (mind/learning.ts), which sizes its constituent
  *  sketch at this capacity instead of a visit budget. */
 export declare function profileCapacity(D: number): number;
+/**
+ *  The POOLED-vote significance floor, and the derivation lives here because
+ *  its PREMISE is a property of the caller's weighting.
+ *
+ *  DERIVATION (docs/architecture/thresholds.md §2): a maximally-specific region
+ *  contributes at most `ln N` to a pooled vote, so `ln(N) + 1/2` sits half a
+ *  unit above ONE region's ceiling — it demands corroboration BEYOND a single
+ *  region, which is what makes it a consensus bar rather than a resonance bar.
+ *
+ *  PREMISE: that per-region ceiling is an IDF, `ln(N/c)` — attention.ts's
+ *  `inverse` mode, the mode every non-test caller runs.  The other two modes
+ *  weight a region by `ln(1+c)` (`direct`) or `ln(N/c) + ln(1+c)` (`combined`),
+ *  i.e. `ln N + ln(1 + 1/c)`, so they exceed the premise's ceiling by at most
+ *  `ln 2` — a DERIVED bound, not a hole: the floor stays within `ln 2` of its
+ *  own premise in every mode, and exactly on it in `inverse`.
+ *
+ *  MEASURED: the floor is read on the pooled vote (`commitVotes`, `recall`,
+ *  `cast`).  Across 27 anchors on 6 queries, 11 cleared it by the sum and NONE
+ *  by a single region's peak — gating on one region would refuse every elected
+ *  root.
+ */
 export declare function consensusFloor(N: number): number;
 /** The coverage bar for the reach (interior) index, when vector-similarity
  *  gating is used.  Returns the concept threshold — the structural midpoint

package/dist/src/geometry.js

@@ -143,6 +143,27 @@ export function dominates(partLen, wholeLen) {
 export function profileCapacity(D) {
     return Math.max(1, Math.floor(Math.sqrt(D)));
 }
+/**
+ *  The POOLED-vote significance floor, and the derivation lives here because
+ *  its PREMISE is a property of the caller's weighting.
+ *
+ *  DERIVATION (docs/architecture/thresholds.md §2): a maximally-specific region
+ *  contributes at most `ln N` to a pooled vote, so `ln(N) + 1/2` sits half a
+ *  unit above ONE region's ceiling — it demands corroboration BEYOND a single
+ *  region, which is what makes it a consensus bar rather than a resonance bar.
+ *
+ *  PREMISE: that per-region ceiling is an IDF, `ln(N/c)` — attention.ts's
+ *  `inverse` mode, the mode every non-test caller runs.  The other two modes
+ *  weight a region by `ln(1+c)` (`direct`) or `ln(N/c) + ln(1+c)` (`combined`),
+ *  i.e. `ln N + ln(1 + 1/c)`, so they exceed the premise's ceiling by at most
+ *  `ln 2` — a DERIVED bound, not a hole: the floor stays within `ln 2` of its
+ *  own premise in every mode, and exactly on it in `inverse`.
+ *
+ *  MEASURED: the floor is read on the pooled vote (`commitVotes`, `recall`,
+ *  `cast`).  Across 27 anchors on 6 queries, 11 cleared it by the sum and NONE
+ *  by a single region's peak — gating on one region would refuse every elected
+ *  root.
+ */
 export function consensusFloor(N) {
     return Math.log(N) + 1 / 2;
 }

package/dist/src/meter.d.ts

@@ -162,9 +162,60 @@ export declare class Meter {
     joinNoKey: number;
     /** Refused: the fact contains no entity that leads anywhere. */
     joinNoEntity: number;
+    /** `recompleteNode` re-covered a produced form — the descent that decomposes
+     *  a completion by ITS OWN kids.  Without this the descent is invisible: a
+     *  caller could see the chain's result but not whether the recomposition
+     *  happened, so "the recursion stopped" and "the recursion never ran" were
+     *  indistinguishable from the counters alone. */
+    recompletes: number;
     /** Times the reasoner pivoted on a span its answer contains and stepped
      *  across that fact. */
     pivotSteps: number;
+    /** Canon probes REFUSED because the canon budget ran out — the one thing the
+     *  budget does that nothing could see.  The budget itself is derived
+     *  (`bytes.length · chainReach(W)²`, recognition.ts), and the cheap exact route
+     *  is deliberately unbudgeted, so this counter says exactly when the expensive
+     *  route was priced out.  Counted where the fact happens (the `!canonBudget`
+     *  refusal), not where the probe is called. */
+    canonProbesDenied: number;
+    /** The pipeline's remainder AT THE DECISION POINT, in bytes: what the grounded
+     *  answer plus the pre-computed spans left unexplained, after the same W floor
+     *  the fuse gate uses.  This is the quantity that licenses (or refuses) the
+     *  post-grounding extension and the fusion — it was computed, used, and never
+     *  published, so nothing could measure what a search had LEFT when it decided.
+     *  Read with {@link postGroundingRemainderSpans}. */
+    postGroundingRemainderBytes: number;
+    /** How many spans that remainder consists of (each at least one W window). */
+    postGroundingRemainderSpans: number;
+    /** Times `fuseAttention` produced a FUSED answer — not times it was called.
+     *  It is entered whenever the query has a remainder ≥ W and returns early when
+     *  there is nothing to bridge (`containsSpan`, a lone root, an empty pass), so
+     *  the call and the fact are different things and only the fact is counted.
+     *  Its own rationale step reports the fusion; this is the untraced view, and
+     *  its cost is one bridging edge: `fuseRuns · STEP`. */
+    fuseRuns: number;
+    /** Steps the post-grounding EXTENSION took — pivots plus forward-absorbs.
+     *  `pivotSteps` counts only the former, so before this the extension's COST was
+     *  not computable at all.  With it, the price of extending the answer is
+     *  `reasonSteps · STEP`, the ladder's own value for following an edge. */
+    reasonSteps: number;
+    /** Bytes of the grounding's UNCOVERED material the extension was justified by
+     *  — the union of the spans each step carried a `W`-window of.  The gate
+     *  already computed WHICH span carried it per step and kept only a boolean;
+     *  this is that fact, accumulated.  Read with {@link reasonSteps}: one is the
+     *  price, the other the explanation. */
+    reasonCarriedBytes: number;
+    /** Branch-node probes the pivot sweep actually spent looking for the learnt
+     *  context an answer contains (one `resonate` per probe).  The untraced view
+     *  of what the multi-hop's shortlist costs. */
+    pivotProbes: number;
+    /** Branch nodes the pivot's probe cap withheld (`branchCount − probeCap`, over
+     *  every call).  A capacity fact, not a verdict: the sweep is breadth-first,
+     *  so the probes it DOES spend are the largest regions, and recognition still
+     *  contributes every exact containment candidate regardless of the budget.
+     *  Read it with {@link pivotProbes} — one says the work, the other the
+     *  shortfall. */
+    pivotBranchesUnprobed: number;
     /** `bridge` calls the cover makes assembling connectors (pairwise + n-ary). */
     coverBridges: number;
     /** Continuations a CHAIN hop offered the search.  Bounded by the question

package/dist/src/meter.js

@@ -166,6 +166,12 @@ export class Meter {
     joinNoKey = 0;
     /** Refused: the fact contains no entity that leads anywhere. */
     joinNoEntity = 0;
+    /** `recompleteNode` re-covered a produced form — the descent that decomposes
+     *  a completion by ITS OWN kids.  Without this the descent is invisible: a
+     *  caller could see the chain's result but not whether the recomposition
+     *  happened, so "the recursion stopped" and "the recursion never ran" were
+     *  indistinguishable from the counters alone. */
+    recompletes = 0;
     // ── Mind: the multi-hop pivot (EXTENSION) ───────────────────────────────
     //
     // `pivotStep` was observable only through the rationale, and the rationale
@@ -175,6 +181,51 @@ export class Meter {
     /** Times the reasoner pivoted on a span its answer contains and stepped
      *  across that fact. */
     pivotSteps = 0;
+    /** Canon probes REFUSED because the canon budget ran out — the one thing the
+     *  budget does that nothing could see.  The budget itself is derived
+     *  (`bytes.length · chainReach(W)²`, recognition.ts), and the cheap exact route
+     *  is deliberately unbudgeted, so this counter says exactly when the expensive
+     *  route was priced out.  Counted where the fact happens (the `!canonBudget`
+     *  refusal), not where the probe is called. */
+    canonProbesDenied = 0;
+    /** The pipeline's remainder AT THE DECISION POINT, in bytes: what the grounded
+     *  answer plus the pre-computed spans left unexplained, after the same W floor
+     *  the fuse gate uses.  This is the quantity that licenses (or refuses) the
+     *  post-grounding extension and the fusion — it was computed, used, and never
+     *  published, so nothing could measure what a search had LEFT when it decided.
+     *  Read with {@link postGroundingRemainderSpans}. */
+    postGroundingRemainderBytes = 0;
+    /** How many spans that remainder consists of (each at least one W window). */
+    postGroundingRemainderSpans = 0;
+    /** Times `fuseAttention` produced a FUSED answer — not times it was called.
+     *  It is entered whenever the query has a remainder ≥ W and returns early when
+     *  there is nothing to bridge (`containsSpan`, a lone root, an empty pass), so
+     *  the call and the fact are different things and only the fact is counted.
+     *  Its own rationale step reports the fusion; this is the untraced view, and
+     *  its cost is one bridging edge: `fuseRuns · STEP`. */
+    fuseRuns = 0;
+    /** Steps the post-grounding EXTENSION took — pivots plus forward-absorbs.
+     *  `pivotSteps` counts only the former, so before this the extension's COST was
+     *  not computable at all.  With it, the price of extending the answer is
+     *  `reasonSteps · STEP`, the ladder's own value for following an edge. */
+    reasonSteps = 0;
+    /** Bytes of the grounding's UNCOVERED material the extension was justified by
+     *  — the union of the spans each step carried a `W`-window of.  The gate
+     *  already computed WHICH span carried it per step and kept only a boolean;
+     *  this is that fact, accumulated.  Read with {@link reasonSteps}: one is the
+     *  price, the other the explanation. */
+    reasonCarriedBytes = 0;
+    /** Branch-node probes the pivot sweep actually spent looking for the learnt
+     *  context an answer contains (one `resonate` per probe).  The untraced view
+     *  of what the multi-hop's shortlist costs. */
+    pivotProbes = 0;
+    /** Branch nodes the pivot's probe cap withheld (`branchCount − probeCap`, over
+     *  every call).  A capacity fact, not a verdict: the sweep is breadth-first,
+     *  so the probes it DOES spend are the largest regions, and recognition still
+     *  contributes every exact containment candidate regardless of the budget.
+     *  Read it with {@link pivotProbes} — one says the work, the other the
+     *  shortfall. */
+    pivotBranchesUnprobed = 0;
     // ── Mind: the cover's connector assembly (LIMIT) ────────────────────────
     //
     // The cover's `run` is 91% of a hub query's time (`"Hello."`: 2.7 s of 3.0 s)

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

@@ -75,6 +75,10 @@ export interface ConsensusAnchorTrace {
     rank: number;
     pooledVote: number;
     idfVote: number;
+    /** The LARGEST single-region contribution behind this anchor — the bar
+     *  recall's own gate reads (mechanisms/recall.ts).  Published so the one
+     *  decision-making quantity the climb computes is not invisible. */
+    peak: number;
     candidateBreadth: number;
     contributingVotes: number;
     contributingEvidence: number;

package/dist/src/mind/attention.js

@@ -775,15 +775,18 @@ export async function voteRegions(ctx, query, regions, k, mode, N, reachMemo, td
             }
             contrastiveMargin = margin;
             // Scaled by what this region does NOT address — see `cov` above.
-            const noiseFloor = estimatorNoise(ctx.store.D) * (1 - cov);
-            if (margin <= noiseFloor) {
+            // The bar THIS gate applies: the estimator's noise scaled by what the
+            // region does NOT address (`cov`).  ONE definition, used by the rejection
+            // path below and by the voted payload — the trace reports the applied bar.
+            const appliedFloor = estimatorNoise(ctx.store.D) * (1 - cov);
+            if (margin <= appliedFloor) {
                 recordRegion("contrastive-margin-rejection", {
                     selected,
                     reachNode: voterId,
                     idf,
                     dfWeight: wf,
                     contrastiveMargin: margin,
-                    contrastiveNoiseFloor: noiseFloor,
+                    contrastiveNoiseFloor: appliedFloor,
                     ...(contrastiveRival ? { contrastiveRival } : {}),
                 });
                 continue;
@@ -834,7 +837,12 @@ export async function voteRegions(ctx, query, regions, k, mode, N, reachMemo, td
             ...(contrastiveMargin !== undefined
                 ? {
                     contrastiveMargin,
-                    contrastiveNoiseFloor: estimatorNoise(ctx.store.D),
+                    // THE BAR THE GATE ACTUALLY APPLIED — the same expression
+                    // the rejection path's `appliedFloor` defines, inline here because
+                    // this payload is built in a scope that does not carry that local.
+                    // Publishing the raw estimatorNoise(D) instead made a region that
+                    // PASSED look closer to its limit than it was.
+                    contrastiveNoiseFloor: estimatorNoise(ctx.store.D) * (1 - cov),
                     ...(contrastiveRival ? { contrastiveRival } : {}),
                 }
                 : {}),
@@ -939,7 +947,17 @@ export function poolVotes(ctx, regionVotes, sat, N, td) {
         },
         pool,
     };
-    lightestDerivation(system);
+    // THE SEARCH WAS THE ONE LAYER WITH NO TIME.  The climb's phases are timed
+    // (voteRegions, structuralResonance, crossRegion) but the pooled derivation
+    // was not, so any cost or gain inside it stayed invisible.
+    // `timeSync`, not `time`: the search is SYNCHRONOUS, and wrapping it in a
+    // promise only to time it would make the profiled path wait where the
+    // unprofiled one does not (meter.ts's own contract).
+    if (ctx.meter) {
+        ctx.meter.timeSync("climb.derivation", () => lightestDerivation(system));
+    }
+    else
+        lightestDerivation(system);
     const votes = new Map();
     const votesIdf = new Map();
     const support = new Map();
@@ -973,12 +991,24 @@ export function poolVotes(ctx, regionVotes, sat, N, td) {
     // The LARGEST single region's contribution to this anchor's pooled vote.
     // The pool is a SUM (deliberately — see the pooling note above), so it says
     // how much evidence there is in total, never whether any ONE place in the
-    // query carries evidence on its own.  Consumers that hold an anchor to
-    // consensusFloor(N) = ln(N) + 1/2 need the latter: that bar prices ONE
-    // region's maximally-discriminative evidence (ln N is the IDF of content
-    // reaching a single context), so comparing a six-region sum against it is a
-    // dimensional error.  Recorded here, beside the count, because this is the
-    // only place the per-region contributions are still separable.
+    // query carries evidence on its own.  Recorded here, beside the count,
+    // because this is the only place the per-region contributions are still
+    // separable.
+    //
+    // THE BAR IS THE POOLED FLOOR, AND IT WAS ONCE CLAIMED OTHERWISE HERE.
+    // This comment used to say that holding an anchor to consensusFloor(N)
+    // "prices ONE region's evidence", so comparing a six-region sum against it
+    // was "a dimensional error".  THAT WAS FALSE.  `thresholds.md` §2 derives
+    // `consensusFloor` as the POOLED-vote significance floor ("each region
+    // contributes at most ln(N/c) <= ln(N); ln(N) + 1/2 demands ..."), and the
+    // climb weights by IDF, so the sum and the floor are in ONE dimension —
+    // which is exactly why `recall.ts` gates `forest[0].idfVote` against it and
+    // why `commitVotes` does too.  The other two weighting modes DO leave that
+    // dimension (by at most ln 2, two-sided: `direct` deflates a region and
+    // `combined` inflates it), and the gates therefore read the IDF sum, which
+    // is mode-independent; `test/55` tests 19 and 20 pin both halves — the sum
+    // as the reading the bar is derived for, and the absence of any gate
+    // inversion across the three modes.
     const regionPeak = new Map();
     const steps = [];
     let order = 0;
@@ -1136,12 +1166,23 @@ export function commitVotes(ctx, pooled, sat, regions, regionVoter, N, td, cfg)
             anchor,
             vote,
             peak: regionPeak.get(anchor) ?? 0,
+            idfVote: votesIdf.get(anchor) ?? 0,
             start: s.start,
             end: s.end,
             breadth: (regionSupport.get(anchor) ?? 0) / totalRegions,
             clusters: countClusters(regionSpans.get(anchor) ?? [], ctx.space.maxGroup),
         };
     })
+        // THE ORDER IS NOT A PREFERENCE: with equal evidence it decides ADMISSION,
+        // through the stable sort and the first-come overlap absorption below.
+        // Measured on test/34's corpus, query "red": the two candidates (`red
+        // circle` and `red square`) carry IDENTICAL `vote` and IDENTICAL `idfVote`
+        // (1.3863 each, three seeds), so this comparator leaves them tied and the
+        // stable sort keeps the ENUMERATION order — which is corpus-determined and
+        // admits `red square`, 60/60 seeds.  Adding an id tie-break (`|| a.anchor -
+        // b.anchor`) picks `red circle` instead and makes a single region reach the
+        // JOINT context, which is the premise `test/34` exists to protect.  The
+        // gates read IDF; this line only decides who gets looked at first.
         .sort((a, b) => b.vote - a.vote);
     const overlaps = (a, b) => a.start < b.end && b.start < a.end;
     // Read the root cut from the anchors the QUERY pointed at.  A vote standing
@@ -1177,6 +1218,13 @@ export function commitVotes(ctx, pooled, sat, regions, regionVoter, N, td, cfg)
             rank,
             pooledVote: point.vote,
             idfVote: votesIdf.get(point.anchor) ?? 0,
+            // The LARGEST single-region contribution behind this anchor — the bar
+            // recall's own gate reads (mechanisms/recall.ts: forest[0].peak > LN2),
+            // and until now the only decision-making quantity the climb computed and
+            // did not publish.  `regionPeak` reached `ranked` (see its build below)
+            // and stopped there.  Published, not recomputed: the value is the one the
+            // climb already carries.
+            peak: point.peak,
             candidateBreadth: regions.length,
             contributingVotes: regionAxioms.get(point.anchor) ?? 0,
             contributingEvidence: regionSupport.get(point.anchor) ?? 0,
@@ -1206,6 +1254,18 @@ export function commitVotes(ctx, pooled, sat, regions, regionVoter, N, td, cfg)
         let passesConsensusFloor;
         let pastLeadingSaturation;
         let tiedWithDominant;
+        // ── ONE OF THREE ADMISSIONS, AND THEY ARE NOT THE SAME READING ────────
+        // This block admits by VOTES: per-region evidence pooled, gated on the
+        // natural break and on consensusFloor, with the dominant allowed to bypass
+        // both.  `structuralResonance` admits by a MARGIN over the estimator's own
+        // noise, and `crossRegionVotes` admits by STRUCTURE (which regions may pair
+        // at all, with at least one side individually discriminative).  Read
+        // together they look like one policy written three times; they are three
+        // different measurements of the same question ("is this evidence?"), and
+        // unifying them would average three readings into one — the mistake
+        // `extraction.ts` records as "do not unify the two into one machine".
+        // What they DO share, and must keep sharing, is the discipline of deriving
+        // every bar from D/W/N rather than choosing it (thresholds.md).
         const rejectionReasons = [];
         if (absorbed) {
             status = "overlap";
@@ -1216,9 +1276,75 @@ export function commitVotes(ctx, pooled, sat, regions, regionVoter, N, td, cfg)
             pastLeadingSaturation = pastLeading;
             const vote = votesIdf.get(point.anchor) ?? 0;
             if (roots.length === 0) {
-                // The first non-overlapping root is DOMINANT and bypasses the two
-                // vote thresholds (it always grounds) — only the leading-saturation
-                // gate still applies to it.
+                // THE DOMINANCE PRIVILEGE, AND THE TENSION IT CARRIES (measured).
+                //
+                // The first non-overlapping candidate is DOMINANT: it bypasses both
+                // vote gates below and grounds on its own; only the leading-saturation
+                // gate still applies to it.  The privilege is load-bearing — analogies,
+                // substitutions and composed contexts are precisely candidates the
+                // query does NOT contain, and the engine loses them without it.
+                //
+                // WHICH candidate receives it, though, is decided by this loop's ORDER.
+                // That order comes from `ranked`, and when two candidates carry equal
+                // evidence the stable sort preserves the ENUMERATION order, so the
+                // privilege is allocated by an ordering rather than by a rule.
+                //
+                // Measured on test/34's corpus, query "red":
+                //
+                //   0:#77 vote=1.3863 idf=1.3863 [0,3) | 1:#49 vote=1.3863 idf=1.3863 [0,3)
+                //
+                // Both candidates (`red square` #77, `red circle` #49) have IDENTICAL
+                // `vote` AND IDENTICAL `idfVote` over the SAME support span, so the
+                // comparator leaves them tied, the second is absorbed as "overlap", and
+                // the first grounds.  With this build's enumeration order that first is
+                // `red square`, 60/60 seeds, and `red circle` — the JOINT context — is
+                // never reached by "red" alone.  That is the premise test/34 exists to
+                // protect: no single region reaches the joint context, which is what
+                // makes the binding query unreachable without direct region
+                // interaction.
+                //
+                // THE TENSION: the premise therefore holds BY ENUMERATION ORDER, not by
+                // a rule, so any change to this ordering can move the privilege onto the
+                // joint context and let one region reach it.  Measured: adding
+                // `|| a.anchor - b.anchor` — the lowest-id tie-break that AGENTS.md §2
+                // sanctions as an equivalent corpus-determined tie-break — does exactly
+                // that: "red" then attends to `red circle`, test/34 fails 6/1, and the
+                // canonical suite reports 1 failure.
+                //
+                // TWO ATTEMPTS TO MAKE IT A RULE, BOTH REFUTED BY MEASUREMENT:
+                //
+                //  1. EVIDENCE SEPARATION.  Grant the privilege only when the first
+                //     candidate's evidence is separated from the next distinct
+                //     candidate's by more than the co-dominant band (sqrt(k) *
+                //     estimatorNoise(D)).  Refuted: that band exists to ADMIT the
+                //     anchors the estimator cannot separate from the dominant — its own
+                //     documented purpose — so withholding the privilege on ties removes
+                //     the very case it was written for.  Suite: 4 failures (the two
+                //     co-dominant band laws, breadth/scale invariance, test/29 D2).
+                //
+                //  2. QUERY-OWNED CONTENT.  Grant the privilege only to a candidate
+                //     that IS a recognised region's identity (regions.some(r => r.id ===
+                //     point.anchor)).  Measured: for "circle" that identity IS the
+                //     ranked candidate, so the privilege stays and `circle` grounds; for
+                //     "red" the identity is the `red` node itself while the candidates
+                //     are the conjunctions, so neither is privileged; for "red then
+                //     circle" the composed context carries idf 3.958 and clears both
+                //     gates on its own evidence.  All four control queries came out
+                //     right — and the suite: 10 failures, six of them in the
+                //     analogy/counterfactual/CAST suites ("an analogy still transfers
+                //     from a structure the query never names"; "a substitute the query
+                //     NAMES may still be voiced").  Refuted: the privilege exists to
+                //     admit what the query does NOT contain, so identity is the wrong
+                //     axis.
+                //
+                // WHAT A FUTURE ATTEMPT MUST RESPECT: whatever allocates this privilege
+                // has to (a) keep it available to candidates the query does not contain
+                // — analogies, substitutions, compositions — and (b) not depend on the
+                // estimator's ordering among anchors of equal evidence, because that
+                // ordering is not a fact about the corpus.  No lever satisfying both has
+                // been found.  Until one is, this premise rests on the enumeration order
+                // recorded above, and test/34 is the only test that notices if it
+                // moves.
                 dominant = true;
                 if (pastLeading) {
                     status = "root";
@@ -1229,8 +1355,15 @@ export function commitVotes(ctx, pooled, sat, regions, regionVoter, N, td, cfg)
                 }
             }
             else {
-                passesNaturalBreak = vote >= rootCut;
-                passesConsensusFloor = vote >= floor;
+                // THE FLOOR AND THE BREAK READ THE IDF WEIGHTING.  `floor` is derived
+                // for pooled IDF-weighted votes, and `rootCut` comes from the IDF
+                // distribution (`idfDesc`), so gating the mode-dependent `vote` against
+                // either let a weighting mode change an admission (measured: anchor 87,
+                // inverse 2.682 admitted vs direct 1.468 refused).  Reading the IDF sum
+                // makes the verdict mode-independent, and changes nothing in the
+                // engine's own mode, where the two readings coincide.
+                passesNaturalBreak = point.idfVote >= rootCut;
+                passesConsensusFloor = point.idfVote >= floor;
                 // CO-DOMINANT — an anchor the estimator cannot separate from the
                 // dominant inherits the dominant's exemption, because that exemption's
                 // only warrant is being TOP, and "top" is not a fact about the corpus
@@ -1685,6 +1818,13 @@ ownRootsA, ownRootsB, trace) {
             outcome,
         });
     };
+    // ── ADMISSION BY MARGIN, not by votes (see voteRegions' note) ─────────
+    // What this site measures: how far the best ANN proposal's effective score
+    // (score × semanticConfidence) stands above the runner-up's, against
+    // `estimatorNoise(D)`.  What it does NOT measure: how many regions voted,
+    // or whether the query's regions agree — that is voteRegions' question, and
+    // here a synthetic gist has already replaced them.  The two bars are both
+    // derived (thresholds.md), and neither is a tuning of the other.
     let selected = null;
     let selectedReach = null;
     let selectedIdf = 0;
@@ -1790,6 +1930,15 @@ async function crossRegionVotes(ctx, query, regions, rvs, k, N, reachMemo, td) {
     // successfully reconstructed while probing one pair must not be read and
     // perceived again while probing another pair in the same climb.
     const siblingGistMemo = new Map();
+    // ── ADMISSION BY STRUCTURE, not by a bar (see voteRegions' note) ──────
+    // What this site decides: WHICH regions may pair at all — a region that
+    // already voted (individually discriminative), or a KNOWN non-voting one as
+    // the weak side of a pair whose other side voted; never two non-voting
+    // regions, and never a span contained in a maximal one whose reading is
+    // exact.  The bar (the container's idf) comes later, on the candidate.  So
+    // its "rejection reasons" name structural disqualifications — a different
+    // vocabulary because it answers a different question, and the three
+    // taxonomies stay separate for the same reason the readings do.
     const votedSpans = new Set();
     for (const rv of rvs.votes)
         votedSpans.add(`${rv.start},${rv.end}`);