Skip to content

Commit e0fe963

Browse files
ToolboxAidToolboxAid
committed
Canonicalize palette schema and enforce direct strict tool payload schemas - PR 11.19
1 parent 97e101b commit e0fe963

31 files changed

Lines changed: 556 additions & 402 deletions

‎docs/dev/codex_commands.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,22 @@
33
model: gpt-5.3-codex
44
reasoning: high
55

6-
Apply PR_11_18_FULL_STRICT_SCHEMA_MODE.
6+
Apply PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION.
77

88
Required:
9-
- Enforce `additionalProperties: false` on every object schema under `tools/schemas/**/*.json`.
10-
- No schema object may use `additionalProperties: true`.
11-
- No schema object may omit `additionalProperties`.
12-
- Explicitly define every allowed field instead of allowing loose payloads.
13-
- Complete missing/weak tool schemas rather than bypassing validation.
14-
- Workspace manifest must reference tool schemas via `$ref`.
15-
- Workspace `tools.palette` remains singular and required.
16-
- Workspace `tools.additionalProperties` must be false.
17-
- Validate all `$ref` targets resolve.
18-
- Add tests/checks that unknown fields fail validation.
9+
- Make `tools/schemas/tools/palette-browser.schema.json` the only canonical palette schema.
10+
- Move/merge correct palette schema content into `palette-browser.schema.json`.
11+
- Delete/remove all `tools/schemas/palette.schema*` files.
12+
- Ensure palette-browser schema is strict with `additionalProperties: false` everywhere.
13+
- Review `tools/schemas/sample.tool-payload.schema.json`; tools must validate only direct tool JSON schemas, not broad sample wrapper objects.
14+
- Remove/demote/narrow `sample.tool-payload.schema.json` so it cannot be used to validate arbitrary extra objects as tool payloads.
15+
- Rename tool schema `config` fields to a clearer field, preferably `payload`, consistently across schemas and sample 1902.
16+
- Replace generic use of `gameId` with a more generic identifier, preferably `projectId`; keep `gameId` only inside explicitly game-specific schemas.
17+
- Update Workspace manifest `$ref` targets to the canonical tool schemas.
18+
- Keep full strict mode: no `additionalProperties: true`, no omitted object `additionalProperties`.
1919
- Validate/rebuild only sample 1902 as needed.
20-
- Ensure sample 1902 Workspace shows all valid tools, not only Palette.
20+
- Do not modify other samples.
2121
- Do not add fallback/default/hidden data.
2222
- Do not modify start_of_day folders.
23-
- Add validation report at docs/dev/reports/PR_11_18_FULL_STRICT_SCHEMA_MODE_report.md.
24-
- Return ZIP artifact at tmp/PR_11_18_FULL_STRICT_SCHEMA_MODE_delta.zip.
23+
- Add validation report at docs/dev/reports/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_report.md.
24+
- Return ZIP artifact at tmp/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_delta.zip.

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Enforce full strict schema mode across tool and workspace schemas - PR 11.18
1+
Canonicalize palette schema and enforce direct strict tool payload schemas - PR 11.19

‎docs/dev/reports/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_report.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION Report
2+
3+
## Result
4+
- PASS
5+
6+
## Palette Schema Canonicalization
7+
8+
### Palette schema files found (pre-change)
9+
- `tools/schemas/palette.schema.json`
10+
- `tools/schemas/tools/palette.schema.json`
11+
- `tools/schemas/tools/palette-browser.schema.json`
12+
13+
### Palette schema files deleted
14+
- `tools/schemas/palette.schema.json`
15+
- `tools/schemas/tools/palette.schema.json`
16+
17+
### Final canonical palette schema path
18+
- `tools/schemas/tools/palette-browser.schema.json`
19+
20+
### Canonical palette schema contract
21+
- strict root with `additionalProperties: false`
22+
- required: `tool`, `version`, `payload`
23+
- `tool` const: `palette-browser`
24+
- `payload` strict object with required `schema`, `version`, `name`, `swatches`
25+
- `swatches[].symbol|hex|name` explicit and strict
26+
- no object schema uses `additionalProperties: true`
27+
28+
## Tool Payload Schema Cleanup
29+
30+
### `sample.tool-payload.schema.json` handling
31+
- Kept file path but demoted/narrowed its role to **sample wrapper only**.
32+
- Added explicit description that runtime tool payloads must validate against `tools/schemas/tools/*.schema.json`.
33+
- Added strict guard (`not` requiring `tool` + `payload`) so it cannot be used as tool payload schema.
34+
- Kept strict mode (`additionalProperties: false`) while allowing sample wrapper document keys via `patternProperties` + strict JSON value defs.
35+
36+
### `config` replacement choice
37+
- Chosen field: `payload`
38+
- Applied consistently across tool schemas and sample 1902 tool entries.
39+
40+
### generic `gameId` replacement choice
41+
- Chosen generic field: `projectId`
42+
- Replaced generic schema-level usage in `tools/schemas/tools/skin-editor.schema.json` (root field now `projectId`).
43+
- Updated sample 1902 generic payload usage:
44+
- `tools.skin-editor.projectId`
45+
- `tools.asset-pipeline-tool.payload.pipelinePayload.projectId`
46+
- Kept game-specific `gameId` only inside game-specific skin document section (`games.pong.skin/1`) in sample 1902.
47+
48+
## Workspace `$ref` Integration
49+
- Updated workspace manifest palette ref:
50+
- `tools/schemas/workspace.manifest.schema.json`
51+
- `tools.properties.palette -> $ref: ./tools/palette-browser.schema.json`
52+
- `tools.additionalProperties` remains `false`.
53+
- tool refs remain explicit by tool id.
54+
55+
## Schemas Updated
56+
- `tools/schemas/workspace.manifest.schema.json`
57+
- `tools/schemas/sample.tool-payload.schema.json`
58+
- `tools/schemas/tools/3d-asset-viewer.schema.json`
59+
- `tools/schemas/tools/3d-camera-path-editor.schema.json`
60+
- `tools/schemas/tools/3d-json-payload-normalizer.schema.json`
61+
- `tools/schemas/tools/asset-browser.schema.json`
62+
- `tools/schemas/tools/asset-pipeline-tool.schema.json`
63+
- `tools/schemas/tools/palette-browser.schema.json`
64+
- `tools/schemas/tools/parallax-editor.schema.json`
65+
- `tools/schemas/tools/performance-profiler.schema.json`
66+
- `tools/schemas/tools/physics-sandbox.schema.json`
67+
- `tools/schemas/tools/replay-visualizer.schema.json`
68+
- `tools/schemas/tools/skin-editor.schema.json`
69+
- `tools/schemas/tools/sprite-editor.schema.json`
70+
- `tools/schemas/tools/state-inspector.schema.json`
71+
- `tools/schemas/tools/tile-map-editor.schema.json`
72+
- `tools/schemas/tools/tile-model-converter.schema.json`
73+
- `tools/schemas/tools/vector-asset-studio.schema.json`
74+
- `tools/schemas/tools/vector-map-editor.schema.json`
75+
76+
## Sample 1902 Validation/Rebuild
77+
- Updated only:
78+
- `samples/phase-19/1902/sample.1902.workspace-all-tools.json`
79+
- Changes include:
80+
- tool entry `config` -> `payload`
81+
- `tools.palette` migrated to canonical palette-browser payload shape
82+
- `tools.palette-browser` given explicit strict payload
83+
- generic `projectId` replacements
84+
- removed nested tile payload `$schema` reference to `sample.tool-payload.schema.json`
85+
86+
## Unknown Field Rejection Result
87+
- Test injects `root.tools.asset-browser.payload.__unknown = true`.
88+
- Validation rejects injection (PASS).
89+
90+
## Validation Commands and Results
91+
- `node --check tests/tools/ToolSchemaStrictModeValidation.test.mjs` -> PASS
92+
- `node --check tests/tools/ToolWorkspaceSchemaManifestBoundaries.test.mjs` -> PASS
93+
- strict object audit across `tools/schemas/**/*.json` -> PASS (`issues: 0`)
94+
- `node -e "import { run } from './tests/tools/ToolSchemaStrictModeValidation.test.mjs'; await run();"` -> PASS
95+
- `npm run test:launch-smoke -- --tools` -> PASS (`PASS=287 FAIL=0 TOTAL=287`, includes sample `1902` PASS)
96+
97+
## Scope Confirmations
98+
- No samples changed outside `samples/phase-19/1902/`.
99+
- No `start_of_day` folders modified.
100+
- No fallback/default/hidden data added.

‎docs/dev/reports/REPORT_PR_11_19.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# REPORT_PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION
2+
3+
## Summary
4+
This PR cleans up schema SSoT:
5+
- one palette schema at tools/schemas/tools/palette-browser.schema.json
6+
- no broad sample wrapper schema for tool payloads
7+
- clearer payload naming instead of config
8+
- generic project/source identity instead of gameId where appropriate
9+
10+
## Target
11+
Tools validate direct strict tool JSON only.

‎docs/dev/reports/launch_smoke_report.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Launch Smoke Report
22

3-
Generated: 2026-04-29T02:30:38.214Z
3+
Generated: 2026-04-29T02:49:57.040Z
44

55
Filters: games=true, samples=true, tools=true, sampleRange=all
66

‎docs/pr/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION/BUILD.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# BUILD_PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION
2+
3+
## Required Codex Work
4+
5+
### 1. Canonicalize Palette schema
6+
Use:
7+
`tools/schemas/tools/palette-browser.schema.json`
8+
9+
This is the only valid palette schema location/name.
10+
11+
Current uploaded palette-browser schema is too loose:
12+
- `additionalProperties: true`
13+
- generic `config`
14+
- does not define swatches
15+
16+
Replace/merge it with the correct palette content from existing `tools/schemas/palette.schema*`.
17+
18+
Delete/remove all `tools/schemas/palette.schema*` files after migration.
19+
20+
Expected strict palette-browser payload:
21+
- `tool`: const `palette-browser`
22+
- `version`
23+
- clear payload field, not loose config
24+
- palette id/name/source/sourceId as needed
25+
- swatches array
26+
- each swatch explicitly defines symbol/hex/name or repo standard fields
27+
- `additionalProperties: false` on every object
28+
29+
### 2. Remove broad sample wrapper validation from tool loading
30+
Review:
31+
`tools/schemas/sample.tool-payload.schema.json`
32+
33+
Goal:
34+
- Tools should accept only tool JSON files.
35+
- Extra objects/wrapper objects should not validate.
36+
- If sample tooling still needs a wrapper schema, move it to a sample/test-specific role and do not use it as the tool payload schema.
37+
38+
Update tool launch/load validation so tool payloads `$ref` their actual tool schema.
39+
40+
### 3. Rename generic `config`
41+
Across tool schemas, replace `config` with a clearer field.
42+
43+
Preferred field:
44+
`payload`
45+
46+
Rationale:
47+
- `config` is too vague.
48+
- `payload` means the tool-owned document/data to render/edit.
49+
50+
If an existing repo standard is discovered, use it consistently and document the choice.
51+
52+
Update sample 1902 and validation fixtures as needed.
53+
54+
### 4. Make `gameId` generic
55+
Replace tool/workspace schema fields that require `gameId` when the payload may represent a sample/tool/workspace.
56+
57+
Preferred:
58+
- `projectId`
59+
60+
Allowed alternatives if already used consistently:
61+
- `sourceId`
62+
- `workspaceId`
63+
64+
Rules:
65+
- Do not require `gameId` for generic tool payloads.
66+
- If game-specific schemas need `gameId`, keep it only in game-specific schema sections.
67+
- Sample 1902 must validate without pretending to be a game.
68+
69+
### 5. Workspace schema integration
70+
Update Workspace manifest `$ref` targets to use:
71+
- `tools/schemas/tools/palette-browser.schema.json`
72+
- other tool schemas directly
73+
74+
Ensure:
75+
- `tools.additionalProperties: false`
76+
- all referenced tool schemas are strict
77+
- unknown keys fail validation
78+
- unknown fields inside payloads fail validation
79+
80+
### 6. Validation report
81+
Create:
82+
docs/dev/reports/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION_report.md
83+
84+
Report must include:
85+
- palette schema files found
86+
- palette schema files deleted
87+
- final canonical palette schema path
88+
- how `sample.tool-payload.schema.json` was handled
89+
- chosen replacement for `config`
90+
- chosen replacement for generic `gameId`
91+
- schemas updated
92+
- sample 1902 validation result
93+
- unknown-field rejection result
94+
- confirmation no other samples changed
95+
- confirmation no start_of_day changes
96+
97+
## Constraints
98+
- One PR purpose only.
99+
- Do not loosen schemas to make validation pass.
100+
- Do not keep duplicate palette schemas.
101+
- Do not modify unrelated samples.
102+
- No fallback/default/hidden data.

‎docs/pr/PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION/PLAN.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# PLAN_PR_11_19_SCHEMA_CLEANUP_TOOL_PAYLOADS_AND_PALETTE_CANONICALIZATION
2+
3+
## Purpose
4+
Clean up schema ownership so tools accept only valid tool JSON payloads, Palette has one canonical schema, and confusing generic schema fields are renamed.
5+
6+
## Problems
7+
1. Palette schema duplication:
8+
- Correct canonical location/name should be:
9+
`tools/schemas/tools/palette-browser.schema.json`
10+
- Existing `tools/schemas/palette.schema*` files should be removed after their content is moved/merged.
11+
- Only one palette schema should remain: palette-browser.
12+
13+
2. `sample.tool-payload.schema.json` is too broad:
14+
- Tools should accept only tool JSON payloads.
15+
- Sample wrapper objects and extra objects should not validate as tool payloads.
16+
- Tool schemas should be referenced directly with `$ref`.
17+
18+
3. Tool schemas use a generic `config` section:
19+
- Rename to a clearer field name that describes what it contains.
20+
- Suggested: `payload`
21+
- Alternative acceptable if repo standard exists: `toolData` or `document`
22+
23+
4. `gameId` is too narrow:
24+
- Workspace/sample 1902 is not necessarily a game.
25+
- Replace or supplement with a generic identifier.
26+
- Suggested: `projectId`, `sourceId`, or `workspaceId` depending on context.
27+
28+
## Scope
29+
- Schema files under `tools/schemas/`
30+
- Tool payload validation
31+
- Workspace manifest schema references
32+
- Sample 1902 only if required to validate
33+
- Do not modify other samples
34+
- Do not modify start_of_day folders
35+
36+
## Acceptance
37+
- Only one canonical palette schema exists: `tools/schemas/tools/palette-browser.schema.json`
38+
- `tools/schemas/palette.schema*` files are deleted/removed
39+
- `palette-browser.schema.json` contains the real strict palette payload schema
40+
- Tools validate against tool-specific schemas directly, not broad sample wrapper schema
41+
- `sample.tool-payload.schema.json` is removed, demoted, or narrowed so it cannot accept extra wrapper data
42+
- `config` is renamed to a clearer schema field consistently
43+
- `gameId` is replaced/supplemented with a generic identifier suitable for samples and games

0 commit comments

Comments
 (0)