Merge pull request #205 from ToolboxAid/PR_26177_DELTA_053-random-shared-helpers

PR_26177_DELTA_053-random-shared-helpers

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -1,38 +1,32 @@
-# PR_26177_DELTA_052-random-seed-utility
+# PR_26177_DELTA_053-random-shared-helpers
 
 ## Purpose
 
-Add a reusable shared JavaScript `RandomSeed` utility for deterministic seeded random sequences.
+Create shared internal helper logic for random utility operations.
 
 ## Source Of Truth
 
-This `BUILD_PR.md`, `PLAN_PR.md`, the user request, and `docs_build/dev/ProjectInstructions.zip` are the source of truth for `PR_26177_DELTA_052-random-seed-utility`.
+This `BUILD_PR.md`, `PLAN_PR.md`, the user request, and `docs_build/dev/ProjectInstructions.zip` are the source of truth for `PR_26177_DELTA_053-random-shared-helpers`.
 
 ## OWNER Override And Team Assignment
 
-OWNER override approved: Assign Team Delta `PR_26177_DELTA_052-random-seed-utility`.
+OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_053-random-shared-helpers`.
 
 Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage.
 
 ## Exact Scope
 
-- Add reusable shared JavaScript utility class named `RandomSeed`.
-- Constructor accepts an initial seed.
-- Include:
-  - `seed(value)`
-  - `next()`
-  - `nextInt(min, max)`
-  - `nextFloat(min, max)`
-  - `pick(array)`
-- Same seed must reproduce the same sequence after reseeding.
-- Different seeds should produce different sequences.
-- Add JSDoc.
+- Add internal/shared helper functions for:
+  - `nextInt(randomNext, min, max)`
+  - `nextFloat(randomNext, min, max)`
+  - `pick(randomNext, array)`
+  - `shuffle(randomNext, array)`
+  - `chance(randomNext, percent)`
+  - `weightedPick(randomNext, weightedItems)`
+- Helper must consume a `randomNext` function returning float `>= 0` and `< 1`.
+- Do not expose this as Creator-facing API.
+- Do not change existing `RandomSeed` behavior.
 - Add targeted unit tests.
-- Do not replace existing `Math.random()` usage.
-- No UI changes.
-- No browser storage.
-- No API/database changes.
-- No unrelated cleanup.
 - Create required Codex reports under `docs_build/dev/reports/`.
 - Create repo-structured delta ZIP under `tmp/`.
 
@@ -42,25 +36,26 @@ Team Delta owns Shared JS, runtime utilities, technical debt remediation, and ru
 - `docs_build/dev/BUILD_PR.md`
 - `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md`
 - `docs_build/dev/ProjectInstructions/team_assignments/ACTIVE_TEAM_REGISTRY.md`
-- `src/shared/math/RandomSeed.js`
-- `tests/shared/RandomSeed.test.mjs`
-- `docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility.md`
-- `docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_branch-validation.md`
-- `docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_requirement-checklist.md`
-- `docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_validation-lane.md`
-- `docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_manual-validation-notes.md`
-- `docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_instruction-compliance-checklist.md`
+- `src/shared/math/randomHelpers.js`
+- `tests/shared/RandomHelpers.test.mjs`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_instruction-compliance-checklist.md`
 - `docs_build/dev/reports/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
 ## Out Of Scope
 
+- No Creator-facing API exposure.
+- No existing `RandomSeed` behavior changes.
 - No existing `Math.random()` call-site replacements.
 - No UI changes.
 - No browser storage changes.
 - No API changes.
 - No database changes.
-- No engine core changes outside the new shared utility.
 - No `start_of_day` folder changes.
 - No unrelated cleanup.
 
@@ -69,18 +64,18 @@ Team Delta owns Shared JS, runtime utilities, technical debt remediation, and ru
 Run exactly:
 
 ```powershell
-node ./scripts/run-node-test-files.mjs tests/shared/RandomSeed.test.mjs
-node --check src/shared/math/RandomSeed.js
-node --check tests/shared/RandomSeed.test.mjs
+node ./scripts/run-node-test-files.mjs tests/shared/RandomHelpers.test.mjs tests/shared/RandomSeed.test.mjs
+node --check src/shared/math/randomHelpers.js
+node --check tests/shared/RandomHelpers.test.mjs
 git diff --check
 ```
 
-Playwright is not required because this PR does not change UI or browser runtime behavior.
+Playwright is not required because this PR does not change UI or browser runtime flows.
 
 ## Artifact
 
 Create repo-structured delta ZIP:
 
 ```text
-tmp/PR_26177_DELTA_052-random-seed-utility_delta.zip
+tmp/PR_26177_DELTA_053-random-shared-helpers_delta.zip
 ```

docs_build/dev/PLAN_PR.md

@@ -1,48 +1,40 @@
-# PLAN_PR: PR_26177_DELTA_052-random-seed-utility
+# PLAN_PR: PR_26177_DELTA_053-random-shared-helpers
 
 ## Purpose
 
-Add a reusable shared JavaScript `RandomSeed` utility for deterministic seeded random sequences.
+Create shared internal helper logic for random utility operations.
 
 ## Owner And Assignment
 
 - Team: Delta
-- OWNER override approved: Assign Team Delta `PR_26177_DELTA_052-random-seed-utility`.
+- OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_053-random-shared-helpers`.
 - Ownership fit: Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage.
 
 ## Scope
 
-- Add a shared JavaScript utility class named `RandomSeed`.
-- Constructor accepts an initial seed.
-- Include:
-  - `seed(value)`
-  - `next()`
-  - `nextInt(min, max)`
-  - `nextFloat(min, max)`
-  - `pick(array)`
-- Add JSDoc for the utility and public methods.
+- Add internal/shared helper functions for:
+  - `nextInt(randomNext, min, max)`
+  - `nextFloat(randomNext, min, max)`
+  - `pick(randomNext, array)`
+  - `shuffle(randomNext, array)`
+  - `chance(randomNext, percent)`
+  - `weightedPick(randomNext, weightedItems)`
+- Helper functions must consume a `randomNext` function returning a float `>= 0` and `< 1`.
+- Do not expose these helpers as Creator-facing API.
+- Do not change existing `RandomSeed` behavior.
 - Add targeted unit tests.
-- Do not replace existing `Math.random()` usage.
-- No UI changes.
-- No browser storage.
-- No API/database changes.
-- No unrelated cleanup.
 
 ## Implementation Plan
 
-1. Add `src/shared/math/RandomSeed.js`.
-2. Add `tests/shared/RandomSeed.test.mjs`.
-3. Validate deterministic reseeding, different-seed divergence, numeric ranges, and array picking.
-4. Run targeted unit tests for `RandomSeed`.
-5. Run changed-file syntax checks for the new JS and test files.
-6. Produce required reports and repo-structured ZIP.
+1. Add `src/shared/math/randomHelpers.js`.
+2. Add `tests/shared/RandomHelpers.test.mjs`.
+3. Validate helper behavior and input guards with targeted unit tests.
+4. Preserve current `RandomSeed` implementation and tests unchanged.
+5. Produce required PR reports and repo-structured ZIP.
 
 ## Acceptance Criteria
 
-- Same seed reproduces the same sequence after reseeding.
-- Different seeds produce different sequences.
-- `next()` returns deterministic normalized values.
-- `nextInt(min, max)` returns deterministic inclusive integers inside range.
-- `nextFloat(min, max)` returns deterministic floats inside range.
-- `pick(array)` returns deterministic values from the provided array.
-- Existing `Math.random()` usage remains unchanged.
+- Helpers use only the supplied `randomNext` source.
+- Integer, float, pick, shuffle, chance, and weighted pick operations are covered.
+- Invalid `randomNext`, ranges, arrays, percentages, and weighted item inputs reject predictably.
+- Existing `RandomSeed` behavior remains unchanged.

docs_build/dev/ProjectInstructions/team_assignments/ACTIVE_TEAM_REGISTRY.md

@@ -31,7 +31,7 @@ If a team has no assignment, no active branch, and no active PR, it is inactive
 | Team Alfa | none | none | none | Available | Active ownership lane |
 | Team Bravo | none | none | none | Available | Active ownership lane |
 | Team Charlie | none | none | none | Available | Active ownership lane |
-| Team Delta | PR_26177_DELTA_052-random-seed-utility | PR_26177_DELTA_052-random-seed-utility | PR_26177_DELTA_052-random-seed-utility | Active | OWNER override approved: Assign Team Delta PR_26177_DELTA_052-random-seed-utility |
+| Team Delta | PR_26177_DELTA_053-random-shared-helpers | PR_26177_DELTA_053-random-shared-helpers | PR_26177_DELTA_053-random-shared-helpers | Active | OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_053-random-shared-helpers |
 | Team Golf | none | none | none | Available | Replacement active ownership lane for retired Team Gamma |
 | Team OWNER | none | none | none | Available | Governance Phase 1 complete |
 

docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md

@@ -7,7 +7,7 @@
 | Team Alfa | none | none | none | Available |
 | Team Bravo | none | none | none | Available |
 | Team Charlie | none | none | none | Available |
-| Team Delta | PR_26177_DELTA_052-random-seed-utility | PR_26177_DELTA_052-random-seed-utility | PR_26177_DELTA_052-random-seed-utility | Active |
+| Team Delta | PR_26177_DELTA_053-random-shared-helpers | PR_26177_DELTA_053-random-shared-helpers | PR_26177_DELTA_053-random-shared-helpers | Active |
 | Team Golf | none | none | none | Available |
 | Team OWNER | none | none | none | Available |
 
@@ -50,13 +50,13 @@ Current OWNER clarification:
 
 Status: Active
 
-Active assignment: PR_26177_DELTA_052-random-seed-utility.
+Active assignment: PR_26177_DELTA_053-random-shared-helpers.
 
-Active branch: PR_26177_DELTA_052-random-seed-utility.
+Active branch: PR_26177_DELTA_053-random-shared-helpers.
 
-Active PR: PR_26177_DELTA_052-random-seed-utility.
+Active PR: PR_26177_DELTA_053-random-shared-helpers.
 
-OWNER override approved: Assign Team Delta PR_26177_DELTA_052-random-seed-utility.
+OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_053-random-shared-helpers.
 
 ## Team Bravo
 

docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers.md

@@ -0,0 +1,49 @@
+# PR_26177_DELTA_053-random-shared-helpers
+
+Date: 2026-06-26
+Team: Delta
+Scope: Shared internal random helper logic and targeted unit tests
+Status: PASS
+
+## Summary
+
+- Added internal shared random helper functions in `src/shared/math/randomHelpers.js`.
+- Added helpers for `nextInt`, `nextFloat`, `pick`, `shuffle`, `chance`, and `weightedPick`.
+- Helpers consume caller-provided `randomNext` functions returning floats `>= 0` and `< 1`.
+- Kept helpers as shared internal code only; no Creator-facing API was added.
+- Preserved existing `RandomSeed` behavior and did not change its implementation in this PR.
+- Added targeted unit tests in `tests/shared/RandomHelpers.test.mjs`.
+- Updated Team Delta active assignment metadata for the stacked random utility workstream.
+
+## Branch Validation
+
+PASS. Branch `PR_26177_DELTA_053-random-shared-helpers` was created from clean synchronized `main` after PR_052 merged.
+
+## Changed Files
+
+- `docs_build/dev/PLAN_PR.md`
+- `docs_build/dev/BUILD_PR.md`
+- `docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md`
+- `docs_build/dev/ProjectInstructions/team_assignments/ACTIVE_TEAM_REGISTRY.md`
+- `src/shared/math/randomHelpers.js`
+- `tests/shared/RandomHelpers.test.mjs`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_instruction-compliance-checklist.md`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/codex_review.diff`
+
+## Validation
+
+- PASS: `node ./scripts/run-node-test-files.mjs tests/shared/RandomHelpers.test.mjs tests/shared/RandomSeed.test.mjs`
+- PASS: `node --check src/shared/math/randomHelpers.js`
+- PASS: `node --check tests/shared/RandomHelpers.test.mjs`
+- PASS: `git diff --check`
+- SKIP: Playwright was not run because this PR does not change UI or browser runtime flows.
+
+## Artifact
+
+- `tmp/PR_26177_DELTA_053-random-shared-helpers_delta.zip`

docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_branch-validation.md

@@ -0,0 +1,16 @@
+# PR_26177_DELTA_053-random-shared-helpers Branch Validation
+
+Status: PASS
+
+## Start Gates
+
+- PASS: PR_052 was merged before starting PR_053.
+- PASS: Current branch was `main` before creating PR_053.
+- PASS: `main` worktree was clean and synchronized with `origin/main`.
+- PASS: Branch `PR_26177_DELTA_053-random-shared-helpers` was created from `main`.
+
+## Scope Confirmation
+
+- PASS: Work is assigned to Team Delta.
+- PASS: Work is limited to shared internal random helper logic, targeted tests, PR docs, reports, and ZIP packaging.
+- PASS: No Creator-facing API, UI, browser storage, API, database, or unrelated cleanup changes were made.

docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_instruction-compliance-checklist.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_053-random-shared-helpers Instruction Compliance Checklist
+
+| Instruction | Status | Notes |
+|---|---:|---|
+| Read `ProjectInstructions.zip` and `README.txt` first | PASS | Read `ProjectInstructions/README.txt` before work. |
+| Merge PR_052 before starting stacked PRs | PASS | PR #204 was merged and `main` synced first. |
+| Keep one PR purpose only | PASS | Scope is shared internal random helper logic. |
+| Use Team Delta ownership | PASS | Team Delta owns Shared JS and runtime test coverage. |
+| Do not expose Creator-facing API | PASS | No Creator-facing surface was added. |
+| Produce required reports | PASS | Reports were added under `docs_build/dev/reports/`. |
+| Produce repo-structured ZIP under `tmp/` | PASS | ZIP path is `tmp/PR_26177_DELTA_053-random-shared-helpers_delta.zip`. |

docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_manual-validation-notes.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_053-random-shared-helpers Manual Validation Notes
+
+Status: PASS
+
+Manual review confirmed:
+
+- Helper functions are shared internal JavaScript utilities under `src/shared/math/`.
+- The helpers are not wired into existing game logic or Creator-facing surfaces.
+- Existing `RandomSeed` behavior was preserved by leaving `RandomSeed.js` unchanged in this PR.
+- Unit tests cover deterministic helper behavior and input validation.
+- No browser storage, UI, API, database, or `start_of_day` files changed.

docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_requirement-checklist.md

@@ -0,0 +1,14 @@
+# PR_26177_DELTA_053-random-shared-helpers Requirement Checklist
+
+| Requirement | Status | Notes |
+|---|---:|---|
+| Add `nextInt(randomNext, min, max)` helper | PASS | Added in `src/shared/math/randomHelpers.js`. |
+| Add `nextFloat(randomNext, min, max)` helper | PASS | Added in `src/shared/math/randomHelpers.js`. |
+| Add `pick(randomNext, array)` helper | PASS | Added in `src/shared/math/randomHelpers.js`. |
+| Add `shuffle(randomNext, array)` helper | PASS | Added in `src/shared/math/randomHelpers.js`. |
+| Add `chance(randomNext, percent)` helper | PASS | Added in `src/shared/math/randomHelpers.js`. |
+| Add `weightedPick(randomNext, weightedItems)` helper | PASS | Added in `src/shared/math/randomHelpers.js`. |
+| Helpers consume `randomNext` returning float `>= 0` and `< 1` | PASS | Helpers validate `randomNext` output before use. |
+| Do not expose as Creator-facing API | PASS | No UI, tool, or barrel export exposure was added. |
+| Do not change existing `RandomSeed` behavior | PASS | `RandomSeed.js` was not changed in this PR; existing test passed. |
+| Add targeted unit tests | PASS | Added `tests/shared/RandomHelpers.test.mjs`. |

docs_build/dev/reports/PR_26177_DELTA_053-random-shared-helpers_validation-lane.md

@@ -0,0 +1,24 @@
+# PR_26177_DELTA_053-random-shared-helpers Validation Lane
+
+Status: PASS
+
+## Commands
+
+```powershell
+node ./scripts/run-node-test-files.mjs tests/shared/RandomHelpers.test.mjs tests/shared/RandomSeed.test.mjs
+node --check src/shared/math/randomHelpers.js
+node --check tests/shared/RandomHelpers.test.mjs
+git diff --check
+```
+
+## Results
+
+- PASS: `tests/shared/RandomHelpers.test.mjs`
+- PASS: `tests/shared/RandomSeed.test.mjs`
+- PASS: `src/shared/math/randomHelpers.js` syntax check
+- PASS: `tests/shared/RandomHelpers.test.mjs` syntax check
+- PASS: `git diff --check`
+
+## Playwright
+
+SKIP. Playwright was not run because this PR does not change UI or browser runtime flows.