@hviana/sema 0.8.5 → 0.8.7

package/dist/src/meter.d.ts

@@ -199,15 +199,30 @@ export declare class Meter {
      *  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. */
+    /** Bytes the admitted steps ACCOUNTED for — the witnesses' spans, summed by the
+     *  law's own function over the tail of the state's accounting.  It is NOT what
+     *  they carried: a step admitted by `reaches` may declare spans it holds no
+     *  window of, and then it accounts without carrying and consumes nothing (see
+     *  {@link closureDrainedBytes}).  Read with {@link reasonSteps}: one is the
+     *  price, the other the accounting. */
+    reasonAccountedBytes: number;
+    /** Bytes of the QUESTION's own material an admitted step CARRIED — the windows
+     *  of the remainder its product holds, read by the law's one reading.  The
+     *  accounting may be larger (a `reaches` step declares spans it holds no window
+     *  of) and the consumption is the window of a step that also reaches, so the
+     *  three form a lattice: consumed ⊆ carried ⊆ accounted. */
     reasonCarriedBytes: number;
+    /** Times the layer OFFERED a continuation to the law.  Read with
+     *  {@link lawRejects}: the offers the law refused are the Model X contract being
+     *  exercised, and `offerRuns - lawRejects` is the accepted transitions. */
+    offerRuns: number;
+    /** Times the law REFUSED the continuation the layer offered.  A refusal is
+     *  terminal by the layer's contract, so this counts the moments the contract
+     *  mattered — zero means the walk never needed it. */
+    lawRejects: number;
     /** Bytes of the question's REMAINDER a step CONSUMED — the drop the law's own
      *  `advance` makes when a declared move carries the material it accounts for.
-     *  Read with {@link reasonSteps} and {@link reasonCarriedBytes}: carrying is
+     *  Read with {@link reasonSteps} and {@link reasonAccountedBytes}: carrying is
      *  the engagement, this is the consumption, and before it the second was
      *  invisible. */
     closureDrainedBytes: number;

package/dist/src/meter.js

@@ -209,15 +209,30 @@ export class Meter {
      *  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. */
+    /** Bytes the admitted steps ACCOUNTED for — the witnesses' spans, summed by the
+     *  law's own function over the tail of the state's accounting.  It is NOT what
+     *  they carried: a step admitted by `reaches` may declare spans it holds no
+     *  window of, and then it accounts without carrying and consumes nothing (see
+     *  {@link closureDrainedBytes}).  Read with {@link reasonSteps}: one is the
+     *  price, the other the accounting. */
+    reasonAccountedBytes = 0;
+    /** Bytes of the QUESTION's own material an admitted step CARRIED — the windows
+     *  of the remainder its product holds, read by the law's one reading.  The
+     *  accounting may be larger (a `reaches` step declares spans it holds no window
+     *  of) and the consumption is the window of a step that also reaches, so the
+     *  three form a lattice: consumed ⊆ carried ⊆ accounted. */
     reasonCarriedBytes = 0;
+    /** Times the layer OFFERED a continuation to the law.  Read with
+     *  {@link lawRejects}: the offers the law refused are the Model X contract being
+     *  exercised, and `offerRuns - lawRejects` is the accepted transitions. */
+    offerRuns = 0;
+    /** Times the law REFUSED the continuation the layer offered.  A refusal is
+     *  terminal by the layer's contract, so this counts the moments the contract
+     *  mattered — zero means the walk never needed it. */
+    lawRejects = 0;
     /** Bytes of the question's REMAINDER a step CONSUMED — the drop the law's own
      *  `advance` makes when a declared move carries the material it accounts for.
-     *  Read with {@link reasonSteps} and {@link reasonCarriedBytes}: carrying is
+     *  Read with {@link reasonSteps} and {@link reasonAccountedBytes}: carrying is
      *  the engagement, this is the consumption, and before it the second was
      *  invisible. */
     closureDrainedBytes = 0;

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

@@ -203,6 +203,11 @@ export interface ClimbConsensusData {
         total: number;
     };
     regions?: ConsensusRegionTrace[];
+    /** A NAME SHARED WITH THE LAW, AND NOT THE SAME THING: these are the reaches
+     *  the consensus climb took, for the trace.  The law's `Continuation.reaches`
+     *  (derivation.ts) is a producer's claim that a step moves — different type,
+     *  different owner, no relation.  Kept distinct rather than renamed because the
+     *  trace's own vocabulary is about the climb, not about derivation. */
     reaches?: ConsensusReachTrace[];
     crossRegion?: {
         eligibleRegions: number;

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

@@ -176,14 +176,19 @@ export declare function advance(d: DerivationState, t: Continuation, explains: R
 /** What a layer offers the law: the next continuation of a state, or null when
  *  it has none.  A layer OFFERS; the law disposes.
  *
- *  ONE OFFER, AND IT IS THE LAYER'S LAST: {@link closure} stops when the law
- *  refuses what was offered, so a refusal is read as "no continuation exists".
- *  A layer must not offer candidates one at a time and expect the walk to
- *  continue after a refusal — its own fallbacks belong inside this function.
- *  The producers do exactly that: they choose between the forward absorb and the
- *  pivot before offering, and return null only when neither exists, which is why
- *  the one offer the law can still refuse (a pivot without ownership, whose
- *  material the answer does not carry) really is the last one. */
+ *  ONE OFFER AT A TIME: {@link closure} asks again only while the law admits what
+ *  was offered, so a refusal ends the walk.  A layer must not offer candidates
+ *  one at a time and expect the walk to continue after a refusal — its own
+ *  fallbacks belong inside this function, and the producers do exactly that:
+ *  they choose between the forward absorb and the pivot before offering.
+ *
+ *  WHAT `null` DOES NOT SAY: it is not a claim of exhaustion.  A layer returns
+ *  null for several distinct reasons — it exhausted its enumeration, it refused a
+ *  candidate it had reached, or a read bound cut one off — and the law cannot tell
+ *  them apart: it reads every one as "no continuation exists".  The layer's reasons
+ *  are therefore made OBSERVABLE where they happen, on the rationale's own channel
+ *  (`enumerationExhausted`, `pivotCandidateRefused`, `absorbCandidateRefused`), and
+ *  it is there — not here — that a reader learns which of them stopped the walk. */
 export type Offer = (d: DerivationState) => Promise<Continuation | null>;
 /** THE CLOSURE — the walk of {@link advance} over the continuations `offer`
  *  proposes, run until the layer has nothing further to offer or the law refuses
@@ -196,6 +201,6 @@ export type Offer = (d: DerivationState) => Promise<Continuation | null>;
  *  Nothing here counts steps, and nothing here decides admissibility. */
 export declare function closure(d: DerivationState, query: Uint8Array, W: number, offer: Offer, 
 /** Called for each step the law admits, with the state before and after. */
-onTaken?: (before: DerivationState, after: DerivationState) => void, 
+onTaken?: (before: DerivationState, after: DerivationState, witnesses: ReadonlyArray<Witness>) => void, 
 /** Called when the law refused the continuation the layer offered. */
 onRefused?: (at: DerivationState) => void): Promise<DerivationState>;

package/dist/src/mind/derivation.js

@@ -234,6 +234,15 @@ export function closed(d) {
 export function admissible(d, t, query, W) {
     if (d.fixed)
         return null;
+    // THE GATE THAT NEVER FIRES, AND WHY IT STAYS.  `contains` is the step's claim
+    // to BE a continuation of this product at all, and the formula is stated with
+    // it (see the doc above).  Every producer in the engine declares it true — the
+    // three literals in reasoning.ts are constants, measured — so this line cannot
+    // reject anything today.  It stays because the claim is what makes an `Offer`
+    // answerable: a layer that handed over something it does not call a
+    // continuation would be refused here rather than trusted.  What it must NOT be
+    // is a place where a producer says "false" to end a walk: the walk ends by
+    // offering nothing (`null`), which is the contract.
     if (!t.contains)
         return null;
     if (closed(d))
@@ -321,7 +330,7 @@ onRefused) {
             return d;
         }
         const next = advance(d, t, explains);
-        onTaken?.(d, next);
+        onTaken?.(d, next, explains);
         d = next;
     }
 }

package/dist/src/mind/pipeline.js

@@ -451,6 +451,15 @@ export async function think(ctx, query, mechs) {
         meter.postGroundingRemainderSpans += uncovered.length;
         meter.postGroundingRemainderBytes += unaccountedBytes(uncovered);
     }
+    // THE WALK THAT DOES NOT RUN, NAMED — the audit's point 1 could not attribute
+    // real questions that stopped with no note anywhere.  They never reached the
+    // offer: `decided.complete` says the grounding supplied a fixed point, so the
+    // walk is skipped BY DESIGN and the state is the grounding's own.  That state
+    // carries `fixed: true` (the trace already reports it), and the law's first
+    // clause refuses any continuation against it — so there is no `null` here to
+    // read as exhaustion, and the `Offer` contract is not in play at all.  The
+    // silent stop is therefore a NAMED state, not a gap.
+    //
     // 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

package/dist/src/mind/reasoning.js

@@ -39,6 +39,13 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
     // broad structural gate; pinned by test/31-audit.
     const qId = pre.queryResolved;
     if (qId !== null && ctx.store.prevCount(qId) > 0) {
+        // THE ECHO GUARD, NAMED — the audit's point 1 could not attribute two real
+        // walks that stopped with no note at all, and this is where one of them went:
+        // the query IS a learnt continuation, so the reasoner returns the grounded
+        // read-out and never offers anything.  Without this note the walk looks like
+        // an unexplained stop; with it, "no note" can only mean the offer was never
+        // asked.  No decision changes: the guard returns exactly where it did.
+        ctx.trace?.step("echoGuard", [rItem(query, "query")], [], "the query is itself a learnt continuation — answering the grounded read-out without walking");
         return d0;
     }
     // Consume a node and its neighbours for pivot-cycle prevention — CAPPED at
@@ -183,6 +190,8 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
     // admitted.
     let pending = null;
     const offer = async (d) => {
+        if (ctx.meter)
+            ctx.meter.offerRuns += 1;
         const cur = d.product;
         // The first step's `cur` IS the grounding's product, so the guard above
         // already resolved it and read its reverse edges — reuse both.
@@ -196,8 +205,30 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
         // fixpoint falls through to the pivot step instead.  Offered with `moves`:
         // completing the answer's OWN learnt form is an identity step, not a claim
         // about the asker's material.
-        if (curId !== null &&
-            ctx.store.nextFirst(curId, bound).some((n) => !consumed.has(n))) {
+        // THE READ, KEPT — its LENGTH is free and it is the only instrument the
+        // bound has: a read that came back full may have been cut off, and a read
+        // that came back short did not.  No second read is paid for this.
+        const outs = curId !== null ? ctx.store.nextFirst(curId, bound) : [];
+        const saturated = outs.length >= bound;
+        // THE RE-REACH, NAMED — the audit's structural-identity case (its test G), and
+        // the silent path it hid in.  MEASURED, and this is the point's closure: across
+        // thirteen real questions on the trained store — the roteiro's ten plus three —
+        // this note fires ZERO times.  The case, if it exists in this engine, is not on
+        // that material.  It is not unimplementable, it is unobserved, and the audit's
+        // own rule is that an unobserved claim stays declared as unobserved: a
+        // distinction between legitimate convergence and a cycle cannot be implemented
+        // responsibly before it is seen, and the brief's section 13 puts measurement
+        // before code.  What exists here is the instrument that will show it the moment
+        // it happens.  When every successor of the current product has already
+        // been spoken for, the absorb above is skipped WITHOUT a word and the walk
+        // falls to the pivot: the same structure reached again is indistinguishable
+        // from having none.  This note does not change the decision — it makes the
+        // state observable first, because the distinction between a legitimate
+        // convergence and a cycle cannot be implemented responsibly until it is seen.
+        if (curId !== null && outs.length > 0 && !outs.some((n) => !consumed.has(n))) {
+            ctx.trace?.step("reachAlreadySpokenFor", [rItem(cur, "answer")], [], `every continuation of this product (${outs.length}) has already been spoken for — the same structure, reached again`);
+        }
+        if (curId !== null && outs.some((n) => !consumed.has(n))) {
             const fwd = await follow(ctx, curId, qv);
             const fwdId = fwd !== null ? resolve(ctx, fwd) : null;
             if (fwd !== null && !bytesEqual(fwd, cur) &&
@@ -207,16 +238,55 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
                 pending = { kind: "absorb", cur, curId, fwd };
                 return { product: fwd, contains: true, reaches: true, cost: STEP };
             }
+            // THE ABSORB'S OWN REFUSALS, TOLD APART — a learnt continuation existed
+            // and was declined, so the walk falls through to the pivot rather than
+            // ending.  Which of the four reasons it was is exactly what the rationale
+            // could not say before: `null` at the end of the walk is one state, and
+            // this is another (AGENTS §6 — the note belongs where the mechanism emits
+            // it, not in a counter beside it).
+            const whyAbsorb = fwd === null
+                ? "the unconsumed edge led nowhere"
+                : bytesEqual(fwd, cur)
+                    ? "the continuation reached was the product already in hand"
+                    : fwdId !== null && consumed.has(fwdId)
+                        ? "the continuation reached had already been spoken for"
+                        : "this continuation only restates the question";
+            ctx.trace?.step("absorbCandidateRefused", [rItem(cur, "answer")], [], `${whyAbsorb} — falling through to the pivot`);
+        }
+        if (saturated) {
+            // THE BUDGET, NAMED — the audit's point 2.  `nextFirst` is read with a cap
+            // (`hubBound`), so a saturated read may have hidden a continuation, and the
+            // walk would end as if none existed.  The note says MAY, because the length
+            // cannot tell a full read from a truncated one; it can only tell that this
+            // is where a cut would have happened.
+            ctx.trace?.step("readBoundSaturated", [rItem(cur, "answer")], [], "the read came back full — a continuation may have been cut off by the bound");
         }
         // Pivot: the longest unconsumed learnt context the answer contains.
         consumeAll(curId);
         const pivot = await pivotInto(ctx, cur, consumed, voiced);
-        if (pivot === null)
+        if (pivot === null) {
+            // THE ENUMERATION, DECLARED — the one duty the law cannot perform for the
+            // layer: only the layer knows that it has nothing left to offer.  Before
+            // this note the walk ended in a bare `null`, indistinguishable from the
+            // causes below it; a reader of the rationale could not tell "exhausted"
+            // from "the candidate was refused" (AGENTS §6: a gap in instrumentation
+            // is a defect IN the instrumentation).
+            ctx.trace?.step("enumerationExhausted", [rItem(cur, "answer")], [], "the layer has no further candidate — its enumeration is exhausted");
             return null;
+        }
         const fc = await follow(ctx, pivot, qv);
         consumeAll(pivot);
         if (fc === null || bytesEqual(fc, cur) ||
             restates(query, fc, 0, { proper: true })) {
+            // THE THREE REFUSALS, TOLD APART — a candidate was reached and declined,
+            // which is NOT the same state as having none: the law reads both as "no
+            // continuation", but the rationale should not.
+            const why = fc === null
+                ? "the pivot's context carried no continuation"
+                : bytesEqual(fc, cur)
+                    ? "the continuation reached was the product already in hand"
+                    : "this continuation only restates the question";
+            ctx.trace?.step("pivotCandidateRefused", [rItem(cur, "answer")], [], `${why} — refused`);
             return null;
         }
         pending = { kind: "pivot", cur, pivot, fc };
@@ -232,8 +302,9 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
             cost: STEP,
         };
     };
-    const closed_ = await closure(d0, query, W, offer, (before, after) => {
+    const closed_ = await closure(d0, query, W, offer, (before, after, witnesses) => {
         if (ctx.meter) {
+            ctx.meter.reasonCarriedBytes += witnesses.reduce((n, w) => n + (w.window ? w.window[1] - w.window[0] : 0), 0);
             ctx.meter.closureDrainedBytes += unaccountedBytes(before.remainder) -
                 unaccountedBytes(after.remainder);
         }
@@ -251,6 +322,10 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
             ctx.trace?.step("pivotStep", [rItem(p.cur, "answer"), rNode(ctx, p.pivot, "pivot")], [rItem(p.fc, "answer", resolve(ctx, p.fc) ?? undefined)], "pivot on the shared span this answer contains, then step forward across that fact");
         }
     }, (at) => {
+        // THE LAW REFUSED — counted where it happened, before the bookkeeping
+        // below decides whether there is a step to report.
+        if (ctx.meter)
+            ctx.meter.lawRejects += 1;
         const p = pending;
         pending = null;
         if (p === null || p.kind !== "pivot")
@@ -266,6 +341,20 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
         ctx.trace?.step("pivotRefused", [rItem(p.cur, "answer"), rItem(query, "query")], at.remainder.map(([a, b]) => rItem(query.subarray(a, b), "uncovered")), `the step carries none of the question material the grounding left ` +
             `unaccounted (${left} byte(s) in ${at.remainder.length} span(s)) — refused`);
     });
+    // THE WALK'S OWN ENDING, NAMED — the audit's point 1.  Every stop INSIDE the
+    // offer now has a note, but a walk can also end without the offer ever being
+    // asked, or after a step the law took and then found nothing to follow: those
+    // ended as "no note at all", indistinguishable from a mechanism that never ran.
+    // Two endings cover every remaining case, and together they make a silent stop
+    // impossible — which is what the `Offer` contract needs, because `null` is read
+    // as exhaustion and exhaustion must be a statement, not an absence.
+    t ??= ctx.trace?.enter("reason", [rItem(startedFrom, "grounded")]);
+    if (closed_.remainder.length === 0) {
+        ctx.trace?.step("walkClosed", [rItem(closed_.product, "answer")], [], "the derivation is closed — nothing is left unaccounted for");
+    }
+    else {
+        ctx.trace?.step("walkEndedWithoutOffer", [rItem(closed_.product, "answer")], closed_.remainder.map(([a, b]) => rItem(query.subarray(a, b), "uncovered")), `the walk ended with ${unaccountedBytes(closed_.remainder)} byte(s) unaccounted and no further offer — no structural continuation`);
+    }
     // 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, and both
@@ -279,7 +368,7 @@ export async function reason(ctx, query, d0, preConsumed, pre, voiced = []) {
         // over the tail of the state's list — and computed ONLY when a meter is
         // attached: this used to slice and MAP a fresh array on every response, for a
         // counter that usually does not exist.  One allocation, under the meter.
-        ctx.meter.reasonCarriedBytes += unaccountedBytes(closed_.accounted.slice(d0.accounted.length));
+        ctx.meter.reasonAccountedBytes += unaccountedBytes(closed_.accounted.slice(d0.accounted.length));
     }
     t?.done([rItem(closed_.product, "answer", resolve(ctx, closed_.product) ?? undefined)], 
     // A FIXPOINT: no further step was offered, or the law refused the one that
@@ -489,6 +578,7 @@ primarySpans = []) {
         return { ...state, product: out };
     const fused = advance(state, fusedT, fusedWitness);
     if (ctx.meter) {
+        ctx.meter.reasonCarriedBytes += fusedWitness.reduce((n, w) => n + (w.window ? w.window[1] - w.window[0] : 0), 0);
         ctx.meter.closureDrainedBytes += unaccountedBytes(state.remainder) -
             unaccountedBytes(fused.remainder);
     }

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

@@ -95,7 +95,13 @@ export declare function hubCap<T>(ctx: MindContext, ids: readonly T[]): readonly
 /** Whether `descendant` lies within `ancestor`'s subtree — a structural DAG
  *  relation read off the hash-consed `kids` lists, by a bounded explicit-stack
  *  descent.  Used by articulation to keep a voice from revoicing a fragment
- *  OF that voice. */
+ *  OF that voice.
+ *
+ *  A HOMONYM, NOT A RELATIVE: the law's `Continuation.contains` (derivation.ts) is
+ *  a producer's claim that its step IS a continuation, a boolean on one step.  This
+ *  is a structural relation between two nodes in the DAG.  The shared word is
+ *  deliberate vocabulary — "containment" is what both name — and the two must not be
+ *  read as one. */
 export declare function contains(ctx: MindContext, ancestor: number, descendant: number): boolean;
 /** Whether a continuation edge joins the two forms, in either direction —
  *  the EXACT half's veto on calling them synonyms.

package/dist/src/mind/traverse.js

@@ -495,7 +495,13 @@ export function hubCap(ctx, ids) {
 /** Whether `descendant` lies within `ancestor`'s subtree — a structural DAG
  *  relation read off the hash-consed `kids` lists, by a bounded explicit-stack
  *  descent.  Used by articulation to keep a voice from revoicing a fragment
- *  OF that voice. */
+ *  OF that voice.
+ *
+ *  A HOMONYM, NOT A RELATIVE: the law's `Continuation.contains` (derivation.ts) is
+ *  a producer's claim that its step IS a continuation, a boolean on one step.  This
+ *  is a structural relation between two nodes in the DAG.  The shared word is
+ *  deliberate vocabulary — "containment" is what both name — and the two must not be
+ *  read as one. */
 export function contains(ctx, ancestor, descendant) {
     if (ancestor === descendant)
         return true;

package/docs/INDEX.md

@@ -36,7 +36,7 @@ proof in `test/` (pins that fail when the law is broken).
 | 11  | `docs/architecture/memoization.md`          | `Precomputed` is per-response lazy cache (promise-cached async); `beginResponse`/`endResponse` lifecycle        | `test/42`            |
 | 12  | `docs/architecture/saturation.md`           | Every walk names a deciding saturation beside its cap; cap is safety net, not decision                          | `test/27`, `test/16` |
 | 13  | `docs/architecture/meter.md`                | `meter.ts` is write-only work accounting; counts are exact, phases nest                                         | `test/55`            |
-| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law | `test/133`–`140`     |
+| 14  | `docs/architecture/closure.md`              | A derivation is closed when its structure accounts for the question's remainder; every transition asks that law | `test/133`–`147`     |
 
 ## Mechanisms (8)
 

package/docs/INVARIANTS.md

@@ -15,4 +15,4 @@
 | 11 | Honest degradation                   | `src/mind/pipeline.ts:weight=moves+PASS*unaccounted` `src/store.ts:BoundedMap:miss→re-derive`                                         | `test/28` `test/84` | `store.md`+`caches.md`    |
 | 12 | Meter contracts                      | `src/meter.ts:Meter,PhaseCost,time` `src/mind/pipeline-mechanism.ts:Precomputed.shared`                                               | `test/55`           | `meter.md`                |
 | 13 | Saturation                           | `traverse.ts:edgeAncestors,types.ts:SaturationReason` `src/mind/junction.ts:junctionContainersFrom` `src/mind/resonance.ts:pivotInto` | `test/27` `test/16` | `saturation.md`           |
-| 14 | Closure                              | `src/mind/derivation.ts:closed,admissible,advance`                                                                                    | `test/133`–`140`    | `closure.md`              |
+| 14 | Closure                              | `src/mind/derivation.ts:closed,admissible,advance`                                                                                    | `test/133`–`147`    | `closure.md`              |

package/docs/architecture/closure.md

@@ -23,6 +23,14 @@ field, no producer field, and no count of any kind. The witnesses `contains` and
 `moves` are the LAYER's: it holds the structure and hands them in, so the law
 never probes the store.
 
+## The boundary
+
+`product` (what it stands on, its identity being `resolve(product)`),
+`accounted` (the price its steps summed) and `remainder` (the question's debt,
+at one quantum) are the derivation's own. What it REACHED and what it SPENT are
+the layer's (`reaches`, `consumed`), never a field here: the law decides
+admission and consumption, the layer decides frontier and termination.
+
 ## The transition
 
 `admissible(state, continuation, query, W)` returns the witnesses the step pays
@@ -33,6 +41,10 @@ consumes what its window proves. Whole-span draining was refuted by `test/110`,
 the window alone by `test/138`. The state is BORN owing what its product does
 not carry.
 
+The walk ends when the layer stops offering or the law refuses; owning no
+search, the law cannot prevent a cycle — that is the layer's, over the structure
+it holds.
+
 ## One cost home
 
 `moves + PASS · unaccountedBytes` is computed in ONE place (`pipeline.ts`,
@@ -60,6 +72,9 @@ vocabulary, not the tracer's.
 ## Pins
 
 - `test/133`–`137` — the law's home, readings, refusal, limits.
-- `test/138` — a cycle cannot close it; a carried move can.
+- `test/138` — a cycle cannot close it, a carried move can.
 - `test/139` — carrying is ENGAGEMENT, not explanation.
-- `test/140` — irrelevant supply changes no answer.
+- `test/140` — irrelevant supply changes nothing.
+- `test/142`, `test/143` — the offer's contract, and the cycles.
+- `test/144`, `test/146`, `test/147` — identity is content, the `contains` gate,
+  the witness ladder.

package/docs/harness/gates.md

@@ -13,7 +13,7 @@ Guards honest silence, determinism, and every pinned contract. Silence:
 unrelated queries ground to nothing (`test/28`, `50`, `56`, `67`, `76`, `84`).
 Determinism: same seed + deposit order + query gives byte-identical answer
 (`test/20`). Every invariant is pinned, the closure law included
-(`test/133`–`140`). §14–25 (pipeline), §64 (derived thresholds), AGENTS.md §2
+(`test/133`–`147`). §14–25 (pipeline), §64 (derived thresholds), AGENTS.md §2
 invariants 1–5.
 
 ## 2 — Work accounting (profiler)

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@hviana/sema",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "repository": {
     "type": "git",

package/src/meter.ts

@@ -267,15 +267,30 @@ export class Meter {
    *  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. */
+  /** Bytes the admitted steps ACCOUNTED for — the witnesses' spans, summed by the
+   *  law's own function over the tail of the state's accounting.  It is NOT what
+   *  they carried: a step admitted by `reaches` may declare spans it holds no
+   *  window of, and then it accounts without carrying and consumes nothing (see
+   *  {@link closureDrainedBytes}).  Read with {@link reasonSteps}: one is the
+   *  price, the other the accounting. */
+  reasonAccountedBytes = 0;
+  /** Bytes of the QUESTION's own material an admitted step CARRIED — the windows
+   *  of the remainder its product holds, read by the law's one reading.  The
+   *  accounting may be larger (a `reaches` step declares spans it holds no window
+   *  of) and the consumption is the window of a step that also reaches, so the
+   *  three form a lattice: consumed ⊆ carried ⊆ accounted. */
   reasonCarriedBytes = 0;
+  /** Times the layer OFFERED a continuation to the law.  Read with
+   *  {@link lawRejects}: the offers the law refused are the Model X contract being
+   *  exercised, and `offerRuns - lawRejects` is the accepted transitions. */
+  offerRuns = 0;
+  /** Times the law REFUSED the continuation the layer offered.  A refusal is
+   *  terminal by the layer's contract, so this counts the moments the contract
+   *  mattered — zero means the walk never needed it. */
+  lawRejects = 0;
   /** Bytes of the question's REMAINDER a step CONSUMED — the drop the law's own
    *  `advance` makes when a declared move carries the material it accounts for.
-   *  Read with {@link reasonSteps} and {@link reasonCarriedBytes}: carrying is
+   *  Read with {@link reasonSteps} and {@link reasonAccountedBytes}: carrying is
    *  the engagement, this is the consumption, and before it the second was
    *  invisible. */
   closureDrainedBytes = 0;

package/src/mind/attention.ts

@@ -347,6 +347,11 @@ export interface ClimbConsensusData {
   };
 
   regions?: ConsensusRegionTrace[];
+  /** A NAME SHARED WITH THE LAW, AND NOT THE SAME THING: these are the reaches
+   *  the consensus climb took, for the trace.  The law's `Continuation.reaches`
+   *  (derivation.ts) is a producer's claim that a step moves — different type,
+   *  different owner, no relation.  Kept distinct rather than renamed because the
+   *  trace's own vocabulary is about the climb, not about derivation. */
   reaches?: ConsensusReachTrace[];
 
   crossRegion?: {

package/src/mind/derivation.ts

@@ -359,6 +359,15 @@ export function admissible(
   W: number,
 ): ReadonlyArray<Witness> | null {
   if (d.fixed) return null;
+  // THE GATE THAT NEVER FIRES, AND WHY IT STAYS.  `contains` is the step's claim
+  // to BE a continuation of this product at all, and the formula is stated with
+  // it (see the doc above).  Every producer in the engine declares it true — the
+  // three literals in reasoning.ts are constants, measured — so this line cannot
+  // reject anything today.  It stays because the claim is what makes an `Offer`
+  // answerable: a layer that handed over something it does not call a
+  // continuation would be refused here rather than trusted.  What it must NOT be
+  // is a place where a producer says "false" to end a walk: the walk ends by
+  // offering nothing (`null`), which is the contract.
   if (!t.contains) return null;
   if (closed(d)) return (t.explains ?? []).map((span) => ({ span }));
   // MOVES BEFORE CARRIES, and that order is not arbitrary: a transition that
@@ -429,14 +438,19 @@ export function advance(
 /** What a layer offers the law: the next continuation of a state, or null when
  *  it has none.  A layer OFFERS; the law disposes.
  *
- *  ONE OFFER, AND IT IS THE LAYER'S LAST: {@link closure} stops when the law
- *  refuses what was offered, so a refusal is read as "no continuation exists".
- *  A layer must not offer candidates one at a time and expect the walk to
- *  continue after a refusal — its own fallbacks belong inside this function.
- *  The producers do exactly that: they choose between the forward absorb and the
- *  pivot before offering, and return null only when neither exists, which is why
- *  the one offer the law can still refuse (a pivot without ownership, whose
- *  material the answer does not carry) really is the last one. */
+ *  ONE OFFER AT A TIME: {@link closure} asks again only while the law admits what
+ *  was offered, so a refusal ends the walk.  A layer must not offer candidates
+ *  one at a time and expect the walk to continue after a refusal — its own
+ *  fallbacks belong inside this function, and the producers do exactly that:
+ *  they choose between the forward absorb and the pivot before offering.
+ *
+ *  WHAT `null` DOES NOT SAY: it is not a claim of exhaustion.  A layer returns
+ *  null for several distinct reasons — it exhausted its enumeration, it refused a
+ *  candidate it had reached, or a read bound cut one off — and the law cannot tell
+ *  them apart: it reads every one as "no continuation exists".  The layer's reasons
+ *  are therefore made OBSERVABLE where they happen, on the rationale's own channel
+ *  (`enumerationExhausted`, `pivotCandidateRefused`, `absorbCandidateRefused`), and
+ *  it is there — not here — that a reader learns which of them stopped the walk. */
 export type Offer = (d: DerivationState) => Promise<Continuation | null>;
 
 /** THE CLOSURE — the walk of {@link advance} over the continuations `offer`
@@ -454,7 +468,11 @@ export async function closure(
   W: number,
   offer: Offer,
   /** Called for each step the law admits, with the state before and after. */
-  onTaken?: (before: DerivationState, after: DerivationState) => void,
+  onTaken?: (
+    before: DerivationState,
+    after: DerivationState,
+    witnesses: ReadonlyArray<Witness>,
+  ) => void,
   /** Called when the law refused the continuation the layer offered. */
   onRefused?: (at: DerivationState) => void,
 ): Promise<DerivationState> {
@@ -467,7 +485,7 @@ export async function closure(
       return d;
     }
     const next = advance(d, t, explains);
-    onTaken?.(d, next);
+    onTaken?.(d, next, explains);
     d = next;
   }
 }

package/src/mind/pipeline.ts

@@ -664,6 +664,15 @@ export async function think(
     meter.postGroundingRemainderSpans += uncovered.length;
     meter.postGroundingRemainderBytes += unaccountedBytes(uncovered);
   }
+  // THE WALK THAT DOES NOT RUN, NAMED — the audit's point 1 could not attribute
+  // real questions that stopped with no note anywhere.  They never reached the
+  // offer: `decided.complete` says the grounding supplied a fixed point, so the
+  // walk is skipped BY DESIGN and the state is the grounding's own.  That state
+  // carries `fixed: true` (the trace already reports it), and the law's first
+  // clause refuses any continuation against it — so there is no `null` here to
+  // read as exhaustion, and the `Offer` contract is not in play at all.  The
+  // silent stop is therefore a NAMED state, not a gap.
+  //
   // 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