Add production-ready Graveyard death recovery

docs/features/README.md

@@ -53,6 +53,7 @@ This directory documents all **58** feature modules currently present in ServerF
 - [DurabilityAlert](durabilityalert.md) — Warns players when equipped or used items cross configured durability thresholds.
 - [VillagerOptimizer](villageroptimizer.md) — Reduces villager processing cost by applying configurable optimization rules without changing intended gameplay more than necessary.
 - [WorldEditVisualizer](worldeditvisualizer.md) — Visualizes WorldEdit selections for authorized builders with temporary particles or display markers.
+- [Graveyard](graveyard.md) — Stores death contents durably and renders claimable packet-only graves with active-server-time expiry and crash recovery.
 
 ## Moderation and administration
 

pom.xml

@@ -62,7 +62,7 @@
     </modules>
 
     <properties>
-        <revision>3.1.7</revision>
+        <revision>3.1.8</revision>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <project.build.outputTimestamp>2026-07-26T00:00:00Z</project.build.outputTimestamp>

serverfeatures-api/src/main/java/nl/hauntedmc/serverfeatures/api/graveyard/ClaimReason.java

@@ -0,0 +1,12 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+/**
+ * Why a grave claim was initiated.
+ */
+public enum ClaimReason {
+    PHYSICAL_INTERACTION,
+    REMOTE_UNREACHABLE,
+    STAFF_DELIVERY,
+    PENDING_DELIVERY,
+    ADMIN_RECOVERY
+}

serverfeatures-api/src/main/java/nl/hauntedmc/serverfeatures/api/graveyard/GraveClaimOutcome.java

@@ -0,0 +1,18 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+/**
+ * Terminal result reported by a Graveyard claim request.
+ */
+public enum GraveClaimOutcome {
+    CLAIMED,
+    PARTIAL,
+    DELIVERY_QUEUED,
+    RECOVERY_PENDING,
+    NOTHING_FIT,
+    NOT_FOUND,
+    NOT_OWNER,
+    NOT_CLAIMABLE,
+    WRONG_INVENTORY_SCOPE,
+    BUSY,
+    FAILED
+}

serverfeatures-api/src/main/java/nl/hauntedmc/serverfeatures/api/graveyard/GraveClaimResult.java

@@ -0,0 +1,16 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+import java.util.UUID;
+
+/**
+ * Immutable result of one grave claim attempt.
+ */
+public record GraveClaimResult(
+        UUID graveId,
+        GraveClaimOutcome outcome,
+        int transferredEntries,
+        int remainingEntries,
+        int transferredExperience,
+        String message
+) {
+}

serverfeatures-api/src/main/java/nl/hauntedmc/serverfeatures/api/graveyard/GraveSnapshot.java

@@ -0,0 +1,26 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+import java.util.UUID;
+
+/**
+ * Read-only grave metadata exposed to other features and plugins.
+ */
+public record GraveSnapshot(
+        UUID graveId,
+        String shortId,
+        UUID ownerUuid,
+        String ownerName,
+        String serverId,
+        String inventoryScope,
+        UUID worldUuid,
+        String worldKey,
+        double x,
+        double y,
+        double z,
+        GraveStatus status,
+        boolean remoteOnly,
+        long remainingActiveMillis,
+        int itemEntryCount,
+        int remainingExperience
+) {
+}

serverfeatures-api/src/main/java/nl/hauntedmc/serverfeatures/api/graveyard/GraveStatus.java

@@ -0,0 +1,28 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+/**
+ * Durable lifecycle state of a Graveyard grave.
+ */
+public enum GraveStatus {
+    ACTIVE,
+    PARTIAL,
+    ORPHANED_WORLD,
+    DELIVERY_PENDING,
+    CLAIMED,
+    EXPIRED,
+    CORRUPT,
+    ADMIN_RECOVERED,
+    PURGED;
+
+    public boolean isVisible() {
+        return this == ACTIVE || this == PARTIAL;
+    }
+
+    public boolean isPlayerClaimable() {
+        return this == ACTIVE || this == PARTIAL || this == ORPHANED_WORLD;
+    }
+
+    public boolean hasRecoverablePayload() {
+        return this != CLAIMED && this != ADMIN_RECOVERED && this != PURGED;
+    }
+}

serverfeatures-api/src/main/java/nl/hauntedmc/serverfeatures/api/graveyard/GraveyardService.java

@@ -0,0 +1,23 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+import java.util.concurrent.CompletionStage;
+
+/**
+ * Public, ownership-safe access to Graveyard metadata and claim requests.
+ */
+public interface GraveyardService {
+    Optional<GraveSnapshot> find(UUID graveId);
+
+    Optional<GraveSnapshot> findByShortId(String shortId);
+
+    List<GraveSnapshot> findActiveByOwner(UUID ownerUuid);
+
+    CompletionStage<GraveClaimResult> requestClaim(
+            UUID graveId,
+            UUID ownerUuid,
+            ClaimReason reason
+    );
+}

serverfeatures-api/src/test/java/nl/hauntedmc/serverfeatures/api/graveyard/GraveyardApiTest.java

@@ -0,0 +1,99 @@
+package nl.hauntedmc.serverfeatures.api.graveyard;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class GraveyardApiTest {
+
+    @Test
+    void enumContractsExposeEverySupportedValue() {
+        assertEquals(5, ClaimReason.values().length);
+        assertSame(ClaimReason.PHYSICAL_INTERACTION, ClaimReason.valueOf("PHYSICAL_INTERACTION"));
+
+        assertEquals(11, GraveClaimOutcome.values().length);
+        assertSame(GraveClaimOutcome.RECOVERY_PENDING, GraveClaimOutcome.valueOf("RECOVERY_PENDING"));
+
+        assertEquals(9, GraveStatus.values().length);
+        assertSame(GraveStatus.DELIVERY_PENDING, GraveStatus.valueOf("DELIVERY_PENDING"));
+    }
+
+    @Test
+    void statusCapabilitiesMatchTheLifecycleContract() {
+        assertTrue(GraveStatus.ACTIVE.isVisible());
+        assertTrue(GraveStatus.PARTIAL.isVisible());
+        assertFalse(GraveStatus.EXPIRED.isVisible());
+
+        assertTrue(GraveStatus.ACTIVE.isPlayerClaimable());
+        assertTrue(GraveStatus.PARTIAL.isPlayerClaimable());
+        assertTrue(GraveStatus.ORPHANED_WORLD.isPlayerClaimable());
+        assertFalse(GraveStatus.DELIVERY_PENDING.isPlayerClaimable());
+
+        assertTrue(GraveStatus.CORRUPT.hasRecoverablePayload());
+        assertFalse(GraveStatus.CLAIMED.hasRecoverablePayload());
+        assertFalse(GraveStatus.ADMIN_RECOVERED.hasRecoverablePayload());
+        assertFalse(GraveStatus.PURGED.hasRecoverablePayload());
+    }
+
+    @Test
+    void immutableResultAndSnapshotPreserveTheirValues() {
+        UUID graveId = UUID.randomUUID();
+        UUID ownerId = UUID.randomUUID();
+        UUID worldId = UUID.randomUUID();
+        GraveClaimResult result = new GraveClaimResult(
+                graveId,
+                GraveClaimOutcome.PARTIAL,
+                3,
+                2,
+                17,
+                "partial"
+        );
+        GraveSnapshot snapshot = new GraveSnapshot(
+                graveId,
+                "remymine-world-20260804-002600-000",
+                ownerId,
+                "remymine",
+                "demo",
+                "demo",
+                worldId,
+                "minecraft:world",
+                10.5,
+                64.0,
+                -20.5,
+                GraveStatus.PARTIAL,
+                false,
+                60_000L,
+                2,
+                17
+        );
+
+        assertEquals(graveId, result.graveId());
+        assertEquals(GraveClaimOutcome.PARTIAL, result.outcome());
+        assertEquals(3, result.transferredEntries());
+        assertEquals(2, result.remainingEntries());
+        assertEquals(17, result.transferredExperience());
+        assertEquals("partial", result.message());
+
+        assertEquals(graveId, snapshot.graveId());
+        assertEquals("remymine-world-20260804-002600-000", snapshot.shortId());
+        assertEquals(ownerId, snapshot.ownerUuid());
+        assertEquals("remymine", snapshot.ownerName());
+        assertEquals("demo", snapshot.serverId());
+        assertEquals("demo", snapshot.inventoryScope());
+        assertEquals(worldId, snapshot.worldUuid());
+        assertEquals("minecraft:world", snapshot.worldKey());
+        assertEquals(10.5, snapshot.x());
+        assertEquals(64.0, snapshot.y());
+        assertEquals(-20.5, snapshot.z());
+        assertEquals(GraveStatus.PARTIAL, snapshot.status());
+        assertFalse(snapshot.remoteOnly());
+        assertEquals(60_000L, snapshot.remainingActiveMillis());
+        assertEquals(2, snapshot.itemEntryCount());
+        assertEquals(17, snapshot.remainingExperience());
+    }
+}

serverfeatures-platform-paper/src/main/java/nl/hauntedmc/serverfeatures/ServerFeatures.java

@@ -18,6 +18,7 @@
 import nl.hauntedmc.serverfeatures.framework.listener.ScoreboardListener;
 import nl.hauntedmc.serverfeatures.framework.loader.FeatureLoadManager;
 import nl.hauntedmc.serverfeatures.framework.localization.LocalizationHandler;
+import nl.hauntedmc.serverfeatures.framework.time.ServerActiveClock;
 import org.bukkit.Bukkit;
 import org.bukkit.plugin.PluginManager;
 import org.bukkit.plugin.java.JavaPlugin;
@@ -32,6 +33,7 @@ public class ServerFeatures extends JavaPlugin {
     private ConfigService configService;
     private FeatureLifecycleFactory featureLifecycleFactory;
     private FeatureScopeFactory featureScopeFactory;
+    private ServerActiveClock serverActiveClock;
 
     // Keep if other parts of your framework still use dispatcher (features registering their own brig nodes).
     private BrigadierDispatcher brigadierDispatcher;
@@ -53,6 +55,8 @@ public void onEnable() {
                 localizationHandler,
                 featureLifecycleFactory
         );
+        serverActiveClock = new ServerActiveClock(this);
+        serverActiveClock.start();
         featureLoadManager = FeatureLoadManager.create(this);
 
         // Optional: if your feature system still needs direct dispatcher access elsewhere
@@ -92,6 +96,10 @@ public void onDisable() {
         ((PaperActionBarAPI) ActionBars.service()).shutdown();
         ActionBars.shutdown();
 
+        if (serverActiveClock != null) {
+            serverActiveClock.close();
+        }
+
         getLogger().info("ServerFeatures is shutting down...");
     }
 
@@ -131,6 +139,10 @@ public BrigadierDispatcher getBrigadierDispatcher() {
         return brigadierDispatcher;
     }
 
+    public ServerActiveClock getServerActiveClock() {
+        return serverActiveClock;
+    }
+
     public Optional<DataRegistryApi> getDataRegistry() {
         return Optional.ofNullable(Bukkit.getPluginManager().getPlugin("DataRegistry"))
                 .filter(DataRegistryApiProvider.class::isInstance)