Merge pull request #206 from ToolboxAid/PR_26177_DELTA_054-random-utility

PR_26177_DELTA_054-random-utility

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -1,31 +1,42 @@
-# PR_26177_DELTA_053-random-shared-helpers
+# PR_26177_DELTA_054-random-utility
 
 ## Purpose
 
-Create shared internal helper logic for random utility operations.
+Add a nondeterministic `Random` utility with the same public convenience API shape as `RandomSeed`.
 
 ## 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_053-random-shared-helpers`.
+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_054-random-utility`.
 
 ## OWNER Override And Team Assignment
 
-OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_053-random-shared-helpers`.
+OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_054-random-utility`.
 
 Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage.
 
+## Stack
+
+- Base branch: `PR_26177_DELTA_053-random-shared-helpers`
+- This PR depends on the internal random helper module from PR_053.
+
 ## Exact Scope
 
-- 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 `Random` utility.
+- Include:
+  - `Random.next()`
+  - `Random.nextInt(min, max)`
+  - `Random.nextFloat(min, max)`
+  - `Random.pick(array)`
+  - `Random.shuffle(array)`
+  - `Random.chance(percent)`
+  - `Random.weightedPick(weightedItems)`
+  - `Random.uuid()`
+- Prefer `crypto.getRandomValues()` when available.
+- Use `Math.random()` only as compatibility fallback.
+- No deterministic seed support in `Random`.
+- No browser storage.
+- No UI changes.
+- Add JSDoc.
 - Add targeted unit tests.
 - Create required Codex reports under `docs_build/dev/reports/`.
 - Create repo-structured delta ZIP under `tmp/`.
@@ -36,21 +47,21 @@ 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/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`
+- `src/shared/math/Random.js`
+- `tests/shared/Random.test.mjs`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_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 deterministic seed support in `Random`.
+- No existing game logic adoption changes.
 - No existing `Math.random()` call-site replacements.
 - No UI changes.
 - No browser storage changes.
@@ -64,9 +75,9 @@ Team Delta owns Shared JS, runtime utilities, technical debt remediation, and ru
 Run exactly:
 
 ```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
+node ./scripts/run-node-test-files.mjs tests/shared/Random.test.mjs tests/shared/RandomHelpers.test.mjs
+node --check src/shared/math/Random.js
+node --check tests/shared/Random.test.mjs
 git diff --check
 ```
 
@@ -77,5 +88,5 @@ Playwright is not required because this PR does not change UI or browser runtime
 Create repo-structured delta ZIP:
 
 ```text
-tmp/PR_26177_DELTA_053-random-shared-helpers_delta.zip
+tmp/PR_26177_DELTA_054-random-utility_delta.zip
 ```

docs_build/dev/PLAN_PR.md

@@ -1,40 +1,46 @@
-# PLAN_PR: PR_26177_DELTA_053-random-shared-helpers
+# PLAN_PR: PR_26177_DELTA_054-random-utility
 
 ## Purpose
 
-Create shared internal helper logic for random utility operations.
+Add a nondeterministic `Random` utility with the same public convenience API shape as `RandomSeed`.
 
 ## Owner And Assignment
 
 - Team: Delta
-- 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.
+- OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_054-random-utility`.
+- Stack base: `PR_26177_DELTA_053-random-shared-helpers`.
 
 ## Scope
 
-- 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 `Random` utility.
+- Include:
+  - `Random.next()`
+  - `Random.nextInt(min, max)`
+  - `Random.nextFloat(min, max)`
+  - `Random.pick(array)`
+  - `Random.shuffle(array)`
+  - `Random.chance(percent)`
+  - `Random.weightedPick(weightedItems)`
+  - `Random.uuid()`
+- Prefer `crypto.getRandomValues()` when available.
+- Use `Math.random()` only as compatibility fallback.
+- No deterministic seed support in `Random`.
+- No browser storage.
+- No UI changes.
+- Add JSDoc.
 - Add targeted unit tests.
 
 ## Implementation Plan
 
-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.
+1. Add `src/shared/math/Random.js`.
+2. Reuse internal helper functions from `src/shared/math/randomHelpers.js`.
+3. Add `tests/shared/Random.test.mjs`.
+4. Validate crypto preference, Math fallback, utility methods, UUID shape, and absence of seed API.
 5. Produce required PR reports and repo-structured ZIP.
 
 ## Acceptance Criteria
 
-- 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.
+- `Random` exposes the required static convenience methods.
+- `Random` does not expose deterministic seed support.
+- `Random` uses `crypto.getRandomValues()` when available.
+- `Math.random()` is used only when crypto random values are unavailable.

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_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 Delta | PR_26177_DELTA_054-random-utility | PR_26177_DELTA_054-random-utility | PR_26177_DELTA_054-random-utility | Active | OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_054-random-utility |
 | 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_053-random-shared-helpers | PR_26177_DELTA_053-random-shared-helpers | PR_26177_DELTA_053-random-shared-helpers | Active |
+| Team Delta | PR_26177_DELTA_054-random-utility | PR_26177_DELTA_054-random-utility | PR_26177_DELTA_054-random-utility | 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_053-random-shared-helpers.
+Active assignment: PR_26177_DELTA_054-random-utility.
 
-Active branch: PR_26177_DELTA_053-random-shared-helpers.
+Active branch: PR_26177_DELTA_054-random-utility.
 
-Active PR: PR_26177_DELTA_053-random-shared-helpers.
+Active PR: PR_26177_DELTA_054-random-utility.
 
-OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_053-random-shared-helpers.
+OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_054-random-utility.
 
 ## Team Bravo
 

docs_build/dev/reports/PR_26177_DELTA_054-random-utility.md

@@ -0,0 +1,50 @@
+# PR_26177_DELTA_054-random-utility
+
+Date: 2026-06-26
+Team: Delta
+Scope: Nondeterministic shared Random utility and targeted unit tests
+Status: PASS
+
+## Summary
+
+- Added `Random` as a nondeterministic shared random utility in `src/shared/math/Random.js`.
+- Added static convenience methods matching the public shape requested: `next`, `nextInt`, `nextFloat`, `pick`, `shuffle`, `chance`, `weightedPick`, and `uuid`.
+- Reused internal helper logic from PR_053.
+- Preferred `crypto.getRandomValues()` when available.
+- Used `Math.random()` only as compatibility fallback when crypto random values are unavailable.
+- Did not add deterministic seed support to `Random`.
+- Added targeted unit tests in `tests/shared/Random.test.mjs`.
+- No browser storage, UI, API, database, or existing game logic adoption changes were made.
+
+## Branch Validation
+
+PASS. Branch `PR_26177_DELTA_054-random-utility` was created from `PR_26177_DELTA_053-random-shared-helpers`.
+
+## 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/Random.js`
+- `tests/shared/Random.test.mjs`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_054-random-utility_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/Random.test.mjs tests/shared/RandomHelpers.test.mjs`
+- PASS: `node --check src/shared/math/Random.js`
+- PASS: `node --check tests/shared/Random.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_054-random-utility_delta.zip`

docs_build/dev/reports/PR_26177_DELTA_054-random-utility_branch-validation.md

@@ -0,0 +1,15 @@
+# PR_26177_DELTA_054-random-utility Branch Validation
+
+Status: PASS
+
+## Start Gates
+
+- PASS: PR_054 branch was created from `PR_26177_DELTA_053-random-shared-helpers`.
+- PASS: Stack base was clean before branch creation.
+- PASS: Branch name is `PR_26177_DELTA_054-random-utility`.
+
+## Scope Confirmation
+
+- PASS: Work is assigned to Team Delta.
+- PASS: Work is limited to nondeterministic Random utility, targeted tests, PR docs, reports, and ZIP packaging.
+- PASS: No deterministic seed support, UI, browser storage, API, database, or unrelated cleanup changes were made.

docs_build/dev/reports/PR_26177_DELTA_054-random-utility_instruction-compliance-checklist.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_054-random-utility Instruction Compliance Checklist
+
+| Instruction | Status | Notes |
+|---|---:|---|
+| Continue stacked Random PR sequence | PASS | Branch was created from PR_053. |
+| Keep one PR purpose only | PASS | Scope is nondeterministic Random utility. |
+| Use shared helper logic from PR_053 | PASS | Random delegates convenience methods to `randomHelpers.js`. |
+| Do not add deterministic seed support | PASS | No seed API or seed state was added. |
+| No UI/browser storage/API/database changes | PASS | No such files or behaviors changed. |
+| 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_054-random-utility_delta.zip`. |

docs_build/dev/reports/PR_26177_DELTA_054-random-utility_manual-validation-notes.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_054-random-utility Manual Validation Notes
+
+Status: PASS
+
+Manual review confirmed:
+
+- `Random` is nondeterministic and does not support seeding.
+- `Random` prefers `crypto.getRandomValues()` and falls back to `Math.random()` only when crypto random values are unavailable.
+- Public methods match the requested convenience API shape.
+- `Random` does not use browser storage and is not wired into UI or existing game logic.
+- Tests mock crypto and Math fallback sources and restore globals after assertions.

docs_build/dev/reports/PR_26177_DELTA_054-random-utility_requirement-checklist.md

@@ -0,0 +1,20 @@
+# PR_26177_DELTA_054-random-utility Requirement Checklist
+
+| Requirement | Status | Notes |
+|---|---:|---|
+| Add `Random` utility | PASS | Added `src/shared/math/Random.js`. |
+| Include `Random.next()` | PASS | Static method added. |
+| Include `Random.nextInt(min, max)` | PASS | Static method added using shared helper. |
+| Include `Random.nextFloat(min, max)` | PASS | Static method added using shared helper. |
+| Include `Random.pick(array)` | PASS | Static method added using shared helper. |
+| Include `Random.shuffle(array)` | PASS | Static method added using shared helper. |
+| Include `Random.chance(percent)` | PASS | Static method added using shared helper. |
+| Include `Random.weightedPick(weightedItems)` | PASS | Static method added using shared helper. |
+| Include `Random.uuid()` | PASS | Static RFC 4122 v4 UUID method added. |
+| Prefer `crypto.getRandomValues()` when available | PASS | `Random.next()` and `Random.uuid()` use crypto random values when present. |
+| Use `Math.random()` only as compatibility fallback | PASS | Fallback path is used only when crypto random values are unavailable. |
+| No deterministic seed support in `Random` | PASS | No `seed` method or seed state added. |
+| No browser storage | PASS | No storage usage added. |
+| No UI changes | PASS | No UI files changed. |
+| Add JSDoc | PASS | Added class and public method JSDoc. |
+| Add targeted unit tests | PASS | Added `tests/shared/Random.test.mjs`. |

docs_build/dev/reports/PR_26177_DELTA_054-random-utility_validation-lane.md

@@ -0,0 +1,24 @@
+# PR_26177_DELTA_054-random-utility Validation Lane
+
+Status: PASS
+
+## Commands
+
+```powershell
+node ./scripts/run-node-test-files.mjs tests/shared/Random.test.mjs tests/shared/RandomHelpers.test.mjs
+node --check src/shared/math/Random.js
+node --check tests/shared/Random.test.mjs
+git diff --check
+```
+
+## Results
+
+- PASS: `tests/shared/Random.test.mjs`
+- PASS: `tests/shared/RandomHelpers.test.mjs`
+- PASS: `src/shared/math/Random.js` syntax check
+- PASS: `tests/shared/Random.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.