fix(portal): emit per-chain metrics file on a 0-block window (#140)

[dzhelezov]

Fixes #140.

Mechanism

syncBlockData early-returns at the blockArr.length === 0 guard before the writeMetrics(...) call, so a chain that streams 0 blocks in a sync window never writes its portal-metrics.<chainId> file. Any consumer expecting one metrics file per configured chain then fails with metrics file not found: portal-metrics.<chainId>.

Where it shows up: running the keyless euler-multichain example, base (8453) and arbitrum (42161) stream 0 blocks in the small default window (their factory-discovered events fall outside it), so their metrics files are absent and the run is un-gate-able. All chains do backfill via the Portal (rpc_fallback=0) — only the metrics-file emission is skipped. Indexing correctness is unaffected; this is an observability/DX gap.

Fix

Extract the writeMetrics({...}) args into a single emitMetrics() closure — one source of truth for the arg shape — and invoke it on both syncBlockData exits: the normal insert path and the 0-block early return. writeMetrics overwrites ${metricsFile}.${chain.id} (last-write-wins) and reads the live cumulative stats, so the 0-block file carries the same FROZEN schema with honest zero counts (inserted.blocks=0, rpcFallbackIntervals=0). The early-out (nothing to insert for 0 blocks) is preserved. No duplication of the arg object, so the two call sites cannot diverge.

The !s path (interval not Portal-served / RPC-delegated) is deliberately untouched — it did not write metrics before and still doesn't; only the "Portal served this interval but it assembled 0 blocks" branch is fixed, which is exactly the issue's case.

Mutation-verified regression test

portal/portal.test.ts — regression (#140): a chain that streams 0 blocks in its window STILL emits a per-chain metrics file (blocks=0). Drives a Portal-served in-range window [0, 5000] that assembles 0 blocks (header-only anchor, no matched data), sets PORTAL_METRICS_FILE, runs syncBlockRangeData + syncBlockData, asserts the precondition inserted.blocks == 0 (proving the buggy early-return path is reached), then asserts the per-chain file exists with the zero-window schema.

Mutation verification (in the grafted 0.16.8 tree — my repo tree stayed clean):

• RED — removed emitMetrics() from the early-return branch (the old code): test FAILS at expect(existsSync(perChainFile)).toBe(true) → expected false to be true (file absent), vitest EXIT=1.
• GREEN — restored the fix: test PASSES, EXIT=0.

Both-version gates (scripts/sync-upstream.sh <ver> --test)

version	Test Files	Tests	portal.test.ts	EXIT
0.16.8	16 passed	313 passed	58 tests	0
0.16.6	16 passed	313 passed	58 tests	0

biome check . clean (error-level, pinned @biomejs/biome@2.5.2).

🤖 Generated with Claude Code