feat(characters): add native sheets and safe recipe previews

feat(equipment): pack and restore native shulker contents
feat(persistence): save characters and create signed Tail books
2026-09-17 20:57:55 -04:00 · 2026-09-17 20:33:18 -04:00 · 2026-09-17 08:23:52 -04:00
15 changed files with 1567 additions and 3 deletions
@@ -2,7 +2,7 @@

 **Development foundation only. No playable gameplay is registered, and this JAR is not ready for deployment.**

-Fantasy Stick is the proposed transferable-character RPG plugin for Social Minecraft. Its approved design uses Paper character sheets, native equipment storage and a book/basic-stick/seven-ability hotbar. These remain planned native features. The server-independent progression core now tests initial stats/points, stat purchases, CON's equal maximum/current-health gain, capped XP and `MAX` presentation. It is not yet connected to crafting, native health, the book or persistence.
+Fantasy Stick is the proposed transferable-character RPG plugin for Social Minecraft. Its approved design uses Paper character sheets, native equipment storage and a book/basic-stick/seven-ability hotbar. These remain planned native features. The server-independent progression core now tests initial stats/points, stat purchases, CON's equal maximum/current-health gain, capped XP and `MAX` presentation. YAML persistence, backend death/revival transitions and a native signed-book factory are also present. None is yet wired into playable crafting, health, session or spell interactions.

 ## Build and verify

@@ -15,10 +15,36 @@ Fantasy Stick is the proposed transferable-character RPG plugin for Social Minec
 ./gradlew check jar -PreleaseVersion=0.1.0
 ```

-`check` runs Java packaging tests, TypeScript release-client/credential-helper tests, and a native compatibility test against the checksum-verified Purpur runtime. Native preparation downloads and patches the declared runtime **without starting a listening server or creating a gameplay world**. A clean build repeats that preparation. Dependencies and runtime downloads require network access.
+`check` runs Java packaging tests, TypeScript release-client/credential-helper tests, and a native compatibility test against the checksum-verified Purpur runtime. Native preparation downloads and patches the declared runtime and loads vanilla registries/components **without starting a listening server or creating a gameplay world**. The item tests decode signed written books with Minecraft's real codec, without a plugin instance or YAML lookup. A clean build repeats that preparation. Dependencies and runtime downloads require network access.

 Build output is `build/libs/purpur-fantasy-stick-<version>.jar`. Server APIs, tests, credentials, and Node tooling are not bundled in the plugin. Runtime identity is `FantasyStick`, entrypoint `games.dmg.fantasystick.FantasyStickPlugin`, data folder `FantasyStick`, namespace `fantasystick`. Bootstrap registers no commands, permissions, recipes, sessions or gameplay listeners.

+## Character storage and keepsakes
+
+`YamlCharacterRepository` stores schema-version-1 records at `<plugin data directory>/characters/<character UUID>.yml`. Character identity, name, progress, seven-slot loadout, ability cooldowns, explicit `dead` flag and latest death ID/time are preserved; the record has no holder-owned equipment or ordinary-health/nutrition snapshot. Integer values and decimal health retain exact precision, and timestamps use UTC RFC 3339 strings. Unknown learned ability IDs and unlearned cooldowns survive reload.
+
+The file adapter uses safe YAML construction, duplicate-key rejection, bounded reads (1 MiB per record), typed validation, UUID filenames and no symlinked record reads. Replacement writes a complete temporary file, flushes it and atomically renames it; expected revisions and transient OS file locks reject duplicate/stale writers. Empty `.lock` files are coordination files, not administrator-unlock flags. Unsupported atomic replacement fails rather than falling back to a partial overwrite. Malformed files are retained, not reset.
+
+`CharacterStorage` queues disk operations on its persistence worker and acknowledges successful writes only after commit. Its backend restoration checks the saved dead flag, matching current death ID and death age strictly under 24 hours at the request/selection time. It preserves progress/cooldowns and restores full character health; old books do not become eligible after a later death. This method is **not** a complete Revive spell: the engine must still validate the caster and native dialog, spend its cooldown, recheck item possession and perform physical conversion safely.
+
+`TailBooks` creates vanilla `WRITTEN_BOOK` items with static pages. The full character name remains in display/pages; the native title is bounded to vanilla's 32 UTF-16 units without splitting a surrogate pair. `fantasystick:tail_version`, `character_id` and `death_id` identify the saved record. Pages/title are never read as authoritative stats or revival eligibility. Plugin absence does not remove the vanilla written-book contents. The factory does not yet deliver books from a death event.
+
+File-level atomic replacement is **not** atomicity with Minecraft inventory/player saves. This checkpoint does not implement cross-save reconciliation, an administrator lock, automatic overflow drops or player/session persistence.
+
+## Paper sheet and recipe definition
+
+`CharacterSheets` renders one Paper sheet from a saved live record, with its current name and the exact offhand instruction. `fantasystick:sheet_version` (integer 1) and `character_id` (UUID string) identify the character, with no owner lock or duplicated progress snapshot. Identification is only a reference: it does not authorize entry or replace saved-state/session validation. Rendering from a dead record is refused.
+
+The `fantasystick:character_sheet` shapeless recipe definition contains one stick, paper, feather and ink sac. Its preview has no character metadata and allocates no identity/name. It is deliberately **not registered** yet: actual completion, bulk crafting, cancellation/save handling and anvil rename persistence still need their event adapters. Presentation edits preserving metadata are tested, not a claim that complete anvil transactions work.
+
+## Native equipment adapter
+
+`EquipmentStorage` preflights and moves nine hotbar/four armor slots into an actual named shulker in one free main-inventory slot. Item counts, metadata/damage/enchantments and legal nested contents remain native item data, accessible without this plugin. Eligibility is tested against the real vanilla shulker slot for every nonlegacy native item material; a main-inventory shulker does not prevent entry. Oversized or ineligible equipment and missing space produce unchanged refusals.
+
+Version-1 box metadata uses `fantasystick:storage_version`, `storage_owner_id`, `storage_session_id` and `storage_slots`. Box positions 0–8 contain original hotbar slots 0–8; positions 9–12 contain boots, leggings, chest and head from player slots 36–39. These metadata fields are for identity/restoration, not the only copy of the items. Restoration searches main slots 9–35, so sorting relocation does not lose the box. Repeated requests, wrong identity, duplicate/malformed boxes, unexpected extra contents or occupied restoration slots do not overwrite/delete items. These are adapter error results, not a persistent administrator lock or completed recovery policy.
+
+The caller must remove authenticated fantasy controls before restoration. One new head stack uses the slot freed by removing the box, even with a full main inventory; there is no drop fallback. The adapter does not yet route sheet/cursor events, emit entry warnings, manage character/player snapshots or register a playable session. Native tests use real player-slot storage with only the absent network recipient stubbed; client packets and live gameplay remain unverified.
+
 ## CI and publication

 Gitea CI verifies pushes/PRs; main pushes run semantic-release and can publish immutable versioned JARs. Source checkout is anonymous from the public repository; external action revisions are pinned to full commit SHAs. CI and actual release publication must both be verified for the exact source commit before any deployment preparation. The operator has provisioned `RELEASE_TOKEN` and the bootstrap is pushed. Do not infer successful CI, publication or credential validity from the secret name alone; record actual exact-commit workflow and artifact results in the canonical wiki.
@@ -81,7 +81,7 @@ val nativeRuntimeJars = files(fileTree(nativeRuntime) {
 nativeTest.compileClasspath += sourceSets.main.get().output + nativeRuntimeJars
 nativeTest.runtimeClasspath += sourceSets.main.get().output + nativeRuntimeJars
 val nativeCompatibilityTest = tasks.register<Test>("nativeCompatibilityTest") {
-    description = "Verifies packaged metadata against the actual Purpur runtime without starting a server"
+    description = "Verifies packaged metadata and native item serialization without starting a server"
    dependsOn(tasks.jar)
    testClassesDirs = nativeTest.output.classesDirs
    classpath = nativeTest.runtimeClasspath
@@ -0,0 +1,60 @@
+package games.dmg.fantasystick.items;
+
+import games.dmg.fantasystick.persistence.CharacterRecord;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.ShapelessRecipe;
+import org.bukkit.persistence.PersistentDataType;
+
+/** Sheet presentation/identity only; saved records and session eligibility remain authoritative. */
+public final class CharacterSheets {
+    private static final NamespacedKey VERSION = new NamespacedKey("fantasystick", "sheet_version");
+    private static final NamespacedKey CHARACTER = new NamespacedKey("fantasystick", "character_id");
+    private static final String INSTRUCTION = "Character sheet: place in off hand to enter fantasy world.";
+
+    public ItemStack create(CharacterRecord character) {
+        if (character.dead()) throw new IllegalArgumentException("Dead characters require authoritative revival before sheet creation");
+        var item = paper(character.name());
+        var meta = item.getItemMeta();
+        var data = meta.getPersistentDataContainer();
+        data.set(VERSION, PersistentDataType.INTEGER, 1);
+        data.set(CHARACTER, PersistentDataType.STRING, character.id().toString());
+        item.setItemMeta(meta);
+        return item;
+    }
+
+    /** Definition only: a future craft-completion adapter must persist and mint each actual result. */
+    public ShapelessRecipe recipe() {
+        return new ShapelessRecipe(new NamespacedKey("fantasystick", "character_sheet"), paper("Character sheet"))
+            .addIngredient(Material.STICK).addIngredient(Material.PAPER)
+            .addIngredient(Material.FEATHER).addIngredient(Material.INK_SAC);
+    }
+
+    private static ItemStack paper(String name) {
+        var item = new ItemStack(Material.PAPER);
+        var meta = item.getItemMeta();
+        meta.displayName(Component.text(name));
+        meta.lore(List.of(Component.text(INSTRUCTION)));
+        item.setItemMeta(meta);
+        return item;
+    }
+
+    /** A reference, not authorization to activate: the caller must load saved state and claim the session. */
+    public Optional<UUID> identify(ItemStack item) {
+        if (item == null || item.getType() != Material.PAPER || !item.hasItemMeta()) return Optional.empty();
+        var data = item.getItemMeta().getPersistentDataContainer();
+        if (!data.has(VERSION, PersistentDataType.INTEGER)
+                || !Integer.valueOf(1).equals(data.get(VERSION, PersistentDataType.INTEGER))
+                || !data.has(CHARACTER, PersistentDataType.STRING)) return Optional.empty();
+        try {
+            return Optional.of(UUID.fromString(data.get(CHARACTER, PersistentDataType.STRING)));
+        } catch (IllegalArgumentException exception) {
+            return Optional.empty();
+        }
+    }
+}
@@ -0,0 +1,111 @@
+package games.dmg.fantasystick.items;
+
+import java.util.Arrays;
+import java.util.Objects;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.block.ShulkerBox;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.PlayerInventory;
+import org.bukkit.inventory.meta.BlockStateMeta;
+import org.bukkit.persistence.PersistentDataType;
+
+/** Server-thread inventory operations; session eligibility and event routing belong to the caller. */
+public final class EquipmentStorage {
+    public enum PackResult { PACKED, NO_SPACE, INELIGIBLE_EQUIPMENT, ALREADY_PACKED }
+
+    private static final int[] EQUIPMENT_SLOTS = {0, 1, 2, 3, 4, 5, 6, 7, 8, 36, 37, 38, 39};
+    private static final NamespacedKey VERSION = key("storage_version");
+    private static final NamespacedKey OWNER = key("storage_owner_id");
+    private static final NamespacedKey SESSION = key("storage_session_id");
+    private static final NamespacedKey SLOTS = key("storage_slots");
+
+    public PackResult pack(PlayerInventory inventory, UUID owner, UUID session) {
+        Objects.requireNonNull(owner);
+        Objects.requireNonNull(session);
+        for (int slot = 9; slot < 36; slot++) {
+            if (matches(inventory.getItem(slot), owner, session)) return PackResult.ALREADY_PACKED;
+        }
+        for (int slot : EQUIPMENT_SLOTS) {
+            var item = inventory.getItem(slot);
+            if (!empty(item) && item.getType().name().endsWith("SHULKER_BOX")) return PackResult.INELIGIBLE_EQUIPMENT;
+        }
+        int available = -1;
+        for (int slot = 9; slot < 36; slot++) {
+            if (empty(inventory.getItem(slot))) { available = slot; break; }
+        }
+        if (available == -1) return PackResult.NO_SPACE;
+        var item = new ItemStack(Material.SHULKER_BOX);
+        var meta = (BlockStateMeta) item.getItemMeta();
+        var box = (ShulkerBox) meta.getBlockState();
+        var contents = box.getInventory();
+        for (int i = 0; i < EQUIPMENT_SLOTS.length; i++) {
+            var equipment = inventory.getItem(EQUIPMENT_SLOTS[i]);
+            if (!empty(equipment) && equipment.getAmount() > Math.min(equipment.getMaxStackSize(), contents.getMaxStackSize())) {
+                return PackResult.INELIGIBLE_EQUIPMENT;
+            }
+            contents.setItem(i, equipment);
+        }
+        meta.setBlockState(box);
+        meta.displayName(Component.text("Fantasy Storage Box"));
+        var data = meta.getPersistentDataContainer();
+        data.set(VERSION, PersistentDataType.INTEGER, 1);
+        data.set(OWNER, PersistentDataType.STRING, owner.toString());
+        data.set(SESSION, PersistentDataType.STRING, session.toString());
+        data.set(SLOTS, PersistentDataType.INTEGER_ARRAY, EQUIPMENT_SLOTS.clone());
+        item.setItemMeta(meta);
+        for (int slot : EQUIPMENT_SLOTS) inventory.setItem(slot, null);
+        inventory.setItem(available, item);
+        return PackResult.PACKED;
+    }
+
+    public enum RestoreResult { RESTORED, NOT_FOUND, AMBIGUOUS, INVALID_BOX, OCCUPIED_SLOT }
+
+    /** Caller removes validated fantasy controls first. Unexpected slot occupants are never overwritten. */
+    public RestoreResult restore(PlayerInventory inventory, UUID owner, UUID session) {
+        Objects.requireNonNull(owner);
+        Objects.requireNonNull(session);
+        int found = -1;
+        for (int slot = 9; slot < 36; slot++) {
+            if (matches(inventory.getItem(slot), owner, session)) {
+                if (found != -1) return RestoreResult.AMBIGUOUS;
+                found = slot;
+            }
+        }
+        if (found == -1) return RestoreResult.NOT_FOUND;
+        var item = inventory.getItem(found);
+        if (item.getAmount() != 1 || !(item.getItemMeta() instanceof BlockStateMeta meta)
+                || !(meta.getBlockState() instanceof ShulkerBox box)) return RestoreResult.INVALID_BOX;
+        var data = meta.getPersistentDataContainer();
+        if (!data.has(VERSION, PersistentDataType.INTEGER) || data.get(VERSION, PersistentDataType.INTEGER) != 1
+                || !data.has(SLOTS, PersistentDataType.INTEGER_ARRAY)
+                || !Arrays.equals(EQUIPMENT_SLOTS, data.get(SLOTS, PersistentDataType.INTEGER_ARRAY))) {
+            return RestoreResult.INVALID_BOX;
+        }
+        var contents = box.getInventory();
+        for (int slot = EQUIPMENT_SLOTS.length; slot < contents.getSize(); slot++) {
+            if (!empty(contents.getItem(slot))) return RestoreResult.INVALID_BOX;
+        }
+        for (int slot : EQUIPMENT_SLOTS) {
+            if (slot != 39 && !empty(inventory.getItem(slot))) return RestoreResult.OCCUPIED_SLOT;
+        }
+        var currentHead = inventory.getItem(39);
+        var displacedHead = empty(currentHead) ? null : currentHead.clone();
+        for (int i = 0; i < EQUIPMENT_SLOTS.length; i++) inventory.setItem(EQUIPMENT_SLOTS[i], contents.getItem(i));
+        inventory.setItem(found, displacedHead);
+        return RestoreResult.RESTORED;
+    }
+
+    private static boolean matches(ItemStack item, UUID owner, UUID session) {
+        if (empty(item)) return false;
+        var data = item.getItemMeta().getPersistentDataContainer();
+        return data.has(OWNER, PersistentDataType.STRING) && data.has(SESSION, PersistentDataType.STRING)
+            && owner.toString().equals(data.get(OWNER, PersistentDataType.STRING))
+            && session.toString().equals(data.get(SESSION, PersistentDataType.STRING));
+    }
+
+    private static NamespacedKey key(String name) { return new NamespacedKey("fantasystick", name); }
+    private static boolean empty(ItemStack item) { return item == null || item.isEmpty(); }
+}
@@ -0,0 +1,70 @@
+package games.dmg.fantasystick.items;
+
+import games.dmg.fantasystick.persistence.CharacterRecord;
+import games.dmg.fantasystick.progression.Stat;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.BookMeta;
+import org.bukkit.persistence.PersistentDataType;
+
+/** Native readable keepsake; revival uses only its IDs to consult authoritative saved character data. */
+public final class TailBooks {
+    private static final NamespacedKey VERSION = new NamespacedKey("fantasystick", "tail_version");
+    private static final NamespacedKey CHARACTER = new NamespacedKey("fantasystick", "character_id");
+    private static final NamespacedKey DEATH = new NamespacedKey("fantasystick", "death_id");
+
+    public record Identity(UUID characterId, UUID deathId) { }
+
+    public ItemStack create(CharacterRecord character) {
+        if (!character.dead()) throw new IllegalArgumentException("A Tail book requires a dead character record");
+        var item = new ItemStack(Material.WRITTEN_BOOK);
+        var meta = (BookMeta) item.getItemMeta();
+        String fullTitle = "Tail of " + character.name();
+        int titleEnd = Math.min(32, fullTitle.length());
+        if (titleEnd < fullTitle.length() && Character.isHighSurrogate(fullTitle.charAt(titleEnd - 1))) titleEnd--;
+        if (!meta.setTitle(fullTitle.substring(0, titleEnd))) {
+            throw new IllegalStateException("Native written-book title was rejected");
+        }
+        meta.setAuthor("Fantasy Stick");
+        meta.setGeneration(BookMeta.Generation.ORIGINAL);
+        meta.displayName(Component.text(fullTitle));
+        List<Component> pages = new ArrayList<>();
+        pages.add(Component.text(fullTitle));
+        pages.add(Component.text("Level: " + character.level()));
+        pages.add(Component.text("XP: " + character.experience()));
+        pages.add(Component.text("Unspent points: " + character.unspentPoints()));
+        for (Stat stat : Stat.values()) pages.add(Component.text(stat + ": " + character.stats().get(stat)));
+        pages.add(Component.text("Abilities: " + (character.learned().isEmpty() ? "None" : "")));
+        character.learned().stream().sorted().forEach(ability -> pages.add(Component.text(ability)));
+        pages.add(Component.text("Fell: " + character.diedAt()));
+        meta.pages(pages);
+        var data = meta.getPersistentDataContainer();
+        data.set(VERSION, PersistentDataType.INTEGER, 1);
+        data.set(CHARACTER, PersistentDataType.STRING, character.id().toString());
+        data.set(DEATH, PersistentDataType.STRING, character.deathId().toString());
+        item.setItemMeta(meta);
+        return item;
+    }
+
+    public Optional<Identity> identify(ItemStack item) {
+        if (item == null || item.getType() != Material.WRITTEN_BOOK || !item.hasItemMeta()) return Optional.empty();
+        var data = item.getItemMeta().getPersistentDataContainer();
+        if (!data.has(VERSION, PersistentDataType.INTEGER)
+                || !Integer.valueOf(1).equals(data.get(VERSION, PersistentDataType.INTEGER))
+                || !data.has(CHARACTER, PersistentDataType.STRING) || !data.has(DEATH, PersistentDataType.STRING)) {
+            return Optional.empty();
+        }
+        try {
+            return Optional.of(new Identity(UUID.fromString(data.get(CHARACTER, PersistentDataType.STRING)),
+                UUID.fromString(data.get(DEATH, PersistentDataType.STRING))));
+        } catch (IllegalArgumentException exception) {
+            return Optional.empty();
+        }
+    }
+}
@@ -0,0 +1,51 @@
+package games.dmg.fantasystick.persistence;
+
+import games.dmg.fantasystick.progression.Stat;
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.time.Instant;
+import java.util.EnumSet;
+import java.util.Map;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+
+/** Immutable character data, never a holder's ordinary equipment or session snapshot. */
+public record CharacterRecord(
+        UUID id, String name, BigInteger revision, Map<Stat, BigInteger> stats,
+        int level, BigInteger experience, BigInteger unspentPoints, BigDecimal health,
+        Set<String> learned, List<String> loadout, Map<String, Instant> cooldowns,
+        boolean dead, UUID deathId, Instant diedAt) {
+    public CharacterRecord {
+        Objects.requireNonNull(id);
+        Objects.requireNonNull(name);
+        Objects.requireNonNull(revision);
+        Objects.requireNonNull(experience);
+        Objects.requireNonNull(unspentPoints);
+        Objects.requireNonNull(health);
+        stats = Map.copyOf(stats);
+        learned = Set.copyOf(learned);
+        loadout = List.copyOf(loadout);
+        cooldowns = Map.copyOf(cooldowns);
+        if (revision.signum() < 0 || experience.signum() < 0 || unspentPoints.signum() < 0 || level < 1
+                || !stats.keySet().equals(EnumSet.allOf(Stat.class))
+                || stats.values().stream().anyMatch(value -> value.signum() < 0)
+                || health.signum() < 0
+                || health.compareTo(new BigDecimal(stats.get(Stat.CON).add(BigInteger.TEN))) > 0
+                || loadout.size() != 7 || learned.stream().anyMatch(String::isBlank)
+                || cooldowns.keySet().stream().anyMatch(String::isBlank)
+                || (deathId == null) != (diedAt == null) || dead && deathId == null) {
+            throw new IllegalArgumentException("Invalid character record");
+        }
+        for (String ability : loadout) {
+            if (!ability.isEmpty() && !learned.contains(ability)) {
+                throw new IllegalArgumentException("Loadout references an unlearned ability");
+            }
+        }
+    }
+
+    public BigDecimal maximumHealth() {
+        return new BigDecimal(stats.get(Stat.CON).add(BigInteger.TEN));
+    }
+}
@@ -0,0 +1,99 @@
+package games.dmg.fantasystick.persistence;
+
+import java.io.IOException;
+import java.math.BigInteger;
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.RejectedExecutionException;
+
+/** Asynchronous character persistence; this does not cast Revive or consume/deliver inventory items. */
+public final class CharacterStorage implements AutoCloseable {
+    private final YamlCharacterRepository repository;
+    private final Clock clock;
+    private final ExecutorService worker = Executors.newSingleThreadExecutor(
+        task -> new Thread(task, "fantasy-character-persistence"));
+
+    public CharacterStorage(YamlCharacterRepository repository, Clock clock) {
+        this.repository = Objects.requireNonNull(repository);
+        this.clock = Objects.requireNonNull(clock);
+    }
+
+    public CompletableFuture<Void> create(CharacterRecord character) {
+        return submit(() -> {
+            repository.create(character);
+            return null;
+        });
+    }
+
+    public CompletableFuture<Optional<CharacterRecord>> find(UUID id) {
+        return submit(() -> repository.load(id));
+    }
+
+    public CompletableFuture<Optional<CharacterRecord>> recordDeath(UUID characterId, BigInteger expectedRevision) {
+        Objects.requireNonNull(characterId);
+        Objects.requireNonNull(expectedRevision);
+        Instant diedAt = clock.instant();
+        return submit(() -> {
+            Optional<CharacterRecord> found = repository.load(characterId);
+            if (found.isEmpty()) return Optional.empty();
+            CharacterRecord old = found.orElseThrow();
+            if (old.dead() || !old.revision().equals(expectedRevision)) return Optional.empty();
+            var dead = new CharacterRecord(old.id(), old.name(), old.revision().add(BigInteger.ONE), old.stats(),
+                old.level(), old.experience(), old.unspentPoints(), java.math.BigDecimal.ZERO, old.learned(),
+                old.loadout(), old.cooldowns(), true, UUID.randomUUID(), diedAt);
+            repository.replace(dead, old.revision());
+            return Optional.of(dead);
+        });
+    }
+
+    public CompletableFuture<Optional<CharacterRecord>> restoreDeathRecord(UUID characterId, UUID deathId) {
+        Objects.requireNonNull(characterId);
+        Objects.requireNonNull(deathId);
+        Instant selectedAt = clock.instant();
+        return submit(() -> {
+            Optional<CharacterRecord> found = repository.load(characterId);
+            if (found.isEmpty() || !found.orElseThrow().dead()) return Optional.empty();
+            CharacterRecord old = found.orElseThrow();
+            Duration age = Duration.between(old.diedAt(), selectedAt);
+            if (!deathId.equals(old.deathId()) || age.isNegative() || age.compareTo(Duration.ofHours(24)) >= 0) {
+                return Optional.empty();
+            }
+            var restored = new CharacterRecord(old.id(), old.name(), old.revision().add(BigInteger.ONE), old.stats(),
+                old.level(), old.experience(), old.unspentPoints(), old.maximumHealth(), old.learned(),
+                old.loadout(), old.cooldowns(), false, old.deathId(), old.diedAt());
+            repository.replace(restored, old.revision());
+            return Optional.of(restored);
+        });
+    }
+
+    @FunctionalInterface
+    private interface DiskOperation<T> { T run() throws IOException; }
+
+    private <T> CompletableFuture<T> submit(DiskOperation<T> operation) {
+        try {
+            return CompletableFuture.supplyAsync(() -> {
+                try {
+                    return operation.run();
+                } catch (IOException exception) {
+                    throw new CompletionException(exception);
+                }
+            }, worker);
+        } catch (RejectedExecutionException exception) {
+            return CompletableFuture.failedFuture(exception);
+        }
+    }
+
+    /** Stop accepting work without blocking shutdown; already queued file writes may finish. */
+    @Override
+    public void close() {
+        worker.shutdown();
+    }
+}
@@ -0,0 +1,117 @@
+package games.dmg.fantasystick.persistence;
+
+import games.dmg.fantasystick.progression.Stat;
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.EnumMap;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import org.yaml.snakeyaml.LoaderOptions;
+import org.yaml.snakeyaml.Yaml;
+import org.yaml.snakeyaml.constructor.SafeConstructor;
+
+/** Plain values only: no Bukkit item deserialization or arbitrary Java YAML tags. */
+final class CharacterYaml {
+    private CharacterYaml() { }
+
+    private static Yaml yaml() {
+        var options = new LoaderOptions();
+        options.setAllowDuplicateKeys(false);
+        options.setMaxAliasesForCollections(0);
+        options.setCodePointLimit(1_048_576);
+        return new Yaml(new SafeConstructor(options));
+    }
+
+    static String encode(CharacterRecord record) {
+        Map<String, Object> root = new LinkedHashMap<>();
+        root.put("schema-version", 1);
+        root.put("character-id", record.id().toString());
+        root.put("name", record.name());
+        root.put("revision", record.revision().toString());
+        Map<String, String> stats = new LinkedHashMap<>();
+        for (Stat stat : Stat.values()) stats.put(stat.name(), record.stats().get(stat).toString());
+        root.put("stats", stats);
+        root.put("level", record.level());
+        root.put("experience", record.experience().toString());
+        root.put("unspent-points", record.unspentPoints().toString());
+        root.put("health", record.health().toString());
+        root.put("learned-abilities", record.learned().stream().sorted().toList());
+        root.put("loadout", record.loadout());
+        List<Map<String, String>> cooldowns = new ArrayList<>();
+        record.cooldowns().entrySet().stream().sorted(Map.Entry.comparingByKey()).forEach(entry ->
+            cooldowns.add(Map.of("ability", entry.getKey(), "ready-at", entry.getValue().toString())));
+        root.put("cooldowns", cooldowns);
+        root.put("dead", record.dead());
+        if (record.deathId() != null) {
+            root.put("death-id", record.deathId().toString());
+            root.put("died-at", record.diedAt().toString());
+        }
+        return yaml().dump(root);
+    }
+
+    static CharacterRecord decode(String input) {
+        Map<?, ?> root = object(yaml().load(input));
+        if (!number(root.get("schema-version")).equals(BigInteger.ONE)) {
+            throw new IllegalArgumentException("Unsupported character schema");
+        }
+        Map<?, ?> storedStats = object(root.get("stats"));
+        var stats = new EnumMap<Stat, BigInteger>(Stat.class);
+        for (var entry : storedStats.entrySet()) {
+            stats.put(Stat.valueOf(text(entry.getKey())), number(entry.getValue()));
+        }
+        List<String> learnedList = strings(root.get("learned-abilities"));
+        var learned = new LinkedHashSet<>(learnedList);
+        if (learned.size() != learnedList.size()) throw new IllegalArgumentException("Duplicate learned ability");
+        Map<String, Instant> cooldowns = new LinkedHashMap<>();
+        for (Object value : list(root.get("cooldowns"))) {
+            Map<?, ?> row = object(value);
+            if (cooldowns.putIfAbsent(text(row.get("ability")), instant(row.get("ready-at"))) != null) {
+                throw new IllegalArgumentException("Duplicate cooldown");
+            }
+        }
+        if (!(root.get("dead") instanceof Boolean dead)) throw new IllegalArgumentException("Missing dead flag");
+        return new CharacterRecord(UUID.fromString(text(root.get("character-id"))), text(root.get("name")),
+            number(root.get("revision")), stats, number(root.get("level")).intValueExact(),
+            number(root.get("experience")), number(root.get("unspent-points")),
+            new BigDecimal(text(root.get("health"))), learned, strings(root.get("loadout")), cooldowns,
+            dead, root.containsKey("death-id") ? UUID.fromString(text(root.get("death-id"))) : null,
+            root.containsKey("died-at") ? instant(root.get("died-at")) : null);
+    }
+
+    private static Map<?, ?> object(Object value) {
+        if (value instanceof Map<?, ?> map) return map;
+        throw new IllegalArgumentException("Expected YAML mapping");
+    }
+
+    private static List<?> list(Object value) {
+        if (value instanceof List<?> result) return result;
+        throw new IllegalArgumentException("Expected YAML list");
+    }
+
+    private static List<String> strings(Object value) {
+        return list(value).stream().map(CharacterYaml::text).toList();
+    }
+
+    private static String text(Object value) {
+        if (value instanceof String string) return string;
+        throw new IllegalArgumentException("Expected YAML string");
+    }
+
+    private static BigInteger number(Object value) {
+        if (value instanceof Integer || value instanceof Long || value instanceof BigInteger) {
+            return new BigInteger(value.toString());
+        }
+        return new BigInteger(text(value));
+    }
+
+    private static Instant instant(Object value) {
+        String string = text(value);
+        if (!string.endsWith("Z")) throw new IllegalArgumentException("Expected UTC timestamp");
+        return Instant.parse(string);
+    }
+}
@@ -0,0 +1,109 @@
+package games.dmg.fantasystick.persistence;
+
+import java.io.IOException;
+import java.math.BigInteger;
+import java.nio.ByteBuffer;
+import java.nio.channels.FileChannel;
+import java.nio.channels.OverlappingFileLockException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.StandardOpenOption;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.UUID;
+
+/** Blocking disk adapter: callers must use the persistence worker, never the server tick thread. */
+public final class YamlCharacterRepository {
+    private static final int MAX_FILE_BYTES = 1_048_576;
+    private final Path directory;
+    private final Replacement replacement;
+
+    @FunctionalInterface
+    interface Replacement { void move(Path source, Path target) throws IOException; }
+    @FunctionalInterface
+    private interface Operation { void run() throws IOException; }
+
+    public YamlCharacterRepository(Path pluginDataDirectory) {
+        this(pluginDataDirectory, (source, target) -> Files.move(source, target,
+            StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING));
+    }
+
+    YamlCharacterRepository(Path pluginDataDirectory, Replacement replacement) {
+        directory = pluginDataDirectory.resolve("characters").toAbsolutePath();
+        this.replacement = Objects.requireNonNull(replacement);
+    }
+
+    public void create(CharacterRecord character) throws IOException {
+        if (character.revision().signum() != 0) throw new IOException("New character revision must be zero");
+        withLock(character.id(), () -> {
+            if (Files.exists(file(character.id()), LinkOption.NOFOLLOW_LINKS)) {
+                throw new IOException("Character already exists: " + character.id());
+            }
+            write(character);
+        });
+    }
+
+    public void replace(CharacterRecord character, BigInteger expectedRevision) throws IOException {
+        if (!character.revision().equals(expectedRevision.add(BigInteger.ONE))) {
+            throw new IOException("Character update must advance exactly one revision");
+        }
+        withLock(character.id(), () -> {
+            CharacterRecord current = load(character.id()).orElseThrow(() -> new IOException("Character not found"));
+            if (!current.revision().equals(expectedRevision)) throw new IOException("Stale character revision");
+            write(character);
+        });
+    }
+
+    public Optional<CharacterRecord> load(UUID id) throws IOException {
+        Path file = file(id);
+        if (Files.notExists(file, LinkOption.NOFOLLOW_LINKS)) return Optional.empty();
+        try (var input = Files.newInputStream(file, StandardOpenOption.READ, LinkOption.NOFOLLOW_LINKS)) {
+            byte[] bytes = input.readNBytes(MAX_FILE_BYTES + 1);
+            if (bytes.length > MAX_FILE_BYTES) throw new IOException("Character YAML exceeds the safe file-size limit");
+            String text = StandardCharsets.UTF_8.newDecoder().decode(ByteBuffer.wrap(bytes)).toString();
+            CharacterRecord record = CharacterYaml.decode(text);
+            if (!record.id().equals(id)) throw new IllegalArgumentException("Character ID mismatch");
+            return Optional.of(record);
+        } catch (RuntimeException exception) {
+            // Parser diagnostics may contain user-controlled data; preserve the file, not its text in logs.
+            throw new IOException("Invalid character YAML for " + id);
+        }
+    }
+
+    private void write(CharacterRecord character) throws IOException {
+        byte[] bytes = CharacterYaml.encode(character).getBytes(StandardCharsets.UTF_8);
+        if (bytes.length > MAX_FILE_BYTES) throw new IOException("Character YAML exceeds the safe file-size limit");
+        Path temporary = Files.createTempFile(directory, ".character-", ".tmp");
+        try {
+            try (var output = FileChannel.open(temporary, StandardOpenOption.WRITE)) {
+                ByteBuffer buffer = ByteBuffer.wrap(bytes);
+                while (buffer.hasRemaining()) output.write(buffer);
+                output.force(true);
+            }
+            // Never fall back to an in-place, partially written character record.
+            replacement.move(temporary, file(character.id()));
+        } finally {
+            Files.deleteIfExists(temporary);
+        }
+    }
+
+    private void withLock(UUID id, Operation operation) throws IOException {
+        Files.createDirectories(directory);
+        Path lockPath = directory.resolve(id + ".lock");
+        try (var channel = FileChannel.open(lockPath, StandardOpenOption.CREATE, StandardOpenOption.WRITE,
+                LinkOption.NOFOLLOW_LINKS);
+             var lock = channel.tryLock()) {
+            if (lock == null) throw new IOException("Character record busy; retry the operation");
+            operation.run();
+        } catch (OverlappingFileLockException exception) {
+            throw new IOException("Character record busy; retry the operation");
+        }
+    }
+
+    private Path file(UUID id) {
+        return directory.resolve(Objects.requireNonNull(id) + ".yml");
+    }
+}
@@ -0,0 +1,117 @@
+package games.dmg.fantasystick;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import games.dmg.fantasystick.items.CharacterSheets;
+import games.dmg.fantasystick.persistence.CharacterRecord;
+import games.dmg.fantasystick.progression.Stat;
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.util.Collections;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import net.minecraft.nbt.NbtOps;
+import net.minecraft.resources.RegistryOps;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.craftbukkit.CraftRegistry;
+import org.bukkit.craftbukkit.inventory.CraftItemStack;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.RecipeChoice;
+import org.bukkit.persistence.PersistentDataType;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class CharacterSheetsNativeTest {
+    @BeforeAll static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
+
+    private static CharacterRecord character() {
+        var stats = new EnumMap<Stat, BigInteger>(Stat.class);
+        for (Stat stat : Stat.values()) stats.put(stat, BigInteger.ZERO);
+        return new CharacterRecord(UUID.randomUUID(), "Ari of Ash", BigInteger.ZERO, stats, 1,
+            BigInteger.ZERO, BigInteger.valueOf(40), BigDecimal.TEN, Set.of(), Collections.nCopies(7, ""),
+            Map.of(), false, null, null);
+    }
+
+    @Test
+    void presentationEditsPreserveIdentityButLookalikesAndMalformedReferencesAreRejected() {
+        var sheets = new CharacterSheets();
+        var record = character();
+        var sheet = sheets.create(record);
+        var meta = sheet.getItemMeta();
+        meta.displayName(Component.text("Different presentation"));
+        sheet.setItemMeta(meta);
+        assertEquals(record.id(), sheets.identify(sheet).orElseThrow());
+        var fake = new ItemStack(Material.PAPER);
+        var fakeMeta = fake.getItemMeta();
+        fakeMeta.displayName(meta.displayName());
+        fakeMeta.lore(meta.lore());
+        fake.setItemMeta(fakeMeta);
+        assertTrue(sheets.identify(fake).isEmpty());
+        assertTrue(sheets.identify(new ItemStack(Material.STICK)).isEmpty());
+        assertTrue(sheets.identify(null).isEmpty());
+        var version = new NamespacedKey("fantasystick", "sheet_version");
+        for (int variant = 0; variant < 3; variant++) {
+            var invalid = sheet.clone();
+            var invalidMeta = invalid.getItemMeta();
+            var data = invalidMeta.getPersistentDataContainer();
+            if (variant == 0) data.set(version, PersistentDataType.INTEGER, 2);
+            else if (variant == 1) data.set(version, PersistentDataType.STRING, "1");
+            else data.set(new NamespacedKey("fantasystick", "character_id"), PersistentDataType.STRING, "not-a-uuid");
+            invalid.setItemMeta(invalidMeta);
+            assertTrue(sheets.identify(invalid).isEmpty());
+        }
+    }
+
+    @Test
+    void fourIngredientShapelessRecipeOnlyExposesAnUnidentifiedPaperPreview() {
+        var sheets = new CharacterSheets();
+        var recipe = sheets.recipe();
+        assertEquals(new NamespacedKey("fantasystick", "character_sheet"), recipe.getKey());
+        assertEquals(4, recipe.getChoiceList().size());
+        assertTrue(recipe.getChoiceList().stream().allMatch(choice ->
+            choice instanceof RecipeChoice.MaterialChoice materials && materials.getChoices().size() == 1));
+        assertEquals(Set.of(Material.STICK, Material.PAPER, Material.FEATHER, Material.INK_SAC),
+            recipe.getChoiceList().stream().map(choice -> ((RecipeChoice.MaterialChoice) choice).getChoices().getFirst())
+                .collect(java.util.stream.Collectors.toSet()));
+        for (int i = 0; i < 10; i++) {
+            var preview = sheets.recipe().getResult();
+            assertEquals(Material.PAPER, preview.getType());
+            assertEquals(1, preview.getAmount());
+            assertTrue(sheets.identify(preview).isEmpty());
+            assertTrue(preview.getItemMeta().getPersistentDataContainer().isEmpty());
+        }
+    }
+
+    @Test
+    void aDeadRecordCannotBeTurnedIntoASheetByTheItemFactory() {
+        var original = character();
+        var dead = new CharacterRecord(original.id(), original.name(), original.revision(), original.stats(),
+            original.level(), original.experience(), original.unspentPoints(), BigDecimal.ZERO,
+            original.learned(), original.loadout(), original.cooldowns(), true, UUID.randomUUID(), java.time.Instant.EPOCH);
+        assertThrows(IllegalArgumentException.class, () -> new CharacterSheets().create(dead));
+    }
+
+    @Test
+    void sheetShowsSavedNameAndInstructionAndSerializesIdentityWithoutAnOwnerLock() {
+        var record = character();
+        var sheets = new CharacterSheets();
+        var sheet = sheets.create(record);
+        assertEquals(Material.PAPER, sheet.getType());
+        assertEquals(1, sheet.getAmount());
+        assertEquals(Component.text(record.name()), sheet.getItemMeta().displayName());
+        assertEquals(List.of(Component.text("Character sheet: place in off hand to enter fantasy world.")), sheet.getItemMeta().lore());
+        assertEquals(record.id(), sheets.identify(sheet).orElseThrow());
+        assertEquals(Set.of(new NamespacedKey("fantasystick", "sheet_version"), new NamespacedKey("fantasystick", "character_id")),
+            sheet.getItemMeta().getPersistentDataContainer().getKeys(), "No player owner, equipment or progress snapshot belongs on the sheet");
+        var ops = RegistryOps.create(NbtOps.INSTANCE, CraftRegistry.getMinecraftRegistry());
+        var encoded = net.minecraft.world.item.ItemStack.CODEC.encodeStart(ops, CraftItemStack.asNMSCopy(sheet)).getOrThrow();
+        var reloaded = CraftItemStack.asBukkitCopy(net.minecraft.world.item.ItemStack.CODEC.parse(ops, encoded).getOrThrow());
+        assertEquals(record.id(), new CharacterSheets().identify(reloaded).orElseThrow());
+        assertEquals(sheet, reloaded);
+    }
+}
@@ -0,0 +1,274 @@
+package games.dmg.fantasystick;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import games.dmg.fantasystick.items.EquipmentStorage;
+import java.util.Arrays;
+import java.util.UUID;
+import net.kyori.adventure.text.Component;
+import net.minecraft.core.NonNullList;
+import net.minecraft.core.component.DataComponents;
+import net.minecraft.nbt.NbtOps;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.world.entity.EntityEquipment;
+import net.minecraft.world.entity.player.Inventory;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
+import org.bukkit.block.ShulkerBox;
+import org.bukkit.craftbukkit.CraftRegistry;
+import org.bukkit.craftbukkit.inventory.CraftInventoryPlayer;
+import org.bukkit.craftbukkit.inventory.CraftItemStack;
+import org.bukkit.enchantments.Enchantment;
+import org.bukkit.inventory.InventoryHolder;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.BlockStateMeta;
+import org.bukkit.inventory.meta.Damageable;
+import org.bukkit.inventory.meta.BundleMeta;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class EquipmentStorageNativeTest {
+    @BeforeAll static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
+
+    private static CraftInventoryPlayer inventory() {
+        // Real native player slot/equipment storage. Only the absent network recipient is stubbed.
+        return new CraftInventoryPlayer(new Inventory(null, new EntityEquipment()) {
+            @Override public InventoryHolder getOwner() { return null; }
+        });
+    }
+
+    @Test
+    void malformedAmbiguousAndOccupiedRestorationPathsLeaveAllItemsUntouched() {
+        for (int variant = 0; variant < 6; variant++) {
+            var inventory = inventory();
+            var owner = UUID.randomUUID();
+            var session = UUID.randomUUID();
+            var storage = new EquipmentStorage();
+            inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+            assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+            var item = inventory.getItem(9);
+            var meta = item.getItemMeta();
+            var expected = EquipmentStorage.RestoreResult.INVALID_BOX;
+            switch (variant) {
+                case 0 -> {
+                    meta.getPersistentDataContainer().set(new NamespacedKey("fantasystick", "storage_version"), PersistentDataType.INTEGER, 2);
+                    item.setItemMeta(meta);
+                }
+                case 1 -> {
+                    meta.getPersistentDataContainer().set(new NamespacedKey("fantasystick", "storage_slots"), PersistentDataType.INTEGER_ARRAY, new int[]{35, 35});
+                    item.setItemMeta(meta);
+                }
+                case 2 -> {
+                    inventory.setItem(0, new ItemStack(Material.EMERALD));
+                    expected = EquipmentStorage.RestoreResult.OCCUPIED_SLOT;
+                }
+                case 3 -> {
+                    inventory.setItem(10, item.clone());
+                    expected = EquipmentStorage.RestoreResult.AMBIGUOUS;
+                }
+                case 4 -> item.setAmount(2);
+                case 5 -> {
+                    var impostor = new ItemStack(Material.SHULKER_BOX);
+                    var impostorMeta = impostor.getItemMeta();
+                    impostorMeta.displayName(Component.text("Fantasy Storage Box"));
+                    impostor.setItemMeta(impostorMeta);
+                    inventory.setItem(9, impostor);
+                    expected = EquipmentStorage.RestoreResult.NOT_FOUND;
+                }
+                default -> throw new AssertionError();
+            }
+            var before = snapshot(inventory);
+            assertEquals(expected, storage.restore(inventory, owner, session), "variant " + variant);
+            assertArrayEquals(before, inventory.getContents(), "variant " + variant);
+        }
+    }
+
+    @Test
+    void eligibilityMatchesTheActualVanillaShulkerSlotForEveryNativeItemMaterial() {
+        var nativeSlot = new net.minecraft.world.inventory.ShulkerBoxSlot(new net.minecraft.world.SimpleContainer(27), 0, 0, 0);
+        var storage = new EquipmentStorage();
+        for (Material material : Material.values()) {
+            if (material.isLegacy() || !material.isItem() || material.isAir()) continue;
+            var item = new ItemStack(material);
+            boolean allowed = nativeSlot.mayPlace(CraftItemStack.asNMSCopy(item));
+            var inventory = inventory();
+            inventory.setItem(0, item);
+            assertEquals(allowed ? EquipmentStorage.PackResult.PACKED : EquipmentStorage.PackResult.INELIGIBLE_EQUIPMENT,
+                storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()), material.name());
+        }
+    }
+
+    @Test
+    void rejectsOversizedStacksBeforeAnyEquipmentMoves() {
+        var inventory = inventory();
+        inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+        inventory.setItem(8, new ItemStack(Material.ARROW, 65));
+        var before = snapshot(inventory);
+        assertEquals(EquipmentStorage.PackResult.INELIGIBLE_EQUIPMENT,
+            new EquipmentStorage().pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        assertArrayEquals(before, inventory.getContents());
+    }
+
+    @Test
+    void fullMainInventoryRefusesUnchangedAndOnlyAMainSlotCountsAsSpace() {
+        var inventory = inventory();
+        for (int slot = 9; slot < 36; slot++) inventory.setItem(slot, new ItemStack(Material.STONE, 64));
+        inventory.setItem(0, new ItemStack(Material.DIAMOND, 12));
+        inventory.setItemInOffHand(new ItemStack(Material.PAPER));
+        var before = snapshot(inventory);
+        var storage = new EquipmentStorage();
+        assertEquals(EquipmentStorage.PackResult.NO_SPACE, storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        assertArrayEquals(before, inventory.getContents());
+        inventory.setItem(35, null);
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        assertEquals(Material.SHULKER_BOX, inventory.getItem(35).getType());
+    }
+
+    @Test
+    void refusesUnexpectedBoxContentsInsteadOfDeletingThemOnRestoration() {
+        var inventory = inventory();
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        var item = inventory.getItem(9);
+        var meta = (BlockStateMeta) item.getItemMeta();
+        var box = (ShulkerBox) meta.getBlockState();
+        box.getInventory().setItem(26, new ItemStack(Material.EMERALD, 64));
+        meta.setBlockState(box);
+        item.setItemMeta(meta);
+        var before = snapshot(inventory);
+        assertEquals(EquipmentStorage.RestoreResult.INVALID_BOX, storage.restore(inventory, owner, session));
+        assertArrayEquals(before, inventory.getContents());
+    }
+
+    @Test
+    void repeatedPackingAndWrongOwnerOrSessionCannotDuplicateOrRestoreEquipment() {
+        var inventory = inventory();
+        inventory.setItem(0, new ItemStack(Material.DIAMOND_SWORD));
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        var packed = snapshot(inventory);
+        assertEquals(EquipmentStorage.PackResult.ALREADY_PACKED, storage.pack(inventory, owner, session));
+        assertArrayEquals(packed, inventory.getContents());
+        assertEquals(EquipmentStorage.RestoreResult.NOT_FOUND, storage.restore(inventory, UUID.randomUUID(), session));
+        assertEquals(EquipmentStorage.RestoreResult.NOT_FOUND, storage.restore(inventory, owner, UUID.randomUUID()));
+        assertArrayEquals(packed, inventory.getContents());
+    }
+
+    @Test
+    void keepsNewHeadInTheFreedBoxSlotEvenWhenMainInventoryIsFull() {
+        var inventory = inventory();
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        var helmet = new ItemStack(Material.DIAMOND_HELMET);
+        var meta = (Damageable) helmet.getItemMeta();
+        meta.setDamage(93);
+        meta.addEnchant(Enchantment.PROTECTION, 4, true);
+        helmet.setItemMeta(meta);
+        inventory.setHelmet(helmet);
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        for (int slot = 10; slot < 36; slot++) inventory.setItem(slot, new ItemStack(Material.COBBLESTONE, 64));
+        var pumpkin = new ItemStack(Material.CARVED_PUMPKIN);
+        inventory.setHelmet(pumpkin);
+        assertEquals(EquipmentStorage.RestoreResult.RESTORED, storage.restore(inventory, owner, session));
+        assertEquals(helmet, inventory.getHelmet(), "Existing damage and protection are not repaired or discarded");
+        assertEquals(pumpkin, inventory.getItem(9));
+        for (int slot = 10; slot < 36; slot++) assertEquals(new ItemStack(Material.COBBLESTONE, 64), inventory.getItem(slot));
+    }
+
+    @Test
+    void nativeSerializedContentsNeedNoPluginAndRestoreAfterTheBoxMoves() {
+        var inventory = inventory();
+        var owner = UUID.randomUUID();
+        var session = UUID.randomUUID();
+        var storage = new EquipmentStorage();
+        for (int slot = 0; slot < 9; slot++) inventory.setItem(slot, new ItemStack(Material.ARROW, slot + 1));
+        var nested = new ItemStack(Material.BUNDLE);
+        var bundle = (BundleMeta) nested.getItemMeta();
+        bundle.addItem(new ItemStack(Material.EMERALD, 12));
+        nested.setItemMeta(bundle);
+        inventory.setItem(3, nested);
+        inventory.setHelmet(new ItemStack(Material.DIAMOND_HELMET));
+        inventory.setLeggings(new ItemStack(Material.IRON_LEGGINGS));
+        inventory.setChestplate(new ItemStack(Material.ELYTRA));
+        inventory.setBoots(new ItemStack(Material.GOLDEN_BOOTS));
+        var before = snapshot(inventory);
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, owner, session));
+        var ops = RegistryOps.create(NbtOps.INSTANCE, CraftRegistry.getMinecraftRegistry());
+        var encoded = net.minecraft.world.item.ItemStack.CODEC.encodeStart(ops,
+            CraftItemStack.asNMSCopy(inventory.getItem(9))).getOrThrow();
+        var decoded = net.minecraft.world.item.ItemStack.CODEC.parse(ops, encoded).getOrThrow();
+        // Minecraft's native container component, not a Fantasy Stick reconstruction receipt.
+        var contents = NonNullList.withSize(27, net.minecraft.world.item.ItemStack.EMPTY);
+        assertNotNull(decoded.get(DataComponents.CONTAINER));
+        decoded.get(DataComponents.CONTAINER).copyInto(contents);
+        assertTrue(net.minecraft.world.item.ItemStack.matches(CraftItemStack.asNMSCopy(nested), contents.get(3)));
+        assertTrue(net.minecraft.world.item.ItemStack.matches(CraftItemStack.asNMSCopy(before[36]), contents.get(9)));
+        assertTrue(net.minecraft.world.item.ItemStack.matches(CraftItemStack.asNMSCopy(before[39]), contents.get(12)));
+        inventory.setItem(9, null);
+        inventory.setItem(35, CraftItemStack.asBukkitCopy(decoded));
+        assertEquals(EquipmentStorage.RestoreResult.RESTORED, storage.restore(inventory, owner, session));
+        assertArrayEquals(before, inventory.getContents());
+        assertEquals(EquipmentStorage.RestoreResult.NOT_FOUND, storage.restore(inventory, owner, session));
+        assertArrayEquals(before, inventory.getContents());
+    }
+
+    @Test
+    void refusesEveryShulkerColorInPackedSlotsWithoutAnyPartialMutation() {
+        for (Material material : Material.values()) {
+            if (!material.name().endsWith("SHULKER_BOX") || material.isLegacy()) continue;
+            for (int slot : new int[]{0, 8, 36, 39}) {
+                var inventory = inventory();
+                inventory.setItem(1, new ItemStack(Material.DIAMOND, 12));
+                inventory.setItem(slot, new ItemStack(material));
+                var before = snapshot(inventory);
+                assertEquals(EquipmentStorage.PackResult.INELIGIBLE_EQUIPMENT,
+                    new EquipmentStorage().pack(inventory, UUID.randomUUID(), UUID.randomUUID()), material + " slot " + slot);
+                assertArrayEquals(before, inventory.getContents());
+            }
+        }
+    }
+
+    private static ItemStack[] snapshot(CraftInventoryPlayer inventory) {
+        return Arrays.stream(inventory.getContents()).map(item -> item == null ? null : item.clone()).toArray(ItemStack[]::new);
+    }
+
+    @Test
+    void movesActualHotbarAndArmorIntoOneNativeShulkerWithoutTouchingMainItemsOrSheet() {
+        var inventory = inventory();
+        var sword = new ItemStack(Material.DIAMOND_SWORD);
+        var meta = (Damageable) sword.getItemMeta();
+        meta.setDamage(137);
+        meta.displayName(Component.text("Old sword"));
+        sword.setItemMeta(meta);
+        var arrows = new ItemStack(Material.ARROW, 47);
+        var boots = new ItemStack(Material.DIAMOND_BOOTS);
+        inventory.setItem(0, sword);
+        inventory.setItem(8, arrows);
+        inventory.setBoots(boots);
+        var unrelated = new ItemStack(Material.RED_SHULKER_BOX);
+        var sheet = new ItemStack(Material.PAPER);
+        inventory.setItem(9, unrelated);
+        inventory.setItemInOffHand(sheet);
+        var storage = new EquipmentStorage();
+        assertEquals(EquipmentStorage.PackResult.PACKED, storage.pack(inventory, UUID.randomUUID(), UUID.randomUUID()));
+        for (int i = 0; i < 9; i++) assertNull(inventory.getItem(i));
+        assertTrue(inventory.getBoots().isEmpty());
+        assertEquals(unrelated, inventory.getItem(9));
+        assertEquals(sheet, inventory.getItemInOffHand());
+        var boxItem = inventory.getItem(10);
+        assertNotNull(boxItem);
+        assertEquals(Material.SHULKER_BOX, boxItem.getType());
+        assertEquals(Component.text("Fantasy Storage Box"), boxItem.getItemMeta().displayName());
+        var box = (ShulkerBox) ((BlockStateMeta) boxItem.getItemMeta()).getBlockState();
+        assertEquals(sword, box.getInventory().getItem(0));
+        assertEquals(arrows, box.getInventory().getItem(8));
+        assertEquals(boots, box.getInventory().getItem(9));
+    }
+}
@@ -0,0 +1,60 @@
+package games.dmg.fantasystick;
+
+import java.util.List;
+import java.util.stream.Stream;
+import net.minecraft.SharedConstants;
+import net.minecraft.commands.Commands;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.LayeredRegistryAccess;
+import net.minecraft.core.Registry;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.RegistryDataLoader;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.RegistryLayer;
+import net.minecraft.server.ReloadableServerResources;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.server.permissions.LevelBasedPermissionSet;
+import net.minecraft.tags.TagLoader;
+import net.minecraft.util.Util;
+import net.minecraft.world.flag.FeatureFlags;
+import net.minecraft.world.level.DataPackConfig;
+import net.minecraft.world.level.WorldDataConfiguration;
+import org.bukkit.craftbukkit.CraftRegistry;
+
+/** Vanilla registry/tag/component bootstrap, shared in approach with the other Purpur native suites. */
+final class NativeRuntime {
+    private NativeRuntime() { }
+    private static boolean ready;
+    static synchronized void bootstrap() throws Exception {
+        if (ready) { return; }
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        var flags = FeatureFlags.VANILLA_SET;
+        var packs = ServerPacksSource.createVanillaTrustedRepository();
+        MinecraftServer.configurePackRepository(packs, new WorldDataConfiguration(new DataPackConfig(
+                FeatureFlags.REGISTRY.toNames(flags).stream().map(Identifier::getPath).toList(), List.of()), flags), true, false);
+        try (var resources = new MultiPackResourceManager(PackType.SERVER_DATA, packs.openAllSelected())) {
+            LayeredRegistryAccess<RegistryLayer> layers = RegistryLayer.createRegistryAccess();
+            List<Registry.PendingTags<?>> tags = TagLoader.loadTagsForExistingRegistries(resources, layers.getLayer(RegistryLayer.STATIC));
+            List<HolderLookup.RegistryLookup<?>> lookups = TagLoader.buildUpdatedLookups(layers.getAccessForLoading(RegistryLayer.WORLDGEN), tags);
+            RegistryAccess.Frozen worldgen = RegistryDataLoader.load(resources, lookups,
+                    RegistryDataLoader.WORLDGEN_REGISTRIES, Util.backgroundExecutor()).join();
+            layers = layers.replaceFrom(RegistryLayer.WORLDGEN, worldgen);
+            RegistryAccess.Frozen dimensions = RegistryDataLoader.load(resources,
+                    Stream.concat(lookups.stream(), worldgen.listRegistries()).toList(),
+                    RegistryDataLoader.DIMENSION_REGISTRIES, Util.backgroundExecutor()).join();
+            layers = layers.replaceFrom(RegistryLayer.DIMENSIONS, dimensions);
+            Class.forName("org.bukkit.Registry"); // Initialize the fixed API registry before loading data packs.
+            var datapack = ReloadableServerResources.loadResources(resources, layers, tags, flags,
+                    Commands.CommandSelection.DEDICATED, LevelBasedPermissionSet.ALL_PERMISSIONS,
+                    Util.backgroundExecutor(), Runnable::run).join();
+            datapack.updateComponentsAndStaticRegistryTags();
+            CraftRegistry.setMinecraftRegistry(layers.compositeAccess().freeze());
+        }
+        ready = true;
+    }
+}
@@ -0,0 +1,101 @@
+package games.dmg.fantasystick;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import games.dmg.fantasystick.items.TailBooks;
+import games.dmg.fantasystick.persistence.CharacterRecord;
+import games.dmg.fantasystick.progression.Stat;
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.time.Instant;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import net.minecraft.core.component.DataComponents;
+import net.minecraft.nbt.NbtOps;
+import net.minecraft.resources.RegistryOps;
+import net.kyori.adventure.text.Component;
+import org.bukkit.Material;
+import org.bukkit.NamespacedKey;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.meta.BookMeta;
+import org.bukkit.persistence.PersistentDataType;
+import org.bukkit.craftbukkit.CraftRegistry;
+import org.bukkit.craftbukkit.inventory.CraftItemStack;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class TailBooksNativeTest {
+    @BeforeAll static void bootstrap() throws Exception { NativeRuntime.bootstrap(); }
+
+    private static CharacterRecord fallen() {
+        var stats = new EnumMap<Stat, BigInteger>(Stat.class);
+        for (Stat stat : Stat.values()) stats.put(stat, BigInteger.ZERO);
+        stats.put(Stat.CON, BigInteger.TEN);
+        return new CharacterRecord(UUID.randomUUID(), "Ari", BigInteger.ONE, stats, 2,
+            BigInteger.valueOf(100), BigInteger.valueOf(30), BigDecimal.ZERO,
+            Set.of("second_wind"), List.of("second_wind", "", "", "", "", "", ""),
+            Map.of(), true, UUID.randomUUID(), Instant.parse("2026-09-17T00:00:00Z"));
+    }
+
+    @Test
+    void respectsTheVanillaTitleLimitWithoutLosingTheFullCharacterName() {
+        var original = fallen();
+        String name = "A".repeat(23) + "\uD83D\uDD25" + "Long Character Name";
+        var saved = new CharacterRecord(original.id(), name, original.revision(), original.stats(), original.level(),
+            original.experience(), original.unspentPoints(), original.health(), original.learned(),
+            original.loadout(), original.cooldowns(), true, original.deathId(), original.diedAt());
+        var book = new TailBooks().create(saved);
+        var meta = (BookMeta) book.getItemMeta();
+        assertNotNull(meta.getTitle(), "A long character name must not leave an unsigned/missing book title");
+        assertFalse(meta.getTitle().isEmpty(), "The native title setter must not silently reject a long name");
+        assertTrue(meta.getTitle().length() <= 32);
+        assertFalse(Character.isHighSurrogate(meta.getTitle().charAt(meta.getTitle().length() - 1)));
+        assertEquals(Component.text("Tail of " + name), meta.displayName());
+        assertTrue(meta.pages().contains(Component.text("Tail of " + name)));
+    }
+
+    @Test
+    void identityComesOnlyFromTypedMetadataNotEditablePagesOrANameOnlyLookalike() {
+        var saved = fallen();
+        var books = new TailBooks();
+        var book = books.create(saved);
+        var identity = books.identify(book).orElseThrow();
+        var meta = (BookMeta) book.getItemMeta();
+        meta.setTitle("Fake progression");
+        meta.displayName(Component.text("Changed name"));
+        meta.pages(List.of(Component.text("Level: 999999")));
+        book.setItemMeta(meta);
+        assertEquals(identity, books.identify(book).orElseThrow());
+        assertTrue(books.identify(new ItemStack(Material.WRITTEN_BOOK)).isEmpty());
+        assertTrue(books.identify(new ItemStack(Material.WRITABLE_BOOK)).isEmpty());
+        meta.getPersistentDataContainer().set(new NamespacedKey("fantasystick", "death_id"), PersistentDataType.STRING, "not-a-uuid");
+        book.setItemMeta(meta);
+        assertTrue(books.identify(book).isEmpty());
+    }
+
+    @Test
+    void vanillaWrittenBookContentSurvivesNativeSerializationWithoutLoadingAPluginOrYaml() {
+        var saved = fallen();
+        var books = new TailBooks();
+        var book = books.create(saved);
+        assertEquals(Material.WRITTEN_BOOK, book.getType(), "Tail must be a signed vanilla book, not a writable book or paper");
+        var ops = RegistryOps.create(NbtOps.INSTANCE, CraftRegistry.getMinecraftRegistry());
+        var encoded = net.minecraft.world.item.ItemStack.CODEC.encodeStart(ops, CraftItemStack.asNMSCopy(book)).getOrThrow();
+        // Read using Minecraft's codec/components only; no Fantasy Stick lookup or plugin instance.
+        var restored = net.minecraft.world.item.ItemStack.CODEC.parse(ops, encoded).getOrThrow();
+        var content = restored.get(DataComponents.WRITTEN_BOOK_CONTENT);
+        assertNotNull(content);
+        assertEquals("Tail of Ari", content.title().raw());
+        assertEquals("Fantasy Stick", content.author());
+        String pages = content.pages().stream().map(page -> page.raw().getString()).reduce("", (a, b) -> a + "\n" + b);
+        assertTrue(pages.contains("Ari"));
+        assertTrue(pages.contains("Level: 2"));
+        assertTrue(pages.contains("XP: 100"));
+        assertTrue(pages.contains("CON: 10"));
+        assertTrue(pages.contains("second_wind"));
+        assertEquals(new TailBooks.Identity(saved.id(), saved.deathId()), books.identify(CraftItemStack.asBukkitCopy(restored)).orElseThrow());
+    }
+}
@@ -0,0 +1,191 @@
+package games.dmg.fantasystick.persistence;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.IOException;
+import java.math.BigInteger;
+import java.nio.file.Files;
+import java.nio.file.StandardCopyOption;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.nio.file.Path;
+import java.time.Clock;
+import java.time.ZoneOffset;
+import java.util.UUID;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class CharacterStorageTest {
+    @TempDir Path data;
+
+    @Test
+    void performsFileWritesOffTheCallerThreadAndAcknowledgesOnlyAfterCommit() throws Exception {
+        Thread caller = Thread.currentThread();
+        var entered = new CountDownLatch(1);
+        var allowCommit = new CountDownLatch(1);
+        var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data, (source, target) -> {
+            assertNotSame(caller, Thread.currentThread());
+            entered.countDown();
+            try {
+                if (!allowCommit.await(5, TimeUnit.SECONDS)) throw new IOException("Test gate timed out");
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+                throw new IOException("Interrupted", exception);
+            }
+            Files.move(source, target, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);
+        });
+        try (var storage = new CharacterStorage(repository, Clock.systemUTC())) {
+            var pending = storage.create(saved);
+            try {
+                assertTrue(entered.await(5, TimeUnit.SECONDS));
+                assertFalse(pending.isDone(), "No success acknowledgment before the file commit");
+            } finally {
+                allowCommit.countDown();
+            }
+            pending.join();
+            assertEquals(saved, storage.find(saved.id()).join().orElseThrow());
+        }
+    }
+
+    @Test
+    void failedRevivalSaveLeavesDeadStateRetryableAndShutdownRejectsNewWork() throws Exception {
+        var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(saved);
+        var failing = new YamlCharacterRepository(data, (source, target) -> { throw new IOException("Simulated failure"); });
+        try (var storage = new CharacterStorage(failing, Clock.fixed(saved.diedAt().plusSeconds(60), ZoneOffset.UTC))) {
+            assertThrows(CompletionException.class, () -> storage.restoreDeathRecord(saved.id(), saved.deathId()).join());
+            assertEquals(saved, repository.load(saved.id()).orElseThrow());
+        }
+        var retry = new CharacterStorage(repository, Clock.fixed(saved.diedAt().plusSeconds(60), ZoneOffset.UTC));
+        assertTrue(retry.restoreDeathRecord(saved.id(), saved.deathId()).join().isPresent());
+        retry.close();
+        assertThrows(CompletionException.class, () -> retry.find(saved.id()).join());
+    }
+
+    @Test
+    void concurrentRequestsAndAReopenedStoreCannotRestoreTheSameDeathTwice() throws Exception {
+        var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(saved);
+        var clock = Clock.fixed(saved.diedAt().plusSeconds(60), ZoneOffset.UTC);
+        try (var storage = new CharacterStorage(repository, clock)) {
+            var first = storage.restoreDeathRecord(saved.id(), saved.deathId());
+            var second = storage.restoreDeathRecord(saved.id(), saved.deathId());
+            assertTrue(first.join().isPresent());
+            assertTrue(second.join().isEmpty());
+        }
+        try (var reopened = new CharacterStorage(new YamlCharacterRepository(data), clock)) {
+            assertTrue(reopened.restoreDeathRecord(saved.id(), saved.deathId()).join().isEmpty());
+        }
+    }
+
+    @Test
+    void aLaterDeathDoesNotMakeThePreviousBookEligibleAgain() throws Exception {
+        var original = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(original);
+        var clock = Clock.fixed(original.diedAt().plusSeconds(60), ZoneOffset.UTC);
+        try (var storage = new CharacterStorage(repository, clock)) {
+            var alive = storage.restoreDeathRecord(original.id(), original.deathId()).join().orElseThrow();
+            var later = new CharacterRecord(alive.id(), "Saved current name", alive.revision().add(BigInteger.ONE),
+                alive.stats(), alive.level(), alive.experience(), alive.unspentPoints(), java.math.BigDecimal.ZERO,
+                alive.learned(), alive.loadout(), alive.cooldowns(), true, UUID.randomUUID(), original.diedAt().plusSeconds(30));
+            repository.replace(later, alive.revision());
+            assertTrue(storage.restoreDeathRecord(original.id(), original.deathId()).join().isEmpty());
+            var restored = storage.restoreDeathRecord(later.id(), later.deathId()).join().orElseThrow();
+            assertEquals("Saved current name", restored.name(), "Use saved state, not the old book's snapshot");
+            assertFalse(restored.dead());
+        }
+    }
+
+    @Test
+    void recordsEachDeathOnceWithANewIdentityAndNeverReplaysAnOldDefeat() throws Exception {
+        var template = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var live = new CharacterRecord(template.id(), template.name(), BigInteger.ZERO, template.stats(),
+            template.level(), template.experience(), template.unspentPoints(), template.maximumHealth(),
+            template.learned(), template.loadout(), template.cooldowns(), false, null, null);
+        var now = template.diedAt().plusSeconds(60);
+        var repository = new YamlCharacterRepository(data);
+        try (var storage = new CharacterStorage(repository, Clock.fixed(now, ZoneOffset.UTC))) {
+            storage.create(live).join();
+            var first = storage.recordDeath(live.id(), live.revision()).join();
+            assertTrue(first.isPresent(), "Death must persist the dead flag and current death identity");
+            var dead = first.orElseThrow();
+            assertTrue(dead.dead());
+            assertEquals(java.math.BigDecimal.ZERO, dead.health());
+            assertNotNull(dead.deathId());
+            assertEquals(now, dead.diedAt());
+            assertTrue(storage.recordDeath(live.id(), live.revision()).join().isEmpty());
+            assertEquals(dead, storage.find(live.id()).join().orElseThrow());
+            var revived = storage.restoreDeathRecord(live.id(), dead.deathId()).join().orElseThrow();
+            assertTrue(storage.recordDeath(live.id(), live.revision()).join().isEmpty(), "An old callback cannot kill a revived life");
+            var later = storage.recordDeath(live.id(), revived.revision()).join().orElseThrow();
+            assertNotEquals(dead.deathId(), later.deathId());
+            assertTrue(storage.restoreDeathRecord(live.id(), dead.deathId()).join().isEmpty());
+            assertTrue(storage.restoreDeathRecord(live.id(), later.deathId()).join().isPresent());
+        }
+    }
+
+    @Test
+    void refusesAnOldOrUnknownDeathBookWithoutChangingTheSavedCharacter() throws Exception {
+        var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(saved);
+        try (var storage = new CharacterStorage(repository, Clock.fixed(saved.diedAt().plusSeconds(60), ZoneOffset.UTC))) {
+            assertTrue(storage.restoreDeathRecord(saved.id(), UUID.randomUUID()).join().isEmpty());
+            assertTrue(storage.restoreDeathRecord(UUID.randomUUID(), saved.deathId()).join().isEmpty());
+            assertEquals(saved, repository.load(saved.id()).orElseThrow());
+        }
+    }
+
+    @Test
+    void requiresDeathAgeStrictlyBelowTwentyFourHoursAndNotInTheFuture() throws Exception {
+        for (long seconds : new long[] {-1, 86400, 86401}) {
+            var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+            var repository = new YamlCharacterRepository(data);
+            repository.create(saved);
+            try (var storage = new CharacterStorage(repository, Clock.fixed(saved.diedAt().plusSeconds(seconds), ZoneOffset.UTC))) {
+                assertTrue(storage.restoreDeathRecord(saved.id(), saved.deathId()).join().isEmpty());
+                assertEquals(saved, repository.load(saved.id()).orElseThrow());
+            }
+        }
+        var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(saved);
+        try (var storage = new CharacterStorage(repository,
+                Clock.fixed(saved.diedAt().plusSeconds(86400).minusNanos(1), ZoneOffset.UTC))) {
+            assertTrue(storage.restoreDeathRecord(saved.id(), saved.deathId()).join().isPresent());
+        }
+    }
+
+    @Test
+    void restoresOnlyFromTheSavedDeadCharacterAndPreservesProgressAndCooldowns() throws Exception {
+        var saved = YamlCharacterRepositoryTest.sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(saved);
+        try (var storage = new CharacterStorage(repository, Clock.fixed(saved.diedAt().plusSeconds(60), ZoneOffset.UTC))) {
+            var result = storage.restoreDeathRecord(saved.id(), saved.deathId()).join();
+            assertTrue(result.isPresent(), "A current, recently dead saved character must be restored");
+            var restored = result.orElseThrow();
+            assertFalse(restored.dead());
+            assertEquals(saved.maximumHealth(), restored.health());
+            assertEquals(saved.id(), restored.id());
+            assertEquals(saved.name(), restored.name());
+            assertEquals(saved.stats(), restored.stats());
+            assertEquals(saved.level(), restored.level());
+            assertEquals(saved.experience(), restored.experience());
+            assertEquals(saved.unspentPoints(), restored.unspentPoints());
+            assertEquals(saved.learned(), restored.learned());
+            assertEquals(saved.loadout(), restored.loadout());
+            assertEquals(saved.cooldowns(), restored.cooldowns());
+            assertEquals(saved.deathId(), restored.deathId());
+            assertEquals(saved.diedAt(), restored.diedAt());
+            assertEquals(saved.revision().add(BigInteger.ONE), restored.revision());
+            assertEquals(restored, new YamlCharacterRepository(data).load(saved.id()).orElseThrow());
+            assertTrue(storage.restoreDeathRecord(saved.id(), saved.deathId()).join().isEmpty());
+        }
+    }
+}
@@ -0,0 +1,178 @@
+package games.dmg.fantasystick.persistence;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import games.dmg.fantasystick.progression.Stat;
+import java.io.IOException;
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Instant;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.Collections;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Executors;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+class YamlCharacterRepositoryTest {
+    @TempDir Path data;
+    private static final Instant DEATH = Instant.parse("2026-09-17T00:00:00Z"); // synthetic test clock
+
+    static CharacterRecord sample(UUID id) {
+        var stats = new EnumMap<Stat, BigInteger>(Stat.class);
+        for (Stat stat : Stat.values()) stats.put(stat, BigInteger.ZERO);
+        stats.put(Stat.STR, BigInteger.TEN.pow(100));
+        stats.put(Stat.CON, BigInteger.valueOf(6));
+        return new CharacterRecord(id, "Ari 'Ash' ☃", BigInteger.ZERO, stats, 7,
+            BigInteger.valueOf(600), BigInteger.TEN.pow(99), BigDecimal.ZERO,
+            Set.of("fireball", "revive", "future.unknown"),
+            List.of("fireball", "", "", "future.unknown", "revive", "", ""),
+            Map.of("revive", DEATH.plusSeconds(86400), "unlearned.ability", DEATH.plusSeconds(60)),
+            true, UUID.randomUUID(), DEATH);
+    }
+
+    static CharacterRecord rename(CharacterRecord original, String name, BigInteger revision) {
+        return new CharacterRecord(original.id(), name, revision, original.stats(), original.level(),
+            original.experience(), original.unspentPoints(), original.health(), original.learned(),
+            original.loadout(), original.cooldowns(), original.dead(), original.deathId(), original.diedAt());
+    }
+
+    @Test
+    void updatesExactlyTheExpectedRevisionAndNeverOverwritesWithAStaleCopy() throws Exception {
+        var repository = new YamlCharacterRepository(data);
+        var original = sample(UUID.randomUUID());
+        repository.create(original);
+        var updated = rename(original, "New name", BigInteger.ONE);
+        repository.replace(updated, BigInteger.ZERO);
+        assertEquals(updated, repository.load(original.id()).orElseThrow());
+        assertThrows(IOException.class, () -> repository.replace(rename(original, "Stale name", BigInteger.ONE), BigInteger.ZERO));
+        assertThrows(IOException.class, () -> repository.create(original));
+        assertEquals(updated, repository.load(original.id()).orElseThrow());
+    }
+
+    @Test
+    void failedAtomicReplacementKeepsOriginalStateAndCleansTemporaryData() throws Exception {
+        var original = sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(original);
+        var failing = new YamlCharacterRepository(data, (temporary, target) -> {
+            assertTrue(Files.isRegularFile(temporary));
+            assertEquals(original, repository.load(original.id()).orElseThrow());
+            throw new IOException("Simulated atomic-move failure");
+        });
+        assertThrows(IOException.class,
+            () -> failing.replace(rename(original, "Unsaved", BigInteger.ONE), BigInteger.ZERO));
+        assertEquals(original, repository.load(original.id()).orElseThrow());
+        try (var paths = Files.list(data.resolve("characters"))) {
+            assertFalse(paths.anyMatch(path -> path.getFileName().toString().endsWith(".tmp")));
+        }
+        // A normal retry succeeds; there is no persistent administrator-unlock flag.
+        repository.replace(rename(original, "Retry", BigInteger.ONE), BigInteger.ZERO);
+        assertEquals("Retry", repository.load(original.id()).orElseThrow().name());
+    }
+
+    @Test
+    void separateRepositoryInstancesCannotCommitTheSameRevisionTwice() throws Exception {
+        var original = sample(UUID.randomUUID());
+        new YamlCharacterRepository(data).create(original);
+        Callable<Boolean> change = () -> {
+            try {
+                new YamlCharacterRepository(data).replace(rename(original, "Winner", BigInteger.ONE), BigInteger.ZERO);
+                return true;
+            } catch (IOException conflict) {
+                return false;
+            }
+        };
+        try (var pool = Executors.newVirtualThreadPerTaskExecutor()) {
+            int successes = 0;
+            for (var future : pool.invokeAll(Collections.nCopies(8, change))) if (future.get()) successes++;
+            assertEquals(1, successes);
+        }
+        assertEquals(BigInteger.ONE, new YamlCharacterRepository(data).load(original.id()).orElseThrow().revision());
+    }
+
+    @Test
+    void preservesExactDecimalHealthWithoutExpandingHugeScalesOnSave() throws Exception {
+        var template = sample(UUID.randomUUID());
+        var tiny = new CharacterRecord(template.id(), template.name(), template.revision(), template.stats(),
+            template.level(), template.experience(), template.unspentPoints(), new BigDecimal("1E-10000"),
+            template.learned(), template.loadout(), template.cooldowns(), template.dead(), template.deathId(), template.diedAt());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(tiny);
+        assertTrue(Files.size(data.resolve("characters").resolve(tiny.id() + ".yml")) < 4096,
+            "Persist decimal notation without allocating thousands of padding zeros");
+        assertEquals(tiny, repository.load(tiny.id()).orElseThrow());
+    }
+
+    @Test
+    void boundsFileReadsAndWritesWithoutReplacingExistingData() throws Exception {
+        var original = sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(original);
+        Path file = data.resolve("characters").resolve(original.id() + ".yml");
+        byte[] before = Files.readAllBytes(file);
+        String oversized = "x".repeat(1_048_577);
+        assertThrows(IOException.class,
+            () -> repository.replace(rename(original, oversized, BigInteger.ONE), BigInteger.ZERO));
+        assertArrayEquals(before, Files.readAllBytes(file));
+        Files.writeString(file, oversized);
+        assertThrows(IOException.class, () -> repository.load(original.id()));
+        assertEquals(oversized.length(), Files.size(file));
+    }
+
+    @Test
+    void rejectsInvalidCharacterDataWithoutChangingTheOriginalFile() throws Exception {
+        var character = sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(character);
+        Path file = data.resolve("characters").resolve(character.id() + ".yml");
+        String valid = Files.readString(file);
+        for (String invalid : List.of(
+                valid.replaceAll("(?m)^revision:.*$", "revision: '-1'"),
+                valid.replaceAll("(?m)^health:.*$", "health: '17'"),
+                valid.replaceAll("(?m)^level:.*$", "level: 0"),
+                valid.replaceAll("(?m)^death-id:.*\\R", ""),
+                valid.replaceAll("(?m)^died-at:.*\\R", ""),
+                valid.replace("schema-version: 1", "schema-version: 2"),
+                valid.replace("dead: true", "dead: true\ndead: false"),
+                valid.replace(character.id().toString(), UUID.randomUUID().toString()),
+                "!!java.net.URL ['https://invalid.example/']")) {
+            Files.writeString(file, invalid);
+            IOException error = assertThrows(IOException.class, () -> repository.load(character.id()));
+            assertEquals("Invalid character YAML for " + character.id(), error.getMessage());
+            assertEquals(invalid, Files.readString(file));
+        }
+    }
+
+    @Test
+    void rejectsSymlinkedRecordsInsteadOfReadingOutsideTheCharacterDirectory() throws Exception {
+        var character = sample(UUID.randomUUID());
+        Files.createDirectories(data.resolve("characters"));
+        Path other = data.resolve("outside.yml");
+        Files.writeString(other, CharacterYaml.encode(character));
+        Files.createSymbolicLink(data.resolve("characters").resolve(character.id() + ".yml"), other);
+        assertThrows(IOException.class, () -> new YamlCharacterRepository(data).load(character.id()));
+    }
+
+    @Test
+    void storesACompleteVersionedCharacterYamlAndReloadsItWithoutItemOrHolderState() throws Exception {
+        CharacterRecord character = sample(UUID.randomUUID());
+        var repository = new YamlCharacterRepository(data);
+        repository.create(character);
+        Path file = data.resolve("characters").resolve(character.id() + ".yml");
+        assertTrue(Files.isRegularFile(file), "Create must persist character YAML in the plugin data directory");
+        String yaml = Files.readString(file);
+        assertTrue(yaml.contains("schema-version: 1"));
+        assertTrue(yaml.contains("dead: true"));
+        assertTrue(yaml.contains("2026-09-17T00:00:00Z"));
+        assertFalse(yaml.contains("!!"), "Use plain YAML data, never Java object tags");
+        assertEquals(character, new YamlCharacterRepository(data).load(character.id()).orElseThrow());
+        assertTrue(repository.load(UUID.randomUUID()).isEmpty());
+    }
+}
Author	SHA1	Message	Date
dmg	272acfde11	feat(characters): add native sheets and safe recipe previews Release / release (push) Successful in 4m48s Details CI / build (push) Successful in 3m13s Details	2026-09-17 20:57:55 -04:00
dmg	c215dc1990	feat(equipment): pack and restore native shulker contents Release / release (push) Successful in 4m40s Details CI / build (push) Successful in 2m28s Details	2026-09-17 20:33:18 -04:00
dmg	b35cac3d1c	feat(persistence): save characters and create signed Tail books Release / release (push) Successful in 7m21s Details CI / build (push) Successful in 2m36s Details	2026-09-17 08:23:52 -04:00