feat: add safe admin score fast-forward

Author: mrfloris

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 This changelog records source milestones. A listed feature is not production approval; release evidence and the Paper/live-data acceptance result belong in [checklist-walktheplank.md](checklist-walktheplank.md).
 
+## [2.8.4-029] — 2026-08-03
+
+Expected artifact: `1MB-WalkThePlank-v2.8.4-029-j25-26.2.jar`
+
+### Non-scoring high-score reproduction
+
+- Added the separately permissioned `/walk admin test fast-forward <target-score>` workflow for reproducing long-run behavior without requiring an operator to make hundreds of manual jumps. Administrative testing is disabled by default and bounded by `adminTesting.maximumTargetScore`.
+- Fast-forwarding replays the real platform planner, durability journal, restoration, block-lease, and successor pipeline one transition at a time on the primary thread while file durability remains on its bounded worker. It waits for each predecessor cleanup and the next durable successor instead of faking a score counter.
+- The run is irreversibly marked as an administrative test before the first synthetic transition. Test runs cannot update Classic, season, Combo, or Flawless results; cannot prepare or dispatch rewards; and settle as an audited `ABORTED` run without a score.
+- Normal movement handling and cosmetic feedback are suppressed only while synthetic transitions are in flight. Public jump/completion events and normal jump metrics remain suppressed for the entire marked test run, preventing unaware integrations from treating its manual tail as genuine gameplay. At the target score the player is placed on the exact current platform with a ready successor and resumes ordinary manual movement, allowing a direct 110-to-111-to-112 reproduction.
+- Source review found no explicit score-111 ceiling. The planner changes difficulty at score 100 and otherwise continues; this controlled workflow is intended to distinguish a genuine cumulative durability/world-placement failure from an ordinary fall on the harder post-100 jumps. No database-schema or historical-leaderboard change is included.
+
 ## [2.8.3-028] — 2026-07-28
 
 Expected artifact: `1MB-WalkThePlank-v2.8.3-028-j25-26.2.jar`

README.md

@@ -1,17 +1,17 @@
 # WalkThePlank future improvements and release status
 
-This is the authoritative future-development TODO and release-status document. It separates what is implemented through source release **v2.8.3 build 028** from what still needs server acceptance or future design work. “Implemented” means the behavior is present in source; the table or checklist identifies whether automated or Paper/live-data evidence still remains. It does not mean the summer-event candidate is production-approved. The release candidate still has to pass [checklist-walktheplank.md](checklist-walktheplank.md).
+This is the authoritative future-development TODO and release-status document. It separates what is implemented through source release **v2.8.4 build 029** from what still needs server acceptance or future design work. “Implemented” means the behavior is present in source; the table or checklist identifies whether automated or Paper/live-data evidence still remains. It does not mean the summer-event candidate is production-approved. The release candidate still has to pass [checklist-walktheplank.md](checklist-walktheplank.md).
 
 Status labels:
 
-- **Implemented** — present in the current build-028 source.
+- **Implemented** — present in the current build-029 source.
 - **Implemented; beta verification pending** — present, but the final JAR still needs the named Paper/live-data test.
 - **Partial** — a safe foundation exists, but an important workflow or assurance remains.
 - **Proposed** — not present and must not be advertised as a current feature.
 
 ## Deferred modernization queue
 
-Build 003 remains the historical modernization baseline, build 004 the event-safety release, build 005 the destructive-testing foundation, build 006 the off-main durability release, and build 007 the command/API modernization release. Build 008 added bounded migration-backup retention, milestones/accessibility, separate Combo/Flawless categories, rate-limited movement anomaly evidence, and a verified audit chain. Builds 009–022 culminated in a successful real-player score-9 run and approved summer appearance. Builds 023–026 added optional queue reservation, event themes/sounds, paged GUI status, and atomic in-game event control. Build 027 added UUID-first dot-prefixed Floodgate display metadata and schema v4 without changing Classic ownership. Build 028 refreshes the maintained PaperScript/server profile, exact stable Paper API/runtime floor, Java 25 tooling, embedded release metadata, and drift verification without changing gameplay or persistence. Every remaining unchecked feature stays deferred so its evidence cannot be confused with this candidate.
+Build 003 remains the historical modernization baseline, build 004 the event-safety release, build 005 the destructive-testing foundation, build 006 the off-main durability release, and build 007 the command/API modernization release. Build 008 added bounded migration-backup retention, milestones/accessibility, separate Combo/Flawless categories, rate-limited movement anomaly evidence, and a verified audit chain. Builds 009–022 culminated in a successful real-player score-9 run and approved summer appearance. Builds 023–026 added optional queue reservation, event themes/sounds, paged GUI status, and atomic in-game event control. Build 027 added UUID-first dot-prefixed Floodgate display metadata and schema v4 without changing Classic ownership. Build 028 refreshed the maintained PaperScript/server profile, exact stable Paper API/runtime floor, Java 25 tooling, embedded release metadata, and drift verification. Build 029 adds an explicitly enabled, separately permissioned, irreversibly non-scoring administrative fast-forward that replays genuine platform lifecycle transitions for controlled high-score reproduction without changing the database schema or historical leaderboards. Every remaining unchecked feature stays deferred so its evidence cannot be confused with this candidate.
 
 1. [x] **v2.1.1 build 004 — event-safety and operations implemented; beta acceptance still pending.** External-teleport decisions occur at `HIGHEST` with observation-only `MONITOR` and next-tick verification; GUI sessions bind owner UUID/nonce/generation/exact inventory with one pending action; trusted formatting is parsed separately from literal dynamic components with explicit `minimessage:` opt-in and legacy `&` compatibility; `/walk admin doctor` produces a privacy-safe report with an asynchronous SQLite probe.
 2. [x] **v2.1.2 build 005 — disposable Paper integration and fault-injection harness implemented; final-candidate and real-client evidence pending.** A separate test plugin, Java 25 Class-File API instrumented-copy builder, 24 named failpoints, two-start/PlaceholderAPI/lifecycle/log runner, real-player queue/teleport/GUI/reconnect/exit probes, reflection event contracts, and positive/negative production-isolation checks are present. Development-artifact runs passed the automated two-start profile and the `config.after_runtime_commit` exit-97/recovery profile; repeat them against the clean committed candidate and complete every applicable real-client/hard-kill checklist row before treating this item as release-qualified.
@@ -46,7 +46,7 @@ Build 008 includes all previous modernization layers documented in [CHANGELOG.md
 | Capability | Status | Notes |
 | --- | --- | --- |
 | Gradle build and wrapper | **Implemented** | Gradle 9.6.1, Shadow 9.5.1, strict Java 25 compilation. |
-| Paper target | **Implemented; clean freeze rerun pending** | Exact compile API is `26.2.build.84-stable`; `api-version: 26.2` and an explicit `ServerBuildInfo` gate reject older lines and Paper-compatible runtimes below the separately embedded minimum build 84. The uncommitted build-028 artifact passed full-stack build-84 smoke on Java 25.0.4 and Java 26.0.2; repeat it after the clean freeze. |
+| Paper target | **Implemented; clean freeze rerun pending** | Exact compile API is `26.2.build.84-stable`; `api-version: 26.2` and an explicit `ServerBuildInfo` gate reject older lines and Paper-compatible runtimes below the separately embedded minimum build 84. Build 028 passed full-stack build-84 smoke on Java 25.0.4 and Java 26.0.2; repeat it for the clean build-029 candidate. |
 | Standalone SQLite JAR | **Implemented** | SQLite JDBC 3.53.2.0 is shaded; MySQL/MariaDB is absent. |
 | Archive-composition gate | **Implemented** | Rejects bundled Paper/Bukkit/PlaceholderAPI/live-database classes or files and remote-database drivers. |
 | Isolated scenario artifacts | **Implemented; clean-candidate rerun pending** | The harness is an independent Paper plugin and the Java 25 Class-File API transformer writes a distinct `TEST-ONLY-` copy. Neither is packaged beneath `build/libs/` or allowed to replace the production JAR. Build-028 development-artifact isolation and controlled-profile gates passed. |

checklist-walktheplank.md

@@ -1,5 +1,5 @@
-pluginVersion=2.8.3
-buildNumber=028
+pluginVersion=2.8.4
+buildNumber=029
 javaTarget=25
 paperTarget=26.2
 paperApiVersion=26.2.build.84-stable

feature-improvements-walktheplank.md

@@ -151,7 +151,8 @@ boolean hasAnyAdminPermission(CommandSender sender) {
                 || sender.hasPermission(permissions.adminSeason())
                 || sender.hasPermission(permissions.adminExport())
                 || sender.hasPermission(permissions.adminReward())
-                || sender.hasPermission(permissions.adminInvestigate());
+                || sender.hasPermission(permissions.adminInvestigate())
+                || sender.hasPermission(permissions.adminTest());
     }
 
     void deny(CommandSender sender, String permission) {

gradle.properties

@@ -602,7 +602,7 @@ private void showCommands(CommandSender sender) {
         support.sendLine(
                 sender,
                 "&7Staff: &f/walk admin open, reload, stop, recover, validate, "
-                        + "arena, queue, season, export, reward, run, status, "
+                        + "arena, queue, season, export, reward, run, test, status, "
                         + "debug, doctor");
         support.sendLine(
                 sender,
@@ -638,6 +638,7 @@ private void showPermissions(CommandSender sender) {
                 Map.entry("admin.season", permissions.adminSeason()),
                 Map.entry("admin.export", permissions.adminExport()),
                 Map.entry("admin.reward", permissions.adminReward()),
+                Map.entry("admin.test", permissions.adminTest()),
                 Map.entry(
                         "admin.investigate",
                         permissions.adminInvestigate())).entrySet()) {

src/main/java/com/mrfdev/walktheplank/command/CommandSupport.java

@@ -0,0 +1,74 @@
+package com.mrfdev.walktheplank.command;
+
+import com.mrfdev.walktheplank.game.GameManager.AdminTestStartResult;
+import java.util.Map;
+import org.bukkit.command.CommandSender;
+import org.bukkit.entity.Player;
+
+/** Explicitly armed, self-only administrative gameplay reproduction controls. */
+final class TestCommands {
+    private final CommandSupport support;
+
+    TestCommands(CommandSupport support) {
+        this.support = support;
+    }
+
+    void help(CommandSender sender) {
+        if (!support.requireAdministrativePermission(
+                sender, support.permissions().adminTest())) {
+            return;
+        }
+        var testing = support.settings.get().adminTesting();
+        support.sendHeader(sender, "Administrative gameplay test");
+        support.sendField(sender, "Enabled", Boolean.toString(testing.enabled()));
+        support.sendField(
+                sender,
+                "Maximum target",
+                Integer.toString(testing.maximumTargetScore()));
+        support.sendCommandHelp(
+                sender,
+                "/walk admin test fast-forward <target-score>",
+                "Fast-forward your score-zero run without scores or rewards");
+    }
+
+    void fastForward(CommandSender sender, int targetScore) {
+        if (!support.requireAdministrativePermission(
+                sender, support.permissions().adminTest())) {
+            return;
+        }
+        Player player = support.requirePlayer(sender);
+        if (player == null) {
+            return;
+        }
+
+        AdminTestStartResult result =
+                support.games.startAdminTestFastForward(player, targetScore);
+        switch (result) {
+            case STARTED -> support.sendLine(
+                    sender,
+                    "&aStarted a non-scoring fast-forward toward score &f{{score}}&a. "
+                            + "Wait for its completion message before jumping.",
+                    Map.of("score", targetScore));
+            case DISABLED -> support.sendLine(
+                    sender,
+                    "&eAdministrative gameplay testing is disabled in config.");
+            case NO_ACTIVE_RUN -> support.sendLine(
+                    sender,
+                    "&eStart a WalkThePlank run before using fast-forward.");
+            case SCORE_NOT_ZERO -> support.sendLine(
+                    sender,
+                    "&eFast-forward is accepted only while the active run is still at score 0.");
+            case ALREADY_RUNNING -> support.sendLine(
+                    sender,
+                    "&eAn administrative fast-forward is already in progress.");
+            case TARGET_OUT_OF_RANGE -> support.sendLine(
+                    sender,
+                    "&eThe target must be between 1 and the configured maximum of &f{{maximum}}&e.",
+                    Map.of(
+                            "maximum",
+                            support.settings.get()
+                                    .adminTesting()
+                                    .maximumTargetScore()));
+        }
+    }
+}

src/main/java/com/mrfdev/walktheplank/command/DatabaseCommands.java

@@ -23,7 +23,7 @@
 /**
  * Lifecycle-registered Brigadier command coordinator.
  *
- * <p>Domain behavior lives in the player, queue, arena, season, reward, investigation, and
+ * <p>Domain behavior lives in the player, queue, arena, season, reward, investigation, test, and
  * database modules. This class only coordinates registration, shutdown, reload, and shared help.
  */
 public final class WalkCommand {
@@ -35,6 +35,7 @@ public final class WalkCommand {
     final SeasonCommands seasons;
     final RewardCommands rewards;
     final InvestigationCommands investigations;
+    final TestCommands tests;
     final DatabaseCommands database;
 
     private final ReloadHandler reloadHandler;
@@ -75,6 +76,7 @@ public WalkCommand(
         this.seasons = new SeasonCommands(support);
         this.rewards = new RewardCommands(support);
         this.investigations = new InvestigationCommands(support);
+        this.tests = new TestCommands(support);
         this.database = new DatabaseCommands(support);
     }
 
@@ -249,6 +251,11 @@ void adminHelp(CommandSender sender) {
                 permissions.adminInvestigate(),
                 "/walk admin run",
                 "Query redacted retained-run evidence");
+        support.addAdminHelp(
+                sender,
+                permissions.adminTest(),
+                "/walk admin test fast-forward <target-score>",
+                "Start a self-only non-scoring reproduction run");
         support.addAdminHelp(
                 sender,
                 permissions.adminDebug(),

src/main/java/com/mrfdev/walktheplank/command/TestCommands.java

@@ -293,6 +293,7 @@ private static LiteralArgumentBuilder<CommandSourceStack> adminNode(
         admin.then(exportNode(command));
         admin.then(rewardNode(command));
         admin.then(investigationNode(command));
+        admin.then(adminTestNode(command));
 
         LiteralArgumentBuilder<CommandSourceStack> status =
                 Commands.literal("status")
@@ -319,6 +320,27 @@ private static LiteralArgumentBuilder<CommandSourceStack> adminNode(
         return admin;
     }
 
+    private static LiteralArgumentBuilder<CommandSourceStack> adminTestNode(
+            WalkCommand command) {
+        return Commands.literal("test")
+                .requires(source -> command.adminPermission(
+                        source,
+                        command.support.permissions().adminTest()))
+                .executes(context -> command.execute(
+                        context.getSource(), command.tests::help))
+                .then(Commands.literal("fast-forward")
+                        .then(Commands.argument(
+                                        "target-score",
+                                        IntegerArgumentType.integer(1, 500))
+                                .executes(context -> command.execute(
+                                        context.getSource(),
+                                        sender -> command.tests.fastForward(
+                                                sender,
+                                                IntegerArgumentType.getInteger(
+                                                        context,
+                                                        "target-score"))))));
+    }
+
     private static LiteralArgumentBuilder<CommandSourceStack> eventNode(
             WalkCommand command) {
         LiteralArgumentBuilder<CommandSourceStack> event =