Merge pull request #209 from ToolboxAid/PR_26177_001-shared-hash-foundation

PR_26177_001-shared-hash-foundation

Author: ToolboxAid

docs_build/dev/BUILD_PR.md

@@ -1,89 +1,64 @@
-# PR_26177_DELTA_056-shared-validation-assertions
+# PR_26177_001-shared-hash-foundation
 
 ## Purpose
 
-Move generic validation/assertion helpers out of random helper code into a shared validation module.
+Add a small shared non-cryptographic hash foundation.
 
 ## 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_056-shared-validation-assertions`.
-
-## OWNER Override And Team Assignment
-
-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_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.
+This `BUILD_PR.md`, `PLAN_PR.md`, and the user request are the source of truth for `PR_26177_001-shared-hash-foundation`.
 
 ## Exact Scope
 
-- 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.
+- Add `src/shared/hash/` foundation.
+- Include deterministic non-crypto hash helpers.
+- No browser-owned product data.
+- No runtime UI changes.
+- Add targeted tests for the shared hash area.
 - 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/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`
+- `src/shared/hash/hash.js`
+- `tests/shared/HashFoundation.test.mjs`
+- `docs_build/dev/reports/PR_26177_001-shared-hash-foundation.md`
+- `docs_build/dev/reports/PR_26177_001-shared-hash-foundation_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_001-shared-hash-foundation_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_001-shared-hash-foundation_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_001-shared-hash-foundation_manual-validation-notes.md`
 - `docs_build/dev/reports/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
 ## Out Of Scope
 
-- No public API changes.
-- No new unrelated validation helpers.
-- No existing game logic adoption changes.
-- No UI changes.
+- No cryptographic hashing.
+- No browser-owned product data.
+- No runtime UI changes.
 - No browser storage changes.
-- No API changes.
-- No database changes.
+- No API/database changes.
+- No engine refactor.
 - No `start_of_day` folder changes.
 - No unrelated cleanup.
+- No full samples smoke by default.
 
 ## Validation
 
 Run exactly:
 
 ```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
+node ./scripts/run-node-test-files.mjs tests/shared/HashFoundation.test.mjs
+node --check src/shared/hash/hash.js
+node --check tests/shared/HashFoundation.test.mjs
 git diff --check
 ```
 
-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_056-shared-validation-assertions_delta.zip
+tmp/PR_26177_001-shared-hash-foundation_delta.zip
 ```

docs_build/dev/PLAN_PR.md

@@ -1,43 +1,28 @@
-# PLAN_PR: PR_26177_DELTA_056-shared-validation-assertions
+# PLAN_PR: PR_26177_001-shared-hash-foundation
 
 ## Purpose
 
-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_056-shared-validation-assertions`.
-- Stack base: `PR_26177_DELTA_055-random-seed-enhancements`.
+Add a small shared non-cryptographic hash foundation.
 
 ## Scope
 
-- 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.
+- Add `src/shared/hash/` foundation.
+- Include deterministic non-crypto hash helpers.
+- Add targeted unit tests.
+- No browser-owned product data.
+- No runtime UI changes.
 - No unrelated cleanup.
 
 ## Implementation Plan
 
-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.
+1. Add `src/shared/hash/hash.js` with deterministic stable string and FNV-1a based helpers.
+2. Add `tests/shared/HashFoundation.test.mjs`.
+3. Validate determinism, object key ordering, seed variation, combination, and normalized hash output.
+4. Produce required Codex reports and repo-structured ZIP.
 
 ## Acceptance Criteria
 
-- 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.
+- Hash helpers are deterministic for identical values.
+- Object hashing is stable regardless of property insertion order.
+- Helpers are documented as non-cryptographic.
+- No browser storage, UI, API, database, or sample smoke changes are introduced.

docs_build/dev/reports/PR_26177_001-shared-hash-foundation.md

@@ -0,0 +1,23 @@
+# PR_26177_001-shared-hash-foundation
+
+Date: 2026-06-26
+Scope: Shared non-cryptographic hash foundation
+Status: PASS
+
+## Summary
+
+- Added `src/shared/hash/hash.js`.
+- Added deterministic non-cryptographic hash helpers for stable strings, string/value hashes, combined hashes, and normalized hash values.
+- Added targeted tests in `tests/shared/HashFoundation.test.mjs`.
+- No browser-owned product data, runtime UI, API, database, or unrelated cleanup changes were made.
+
+## Validation
+
+- PASS: `node ./scripts/run-node-test-files.mjs tests/shared/HashFoundation.test.mjs`.
+- PASS: `node --check src/shared/hash/hash.js`.
+- PASS: `node --check tests/shared/HashFoundation.test.mjs`.
+- PASS: `git diff --check`.
+
+## Artifact
+
+- `tmp/PR_26177_001-shared-hash-foundation_delta.zip`

docs_build/dev/reports/PR_26177_001-shared-hash-foundation_branch-validation.md

@@ -0,0 +1,8 @@
+# PR_26177_001-shared-hash-foundation Branch Validation
+
+Status: PASS
+
+- PASS: Started from clean synchronized `main`.
+- PASS: Branch `PR_26177_001-shared-hash-foundation` was created from `main`.
+- PASS: One PR purpose only: shared hash foundation.
+- PASS: No `start_of_day` files changed.

docs_build/dev/reports/PR_26177_001-shared-hash-foundation_manual-validation-notes.md

@@ -0,0 +1,5 @@
+# PR_26177_001-shared-hash-foundation Manual Validation Notes
+
+Status: PASS
+
+Manual review confirmed the new hash helpers are deterministic, non-cryptographic, isolated to `src/shared/hash/`, and do not add browser product-data ownership or runtime UI behavior.

docs_build/dev/reports/PR_26177_001-shared-hash-foundation_requirement-checklist.md

@@ -0,0 +1,12 @@
+# PR_26177_001-shared-hash-foundation Requirement Checklist
+
+| Requirement | Status | Notes |
+|---|---:|---|
+| Add `src/shared/hash/` foundation | PASS | Added `src/shared/hash/hash.js`. |
+| Include deterministic non-crypto hash helpers | PASS | Added stable string, string/value hash, combined hash, and normalized helpers. |
+| No browser-owned product data | PASS | No storage or product-data files changed. |
+| No runtime UI changes | PASS | No UI files changed. |
+| One PR purpose only | PASS | Scope is limited to hash foundation. |
+| Smallest valid scoped change | PASS | No unrelated exports or integrations added. |
+| Add targeted tests | PASS | Added `tests/shared/HashFoundation.test.mjs`. |
+| Do not run full samples smoke by default | PASS | Full samples smoke was not run. |

docs_build/dev/reports/PR_26177_001-shared-hash-foundation_validation-lane.md

@@ -0,0 +1,22 @@
+# PR_26177_001-shared-hash-foundation Validation Lane
+
+Status: PASS
+
+## Commands
+
+```powershell
+node ./scripts/run-node-test-files.mjs tests/shared/HashFoundation.test.mjs
+node --check src/shared/hash/hash.js
+node --check tests/shared/HashFoundation.test.mjs
+git diff --check
+```
+
+## Results
+
+- PASS: Targeted hash foundation test.
+- PASS: Changed JS syntax checks.
+- PASS: `git diff --check`.
+
+## Not Run
+
+- Full samples smoke was not run by default.

docs_build/dev/reports/codex_changed_files.txt

@@ -1,14 +1,11 @@
 docs_build/dev/BUILD_PR.md
 docs_build/dev/PLAN_PR.md
-docs_build/dev/ProjectInstructions/team_assignments/ACTIVE_TEAM_REGISTRY.md
-docs_build/dev/ProjectInstructions/team_assignments/TEAM_ASSIGNMENTS.md
-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_instruction-compliance-checklist.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_requirement-checklist.md
-docs_build/dev/reports/PR_26177_DELTA_056-shared-validation-assertions_validation-lane.md
+docs_build/dev/reports/PR_26177_001-shared-hash-foundation.md
+docs_build/dev/reports/PR_26177_001-shared-hash-foundation_branch-validation.md
+docs_build/dev/reports/PR_26177_001-shared-hash-foundation_manual-validation-notes.md
+docs_build/dev/reports/PR_26177_001-shared-hash-foundation_requirement-checklist.md
+docs_build/dev/reports/PR_26177_001-shared-hash-foundation_validation-lane.md
 docs_build/dev/reports/codex_changed_files.txt
 docs_build/dev/reports/codex_review.diff
-src/shared/math/randomHelpers.js
-src/shared/validation/assert.js
+src/shared/hash/hash.js
+tests/shared/HashFoundation.test.mjs