@hviana/sema 0.2.9 → 0.4.0

package/src/mind/bridge.ts

@@ -94,9 +94,14 @@ import { cosine } from "../vec.js";
 import { conceptThreshold, dominates } from "../geometry.js";
 import { bytesEqual, indexOf } from "../bytes.js";
 import type { MindContext } from "./types.js";
-import { foldTree, perceive } from "./primitives.js";
+import { foldTree, perceive, read } from "./primitives.js";
 import { chainReach, leafIdRun } from "./canonical.js";
-import { corpusN, edgeAncestors, hubBound } from "./traverse.js";
+import {
+  corpusN,
+  edgeAncestors,
+  hubBound,
+  sharedReachMemo,
+} from "./traverse.js";
 import { rItem, rNode } from "./trace.js";
 
 /** One accepted substitution: query span [qs,qe) stands in for the
@@ -242,10 +247,30 @@ function align(
 
 /** Recall's corroborated-substitution bridge — see the module comment.
  *  Returns the best bridged grounding proposal, or null. */
+/** `proposed` is a THUNK, not a list: the bridge's own cheap gates (the
+ *  two-quantum query floor and the O(|query|) stored-window anchor scan)
+ *  decide whether ANY candidate can be aligned, and they need no proposals
+ *  to do it.  Resolving the caller's proposals eagerly meant recall paid its
+ *  exhaustive whole-index resonance — the most expensive single act on the
+ *  refusal path — for every query, including the ones whose windows the
+ *  store has never seen and which the anchor scan rejects outright.  Same
+ *  investment discipline the mechanism floors follow (AGENTS §2.6): never
+ *  compute a shared analysis just to discard it. */
 export async function substitutionBridge(
   ctx: MindContext,
   query: Uint8Array,
-  proposed: ReadonlyArray<number> = [],
+  proposed: () => Promise<ReadonlyArray<number>> = async () => [],
+): Promise<BridgeHit | null> {
+  const meter = ctx.meter;
+  return meter
+    ? meter.time("substitutionBridge", () => bridgeImpl(ctx, query, proposed))
+    : bridgeImpl(ctx, query, proposed);
+}
+
+async function bridgeImpl(
+  ctx: MindContext,
+  query: Uint8Array,
+  proposed: () => Promise<ReadonlyArray<number>>,
 ): Promise<BridgeHit | null> {
   const W = ctx.space.maxGroup;
   if (query.length < 2 * W) return null;
@@ -254,6 +279,38 @@ export async function substitutionBridge(
   const bar = conceptThreshold(ctx.store.D);
   const reachCap = chainReach(W);
 
+  // PHRASE-SCALE CANDIDATE CAP — the same |content|·W bound the weave
+  // (pipeline-mechanism.ts), the cross-region junction ladder's
+  // `maxInterior`, and structural resonance's `maxSiblingBytes` all apply,
+  // for the same reason and now at the one remaining place that read
+  // candidate contexts WHOLE.
+  //
+  // The bridge accepts a candidate only when the query is DOMINATED by its
+  // matched runs plus substitutions, with at most one window W of slack at
+  // each edge and at most one chain reach (W²) per interior gap — so the
+  // candidate region an accepted alignment can ever consume is bounded by
+  // |query|·W.  Content beyond that cannot participate in any alignment
+  // this function would accept; reading it is pure cost.  And a candidate
+  // an order of magnitude past the query is not a paraphrase of it: it is a
+  // document or a whole conversation that merely quotes a phrase, and
+  // grounding through ITS learnt edge voices that document's continuation,
+  // not a phrase answer.
+  //
+  // Measured on the 17.7M-node / 325K-context store: uncapped, the refusal
+  // path materialised up to ~1 MB of candidate bytes per query (up to √N
+  // proposals plus √N climbed contexts, each read in full), and the frame-
+  // unanimity scan — which walks EVERY collected candidate's bytes, inside
+  // the per-gap expansion loop — paid that volume back tens of times per
+  // substitution.  Recall's run() was 0.7–2.6 s per refusing query.
+  const capBytes = query.length * W;
+  /** A candidate's bytes, phrase-scale capped: null when it exceeds the cap
+   *  (read one byte past it, so "too long" is decided without materialising
+   *  the rest) or has no content. */
+  const candidateBytes = (sid: number): Uint8Array | null => {
+    const b = read(ctx, sid, capBytes + 1);
+    return b.length === 0 || b.length > capBytes ? null : b;
+  };
+
   // 1. The query's stored windows, rarest first (fewest containers — the
   //    most discriminative anchors; hub-clamped like every fan-out read).
   //    The scan doubles as the ONE store probe of every query window: the
@@ -302,6 +359,54 @@ export async function substitutionBridge(
     }
     return false;
   };
+  // ── EXPLAINED SPANS — the scaffolding judgement, corpus-global ──────────
+  //
+  // The question every gap poses is "may the two forms differ HERE without
+  // differing in what they SAY?", and that is the discriminative-vs-
+  // scaffolding question AGENTS §2.7 names, over the CORPUS-GLOBAL
+  // population.  It already has one definition — `dominates(reachOf(...), N)`,
+  // the same gate confluence's filler test uses ("scaffolding never binds").
+  // Nothing new is derived here; the bar is read, not invented.
+  //
+  // A span is explained when EITHER
+  //   • it is sub-quantum (< W) — typographic glue, the tolerance identityBar
+  //     already prices ("below one river window, byte overlap is chance"); or
+  //   • every full W-window inside it is COMMON by the store's own climb:
+  //     the ascent SATURATES (the window sits in more places than √N — the
+  //     climb's own definition of non-discriminative), or it resolves to a
+  //     majority of the corpus's contexts.  "the process of ", " is the ".
+  //
+  // THE READING MATTERS, not just the population (AGENTS §2.7).  This
+  // deliberately does NOT go through `reachOf`, which maps BOTH "saturated"
+  // and "reaches nothing" to Infinity.  For IDF weighting those are the same
+  // thing (no usable identity evidence); for THIS question they are
+  // opposites — a window reaching nothing is novel content, the most
+  // discriminative material there is, and reading it as Infinity would call
+  // it scaffolding.  Measured: with `reachOf`, "Is water wet?" was answered
+  // with "No, heavy water is not wet." — "heav"/"eavy" occur once, reach no
+  // edge-bearing ancestor, and were written off as filler.  So an
+  // empty-rooted window is NEVER explained, and neither is an untrained one
+  // (the same principle attestedQ applies to the query side).
+  const reachMemo = sharedReachMemo(ctx);
+  const explainedSpan = (
+    bytes: Uint8Array,
+    from: number,
+    to: number,
+  ): boolean => {
+    if (to - from < W) return true;
+    for (let o = from; o + W <= to; o++) {
+      const ids = leafIdRun(ctx, bytes, o, o + W);
+      if (ids === null) return false;
+      const wid = ctx.store.findBranch(ids);
+      if (wid === null) return false;
+      const r = edgeAncestors(ctx, wid, N, reachMemo);
+      if (r.saturated) continue; // in too many places to discriminate
+      if (r.roots.length === 0) return false; // reaches nothing: novel content
+      if (!dominates(r.contextsReached, N)) return false;
+    }
+    return true;
+  };
+
   anchors.sort((a, b) => a.rarity - b.rarity);
   // Up to W anchors, at least one window apart — the quantum's own count.
   const picked: typeof anchors = [];
@@ -331,11 +436,13 @@ export async function substitutionBridge(
   // that could align at all: alignment can only seed at a picked anchor
   // window occurring literally in the candidate (measured: unconditional
   // re-folds multiplied the refusal-path latency several-fold).
-  for (const sid of proposed) {
+  // FIRST TOUCH of the caller's proposals — past every gate that could have
+  // refused without them (see substitutionBridge's doc).
+  for (const sid of await proposed()) {
     if (seen.has(sid)) continue;
     seen.add(sid);
-    const tb = ctx.store.bytes(sid);
-    if (tb.length === 0) continue;
+    const tb = candidateBytes(sid);
+    if (tb === null) continue;
     if (
       !picked.some((a) => indexOf(tb, query.subarray(a.off, a.off + W), 0) >= 0)
     ) continue;
@@ -368,8 +475,14 @@ export async function substitutionBridge(
   }
 
   // 3. Align each candidate; gate its mismatches; keep the best.
+  // Over-cap candidates are dropped here rather than earlier: the climb
+  // channel deliberately reads no bytes while collecting (the climb visits
+  // hundreds of roots), so this is where its proposals are first sized.
   const allBytes = new Map<number, Uint8Array>();
-  for (const sid of candidates) allBytes.set(sid, ctx.store.bytes(sid));
+  for (const sid of candidates) {
+    const b = candidateBytes(sid);
+    if (b !== null) allBytes.set(sid, b);
+  }
 
   // FRAME UNANIMITY: a substitution U → C inside the frame (Lf, Rf) is
   // groundable only when the collected candidates — the store's own sample
@@ -428,8 +541,8 @@ export async function substitutionBridge(
   let best: BridgeHit | null = null;
   let bestAccounted = 0;
   for (const sid of candidates) {
-    const cBytes = allBytes.get(sid)!;
-    if (cBytes.length === 0) continue;
+    const cBytes = allBytes.get(sid);
+    if (cBytes === undefined) continue;
     // Seed at the rarest picked anchor that literally occurs in this
     // candidate.
     let seed: { qo: number; co: number } | null = null;
@@ -541,7 +654,7 @@ export async function substitutionBridge(
     // resonance rank but has no outgoing edge to bridge through).  This
     // mechanism exists to explain SUBSTITUTIONS; a query needing none is
     // recall's job, not the bridge's.
-    if (!ok || subs.length === 0) continue;
+    if (!ok) continue;
 
     // Coverage: matched runs plus accepted substitutions must dominate the
     // query, every interior gap already proved ≤ W above, and the EDGES
@@ -565,6 +678,70 @@ export async function substitutionBridge(
     if (spans[0][0] > W || query.length - reachEnd > W) continue;
     if (!dominates(covered, query.length)) continue;
 
+    // ZERO-SUBSTITUTION ADMISSION — an IDENTITY claim, not a substitution.
+    //
+    // A candidate needing no substitution is normally refused (see the trap
+    // above), and that refusal is right for the case it was written for: the
+    // query is a strict byte-PREFIX of several candidates, each of which
+    // continues differently, and nothing here corroborates picking one
+    // continuation over another.  But that trap has a signature — the
+    // candidate carries substantial content BEYOND the alignment, and that
+    // surplus is exactly the "answer" the bridge would be inventing.
+    //
+    // The opposite shape is not ambiguous at all: the alignment explains BOTH
+    // strings end to end, and the only thing between them is sub-quantum glue
+    // — typographic punctuation the fold treats as structure.  Then the two
+    // are the SAME learnt form, and grounding through its edge returns that
+    // form's own trained answer, never a chosen-among-many completion.
+    //
+    // Why the ladder cannot reach these otherwise: the gist is a STRUCTURAL
+    // signature, so a mid-string insertion shifts every fold boundary after
+    // it.  Measured: `Who wrote Romeo and Juliet?` against the trained
+    // `Who wrote "Romeo and Juliet"?` — two inserted quote characters — scores
+    // cos 0.377, BELOW unrelated neighbours like "Who wrote the opera
+    // Carmen??" (0.603).  Recall's identity tiers gate on identityBar (0.969
+    // here) and its reach tiers on 0.875, so no gist-based tier can ever see
+    // it; only byte-exact alignment can, which is what this function does.
+    //
+    // The claim is deliberately strict, in three parts:
+    //
+    //   • QUERY SIDE — EXACT.  Every byte of the query must be a literal
+    //     match against the candidate: covered === query.length, no slack at
+    //     all, not even sub-quantum.  The query is what we are answering, so
+    //     an identity claim about it may write off NOTHING.  This is stricter
+    //     than the ≤ W edge tolerance the substituted path uses, and it has
+    //     to be: with a one-window allowance, `what is 2^10?` matched the
+    //     trained `what is 2+2?` — "^10" against "+2", four bytes, both sides
+    //     below W — and answered "2+2 is 4.", outweighing cover's authoritative
+    //     ALU result.  Below W, byte OVERLAP is chance rather than evidence;
+    //     that never made a below-W DIFFERENCE meaningless, and digits are the
+    //     case that proves it.
+    //   • CANDIDATE SIDE, INTERIOR — each gap must be an EXPLAINED span (see
+    //     explainedSpan): sub-quantum glue, or corpus-global scaffolding.
+    //     This side is asymmetric ON PURPOSE.  Material the CANDIDATE has and
+    //     the query omits is not something the asker asked about: if it is
+    //     scaffolding, dropping it changes nothing ("What is *the process of*
+    //     photosynthesis?"); if it is discriminative, the candidate answers a
+    //     DIFFERENT, narrower question ("Is *heavy* water wet?") and must be
+    //     refused.  Only the corpus can tell those apart, and it does.
+    //   • CANDIDATE SIDE, SURPLUS — its bytes are the matched runs
+    //     (byte-identical to the query's, hence the same total length) plus
+    //     its own gap spans; anything past that is surplus, and surplus is
+    //     the prefix trap.  A prefix-completion candidate fails here by the
+    //     whole length of the completion it wanted to supply — which is why
+    //     admitting scaffolding interiors does not reopen that trap.
+    //
+    // Ordered cheapest-first: the two arithmetic tests run before
+    // explainedSpan, whose per-window `reachOf` climbs are the only costly
+    // part (shared through the response/conversation reach memo, and reached
+    // only by a candidate that already survived every structural gate).
+    if (subs.length === 0) {
+      if (covered !== query.length) continue;
+      const cGap = gaps.reduce((n, g) => n + (g.ce - g.cs), 0);
+      if (cBytes.length - covered - cGap > W) continue;
+      if (!gaps.every((g) => explainedSpan(cBytes, g.cs, g.ce))) continue;
+    }
+
     // KNOWN content may never be dismissed — see dismissedKnownContent
     // (the live case: "what is the capital of france" aligning into a
     // Matrix synopsis by writing off "ance" — a stored window of the

package/src/mind/canonical.ts

@@ -27,7 +27,12 @@ import type { MindContext } from "./types.js";
 
 /** The two sliding-window lengths the WRITE side interns over a stream's leaf
  *  ids: W−1 and W (the river's grouping quantum and its off-by-one neighbour,
- *  so a form straddling a group boundary is reachable from either cut). */
+ *  so a form straddling a group boundary is reachable from either cut).
+ *
+ *  Widening this to cover the reader's full segment scale (W−1..2W) was
+ *  measured and REFUTED: it tripled the store (3,160 → 8,980 nodes on a
+ *  200-pair corpus), slowed ingest 80%, and fixed not one test.  Unknown
+ *  regions are not caused by the index's scale. */
 export function canonicalWindows(W: number): [number, number] {
   return [W - 1, W];
 }

package/src/mind/graph-search.ts

@@ -350,6 +350,18 @@ export class GraphSearch {
     private readonly host: GraphSearchHost,
   ) {}
 
+  /** The hub bound √N (AGENTS §2.8) — the ONE fan-out cap, stated here
+   *  rather than imported from `traverse.ts` because this module is
+   *  deliberately host-based (it holds a bare Store, never a MindContext).
+   *  That is the same write/read-side duplication convention canonical.ts's
+   *  header documents: if the formula changes it must change in BOTH places.
+   *  It is stated ONCE per side, though — the expression used to be spelled
+   *  out at three call sites here, one of them inside a per-item rules
+   *  generator, and they had already drifted on the `Math.max(2, …)` floor. */
+  private hubBound(): number {
+    return Math.ceil(Math.sqrt(Math.max(2, this.store.edgeSourceCount())));
+  }
+
   /** Explore the Sema graph for the lightest cover of the query and return its
    *  chosen spans left-to-right — WITH the derivation's total weight (the g
    *  value of the goal item, in the exported cost ladder), which think's
@@ -442,7 +454,17 @@ export class GraphSearch {
       connectors,
       computedResults,
     );
-    const derivation = lightestDerivation(system);
+    // Search-effort accounting (src/meter.ts): the chart's pops/pushes are
+    // the cover's real cost, and a heuristic that stops being admissible
+    // shows up as a pop count that explodes while the answer stays the same.
+    const meter = this.host.meter;
+    const stats = meter ? { pops: 0, pushes: 0 } : undefined;
+    const derivation = lightestDerivation(system, stats);
+    if (meter && stats) {
+      meter.searches++;
+      meter.searchPops += stats.pops;
+      meter.searchPushes += stats.pushes;
+    }
     // When covering under a substitution map (articulation), a form→out rule is
     // the form EMITTING the asker's voice, not grounding to its own answer — so
     // tell the reader to name those moves `voice` rather than `ground`.
@@ -475,15 +497,12 @@ export class GraphSearch {
   ): DeductionSystem<GItem> {
     const W = this.maxGroup; // fusible span ceiling (shortest composite bound)
     // Same corpus-scale hub floor {@link atomIsHub}/{@link atomReach} (traverse.ts)
-    // derive for byte atoms — duplicated here rather than imported because this
-    // module is deliberately host-based (no MindContext), and both inputs
-    // (maxGroup, edgeSourceCount) are already in scope with no ctx needed.  If
-    // the formula ever changes, it must change in BOTH places (see canonical.ts's
-    // header for the same write/read-side duplication convention).
+    // derive for byte atoms — see {@link hubBound} below for why this module
+    // states the formula itself instead of importing it.
     const atomsAreHubs = Math.max(
       1,
       Math.ceil((this.store.edgeSourceCount() * W) / 256),
-    ) > Math.ceil(Math.sqrt(Math.max(2, this.store.edgeSourceCount())));
+    ) > this.hubBound();
     const nodeBytes = (n: number) => this.store.bytesPrefix(n, ALL);
     // Content-addressed probes over the store's hash-cons maps — the same keys
     // training filled.  No byte-by-byte trie walk.
@@ -753,10 +772,7 @@ export class GraphSearch {
       // guard then dead-ends it) with no way to reach the forward edge.
       // Forking offers every continuation as its own rule so the one that
       // genuinely advances (not a duplicate) is still reachable.
-      const bound = Math.ceil(
-        Math.sqrt(Math.max(2, this.store.edgeSourceCount())),
-      );
-      const nx = this.store.nextFirst(it.node, bound);
+      const nx = this.store.nextFirst(it.node, this.hubBound());
       if (nx.length) {
         // The SAME evidence-weighted disambiguation the first hop uses
         // (below) identifies the most-corroborated continuation.  Yielding
@@ -1142,16 +1158,39 @@ export class GraphSearch {
     // is opportunistic cross-leaf recovery exactly like recognition.ts's own
     // canonical chain — findLeaf/findBranch here have no idea WHY these two
     // leaves are adjacent, only that their concatenation happens to spell a
-    // trained form ("hi" recovered from "W[hi]ch").  The same corpus-scale
-    // caution recognition.ts's `boundary` gate applies: trust it fully when
-    // `l.i` is a position the query's OWN fold chose as a boundary (real
-    // structural evidence); past the scale where atoms themselves stop
-    // discriminating, an interior offset's opportunistic match is noise, not
-    // a genuine cross-leaf recovery.  A completion-involved fuse (l.rec ||
-    // r.rec) is a different, legitimate case — a rewrite growing into its
-    // neighbour — and is exempt, same as recognition.ts's rec-derived sites.
-    const trusted = l.rec || r.rec || ctx.starts.has(l.i) ||
-      !ctx.atomsAreHubs;
+    // trained form ("hi" recovered from "W[hi]ch").  At hub scale, where
+    // atoms themselves no longer discriminate, that coincidence is noise.
+    //
+    // A FOLD BOUNDARY IS NOT EVIDENCE.  This gate used to exempt any fuse
+    // starting at `starts.has(l.i)` — documented as "a position the query's
+    // OWN fold chose as a boundary (real structural evidence)".  The plain
+    // river fold CHOOSES NOTHING: `riverFold` groups fixed-arity
+    // (`for (i = 0; i < complete; i += mg)`), so `starts` is exactly
+    // {0, W, 2W, 3W, …} for every query.  Measured on three unrelated
+    // queries: starts = 0,4,8,12,16,20,24,28[,32] in every case — the set
+    // carries ZERO content information, and the exemption therefore fired at
+    // a quarter of all offsets by arithmetic alone.
+    //
+    // What it cost (17.9M-node store, W=4): "In which country is the Eiffel
+    // Tower?" fused the atoms "h"+"i" at offset 4 — trusted only because
+    // 4 ≡ 0 (mod 4) — into the trained form "hi", followed its continuation
+    // edge, and grounded "Hello there. If you are looking for Open
+    // Assistant, look no further." as a FACT, explaining 2 of 37 bytes
+    // (density 0.054, a fifth of the 1/W honesty bar `thinGrounding`
+    // reports and does not enforce).
+    //
+    // So the exemption is removed rather than replaced: there is no cheap
+    // signal here that means what it claimed to mean, and inventing one
+    // would be worse than admitting the absence. Genuine cross-leaf forms
+    // are not lost — recognition.ts's canonical pass already probes EVERY
+    // byte offset for the write side's interned windows and emits them as
+    // sites, which arrive here as `l.rec`/`r.rec` and stay exempt. What
+    // remains excluded at hub scale is precisely the case with no evidence
+    // behind it: two byte atoms that happen to spell something.
+    //
+    // Below hub scale nothing changes (`!atomsAreHubs`): on a small store
+    // coincidence is rare and every chain is real evidence.
+    const trusted = l.rec || r.rec || !ctx.atomsAreHubs;
     let node = (trusted && bytes.length <= ctx.W)
       ? ctx.findLeafU(bytes)
       : undefined;

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/junction.ts

@@ -186,6 +186,16 @@ function cachedContainers(
  *     few levels of its parts).  A side too common to decide within the
  *     budget abstains here and falls through to the resonance tier (the
  *     climb's own saturation semantics).
+ *
+ *     REFUTED TIGHTENING (measured, 325K contexts): giving this walk
+ *     edgeAncestors' cumulative LATERAL-CONE limit — abstain once the
+ *     accumulated lateral entries pass √N — would cut most of the pops (47
+ *     of 56 walks exceed √N lateral, and 47 exhaust the budget), but TWO OF
+ *     THE FOUR walks that actually found a container had lateral spread of
+ *     1425 and 1426, far past √N.  The cone limit is sound for
+ *     edgeAncestors' question and wrong for this one: a junction container
+ *     is legitimately reached across many containing structures.  Half the
+ *     successful junctions would be lost.
  *   • per-node hub guards — parent fan-outs beyond √N are hubs (not
  *     expanded); each node contributes at most one √N page of containers;
  *     √N collected candidates decide. */
@@ -215,6 +225,7 @@ export function junctionContainersFrom(
   if (seeds.length === 0) return [];
 
   const b = budget ?? { n: bound * ctx.space.maxGroup };
+  if (ctx.meter) ctx.meter.junctionWalks++;
   // DEPTH CAP: perception trees are W-ary and a junction container is
   // phrase-scale, so it sits within ~log_W(maxContainer) structural levels
   // of its parts — at most W levels for any practical W (plus the
@@ -231,6 +242,7 @@ export function junctionContainersFrom(
   }));
   while (stack.length > 0 && out.length < bound && b.n-- > 0) {
     const { id: x, d } = stack.pop()!;
+    if (ctx.meter) ctx.meter.junctionPops++;
     const f = cachedRead(ctx, cache, x, maxContainer);
     if (f.length > maxContainer) continue; // beyond phrase scale: prune branch
     if (unordered) {

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,
+      });
+    },
   );
 }