#109 Changes sign storage to be sharded by region

[tpwalke2]

Region-shards sign persistence into per-(dimension, region) JSON files stored under a per-server root, replacing the single flat signs.json per world, and fixes a related storage-path bug (#133) along the way.

Why

Chunk deletion/regen tools (Chunky, MCA Selector, manual .mca deletion) give no "sign removed" event, so stale signs accumulate forever; fixing that requires cheaply answering "what signs exist in this region," which a single-file, full-scan load can't do.
Region-sharded storage (32×32 chunks, matching Minecraft's own Anvil region size) gives that query a natural home — the actual reconciliation logic is a follow-up issue (#110).

Addresses GitHub issues

• Refactoring sign storage (on disk and in memory) #109
• getMarkerFilePath resolves to incorrect path #133
• Loading signs should continue loading even if one sign throws exception #136

Changes

• Storage layout: signs now live at {server_root}/bluemapsignmarkers/{level}/{namespace}/{path}/r.{regionX}.{regionZ}.json instead of config/bluemapsignmarkers/{level}/signs.json — new SignRegionKey/SignRegionPartitioner do the region-coordinate math (floorDiv-based,
  so negative coordinates partition correctly) and dimension-string splitting.
• ServerPathProvider: repurposed from a dead/unimplemented interface into getMarkerStorageRoot(MinecraftServer), implemented on BlueMapSignMarkersMod. Requires .normalize() on the resolved level path — LevelResource.ROOT's relative path is literally ".", and without
  normalizing, getParent()/getFileName() land one level too deep (inside the world save folder instead of beside it).
• Read/write: RegionShardedSignEntryLoader (walk + load all region files) and RegionShardedSignEntryWriter (partition + write per-region files, deleting stale empty-region files) replace the single-file logic in SignProvider.
• Migration: LegacySignFileMigrator one-shot migrates an existing flat signs.json (reusing the existing V1→V2→V3 loader chain unchanged) into region-sharded files, then backs up the legacy file (.migrated suffix, via new FileUtils.moveToBackup) rather than deleting it. Migration locates the legacy file via the old (unchanged) path formula, since that's what's actually on disk for existing installs.
• mod_version bumped 26.2-0.16.1 → 26.2-0.17.0 (storage location change for every install).
• New tests for region-key math, dimension splitting, partitioning, round-trip load/write, and migration.
• Design rationale and rejected alternatives (SQLite, H2, LMDB/MapDB, store-by-player) documented in plans/region-sharded-sign-persistence-plan.md.

Testing

• ./gradlew test — new persistence/migration/region-math tests pass alongside existing suite.
• ./gradlew build — full build succeeds.
• Manual via ./gradlew runServer: place signs across multiple regions and dimensions (overworld + nether), restart, confirm markers still appear; separately, boot against a pre-existing flat signs.json fixture and confirm it migrates to the new region-file layout with
  the legacy file backed up, not deleted.

[Copilot]

Pull request overview

This PR refactors sign persistence from a single per-world signs.json into per-(dimension, region) shard files (matching Minecraft’s 32×32-chunk region grid) under a server-root-based storage directory, and introduces a one-shot migration from legacy installs while also fixing the world-path resolution issue described in #133.

Changes:

• Introduces SignRegionKey + SignRegionPartitioner and new region-sharded loader/writer to store signs as r.<regionX>.<regionZ>.json per dimension.
• Updates server path resolution via ServerPathProvider#getMarkerStorageRoot(MinecraftServer) and wires it into mod startup/shutdown persistence.
• Adds migration logic for legacy signs.json (load via existing V1/V2/V3 loader chain, write shards, then back up legacy file) plus a comprehensive JUnit test suite for the new persistence behavior.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/main/java/com/tpwalke2/bluemapsignmarkers/BlueMapSignMarkersMod.java	Uses new storage-root API; loads from sharded storage or migrates legacy; saves to sharded storage.
src/main/java/com/tpwalke2/bluemapsignmarkers/ServerPathProvider.java	Repurposes interface to provide marker storage root from MinecraftServer.
src/main/java/com/tpwalke2/bluemapsignmarkers/common/FileUtils.java	Adds move-to-backup helper used by legacy migration.
src/main/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/SignProvider.java	Switches persistence orchestration to region-sharded storage + legacy migration fallback.
src/main/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/SignRegionKey.java	Defines (dimension, regionX, regionZ) key and shard file path mapping.
src/main/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/SignRegionPartitioner.java	Partitions sign entries into region shards for writing.
src/main/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/RegionShardedSignEntryWriter.java	Writes per-region JSON shards and cleans up stale shard files.
src/main/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/loaders/RegionShardedSignEntryLoader.java	Walks shard tree and loads all region files into sign entries.
src/main/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/LegacySignFileMigrator.java	One-shot migration from legacy single-file storage into region shards + backup.
src/test/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/SignRegionKeyTest.java	Tests region math + dimension path splitting for shard layout.
src/test/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/SignRegionPartitionerTest.java	Tests partitioning behavior across dimensions and regions.
src/test/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/RegionShardedSignEntryWriterTest.java	Verifies writer output, version envelope, and stale shard deletion.
src/test/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/RegionShardedSignEntryLoaderTest.java	Verifies loader behavior and writer/loader round-trip across shards.
src/test/java/com/tpwalke2/bluemapsignmarkers/core/signs/persistence/LegacySignFileMigratorTest.java	Verifies migration behavior and legacy backup semantics.
plans/region-sharded-sign-persistence-plan.md	Documents rationale, design, and migration considerations.
plans/codebase-review-2026-07-11.md	Adds broader codebase-review notes (reference material).
gradle.properties	Bumps mod_version for the storage layout change.
.gitignore	Ignores logs/ directory.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.