Enforce tool payload schema boundaries and route exact child JSON inputs - PR 11.122-123-124

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,70 +1,27 @@
 # CODEX COMMANDS
 
 Model: GPT-5.3-codex
-Reasoning: medium
+Reasoning: high
 
-## PR
-BUILD_PR_LEVEL_11_121_VALIDATE_SSOT_TOOL_RELATIONSHIPS_LOAD_DIRECT_JSON
+## EXECUTION MODE: FORCE WRITE
 
-## Execute
+1. Open:
+   workspace.manifest.schema.json
+   palette-browser.schema.json
 
-1. Continue from PR 11.120 where hub counts match.
+2. MODIFY FILES DIRECTLY:
+   - remove palette payload from workspace schema
+   - simplify palette schema to payload-only
 
-2. Use only this SSoT:
-   - samples/metadata/samples.index.metadata.json
+3. SAVE FILES
 
-3. For every sample/tool relationship in the SSoT:
-   - identify sample id
-   - identify tool id
-   - identify explicit JSON input path
-   - identify schema path
-   - verify JSON exists
-   - verify JSON parses
-   - verify JSON validates against schema
-   - verify tool loading path uses JSON directly without fallback/default/preset
+4. VERIFY:
+   - re-open files
+   - confirm changes exist
 
-4. Fix deterministic issues:
-   - path typo/casing
-   - stale schema filename
-   - stale canonical tool name
-   - extra invalid fields
-   - compact primitive-array formatting
-   - obvious property-name mismatch
+5. OUTPUT:
+   - list of files changed
+   - before/after diff
 
-5. Remove relationship from SSoT when:
-   - JSON input missing
-   - real required data missing
-   - tool needs defaults to render
-   - relationship is unrelated to sample
-   - intent is ambiguous
-
-6. Do not:
-   - add fake data
-   - add fallback/default/preset data
-   - normalize/transform/convert runtime data
-   - reintroduce duplicate relationship sources
-
-7. Validate after changes:
-   - changed JSON parses
-   - SSoT metadata validates
-   - sample hub count matches SSoT
-   - tools hub count matches SSoT
-   - known-bad links remain absent
-   - no second active source exists
-
-8. Write populated reports:
-   - docs/dev/reports/ssot_relationship_load_validation_11_121.txt
-   - docs/dev/reports/relationships_fixed_11_121.txt
-   - docs/dev/reports/relationships_removed_11_121.txt
-   - docs/dev/reports/relationships_working_11_121.txt
-   - docs/dev/reports/validation_after_11_121.txt
-
-9. Reports must include final count.
-
-10. Roadmap:
-   - status-only update if execution-backed
-   - do not rewrite roadmap text
-   - do not delete roadmap text
-
-11. Package Codex output ZIP at:
-   tmp/PR_11_121_VALIDATE_SSOT_TOOL_RELATIONSHIPS_LOAD_DIRECT_JSON.zip
+6. IF NO FILES CHANGED:
+   FAIL EXECUTION

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Validate SSoT sample tool relationships load direct JSON - PR 11.121
+Force actual schema file changes instead of no-op runs - PR 11.124

docs/dev/reports/file_diff_11_124.txt

@@ -0,0 +1,38 @@
+PR 11.122 - Palette Schema Payload Only
+
+PASS
+
+Changed schema
+- tools/schemas/tools/palette-browser.schema.json
+
+Direct palette JSON contract
+- schema: html-js-gaming.palette
+- version: integer >= 1
+- name: non-empty string
+- swatches: array of swatch objects
+- optional: $schema, id, source, sourceId, locked
+
+Removed wrapper acceptance
+- oneOf removed.
+- $defs.toolPayload removed.
+- properties.tool removed.
+- properties.payload removed.
+- Wrapper object { tool, version, payload } no longer validates as Palette Browser input.
+
+Validation evidence
+- node schema-only validation: samples/phase-02/0213/sample.0213.palette.json PASS valid.
+- node schema-only validation: wrapper { tool, version, payload } PASS invalid.
+- node schema-only validation: samples/phase-19/1902/sample.1902.workspace-all-tools.json PASS invalid against palette-browser schema.
+- node schema-only validation: games/Asteroids/game.manifest.json PASS invalid against palette-browser schema.
+- node inspection: palette wrapper schema fields remaining: none.
+
+Search evidence
+- rg against tools/schemas/tools/palette-browser.schema.json found no oneOf, toolPayload, properties.tool, or properties.payload wrapper contract.
+- rg against samples/phase-19/1902/sample.1902.workspace-all-tools.json and palette schema found no palette-browser wrapper tool/payload entry for sample 1902.
+
+Runtime loader change
+- tools/Palette Browser/main.js now imports the fetched raw preset as direct palette JSON instead of extracting rawPreset.payload.
+- logToolLoadLoaded remains the schema-only gate before Palette Browser imports the data.
+
+Blockers
+- None.

docs/dev/reports/forced_changes_11_124.txt

@@ -0,0 +1,29 @@
+PR 11.123 - Schema Separation Restore / Revert Review
+
+PASS
+
+Workspace manifest result
+- tools/schemas/workspace.manifest.schema.json already uses $ref for Palette Browser:
+  tools.palette-browser -> ./tools/palette-browser.schema.json
+- No swatch, palette symbol, palette hex, palette name, sourceId, locked, or html-js-gaming.palette child details are in the workspace palette-browser node.
+- No code revert was required in workspace.manifest.schema.json.
+
+Palette schema result
+- tools/schemas/tools/palette-browser.schema.json owns palette details.
+- It validates direct palette JSON only.
+- It contains the swatch schema and swatch fields.
+- It does not accept { tool, version, payload } wrappers.
+- It does not accept game, workspace, or sample parent JSON.
+
+Separation decision
+- Parent schemas validate parent document structure.
+- Workspace manifest references tool schemas instead of duplicating tool internals.
+- Tool schemas validate their direct input documents.
+- Routing code is responsible for selecting/passing the correct child payload.
+
+Files changed for PR 11.123
+- Report files only.
+- No implementation changes were needed beyond the already staged valid 11.122 separation work.
+
+Blockers
+- None.

docs/dev/reports/palette_schema_payload_only_11_122.txt

@@ -0,0 +1,55 @@
+PR 11.123 - Staged Changes Review
+
+PASS
+
+Command run first
+- git diff --staged --stat
+- git diff --staged --name-only
+- git diff --staged -- schema/routing target files
+
+Staged files inspected
+- docs/dev/codex_commands.md
+- docs/dev/commit_comment.txt
+- docs/dev/reports/palette_schema_payload_only_11_122.txt
+- docs/dev/reports/tool_schema_boundary_11_122.txt
+- docs/dev/reports/validation_after_11_122.txt
+- docs/dev/reports/workspace_tool_payload_routing_11_122.txt
+- docs/dev/restart_notes_11_122.md
+- docs/pr/BUILD_PR_LEVEL_11_122_TOOL_SCHEMA_BOUNDARY_AND_PAYLOAD_ROUTING.md
+- samples/phase-19/1902/sample.1902.workspace-all-tools.json
+- scripts/validate-json-contracts.mjs
+- tests/tools/ToolSchemaStrictModeValidation.test.mjs
+- tools/Palette Browser/main.js
+- tools/Workspace Manager/main.js
+- tools/schemas/tools/palette-browser.schema.json
+- tools/shared/platformShell.js
+
+Schema/routing files staged
+- samples/phase-19/1902/sample.1902.workspace-all-tools.json
+- scripts/validate-json-contracts.mjs
+- tests/tools/ToolSchemaStrictModeValidation.test.mjs
+- tools/Palette Browser/main.js
+- tools/Workspace Manager/main.js
+- tools/schemas/tools/palette-browser.schema.json
+- tools/shared/platformShell.js
+
+Workspace manifest staged status
+- tools/schemas/workspace.manifest.schema.json was not staged and had no content diff.
+- Verification showed tools.palette-browser is { "$ref": "./tools/palette-browser.schema.json" }.
+- No palette/swatch internals were present in workspace.manifest.schema.json.
+
+Staged changes preserved
+- Palette Browser direct-palette schema change is valid separation of duties.
+- Sample 1902 direct tools.palette-browser palette payload is valid because workspace schema references the Palette Browser schema instead of inlining it.
+- Workspace Manager direct-palette classification is valid routing support for the referenced child payload.
+- platformShell direct-palette routing is valid pass-through support.
+- Validation helper updates are valid because they stop assuming every tool schema has a wrapper payload property.
+
+Staged changes reverted
+- None. No staged schema/routing file was found to violate separation of duties.
+
+Unrelated staged/modified work
+- docs/dev/codex_commands.md and docs/dev/commit_comment.txt were inspected by filename/status only and left untouched.
+
+Blockers
+- None.

docs/dev/reports/schema_separation_revert_11_123.txt

@@ -0,0 +1,66 @@
+PR 11.122 - Tool Schema Boundary
+
+PASS
+
+Purpose
+- Correct the boundary so child tool schemas do not validate parent game/workspace/sample documents.
+- Palette Browser is now schema-bound to direct palette JSON only.
+
+Files searched / reviewed
+- docs/pr/BUILD_PR_LEVEL_11_122_TOOL_SCHEMA_BOUNDARY_AND_PAYLOAD_ROUTING.md
+- tools/schemas/tools/*.schema.json
+- tools/schemas/tools/palette-browser.schema.json
+- tools/schemas/workspace.manifest.schema.json
+- tools/shared/platformShell.js
+- tools/Workspace Manager/main.js
+- tools/Palette Browser/main.js
+- samples/phase-19/1902/sample.1902.workspace-all-tools.json
+- samples/metadata/samples.index.metadata.json
+
+Tool schemas reviewed
+- 3d-asset-viewer.schema.json
+- 3d-camera-path-editor.schema.json
+- 3d-json-payload.schema.json
+- asset-browser.schema.json
+- asset-pipeline.schema.json
+- palette-browser.schema.json
+- parallax-editor.schema.json
+- performance-profiler.schema.json
+- physics-sandbox.schema.json
+- replay-visualizer.schema.json
+- skin-editor.schema.json
+- sprite-editor.schema.json
+- state-inspector.schema.json
+- svg-asset-studio.schema.json
+- tile-map-editor.schema.json
+- tile-model-converter.schema.json
+- vector-map-editor.schema.json
+
+Schemas changed
+- tools/schemas/tools/palette-browser.schema.json
+
+Schema decision
+- Removed Palette Browser wrapper acceptance from the child tool schema.
+- Removed oneOf wrapper mode.
+- Removed $defs.toolPayload.
+- Removed top-level tool.
+- Removed wrapper payload.
+- Kept direct palette fields only: $schema, schema, version, id, name, source, sourceId, locked, swatches.
+
+Other tool schema review result
+- The remaining tool schemas were reviewed for parent game/workspace/sample document acceptance.
+- No other tool schema was changed in this PR.
+- Existing tool schemas that use tool/version/payload are the current direct tool JSON contracts for those tools; they do not accept game/workspace/sample parent documents.
+- Broadly converting every tool contract from tool/version/payload into inner payload-only shape was intentionally not done because PR 11.122 specifically identified Palette Browser's dual wrapper/direct acceptance as the boundary violation.
+
+Files changed
+- samples/phase-19/1902/sample.1902.workspace-all-tools.json
+- scripts/validate-json-contracts.mjs
+- tests/tools/ToolSchemaStrictModeValidation.test.mjs
+- tools/Palette Browser/main.js
+- tools/Workspace Manager/main.js
+- tools/schemas/tools/palette-browser.schema.json
+- tools/shared/platformShell.js
+
+Blockers
+- None.

docs/dev/reports/staged_changes_review_11_123.txt

@@ -0,0 +1,39 @@
+PR 11.123 - Tool Schema Payload Review
+
+PASS
+
+Scope reviewed
+- tools/schemas/tools/*.schema.json
+
+Review criteria
+- Root schema is an object.
+- Root schema has additionalProperties: false.
+- Schema does not include parent workspace-manifest, game.manifest, samples.index.metadata, or sample metadata terms.
+- Palette Browser schema owns palette details directly and rejects wrappers.
+
+Per-schema result
+- 3d-asset-viewer.schema.json: PASS
+- 3d-camera-path-editor.schema.json: PASS
+- 3d-json-payload.schema.json: PASS
+- asset-browser.schema.json: PASS
+- asset-pipeline.schema.json: PASS
+- palette-browser.schema.json: PASS
+- parallax-editor.schema.json: PASS
+- performance-profiler.schema.json: PASS
+- physics-sandbox.schema.json: PASS
+- replay-visualizer.schema.json: PASS
+- skin-editor.schema.json: PASS
+- sprite-editor.schema.json: PASS
+- state-inspector.schema.json: PASS
+- svg-asset-studio.schema.json: PASS
+- tile-map-editor.schema.json: PASS
+- tile-model-converter.schema.json: PASS
+- vector-map-editor.schema.json: PASS
+
+Notes
+- Many non-palette tool schemas currently use tool/version/payload as their direct tool JSON input shape. That is not a parent game/workspace/sample schema and was not changed in this PR.
+- No schema was found inlining another tool's payload details.
+- Workspace manifest keeps tool details behind $ref entries.
+
+Blockers
+- None.

docs/dev/reports/tool_schema_boundary_11_122.txt

@@ -0,0 +1,43 @@
+PR 11.122 - Validation After Changes
+
+PASS
+
+Commands run and results
+- node --check "tools/Palette Browser/main.js"
+  Result: PASS
+- node --check "tools/Workspace Manager/main.js"
+  Result: PASS
+- node --check tools/shared/platformShell.js
+  Result: PASS
+- node --check scripts/validate-json-contracts.mjs
+  Result: PASS
+- node --check tests/tools/ToolSchemaStrictModeValidation.test.mjs
+  Result: PASS
+- JSON parse check for tools/schemas/tools/palette-browser.schema.json, tools/schemas/workspace.manifest.schema.json, samples/phase-19/1902/sample.1902.workspace-all-tools.json, samples/metadata/samples.index.metadata.json
+  Result: PASS
+- Palette schema-only validation using tools/shared/schemaOnlyToolPresetValidation.js
+  Result: direct palette PASS valid; wrapper PASS invalid; workspace manifest PASS invalid; Asteroids game manifest PASS invalid
+- node -e import('./tests/tools/ToolSchemaStrictModeValidation.test.mjs').then(m => m.run())
+  Result: PASS
+- node -e import('./tests/tools/ToolWorkspaceSchemaManifestBoundaries.test.mjs').then(m => m.run())
+  Result: PASS
+- node ./tests/runtime/LaunchSmokeAllEntries.test.mjs --samples --sample-range=1902-1902 --tools
+  Result: PASS=19 FAIL=0 TOTAL=19
+- node metadata relationship count
+  Result: samples.metadata roundtripToolPresets count 31; missing explicit fields 0
+- git diff --check
+  Result: PASS
+
+Required acceptance evidence
+- valid palette JSON passes palette schema: PASS
+- { tool, version, payload } wrapper fails palette schema: PASS
+- game/workspace JSON fails palette-browser schema: PASS
+- sample/tool relationships still point to explicit tool JSON: PASS, 31 relationships and 0 missing explicit fields
+- schema-only validation remains active: PASS, logToolLoadLoaded still calls enforceToolPresetSchemaOnlyContract
+- no fallback/default/preset data introduced: PASS, changes route existing explicit JSON only
+
+Full samples smoke
+- Skipped by PR instruction because this is targeted schema boundary/routing cleanup and full samples smoke takes approximately 20 minutes.
+
+Blockers
+- None.