PR_26175_DELTA_002: consolidate replay runtime cloning

docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md

@@ -241,7 +241,8 @@ Current OWNER clarification:
 
 ### Team Delta
 
-- [ ] Delta - Shared JS consolidation
+- [x] Delta - Shared JS consolidation
+  - Completion reference: PR_26175_DELTA_002_Shared_Runtime_Consolidation.
 - [ ] Delta - API client consolidation
 - [x] Delta - Runtime performance audit
   - Completion reference: PR_26175_DELTA_001_Runtime_Performance_Optimization.

docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-branch-validation.md

@@ -0,0 +1,15 @@
+# PR_26175_DELTA_002 Branch Validation
+
+| Gate | Status | Evidence |
+| --- | --- | --- |
+| Current branch before work | PASS | `main` after PR_001 merge |
+| Worktree before work | PASS | Clean |
+| Local/origin sync before work | PASS | `0 0` |
+| Team ownership | PASS | Team Delta owns Runtime, Shared JS, and technical consolidation. |
+| Work branch | PASS | `PR_26175_DELTA_002_Shared_Runtime_Consolidation` |
+| Previous Delta PR closed | PASS | PR_001 was merged and `main` was verified before PR_002 started. |
+| Scope boundary | PASS | Shared runtime clone helper plus replay runtime adopters and focused test only. |
+
+## Instruction Reads
+
+PASS - All files under `docs_build/dev/ProjectInstructions/` were read before the Delta sequence, and updated instructions were reread after pulling latest `main`.

docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-manual-validation-notes.md

@@ -0,0 +1,9 @@
+# PR_26175_DELTA_002 Manual Validation Notes
+
+- Confirmed Team Delta ownership covers Shared JS and Runtime.
+- Confirmed replay runtime cloning duplicated local `structuredClone` calls before this PR.
+- Confirmed replay model and replay system now use the shared runtime clone helper.
+- Confirmed fallback behavior by temporarily disabling `globalThis.structuredClone` in the focused replay test.
+- Confirmed no browser-owned data, API contract, UI, or tool state changes were introduced.
+- Confirmed backlog completion reference was added for `Delta - Shared JS consolidation`.
+- Confirmed source branch disposition should remain `retained`.

docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-requirement-checklist.md

@@ -0,0 +1,19 @@
+# PR_26175_DELTA_002 Requirement Checklist
+
+| Requirement | Status | Notes |
+| --- | --- | --- |
+| Team Delta ownership only | PASS | Shared JS and runtime replay consolidation are Delta-owned. |
+| One PR purpose | PASS | Shared runtime clone consolidation only. |
+| Preserve backward compatibility | PASS | Added JSON fallback when `structuredClone` is unavailable. |
+| Update backlog | PASS | `Delta - Shared JS consolidation` marked complete. |
+| Update tool state if applicable | PASS | Not applicable; no tool tile/status changed. |
+| Produce governance reports | PASS | Summary, branch validation, checklist, validation lane, manual notes, Codex diff, changed-file list, and ZIP. |
+| Runtime validation | PASS | Focused node checks, replay system test, and final systems test passed. |
+| No unrelated files | PASS | Changes are limited to shared runtime clone, replay runtime adopters, focused test, backlog, and reports. |
+| No branch deletion | PASS | Source branch retained. |
+
+## Compatibility Notes
+
+- Public replay model shape is unchanged.
+- Replay frames remain deep-cloned before storage and output.
+- Fallback cloning supports runtime environments without native `structuredClone`.

docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-validation.md

@@ -0,0 +1,31 @@
+# PR_26175_DELTA_002 Validation Lane
+
+## Commands
+
+```powershell
+node --check src/shared/runtime/snapshotClone.js
+node --check src/engine/replay/ReplayModel.js
+node --check src/engine/replay/ReplaySystem.js
+node --check tests/replay/ReplaySystem.test.mjs
+node tests/replay/ReplaySystem.test.mjs
+node tests/final/FinalSystems.test.mjs
+```
+
+## Results
+
+| Command | Status |
+| --- | --- |
+| `node --check src/shared/runtime/snapshotClone.js` | PASS |
+| `node --check src/engine/replay/ReplayModel.js` | PASS |
+| `node --check src/engine/replay/ReplaySystem.js` | PASS |
+| `node --check tests/replay/ReplaySystem.test.mjs` | PASS |
+| `node tests/replay/ReplaySystem.test.mjs` | PASS |
+| `node tests/final/FinalSystems.test.mjs` | PASS |
+
+## Browser Validation
+
+SKIP - No browser UI files changed.
+
+## Playwright Validation
+
+SKIP - Runtime replay/shared helper behavior is covered by focused Node tests.

docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation.md

@@ -0,0 +1,44 @@
+# PR_26175_DELTA_002_Shared_Runtime_Consolidation
+
+## Summary
+
+Team Delta consolidated replay cloning onto the shared runtime helper surface.
+
+`src/shared/runtime/snapshotClone.js` now exports `cloneRuntimeValue(...)`, which gives runtime code one shared cloning path with a `structuredClone` fast path and JSON fallback. Replay model and replay system cloning now use that shared helper instead of local `structuredClone` calls.
+
+## Scope
+
+- Team: Delta
+- Backlog item: `Delta - Shared JS consolidation`
+- Shared runtime file changed: `src/shared/runtime/snapshotClone.js`
+- Runtime replay files changed:
+  - `src/engine/replay/ReplayModel.js`
+  - `src/engine/replay/ReplaySystem.js`
+- Tests changed: `tests/replay/ReplaySystem.test.mjs`
+- Backlog updated: `docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md`
+
+## Runtime Impact
+
+PASS - Replay cloning behavior remains backward compatible.
+
+- Replay records still deep-clone metadata, initial state, frames, and final state.
+- Runtime replay code now works even when `structuredClone` is unavailable.
+- Existing replay playback and replacement behavior is preserved.
+
+## Backlog Update
+
+PASS - `Delta - Shared JS consolidation` is marked complete with this PR as the completion reference.
+
+## Tool State Update
+
+SKIP - No Build Path tool status or tool tile state changed.
+
+## Validation Summary
+
+PASS - Focused replay and final system validation completed.
+
+See `PR_26175_DELTA_002_Shared_Runtime_Consolidation-validation.md` for command details.
+
+## Branch Disposition
+
+Source branch should be retained after merge unless OWNER later approves branch deletion.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,10 +1,12 @@
 docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md / updated
-src/engine/runtime/runtimeTickLoop.js / updated
-tests/engine/RuntimeTickLoop.test.mjs / updated
-docs_build/dev/reports/PR_26175_DELTA_001_Runtime_Performance_Optimization.md / added
-docs_build/dev/reports/PR_26175_DELTA_001_Runtime_Performance_Optimization-branch-validation.md / added
-docs_build/dev/reports/PR_26175_DELTA_001_Runtime_Performance_Optimization-requirement-checklist.md / added
-docs_build/dev/reports/PR_26175_DELTA_001_Runtime_Performance_Optimization-validation.md / added
-docs_build/dev/reports/PR_26175_DELTA_001_Runtime_Performance_Optimization-manual-validation-notes.md / added
+src/shared/runtime/snapshotClone.js / updated
+src/engine/replay/ReplayModel.js / updated
+src/engine/replay/ReplaySystem.js / updated
+tests/replay/ReplaySystem.test.mjs / updated
+docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation.md / added
+docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-branch-validation.md / added
+docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-requirement-checklist.md / added
+docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-validation.md / added
+docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-manual-validation-notes.md / added
 docs_build/dev/reports/codex_changed_files.txt / updated
 docs_build/dev/reports/codex_review.diff / updated

src/engine/replay/ReplayModel.js

@@ -7,9 +7,10 @@ ReplayModel.js
 import {
   SHARED_REPLAY_MODEL_CONTRACT_VERSION,
 } from "../../shared/contracts/replayContracts.js";
+import { cloneRuntimeValue } from "../../shared/runtime/snapshotClone.js";
 
 function cloneOrNull(value) {
-  return value === undefined || value === null ? null : structuredClone(value);
+  return cloneRuntimeValue(value);
 }
 
 function cloneFrames(frames) {
@@ -18,7 +19,7 @@ function cloneFrames(frames) {
   }
   const out = [];
   for (let i = 0; i < frames.length; i += 1) {
-    out.push(structuredClone(frames[i]));
+    out.push(cloneRuntimeValue(frames[i]));
   }
   return out;
 }

src/engine/replay/ReplaySystem.js

@@ -5,6 +5,7 @@ David Quesenberry
 ReplaySystem.js
 */
 import { asNonNegativeInteger } from '../../shared/math/numberNormalization.js';
+import { cloneRuntimeValue } from '../../shared/runtime/snapshotClone.js';
 import { createReplayModel, normalizeReplayModel, withFinalState } from './ReplayModel.js';
 import { ReplayTimeline } from './ReplayTimeline.js';
 
@@ -37,7 +38,7 @@ export default class ReplaySystem {
 
   recordFrame(frame) {
     if (this.recording) {
-      const clonedFrame = structuredClone(frame);
+      const clonedFrame = cloneRuntimeValue(frame);
       this.frames.push(clonedFrame);
       this.timeline.pushSnapshot(this.frames.length - 1, clonedFrame);
     }
@@ -51,7 +52,7 @@ export default class ReplaySystem {
   }
 
   getReplay() {
-    return structuredClone(this.replay);
+    return cloneRuntimeValue(this.replay);
   }
 
   loadReplay(replay) {
@@ -96,7 +97,7 @@ export default class ReplaySystem {
     const normalizedFrameId = asNonNegativeInteger(frameId, this.frames.length);
     const prefix = this.frames.slice(0, normalizedFrameId);
     const replacementFrames = Array.isArray(frames)
-      ? frames.map((frame) => structuredClone(frame))
+      ? frames.map((frame) => cloneRuntimeValue(frame))
       : [];
     const nextFrames = [...prefix, ...replacementFrames];
 

src/shared/runtime/snapshotClone.js

@@ -1,3 +1,13 @@
+export function cloneRuntimeValue(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
 export function cloneSnapshot(snapshot) {
   if (snapshot === null || typeof snapshot !== "object") {
     return {};

tests/replay/ReplaySystem.test.mjs

@@ -58,4 +58,26 @@ export function run() {
   assert.equal(replaced.frames.length, 1);
   assert.equal(replaced.frames[0].events.status, 'patched');
   assert.equal(replay.getTimelineSnapshot(0).snapshot.events.status, 'patched');
+
+  const originalStructuredClone = globalThis.structuredClone;
+  try {
+    globalThis.structuredClone = undefined;
+    const fallbackReplay = new ReplaySystem();
+    const fallbackFrame = { input: { jump: true }, events: { status: 'fallback' } };
+    fallbackReplay.startRecording({
+      metadata: { mode: 'json-fallback' },
+      initialState: { player: { x: 4 } },
+    });
+    fallbackReplay.recordFrame(fallbackFrame);
+    fallbackFrame.input.jump = false;
+    fallbackReplay.stopRecording({ finalState: { status: 'done' } });
+
+    const fallbackSavedReplay = fallbackReplay.getReplay();
+    assert.equal(fallbackSavedReplay.metadata.mode, 'json-fallback');
+    assert.equal(fallbackSavedReplay.initialState.player.x, 4);
+    assert.equal(fallbackSavedReplay.frames[0].input.jump, true);
+    assert.equal(fallbackSavedReplay.finalState.status, 'done');
+  } finally {
+    globalThis.structuredClone = originalStructuredClone;
+  }
 }