PR_26175_DELTA_002: consolidate replay runtime cloning

Delta Team · Delta Team · commit 27f185b26e82 · 2026-06-25T11:22:48.000-04:00
diff --git a/docs_build/dev/ProjectInstructions/backlog/BACKLOG_MASTER.md b/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.
diff --git a/docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-branch-validation.md b/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`.
diff --git a/docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-manual-validation-notes.md b/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`.
diff --git a/docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-requirement-checklist.md b/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`.
diff --git a/docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation-validation.md b/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.
diff --git a/docs_build/dev/reports/PR_26175_DELTA_002_Shared_Runtime_Consolidation.md b/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.
diff --git a/docs_build/dev/reports/codex_changed_files.txt b/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
diff --git a/docs_build/dev/reports/codex_review.diff b/docs_build/dev/reports/codex_review.diff
diff --git a/src/engine/replay/ReplayModel.js b/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;
 }
diff --git a/src/engine/replay/ReplaySystem.js b/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];
 
diff --git a/src/shared/runtime/snapshotClone.js b/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 {};
diff --git a/tests/replay/ReplaySystem.test.mjs b/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;
+  }
 }

Original file line number	Diff line number	Diff line change
`@@ -7,9 +7,10 @@ ReplayModel.js`
`7`	`7`	`import {`
`8`	`8`	`SHARED_REPLAY_MODEL_CONTRACT_VERSION,`
`9`	`9`	`} from "../../shared/contracts/replayContracts.js";`
	`10`	`+import { cloneRuntimeValue } from "../../shared/runtime/snapshotClone.js";`
`10`	`11`
`11`	`12`	`function cloneOrNull(value) {`
`12`		`- return value === undefined \|\| value === null ? null : structuredClone(value);`
	`13`	`+ return cloneRuntimeValue(value);`
`13`	`14`	`}`
`14`	`15`
`15`	`16`	`function cloneFrames(frames) {`
`@@ -18,7 +19,7 @@ function cloneFrames(frames) {`
`18`	`19`	`}`
`19`	`20`	`const out = [];`
`20`	`21`	`for (let i = 0; i < frames.length; i += 1) {`
`21`		`- out.push(structuredClone(frames[i]));`
	`22`	`+ out.push(cloneRuntimeValue(frames[i]));`
`22`	`23`	`}`
`23`	`24`	`return out;`
`24`	`25`	`}`