Port optional integrations and finish Age creation and modifier lifecycle

docs/MINECRAFT_26_3_PORT.md

@@ -8,6 +8,21 @@ The user wants both Minecraft lines maintained after the port, not a one-time
 26.3 release. Gitea milestone "Dual-version support: 1.21.1 and 26.3"
 tracks issues #97–#103 under parent #96.
 
+## Published status — 2026-11-11
+
+[1.0.1.136-beta.1](../ports/mc263/RELEASE_NOTES_1.0.1.136-beta.1.md) collects
+player-validated .130–.136: Link Modifier seed editing and operator retirement,
+creation rollback, and optional JEI, TerraBlender/BOP, Serene Seasons/GlitchCore
+and Ruins. Both Minecraft builds pass. The latest production client log records
+all these optional integrations loaded together. Issue #99's remaining creation
+rollback requirement is complete. #100 still requires the current dedicated
+two-client/normal-book matrix; #102 retains the live-renderer/alternative review;
+#103/#104 and parent #96 remain open. Shared dual-version follow-ups remain open
+where one or both implementations are pending. The versioning change requested
+in #103's comment remains part of that next release-workflow task; this release
+retains the version already built and player-tested. Entries below are historical
+engineering records and may describe limitations addressed in later slices.
+
 ## Version boundary
 
 Local slice `1.0.1.106-beta.1` ports the Writing Desk's two-part block,
@@ -2588,3 +2603,271 @@ new server run was performed; the previous 19 checks covered server actions, not
 client input. Please click each option with an inserted Linking Book and verify
 its selected shading and tooltip/book properties change, then repeat supported
 options with a Descriptive Book. No commit, push or publication.
+
+
+## .130 Link Modifier seed editing
+
+Ported the 1.21.1 station's seed field into the Legacy GUI. It is visible for a
+bound Descriptive Book whose Age is still indexed, including an unloaded Age.
+The complete signed 64-bit seed synchronizes through four 16-bit menu data words;
+zero and negative seeds are not treated as missing data. Linking Books and unbound
+or retired references do not expose an editable seed.
+
+Enter/keypad Enter or clicking outside the field applies the edit; Escape closes
+without applying unfinished text. Focused typing consumes inventory/hotbar shortcuts.
+Modern InputConstants are used rather than legacy numeric key values. The bounded
+payload validates the open menu ID and expected Age ID, plus menu owner, station
+identity and distance. Invalid/overflowing input and occupied Ages are refused.
+This matches 1.21.1's ordinary creative-acquired station editing permissions.
+
+Successful edits use RuntimeAgeBackend.reseed, not a display-only book component.
+Existing chunks and book identity remain intact, while newly generated chunks use
+the changed seed. Existing backend unload/save/catalog synchronization is reused;
+frozen written choices and instability history are not rerolled. Retirement UI
+remains a later port slice.
+
+Version 1.0.1.130-beta.1 builds. A temporary dedicated-server fixture passed 16 menu/
+backend checks plus two restart checks: bound/unbound visibility, malformed/overflow
+input, stale expected Age, occupied and remote refusal, retained old terrain,
+changed index/level seed, unloaded reseeding including Long.MIN_VALUE, retained
+book identity and full restart persistence. Future-chunk height fingerprints from
+the menu-reseeded Age matched a fresh new-seed control and differed from an old-seed
+control (new=-1541880620; retained origin=924831745). The initial flat-world fixture
+could not distinguish terrain seeds; the terrain comparison used a normal-world
+fixture. All temporary test worlds and fixture sources were removed and the server
+stopped. The production JAR was rebuilt without fixtures. Client field input,
+feedback and real travel validation are delegated to the player. No commit, push
+or publication.
+
+
+## .131 Link Modifier Age retirement
+
+The player passed .130 seed editing. Ported the remaining 1.21.1 station retirement
+control through the existing 26.3 lifecycle backend. A bound, active Descriptive
+Book exposes the control only to players with modern Gamemaster (OP level 2)
+permission. The first native button arms retirement; a separate red confirmation
+button performs it. The arm and confirm actions have distinct IDs so repeating the
+initial click cannot silently confirm. Normal book editing permissions are unchanged.
+
+Confirmation is server-owned and tied to the exact Age and book components.
+Replacing/removing the book, renaming, changing properties or applying a seed edit
+clears confirmation; reopening the menu starts unarmed. Invalid, stale, non-OP and
+remote actions cannot retire an Age. The target must be empty of players, including
+the operator. A failed attempt clears confirmation and reports refusal.
+
+Successful retirement uses RuntimeAgeBackend.retire: flush/unload the target,
+persist its tombstone, archive only its directory beside the active world and
+synchronize the runtime catalog. Other Ages are retained. The inserted book keeps
+its now-dead identity, cannot reopen the retired Age, and no longer exposes seed or
+retirement controls. Storage failures reuse backend rollback and display failure.
+This follows 1.21.1 archival behavior rather than permanently erasing the files.
+
+Version 1.0.1.131-beta.1 builds. Eighteen temporary dedicated-server checks plus four
+restart checks passed: permission boundary, arm/confirm order, edits and book swaps,
+occupied/remote refusal, successful retirement, exact archive and surviving control
+Age, retained dead-book identity, repeated confirmation refusal, persisted tombstone,
+and refusal to reload/recreate after restart. Test servers were stopped and all
+worlds, archives and fixture sources removed. Production JAR rebuilt without the
+fixture. Client button visibility, tooltip/feedback, occupied refusal and travel
+through an old book are delegated to the player. No commit, push or publication.
+
+
+## .132 failed Age-creation rollback (#99)
+
+The player passed .131 retirement. Wrapped new runtime Age setup in one rollback
+boundary: library writing, level construction/load event, weather and Accelerated
+settings, index/initial display name, instability record and initial SavedData save.
+The catalog is published only after those steps succeed. Book creation now supplies
+its initial name to this operation and no longer configures acceleration/name after
+commit. Operator/default callers retain the prior overloads.
+
+A failed attempt closes the level stores, dispatches unload cleanup, removes its
+new index/environment entries without leaving a retirement tombstone, restores the
+prior library/instability metadata and saves that restoration. It removes only the
+exact, newly allocated Age directory with a non-following tree walk. Existing Age
+storage, live levels, retired IDs and unsafe/symlink paths are refused before any
+setup. Pre-existing directories are never reused or erased. Cleanup failures are
+attached to the original exception; if stores cannot close, files are retained to
+avoid racing an active writer. Book failures are logged/reported and do not move
+the caller. This covers recoverable runtime exceptions, not arbitrary process death
+or a guarantee against persistent filesystem/I/O failure.
+
+Index entry cleanup is shared with retirement without removing the retained display
+name needed by retirement rollback. No existing Age scores, generation or settings
+are migrated. No production fault-injection command/hook was introduced.
+
+Version 1.0.1.132-beta.1 builds. A temporary dedicated fixture passed 36 checks plus
+seven restart checks. Injected failures during LevelEvent.Load, instability creation
+and late display-name validation left no live/indexed Age, restored prior writing,
+dispatched one unload and removed only the new directory. Clean retries of the same
+IDs succeeded. An existing directory marker survived refusal. A failed book-creation
+call returned no Age and left its caller in the original world. Restart confirmed
+failed metadata stayed absent while committed names/Accelerated settings persisted.
+Fixture source, worlds and servers were removed/stopped; production JAR rebuilt
+without the fixture. Client validation: create two Ages with distinct names, travel
+and restart, including a book with Accelerated pages, and confirm their names,
+settings and destinations remain independent. No commit, push or publication.
+
+
+## .133 optional JEI integration (#102)
+
+The player passed .132. Adapted the 1.21.1 JEI plugin to the current 26.3 API and
+render extraction path. At the player's request, the target is the newest published
+26.3 NeoForge build, 31.17.0.109 (JEI labels it beta), verified against its official
+Maven metadata and Modrinth release API. This supersedes the initially inspected
+installed 31.17.0.94. The latest release channel differs from the latest published
+build; this slice deliberately targets the newer 31.17.0.109 build.
+
+Added searchable component-aware Symbol Pages, all eight mixer Link Panel variants
+and category/volume Symbol Portfolios. Registered biome and eligible Block/Fluid
+pages use the same pools as Creative, including installed registry content. Runtime
+registration fills any missing world-dependent variants; Blank Pages and the empty
+base portfolio are removed from JEI's ingredient list. Future pages entering the
+shared category pools participate automatically. Shared link-panel variant creation
+now supplies both Creative and JEI.
+
+Reused the Writing and Ink Mixer recipe-guide categories, additive chance guides,
+and Ink Vial/Writing Desk/Book Binder/Ink Mixer catalysts. The port-specific mixer
+text correctly states one paper plus one ink per panel, 16 units per vial and reset
+of additives on output pickup. Added Link Modifier information, without a recipe.
+Wrapped guide text uses opaque, shadow-free rendering and extra Mixer guide height.
+These are explanatory guides; no auto-transfer handler or fictitious Blank Page
+crafting recipe is introduced.
+
+JEI is compile-only and isolated in its annotated scanner plugin. It is not bundled
+or a required runtime dependency; no common class loads its plugin. The developer
+`-PwithJei` option adds JEI locally, including its Maven dependencies. The current
+109 POM requires MezzConfig 0.6.10 (and its GUI module); the existing test instance's
+0.6.9 must be updated alongside JEI as required by the mod's distribution metadata.
+Maven repository filters include JEI and MezzConfig groups only.
+
+Version 1.0.1.133-beta.1 builds against the 109 API. A fresh dedicated server started
+without JEI or any optional mods and stopped normally; its world was removed. Client
+plugin discovery, ingredient counts/subtype uniqueness, guide rendering and category
+navigation await the player's check with JEI 31.17.0.109 and its dependencies. Other
+optional integrations remain unported; #102 is not complete. No commit, push or
+publication, and no user's instance files were replaced.
+
+
+## .134 optional TerraBlender regions (#102)
+
+The player passed .133 JEI. Ported the 1.21.1 optional TerraBlender region adapter
+to the current 26.3 API, compile-only at 26.3.0.0.9 (the latest published 26.3
+build checked on Modrinth). The core boundary never exposes TerraBlender types.
+Absent/broken optional API falls back to existing tags/native pools, with one
+warning for API failures. No content mod is required or bundled. A developer
+`-PwithTerraBlender` runtime option is available.
+
+Enumerates registered non-vanilla biome keys from Overworld and Nether regions,
+excluding TerraBlender's deferred placeholder. Overworld additions extend random
+and seed-completed Standard/Amplified/Island/Flat pools. Nether-region membership
+extends Cave-compatible selection and Cave Page classification even without an
+is_nether tag. Registry-derived Creative and JEI page pools share that result.
+Runtime Age construction primes membership before biome validation/generation;
+Nether material-rule conditions also include recognized TerraBlender Nether keys.
+
+Region scans are cached per registry access with weak keys; hot generation queries
+use weak-holder membership rather than rescanning all regions. Tags updates refresh
+the relevant registry entry, and a lowest-priority server-about-to-start callback
+refreshes after TerraBlender loads data-driven regions. Frozen saved biome pools
+are not rerolled or migrated. No mod-specific biome names are hardcoded.
+
+Both 1.21.1 and 26.3 APIs expose OVERWORLD/NETHER, but no CAVE or END region type.
+This distinction and the need for cave tags/metadata were posted and verified in
+#111 (comment 605), including Nether precedence for overlapping Cave/Nether tags,
+explicit authoring, and the planned Native Nether/End pages. This slice retains
+current Native Cave eligibility: excluding Nether from its default pool and adding
+those new pages remain #111, for both version tracks. No 1.21.1 code was changed.
+
+Version 1.0.1.134-beta.1 builds. A clean dedicated server without TerraBlender
+starts normally. A fresh server with TerraBlender 26.3.0.0.9, BOP 26.3.0.0.16 and
+GlitchCore 26.3.0.0.5 passed nine focused checks: 59 Overworld additions, five Nether
+additions, placeholder exclusion, completion pools, Cave Page placement, an injected
+Nether region referencing an untagged biome, cache removal after region removal,
+and Cave Age acceptance/reload with a modded Nether biome. No bulk generation or
+client rendering was claimed. Test servers stopped, worlds and fixture sources
+removed; production JAR rebuilt without fixtures. Client Creative/JEI placement,
+actual BOP surface/Cave terrain materials and decoration remain player checks.
+No commit, push or publication. Other #102 integrations remain incomplete.
+
+
+## .135 optional Serene Seasons per-Age policies (#102)
+
+The player passed .134. Ported 1.21.1's six modes: No Seasons, cycling Seasons,
+Eternal Winter/Summer/Fall/Spring. Uses the latest published 26.3 Serene build
+26.1.2.0.7 (QnvW5HPm) and GlitchCore 26.3.0.0.5 (pQgy3bfh), matching the test
+instance. Both APIs are compile-only behind a guarded adapter, never bundled or
+required. The developer -PwithSereneSeasons flag adds them to the local runtime.
+
+New Ages freeze an authored or seed-selected policy in separate SavedData. Omitted
+choices randomize only when Serene is installed, matching root Legacy ranks:
+Seasons weight 6, No Seasons 5 and each Eternal 1. Cave terrain always disables
+seasons. Existing Ages without a stored policy retain legacy cycling behavior
+when integration/auto-whitelisting is enabled; they are not randomly reassigned.
+No Seasons is usable without the optional mod; other seasonal pages require it.
+Singular page recovery keeps the last seasonal controller with existing penalties.
+
+The guarded adapter writes only the target Age's whitelist entry and persists it
+through Serene/GlitchCore's config API. Connected-client updates and login replay
+apply the same entries without a restart. Existing unrelated entries are retained.
+Eternal policies hold the middle sub-season in a bounded mid-season window, avoiding
+per-tick dirty data and leaving the Overworld calendar unchanged. Server config
+serene_seasons.auto_whitelist_ages defaults true, matching 1.21.1: explicit policies
+still apply when disabled, while existing whitelist entries are not removed merely
+by disabling automatic behavior.
+
+Policy selection participates in creation rollback before catalog publication;
+optional whitelist changes happen only after successful creation. Reload/reseed
+reuse the frozen policy. Retirement removes its whitelist entry only after backend
+retirement succeeds, while policy history can remain in global metadata. Client
+messages are limited to Rivencraft Age IDs. Compatibility failures log once rather
+than flood every level tick. No Ecliptic Seasons support is added.
+
+Version 1.0.1.135-beta.1 builds. A clean dedicated server starts without optional
+mods. With Serene/GlitchCore, 25 checks passed on creation and 22 after full restart:
+all six saved modes/whitelist policies, each eternal mid-season and recovery from a
+changed cycle value, unchanged Overworld season data, unrelated whitelist entries,
+deterministic omitted choices, no random choice when the mod is absent, and Cave
+suppression. The initial restart assertion was corrected to allow the deliberate
+mid-season hold window inherited from 1.21.1. Test worlds/fixtures were removed and
+servers stopped; production JAR rebuilt without fixtures. Client visual effects,
+reconnect/live whitelist synchronization, normal season progression, authoring and
+retirement with a real connected client remain player validation. No commit, push
+or publication; other #102 integrations remain open.
+
+
+### Optional Ruins template pages — 1.0.1.136-beta.1
+
+The preceding Serene Seasons slice passed the player's in-game check. Ruins now
+uses the 1.21.1 exact-template bridge: each unambiguous installed `.tml` filename
+gets a dynamic glyph page in a Ruins creative tab, portfolios, and JEI's page pool.
+Names preserve case and Unicode through reversible IDs. Discovery reads Ruins'
+active `config/ruins_config` directory, with its bundled archive as the first-launch
+fallback. Duplicate basenames disable the bridge because Ruins' event cannot
+identify which directory supplied the template.
+
+Authored template choices and all duplicate counts are frozen in the Age's terrain
+feature plan and restored before its load event. Only selected templates pass the
+Age dimension and pre-spawn gates; other worlds retain Ruins' own behavior. Ruins'
+biome/surface/distance requirements remain applicable. Copies multiply template
+weight and increase attempts by one per extra page, capped at 32 attempts without
+lowering an explicitly higher Ruins configuration. The first three copies are free;
+each later copy adds 100 instability, including copies beyond the attempt cap.
+Material pages do not modify Ruins structures. Unloading clears bridge state and
+reloading restores it; optional Ruins classes are not loaded when the mod is absent.
+
+The reproducible compile-only baseline is Ruins 26.3.1NF (CurseForge file 8962119);
+the installed Ruins 26.3.2NF was used for integration validation. For development,
+`-PwithRuins` adds the baseline runtime, or combine it with
+`-PruinsJar=/absolute/path/to/ruins-26.3.2NF.jar` to run a local current build.
+Neither dependency is bundled or required to run Rivencraft.
+
+Build and clean dedicated-server startup without Ruins passed. With Ruins 26.3.2NF,
+21 checks passed on creation and 10 after restart, covering 25 discovered templates,
+creative/JEI pool parity, readable/case-sensitive IDs, authoring, codec roundtrip,
+50 retained copies, attempt limits, 4,700 excess-page instability, exact template
+filtering, both dimension gates, spawn-event veto, and a real Tiki Head placement
+(149 non-air blocks counted in the checked volume). Restart, unload, and reload
+retained the counts. Temporary fixtures and test worlds were removed; test servers
+were stopped. Client glyph/GUI checks and natural spawning while exploring an Age
+remain player validation. No commit, push, or publication; #102 remains open.