rivencraft/docs/MILESTONE_6_REGRESSION.md

# Milestone 6 instability regression and migration check (#73)

This is the release-slice acceptance record for instability, not a promise of
general old-save compatibility. The latter remains issue #60. Run the focused
archive with `./gradlew build runGameTestServer -ParchivedGameTestSuites=instability`;
it includes the default smoke suite.
For 0.5.8.10 on 2026-10-10, that dedicated GameTest server passed all 55 required tests
with no optional content/client integrations installed (the required Dynamic
Dimensions and Bad Packets dependencies were present). The full archive was not run;
it has a previously documented storage stall, so do not count it as passing.
The 0.5.8.11 run with live block profiling stalled in its initial batch and
was stopped; it is **not** a passing result. The live profiling scenario is
handed to the player in [the block-profile checklist](LIVE_BLOCK_INSTABILITY.md).

## Automated coverage

| Requirement | Existing default test or focused archive |
| --- | --- |
| Stable writing, defective writing, score explanations, repeated use of the same book | `AgePersistenceGameTests.instabilitySeparatesStableAndDefectiveWriting` |
| Frozen score, age-scoped writing cost, random baseline | `AgePersistenceGameTests.randomBaselineAndBrightBalanceAreFrozen`, `auditedSymbolCostsAreCountedAndAgeScoped` |
| Complete Age definition, score and provider-plan save/load | `AgePersistenceGameTests.authoredPlanRetainsResolvedMeaningAndAgeIdentity`; `AgeInstabilityRuntimeGameTests.selectionIsDeterministicAndFrozen` |
| Old pre-scoring Ages, score-only saves, removed symbols, unavailable handlers | `AgePersistenceGameTests.missingRegistryEntryDoesNotReinterpretAnOldAge`, `instabilitySeparatesStableAndDefectiveWriting`; `AgeInstabilityRuntimeGameTests.savedPlanSurvivesAgeUpdatesAndMissingHandlers` |
| Per-Age controls and changed config without score/plan reroll | `AgeInstabilityRuntimeGameTests.perAgeControlsPersistWithoutChangingScoresOrOtherAges`; `Milestone6RegressionGameTests.disablingEffectsCannotRerollFrozenPlan` |
| Hazard cooldown and attempt sequence across saved-state reload | `AgeInstabilityRuntimeGameTests.hazardCooldownAndAttemptSequenceSurviveReload` |
| Active-Age rotation, action/tick budget | `AgeInstabilityRuntimeGameTests.ageScopeRotationAndActionBudgetAreBounded` |
| Multiplayer loaded-chunk-only candidate selection, deduplication and cap | `Milestone6RegressionGameTests.multiplayerCandidatesStayLoadedDeduplicatedAndCapped` |
| Decay loaded-chunk target and spawn protection | `AgeDecayGameTests.targetMustRemainInChosenLoadedChunk`, `savedSpawnAndPlatformAreProtected` |
| Explosion policy gates and protected blocks | `Milestone6RegressionGameTests.disabledGriefAndProtectedBlocksStayUntouched` |
| No Overworld status or decay provider | `AgeStatusEffectGameTests.overworldCannotRunAnAgeStatusProvider`; `AgeDecayGameTests.overworldCannotRunDecayProvider` |

These tests exercise saved-data serialization and deterministic policies. They
do **not** simulate a complete process restart, an actual multiplayer server,
optional-mod installation, or real terrain and hazard visuals. The three new
checks live only in the `instability` archive to avoid duplicating default tests.

## Migration outcome and known gaps

- Pre-scoring Milestone 5 Ages load with a neutral score and no effects; they
  are not retroactively rescored under current writing rules.
- Score-only Ages receive a deterministic provider plan once from their saved
  score and Age seed. An already-saved score and plan retain their meaning when
  pages, handlers, or runtime config change. Unknown but syntactically valid
  provider IDs are preserved and skipped if their handler is unavailable.
- Missing symbol definitions do not reinterpret a frozen instability score.
  That check is narrower than arbitrary missing biome, block, or worldgen
  registry entries: loading a world with removed data packs is not guaranteed.
  Broad save compatibility and migration remain tracked in #60.
- In-process roundtrips cannot prove that Age dimensions reload correctly
  after a full stop/start. Check that in a real client/server world. Do not add
  another GameTest for it if it hits the documented storage stall; hand the
  exact scenario to the player instead.
- The dedicated GameTest run establishes classloading with no optional runtime
  flags. It does not establish classloading with every optional integration
  installed, nor the reverse of removing one from an existing save.

## Manual in-game matrix

Use a fresh test world, then keep one save for the restart and data-pack checks.
Record the seed, mod list, age name, and `/rivencraft age instability` output
before and after each change. Do not deliberately remove a required registry
entry from a valued world; copy the test save first.

1. Bind a low-instability book and a deliberately unstable book. Reuse each
   book and verify the Age name, dimension ID, score, selected providers and
   provider levels remain unchanged. Exit the Ages, stop Minecraft completely,
   restart and re-enter; compare the same diagnostic values.
2. With two survival players in one unstable Age and a third player in the
   Overworld, verify effects stay in the Age, follow the Age players, and do
   not appear in the Overworld. Move both Age players away, let old chunks
   unload, and confirm hazards do not keep remote chunks loaded or operate
   there. Confirm controls on one Age do not alter a second Age.
3. Disable global instability, then world mutation, then one provider. Verify
   the suppressed effect stops and the frozen score/plan do not change after
   re-enabling or restarting. With block destruction disabled, trigger an
   explosion in an expendable Age; check that arrival platforms, portals,
   block entities and protected blocks survive. Check lightning, explosion,
   decay, status-effect, burning, meteor and erosion visuals where selected.
4. With Biomes O' Plenty or another TerraBlender biome mod, confirm recognized
   biome pages still author an Age and the instability diagnostics remain
   stable after restart. Repeat with Serene Seasons installed, then absent in
   a disposable copy; confirm its Age season behavior and that Rivencraft
   itself still loads. JEI should display the relevant pages and recipes when
   installed, while the mod works without it.
5. Check the book preview separately with its fallback animation, Ponder/Create,
   and Immersive Portals when available. Opening a book should not change
   player location, instability diagnostics, or ambient audio in the actual
   Age. Do not install both season mods together for this matrix.
6. On a copied save, remove or alter a **nonessential** data pack providing
   a writing symbol or optional handler, then reload. Existing saved scores
   and provider plans must not reroll. If a referenced worldgen registry entry
   prevents load, record it against issue #60 rather than treating #73's
   frozen-instability guarantee as general missing-registry support.

The matrix is guidance for a player-run pass; none of these six scenarios is
claimed as completed by the automated result above.