@hviana/sema 0.2.9 → 0.3.0

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

@@ -63,6 +63,11 @@ export interface ConsensusReachTrace {
     contextsReached: number;
     saturated: boolean;
     saturation?: SaturationStop;
+    /** Nodes the climb processed — see {@link AncestorReach.visited}.  Absent
+     *  on payloads recorded before this field existed. */
+    visited?: number;
+    /** Maximum ascent distance — see {@link AncestorReach.maxDepth}. */
+    maxDepth?: number;
 }
 export type AnchorRejectionReason = "below-natural-break" | "below-consensus-floor" | "leading-saturation";
 export interface ConsensusAnchorTrace {

package/dist/src/mind/attention.js

@@ -38,6 +38,9 @@ function serialiseReaches(reachMemo) {
             contextsReached: r.contextsReached,
             saturated: r.saturated,
             ...(r.saturation ? { saturation: r.saturation } : {}),
+            ...(r.visited !== undefined
+                ? { visited: r.visited, maxDepth: r.maxDepth }
+                : {}),
         });
     }
     return out;

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

@@ -5,3 +5,5 @@ export type { MechanismResult, PipelineMechanism, Precomputed, } from "./pipelin
 export type { InspectRationale, RationaleItem, RationaleStep, } from "./rationale.js";
 export type { AnchorRejectionReason, ClimbConsensusData, ConsensusAnchorTrace, ConsensusReachTrace, ConsensusRegionTrace, CrossRegionTier, JunctionVoteTrace, RegionOutcome, } from "./attention.js";
 export type { AncestorReach, AttentionRead, SaturationReason, SaturationStop, } from "./types.js";
+export type { DepositReport } from "./learning.js";
+export type { DecideGroundingData, NarrowDecisionData, Provenance, } from "./pipeline.js";

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

@@ -28,8 +28,30 @@ export declare function deposit(ctx: MindContext, input: Input, track: boolean,
 export declare function ingestOne(ctx: MindContext, input: Input): Promise<Sema & {
     id: number;
 }>;
-/** Ingest a pair (context, continuation) — learn an edge and pour halos. */
-export declare function ingestPair(ctx: MindContext, ctxInput: Input, cont: Input): Promise<void>;
+/** What one ingested item deposited — reported through {@link ingest}'s
+ *  optional `onDeposit` callback.  Pure provenance read-out: node ids are
+ *  content-addressed, so two byte-identical items report the SAME ids (that
+ *  is content addressing working, not an error), and the callback observes
+ *  the deposit without influencing it. */
+export interface DepositReport {
+    /** Zero-based position of the item in the ingested input (0 for a scalar
+     *  or single pair). */
+    index: number;
+    /** Whether the item was a bare experience or a (context, continuation)
+     *  pair. */
+    kind: "one" | "pair";
+    /** Root node id of the item's (context) bytes. */
+    contextId: number;
+    /** Root node id of the continuation bytes — pairs only. */
+    continuationId?: number;
+}
+/** Ingest a pair (context, continuation) — learn an edge and pour halos.
+ *  Returns the deposited root ids (context, continuation) — a pure
+ *  read-out; callers that ignore it behave exactly as before. */
+export declare function ingestPair(ctx: MindContext, ctxInput: Input, cont: Input): Promise<{
+    ctxId: number;
+    contId: number;
+}>;
 /** Dispatch the public ingest input shapes onto one-input / pair handlers —
  *  THE one reading of ingest's polymorphic surface (scalar, (context,
  *  continuation) pair, or a list mixing bare inputs and pairs).  Both ingest
@@ -41,7 +63,13 @@ export declare function dispatchIngest(input: Input | (Input | [Input, Input])[]
 }>, onPair: (ctxInput: Input, cont: Input) => Promise<void>): Promise<(Sema & {
     id: number;
 }) | undefined>;
-/** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
-export declare function ingest(ctx: MindContext, input: Input | (Input | [Input, Input])[], second?: Input): Promise<(Sema & {
+/** Ingest an input or array of inputs/pairs.  The public ingest entry point.
+ *
+ *  `onDeposit`, when given, is invoked once per ingested item with the
+ *  deposited root node ids ({@link DepositReport}) — item-level provenance
+ *  for tooling that needs to know which stored node an ingested item became.
+ *  Purely observational: the callback runs after the item's deposit
+ *  completed and nothing reads its result. */
+export declare function ingest(ctx: MindContext, input: Input | (Input | [Input, Input])[], second?: Input, onDeposit?: (report: DepositReport) => void): Promise<(Sema & {
     id: number;
 }) | undefined>;

package/dist/src/mind/learning.js

@@ -188,7 +188,9 @@ async function propagateSuffixes(ctx, src, dst) {
         await ctx.store.link(id, dst);
     }
 }
-/** Ingest a pair (context, continuation) — learn an edge and pour halos. */
+/** Ingest a pair (context, continuation) — learn an edge and pour halos.
+ *  Returns the deposited root ids (context, continuation) — a pure
+ *  read-out; callers that ignore it behave exactly as before. */
 export async function ingestPair(ctx, ctxInput, cont) {
     const c = await deposit(ctx, ctxInput, true, true);
     const cont_ = await deposit(ctx, cont, false);
@@ -213,6 +215,7 @@ export async function ingestPair(ctx, ctxInput, cont) {
         await ctx.store.pourHalo(partId, contSeat);
         await ctx.store.pourHalo(contId, bindSeat(ctx.space, companySignature(ctx.space, partId), 0));
     }
+    return { ctxId, contId };
 }
 /** Dispatch the public ingest input shapes onto one-input / pair handlers —
  *  THE one reading of ingest's polymorphic surface (scalar, (context,
@@ -242,7 +245,26 @@ export async function dispatchIngest(input, second, onOne, onPair) {
     await onPair(input, second);
     return undefined;
 }
-/** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
-export async function ingest(ctx, input, second) {
-    return dispatchIngest(input, second, (i) => ingestOne(ctx, i), (a, b) => ingestPair(ctx, a, b));
+/** Ingest an input or array of inputs/pairs.  The public ingest entry point.
+ *
+ *  `onDeposit`, when given, is invoked once per ingested item with the
+ *  deposited root node ids ({@link DepositReport}) — item-level provenance
+ *  for tooling that needs to know which stored node an ingested item became.
+ *  Purely observational: the callback runs after the item's deposit
+ *  completed and nothing reads its result. */
+export async function ingest(ctx, input, second, onDeposit) {
+    let index = 0;
+    return dispatchIngest(input, second, async (i) => {
+        const r = await ingestOne(ctx, i);
+        onDeposit?.({ index: index++, kind: "one", contextId: r.id });
+        return r;
+    }, async (a, b) => {
+        const { ctxId, contId } = await ingestPair(ctx, a, b);
+        onDeposit?.({
+            index: index++,
+            kind: "pair",
+            contextId: ctxId,
+            continuationId: contId,
+        });
+    });
 }

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

@@ -235,7 +235,10 @@ export declare class Mind implements MindContext {
      *  read-out direction of the same operation, without recall's grounding
      *  ladder.  If either side's acceptance rule changes, revisit the other. */
     express(idOrV: number | Vec): Promise<Uint8Array>;
-    ingest(input: Input | (Input | [Input, Input])[], second?: Input): Promise<(Sema & {
+    /** See {@link import("./learning.js").ingest} — `onDeposit`, when given,
+     *  reports each ingested item's deposited root node ids
+     *  ({@link DepositReport}); purely observational. */
+    ingest(input: Input | (Input | [Input, Input])[], second?: Input, onDeposit?: (report: import("./learning.js").DepositReport) => void): Promise<(Sema & {
         id: number;
     }) | undefined>;
     private extensionHost;

package/dist/src/mind/mind.js

@@ -464,8 +464,11 @@ export class Mind {
         return new Uint8Array(0);
     }
     // ── Learning ─────────────────────────────────────────────────────────────
-    async ingest(input, second) {
-        return ingest(this, input, second);
+    /** See {@link import("./learning.js").ingest} — `onDeposit`, when given,
+     *  reports each ingested item's deposited root node ids
+     *  ({@link DepositReport}); purely observational. */
+    async ingest(input, second, onDeposit) {
+        return ingest(this, input, second, onDeposit);
     }
     // ── Extension Surface ────────────────────────────────────────────────────
     extensionHost() {

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

@@ -8,6 +8,35 @@ export interface Thought {
     bytes: Uint8Array;
     provenance: Provenance;
 }
+/** Structured payload of the "decideGrounding" rationale step — the same
+ *  numbers the human-readable candidate labels already carry, exposed as
+ *  data so a downstream tool need not parse free text.  Purely additive
+ *  instrumentation: built only under `ctx.trace?.` (optional chaining
+ *  short-circuits its arguments), never read by inference. */
+export interface DecideGroundingData {
+    version: 1;
+    /** Every grounding candidate weighed, in consideration order. */
+    candidates: Array<{
+        provenance: string;
+        /** The candidate's exact weight in the one cost ladder. */
+        weight: number;
+        /** The DISCRETE grade the decision actually compares (floor(weight/STEP)). */
+        grade: number;
+        /** Query bytes the candidate's accounted spans leave unexplained. */
+        unexplainedBytes: number;
+        /** Whether this candidate won the decision. */
+        decided: boolean;
+    }>;
+    /** Grade margin between the winner and the runner-up, when both exist —
+     *  the same quantity the "narrowDecision" step reports as narrow when
+     *  ≤ 1.  Absent for a single-candidate decision. */
+    runnerUpMargin?: number;
+}
+/** Structured payload of the "narrowDecision" rationale step. */
+export interface NarrowDecisionData {
+    version: 1;
+    margin: number;
+}
 /** Think: a single lightest-derivation exploration of the Sema graph.
  *
  *  Every answer travels the same path:

package/dist/src/mind/pipeline.js

@@ -132,9 +132,12 @@ export async function think(ctx, query, mechs) {
     // initial null, so the read-back needs the assertion.)
     const decided = best;
     if (candidates.length > 1) {
-        ctx.trace?.step("decideGrounding", candidates.map((c) => rItem(c.bytes, `${c.provenance} (weight ${c.weight.toFixed(3)}${c.unexplained ? `, unexplained: "${c.unexplained}"` : ""})`)), decided ? [rItem(decided.bytes, decided.provenance)] : [], "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder");
+        // The runner-up is computed BEFORE the decideGrounding step so its grade
+        // margin can ride along in the step's structured data payload; the
+        // computation itself is pure and was always unconditional — only its
+        // position moved.
+        let runnerUp = null;
         if (decided !== null) {
-            let runnerUp = null;
             for (const c of candidates) {
                 if (c === decided)
                     continue;
@@ -142,15 +145,28 @@ export async function think(ctx, query, mechs) {
                     runnerUp = c;
                 }
             }
-            if (runnerUp !== null) {
-                const margin = grade(runnerUp.weight) - grade(decided.weight);
-                if (margin <= 1) {
-                    ctx.trace?.step("narrowDecision", [
-                        rItem(decided.bytes, `${decided.provenance} (weight ${decided.weight.toFixed(3)})`),
-                    ], [
-                        rItem(runnerUp.bytes, `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`),
-                    ], `margin ${margin} grade-unit(s) — the decision could change with one more training fact`);
-                }
+        }
+        const margin = decided !== null && runnerUp !== null
+            ? grade(runnerUp.weight) - grade(decided.weight)
+            : null;
+        ctx.trace?.step("decideGrounding", candidates.map((c) => rItem(c.bytes, `${c.provenance} (weight ${c.weight.toFixed(3)}${c.unexplained ? `, unexplained: "${c.unexplained}"` : ""})`)), decided ? [rItem(decided.bytes, decided.provenance)] : [], "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder", undefined, {
+            version: 1,
+            candidates: candidates.map((c) => ({
+                provenance: c.provenance,
+                weight: c.weight,
+                grade: grade(c.weight),
+                unexplainedBytes: unaccounted(c.accounted),
+                decided: c === decided,
+            })),
+            ...(margin !== null ? { runnerUpMargin: margin } : {}),
+        });
+        if (decided !== null && runnerUp !== null && margin !== null) {
+            if (margin <= 1) {
+                ctx.trace?.step("narrowDecision", [
+                    rItem(decided.bytes, `${decided.provenance} (weight ${decided.weight.toFixed(3)})`),
+                ], [
+                    rItem(runnerUp.bytes, `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`),
+                ], `margin ${margin} grade-unit(s) — the decision could change with one more training fact`, undefined, { version: 1, margin });
             }
         }
     }

package/dist/src/mind/traverse.js

@@ -102,6 +102,8 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
                         observed: atomReach(ctx, contextCount),
                         limit: bound0,
                     },
+                    visited: 0,
+                    maxDepth: 0,
                 }
                 : {}),
         };
@@ -151,7 +153,20 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     // ~20K distinct nodes per climb family, >95% unique — not memoisable)
     // while the context account never decided.
     let lateral = 0;
+    // CLIMB READ-OUT (pure instrumentation, same contract as satStop): the
+    // parallel `depths` stack mirrors every push/pop of `stack`, so a node's
+    // ascent distance is known at its pop.  Allocated only when a trace is
+    // requested; the climb itself never reads any of these back.
+    const depths = ctx.trace ? [] : null;
+    let curDepth = 0;
+    let visitedCount = 0;
+    let maxDepth = 0;
     const visit = (x) => {
+        if (depths) {
+            visitedCount++;
+            if (curDepth > maxDepth)
+                maxDepth = curDepth;
+        }
         const hasNx = cachedHasNext(ctx, x, structCache);
         const pc = cachedPrevCount(ctx, x, structCache);
         if (hasNx || pc > 0) {
@@ -203,6 +218,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
             if (!seen.has(p)) {
                 seen.add(p);
                 stack.push(p);
+                depths?.push(curDepth + 1);
                 fresh++;
             }
         }
@@ -225,8 +241,10 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
     };
     const stack = [];
     const containment = !cachedHasParents(ctx, id, structCache);
-    if (!containment)
+    if (!containment) {
         stack.push(id);
+        depths?.push(0);
+    }
     // The containment seed is STREAMED in pages of √N: a distinctive window's
     // containers (which converge on one or two contexts, however many chunks
     // of one deposit repeat it) are walked IN FULL — exact — while a common
@@ -247,17 +265,22 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
                 if (!seen.has(c)) {
                     seen.add(c);
                     stack.push(c);
+                    depths?.push(1);
                 }
             }
             if (stack.length === 0) {
-                if (containerOff === 0)
+                if (containerOff === 0) {
                     stack.push(id); // no containers at all
+                    depths?.push(0);
+                }
                 else
                     break;
             }
         }
         while (stack.length > 0) {
             let x = stack.pop();
+            if (depths)
+                curDepth = depths.pop();
             // TRANSPARENT-CHAIN HOP: a node with no edges in or out and exactly one
             // parent contributes nothing here — no root, no context, no lateral
             // entry — so the run to its first non-transparent ancestor is skipped
@@ -277,6 +300,10 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
                 if (dup)
                     continue;
                 x = top;
+                // The chain's interior hops are part of the terminal's ascent
+                // distance — count them exactly as a node-at-a-time ascent would.
+                if (depths)
+                    curDepth += run.length - 1;
             }
             if (!visit(x)) {
                 saturated = true;
@@ -289,6 +316,7 @@ export function edgeAncestors(ctx, id, contextCount, memo) {
         contextsReached: ctxSeen.size,
         saturated,
         ...(saturated && satStop ? { saturation: satStop } : {}),
+        ...(depths ? { visited: visitedCount, maxDepth } : {}),
     };
     memo?.set(id, reach);
     return reach;

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

@@ -156,6 +156,17 @@ export interface AncestorReach {
      *  a non-saturated reach, and absent (even when saturated) when no trace
      *  was requested — instrumentation must not allocate when tracing is off. */
     saturation?: SaturationStop;
+    /** The number of nodes the climb actually PROCESSED (popped and examined
+     *  by its visit step; a transparent chain counts as its one terminal).
+     *  Present only when a trace was requested — same contract as
+     *  {@link saturation}: instrumentation must not allocate when tracing is
+     *  off.  Purely a read-out; the climb never consults it. */
+    visited?: number;
+    /** The maximum structural ascent distance (in parent/containment hops,
+     *  transparent-chain interiors counted) from the start node among the
+     *  processed nodes.  Present only when a trace was requested — see
+     *  {@link visited}. */
+    maxDepth?: number;
 }
 /** Saturated-interval information for the noise-drop gate. */
 export interface SaturationInfo {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "type": "module",
   "main": "dist/src/index.js",

package/src/mind/attention.ts

@@ -149,6 +149,11 @@ export interface ConsensusReachTrace {
   contextsReached: number;
   saturated: boolean;
   saturation?: SaturationStop;
+  /** Nodes the climb processed — see {@link AncestorReach.visited}.  Absent
+   *  on payloads recorded before this field existed. */
+  visited?: number;
+  /** Maximum ascent distance — see {@link AncestorReach.maxDepth}. */
+  maxDepth?: number;
 }
 
 export type AnchorRejectionReason =
@@ -419,6 +424,9 @@ function serialiseReaches(
       contextsReached: r.contextsReached,
       saturated: r.saturated,
       ...(r.saturation ? { saturation: r.saturation } : {}),
+      ...(r.visited !== undefined
+        ? { visited: r.visited, maxDepth: r.maxDepth }
+        : {}),
     });
   }
   return out;

package/src/mind/index.ts

@@ -32,3 +32,9 @@ export type {
   SaturationReason,
   SaturationStop,
 } from "./types.js";
+export type { DepositReport } from "./learning.js";
+export type {
+  DecideGroundingData,
+  NarrowDecisionData,
+  Provenance,
+} from "./pipeline.js";

package/src/mind/learning.ts

@@ -215,12 +215,32 @@ async function propagateSuffixes(
   }
 }
 
-/** Ingest a pair (context, continuation) — learn an edge and pour halos. */
+/** What one ingested item deposited — reported through {@link ingest}'s
+ *  optional `onDeposit` callback.  Pure provenance read-out: node ids are
+ *  content-addressed, so two byte-identical items report the SAME ids (that
+ *  is content addressing working, not an error), and the callback observes
+ *  the deposit without influencing it. */
+export interface DepositReport {
+  /** Zero-based position of the item in the ingested input (0 for a scalar
+   *  or single pair). */
+  index: number;
+  /** Whether the item was a bare experience or a (context, continuation)
+   *  pair. */
+  kind: "one" | "pair";
+  /** Root node id of the item's (context) bytes. */
+  contextId: number;
+  /** Root node id of the continuation bytes — pairs only. */
+  continuationId?: number;
+}
+
+/** Ingest a pair (context, continuation) — learn an edge and pour halos.
+ *  Returns the deposited root ids (context, continuation) — a pure
+ *  read-out; callers that ignore it behave exactly as before. */
 export async function ingestPair(
   ctx: MindContext,
   ctxInput: Input,
   cont: Input,
-): Promise<void> {
+): Promise<{ ctxId: number; contId: number }> {
   const c = await deposit(ctx, ctxInput, true, true);
   const cont_ = await deposit(ctx, cont, false);
   const ctxId = c.rootId, contId = cont_.rootId;
@@ -249,6 +269,7 @@ export async function ingestPair(
       bindSeat(ctx.space, companySignature(ctx.space, partId), 0),
     );
   }
+  return { ctxId, contId };
 }
 
 /** Dispatch the public ingest input shapes onto one-input / pair handlers —
@@ -286,16 +307,36 @@ export async function dispatchIngest(
   return undefined;
 }
 
-/** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
+/** Ingest an input or array of inputs/pairs.  The public ingest entry point.
+ *
+ *  `onDeposit`, when given, is invoked once per ingested item with the
+ *  deposited root node ids ({@link DepositReport}) — item-level provenance
+ *  for tooling that needs to know which stored node an ingested item became.
+ *  Purely observational: the callback runs after the item's deposit
+ *  completed and nothing reads its result. */
 export async function ingest(
   ctx: MindContext,
   input: Input | (Input | [Input, Input])[],
   second?: Input,
+  onDeposit?: (report: DepositReport) => void,
 ): Promise<(Sema & { id: number }) | undefined> {
+  let index = 0;
   return dispatchIngest(
     input,
     second,
-    (i) => ingestOne(ctx, i),
-    (a, b) => ingestPair(ctx, a, b),
+    async (i) => {
+      const r = await ingestOne(ctx, i);
+      onDeposit?.({ index: index++, kind: "one", contextId: r.id });
+      return r;
+    },
+    async (a, b) => {
+      const { ctxId, contId } = await ingestPair(ctx, a, b);
+      onDeposit?.({
+        index: index++,
+        kind: "pair",
+        contextId: ctxId,
+        continuationId: contId,
+      });
+    },
   );
 }

package/src/mind/mind.ts

@@ -767,11 +767,15 @@ export class Mind implements MindContext {
 
   // ── Learning ─────────────────────────────────────────────────────────────
 
+  /** See {@link import("./learning.js").ingest} — `onDeposit`, when given,
+   *  reports each ingested item's deposited root node ids
+   *  ({@link DepositReport}); purely observational. */
   async ingest(
     input: Input | (Input | [Input, Input])[],
     second?: Input,
+    onDeposit?: (report: import("./learning.js").DepositReport) => void,
   ): Promise<(Sema & { id: number }) | undefined> {
-    return ingest(this, input, second);
+    return ingest(this, input, second, onDeposit);
   }
 
   // ── Extension Surface ────────────────────────────────────────────────────

package/src/mind/pipeline.ts

@@ -77,6 +77,37 @@ export interface Thought {
   provenance: Provenance;
 }
 
+/** Structured payload of the "decideGrounding" rationale step — the same
+ *  numbers the human-readable candidate labels already carry, exposed as
+ *  data so a downstream tool need not parse free text.  Purely additive
+ *  instrumentation: built only under `ctx.trace?.` (optional chaining
+ *  short-circuits its arguments), never read by inference. */
+export interface DecideGroundingData {
+  version: 1;
+  /** Every grounding candidate weighed, in consideration order. */
+  candidates: Array<{
+    provenance: string;
+    /** The candidate's exact weight in the one cost ladder. */
+    weight: number;
+    /** The DISCRETE grade the decision actually compares (floor(weight/STEP)). */
+    grade: number;
+    /** Query bytes the candidate's accounted spans leave unexplained. */
+    unexplainedBytes: number;
+    /** Whether this candidate won the decision. */
+    decided: boolean;
+  }>;
+  /** Grade margin between the winner and the runner-up, when both exist —
+   *  the same quantity the "narrowDecision" step reports as narrow when
+   *  ≤ 1.  Absent for a single-candidate decision. */
+  runnerUpMargin?: number;
+}
+
+/** Structured payload of the "narrowDecision" rationale step. */
+export interface NarrowDecisionData {
+  version: 1;
+  margin: number;
+}
+
 /** Think: a single lightest-derivation exploration of the Sema graph.
  *
  *  Every answer travels the same path:
@@ -211,6 +242,22 @@ export async function think(
   // initial null, so the read-back needs the assertion.)
   const decided = best as Candidate | null;
   if (candidates.length > 1) {
+    // The runner-up is computed BEFORE the decideGrounding step so its grade
+    // margin can ride along in the step's structured data payload; the
+    // computation itself is pure and was always unconditional — only its
+    // position moved.
+    let runnerUp: Candidate | null = null;
+    if (decided !== null) {
+      for (const c of candidates) {
+        if (c === decided) continue;
+        if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
+          runnerUp = c;
+        }
+      }
+    }
+    const margin = decided !== null && runnerUp !== null
+      ? grade(runnerUp.weight) - grade(decided.weight)
+      : null;
     ctx.trace?.step(
       "decideGrounding",
       candidates.map((c) =>
@@ -223,35 +270,39 @@ export async function think(
       ),
       decided ? [rItem(decided.bytes, decided.provenance)] : [],
       "the lightest grounding derivation wins — every mechanism weighed in the one cost ladder",
+      undefined,
+      {
+        version: 1,
+        candidates: candidates.map((c) => ({
+          provenance: c.provenance,
+          weight: c.weight,
+          grade: grade(c.weight),
+          unexplainedBytes: unaccounted(c.accounted),
+          decided: c === decided,
+        })),
+        ...(margin !== null ? { runnerUpMargin: margin } : {}),
+      } satisfies DecideGroundingData,
     );
-    if (decided !== null) {
-      let runnerUp: Candidate | null = null;
-      for (const c of candidates) {
-        if (c === decided) continue;
-        if (runnerUp === null || grade(c.weight) < grade(runnerUp.weight)) {
-          runnerUp = c;
-        }
-      }
-      if (runnerUp !== null) {
-        const margin = grade(runnerUp.weight) - grade(decided.weight);
-        if (margin <= 1) {
-          ctx.trace?.step(
-            "narrowDecision",
-            [
-              rItem(
-                decided.bytes,
-                `${decided.provenance} (weight ${decided.weight.toFixed(3)})`,
-              ),
-            ],
-            [
-              rItem(
-                runnerUp.bytes,
-                `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`,
-              ),
-            ],
-            `margin ${margin} grade-unit(s) — the decision could change with one more training fact`,
-          );
-        }
+    if (decided !== null && runnerUp !== null && margin !== null) {
+      if (margin <= 1) {
+        ctx.trace?.step(
+          "narrowDecision",
+          [
+            rItem(
+              decided.bytes,
+              `${decided.provenance} (weight ${decided.weight.toFixed(3)})`,
+            ),
+          ],
+          [
+            rItem(
+              runnerUp.bytes,
+              `${runnerUp.provenance} (weight ${runnerUp.weight.toFixed(3)})`,
+            ),
+          ],
+          `margin ${margin} grade-unit(s) — the decision could change with one more training fact`,
+          undefined,
+          { version: 1, margin } satisfies NarrowDecisionData,
+        );
       }
     }
   }

package/src/mind/traverse.ts

@@ -147,6 +147,8 @@ export function edgeAncestors(
             observed: atomReach(ctx, contextCount),
             limit: bound0,
           },
+          visited: 0,
+          maxDepth: 0,
         }
         : {}),
     };
@@ -201,7 +203,20 @@ export function edgeAncestors(
   // while the context account never decided.
   let lateral = 0;
 
+  // CLIMB READ-OUT (pure instrumentation, same contract as satStop): the
+  // parallel `depths` stack mirrors every push/pop of `stack`, so a node's
+  // ascent distance is known at its pop.  Allocated only when a trace is
+  // requested; the climb itself never reads any of these back.
+  const depths: number[] | null = ctx.trace ? [] : null;
+  let curDepth = 0;
+  let visitedCount = 0;
+  let maxDepth = 0;
+
   const visit = (x: number): boolean => {
+    if (depths) {
+      visitedCount++;
+      if (curDepth > maxDepth) maxDepth = curDepth;
+    }
     const hasNx = cachedHasNext(ctx, x, structCache);
     const pc = cachedPrevCount(ctx, x, structCache);
     if (hasNx || pc > 0) {
@@ -251,6 +266,7 @@ export function edgeAncestors(
       if (!seen.has(p)) {
         seen.add(p);
         stack.push(p);
+        depths?.push(curDepth + 1);
         fresh++;
       }
     }
@@ -274,7 +290,10 @@ export function edgeAncestors(
 
   const stack: number[] = [];
   const containment = !cachedHasParents(ctx, id, structCache);
-  if (!containment) stack.push(id);
+  if (!containment) {
+    stack.push(id);
+    depths?.push(0);
+  }
 
   // The containment seed is STREAMED in pages of √N: a distinctive window's
   // containers (which converge on one or two contexts, however many chunks
@@ -295,15 +314,19 @@ export function edgeAncestors(
         if (!seen.has(c)) {
           seen.add(c);
           stack.push(c);
+          depths?.push(1);
         }
       }
       if (stack.length === 0) {
-        if (containerOff === 0) stack.push(id); // no containers at all
-        else break;
+        if (containerOff === 0) {
+          stack.push(id); // no containers at all
+          depths?.push(0);
+        } else break;
       }
     }
     while (stack.length > 0) {
       let x = stack.pop()!;
+      if (depths) curDepth = depths.pop()!;
       // TRANSPARENT-CHAIN HOP: a node with no edges in or out and exactly one
       // parent contributes nothing here — no root, no context, no lateral
       // entry — so the run to its first non-transparent ancestor is skipped
@@ -321,6 +344,9 @@ export function edgeAncestors(
         for (let i = 1; i < run.length; i++) seen.add(run[i]);
         if (dup) continue;
         x = top;
+        // The chain's interior hops are part of the terminal's ascent
+        // distance — count them exactly as a node-at-a-time ascent would.
+        if (depths) curDepth += run.length - 1;
       }
       if (!visit(x)) {
         saturated = true;
@@ -334,6 +360,7 @@ export function edgeAncestors(
     contextsReached: ctxSeen.size,
     saturated,
     ...(saturated && satStop ? { saturation: satStop } : {}),
+    ...(depths ? { visited: visitedCount, maxDepth } : {}),
   };
   memo?.set(id, reach);
   return reach;

package/src/mind/types.ts

@@ -205,6 +205,17 @@ export interface AncestorReach {
    *  a non-saturated reach, and absent (even when saturated) when no trace
    *  was requested — instrumentation must not allocate when tracing is off. */
   saturation?: SaturationStop;
+  /** The number of nodes the climb actually PROCESSED (popped and examined
+   *  by its visit step; a transparent chain counts as its one terminal).
+   *  Present only when a trace was requested — same contract as
+   *  {@link saturation}: instrumentation must not allocate when tracing is
+   *  off.  Purely a read-out; the climb never consults it. */
+  visited?: number;
+  /** The maximum structural ascent distance (in parent/containment hops,
+   *  transparent-chain interiors counted) from the start node among the
+   *  processed nodes.  Present only when a trace was requested — see
+   *  {@link visited}. */
+  maxDepth?: number;
 }
 
 /** Saturated-interval information for the noise-drop gate. */

package/test/54-evidence-k-instrumentation.test.mjs

@@ -0,0 +1,175 @@
+// 54-evidence-k-instrumentation.test.mjs — the three purely-additive
+// read-outs added for evidence-breadth measurement tooling:
+//   1. AncestorReach.visited / maxDepth (trace-gated, serialised into
+//      ClimbConsensusData.reaches),
+//   2. structured data payloads on "decideGrounding" / "narrowDecision",
+//   3. ingest()'s optional onDeposit provenance callback.
+//
+// Every assertion here checks a READ-OUT; the final test pins that none of
+// them changes the answer (the same invariant tests 52 §6 / 53 §9 pin for
+// the climb instrumentation).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { decodeText, Mind } from "../dist/src/index.js";
+import { SQliteStore } from "../dist/src/store-sqlite.js";
+
+const mk = (seed = 1) =>
+  new Mind({ seed, store: new SQliteStore({ path: ":memory:" }) });
+
+const CORPUS = [
+  ["red", "is a color"],
+  ["blue", "is a color"],
+  ["circle", "is a shape"],
+  ["square", "is a shape"],
+  ["red circle", "answer alpha"],
+  ["red square", "answer beta"],
+  ["blue circle", "answer gamma"],
+  ["blue square", "answer delta"],
+];
+
+async function trace(mind, q) {
+  const steps = [];
+  const ans = await mind.respondText(q, (s) => steps.push(s));
+  return { steps, ans };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. climb read-out: visited / maxDepth
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("1. traced climb reaches carry visited/maxDepth; untraced ones do not", async () => {
+  const m = mk(1);
+  await m.ingest(CORPUS);
+
+  const { steps } = await trace(m, "red then circle");
+  const climb = steps.find((s) => s.mechanism.at(-1) === "climbConsensus");
+  assert.ok(climb?.data?.reaches?.length > 0, "expected reach traces");
+  for (const r of climb.data.reaches) {
+    assert.equal(typeof r.visited, "number");
+    assert.equal(typeof r.maxDepth, "number");
+    assert.ok(r.visited >= 0);
+    assert.ok(r.maxDepth >= 0);
+    // A climb that processed no node cannot have ascended.  (One processed
+    // node can already sit at depth 1: containment seeds start one hop up.)
+    if (r.visited === 0) assert.equal(r.maxDepth, 0);
+    // Depth is bounded by the number of processed nodes plus any
+    // transparent-chain interiors — sanity only: never negative, and zero
+    // whenever nothing was climbed.
+    assert.ok(r.maxDepth >= 0);
+  }
+
+  // Untraced (no respond in flight): the same contract as `saturation` —
+  // instrumentation fields absent when no trace was requested.
+  const someNode = climb.data.reaches[0].node;
+  const reach = m.edgeAncestors(someNode, 8);
+  assert.equal(reach.visited, undefined);
+  assert.equal(reach.maxDepth, undefined);
+  await m.store.close();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. decideGrounding / narrowDecision data payloads
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("2. decideGrounding carries every candidate's weight/grade as data, exactly one decided", async () => {
+  const m = mk(1);
+  await m.ingest(CORPUS);
+  const { steps, ans } = await trace(m, "red then circle");
+  await m.store.close();
+
+  const dg = steps.find((s) => s.mechanism.at(-1) === "decideGrounding");
+  assert.ok(dg, "expected a decideGrounding step (≥2 candidates)");
+  assert.ok(dg.data, "decideGrounding must carry a data payload");
+  assert.equal(dg.data.version, 1);
+  assert.equal(dg.data.candidates.length, dg.inputs.length);
+  for (const c of dg.data.candidates) {
+    assert.equal(typeof c.provenance, "string");
+    assert.equal(typeof c.weight, "number");
+    assert.equal(typeof c.grade, "number");
+    assert.equal(typeof c.unexplainedBytes, "number");
+    assert.ok(c.unexplainedBytes >= 0);
+  }
+  const decided = dg.data.candidates.filter((c) => c.decided);
+  assert.equal(decided.length, 1, "exactly one candidate wins");
+  // The winner's grade is minimal — the data restates the decision rule.
+  const minGrade = Math.min(...dg.data.candidates.map((c) => c.grade));
+  assert.equal(decided[0].grade, minGrade);
+  assert.ok(ans.length > 0);
+
+  if (dg.data.runnerUpMargin !== undefined) {
+    assert.ok(dg.data.runnerUpMargin >= 0);
+    const nd = steps.find((s) => s.mechanism.at(-1) === "narrowDecision");
+    if (dg.data.runnerUpMargin <= 1) {
+      assert.ok(nd, "margin ≤ 1 must emit narrowDecision");
+      assert.equal(nd.data.version, 1);
+      assert.equal(nd.data.margin, dg.data.runnerUpMargin);
+    } else {
+      assert.equal(nd, undefined);
+    }
+  }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. onDeposit provenance callback
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("3. onDeposit reports one item-indexed record per ingested item, ids content-addressed", async () => {
+  const m = mk(1);
+  const reports = [];
+  await m.ingest(CORPUS, undefined, (r) => reports.push(r));
+
+  assert.equal(reports.length, CORPUS.length);
+  reports.forEach((r, i) => {
+    assert.equal(r.index, i);
+    assert.equal(r.kind, "pair");
+    assert.equal(typeof r.contextId, "number");
+    assert.equal(typeof r.continuationId, "number");
+    // The reported ids ARE the items' content-addressed nodes.
+    assert.equal(decodeText(m.store.bytes(r.contextId)), CORPUS[i][0]);
+    assert.equal(decodeText(m.store.bytes(r.continuationId)), CORPUS[i][1]);
+  });
+  // Content addressing: identical continuations share one node id.
+  const colorIds = [reports[0], reports[1]].map((r) => r.continuationId);
+  assert.equal(colorIds[0], colorIds[1]);
+  await m.store.close();
+});
+
+test("3b. onDeposit reports bare items as kind 'one'; omitting it changes nothing", async () => {
+  const m = mk(1);
+  const reports = [];
+  await m.ingest(
+    ["standalone note", ["ctx", "cont"]],
+    undefined,
+    (r) => reports.push(r),
+  );
+  assert.deepEqual(reports.map((r) => [r.index, r.kind]), [[0, "one"], [
+    1,
+    "pair",
+  ]]);
+  assert.equal(reports[1].continuationId !== undefined, true);
+  assert.equal(reports[0].continuationId, undefined);
+  await m.store.close();
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. none of the read-outs changes the answer
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("4. answers are identical with and without the new read-outs attached", async () => {
+  const ask = async (withHooks) => {
+    const m = mk(7);
+    await m.ingest(CORPUS, undefined, withHooks ? () => {} : undefined);
+    const out = [];
+    for (
+      const q of ["red then circle", "red circle blue square", "blue square"]
+    ) {
+      out.push(
+        withHooks ? await m.respondText(q, () => {}) : await m.respondText(q),
+      );
+    }
+    await m.store.close();
+    return out;
+  };
+  assert.deepEqual(await ask(true), await ask(false));
+});