rivencraft/docs/MILESTONE_5_ACCEPTANCE.md

Milestone 5 acceptance: Age grammar

This is the completion record for Gitea issue #42 and release 0.5.0.0. Issues #28–#41, #45–#59, #61, and #62 are closed. #39 was closed with an explicit Ecliptic Seasons limitation, not with a working Ecliptic adapter. #42 is the final gate. Issues #43, #44, and #60 are separate open follow-ups, not hidden Milestone 5 completion claims.

Authoring and generation contract

• Schema-v2 symbol JSON lives at data/<namespace>/rivencraft/symbols/<path>.json. Its file path is the stable page ID; name, description, and category are display metadata, while typed semantics.role and semantics.value control generation on the server. See schema and role table. Schema v1 remains display-only. Registry-derived biome, solid-block, and source-fluid pages are generated from valid registered entries rather than requiring one PNG or JSON definition per material.
• Ordered writing is parsed as Link Panel, terrain, biomes/controller, weather, season, lighting, sky, celestial modifiers/celestial, then material/feature pairs. Missing branches are seeded completion warnings. Unresolved symbols, unsupported combinations, conflicting single-choice pages, incorrect order, and an invalid Link Panel produce Binder diagnostics before items are consumed. Repeated feature and material pages retain their occurrence order. See grammar and diagnostics.
• Legacy's grammar ranks informed the random-choice weights; Rivencraft does not claim to run Legacy's complete 1.12.2 grammar or reproduce its terrain byte-for-byte. The source audit, weight table, and runtime profiles record exact mappings and adaptations. Authored supported symbols override seeded choices. A page-free or Link-Panel-only Descriptive Book creates a random Age. The resolved plan, seed, profile, biome IDs, traits, features, and writing order are saved with its Age identity before chunks generate. Reopening a book or restarting must not reroll it.
• Feature pages cover decorations, terrain additions, dense ores, crystals, fissures, and supported structures including Trial Chambers and newer vanilla structures. Material pages may explicitly choose a compatible block/fluid or receive a seeded compatible feature. Terrain and biome eligibility still restrict combinations; incompatibility is reported rather than silently ignored. Age documentation and feature rules describe the supported subset.

Optional integrations and fallback

Integration	Milestone 5 result
TerraBlender	Optional adapter reads registered Overworld and Nether region biome IDs. Any compatible biome-producing mod using those regions can supply eligible pages; no Biomes O' Plenty ID is hard-coded. Missing TerraBlender leaves vanilla Age generation intact. A removed biome warns and uses an eligible load-time fallback without rewriting the saved plan. See TerraBlender checks.
Serene Seasons	Optional per-Age seasonal modes: No Seasons, Seasons, Eternal Winter/Summer/Fall/Spring. The adapter enrolls dynamic Age IDs in Serene's whitelist and synchronizes connected clients without a restart. Its internal config/saved-clock hooks are version-sensitive because a public dynamic-dimension registration/fixed-season API is unavailable. Without Serene, only No Seasons is valid for a new book; saved Ages retain their data with effects inactive. See config and real-client checks.
Ecliptic Seasons	Deliberately not integrated. Its 1.21.1 ValidDimensions setting requires a world restart and caches validity on server/client level load; no supported live registration or per-dimension calendar-control API was found. Issue #39 records the blocker and the upstream API needed to revisit it. Rivencraft does not require Ecliptic and does not support both season mods together.
JEI, Create/Ponder, Immersive Portals	Optional presentation/integration paths; none is required for core dedicated-server loading or Age grammar. Existing preview fallback and manual checks remain in preview compatibility.

Migration, limits, and milestone boundary

Existing saved writing keeps its stable IDs and order. Unresolved pages remain recoverable in books instead of being silently replaced. Existing bound books without a plan are not reinterpreted as newly authored grammar. A frozen plan can load without the old symbol definition or runtime-profile JSON, but missing referenced registry resources prevent or alter that load as documented in runtime profiles; restore the data pack/mod and keep a backup. The migration regression suite covers legacy writing components, schema-v1 display pages, missing symbols, and old Binder/Desk data. It is not a promise of full compatibility with every pre-release world; that broader requirement is tracked separately by open issue #60.

Milestone 5 owns recognized symbol semantics, ordered grammar, deterministic completion, persistent Age configuration, and supported feature/integration effects. Milestone 6 owns instability from invalid or excessive writing and server-safe instability effects. Milestone 7 owns remaining structures/polish, portals, recipes, models, sounds, advancements, and migration depth. Several Legacy structures and crystals were pulled forward into Milestone 5 as their own closed port issues; that does not imply the rest of Milestone 7 is complete. Custom multi-body skies, gradients, unsupported direct Rain/Snow pages, and exact Legacy terrain/feature parity remain outside the accepted M5 subset. Open issue #44 tracks custom skybox work.

Test and acceptance matrix

Check	Result or handoff
Default dedicated-server GameTests, no optional mods	26/26 passed after moving 25 detailed generation checks to the selectable generation archive. Core persistence, grammar, transaction, and migration checks remain.
Focused generation archive	51/51 passed on the reduced core plus -ParchivedGameTestSuites=generation. No generation test was deleted; 25 detailed checks moved out of the default run.
Full archive	Previously passed 116/116 before the final random-biome-count adjustment in #41. Its later rerun stalled in the first batch and was stopped under the project GameTest rule; not claimed as a passing current run. Manual random-Age biome and six-terrain travel checks are in GameTest handoffs.
Optional TerraBlender	An earlier optional-mod GameTest run passed 51/51; Biomes O' Plenty/Nether-region behavior was checked in-game during #37. The published jar does not bundle TerraBlender.
Optional Serene Seasons	In-game acceptance was recorded on #38 for six pages, saved whitelist, and no-restart sync. The GameTest mock player cannot negotiate Serene's season packet; the real-client path is documented.
Gradle build and JAR	./gradlew build --offline --no-daemon passed and produced build/libs/rivencraft-0.5.0.0.jar. Its SHA-256 is attached to the Gitea release.
Asset audit	Three byte-identical PNGs were replaced by references to their retained counterparts; no other unreferenced shipped textures or sounds were found. The user-provided dev images reference remains untouched.

Completion checklist: implementation issues reviewed; #39 explicitly scoped as unsupported; schema/Legacy/grammar/generation/integration/migration boundaries documented; core and focused validation recorded; current archive stall disclosed; release JAR and SHA-256 published; issue #42 and Milestone 5 closed only after those release artifacts are verified.