@hviana/sema 0.8.2 → 0.8.3

package/src/mind/graph-search.ts

@@ -238,6 +238,14 @@ export interface DerivationItem {
  *  {@link GraphSearch}'s rules fired, recovered from the rule's premise/
  *  conclusion shape (the rules carry no label, so this classifies by structure,
  *  the single place that maps rule geometry to a name). */
+// CLOSED ON PURPOSE — AND ONLY THIS ONE IS.  A derivation move is BRANCHED ON
+// (`classifyMove`, the rationale's readers, MOVE_NOTE's fallback), so it is a
+// closed union: adding one without teaching every reader is a compile error,
+// which is what a closed vocabulary buys.  The MECHANISM names in
+// `rationale.ts` are the opposite case — written and displayed, never
+// branched on — and they stay free strings that COMPOSE with the nesting
+// (`["respond", "think", "recognise"]`).  That asymmetry is deliberate; do not
+// "fix" it by uniting the two (see test/126 for the pipeline half of it).
 export type DerivationMove =
   | "axiom" // a seed: a perceived leaf, a recognised form, or a computed result
   | "follow-edge" // form→form via a continuation edge (STEP) — the core "what follows what"
@@ -1135,6 +1143,7 @@ export class GraphSearch {
       // concepts/connectors either (those need the caller's async
       // pre-resolution) — the recursion follows edges and fusion, which is what
       // a deeper rewrite chain is made of.
+      if (this.host.meter) this.host.meter.recompletes++;
       const rec = this.host.recogniseSpan(bytes);
       const kids = new Set(nrec.kids);
       // THE NODE'S OWN KIDS ARE SITES BY STRUCTURE — recognition cannot be the
@@ -1391,20 +1400,36 @@ export class GraphSearch {
       // duplicate read and a branch that could never be taken.
       let next: number | null = null;
       let keyBytes = c.bytes;
-      // THE PREFIX ENDS ARE THE TAIL'S OWN FOLD BOUNDARIES, not every byte
-      // length.  The key is `entity + prefix`, and the prefix that names a
-      // stored relation ends where the fold cuts: measured over four join-firing
-      // queries, 5 of 5 accepted keys ended on a boundary (or the tail's end)
-      // while the byte-by-byte scan spent 153 probes where 14 boundaries would
-      // do.  Same criterion — resolves AND leads — same shortest-first order, so
-      // the answer is the same one the enumeration found; only the candidates
-      // come from the structure instead of from the byte count.  A host with no
-      // boundary rule falls back to the enumeration.
-      const cuts = this.host.contentCuts?.(tail);
-      const ends = cuts && cuts.length > 0
-        ? [...cuts.filter((c) => c > 0 && c < tail.length), tail.length]
-        : Array.from({ length: tail.length }, (_, i) => i + 1);
-      for (const len of ends) {
+      // THE CANDIDATE ENDS ARE THE PREFIXES THAT ARE STORED NODES, ASCENDING.
+      // The key is `entity + prefix`, and it names a relation exactly when that
+      // concatenation IS a node — so the ends come from a content-addressed
+      // probe per offset (the host's `contentKeyEnds`, the learning path's own
+      // mechanism: one leaf walk plus one `findBranch` per offset, no `resolve`),
+      // never from the fold's boundaries.  A boundary is not a proxy: a stored
+      // member's end is the end of ITS OWN stream, and the fold never cuts at a
+      // stream's end — measured, "stockholm mayor" exists, leads on to the mayor
+      // fact, and its boundary 6 sits in neither the tail's cuts ([4,7]) nor the
+      // concatenation's.  Filtering the scan by "is this a node?" cannot change
+      // the winner: a position that is not a node cannot resolve, so skipping it
+      // is invisible; and the order stays SHORTEST FIRST, which is a semantic
+      // law, not an optimisation (test/106, test/108 pin it).
+      //
+      // A host that cannot answer falls back to every prefix: exact and
+      // complete, at a `resolve` per offset.  A host that CAN answer is
+      // authoritative even when it answers "none" — if no prefix is a node then
+      // no key exists to resolve, so enumerating would only pay nulls.  (A key
+      // reachable through the CANONICAL equivalence alone and ending off every
+      // node end is therefore not tried here; that dimension is unreachable on
+      // this path by construction and is not part of the exact-key law.)
+      const ends = this.host.contentKeyEnds?.(c.bytes, tail);
+      const candidateEnds = function* (): Generator<number> {
+        if (ends !== undefined) {
+          yield* ends;
+          return;
+        }
+        for (let p = 1; p <= tail.length; p++) yield p;
+      };
+      for (const len of candidateEnds()) {
         keyBytes = concat2(c.bytes, tail.subarray(0, len));
         const k = this.host.resolve(keyBytes) ??
           this.host.canonResolve?.(keyBytes) ??

package/src/mind/match.ts

@@ -723,7 +723,7 @@ export function frameSlots(
  *  ANCHOR that the query displaced.  Neither implies the other, and the
  *  observed failures pass the restatement guard cleanly.
  *
- *  Three conditions, all byte-exact and all necessary:
+ *  Four conditions, all byte-exact and all necessary:
  *
  *  1. the query and the anchor must be ONE STRUCTURE — what they share has to
  *     dominate the query, or the query is not a variant of the anchor at all
@@ -811,8 +811,10 @@ export function substituteAll(
   const usable = pairs.filter((p) => p.needle.length > 0);
   if (usable.length === 0) return hay;
   // Longest needle first, so a needle that is a prefix of another can never
-  // pre-empt it.  Ties cannot arise: an instance whose fillers are not
-  // pairwise distinct is refused by frameSlots.
+  // pre-empt it.  Ties cannot arise: a consumer that VOICES checks the
+  // fillers pairwise with `distinct` and refuses such an instance itself —
+  // `frameSlots` reports and does not judge (see its own doc), so the refusal
+  // lives with the mechanism that needs it, not here.
   const order = [...usable].sort((a, b) => b.needle.length - a.needle.length);
   const out: number[] = [];
   let i = 0;

package/src/mind/mechanisms/cast.ts

@@ -867,7 +867,9 @@ export async function counterfactualTransfer(
   // grounds") — fine for ORIENTING mechanisms, not for voicing learnt
   // content the query never asked about.  Computed once here; both the
   // hub fallback below and the comparison gate consume it.
-  const rootTrusted = roots.some((r) => r.vote >= consensusFloor(corpusN(ctx)));
+  const rootTrusted = roots.some((r) =>
+    r.idfVote >= consensusFloor(corpusN(ctx))
+  ); // the IDF sum: the bar's own quantity
   // The context that ESTABLISHES a filler — the same reverse context, under
   // the same naming test, `seatOfNode` uses to VOICE an analog (a predecessor
   // whose bytes CONTAIN the node's: it names or describes it, rather than

package/src/mind/mechanisms/confluence.ts

@@ -146,6 +146,30 @@ export async function confluenceJoin(
   const bindsAConstituent = (cover: Array<[number, number]>): boolean =>
     cover.some(([cs, ce]) => ce - cs >= 2 * W);
 
+  // THE VOTE ENTERS AS ORDER, NEVER AS A BAR.  This is the only one of the
+  // climb's four consumers (recall, fuseAttention, cast, here) that uses the
+  // evidence's MAGNITUDE without a floor, and it is legitimate by construction:
+  // `ranked` answers "which anchor is stronger" — a question about votes, so the
+  // comparison stays within one dimension — and the vote is otherwise only
+  // REPORTED (Stream.vote travels to the rationale's constraint nodes).  What
+  // actually SELECTS a constraint is byte-structural and never the magnitude: a
+  // run of at least 2W (`bindsAConstituent`, with its accidental-sharing
+  // counter-examples above), disjoint covers (`disjoint`), and scaffolding never
+  // binds at all (`dominates(reachOf(…), N)`).  The MEET such a stream may
+  // produce is selected the same way: a span shorter than 2W is rejected, and
+  // the winner is the one with the smallest `reach` (ties broken by the longer
+  // span) — a corpus quantity and bytes, never the vote, which appears only in
+  // the trace item.
+  // binds at all (`dominates(reachOf(…), N)`).  The only cut in this loop is a
+  // BUDGET, and it is measured: stopping the scan at 2W anchors saves 50-70% of
+  // confluence's cost on non-conjunctive queries while preserving every genuinely
+  // conjunctive case, whose top anchors ARE its constraints.
+  // MEASURED (this goal, on THIS file's own conjunctive fixture): the two
+  // streams appear at ranks 1 and 4 against a budget of 2W = 8, on a query whose
+  // `ranked` is 9 — so the cut IS live (it would have returned null at the 8th
+  // anchor) and it does NOT prune the case it exists to protect.  The other
+  // conjunctive fixture (the Leonardo one) finds them at ranks 0 and 1.  Scope:
+  // these are the repo's conjunctive fixtures, and no more.
   const streams: Stream[] = [];
   const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
   // CONJUNCTIVITY EARLY-EXIT: a conjunctive query's top-ranked anchors

package/src/mind/mechanisms/recall.ts

@@ -276,9 +276,36 @@ export async function recallByResonance(
     // consensus", while breadth is the SCALE-INVARIANT reading — "a point whose
     // breadth clears `dominates` (> half the query's regions corroborate it) is
     // real consensus; one that does not is a coincidental single-region echo".
-    // Attention.peak's contract makes the same point from the other side:
-    // comparing a POOLED SUM against a floor that prices ONE region's evidence
-    // is a dimensional error.
+    // THIS USED TO CLAIM A DIMENSIONAL ERROR, AND THAT CLAIM WAS FALSE.
+    // It read: "comparing a POOLED SUM against a floor that prices ONE region's
+    // evidence is a dimensional error."  `consensusFloor` is not priced for one
+    // region: thresholds.md §2 derives it as the POOLED-vote significance floor —
+    // "each region contributes at most ln(N/c) <= ln(N); ln(N)+1/2 demands ..." —
+    // and attention.ts says the same where it builds the vote ("the scale
+    // consensusFloor is derived for").  The comparison is in ONE dimension, and
+    // it is so because the climb WEIGHTS BY IDF: `wf` in voteRegions is
+    // `direct ? df : combined ? idf + df : idf`, and the engine only ever runs the
+    // last one (DFMode's default "inverse", the mode every non-test caller uses —
+    // `direct` and `combined` are exercised by test/24 and test/27 only, and
+    // test/24 pins that their votes DO differ).  In those two the sum would leave
+    // the floor's dimension and the floor would need re-deriving.
+    //
+    // What the OR below is really for is SCALE, not dimension (the paragraph
+    // above says it): a vote that clears ln(N)+1/2 means "strong" on a small store
+    // and "weak" on a large one for the same genuine consensus, so the
+    // scale-invariant breadth reading is added beside it.
+    //
+    // AND THE PREMISE IS IDF.  The deviation in the other two weighting modes is
+    // TWO-SIDED and DERIVED: `direct` DEFLATES a region (ln(1+c) < ln(N/c) for
+    // small c) and `combined` INFLATES it (ln N + ln(1+1/c)), both by at most
+    // `ln 2` — see `geometry.ts`'s `consensusFloor`, where the bound lives.
+    // MEASURED on 8 anchors across 5 queries, running the same climb in all
+    // three modes: ZERO gate inversions — every anchor's `vote >= floor` verdict
+    // is the same in `inverse`, `direct` and `combined`, even where the readings
+    // straddle the floor on opposite sides (#148: inverse 3.39, combined 4.71
+    // above it, direct 1.31 below).  Pinned by test/55's test 20.  The bar is not
+    // re-derived for those modes because nothing reachable needs it; the premise
+    // is IDF, and that is now written where the gate reads it.
     //
     // Measured on the 15.7M-node store (N=325,615, so the old floor was 13.19).
     // The absolute vote cannot separate right from wrong at this scale, and the
@@ -348,7 +375,7 @@ export async function recallByResonance(
     if (
       forest.length > 0 &&
       !allWindowsAreScaffolding(ctx, query) &&
-      (forest[0].vote >= minVote ||
+      (forest[0].idfVote >= minVote || // the IDF sum: the bar's own quantity
         (dominates(forest[0].breadth, 1) && forest[0].peak > Math.LN2))
     ) {
       const g = await project(ctx, forest[0].anchor, queryGist);
@@ -602,6 +629,7 @@ export const recallMechanism: PipelineMechanism = {
       moves: r.moves,
       unexplained: r.unexplained,
       provenance: r.echoed ? "recall-echo" : "recall",
+      used: new Set<number>(),
       ...(r.complete ? { complete: true } : {}),
     }];
   },

package/src/mind/mind.ts

@@ -16,7 +16,6 @@ import type { CorpusPair, CorpusResult } from "./corpus.js";
 import { Alphabet } from "../alphabet.js";
 import {
   bytesToTree,
-  contentBoundaries,
   contentFoldIncremental,
   Grid,
   gridToTree,
@@ -24,6 +23,7 @@ import {
   reachThreshold,
   stackGrids,
 } from "../geometry.js";
+import { keyEnds } from "./canonical.js";
 import type { ContentFold } from "../geometry.js";
 import { BoundedMap, type Store } from "../store.js";
 import { SQliteStore } from "../store-sqlite.js";
@@ -244,6 +244,8 @@ export interface MindOptions {
   seed?: number;
   recallQueryK?: number;
   haloQueryK?: number;
+  /** Branch nodes the pivot sweep may probe — see {@link MindConfig}. */
+  pivotProbeK?: number;
   /** Items one rationale step may itemise — see {@link MindConfig}. */
   rationaleSampleK?: number;
   /** Corpus-reading capacities and budgets — see {@link MindConfig}. */
@@ -443,9 +445,9 @@ export class Mind implements MindContext {
    *  with the most distributional evidence (highest `prevOf` count — the
    *  structural manifestation of its halo).  When evidence is equal the
    *  first-inserted edge wins. */
-  /** See {@link GraphSearchHost.contentCuts}. */
-  contentCuts(bytes: Uint8Array): readonly number[] {
-    return contentBoundaries(this.space, bytes);
+  /** See {@link GraphSearchHost.contentKeyEnds}. */
+  contentKeyEnds(prefix: Uint8Array, tail: Uint8Array): readonly number[] {
+    return keyEnds(this, prefix, tail);
   }
 
   chooseNext(node: number): number | undefined {

package/src/mind/pipeline-mechanism.ts

@@ -675,6 +675,13 @@ export interface MechanismResult {
   bytes: Uint8Array;
   accounted: Array<[number, number]>;
   moves: number;
+  /** WHAT THIS ANSWER SPEAKS FOR — the anchors it voices, and therefore the
+   *  content the reasoner must not pivot back through.  Declared by the
+   *  mechanism about its OWN result, exactly like `accounted`/`unexplained`/
+   *  `complete`: post-grounding honours the property and NEVER ASKS WHICH
+   *  MECHANISM SET IT, so the market stays uniform.  An EMPTY set is a real
+   *  declaration — "this answer voices nothing" (recall) — and withholds
+   *  nothing; omit the field and the pipeline re-recognises the answer. */
   used?: ReadonlySet<number>;
   unexplained: string;
   /** Explicit weight override.  When absent, weight = moves + PASS·unaccounted. */

package/src/mind/pipeline.ts

@@ -15,7 +15,7 @@ import type { ComputedSpan } from "../extension.js";
 import { gistOf, read, resolve } from "./primitives.js";
 import { recognise } from "./recognition.js";
 import { fuseAttention, reason } from "./reasoning.js";
-import { unexplainedSpans } from "./rationale.js";
+import { unaccountedBytes, unexplainedSpans } from "./rationale.js";
 import { rItem } from "./trace.js";
 import { hubBound } from "./traverse.js";
 import { type PipelineMechanism, Precomputed } from "./pipeline-mechanism.js";
@@ -253,8 +253,7 @@ export async function think(
   }
   const grade = (w: number) => Math.floor(w / STEP);
   const unaccounted = (spans: ReadonlyArray<[number, number]>): number =>
-    unexplainedSpans(query.length, spans)
-      .reduce((sum, [s, e]) => sum + (e - s), 0);
+    unaccountedBytes(unexplainedSpans(query.length, spans));
   const weigh = (
     accounted: ReadonlyArray<[number, number]>,
     moves: number,
@@ -504,14 +503,11 @@ export async function think(
   }
   const answer: Uint8Array = decided.bytes;
   const provenance = decided.provenance as Provenance;
-  const castUsed: ReadonlySet<number> = decided.used ?? new Set();
+  const declaredUsed = decided.used;
 
   // ── Post-grounding, gated by provenance ──────────────────────────────
-  const preConsumed = provenance === "cast" || provenance === "join"
-    ? castUsed
-    : provenance === "recall" || provenance === "recall-echo"
-    ? new Set<number>()
-    : new Set(recognise(ctx, answer).sites.map((s) => s.payload));
+  const preConsumed = declaredUsed ??
+    new Set(recognise(ctx, answer).sites.map((s) => s.payload));
   // A grounding that DECLARED itself complete is not extended: the answer is
   // already a trained form's own continuation, reached through an identity
   // claim about the query, so a multi-hop pivot could only chain past the
@@ -540,11 +536,30 @@ export async function think(
   // `preConsumed` is derived by re-recognising the answer — "everything in
   // it", not "what it voiced" — and a containment rule over that would
   // suppress every pivot the answer legitimately contains.
-  const voiced = (provenance === "cast" || provenance === "join")
-    ? [...castUsed].flatMap((id) =>
-      ctx.store.nextFirst(id, hubBound(ctx)).map((n) => read(ctx, n))
-    )
-    : [];
+  const voiced = declaredUsed === undefined ? [] : [...declaredUsed].flatMap(
+    (id) => ctx.store.nextFirst(id, hubBound(ctx)).map((n) => read(ctx, n)),
+  );
+  // WHAT THIS BRANCH READ, published where it was read.  Post-grounding decides
+  // by `decided.used` and by the provenance NAME; the operands were invisible in
+  // the trace, so a change to the branching could not be shown equivalent or
+  // otherwise from outside — three separate investigations failed on exactly
+  // that gap.  A gap in instrumentation is a defect IN the instrumentation
+  // (AGENTS.md §6): closed here, once, as counts only — never content.
+  ctx.trace?.step(
+    "postGrounding",
+    [rItem(answer, provenance)],
+    [],
+    `used=${decided.used !== undefined ? "declared" : "absent"} · ` +
+      `preConsumed=${preConsumed.size} · voiced=${voiced.length}`,
+    undefined,
+    {
+      version: 1,
+      provenance,
+      usedDeclared: decided.used !== undefined,
+      preConsumed: preConsumed.size,
+      voiced: voiced.length,
+    },
+  );
   // REPORTABLE, NOT SILENT.  A declared-complete grounding ends the derivation
   // here, and that decision is part of the derivation's shape: the reader of a
   // rationale must be able to see that the chain stopped because the mechanism
@@ -573,12 +588,24 @@ export async function think(
   ];
   const uncovered = unexplainedSpans(query.length, explained)
     .filter(([a, b]) => b - a >= ctx.space.maxGroup);
-  const reasoned = decided.complete ? answer : meter
+  // PUBLISHED, NOT RECOMPUTED: the same `uncovered` the gates below read.  A
+  // write-only accounting (meter contract 1), so the number that licenses an
+  // extension or a fusion stops being invisible.
+  if (meter) {
+    meter.postGroundingRemainderSpans += uncovered.length;
+    meter.postGroundingRemainderBytes += unaccountedBytes(uncovered);
+  }
+  // The extension is kept as a WHOLE (bytes + what it carried + how many steps),
+  // not just its bytes: pricing it — `steps · STEP` against `PASS · unaccounted`
+  // — is the caller's job, one comparison away.  `reasoned` stays the bytes so
+  // everything downstream is untouched.
+  const extension = decided.complete ? undefined : meter
     ? await meter.time(
       "reason",
       () => reason(ctx, query, answer, preConsumed, pre, voiced, uncovered),
     )
     : await reason(ctx, query, answer, preConsumed, pre, voiced, uncovered);
+  const reasoned = extension?.bytes ?? answer;
 
   // Fuse only when the query has a genuine REMAINDER no mechanism's
   // structural evidence touched at all.  `decided.accounted` alone
@@ -639,7 +666,13 @@ export async function think(
 
   done(
     fused,
-    "grounded, reasoned forward, fused across points of attention",
+    // NO CLAIM ABOUT FUSION HERE.  `fuseAttention` is entered whenever a
+    // remainder ≥ W exists and returns early when there is nothing to bridge, so
+    // this note used to assert a fusion that frequently did not happen (measured:
+    // "What is the capital of France famous for" fuses 0 times).  The fusion is
+    // reported by `fuseAttention`'s own `done` when it happens — the layer that
+    // did the work is the layer that says so.
+    "grounded, reasoned forward",
   );
   return { bytes: fused, provenance };
 }

package/src/mind/primitives.ts

@@ -338,7 +338,15 @@ export function canonResolve(
     // on exactly the node the canonical-case query would have found.
     const folded = foldTree(ctx, perceive(ctx, bytesOf), 0).node;
     const use = folded ?? id;
-    const leads = store.hasNext(use) || store.haloMass(use) > 0;
+    // THE ADMISSION PREDICATE, by its own pair of probes: `traverse.ts`'s
+    // `leadsSomewhere` is edge-or-halo, and `hasHalo` is the one that carries
+    // the mass bar (`mass >= minHaloMass`).  Asking `haloMass(use) > 0` instead
+    // is the same answer only while `minHaloMass <= 1` (its default): raise the
+    // bar and this site would rank a node as leading on evidence the law
+    // refuses.  Calling `leadsSomewhere` here is not possible — `traverse.ts`
+    // imports THIS file, so it would be a cycle — which is why the pair is
+    // spelled out rather than named.
+    const leads = store.hasNext(use) || store.hasHalo(use);
     if (
       best === null || (leads && !bestLeads) ||
       (leads === bestLeads && use < best)

package/src/mind/rationale.ts

@@ -49,6 +49,17 @@ export interface RationaleItem {
    *  caller asked to carry it (off by default — a D-float array per item would
    *  bury the reasoning it is meant to explain). */
   v?: Vec;
+  /** The element's OWN bytes, attached BY REFERENCE when the step was built from
+   *  bytes (a `rationale.ts` item made from a node carries none: read it back
+   *  through `node`).  `text` is a RENDERING and cannot stand in for them — it
+   *  decodes UTF-8 and DROPS NUL bytes, so a key containing one is unrecoverable
+   *  from it, which is exactly how a join refusal (`deriveThroughMiss`) became
+   *  impossible to test exactly without re-encoding.  Treat as READ-ONLY: the
+   *  array belongs to the caller (and may be a view into the query).
+   *
+   *  Costs nothing when nothing inspects: items exist only while a rationale
+   *  sink is attached, and this holds a reference rather than a copy. */
+  bytes?: Uint8Array;
 }
 
 /** A single completed act of inference — one mechanism, run once.
@@ -101,6 +112,20 @@ export function decodeText(bytes: Uint8Array): string {
   return new TextDecoder().decode(bytes.filter((b) => b !== 0x00));
 }
 
+/** The BYTE COUNT of the complement — what the currency calls `unaccounted`
+ *  in `weight = moves + PASS·unaccounted`.  It lives here, beside the function
+ *  that produces the gaps, because the price's second term has ONE definition:
+ *  this was four copies of the same `reduce` (two in reasoning.ts, two in
+ *  pipeline.ts) before the architecture audit of `../auditoria-arquitectura-sema.md`
+ *  collapsed them.  Same value at every site — the control diff is identical. */
+export function unaccountedBytes(
+  spans: ReadonlyArray<readonly [number, number]>,
+): number {
+  let total = 0;
+  for (const [a, b] of spans) total += b - a;
+  return total;
+}
+
 /** The `[start, end)` gaps of `[0, queryLen)` NOT covered by `accounted` —
  *  the same union-of-spans reading think's grounding decider prices at PASS
  *  per byte, exposed here so a mechanism can turn it into a human label. */
@@ -264,7 +289,16 @@ export class Rationale {
     };
   }
 
-  /** Record a mechanism that has no sub-steps — its inputs and outputs are both
+  /** WHY THIS NAME IS A FREE STRING, when the derivation's moves are a closed
+   *  union: a mechanism name is WRITTEN and DISPLAYED, and it COMPOSES with
+   *  the nesting — `mechanism` is the whole path (`["respond", "think",
+   *  "recognise"]`), which no fixed union can express.  Nothing branches on it:
+   *  `nothing here drives the inference; it only WITNESSES it`.  A vocabulary
+   *  that is only witnessed needs no union; one that is read does
+   *  (`DerivationMove`, in graph-search.ts).  The asymmetry is the design, not
+   *  a drift.
+   *
+   *  Record a mechanism that has no sub-steps — its inputs and outputs are both
    *  known at the call site.  Returns its index, for a later step to depend on. */
   step(
     name: string,

package/src/mind/reasoning.ts

@@ -8,10 +8,10 @@ import { bytesEqual, indexOf } from "../bytes.js";
 import type { Attention, MindContext } from "./types.js";
 import { resolve } from "./primitives.js";
 import { corpusN, hubBound } from "./traverse.js";
-import { follow, haloSiblings, project } from "./match.js";
+import { containsSpan, follow, haloSiblings, project } from "./match.js";
 import { joinWithBridge, pivotInto } from "./resonance.js";
 import type { Precomputed } from "./pipeline-mechanism.js";
-import type { Rationale } from "./rationale.js";
+import { type Rationale, unaccountedBytes } from "./rationale.js";
 
 /** Whether `bytes` is a proper byte-subspan of `query` — already present in
  *  the question, so voicing it back only restates part of what was asked,
@@ -29,13 +29,32 @@ export function restatesQuery(query: Uint8Array, bytes: Uint8Array): boolean {
 
 /** Extend a grounded answer forward across facts (multi-hop reasoning).
  *  Pivots on the longest unconsumed learnt context each answer contains,
- *  then follows the pivot's continuation to the next fact.  Repeats up
- *  to `cfg.recallQueryK` hops.  `preConsumed` carries node ids already
+ *  then follows the pivot's continuation to the next fact.  **The chain ends
+ *  when it STOPS, never when a count runs out**: every exit is a refusal (no
+ *  pivot, no forward step, no question material carried) and the walk is bounded
+ *  by the material and the graph — `consumed` refuses to revisit a node.  There
+ *  is no hop allowance, so this doc deliberately names no `cfg` capacity: the
+ *  cover prices every hop at `STEP` and lets the search decide the depth, and a
+ *  second count here would be a second decision about the same thing.
+ *  `preConsumed` carries node ids already
  *  spoken for by the grounding stage (cover/extract/CAST).  `voiced` carries
  *  the BYTES of the anchors a mechanism declared it voiced (its `used` set),
  *  when it declared one — see the pivot's own containment rule.  `pre` is the
  *  response's shared pre-computation — the post-grounding stages read the
  *  same container the mechanisms did. */
+/** What the multi-hop extension produced, and what it cost: the bytes (the
+ *  answer), the spans of the grounding's UNCOVERED material that each step was
+ *  justified by, and how many steps were taken.  The last two exist so the
+ *  caller can price the extension in the ladder's own currency — `steps · STEP`
+ *  against `PASS · unaccounted` — instead of taking it unconditionally.  Both
+ *  are FACTS, not verdicts: nothing here says whether the extension was worth
+ *  it; that is the comparison's job, one layer up. */
+export interface ReasonedAnswer {
+  bytes: Uint8Array;
+  carried: Array<[number, number]>;
+  steps: number;
+}
+
 export async function reason(
   ctx: MindContext,
   query: Uint8Array,
@@ -47,14 +66,16 @@ export async function reason(
    *  `unaccounted` spans.  Only the reasoner's OWN extensions are judged
    *  against it; a mechanism carrying its own `used` set owns its shape. */
   uncovered: readonly (readonly [number, number])[] = [],
-): Promise<Uint8Array> {
+): Promise<ReasonedAnswer> {
   // Echo guard: a query that is ITSELF a learnt continuation (some context's
   // answer) is being asked back at the system — hopping forward from it would
   // chain through the very fact that produced it and echo the conversation
   // back.  The grounded answer alone is the honest read-out.  Deliberately a
   // broad structural gate; pinned by test/31-audit.
   const qId = pre.queryResolved;
-  if (qId !== null && ctx.store.prevCount(qId) > 0) return answer;
+  if (qId !== null && ctx.store.prevCount(qId) > 0) {
+    return { bytes: answer, carried: [], steps: 0 };
+  }
 
   // Consume a node and its neighbours for pivot-cycle prevention — CAPPED at
   // the hub bound, via the store's LIMITed edge reads: a common continuation's
@@ -113,7 +134,7 @@ export async function reason(
     ? null
     : ctx.store.prevFirst(groundedId, bound);
   if (qId !== null && groundedPrev !== null && groundedPrev.includes(qId)) {
-    return answer;
+    return { bytes: answer, carried: [], steps: 0 };
   }
 
   const consumed = new Set<number>();
@@ -159,7 +180,27 @@ export async function reason(
   const qv = pre.guide; // the response-wide guide IS the query's gist
   let t: ReturnType<Rationale["enter"]> | undefined;
   const startedFrom = answer;
-  for (let hop = 0; hop < ctx.cfg.recallQueryK; hop++) {
+  // INSTRUMENTATION ONLY — the two facts the extension's own decision already
+  // used and threw away: the spans of uncovered material each step was
+  // JUSTIFIED by (the gate below computes which span carries it and kept only a
+  // boolean), and how many steps were taken.  Nothing here decides anything:
+  // both are read after the loop, to bump counters and to let the caller compare
+  // the extension's cost against what it explains, in the ladder's own currency.
+  const carried: Array<[number, number]> = [];
+  let steps = 0;
+  // NO ALLOWANCE: THE CHAIN ENDS WHEN IT STOPS.  Every exit below is the law —
+  // no pivot, no forward step, no question material carried — and the walk is
+  // bounded by the material and the graph rather than by a count: each taken
+  // step must carry a W-window of the uncovered material (finite), and
+  // `consumed` refuses to revisit a node.  `recallQueryK` no longer bounds the
+  // reasoner here; it keeps its other roles (the bridge's candidate reads, the
+  // pivot's probe budget, the resonance limits).
+  //
+  // Measured before removing it: test/89 — the corpus-cost guard, the heaviest
+  // case in the suite — is green and no slower without the allowance (27 s
+  // against 30 s); and raising it from 12 to 200 changed neither the answer nor
+  // `pivotSteps` on the chain fixtures.
+  for (let hop = 0;; hop++) {
     // Hop 0's `cur` IS `answer`, so the guard above already resolved it and
     // read its reverse edges — reuse both rather than repeat them.
     const curId = hop === 0 ? groundedId : resolve(ctx, cur);
@@ -192,6 +233,7 @@ export async function reason(
           "the answer is itself a learnt fact — follow its continuation to the fixpoint",
         );
         cur = fwd;
+        steps++;
         continue;
       }
     }
@@ -227,12 +269,17 @@ export async function reason(
     if (!producerOwnsShape && uncovered.length > 0) {
       const W = ctx.space.maxGroup;
       let progress = false;
+      let justified: [number, number] | undefined;
       for (const [a, b] of uncovered) {
         for (let i = a; i + W <= b && !progress; i++) {
-          if (indexOf(fc, query.subarray(i, i + W), 0) >= 0) progress = true;
+          if (indexOf(fc, query.subarray(i, i + W), 0) >= 0) {
+            progress = true;
+            justified = [a, b];
+          }
         }
         if (progress) break;
       }
+      if (progress && justified !== undefined) carried.push(justified);
       if (!progress) {
         // THE BRAKE, MADE VISIBLE.  The reasoner declines a step that carries
         // none of the material the grounding left uncovered — the drift the
@@ -243,7 +290,25 @@ export async function reason(
         // the check disabled, test/110 and test/116 fail — so this brake is the
         // only thing keeping the extension honest until the pivot reports its
         // own accounted spans and the ladder can judge it instead.
-        const left = uncovered.reduce((n, [a, b]) => n + (b - a), 0);
+        //
+        // THE PROMISE IS NOW KEPT, AND THE BRAKE TURNS OUT TO BE THE LADDER'S
+        // OWN CONSEQUENCE.  The extension reports what it carried (`carried`,
+        // the span each step was justified by) and what it cost (`steps`), both
+        // counted in the meter (`reasonCarriedBytes`, `reasonSteps`), so the
+        // ladder CAN judge it: it accepts while
+        //
+        //     steps · STEP  <  PASS · carried
+        //
+        // and this brake accepts whenever the step carries a `W`-window, i.e.
+        // whenever `carried ≥ W ≥ 1`.  With `PASS/STEP = 1000` the two therefore
+        // agree on every extension with `steps ≤ 1000 · carried` — and every
+        // extension this repository produces takes 0 or 1 steps (measured on
+        // chains of 3, 8, 20 and 40 links).  Above that bound the ladder would
+        // refuse what this brake accepts, which is the corner named in the
+        // closure report's limits: a chain of thousands of links explaining a
+        // handful of bytes.  No guard is added for it — a limit without a
+        // derivation is exactly what the brake must not become.
+        const left = unaccountedBytes(uncovered);
         ctx.trace?.step(
           "pivotRefused",
           [rItem(cur, "answer"), rItem(query, "query")],
@@ -263,12 +328,25 @@ export async function reason(
       "pivot on the shared span this answer contains, then step forward across that fact",
     );
     cur = fc;
+    steps++;
+  }
+  // INSTRUMENTATION ONLY — the extension's two facts, untraced (meter.ts
+  // contract 1: a counter never reaches a decision).  They are what a caller
+  // needs to PRICE the extension instead of taking it unconditionally: the work
+  // it did (`steps · STEP`) and the uncovered material it carried.
+  if (ctx.meter) {
+    ctx.meter.reasonSteps += steps;
+    ctx.meter.reasonCarriedBytes += unaccountedBytes(carried);
   }
   t?.done(
     [rItem(cur, "answer", resolve(ctx, cur) ?? undefined)],
+    // A FIXPOINT: no further step was possible.  This note used to also cover an
+    // exhausted hop allowance — a different fact, and the reason F1 added a
+    // counter for it.  The allowance is gone, so the only way out of the loop is
+    // a refusal, and the note is true again by construction.
     "the multi-hop chain's fixpoint",
   );
-  return cur;
+  return { bytes: cur, carried, steps };
 }
 
 /** Fuse independent points of attention into one answer (multi-topic).
@@ -462,9 +540,8 @@ export async function fuseAttention(
     [rItem(out, "answer", resolve(ctx, out) ?? undefined)],
     `fused ${pieces.length} independent points of attention into one answer`,
   );
+  // THE FACT IS THE FUSED ANSWER, not the call: every early return above hands
+  // back `primary` untouched.  Untraced on purpose (meter.ts contract 1).
+  if (ctx.meter) ctx.meter.fuseRuns++;
   return out;
 }
-
-// (resonance.js is already a static dependency above — `bridge` — so the old
-// dynamic import of pivotInto guarded against a cycle that does not exist.)
-import { containsSpan } from "./match.js";