World Dimension Loader 1.4.0 - Upgrade Guide

============================================================
1. Before updating
============================================================
Back up:
1) config/worlddimensionloader/
2) WDL_custom_dimensions/
3) the complete Minecraft save that uses WDL

WDL 1.4.0 does not add new Config keys or change Config defaults.
Regenerating Config solely because you upgraded from 1.3.0 to 1.4.0 is therefore not required.

If you want the newest generated comments:
- move the old Config files aside;
- start once to regenerate;
- copy only your intentional overrides into the new files.

Existing Config files are never overwritten automatically.

============================================================
2. Key 1.4.0 change - fixed physical ID when Reset is OFF
============================================================
For a new/pristine runtime with:

reset_on_empty = false

WDL 1.4.0 does not add a timestamp.

Physical Dimension ID:
wdl:<id>

Storage:
dimensions/wdl/<id>/

If another mod requires a predictable fixed Dimension ID, the supported pattern is to create the runtime with Reset disabled from the beginning.

============================================================
3. Existing 1.3.0 timestamp runtimes
============================================================
A timestamp runtime that is already current from 1.3.0 stays in place after updating to 1.4.0, even if Reset is disabled.

Example:
wdl:test_world_01/20260822123000

WDL 1.4.0 does not provide:
- automatic timestamp -> fixed-ID reverse migration;
- an in-place migration command.

Do not manually rename or move WDL runtime folders.
Changing a physical Dimension ID through file operations alone can conflict with player positions, other mods' SavedData/caches, and WDL recovery authority.

============================================================
4. Reset OFF -> ON
============================================================
Changing an existing fixed-ID runtime to:

reset_on_empty = true

does not rename it immediately.

The current fixed runtime remains active until the first actual Reset succeeds. That Reset rotates the logical Dimension to a timestamp physical generation.

A Dimension that actually uses Runtime Reset cannot be promised a permanently fixed physical ID afterward.

============================================================
5. Ambiguous runtime storage fails closed
============================================================
If exact lifecycle authority is unavailable and more than one physical candidate exists for the same logical ID, for example:

dimensions/wdl/test_world_01/                 # fixed payload
dimensions/wdl/test_world_01/<timestamp>/     # timestamp generation

The same fail-closed rule applies if the legacy canonical path
`dimensions/worlddimensionloader/test_world_01/` also exists. This legacy path is retained only as an existing-authority compatibility case; it is not the new 1.4.0 Reset-OFF storage location.

WDL 1.4.0 does not guess which one is current.

Safe behavior:
- do not adopt a candidate by guess;
- do not silently allocate a replacement generation;
- do not move folders;
- do not delete candidates;
- Startup GC must not delete candidates whose current/retired status cannot be proven;
- remain fail-closed for diagnosis.

Do not try to repair this by deleting folders while the game/server is running. Preserve backups and latest.log/debug.log.

============================================================
6. Config changes during Reset
============================================================
If Reset has not reached destructive authority yet, changing Reset to OFF may cancel the pending operation.

After same-operation destructive/recovery authority exists, a Config change does not simply cancel the transaction.

Recovery/transaction safety takes precedence over Config.

Malformed or conflicting authority is not treated as "nothing happened". WDL fails closed instead.

============================================================
7. Gate selection
============================================================
Current behavior since 1.3.0:
- omitted selection_mode + non-empty dimensions -> LIST;
- explicit LIST -> LIST;
- explicit ALL -> all eligible READY WDL imported Dimensions;
- omitted mode + no dimensions -> legacy ALL fallback.

Explicitly write selection_mode="ALL" when ALL is intended.

============================================================
8. Cleanup / Resident behavior
============================================================
Current key:
runtime.defer_dimension_cleanup_until_restart

Legacy compatibility key:
runtime.resident_reset_compatibility

Safe default: true.

true:
retain old generations during play and let Startup GC clean proved-safe retired generations after restart.

false:
expert live unload/delete path. Not recommended.

Valkyrien Skies detection forces deferred cleanup.

resident_gc_backup defaults to false.

============================================================
9. Compatibility
============================================================
Valkyrien Skies and Distant Horizons are both optional dependencies.
The normal baseline works with neither installed.

Current protection/testing was centered on:
- Valkyrien Skies 2.4.11;
- Distant Horizons 3.2.0-b.

Unknown future versions are not guaranteed.

============================================================
10. Post-upgrade checks
============================================================
At minimum:
1) run /wdl scan;
2) check /wdl list;
3) check /wdl status;
4) confirm existing Dimensions remain enterable;
5) confirm a newly initialized Reset-OFF Dimension uses wdl:<id>;
6) confirm existing timestamp Dimensions were not silently moved.

STARTUP ONLY changes require a full restart.
