feat(realtime): RT-2 — isolated-cutover finality floor (INV-25, RG0 INERT)

The isolated single-chain historical→realtime cutover clamp
(getHistoricalEventsIsolated) now passes floor = params.syncProgress
.finalized.number to clampFinalizedToPortalHead, mirroring the
multichain/omnichain cutover sites. Added to all 5 wiring patches
(0.15.17–0.16.9), added block byte-identical; hunk headers rebalanced.

CANDID: the floor is INERT defense-in-depth / doc-parity. RG0 proved the
isolated path is already safe via the upstream break-before-adopt guard
(delta <= finalityBlockCount ⇒ break, before the boundary assignment): a
stale-LOW probe yields a negative delta and is never adopted regardless
of the floor. Since floor equals the guard's compare value, the floor
MASKS a guard mutation — so the test pins the guard INDEPENDENTLY of the
floor rather than through the real path (which would be vacuous, per RG0):
  Pin A pins the shipped floor; Pin B pins the load-bearing guard.

Mutation-verified: M1 (drop the floor line) fails Pin A only; M2 (weaken
the guard <= → >=) fails Pin B only — the pins are independent.

INVARIANTS.md: add INV-25. Plan: mark RT-2 landed in RG1 + the RT-G13
register disposition (PR number left as #NNN for the merge gate).

Gates: scripts/sync-upstream.sh {0.16.6,0.15.17} --test → 361 passed each
(cutover-guard 42 tests); biome check portal/ --diagnostic-level=error → 0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dzhelezov

.agents/plans/stream-realtime-production.md

@@ -35,7 +35,7 @@ and nowhere else; it is gated on the complete dossier, not on judgment.
 | Gate | Name | One-line exit criterion |
 |------|------|------------------------|
 | RG0 | Ground truth ratified | This plan merged; RT-G13 (cutover floor) verified true-bug-or-not with a written verdict. **MET** — plan merged ([#157](../../pull/157)); RT-G13 verified **INERT / NOT-A-BUG** (upstream guards isolated adoption — verdict in the RT-G13 register entry below), so RT-2 reclassifies to should-fix (defense / doc-parity). |
-| RG1 | Must-fix code landed | RT-1/RT-2/RT-3 merged: mutation-verified tests, committee review, both-version gates green |
+| RG1 | Must-fix code landed | RT-1/RT-2/RT-3 merged: mutation-verified tests, committee review, both-version gates green. RT-1 ([#161](../../pull/161)) + RT-3 ([#162](../../pull/162)) merged; **RT-2 landed** ([#163](../../pull/163)) — isolated-cutover finality `floor` shipped for parity across all 5 wiring patches (INV-25), test pins the load-bearing break-before-adopt guard INDEPENDENTLY of the inert floor (M1/M2 mutation-verified), both-version `--test` gates green (361 passed each). |
 | RG2 | Fail-loud audit complete | Fatal-injection suite + silent-gap fuzzer green in CI; no enumerated silent path survives |
 | RG3 | Realtime chaos passed | ≥200 kills across ≥6 timing classes, 100 % clean resumes, byte-identical digests. **MET (Phase A, [#158](../../pull/158))** — 238 kills / 7 timing-class sub-runs, 238/238 clean, byte-identical, 0 dup FINALIZED; K6-cutover + K2-spread non-vacuity self-certified. Numbers + candid mock-fidelity caveats in VALIDATION §5.11. |
 | RG4 | Multichain stream soak passed | ≥72 h multi-chain stream soak (incl. one fast chain + omnichain), crash drills clean, parity clean |
@@ -226,7 +226,7 @@ gates RG1), **should-fix** (lands during the campaign, doesn't gate the label by
 | RT-G10 | must-fix | RT-1 (progress watchdog) |
 | RT-G11 | must-fix | RT-1 (read idle bound → reconnect) |
 | RT-G12 | must-fix | RT-1 (poll decoupled from delivery) |
-| RT-G13 | verified INERT (RG0) → should-fix | RT-2 (floor for parity; test pins the upstream guard, not the floor) |
+| RT-G13 | verified INERT (RG0) → should-fix → **LANDED (RT-2, [#163](../../pull/163))** | RT-2 (floor shipped for parity across all 5 wiring patches → INV-25; Pin A pins the floor, Pin B pins the upstream break-before-adopt guard, mutation-verified independent — M1 fails Pin A only, M2 fails Pin B only) |
 | RT-G14 | evidence | RG3 |
 | RT-G15 | evidence | RG3 K5 + RG2 seam test |
 
@@ -280,6 +280,16 @@ mirroring the multichain site.
 cutover the boundary does not regress (fails with the floor removed); if RG0 verification shows
 upstream already guards adoption, the test instead pins the guard and the change is documentation-
 parity. Both-version gates; the patches for all pinned versions updated together.
+**Status — LANDED ([#163](../../pull/163)).** RG0 confirmed the isolated path is already INERT-safe
+(break-before-adopt guard), so RT-2 shipped the `floor` for cross-site parity + defense-in-depth (INV-25)
+across all 5 wiring patches (0.15.17–0.16.9, added `+` block byte-identical). Per RG0 the test does NOT
+assert the boundary through the real path (the floor equals the guard's compare value, so it MASKS a guard
+mutation → a behavioral test would be vacuous); instead `portal-cutover-guard.test.ts`
+"INV-25 / RT-2: isolated-cutover finality floor" pins the two protections INDEPENDENTLY at the grafted
+source — **Pin A** the shipped floor, **Pin B** the load-bearing break-before-adopt guard. Mutation-verified:
+M1 (drop the floor line) fails Pin A only; M2 (weaken the guard `<=`→`>=`) fails Pin B only — the pins are
+independent. Both-version `--test` gates green (0.16.6 + 0.15.17, 361 passed each; cutover-guard 42 tests);
+biome clean.
 
 ### RT-3 — RING_CAP headroom + eviction-path proof (RT-G2)
 

portal/INVARIANTS.md

@@ -803,3 +803,82 @@ describe('INV-18: wiring pins (grafted runtime/historical.ts)', () => {
     );
   });
 });
+
+// ─────────────────── INV-25 / RT-2: isolated-cutover finality floor (grafted wiring pins) ───────────────────
+//
+// RT-2 lands the `floor` on the isolated single-chain cutover clamp so it mirrors the multichain/omnichain
+// sites (documentation-parity / defense-in-depth). CANDID DESIGN NOTE — the floor is INERT here:
+// `floor = params.syncProgress.finalized.number` is the SAME value the break-before-adopt guard just below
+// compares against, so it can only clamp a stale-LOW probe UP to exactly the previously-adopted boundary —
+// a no-op relative to that boundary. The LOAD-BEARING protection against a below-boundary adoption is the
+// upstream guard (`… <= params.chain.finalityBlockCount ⇒ break;`), which refuses to adopt a non-advancing
+// (stale-LOW ⇒ negative-delta) boundary at all. Because the floor MASKS a guard-weakening mutation (drop
+// the guard and the floor still prevents a below-boundary clamp OUTPUT), a behavioral test through the real
+// isolated path would be VACUOUS — so per RG0 the two protections are pinned INDEPENDENTLY at the source:
+//   Pin A pins the SHIPPED floor (the parity change); Pin B pins the LOAD-BEARING guard.
+// Both read the grafted `runtime/historical.ts` (byte-identical across all pinned versions) and slice the
+// isolated function body [getHistoricalEventsIsolated, refetchHistoricalEvents) so a pin can never match the
+// multichain/omnichain clamp (which use `floor: hexToNumber( params.perChainSync.get(...)…`).
+
+describe('INV-25 / RT-2: isolated-cutover finality floor', () => {
+  const historical = readFileSync(
+    join(__dirname, '..', 'runtime', 'historical.ts'),
+    'utf8',
+  );
+
+  // The function AFTER getHistoricalEventsIsolated is refetchHistoricalEvents (not getLocalSyncGenerator —
+  // two refetch/generator helpers sit between them). Slicing to its start bounds the isolated body exactly.
+  const isolatedStart = historical.indexOf('getHistoricalEventsIsolated');
+  const isolatedEnd = historical.indexOf('refetchHistoricalEvents');
+  const isolated = historical.slice(isolatedStart, isolatedEnd);
+
+  test('the slice bounds are sane (isolated body is non-empty and precedes refetchHistoricalEvents)', () => {
+    expect(isolatedStart).toBeGreaterThan(-1);
+    expect(isolatedEnd).toBeGreaterThan(isolatedStart);
+    // The isolated body must contain its own cutover clamp — the site RT-2 edits.
+    expect(isolated).toContain('clampFinalizedToPortalHead({');
+  });
+
+  // ── Pin A: the SHIPPED parity change. The isolated cutover clamp now carries the finality floor.
+  //    Scoped to `isolated` so it cannot match the multichain/omnichain sites (whose floor reads from
+  //    `params.perChainSync.get(...)`, not `params.syncProgress` — the single-chain isolated form).
+  //    MUTATION RECIPE (M1): delete the `floor: hexToNumber(params.syncProgress.finalized.number),` line
+  //    from the isolated clamp in the wiring patch → this pin FAILS (Pin B still passes — they are
+  //    independent; the floor is inert so no behavioral test could catch its removal).
+  test('Pin A (shipped parity): the isolated cutover clamp carries floor = hexToNumber(params.syncProgress.finalized.number)', () => {
+    expect(isolated).toContain(
+      'floor: hexToNumber(params.syncProgress.finalized.number),',
+    );
+  });
+
+  // ── Pin B: the LOAD-BEARING guard (RG0). The isolated path BREAKS-BEFORE-ADOPT on the finality-delta
+  //    guard; the boundary assignment `params.syncProgress.finalized =` sits AFTER that guarded break, so a
+  //    stale-LOW (non-advancing) probe is never adopted. This — NOT the inert floor above — is what prevents
+  //    a below-boundary adoption. Pinned independently precisely because the floor MASKS a guard mutation.
+  //    MUTATION RECIPE (M2): in the grafted historical.ts, alter the pinned guard text — e.g. rename
+  //    `finalityBlockCount` in that predicate, or remove the `break;` / move the boundary assignment before
+  //    the guard → this pin FAILS. (Editing the pinned source and showing the pin fails IS the accepted
+  //    "pin the guard" verification per the plan — the floor cannot be relied on to catch it.)
+  test('Pin B (load-bearing guard, RG0): the isolated path breaks-before-adopt on the finality-delta guard', () => {
+    // The break-before-adopt guard: a non-advancing (stale-LOW ⇒ negative) delta is `<= finalityBlockCount`,
+    // so the loop breaks WITHOUT adopting the probed boundary.
+    expect(isolated).toContain('params.chain.finalityBlockCount');
+    expect(isolated).toContain('params.syncProgress.finalized.number) <=');
+
+    // The boundary assignment must sit AFTER the guarded break — never before it — so a stale-LOW probe
+    // that trips the guard can never reach the adopt. Anchor on the guard PREDICATE itself (`… .number) <=`),
+    // NOT the first `params.chain.finalityBlockCount` (that occurrence is the probe computation
+    // `latest.number - finalityBlockCount`, not the guard), so the ordering assertion targets what it names.
+    const guardAt = isolated.indexOf(
+      'params.syncProgress.finalized.number) <=',
+    );
+    const breakAt = isolated.indexOf('break;', guardAt);
+    const adoptAt = isolated.indexOf(
+      'params.syncProgress.finalized = finalizedBlock;',
+    );
+
+    expect(guardAt).toBeGreaterThan(-1);
+    expect(breakAt).toBeGreaterThan(guardAt);
+    expect(adoptAt).toBeGreaterThan(breakAt);
+  });
+});

portal/portal-cutover-guard.test.ts

@@ -532,7 +532,7 @@ index 01b6288..8567db1 100644
      if (Date.now() - lastUnfinalizedRefetch < 30_000) {
        break;
      }
-@@ -826,6 +979,14 @@ export async function* getHistoricalEventsIsolated(params: {
+@@ -826,6 +979,17 @@ export async function* getHistoricalEventsIsolated(params: {
          ],
          context,
        ),
@@ -542,12 +542,15 @@ index 01b6288..8567db1 100644
 +        chain: params.chain,
 +        rpc,
 +        finalizedBlock: fb,
++        // The previously adopted boundary is the in-run finality floor — a stale-LOW probe must not regress
++        // it (RT-2; INERT given the isolated adopt-guard below, defense/parity per RG0).
++        floor: hexToNumber(params.syncProgress.finalized.number),
 +        common: params.common,
 +      }),
      );
 
      const finalizedBlockNumber = hexToNumber(finalizedBlock.number);
-@@ -1216,7 +1377,9 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1216,7 +1380,9 @@ export async function* getLocalSyncGenerator(params: {
        return;
      } else if (params.isCatchup === false) {
        params.common.logger.info({
@@ -558,7 +561,7 @@ index 01b6288..8567db1 100644
          chain: params.chain.name,
          chain_id: params.chain.id,
          cached_block: hexToNumber(params.syncProgress.current.number),
-@@ -1227,14 +1390,18 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1227,14 +1393,18 @@ export async function* getLocalSyncGenerator(params: {
      first = hexToNumber(params.syncProgress.current.number) + 1;
    } else {
      params.common.logger.info({

portal/wiring/0.15.17.patch

@@ -532,7 +532,7 @@ index 0bd78dc..48c2f24 100644
      if (Date.now() - lastUnfinalizedRefetch < 30_000) {
        break;
      }
-@@ -813,6 +966,14 @@ export async function* getHistoricalEventsIsolated(params: {
+@@ -813,6 +966,17 @@ export async function* getHistoricalEventsIsolated(params: {
          ],
          context,
        ),
@@ -542,12 +542,15 @@ index 0bd78dc..48c2f24 100644
 +        chain: params.chain,
 +        rpc,
 +        finalizedBlock: fb,
++        // The previously adopted boundary is the in-run finality floor — a stale-LOW probe must not regress
++        // it (RT-2; INERT given the isolated adopt-guard below, defense/parity per RG0).
++        floor: hexToNumber(params.syncProgress.finalized.number),
 +        common: params.common,
 +      }),
      );
 
      const finalizedBlockNumber = hexToNumber(finalizedBlock.number);
-@@ -1203,7 +1364,9 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1203,7 +1367,9 @@ export async function* getLocalSyncGenerator(params: {
        return;
      } else if (params.isCatchup === false) {
        params.common.logger.info({
@@ -558,7 +561,7 @@ index 0bd78dc..48c2f24 100644
          chain: params.chain.name,
          chain_id: params.chain.id,
          cached_block: hexToNumber(params.syncProgress.current.number),
-@@ -1214,14 +1377,18 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1214,14 +1380,18 @@ export async function* getLocalSyncGenerator(params: {
      first = hexToNumber(params.syncProgress.current.number) + 1;
    } else {
      params.common.logger.info({

portal/wiring/0.16.6.patch

@@ -532,7 +532,7 @@ index 0bd78dc..48c2f24 100644
      if (Date.now() - lastUnfinalizedRefetch < 30_000) {
        break;
      }
-@@ -813,6 +966,14 @@ export async function* getHistoricalEventsIsolated(params: {
+@@ -813,6 +966,17 @@ export async function* getHistoricalEventsIsolated(params: {
          ],
          context,
        ),
@@ -542,12 +542,15 @@ index 0bd78dc..48c2f24 100644
 +        chain: params.chain,
 +        rpc,
 +        finalizedBlock: fb,
++        // The previously adopted boundary is the in-run finality floor — a stale-LOW probe must not regress
++        // it (RT-2; INERT given the isolated adopt-guard below, defense/parity per RG0).
++        floor: hexToNumber(params.syncProgress.finalized.number),
 +        common: params.common,
 +      }),
      );
 
      const finalizedBlockNumber = hexToNumber(finalizedBlock.number);
-@@ -1203,7 +1364,9 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1203,7 +1367,9 @@ export async function* getLocalSyncGenerator(params: {
        return;
      } else if (params.isCatchup === false) {
        params.common.logger.info({
@@ -558,7 +561,7 @@ index 0bd78dc..48c2f24 100644
          chain: params.chain.name,
          chain_id: params.chain.id,
          cached_block: hexToNumber(params.syncProgress.current.number),
-@@ -1214,14 +1377,18 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1214,14 +1380,18 @@ export async function* getLocalSyncGenerator(params: {
      first = hexToNumber(params.syncProgress.current.number) + 1;
    } else {
      params.common.logger.info({

portal/wiring/0.16.7.patch

@@ -532,7 +532,7 @@ index 0bd78dc..48c2f24 100644
      if (Date.now() - lastUnfinalizedRefetch < 30_000) {
        break;
      }
-@@ -813,6 +966,14 @@ export async function* getHistoricalEventsIsolated(params: {
+@@ -813,6 +966,17 @@ export async function* getHistoricalEventsIsolated(params: {
          ],
          context,
        ),
@@ -542,12 +542,15 @@ index 0bd78dc..48c2f24 100644
 +        chain: params.chain,
 +        rpc,
 +        finalizedBlock: fb,
++        // The previously adopted boundary is the in-run finality floor — a stale-LOW probe must not regress
++        // it (RT-2; INERT given the isolated adopt-guard below, defense/parity per RG0).
++        floor: hexToNumber(params.syncProgress.finalized.number),
 +        common: params.common,
 +      }),
      );
 
      const finalizedBlockNumber = hexToNumber(finalizedBlock.number);
-@@ -1203,7 +1364,9 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1203,7 +1367,9 @@ export async function* getLocalSyncGenerator(params: {
        return;
      } else if (params.isCatchup === false) {
        params.common.logger.info({
@@ -558,7 +561,7 @@ index 0bd78dc..48c2f24 100644
          chain: params.chain.name,
          chain_id: params.chain.id,
          cached_block: hexToNumber(params.syncProgress.current.number),
-@@ -1214,14 +1377,18 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1214,14 +1380,18 @@ export async function* getLocalSyncGenerator(params: {
      first = hexToNumber(params.syncProgress.current.number) + 1;
    } else {
      params.common.logger.info({

portal/wiring/0.16.8.patch

@@ -532,7 +532,7 @@ index 0bd78dc..48c2f24 100644
      if (Date.now() - lastUnfinalizedRefetch < 30_000) {
        break;
      }
-@@ -813,6 +966,14 @@ export async function* getHistoricalEventsIsolated(params: {
+@@ -813,6 +966,17 @@ export async function* getHistoricalEventsIsolated(params: {
          ],
          context,
        ),
@@ -542,12 +542,15 @@ index 0bd78dc..48c2f24 100644
 +        chain: params.chain,
 +        rpc,
 +        finalizedBlock: fb,
++        // The previously adopted boundary is the in-run finality floor — a stale-LOW probe must not regress
++        // it (RT-2; INERT given the isolated adopt-guard below, defense/parity per RG0).
++        floor: hexToNumber(params.syncProgress.finalized.number),
 +        common: params.common,
 +      }),
      );
 
      const finalizedBlockNumber = hexToNumber(finalizedBlock.number);
-@@ -1203,7 +1364,9 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1203,7 +1367,9 @@ export async function* getLocalSyncGenerator(params: {
        return;
      } else if (params.isCatchup === false) {
        params.common.logger.info({
@@ -558,7 +561,7 @@ index 0bd78dc..48c2f24 100644
          chain: params.chain.name,
          chain_id: params.chain.id,
          cached_block: hexToNumber(params.syncProgress.current.number),
-@@ -1214,14 +1377,18 @@ export async function* getLocalSyncGenerator(params: {
+@@ -1214,14 +1380,18 @@ export async function* getLocalSyncGenerator(params: {
      first = hexToNumber(params.syncProgress.current.number) + 1;
    } else {
      params.common.logger.info({