BUILD PR: centralize asPositiveNumber across exact network sample batch.

DavidQ · DavidQ · commit 7eebcf39f4df · 2026-04-08T17:16:59.000-04:00
diff --git a/MASTER_ROADMAP_HIGH_LEVEL_status_only_updated.md b/MASTER_ROADMAP_HIGH_LEVEL_status_only_updated.md
diff --git a/UPDATED_MASTER_ROADMAP_HIGH_LEVEL_v2.md b/UPDATED_MASTER_ROADMAP_HIGH_LEVEL_v2.md
@@ -0,0 +1,103 @@
+# MASTER ROADMAP — HIGH LEVEL (v6 ADDITIVE) — UPDATED
+
+## Status Key
+- [x] complete
+- [.] in progress
+- [ ] planned
+
+---
+
+## 1. Repo Structure Normalization
+- [.] target structure defined at high level
+- [.] `src/engine` target established
+- [.] `src/shared` target established
+- [.] `games/` target established
+- [.] `games/_template/` target established
+- [.] `tools/shared` target established
+- [.] phase-based `samples/` grouping target established
+- [.] dependency direction rules defined
+- [.] shared asset promotion rules defined
+- [.] network samples classified as sample-phase content
+- [ ] current folder inventory mapped to target homes
+- [ ] move-map defined for root `engine/` -> `src/engine/`
+- [x] duplicate-helper migration map defined
+- [ ] ambiguous-name rename map defined
+- [ ] legacy migration map defined
+- [ ] implementation PRs executed
+- [x] imports normalized after moves
+- [ ] post-move validation complete
+
+---
+
+## 3. Shared Foundation (`src/shared`)
+- [x] core shared extraction pipeline executed
+- [x] enforcement guard in place
+- [x] numbers utilities consolidated
+- [x] objects utilities consolidated
+- [.] arrays utilities consolidated
+- [.] strings utilities consolidated
+- [ ] ids utilities consolidated
+- [ ] shared math layer consolidated
+- [ ] shared state guards consolidated
+- [ ] shared state normalization consolidated
+- [ ] shared selectors consolidated
+- [ ] shared contracts consolidated
+- [ ] shared io/data/types stabilized
+
+### Duplicate / Rename Focus
+- [x] `asFiniteNumber` unified
+- [x] `asPositiveInteger` unified
+- [x] `isPlainObject` unified
+- [.] `getState` variants bucketed by domain
+- [ ] `getSimulationState` naming established where needed
+- [ ] `getReplayState` naming established where needed
+- [ ] `getEditorState` naming established where needed
+
+---
+
+## 6. Samples Program
+- [.] sample numbering normalization completed
+- [.] sample formatting alignment completed
+- [ ] phase grouping normalized
+- [ ] `samples/shared` boundaries defined and used
+- [ ] sample index normalized to phase structure
+- [ ] sample-to-engine dependency cleanup completed
+- [x] sample duplicate helper usage reduced
+- [ ] sample curriculum progression validated
+
+---
+
+## 7. Phase 13 — Network Concepts
+
+### Track Q — Network Debug Panels
+- [x] Connection status panel
+- [.] Latency / RTT panel
+- [ ] Replication state viewer
+- [x] Client/server divergence inspector
+- [x] Event tracing panel
+
+### Track R — Network Debug Commands
+- [ ] network.help
+- [x] network.status
+- [x] network.latency
+- [.] network.replication
+- [x] network.divergence
+- [x] network.trace
+- [.] network.sample.*
+
+---
+
+## Dependency-Ordered Future Build Sequence
+- [ ] Finish current promotion-gate lane (BUILD → APPLY)
+- [ ] Apply master roadmap baseline
+- [ ] Apply repo structure normalization implementation plan
+- [.] Extract / normalize shared utilities
+- [ ] Normalize samples phase structure
+- [ ] Normalize phase-13 network concepts samples
+- [ ] Establish games/_template and normalize games layer
+- [ ] Normalize tools/shared and tool boundaries
+- [ ] Normalize assets/data ownership
+- [ ] Expand testing/validation structure
+- [ ] Execute 2D capability polish lanes
+- [ ] Execute phase-16 / 3D capability lanes
+- [ ] Reduce legacy footprint after replacements are proven
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,36 +1,14 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_31_CLONE_JSON_BATCH_RETRY.md exactly.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_34_AS_POSITIVE_NUMBER_NETWORK_BATCH.md exactly.
 Edit only these files:
-- src/shared/utils/jsonUtils.js (new file)
-- tools/dev/devConsoleIntegration.js
-- tools/dev/advanced/debugMacroRegistry.js
-- tools/dev/advanced/debugPanelGroupRegistry.js
-- tools/dev/inspectors/inspectorStore.js
-- tools/dev/plugins/debugPluginSystem.js
-- tools/dev/presets/debugPresetApplier.js
-- tools/dev/presets/debugPresetRegistry.js
-- tools/shared/assetMarketplace.js
-- tools/shared/asteroidsPlatformDemo.js
-- tools/shared/cloudRuntime.js
-- tools/shared/collaborationSystem.js
-- tools/shared/contractVersioning.js
-- tools/shared/devConsoleDebugOverlay.js
-- tools/shared/hotReloadSystem.js
-- tools/shared/multiTargetExport.js
-- tools/shared/performanceBenchmarks.js
-- tools/shared/platformValidationSuite.js
-- tools/shared/pluginArchitecture.js
-- tools/shared/renderPipelineContract.js
-- tools/shared/runtimeAssetLoader.js
-- tools/shared/runtimeSceneLoaderHotReload.js
-- tools/shared/runtimeStreaming.js
-- tools/shared/vectorAssetSystem.js
-- tools/shared/vectorGeometryRuntime.js
-- tools/shared/vectorNativeTemplate.js
-- tools/shared/vectorTemplateSampleGame.js
-- tools/shared/vector/vectorAssetContract.js
-- tools/shared/vector/vectorRenderPrep.js
+- src/shared/utils/numberUtils.js (only to add/export asPositiveNumber if missing, or minimum export fix if present)
+- games/network_sample_a/game/FakeLoopbackNetworkModel.js
+- games/network_sample_a/game/NetworkSampleAScene.js
+- games/network_sample_b/game/FakeHostClientNetworkModel.js
+- games/network_sample_b/game/NetworkSampleBScene.js
+- games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js
+- games/network_sample_c/game/NetworkSampleCScene.js
 Do not expand scope.
-Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_31_CLONE_JSON_BATCH_RETRY_delta.zip
+Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_34_AS_POSITIVE_NUMBER_NETWORK_BATCH_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-BUILD PR: centralize cloneJson across exact tools/dev + tools/shared batch.
+BUILD PR: centralize asPositiveNumber across exact network sample batch.
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-Next: run BUILD_PR_SHARED_EXTRACTION_32_IS_OBJECT_BATCH_RETRY after this batch.
+Next: run BUILD_PR_SHARED_EXTRACTION_35_NETWORK_DEBUG_SERIALIZATION_BATCH after this batch.
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1 @@
-Replaced the blocked cloneJson BUILD with an execution-grade retry using the exact target file list from the duplicate report.
+Execution-grade batch for asPositiveNumber using the exact duplicate-report file list.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1 +1 @@
-Exact file list present; no guessing; one PR purpose only.
+Exact file list present; one PR purpose only; no guessing.
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -92,11 +92,11 @@
 - [.] network samples classified as sample-phase content
 - [ ] current folder inventory mapped to target homes
 - [ ] move-map defined for root `engine/` -> `src/engine/`
-- [ ] duplicate-helper migration map defined
+- [x] duplicate-helper migration map defined
 - [ ] ambiguous-name rename map defined
 - [ ] legacy migration map defined
 - [ ] implementation PRs executed
-- [ ] imports normalized after moves
+- [x] imports normalized after moves
 - [ ] post-move validation complete
 
 ### Structure Targets
@@ -156,8 +156,8 @@
 - [x] enforcement guard in place
 - [x] numbers utilities consolidated
 - [x] objects utilities consolidated
-- [ ] arrays utilities consolidated
-- [ ] strings utilities consolidated
+- [.] arrays utilities consolidated
+- [.] strings utilities consolidated
 - [ ] ids utilities consolidated
 - [ ] shared math layer consolidated
 - [ ] shared state guards consolidated
@@ -170,7 +170,7 @@
 - [x] `asFiniteNumber` unified
 - [x] `asPositiveInteger` unified
 - [x] `isPlainObject` unified
-- [ ] `getState` variants bucketed by domain
+- [.] `getState` variants bucketed by domain
 - [ ] `getSimulationState` naming established where needed
 - [ ] `getReplayState` naming established where needed
 - [ ] `getEditorState` naming established where needed
@@ -337,16 +337,16 @@
 - [.] Latency / RTT panel
 - [ ] Replication state viewer
 - [x] Client/server divergence inspector
-- [.] Event tracing panel
+- [x] Event tracing panel
 
 ### Track R — Network Debug Commands
 - [ ] network.help
 - [x] network.status
 - [x] network.latency
-- [ ] network.replication
+- [.] network.replication
 - [x] network.divergence
 - [x] network.trace
-- [ ] network.sample.*
+- [.] network.sample.*
 
 ### Track S — Readiness To Promote
 - [.] Sample-backed provider validation
@@ -557,7 +557,7 @@
 - [ ] Finish current promotion-gate lane (BUILD → APPLY)
 - [ ] Apply master roadmap baseline
 - [ ] Apply repo structure normalization implementation plan
-- [ ] Extract / normalize shared utilities
+- [.] Extract / normalize shared utilities
 - [ ] Normalize samples phase structure
 - [ ] Normalize phase-13 network concepts samples
 - [ ] Establish games/_template and normalize games layer
diff --git a/docs/pr/BUILD_PR_SHARED_EXTRACTION_34_AS_POSITIVE_NUMBER_NETWORK_BATCH.md b/docs/pr/BUILD_PR_SHARED_EXTRACTION_34_AS_POSITIVE_NUMBER_NETWORK_BATCH.md
@@ -0,0 +1,92 @@
+# BUILD_PR_SHARED_EXTRACTION_34_AS_POSITIVE_NUMBER_NETWORK_BATCH
+
+## Purpose
+Centralize duplicated `asPositiveNumber(value, fallback)` implementations across the exact network sample batch identified in the duplicate report.
+
+## Single PR Purpose
+Normalize ONLY this helper:
+
+- `asPositiveNumber(value, fallback)`
+
+## Exact Files Allowed
+
+### Shared source
+1. `src/shared/utils/numberUtils.js`
+
+### Consumer files
+2. `games/network_sample_a/game/FakeLoopbackNetworkModel.js`
+3. `games/network_sample_a/game/NetworkSampleAScene.js`
+4. `games/network_sample_b/game/FakeHostClientNetworkModel.js`
+5. `games/network_sample_b/game/NetworkSampleBScene.js`
+6. `games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js`
+7. `games/network_sample_c/game/NetworkSampleCScene.js`
+
+Do not edit any other file.
+
+## Source of Truth
+This exact file list comes from the provided duplicate report entry for:
+
+`function asPositiveNumber(value, fallback)`
+
+No other numeric helpers are in scope for this PR.
+
+## Shared Helper Assumption
+Use the existing shared utility:
+
+`src/shared/utils/numberUtils.js`
+
+Fail fast unless that file exists and exports:
+
+- `asPositiveNumber`
+
+If the file exists and contains `asPositiveNumber` but does not export it correctly, the only allowed shared-file change is the minimum export-only fix.
+
+If the helper does not exist in the shared file, create ONLY this helper in `src/shared/utils/numberUtils.js` by copying one existing local implementation exactly, with no behavior change and no other edits to that file.
+
+## Exact Consumer Changes
+For each of the 6 listed consumer files:
+
+If the file contains a local function definition matching:
+```js
+function asPositiveNumber(value, fallback)
+```
+then:
+- remove the local `asPositiveNumber(value, fallback)` function definition
+- import `asPositiveNumber` from the correct relative path to:
+  - `src/shared/utils/numberUtils.js`
+- if the file already imports from that module, add `asPositiveNumber` 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 `asPositiveNumber`, leave it unchanged.
+
+## Relative Import Rule
+Use the correct relative path from each consumer file to:
+
+`src/shared/utils/numberUtils.js`
+
+Do not use aliases.
+Do not change `.js` extension usage.
+
+## Hard Constraints
+- no engine changes outside `src/shared/utils/numberUtils.js`
+- no game files outside the 6 listed consumers
+- no sample files
+- no repo-wide number helper cleanup
+- no behavior changes
+- keep one PR purpose only
+
+## Validation Checklist
+1. Confirm no more than the 7 listed files changed
+2. Confirm `src/shared/utils/numberUtils.js` exports `asPositiveNumber`
+3. Confirm local `function asPositiveNumber(value, fallback)` definitions no longer exist in changed listed consumer files
+4. Confirm changed consumer files import `asPositiveNumber` from the correct relative path to `src/shared/utils/numberUtils.js`
+5. Confirm no unrelated engine, game, or sample files changed
+6. Confirm no behavior changes were made
+
+## Non-Goals
+- no cleanup of `asPositiveInteger`
+- no cleanup of `asPositiveInt`
+- no cleanup outside the 6 listed consumer files
+- no refactor beyond this exact duplicate-removal batch
diff --git a/games/network_sample_a/game/FakeLoopbackNetworkModel.js b/games/network_sample_a/game/FakeLoopbackNetworkModel.js
@@ -6,17 +6,10 @@ FakeLoopbackNetworkModel.js
 */
 
 import { clamp } from '../../../src/engine/utils/math.js';
+import { asPositiveNumber } from '../../../src/shared/utils/numberUtils.js';
 
 const MAX_TRACE_EVENTS = 80;
 
-function asPositiveNumber(value, fallback) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) {
-    return fallback;
-  }
-  return numeric;
-}
-
 function normalizePhase(value) {
   const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
   if (normalized === "disconnected" || normalized === "connecting" || normalized === "synchronizing" || normalized === "connected") {
diff --git a/games/network_sample_a/game/NetworkSampleAScene.js b/games/network_sample_a/game/NetworkSampleAScene.js
@@ -7,6 +7,7 @@ NetworkSampleAScene.js
 import { Scene } from "../../../engine/scenes/index.js";
 import FakeLoopbackNetworkModel from "./FakeLoopbackNetworkModel.js";
 import { clamp } from "../../../src/engine/utils/math.js";
+import { asPositiveNumber } from "../../../src/shared/utils/numberUtils.js";
 
 const VIEW_WIDTH = 960;
 const VIEW_HEIGHT = 720;
@@ -19,14 +20,6 @@ const GOOD_COLOR = "#22c55e";
 const WARN_COLOR = "#f59e0b";
 const BAD_COLOR = "#ef4444";
 
-function asPositiveNumber(value, fallback) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) {
-    return fallback;
-  }
-  return numeric;
-}
-
 function getInputEdgePress(input, keyCode, edgeState) {
   if (!input || typeof input.isDown !== "function" || typeof keyCode !== "string") {
     return false;
diff --git a/games/network_sample_b/game/FakeHostClientNetworkModel.js b/games/network_sample_b/game/FakeHostClientNetworkModel.js
@@ -6,17 +6,10 @@ FakeHostClientNetworkModel.js
 */
 import FakeLoopbackNetworkModel from "../../network_sample_a/game/FakeLoopbackNetworkModel.js";
 import { clamp } from "../../../src/engine/utils/math.js";
+import { asPositiveNumber } from "../../../src/shared/utils/numberUtils.js";
 
 const MAX_TRACE_EVENTS = 120;
 
-function asPositiveNumber(value, fallback) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) {
-    return fallback;
-  }
-  return numeric;
-}
-
 function toConnectionState(peers) {
   const source = Array.isArray(peers) ? peers : [];
   if (source.length === 0) {
diff --git a/games/network_sample_b/game/NetworkSampleBScene.js b/games/network_sample_b/game/NetworkSampleBScene.js
diff --git a/games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js b/games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js
diff --git a/games/network_sample_c/game/NetworkSampleCScene.js b/games/network_sample_c/game/NetworkSampleCScene.js
diff --git a/src/shared/utils/numberUtils.js b/src/shared/utils/numberUtils.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD PR: centralize cloneJson across exact tools/dev + tools/shared batch.`
	`1`	`+BUILD PR: centralize asPositiveNumber across exact network sample batch.`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Next: run BUILD_PR_SHARED_EXTRACTION_32_IS_OBJECT_BATCH_RETRY after this batch.`
	`1`	`+Next: run BUILD_PR_SHARED_EXTRACTION_35_NETWORK_DEBUG_SERIALIZATION_BATCH after this batch.`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Replaced the blocked cloneJson BUILD with an execution-grade retry using the exact target file list from the duplicate report.`
	`1`	`+Execution-grade batch for asPositiveNumber using the exact duplicate-report file list.`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Exact file list present; no guessing; one PR purpose only.`
	`1`	`+Exact file list present; one PR purpose only; no guessing.`