Merge pull request #204 from ToolboxAid/PR_26177_DELTA_052-random-seed-utility

PR_26177_DELTA_052-random-seed-utility

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -1,89 +1,86 @@
-# PR_26177_OWNER_051-environment-configuration-standards
+# PR_26177_DELTA_052-random-seed-utility
 
 ## Purpose
 
-Define the official Game Foundry Studio environment configuration standards that build on the OWNER_050 environment model.
+Add a reusable shared JavaScript `RandomSeed` utility for deterministic seeded random sequences.
 
 ## Source Of Truth
 
-This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OWNER_051-environment-configuration-standards`.
+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`.
+
+## OWNER Override And Team Assignment
+
+OWNER override approved: Assign Team Delta `PR_26177_DELTA_052-random-seed-utility`.
+
+Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage.
 
 ## Exact Scope
 
-- Governance/documentation only.
-- Build on OWNER_050 environment model.
-- Standardize environment file names:
-  - `.env.local`
-  - `.env.dev`
-  - `.env.ist`
-  - `.env.uat`
-  - `.env.prod`
-- Treat `.env.prd` as legacy technical debt only.
-- Add `GAMEFOUNDRY_ENVIRONMENT` allowed values:
-  - `local`
-  - `dev`
-  - `ist`
-  - `uat`
-  - `prod`
-- Keep `GAMEFOUNDRY_ENVIRONMENT_LABEL` display-only.
-- Document that only `.env` values and environment-managed secrets differ.
-- Document that the deployable artifact must remain identical.
-- Document one shared API/service contract.
-- Document feature flags cannot create permanent environment-specific behavior.
-- Review `.env.example` comments/placeholders only.
-- Clarify that only `.env.example` is committed to the repository.
-- Clarify that real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
-- Document the external `/env/<target>/.env` layout next to the `/GFS/` repo clone.
-- Do not change runtime behavior.
+- 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 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/`.
 
 ## Exact Targets
 
+- `docs_build/dev/PLAN_PR.md`
 - `docs_build/dev/BUILD_PR.md`
-- `docs_build/dev/PROJECT_INSTRUCTIONS.md`
-- `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
-- `docs_build/dev/ProjectInstructions/README.txt`
-- `docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md`
-- `docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md`
-- `docs_build/dev/ProjectInstructions/addendums/release_gate.md`
-- `.env.example`
-- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards.md`
-- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_branch-validation.md`
-- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_requirement-checklist.md`
-- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_validation-lane.md`
-- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_manual-validation-notes.md`
-- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_instruction-compliance-checklist.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`
 - `docs_build/dev/reports/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
 ## Out Of Scope
 
-- No runtime code changes.
+- No existing `Math.random()` call-site replacements.
 - No UI changes.
-- No engine core 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 actual `.env`, `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, `.env.prod`, or `.env.prd` secret/value file edits.
-- No committed real `.env.*` copy-source files.
-- No API implementation changes.
-- No storage implementation changes.
-- No database migration or DDL changes.
-- No feature flag implementation changes.
+- No unrelated cleanup.
 
 ## Validation
 
 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
 git diff --check
 ```
 
-Playwright is not required unless runtime files change.
+Playwright is not required because this PR does not change UI or browser runtime behavior.
 
 ## Artifact
 
 Create repo-structured delta ZIP:
 
 ```text
-tmp/PR_26177_OWNER_051-environment-configuration-standards_delta.zip
+tmp/PR_26177_DELTA_052-random-seed-utility_delta.zip
 ```

docs_build/dev/PLAN_PR.md

@@ -1,39 +1,48 @@
-# PLAN_PR: Move JSON schemas under tools ownership
+# PLAN_PR: PR_26177_DELTA_052-random-seed-utility
 
 ## Purpose
-Move schema contracts out of the repository root and into the tools area so schema ownership matches the systems that load, edit, validate, and export tool/sample data.
+
+Add a reusable shared JavaScript `RandomSeed` utility for deterministic seeded random sequences.
+
+## Owner And Assignment
+
+- Team: Delta
+- OWNER override approved: Assign Team Delta `PR_26177_DELTA_052-random-seed-utility`.
+- Ownership fit: Team Delta owns Shared JS, runtime utilities, technical debt remediation, and runtime test coverage.
 
 ## Scope
-- Do not change runtime behavior directly.
-- Do not edit locked samples.
-- Do not modify start_of_day folders.
-- Establish schema placement rules for Codex to implement in the next pass.
-
-## Schema placement rule
-Use this structure:
-
-```text
-toolbox/
-  schemas/
-    tool.manifest.schema.json
-    palette.schema.json
-    samples/
-      sample.tool-payload.schema.json
-    toolbox/
-      vector-map-editor.schema.json
-      vector-asset-studio.schema.json
-      sprite-editor.schema.json
-```
-
-## Rationale
-Schemas belong near tool contracts, not at repository root. The root should stay clean and should not accumulate validation artifacts.
-
-Shared schemas live at `src/shared/schemas/`.
-Tool-specific schemas live at `src/shared/schemas/tools/<tool>.schema.json`.
-
-## Acceptance criteria
-- No new schema files are added at repository root.
-- All JSON schema files are under `src/shared/schemas/`.
-- Tool manifest validation uses `src/shared/schemas/tool.manifest.schema.json`.
-- Tool-specific payload validation uses `src/shared/schemas/tools/<tool>.schema.json`.
-- Samples reference the same tool schema contracts used by tool manifests.
+
+- 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 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.
+
+## 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.

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 | 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 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 | 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 Golf | none | none | none | Available |
 | Team OWNER | none | none | none | Available |
 
@@ -48,11 +48,15 @@ Current OWNER clarification:
 
 ## Team Alfa
 
-Status: Available
+Status: Active
 
-Active assignment: none.
+Active assignment: PR_26177_DELTA_052-random-seed-utility.
 
-Active branch: none.
+Active branch: PR_26177_DELTA_052-random-seed-utility.
+
+Active PR: PR_26177_DELTA_052-random-seed-utility.
+
+OWNER override approved: Assign Team Delta PR_26177_DELTA_052-random-seed-utility.
 
 ## Team Bravo
 

docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility.md

@@ -0,0 +1,55 @@
+# PR_26177_DELTA_052-random-seed-utility
+
+Date: 2026-06-26
+Team: Delta
+Scope: Shared JavaScript utility and targeted unit tests
+Status: PASS
+
+## Summary
+
+- Added reusable shared JavaScript utility class `RandomSeed`.
+- Implemented constructor seed initialization plus `seed(value)`, `next()`, `nextInt(min, max)`, `nextFloat(min, max)`, and `pick(array)`.
+- Added JSDoc for the utility and public methods.
+- Verified same-seed reproducibility after reseeding.
+- Verified different seeds produce different sequences.
+- Added targeted unit tests in `tests/shared/RandomSeed.test.mjs`.
+- Preserved existing `Math.random()` usage; no call sites were replaced.
+- Updated active Team Delta assignment metadata required by the attached Project Instructions.
+- No UI, browser storage, API, database, or unrelated cleanup changes were made.
+
+## Branch Validation
+
+PASS. Work started from clean `main` synchronized with `origin/main` at `0e9aa23eee267edcc6aac0eb660185c4552128c8`.
+
+Current PR branch:
+
+`PR_26177_DELTA_052-random-seed-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_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`
+- `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`
+- 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 no UI or browser runtime files changed.
+
+## Artifact
+
+- `tmp/PR_26177_DELTA_052-random-seed-utility_delta.zip`

docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_branch-validation.md

@@ -0,0 +1,24 @@
+# PR_26177_DELTA_052-random-seed-utility Branch Validation
+
+Status: PASS
+
+## Start Gates
+
+- PASS: Initial branch was `main`.
+- PASS: Initial worktree was clean.
+- PASS: `main` was synchronized with `origin/main`.
+- PASS: PR branch was created from `main`.
+
+## Active Branch
+
+`PR_26177_DELTA_052-random-seed-utility`
+
+## Base Commit
+
+`0e9aa23eee267edcc6aac0eb660185c4552128c8`
+
+## Scope Confirmation
+
+- PASS: Team Delta assignment was OWNER-approved.
+- PASS: Work is limited to shared JS utility, targeted test coverage, PR governance docs, reports, and ZIP packaging.
+- PASS: No UI, browser storage, API, database, or unrelated cleanup changes were made.

docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_instruction-compliance-checklist.md

@@ -0,0 +1,13 @@
+# PR_26177_DELTA_052-random-seed-utility Instruction Compliance Checklist
+
+| Instruction | Status | Notes |
+|---|---:|---|
+| Read `ProjectInstructions.zip` and `README.txt` first | PASS | Read `ProjectInstructions/README.txt` before applying relevant instructions. |
+| Use `main` branch only as start/base | PASS | Start gate confirmed current branch `main` before work. |
+| Hard stop if current branch is not `main` | PASS | Branch was `main`. |
+| Hard stop if worktree is not clean | PASS | Worktree was clean. |
+| Use PR workflow rather than direct commit to `main` | PASS | Created `PR_26177_DELTA_052-random-seed-utility` from `main`. |
+| Apply OWNER override assignment to Team Delta | PASS | Assignment documented in active Team Delta metadata. |
+| Keep one PR purpose only | PASS | Scope is RandomSeed shared utility and targeted tests. |
+| Produce required reports | PASS | Required report files were created under `docs_build/dev/reports/`. |
+| Produce repo-structured ZIP under `tmp/` | PASS | ZIP path is `tmp/PR_26177_DELTA_052-random-seed-utility_delta.zip`. |

docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_manual-validation-notes.md

@@ -0,0 +1,13 @@
+# PR_26177_DELTA_052-random-seed-utility Manual Validation Notes
+
+Status: PASS
+
+Manual review confirmed:
+
+- `RandomSeed` is opt-in and does not replace existing `Math.random()` usage.
+- The utility is in the existing shared math area: `src/shared/math/RandomSeed.js`.
+- The class exposes the required public methods.
+- The implementation stores generator state in memory only.
+- No browser storage, API, database, UI, or start-of-day files were changed.
+- Team Delta assignment metadata reflects the OWNER override and active PR branch.
+- Playwright is not impacted by this shared utility/test-only change set.

docs_build/dev/reports/PR_26177_DELTA_052-random-seed-utility_requirement-checklist.md

@@ -0,0 +1,20 @@
+# PR_26177_DELTA_052-random-seed-utility Requirement Checklist
+
+| Requirement | Status | Notes |
+|---|---:|---|
+| Add reusable shared JavaScript utility class named `RandomSeed` | PASS | Added `src/shared/math/RandomSeed.js`. |
+| Constructor accepts an initial seed | PASS | `constructor(initialSeed = 1)` seeds the instance. |
+| Include `seed(value)` | PASS | Reseeds and returns the instance. |
+| Include `next()` | PASS | Returns deterministic values in `[0, 1)`. |
+| Include `nextInt(min, max)` | PASS | Returns inclusive deterministic integers. |
+| Include `nextFloat(min, max)` | PASS | Returns deterministic floats in `[min, max)`. |
+| Include `pick(array)` | PASS | Deterministically selects from a non-empty array. |
+| Same seed reproduces same sequence after reseeding | PASS | Covered by targeted unit test. |
+| Different seeds should produce different sequences | PASS | Covered by targeted unit test. |
+| Add JSDoc | PASS | Added class and public method JSDoc. |
+| Add targeted unit tests | PASS | Added `tests/shared/RandomSeed.test.mjs`. |
+| Do not replace existing `Math.random()` usage | PASS | No existing call sites were changed. |
+| No UI changes | PASS | No UI files changed. |
+| No browser storage | PASS | No storage usage was added. |
+| No API/database changes | PASS | No API or database files changed. |
+| No unrelated cleanup | PASS | Changes stayed scoped to utility, tests, PR docs, assignment metadata, and reports. |