BUILD_PR_LEVEL_09_07_TOOL_BOUNDARY_NORMALIZATION

DavidQ · DavidQ · commit 467b7cd98165 · 2026-04-14T09:32:43.000-04:00
Normalizes active tool boundaries by centralizing proven reusable tool logic under tools/shared, removing cross-tool coupling, and adding focused boundary validation without changing engine/runtime or asset layout. &amp; BUILD_PR_LEVEL_09_08_TOOL_DATA_CONTRACTS
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
-REASONING: medium
-COMMAND: Align tool launch contract.
+REASONING: high
+COMMAND: Define and enforce tool data contracts.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_09_06_TOOL_LAUNCH_CONTRACT_ALIGNMENT
+BUILD_PR_LEVEL_09_08_TOOL_DATA_CONTRACTS
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-NEXT: BUILD_PR_LEVEL_09_07_TOOL_BOUNDARY_NORMALIZATION
+NEXT: BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1 @@
-Aligned tool entry + config loading.
+Introduces tool data contract layer.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,3 +1,3 @@
-[ ] entry aligned
-[ ] config consistent
-[ ] tests pass
+[ ] contracts defined
+[ ] tools aligned
+[ ] no engine changes
diff --git a/docs/pr/BUILD_PR_LEVEL_09_07_TOOL_BOUNDARY_NORMALIZATION.md b/docs/pr/BUILD_PR_LEVEL_09_07_TOOL_BOUNDARY_NORMALIZATION.md
@@ -0,0 +1,122 @@
+# BUILD_PR — LEVEL 09_07 — TOOL BOUNDARY NORMALIZATION
+
+## Objective
+Normalize boundaries across active tools so `tools/shared` becomes the only approved shared surface for reusable tool logic, while each tool remains responsible only for its own UI and orchestration.
+
+## Why This PR Exists
+The prior lane completed:
+- asset structure simplification
+- shared asset handoff enforcement
+- tool launch contract alignment
+
+This PR is the next dependency-ordered step. The repo now needs a strict separation between:
+- tool-local UI / workflow code
+- shared tool utilities / state / IO helpers
+
+Without this pass, active tools risk continuing to:
+- duplicate helper logic
+- import across tool folders
+- hide reusable logic inside one tool and copy it elsewhere
+- blur the line between shared utility code and tool-specific implementation
+
+## In Scope
+- inventory reusable exact-clusters inside active tools
+- extract only proven multi-tool logic into `tools/shared`
+- replace cross-tool imports with `tools/shared` imports
+- document and enforce the rule that tools do not import other tools
+- normalize shared helper placement for tool-only utilities
+- add or update focused validation that guards tool-boundary rules
+
+## Out of Scope
+- no engine changes
+- no runtime/gameplay changes
+- no asset relocation
+- no feature additions
+- no UI redesign
+- no broad cleanup unrelated to tool boundaries
+- no speculative extraction without reuse evidence
+
+## Target Tools
+Primary active tools for this pass:
+- Tile Map Editor
+- Parallax Editor
+- Vector Map Editor
+- Vector Asset Studio
+- Sprite Editor
+
+Secondary tool shells to keep aligned if touched:
+- State Inspector
+- Replay Visualizer
+- Performance Profiler
+
+## Boundary Rules To Enforce
+1. A tool must not import code from another tool folder.
+2. Reusable tool logic must live under `tools/shared`.
+3. Tool entry files should orchestrate only:
+   - boot
+   - UI wiring
+   - tool-local composition
+4. Shared logic extracted into `tools/shared` must be:
+   - tool-agnostic
+   - minimal
+   - contractable
+   - reused by 2+ active tools, or clearly required as the single approved shared surface
+5. Tool-specific workflow logic remains in the owning tool.
+
+## Extraction Heuristics
+Promote only exact clusters such as:
+- path / URL resolution helpers
+- manifest/sample loading helpers
+- palette serialization / normalization helpers
+- shared storage key helpers
+- common panel / layout state helpers
+- tool-local fetch / import/export wrappers with repeated usage
+
+Do not promote:
+- editor-specific commands
+- tool-specific scene behavior
+- one-off UI event flows
+- feature logic that belongs to a single editor
+
+## Expected Implementation Shape
+Preferred shared homes:
+- `tools/shared/io/...`
+- `tools/shared/state/...`
+- `tools/shared/utils/...`
+- `tools/shared/contracts/...` (only if needed by proven reuse)
+- `tools/shared/validation/...` (only if needed by focused checks)
+
+## Required Deliverables
+Codex should produce a small surgical delta containing:
+- exact-cluster extractions only
+- updated imports in affected tools
+- focused validation / test coverage for boundary rules
+- no unrelated file movement
+
+## Validation Requirements
+At minimum validate:
+- touched tool entry files parse successfully
+- no active tool imports another tool directly
+- extracted helpers resolve from `tools/shared`
+- prior launch-contract behavior still passes
+- asset/palette hook expectations are not regressed
+
+## Suggested Validation Commands
+Use the repo's existing validation style and keep it lightweight. Prefer focused checks such as:
+- node --check on touched files
+- focused tests for tool launch / boundary rules
+- existing asset usage / launch contract tests if present
+
+## Acceptance Criteria
+- active tools do not import one another
+- reusable exact-cluster helpers are centralized under `tools/shared`
+- no engine/runtime code is touched
+- no asset layout changes occur
+- tests/checks covering boundary rules pass
+- the delta remains small and purpose-specific
+
+## Implementation Notes
+- Keep this PR docs-first and surgical.
+- Favor exact-cluster extraction over broad reorganization.
+- If a candidate helper is only used once, leave it local.
+- If a helper contains UI assumptions from one tool, do not promote it until split cleanly.
diff --git a/docs/pr/BUILD_PR_LEVEL_09_08_TOOL_DATA_CONTRACTS.md b/docs/pr/BUILD_PR_LEVEL_09_08_TOOL_DATA_CONTRACTS.md
@@ -0,0 +1 @@
+Tool data contracts normalization (docs-only PR).
diff --git a/docs/specs/tool_data_contract.md b/docs/specs/tool_data_contract.md
@@ -0,0 +1,61 @@
+# Tool Data Contract
+
+## Purpose
+Define and enforce normalized tool-state data contracts used by project save/open integration.
+
+This contract is enforced by:
+- `tools/shared/projectToolIntegration.js`
+- `tests/tools/ProjectToolDataContracts.test.mjs`
+
+## Contract Metadata
+- schema: `html-js-gaming.tool-data-contract`
+- version: `1`
+
+## Tool Contracts
+
+### Tile Map Editor
+- contractId: `tool-state.tile-map-editor/1`
+- required state blocks:
+  - `documentModel`
+  - `documentModel.assetRefs`
+
+### Parallax Editor
+- contractId: `tool-state.parallax-editor/1`
+- required state blocks:
+  - `documentModel`
+  - `documentModel.assetRefs`
+
+### Sprite Editor
+- contractId: `tool-state.sprite-editor/1`
+- required state blocks:
+  - `project`
+  - `project.assetRefs`
+
+### Vector Map Editor
+- contractId: `tool-state.vector-map-editor/1`
+- normalized as tool-local object state.
+
+### Vector Asset Studio
+- contractId: `tool-state.vector-asset-studio/1`
+- normalized field:
+  - `selectedPaletteId` (string id normalization when present)
+
+### Asset Browser
+- contractId: `tool-state.asset-browser/1`
+- normalized field:
+  - `selectedAssetId` (string id normalization when present)
+
+### Palette Browser
+- contractId: `tool-state.palette-browser/1`
+- normalized field:
+  - `selectedPaletteId` (string id normalization when present)
+
+## Enforcement Outputs
+`buildProjectToolIntegration(...)` publishes:
+- per-tool contract status (`valid` / `invalid`)
+- per-tool `contractIssues`
+- aggregate `contractSummary` with:
+  - schema/version
+  - status
+  - invalid tool ids
+  - warnings by tool
diff --git a/tests/run-tests.mjs b/tests/run-tests.mjs
@@ -88,6 +88,8 @@ import { run as runStorageService } from './persistence/StorageService.test.mjs'
 import { run as runAssetValidationEngine } from './tools/AssetValidationEngine.test.mjs';
 import { run as runAssetUsageIntegration } from './tools/AssetUsageIntegration.test.mjs';
 import { run as runAssetRemediationSystem } from './tools/AssetRemediationSystem.test.mjs';
+import { run as runToolBoundaryEnforcement } from './tools/ToolBoundaryEnforcement.test.mjs';
+import { run as runProjectToolDataContracts } from './tools/ProjectToolDataContracts.test.mjs';
 import { run as runToolEntryLaunchContract } from './tools/ToolEntryLaunchContract.test.mjs';
 import { run as runProjectPackagingSystem } from './tools/ProjectPackagingSystem.test.mjs';
 import { run as runRuntimeAssetLoader } from './tools/RuntimeAssetLoader.test.mjs';
@@ -201,6 +203,8 @@ const tests = [
     ['AssetValidationEngine', runAssetValidationEngine],
     ['AssetUsageIntegration', runAssetUsageIntegration],
     ['AssetRemediationSystem', runAssetRemediationSystem],
+    ['ToolBoundaryEnforcement', runToolBoundaryEnforcement],
+    ['ProjectToolDataContracts', runProjectToolDataContracts],
     ['ToolEntryLaunchContract', runToolEntryLaunchContract],
     ['ProjectPackagingSystem', runProjectPackagingSystem],
     ['RuntimeAssetLoader', runRuntimeAssetLoader],
diff --git a/tests/tools/ProjectToolDataContracts.test.mjs b/tests/tools/ProjectToolDataContracts.test.mjs
@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import {
+  TOOL_DATA_CONTRACT_SCHEMA,
+  TOOL_DATA_CONTRACT_VERSION,
+  buildProjectToolIntegration,
+  validateToolStateContract
+} from "../../tools/shared/projectToolIntegration.js";
+
+export async function run() {
+  const validTileState = {
+    documentModel: {
+      assetRefs: {
+        tilemapId: "tilemap.alpha",
+        tilesetId: "tileset.alpha",
+        parallaxSourceIds: ["parallax.alpha", "parallax.alpha"]
+      }
+    }
+  };
+  const validSpriteState = {
+    project: {
+      assetRefs: {
+        spriteId: "sprite.hero",
+        paletteId: "palette.hero"
+      }
+    }
+  };
+
+  const tileValidation = validateToolStateContract("tile-map-editor", validTileState);
+  assert.equal(tileValidation.valid, true);
+  assert.equal(tileValidation.contractId, "tool-state.tile-map-editor/1");
+  assert.equal(tileValidation.normalizedState.documentModel.assetRefs.tilemapId, "tilemap.alpha");
+  assert.deepEqual(tileValidation.normalizedState.documentModel.assetRefs.parallaxSourceIds, ["parallax.alpha"]);
+
+  const invalidSpriteValidation = validateToolStateContract("sprite-editor", { project: {} });
+  assert.equal(invalidSpriteValidation.valid, false);
+  assert.deepEqual(invalidSpriteValidation.issues, ["project.assetRefs block is required."]);
+
+  const integration = buildProjectToolIntegration({
+    "tile-map-editor": validTileState,
+    "sprite-editor": { project: {} },
+    "vector-asset-studio": { selectedPaletteId: "palette.shared" }
+  });
+
+  assert.equal(integration.contractSummary.schema, TOOL_DATA_CONTRACT_SCHEMA);
+  assert.equal(integration.contractSummary.version, TOOL_DATA_CONTRACT_VERSION);
+  assert.equal(integration.contractSummary.status, "invalid");
+  assert.deepEqual(integration.contractSummary.invalidToolIds, ["sprite-editor"]);
+  assert.equal(integration.tools["tile-map-editor"].contractStatus, "valid");
+  assert.equal(integration.tools["sprite-editor"].contractStatus, "invalid");
+  assert.equal(
+    integration.tools["sprite-editor"].contractIssues.includes("project.assetRefs block is required."),
+    true
+  );
+  assert.equal(integration.tools["vector-asset-studio"].contractStatus, "valid");
+  assert.deepEqual(integration.assetReferences.tilemapIds, ["tilemap.alpha"]);
+  assert.deepEqual(integration.assetReferences.tilesetIds, ["tileset.alpha"]);
+  assert.deepEqual(integration.assetReferences.parallaxSourceIds, ["parallax.alpha"]);
+  assert.deepEqual(integration.assetReferences.paletteIds, ["palette.shared"]);
+}
diff --git a/tests/tools/ToolBoundaryEnforcement.test.mjs b/tests/tools/ToolBoundaryEnforcement.test.mjs
@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+const ACTIVE_TOOL_FOLDERS = Object.freeze([
+  "Tilemap Studio",
+  "Parallax Scene Studio",
+  "Vector Map Editor",
+  "Vector Asset Studio",
+  "Sprite Editor"
+]);
+
+function listScriptFiles(directoryPath) {
+  const files = [];
+  const entries = readdirSync(directoryPath, { withFileTypes: true });
+  entries.forEach((entry) => {
+    const nextPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listScriptFiles(nextPath));
+      return;
+    }
+    if (entry.isFile() && (nextPath.endsWith(".js") || nextPath.endsWith(".mjs"))) {
+      files.push(nextPath);
+    }
+  });
+  return files;
+}
+
+function extractSpecifiers(fileText) {
+  const specifiers = [];
+  const fromMatches = fileText.matchAll(/from\s+["']([^"']+)["']/g);
+  for (const match of fromMatches) {
+    specifiers.push(match[1]);
+  }
+  const importCallMatches = fileText.matchAll(/import\s*\(\s*["']([^"']+)["']\s*\)/g);
+  for (const match of importCallMatches) {
+    specifiers.push(match[1]);
+  }
+  return specifiers;
+}
+
+function toPosixPath(value) {
+  return value.replace(/\\/g, "/");
+}
+
+export async function run() {
+  const toolsRoot = path.join(REPO_ROOT, "tools");
+
+  ACTIVE_TOOL_FOLDERS.forEach((toolFolder) => {
+    const toolPath = path.join(toolsRoot, toolFolder);
+    assert.equal(statSync(toolPath).isDirectory(), true, `${toolFolder} must exist.`);
+    const files = listScriptFiles(toolPath);
+
+    files.forEach((filePath) => {
+      const text = readFileSync(filePath, "utf8");
+      const specifiers = extractSpecifiers(text);
+      specifiers.forEach((specifier) => {
+        if (!specifier.startsWith("../")) {
+          return;
+        }
+        ACTIVE_TOOL_FOLDERS.forEach((candidateToolFolder) => {
+          if (candidateToolFolder === toolFolder) {
+            return;
+          }
+          const candidatePrefix = `../${candidateToolFolder}/`;
+          assert.equal(
+            specifier.startsWith(candidatePrefix),
+            false,
+            `${toPosixPath(filePath)} imports another active tool (${specifier}).`
+          );
+        });
+      });
+    });
+  });
+
+  const tilemapMain = readFileSync(path.join(toolsRoot, "Tilemap Studio", "main.js"), "utf8");
+  const parallaxMain = readFileSync(path.join(toolsRoot, "Parallax Scene Studio", "main.js"), "utf8");
+  const vectorAssetMain = readFileSync(path.join(toolsRoot, "Vector Asset Studio", "main.js"), "utf8");
+  const sharedHelper = readFileSync(path.join(toolsRoot, "shared", "toolSampleCatalog.js"), "utf8");
+
+  assert.match(tilemapMain, /from "\.\.\/shared\/toolSampleCatalog\.js"/);
+  assert.match(parallaxMain, /from "\.\.\/shared\/toolSampleCatalog\.js"/);
+  assert.match(vectorAssetMain, /from "\.\.\/shared\/toolSampleCatalog\.js"/);
+  assert.doesNotMatch(tilemapMain, /function normalizeSamplePath\(/);
+  assert.doesNotMatch(parallaxMain, /function normalizeSamplePath\(/);
+  assert.doesNotMatch(vectorAssetMain, /function normalizeSamplePath\(/);
+  assert.match(sharedHelper, /export function normalizeToolSamplePath\(/);
+}
diff --git a/tools/Parallax Scene Studio/main.js b/tools/Parallax Scene Studio/main.js
diff --git a/tools/Tilemap Studio/main.js b/tools/Tilemap Studio/main.js
diff --git a/tools/Vector Asset Studio/main.js b/tools/Vector Asset Studio/main.js
diff --git a/tools/shared/projectToolIntegration.js b/tools/shared/projectToolIntegration.js
diff --git a/tools/shared/toolSampleCatalog.js b/tools/shared/toolSampleCatalog.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_09_06_TOOL_LAUNCH_CONTRACT_ALIGNMENT`
	`1`	`+BUILD_PR_LEVEL_09_08_TOOL_DATA_CONTRACTS`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-NEXT: BUILD_PR_LEVEL_09_07_TOOL_BOUNDARY_NORMALIZATION`
	`1`	`+NEXT: BUILD_PR_LEVEL_09_09_ASSET_PIPELINE_TOOLING`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Aligned tool entry + config loading.`
	`1`	`+Introduces tool data contract layer.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Tool data contracts normalization (docs-only PR).`