@effectstream/runtime 0.100.19 → 0.100.20

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.20",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,17 +13,17 @@
   },
   "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.20",
+    "@effectstream/config": "0.100.20",
+    "@effectstream/coroutine": "0.100.20",
+    "@effectstream/crypto": "0.100.20",
+    "@effectstream/db": "0.100.20",
+    "@effectstream/event-client": "0.100.20",
+    "@effectstream/event-server": "0.100.20",
+    "@effectstream/log": "0.100.20",
+    "@effectstream/sm": "0.100.20",
+    "@effectstream/sync": "0.100.20",
+    "@effectstream/utils": "0.100.20",
     "@fastify/cors": "^11.0.1",
     "@metamask/json-rpc-engine": "^10.0.3",
     "pg": "8.17.2",

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

@@ -32,6 +32,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,9 +93,12 @@ 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>();
 
@@ -148,9 +152,36 @@ 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;
+  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;
+
     // 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

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