@effectstream/sync 0.101.1 → 0.103.0

package/src/sync-protocols/solana/read-data-retry.test.ts

@@ -0,0 +1,153 @@
+import { expect, test } from "bun:test";
+import { run } from "effection";
+import { SolanaFetcher } from "./fetcher.ts";
+import type { ConfigType, Output, Page } from "./types.ts";
+import type { LastPage } from "../base/state.ts";
+import type { RootPage } from "../types.ts";
+
+/**
+ * How `readData` behaves when the RPC misbehaves. The contract it must keep:
+ *
+ *  - a transient failure costs nothing — the block is retried immediately
+ *  - a persistent failure keeps whatever was already fetched, and the page
+ *    advances only over slots that were positively resolved, so no slot is ever
+ *    stepped over unread
+ *  - a failure with nothing resolved throws, so the fetch loop counts it and
+ *    /health can see it, rather than looking idle
+ */
+
+const BLOCKHASH = "hash";
+
+function makeFetcher(getBlock: (slot: number) => Promise<any>): SolanaFetcher {
+  const fetcher = new SolanaFetcher({
+    network: { rpcUrl: "http://127.0.0.1:8899" },
+    syncProtocol: { name: "parallelSolanaRPC" },
+    primitives: [],
+  } as unknown as ConfigType);
+  (fetcher.client as any).getBlock = getBlock;
+  return fetcher;
+}
+
+const block = (slot: number) => ({
+  blockhash: `${BLOCKHASH}-${slot}`,
+  blockTime: 1_700_000_000 + slot,
+  blockHeight: slot,
+  parentSlot: slot - 1,
+  transactions: [],
+});
+
+const rootConversion = {
+  toRootPage: (o: Output) => (o.blockTime * 1000) as RootPage,
+} as any;
+
+const priorPage: LastPage<Page, RootPage> = {
+  own: 0 as Page,
+  ownBlockNumber: 0 as Page,
+  root: 0 as RootPage,
+};
+
+function readData(fetcher: SolanaFetcher, from: number, to: number) {
+  return run(() =>
+    fetcher.readData(
+      { from, to, isPresync: false } as any,
+      rootConversion,
+      priorPage,
+    )
+  );
+}
+
+test("a transient failure is retried and costs no blocks", async () => {
+  const attempts = new Map<number, number>();
+  const fetcher = makeFetcher(async (slot) => {
+    const n = (attempts.get(slot) ?? 0) + 1;
+    attempts.set(slot, n);
+    if (slot === 2 && n === 1) throw new Error("transient timeout");
+    return block(slot);
+  });
+
+  const result = await readData(fetcher, 1, 3);
+
+  expect(result.output.length).toBe(3);
+  expect(attempts.get(2)).toBe(2); // failed once, succeeded on retry
+  expect(Number(result.lastPage.own)).toBe(3);
+});
+
+test("a persistent failure keeps earlier blocks and stops at the bad slot", async () => {
+  const fetcher = makeFetcher(async (slot) => {
+    if (slot >= 3) throw new Error("still down");
+    return block(slot);
+  });
+
+  const result = await readData(fetcher, 1, 5);
+
+  // Slots 1-2 survive rather than the whole chunk being discarded...
+  expect(result.output.map((o) => o.output.slot)).toEqual([1, 2]);
+  // ...and the page stops at 2, so the next poll resumes AT 3 — the failed slot
+  // is never stepped over.
+  expect(Number(result.lastPage.own)).toBe(2);
+});
+
+test("a failure with nothing resolved throws, so the loop can count it", async () => {
+  const fetcher = makeFetcher(async () => {
+    throw new Error("RPC unreachable");
+  });
+
+  let thrown: unknown;
+  try {
+    await readData(fetcher, 10, 15);
+  } catch (e) {
+    thrown = e;
+  }
+  expect(String(thrown)).toContain("RPC unreachable");
+});
+
+test("retries are bounded — it gives up rather than hanging forever", async () => {
+  let calls = 0;
+  const fetcher = makeFetcher(async () => {
+    calls++;
+    throw new Error("down");
+  });
+
+  let thrown: unknown;
+  try {
+    await readData(fetcher, 1, 1);
+  } catch (e) {
+    thrown = e;
+  }
+  expect(String(thrown)).toContain("down");
+  // 3 attempts for the single slot, then hand back to the fetch loop. An
+  // unbounded inner retry would never return and would freeze the health signal.
+  expect(calls).toBe(3);
+});
+
+test("a fully skipped range advances the page over CONFIRMED-skipped slots only", async () => {
+  const fetcher = makeFetcher(async () => null); // every slot skipped
+
+  const result = await readData(fetcher, 1, 4);
+
+  expect(result.output.length).toBe(0);
+  expect(Number(result.lastPage.own)).toBe(4);
+});
+
+test("skipped-then-failed advances only to the last confirmed slot", async () => {
+  const fetcher = makeFetcher(async (slot) => {
+    if (slot <= 2) return null; // confirmed skipped
+    throw new Error("down"); // never resolved
+  });
+
+  const result = await readData(fetcher, 1, 5);
+
+  expect(result.output.length).toBe(0);
+  // 2, not 5: slots 3-5 were never read, so the page must not pass them.
+  expect(Number(result.lastPage.own)).toBe(2);
+});
+
+test("trailing skipped slots still advance the page past the last block", async () => {
+  const fetcher = makeFetcher(async (slot) => (slot === 1 ? block(1) : null));
+
+  const result = await readData(fetcher, 1, 4);
+
+  expect(result.output.map((o) => o.output.slot)).toEqual([1]);
+  // Paging to 4 (not 1) avoids re-scanning slots already confirmed empty.
+  expect(Number(result.lastPage.own)).toBe(4);
+});

package/src/sync-protocols/solana/read-primitives.test.ts

@@ -0,0 +1,435 @@
+import { expect, test } from "bun:test";
+import {
+  SOLANA_PRIMITIVE_ACCOUNT_BALANCE,
+  SOLANA_PRIMITIVE_PROGRAM_LOG,
+  SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+} from "@effectstream/config";
+import { SolanaFetcher } from "./fetcher.ts";
+import type { ConfigType } from "./types.ts";
+
+/**
+ * Direct unit coverage for `SolanaFetcher.readPrimitives` — the function that
+ * decides what the state machine is told happened on chain. It had none, which
+ * meant the reverted-transaction skip, the lookup-table resolution and the
+ * two-primitive dispatch were all only exercised (if at all) by a full e2e run
+ * against a live validator.
+ *
+ * `readPrimitives` is a generator that never yields, so it can be driven to
+ * completion with a single `.next()`.
+ */
+
+const WATCHED_PROGRAM = "Watch1111111111111111111111111111111111111";
+const OTHER_PROGRAM = "0ther1111111111111111111111111111111111111";
+const WATCHED_ADDRESS = "Addr11111111111111111111111111111111111111";
+
+function makeFetcher(): SolanaFetcher {
+  return new SolanaFetcher({
+    network: { rpcUrl: "http://127.0.0.1:8899" },
+    syncProtocol: { name: "parallelSolanaRPC" },
+    primitives: [],
+  } as unknown as ConfigType);
+}
+
+/** Run the generator to completion and return the primitives it produced. */
+function run(fetcher: SolanaFetcher, slot: number, block: any, entries: any[]) {
+  const it = fetcher.readPrimitives(slot, block, entries as any) as any;
+  const step = it.next();
+  expect(step.done).toBe(true);
+  return step.value as any[];
+}
+
+// `type` is what readPrimitives dispatches on. These fixtures used to omit it,
+// which the old field-truthy dispatch tolerated — real configs always carry it,
+// because `Primitive.getConfig()` sets it and runtime/src/main.ts substitutes its
+// output for the raw config entry.
+const programLogEntry = {
+  syncProtocol: "parallelSolanaRPC",
+  primitive: {
+    name: "WatchedLog",
+    type: SOLANA_PRIMITIVE_PROGRAM_LOG,
+    programId: WATCHED_PROGRAM,
+  },
+};
+const balanceEntry = {
+  syncProtocol: "parallelSolanaRPC",
+  primitive: {
+    name: "WatchedBalance",
+    type: SOLANA_PRIMITIVE_ACCOUNT_BALANCE,
+    address: WATCHED_ADDRESS,
+  },
+};
+
+/** A transaction that genuinely invoked the watched program. */
+function invokingTx(overrides: Record<string, unknown> = {}) {
+  return {
+    transaction: {
+      message: { accountKeys: [WATCHED_ADDRESS, WATCHED_PROGRAM] },
+      signatures: ["sig-1"],
+    },
+    meta: {
+      err: null,
+      logMessages: [
+        `Program ${WATCHED_PROGRAM} invoke [1]`,
+        "Program log: hello",
+        `Program ${WATCHED_PROGRAM} success`,
+      ],
+      postBalances: [500, 0],
+      ...overrides,
+    },
+  };
+}
+
+test("emits a ProgramLog primitive for a genuine invocation", () => {
+  const out = run(makeFetcher(), 42, { transactions: [invokingTx()] }, [
+    programLogEntry,
+  ]);
+  expect(out.length).toBe(1);
+  expect(out[0].primitive).toBe("WatchedLog");
+  expect(out[0].output.payload.programId).toBe(WATCHED_PROGRAM);
+  expect(out[0].output.payload.logMessages).toEqual(["Program log: hello"]);
+  expect(out[0].syncProtocol.transactionHash).toBe("sig-1");
+});
+
+test("SKIPS a reverted transaction (security fix B2)", () => {
+  // A failed tx's logs describe work that was rolled back and its postBalances
+  // are the pre-state. Emitting either would drive state transitions off events
+  // that never happened.
+  const reverted = invokingTx({ err: { InstructionError: [0, "Custom"] } });
+  const out = run(makeFetcher(), 42, { transactions: [reverted] }, [
+    programLogEntry,
+    balanceEntry,
+  ]);
+  expect(out).toEqual([]);
+});
+
+test("SKIPS a transaction the RPC could not decode (meta === null)", () => {
+  const undecodable = {
+    transaction: {
+      message: { accountKeys: [WATCHED_PROGRAM] },
+      signatures: ["sig-x"],
+    },
+    meta: null,
+  };
+  const out = run(makeFetcher(), 42, { transactions: [undecodable] }, [
+    programLogEntry,
+  ]);
+  expect(out).toEqual([]);
+});
+
+test("does NOT attribute another program's logs to the watched program", () => {
+  // The spoof: the watched program is present as a bare account key while a
+  // different program emits the text.
+  const spoof = {
+    transaction: {
+      message: { accountKeys: [WATCHED_PROGRAM, OTHER_PROGRAM] },
+      signatures: ["sig-2"],
+    },
+    meta: {
+      err: null,
+      logMessages: [
+        `Program ${OTHER_PROGRAM} invoke [1]`,
+        `Program log: ${WATCHED_PROGRAM} forged event`,
+        `Program ${OTHER_PROGRAM} success`,
+      ],
+      postBalances: [0, 0],
+    },
+  };
+  const out = run(makeFetcher(), 42, { transactions: [spoof] }, [
+    programLogEntry,
+  ]);
+  expect(out).toEqual([]);
+});
+
+test("eventType filters against the program's OWN lines only", () => {
+  const tx = invokingTx({
+    logMessages: [
+      `Program ${OTHER_PROGRAM} invoke [1]`,
+      "Program log: MARKER from someone else",
+      `Program ${OTHER_PROGRAM} success`,
+      `Program ${WATCHED_PROGRAM} invoke [1]`,
+      "Program log: nothing relevant",
+      `Program ${WATCHED_PROGRAM} success`,
+    ],
+  });
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedLog",
+      type: SOLANA_PRIMITIVE_PROGRAM_LOG,
+      programId: WATCHED_PROGRAM,
+      eventType: "MARKER",
+    },
+  };
+  expect(run(makeFetcher(), 42, { transactions: [tx] }, [entry])).toEqual([]);
+});
+
+test("AccountBalance reads postBalances by resolved account index", () => {
+  const out = run(makeFetcher(), 7, { transactions: [invokingTx()] }, [
+    balanceEntry,
+  ]);
+  expect(out.length).toBe(1);
+  expect(out[0].output.payload).toMatchObject({
+    address: WATCHED_ADDRESS,
+    lamports: 500,
+    slot: 7,
+  });
+});
+
+test("AccountBalance resolves lookup-table addresses (security fix B3)", () => {
+  // The watched address arrives via an ALT, so it is absent from
+  // message.accountKeys — but postBalances is indexed over the full list:
+  // static keys, then ALT writable, then ALT readonly.
+  const tx = {
+    transaction: {
+      message: { accountKeys: [OTHER_PROGRAM] },
+      signatures: ["sig-3"],
+    },
+    meta: {
+      err: null,
+      logMessages: [],
+      postBalances: [1, 999, 2],
+      loadedAddresses: { writable: [WATCHED_ADDRESS], readonly: ["Ro11111111111111111111111111111111111111111"] },
+    },
+  };
+  const out = run(makeFetcher(), 9, { transactions: [tx] }, [balanceEntry]);
+  expect(out.length).toBe(1);
+  expect(out[0].output.payload.lamports).toBe(999);
+});
+
+test("dispatches both primitive kinds from one transaction", () => {
+  const out = run(makeFetcher(), 42, { transactions: [invokingTx()] }, [
+    balanceEntry,
+    programLogEntry,
+  ]);
+  expect(out.map((p) => p.primitive).sort())
+    .toEqual(["WatchedBalance", "WatchedLog"]);
+});
+
+test("returns nothing when no primitives are configured", () => {
+  expect(run(makeFetcher(), 42, { transactions: [invokingTx()] }, [])).toEqual([]);
+});
+
+// ───────────────────────── SOLANA:TokenAccount ─────────────────────────
+
+const MINT = "Mint111111111111111111111111111111111111111";
+const OTHER_MINT = "0therMint11111111111111111111111111111111";
+const TOKEN_ACCOUNT = "Tok111111111111111111111111111111111111111";
+const OWNER = "0wner11111111111111111111111111111111111111";
+const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+const TOKEN_2022_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+
+const tokenEntry = {
+  syncProtocol: "parallelSolanaRPC",
+  primitive: {
+    name: "WatchedToken",
+    type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+    mint: MINT,
+  },
+};
+
+/** `meta.postTokenBalances` record shape, per the JSON-RPC `getBlock` response. */
+function tokenBalance(overrides: Record<string, unknown> = {}) {
+  return {
+    accountIndex: 0,
+    mint: MINT,
+    owner: OWNER,
+    programId: TOKEN_PROGRAM,
+    uiTokenAmount: {
+      amount: "1500000000",
+      decimals: 9,
+      uiAmount: 1.5,
+      uiAmountString: "1.5",
+    },
+    ...overrides,
+  };
+}
+
+/** A successful transaction carrying token balances. */
+function tokenTx(
+  balances: Record<string, unknown>[],
+  overrides: Record<string, unknown> = {},
+) {
+  return {
+    transaction: {
+      message: { accountKeys: [TOKEN_ACCOUNT, WATCHED_PROGRAM] },
+      signatures: ["sig-tok"],
+    },
+    meta: {
+      err: null,
+      logMessages: [],
+      postBalances: [0, 0],
+      postTokenBalances: balances,
+      ...overrides,
+    },
+  };
+}
+
+test("TokenAccount emits the post balance for a watched mint", () => {
+  const out = run(makeFetcher(), 11, { transactions: [tokenTx([tokenBalance()])] }, [
+    tokenEntry,
+  ]);
+  expect(out.length).toBe(1);
+  expect(out[0].primitive).toBe("WatchedToken");
+  expect(out[0].output.payloadType).toBe("solana:token-balance");
+  expect(out[0].output.payload).toEqual({
+    tokenAccount: TOKEN_ACCOUNT,
+    mint: MINT,
+    owner: OWNER,
+    // Raw u64 as a string: 1.5 tokens at 9 decimals does not survive a JS number
+    // once amounts get large, so the grammar carries the base units.
+    amount: "1500000000",
+    decimals: 9,
+    slot: 11,
+  });
+});
+
+test("TokenAccount resolves lookup-table token accounts (security fix B3)", () => {
+  // `accountIndex` indexes the resolved list — static keys, then ALT writable, then
+  // ALT readonly — so a token account reached through an ALT is at an index past
+  // the end of message.accountKeys. Without resolution this reads undefined and
+  // drops the balance silently.
+  // Two static keys (indices 0-1), then ALT writable (2), then ALT readonly (3),
+  // so the watched token account sits at index 3 — past the end of accountKeys.
+  const tx = tokenTx([tokenBalance({ accountIndex: 3 })], {
+    loadedAddresses: {
+      writable: ["W1111111111111111111111111111111111111111111"],
+      readonly: [TOKEN_ACCOUNT],
+    },
+  });
+  tx.transaction.message.accountKeys = [OTHER_PROGRAM, WATCHED_PROGRAM];
+  const out = run(makeFetcher(), 12, { transactions: [tx] }, [tokenEntry]);
+  expect(out.length).toBe(1);
+  expect(out[0].output.payload.tokenAccount).toBe(TOKEN_ACCOUNT);
+});
+
+test("TokenAccount SKIPS a reverted transaction (security fix B2)", () => {
+  const tx = tokenTx([tokenBalance()], { err: { InstructionError: [0, "Custom"] } });
+  expect(run(makeFetcher(), 13, { transactions: [tx] }, [tokenEntry])).toEqual([]);
+});
+
+test("TokenAccount ignores balances for a different mint", () => {
+  const tx = tokenTx([tokenBalance({ mint: OTHER_MINT })]);
+  expect(run(makeFetcher(), 14, { transactions: [tx] }, [tokenEntry])).toEqual([]);
+});
+
+test("TokenAccount narrows by owner", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      mint: MINT,
+      owner: OWNER,
+    },
+  };
+  expect(
+    run(makeFetcher(), 15, { transactions: [tokenTx([tokenBalance()])] }, [entry]),
+  ).toHaveLength(1);
+  expect(
+    run(
+      makeFetcher(),
+      15,
+      { transactions: [tokenTx([tokenBalance({ owner: "someone-else" })])] },
+      [entry],
+    ),
+  ).toEqual([]);
+});
+
+test("TokenAccount narrows by tokenProgramId, separating Token-2022", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      mint: MINT,
+      tokenProgramId: TOKEN_2022_PROGRAM,
+    },
+  };
+  // Same mint, classic SPL Token program — must not match a Token-2022 filter.
+  expect(
+    run(makeFetcher(), 16, { transactions: [tokenTx([tokenBalance()])] }, [entry]),
+  ).toEqual([]);
+  expect(
+    run(
+      makeFetcher(),
+      16,
+      { transactions: [tokenTx([tokenBalance({ programId: TOKEN_2022_PROGRAM })])] },
+      [entry],
+    ),
+  ).toHaveLength(1);
+});
+
+test("TokenAccount narrows by tokenAccount", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      tokenAccount: TOKEN_ACCOUNT,
+    },
+  };
+  expect(
+    run(makeFetcher(), 17, { transactions: [tokenTx([tokenBalance()])] }, [entry]),
+  ).toHaveLength(1);
+  // accountIndex 1 resolves to WATCHED_PROGRAM, not the watched token account.
+  expect(
+    run(
+      makeFetcher(),
+      17,
+      { transactions: [tokenTx([tokenBalance({ accountIndex: 1 })])] },
+      [entry],
+    ),
+  ).toEqual([]);
+});
+
+test("TokenAccount emits one primitive per matching balance record", () => {
+  const tx = tokenTx([
+    tokenBalance(),
+    tokenBalance({ accountIndex: 1, owner: "second-owner" }),
+    tokenBalance({ mint: OTHER_MINT, accountIndex: 1 }),
+  ]);
+  const out = run(makeFetcher(), 18, { transactions: [tx] }, [tokenEntry]);
+  expect(out.length).toBe(2);
+  expect(out.map((p) => p.output.payload.owner)).toEqual([OWNER, "second-owner"]);
+});
+
+test("TokenAccount tolerates a transaction with no token balances", () => {
+  expect(run(makeFetcher(), 19, { transactions: [invokingTx()] }, [tokenEntry]))
+    .toEqual([]);
+});
+
+test("a TokenAccount entry is never treated as an AccountBalance", () => {
+  // The regression the type dispatch exists for. `SolanaPrimitive` is a flat bag of
+  // optionals, so a config can set `address` on a TokenAccount entry — under the old
+  // field-truthy dispatch (`if (prim.address)` first) that emitted a lamport-balance
+  // event under the token primitive's name.
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      mint: MINT,
+      address: TOKEN_ACCOUNT,
+    },
+  };
+  const out = run(makeFetcher(), 20, { transactions: [tokenTx([tokenBalance()])] }, [
+    entry,
+  ]);
+  expect(out.length).toBe(1);
+  expect(out[0].output.payloadType).toBe("solana:token-balance");
+  expect(out[0].output.payload).not.toHaveProperty("lamports");
+});
+
+test("an unsupported primitive type is ignored rather than misrouted", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "FromTheFuture",
+      type: "SOLANA:NotImplementedYet",
+      address: WATCHED_ADDRESS,
+      programId: WATCHED_PROGRAM,
+    },
+  };
+  expect(run(makeFetcher(), 21, { transactions: [invokingTx()] }, [entry]))
+    .toEqual([]);
+});

package/src/sync-protocols/solana/root-page.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import { toMsTimestamp } from "./types.ts";
+import { applyDelay } from "../common/utils.ts";
+
+/**
+ * The merge pulls buffered parallel (Solana) outputs in slot order and gates
+ * them with `rootPage <= mainChainTime`, so the root timestamp must be
+ * monotonically non-decreasing across slots. Solana guarantees that for
+ * `blockTime`, and duplicate blockTimes must map to EQUAL roots — the merge
+ * disambiguates by buffer/slot order, not by this value.
+ *
+ * Regression guard for the original `(slot % 1000) * 0.001` tiebreaker, which
+ * wrapped every 1000 slots so slot 1000 could sort before slot 999.
+ */
+
+/** What SolanaSyncState.toRootPage does, minus the config plumbing. */
+const rootPage = (blockTime: number, delayMs: number) =>
+  Number(applyDelay(toMsTimestamp(blockTime), delayMs));
+
+const DELAY = 2400;
+
+test("root timestamp is non-decreasing across a realistic slot stream", () => {
+  // Repeated blockTimes are normal: slots are ~400ms but blockTime has 1-second
+  // resolution, so several consecutive slots share a timestamp.
+  const stream = [
+    { slot: 100, blockTime: 1_700_000_000 },
+    { slot: 101, blockTime: 1_700_000_000 },
+    { slot: 102, blockTime: 1_700_000_001 },
+    { slot: 999, blockTime: 1_700_000_001 },
+    { slot: 1000, blockTime: 1_700_000_002 }, // the old %1000 wrap point
+    { slot: 1001, blockTime: 1_700_000_002 },
+  ];
+  const roots = stream.map((s) => rootPage(s.blockTime, DELAY));
+  for (let i = 1; i < roots.length; i++) {
+    expect(roots[i]).toBeGreaterThanOrEqual(roots[i - 1]);
+  }
+});
+
+test("the root depends only on blockTime, never on slot", () => {
+  // The previous version of this test compared f(x) to f(x), which holds for any
+  // implementation. Assert the actual property instead: a 1-second blockTime
+  // step moves the root by exactly 1000ms and nothing else contributes.
+  const a = rootPage(1_700_000_001, DELAY);
+  const b = rootPage(1_700_000_002, DELAY);
+  expect(b - a).toBe(1000);
+});
+
+test("ordering holds across the slot-1000 boundary that broke the old tiebreaker", () => {
+  // Under `(slot % 1000) * 0.001` the offset reset at slot 1000, so a later slot
+  // could sort before an earlier one. Verify the real ordering across it.
+  expect(rootPage(1_700_000_002, DELAY))
+    .toBeGreaterThan(rootPage(1_700_000_001, DELAY));
+});
+
+test("blockTime seconds convert to milliseconds", () => {
+  expect(Number(toMsTimestamp(1_700_000_000))).toBe(1_700_000_000_000);
+});
+
+test("delayMs shifts the root forward, preserving order", () => {
+  // applyDelay ADDS the confirmation delay so older blocks merge into more
+  // recent root slots (sync CLAUDE.md, design idea #3).
+  const undelayed = rootPage(1_700_000_000, 0);
+  const delayed = rootPage(1_700_000_000, DELAY);
+  expect(delayed - undelayed).toBe(DELAY);
+  expect(rootPage(1_700_000_001, DELAY)).toBeGreaterThan(delayed);
+});