feat(oracles): select every oracle replay through shared helpers

.github/workflows/pr.yml

@@ -21,13 +21,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
+          # The run-budget report compares changed files with the merge-base.
+          fetch-depth: 0
           persist-credentials: false
       - name: Setup Tools
         uses: tanstack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3
       - name: Check lint
         run: pnpm run lint:check
       - name: Check oracle lint without inline directives
         run: pnpm run lint:oracles
+      - name: Report lowered oracle run budgets
+        run: node scripts/check-oracle-run-counts.mjs --format=github
       - name: Test oracle lint rules
         run: pnpm run test:lint-rules
   minified-db:

AGENTS.md

@@ -134,6 +134,11 @@ after each edit and at the end of each turn. A hook sees only the edits that
 the harness's own edit tools make. After an edit through a shell command, or
 in a harness without these hooks, run `pnpm lint:changed` before you finish.
 
+The end-of-turn hook and `pnpm lint:changed` also report every oracle run
+budget that the branch lowered, and CI prints it as a warning. A lowered
+budget can be deliberate. Restore it, or explain the reason in the pull
+request.
+
 Fix a report. Do not turn the rule off. The hooks, `pnpm lint:changed`, the
 pre-commit hook, and CI ignore `eslint-disable` comments for these rules. A
 true exception needs a maintainer to change the rule in a reviewed pull

CONTRIBUTING.md

@@ -57,7 +57,9 @@ If you have been assigned to fix an issue or develop a new feature, please follo
   your branch changes. It does not replace `pnpm lint`. If you work with a
   coding agent, the repository's hooks return oracle lint reports to it as it
   edits. Codex and Gemini CLI run project hooks only after you
-  trust them in `/hooks`; review them again when they change.
+  trust them in `/hooks`; review them again when they change. In a linked Git
+  worktree, Codex reads project hooks from the main checkout, not from the
+  worktree, so the hooks run there only after the main checkout has them.
 
 - Implement your changes and tests in the relevant package or example.
 - For a production change that adds, removes, or changes observable behavior,

docs/contributing/oracle-coverage.md

@@ -410,7 +410,7 @@ does not award oracle credit for a filename alone.
 | [#1833](https://github.com/TanStack/db/pull/1833) | Explicit oracle                  | `packages/db/tests/query/pagination-oracle.property.test.ts` owns inherited collection collation, actual `item2`/`item10` order, exact request options, hostile lexical/numeric controls, and both scan and auto-index paths. It runs in `@tanstack/db`'s `test:oracles` campaign.                                                                                                               |
 | [#1834](https://github.com/TanStack/db/pull/1834) | Explicit oracle                  | `packages/db/tests/query/cold-join-reconciliation-oracle.test.ts` owns join/predicate equality equivalence across the established value domains, binary/string and nullish controls, replacement histories, raw lazy demand, and scan/auto-index paths. It runs in `@tanstack/db`'s `test:oracles` campaign.                                                                                     |
 | [#1835](https://github.com/TanStack/db/pull/1835) | Explicit oracle                  | The existing `packages/db/tests/collection-state-retention-oracle.property.test.ts` and `packages/db/tests/optimistic-transaction-oracle.property.test.ts` owners cover separate collection-state and transaction-history laws. Both were already registered in `@tanstack/db`'s `test:oracles` campaign; focused storage/local-only tests remain collateral.                                    |
-| [#1837](https://github.com/TanStack/db/pull/1837) | Explicit oracle                  | The offline scheduler, leadership replay, and serializer owners cover selective replay retirement, durable per-ID settlement, stale-read fencing, lifecycle recovery, native scalar encoding, and prior wire compatibility. They run in the package test campaign; generated owners expose `OFFLINE_ORACLE_{SEED,PATH,RUNS}` or the scheduler's `TANSTACK_DB_OFFLINE_ORACLE_*` replay interface. |
+| [#1837](https://github.com/TanStack/db/pull/1837) | Explicit oracle                  | The offline scheduler, leadership replay, and serializer owners cover selective replay retirement, durable per-ID settlement, stale-read fencing, lifecycle recovery, native scalar encoding, and prior wire compatibility. They run in the package test campaign. Every generated campaign in these owners uses the shared `TANSTACK_DB_ORACLE_{SEED,PATH,PROPERTY}` replay interface, with one property per campaign (`offline.fifo-retry`, `offline.leadership.*`, `offline.serializer.*`, `offline.settlement.*`). |
 | [#1842](https://github.com/TanStack/db/pull/1842) | No shipped-law case              | The PR changed only focused observer tests and introduced no production behavior. `packages/db/tests/live-query-observer.test.ts` remains the correct evidence; no synthetic oracle or campaign claim is added.                                                                                                                                                                                  |
 
 [PR #1816](https://github.com/TanStack/db/pull/1816) preserves existing witnesses,
@@ -2296,11 +2296,12 @@ properties have separate environment variables; inspect their test headers.
 Do not assume the core multiplier reaches them.
 
 The Node expression-index oracle runs matching fixed-seed and seedless-random
-campaigns by default. Supplying both replay values selects only the requested
-seed and shrink path:
+campaigns by default. A path replay of its property selects only the
+requested seed and shrink path:
 
 ```sh
-TANSTACK_DB_WS5A_SEED=1659005 TANSTACK_DB_WS5A_PATH=0 \
+TANSTACK_DB_ORACLE_SEED=1659005 TANSTACK_DB_ORACLE_PATH=0 \
+TANSTACK_DB_ORACLE_PROPERTY=sqlite-persistence.expression-index \
 pnpm --filter @tanstack/node-db-sqlite-persistence test:oracles
 ```
 

docs/contributing/oracle-reviews/2026-09-30-guide-portfolio.md

@@ -115,7 +115,7 @@ Revised means changed in executable revision 7e4266bb; retained means the assign
 | packages/db/tests/live-query-observer-history.property.test.ts | revised |
 | packages/db/tests/mutation-handler-type-oracle.test-d.ts | revised |
 | packages/db/tests/optimistic-transaction-oracle.property.test.ts | revised |
-| packages/db/tests/oracle-replay.fixture.test.ts | retained |
+| packages/db/tests/replay-guard-calibration.fixture.test.ts | retained |
 | packages/db/tests/oracle-replay.test.ts | revised |
 | packages/db/tests/paced-mutations-oracle.test.ts | retained |
 | packages/db/tests/query/cold-join-reconciliation-oracle.test.ts | revised |

docs/contributing/oracle-rubric.md

@@ -702,8 +702,12 @@ example or fixed campaign.
 
 [`fifo-retry-oracle.property.test.ts`](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/fifo-retry-oracle.property.test.ts)
 shows this shape. Its fixed run preserves one scheduler campaign. Its second
-campaign uses a random seed by default and accepts `OFFLINE_ORACLE_SEED` with
-`OFFLINE_ORACLE_PATH` for replay.
+campaign uses a random seed by default. To replay its recorded failure, set
+`TANSTACK_DB_ORACLE_PROPERTY=offline.fifo-retry` with
+`TANSTACK_DB_ORACLE_SEED` and `TANSTACK_DB_ORACLE_PATH`. The fixed run stands
+aside, and the random campaign runs the recorded path once. The offline
+owners' other properties use the same variables and name their own properties,
+such as `offline.leadership.stale-read` and `offline.settlement.retry-decision`.
 
 Do not use a larger random run count as a substitute for structural reach.
 Pinned examples force rare boundaries. Bounded enumeration proves small finite

package.json

@@ -21,6 +21,7 @@
     "lint:check": "pnpm --filter \"./packages/**\" lint --fix=false",
     "lint:changed": "node scripts/agent-lint-feedback.mjs",
     "lint:oracles": "node scripts/agent-lint-feedback.mjs --all",
+    "lint:run-budgets": "node scripts/check-oracle-run-counts.mjs",
     "test:lint-rules": "node --test \"scripts/eslint-plugin-oracle/*.test.js\"",
     "lint-all": "eslint . --fix",
     "prepare": "husky",

packages/browser-db-sqlite-persistence/tests/opfs-page-lifecycle-oracle.test.ts

@@ -1,5 +1,10 @@
 import { fc, test as fcTest } from '@fast-check/vitest'
 import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  oraclePropertyOptions,
+  oracleReplayTest,
+  oracleRuns,
+} from '../../db/tests/oracle-config'
 import { openBrowserWASQLiteOPFSDatabase } from '../src/opfs-database'
 import type {
   BrowserOPFSWorkerErrorCode,
@@ -932,66 +937,6 @@ afterEach(async () => {
   vi.useRealTimers()
 })
 
-const lifecycleSeed = Number(
-  process.env.TANSTACK_DB_OPFS_LIFECYCLE_ORACLE_SEED ?? 1844,
-)
-const lifecycleRuns = Number(
-  process.env.TANSTACK_DB_OPFS_LIFECYCLE_ORACLE_RUNS ?? 48,
-)
-const lifecyclePath = process.env.TANSTACK_DB_OPFS_LIFECYCLE_ORACLE_PATH
-const mixedSeed = Number(process.env.TANSTACK_DB_OPFS_MIXED_ORACLE_SEED ?? 1845)
-const mixedRuns = Number(process.env.TANSTACK_DB_OPFS_MIXED_ORACLE_RUNS ?? 32)
-const mixedPath = process.env.TANSTACK_DB_OPFS_MIXED_ORACLE_PATH
-const failureSeed = Number(
-  process.env.TANSTACK_DB_OPFS_FAILURE_ORACLE_SEED ?? 1846,
-)
-const failureRuns = Number(
-  process.env.TANSTACK_DB_OPFS_FAILURE_ORACLE_RUNS ?? 18,
-)
-const failurePath = process.env.TANSTACK_DB_OPFS_FAILURE_ORACLE_PATH
-const terminalEventSeed = Number(
-  process.env.TANSTACK_DB_OPFS_TERMINAL_EVENT_ORACLE_SEED ?? 1847,
-)
-const terminalEventRuns = Number(
-  process.env.TANSTACK_DB_OPFS_TERMINAL_EVENT_ORACLE_RUNS ?? 24,
-)
-const terminalEventPath =
-  process.env.TANSTACK_DB_OPFS_TERMINAL_EVENT_ORACLE_PATH
-const closeSeed = Number(process.env.TANSTACK_DB_OPFS_CLOSE_ORACLE_SEED ?? 1848)
-const closeRuns = Number(process.env.TANSTACK_DB_OPFS_CLOSE_ORACLE_RUNS ?? 32)
-const closePath = process.env.TANSTACK_DB_OPFS_CLOSE_ORACLE_PATH
-const replayRequested = [
-  process.env.TANSTACK_DB_OPFS_LIFECYCLE_ORACLE_SEED,
-  lifecyclePath,
-  process.env.TANSTACK_DB_OPFS_MIXED_ORACLE_SEED,
-  mixedPath,
-  process.env.TANSTACK_DB_OPFS_FAILURE_ORACLE_SEED,
-  failurePath,
-  process.env.TANSTACK_DB_OPFS_TERMINAL_EVENT_ORACLE_SEED,
-  terminalEventPath,
-  process.env.TANSTACK_DB_OPFS_CLOSE_ORACLE_SEED,
-  closePath,
-].some((value) => value !== undefined)
-
-type OracleCampaign = {
-  label: `fixed` | `random` | `replay`
-  seed?: number
-  path?: string
-}
-
-function oracleCampaigns(
-  seed: number,
-  replaySeedSupplied: boolean,
-  path: string | undefined,
-  replayRequestedForFile: boolean,
-): Array<OracleCampaign> {
-  if (replaySeedSupplied || path !== undefined) {
-    return [{ label: `replay`, seed, ...(path === undefined ? {} : { path }) }]
-  }
-  if (replayRequestedForFile) return []
-  return [{ label: `fixed`, seed }, { label: `random` }]
-}
-
 const pagehideHistory = fc.record({
   pending: fc.constantFrom<RequestKind>(`init`, `execute`, `close`),
   delivery: fc.constantFrom<DeliveryStage>(
@@ -1189,10 +1134,12 @@ bfcache admission, durability, native handle release, or wa-sqlite #88. The
 Chromium Web Lock fixture checks native queued-lock release separately.
 Challenge/replay: fixed examples exhaust the cheap structural products. Each
 generated lane runs a fixed and an unseeded campaign with the same grammar and
-run budget. Verbose FastCheck output retains original/reduced traces. Setting
-SEED or PATH selects only the direct replay for that lane. Use its
-TANSTACK_DB_OPFS_*_ORACLE_{SEED,RUNS,PATH} controls with this file's
-package-local Vitest command.
+run budget. Verbose FastCheck output retains original/reduced traces. A path
+replay selects only the direct replay of its lane's property, named by
+TANSTACK_DB_ORACLE_PROPERTY: opfs.page-lifecycle, opfs.mixed-execute,
+opfs.terminal-event, opfs.close, or opfs.failure-cleanup. A seed without a
+path reseeds the unseeded campaigns. Run it with this file's package-local
+Vitest command.
 */
 describe(`OPFS page lifecycle oracle`, () => {
   it.each([
@@ -1397,93 +1344,89 @@ describe(`OPFS page lifecycle oracle`, () => {
     expectDisposed(page, worker)
   })
 
-  for (const campaign of oracleCampaigns(
-    lifecycleSeed,
-    process.env.TANSTACK_DB_OPFS_LIFECYCLE_ORACLE_SEED !== undefined,
-    lifecyclePath,
-    replayRequested,
-  )) {
-    fcTest.prop([pagehideHistory], {
-      ...(campaign.seed === undefined ? {} : { seed: campaign.seed }),
-      numRuns: lifecycleRuns,
-      ...(campaign.path === undefined ? {} : { path: campaign.path }),
-      examples: pagehideExamples,
-      verbose: true,
-    })(
-      `matches the independent model across generated histories (${campaign.label})`,
-      runPagehideHistory,
-    )
-  }
-
-  for (const campaign of oracleCampaigns(
-    mixedSeed,
-    process.env.TANSTACK_DB_OPFS_MIXED_ORACLE_SEED !== undefined,
-    mixedPath,
-    replayRequested,
-  )) {
-    fcTest.prop([mixedExecuteHistory], {
-      ...(campaign.seed === undefined ? {} : { seed: campaign.seed }),
-      numRuns: mixedRuns,
-      ...(campaign.path === undefined ? {} : { path: campaign.path }),
-      examples: mixedExamples,
-      verbose: true,
-    })(
-      `preserves completed siblings while aborting pending siblings (${campaign.label})`,
-      runMixedExecuteHistory,
-    )
-  }
-
-  for (const campaign of oracleCampaigns(
-    terminalEventSeed,
-    process.env.TANSTACK_DB_OPFS_TERMINAL_EVENT_ORACLE_SEED !== undefined,
-    terminalEventPath,
-    replayRequested,
-  )) {
-    fcTest.prop([terminalEventHistory], {
-      ...(campaign.seed === undefined ? {} : { seed: campaign.seed }),
-      numRuns: terminalEventRuns,
-      ...(campaign.path === undefined ? {} : { path: campaign.path }),
-      examples: terminalEventExamples,
-      verbose: true,
-    })(
-      `rejects pending work across Worker terminal event paths (${campaign.label})`,
-      runTerminalEventHistory,
-    )
-  }
-
-  for (const campaign of oracleCampaigns(
-    closeSeed,
-    process.env.TANSTACK_DB_OPFS_CLOSE_ORACLE_SEED !== undefined,
-    closePath,
-    replayRequested,
-  )) {
-    fcTest.prop([closeHistory], {
-      ...(campaign.seed === undefined ? {} : { seed: campaign.seed }),
-      numRuns: closeRuns,
-      ...(campaign.path === undefined ? {} : { path: campaign.path }),
-      examples: closeExamples,
-      verbose: true,
-    })(
-      `settles pending work and refuses new work across explicit close (${campaign.label})`,
-      runCloseHistory,
-    )
-  }
-
-  for (const campaign of oracleCampaigns(
-    failureSeed,
-    process.env.TANSTACK_DB_OPFS_FAILURE_ORACLE_SEED !== undefined,
-    failurePath,
-    replayRequested,
-  )) {
-    fcTest.prop([failureHistory], {
-      ...(campaign.seed === undefined ? {} : { seed: campaign.seed }),
-      numRuns: failureRuns,
-      ...(campaign.path === undefined ? {} : { path: campaign.path }),
-      examples: failureExamples,
-      verbose: true,
-    })(
-      `matches terminal cleanup and error mapping across worker failures (${campaign.label})`,
-      runFailureHistory,
-    )
-  }
+  oracleReplayTest(fcTest).prop([pagehideHistory], {
+    seed: 1844,
+    numRuns: oracleRuns(48),
+    examples: pagehideExamples,
+    verbose: true,
+  })(
+    `matches the independent model across generated histories (fixed)`,
+    runPagehideHistory,
+  )
+  oracleReplayTest(fcTest, `opfs.page-lifecycle`).prop([pagehideHistory], {
+    ...oraclePropertyOptions(48, `opfs.page-lifecycle`),
+    examples: pagehideExamples,
+    verbose: true,
+  })(
+    `matches the independent model across generated histories (random)`,
+    runPagehideHistory,
+  )
+  oracleReplayTest(fcTest).prop([mixedExecuteHistory], {
+    seed: 1845,
+    numRuns: oracleRuns(32),
+    examples: mixedExamples,
+    verbose: true,
+  })(
+    `preserves completed siblings while aborting pending siblings (fixed)`,
+    runMixedExecuteHistory,
+  )
+  oracleReplayTest(fcTest, `opfs.mixed-execute`).prop([mixedExecuteHistory], {
+    ...oraclePropertyOptions(32, `opfs.mixed-execute`),
+    examples: mixedExamples,
+    verbose: true,
+  })(
+    `preserves completed siblings while aborting pending siblings (random)`,
+    runMixedExecuteHistory,
+  )
+  oracleReplayTest(fcTest).prop([terminalEventHistory], {
+    seed: 1847,
+    numRuns: oracleRuns(24),
+    examples: terminalEventExamples,
+    verbose: true,
+  })(
+    `rejects pending work across Worker terminal event paths (fixed)`,
+    runTerminalEventHistory,
+  )
+  oracleReplayTest(fcTest, `opfs.terminal-event`).prop([terminalEventHistory], {
+    ...oraclePropertyOptions(24, `opfs.terminal-event`),
+    examples: terminalEventExamples,
+    verbose: true,
+  })(
+    `rejects pending work across Worker terminal event paths (random)`,
+    runTerminalEventHistory,
+  )
+  oracleReplayTest(fcTest).prop([closeHistory], {
+    seed: 1848,
+    numRuns: oracleRuns(32),
+    examples: closeExamples,
+    verbose: true,
+  })(
+    `settles pending work and refuses new work across explicit close (fixed)`,
+    runCloseHistory,
+  )
+  oracleReplayTest(fcTest, `opfs.close`).prop([closeHistory], {
+    ...oraclePropertyOptions(32, `opfs.close`),
+    examples: closeExamples,
+    verbose: true,
+  })(
+    `settles pending work and refuses new work across explicit close (random)`,
+    runCloseHistory,
+  )
+  oracleReplayTest(fcTest).prop([failureHistory], {
+    seed: 1846,
+    numRuns: oracleRuns(18),
+    examples: failureExamples,
+    verbose: true,
+  })(
+    `matches terminal cleanup and error mapping across worker failures (fixed)`,
+    runFailureHistory,
+  )
+  oracleReplayTest(fcTest, `opfs.failure-cleanup`).prop([failureHistory], {
+    ...oraclePropertyOptions(18, `opfs.failure-cleanup`),
+    examples: failureExamples,
+    verbose: true,
+  })(
+    `matches terminal cleanup and error mapping across worker failures (random)`,
+    runFailureHistory,
+  )
 })