feat(oracles): require every oracle test to reach a declared part

.gitignore

@@ -48,3 +48,7 @@ examples/react-native/shopping-list/ios/
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 tsconfig.vitest-temp.json
+
+# The part-reach oracle lints scratch programs inside the repository; an
+# interrupted run can leave them behind.
+/part-reach-scratch-*/

AGENTS.md

@@ -138,9 +138,10 @@ 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.
+budget that the branch lowered or removed, and CI prints it as a warning. A
+budget is removed when its key is in no oracle file, or in a module that an
+oracle file imports, any more. A lowered or removed 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
@@ -729,6 +730,15 @@ Modules that define the model, checker, or its history grammar also qualify.
 Identify the actual mechanism before renaming a file. A coverage-map entry,
 contract comment, or collection of fixed assertions is not sufficient evidence.
 
+An oracle file holds only oracle tests. It declares its check, model, and history
+grammar with `declareOracle` from `packages/db/tests/oracle-declaration.ts`. A
+type-level oracle names its model types in `typeModel`. Each
+part is optional. Every test in the file must use a declared part, directly
+or through a driver, or run a generated property that states its law inline.
+A test that compares production with a hand-written value is a unit test:
+put it in an ordinary test file. The `oracle/no-unit-test` lint rule reports
+a test that does neither.
+
 Ordinary example tests, type assertions, fixtures, registration wrappers, and
 runner utilities keep their ordinary names. A module that only drives production
 or records observations is not an oracle definition. Report oracle owners and

docs/contributing/oracle-rubric.md

@@ -390,6 +390,45 @@ Use `oracle` in filenames that own an independent expected-result computation,
 state model, differential or metamorphic comparison, or reusable law checker.
 A separate module that defines that model, checker, or its history grammar also
 qualifies. Identify the mechanism in the code before applying the name.
+
+An oracle file holds only oracle tests. It names its parts with
+`declareOracle({ check: [...], model: [...], grammar: [...] })` from
+[`oracle-declaration.ts`](../../packages/db/tests/oracle-declaration.ts), which
+imports nothing so that browser and native-app modules can use it: the check
+compares production observations with the model or with a second
+formulation, and the grammar is the generators that produce legal histories.
+Each part is optional. Every test in the file uses a declared part, directly
+or through a driver:
+
+- A generated property or a fixed history runs through the check.
+- A model pin steps the model and checks one rule against its authority.
+- A calibration shows that the check rejects a wrong answer (ORC-006).
+- A grammar calibration shows that the generators reach the states that the
+  laws need (ORC-004, ORC-015).
+- A generated property can state its law inline: its predicate relates
+  production to inputs that nobody wrote down. A property whose arbitraries
+  are all constants, or whose predicate ignores its input, checks written
+  values instead.
+- A type-level test compares an inferred type with a type model. A type has no
+  value to pass, so the file names its model types in
+  `declareOracle({ typeModel: [...] })`. Each name is a type alias or
+  interface in the same file, and a type built from one counts as using it.
+
+A test that uses none of them compares production with a hand-written value. It
+is a unit test, even when it asserts a contract, and it belongs in an
+ordinary test file beside the oracle. A finite table of hand-written expected
+values selected by a test's parameters is not a model. The `oracle/no-unit-test` lint rule
+reports such a test. Files named `oracle-*`, such as `oracle-config.ts`, are
+the shared oracle machinery and declare no parts.
+
+An oracle file also registers no test through a helper from an ordinary module.
+The rule reports a call to such a helper, because the helper's tests then appear
+under the oracle file. The ordinary runner registers those tests, and passes the
+shared suite a registrar when the suite needs one. A helper from an oracle-named
+module is linted on its own, so the rule does not report a call to it. An
+`oracle-` machinery module, such as `oracle-config.ts`, is not linted, so the
+rule judges a call to its helpers as it judges an ordinary module's.
+
 ORC-016 keeps ordinary unit tests and concrete type assertions out of oracle
 files. Fixed regressions replay the shared law; supplemental examples live in
 ordinary test files.

examples/react/action-enforcement/eslint-rules/no-direct-collection-mutations-oracle.test.js → examples/react/action-enforcement/eslint-rules/no-direct-collection-mutations.test.js

@@ -15,7 +15,9 @@ import config from '../eslint.config.mjs'
  * Moving a callback definition before an alias cannot change that alias's value
  * when the callback runs after initialization.
  *
- * This finite syntax oracle covers the bindings, call forms, and scopes below.
+ * These are fixed tests, not an oracle: each expected diagnostic count is a
+ * written value, chosen by the method under test (the operations table). They
+ * cover the bindings, call forms, and scopes below.
  * It does not model execution paths, inter-module re-exports, function arguments,
  * factory returns, dynamic method names, or aliases stored in new containers.
  * Mutable aliases conservatively retain their Collection classification.

lint-staged.config.js

@@ -5,9 +5,19 @@
 const chunkSize = 40
 
 export default {
-  // The oracle rules, without inline directives. lint-staged appends the
-  // staged oracle files as arguments.
-  '*oracle*.{ts,tsx}': `node scripts/agent-lint-feedback.mjs`,
+  // The oracle rules, without inline directives. The script lints the oracle
+  // files that each staged test or support module affects, so every module
+  // that an oracle can import is passed. It selects the oracle files itself.
+  '*.{ts,tsx,js,mjs}': (files) => {
+    const commands = []
+    for (let start = 0; start < files.length; start += chunkSize) {
+      const chunk = files.slice(start, start + chunkSize)
+      commands.push(
+        `node scripts/agent-lint-feedback.mjs ${chunk.map((file) => `"${file}"`).join(` `)}`,
+      )
+    }
+    return commands
+  },
   '*.{ts,tsx}': (files) => {
     const commands = []
     for (let start = 0; start < files.length; start += chunkSize) {

package.json

@@ -22,7 +22,7 @@
     "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\"",
+    "test:lint-rules": "vitest run --config scripts/eslint-plugin-oracle/vitest.config.mjs && vitest run --config scripts/oracle-scripts.vitest.config.mjs",
     "lint-all": "eslint . --fix",
     "prepare": "husky",
     "test": "pnpm --filter \"./packages/**\" test && pnpm --filter @tanstack/db test:indexed-db:package",

packages/browser-db-sqlite-persistence/e2e/hydration-commit-oracle.opfs.spec.ts → packages/browser-db-sqlite-persistence/e2e/hydration-commit.opfs.spec.ts

@@ -1,3 +1,38 @@
+/**
+ * Harness self-test for the hydration-commit checkpoint: the fixture's cleanup
+ * failures must not replace the primary observation. The real-provider matrix below
+ * is in this file too.
+ */
+import { expect, test } from '@playwright/test'
+import type { HydrationCommitObservation } from './hydration-commit.opfs'
+
+// ORC-010 calibration: two teardown failures cannot erase the independently
+// captured observation, mutate its receipt errors, or hide one another.
+test(`preserves the primary observation through multiple cleanup failures`, async ({
+  page,
+}) => {
+  await page.goto(
+    `/e2e/hydration-commit.opfs.html?phase=after-ready&baseline=false&coordinator=browser&rich=false&cleanupFault=true`,
+  )
+  await page.waitForFunction(() => window.__hydrationCommitDone === true)
+  const result = await page.evaluate(() => ({
+    observation: window.__hydrationCommitResult,
+    error: window.__hydrationCommitError,
+    cleanup: window.__hydrationCommitCleanupErrors,
+  }))
+  expect(result.error).toBeUndefined()
+  expect(result.observation?.cycleCalls).toBe(0)
+  expect(result.observation?.errors).toEqual([])
+  expect(result.observation?.reopenedRows).toEqual([
+    { id: `r1`, value: 1 },
+    { id: `tail`, value: 9 },
+  ])
+  expect(result.cleanup).toEqual([
+    `Error: injected first cleanup failure`,
+    `Error: injected last cleanup failure`,
+  ])
+})
+
 /**
  * Real-provider refinement of the law/driver in hydration-commit.opfs.ts.
  * The insert history retains baseline+r1. The rich history replaces all rows,
@@ -10,8 +45,23 @@
  * post-cleanup fresh claim checks durable rows, not offline Collection restore;
  * a partial on-demand cache has no authority to restore public rows alone.
  */
-import { expect, test } from '@playwright/test'
-import type { HydrationCommitObservation } from './hydration-commit.opfs'
+// The edit-log model's rows after the receipt cut and the ordinary tail: the rich
+// history replaces all rows with r2; the insert history keeps r1 and an optional baseline.
+function expectedHydrationCommitRows(
+  baseline: boolean,
+  rich: boolean,
+): Array<{ id: string; value: number }> {
+  return rich
+    ? [
+        { id: `r2`, value: 3 },
+        { id: `tail`, value: 9 },
+      ]
+    : [
+        ...(baseline ? [{ id: `baseline`, value: 0 }] : []),
+        { id: `r1`, value: 1 },
+        { id: `tail`, value: 9 },
+      ]
+}
 
 for (const phase of [`startup`, `subscription`, `after-ready`] as const) {
   for (const baseline of [false, true]) {
@@ -82,16 +132,7 @@ for (const phase of [`startup`, `subscription`, `after-ready`] as const) {
             ordinary: `fulfilled`,
             exited: phase === `after-ready` ? null : true,
           })
-          const expected = rich
-            ? [
-                { id: `r2`, value: 3 },
-                { id: `tail`, value: 9 },
-              ]
-            : [
-                ...(baseline ? [{ id: `baseline`, value: 0 }] : []),
-                { id: `r1`, value: 1 },
-                { id: `tail`, value: 9 },
-              ]
+          const expected = expectedHydrationCommitRows(baseline, rich)
           expect(observed.rows).toEqual(expected)
           expect(observed.durableRows).toEqual(expected)
           expect(observed.reopenedRows).toEqual(expected)
@@ -122,30 +163,3 @@ for (const phase of [`startup`, `subscription`, `after-ready`] as const) {
     }
   }
 }
-
-// ORC-010 calibration: two teardown failures cannot erase the independently
-// captured observation, mutate its receipt errors, or hide one another.
-test(`preserves the primary observation through multiple cleanup failures`, async ({
-  page,
-}) => {
-  await page.goto(
-    `/e2e/hydration-commit.opfs.html?phase=after-ready&baseline=false&coordinator=browser&rich=false&cleanupFault=true`,
-  )
-  await page.waitForFunction(() => window.__hydrationCommitDone === true)
-  const result = await page.evaluate(() => ({
-    observation: window.__hydrationCommitResult,
-    error: window.__hydrationCommitError,
-    cleanup: window.__hydrationCommitCleanupErrors,
-  }))
-  expect(result.error).toBeUndefined()
-  expect(result.observation?.cycleCalls).toBe(0)
-  expect(result.observation?.errors).toEqual([])
-  expect(result.observation?.reopenedRows).toEqual([
-    { id: `r1`, value: 1 },
-    { id: `tail`, value: 9 },
-  ])
-  expect(result.cleanup).toEqual([
-    `Error: injected first cleanup failure`,
-    `Error: injected last cleanup failure`,
-  ])
-})

packages/browser-db-sqlite-persistence/e2e/install-layout-oracle.e2e.test.ts

@@ -48,6 +48,7 @@ import { fileURLToPath } from 'node:url'
 import { chromium } from '@playwright/test'
 import { afterAll, beforeAll, expect, it } from 'vitest'
 import { createServer, preview } from 'vite'
+import { declareOracle } from '../../db/tests/oracle-declaration'
 import { buildForProduction } from './packaged-consumer'
 import type { Browser } from '@playwright/test'
 import type { BrowserWASQLiteDatabase } from '../src'
@@ -169,6 +170,23 @@ const layoutCases: Array<LayoutCase> = [
   })),
 ]
 
+declareOracle({
+  check: [expectLayoutOutcome],
+  model: [expectedOutcome],
+  grammar: [layoutCases],
+})
+
+// The check: the installed copy's observed outcome equals the layout model's
+// prediction for the same case and install facts.
+async function expectLayoutOutcome(
+  layoutCase: LayoutCase,
+  install: InstallFacts,
+): Promise<void> {
+  expect(await openInLayout(install, layoutCase)).toEqual(
+    expectedOutcome(layoutCase, install),
+  )
+}
+
 let browser: Browser
 const coveredOutcomes = new Set<string>()
 beforeAll(async () => {
@@ -188,7 +206,7 @@ it.each(layoutCases)(
       const install = installLayout(temporaryDirectory, layoutCase.layout)
       const expected = expectedOutcome(layoutCase, install)
       coveredOutcomes.add(JSON.stringify(expected))
-      expect(await openInLayout(install, layoutCase)).toEqual(expected)
+      await expectLayoutOutcome(layoutCase, install)
     } finally {
       rmSync(temporaryDirectory, { recursive: true, force: true })
     }