Merge pull request #208 from ToolboxAid/PR_26177_DELTA_056-shared-validation-assertions

PR_26177_DELTA_056-shared-validation-assertions

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -1,39 +1,40 @@
-# PR_26177_DELTA_055-random-seed-enhancements
+# PR_26177_DELTA_056-shared-validation-assertions
 
 ## Purpose
 
-Enhance `RandomSeed` with matching procedural convenience methods.
+Move generic validation/assertion helpers out of random helper code into a shared validation module.
 
 ## 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_055-random-seed-enhancements`.
+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_056-shared-validation-assertions`.
 
 ## OWNER Override And Team Assignment
 
-OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_055-random-seed-enhancements`.
+OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_056-shared-validation-assertions`.
 
 Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage.
 
 ## Stack
 
-- 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.
+- Base branch: `PR_26177_DELTA_055-random-seed-enhancements`
+- This PR depends on the random helper module from PR_053, `Random` from PR_054, and `RandomSeed` enhancements from PR_055.
 
 ## Exact Scope
 
-- 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.
+- Create `src/shared/validation/assert.js`.
+- Move generic assertion helpers from random helper code into `assert.js`.
+- Include only generic reusable validation functions needed by current random helpers:
+  - `assertArray`
+  - `assertFiniteNumber`
+  - `assertOrderedRange`
+- Update random helper code to import from `src/shared/validation/assert.js`.
+- Preserve existing `Random` and `RandomSeed` behavior.
+- Do not change public API.
+- Do not expand into unrelated validation functions yet.
+- Add/update targeted unit tests if needed.
 - No UI changes.
+- No API/database changes.
+- No unrelated cleanup.
 - Create required Codex reports under `docs_build/dev/reports/`.
 - Create repo-structured delta ZIP under `tmp/`.
 
@@ -43,20 +44,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/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`
+- `src/shared/validation/assert.js`
+- `src/shared/math/randomHelpers.js`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_instruction-compliance-checklist.md`
 - `docs_build/dev/reports/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
 ## Out Of Scope
 
-- No seeded `next()` algorithm changes.
+- No public API changes.
+- No new unrelated validation helpers.
 - No existing game logic adoption changes.
 - No UI changes.
 - No browser storage changes.
@@ -70,9 +72,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/RandomSeed.test.mjs tests/shared/RandomHelpers.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/Random.test.mjs tests/shared/RandomSeed.test.mjs
+node --check src/shared/validation/assert.js
+node --check src/shared/math/randomHelpers.js
 git diff --check
 ```
 
@@ -83,5 +85,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_055-random-seed-enhancements_delta.zip
+tmp/PR_26177_DELTA_056-shared-validation-assertions_delta.zip
 ```

docs_build/dev/PLAN_PR.md

@@ -1,42 +1,43 @@
-# PLAN_PR: PR_26177_DELTA_055-random-seed-enhancements
+# PLAN_PR: PR_26177_DELTA_056-shared-validation-assertions
 
 ## Purpose
 
-Enhance `RandomSeed` with matching procedural convenience methods.
+Move generic validation/assertion helpers out of random helper code into a shared validation module.
 
 ## Owner And Assignment
 
 - Team: Delta
-- 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`.
+- OWNER override approved: Continue Team Delta random utility stack with `PR_26177_DELTA_056-shared-validation-assertions`.
+- Stack base: `PR_26177_DELTA_055-random-seed-enhancements`.
 
 ## Scope
 
-- 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.
+- Create `src/shared/validation/assert.js`.
+- Move generic assertion helpers from random helper code into `assert.js`.
+- Include only generic reusable validation functions needed by current random helpers:
+  - `assertArray`
+  - `assertFiniteNumber`
+  - `assertOrderedRange`
+- Update random helper code to import from `src/shared/validation/assert.js`.
+- Preserve existing `Random` and `RandomSeed` behavior.
+- Do not change public API.
+- Do not expand into unrelated validation functions yet.
+- Add/update targeted unit tests if needed.
 - No UI changes.
+- No API/database changes.
+- No unrelated cleanup.
 
 ## Implementation Plan
 
-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.
+1. Add `src/shared/validation/assert.js` with only the required generic assertion helpers.
+2. Remove duplicated generic assertions from `src/shared/math/randomHelpers.js`.
+3. Import the shared assertions from `randomHelpers.js`.
+4. Run targeted random helper, `Random`, and `RandomSeed` tests.
 5. Produce required PR reports and repo-structured ZIP.
 
 ## Acceptance Criteria
 
-- 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.
+- Existing random helper behavior is preserved.
+- Existing `Random` and `RandomSeed` behavior is preserved.
+- Public random APIs are unchanged.
+- Shared assertion module stays limited to the current reusable validation helpers.

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

docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions.md

@@ -0,0 +1,50 @@
+# PR_26177_DELTA_056-shared-validation-assertions
+
+Date: 2026-06-26
+Team: Delta
+Scope: Shared validation assertions extracted from random helper code
+Status: PASS
+
+## Summary
+
+- Added `src/shared/validation/assert.js`.
+- Moved generic reusable assertion helpers out of `src/shared/math/randomHelpers.js`.
+- Included only the current generic assertion helpers needed by random helpers: `assertArray`, `assertFiniteNumber`, and `assertOrderedRange`.
+- Updated `randomHelpers.js` to import those assertions from the shared validation module.
+- Preserved existing `Random`, `RandomSeed`, and random helper behavior.
+- Did not change public API.
+- Did not add unrelated validation helpers.
+- No UI, API, database, or unrelated cleanup changes were made.
+
+## Branch Validation
+
+PASS. Branch `PR_26177_DELTA_056-shared-validation-assertions` was created from clean `PR_26177_DELTA_055-random-seed-enhancements`.
+
+## 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/validation/assert.js`
+- `src/shared/math/randomHelpers.js`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_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/Random.test.mjs tests/shared/RandomSeed.test.mjs`
+- PASS: `node --check src/shared/validation/assert.js`
+- PASS: `node --check src/shared/math/randomHelpers.js`
+- 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_056-shared-validation-assertions_delta.zip`

docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_branch-validation.md

@@ -0,0 +1,15 @@
+# PR_26177_DELTA_056-shared-validation-assertions Branch Validation
+
+Status: PASS
+
+## Start Gates
+
+- PASS: Current branch was `PR_26177_DELTA_055-random-seed-enhancements`.
+- PASS: Worktree was clean before creating PR_056.
+- PASS: Branch `PR_26177_DELTA_056-shared-validation-assertions` was created from PR_055.
+
+## Scope Confirmation
+
+- PASS: Work is assigned to Team Delta.
+- PASS: Work is limited to extracting generic assertions used by random helpers.
+- PASS: No public API, UI, browser storage, API, database, or unrelated cleanup changes were made.

docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_instruction-compliance-checklist.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_056-shared-validation-assertions Instruction Compliance Checklist
+
+| Instruction | Status | Notes |
+|---|---:|---|
+| Read `ProjectInstructions.zip` and `README.txt` first | PASS | Read `ProjectInstructions/README.txt` before work. |
+| Create PR_056 as stacked PR on current branch | PASS | Branch was created from `PR_26177_DELTA_055-random-seed-enhancements`. |
+| Hard stop if branch/worktree gates fail | PASS | Branch and clean worktree gates passed. |
+| Keep one PR purpose only | PASS | Scope is shared validation assertion extraction. |
+| Do not change public API | PASS | No public API changes were made. |
+| 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_056-shared-validation-assertions_delta.zip`. |

docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_manual-validation-notes.md

@@ -0,0 +1,11 @@
+# PR_26177_DELTA_056-shared-validation-assertions Manual Validation Notes
+
+Status: PASS
+
+Manual review confirmed:
+
+- The extracted assertions are generic and reusable.
+- `assert.js` intentionally contains only `assertArray`, `assertFiniteNumber`, and `assertOrderedRange`.
+- Random helper behavior is preserved through imports from the shared validation module.
+- `Random` and `RandomSeed` public APIs are unchanged.
+- No UI, browser storage, API, database, or unrelated files changed.

docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_requirement-checklist.md

@@ -0,0 +1,16 @@
+# PR_26177_DELTA_056-shared-validation-assertions Requirement Checklist
+
+| Requirement | Status | Notes |
+|---|---:|---|
+| Create `src/shared/validation/assert.js` | PASS | New shared validation module added. |
+| Move generic assertion helpers from random helper code into `assert.js` | PASS | `assertArray`, `assertFiniteNumber`, and `assertOrderedRange` were extracted. |
+| Include only generic reusable validation functions needed by current random helpers | PASS | No unrelated validation helpers were added. |
+| Update random helper code to import from `src/shared/validation/assert.js` | PASS | `randomHelpers.js` now imports from shared validation. |
+| Preserve existing `Random` behavior | PASS | Targeted `Random` tests pass. |
+| Preserve existing `RandomSeed` behavior | PASS | Targeted `RandomSeed` tests pass. |
+| Do not change public API | PASS | No public API methods or call sites changed. |
+| Do not expand into unrelated validation functions yet | PASS | Module includes only the requested assertions. |
+| Add/update targeted unit tests if needed | PASS | Existing targeted random tests cover behavior after extraction. |
+| No UI changes | PASS | No UI files changed. |
+| No API/database changes | PASS | No API or database files changed. |
+| No unrelated cleanup | PASS | Changes stayed scoped to assertion extraction and reports. |

docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_validation-lane.md

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