test(db): reach every declared source-health state in every run #2290
Merged
KyleAMathews(GitHub profile, opens in a new tab)merged 14 commits into
main fromrefs/pull/2290/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Showing 10 changed files with 199 additions and 0 deletions (loading 8).
x
139 additions and 0 deletions+139-0docs/contributing/oracle-reviews/pr-2290-declared-reach.mdAddedView file
@@ -0,0 +1,139 @@
+# Declared reach machinery (PR #2290)
+
+This record applies to the executable oracle at commit `590588a65`. It is
+append-only: a later change adds an entry with its own commit and does not
+edit an earlier one. It records the evidence behind the
+`oracle.declared-reach` owner in the coverage map's "Oracle tooling" section.
+
+## Entry 1: commit `590588a65`
+
+### Scope and laws
+
+The oracle owns these laws of `createOracleReach`, `runOracleCampaign`,
+`oracleRandomParameters`, and `oraclePropertyOptions`. Authority is ORC-015,
+ORC-007, issue #2287, and maintainer decisions in the PR #2290 session.
+
+| Law | Authority | Generated witness |
+| --- | --- | --- |
+| A history counts once per declared state it enters | ORC-015 | repeats within a history |
+| A reach call for an undeclared state, or before the first history, throws and counts nothing | maintainer decision | undeclared index, early reaches |
+| Invalid options throw at creation | maintainer decision | minimums 0, -1, and 1.5. Fixed counts -1 and 0.5. A state declared twice |
+| The check fails below the minimum | ORC-015 | minimums 1 to 3 |
+| A fixed history is one begun with `fixed: true`. The check fails for a state that no fixed history entered. An extra fixed history counts as fixed. Too few fixed histories report only the stop | #2287, maintainer decision | fixed marks per history, an unfixed history first, extra and missing fixed histories |
+| A seed-only run checks reach, any path replay in the process skips it, an explicit `replaying` overrides the environment | maintainer decisions | four run kinds, optional override |
+| Examples come on top of the base runs, a replay keeps its seed, a path replay of the property keeps its path and runs once | #2287, ORC-007 | run kinds, base runs 1 to 200, up to five examples, the process multiplier |
+| `runOracleCampaign` runs fixed-seed and random campaigns, or one replay campaign, passes each its parameters, reports each passing campaign, and rejects an invalid environment | ORC-007, ORC-015 | run kinds, a fixed seed, three invalid environments |
+
+The law discovery behind this table, with the receiving-path inventory and