fix(dev): honor processed world reset policy

Author: SupaHam

.changeset/quiet-pumas-reseed.md

@@ -0,0 +1,5 @@
+---
+"@blurengine/cli": patch
+---
+
+Honor `dev.localServer.worldSync.runtimeWorldMode` for processed development worlds, including deterministic replace and backup behavior on `blr dev` startup while preserving script-only hot reloads.

packages/blr/docs/reference/commands.md

@@ -166,6 +166,7 @@ Runtime world safety:
   - `prompt`: ask before replacing it
   - `preserve`: keep it
 - runtime backup and replacement only happen before BDS starts
+- processed development worlds follow the same startup policy; `replace` rebuilds and reseeds the processed world on each `blr dev` startup without resetting it during script-only hot reloads
 
 Flags:
 

packages/blr/docs/reference/config.md

@@ -544,6 +544,7 @@ Notes:
   - `replace`: replace the runtime world automatically from the project world before startup
   - `backup`: move the existing runtime world into `worlds_backups/` and then replace it before startup
 - runtime-world replacement and backup only happen before BDS starts; `blr` does not modify a running server world
+- the same `runtimeWorldMode` policy applies when development world processors produce the world that BDS runs; `replace` reseeds that processed world on each `blr dev` startup, while script-only hot reloads preserve the running world
 - `watch-world` starts after startup reconciliation and captures runtime world state back into the project source
 - `watch-allowlist` captures both retained runtime server-state files:
   - `allowlist.json`

packages/blr/src/commands/dev.ts

@@ -42,7 +42,7 @@ import {
 import { buildTrackedProjectWorldFingerprint } from "../project-world-state.js";
 import { runPrompt } from "../prompt.js";
 import { buildProject, runLocalDeploy } from "../runtime.js";
-import type { BlurProject } from "../types.js";
+import type { BlurProject, WorldSyncRuntimeMode } from "../types.js";
 import {
     clearLocalServerSession,
     clearRuntimeWorldSeedState,
@@ -972,6 +972,37 @@ type RuntimeWorldDecision =
           note?: string;
       };
 
+type ProcessedRuntimeWorldDecision = Readonly<{
+    action: "backup-and-replace" | "preserve" | "prompt" | "replace";
+}>;
+
+export function resolveProcessedRuntimeWorldDecision(options: {
+    reconcileRequested: boolean;
+    runtimeWorldExists: boolean;
+    runtimeWorldMode: WorldSyncRuntimeMode;
+    sourceMatches: boolean;
+}): ProcessedRuntimeWorldDecision {
+    if (!options.runtimeWorldExists) {
+        return { action: "replace" };
+    }
+    if (!options.reconcileRequested) {
+        return { action: "preserve" };
+    }
+    switch (options.runtimeWorldMode) {
+        case "replace":
+            return { action: "replace" };
+        case "backup":
+            return { action: "backup-and-replace" };
+        case "preserve":
+            return { action: "preserve" };
+        case "prompt":
+        default:
+            return options.sourceMatches
+                ? { action: "preserve" }
+                : { action: "prompt" };
+    }
+}
+
 function buildRuntimeWorldOutOfSyncMessage(
     worldName: string,
     outcome: string,
@@ -2732,12 +2763,63 @@ export async function runDevCommand(options: DevCommandOptions): Promise<void> {
                           ),
                       )
                     : false;
+                let processedDecision = resolveProcessedRuntimeWorldDecision({
+                    reconcileRequested: options.rebuildProcessedWorld,
+                    runtimeWorldExists,
+                    runtimeWorldMode:
+                        config.dev.localServer.worldSync.runtimeWorldMode,
+                    sourceMatches:
+                        lastSeed?.sourceIdentity ===
+                        currentProcessedWorldInput.seedIdentity,
+                });
+                if (processedDecision.action === "prompt") {
+                    if (!canPromptForDevWorldSync()) {
+                        processedDecision = { action: "preserve" };
+                        console.log(
+                            buildRuntimeWorldOutOfSyncMessage(
+                                currentProcessedWorldInput.worldName,
+                                "keeping existing local-server world because this run is non-interactive",
+                            ),
+                        );
+                    } else {
+                        switch (
+                            await promptForRuntimeWorldAction(
+                                currentProcessedWorldInput.worldName,
+                            )
+                        ) {
+                            case "replace":
+                                processedDecision = { action: "replace" };
+                                break;
+                            case "backup":
+                                processedDecision = {
+                                    action: "backup-and-replace",
+                                };
+                                break;
+                            case "keep":
+                            default:
+                                processedDecision = { action: "preserve" };
+                                break;
+                        }
+                    }
+                }
                 const replaceProcessedWorld =
-                    !runtimeWorldExists ||
-                    lastSeed?.sourceIdentity !==
-                        currentProcessedWorldInput.seedIdentity;
+                    processedDecision.action === "replace" ||
+                    processedDecision.action === "backup-and-replace";
+                if (processedDecision.action === "backup-and-replace") {
+                    if (!runtimeState) {
+                        throw new Error(
+                            "Processed runtime-world backup requires a resolved local-server runtime.",
+                        );
+                    }
+                    await localServer.stop({
+                        suppressExitNotification: true,
+                    });
+                    await backupRuntimeWorldForBdsStartup(runtimeState, debug);
+                }
                 const processedApplyMode: PipelineMode = replaceProcessedWorld
-                    ? "restart"
+                    ? processedDecision.action === "backup-and-replace"
+                        ? "start"
+                        : "restart"
                     : mode;
                 await waitForPromiseIfSlow(
                     localServer.apply(processedApplyMode, {

packages/blr/test/dev.test.ts

@@ -9,6 +9,7 @@ import {
     buildRemoteWorldSyncFailureMessage,
     createWorldProcessorWatchPlan,
     mergePipelineModes,
+    resolveProcessedRuntimeWorldDecision,
     resolveRuntimeWorldDecision,
     resolveProjectWatchChangeAction,
     resolveLocalServerLinkOptions,
@@ -467,6 +468,51 @@ test("resolveRuntimeWorldDecision refreshes runtime worlds in replace mode even
     assert.equal(decision.action, "replace");
 });
 
+test("resolveProcessedRuntimeWorldDecision honors replace mode at startup even when the processed seed matches", () => {
+    assert.deepEqual(
+        resolveProcessedRuntimeWorldDecision({
+            reconcileRequested: true,
+            runtimeWorldExists: true,
+            runtimeWorldMode: "replace",
+            sourceMatches: true,
+        }),
+        { action: "replace" },
+    );
+});
+
+test("resolveProcessedRuntimeWorldDecision preserves a running world for script-only reloads", () => {
+    assert.deepEqual(
+        resolveProcessedRuntimeWorldDecision({
+            reconcileRequested: false,
+            runtimeWorldExists: true,
+            runtimeWorldMode: "replace",
+            sourceMatches: true,
+        }),
+        { action: "preserve" },
+    );
+});
+
+test("resolveProcessedRuntimeWorldDecision keeps processed preserve and backup modes distinct", () => {
+    assert.deepEqual(
+        resolveProcessedRuntimeWorldDecision({
+            reconcileRequested: true,
+            runtimeWorldExists: true,
+            runtimeWorldMode: "preserve",
+            sourceMatches: false,
+        }),
+        { action: "preserve" },
+    );
+    assert.deepEqual(
+        resolveProcessedRuntimeWorldDecision({
+            reconcileRequested: true,
+            runtimeWorldExists: true,
+            runtimeWorldMode: "backup",
+            sourceMatches: true,
+        }),
+        { action: "backup-and-replace" },
+    );
+});
+
 test("buildRemoteWorldSyncFailureMessage replaces raw unknown backend errors with a helpful dev warning", () => {
     assert.match(
         buildRemoteWorldSyncFailureMessage({