BUILD PR: centralize cloneSnapshot across exact network_sample_c batch.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,10 +1,10 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_39_SAFE_NORMALIZE_AITARGETDUMMY_BATCH.md exactly.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_40_CLONE_SNAPSHOT_NETWORK_SAMPLE_C_BATCH.md exactly.
 Edit only these files:
-- src/shared/math/vectorNormalizeUtils.js (new file)
-- games/AITargetDummy/game/AITargetDummyController.js
-- games/AITargetDummy/game/AITargetDummyWorld.js
+- src/shared/utils/snapshotCloneUtils.js (new file)
+- games/network_sample_c/game/ReconciliationLayerAdapter.js
+- games/network_sample_c/game/StateTimelineBuffer.js
 Do not expand scope.
-Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_39_SAFE_NORMALIZE_AITARGETDUMMY_BATCH_delta.zip
+Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_40_CLONE_SNAPSHOT_NETWORK_SAMPLE_C_BATCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: centralize safeNormalize across exact AITargetDummy batch.
+BUILD PR: centralize cloneSnapshot across exact network_sample_c batch.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: run BUILD_PR_SHARED_EXTRACTION_40_CLONE_SNAPSHOT_NETWORK_SAMPLE_C_BATCH after this batch.
+Next: continue duplicate-family extraction from the provided duplicate report.

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Rebuilt 39 as an execution-grade batch using the exact duplicate-report file list for safeNormalize(x, y).
+Rebuilt 40 as an execution-grade batch using the exact duplicate-report file list for cloneSnapshot(snapshot).

docs/pr/BUILD_PR_SHARED_EXTRACTION_40_CLONE_SNAPSHOT_NETWORK_SAMPLE_C_BATCH.md

@@ -0,0 +1,95 @@
+# BUILD_PR_SHARED_EXTRACTION_40_CLONE_SNAPSHOT_NETWORK_SAMPLE_C_BATCH
+
+## Purpose
+Centralize duplicated `cloneSnapshot(snapshot)` implementations across the exact network_sample_c batch identified in the duplicate report.
+
+## Single PR Purpose
+Normalize ONLY this helper:
+
+- `cloneSnapshot(snapshot)`
+
+## Exact Files Allowed
+
+### New shared file
+1. `src/shared/utils/snapshotCloneUtils.js`
+
+### Consumer files
+2. `games/network_sample_c/game/ReconciliationLayerAdapter.js`
+3. `games/network_sample_c/game/StateTimelineBuffer.js`
+
+Do not edit any other file.
+
+## Source of Truth
+This exact scope comes from the provided duplicate report entry for:
+
+`function cloneSnapshot(snapshot)`
+
+Only the 2 listed consumer files are in scope.
+
+## Exact Shared Helper Creation
+Create:
+
+`src/shared/utils/snapshotCloneUtils.js`
+
+Export exactly:
+
+```js
+export function cloneSnapshot(snapshot) {
+  // copy one existing implementation exactly
+}
+```
+
+Implementation rules:
+- use ONE existing local implementation as source-of-truth
+- do NOT merge logic
+- do NOT generalize behavior
+- preserve the function signature exactly:
+  - `cloneSnapshot(snapshot)`
+
+## Exact Consumer Changes
+For each of the 2 listed consumer files:
+
+If the file contains a local function definition matching:
+```js
+function cloneSnapshot(snapshot)
+```
+then:
+- remove the local `cloneSnapshot(snapshot)` function definition
+- import `cloneSnapshot` from the correct relative path to:
+  - `src/shared/utils/snapshotCloneUtils.js`
+- if the file already imports from that module, add `cloneSnapshot` with the minimum safe edit
+- do not duplicate imports
+- do not touch unrelated helpers
+- do not change logic
+
+If a listed file already imports and uses shared `cloneSnapshot`, leave it unchanged.
+
+## Relative Import Rule
+Use the correct relative path from each consumer file to:
+
+`src/shared/utils/snapshotCloneUtils.js`
+
+Do not use aliases.
+Do not change `.js` extension usage.
+
+## Hard Constraints
+- no engine changes
+- no game files outside the 2 listed consumers
+- no sample files
+- no repo-wide snapshot/deep-clone cleanup
+- no behavior changes
+- keep one PR purpose only
+
+## Validation Checklist
+1. Confirm no more than the 3 listed files changed
+2. Confirm `src/shared/utils/snapshotCloneUtils.js` exists and exports `cloneSnapshot`
+3. Confirm local `function cloneSnapshot(snapshot)` definitions no longer exist in changed listed consumer files
+4. Confirm changed consumer files import `cloneSnapshot` from the correct relative path to `src/shared/utils/snapshotCloneUtils.js`
+5. Confirm no unrelated engine, game, or sample files changed
+6. Confirm no behavior changes were made
+
+## Non-Goals
+- no cleanup of `clone(value)`
+- no cleanup of `cloneJson(value)`
+- no cleanup outside the 2 listed consumer files
+- no refactor beyond this exact duplicate-removal batch

games/network_sample_c/game/ReconciliationLayerAdapter.js

@@ -6,6 +6,7 @@ ReconciliationLayerAdapter.js
 */
 import StateTimelineBuffer from "./StateTimelineBuffer.js";
 import { asFiniteNumber, asPositiveInteger } from "../../../src/shared/utils/numberUtils.js";
+import { cloneSnapshot } from "../../../src/shared/utils/snapshotCloneUtils.js";
 
 const APPROVED_PUBLIC_EVENT_TYPES = new Set([
   "worldState.transition.applied",
@@ -19,26 +20,6 @@ function sanitizeText(value, fallback = "") {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
 
-function cloneSnapshot(snapshot) {
-  if (snapshot === null || typeof snapshot !== "object") {
-    return {};
-  }
-  return {
-    ...snapshot,
-    entities: Array.isArray(snapshot.entities)
-      ? snapshot.entities.map((entity) => ({
-          ...entity,
-          position: entity?.position ? { ...entity.position } : undefined,
-          velocity: entity?.velocity ? { ...entity.velocity } : undefined,
-          stateFlags: entity?.stateFlags ? { ...entity.stateFlags } : undefined
-        }))
-      : [],
-    meta: snapshot.meta && typeof snapshot.meta === "object"
-      ? { ...snapshot.meta }
-      : undefined
-  };
-}
-
 function cloneEntitySnapshot(entity) {
   const source = entity && typeof entity === "object" ? entity : {};
   return {

games/network_sample_c/game/StateTimelineBuffer.js

@@ -6,6 +6,7 @@ StateTimelineBuffer.js
 */
 
 import { asPositiveInteger } from "../../../src/shared/utils/numberUtils.js";
+import { cloneSnapshot } from "../../../src/shared/utils/snapshotCloneUtils.js";
 
 function normalizeFrameId(frameId) {
   const numeric = Number(frameId);
@@ -15,26 +16,6 @@ function normalizeFrameId(frameId) {
   return Math.floor(numeric);
 }
 
-function cloneSnapshot(snapshot) {
-  if (snapshot === null || typeof snapshot !== "object") {
-    return {};
-  }
-  return {
-    ...snapshot,
-    entities: Array.isArray(snapshot.entities)
-      ? snapshot.entities.map((entity) => ({
-          ...entity,
-          position: entity?.position ? { ...entity.position } : undefined,
-          velocity: entity?.velocity ? { ...entity.velocity } : undefined,
-          stateFlags: entity?.stateFlags ? { ...entity.stateFlags } : undefined
-        }))
-      : [],
-    meta: snapshot.meta && typeof snapshot.meta === "object"
-      ? { ...snapshot.meta }
-      : undefined
-  };
-}
-
 function lowerBound(sortedValues, target) {
   let left = 0;
   let right = sortedValues.length;

src/shared/utils/snapshotCloneUtils.js

@@ -0,0 +1,19 @@
+export function cloneSnapshot(snapshot) {
+  if (snapshot === null || typeof snapshot !== "object") {
+    return {};
+  }
+  return {
+    ...snapshot,
+    entities: Array.isArray(snapshot.entities)
+      ? snapshot.entities.map((entity) => ({
+          ...entity,
+          position: entity?.position ? { ...entity.position } : undefined,
+          velocity: entity?.velocity ? { ...entity.velocity } : undefined,
+          stateFlags: entity?.stateFlags ? { ...entity.stateFlags } : undefined
+        }))
+      : [],
+    meta: snapshot.meta && typeof snapshot.meta === "object"
+      ? { ...snapshot.meta }
+      : undefined
+  };
+}