DELTA: enhance random seed utility

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -1,43 +1,39 @@
-# PR_26177_DELTA_054-random-utility
+# PR_26177_DELTA_055-random-seed-enhancements
 
 ## Purpose
 
-Add a nondeterministic `Random` utility with the same public convenience API shape as `RandomSeed`.
+Enhance `RandomSeed` with matching procedural convenience methods.
 
 ## 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_054-random-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_055-random-seed-enhancements`.
 
 ## OWNER Override And Team Assignment
 
-OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_054-random-utility`.
+OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_055-random-seed-enhancements`.
 
 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.
+- Base branch: `PR_26177_DELTA_054-random-utility`
+- This PR depends on the shared helper module from PR_053 and the stack context from PR_054.
 
 ## Exact Scope
 
-- 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.
+- Update `RandomSeed` to use shared helper logic where appropriate.
+- Add:
+  - `shuffle(array)`
+  - `chance(percent)`
+  - `weightedPick(weightedItems)`
+  - `saveState()`
+  - `restoreState(state)`
+- Preserve existing `RandomSeed` sequence compatibility.
+- Same seed must still reproduce same sequence.
+- Reseeding must still reproduce same sequence.
+- Add targeted unit tests for new methods.
+- No adoption changes in existing game logic.
 - 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/`.
 
@@ -47,22 +43,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/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`
+- `src/shared/math/RandomSeed.js`
+- `tests/shared/RandomSeed.test.mjs`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_instruction-compliance-checklist.md`
 - `docs_build/dev/reports/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
 ## Out Of Scope
 
-- No deterministic seed support in `Random`.
+- No seeded `next()` algorithm changes.
 - No existing game logic adoption changes.
-- No existing `Math.random()` call-site replacements.
 - No UI changes.
 - No browser storage changes.
 - No API changes.
@@ -75,9 +70,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/Random.test.mjs tests/shared/RandomHelpers.test.mjs
-node --check src/shared/math/Random.js
-node --check tests/shared/Random.test.mjs
+node ./scripts/run-node-test-files.mjs tests/shared/RandomSeed.test.mjs tests/shared/RandomHelpers.test.mjs
+node --check src/shared/math/RandomSeed.js
+node --check tests/shared/RandomSeed.test.mjs
 git diff --check
 ```
 
@@ -88,5 +83,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_054-random-utility_delta.zip
+tmp/PR_26177_DELTA_055-random-seed-enhancements_delta.zip
 ```

docs_build/dev/PLAN_PR.md

@@ -1,46 +1,42 @@
-# PLAN_PR: PR_26177_DELTA_054-random-utility
+# PLAN_PR: PR_26177_DELTA_055-random-seed-enhancements
 
 ## Purpose
 
-Add a nondeterministic `Random` utility with the same public convenience API shape as `RandomSeed`.
+Enhance `RandomSeed` with matching procedural convenience methods.
 
 ## Owner And Assignment
 
 - Team: Delta
-- 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`.
+- OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_055-random-seed-enhancements`.
+- Stack base: `PR_26177_DELTA_054-random-utility`.
 
 ## Scope
 
-- 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.
+- Update `RandomSeed` to use shared helper logic where appropriate.
+- Add:
+  - `shuffle(array)`
+  - `chance(percent)`
+  - `weightedPick(weightedItems)`
+  - `saveState()`
+  - `restoreState(state)`
+- Preserve existing `RandomSeed` sequence compatibility.
+- Same seed must still reproduce same sequence.
+- Reseeding must still reproduce same sequence.
+- Add targeted unit tests for new methods.
+- No adoption changes in existing game logic.
 - No UI changes.
-- Add JSDoc.
-- Add targeted unit tests.
 
 ## Implementation Plan
 
-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.
+1. Update `src/shared/math/RandomSeed.js` to reuse `randomHelpers.js` for procedural helper methods.
+2. Keep the existing seeded `next()` algorithm unchanged.
+3. Add state save/restore methods.
+4. Extend `tests/shared/RandomSeed.test.mjs` with sequence compatibility, new method, and state tests.
 5. Produce required PR reports and repo-structured ZIP.
 
 ## Acceptance Criteria
 
-- `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.
+- Existing seeded sequence values remain compatible.
+- Same seed and reseeding behavior remain deterministic.
+- New procedural methods use the same seeded random stream.
+- State save/restore resumes the sequence from the saved point.

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_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 Delta | PR_26177_DELTA_055-random-seed-enhancements | PR_26177_DELTA_055-random-seed-enhancements | PR_26177_DELTA_055-random-seed-enhancements | Active | OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_055-random-seed-enhancements |
 | 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_054-random-utility | PR_26177_DELTA_054-random-utility | PR_26177_DELTA_054-random-utility | Active |
+| Team Delta | PR_26177_DELTA_055-random-seed-enhancements | PR_26177_DELTA_055-random-seed-enhancements | PR_26177_DELTA_055-random-seed-enhancements | 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_054-random-utility.
+Active assignment: PR_26177_DELTA_055-random-seed-enhancements.
 
-Active branch: PR_26177_DELTA_054-random-utility.
+Active branch: PR_26177_DELTA_055-random-seed-enhancements.
 
-Active PR: PR_26177_DELTA_054-random-utility.
+Active PR: PR_26177_DELTA_055-random-seed-enhancements.
 
-OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_054-random-utility.
+OWNER override approved: Continue Team Delta random utility stack with PR_26177_DELTA_055-random-seed-enhancements.
 
 ## Team Bravo
 

docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements.md

@@ -0,0 +1,50 @@
+# PR_26177_DELTA_055-random-seed-enhancements
+
+Date: 2026-06-26
+Team: Delta
+Scope: RandomSeed procedural enhancements and targeted unit tests
+Status: PASS
+
+## Summary
+
+- Updated `RandomSeed` to use shared helper logic for `nextInt`, `nextFloat`, and `pick`.
+- Added seeded procedural methods: `shuffle`, `chance`, and `weightedPick`.
+- Added `saveState()` and `restoreState(state)` for deterministic sequence checkpointing.
+- Preserved the existing `RandomSeed.next()` algorithm.
+- Added a hardcoded compatibility check for the existing `RandomSeed(42)` sequence.
+- Verified same-seed and reseeding reproducibility still pass.
+- Added targeted tests for the new methods and state restore behavior.
+- No existing game logic adoption changes or UI changes were made.
+
+## Branch Validation
+
+PASS. Branch `PR_26177_DELTA_055-random-seed-enhancements` was created from `PR_26177_DELTA_054-random-utility`.
+
+## 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/RandomSeed.js`
+- `tests/shared/RandomSeed.test.mjs`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_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/RandomSeed.test.mjs tests/shared/RandomHelpers.test.mjs`
+- PASS: `node --check src/shared/math/RandomSeed.js`
+- PASS: `node --check tests/shared/RandomSeed.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_055-random-seed-enhancements_delta.zip`

docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_branch-validation.md

@@ -0,0 +1,15 @@
+# PR_26177_DELTA_055-random-seed-enhancements Branch Validation
+
+Status: PASS
+
+## Start Gates
+
+- PASS: PR_055 branch was created from `PR_26177_DELTA_054-random-utility`.
+- PASS: Stack base was clean before branch creation.
+- PASS: Branch name is `PR_26177_DELTA_055-random-seed-enhancements`.
+
+## Scope Confirmation
+
+- PASS: Work is assigned to Team Delta.
+- PASS: Work is limited to `RandomSeed` procedural enhancements, targeted tests, PR docs, reports, and ZIP packaging.
+- PASS: No existing game logic adoption changes, UI changes, API changes, database changes, or unrelated cleanup were made.

docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_instruction-compliance-checklist.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_055-random-seed-enhancements Instruction Compliance Checklist
+
+| Instruction | Status | Notes |
+|---|---:|---|
+| Continue stacked Random PR sequence | PASS | Branch was created from PR_054. |
+| Keep one PR purpose only | PASS | Scope is RandomSeed enhancements. |
+| Preserve sequence compatibility | PASS | Existing `RandomSeed(42)` sequence is asserted in tests. |
+| No adoption changes in existing game logic | PASS | No call sites were changed. |
+| No UI changes | PASS | No UI files 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_055-random-seed-enhancements_delta.zip`. |

docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_manual-validation-notes.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_055-random-seed-enhancements Manual Validation Notes
+
+Status: PASS
+
+Manual review confirmed:
+
+- `RandomSeed.next()` was not changed.
+- The hardcoded `RandomSeed(42)` sequence remains compatible with PR_052 behavior.
+- New procedural methods consume the same seeded stream through shared helpers.
+- `saveState()` and `restoreState(state)` are in-memory and serializable; no browser storage was added.
+- No UI, API, database, or existing game logic adoption files changed.

docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_requirement-checklist.md

@@ -0,0 +1,16 @@
+# PR_26177_DELTA_055-random-seed-enhancements Requirement Checklist
+
+| Requirement | Status | Notes |
+|---|---:|---|
+| Update `RandomSeed` to use shared helper logic where appropriate | PASS | `nextInt`, `nextFloat`, `pick`, and new methods use `randomHelpers.js`. |
+| Add `shuffle(array)` | PASS | Added seeded shuffle method. |
+| Add `chance(percent)` | PASS | Added seeded chance method. |
+| Add `weightedPick(weightedItems)` | PASS | Added seeded weighted pick method. |
+| Add `saveState()` | PASS | Added serializable state capture. |
+| Add `restoreState(state)` | PASS | Added state restore with validation. |
+| Preserve existing `RandomSeed` sequence compatibility | PASS | Hardcoded `RandomSeed(42)` sequence check passes. |
+| Same seed still reproduces same sequence | PASS | Existing targeted test still passes. |
+| Reseeding still reproduces same sequence | PASS | Existing targeted test still passes. |
+| Add targeted unit tests for new methods | PASS | Extended `tests/shared/RandomSeed.test.mjs`. |
+| No adoption changes in existing game logic | PASS | No game logic call sites changed. |
+| No UI changes | PASS | No UI files changed. |

docs_build/dev/reports/PR_26177_DELTA_055-random-seed-enhancements_validation-lane.md

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