test(realtime): RG2 fuzzer revision — reorgedBlocks payload assertion + honest scope + non-vacuity floors

dzhelezov · claude · dzhelezov · commit 630f6c8a27eb · 2026-07-13T02:07:37.000Z
Committee revision (glm/codex/reviewer) on the RG2 silent-gap fuzzer, turning three review
findings into real coverage and candor:

1. REORG PAYLOAD assertion (was a false-green). `ChainModel.apply` now returns the model's
   rolled-back suffix on a reorg; the harness asserts the emitted `reorgedBlocks` (by hash, in
   order) EQUALS that suffix. Closes the gap where the right `commonAncestor` was emitted with an
   empty/mis-sized `reorgedBlocks` — the chain reconstruction (ancestor-keyed) passed while
   downstream rollback would break. Mutation-verified: reconcile `reorgedBlocks -&gt; []` now FAILS
   here (`expected [ [] ] to deeply equal [ Array(1) ]`) though it stays invisible to the chain
   equality check.

2. Header candor. The header claimed a 204/409 interleave that never happened. The generator now
   really prefixes a server-concurs 409 (previousBlocks == the seeded ring anchor) on ~1/4 of
   sequences, driving the shell's parsePreviousBlocks -&gt; ring-match rewind -&gt; reconnect path on the
   wire while leaving the delivered sequence (and the model's prediction) unchanged — zero
   model-fidelity risk. Genuine fork-rewind 409 and same-block child redelivery are now explicitly
   OUT OF SCOPE with cross-refs to the wire tests that cover them. Finality is documented as a
   deliberate isolation, "NOT the full realtime trichotomy".

3. Non-vacuity FLOORS. Per-class + per-wire-shape coverage tallies with lower-bound assertions, so
   a future generator edit that collapsed to all-append (or dropped the 409/204 interleave) fails
   loudly instead of passing vacuously. Verified green at FUZZ_N=100000.

CONTRACT vs OBEDIENCE caveat added: this proves the consumer OBEYS reconcile's contract in its
event loop, not that the contract itself is correct (reconcile's spec is pinned by the pure-function
unit tests). No production change. Both-version gates green (0.16.8 / 0.16.9, 362 each), biome clean.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/portal/portal-realtime-fuzz.test.ts b/portal/portal-realtime-fuzz.test.ts
@@ -2,9 +2,10 @@
  * RG2 — silent-gap property fuzzer (realtime campaign plan item (e).2).
  *
  * WHAT IT PROVES — the TRICHOTOMY. The fork's brand is "loud-restart, never-wrong-data". A stream of
- * adversarial block deliveries (dropped / duplicated / out-of-order / mutated hash|parentHash /
- * interleaved 204-idle & 409-fork phases) driven through the REAL realtime consumer
- * `portalRealtimeEvents` must resolve EVERY delivery into exactly one of three outcomes:
+ * adversarial block deliveries (dropped / duplicated / out-of-order / mutated hash|parentHash),
+ * interleaved with 204-idle re-polls and server-concurs 409 fork-negotiation rounds, driven through the
+ * REAL realtime consumer `portalRealtimeEvents` must resolve EVERY delivery into exactly one of three
+ * outcomes:
  *   1. APPENDED    — the code's realized chain grew by that block (model chain matches), or
  *   2. RECONCILED  — a reorg (window rolled back to the right ancestor, new fork adopted) or a
  *                    duplicate (idempotent no-op, no state change), or
@@ -27,15 +28,35 @@
  * actually emits exercises the append + rollback + fatal control flow end-to-end, so a regression that
  * dropped a block, mis-rolled a reorg, or swallowed a gap would be caught here where the pure-function
  * test could not see it. We feed blocks via a scripted `fetchImpl` /stream mock (the same seam every
- * existing realtime test uses) and interleave 204 (idle) and 409 (fork-negotiation) responses so the
- * I/O shell's own paths are on the wire too.
+ * existing realtime test uses).
  *
- * FINALITY IS HELD INERT for the core trichotomy (`finalizedHead` stays at/below the window base, poll
- * disabled): a mid-sequence finalize prunes the private window and advances the anchor, which changes
- * what `reconcile` sees and would make the reference model depend on finalize timing rather than pure
- * chain structure. Finality/finalize is exhaustively covered by the hand-written realtime tests and
- * the B1/RT-G10 watchdog suites; this fuzzer isolates the append|reorg|dup|gap decision, which is where
- * a silent gap lives. (A separate 409/204 interleave still drives the shell's negotiation paths.)
+ * SCOPE — what this fuzzer OBEYS vs proves, and what it deliberately does NOT model:
+ *   • CONTRACT vs OBEDIENCE. The reference model's `classify` structurally parallels `reconcile`'s
+ *     CONTRACT (append|duplicate|reorg|gap by hash/parentHash structure). This fuzzer proves the
+ *     consumer OBEYS that contract in its event loop end-to-end — NOT that the contract itself is
+ *     correct. A shared contract-level misconception (both `reconcile` and `classify` wrong the same
+ *     way) would be invisible here; `reconcile`'s own correctness is pinned by the pure-function unit
+ *     tests. Do not over-trust this as a proof of the reconcile SPEC.
+ *   • 409 fork-negotiation — SERVER-CONCURS baseline ONLY. Some sequences prefix a 409 whose
+ *     `previousBlocks` AGREES with the model's own canonical ring (the anchor). That drives the shell's
+ *     real 409 code path on the wire (parsePreviousBlocks → ring-match rewind → reconnect) while leaving
+ *     the DELIVERED block sequence — and thus the reference model's predicted chain — unchanged, so
+ *     there is no model-fidelity risk. A GENUINE fork-rewind 409 (previousBlocks naming a DIFFERENT
+ *     canonical chain, driving a mid-stream cursor rewind that re-delivers divergent blocks) is OUT OF
+ *     SCOPE here — modeling it would couple the reference model to the shell's cursor arithmetic and
+ *     risk a false green. That path is covered end-to-end by the dedicated wire tests
+ *     (`portal-realtime-wire.test.ts` — "1-block orphan at tip HEALS via 409 fork negotiation", T1/T5).
+ *   • SAME-BLOCK CHILD REDELIVERY — out of scope. The consumer is driven with NO `shouldRedeliver`
+ *     predicate, so the `duplicate && redelivered` re-emit branch is inert here; a bare duplicate is an
+ *     idempotent no-op. The redelivery handshake is covered by the wire same-block-child-redelivery
+ *     tests (issue #26 T5).
+ *   • FINALITY held INERT. `finalizedHead` stays at/below the window base (poll effectively disabled): a
+ *     mid-sequence finalize prunes the private window and advances the anchor, which changes what
+ *     `reconcile` sees and would make the reference model depend on finalize timing rather than pure
+ *     chain structure. This is a DELIBERATE isolation of the block-delivery append|reorg|dup|gap
+ *     decision (where a silent gap lives) — it is NOT the full realtime trichotomy. Finalize/prune
+ *     interleaving is exhaustively covered by the hand-written realtime tests and the B1/RT-G10
+ *     watchdog suites.
  *
  * REPRODUCIBILITY. A seeded mulberry32 PRNG (NOT Math.random). Each sequence's seed is derived from a
  * base seed; on ANY trichotomy violation the failing seed is printed so the exact sequence repros. The
@@ -169,6 +190,11 @@ class ChainModel {
    * duplicate if it IS the tip / the anchor re-delivered; reorg if the parent is a known earlier
    * window block or the anchor; gap otherwise) but is written independently against the model's own
    * state so it is not a copy of the code under test.
+   *
+   * SCOPE (see the file header): because `classify` mirrors the reconcile CONTRACT, this fuzzer proves
+   * the consumer OBEYS that contract in its event loop — NOT that the contract itself is correct. A
+   * shared contract-level misconception would be invisible here; reconcile's own correctness is the job
+   * of the pure-function unit tests. Future readers: do not over-trust this as a spec proof.
    */
   classify(next: Light): Expected {
     const tip = this.tip();
@@ -189,27 +215,38 @@ class ChainModel {
     return 'gap';
   }
 
-  /** Advance the model to the realized chain a CORRECT consumer must hold after processing `next`. */
-  apply(next: Light, cls: Expected): void {
+  /**
+   * Advance the model to the realized chain a CORRECT consumer must hold after processing `next`.
+   * Returns the REORGED SUFFIX for a `reorg` (the window blocks that were strictly above the common
+   * ancestor before this delivery — exactly the `reorgedBlocks` a correct consumer must emit on the
+   * reorg event), and `undefined` for every other class. Used by the harness to assert the emitted
+   * `reorgedBlocks` payload, not just the rollback depth.
+   */
+  apply(next: Light, cls: Expected): Light[] | undefined {
     if (cls === 'append') {
       this.window.push(next);
       this.seen.add(next.hash);
 
-      return;
+      return undefined;
     }
     if (cls === 'reorg') {
+      let reorged: Light[];
       if (next.parentHash === this.anchor.hash) {
+        // fork at the finality boundary: the WHOLE window is reorged away, anchor is the common ancestor.
+        reorged = [...this.window];
         this.window = [next];
       } else {
         const idx = this.window.findIndex((b) => b.hash === next.parentHash);
+        reorged = this.window.slice(idx + 1);
         this.window = this.window.slice(0, idx + 1);
         this.window.push(next);
       }
       this.seen.add(next.hash);
 
-      return;
+      return reorged;
     }
     // duplicate / gap: no state change (a gap additionally fatals the consumer — handled by the caller).
+    return undefined;
   }
 }
 
@@ -241,13 +278,14 @@ function replayRealized(
     }
     if (e.type === 'reorg') {
       const anchorHash = e.block.hash;
-      let cut = chain.length;
+      // Roll the window back to (and including) the common ancestor. If the ancestor is not in the
+      // reconstructed chain (it is the finality anchor, off-window), the whole window is rolled back.
+      let cut = 0;
       for (let k = chain.length - 1; k >= 0; k--) {
         if (chain[k]!.hash === anchorHash) {
           cut = k + 1;
           break;
         }
-        cut = k;
       }
       chain.length = cut;
     }
@@ -356,11 +394,30 @@ function buildSequence(
 // ─────────────────────────────── the property ───────────────────────────────
 
 /**
- * Run ONE sequence end-to-end and assert the trichotomy. Returns nothing; throws (via expect) with the
- * seed embedded on any violation. Re-derives the model here (in lockstep with the consumer's events) so
- * the assertion is against a freshly-computed independent chain, not the generator's bookkeeping.
+ * Per-class delivery + wire-shape tallies accumulated across the whole run so a FUTURE generator edit
+ * that silently made every sequence an all-append no-op (vacuity) fails LOUDLY at the coverage floor
+ * asserted after the run — the property "the fuzzer exercised each trichotomy branch" is itself tested.
+ */
+type Coverage = {
+  append: number;
+  duplicate: number;
+  reorg: number;
+  gap: number;
+  /** sequences whose reconstructed chain is NON-EMPTY (a genuine append/reorg path, not a trivial pass) */
+  nonEmptyChains: number;
+  /** connections scripted as a server-concurs 409 fork-negotiation round (issue #33 shell path) */
+  conn409: number;
+  /** connections scripted as a 204 idle re-poll (the shell's no-data path) */
+  conn204: number;
+};
+
+/**
+ * Run ONE sequence end-to-end and assert the trichotomy. Throws (via expect) with the seed embedded on
+ * any violation; otherwise returns this sequence's contribution to the run-wide coverage tallies. Re-
+ * derives the model here (in lockstep with the consumer's events) so the assertion is against a freshly-
+ * computed independent chain, not the generator's bookkeeping.
  */
-async function runSequence(seed: number, anchor: Light): Promise<void> {
+async function runSequence(seed: number, anchor: Light): Promise<Coverage> {
   const { blocks, expected, endsInGap } = buildSequence(seed, anchor);
 
   const ac = new AbortController();
@@ -370,7 +427,27 @@ async function runSequence(seed: number, anchor: Light): Promise<void> {
   // `min(500, floor(pollMs/2))`), so 10^5 sequences stay fast; finality is still INERT because the
   // probed head equals the anchor (never above the window base ⇒ `takeFinalized` yields no finalizedTip
   // and no finalize event fires however often the cadence polls). See the file header.
-  const conns: Conn[] = [{ status: 200, blocks }, { status: 204 }];
+  //
+  // 409 INTERLEAVE (server-concurs baseline — see the file header SCOPE note). On a fraction of seeds we
+  // PREFIX a 409 whose `previousBlocks` is exactly the seeded ring's anchor entry `{anchor.number,
+  // anchor.hash}`. On the first request the shell's cursor sits at `anchor.number + 1` with the ring
+  // holding the anchor's hash, so this 409 MATCHES the ring at the anchor: the shell rewinds `cursor` to
+  // `anchor.number + 1` (i.e. UNCHANGED) and re-opens — driving the real 409 code path (parsePreviousBlocks
+  // → ring-match rewind → reconnect) on the wire while the DELIVERED block sequence, and thus the reference
+  // model's predicted chain, is left identical. So the trichotomy assertion holds ACROSS the reconnect with
+  // zero model-fidelity risk. A genuine fork-rewind 409 that re-delivers a divergent chain is out of scope
+  // here (covered by the wire tests) — see the header.
+  const use409 = (seed & 0x3) === 0; // ~1/4 of sequences prefix a server-concurs 409
+  const conns: Conn[] = use409
+    ? [
+        {
+          status: 409,
+          previousBlocks: [{ number: anchor.number, hash: anchor.hash }],
+        },
+        { status: 200, blocks },
+        { status: 204 },
+      ]
+    : [{ status: 200, blocks }, { status: 204 }];
   const iter = portalRealtimeEvents({
     portalUrl: 'http://portal',
     headers: {},
@@ -429,8 +506,13 @@ async function runSequence(seed: number, anchor: Light): Promise<void> {
   //    assert it EQUALS the independently-derived canonical chain (processing every delivery the model
   //    did NOT predict as a terminating gap). This is the load-bearing assertion — the ONLY way the two
   //    can differ with no throw is a silently-skipped block, which is exactly a trichotomy violation.
+  //    Alongside it we capture, per reorg step, the model's ROLLED-BACK SUFFIX (the window blocks that
+  //    were strictly above the common ancestor) so the emitted reorg events' `reorgedBlocks` payload can
+  //    be checked below — a reconstruction keyed on commonAncestor alone would miss a regression that
+  //    emitted the right ancestor with a wrong/empty `reorgedBlocks`.
   const model = new ChainModel(anchor);
   const processed = endsInGap ? expected.length - 1 : expected.length;
+  const expectedReorgSuffixes: string[][] = [];
   for (let k = 0; k < processed; k++) {
     const b = blocks[k]!;
     const light: Light = {
@@ -439,7 +521,10 @@ async function runSequence(seed: number, anchor: Light): Promise<void> {
       parentHash: b.header.parentHash,
       timestamp: b.header.timestamp,
     };
-    model.apply(light, expected[k]!);
+    const reorged = model.apply(light, expected[k]!);
+    if (reorged !== undefined) {
+      expectedReorgSuffixes.push(reorged.map((r) => r.hash));
+    }
   }
   const modelChain = model.window.map((b) => ({
     hash: b.hash,
@@ -452,6 +537,30 @@ async function runSequence(seed: number, anchor: Light): Promise<void> {
     `SILENT-GAP TRICHOTOMY VIOLATION: the consumer's realized chain diverged from the canonical model with no fatal (${seedTag}). ` +
       `expected classes=${expected.join(',')}${endsInGap ? ' [last=gap→fatal]' : ''}`,
   ).toEqual(modelChain);
+
+  // 3. REORG PAYLOAD: the emitted reorg events, in order, must carry the model's rolled-back suffix as
+  //    their `reorgedBlocks` (keyed on hash). This closes the false-green where the right commonAncestor
+  //    is emitted with an empty/mis-sized `reorgedBlocks` — the reconstruction above (ancestor-keyed)
+  //    would still pass, but downstream rollback/redelivery would break. Same count, same hashes, order.
+  const emittedReorgSuffixes = events
+    .filter((e): e is Extract<RtEvent, { type: 'reorg' }> => e.type === 'reorg')
+    .map((e) => e.reorgedBlocks.map((r) => r.hash));
+
+  expect(
+    emittedReorgSuffixes,
+    `REORG PAYLOAD VIOLATION: the consumer's emitted reorgedBlocks diverged from the model's rolled-back suffix (${seedTag}). ` +
+      `expected classes=${expected.join(',')}`,
+  ).toEqual(expectedReorgSuffixes);
+
+  return {
+    append: expected.filter((c) => c === 'append').length,
+    duplicate: expected.filter((c) => c === 'duplicate').length,
+    reorg: expected.filter((c) => c === 'reorg').length,
+    gap: endsInGap ? 1 : 0,
+    nonEmptyChains: modelChain.length > 0 ? 1 : 0,
+    conn409: use409 ? 1 : 0,
+    conn204: 1, // every sequence scripts exactly one 204 idle re-poll before exhaustion
+  };
 }
 
 // ─────────────────────────────── the driver ───────────────────────────────
@@ -473,30 +582,88 @@ const ANCHOR: Light = {
 // via this explicit override, and the heavy bar (FUZZ_N=100000 ⇒ ~510s cap) has headroom.
 const TIMEOUT_MS = Math.max(15_000, N * 5 + 10_000);
 
+// NON-VACUITY FLOORS. Sane lower bounds each trichotomy class (and each wire shape) MUST clear over a
+// DEFAULT run, so a future generator edit that silently collapsed to all-append (or dropped the 409/204
+// interleave) fails LOUDLY here instead of passing vacuously. Deliberately conservative — the observed
+// counts at DEFAULT_N=2500 are far higher (thousands of appends, hundreds of each reconcile class); these
+// floors only assert "each branch was genuinely exercised", scaled down for a small FUZZ_N. (committee)
+const floors = (n: number) => ({
+  append: Math.max(5, n),
+  duplicate: Math.max(3, Math.floor(n / 8)),
+  reorg: Math.max(3, Math.floor(n / 8)),
+  gap: Math.max(3, Math.floor(n / 8)),
+  nonEmptyChains: Math.max(3, Math.floor(n / 8)),
+  conn409: Math.max(3, Math.floor(n / 8)),
+  conn204: n, // every sequence scripts exactly one 204
+});
+
 test(
   `RG2 silent-gap fuzzer: ${N} adversarial sequences, trichotomy (append | reorg/dup | fatal) never silently skips`,
   async () => {
-    let violations = 0;
-    let firstFailSeed: number | undefined;
+    const cov: Coverage = {
+      append: 0,
+      duplicate: 0,
+      reorg: 0,
+      gap: 0,
+      nonEmptyChains: 0,
+      conn409: 0,
+      conn204: 0,
+    };
     for (let i = 0; i < N; i++) {
       const seed = (BASE_SEED + i * 0x9e3779b1) >>> 0; // golden-ratio stride → well-spread seeds
       try {
-        await runSequence(seed, ANCHOR);
+        const c = await runSequence(seed, ANCHOR);
+        cov.append += c.append;
+        cov.duplicate += c.duplicate;
+        cov.reorg += c.reorg;
+        cov.gap += c.gap;
+        cov.nonEmptyChains += c.nonEmptyChains;
+        cov.conn409 += c.conn409;
+        cov.conn204 += c.conn204;
       } catch (err) {
-        violations += 1;
-        if (firstFailSeed === undefined) {
-          firstFailSeed = seed;
-          // Surface the first failure loudly and immediately with its repro seed.
-          const msg = err instanceof Error ? err.message : String(err);
-          throw new Error(
-            `RG2 fuzzer FAILED on sequence ${i} (seed=0x${seed.toString(16)}). Repro exactly this sequence: ` +
-              `FUZZ_N=1 FUZZ_SEED=${seed} (BASE_SEED becomes this seed and i=0 reuses it). Underlying: ${msg}`,
-          );
-        }
+        // Throw-on-FIRST violation with the exact repro seed — deterministic, so one repro is enough; a
+        // "collect all failures" counter would only ever reach 1 before this throw, so we don't keep one.
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `RG2 fuzzer FAILED on sequence ${i} (seed=0x${seed.toString(16)}). Repro exactly this sequence: ` +
+            `FUZZ_N=1 FUZZ_SEED=${seed} (BASE_SEED becomes this seed and i=0 reuses it). Underlying: ${msg}`,
+        );
       }
     }
 
-    expect(violations).toBe(0);
+    // NON-VACUITY GUARD: assert every class + wire shape cleared its floor, so the run PROVABLY exercised
+    // each branch of the trichotomy rather than passing on a degenerate all-append (or interleave-free)
+    // generator. A future edit that starves a branch fails HERE, loudly, with the observed tallies.
+    const floor = floors(N);
+    const covMsg = `observed coverage over ${N} sequences: ${JSON.stringify(cov)} vs floors ${JSON.stringify(floor)}`;
+    expect(
+      cov.append,
+      `append underexercised — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.append);
+    expect(
+      cov.duplicate,
+      `duplicate underexercised — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.duplicate);
+    expect(
+      cov.reorg,
+      `reorg underexercised — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.reorg);
+    expect(
+      cov.gap,
+      `gap/fatal underexercised — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.gap);
+    expect(
+      cov.nonEmptyChains,
+      `non-empty reconstructed chains underexercised (would pass vacuously on trivial chains) — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.nonEmptyChains);
+    expect(
+      cov.conn409,
+      `409 fork-negotiation interleave underexercised — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.conn409);
+    expect(
+      cov.conn204,
+      `204 idle interleave underexercised — ${covMsg}`,
+    ).toBeGreaterThanOrEqual(floor.conn204);
   },
   TIMEOUT_MS,
 );
