gammonview 2.0.2__tar.gz → 3.0.0__tar.gz

{gammonview-2.0.2 → gammonview-3.0.0}/CHANGELOG.md

@@ -13,6 +13,145 @@ when the repository was opened; they are kept because they record why things
 are the way they are — particularly the breaking changes and the measurements
 behind several design decisions. Dates are the tag dates.
 
+## 3.0.0 — 2026-10-22
+
+**Presets are versioned, and a built-in cannot be changed** *(breaking)*
+
+An analysis now records which version of a preset produced it: `world_class@2`
+for a built-in, `custom/<name>@<digest>` for a preset from `presets.yaml`. Two
+analyses with the same label used the same method, so a player comparing
+matches, or a title-granting body requiring one method, can check that.
+Locking the built-ins is what makes that hold. A `presets.yaml` entry that
+reuses a built-in's name or alias is now skipped with a warning, where it used
+to override the built-in. A custom preset's label comes from a digest of its
+whole definition, screening constants included, so renaming it changes nothing
+and a changed threshold changes the label. An environment override
+(`GVAN_STAGED=0`, `GVAN_NO_SCREEN`, `GVAN_ROLLOUT_SELECT=0`) runs as `world_class@2+<digest>` rather
+than under the real label. `--preset world_class@2` runs exactly that revision,
+and refuses if anything else would run. The label travels in the block's
+`x-gammonview-analysis` annotation (`preset=`), in Python and JS; older files
+carry none.
+
+**Checker plays are screened in stages, as XG screens them** *(change)*
+
+`fast`, `deep` and `world_class` move to revision 2:
+
+1. Every move is screened at 1-ply.
+2. The top 14 are rescored at 2-ply, or every move within 0.2 of the 1-ply
+   leader when that is more (at most 40). A fixed count ignored a crowded
+   field: on 10,715 decisions the 3-ply best ranked 14th or worse at 1-ply on
+   0.19% of them, and the window recovers what that cost.
+3. Moves within 0.16 of the 2-ply leader, at most 12, are evaluated at full
+   depth, along with the played move.
+
+A middle tier now starts from the screen's numbers, and deepens only the moves
+within `close_threshold` of the best, at most 8. That is XG's search interval,
+4 moves within 0.080. The top-two gap is measured between moves at the same
+depth, so a lone deep move is never "close", and it stays at the screen's
+depth as XG's does. 4-ply checker work falls to about 36% of its cost.
+`world_class` ran 1.31x faster end to end on 12 matches on a 24-core machine,
+and 1.45x on an 8-core one. PR is identical to two decimals on 24 players, and
+8 of 2,323 best moves differ, every one of them a tie. `very_quick` never
+reaches the staged screen and stays at revision 1.
+
+**A checker rollout rolls out the moves the tier below chose** *(change)*
+
+When a checker play goes to the rollout tier, the moves rolled out are now
+the best move from the tier that sent it (the 3-ply screen, or 4-ply after a
+middle tier), its runner-up when within 0.02 of that best at the same depth,
+and the played move. Every other move keeps that tier's numbers. bgsage
+used to choose the set again from a fresh 2-ply filter, plus a loop that rolled
+out any unrolled move ranked above the rolled ones: 3.85 moves a decision across
+43,691 decisions in our corpus outputs, where XG World Class rolls out 2.06
+(93.9% of its Roller+ decisions roll out exactly the best and the played move).
+Ours now average 2.26. On 11 matches `world_class` ran 28% faster (448s to
+320s); 4 of 1,937 best moves changed, together 0.029 equity of error, and PR
+moved by 0.006 on average (at most 0.11). Each rolled-out row is bgsage's own
+rollout of that board, to the last digit. `GVAN_ROLLOUT_SELECT=0` restores
+bgsage's choice for A/B work. Part of `world_class@2`.
+
+**`world_class_fast` is retired** *(breaking)*
+
+`--preset world_class_fast` (`wcf`) now fails with a message pointing to
+`world_class` or `deep`. Faster rollouts and the staged screen made
+`world_class` cheap enough that `world_class_fast` stopped earning its place.
+On 11 matches it took 74% of `world_class`'s time (234s against 318s) for PR
+0.13 away from it on average (at most 0.38), while `deep` takes 9% (29s). Two
+world-class methods would also split the comparison that preset labels exist
+for. Files analyzed with it are unaffected, and it is not aliased to
+`world_class`, since that would mislabel the analysis.
+
+**`world_class` rolls out every wrong cube** *(change)*
+
+A cube is still screened at 3-ply, but deepened to 4-ply within 0.12 of its
+double or take point (was 0.08), and any wrong cube action is now rolled out
+(was: only one wrong by more than 0.02), as XG World Class's "if different"
+does. On 11 matches (1,109 cubes) it costs 2% of wall time and 6 more cube
+rollouts, and it reaches the same optimal action on every cube as screening
+them all at 4-ply would, which costs 11%. Against the old shape it flips 3
+optimal actions; PR moves by 0.02 on average (at most 0.23). A preset's
+`first_pass` also takes a `{checker, cube}` mapping now, for a cube screen at
+its own depth. Part of `world_class@2`.
+
+**A custom preset can be passed as data** *(new)*
+
+`custom_preset(name, spec)` builds a custom preset from a definition held in
+memory, in the shape of one `presets.yaml` entry, and `analyze_match` (with
+`analyze_file`, `analyze_ogxm` and `resolve_preset`) accepts the `Preset` it
+returns wherever it took a name. It obeys the file's rules and gets the file's
+label, `custom/<name>@<digest>`, so a program that keeps presets somewhere of its
+own no longer has to write a YAML file and re-import the module to run one.
+Both are exported from `gvanalysis`, with `Preset` and `PresetConfigError`.
+
+**A preset can size cube errors at a level of their own** *(new)*
+
+`second_pass` takes a `{checker, cube}` mapping, as `first_pass` does, so a
+preset can roll out a wrong cube and settle a wrong checker play at 4-ply, or
+the reverse. A rollout of a cube is one position and a rollout of a checker
+play is every candidate that survives, so the level worth paying for is not the
+same one. The checker level is required: every kind still has an on-error
+tier. A mapping naming one level for both is the bare level, with the same
+digest, and no built-in changes. The analysis summary gains
+`second_pass_cube_level`, set only when the two differ, and a cube decision
+records the level it was sized at.
+
+**Resign errors** *(new, opt-in)*
+
+`--resign-errors` (`resign_errors=True` in the API) judges every accepted
+resignation, as BMAB's configuration of XG does. It is off by default and no
+preset turns it on; an analysis run with it is labelled `<preset>+resign`
+(`world_class@2+resign`), and a pinned `--preset world_class@2` still accepts
+it. A resignation counts as a decision for each player: the resigner is charged
+if they conceded more than the position was worth, and the acceptor if they
+took less. A resignation conceding the position's exact value counts for
+neither. The position is the one the record shows was resigned: before the roll
+after a play or a dance, and after it when the record shows a roll that had a
+legal play and was left unplayed, since the resigner had seen it. In the XG
+corpus 18 of 149 judged resignations come after a seen roll; judged before the
+roll instead, two of them would be charged 0.33 and 0.60 that the roll actually
+seen makes 0. A resignation on a pending double is not judged. The analysis goes
+in v2's resign record (`resign_error`, `take_resign_error`, with its level), and
+`compute_aggregates` / `computeAggregates` now count it in PR.
+
+**Auto `--jobs` is `cpu // 3` workers, at least 2** *(behaviour change on
+`--jobs 0`)*
+
+It was `ceil(cpu / 7)`. A staged decision keeps fewer cores busy, so 4 workers
+left a 24-core machine short: 8 workers ran 162.6s against 171.4s. On 8 and 4
+cores the count is unchanged, at 2. Output is identical at any setting.
+
+**An XG match's header names the deepest level it was read at** *(fix)*
+
+`convert_xg` / `convertXg` set the block's `eval_level` to the plain n-ply
+depth, which ignored XG Roller levels (and full rollouts) altogether. Since XG
+stamps no analysis time -- `timestamp` is the match's date -- two runs of one
+match that differed only in sending the doubtful plays to Roller+ or to
+Roller++ converted to identical headers, and GammonView's library took the
+second for the first. The header now names the deepest level any decision in
+the document reports (`truncated2`, `truncated3`, `rollout`), with `ply`
+unchanged. Every decision's own level is untouched; across the 13-file XG
+corpus only headers moved.
+
 ## 2.0.2 — 2026-10-12
 
 **A set-up start is written once** *(fix)*

{gammonview-2.0.2 → gammonview-3.0.0}/CLAUDE.md

@@ -218,58 +218,103 @@ in step when a flag changes; the rationale belongs only here.
   two-pass scheme: a cheap first pass screens every decision, a stronger second
   pass runs only on an error (the played checker move or cube action disagrees
   with the first pass). Single-pass presets judge everything at the first pass.
-  The five built-in presets live in `gvanalysis/presets.py` (always available). Optional
-  `presets.yaml` overrides are layered on top from two locations, project-local
-  winning over global: `~/.config/bgsage/presets.yaml` then `./presets.yaml`.
-  Create either with `--init-presets` (add `--global` for the config-dir one).
-  Overrides merge into a built-in by key (field-by-field) or add new presets;
-  `default:` sets the default. Restore defaults by deleting the file(s); a
-  malformed file is skipped with a warning (the other layer still loads).
+  The four built-in presets live in `gvanalysis/presets.py` (always available)
+  and **cannot be overridden**. Optional `presets.yaml` files add custom presets
+  from two locations, project-local winning over global:
+  `~/.config/bgsage/presets.yaml` then `./presets.yaml`. Create either with
+  `--init-presets` (add `--global` for the config-dir one). An entry reusing a
+  built-in's name or alias is skipped with a warning; `default:` sets the
+  default. Restore defaults by deleting the file(s); a malformed file is skipped
+  with a warning (the other layer still loads).
+  `custom_preset(name, spec)` is the in-memory twin of one file entry (same
+  rules via `_check_custom`, same label), and every entry point that takes a
+  preset name also takes the `Preset` it returns.
+
+  **A preset label names one method.** Output records `Preset.label`:
+  `world_class@2` for a built-in, `custom/<name>@<digest>` for a user preset
+  (digest of its whole definition). The point is comparability -- a user, or a
+  title-granting body, must be able to tell and require that analyses used the
+  same version; it is not an anti-tampering measure. `Preset.definition()`
+  includes the screening constants from `checker_eval.screening()`, so any
+  change that can move results changes the digest, and `_REVISIONS` pins the
+  digest of every shipped revision: **`test_presets` fails until a changed
+  definition appends a new revision -- append a row, never edit one.** An
+  environment override (`GVAN_STAGED`, `GVAN_NO_SCREEN`) shows as
+  `world_class@2+<digest>` rather than running under the real label, and
+  `--preset world_class@2` is refused unless that exact revision is what runs.
+  Old revisions are listed, not runnable. The label travels in the block's
+  `x-gammonview-analysis` annotation (`preset=`); before that it was not
+  written to `.gvab` at all, so older files carry no preset.
 
   | Preset (aliases) | 1st pass | 2nd pass | XG equivalent |
   |---|---|---|---|
   | `very_quick` (`vq`) | `2ply` | — | Very quick |
   | `fast` (`f`) | `2ply` | `3ply` | Fast |
   | `deep` (`d`) | `3ply` | — | Deep |
-  | `world_class` (`wc`) | `3ply` → `4ply` on close | `truncated2` | World Class (XG Roller+) |
-  | `world_class_fast` (`wcf`) | `3ply` (cube: → rollout on close too) | `truncated2` | World Class (3-tier) |
-
-  `world_class_fast` is a 3-tier scheme (`mid_pass` + `close_threshold` on the
-  preset): `3ply` baseline, `truncated2` rollout on error, and a middle tier on
-  borderline decisions — but only for cubes. A middle tier is added on top of
-  the screen — it fires on decisions the screen would otherwise have settled —
-  so what decides whether it pays is its cost against the *screen below*, not
-  against the tier above. Measured per decision off a `3ply` screen, 4-ply is
-  19x the screen on a move list (25ms → 467ms) and only 4x on one pre-roll cube
-  (24ms → 100ms). Dropping the checker middle tier made the preset ~36%
-  faster while it ran twice as many rollouts, so borderline checker plays now go
-  straight from the 3-ply screen to `truncated2` when they are wrong, and are
-  left at the screen when they are right. The argument now rests on the
-  borderline *rate* alone: at a 0.04 window a cube is borderline ~5% of the time
-  and a checker play 53.8%, so the same rule costs ~0.4s per match on one and
-  tens of seconds on the other. The old second argument — that restoring the
-  tier "diverts 65 of the 83 checker rollouts into 4-ply, the weaker estimator"
-  — described the **escalation defect**, not the tier: a borderline decision
-  used to be capped at the middle tier however large its error proved. It
-  escalates now, so a middle tier no longer steals rollouts (it would still
-  cost, and more, since those decisions pay both tiers). Note also that the cost
-  order has flipped since that measurement: on 760 paired checker decisions
-  4-ply beats `truncated2` on 710, median 2.23x, because `checker_eval.py`
-  screens candidates before the full-width pass. `mid_pass` takes a
-  `{checker, cube}` mapping as well as a bare level (which still sets both); an
-  omitted kind is plain 2-tier.
-
-  The cube middle tier names `truncated2` — the same level as `second_pass`, so
-  the cube rule reads "borderline **or** wrong → roll it out". It was `4ply`
-  until 632 borderline cubes from XG-analyzed matches were scored against an
-  independent `truncated3` arbiter: 4-ply disagreed with the arbiter's verdict
-  on 14% of them (mean gap error 0.0127) against 12%/0.0091 for a single
-  `truncated2` run, and averaging ten `truncated2` seeds improved that to only
-  0.0090 — so a 360-trial rollout is limited by its horizon, not its variance,
-  and 4-ply's zero variance buys nothing back. Naming an existing level in
-  `mid_pass` costs no extra analyzer (levels are built once and shared), and
-  routing the ~6% of cubes that are borderline to the rollout adds roughly
-  0.4s per match.
+  | `world_class` (`wc`) | `3ply` → `4ply` on close (cube: within 0.12) | `truncated2` | World Class (XG Roller+) |
+
+  `world_class`'s cubes: a 3-ply screen, 4-ply within 0.12 of the double or
+  take point (`close_threshold: {checker: 0.08, cube: 0.12}`), and cube
+  `error_threshold` 0 -- any wrong action rolled out ("if different"). XG's own
+  routing, read off 39,284 cube records in 524 XG files, is shallower: no
+  cube is 3-ply; it screens at 2-ply and goes to 4-ply only within ~0.25 of the
+  double point (no 2-ply record above a gap of -0.24), every actual double,
+  take and pass at 4-ply or Roller+. We keep the deeper screen. Measured on
+  11 matches, 1,109 cubes, against the old shape (0.08 window, rollout above
+  0.02) and against 4-ply on every cube:
+
+  | cube shape | wall | 3-ply / 4-ply / rollout | action flips vs all-4-ply |
+  |---|---|---|---|
+  | old (@1) | 442s | 1013 / 49 / 47 | 3 |
+  | all 4-ply | 491s (+11%) | 0 / 1057 / 52 | -- |
+  | **@2** | 451s (+2%) | 981 / 75 / 53 | **0** |
+
+  So @2 reaches every verdict the all-4-ply shape does at a fifth of its cost.
+  PR still differs from it by 0.097 mean (max 0.56), and not through any cube
+  error -- lost equity is identical on all 1,109 -- but through the decision
+  count: 3-ply and 4-ply disagree on whether 1-2 cubes per player are trivial.
+  The checker interval stays at XG's Normal: Gigantic (16 within 0.32)
+  costs 3x the non-rollout checker CPU for 0.089 total best-move regret over
+  11,037 decisions, one decision holding 0.071 of it, rollouts unchanged.
+
+  **Resign errors are an analysis option, never a preset's** (`--resign-errors`,
+  `resign_errors=True`; `Preset.with_resign_errors`). They move PR, so the label
+  says so (`world_class@2+resign`), but they stay out of the definition and
+  digest: a pin names the preset, and `presets.yaml` refuses the key. The
+  position judged is the one the record shows was resigned. After a play or a
+  dance it is pre-roll for the next player. After a roll left unplayed that had
+  a legal play, it is that roll's best play, because the resigner saw the dice. In the XG
+  corpus 18 of 149 judged resignations follow a seen roll, and pre-roll
+  judging would have charged two of them 0.33 and 0.60 where the seen roll
+  makes both 0. A roll seen but not recorded cannot be detected; XG does record
+  one.
+
+  **`world_class_fast` was retired 2026-10-21**, before any release carried
+  preset labels. It was `world_class` without the checker middle tier: a 3-ply
+  screen, `truncated2` on error, and cubes that were merely borderline also
+  rolled out. Once seeded rollouts and the staged screen made `world_class`
+  cheap, it stopped earning a place. Paired on 11 matches it took 234s against
+  `world_class`'s 318s, for PR 0.13 away from it (mean; max 0.38). Cube verdicts
+  matched on all but 5 of 1,164, and 98 of 1,937 best moves differed, nearly
+  all near-ties that `world_class` deepens. `deep` took 29s. A second
+  world-class method also splits the pool that preset labels exist to keep
+  comparable, and analysis runs in the helper, not on a server, so there is no
+  hosting bill to save. Like `balanced`, it stays in `_RETIRED` and is not
+  aliased.
+
+  What its design established still holds for any 3-tier preset. A middle tier
+  pays against the *screen below* it, not the tier above, because it fires on
+  decisions the screen would otherwise have settled. Measured off a `3ply`
+  screen, 4-ply is 19x the screen on a move list (25ms → 467ms) and only 4x on
+  one pre-roll cube (24ms → 100ms). At a 0.04 window a cube is borderline ~5%
+  of the time and a checker play 53.8%. `mid_pass` takes a `{checker, cube}`
+  mapping as well as a bare level for that reason; no built-in uses it now. On
+  632 borderline cubes from XG-analyzed matches scored against an independent
+  `truncated3` arbiter, 4-ply disagreed with the arbiter's verdict on 14% of
+  them (mean gap error 0.0127) against 12%/0.0091 for a single `truncated2`
+  run. Averaging ten `truncated2` seeds improved that only to 0.0090, so a
+  360-trial rollout is limited by its horizon, not its variance, and 4-ply's
+  zero variance buys nothing back.
 
   **Two thresholds, not one — they answer different questions.**
   `close_threshold` gates the *middle* tier: how near a tie before the screen's
@@ -297,8 +342,8 @@ in step when a flag changes; the rationale belongs only here.
   threshold, worst 0.56) and a borderline cube was re-checked never (0.4% of
   cubes, median 0.07, max 0.22). The escalation is skipped when `mid_pass` names
   `second_pass`'s own level — analyzers are memoized by level, so identity is
-  exact and re-running would buy the same answer twice. That makes it a no-op
-  for `world_class_fast`'s cube tier by construction.
+  exact and re-running would buy the same answer twice. That made it a no-op
+  for the retired `world_class_fast`'s cube tier by construction.
 
   **Every sizing tier is `truncated2`, never `4ply`, and that holds for both
   decision kinds.** The cube half is the arbiter test above (12%/0.0091 against
@@ -324,8 +369,8 @@ in step when a flag changes; the rationale belongs only here.
   name in `_RETIRED` and fails with an explanation rather than a bare "unknown
   preset"; it is deliberately **not** aliased to `world_class_fast`, since the
   preset name is written into the output document and a silent redirect would
-  mislabel the analysis. The gap below `world_class_fast` is now `deep`, an
-  order of magnitude cheaper. Don't reinvent it without a sizing tier cheaper
+  mislabel the analysis. With `world_class_fast` retired too, the gap below
+  `world_class` is `deep`, an order of magnitude cheaper. Don't reinvent it without a sizing tier cheaper
   than `truncated2`, because that is the whole of what went wrong.
 
 - **`gvan-batch`** (`gvanalysis/batch.py`) — Batch-analyze many match files
@@ -455,7 +500,10 @@ legal — our `.mat` path put bar entries last) and the duplicate played move.
 
 `tests/test_ogxm2_reference.py` is the older ratchet: the reference `v1_to_v2`
 over each golden's content written as v1, against a **pinned** table. Never edit
-a row to make a run pass. The goldens themselves are v2 now.
+a row to make a run pass. The goldens themselves are v2 now. Since the staged screen every row
+reads `alternatives`: a top-ten list mixes 3-ply and 2-ply plays, and the
+reference's frozen v1 reader gives every alternative the decision's level.
+That is v1's limit; the v2 files we write pass (`test_ogxm2_writer`).
 
 The two v1 parity suites, `test_gvab_writer` and `test_ogxm_conformance`,
 compare against libogxm's *v1* writer and projection, and skip — saying so —
@@ -523,14 +571,59 @@ label. The best move agrees with bgsage's full-width answer on every decision
 measured — 4 differences in 1567, all exact ties — while evaluating 1.8x fewer
 moves.
 
-Three constants tune it, all documented with their measurements in the module:
-`ELEVATE_THRESHOLD` / `ELEVATE_MAX_MOVES` (the accuracy filter) and
-`ELEVATE_MIN_MOVES` (a display-quality floor, so the top ten a viewer reads is
-always N-ply). Rollout tiers, cubeless and 1-ply analyzers, and any bgsage whose
+**The screen is staged, as XG's is** (since the presets' `@2` revisions). A
+decision goes 1-ply on every move -> 2-ply on the top `STAGE_SCREEN_MOVES` (14:
+the display floor, paid at the cheapest real depth), widened to every move
+within `STAGE_SCREEN_WINDOW` (0.2) of the 1-ply leader on a crowded field, at
+most `STAGE_SCREEN_CAP` (40) -> N-ply on the 2-ply moves
+within `STAGE_THRESHOLD` (0.16) of the leader, at most `STAGE_MAX_MOVES` (12),
+plus the played move. A middle tier is handed the screen's result (`seed=`) and
+deepens only its moves within `close_threshold` of the best, at most
+`DEEPEN_MAX_MOVES` (8) -- XG's search interval, "4 moves within 0.080 at
+3-ply" -- keeping the screen's numbers for the rest. `game_eval` measures the
+top-two gap only between moves at the same depth, so a lone deep move is never
+"close" (XG's rule: nothing in the window, it stays at 3-ply). Why: 4-ply was
+90% of world_class's non-rollout checker CPU, re-screened from 1-ply on 14+
+moves; staged it is 36% of that cost, PR identical to two decimals on 24
+players, 8 of 2,323 best moves different and every one a tie, and
+world_class 1.31x faster end to end (727s -> 554s, 12 matches), 1.45x on the
+8-core M3. The XG facts behind it (window AND cap, no display floor -- a
+quarter of XG World Class's listed moves are 1-ply) were read off the corpus.
+A fixed 14 ignores how crowded the field is: on 10,715 decisions the 3-ply best
+ranked 14th or worse at 1-ply on 0.19% of them, and the window recovers all that
+loss (0.175 -> 0.130 total equity, the floor of sending every move to 2-ply) for
+1.4 more 2-ply evaluations a decision. It went into `@2` before `@2` shipped.
+`GVAN_STAGED=0` restores the flat screen for A/B work, and the preset label
+then says `@2+<digest>`.
+
+The flat screen's constants, still used at 2-ply and with `GVAN_STAGED=0`, are
+documented with their measurements in the module: `ELEVATE_THRESHOLD` /
+`ELEVATE_MAX_MOVES` (the accuracy filter) and `ELEVATE_MIN_MOVES` (a
+display-quality floor). **Every one of these constants is part of a preset's
+definition** (`checker_eval.screening()` feeds `Preset.digest()`), so changing
+one fails `test_presets` until the affected presets get a new revision. An
+unseeded rollout tier, cubeless and 1-ply analyzers, and any bgsage whose
 internals have moved all fall back to `analyzer.checker_play` unchanged;
 `GVAN_NO_SCREEN=1` forces that fallback everywhere, which is how the A/B
 measurements above were taken.
 
+**A rollout tier rolls out what the tier below chose, as XG's does.**
+`game_eval` hands the second pass the screen's (or middle tier's) result as
+`seed=`, and a rollout analyzer then rolls out only that result's best, its
+runner-up within `ROLLOUT_RUNNER_UP_WINDOW` (0.02) at the same depth, and the
+played move, keeping the seed's numbers for the rest. Left to itself bgsage
+throws the seed away and picks again with a 2-ply filter (within 0.08, at most
+5) plus a promotion loop: 3.85 rollouts a decision over 43,691 in our corpus
+outputs, against XG World Class's 2.06 (93.9% exactly best + played; 6% add one,
+nearly always the runner-up). Ours average 2.26 (26% take the runner-up, so the
+window is wider than XG's; it is cheap insurance). On 11 matches `world_class`
+went 448s -> 320s (-28%); 4 of 1,937 best moves changed, 0.029 equity of error
+in total, PR within 0.006 mean (0.11 max). Each rolled row is bgsage's own
+`cubeful_evaluate_board` call, so it matches bgsage exactly
+(`test_screened_checker.check_seeded_rollout`). The second pass gets a seed
+but no `seed_window`, so a multi-ply second pass (`fast`'s 3-ply) does not
+deepen and is unchanged. `GVAN_ROLLOUT_SELECT=0` restores bgsage's choice.
+
 **Because it duplicates a bgsage call site, it inherits that call's signature.**
 bgsage 2.0 added `root_board=` to `cubeful_probs_and_equity_nply` — Stage 11's
 snake NN is chosen once from the root position and held for the whole tree,

{gammonview-2.0.2 → gammonview-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gammonview
-Version: 2.0.2
+Version: 3.0.0
 Summary: Backgammon match analysis — the pure-Python OGXM/GVA codec (`gvformat`) plus bgsage-powered match and position analysis (`gvanalysis`).
 Project-URL: Homepage, https://github.com/ngvlamis/gammonview-analysis
 Project-URL: Repository, https://github.com/ngvlamis/gammonview-analysis
@@ -202,7 +202,7 @@ own; analysis does not need them.) `--link` encodes the whole match into a
 ### Analysis presets
 
 `--preset` selects an eXtreme Gammon–style scheme: a cheap first pass screens
-every decision, and a stronger pass runs only where it is needed. The five
+every decision, and a stronger pass runs only where it is needed. The four
 built-ins:
 
 | Preset (aliases) | 1st pass | Middle tier | 2nd pass | XG equivalent |
@@ -210,60 +210,46 @@ built-ins:
 | `very_quick` (`vq`) | `2ply` | — | — | Very quick |
 | `fast` (`f`) | `2ply` | — | `3ply` | Fast |
 | `deep` (`d`) | `3ply` | — | — | Deep |
-| `world_class` (`wc`) | `3ply` | `4ply` (both kinds) | `truncated2` | World Class (XG Roller+) |
-| `world_class_fast` (`wcf`) | `3ply` | `truncated2` (**cube only**) | `truncated2` | World Class (3-tier) |
+| `world_class` (`wc`) | `3ply` | `4ply` | `truncated2` | World Class (XG Roller+) |
 
 The second pass runs on an **error**; the middle tier runs on a **borderline**
 decision the screen would otherwise have settled. `fast` is the default.
 
 #### Which one to use
 
-493 matches were analyzed by XG at World Class and by each of the strong
-presets, then compared decision by decision:
+493 matches were analyzed by XG at World Class and by `world_class`, then
+compared decision by decision:
 
-| | mean gap to XG's match PR | same checker play as XG | PR within 1 of XG | cost, ms/ply (24c → 4c) |
-|---|---|---|---|---|
-| `world_class` | 0.423 | 90.3% | 91.7% | 291 → 2048 |
-| `world_class_fast` | 0.431 | 90.0% | 91.3% | 166 → 1016 |
+| | mean gap to XG's match PR | PR within 1 of XG | same cube action as XG |
+|---|---|---|---|
+| `world_class@2` | 0.420 | 92.0% | 96.2% |
 
-Re-measured 2026-09-20 over the same 493 matches after the retune. The retune
-moved both presets about 0.01 PR closer to XG, which is **not** a significant
-improvement — the paired confidence intervals span zero — but does establish
-that it cost nothing. The checker-play column is carried over from the original
-study; a like-for-like check says the retune moves it by at most 0.6 points, but
-its exact figure could not be reproduced (see
-[the write-up](experiments/2026-09-20-corpus-rerun.md)).
+Measured 2026-10-21. Against the September `world_class` on the same matches
+the gap moved by −0.003, inside the noise (95% CI [−0.010, +0.004]), while the
+run took 1.83× less time: 3 h 31 m against 6 h 25 m on a 24-core M2 Ultra, or
+about 150 ms per ply. See [the write-up](experiments/2026-10-21-wc2-corpus.md).
 
 **Mean gap** is the average distance between the two *ratings* of the same
 player-match, in either direction: rate a match with `world_class` and XG rates
-it 0.434 PR away, typically. It is not what following the preset costs you —
-priced by XG's own equities, a player who made `world_class`'s recommended
-checker play every time would post a PR of 0.333 and `world_class_fast`
-0.353. Both are inside what XG itself calls world-class play. (Those two
-figures predate the retune and were not re-measured; everything else in this
-section was.)
-
-Cost is milliseconds per ply over six matches, on a 24-core M2 Ultra and a
-4-core i5-7600 — absolutes rather than a multiple of `fast`, because that
-multiple is not constant across machines. Individual matches spread about 2×
-around these means. See [the timings](docs/CLI.md#what-they-cost).
-
-- **`world_class_fast` is the recommended analysis.** It lands 0.008 PR behind
-  the deepest preset for a little under half the time — a difference the
-  493-match corpus cannot resolve from zero (95% CI [−0.020, +0.004]). The two sit three times
-  closer to each other (0.136) than either does to XG, because what separates
-  them from XG is the *engine*, not the search depth — 95% of
-  `world_class_fast`'s squared PR error against XG is that engine floor, which
-  no preset can spend its way past.
-- **`world_class` is for reproducing XG specifically**, not for being more
-  accurate. Its only real edge is on borderline cubes, and it gets there by
-  rolling them out *less* often than `world_class_fast` does — which is
-  XG-like, not demonstrably better. It costs roughly twice as much for that.
-- **If you want cheap, drop to `deep`**, which costs an order of magnitude
-  less than either. There is nothing between them: a `balanced` preset used to
-  sit in that gap, but after the September 2026 retune it cost about what
-  `world_class_fast` costs while agreeing with XG less often, so it was
-  retired.
+it about 0.42 PR away, typically. It is not what following the preset costs you.
+Priced by XG's own equities, a player who made `world_class`'s recommended
+checker play every time would post a PR of 0.333, inside what XG itself calls
+world-class play. (That figure predates the September retune and was not
+re-measured.)
+
+- **`world_class` is the analysis to trust.** It routes as XG World Class
+  does: checker plays from a 3-ply screen to 4-ply on near-ties, cubes from a
+  3-ply screen to 4-ply within 0.12 of the double or take point, any wrong cube
+  action rolled out, and checker errors over 0.02 rolled out. Most of what
+  separates it from XG is the *engine*, not the search depth, and no preset can
+  spend its way past that. Resign errors, which BMAB's configuration counts,
+  are a separate switch (`--resign-errors`) that any preset can run with.
+- **If you want cheap, drop to `deep`**, which costs about a tenth as much.
+  Nothing sits between them any more. `balanced` was retired in September 2026
+  for costing what the preset above it cost. `world_class_fast` was retired in
+  October 2026 once faster rollouts made `world_class` nearly as cheap: on 11
+  matches it took 74% of `world_class`'s time for a PR 0.13 away from it. Both
+  names now fail with a message saying so.
 
 Every number above measures *similarity to XG*, which is not the same as being
 right — where the two engines differ there is no arbiter here to say which is
@@ -272,9 +258,10 @@ experiment: how the presets split on checker play versus the cube, why rolling
 out *costs* agreement with XG, and the evidence that the residual disagreement
 is systematic rather than noise.
 
-Presets live in `gvanalysis/presets.py` and are overridable via `presets.yaml`.
+Presets live in `gvanalysis/presets.py`; every analysis records the preset's
+version (`world_class@2`), and custom presets can be added via `presets.yaml`.
 See **[`docs/CLI.md`](docs/CLI.md)** for the full reference — every flag, how the
-tiers fire, parallelism, and preset overrides.
+tiers fire, parallelism, preset versions and custom presets.
 
 ## Documentation