@effectstream/runtime 0.100.19 → 0.100.21

package/README.md

@@ -69,6 +69,40 @@ exercised when this loop is running. The `StartConfig` shape determines
 which DB migrations apply, which state machines fire, and whether the
 runtime exposes a Fastify router.
 
+## Empty-block coalescing (catch-up)
+
+The runtime replays one Effectstream block per main-clock tick, each in its
+own DB transaction. During a deep catch-up over an idle gap (e.g. an NTP main
+chain at one block/second across days), most of those blocks are **empty** — no
+on-chain content, no scheduled input, no migration — yet still cost a full
+`BEGIN…COMMIT` round-trip.
+Empty-block coalescing folds a run of consecutive empty blocks into a **single
+transaction** that writes only the run's endpoint. It is **opt-in** and off by
+default:
+
+```bash
+EFFECTSTREAM_COALESCE_EMPTY_BLOCKS=true
+```
+
+Behavior and guarantees:
+
+- **Catch-up only.** Coalescing engages only while behind the chain tip
+  (`now - block.timestamp` greater than 10× the main clock's block time) and
+  disengages at the tip, so steady-state stays one block per transaction.
+- **Identical database.** A coalesced sync produces a byte-for-byte identical
+  database to a non-coalesced one. Empty blocks already never advance the block
+  hash or RNG seed, so only the endpoint's block row and the per-protocol resume
+  watermark are written — exactly as the normal path would leave them.
+- **Never skips work.** A run is flushed before any block that has on-chain
+  content, a migration at its height, or a due block-height/timestamp-scheduled
+  input — so nothing that mutates state is ever folded away.
+- **Tip stays visible.** If the producer goes quiet on an empty tail, the run is
+  flushed on a short idle timeout so the latest height still commits.
+- A run is also capped (`MAX_EMPTY_RUN`) to bound transaction size and recovery.
+
+Implementation: [`src/coalesce.ts`](./src/coalesce.ts) (the `createEmptyBlockCoalescer`
+coordinator the main loop drives).
+
 ## Key exports
 
 - `init()` - `Operation<void>`. One-shot setup: OpenTelemetry, config validation, version pinning. Call before `start`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/runtime",
-  "version": "0.100.19",
+  "version": "0.100.21",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,20 +13,20 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/concise": "0.100.19",
-    "@effectstream/config": "0.100.19",
-    "@effectstream/coroutine": "0.100.19",
-    "@effectstream/crypto": "0.100.19",
-    "@effectstream/db": "0.100.19",
-    "@effectstream/event-client": "0.100.19",
-    "@effectstream/event-server": "0.100.19",
-    "@effectstream/log": "0.100.19",
-    "@effectstream/sm": "0.100.19",
-    "@effectstream/sync": "0.100.19",
-    "@effectstream/utils": "0.100.19",
+    "@effectstream/concise": "0.100.21",
+    "@effectstream/config": "0.100.21",
+    "@effectstream/coroutine": "0.100.21",
+    "@effectstream/crypto": "0.100.21",
+    "@effectstream/db": "0.100.21",
+    "@effectstream/event-client": "0.100.21",
+    "@effectstream/event-server": "0.100.21",
+    "@effectstream/log": "0.100.21",
+    "@effectstream/sm": "0.100.21",
+    "@effectstream/sync": "0.100.21",
+    "@effectstream/utils": "0.100.21",
     "@fastify/cors": "^11.0.1",
     "@metamask/json-rpc-engine": "^10.0.3",
-    "pg": "8.17.2",
+    "pg": "8.21.0",
     "effection": "^3.5.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.54.0",

package/src/api/http-server.ts

@@ -504,6 +504,10 @@ export const startHttpServer = function* (
           pausedNow: p.pausedNow,
           pauses: p.backpressurePauses,
           pausedMs: p.backpressurePausedMs,
+          // Merge-demand exemption: when true the merge is gated on this chain's
+          // page and the cap is lifted.
+          mergeWaiting: p.mergeWaitingForPage,
+          mergeDemandRoot: p.mergeDemandRoot ?? null,
         })),
         // Apply-stage lag: how old the last-applied block is. Unlike `buf` (fetch
         // backlog) this stays high when the node is write/apply-bound.

package/src/coalesce.ts

@@ -0,0 +1,291 @@
+/** Empty-block coalescing during deep catch-up: fold consecutive no-op blocks into one transaction. */
+import type { ChainBlock } from "@effectstream/sync";
+import { call, type Operation, race, sleep, until } from "effection";
+import type { Pool, PoolClient } from "pg";
+import {
+  acquireDBMutex,
+  blockHeightDone,
+  deleteEmptyBlocks,
+  getEarliestScheduledBlockHeight,
+  getEarliestScheduledTimestamp,
+  getMigrationsForBlockHeight,
+  isTransientPgError,
+  poolErrors,
+  releaseDBMutex,
+  removePages,
+  saveLastBlock,
+  upsertPage,
+} from "@effectstream/db";
+import { Buffer } from "node:buffer";
+import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
+import { generateEffectstreamBlockHash, Prando } from "@effectstream/crypto";
+import type { EffectstreamBlockHash } from "@effectstream/utils";
+import type { DBMigrations } from "@effectstream/runtime";
+
+/** Scheduled-input boundaries sampled once at run start (stable until the next non-empty block). */
+export type EmptyRunBoundaries = {
+  minScheduledBlockHeight: number | null;
+  minScheduledTimestampMs: number | null;
+};
+
+export const MAX_EMPTY_RUN = 5_000;
+
+const MAX_RETRY_BACKOFF_MS = 5_000;
+
+export function* loadEmptyRunBoundaries(
+  dbConn: Pool,
+): Operation<EmptyRunBoundaries> {
+  const [bh] = yield* until(getEarliestScheduledBlockHeight.run(undefined, dbConn));
+  const [ts] = yield* until(getEarliestScheduledTimestamp.run(undefined, dbConn));
+  return {
+    minScheduledBlockHeight: bh?.min_block_height ?? null,
+    minScheduledTimestampMs: ts?.min_timestamp != null
+      ? new Date(ts.min_timestamp).getTime()
+      : null,
+  };
+}
+
+/** Mirrors the empty-block checks in process-blocks.ts without DB/STF work. */
+export function isCoalescableEmptyBlock(
+  value: ChainBlock,
+  boundaries: EmptyRunBoundaries,
+  migrations: DBMigrations[] | undefined,
+): boolean {
+  if (value.primitives.length > 0) return false;
+  if (
+    getMigrationsForBlockHeight(migrations, value.blockNumber, value.blockNumber)
+      .length > 0
+  ) {
+    return false;
+  }
+  if (
+    boundaries.minScheduledBlockHeight != null &&
+    value.blockNumber >= boundaries.minScheduledBlockHeight
+  ) {
+    return false;
+  }
+  if (
+    boundaries.minScheduledTimestampMs != null &&
+    boundaries.minScheduledTimestampMs <= value.timestamp
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export function* processCoalescedEmptyRun(
+  endpoint: ChainBlock,
+  pool: Pool,
+  previousBlockHash: EffectstreamBlockHash | null,
+): Operation<void> {
+  const lockName = `processing-blocks:${endpoint.blockNumber}`;
+  let attempt = 0;
+  while (true) {
+    let dbClient: PoolClient | undefined;
+    let transientErr: unknown;
+    try {
+      yield* acquireDBMutex(lockName);
+      dbClient = yield* until(pool.connect());
+      yield* writeEndpoint(
+        endpoint,
+        dbClient as unknown as Pool,
+        previousBlockHash,
+      );
+      return;
+    } catch (err) {
+      if (!isTransientPgError(err)) throw err;
+      transientErr = err;
+    } finally {
+      releaseDBMutex(lockName);
+      if (dbClient) {
+        try {
+          dbClient.release(transientErr as Error | undefined);
+        } catch {
+          /* already released/destroyed */
+        }
+      }
+    }
+
+    attempt++;
+    poolErrors.log(transientErr, ["sync-write"]);
+    const backoffMs = Math.min(500 * 2 ** (attempt - 1), MAX_RETRY_BACKOFF_MS);
+    log.local(
+      ComponentNames.EFFECTSTREAM_SYNC,
+      "block-processing",
+      SeverityNumber.WARN,
+      (l) =>
+        l(
+          `transient db error on coalesced run → block ${endpoint.blockNumber}; retry #${attempt} in ${backoffMs}ms: ${
+            String(transientErr)
+          }`,
+        ),
+    );
+    yield* sleep(backoffMs);
+  }
+}
+
+/** One transaction for the run endpoint; matches process-blocks.ts empty-block writes. */
+function* writeEndpoint(
+  endpoint: ChainBlock,
+  dbConn: Pool,
+  previousBlockHash: EffectstreamBlockHash | null,
+): Operation<void> {
+  const blockHash = generateEffectstreamBlockHash(endpoint, previousBlockHash);
+  const seed = new Prando(blockHash).seed.toString();
+  try {
+    yield* until(dbConn.query("BEGIN"));
+
+    yield* call(() =>
+      saveLastBlock.run({
+        block_height: endpoint.blockNumber,
+        ver: 0,
+        main_chain_block_hash: Buffer.from(endpoint.blockNumber.toString()),
+        seed,
+        ms_timestamp: new Date(endpoint.timestamp),
+      }, dbConn)
+    );
+
+    yield* call(() => deleteEmptyBlocks.run(undefined, dbConn));
+    yield* call(() =>
+      blockHeightDone.run({
+        block_hash: Buffer.from("0x0"),
+        block_height: endpoint.blockNumber,
+      }, dbConn)
+    );
+
+    for (const { protocol_name, lastPage } of endpoint.resumePages) {
+      yield* until(
+        upsertPage.run({
+          protocol_name,
+          page_number: lastPage.ownBlockNumber,
+          page: JSON.stringify(lastPage),
+        }, dbConn),
+      );
+      yield* until(
+        removePages.run({
+          protocol_name,
+          page_number: lastPage.ownBlockNumber,
+        }, dbConn),
+      );
+    }
+
+    yield* until(dbConn.query("COMMIT"));
+    poolErrors.markHealthy();
+  } catch (err) {
+    try {
+      yield* until(dbConn.query("ROLLBACK"));
+    } catch (rollbackErr) {
+      log.remote(
+        ComponentNames.EFFECTSTREAM_SYNC,
+        "block-processing",
+        SeverityNumber.WARN,
+        (l) =>
+          l(
+            `ROLLBACK failed for coalesced run → block ${endpoint.blockNumber} (connection likely dead): ${
+              String(rollbackErr)
+            }`,
+          ),
+      );
+    }
+    throw err;
+  }
+}
+
+export type FinalizedBlockSubscription = {
+  next(): Operation<IteratorResult<ChainBlock, void>>;
+};
+
+function* readFinalizedBlock(
+  subscription: FinalizedBlockSubscription,
+): Operation<{ tag: "item"; value: ChainBlock } | { tag: "done" }> {
+  const n = yield* subscription.next();
+  if (n.done) return { tag: "done" };
+  // IteratorResult value type does not narrow on `done` under non-strict tsconfig.
+  return { tag: "item", value: n.value as ChainBlock };
+}
+
+export type EmptyBlockCoalescerOptions = {
+  enabled: boolean;
+  subscription: FinalizedBlockSubscription;
+  pool: Pool;
+  migrations: DBMigrations[] | undefined;
+  /** Coalesce only while `now - block.timestamp` exceeds this. Undefined disables lag gating. */
+  lagThresholdMs: number | undefined;
+  getPreviousBlockHash: () => EffectstreamBlockHash | null;
+  onFlush: (endpoint: ChainBlock, length: number) => void;
+  idleFlushMs?: number;
+};
+
+export type EmptyBlockCoalescer = {
+  advance(): Operation<ChainBlock | undefined>;
+};
+
+export function createEmptyBlockCoalescer(
+  opts: EmptyBlockCoalescerOptions,
+): EmptyBlockCoalescer {
+  const idleFlushMs = opts.idleFlushMs ?? 250;
+  let pendingRun:
+    | { endpoint: ChainBlock; boundaries: EmptyRunBoundaries; length: number }
+    | null = null;
+
+  function* flush(): Operation<void> {
+    if (pendingRun == null) return;
+    const { endpoint, length } = pendingRun;
+    yield* processCoalescedEmptyRun(
+      endpoint,
+      opts.pool,
+      opts.getPreviousBlockHash(),
+    );
+    pendingRun = null;
+    opts.onFlush(endpoint, length);
+  }
+
+  function* nextItem(): Operation<
+    { tag: "item"; value: ChainBlock } | { tag: "done" } | { tag: "idle" }
+  > {
+    if (pendingRun == null) return yield* readFinalizedBlock(opts.subscription);
+    return yield* race([
+      readFinalizedBlock(opts.subscription),
+      (function* () {
+        yield* sleep(idleFlushMs);
+        return { tag: "idle" as const };
+      })(),
+    ]);
+  }
+
+  function* advance(): Operation<ChainBlock | undefined> {
+    if (!opts.enabled) {
+      const n = yield* readFinalizedBlock(opts.subscription);
+      return n.tag === "done" ? undefined : n.value;
+    }
+    while (true) {
+      const next = yield* nextItem();
+      if (next.tag === "idle") {
+        yield* flush();
+        continue;
+      }
+      if (next.tag === "done") {
+        yield* flush();
+        return undefined;
+      }
+      const value = next.value;
+      const behindTip = opts.lagThresholdMs != null &&
+        Date.now() - value.timestamp > opts.lagThresholdMs;
+      if (behindTip && value.primitives.length === 0) {
+        const boundaries = pendingRun?.boundaries ??
+          (yield* loadEmptyRunBoundaries(opts.pool));
+        if (isCoalescableEmptyBlock(value, boundaries, opts.migrations)) {
+          pendingRun = pendingRun
+            ? { boundaries, endpoint: value, length: pendingRun.length + 1 }
+            : { boundaries, endpoint: value, length: 1 };
+          if (pendingRun.length >= MAX_EMPTY_RUN) yield* flush();
+          continue;
+        }
+      }
+      yield* flush();
+      return value;
+    }
+  }
+
+  return { advance };
+}

package/src/main.ts

@@ -6,11 +6,13 @@ import {
 import {
   acquireDBMutex,
   createDynamicTables,
+  detectCapabilities,
   getConnection,
   getLastNonEmptyBlockHash,
   releaseDBMutex,
   resetPublicTables,
   runSnapshotLoop,
+  selectViewStrategy,
 } from "@effectstream/db";
 import { EventBroker } from "@effectstream/event-server";
 import { ENV } from "@effectstream/utils/node-env";
@@ -32,6 +34,7 @@ import {
   type PendingEvent,
   processFinalizedBlockWithRetry,
 } from "./process-blocks.ts";
+import { createEmptyBlockCoalescer } from "./coalesce.ts";
 import { startHttpServer } from "./api/http-server.ts";
 import { recordAppliedBlock } from "./api/apply-status.ts";
 import type { StartConfig } from "./types.ts";
@@ -92,19 +95,21 @@ export function* start(config: StartConfig): Operation<void> {
     );
   });
 
+  // 10× main clock block time (NTP if present, else protocol 0). Undefined disables lag gating.
   const ntpConfig = syncInfo.find(s => s.networkType === ConfigNetworkType.NTP);
-  const ntpBlockTimeMS = (ntpConfig?.network as { blockTimeMS: number } | undefined)?.blockTimeMS;
-  const lagThresholdMs = ntpBlockTimeMS != null ? ntpBlockTimeMS * 10 : undefined;
+  const clockBlockTimeMS =
+    (ntpConfig?.network as { blockTimeMS?: number } | undefined)?.blockTimeMS ??
+    (syncInfo[0]?.network as { blockTimeMS?: number } | undefined)?.blockTimeMS;
+  const lagThresholdMs = clockBlockTimeMS != null ? clockBlockTimeMS * 10 : undefined;
 
   const finalizedBlockStream = createChannel<ChainBlock>();
 
   // Subscribe BEFORE spawning the merge: effection channels drop sends with no
-  // active subscriber, so a fast restart (in-memory state, no RPC wait) could
-  // emit blocks before we subscribe and silently stall at the pre-restart height.
+  // subscriber, so a fast restart could emit blocks before we subscribe and
+  // stall at the pre-restart height.
   const finalizedBlocks = yield* finalizedBlockStream;
-  // NOTE: this subscriber's queue is unbounded. During deep catch-up the merge
-  // can outpace the per-block processing below and grow it without bound — the
-  // downstream side of the Fix C backpressure issue (see sync/CLAUDE.md).
+  // NOTE: this subscriber's queue is unbounded — during deep catch-up the merge
+  // can outpace block processing and grow it (Fix C backpressure, sync/CLAUDE.md).
 
   yield* spawn(() => startMerge(syncProtocols, finalizedBlockStream));
 
@@ -148,13 +153,39 @@ export function* start(config: StartConfig): Operation<void> {
     yield* spawn(() => runSnapshotLoop(config.snapshotConfig!));
   }
 
-  let nextBlock = yield* finalizedBlocks.next();
-  for (; !nextBlock.done; nextBlock = yield* finalizedBlocks.next()) {
-    const value = nextBlock.value;
-    // processFinalizedBlockWithRetry owns connection checkout, the per-block
-    // DB mutex (PGLite), and transient-pg retry/backoff. App events it
-    // collects are flushed below ONLY after it returns — i.e. strictly after
-    // the block's COMMIT.
+  const coalescer = createEmptyBlockCoalescer({
+    enabled: ENV.EFFECTSTREAM_COALESCE_EMPTY_BLOCKS,
+    subscription: finalizedBlocks,
+    pool: dbConn as any, // Pool,
+    migrations: config.migrations,
+    lagThresholdMs,
+    getPreviousBlockHash: () => blockHash,
+    onFlush: (endpoint, length) => {
+      recordAppliedBlock(endpoint);
+      emitLatestBlocks(
+        endpoint.blockNumber,
+        endpoint.timestamp,
+        getRangesForSyncProtocols(endpoint),
+      );
+      log.local(
+        ComponentNames.EFFECTSTREAM_SYNC,
+        "block-merge",
+        SeverityNumber.INFO,
+        (l) =>
+          l(
+            `coalesced ${length} empty block(s) → block ${endpoint.blockNumber}`,
+          ),
+      );
+    },
+  });
+
+  while (true) {
+    const value = yield* coalescer.advance();
+    if (value === undefined) break;
+
+    // Owns connection checkout, the per-block DB mutex (PGLite), and
+    // transient-pg retry/backoff. App events flush below only after it
+    // returns — strictly after the block's COMMIT.
     const result = yield* processFinalizedBlockWithRetry(
       value,
       config,
@@ -171,21 +202,14 @@ export function* start(config: StartConfig): Operation<void> {
     // Used to emit & log the block range for each protocol.
     const contentBlocksForProtocol = getRangesForSyncProtocols(value);
 
-    // Fire-and-forget: do not stall the sync loop on broker acks.
+    // Fire-and-forget: don't stall the sync loop on broker acks. Ordering is
+    // safe without a wrapper queue — Opifex assigns packet IDs synchronously in
+    // publish() and net.Socket serializes writes in call order, so MQTT 3.1.1
+    // §4.6 in-order delivery holds per (publisher, topic, QoS).
     //
-    // Opifex's TcpClient assigns packet IDs synchronously in client.publish()
-    // and writes to the socket via Node's net.Socket, which has its own write
-    // queue — so concurrent publish() calls land on the wire in call order.
-    // MQTT 3.1.1 §4.6 then guarantees in-order delivery to each subscriber
-    // per (publisher, topic, QoS). We don't need a wrapper queue.
-    //
-    // TODO(scaling): the broker runs in-process (see `new EventBroker(...)`
-    // above). Fan-out to N subscribers consumes the same event loop as block
-    // processing. At ~thousands of subscribers, consider:
-    //   1) moving the broker to a worker / separate process,
-    //   2) a publisher-side circuit breaker if ctx.unresolvedPublish.size > N
-    //      (drop events with a counter for observability).
-    // Today: localhost, in-process, expected O(10²) subscribers — non-issue.
+    // TODO(scaling): the broker is in-process, so fan-out shares this event
+    // loop. At ~thousands of subscribers, move it to a worker and/or add a
+    // publisher-side circuit breaker. Today: localhost, O(10²) subs — non-issue.
     emitLatestBlocks(
       value.blockNumber,
       value.timestamp,
@@ -237,13 +261,9 @@ function getRangesForSyncProtocols(value: ChainBlock): Record<string, [number, n
 }
 
 /**
- * Publish built-in block-level events.
- *
- * Fire-and-forget for the same reasons as the app-event flush above
- * (do not stall the sync loop; ordering preserved by Opifex + MQTT 3.1.1).
- *
- * Errors are caught locally so they don't escape to the global
- * `unhandledrejection` handler without context.
+ * Publish built-in block-level events. Fire-and-forget like the app-event flush
+ * above (don't stall the sync loop; ordering held by Opifex + MQTT 3.1.1).
+ * Errors are caught locally so they don't reach the global handler contextless.
  */
 function emitLatestBlocks(
   rollUpBlockHeight: number,
@@ -294,41 +314,48 @@ function* startup(
     });
   });
 
-  
   yield* acquireDBMutex(`startup-node`);
+  // `finally` releases the mutex on error/cancellation too; a throw in any step
+  // below would otherwise leak it and deadlock every later DB operation.
+  try {
+    // Dev-only reset of user-owned public tables
+    if (config.dev?.resetPublicData) {
+      yield* resetPublicTables(dbConn as any); // Client,
+    }
 
-  // Dev-only reset of user-owned public tables
-  if (config.dev?.resetPublicData) {
-    yield* resetPublicTables(dbConn as any); // Client,
-  }
+    // When the node is started, we apply system migrations.
+    // Either system initial migrations, or migrations given a Paima Engine Update.
+    yield* applySystemMigrations(
+      config.appVersion,
+      versionInfo,
+      lastBlockHeight,
+      dbConn,
+      config.migrations,
+    );
 
-  // When the node is started, we apply system migrations.
-  // Either system initial migrations, or migrations given a Paima Engine Update.
-  yield* applySystemMigrations(
-    config.appVersion,
-    versionInfo,
-    lastBlockHeight,
-    dbConn,
-    config.migrations,
-  );
+    // Validate that immutable config fields (e.g. NTP startTime, startBlockHeight)
+    // have not changed since the last run. Persists a snapshot on first start.
+    // Must run after system migrations so the snapshot table exists.
+    yield* validateAndSnapshotConfig(syncInfo, dbConn);
 
-  // Validate that immutable config fields (e.g. NTP startTime, startBlockHeight)
-  // have not changed since the last run. Persists a snapshot on first start.
-  // Must run after system migrations so the snapshot table exists.
-  yield* validateAndSnapshotConfig(syncInfo, dbConn);
+    const syncProtocols = yield* genSyncProtocols(dbConn as any, // Client,
+      syncInfo);
 
-  const syncProtocols = yield* genSyncProtocols(dbConn as any, // Client,
-    syncInfo);
+    const capabilities = yield* until(detectCapabilities(dbConn as any));
+    const viewStrategy = selectViewStrategy(capabilities);
 
-  yield* createDynamicTables(
-    versionInfo,
-    lastBlockHeight,
-    dbConn as any, // Client,
-    syncProtocols,
-  );
+    yield* createDynamicTables(
+      versionInfo,
+      lastBlockHeight,
+      dbConn as any, // Client,
+      syncProtocols,
+      viewStrategy,
+    );
 
-  releaseDBMutex(`startup-node`);
-  return syncProtocols;
+    return syncProtocols;
+  } finally {
+    releaseDBMutex(`startup-node`);
+  }
 }
 
 // Convert the primitive config to the final primitive instance

package/test/coalesce.unit.test.ts

@@ -0,0 +1,69 @@
+import { expect, test } from "bun:test";
+import {
+  type EmptyRunBoundaries,
+  isCoalescableEmptyBlock,
+} from "../src/coalesce.ts";
+
+const NO_BOUNDARIES: EmptyRunBoundaries = {
+  minScheduledBlockHeight: null,
+  minScheduledTimestampMs: null,
+};
+
+function block(
+  blockNumber: number,
+  timestamp: number,
+  primitives: unknown[] = [],
+): any {
+  return { blockNumber, timestamp, blockInfo: [], resumePages: [], primitives };
+}
+
+test("empty block with no boundaries is coalescable", () => {
+  expect(isCoalescableEmptyBlock(block(10, 10_000), NO_BOUNDARIES, undefined))
+    .toBe(true);
+});
+
+test("block with on-chain content is NOT coalescable", () => {
+  expect(
+    isCoalescableEmptyBlock(block(10, 10_000, [{}]), NO_BOUNDARIES, undefined),
+  ).toBe(false);
+});
+
+test("block where a migration fires is NOT coalescable", () => {
+  const migrations = [{ name: "m1", sql: "", blockHeight: 10 }];
+  expect(isCoalescableEmptyBlock(block(10, 10_000), NO_BOUNDARIES, migrations))
+    .toBe(false);
+  expect(isCoalescableEmptyBlock(block(9, 9_000), NO_BOUNDARIES, migrations))
+    .toBe(true);
+});
+
+test("block at/after a pending block-height-scheduled input is NOT coalescable", () => {
+  const boundaries: EmptyRunBoundaries = {
+    minScheduledBlockHeight: 10,
+    minScheduledTimestampMs: null,
+  };
+  expect(isCoalescableEmptyBlock(block(9, 9_000), boundaries, undefined)).toBe(
+    true,
+  );
+  expect(isCoalescableEmptyBlock(block(10, 10_000), boundaries, undefined)).toBe(
+    false,
+  );
+  expect(isCoalescableEmptyBlock(block(11, 11_000), boundaries, undefined)).toBe(
+    false,
+  );
+});
+
+test("block at/after a due timestamp-scheduled input is NOT coalescable", () => {
+  const boundaries: EmptyRunBoundaries = {
+    minScheduledBlockHeight: null,
+    minScheduledTimestampMs: 10_000,
+  };
+  expect(isCoalescableEmptyBlock(block(9, 9_999), boundaries, undefined)).toBe(
+    true,
+  );
+  expect(isCoalescableEmptyBlock(block(10, 10_000), boundaries, undefined)).toBe(
+    false,
+  );
+  expect(isCoalescableEmptyBlock(block(11, 10_001), boundaries, undefined)).toBe(
+    false,
+  );
+});

package/test/reproduction/buffering.test.ts

@@ -8,6 +8,10 @@
  *  1b — head-of-line blocking: a stalled slow chain STILL halts block production
  *       (the merge gate is correct), but the fast chain's buffer is now bounded by
  *       the cap instead of ballooning behind the head-of-line block.
+ *  1c — skip-ahead: the merge-demand exemption lifts the cap while the merge is gated
+ *       on a chain whose page is far behind the (skipped-ahead) root, so it advances
+ *       instead of deadlocking.
+ *  1d — density: the same exemption when a parallel chain is finer-grained than the cap.
  *
  * Before the fix these buffers reached ~49k–50k (see
  * e2e/perf/results/BACKPRESSURE-BASELINE.md); these tests assert they now
@@ -177,7 +181,7 @@ test("1a: backpressure caps the buffer while the node keeps applying blocks", as
   let mainPauses = 0;
   try {
     const startMs = Date.now();
-    const deadline = startMs + 6000;
+    const deadline = startMs + 30_000;
     while (Date.now() < deadline) {
       const wall = Date.now();
       const mainBuf = bufferSize(node, MAIN_1A);
@@ -327,7 +331,8 @@ test("1b: a stalled chain still halts production, but the fast chain's buffer st
   let fastPauses = 0;
   try {
     const startMs = Date.now();
-    const deadline = startMs + 15_000;
+    // Generous for slow CI; exits early once the stall + capped sibling are captured.
+    const deadline = startMs + 30_000;
     let lastHeight = -1;
     let lastChange = Date.now();
     while (Date.now() < deadline) {
@@ -387,3 +392,259 @@ test("1b: a stalled chain still halts production, but the fast chain's buffer st
   // ...and the cap actually fired on the fast chain (observability metric populated).
   expect(fastPauses).toBeGreaterThan(0);
 }, 60_000);
+
+// ── 1c — skip-ahead: merge-demand exemption keeps the cap from deadlocking ────────
+//
+// The root (main clock) starts far ahead of a parallel chain that starts at block 1.
+// To produce the first root block at τ (main page SKIP_START) the merge needs the
+// parallel page PAST τ — so the fetcher must scan ~SKIP_START blocks, more than the
+// cap. The exemption lifts the cap while the merge is gated on this chain, so it
+// reaches τ and production proceeds (without it the node wedges on the first block).
+
+const MAIN_1C = "mainClock1c";
+const PAR_1C = "parallelP1c";
+// Main genesis page (skip-ahead); cap far below it so the parallel chain must buffer
+// past the cap to reach τ.
+const SKIP_START = 300;
+const SMALL_STEP = 50;
+const SMALL_CAP = 100;
+// Liveness: past the first non-empty block at SKIP_START.
+const LIVE_TARGET_1C = SKIP_START + 10;
+// Bounded by necessity: at most the skip window + one in-flight chunk.
+const SKIP_BUFFER_BOUND = SKIP_START + SMALL_STEP + 200;
+
+function buildConfig1c() {
+  return new ConfigBuilder()
+    .setNamespace((b) => b.setSecurityNamespace("sync-buffering-1c"))
+    .buildNetworks((b) =>
+      b
+        .addNetwork({
+          name: "clock",
+          type: ConfigNetworkType.TEST,
+          startTime: START_TIME,
+          blockTimeMS: BLOCK_TIME_MS,
+        })
+        .addNetwork({
+          name: "chainP",
+          type: ConfigNetworkType.TEST,
+          startTime: START_TIME,
+          blockTimeMS: BLOCK_TIME_MS,
+        })
+    )
+    .buildDeployments((b) => b)
+    .buildSyncProtocols((b) =>
+      b
+        .addMain(
+          (n) => n.clock,
+          () => ({
+            name: MAIN_1C,
+            type: ConfigSyncProtocolType.TEST_MAIN,
+            // Skipped far ahead of the parallel chain (the recovery skip-ahead).
+            startBlockHeight: SKIP_START,
+            pollingInterval: 30,
+            stepSize: SMALL_STEP,
+            maxBufferedPages: SMALL_CAP,
+          }),
+        )
+        .addParallel(
+          (n) => (n as any).chainP,
+          () => ({
+            name: PAR_1C,
+            type: ConfigSyncProtocolType.TEST_PARALLEL,
+            startBlockHeight: 1,
+            pollingInterval: 30,
+            stepSize: SMALL_STEP,
+            delayMs: 0,
+            events: [],
+            maxBufferedPages: SMALL_CAP,
+          }),
+        )
+    )
+    .buildPrimitives((b) =>
+      b.addPrimitive(
+        (sp) => (sp as any)[PAR_1C],
+        () => ({ name: "noEvt1c", type: TEST_PRIMITIVE_TYPE, startBlockHeight: 1 }),
+      )
+    )
+    .build();
+}
+
+test("1c: a skipped-ahead root does NOT deadlock the merge on the first non-empty block", async () => {
+  // Main skipped to SKIP_START; parallel starts at 1 with a high tip.
+  TestChainControl.setTip(MAIN_1C, SKIP_START + 100);
+  TestChainControl.setTip(PAR_1C, 10_000);
+
+  const node = await h.runNode({ config: buildConfig1c(), apiPort: 19143 });
+  const samples: BufSample[] = [];
+  let peakPar = 0;
+  let lastApplied = 0;
+  try {
+    const startMs = Date.now();
+    // Generous for slow CI; exits early once the liveness target is reached.
+    const deadline = startMs + 30_000;
+    while (Date.now() < deadline) {
+      const wall = Date.now();
+      const mainBuf = bufferSize(node, MAIN_1C);
+      const parBuf = bufferSize(node, PAR_1C);
+      const appliedBlock = await latestFinalizedHeight(h.pool);
+      samples.push({
+        t: wall - startMs,
+        wall,
+        mainBuf,
+        evmBuf: parBuf,
+        mainOwnBlock: ownBlock(node, MAIN_1C),
+        evmOwnBlock: ownBlock(node, PAR_1C),
+        rss: process.memoryUsage().rss,
+        appliedBlock,
+      });
+      peakPar = Math.max(peakPar, parBuf);
+      lastApplied = appliedBlock ?? lastApplied;
+      // Got past the first non-empty block → the deadlock is broken; stop early.
+      if (lastApplied >= LIVE_TARGET_1C) break;
+      await sleep(50);
+    }
+  } finally {
+    writeArtifact("buffering-1c", samples, {
+      mode: "1c-skip-ahead-deadlock",
+      stepSize: SMALL_STEP,
+      skipStart: SKIP_START,
+      cap: SMALL_CAP,
+      liveTarget: LIVE_TARGET_1C,
+      peakParBuf: peakPar,
+      lastApplied,
+    });
+    await node.stop();
+  }
+
+  // Liveness: production advanced past the first non-empty block (no wedge).
+  expect(lastApplied).toBeGreaterThanOrEqual(LIVE_TARGET_1C);
+  // Bounded by necessity: only the skip window + one chunk, not the whole tip.
+  expect(peakPar).toBeLessThanOrEqual(SKIP_BUFFER_BOUND);
+}, 60_000);
+
+// ── 1d — density: same exemption when a chain is finer-grained than the cap ───────
+//
+// Same circular wait without a skip-ahead: a parallel chain far finer than the root
+// (100 parallel blocks per root slot). Each root block needs the parallel page past
+// the slot boundary (~PER_SLOT buffered items), but the cap is below that. The
+// exemption lets the per-slot window buffer and drain each slot (without it the node
+// wedges on the first block).
+
+const MAIN_1D = "mainClock1d";
+const PAR_1D = "parallelP1d";
+const DENSE_BLOCK_MS = 10; // 100 parallel blocks per 1000ms root slot
+const PER_SLOT = BLOCK_TIME_MS / DENSE_BLOCK_MS; // 100 parallel items per root slot
+// Step + cap small enough that cap + one overshoot chunk (~40) stays below PER_SLOT
+// (100), so the fetcher pauses before its page can cross the slot boundary.
+const DENSE_STEP = 10;
+const CAP_1D = 30;
+const LIVE_TARGET_1D = 20;
+// Bounded by the per-slot need plus one chunk — not the whole tip.
+const DENSE_BUFFER_BOUND = PER_SLOT + DENSE_STEP + 150;
+
+function buildConfig1d() {
+  return new ConfigBuilder()
+    .setNamespace((b) => b.setSecurityNamespace("sync-buffering-1d"))
+    .buildNetworks((b) =>
+      b
+        .addNetwork({
+          name: "clock",
+          type: ConfigNetworkType.TEST,
+          startTime: START_TIME,
+          blockTimeMS: BLOCK_TIME_MS,
+        })
+        .addNetwork({
+          name: "chainDense",
+          type: ConfigNetworkType.TEST,
+          startTime: START_TIME,
+          blockTimeMS: DENSE_BLOCK_MS,
+        })
+    )
+    .buildDeployments((b) => b)
+    .buildSyncProtocols((b) =>
+      b
+        .addMain(
+          (n) => n.clock,
+          () => ({
+            name: MAIN_1D,
+            type: ConfigSyncProtocolType.TEST_MAIN,
+            startBlockHeight: 1,
+            pollingInterval: 30,
+            stepSize: DENSE_STEP,
+            maxBufferedPages: 200,
+          }),
+        )
+        .addParallel(
+          (n) => (n as any).chainDense,
+          () => ({
+            name: PAR_1D,
+            type: ConfigSyncProtocolType.TEST_PARALLEL,
+            startBlockHeight: 1,
+            pollingInterval: 30,
+            stepSize: DENSE_STEP,
+            delayMs: 0,
+            events: [],
+            maxBufferedPages: CAP_1D,
+          }),
+        )
+    )
+    .buildPrimitives((b) =>
+      b.addPrimitive(
+        (sp) => (sp as any)[PAR_1D],
+        () => ({ name: "noEvt1d", type: TEST_PRIMITIVE_TYPE, startBlockHeight: 1 }),
+      )
+    )
+    .build();
+}
+
+test("1d: a parallel chain denser than the cap does NOT deadlock the merge", async () => {
+  TestChainControl.setTip(MAIN_1D, 60);
+  TestChainControl.setTip(PAR_1D, 10_000);
+
+  const node = await h.runNode({ config: buildConfig1d(), apiPort: 19144 });
+  const samples: BufSample[] = [];
+  let peakPar = 0;
+  let lastApplied = 0;
+  try {
+    const startMs = Date.now();
+    // Generous for slow CI; exits early once the liveness target is reached.
+    const deadline = startMs + 30_000;
+    while (Date.now() < deadline) {
+      const wall = Date.now();
+      const mainBuf = bufferSize(node, MAIN_1D);
+      const parBuf = bufferSize(node, PAR_1D);
+      const appliedBlock = await latestFinalizedHeight(h.pool);
+      samples.push({
+        t: wall - startMs,
+        wall,
+        mainBuf,
+        evmBuf: parBuf,
+        mainOwnBlock: ownBlock(node, MAIN_1D),
+        evmOwnBlock: ownBlock(node, PAR_1D),
+        rss: process.memoryUsage().rss,
+        appliedBlock,
+      });
+      peakPar = Math.max(peakPar, parBuf);
+      lastApplied = appliedBlock ?? lastApplied;
+      if (lastApplied >= LIVE_TARGET_1D) break;
+      await sleep(50);
+    }
+  } finally {
+    writeArtifact("buffering-1d", samples, {
+      mode: "1d-density-deadlock",
+      stepSize: SMALL_STEP,
+      denseBlockMs: DENSE_BLOCK_MS,
+      perSlot: PER_SLOT,
+      cap: CAP_1D,
+      liveTarget: LIVE_TARGET_1D,
+      peakParBuf: peakPar,
+      lastApplied,
+    });
+    await node.stop();
+  }
+
+  // Liveness: the node produces blocks (no wedge on block 1).
+  expect(lastApplied).toBeGreaterThanOrEqual(LIVE_TARGET_1D);
+  // Bounded by the per-slot need: ~one slot of parallel data plus one chunk.
+  expect(peakPar).toBeLessThanOrEqual(DENSE_BUFFER_BOUND);
+}, 60_000);

package/test/reproduction/coalesce.test.ts

@@ -0,0 +1,133 @@
+/** E2E: coalesced vs non-coalesced syncs produce the same DB; resume through coalescing matches a clean run. */
+import { expect, test } from "bun:test";
+import { setupHarness } from "./harness.ts";
+import {
+  compareConsistencySnapshots,
+  type ConsistencySnapshot,
+  dumpConsistencySnapshot,
+  type SnapshotDiff,
+  type SnapshotOpts,
+  SYNC_BOOKKEEPING_TABLES,
+} from "./consistency-snapshot.ts";
+
+function summarize(snap: ConsistencySnapshot): string {
+  let rows = 0;
+  for (const f of snap.values()) rows += f.rowCount;
+  return `${snap.size} tables, ${rows} rows`;
+}
+
+function formatDiffs(diffs: SnapshotDiff[]): string {
+  return diffs
+    .map((d) => `${d.table} [${d.reason} A=${d.aRows ?? "—"} B=${d.bRows ?? "—"}]`)
+    .join(", ");
+}
+
+function logComparison(
+  tag: string,
+  aLabel: string,
+  a: ConsistencySnapshot,
+  bLabel: string,
+  b: ConsistencySnapshot,
+  diffs: SnapshotDiff[],
+): void {
+  console.log(tag);
+  console.log(`${tag}   ${aLabel}: ${summarize(a)}`);
+  console.log(`${tag}   ${bLabel}: ${summarize(b)}`);
+  console.log(
+    diffs.length === 0
+      ? `${tag}   → IDENTICAL (0 differences)`
+      : `${tag}   → ${diffs.length} diff(s): ${formatDiffs(diffs)}`,
+  );
+}
+
+test(
+  "coalesced and non-coalesced from-scratch syncs produce identical databases",
+  async () => {
+    const events = [
+      { atBlock: 25, marker: "e25" },
+      { atBlock: 50, marker: "e50" },
+      { atBlock: 75, marker: "e75" },
+    ];
+
+    const runOnce = async (
+      coalesce: boolean,
+      apiPort: number,
+    ): Promise<ConsistencySnapshot> => {
+      const h = await setupHarness();
+      try {
+        await h.runToHeight({
+          events,
+          tips: { mainClock: 100, parallelP: 200 },
+          target: 100,
+          apiPort,
+          coalesce,
+        });
+        return await dumpConsistencySnapshot(h.pool);
+      } finally {
+        await h.teardown();
+      }
+    };
+
+    const off = await runOnce(false, 19160);
+    const on = await runOnce(true, 19161);
+
+    const { diffs } = compareConsistencySnapshots(off, on);
+    logComparison("[coalesce A] from-scratch sync to height 100:", "coalesce OFF", off, "coalesce ON", on, diffs);
+    expect(diffs).toEqual([]);
+  },
+  120_000,
+);
+
+test(
+  "a coalesced sync that resumes matches a clean coalesced sync",
+  async () => {
+    const events = [{ atBlock: 20, marker: "gap20" }];
+    const parallelStepSize = 1000;
+    const dumpOpts: SnapshotOpts = { excludeTables: SYNC_BOOKKEEPING_TABLES };
+
+    const ref = await setupHarness();
+    let refSnap: ConsistencySnapshot;
+    try {
+      await ref.runToHeight({
+        events,
+        parallelStepSize,
+        tips: { mainClock: 30, parallelP: 50 },
+        target: 30,
+        apiPort: 19170,
+        coalesce: true,
+      });
+      refSnap = await dumpConsistencySnapshot(ref.pool, dumpOpts);
+    } finally {
+      await ref.teardown();
+    }
+
+    const resumed = await setupHarness();
+    let resumeSnap: ConsistencySnapshot;
+    try {
+      await resumed.runToHeight({
+        events,
+        parallelStepSize,
+        tips: { mainClock: 10, parallelP: 50 },
+        target: 10,
+        apiPort: 19171,
+        coalesce: true,
+      });
+      await resumed.runToHeight({
+        events,
+        parallelStepSize,
+        tips: { mainClock: 30, parallelP: 50 },
+        target: 30,
+        apiPort: 19172,
+        coalesce: true,
+      });
+      resumeSnap = await dumpConsistencySnapshot(resumed.pool, dumpOpts);
+    } finally {
+      await resumed.teardown();
+    }
+
+    const { diffs } = compareConsistencySnapshots(refSnap, resumeSnap);
+    logComparison("[coalesce B] clean vs resumed coalesced sync to height 30:", "clean ref", refSnap, "resumed", resumeSnap, diffs);
+    expect(diffs).toEqual([]);
+  },
+  120_000,
+);

package/test/reproduction/harness.ts

@@ -305,6 +305,8 @@ export type RunToHeightOpts = {
   /** Optional per-protocol page watermarks to also wait for before exiting. */
   waitPages?: Record<string, number>;
   securityNamespace?: string;
+  /** Enable/disable empty-block coalescing. */
+  coalesce?: boolean;
 };
 
 const RUNNER = join(import.meta.dir, "node-runner.ts");
@@ -329,6 +331,7 @@ function makeRunToHeight(
       target: opts.target,
       apiPort: opts.apiPort,
       waitPages: opts.waitPages,
+      coalesce: opts.coalesce,
     };
     return new Promise<void>((resolve, reject) => {
       const child = spawn("bun", [RUNNER, JSON.stringify(spec)], {

package/test/reproduction/node-runner.ts

@@ -48,6 +48,7 @@ export type RunSpec = {
    * ahead and persisted its page row before we kill the process.
    */
   waitPages?: Record<string, number>;
+  coalesce?: boolean;
 };
 
 const noopStf: StartConfigGameStateTransitions = function* () {};
@@ -60,6 +61,7 @@ async function main() {
   // broker (it binds fixed ports and isn't freed on halt) and a per-run API port.
   process.env.MQTT_BROKER = "false";
   process.env.EFFECTSTREAM_API_PORT = String(spec.apiPort);
+  process.env.EFFECTSTREAM_COALESCE_EMPTY_BLOCKS = spec.coalesce ? "true" : "false";
   const isPglite = process.env.PGLITE === "true";
 
   for (const [name, tip] of Object.entries(spec.tips)) {