Preserve publication ownership through shutdown and live saves

AGENTS.md

@@ -52,8 +52,8 @@ For compatibility-sensitive changes, keep regression coverage for established be
 2. Do not access Bukkit entities, inventories, worlds, or other thread-confined state from arbitrary async callbacks.
 3. Reward execution must not be lost or duplicated across delay, disconnect, reload, retry, or partial failure. Preserve the component's documented delivery contract.
 4. Read-only lookups must not create users, mutate caches, or trigger persistence unless that behavior is part of the established API.
-5. Keep user identity and UUID resolution consistent across online/offline paths. Coordinate cache updates, database writes, resets, and shutdown flushing.
-6. Reload and disable must cancel or retire tasks, listeners, executors, connections, and callbacks without allowing stale work to mutate new state.
+5. Keep user identity and UUID resolution consistent across online/offline paths. Coordinate cache updates, database writes, resets, and shutdown flushing. Final shared-runtime retirement fences queued notifications before marking storage retiring; callbacks already holding lifecycle admission may finish and re-enter storage. The optional pre-storage shutdown stage must finish before native storage retirement. Platform cleanup and the completion hook may run earlier on deferred shutdown; consumers must retain their own persistence owner until their stage settles.
+6. Reload and disable must cancel or retire tasks, listeners, executors, connections, and callbacks without allowing stale work to mutate new state. Native ServerData admission precedes early enable hooks and reads and is shared across shaded classloaders through bounded opaque JVM Properties tokens. Release only after successful publication/preparation and actual captured native executor termination; failed or cancelled stages retain admission until JVM restart because settlement alone cannot prove drain. Retain the originating Properties object for release. Repeated disable must not submit stale final writes after release. Final whole-file publications settle in order even for asynchronous owners. A visible native final replacement gets one bounded settlement retry; if unconfirmed, fence that owner against subsequent writes/reload/setup so another save cannot commit its unacknowledged values.
 7. GUI/editor actions must recheck permissions and ownership and must not duplicate items, lose configuration, or save to the wrong path or user.
 8. Optional integrations must be guarded against absent classes and incompatible versions. One platform must not load another platform's API accidentally.
 

AdvancedCore/pom.xml

@@ -238,7 +238,7 @@
         <dependency>
             <groupId>com.bencodez</groupId>
             <artifactId>simpleapi</artifactId>
-            <!-- Published SQL lifecycle fix; do not resolve an older rolling snapshot. -->
+            <!-- Shared SQL lifecycle and delayed entity scheduling support. -->
             <version>1.0.2-SNAPSHOT</version>
             <scope>compile</scope>
             <exclusions>

AdvancedCore/src/main/java/com/bencodez/advancedcore/AdvancedCorePlugin.java

@@ -91,6 +91,54 @@
 public abstract class AdvancedCorePlugin extends JavaPlugin {
 
 	private static AdvancedCorePlugin javaPlugin;
+
+	/** Lifecycle admission is independent from consumer replay/checkpoint synchronization. */
+	private final Object lifecycleLock = new Object();
+	private com.bencodez.advancedcore.lifecycle.ServerDataOwnership serverDataOwnership;
+	private boolean advancedCoreShutdownStarted;
+	private boolean advancedCoreEnableStarted;
+	private boolean serverDataStartupRejected;
+
+	/** Native file admission also covers consumer hooks that read ServerData early. */
+	private void acquireServerDataOwnership() {
+		synchronized (lifecycleLock) {
+			if (serverDataOwnership != null && !serverDataOwnership.isReleased()) {
+				if (!advancedCoreShutdownStarted) return;
+				throw new IllegalStateException("Previous ServerData shutdown has not finished");
+			}
+			try {
+				serverDataOwnership = com.bencodez.advancedcore.lifecycle.ServerDataOwnership.acquire(
+						new File(getDataFolder(), "ServerData.yml").toPath());
+				advancedCoreShutdownStarted = false;
+				advancedCoreEnableStarted = false;
+				serverDataStartupRejected = false;
+			} catch (RuntimeException | Error failure) {
+				serverDataStartupRejected = true;
+				throw failure;
+			}
+		}
+	}
+
+	/** Internal lifecycle fence, independent of consumer shutdown-hook overrides. */
+	public final boolean hasServerDataOwnership() {
+		synchronized (lifecycleLock) {
+			return serverDataOwnership != null && !serverDataOwnership.isReleased();
+		}
+	}
+
+	/** Internal lifecycle fence, independent of consumer shutdown-hook overrides. */
+	public final void releaseServerDataOwnershipAfter(CompletionStage<Void> completion) {
+		com.bencodez.advancedcore.lifecycle.ServerDataOwnership ownership;
+		synchronized (lifecycleLock) { ownership = serverDataOwnership; }
+		if (ownership != null) ownership.releaseAfter(completion);
+	}
+
+	private void cleanUpFailedStartup(Throwable failure) {
+		try { onDisable(); }
+		catch (Throwable cleanupFailure) {
+			if (cleanupFailure != failure) failure.addSuppressed(cleanupFailure);
+		}
+	}
 
 	/**
 	 * Gets the singleton instance of this plugin.
@@ -843,7 +891,16 @@ private void loadHandle() {
 	/**
 	 * Load AdvancedCore hook
 	 */
-	public void loadHook() {
+	public void loadHook() {
+		acquireServerDataOwnership();
+		try { loadCoreHook(); }
+		catch (RuntimeException | Error failure) {
+			cleanUpFailedStartup(failure);
+			throw failure;
+		}
+	}
+
+	private void loadCoreHook() {
 		serverDataFile = new ServerData(this);
 
 		hologramHandler = new HologramHandler(this);
@@ -1381,22 +1438,81 @@ private void loadVersionFile() {
 	}
 
 	@Override
-	public void onDisable() {
-		var presence = playerPresenceService;
-		playerPresenceService = null;
-		if (presence != null) presence.close();
-		var lookup = playerPresenceLookup;
-		playerPresenceLookup = null;
-		if (lookup != null) {
-			lookup.close();
-			org.bukkit.event.HandlerList.unregisterAll(lookup);
+	public void onDisable() {
+		long startedNanos = System.nanoTime();
+		synchronized (lifecycleLock) {
+			if (advancedCoreShutdownStarted || serverDataStartupRejected) return;
+			advancedCoreShutdownStarted = true;
+		}
+		try {
+			if (serverDataOwnership != null) serverDataOwnership.beginShutdown(startedNanos);
+			var presence = playerPresenceService;
+			playerPresenceService = null;
+			try {
+				if (presence != null) presence.close();
+			} finally {
+				var lookup = playerPresenceLookup;
+				playerPresenceLookup = null;
+				if (lookup != null) {
+					try { lookup.close(); }
+					finally { org.bukkit.event.HandlerList.unregisterAll(lookup); }
+				}
+			}
+		} finally {
+			try { new com.bencodez.advancedcore.lifecycle.AdvancedCoreLifecycle(this).shutdown(startedNanos); }
+			finally { if (javaPlugin == this) javaPlugin = null; }
 		}
-		new com.bencodez.advancedcore.lifecycle.AdvancedCoreLifecycle(this).shutdown();
-		javaPlugin = null;
 	}
 
+	/**
+	 * Gives a plugin one asynchronous admission boundary before native user
+	 * storage starts retiring. The default keeps the established shutdown
+	 * sequence unchanged. Implementations must return promptly and may use the
+	 * returned stage to account for work admitted before storage retirement;
+	 * they must not wait synchronously for that work here.
+	 * Exceptional completion or cancellation is reported after shared storage
+	 * retirement settles; it does not skip flushing accepted cache writes.
+	 *
+	 * @return completion of plugin-owned pre-storage-shutdown work
+	 */
+	public CompletionStage<Void> onBeforeStorageShutdown() {
+		return CompletableFuture.completedFuture(null);
+	}
+
+	/**
+	 * Called after platform cleanup and submission of the final permission-data save.
+	 * Deferred storage retirement and final file saves may still be running; implementations must
+	 * retain any owner needed by their pre-storage stage until that stage settles.
+	 * The default is a no-op so existing subclasses retain their lifecycle.
+	 */
+	public void onShutdownComplete() { }
+
+	/**
+	 * Called on the established lifecycle thread after final file work is admitted.
+	 * The stage settles only when all final file owners confirm publication (or fail).
+	 * Consumers must retain required owners until both their preparation and this
+	 * stage settle, and must not synchronously wait or include owner termination in it.
+	 * Existing zero-argument hooks keep their thread and invocation timing.
+	 */
+	public void onShutdownComplete(CompletionStage<Void> finalFilesStage) {
+		onShutdownComplete();
+	}
+
 	@Override
-	public void onEnable() {
+	public void onEnable() {
+		synchronized (lifecycleLock) {
+			acquireServerDataOwnership();
+			if (advancedCoreEnableStarted) throw new IllegalStateException("AdvancedCore is already enabled");
+			advancedCoreEnableStarted = true;
+		}
+		try { enableCore(); }
+		catch (RuntimeException | Error failure) {
+			cleanUpFailedStartup(failure);
+			throw failure;
+		}
+	}
+
+	private void enableCore() {
 		javaPlugin = this;
 		com.bencodez.advancedcore.lifecycle.AdvancedCoreLifecycle.RuntimeExecutors runtimeExecutors = com.bencodez.advancedcore.lifecycle.AdvancedCoreLifecycle
 				.createRuntimeExecutors(this);
@@ -1716,7 +1832,7 @@ private void reloadAdvancedCoreNow(boolean userStorage) {
 	}
 
 	private void finishReloadAdvancedCore() {
-		timeChecker.update();
+		timeChecker.requestUpdate();
 		TabCompleteHandler.getInstance().reload();
 		TabCompleteHandler.getInstance().loadTabCompleteOptions();
 		getRewardHandler().checkSubRewards();