diff --git a/.agents/skills/oracle-authoring/SKILL.md b/.agents/skills/oracle-authoring/SKILL.md index b6128f45dc..2b94566a36 100644 --- a/.agents/skills/oracle-authoring/SKILL.md +++ b/.agents/skills/oracle-authoring/SKILL.md @@ -9,7 +9,7 @@ Start by making the law clear enough that someone could predict an observation without reading production. The hard part is deciding what is owed, to whom, under which conditions, and when. An executable model enacts that account. -Read [the oracle guide](../../../docs/contributing/oracle-tests.md), +Read [the oracle guide](../../../docs/contributing/oracle-rubric.md), [the glossary](../../../docs/contributing/glossary.md), and the relevant owner and limits in [the coverage map](../../../docs/contributing/oracle-coverage.md). Follow the subsystem reading requirements in AGENTS.md. diff --git a/.agents/skills/oracle-review/SKILL.md b/.agents/skills/oracle-review/SKILL.md index 75ba1162c3..95f7e0cafc 100644 --- a/.agents/skills/oracle-review/SKILL.md +++ b/.agents/skills/oracle-review/SKILL.md @@ -9,7 +9,7 @@ Ask both whether the oracle enforces its stated law and whether that is the right law to promise. A passing test can coexist with a wrong theory; a failing test can coexist with correct production. -Read [the oracle guide](../../../docs/contributing/oracle-tests.md), +Read [the oracle guide](../../../docs/contributing/oracle-rubric.md), [the glossary](../../../docs/contributing/glossary.md), and the relevant owner and limits in [the coverage map](../../../docs/contributing/oracle-coverage.md). Follow the subsystem reading requirements in AGENTS.md. Guide conformance is diff --git a/AGENTS.md b/AGENTS.md index 7518574818..a32486c90e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -442,7 +442,7 @@ const dependentBuilders = [] // Accurately describes dependents ### Required reading: oracle tests Before designing, changing, or reviewing an oracle or generated-history test, -read [Writing reliable oracle tests](docs/contributing/oracle-tests.md). +read [Oracle Testing Rubric](docs/contributing/oracle-rubric.md). Use the [coverage map](docs/contributing/oracle-coverage.md) to find an existing owner and its limits before adding another model. The guide explains testing methods; it does not authorize new product behavior or retire existing laws. @@ -452,9 +452,9 @@ methods; it does not authorize new product behavior or retire existing laws. Write every oracle and generated-history test as a literate program. Combine explanatory prose with executable code so the file teaches the subsystem contract. Follow -[ORC-003](docs/contributing/oracle-tests.md#orc-003-distinguishable-oracle-responsibilities) +[ORC-003](docs/contributing/oracle-rubric.md#orc-003-distinguishable-oracle-responsibilities) and the guide's -[literate-oracle guidance](docs/contributing/oracle-tests.md#write-the-oracle-as-executable-subsystem-documentation). +[literate-oracle guidance](docs/contributing/oracle-rubric.md#write-the-oracle-as-executable-subsystem-documentation). Start with the promised law and its limits before introducing test mechanics. Explain the central law beside the independent model. Describe the legal diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23669fff9c..d34fb357a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,7 @@ If you have been assigned to fix an issue or develop a new feature, please follo coverage-map entry and explain why you cannot extend its owner, create an independent oracle, or add a receiving witness. See the [oracle coverage map](docs/contributing/oracle-coverage.md) and - [oracle test guide](docs/contributing/oracle-tests.md). + [Oracle Testing Rubric](docs/contributing/oracle-rubric.md). - For a bug fix, state how the pull request evaluated and closed the declared bug class. Include the violated law, exercised histories, production paths, observation checkpoints, RED/GREEN evidence, and remaining limits. A passing diff --git a/docs/contributing/instruments/index.md b/docs/contributing/instruments/index.md index 81fd74e9ea..340aa86a52 100644 --- a/docs/contributing/instruments/index.md +++ b/docs/contributing/instruments/index.md @@ -14,7 +14,7 @@ reasoning step or a fixed workflow. | Should these laws or concepts be merged, split, replaced, or removed? | [Law restructuring](law-restructuring.md) | An alternative organization and a check of what it preserves or loses. | These are reasoning aids, not additional oracle conformance requirements. The -[oracle guide](../oracle-tests.md) owns testing requirements. Use the +[oracle guide](../oracle-rubric.md) owns testing requirements. Use the [glossary](../glossary.md) and the relevant architecture and contract sources. The authoring and review skills route oracle work here; the cards can also help with architecture and other design questions. diff --git a/docs/contributing/instruments/mutant-gap-hunt.md b/docs/contributing/instruments/mutant-gap-hunt.md index d6453d0be3..6b71a0ad22 100644 --- a/docs/contributing/instruments/mutant-gap-hunt.md +++ b/docs/contributing/instruments/mutant-gap-hunt.md @@ -58,14 +58,14 @@ distinguish a mistake. Keep test bodies and assertions out of the design brief. rejecting a legal alternative. For a bug on the baseline, demonstrate the production RED before its repair. Update the coverage map when the owner's reach or limits change. For a claimed oracle repair, follow - [ORC-012](../oracle-tests.md#orc-012-review-evidence): at closeout, + [ORC-012](../oracle-rubric.md#orc-012-review-evidence): at closeout, verdict-critical evidence outside the executable oracle belongs in a versioned review record tied to the exact reviewed head. This card also asks the record to name the executable revision of every campaign, witness, and review-fix run behind its claims. **Return:** each chosen mutant's pinned revision, exact edit, observed run -outcome using [ORC-006's categories](../oracle-tests.md#orc-006-checker-calibration), +outcome using [ORC-006's categories](../oracle-rubric.md#orc-006-checker-calibration), public distinction or scoped equivalence argument, and disposition: oracle gap, product bug, permitted difference, equivalence at a stated grade, or unresolved. Keep raw run logs and result tables task-local unless the task explicitly asks diff --git a/docs/contributing/oracle-coverage.md b/docs/contributing/oracle-coverage.md index 384d5de3cd..00fec5a8c7 100644 --- a/docs/contributing/oracle-coverage.md +++ b/docs/contributing/oracle-coverage.md @@ -1,6 +1,6 @@ # Oracle coverage and closeout -Use [Writing reliable oracle tests](oracle-tests.md) when adding or reviewing a +Use [Oracle Testing Rubric](oracle-rubric.md) when adding or reviewing a law. This map identifies existing owners, their judgment, and their limits. It is not a claim that every state or every test has been audited. diff --git a/docs/contributing/oracle-reviews/2026-09-25-query-readiness.md b/docs/contributing/oracle-reviews/2026-09-25-query-readiness.md index ef522dc865..9df900b300 100644 --- a/docs/contributing/oracle-reviews/2026-09-25-query-readiness.md +++ b/docs/contributing/oracle-reviews/2026-09-25-query-readiness.md @@ -108,7 +108,7 @@ The preservation contract was frozen before the final grammar changes: | DG-P6 | A fulfilled Promise parent remains owned when its continuation throws; repair debt is recorded without retiring the successful acquisition. | Acquisition ownership and repair contract | | DG-P7 | Nullable multi-term ordering varies each term's direction and null placement independently. | Public order-by semantics | | DG-P8 | Readiness evidence includes rows and status; work evidence includes the exact acquisition and release trace. | Oracle observation contract | -| DG-P9 | A primary oracle mismatch remains primary while every cleanup failure remains distinguishable and every cleanup is attempted. | `oracle-tests.md` ORC-010 | +| DG-P9 | A primary oracle mismatch remains primary while every cleanup failure remains distinguishable and every cleanup is attempted. | `oracle-rubric.md` ORC-010 | | DG-P10 | Explicit-window, replay, repair, and Effect scheduling laws keep their existing owners; this grammar does not silently absorb them. | Coverage map and user-confirmed scope | The surviving grammar has four separate subgrammars rather than one artificial diff --git a/docs/contributing/oracle-reviews/code-weight-draft-proxy.md b/docs/contributing/oracle-reviews/code-weight-draft-proxy.md index 5365cdcc82..fa69043373 100644 --- a/docs/contributing/oracle-reviews/code-weight-draft-proxy.md +++ b/docs/contributing/oracle-reviews/code-weight-draft-proxy.md @@ -24,7 +24,7 @@ commit. - `0ce101acf` fixes two more lost-write classes from CodeRabbit review: accessor definitions and typed-array mutator methods. - `cbd2aff06` and `556cbd8ff` act on a loss audit of these oracles against - `docs/contributing/oracle-tests.md`. They fix one bug, make the array and + `docs/contributing/oracle-rubric.md`. They fix one bug, make the array and typed-array laws generated, and close the audit's grammar, checkpoint, and replay gaps. - `7e5dfee25` fixes three bugs that code review found in the earlier fixes: diff --git a/docs/contributing/oracle-reviews/issue-2034-design/model.md b/docs/contributing/oracle-reviews/issue-2034-design/model.md index 8e6f698961..b61bc933a1 100644 --- a/docs/contributing/oracle-reviews/issue-2034-design/model.md +++ b/docs/contributing/oracle-reviews/issue-2034-design/model.md @@ -32,7 +32,7 @@ These are dimensions of one contract, not six proposed production classes. | P3 | Representation mapping: runtime value ↔ tagged wire/storage value, plus operation-specific query representation | Stored spelling alone cannot establish query semantics or old-reader behavior. | E1/E3/E4 | | P4 | Operation and observation: encode/revive, equality, order, candidate filtering, pagination, index lifecycle, accepted/rejected committed write | Storing a value does not imply it can be ordered or safely filtered in SQL. | E2–E7 | | P5 | Execution boundary: direct core, transaction driver, persisted wrapper/coordinator, platform host | Erasing boundary borrows admission, ordering or native-host evidence from a different route. | E5/E7/E8/E10 | -| P6 | Evidence obligation: positive path reach, independent expected result, checkpoint, wrong-design control, declared limit | Removing it promotes a green serializer/control into end-to-end support. | oracle-tests.md and E10 | +| P6 | Evidence obligation: positive path reach, independent expected result, checkpoint, wrong-design control, declared limit | Removing it promotes a green serializer/control into end-to-end support. | oracle-rubric.md and E10 | ## Relations, overlaps and grammar rules diff --git a/docs/contributing/oracle-reviews/issue-2071-refused-insert.md b/docs/contributing/oracle-reviews/issue-2071-refused-insert.md index b5a8239420..b0b241781f 100644 --- a/docs/contributing/oracle-reviews/issue-2071-refused-insert.md +++ b/docs/contributing/oracle-reviews/issue-2071-refused-insert.md @@ -72,7 +72,7 @@ All mutants were temporary and restored before commit. Each failure below reache A narrower attempt that removed only the direct `pendingLocalChanges` check survived the truncate witness because the retained truncate snapshot enforced the same rule. That survival does not weaken M7's separate assertion failure and is not counted as a kill. The old model's false RED and M10's production assertion failure are distinct controls. M8 and M9 directly challenge the reported ghost-row class; M2 and M3 challenge the neighboring source and timing laws. -On executable commit `3e33fec8d`, the two core optimistic-history suites passed **37/37**, with no type errors. The affected persistence suites passed **869**, with **2 existing todos** and no type errors. Prettier and `git diff --check` passed. The docs link check still exits 1 on two links in unchanged `docs/contributing/oracle-tests.md` that point outside the docs tree; it reports no new link from this review. The `@tanstack/db` build passed earlier in this review, before the final test and documentation edits. The reported release's scratch controlled matrix passed five selected probes, and its fresh-adapter SQLite probe passed three selected tests. The release probes are uncommitted diagnostic files in a separate checkout; only the current-head witnesses are in the executable commits. +On executable commit `3e33fec8d`, the two core optimistic-history suites passed **37/37**, with no type errors. The affected persistence suites passed **869**, with **2 existing todos** and no type errors. Prettier and `git diff --check` passed. The docs link check still exits 1 on two links in unchanged `docs/contributing/oracle-rubric.md` that point outside the docs tree; it reports no new link from this review. The `@tanstack/db` build passed earlier in this review, before the final test and documentation edits. The reported release's scratch controlled matrix passed five selected probes, and its fresh-adapter SQLite probe passed three selected tests. The release probes are uncommitted diagnostic files in a separate checkout; only the current-head witnesses are in the executable commits. ## Oracle guide audit (ORC-001–014) diff --git a/docs/contributing/oracle-tests.md b/docs/contributing/oracle-rubric.md similarity index 99% rename from docs/contributing/oracle-tests.md rename to docs/contributing/oracle-rubric.md index 9b4d8ffaff..bab27011ad 100644 --- a/docs/contributing/oracle-tests.md +++ b/docs/contributing/oracle-rubric.md @@ -1,4 +1,4 @@ -# Writing reliable oracle tests +# Oracle Testing Rubric A test needs two things: something to try, and a way to tell whether it worked. @@ -23,7 +23,7 @@ numbered requirements below continue to define guide conformance. ## How to interpret this guide The numbered requirements in this section are the complete checklist for an -`oracle-tests.md` conformance audit. Repository policies such as `AGENTS.md` and +`oracle-rubric.md` conformance audit. Repository policies such as `AGENTS.md` and the coverage map apply separately. Later sections explain the requirements and give techniques and examples. They do not create additional requirements unless they cite one of these IDs. diff --git a/docs/contributing/oracle-test-notes.md b/docs/contributing/oracle-test-notes.md index 888333faf5..15e4e5fc62 100644 --- a/docs/contributing/oracle-test-notes.md +++ b/docs/contributing/oracle-test-notes.md @@ -1,6 +1,6 @@ # Oracle guide: cases, terms and sources -Companion to [Writing reliable oracle tests](oracle-tests.md). These notes keep evidence and deeper reading off the quick-start path. The historical entries describe archived reports and audits, not current failing tests or reruns performed for this guide. +Companion to [Oracle Testing Rubric](oracle-rubric.md). These notes keep evidence and deeper reading off the quick-start path. The historical entries describe archived reports and audits, not current failing tests or reruns performed for this guide. The shared terms used here are defined in the [project glossary](glossary.md). That glossary is the vocabulary owner for diff --git a/packages/db-ivm/tests/incrementalization-law-oracle.property.test.ts b/packages/db-ivm/tests/incrementalization-law-oracle.property.test.ts index b9c6e18265..6831dc4281 100644 --- a/packages/db-ivm/tests/incrementalization-law-oracle.property.test.ts +++ b/packages/db-ivm/tests/incrementalization-law-oracle.property.test.ts @@ -81,7 +81,7 @@ function withoutPromotion(): PipedOperator { * D2 operators keep state and emit only changes. A wrong delta can leave the * final rows looking right after a later batch, so final-state examples are not * enough. The package README defines MultiSet data as signed changes. The DBSP - * accumulation/difference law in docs/contributing/oracle-tests.md authorizes + * accumulation/difference law in docs/contributing/oracle-rubric.md authorizes * comparison of the net emitted delta and retained relation with a direct * recomputation after each logical batch. It does not specify message order, * client publication, or readiness. diff --git a/packages/query-db-collection/tests/cursor-pagination/LOSS-AUDIT.md b/packages/query-db-collection/tests/cursor-pagination/LOSS-AUDIT.md index 8cf25fe24b..3c52ca92ff 100644 --- a/packages/query-db-collection/tests/cursor-pagination/LOSS-AUDIT.md +++ b/packages/query-db-collection/tests/cursor-pagination/LOSS-AUDIT.md @@ -48,7 +48,7 @@ and the user's choices to ship one PR, retain caching, and reuse Query semantics ## Oracle-guide pass and recovered tests -Source: [Writing reliable oracle tests](../../../../docs/contributing/oracle-tests.md). +Source: [Oracle Testing Rubric](../../../../docs/contributing/oracle-rubric.md). This pass shares the implementer's context; it is weaker than the two isolated readings above. It compares promises and test evidence, not every possible state.