fix(portal): head-clamp ceilings, construction-time discovery floor, extend-local field checks, trace receipts, head-pin (bug-hunt wave 2A) [WIP: source only]

Five correctness fixes from a triple-blind bug hunt. SOURCE changes only in this
commit; regression tests + INVARIANTS.md rows + mutation-verification are follow-up
(see the WIP PR body). Two of the five were empirically reproduced (BUG-A discovery
floor, BUG-B head-clamp).

FIX 1 — head-clamp root cause (BUG-B). dataEnd() = min(backfillEnd??∞, portalHead??∞)
so desiredTo/coveredTo/endHint/raEnd are all head-clamped even when every source is
bounded; removed the `spec.backfillEnd !== undefined` escape from the INV-9 assert
(now strictly stronger — holds by construction).

FIX 2 — discovery floor at construction (BUG-A). Floor derived from the spec
(min over factories of fromBlock ?? 0), pinned at construction and re-pinned per call
before any fetch; requiredFactoryIntervals/interval-start only refine it downward.
Dropped the `discStartIdx === undefined` escapes from the INV-3 asserts.

FIX 3 — extend-local neededMissing. The needed-field crash check now compares the
matched-data map sizes before/after THIS runStreams call, so a data-bearing base +
event-less extend tail (dataset lacking a needed column) is tolerated, not crash-looped.

FIX 4 — trace/transfer receipts. buildTraces now emits toSyncReceipt for matched trace
txs when a trace/transfer filter has hasTransactionReceipt (deduped by hash across all
branches), so buildEvents no longer throws "Missing transaction receipt".

FIX 5 — PORTAL_FINALIZED_HEAD pin. ensureChunkSize only adopts the live probe as the
head when there is no pin (scaling still uses the live value), so the pin governs
finality/delegation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dzhelezov

portal/portal-assemble.ts

@@ -165,12 +165,15 @@ const buildMatchers = (
   };
 };
 
-/** Per-chunk trace assembly: full-tree ranking then client-side filtering (INV-5). */
+/** Per-chunk trace assembly: full-tree ranking then client-side filtering (INV-5). `onReceipt` (FIX 4)
+ * is invoked with each MATCHED trace's parent transaction so the caller can emit a receipt when a
+ * trace/transfer filter has `hasTransactionReceipt` — the log/tx branches never see these txs. */
 const buildTraces = (
   cd: ChunkData,
   lo: number,
   hi: number,
   matchers: Matchers,
+  onReceipt?: (rawTx: RawTx, header: RawHeader) => void,
 ): { trace: SyncTrace; block: SyncBlock; transaction: SyncTransaction }[] => {
   const out: {
     trace: SyncTrace;
@@ -195,6 +198,7 @@ const buildTraces = (
       const rawTx = txByIdx.get(txIndex);
       for (const { frame } of rankTraces(traces)) {
         if (!matchers.traceMatched(frame, bn)) continue;
+        if (rawTx) onReceipt?.(rawTx, tb.header); // FIX 4: receipt for the matched trace's tx
         out.push({
           trace: {
             trace: frame,
@@ -243,6 +247,15 @@ export function assembleRange(
   const syncTxs: SyncTransaction[] = [];
   const syncReceipts: SyncTransactionReceipt[] = [];
   const seenTx = new Set<string>();
+  // FIX 4: receipts are deduped by tx hash across ALL branches (log, tx-filter, trace/transfer) — a tx
+  // matched by more than one source must yield exactly one receipt row.
+  const seenReceipt = new Set<string>();
+  const pushReceipt = (raw: RawTx, hdr: RawHeader): void => {
+    if (!raw.hash || seenReceipt.has(raw.hash)) return;
+
+    seenReceipt.add(raw.hash);
+    syncReceipts.push(toSyncReceipt(raw, hdr));
+  };
 
   // INV-2 is enforced BY CONSTRUCTION here: every emitting branch below sits behind the single
   // `inRange` predicate (there is deliberately no redundant per-row assert — it could never fire),
@@ -258,7 +271,7 @@ export function assembleRange(
           if (tx.hash && !seenTx.has(tx.hash)) {
             seenTx.add(tx.hash);
             syncTxs.push(toSyncTransaction(tx, hdr));
-            if (spec.needReceipts) syncReceipts.push(toSyncReceipt(tx, hdr));
+            if (spec.needReceipts) pushReceipt(tx, hdr);
           }
       }
     }
@@ -285,13 +298,20 @@ export function assembleRange(
           if (raw.hash) seenTx.add(raw.hash);
           blocksByNumber.set(bn, toSyncBlockHeader(tb.header));
           syncTxs.push(tx);
-          if (spec.needReceipts)
-            syncReceipts.push(toSyncReceipt(raw, tb.header));
+          if (spec.needReceipts) pushReceipt(raw, tb.header);
         }
       }
 
+  // FIX 4: a trace/transfer filter with hasTransactionReceipt needs a receipt for every matched trace tx;
+  // those txs ride on the trace query (fields include RECEIPT_FIELDS when needReceipts) and are seen by no
+  // other branch, so emit them here (deduped via pushReceipt). Without this, buildEvents throws
+  // "Missing transaction receipt" on a legit trace-receipt config.
+  const needTraceReceipts =
+    spec.traceFilters.some((f) => f.hasTransactionReceipt) ||
+    spec.transferFilters.some((f) => f.hasTransactionReceipt);
+  const onTraceReceipt = needTraceReceipts ? pushReceipt : undefined;
   const traces = spec.needTraces
-    ? chunks.flatMap((cd) => buildTraces(cd, lo, hi, matchers))
+    ? chunks.flatMap((cd) => buildTraces(cd, lo, hi, matchers, onTraceReceipt))
     : [];
 
   // C9: highest block with data — a LOOP (Math.max(...spread) RangeErrors on ~100k+ keys) — INCLUDING

portal/portal.ts

@@ -124,13 +124,42 @@ export const createPortalHistoricalSync = (
   const delegated = new Set<string>(); //        interval keys routed to RPC (finality gap)
   let chunkBlocks = cfg.chunkBlocks;
   let chunkSizeP: Promise<void> | undefined;
-  let discStartIdx: number | undefined; // factory-deploy chunk = discovery floor (C4: clamps DOWNWARD)
   let portalHead: number | undefined = cfg.finalizedHead;
   let startTime = 0;
 
+  // FIX 2 (INV-3/INV-15): the discovery floor is the earliest block ANY factory could create a child —
+  // `min` over the compiled spec's factories of `fromBlock ?? 0` (undefined ⇒ genesis). It is a property
+  // of the SPEC, not of the intervals ponder happens to still need, so it is pinned at CONSTRUCTION (and
+  // re-pinned per call, since chunkBlocks can scale) — see `pinDiscoveryFloor`. `discFloorBlock` is the
+  // downward-clamped floor BLOCK (grid-independent, so it survives a rescale); requiredFactoryIntervals /
+  // the interval start only REFINE it downward (C4/INV-4).
+  const specFloorBlock =
+    spec.factories.length > 0
+      ? Math.min(...spec.factories.map((f) => f.fromBlock ?? 0))
+      : undefined;
+  let discFloorBlock = specFloorBlock;
+
   const ikey = (i: Interval): string => `${i[0]}-${i[1]}`;
+  // FIX 1 (INV-9/INV-13): the data ceiling is the LOWER of the configured backfill end and the live Portal
+  // head — clamp BOTH. With every source bounded (`backfillEnd` defined) the old `backfillEnd ?? portalHead`
+  // ignored the head, so a frontier chunk's `desiredTo`/`coveredTo` extended PAST the head; the Portal
+  // 204s/truncates above its head, `coveredTo` recorded phantom coverage, and once the head advanced later
+  // intervals blind-hit the stale cache and were marked synced EMPTY (permanent silent gap). Clamping here
+  // flows to desiredTo, coveredTo, endHint and raEnd, and re-arms the INV-13 extend as the head advances.
   const dataEnd = (): number =>
-    spec.backfillEnd ?? portalHead ?? Number.POSITIVE_INFINITY;
+    Math.min(
+      spec.backfillEnd ?? Number.POSITIVE_INFINITY,
+      portalHead ?? Number.POSITIVE_INFINITY,
+    );
+
+  // FIX 2: snap `discFloorBlock` to the current grid and install it as the discovery floor. Idempotent —
+  // called at construction and again on every syncBlockRangeData before any fetch (chunkBlocks may have
+  // scaled since). No-op when there are no factories.
+  const pinDiscoveryFloor = (): void => {
+    if (discFloorBlock === undefined) return;
+
+    discovery.setFloor(idxOf(discFloorBlock, chunkBlocks) * chunkBlocks);
+  };
 
   // finality-gap fallback: Portal serves only finalized data, and its finalized head can (rarely) lag
   // Ponder's target. Any interval reaching past the head is delegated whole to the stock RPC sync.
@@ -161,7 +190,12 @@ export const createPortalHistoricalSync = (
 
       const h = await client.finalizedHead();
       if (h !== undefined) {
-        portalHead = h;
+        // FIX 5: a live probe drives chunk SCALING, but it must NOT overwrite an explicit
+        // PORTAL_FINALIZED_HEAD pin — the pin is authoritative for the finality/delegation decision, and
+        // clobbering it here (which happened whenever the pin was set but PORTAL_CHUNK_FIXED was not) let
+        // intervals above the pin but below the live head be served instead of delegated. Only adopt the
+        // probe as the head when there is no pin; scaling may still use the live `h`.
+        if (cfg.finalizedHead === undefined) portalHead = h;
         chunkBlocks = scaleChunkBlocks(cfg.chunkBlocks, h);
         log.debug({
           service: 'portal',
@@ -184,6 +218,17 @@ export const createPortalHistoricalSync = (
     token: RowToken,
   ): Promise<void> => {
     const neededMissing = new Set<string>();
+    // FIX 3: the needed-field crash check must consider ONLY the rows THIS call adds. On a frontier EXTEND
+    // `cd` already carries the base chunk's data; the tail streams the disjoint range (coveredTo, desiredTo]
+    // whose block numbers are all > coveredTo (new map keys), so a size delta captures exactly the tail's
+    // matched rows. Inspecting the whole accumulated `cd` (as before) let a data-bearing base + an
+    // event-less tail whose dataset lacks a needed column throw fatally → evict → crash-loop on retry.
+    const matchedSize = (): number =>
+      cd.logs.size +
+      cd.traceBlocks.size +
+      cd.txBlocks.size +
+      cd.blockHeaders.size;
+    const matchedBefore = matchedSize();
     const onRows = (n: number): void => {
       if (token.freed) return;
 
@@ -268,15 +313,10 @@ export const createPortalHistoricalSync = (
               });
           }
       }
-    // A NEEDED field the dataset lacked on THIS range: crash ONLY IF the chunk yielded MATCHED data —
-    // an event the indexer processes would be incomplete. Event-less (old/irrelevant) ranges proceed.
-    if (
-      neededMissing.size &&
-      (cd.logs.size ||
-        cd.traceBlocks.size ||
-        cd.txBlocks.size ||
-        cd.blockHeaders.size)
-    ) {
+    // A NEEDED field the dataset lacked on THIS range: crash ONLY IF this call added MATCHED data — an
+    // event the indexer processes would be incomplete. An event-less (old/irrelevant) range — or an
+    // event-less EXTEND tail over a data-bearing base (FIX 3) — proceeds.
+    if (neededMissing.size && matchedSize() > matchedBefore) {
       throw new Error(
         `Portal dataset for ${chain.name} is missing [${[...neededMissing].join(', ')}] on blocks [${from},${to}], which contain matched data your indexer needs — a Portal dataset-completeness gap. Failing fast rather than serving incomplete data; report the gap to SQD, or start your indexer past the affected range.`,
       );
@@ -294,19 +334,21 @@ export const createPortalHistoricalSync = (
       spec.backfillStart,
       dataEnd(),
     );
-    // INV-9: a Portal data request never targets past the known finalized head (an explicit backfill
-    // toBlock may exceed it by configuration — the delegation branch already guards served intervals).
+    // INV-9: a Portal data request never targets past the known finalized head. `dataEnd()` now clamps to
+    // the head (FIX 1), so `desiredTo <= portalHead` holds BY CONSTRUCTION whenever the head is known — the
+    // former `spec.backfillEnd !== undefined` escape (which let a bounded backfill over-reach) is gone and
+    // this assert is a strictly stronger tripwire. Intervals past the head are already delegated to RPC.
     invariant(
       'INV-9',
-      portalHead === undefined ||
-        desiredTo <= portalHead ||
-        spec.backfillEnd !== undefined,
+      portalHead === undefined || desiredTo <= portalHead,
       'data request targets past the Portal finalized head',
       () => ({ idx, desiredTo, portalHead }),
     );
+    // Discovery scans as far as the backfill will need in one pass; head-clamped (FIX 1) via dataEnd().
+    const de = dataEnd();
     const ensureOpts = {
       chunkBlocks,
-      endHint: spec.backfillEnd ?? portalHead ?? desiredTo,
+      endHint: Number.isFinite(de) ? de : desiredTo,
     };
 
     const cached = dataCache.get(idx);
@@ -332,11 +374,12 @@ export const createPortalHistoricalSync = (
       const extended = (async (): Promise<ChunkData> => {
         const cd = await prev;
         await discovery.ensure(desiredTo, ensureOpts); // discovery must reach the extended tail too
+        // FIX 2: the floor is pinned from the spec at construction, so a factory sync always has a floor —
+        // the former `discStartIdx === undefined` escape (which silently disabled this check on the very
+        // chunks that fetched before requiredFactoryIntervals arrived) is gone.
         invariant(
           'INV-3',
-          spec.factories.length === 0 ||
-            discStartIdx === undefined ||
-            discovery.through() >= desiredTo,
+          spec.factories.length === 0 || discovery.through() >= desiredTo,
           'chunk extend under a stale discovery watermark',
           () => ({ idx, through: discovery.through(), desiredTo }),
         );
@@ -358,11 +401,10 @@ export const createPortalHistoricalSync = (
     const token: RowToken = { rows: 0, freed: false };
     const p = (async (): Promise<ChunkData> => {
       await discovery.ensure(desiredTo, ensureOpts); // children ≤ this chunk are known (INV-3)
+      // FIX 2: floor pinned from the spec at construction ⇒ no `discStartIdx === undefined` escape (see extend).
       invariant(
         'INV-3',
-        spec.factories.length === 0 ||
-          discStartIdx === undefined ||
-          discovery.through() >= desiredTo,
+        spec.factories.length === 0 || discovery.through() >= desiredTo,
         'data fetch under a stale discovery watermark',
         () => ({ idx, through: discovery.through(), desiredTo }),
       );
@@ -400,6 +442,10 @@ export const createPortalHistoricalSync = (
     }
   };
 
+  // FIX 2: pin the discovery floor from the spec NOW, before the first fetch (re-pinned per call once
+  // chunkBlocks is finalized). A no-op when there are no factory sources.
+  pinDiscoveryFloor();
+
   return {
     async syncBlockRangeData(params) {
       const { interval, requiredFactoryIntervals, syncStore } = params;
@@ -454,28 +500,25 @@ export const createPortalHistoricalSync = (
         chunkBlocks = capped;
         for (const entry of dataCache.values()) freeToken(entry.token);
         dataCache.clear();
-        discStartIdx = undefined;
-        discovery.reset();
+        discovery.reset(); // discFloorBlock (block-space) survives; re-pinned to the new grid just below
         log.debug({
           service: 'portal',
           msg: `Portal ${chain.name}: dense sources → chunkBlocks capped to ${chunkBlocks} (grid reset)`,
         });
       }
 
-      // pin the discovery floor at the factory's real start (NOT block 0). C4: clamp DOWNWARD only.
-      if (requiredFactoryIntervals.length > 0) {
-        const floor = idxOf(
-          Math.min(
-            ...requiredFactoryIntervals
-              .map((r) => r.interval[0])
-              .concat(interval[0]),
-          ),
-          chunkBlocks,
+      // FIX 2: (re-)pin the discovery floor BEFORE any fetch. Base floor = the spec's earliest factory
+      // start (`discFloorBlock`, seeded at construction); requiredFactoryIntervals and the interval start
+      // only REFINE it downward (C4/INV-4). Applied on EVERY call (not just when ponder hands over
+      // requiredFactoryIntervals) so an early spanning-chunk fetch never runs without discovery.
+      if (discFloorBlock !== undefined) {
+        discFloorBlock = Math.min(
+          discFloorBlock,
+          interval[0],
+          ...requiredFactoryIntervals.map((r) => r.interval[0]),
         );
-        discStartIdx =
-          discStartIdx === undefined ? floor : Math.min(discStartIdx, floor);
-        discovery.setFloor(discStartIdx * chunkBlocks);
       }
+      pinDiscoveryFloor();
 
       const startIdx = idxOf(interval[0], chunkBlocks);
       const endIdx = idxOf(interval[1], chunkBlocks);