Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/oracle-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/oracle-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/contributing/instruments/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/contributing/instruments/mutant-gap-hunt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/contributing/oracle-coverage.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/contributing/oracle-test-notes.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ function withoutPromotion<T>(): PipedOperator<T, T> {
* 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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading