Tighten schemas and validate samples/games against strict tool contracts - PR 11.98

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,26 +1,10 @@
-# Codex Command - PR 11.97
+# Codex Command - PR 11.98
 
 Model: GPT-5.4
 Reasoning: high
 
-```text
-Run BUILD_PR_LEVEL_11_97_FIX_ASSET_BROWSER_SCHEMA_PROPERLY.
+Run this from the repo root:
 
-Goal:
-Fix the Asset Browser schema to match the flat asset-browser.assets contract and update sample 1902 workspace data accordingly.
-
-Requirements:
-- Update tools/schemas/tools/asset-browser.schema.json.
-- asset-browser.assets must be a flat map of asset ids to entries.
-- Asset ids must follow <kind>.<domain>.<name>, for example image.sample1902.preview.
-- Asset entries require path, kind, and source.
-- Allow optional stretchOverride.uniformEdgeStretchPx on image.*.bezel asset entries.
-- Do not restore nested media.
-- Do not remove existing compatibility properties unless proven obsolete.
-- Fix sample 1902 preview asset to image.sample1902.preview.
-- Search for generic asset-browser asset id preview and fix if found.
-- Add/update docs/dev/reports/PR_11_97_schema_validation.md with exact validation results.
-- Run targeted validation only; do not run full sample suite.
-
-Return a ZIP artifact at <project folder>/tmp/PR_11_97_FIX_ASSET_BROWSER_SCHEMA_PROPERLY.zip.
+```powershell
+codex --model gpt-5.4 --reasoning high "Execute BUILD_PR_LEVEL_11_98_STRICT_SCHEMA_VALIDATION_AND_USAGE_REVIEW exactly. Tighten schemas so unknown fields are rejected, validate tools/workspaces/samples/games, update code that expects loose or legacy schema shapes, and write reports under docs/dev/reports. Do not add fallback/default payloads. Do not run the full samples suite unless required by shared loader changes."
 ```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Fix Asset Browser schema for flat manifest assets and sample 1902 preview id - PR 11.97
+Tighten schemas and validate samples/games against strict tool contracts - PR 11.98

docs/dev/reports/PR_11_98_strict_schema_validation_and_usage_review_report.md

@@ -0,0 +1,61 @@
+# PR 11.98 - Strict Schema Validation And Usage Review
+
+## Scope Executed
+- Tightened schema contracts for workspace/tool usage in scoped targets.
+- Added contract validation scripts:
+  - `scripts/PS/validate-tool-schemas.ps1`
+  - `scripts/PS/validate-sample-json.ps1`
+  - `scripts/PS/validate-game-manifests.ps1`
+  - `scripts/PS/validate-all-json-contracts.ps1`
+  - `scripts/validate-json-contracts.mjs`
+- Updated workspace runtime validator coverage in `tools/Workspace Manager/main.js` for strict constructs (`anyOf`, `allOf`, `not`, `propertyNames`, typed `additionalProperties`).
+- Enforced flat asset-browser schema contract updates and removed duplicate workspace palette alias key.
+
+## Required Reports Generated
+- `docs/dev/reports/schema_strictness_inventory.md`
+- `docs/dev/reports/schema_strictness_inventory.csv`
+- `docs/dev/reports/sample_json_schema_validation.csv`
+- `docs/dev/reports/game_manifest_schema_validation.csv`
+- `docs/dev/reports/tool_payload_schema_validation.csv`
+- `docs/dev/reports/schema_usage_code_updates.md`
+
+## Validation Commands Run
+1. `powershell -ExecutionPolicy Bypass -File .\\scripts\\PS\\validate-all-json-contracts.ps1 -Details`
+2. `powershell -ExecutionPolicy Bypass -File .\\scripts\\PS\\validate-tool-schemas.ps1`
+3. `powershell -ExecutionPolicy Bypass -File .\\scripts\\PS\\validate-sample-json.ps1`
+4. `powershell -ExecutionPolicy Bypass -File .\\scripts\\PS\\validate-game-manifests.ps1`
+5. `node tests/tools/ToolSchemaStrictModeValidation.test.mjs`
+6. `node tests/runtime/LaunchSmokeAllEntries.test.mjs --samples --sample-range=1902-1902 --tools`
+7. `node --check scripts/validate-json-contracts.mjs`
+8. `node --check "tools/Workspace Manager/main.js"`
+9. `node --check tests/tools/ToolSchemaStrictModeValidation.test.mjs`
+10. `node -e "...Asteroids manifest asset checks..."`
+11. `rg -n "assets/images/bezel\\.png|assets/images/background\\.png|bezel1\\.png" src tools games samples`
+12. `rg -n "asset-browser\\.assets\\.media|\\.assets\\.media" src tools games samples`
+
+## Validation Results
+- Tool schema validation: `total=17 invalid=0`
+- Sample JSON validation: `total=66 invalid=38`
+- Game manifest validation: `total=12 invalid=0`
+- Sample 1902 strict workspace validation test: PASS
+- Sample 1902 targeted launch smoke (with tools): PASS (19/19)
+- Asteroids manifest asset checks: PASS
+  - `image.asteroids.bezel.path = /games/Asteroids/assets/images/bezel.png`
+  - `image.asteroids.background.path = /games/Asteroids/assets/images/deluxe.png`
+  - `font.asteroids.vector-battle` present
+- Guessed chrome-path search:
+  - only expected manifest declaration hit for `bezel.png`
+  - no `assets.media` usage hits in scanned runtime/tool/sample paths
+
+## Blockers / Remaining Invalid Rows
+- 38 sample JSON files remain invalid under strict schema review.
+- Exact file-level errors are recorded in:
+  - `docs/dev/reports/sample_json_schema_validation.csv`
+- Dominant blocker patterns:
+  - legacy top-level `$schema` fields not accepted by strict tool schemas
+  - legacy `config` vs strict `payload` contract mismatches
+  - payload shape mismatches in older sample payload documents
+
+## Notes
+- No fallback/default payloads were introduced.
+- Full samples suite was skipped by design: this PR used targeted schema + targeted smoke validation only, and did not require a broad full-samples run.

docs/dev/reports/README_PR_11_98.md

@@ -0,0 +1,11 @@
+# PR 11.98 Expected Reports
+
+Codex must generate:
+- schema_strictness_inventory.md
+- schema_strictness_inventory.csv
+- sample_json_schema_validation.csv
+- game_manifest_schema_validation.csv
+- tool_payload_schema_validation.csv
+- schema_usage_code_updates.md
+
+These reports must identify every remaining blocker instead of silently accepting loose payloads.

docs/dev/reports/game_manifest_schema_validation.csv

@@ -0,0 +1,13 @@
+filePath,status,errorCount,firstErrors
+games/_template/game.manifest.json,valid,0,
+games/AITargetDummy/game.manifest.json,valid,0,
+games/Asteroids/game.manifest.json,valid,0,
+games/Bouncing-ball/game.manifest.json,valid,0,
+games/Breakout/game.manifest.json,valid,0,
+games/GravityWell/game.manifest.json,valid,0,
+games/Pacman/game.manifest.json,valid,0,
+games/Pong/game.manifest.json,valid,0,
+games/SolarSystem/game.manifest.json,valid,0,
+games/SpaceDuel/game.manifest.json,valid,0,
+games/SpaceInvaders/game.manifest.json,valid,0,
+games/vector-arcade-sample/game.manifest.json,valid,0,

docs/dev/reports/sample_json_schema_validation.csv

@@ -0,0 +1,67 @@
+filePath,schemaPath,status,errorCount,firstErrors,note
+samples/metadata/samples.index.metadata.json,,skipped,0,,no matching schema contract
+samples/phase-02/0204/sample.0204.3d-asset-viewer.json,tools/schemas/tools/3d-asset-viewer.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.asset3d: value must satisfy exactly one oneOf branch",
+samples/phase-02/0204/sample.0204.asset-browser.json,tools/schemas/tools/asset-browser.schema.json,invalid,3,"$: missing required key ""assets"" | $: unknown key ""$schema"" | $.payload: unknown key ""assetCatalog""",
+samples/phase-02/0207/sample.0207.palette.json,,skipped,0,,no matching schema contract
+samples/phase-02/0207/sample.0207.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-02/0213/sample.0213.palette.json,,skipped,0,,no matching schema contract
+samples/phase-02/0213/sample.0213.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-02/0214/sample.0214.palette.json,,skipped,0,,no matching schema contract
+samples/phase-02/0214/sample.0214.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-02/0219/sample.0219.palette.json,,skipped,0,,no matching schema contract
+samples/phase-02/0219/sample.0219.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-02/0221/sample-0221-tile-map-editor-document.json,,skipped,0,,no matching schema contract
+samples/phase-02/0221/sample.0221.palette.json,,skipped,0,,no matching schema contract
+samples/phase-02/0221/sample.0221.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.tileMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-02/0221/sample.0221.tile-model-converter.json,tools/schemas/tools/tile-model-converter.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-02/0224/sample-0224-tile-map-editor-document.json,,skipped,0,,no matching schema contract
+samples/phase-02/0224/sample.0224.palette.json,,skipped,0,,no matching schema contract
+samples/phase-02/0224/sample.0224.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-02/0224/sample.0224.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.tileMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-02/0226/sample.0226.skin-editor.json,tools/schemas/tools/skin-editor.schema.json,invalid,4,"$: unknown key ""$schema"" | $: unknown key ""config"" | $.payload: unknown key ""gameId""",
+samples/phase-02/0227/sample.0227.skin-editor.json,tools/schemas/tools/skin-editor.schema.json,invalid,4,"$: unknown key ""$schema"" | $: unknown key ""config"" | $.payload: unknown key ""gameId""",
+samples/phase-03/0301/sample.0301.palette.json,,skipped,0,,no matching schema contract
+samples/phase-03/0301/sample.0301.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-03/0302/sample.0302.palette.json,,skipped,0,,no matching schema contract
+samples/phase-03/0302/sample.0302.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-03/0305/sample-0305-tile-map-editor-document.json,,skipped,0,,no matching schema contract
+samples/phase-03/0305/sample.0305.palette.json,,skipped,0,,no matching schema contract
+samples/phase-03/0305/sample.0305.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.tileMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-03/0305/sample.0305.tile-model-converter.json,tools/schemas/tools/tile-model-converter.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-03/0308/sample.0308.palette.json,,skipped,0,,no matching schema contract
+samples/phase-03/0313/sample.0313.palette.json,,skipped,0,,no matching schema contract
+samples/phase-09/0901/sample.0901.palette.json,,skipped,0,,no matching schema contract
+samples/phase-09/0905/sample.0905.palette.json,,skipped,0,,no matching schema contract
+samples/phase-09/0905/sample.0905.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-12/1204/sample.1204.palette.json,,skipped,0,,no matching schema contract
+samples/phase-12/1205/sample.1205.palette.json,,skipped,0,,no matching schema contract
+samples/phase-12/1208/sample.1208.palette.json,,skipped,0,,no matching schema contract
+samples/phase-12/1208/sample.1208.parallax-editor.json,tools/schemas/tools/parallax-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.parallaxDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1208/sample.1208.svg-asset-studio.json,tools/schemas/tools/svg-asset-studio.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-12/1208/sample.1208.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,4,"$: unknown key ""$schema"" | $.payload: unknown key ""vectorAssetSvgPath"" | $.payload.parallaxDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1209/sample-1209-tile-map-editor-document.json,,skipped,0,,no matching schema contract
+samples/phase-12/1209/sample.1209.palette.json,,skipped,0,,no matching schema contract
+samples/phase-12/1209/sample.1209.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.tileMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1209/sample.1209.tile-model-converter.json,tools/schemas/tools/tile-model-converter.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-12/1210/sample-1210-tile-map-editor-document.json,,skipped,0,,no matching schema contract
+samples/phase-12/1210/sample.1210.palette.json,,skipped,0,,no matching schema contract
+samples/phase-12/1210/sample.1210.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.tileMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1211/sample-1211-tile-map-editor-document.json,,skipped,0,,no matching schema contract
+samples/phase-12/1211/sample.1211.palette.json,,skipped,0,,no matching schema contract
+samples/phase-12/1211/sample.1211.tile-map-editor.json,tools/schemas/tools/tile-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.tileMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1212/sample-1212-vector-map-editor.json,tools/schemas/tools/vector-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.vectorMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1213/sample-1213-vector-map-editor.json,tools/schemas/tools/vector-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.vectorMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1214/sample-1214-vector-map-editor.json,tools/schemas/tools/vector-map-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.vectorMapDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1215/sample-1215-svg-asset-studio.json,tools/schemas/tools/svg-asset-studio.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-12/1216/sample-1216-svg-asset-studio.json,tools/schemas/tools/svg-asset-studio.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-12/1217/sample-1217-svg-asset-studio.json,tools/schemas/tools/svg-asset-studio.schema.json,invalid,1,"$: unknown key ""$schema""",
+samples/phase-12/1218/sample-1218-parallax-editor.json,tools/schemas/tools/parallax-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.parallaxDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1219/sample-1219-parallax-editor.json,tools/schemas/tools/parallax-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.parallaxDocument: value must satisfy exactly one oneOf branch",
+samples/phase-12/1220/sample-1220-parallax-editor.json,tools/schemas/tools/parallax-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.parallaxDocument: value must satisfy exactly one oneOf branch",
+samples/phase-14/1413/sample.1413.3d-asset-viewer.json,tools/schemas/tools/3d-asset-viewer.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.asset3d: value must satisfy exactly one oneOf branch",
+samples/phase-14/1413/sample.1413.asset-browser.json,tools/schemas/tools/asset-browser.schema.json,invalid,3,"$: missing required key ""assets"" | $: unknown key ""$schema"" | $.payload: unknown key ""assetCatalog""",
+samples/phase-14/1413/sample.1413.asset-pipeline-tool.json,tools/schemas/tools/asset-pipeline-tool.schema.json,invalid,3,"$: unknown key ""$schema"" | $.payload: unknown key ""sampleImportInput"" | $.payload.pipelinePayload: value must satisfy exactly one oneOf branch",
+samples/phase-14/1414/sample.1414.palette.json,,skipped,0,,no matching schema contract
+samples/phase-14/1414/sample.1414.sprite-editor.json,tools/schemas/tools/sprite-editor.schema.json,invalid,2,"$: unknown key ""$schema"" | $.payload.spriteProject: value must satisfy exactly one oneOf branch",
+samples/phase-15/1505/sample.1505.asset-browser.json,tools/schemas/tools/asset-browser.schema.json,invalid,3,"$: missing required key ""assets"" | $: unknown key ""$schema"" | $.payload: unknown key ""assetCatalog""",
+samples/phase-19/1902/sample.1902.workspace-all-tools.json,tools/schemas/workspace.manifest.schema.json,valid,0,,