Combine the Shared Foundation lane into one low-PR consolidation pass

BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,30 +2,42 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_02_2D_CAPABILITY_COMBINED_FOUNDATION` as one combined 2D capability PR.
+Create `BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS` as one combined Section-3 PR.
 
 Goal:
-Finish the 2D Engine Capability cluster in the fewest practical PRs.
+Finish as much of Shared Foundation (`src/shared`) as truthfully possible in one pass.
 
-Target items to close in this PR if truthfully possible:
-- 2D scene boot
-- 2D render loop
-- 2D camera
-- 2D tilemap integration
-- 2D collision patterns
-- 2D gameplay hooks
+Target items to close in this PR if supported:
+- 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
 
 Required work:
-1. Treat these as one coherent 2D engine slice, not six isolated tasks.
-2. Bundle the work logically:
-   - scene boot + render loop + gameplay hooks
-   - camera + tilemap integration
-   - collision patterns + gameplay hooks
-3. Reuse existing validated repo patterns where possible.
-4. Keep the implementation engine-facing and reusable.
-5. Avoid game-specific hacks unless they are already the accepted engine pattern.
-6. Close as many of the six items as truthfully possible in this one PR.
-7. If anything remains open:
+1. Treat the utility cluster as one lane:
+   - arrays
+   - strings
+   - ids
+   - shared math
+
+2. Treat the shared-state cluster as one lane:
+   - state guards
+   - state normalization
+   - selectors
+   - contracts
+
+3. Stabilize shared io/data/types enough to support and close as much of the above as possible.
+
+4. Reuse existing exact-cluster extraction patterns already established in the repo.
+
+5. Close as many Section-3 items as truthfully possible in this one PR.
+
+6. If anything remains open:
    - keep the residue very small
    - report exact blockers
    - leave it suitable for one residue-only PR
@@ -36,10 +48,10 @@ Roadmap:
 
 Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_LEVEL_02_2D_CAPABILITY_COMBINED_FOUNDATION.zip`
+  `<project folder>/tmp/BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS.zip`
 
 Hard rules:
 - combine aggressively to reduce PR count
-- coherent implementation over scattered edits
+- keep the changes coherent
 - no unrelated repo changes
 - no missing ZIP

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Combine the 2D engine capability foundation into one low-PR pass
-BUILD_PR_LEVEL_02_2D_CAPABILITY_COMBINED_FOUNDATION
+Combine the Shared Foundation lane into one low-PR consolidation pass
+BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_02_2D_CAPABILITY_RESIDUE_ONLY
+BUILD_PR_LEVEL_03_SHARED_FOUNDATION_RESIDUE_ONLY

docs/dev/reports/change_summary.txt

@@ -1,3 +1,3 @@
-- Added a combined PR for the full 2D Engine Capability cluster
-- Bundles scene boot, render loop, camera, tilemap, collision, and gameplay hooks
-- Intended to finish the 2D capability lane in one pass or leave only a tiny residue
+- Added a combined PR for the Section-3 Shared Foundation lane
+- Bundles utilities, shared math, shared state, contracts, and io/data/types stabilization
+- Intended to finish most or all of Section 3 in one pass and leave only tiny residue if needed

docs/dev/reports/validation_checklist.txt

@@ -1,10 +1,13 @@
-- 2D scene boot addressed
-- 2D render loop addressed
-- 2D camera addressed
-- 2D tilemap integration addressed
-- 2D collision patterns addressed
-- 2D gameplay hooks addressed
-- Any residue is explicit and minimal
-- Roadmap updated by status markers only
-- Output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_02_2D_CAPABILITY_COMBINED_FOUNDATION.zip
+- arrays utilities addressed
+- strings utilities addressed
+- ids utilities addressed
+- shared math addressed
+- shared state guards addressed
+- shared state normalization addressed
+- shared selectors addressed
+- shared contracts addressed
+- shared io/data/types addressed
+- any residue is explicit and minimal
+- roadmap updated by status markers only
+- output ZIP created at:
+  <project folder>/tmp/BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS.zip

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -176,15 +176,15 @@
 - [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
+- [x] arrays utilities consolidated
+- [x] strings utilities consolidated
+- [x] ids utilities consolidated
+- [x] shared math layer consolidated
+- [x] shared state guards consolidated
+- [x] shared state normalization consolidated
+- [x] shared selectors consolidated
+- [x] shared contracts consolidated
+- [x] shared io/data/types stabilized
 
 ### Duplicate / Rename Focus
 - [x] `asFiniteNumber` unified

docs/pr/BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS.md

@@ -0,0 +1,83 @@
+# BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS
+
+## Purpose
+Complete the Section-3 Shared Foundation lane in one coherent pass centered on `src/shared` boundaries and reusable contracts.
+
+## What was implemented
+
+### 1) Utility cluster consolidation
+- Arrays:
+  - `src/shared/utils/arrayUtils.js` now exposes `asArray` as the shared array-normalization surface.
+  - `src/shared/utils/objectUtils.js` now reuses array normalization from `arrayUtils` (removes duplicate array normalization behavior).
+- Strings:
+  - `src/shared/utils/stringUtils.js` now owns `escapeHtml`.
+  - `src/shared/string/stringUtil.js` is now a compatibility re-export surface from shared string utils.
+- IDs:
+  - `src/shared/utils/idUtils.js` normalized with shared helpers:
+    - `normalizeId`
+    - `createStableId`
+    - deterministic prefix-safe `createId` / `generateId`
+    - `isValidId`
+- Shared utility barrel:
+  - Added `src/shared/utils/index.js` as the consolidated public utility surface.
+- Shared math barrel:
+  - Added `src/shared/math/index.js` exposing number and vector shared math surfaces.
+
+### 2) Shared-state cluster consolidation
+- Added explicit shared-state contracts:
+  - `src/shared/contracts/sharedStateContracts.js`
+  - `src/shared/contracts/index.js`
+  - `src/shared/state/contracts.js` (state-facing contract bridge)
+- Added shared-state guards:
+  - `src/shared/state/guards.js`
+- Added shared-state normalization:
+  - `src/shared/state/normalization.js`
+- Added shared selectors surface:
+  - `src/shared/state/selectors.js`
+  - `src/shared/state/publicSelectors.js` now routes through selectors
+- Added shared-state barrel:
+  - `src/shared/state/index.js`
+- Updated promotion state accessor:
+  - `src/shared/state/getState.js` now uses shared normalization by default.
+
+### 3) Shared io/data/types stabilization
+- Added shared types:
+  - `src/shared/types/typeGuards.js`
+  - `src/shared/types/index.js`
+- Added shared data normalization:
+  - `src/shared/data/normalization.js`
+  - `src/shared/data/index.js`
+- Added shared io/json surface:
+  - `src/shared/io/jsonIO.js`
+  - `src/shared/io/index.js`
+- Added shared root barrel:
+  - `src/shared/index.js`
+
+## Section-3 completion status
+- Completed in this PR:
+  - 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
+- Remaining residue:
+  - no top-level Section-3 residue identified for the target item list.
+
+## Roadmap handling
+- Updated Section-3 status markers only in `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`.
+- No roadmap prose rewrites.
+
+## Validation run
+- `node --check` on all touched `src/shared/**/*.js` files
+- `node --check tests/shared/SharedFoundationCombinedPass.test.mjs`
+- `node --input-type=module -e "import { run } from './tests/shared/SharedFoundationCombinedPass.test.mjs'; run();"`
+- Focused non-regression checks:
+  - `node tests/core/Section1FinalResidueStructure.test.mjs`
+  - `node tests/render/Renderer.test.mjs`
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_03_SHARED_FOUNDATION_COMBINED_PASS.zip`

src/shared/contracts/index.js

@@ -0,0 +1,13 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+index.js
+*/
+export {
+  SHARED_PROMOTION_CONTRACT_ID,
+  SHARED_PROMOTION_CONTRACT_VERSION,
+  SHARED_PROMOTION_MODES,
+  SHARED_STATE_KEYS,
+  isSharedPromotionMode,
+} from "./sharedStateContracts.js";

src/shared/contracts/sharedStateContracts.js

@@ -0,0 +1,26 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+sharedStateContracts.js
+*/
+export const SHARED_PROMOTION_CONTRACT_ID = "toolbox.shared.state.promotion";
+export const SHARED_PROMOTION_CONTRACT_VERSION = "1.0.0";
+
+export const SHARED_PROMOTION_MODES = Object.freeze({
+  PASSIVE: "passive",
+  AUTHORITATIVE: "authoritative",
+});
+
+export const SHARED_STATE_KEYS = Object.freeze({
+  PROMOTED: "promoted",
+  STABLE_FRAMES: "stableFrames",
+  STABILITY_WINDOW_FRAMES: "stabilityWindowFrames",
+  LAST_REASON: "lastReason",
+  LAST_EVALUATION: "lastEvaluation",
+  STATUS: "status",
+});
+
+export function isSharedPromotionMode(value) {
+  return value === SHARED_PROMOTION_MODES.PASSIVE || value === SHARED_PROMOTION_MODES.AUTHORITATIVE;
+}

src/shared/data/index.js

@@ -0,0 +1,7 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+index.js
+*/
+export { normalizeRecord, normalizeArray, normalizeRecordArray } from "./normalization.js";