@hviana/sema 0.8.6 → 0.8.7

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

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))

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
@@ -198,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) &&
@@ -209,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 };
@@ -273,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

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`–`143`     |
+| 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`–`143`    | `closure.md`              |
+| 14 | Closure                              | `src/mind/derivation.ts:closed,admissible,advance`                                                                                    | `test/133`–`147`    | `closure.md`              |

package/docs/architecture/closure.md

@@ -76,3 +76,5 @@ vocabulary, not the tracer's.
 - `test/139` — carrying is ENGAGEMENT, not explanation.
 - `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`–`143`). §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.6",
+  "version": "0.8.7",
   "exports": "./src/index.ts"
 }

package/package.json

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

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`

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

package/src/mind/reasoning.ts

@@ -58,6 +58,18 @@ export async function reason(
   // 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;
   }
 
@@ -221,10 +233,37 @@ export async function reason(
     // 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.
+    // 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 &&
-      ctx.store.nextFirst(curId, bound).some((n) => !consumed.has(n))
+      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 (
@@ -236,18 +275,79 @@ export async function reason(
         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) return 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 };
@@ -324,6 +424,34 @@ export async function reason(
     },
   );
 
+  // 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

package/src/mind/traverse.ts

@@ -563,7 +563,13 @@ export function hubCap<T>(
 /** 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: MindContext,
   ancestor: number,

package/test/142-the-layer-offers-only-what-the-law-admits.test.mjs

@@ -17,7 +17,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { Mind } from "../dist/src/index.js";
 import { SQliteStore } from "../dist/src/store-sqlite.js";
-import { admissible } from "../dist/src/mind/derivation.js";
+import { admissible, closure } from "../dist/src/mind/derivation.js";
 
 const QUERY = new TextEncoder().encode("ABCDEFGHIJ");
 const W = 4;
@@ -91,3 +91,65 @@ test("142.2 the walk ends at the refusal, with the satisfying answer untouched",
     "the layer's last offer was refused, and the answer stands",
   );
 });
+
+// B OF THE AUDIT'S TEN: what a refusal MEANS at the walk's boundary.
+//
+// The walk asks ONCE per round and stops when the law refuses it — it does not ask
+// again.  That is the load-bearing half of the `Offer` contract: a refusal is read
+// as "no continuation exists", and it is why the layer must offer only what the law
+// will admit (model X, pinned by 142.1 and 142.2).  A layer that offered candidates
+// for the law to filter would be wrong here, and its own fallbacks must therefore be
+// INTERNAL to one offer call — which is what the engine's layer does.
+//
+// WHAT THIS DOES NOT SETTLE, and must not be read as settling: the walk reads every
+// reason the layer stopped as exhaustion, and the audit found six of them (exhausted,
+// candidate refused, cycle, read bound, no structure, layer done).  `enumerationExhausted`
+// in reasoning.ts now makes that claim observable; proving the claim TRUE is the open
+// decision the audit left (its section 18.6), not something this test asserts.
+test("142.3 a refusal ends the walk, and is not retried", async () => {
+  const enc = (t) => new TextEncoder().encode(t);
+  // Refused on the law's own ground; admitted for carrying a window (both from 142.1).
+  const REFUSED = { product: enc("Paris"), contains: true, cost: 1 };
+  const ADMITTED = { product: enc("ZZZZABCDZZ"), contains: true, cost: 1 };
+
+  // SANITY FIRST: the literals must be what this test says they are, or the walk
+  // below would end for another reason and pin nothing.
+  assert.equal(
+    admissible(state(), REFUSED, QUERY, W),
+    null,
+    "REFUSED is refused by the law (as in 142.1)",
+  );
+  assert.notEqual(
+    admissible(state(), ADMITTED, QUERY, W),
+    null,
+    "ADMITTED carries a window, so the law admits it (as in 142.1)",
+  );
+
+  const queued = [REFUSED, ADMITTED];
+  const offered = [];
+  const offer = async () => {
+    const next = queued.length > 0 ? queued.shift() : null;
+    offered.push(next);
+    return next;
+  };
+  const taken = [];
+  await closure(
+    state(),
+    QUERY,
+    W,
+    offer,
+    (_before, after) => taken.push(after),
+  );
+
+  assert.equal(
+    offered.length,
+    1,
+    "the law is asked once: a refusal is not retried",
+  );
+  assert.equal(
+    taken.length,
+    0,
+    "nothing was taken — the walk ended at the refusal",
+  );
+  assert.equal(queued.length, 1, "the second candidate was never offered");
+});

package/test/144-identity-is-content.test.mjs

@@ -0,0 +1,55 @@
+// 144-identity-is-content.test.mjs — two nodes with the same payload do not exist.
+//
+// WHAT IS PINNED.  Two of the audit's ten discriminating tests look like identity
+// gaps and are not: F ("same payload in two nodes") and G ("the same structure by
+// different paths").  The store is content-addressed, so the same text deposited
+// twice adds NO structure at all, and the second deposit resolves to the very node
+// the first one interned.  That is measured here, on the public surface, rather
+// than argued.
+//
+// WHY IT MATTERS FOR THE LAW.  The layer's cycle control is a set of NODE IDS, so
+// if identical content could live at two ids, the set would miss the second — which
+// is what the audit suspected.  It cannot: identity IS the content.  The consequence
+// is the audit's answer to G — "the same structure by another path" is the same
+// node, and calling its re-reach a cycle is correct, because that node's content was
+// already accounted for.
+//
+// The measurement also carries its own sanity: the first deposit MUST move the
+// count, or the probe is measuring the wrong quantity and proves nothing.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Mind, SQliteStore } from "../dist/src/index.js";
+
+test("144.1 depositing the same text twice adds no structure", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "sema-144-"));
+  const stem = join(dir, "store");
+  const store = new SQliteStore({ path: stem });
+  try {
+    const mind = new Mind({ seed: 7, store });
+    const before = store.edgeSourceCount();
+    await mind.ingest("a b c");
+    const once = store.edgeSourceCount();
+    await mind.ingest("a b c");
+    const twice = store.edgeSourceCount();
+
+    // SANITY FIRST: the quantity has to be one the deposit moves, otherwise the
+    // assertion below is true for the wrong reason and pins nothing.
+    assert.ok(
+      once > before,
+      `the first deposit must add structure (was ${before}, now ${once}) — ` +
+        `if it does not, this test is measuring the wrong quantity`,
+    );
+    assert.equal(
+      twice,
+      once,
+      "the same text deposited twice must not add structure: identity IS content",
+    );
+  } finally {
+    await store.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/test/145-the-instrument-answers.test.mjs

@@ -0,0 +1,58 @@
+// 145-the-instrument-answers.test.mjs — a measurement must move what it claims to measure.
+//
+// WHY THIS FILE EXISTS.  During the derivation audit four probes were run and four times the
+// instrument, not the engine, was wrong: a local import map that could not resolve the engine's
+// types; a call I believed deposited text and deposited nothing; a trace note that never fired
+// because the corpus did not reach it; and a two-hop question that grounded on one hop.  Every
+// time the output looked like a result.  The guards that caught them lived inside the probes,
+// and a probe is thrown away — so the two quantities this suite measures with are pinned here,
+// where the next person will find them (AGENTS 6: close the gap in the instrumentation, once).
+//
+// WHAT IS PINNED.  `edgeSourceCount()` must MOVE when a deposit adds structure, and must NOT
+// move when the same text is deposited again.  Positive and negative together are what make it
+// an instrument: the first says it is alive, the second says it discriminates.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Mind, SQliteStore } from "../dist/src/index.js";
+
+async function withStore(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "sema-145-"));
+  const store = new SQliteStore({ path: join(dir, "store") });
+  try {
+    return await fn(new Mind({ seed: 7, store }), store);
+  } finally {
+    await store.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("145.1 the instrument is alive: a deposit moves the edge-source count", async () => {
+  await withStore(async (mind, store) => {
+    const before = store.edgeSourceCount();
+    await mind.ingest("a b c");
+    const after = store.edgeSourceCount();
+    assert.ok(
+      after > before,
+      `a deposit must move the count (was ${before}, now ${after}) — if it does not, ` +
+        `every probe that reads this number measures the wrong quantity`,
+    );
+  });
+});
+
+test("145.2 the instrument discriminates: the same text moves nothing", async () => {
+  await withStore(async (mind, store) => {
+    await mind.ingest("a b c");
+    const once = store.edgeSourceCount();
+    await mind.ingest("a b c");
+    assert.equal(
+      store.edgeSourceCount(),
+      once,
+      "the same text again must not move the count — otherwise the number cannot tell " +
+        "new structure from repeated text, and F of the audit would be unmeasurable",
+    );
+  });
+});

package/test/146-the-contains-gate.test.mjs

@@ -0,0 +1,67 @@
+// 146-the-contains-gate.test.mjs — `contains`, the one gate no producer ever closes.
+//
+// WHAT IS PINNED.  The formula above `admissible` is written with CONTAINS as a term, and the
+// engine's three producers all declare it true (measured: the only `contains:` literals in src/
+// are reasoning.ts's absorb, pivot and fusion — all constants).  So the gate cannot reject
+// anything today, and this file makes that state explicit rather than accidental:
+//
+//   • the clause WORKS when it is told false — the law is not ignoring the field;
+//   • and a layer that wants to END a walk does it by offering nothing (`null`), not by declaring
+//     a step that is not a continuation.
+//
+// The second half is the contract; the first is the proof that the field is real.  A gate that
+// neither fires nor is exercised is indistinguishable from a field that was forgotten.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { admissible } from "../dist/src/mind/derivation.js";
+
+const QUERY = new TextEncoder().encode("ABCDEFGHIJ");
+const W = 4;
+const state = () => ({
+  product: new Uint8Array(0),
+  accounted: [],
+  remainder: [[0, 10]],
+  cost: 0,
+});
+
+test("146.1 the contains clause refuses when it is told false", () => {
+  const admits = {
+    product: new TextEncoder().encode("ZZZZABCDZZ"),
+    contains: true,
+    cost: 1,
+  };
+  assert.notEqual(
+    admissible(state(), admits, QUERY, W),
+    null,
+    "with contains true and a window held, the law admits",
+  );
+  assert.equal(
+    admissible(state(), { ...admits, contains: false }, QUERY, W),
+    null,
+    "with contains false the law refuses, whatever else the step carries — " +
+      "so the field is read, not decorative",
+  );
+});
+
+test("146.2 contains false is not how a walk ends", async () => {
+  // The contract's own words, in the law's doc: a layer ends a walk by offering
+  // nothing.  A step that declares itself not-a-continuation is refused, which is
+  // what makes the declaration meaningful rather than a way to stop silently.
+  const step = {
+    product: new TextEncoder().encode("ZZZZABCDZZ"),
+    contains: true,
+    reaches: true,
+    cost: 1,
+  };
+  assert.notEqual(
+    admissible(state(), step, QUERY, W),
+    null,
+    "a declared move is admitted",
+  );
+  assert.equal(
+    admissible(state(), { ...step, contains: false }, QUERY, W),
+    null,
+    "and the same move with contains false is refused — the claim gates everything",
+  );
+});

package/test/147-the-witness-ladder.test.mjs

@@ -0,0 +1,76 @@
+// 147-the-witness-ladder.test.mjs — consumed ⊆ carried ⊆ accounted, non-vacuously.
+//
+// WHY THIS FILE EXISTS.  The audit's point 5 (E, partial) asks whether the accounting ever exceeds
+// the window: the consumed window is where the remainder drains, the accounting registers the
+// span, and `span != window` is the established reading.  Measured on the real corpus, the three
+// counter families are ZERO on every roteiro question — the answers there come from grounding and
+// derive-through, not from the reasoner's own extensions — and a ladder of zeroes proves nothing.
+// So the ladder is pinned where the values cannot be zero: on a state built for the purpose.
+//
+// WHAT IS PINNED.  Given a step whose product carries a window of what is still owed:
+//   • the law admits it and the witness carries a SPAN and a WINDOW (the two readings);
+//   • the remainder shrinks by AT MOST the window — the consumed set is a subset of the carried one;
+//   • and the accounting grows by AT LEAST the window — nothing consumed goes unaccounted.
+// The sanity assertion is part of the pin: the window must be non-zero, or the two inequalities
+// above hold for the wrong reason.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { admissible, advance } from "../dist/src/mind/derivation.js";
+
+const QUERY = new TextEncoder().encode("ABCDEFGHIJ"); // W = 4 ⇒ one window is "ABCD"
+const W = 4;
+const bytesOf = (spans) => spans.reduce((n, [a, b]) => n + (b - a), 0);
+const state = () => ({
+  product: new Uint8Array(0),
+  accounted: [],
+  remainder: [[0, 10]],
+  cost: 0,
+});
+
+test("147.1 consumed ⊆ carried ⊆ accounted, with a window that is not zero", () => {
+  const step = {
+    product: new TextEncoder().encode("ZZZZABCDZZ"),
+    contains: true,
+    cost: 1,
+  };
+  const before = state();
+  const witnesses = admissible(before, step, QUERY, W);
+  assert.notEqual(
+    witnesses,
+    null,
+    "the law admits a step that carries a window",
+  );
+
+  const windows = witnesses.filter((x) => x.window !== undefined);
+  assert.ok(
+    windows.length > 0,
+    "SANITY: at least one witness must carry a window, or the inequalities below are vacuous",
+  );
+  const windowBytes = windows.reduce(
+    (n, x) => n + (x.window[1] - x.window[0]),
+    0,
+  );
+  assert.ok(
+    windowBytes > 0,
+    `SANITY: the window must be non-zero (got ${windowBytes})`,
+  );
+
+  const after = advance(before, step, witnesses);
+  const spanBytes = bytesOf(witnesses.map((x) => x.span));
+  const drained = bytesOf(before.remainder) - bytesOf(after.remainder);
+  const accounted = bytesOf(after.accounted) - bytesOf(before.accounted);
+
+  assert.ok(
+    drained <= windowBytes,
+    `a step drains AT MOST what it carries: drained ${drained} > window ${windowBytes}`,
+  );
+  assert.ok(
+    accounted >= windowBytes,
+    `nothing consumed goes unaccounted: accounted ${accounted} < window ${windowBytes}`,
+  );
+  assert.ok(
+    spanBytes > 0,
+    "and the accounting is a span, which is why it may exceed the window",
+  );
+});