@hviana/sema 0.8.3 → 0.8.5

package/src/mind/pipeline.ts

@@ -15,8 +15,17 @@ 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 { unaccountedBytes, unexplainedSpans } from "./rationale.js";
+import {
+  closed,
+  type DerivationState,
+  remainderOf,
+  type Span,
+  unaccountedBytes,
+  unexplainedSpans,
+  windowOf,
+} from "./derivation.js";
 import { rItem } from "./trace.js";
+import { unexplainedLabel } from "./rationale.js";
 import { hubBound } from "./traverse.js";
 import { type PipelineMechanism, Precomputed } from "./pipeline-mechanism.js";
 import { coverMechanism } from "./mechanisms/cover.js";
@@ -244,7 +253,6 @@ export async function think(
     weight: number;
     used?: ReadonlySet<number>;
     accounted: ReadonlyArray<[number, number]>;
-    unexplained: string;
     complete?: boolean;
     /** Bytes of this candidate's ANSWER that came from spans nothing
      *  recognised — query words carried through verbatim (see
@@ -393,14 +401,16 @@ export async function think(
       ? await meter.time(`${mech.name}.run`, () => mech.run(ctx, query, pre))
       : await mech.run(ctx, query, pre);
     for (const r of results) {
-      const weight = r.weight ?? weigh(r.accounted, r.moves);
+      // ONE FORMULA, EVERY CANDIDATE: the chart's derivation reports how many
+      // discrete moves it made and which bytes it could not recognise; the
+      // currency prices both.  No mechanism passes a price of its own.
+      const weight = weigh(r.accounted, r.moves);
       consider({
         bytes: r.bytes,
         provenance: r.provenance ?? mech.provenance,
         weight,
         used: r.used,
         accounted: r.accounted,
-        unexplained: r.unexplained,
         complete: r.complete,
         scaffolding: r.scaffolding,
       });
@@ -433,14 +443,21 @@ export async function think(
       : null;
     ctx.trace?.step(
       "decideGrounding",
-      candidates.map((c) =>
-        rItem(
+      // THE LABEL IS RENDERED WHERE IT IS SHOWN.  It was a field on every
+      // mechanism's result, and at every one of them it was exactly
+      // `unexplainedLabel(query, accounted)` — a second representation of a
+      // quantity one pure function already yields, computed on every response
+      // whether or not anyone looked.  Here it is computed only when a rationale
+      // is attached, because `trace?.step` short-circuits its arguments.
+      candidates.map((c) => {
+        const label = unexplainedLabel(query, c.accounted);
+        return rItem(
           c.bytes,
           `${c.provenance} (weight ${c.weight.toFixed(3)}${
-            c.unexplained ? `, unexplained: "${c.unexplained}"` : ""
+            label ? `, unexplained: "${label}"` : ""
           })`,
-        )
-      ),
+        );
+      }),
       decided ? [rItem(decided.bytes, decided.provenance)] : [],
       "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder",
       undefined,
@@ -505,7 +522,61 @@ export async function think(
   const provenance = decided.provenance as Provenance;
   const declaredUsed = decided.used;
 
-  // ── Post-grounding, gated by provenance ──────────────────────────────
+  // ── THE DERIVATION STATE ─────────────────────────────────────────────
+  //
+  // THE REASONER JUDGES ITS OWN EXTENSIONS BY THE PIPELINE'S REMAINDER, not by
+  // the ladder's `accounted` — and by the SAME reading the fuse gate below uses,
+  // with the same W floor.  `accounted` is a COST quantity (measured: a query
+  // fully explained by one computed span plus bridged connectors reports
+  // `accounted: []` while nothing is unexplained), and a remainder under one
+  // river-fold quantum is bridging punctuation, never a second topic — so it
+  // licenses no extension and blocks none.
+  //
+  // The state is built HERE, where these quantities are already computed, so it
+  // costs nothing new: `accounted` is what the winning transition priced,
+  // `remainder` is the coverage reading over `accounted ∪ the response's
+  // computed spans` (the union is what makes the two different quantities, and
+  // both are kept), `cost` is the ladder position, and the two declarations are
+  // the producer's own (`fixed`, `used`).  What follows reads THIS state rather
+  // than a tuple rebuilt at each call site.
+  // A DERIVATION IS BORN OWING WHAT ITS ANSWER DOES NOT CARRY.  The winning
+  // transition PRICED these spans, and pricing is not carrying: coverage claimed
+  // without evidence stays owed, and a later transition pays it only by carrying
+  // it (the law reads the window; see derivation.ts).  Same reading, one
+  // definition — not a second spelling of it here.
+  const explained: Array<[number, number]> = [
+    ...decided.accounted,
+    ...pre.computed.map((u): [number, number] => [u.i, u.j]),
+  ].filter(([a, b]) =>
+    windowOf([a, b], answer, query, ctx.space.maxGroup) !== null
+  );
+  // WHAT THE CONSTRUCTION WITHHOLDS, at or above one quantum: the difference between
+  // the remainder paid in full and the remainder paid by carrying.  Both readings
+  // are the law's, so the floor is applied once and in one place.
+  const paidInFull = remainderOf(
+    query.length,
+    [
+      ...decided.accounted,
+      ...pre.computed.map((u): [number, number] => [u.i, u.j]),
+    ],
+    ctx.space.maxGroup,
+  );
+  const paid = remainderOf(query.length, explained, ctx.space.maxGroup);
+  if (ctx.meter) {
+    ctx.meter.groundingWithheldBytes += unaccountedBytes(paid) -
+      unaccountedBytes(paidInFull);
+  }
+  const state: DerivationState = {
+    product: answer,
+    accounted: decided.accounted,
+    remainder: paid,
+    cost: decided.weight,
+    fixed: decided.complete,
+    used: decided.used,
+  };
+  const uncovered = state.remainder;
+
+  // ── Post-grounding, gated by the declaration and the remainder ────────
   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
@@ -540,10 +611,13 @@ export async function think(
     (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
+  // by the DECLARATION (`decided.used`, which becomes `voiced`), by what the
+  // recognition already consumed (`preConsumed`) and by the derivation's own
+  // remainder — never by the provenance NAME, which is REPORTED throughout and
+  // compared nowhere (a stale comment here claimed otherwise; the register caught
+  // it, and this is the correction).  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",
@@ -558,6 +632,14 @@ export async function think(
       usedDeclared: decided.used !== undefined,
       preConsumed: preConsumed.size,
       voiced: voiced.length,
+      // THE STATE THE LAW GOVERNS, rendered where it is decided: what the asker
+      // said that no step has accounted for, in spans at or above one quantum,
+      // and whether the producer supplied a fixed point.  Counts only, like
+      // every other operand here — and the spans are the state's, so a reader
+      // can check them against the meter's aggregate of the same remainder.
+      remainderSpans: state.remainder.length,
+      remainderBytes: unaccountedBytes(state.remainder),
+      fixed: state.fixed === true,
     },
   );
   // REPORTABLE, NOT SILENT.  A declared-complete grounding ends the derivation
@@ -575,19 +657,6 @@ export async function think(
         "post-grounding extension is skipped",
     );
   }
-  // THE REASONER JUDGES ITS OWN EXTENSIONS BY THE PIPELINE'S REMAINDER, not by
-  // the ladder's `accounted` — and by the SAME reading the fuse gate below uses,
-  // with the same W floor.  `accounted` is a COST quantity (measured: a query
-  // fully explained by one computed span plus bridged connectors reports
-  // `accounted: []` while nothing is unexplained), and a remainder under one
-  // river-fold quantum is bridging punctuation, never a second topic — so it
-  // licenses no extension and blocks none.
-  const explained: Array<[number, number]> = [
-    ...decided.accounted,
-    ...pre.computed.map((u): [number, number] => [u.i, u.j]),
-  ];
-  const uncovered = unexplainedSpans(query.length, explained)
-    .filter(([a, b]) => b - a >= ctx.space.maxGroup);
   // 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.
@@ -595,17 +664,18 @@ export async function think(
     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.
+  // THE WALK CONSUMES AND RETURNS A STATE.  It is handed the derivation's own —
+  // the grounding's product, accounting, remainder and cost — and hands back the
+  // state it advanced to, so what follows reads a state rather than bytes plus a
+  // tuple rebuilt here.  A supplied fixed point is the one case where the walk
+  // does not run at all, and then the state is the grounding's own.
   const extension = decided.complete ? undefined : meter
     ? await meter.time(
       "reason",
-      () => reason(ctx, query, answer, preConsumed, pre, voiced, uncovered),
+      () => reason(ctx, query, state, preConsumed, pre, voiced),
     )
-    : await reason(ctx, query, answer, preConsumed, pre, voiced, uncovered);
-  const reasoned = extension?.bytes ?? answer;
+    : await reason(ctx, query, state, preConsumed, pre, voiced);
+  const reasoned = extension ?? state;
 
   // Fuse only when the query has a genuine REMAINDER no mechanism's
   // structural evidence touched at all.  `decided.accounted` alone
@@ -623,7 +693,15 @@ export async function think(
   // observed: a single space between two fully-computed arithmetic spans
   // ("2+2 3+3") registered as "unaccounted" and pulled in an unrelated
   // corpus fact, corrupting "4 6" into "4 63".
-  const remainder = unaccounted(explained);
+  // THE GATE ASKS THE LAW, and that is an OPTIMISATION, not a tidy-up: the state
+  // above ALREADY carries the remainder (`remainderOf`, per-span, with the W
+  // floor applied), so asking it costs nothing, while the total this line used to
+  // compute (`unaccounted(explained)`) was one more sum over the spans on every
+  // response.  The two readings are the same condition, not two: the ACCOUNTING
+  // applies the same W floor the gate does, so a gap below one quantum never
+  // survives into `explained` and the total cannot reach W without some single
+  // gap reaching it.  Measured over twelve constructions at W = 4 (test/136.3,
+  // which pins the equivalence and both sides of it).
   // Whether the winning candidate's entire recognised substance is
   // COMPUTED — every accounted span exactly a pre.computed span, nothing
   // from a genuinely recognised/climbed site.  fuseAttention's lone-root
@@ -633,8 +711,8 @@ export async function think(
   // `unclimbed` parameter, gated there by Attention.breadth so a
   // coincidental echo (which this flag alone cannot distinguish) is still
   // rejected.
-  const unclimbed = decided.accounted.length > 0 &&
-    decided.accounted.every(([i, j]) =>
+  const unclimbed = state.accounted.length > 0 &&
+    state.accounted.every(([i, j]) =>
       pre.computed.some((u) => u.i === i && u.j === j)
     );
   // Where the winning grounding stands in the query — fusion places primary
@@ -644,13 +722,10 @@ export async function think(
   // Exactly the cost-ladder-vs-coverage distinction `explained` above draws,
   // read here for POSITION instead of for coverage — and resolved here, where
   // both readings are in hand, rather than inside fuseAttention.
-  const primarySpans: ReadonlyArray<[number, number]> =
-    decided.accounted.length > 0
-      ? decided.accounted
-      : pre.computed.map((u): [number, number] => [u.i, u.j]);
-  const fused = remainder < ctx.space.maxGroup
-    ? reasoned
-    : meter
+  const primarySpans: ReadonlyArray<Span> = state.accounted.length > 0
+    ? state.accounted
+    : pre.computed.map((u): [number, number] => [u.i, u.j]);
+  const fused = closed(state) ? reasoned : meter
     ? await meter.time(
       "fuse",
       () => fuseAttention(ctx, query, reasoned, pre, unclimbed, primarySpans),
@@ -665,7 +740,7 @@ export async function think(
     );
 
   done(
-    fused,
+    fused.product,
     // 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:
@@ -674,5 +749,5 @@ export async function think(
     // did the work is the layer that says so.
     "grounded, reasoned forward",
   );
-  return { bytes: fused, provenance };
+  return { bytes: fused.product, provenance };
 }

package/src/mind/rationale.ts

@@ -21,6 +21,7 @@
 // fan-out / fan-in is visible in their lengths.
 
 import type { Vec } from "../vec.js";
+import { unexplainedSpans } from "./derivation.js";
 
 /** One element of a step's input or output vector.
  *
@@ -112,42 +113,11 @@ 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. */
-export function unexplainedSpans(
-  queryLen: number,
-  accounted: ReadonlyArray<[number, number]>,
-): Array<[number, number]> {
-  const sorted = accounted
-    .map(([s, e]) =>
-      [Math.max(0, s), Math.min(queryLen, e)] as [number, number]
-    )
-    .filter(([s, e]) => e > s)
-    .sort((a, b) => a[0] - b[0]);
-  const gaps: Array<[number, number]> = [];
-  let reach = 0;
-  for (const [s, e] of sorted) {
-    if (s > reach) gaps.push([reach, s]);
-    if (e > reach) reach = e;
-  }
-  if (reach < queryLen) gaps.push([reach, queryLen]);
-  return gaps;
-}
+// THE SPAN ALGEBRA LIVES IN derivation.ts.  `unaccountedBytes` and
+// `unexplainedSpans` are the closure law's vocabulary — gap arithmetic over the
+// asker's own bytes — and they moved to the layer that owns the law, so they
+// have ONE home and are no longer asked of the tracer.  This module keeps the
+// inference TOLD as it happens, and reads the gaps only to render a label.
 
 /** A human-readable label for the query bytes a mechanism's `accounted`
  *  spans leave unexplained — purely diagnostic (Task 2's negative evidence):