@effectstream/sync 0.100.22 → 0.100.23

package/CLAUDE.md

@@ -35,7 +35,7 @@ config (syncProtocols.main + syncProtocols.parallel)
 │  PER-CHAIN FETCH LOOPS              one spawn per protocol             │
 │  startSync(state):  stateToInput → readData → updateState             │
 │    → push Output to bufferedData (Deque)  + wake newData/newPageCondVar│
-│    → upsertPage(page_number = chunk_end) into sync_protocol_pagination │
+│    → lastPage kept IN-MEMORY only (no DB write; runtime owns resume)   │
 │    → producerChannel.send(...)  ← NOTE: nothing consumes this today    │
 └────────────────────────────────────────┬─────────────────────────────┘
                                           ▼
@@ -47,8 +47,9 @@ config (syncProtocols.main + syncProtocols.parallel)
 └────────────────────────────────────────┬─────────────────────────────┘
                                           ▼
    runtime/src/main.ts:  for (block of each(finalizedBlockStream))
-     acquire DB mutex → processFinalizedBlock (STF) → COMMIT
-     → removePages(< merged block) → fire-and-forget MQTT events → each.next()
+     acquire DB mutex → processFinalizedBlock (STF)
+     → upsertPage(block.resumePages) + removePages(< committed) [in txn] → COMMIT
+     → fire-and-forget MQTT events → each.next()
 ```
 
 ## The three per-chain abstractions (`src/sync-protocols/<chain>/`)
@@ -112,12 +113,34 @@ iteration it walks protocols in order:
    a parallel chain's timestamp so older blocks merge into more-recent root slots.
 4. **Mutate-after-commit.** `OutputAndCleanup` keeps data in the Deque until the block is
    safely produced; the consumer commits to Postgres *before* emitting events.
-5. **Durable, resumable page queue.** `effectstream.sync_protocol_pagination` is keyed
-   `(protocol_name, page_number)`. Fetch appends a row per chunk (`upsertPage`,
-   `page_number = chunk_end`); on commit the consumer deletes consumed chunks
-   (`removePages(page_number < merged_block)`, `runtime/process-blocks.ts:328`); on boot
-   `restoreState` resumes from `getPage` = `ORDER BY page_number ASC LIMIT 1` (oldest
-   remaining chunk).
+5. **Durable, block-accurate resume queue.** *(Single source of truth for how restart/resume
+   works — code comments point here; see also Finding #2 for the bug this fixes.)*
+
+   `effectstream.sync_protocol_pagination` is keyed `(protocol_name, page_number)` and the
+   **runtime is the sole writer** of the resume position (Fix D). End to end:
+   - **Fetch loop** (`base/state.ts:updateState`) keeps `lastPage` in memory only — it does
+     **not** persist (it runs ahead of commits, so its chunk-end page is not a safe resume
+     point).
+   - **Merge** (`orchestration/merge.ts`) tags every `ChainBlock` with `resumePages`: one
+     marker per protocol = `outputToLastPage(lastConsumed)`, the `LastPage`
+     (`{ own, ownBlockNumber, root }`) of the **highest datum merged into the block**. Each
+     protocol implements `outputToLastPage` (`base/state.ts` + per-chain `state.ts`) because
+     `own` is a structured page for object-paged chains and can't be rebuilt from the block
+     number. Pending data above the committed timestamp is **not** marked, so it is always
+     re-fetched, never skipped.
+   - **Commit** (`runtime/process-blocks.ts`, STEP 7) writes each marker **inside the block's
+     transaction**: `upsertPage(page_number = ownBlockNumber)` then
+     `removePages(page_number < ownBlockNumber)` — leaving exactly one row per protocol = the
+     committed watermark, atomic with the block.
+   - **Boot** (`restoreState`) reads `getPage` = `ORDER BY page_number ASC LIMIT 1` and
+     resumes from `nextInterval(own).from` = the next uncommitted block.
+
+   **Re-scan on restart is bounded by `stepSize`, not a chain's whole quiet tail.** Every
+   fetched chunk's boundary page (`data.to`) is buffered and consumed even when empty, so the
+   marker advances to within one `stepSize` of the committed frontier — and reaches the
+   fetched tip exactly at full catch-up. So a long-quiet chain re-fetches at most ~`stepSize`
+   blocks after a restart, regardless of how long ago its last data was. Trade-off:
+   `getSyncAndLastPage` now reports `synced_page == fetched_page`.
 
 ---
 
@@ -144,26 +167,42 @@ Consequences during catch-up:
   (`mergeIntoRoot`, `merge.ts`), so a slow/stalled chain stalls all block production while
   the others keep ballooning (head-of-line blocking).
 
-→ Fix: **(C) backpressure** — cap `bufferedData` and pause the fetch loop until the merge drains.
-
-### 2. Silent data gap on restart (correctness)
-
-The page queue is **chunk-granular** but commits are **single-block-granular**:
-- fetch persists `upsertPage(page_number = chunk_end)` (`base/state.ts:132`; `own = ownBlockNumber = Number(data.to)`),
-- commit deletes `removePages(page_number < merged_block_N)` (`process-blocks.ts:328`),
-- restart resumes from `getPage` = oldest remaining chunk, at `nextInterval(own).from = chunk_end + 1`.
-
-During catch-up chunks are full `stepSize`, so at restart the committed watermark `N` sits
-**inside** the oldest retained chunk `[start, end]` (`start ≤ N < end ⇒ end ≥ N ⇒ not deleted`).
-Resume jumps to `end + 1`, **silently skipping source blocks `(N, end]`** (up to
-`stepSize - 1`). The in-memory Deque held them; they're gone on restart; the effectstream
-height continues seamlessly with **missing primitives → divergent app state**. There is
-**no error** and **no restart/resume test** (the only tests in `test/examples.test.ts` are
-export smoke-checks). The existing `getSyncAndLastPage` `synced_page` (`MIN(page_number)`)
-is itself chunk-granular and does not reflect the true committed block.
-
-→ Fix: **(D) block-accurate resume** — persist the committed per-protocol watermark and
-resume from `watermark + 1`, reconciling stale fetched-ahead page rows.
+→ Fix: **(C) backpressure** — ✅ SHIPPED. `bufferAtCap` (`common/page-helpers.ts`) caps
+`bufferedData` and pauses the fetch loop (each chain's `stateToInput` returns `undefined`)
+until the merge drains. See README "Backpressure (`maxBufferedPages`)".
+
+> **Merge→apply queue cap (Fix C′) — ✅ SHIPPED.** The Deque cap above bounds *fetch*, but the
+> merge then sends finalized blocks into an effection channel whose subscriber queue buffers
+> unbounded — so the merge (no I/O) could still race ahead of the serial apply loop and grow that
+> queue toward the whole backlog, especially with empty-block coalescing (Fix E) removing the
+> per-block apply brake. The runtime now gates the merge's `send` (`runtime/src/main.ts`): it blocks
+> once `EFFECTSTREAM_FINALIZED_STREAM_CAP` (default 2048) produced blocks are unconsumed, and the
+> apply loop wakes it as it drains. `inFlight = produced − consumed` is surfaced on
+> `/debug/metrics`. Repro/guard: `runtime/test/reproduction/coalesce-memory.test.ts`.
+
+> **Merge-demand exemption (safeguard).** A naive cap can deadlock the merge: it drains a
+> parallel chain's buffer only *after* its page passes the root timestamp `τ`, so if the cap
+> pauses the fetcher while its page is still `≤ τ` (a far skip-ahead, or a chain finer-grained
+> than the cap), merge waits for the page ↔ the page waits for a fetch ↔ the fetch waits for
+> the buffer to drain — circular. Guard: `mergeIntoRoot` sets `SyncState.mergeWaitingForPage`
+> while blocked on a chain's page, and `bufferAtCap` returns `false` for that chain while the
+> flag is set — so the fetcher advances past `τ`. Bounded by necessity: only
+> `(lastPage.root, τ]` is buffered above the cap. Repros: `buffering.test.ts` 1c/1d.
+
+### 2. Silent data gap on restart (correctness) — ✅ FIXED (D)
+
+**The bug (historical).** The page queue was **chunk-granular** but commits are
+**single-block-granular**: the fetch loop persisted `upsertPage(page_number = chunk_end)`,
+commit deleted `removePages(page_number < merged_block_N)`, and restart resumed from
+`getPage` = oldest remaining chunk at `nextInterval(own).from = chunk_end + 1`. During
+catch-up chunks are full `stepSize`, so the committed watermark `N` sat **inside** the
+oldest retained chunk `[start, end]` (`end ≥ N ⇒ not deleted`); resume jumped to `end + 1`,
+**silently skipping `(N, end]`** → missing primitives → divergent app state, with no error.
+
+**The fix (D) — block-accurate resume, runtime is the sole writer.** The runtime persists a
+block-accurate marker per protocol on commit instead of the fetch loop persisting chunk-end
+pages. Full mechanism in **design idea #5** above. Regression test: the
+`consistency.test.ts` "mid-chunk restart" case (Postgres-only).
 
 ### 3. Serial replay is the catch-up bottleneck
 
@@ -182,6 +221,8 @@ block-hash chain.
 > survives a restart. See `docs/ADDING-A-SYNC-PROTOCOL.md` for how to add a chain
 > (with `test` as the worked example).
 >
-> Deterministic reproductions of #1/#2/#3 and their fixes land in **follow-up
-> PRs**, each test alongside its fix: #1 → fetch backpressure; #2 →
-> block-accurate resume; #3 → opt-in empty-block commit batching during catch-up.
+> Deterministic reproductions of #1/#2/#3 and their fixes land alongside each fix:
+> **#2 → block-accurate resume is DONE** (`consistency.test.ts`); **#1 → fetch
+> backpressure is DONE** (`buffering.test.ts`, incl. 1c/1d for the merge-demand
+> exemption). Still in follow-up PRs: #3 → opt-in empty-block commit batching during
+> catch-up.

package/README.md

@@ -46,6 +46,68 @@ const protocols = await genSyncProtocols(config);
 // protocols.parallelEvmRPC_fast.runOne()  // poll one block
 ```
 
+## Backpressure (`maxBufferedPages`)
+
+During deep catch-up a chain's fetch loop races to its tip far faster than the
+merge can drain (the merge applies one block per DB transaction). Without a bound
+the in-memory buffer (`SyncState.bufferedData`) grows toward the **entire backlog**
+— hundreds of thousands of block objects — which is an OOM risk.
+
+**The cap.** Every chain's `stateToInput` calls `bufferAtCap(state, syncProtocol)`
+first (`sync-protocols/common/page-helpers.ts`): when
+`bufferedData.size() >= maxBufferedPages` it returns `undefined`, so the chain stops
+fetching — exactly as if it had caught up to the tip — and the polling loop sleeps
+`pollingInterval` and retries. The merge keeps draining the buffer; once it drops
+below the cap the next poll resumes. Peak in-memory buffering is therefore bounded
+to **≈ `maxBufferedPages + stepSize`** per chain (one in-flight chunk can overshoot
+the cap), instead of the whole backlog.
+
+**Config.** `maxBufferedPages` is an optional field on every sync-protocol config
+(declared once on the shared `PollingSyncProtocol` schema). When unset it defaults to
+**`4 × stepSize`** (the `MAX_BUFFER_MULTIPLE` constant in `page-helpers.ts`), always
+clamped to **`≥ stepSize + 1`** so a chain can always fetch at least one chunk to feed
+the merge. ~4 chunks of look-ahead never starves the merge while keeping memory
+bounded; raise it to trade memory for more fetch look-ahead. The cap only bites during
+catch-up — in steady state the buffer sits near zero and the cap is never reached.
+
+**Deadlock-safety (merge-demand exemption).** A naive cap can deadlock the merge: it
+produces a root block at timestamp `τ` only once a parallel chain's page passes `τ`, and
+drains that chain's buffer only *after* the page passes `τ`. If the cap pauses the
+fetcher while its page is still `≤ τ` (the data up to `τ` exceeds the cap — e.g. a far
+skip-ahead or a parallel chain finer-grained than the cap), neither side can proceed: a
+circular wait, not a lost wakeup.
+
+The safeguard is a **merge-demand exemption**: while the merge is blocked on a chain's
+page (`mergeIntoRoot` sets `SyncState.mergeWaitingForPage`), `bufferAtCap` returns
+`false` for that chain so the fetcher advances until its page crosses `τ`. Memory stays
+**bounded by necessity** — only `(lastPage.root, τ]` is buffered above the cap, exactly
+what the merge must hold to build block `τ`; once the page passes `τ` the normal cap
+re-engages. A chain that is merely tip-limited (caught up, not gated by the merge) is
+*not* exempted, so steady-state and head-of-line bounds are unaffected. Reproductions:
+`buffering.test.ts` 1c (skip-ahead) and 1d (density).
+
+**Scope.** The guard runs in **every** chain's `stateToInput`, so all sync chains are
+covered: EVM, NTP, Bitcoin, Avail, Celestia, NEAR, Midnight, Cardano (UTXO-RPC), and
+the synthetic `test` chain. Two notes:
+- **Cardano (UTXO-RPC)** has no `stepSize` (it streams one block per pass), so the cap
+  falls back to a default chunk size of 1000 (⇒ default cap 4000); set `maxBufferedPages`
+  explicitly to tune it.
+- The cap bounds `SyncState.bufferedData` (the merge-facing Deque the backpressure
+  feature protects). The UTXO-RPC fetcher additionally keeps its own internal FollowTip stream
+  buffer; pausing `stateToInput` stops draining it into `bufferedData`, but bounding
+  that lower-level stream is a separate, fetcher-specific concern.
+
+**Observability.** Each `SyncState` tracks, and the runtime's `/debug/metrics`
+endpoint reports per protocol: `cap` (resolved `maxBufferedPages`), `buf` (current
+size), `bufHighWater` (peak since boot — catches spikes between samples), `pausedNow`,
+`pauses` (rising-edge count — **the "backpressure engaged" signal**), `pausedMs`
+(total time paused), and `mergeWaiting`/`mergeDemandRoot` (merge-demand exemption:
+`mergeWaiting=true` means the merge is gated on this chain's page and the cap is lifted).
+`pauses > 0` means the cap actively bounded memory; `0` means it
+was never needed in that run. Steady-state these sit at `0`; during a real deep
+catch-up (or under the perf harness's `PERF_APPLY_DELAY_MS` drain throttle) they climb
+as `buf` pins to `cap`.
+
 ## Key exports
 
 - `genSyncProtocols(dbConn, syncInfo)` - Effection generator that instantiates a runtime fetcher + state pair for every protocol in `syncInfo` (from `config.syncProtocols`). Called from the runtime's process-blocks loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/sync",
-  "version": "0.100.22",
+  "version": "0.100.23",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,10 +13,10 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/config": "0.100.22",
-    "@effectstream/db": "0.100.22",
-    "@effectstream/log": "0.100.22",
-    "@effectstream/utils": "0.100.22",
+    "@effectstream/config": "0.100.23",
+    "@effectstream/db": "0.100.23",
+    "@effectstream/log": "0.100.23",
+    "@effectstream/utils": "0.100.23",
     "@midnight-ntwrk/ledger-v8": "8.0.3",
     "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.0.4",
     "@midnight-ntwrk/onchain-runtime": "npm:@midnight-ntwrk/onchain-runtime-v3@3.0.0",

package/src/sync-protocols/avail/state.ts

@@ -10,6 +10,7 @@ import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/c
 import { getPage } from "@effectstream/db";
 import { AvailClient } from "./AvailClient.ts";
 import { applyDelay } from "../common/utils.ts";
+import { bufferAtCap } from "../common/page-helpers.ts";
 
 export class AvailSyncState extends SyncState<
   Input,
@@ -63,6 +64,7 @@ export class AvailSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     const latestHeight = yield* call(() => this.client.getLatestBlockHeight());
     const startHeight = this.lastPage?.own.height ??
       this.config.syncProtocol.startBlockHeight - 1;
@@ -99,6 +101,15 @@ export class AvailSyncState extends SyncState<
     rootOutput.primitives.push(...primitives);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    return {
+      own: { height: data.raw.number, hash: data.raw.hash },
+      ownBlockNumber: data.raw.number,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/base/state.ts

@@ -1,4 +1,4 @@
-import { type Operation, until } from "effection";
+import { type Operation } from "effection";
 import Deque from "denque";
 import {
   type BlockNumber,
@@ -11,7 +11,6 @@ import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
 import type { BaseDataFetcher, DataFetched } from "./fetcher.ts";
 import type { PageRelation } from "./page.ts";
 import type { PoolClient } from "pg";
-import { acquireDBMutex, releaseDBMutex, upsertPage } from "@effectstream/db";
 
 export type LastPage<Page, RootPage> = {
   own: Page;
@@ -75,6 +74,32 @@ export abstract class SyncState<
   /** Timestamp of the most recent error, or 0 if no error has occurred. */
   public lastErrorTimestamp: number = 0;
 
+  // ── Backpressure observability (see common/page-helpers.ts + README) ──
+  /** Resolved fetch cap (`maxBufferedPages`); set on each backpressure check, 0 until the first. */
+  public bufferCap: number = 0;
+  /** Peak `bufferedData.size()` seen since boot — catches spikes the periodic sampler misses. */
+  public bufferHighWater: number = 0;
+  /** Whether fetching is currently paused because the buffer is at/over the cap. */
+  public pausedNow: boolean = false;
+  /** How many times the cap engaged (rising edges) — the "backpressure fired" counter. */
+  public backpressurePauses: number = 0;
+  /** Total time fetching has been paused by the cap, in ms. */
+  public backpressurePausedMs: number = 0;
+  /** Start of the current pause, for accumulating `backpressurePausedMs`. */
+  private pauseStartMs: number = 0;
+
+  // ── Merge-demand exemption (see common/page-helpers.ts + README) ──
+  /**
+   * True while the merge is blocked waiting for THIS chain's page to pass the
+   * current root timestamp. The cap must not pause the fetcher here: the merge
+   * drains this chain's buffer only after its page passes the target, so pausing
+   * would be a circular wait. While exempt the fetcher buffers only the data the
+   * merge must hold to build that block anyway (bounded by necessity).
+   */
+  public mergeWaitingForPage: boolean = false;
+  /** Root page (ms timestamp) the merge is waiting to exceed — observability only. */
+  public mergeDemandRoot: RootPage | undefined = undefined;
+
   constructor(
     public readonly name: string,
     lastPage: undefined | LastPage<Page, RootPage>,
@@ -106,6 +131,24 @@ export abstract class SyncState<
    */
   abstract mergeDatum(ourOutput: Output, rootOutput: RootOutput): void;
 
+  recordBackpressure(atCap: boolean, cap: number): void {
+    this.bufferCap = cap;
+    const now = Date.now();
+    if (atCap && !this.pausedNow) {
+      this.pausedNow = true;
+      this.pauseStartMs = now;
+      this.backpressurePauses += 1;
+    } else if (!atCap && this.pausedNow) {
+      this.pausedNow = false;
+      this.backpressurePausedMs += now - this.pauseStartMs;
+    }
+  }
+  /**
+   * Build the resume marker for a single output: the {@link LastPage} to resume
+   * fetching *after* it. See CLAUDE.md design idea #5 (restart/resume).
+   */
+  abstract outputToLastPage(data: Output): LastPage<Page, RootPage>;
+
   @bound
   *updateState(
     _input: Input,
@@ -115,6 +158,8 @@ export abstract class SyncState<
       for (const datum of data.output) {
         this.bufferedData.push(datum);
       }
+      // Peak right after a push — the local max before the merge drains it.
+      this.bufferHighWater = Math.max(this.bufferHighWater, this.bufferedData.size());
       this.newDataCondVar.wake();
     }
 
@@ -129,13 +174,8 @@ export abstract class SyncState<
           ),
       );
 
-      yield* acquireDBMutex(`update-state-${this.name}`);
-      yield* until(upsertPage.run({
-        protocol_name: this.name,
-        page_number: data.lastPage.ownBlockNumber,
-        page: JSON.stringify(data.lastPage),
-      }, this.dbConn as any)); // Client,
-      releaseDBMutex(`update-state-${this.name}`);
+      // lastPage is in-memory only; the runtime is the sole writer of the
+      // persisted resume marker (see CLAUDE.md design idea #5).
       this.lastPage = data.lastPage;
       this.newPageCondVar.wake();
     }

package/src/sync-protocols/bitcoin/state.ts

@@ -16,7 +16,7 @@ import {
   type Output,
   type Page,
 } from "./types.ts";
-import { genInputRange } from "../common/page-helpers.ts";
+import { bufferAtCap, genInputRange } from "../common/page-helpers.ts";
 import type {
   ConfigNetworkType,
   SyncProtocolWithNetwork,
@@ -58,6 +58,7 @@ export class BitcoinSyncState extends SyncState<
         block_number: Number(data.raw.height),
         blockHash: hash,
       })),
+      resumePages: [],
       primitives: data.primitives.map((primitive) => ({
         ...primitive,
         source: this.config.syncProtocol.name,
@@ -75,6 +76,7 @@ export class BitcoinSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     return yield* genInputRange(
       this as BitcoinSyncState,
       this.config.syncProtocol.startBlockHeight as Page,
@@ -112,6 +114,16 @@ export class BitcoinSyncState extends SyncState<
     rootOutput.blockInfo.push(...blockInfo);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    const block = Number(data.raw.height);
+    return {
+      own: block,
+      ownBlockNumber: block,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/celestia/state.ts

@@ -10,6 +10,7 @@ import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/c
 import { getPage } from "@effectstream/db";
 import { CelestiaClient } from "./CelestiaClient.ts";
 import { applyDelay } from "../common/utils.ts";
+import { bufferAtCap } from "../common/page-helpers.ts";
 
 export class CelestiaSyncState extends SyncState<
   Input,
@@ -61,6 +62,7 @@ export class CelestiaSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     const latestHeight = yield* call(() =>
       this.client.getLatestBlockHeight()
     );
@@ -99,6 +101,15 @@ export class CelestiaSyncState extends SyncState<
     rootOutput.primitives.push(...primitives);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    return {
+      own: { height: data.height, hash: data.hash },
+      ownBlockNumber: data.height,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/common/page-helpers.ts

@@ -5,6 +5,47 @@ import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
 import type { PaginatedSyncProtocols } from "../types.ts";
 import type { PageTypeOf } from "../base/state.ts";
 
+// Fetch backpressure. See README "Backpressure (`maxBufferedPages`)".
+const MAX_BUFFER_MULTIPLE = 4;
+// Fallback chunk size for chains that fetch without an explicit stepSize
+// (e.g. utxorpc streams one block per pass).
+const DEFAULT_STEP_SIZE = 1000;
+
+/** Resolved fetch-backpressure cap for a chain. See README "Backpressure". */
+export function bufferCapFor(
+  syncProtocol: { maxBufferedPages?: number; stepSize?: number },
+): number {
+  const step = syncProtocol.stepSize ?? DEFAULT_STEP_SIZE;
+  return Math.max(
+    syncProtocol.maxBufferedPages ?? MAX_BUFFER_MULTIPLE * step,
+    step + 1,
+  );
+}
+
+/**
+ * Whether a chain should pause fetching because its in-memory buffer is at/over
+ * the cap. Each chain's `stateToInput` calls this first and returns `undefined`
+ * when true, so the fetch loop sleeps + retries while the merge drains. Also
+ * records backpressure metrics on `state` (for `/debug/metrics`).
+ * See README "Backpressure (`maxBufferedPages`)".
+ */
+export function bufferAtCap(
+  state: {
+    bufferedData: { size(): number };
+    recordBackpressure(atCap: boolean, cap: number): void;
+    mergeWaitingForPage: boolean;
+  },
+  syncProtocol: { maxBufferedPages?: number; stepSize?: number },
+): boolean {
+  const cap = bufferCapFor(syncProtocol);
+  // Exempt this chain from the cap while the merge is blocked on its page (pausing
+  // there would deadlock — see SyncState.mergeWaitingForPage). Reporting
+  // atCap=false while exempt is correct: the chain is genuinely not paused.
+  const atCap = !state.mergeWaitingForPage && state.bufferedData.size() >= cap;
+  state.recordBackpressure(atCap, cap);
+  return atCap;
+}
+
 type ConfigSubset<Page> = {
   name: string;
   /**

package/src/sync-protocols/common/root.ts

@@ -5,6 +5,7 @@ import type {
   TimestampMs,
 } from "@effectstream/utils";
 import type { PageRelation } from "../base/page.ts";
+import type { LastPage } from "../base/state.ts";
 import type {
   ConfigSyncProtocolType,
   FlattenSyncProtocolIOFor,
@@ -19,6 +20,14 @@ export type ChainBlock = {
     block_number: BlockNumber;
     blockHash: BlockHash;
   }[];
+  /**
+   * Per-protocol block-accurate resume markers the runtime persists on commit.
+   * See `@effectstream/sync` CLAUDE.md, design idea #5 (restart/resume).
+   */
+  resumePages: {
+    protocol_name: string;
+    lastPage: LastPage<unknown, unknown>;
+  }[];
   primitives: (
     & FlattenSyncProtocolIOFor<
       ConfigSyncProtocolType

package/src/sync-protocols/evm/state.ts

@@ -7,7 +7,7 @@ import { bound, type EvmBlockNumber } from "@effectstream/utils";
 import { type LastPage, SyncState } from "../base/state.ts";
 import type { RootOutput, RootPage } from "../types.ts";
 import type { EvmFetcher } from "./fetcher.ts";
-import { genInputRange } from "../common/page-helpers.ts";
+import { bufferAtCap, genInputRange } from "../common/page-helpers.ts";
 import type { Input, Output, Page } from "./types.ts";
 import { toMsTimestamp } from "./types.ts";
 import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/config";
@@ -53,6 +53,7 @@ export class EvmSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     return yield* genInputRange(
       this as EvmSyncState,
       this.config.syncProtocol.startBlockHeight as EvmBlockNumber,
@@ -90,6 +91,16 @@ export class EvmSyncState extends SyncState<
     rootOutput.blockInfo.push(...blockInfo);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    const block = Number(data.raw.number);
+    return {
+      own: block,
+      ownBlockNumber: block,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/midnight/MidnightClient.ts

@@ -40,6 +40,14 @@ export interface MidnightGqlBlockState {
       // Present only on RegularTransaction (selected via inline fragment): the
       // coin-commitment Merkle tree root after this transaction.
       zswapMerkleTreeRoot?: string;
+      // Selected only for MidnightTokenMintPrimitive: the serialized
+      // transaction bytes (Transaction interface) and the apply result
+      // (RegularTransaction only — absent on system transactions).
+      raw?: string;
+      transactionResult?: {
+        status: "SUCCESS" | "PARTIAL_SUCCESS" | "FAILURE";
+        segments?: { id: number; success: boolean }[] | null;
+      };
     }[];
   };
 };
@@ -55,6 +63,8 @@ export interface BlockFetchOptions {
   unshieldedCreatedOutputs?: boolean;
   /** Include `... on RegularTransaction { zswapMerkleTreeRoot }` (needed for MidnightZswapRootPrimitive). Default: false */
   zswapRoots?: boolean;
+  /** Include tx `raw` + `... on RegularTransaction { transactionResult }` (needed for MidnightTokenMintPrimitive). Default: false */
+  tokenMints?: boolean;
 }
 
 type PublicDataProvider = ReturnType<typeof indexerPublicDataProvider>;
@@ -182,6 +192,7 @@ export class MidnightClient {
       unshieldedSpentOutputs = false,
       unshieldedCreatedOutputs = false,
       zswapRoots = false,
+      tokenMints = false,
     } = options;
     const contractActionsField = contractActions
       ? `contractActions { address state }`
@@ -200,6 +211,14 @@ export class MidnightClient {
     const zswapRootFragment = zswapRoots
       ? `... on RegularTransaction { zswapMerkleTreeRoot }`
       : "";
+    // `raw` is on the Transaction interface; `transactionResult` is
+    // RegularTransaction-only (system transactions have neither result nor
+    // contract calls, so they are skipped downstream). Duplicate inline
+    // fragments merge legally in GraphQL.
+    const tokenMintFields = tokenMints
+      ? `raw
+         ... on RegularTransaction { transactionResult { status segments { id success } } }`
+      : "";
     const query = `query {
       block(offset: { height: ${blockHeight} }) {
         hash
@@ -216,6 +235,7 @@ export class MidnightClient {
           ${unshieldedSpentField}
           ${unshieldedCreatedField}
           ${zswapRootFragment}
+          ${tokenMintFields}
         }
       }
     }`;

package/src/sync-protocols/midnight/fetcher.ts

@@ -19,6 +19,7 @@ import { bound } from "@effectstream/utils";
 import { MidnightClient, type BlockFetchOptions, type MidnightGqlBlockState } from "./MidnightClient.ts";
 import { ContractState, StateValue } from "@midnight-ntwrk/onchain-runtime";
 import { decodeZswapInputEvent } from "./zswap-decoder.ts";
+import { decodeTokenMints } from "./mint-decoder.ts";
 
 export class MidnightFetcher extends BaseDataFetcher<
   Input,
@@ -86,7 +87,8 @@ export class MidnightFetcher extends BaseDataFetcher<
           p.primitive.type !== "Midnight:Nullifier" &&
           p.primitive.type !== "Midnight:UnshieldedSpend" &&
           p.primitive.type !== "Midnight:UnshieldedCreate" &&
-          p.primitive.type !== "Midnight:ZswapRoot",
+          p.primitive.type !== "Midnight:ZswapRoot" &&
+          p.primitive.type !== "Midnight:TokenMint",
       ),
       zswapLedgerEvents: this.config.primitives.some(
         (p) => p.primitive.type === "Midnight:Nullifier",
@@ -100,6 +102,9 @@ export class MidnightFetcher extends BaseDataFetcher<
       zswapRoots: this.config.primitives.some(
         (p) => p.primitive.type === "Midnight:ZswapRoot",
       ),
+      tokenMints: this.config.primitives.some(
+        (p) => p.primitive.type === "Midnight:TokenMint",
+      ),
     };
     const self = this;
     const heights = Array.from(
@@ -192,6 +197,8 @@ export class MidnightFetcher extends BaseDataFetcher<
         syncResults.push(...this.fetchUnshieldedCreates(height, primitiveEntry, block));
       } else if (primitiveEntry.primitive.type === "Midnight:ZswapRoot") {
         syncResults.push(...this.fetchZswapRoots(height, primitiveEntry, block));
+      } else if (primitiveEntry.primitive.type === "Midnight:TokenMint") {
+        syncResults.push(...this.fetchTokenMints(height, primitiveEntry, block));
       } else {
         asyncOps.push(
           this.fetchContractState(height, client, primitiveEntry, block),
@@ -339,6 +346,42 @@ export class MidnightFetcher extends BaseDataFetcher<
     ];
   }
 
+  // Decode custom token mints out of each regular transaction's raw bytes
+  // (ledger-v8 deserialize → contract call transcript effects). One input per
+  // (tx, call, domainSep, kind) that actually applied on chain — see
+  // mint-decoder.ts for the segment semantics. System transactions carry no
+  // transactionResult and are skipped.
+  @bound
+  fetchTokenMints(
+    height: number,
+    primitiveEntry: PrimitiveEntryType,
+    block: MidnightGqlBlockState,
+  ): PrimitiveType[] {
+    const results: PrimitiveType[] = [];
+    for (const tx of block.block.transactions) {
+      if (!tx.raw || !tx.transactionResult) continue;
+      for (const mint of decodeTokenMints(tx.raw, tx.transactionResult)) {
+        results.push({
+          syncProtocol: {
+            name: primitiveEntry.syncProtocol,
+            blockNumber: height,
+            transactionHash: tx.hash,
+            contractAddress: mint.contractAddress,
+          },
+          primitive: primitiveEntry.primitive.name,
+          output: {
+            payloadType: "midnight-token-mint",
+            payload: {
+              ...mint,
+              txHash: tx.hash,
+            },
+          },
+        });
+      }
+    }
+    return results;
+  }
+
   @bound
   *fetchContractState(
     height: number,

package/src/sync-protocols/midnight/mint-decoder.ts

@@ -0,0 +1,151 @@
+import { Buffer } from "node:buffer";
+import * as ledger from "@midnight-ntwrk/ledger-v8";
+
+// Decodes custom token mints out of a raw Midnight transaction. A contract
+// call's transcript effects record mints as `domain_sep → amount` maps
+// (`shieldedMints` / `unshieldedMints`); the resulting token type ("color")
+// is `rawTokenType(domain_sep, contract_address)`. Neither the indexer's
+// GraphQL nor the wallet expose this mapping, so the only route is
+// deserializing the transaction bytes with ledger-v8 — same approach as
+// zswap-decoder.ts for nullifier events.
+//
+// Mirrors zswap-decoder.ts tolerance: never throws — an undecodable
+// transaction logs a warning and contributes nothing.
+
+export interface TokenMintRecord {
+  /** Address of the minting contract, hex */
+  contractAddress: string;
+  /** 32-byte domain separator pre-image, hex */
+  domainSep: string;
+  /** Derived token type ("color") = rawTokenType(domainSep, contractAddress), hex */
+  rawTokenType: string;
+  kind: "shielded" | "unshielded";
+  /** Total minted for this (call, domainSep, kind), as a decimal string (u64 exceeds MAX_SAFE_INTEGER) */
+  amount: string;
+  /** Contract entry point that minted, when printable */
+  entryPoint?: string;
+}
+
+export interface TxResultLike {
+  status: "SUCCESS" | "PARTIAL_SUCCESS" | "FAILURE";
+  segments?: { id: number; success: boolean }[] | null;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  return Uint8Array.from(Buffer.from(clean, "hex"));
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function normalizeHex(value: string): string {
+  return value.replace(/^0x/, "").toLowerCase();
+}
+
+/**
+ * Extract every applied token mint from a raw serialized transaction.
+ *
+ * Segment semantics (failed segments roll back on chain):
+ * - no `result` (system transactions) or status FAILURE → nothing applied;
+ * - SUCCESS → guaranteed + all fallible transcripts applied;
+ * - PARTIAL_SUCCESS → guaranteed transcripts applied, fallible only where
+ *   the intent's segment (the `intents` map key) succeeded.
+ */
+export function decodeTokenMints(
+  rawHex: string,
+  result?: TxResultLike | null,
+): TokenMintRecord[] {
+  if (!result || result.status === "FAILURE") return [];
+
+  let tx: any;
+  try {
+    tx = ledger.Transaction.deserialize(
+      "signature",
+      "proof",
+      "binding",
+      hexToBytes(rawHex),
+    );
+  } catch (e) {
+    console.warn(
+      `[mint-decoder] undecodable transaction, skipping: ${
+        (e as Error)?.message ?? e
+      }`,
+    );
+    return [];
+  }
+
+  const records: TokenMintRecord[] = [];
+  for (const [segmentId, intent] of tx.intents ?? new Map()) {
+    const fallibleApplied = result.status === "SUCCESS" ||
+      (result.segments?.some((s) => s.id === Number(segmentId) && s.success) ??
+        false);
+    for (const action of intent.actions ?? []) {
+      // Only contract calls carry transcripts; deploys and maintenance
+      // updates cannot mint.
+      if (!(action instanceof ledger.ContractCall)) continue;
+      try {
+        records.push(...mintsOfCall(action, fallibleApplied));
+      } catch (e) {
+        console.warn(
+          `[mint-decoder] failed to read mints of call to ${
+            (action as any)?.address ?? "?"
+          }: ${(e as Error)?.message ?? e}`,
+        );
+      }
+    }
+  }
+  return records;
+}
+
+function mintsOfCall(
+  call: any,
+  fallibleApplied: boolean,
+): TokenMintRecord[] {
+  // Accumulate domainSep|kind → amount across the applied transcripts. The
+  // guaranteed transcript applied whenever the transaction wasn't a FAILURE
+  // (the caller filters those); the fallible transcript only if its segment
+  // succeeded.
+  const totals = new Map<string, bigint>();
+  const transcripts = [
+    call.guaranteedTranscript,
+    ...(fallibleApplied ? [call.fallibleTranscript] : []),
+  ];
+  for (const transcript of transcripts) {
+    const effects = transcript?.effects;
+    if (!effects) continue;
+    for (
+      const [kind, mints] of [
+        ["shielded", effects.shieldedMints],
+        ["unshielded", effects.unshieldedMints],
+      ] as const
+    ) {
+      for (const [sepHex, amount] of mints ?? new Map()) {
+        const key = `${normalizeHex(String(sepHex))}|${kind}`;
+        totals.set(key, (totals.get(key) ?? 0n) + BigInt(amount));
+      }
+    }
+  }
+
+  const records: TokenMintRecord[] = [];
+  for (const [key, amount] of totals) {
+    const [domainSep, kind] = key.split("|") as [
+      string,
+      "shielded" | "unshielded",
+    ];
+    records.push({
+      contractAddress: normalizeHex(String(call.address)),
+      domainSep,
+      rawTokenType: normalizeHex(
+        String(ledger.rawTokenType(hexToBytes(domainSep), call.address)),
+      ),
+      kind,
+      amount: amount.toString(),
+      entryPoint: typeof call.entryPoint === "string"
+        ? call.entryPoint
+        : bytesToHex(call.entryPoint),
+    });
+  }
+  return records;
+}

package/src/sync-protocols/midnight/state.ts

@@ -10,6 +10,7 @@ import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/c
 import { getPage } from "@effectstream/db";
 import { MidnightClient } from "./MidnightClient.ts";
 import { applyDelay } from "../common/utils.ts";
+import { bufferAtCap } from "../common/page-helpers.ts";
 
 type LatestBlock = {
   block: {
@@ -72,6 +73,7 @@ export class MidnightSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     const latestBlockResult = yield* call(() => this.client.fetchLatestBlock());
     const latestHeight = latestBlockResult.block.height;
 
@@ -110,6 +112,15 @@ export class MidnightSyncState extends SyncState<
     rootOutput.primitives.push(...primitives);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    return {
+      own: { height: data.raw.height, hash: data.raw.hash },
+      ownBlockNumber: data.raw.height,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/near/state.ts

@@ -10,6 +10,7 @@ import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/c
 import { getPage } from "@effectstream/db";
 import { NearClient } from "./NearClient.ts";
 import { applyDelay } from "../common/utils.ts";
+import { bufferAtCap } from "../common/page-helpers.ts";
 
 export class NearSyncState extends SyncState<
   Input,
@@ -60,6 +61,7 @@ export class NearSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     const latestHeight = yield* call(() =>
       this.client.getLatestBlockHeight()
     );
@@ -98,6 +100,15 @@ export class NearSyncState extends SyncState<
     rootOutput.primitives.push(...primitives);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    return {
+      own: { height: data.height, hash: data.hash },
+      ownBlockNumber: data.height,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/ntp/state.ts

@@ -7,7 +7,7 @@ import { bound, type NtpBlockNumber } from "@effectstream/utils";
 import { type LastPage, SyncState } from "../base/state.ts";
 import type { RootOutput, RootPage } from "../types.ts";
 import type { NtpFetcher } from "./fetcher.ts";
-import { genInputRange } from "../common/page-helpers.ts";
+import { bufferAtCap, genInputRange } from "../common/page-helpers.ts";
 import type { Input, Output, Page } from "./types.ts";
 import { toMsTimestamp } from "./types.ts";
 import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/config";
@@ -48,6 +48,7 @@ export class NtpSyncState extends SyncState<
       })),
       blockNumber: Number(data.raw.blockNumber),
       timestamp: this.toRootPage(data),
+      resumePages: [],
       primitives: [],
     };
   }
@@ -59,6 +60,7 @@ export class NtpSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     return yield* genInputRange(
       this as NtpSyncState,
       1, // NTP Pages start from 1, and the fetcher offsets using the start page (date)
@@ -86,6 +88,16 @@ export class NtpSyncState extends SyncState<
     throw new Error("Only parallel chains merge into root");
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    const block = Number(data.raw.blockNumber);
+    return {
+      own: block,
+      ownBlockNumber: block,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/orchestration/merge.ts

@@ -124,6 +124,11 @@ export function* mergeIntoRoot<SyncProtocol extends AllSyncProtocols>(
     }
     const output = iState.bufferedData.peekAt(0)!;
     const newRoot = iState.toRootOutput(output.output);
+    // Resume marker: the single datum this root block is built from (CLAUDE.md #5).
+    newRoot.resumePages.push({
+      protocol_name: state.name,
+      lastPage: iState.outputToLastPage(output.output),
+    });
     return {
       updateCache: () => {
         output.cleanup();
@@ -141,6 +146,11 @@ export function* mergeIntoRoot<SyncProtocol extends AllSyncProtocols>(
       rootInfo.toPage(rootInfo.value),
     ) <= 0
   ) {
+    // Publish the demand before waiting so the cap exempts this chain while the
+    // merge is gated on its page (see SyncState.mergeWaitingForPage). No lock
+    // needed: the fetch loop re-polls stateToInput every pollingInterval.
+    state.mergeWaitingForPage = true;
+    state.mergeDemandRoot = rootInfo.toPage(rootInfo.value);
     log.remote(
       ComponentNames.EFFECTSTREAM_SYNC,
       state.getNamespace(),
@@ -155,6 +165,8 @@ export function* mergeIntoRoot<SyncProtocol extends AllSyncProtocols>(
       (log) => log("Merge unblocked (missing parallel data): got data"),
     );
   }
+  state.mergeWaitingForPage = false;
+  state.mergeDemandRoot = undefined;
   const cleanups = getFromBuffer(
     {
       data: iState.bufferedData,
@@ -168,6 +180,17 @@ export function* mergeIntoRoot<SyncProtocol extends AllSyncProtocols>(
     iState.mergeDatum,
   );
 
+  // Resume marker: the last (highest) datum merged this iteration, still in the
+  // Deque at `cleanups.length - 1` (cleanup runs after send). Nothing consumed →
+  // no marker. See CLAUDE.md #5.
+  if (cleanups.length > 0) {
+    const lastConsumed = iState.bufferedData.peekAt(cleanups.length - 1)!;
+    rootInfo.value.resumePages.push({
+      protocol_name: state.name,
+      lastPage: iState.outputToLastPage(lastConsumed.output),
+    });
+  }
+
   return {
     updateCache: () => {
       state.bufferedData.remove(0, cleanups.length);

package/src/sync-protocols/test/state.ts

@@ -7,7 +7,7 @@ import { bound, type BlockNumber } from "@effectstream/utils";
 import { type LastPage, SyncState } from "../base/state.ts";
 import type { RootOutput, RootPage } from "../types.ts";
 import type { TestFetcher } from "./fetcher.ts";
-import { genInputRange } from "../common/page-helpers.ts";
+import { bufferAtCap, genInputRange } from "../common/page-helpers.ts";
 import type { Input, Output, Page } from "./types.ts";
 import { toMsTimestamp } from "./types.ts";
 import type {
@@ -60,6 +60,7 @@ export class TestSyncState extends SyncState<
       })),
       blockNumber: Number(data.raw.blockNumber),
       timestamp: this.toRootPage(data),
+      resumePages: [],
       primitives: data.primitives.map((p) => ({
         ...p,
         source: this.config.syncProtocol.name,
@@ -77,6 +78,7 @@ export class TestSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     return yield* genInputRange(
       this as TestSyncState,
       this.config.syncProtocol.startBlockHeight as BlockNumber,
@@ -114,6 +116,16 @@ export class TestSyncState extends SyncState<
     rootOutput.blockInfo.push(...blockInfo);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    const block = Number(data.raw.blockNumber);
+    return {
+      own: block,
+      ownBlockNumber: block as BlockNumber,
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/src/sync-protocols/utxorpc/state.ts

@@ -1,4 +1,5 @@
 import { applyDelay } from "../common/utils.ts";
+import { bufferAtCap } from "../common/page-helpers.ts";
 import type { Operation } from "effection";
 import { call } from "effection";
 import { getPage } from "@effectstream/db";
@@ -71,6 +72,7 @@ export class UtxoRpcSyncState extends SyncState<
 
   @bound
   override *stateToInput(): Operation<Input | undefined> {
+    if (bufferAtCap(this, this.config.syncProtocol)) return undefined;
     // Get the value of the latest block height.
     const tipHeight = yield* call(() => this.fetcher.lastHeight());
     if (!tipHeight) {
@@ -157,6 +159,22 @@ export class UtxoRpcSyncState extends SyncState<
     rootOutput.blockInfo.push(...blockInfo);
   }
 
+  @bound
+  override outputToLastPage(data: Output): LastPage<Page, RootPage> {
+    // Mirror the fetcher's `own`: slot/height from the block header, and the
+    // block hash from `blockHashes` (the fetcher builds it as `[completed.hash]`,
+    // the same value it stored in `own.hash`).
+    return {
+      own: {
+        slot: Number(data.raw.header!.slot),
+        height: Number(data.raw.header!.height),
+        hash: data.blockHashes[0],
+      },
+      ownBlockNumber: Number(data.raw.header!.height),
+      root: this.toRootPage(data),
+    };
+  }
+
   @bound
   override getNamespace(): string[] {
     return [this.config.network.name, this.config.syncProtocol.name];

package/test/mint-decoder.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+
+import { decodeTokenMints } from "../src/sync-protocols/midnight/mint-decoder.ts";
+
+// Tolerance contract: the decoder must never throw — an undecodable or
+// inapplicable transaction contributes nothing (the fetcher's per-height
+// error path would otherwise wedge the sync loop).
+describe("decodeTokenMints — tolerance", () => {
+  test("no transactionResult (system tx) → []", () => {
+    expect(decodeTokenMints("deadbeef", undefined)).toEqual([]);
+    expect(decodeTokenMints("deadbeef", null)).toEqual([]);
+  });
+
+  test("status FAILURE → [] (everything rolled back, incl. guaranteed)", () => {
+    expect(
+      decodeTokenMints("deadbeef", { status: "FAILURE", segments: [] }),
+    ).toEqual([]);
+  });
+
+  test("garbage bytes with SUCCESS status → [] without throwing", () => {
+    expect(
+      decodeTokenMints("not-even-hex", { status: "SUCCESS" }),
+    ).toEqual([]);
+    expect(
+      decodeTokenMints("00".repeat(64), { status: "SUCCESS" }),
+    ).toEqual([]);
+  });
+});