Close the remaining number/string/id exact-cluster normalization residue

DavidQ · DavidQ · commit bbbaf9894a84 · 2026-04-14T22:27:20.000-04:00
BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT
diff --git a/docs/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -200,7 +200,7 @@
 - [x] Asteroids numeric sanitizers promoted into shared math
 - [x] duplicated `asObject` / `asArray` consumers moved to shared utils
 - [.] shared math is now a real active layer and should continue by exact-cluster extraction only
-- [ ] remaining number/string/id helpers still need exact-cluster normalization
+- [x] remaining number/string/id helpers still need exact-cluster normalization
 
 ---
 
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,32 +2,30 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP`.
+Create `BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT`.
 
-1. Locate these roadmap items:
-- no standalone showcase-only tool tracks
-- tools header accordion added to reduce vertical real-estate usage
-- tool-shell UI compaction is useful but does not replace tool-boundary normalization work
-- any follow-up tool UI cleanup should remain subordinate to shared-boundary and data-contract work
+Goal:
+Close the final remaining Shared Foundation checkpoint item:
+- remaining number/string/id helpers still need exact-cluster normalization
 
-2. Reclassify them as rules/instructions:
-- move them to the top roadmap rules/instructions area
-- remove checklist/status markers
-- preserve wording exactly
+Required work:
+1. Find the remaining duplicated or fragmented helper clusters in:
+   - number
+   - string
+   - id
+2. Normalize them using exact-cluster extraction only.
+3. Move them into the correct `src/shared` homes.
+4. Update consumers as needed.
+5. Do NOT perform a broad repo-wide cleanup pass.
+6. Do NOT do blind dedupe.
+7. Update roadmap status markers only.
+8. Report whether the item can now be truthfully marked complete.
 
-3. Do NOT:
-- delete content
-- rewrite wording
-- alter unrelated roadmap text
-
-4. Ensure the checklist/task area only contains actionable work after the move.
-
-5. Final packaging step is REQUIRED:
+Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP.zip`
+  `<project folder>/tmp/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.zip`
 
 Hard rules:
-- move, do not delete
-- no wording changes
+- exact-cluster work only
 - no unrelated repo changes
 - no missing ZIP
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Promote tool roadmap rules out of checklist tracking
-BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP
+Close the remaining number/string/id exact-cluster normalization residue
+BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT
diff --git a/docs/dev/reports/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT_report.md b/docs/dev/reports/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT_report.md
@@ -0,0 +1,40 @@
+# BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT Report
+
+## Exact Clusters Normalized
+- `string` helpers:
+  - canonical home: `src/shared/string/stringHelpers.js`
+  - public surface: `src/shared/string/index.js`
+- `id` helpers:
+  - canonical home: `src/shared/id/idUtils.js`
+  - public surface: `src/shared/id/index.js`
+- `number` helpers:
+  - canonical home: `src/shared/number/numberUtils.js`
+  - public surface: `src/shared/number/index.js`
+
+## Compatibility Surfaces Kept
+- `src/shared/utils/stringUtils.js` now re-exports from `src/shared/string/stringHelpers.js`
+- `src/shared/utils/idUtils.js` now re-exports from `src/shared/id/idUtils.js`
+- `src/shared/utils/numberUtils.js` now re-exports from `src/shared/number/numberUtils.js`
+
+## Consumers Updated
+- `src/shared/utils/index.js` now routes string/id/number exports through canonical homes.
+- `samples/shared/numberUtils.js` now imports from `src/shared/number/index.js` (single clustered number source).
+- `tools/shared/debugInspectorData.js` now imports number helpers from `src/shared/number/index.js`.
+- `tools/Performance Profiler/main.js` now imports number helpers from `src/shared/number/index.js`.
+- `tools/Replay Visualizer/main.js` now imports number helpers from `src/shared/number/index.js`.
+- `tools/shared/stringUtils.js` now imports `trimSafe` from `src/shared/string/index.js`.
+
+## Focused Validation
+- `node --check` on all touched JS files: PASS
+- `node tests/shared/SharedNumberStringIdCloseout.test.mjs`: PASS
+- `node tests/shared/SharedFoundationCombinedPass.test.mjs`: PASS
+
+## Roadmap Marker
+- Updated to complete:
+  - `remaining number/string/id helpers still need exact-cluster normalization`
+  - in both roadmap copies:
+    - `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+    - `docs/MASTER_ROADMAP_HIGH_LEVEL.md`
+
+## Completion Decision
+- The checkpoint item is now truthfully complete based on canonical `src/shared/{string,id,number}` cluster homes, compatibility-preserving wrappers, and passing focused validation.
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,3 +1,2 @@
-- Added roadmap cleanup PR for tool-governance rules
-- Moves tool-governance items from checklist/status tracking to top-level roadmap instructions
-- Preserves wording and avoids deletion
+- Added final exact-cluster closeout PR for remaining number/string/id helper normalization
+- Intended to close the last open item in the recent Shared Foundation consolidation checkpoint
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,6 +1,8 @@
-- all specified tool-governance items moved to top-level rules/instructions area
-- wording preserved exactly
-- checklist/status markers removed from those items
-- roadmap task areas left with actionable work only
+- remaining number helper residue addressed
+- remaining string helper residue addressed
+- remaining id helper residue addressed
+- only exact-cluster normalization used
+- roadmap updated by status markers only
+- final checkpoint item either marked complete or exact blockers reported
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.zip
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -208,7 +208,7 @@
 - [x] duplicated `asNumber` consumers migrated to shared math
 - [x] Asteroids numeric sanitizers promoted into shared math
 - [x] duplicated `asObject` / `asArray` consumers moved to shared utils
-- [ ] remaining number/string/id helpers still need exact-cluster normalization
+- [x] remaining number/string/id helpers still need exact-cluster normalization
 
 ---
 
diff --git a/docs/pr/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.md b/docs/pr/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.md
@@ -0,0 +1,36 @@
+# BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT
+
+## Purpose
+Close the final remaining item in the Shared Foundation consolidation checkpoint:
+
+- remaining number/string/id helpers still need exact-cluster normalization
+
+## Scope
+Finish exact-cluster normalization for the remaining reusable helper residue in:
+- number helpers
+- string helpers
+- id helpers
+
+## Rules
+- exact-cluster extraction only
+- no broad repo-wide cleanup pass
+- no blind dedupe
+- normalize only helpers that are clearly reusable and correctly owned by `src/shared`
+- preserve domain boundaries
+
+## Required work
+1. Identify the remaining duplicated or fragmented number/string/id helper clusters.
+2. Normalize those helpers into the correct `src/shared` homes.
+3. Update consumers as needed.
+4. Keep changes surgical.
+5. Mark the checkpoint item complete only if truthfully supported.
+
+## Validation
+Codex must report:
+- which exact clusters were normalized
+- where the helpers now live
+- what consumers were updated
+- whether the final checkpoint item can now be marked complete
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.zip`
diff --git a/samples/shared/numberUtils.js b/samples/shared/numberUtils.js
@@ -1,10 +1,7 @@
 export {
+  isFiniteNumber,
   toFiniteNumber,
   asFiniteNumber,
-  asPositiveInteger
-} from "../../src/shared/math/numberNormalization.js";
-
-export {
-  isFiniteNumber,
+  asPositiveInteger,
   asPositiveNumber
-} from "../../src/shared/utils/numberUtils.js";
+} from "../../src/shared/number/index.js";
diff --git a/src/shared/id/idUtils.js b/src/shared/id/idUtils.js
@@ -0,0 +1,33 @@
+import { sanitizeText } from "../string/index.js";
+
+export function isValidId(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function normalizeId(value, fallback = "") {
+  const normalized = sanitizeText(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return normalized || sanitizeText(fallback);
+}
+
+export function createId(prefix = "id", randomSource = Math.random) {
+  const safePrefix = normalizeId(prefix, "id");
+  const raw = typeof randomSource === "function" ? randomSource() : Math.random();
+  const token = Number(raw).toString(36).slice(2, 10);
+  return `${safePrefix}-${token || "00000000"}`;
+}
+
+export function createStableId(parts = [], fallback = "id") {
+  const normalized = (Array.isArray(parts) ? parts : [parts])
+    .map((part) => normalizeId(part))
+    .filter(Boolean);
+  const safeFallback = normalizeId(fallback, "id");
+  return normalized.length > 0 ? normalized.join(".") : safeFallback;
+}
+
+export function generateId(prefix = "id", randomSource = Math.random) {
+  return createId(prefix, randomSource);
+}
diff --git a/src/shared/id/index.js b/src/shared/id/index.js
@@ -0,0 +1,7 @@
+export {
+  createId,
+  generateId,
+  normalizeId,
+  createStableId,
+  isValidId
+} from "./idUtils.js";
diff --git a/src/shared/index.js b/src/shared/index.js
@@ -6,6 +6,9 @@ index.js
 */
 export * as sharedMath from "./math/index.js";
 export * as sharedUtils from "./utils/index.js";
+export * as sharedString from "./string/index.js";
+export * as sharedId from "./id/index.js";
+export * as sharedNumber from "./number/index.js";
 export * as sharedState from "./state/index.js";
 export * as sharedIO from "./io/index.js";
 export * as sharedData from "./data/index.js";
diff --git a/src/shared/number/index.js b/src/shared/number/index.js
@@ -0,0 +1,7 @@
+export {
+  isFiniteNumber,
+  toFiniteNumber,
+  asFiniteNumber,
+  asPositiveInteger,
+  asPositiveNumber
+} from "./numberUtils.js";
diff --git a/src/shared/number/numberUtils.js b/src/shared/number/numberUtils.js
@@ -0,0 +1,19 @@
+import {
+  asFiniteNumber,
+  asPositiveInteger,
+  toFiniteNumber
+} from "../math/numberNormalization.js";
+
+export { toFiniteNumber, asFiniteNumber, asPositiveInteger };
+
+export function isFiniteNumber(value) {
+  return Number.isFinite(value);
+}
+
+export function asPositiveNumber(value, fallback) {
+  const numeric = toFiniteNumber(value, fallback);
+  if (!isFiniteNumber(numeric) || numeric <= 0) {
+    return fallback;
+  }
+  return numeric;
+}
diff --git a/src/shared/string/index.js b/src/shared/string/index.js
@@ -4,4 +4,12 @@ David Quesenberry
 04/14/2026
 index.js
 */
-export { escapeHtml } from "./stringUtil.js";
+export {
+  safeTrim,
+  toLowerSafe,
+  stringCompare,
+  trimSafe,
+  sanitizeText,
+  normalizeString,
+  escapeHtml
+} from "./stringHelpers.js";
diff --git a/src/shared/string/stringHelpers.js b/src/shared/string/stringHelpers.js
@@ -0,0 +1,32 @@
+export function safeTrim(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function toLowerSafe(value) {
+  return safeTrim(value).toLowerCase();
+}
+
+export function stringCompare(left, right) {
+  return safeTrim(left).localeCompare(safeTrim(right));
+}
+
+export function trimSafe(value) {
+  return safeTrim(value);
+}
+
+export function sanitizeText(value) {
+  return safeTrim(value);
+}
+
+export function normalizeString(value) {
+  return safeTrim(value);
+}
+
+export function escapeHtml(value) {
+  return String(value || "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
diff --git a/src/shared/string/stringUtil.js b/src/shared/string/stringUtil.js
@@ -1 +1 @@
-export { escapeHtml } from "../utils/stringUtils.js";
+export { escapeHtml } from "./stringHelpers.js";
diff --git a/src/shared/utils/idUtils.js b/src/shared/utils/idUtils.js
@@ -1,33 +1 @@
-import { sanitizeText } from "./stringUtils.js";
-
-export function isValidId(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-export function normalizeId(value, fallback = "") {
-  const normalized = sanitizeText(value)
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "");
-  return normalized || sanitizeText(fallback);
-}
-
-export function createId(prefix = "id", randomSource = Math.random) {
-  const safePrefix = normalizeId(prefix, "id");
-  const raw = typeof randomSource === "function" ? randomSource() : Math.random();
-  const token = Number(raw).toString(36).slice(2, 10);
-  return `${safePrefix}-${token || "00000000"}`;
-}
-
-export function createStableId(parts = [], fallback = "id") {
-  const normalized = (Array.isArray(parts) ? parts : [parts])
-    .map((part) => normalizeId(part))
-    .filter(Boolean);
-  const safeFallback = normalizeId(fallback, "id");
-  return normalized.length > 0 ? normalized.join(".") : safeFallback;
-}
-
-export function generateId(prefix = "id", randomSource = Math.random) {
-  return createId(prefix, randomSource);
-}
+export * from "../id/idUtils.js";
diff --git a/src/shared/utils/index.js b/src/shared/utils/index.js
@@ -13,15 +13,15 @@ export {
   sanitizeText,
   normalizeString,
   escapeHtml,
-} from "./stringUtils.js";
+} from "../string/index.js";
 export {
   createId,
   generateId,
   normalizeId,
   createStableId,
   isValidId,
-} from "./idUtils.js";
-export { isFiniteNumber, toFiniteNumber, asFiniteNumber, asPositiveInteger, asPositiveNumber } from "./numberUtils.js";
+} from "../id/index.js";
+export { isFiniteNumber, toFiniteNumber, asFiniteNumber, asPositiveInteger, asPositiveNumber } from "../number/index.js";
 export { isObject, isPlainObject, asObject, asArray as asObjectArray } from "./objectUtils.js";
 export { cloneJson } from "./jsonUtils.js";
 export { stringifyValue } from "./stringifyValueUtils.js";
diff --git a/src/shared/utils/numberUtils.js b/src/shared/utils/numberUtils.js
diff --git a/src/shared/utils/stringUtils.js b/src/shared/utils/stringUtils.js
diff --git a/tests/shared/SharedNumberStringIdCloseout.test.mjs b/tests/shared/SharedNumberStringIdCloseout.test.mjs
diff --git a/tools/Performance Profiler/main.js b/tools/Performance Profiler/main.js
diff --git a/tools/Replay Visualizer/main.js b/tools/Replay Visualizer/main.js
diff --git a/tools/shared/debugInspectorData.js b/tools/shared/debugInspectorData.js
diff --git a/tools/shared/stringUtils.js b/tools/shared/stringUtils.js
