BUILD PR: executable helper extraction to shared (explicit file mapping).

DavidQ · DavidQ · commit 112227342de8 · 2026-04-08T12:48:17.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,11 +1,6 @@
-# docs/dev/codex_commands.md
-
-No Codex command included.
-
-Reason:
-This is a docs-only correction PLAN. The previous BUILD failed because the referenced target map was not executable.
-Do not send Codex another BUILD until the target map contains:
-- exact source files
-- exact destination files
-- exact source -> destination mapping
-- exact import-update targets
+MODEL: GPT-5.3-codex
+REASONING: high
+COMMAND:
+Execute EXACT helper moves as listed.
+Do not expand.
+Output zip to <project folder>/tmp/.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-PLAN PR: replace non-executable shared extraction target map with execution-grade target map requirements. No code changes.
+BUILD PR: executable helper extraction to shared (explicit file mapping).
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1,8 +1 @@
-Next step:
-Create an executable replacement for PLAN_PR_SHARED_EXTRACTION_02_TARGET_MAP with:
-1. exact source file list
-2. exact destination file list
-3. exact source->destination mapping
-4. exact import-update targets
-
-Do not issue another BUILD until all four are explicit.
+Proceed to APPLY_PR after validation.
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,3 +1 @@
-Created a docs-only correction PLAN after BUILD fail-fast.
-Recorded the exact blocker and defined the minimum execution-grade target map structure required before retrying BUILD.
-No code changes. No file moves. No runtime claims.
+Explicit helper extraction mapping created and executed.
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,11 +1,3 @@
-docs/
-  pr/
-    PLAN_PR_SHARED_EXTRACTION_02_EXECUTABLE_TARGET_MAP.md
-  dev/
-    codex_commands.md
-    commit_comment.txt
-    next_command.txt
-    reports/
-      change_summary.txt
-      validation_checklist.txt
-      file_tree.txt
+src/shared/utils/numberUtils.js
+src/shared/utils/objectUtils.js
+src/shared/state/getState.js
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,15 +1,4 @@
-SESSION VALIDATION GATE
-- Bundle type: PLAN
-- One PR purpose only: yes
-- BUILD command included: no
-- Repo scan requested: no
-- Vague execution language present: no
-- Code claims made: no
-- Start-of-day directories touched: no
-- ZIP repo-structured: yes
-
-PLAN-SPECIFIC CHECKS
-- Exact blocker captured: yes
-- Next required artifact defined: yes
-- Non-goals explicit: yes
-- Prevents premature BUILD retry: yes
+- No duplicates
+- Imports updated
+- Shared utils populated
+- Build passes
diff --git a/docs/pr/BUILD_PR_SHARED_EXTRACTION_02_EXACT_HELPER_MOVE.md b/docs/pr/BUILD_PR_SHARED_EXTRACTION_02_EXACT_HELPER_MOVE.md
@@ -1,21 +1,66 @@
-# BUILD_PR_SHARED_EXTRACTION_02_EXACT_HELPER_MOVE
+# BUILD_PR_SHARED_EXTRACTION_02_EXACT_HELPER_MOVE (EXECUTABLE)
 
-Purpose: Move duplicate helpers into src/shared using ONLY the target map.
+## Purpose
+Move duplicated helper functions into src/shared with ZERO guessing.
 
-Source of Truth:
-PLAN_PR_SHARED_EXTRACTION_02_TARGET_MAP
+## Exact Moves
 
-Rules:
-- DO NOT scan repo
-- ONLY use listed files
-- NO API changes
-- NO new helpers
+### asFiniteNumber
+FROM:
+- src/advanced/promotion/createPromotionGate.js
+- src/advanced/state/createWorldGameStateSystem.js
+- games/network_sample_c/game/ReconciliationLayerAdapter.js
 
-Instructions:
-- Move helpers exactly as defined in target map
-- Update imports only
+TO:
+- src/shared/utils/numberUtils.js
 
-Acceptance:
-- No duplicates remain
-- Imports valid
+### asPositiveInteger
+FROM:
+- src/advanced/promotion/createPromotionGate.js
+- src/advanced/state/createWorldGameStateSystem.js
+- games/network_sample_c/game/ReconciliationLayerAdapter.js
+- games/network_sample_c/game/StateTimelineBuffer.js
+- src/engine/debug/inspectors/shared/inspectorUtils.js
+
+TO:
+- src/shared/utils/numberUtils.js
+
+### isPlainObject
+FROM:
+- src/advanced/state/utils.js
+- src/advanced/state/events.js
+- src/advanced/state/initialState.js
+- src/advanced/state/transitions.js
+- src/advanced/promotion/createPromotionGate.js
+
+TO:
+- src/shared/utils/objectUtils.js
+
+### getState (ONLY shared system variants)
+FROM:
+- src/advanced/state/createWorldGameStateSystem.js
+- samples/shared/worldGameStateSystem.js
+
+TO:
+- src/shared/state/getState.js
+
+## Import Updates
+
+All moved helpers must:
+- remove local definition
+- import from src/shared path
+
+Example:
+import { asFiniteNumber } from "../../shared/utils/numberUtils.js";
+
+## Constraints
+- DO NOT scan repo further
+- DO NOT move additional helpers
+- DO NOT modify logic
+- DO NOT rename helpers
+
+## Acceptance
+- Helpers exist only in shared
+- No duplicate definitions remain
+- All imports updated
 - Build passes
diff --git a/games/network_sample_c/game/ReconciliationLayerAdapter.js b/games/network_sample_c/game/ReconciliationLayerAdapter.js
@@ -5,6 +5,7 @@ David Quesenberry
 ReconciliationLayerAdapter.js
 */
 import StateTimelineBuffer from "./StateTimelineBuffer.js";
+import { asFiniteNumber, asPositiveInteger } from "../../../src/shared/utils/numberUtils.js";
 
 const APPROVED_PUBLIC_EVENT_TYPES = new Set([
   "worldState.transition.applied",
@@ -14,19 +15,6 @@ const APPROVED_PUBLIC_EVENT_TYPES = new Set([
   "objective.snapshot.updated"
 ]);
 
-function asPositiveInteger(value, fallback) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) {
-    return fallback;
-  }
-  return Math.floor(numeric);
-}
-
-function asFiniteNumber(value, fallback = 0) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
 function sanitizeText(value, fallback = "") {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
diff --git a/games/network_sample_c/game/StateTimelineBuffer.js b/games/network_sample_c/game/StateTimelineBuffer.js
@@ -5,13 +5,7 @@ David Quesenberry
 StateTimelineBuffer.js
 */
 
-function asPositiveInteger(value, fallback) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) {
-    return fallback;
-  }
-  return Math.floor(numeric);
-}
+import { asPositiveInteger } from "../../../src/shared/utils/numberUtils.js";
 
 function normalizeFrameId(frameId) {
   const numeric = Number(frameId);
diff --git a/src/advanced/promotion/createPromotionGate.js b/src/advanced/promotion/createPromotionGate.js
@@ -5,19 +5,8 @@ David Quesenberry
 createPromotionGate.js
 */
 
-function asFiniteNumber(value, fallback = 0) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
-function asPositiveInteger(value, fallback = 1) {
-  const numeric = Math.floor(asFiniteNumber(value, fallback));
-  return numeric >= 1 ? numeric : fallback;
-}
-
-function isPlainObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
+import { asFiniteNumber, asPositiveInteger } from '../../shared/utils/numberUtils.js';
+import { isPlainObject } from '../../shared/utils/objectUtils.js';
 
 function normalizeCriteriaMap(input, requiredCriteria = []) {
   const normalized = {};
diff --git a/src/advanced/state/createWorldGameStateSystem.js b/src/advanced/state/createWorldGameStateSystem.js
@@ -18,6 +18,8 @@ import {
   createTransitionAppliedEvent,
   createTransitionRejectedEvent
 } from './events.js';
+import { getState as getSharedState } from '../../shared/state/getState.js';
+import { asPositiveInteger } from '../../shared/utils/numberUtils.js';
 import {
   cloneDeep,
   createReadonlyClone,
@@ -76,16 +78,6 @@ function resolveFrameFromMeta(meta, payload) {
   return null;
 }
 
-function asFiniteNumber(value, fallback = 0) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
-function asPositiveInteger(value, fallback = 1) {
-  const numeric = Math.floor(asFiniteNumber(value, fallback));
-  return numeric >= 1 ? numeric : fallback;
-}
-
 function normalizeRequiredCriteria(requiredCriteria) {
   if (!Array.isArray(requiredCriteria)) return [];
   const seen = new Set();
@@ -146,16 +138,6 @@ function createInlinePromotionGate({
     };
   }
 
-  function getState() {
-    return {
-      promoted,
-      stableFrames,
-      stabilityWindowFrames: windowFrames,
-      lastReason,
-      lastEvaluation: lastEvaluation ? cloneDeep(lastEvaluation) : null
-    };
-  }
-
   function evaluate({ criteria = {}, rollbackTriggered = false, transitionName = '', frame = null } = {}) {
     metrics.evaluations += 1;
     const timestampMs = Number(now());
@@ -238,7 +220,19 @@ function createInlinePromotionGate({
   return {
     evaluate,
     getMetrics,
-    getState
+    getState() {
+      const state = getSharedState({
+        promoted,
+        stableFrames,
+        stabilityWindowFrames: windowFrames,
+        lastReason,
+        lastEvaluation
+      });
+      return {
+        ...state,
+        lastEvaluation: state.lastEvaluation ? cloneDeep(state.lastEvaluation) : null
+      };
+    }
   };
 }
 
diff --git a/src/advanced/state/events.js b/src/advanced/state/events.js
@@ -9,7 +9,8 @@ import {
   WORLD_GAME_STATE_EVENT_TYPES,
   WORLD_GAME_STATE_SYSTEM_ID
 } from './constants.js';
-import { cloneDeep, isPlainObject } from './utils.js';
+import { cloneDeep } from './utils.js';
+import { isPlainObject } from '../../shared/utils/objectUtils.js';
 
 function createStateEventEnvelope({
   eventType,
diff --git a/src/advanced/state/initialState.js b/src/advanced/state/initialState.js
@@ -5,7 +5,8 @@ David Quesenberry
 initialState.js
 */
 
-import { isPlainObject, mergeDeep } from './utils.js';
+import { mergeDeep } from './utils.js';
+import { isPlainObject } from '../../shared/utils/objectUtils.js';
 
 function createInitialWorldGameState(initialPatch = {}) {
   const baseline = {
diff --git a/src/advanced/state/transitions.js b/src/advanced/state/transitions.js
@@ -6,7 +6,7 @@ transitions.js
 */
 
 import { WORLD_GAME_STATE_EVENT_TYPES } from './constants.js';
-import { isPlainObject } from './utils.js';
+import { isPlainObject } from '../../shared/utils/objectUtils.js';
 
 function toFiniteNumber(value, fallback = 0) {
   const numeric = Number(value);
diff --git a/src/advanced/state/utils.js b/src/advanced/state/utils.js
@@ -5,9 +5,7 @@ David Quesenberry
 utils.js
 */
 
-function isPlainObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
+import { isPlainObject } from '../../shared/utils/objectUtils.js';
 
 function cloneDeep(value) {
   if (Array.isArray(value)) {
diff --git a/src/engine/debug/inspectors/shared/inspectorUtils.js b/src/engine/debug/inspectors/shared/inspectorUtils.js
@@ -5,6 +5,8 @@ David Quesenberry
 inspectorUtils.js
 */
 
+import { asPositiveInteger } from "../../../../shared/utils/numberUtils.js";
+
 export function sanitizeText(value) {
   return typeof value === "string" ? value.trim() : "";
 }
@@ -28,10 +30,7 @@ export function asNonNegativeInteger(value, fallback = 0) {
   return normalized >= 0 ? normalized : Math.max(0, Math.floor(asFinite(fallback, 0)));
 }
 
-export function asPositiveInteger(value, fallback = 1) {
-  const normalized = Math.floor(asFinite(value, fallback));
-  return normalized > 0 ? normalized : Math.max(1, Math.floor(asFinite(fallback, 1)));
-}
+export { asPositiveInteger };
 
 export function cloneJson(value) {
   if (typeof structuredClone === "function") {
diff --git a/src/shared/state/getState.js b/src/shared/state/getState.js
@@ -0,0 +1,24 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/08/2026
+getState.js
+*/
+
+function getState({
+  promoted,
+  stableFrames,
+  stabilityWindowFrames,
+  lastReason,
+  lastEvaluation
+}) {
+  return {
+    promoted,
+    stableFrames,
+    stabilityWindowFrames,
+    lastReason,
+    lastEvaluation: lastEvaluation || null
+  };
+}
+
+export { getState };
diff --git a/src/shared/utils/numberUtils.js b/src/shared/utils/numberUtils.js
@@ -0,0 +1,21 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/08/2026
+numberUtils.js
+*/
+
+function asFiniteNumber(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function asPositiveInteger(value, fallback = 1) {
+  const numeric = Math.floor(asFiniteNumber(value, fallback));
+  return numeric >= 1 ? numeric : fallback;
+}
+
+export {
+  asFiniteNumber,
+  asPositiveInteger
+};
diff --git a/src/shared/utils/objectUtils.js b/src/shared/utils/objectUtils.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-PLAN PR: replace non-executable shared extraction target map with execution-grade target map requirements. No code changes.`
	`1`	`+BUILD PR: executable helper extraction to shared (explicit file mapping).`