Skip to content

Commit 5bc8174

Browse files
author
DavidQ
committed
Add palette dependency rules to tool input contract - PR 11.130
1 parent 51a857b commit 5bc8174

4 files changed

Lines changed: 212 additions & 27 deletions

File tree

‎docs/dev/codex_commands.md‎

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,31 @@
11
# CODEX COMMANDS
22

33
Model: GPT-5.3-codex
4-
Reasoning: high
4+
Reasoning: medium
5+
6+
## PR
7+
BUILD_PR_LEVEL_11_130_TOOL_INPUT_CONTRACT_WITH_PALETTE_DEPENDENCY
58

69
STRICT SCOPE MODE
710

811
ALLOWED FILES:
9-
- tools/schemas/tools/*.json
10-
- routing files ONLY if needed
11-
12-
EXECUTION:
13-
14-
FOR EACH TOOL:
15-
16-
1. Load schema
17-
2. Test 3 inputs:
18-
A valid tool JSON → must pass
19-
B wrapper JSON → must fail
20-
C parent JSON → must fail
21-
22-
3. If B or C passes:
23-
- fix schema (tighten)
24-
- OR fix routing
25-
26-
4. DO NOT:
27-
- add compatibility
28-
- expand schema
29-
30-
5. REPORT:
31-
docs/dev/reports/tool_input_contract_11_129.txt
32-
33-
FAIL if any tool violates rule
12+
- docs only
13+
14+
TASK:
15+
16+
1. Document palette dependency rules
17+
2. Validate tools that require palette:
18+
- payload JSON direct
19+
- palette JSON direct
20+
3. Ensure:
21+
- no wrapper accepted
22+
- no parent JSON accepted
23+
- no fallback palette
24+
- no transform
25+
26+
REPORT:
27+
docs/dev/reports/tool_palette_dependency_11_130.txt
28+
29+
FAIL if any tool:
30+
- injects palette
31+
- transforms palette

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Verify all tools enforce direct JSON-only input contract - PR 11.129
1+
Add palette dependency rules to tool input contract - PR 11.130

‎docs/dev/reports/tool_palette_dependency_11_130.txt‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
BUILD_PR_LEVEL_11_130_TOOL_INPUT_CONTRACT_WITH_PALETTE_DEPENDENCY
2+
Report: tool_palette_dependency_11_130
3+
Date: 2026-04-30
4+
Mode: STRICT SCOPE (docs-only edits)
5+
6+
Scope
7+
- Document palette dependency rules.
8+
- Validate palette-dependent tools for:
9+
- direct tool payload JSON
10+
- direct palette JSON
11+
- Enforce:
12+
- no wrapper accepted
13+
- no parent JSON accepted
14+
- no fallback palette
15+
- no transform
16+
17+
Palette Dependency Rules (Observed)
18+
1) Workspace context palette gate applies to all non-palette tools.
19+
2) Palette Browser is the only tool exempt from the palette lock gate.
20+
3) Non-palette tools are blocked when shared palette is not ready.
21+
22+
Palette-dependent tool set (active, visible, non-palette):
23+
- vector-map-editor
24+
- svg-asset-studio
25+
- tile-map-editor
26+
- parallax-editor
27+
- sprite-editor
28+
- skin-editor
29+
- asset-browser
30+
- state-inspector
31+
- replay-visualizer
32+
- performance-profiler
33+
- physics-sandbox
34+
- asset-pipeline
35+
- tile-model-converter
36+
- 3d-json-payload
37+
- 3d-asset-viewer
38+
- 3d-camera-path-editor
39+
40+
Validation Results
41+
A) Direct tool payload JSON contract (per tool schema)
42+
- Result: PASS for all palette-dependent tools.
43+
- A valid direct tool JSON passes.
44+
- Wrapper JSON fails.
45+
- Parent/workspace JSON fails.
46+
47+
B) Direct palette JSON contract
48+
- Child tool routing path (workspace scoped preset for palette-browser):
49+
- PASS for direct-only requirement in child route.
50+
- Non-direct palette payload is rejected.
51+
52+
C) Prohibited behaviors
53+
1. No wrapper accepted
54+
- FAIL
55+
- Wrapper palette payload is still accepted in palette handoff extraction path via `wrappedPalettePayload`.
56+
57+
2. No parent JSON accepted
58+
- PASS (tool schema boundary)
59+
- Parent/workspace JSON rejected by tool payload schemas.
60+
61+
3. No fallback palette
62+
- FAIL
63+
- Fallback palette id/display name paths still exist.
64+
65+
4. No transform
66+
- FAIL
67+
- Palette transformation/normalization functions still used in handoff path:
68+
- hex normalization
69+
- swatch/entries/colors remap
70+
- synthetic display/name fallbacks
71+
72+
5. No palette injection
73+
- FAIL
74+
- Shared palette is injected into shared handoff storage from manifest/catalog hydration paths.
75+
76+
Evidence (code locations)
77+
- Direct-only child palette route enforcement:
78+
- tools/shared/platformShell.js:501-508
79+
- Palette wrapper acceptance in handoff extraction:
80+
- tools/shared/platformShell.js:1241-1244
81+
- Fallback palette id/display:
82+
- tools/shared/platformShell.js:1249-1253
83+
- tools/shared/platformShell.js:1218-1219
84+
- Palette transform functions and remap:
85+
- tools/shared/platformShell.js:1180-1209
86+
- tools/shared/platformShell.js:1213-1221
87+
- Palette injection into shared handoff:
88+
- tools/shared/platformShell.js:1287-1297
89+
- tools/shared/platformShell.js:1317-1328
90+
- tools/shared/platformShell.js:1351-1362
91+
- Palette dependency lock for non-palette tools:
92+
- tools/shared/platformShell.js:1551-1554
93+
- tools/shared/platformShell.js:1580-1587
94+
- tools/shared/platformShell.js:1891-1899
95+
96+
Final Status
97+
- FAIL
98+
Reason:
99+
- Palette wrapper acceptance remains in handoff extraction path.
100+
- Palette fallback generation remains.
101+
- Palette transformation and palette injection paths remain.

‎docs/pr/BUILD_PR_LEVEL_11_130_TOOL_INPUT_CONTRACT_WITH_PALETTE_DEPENDENCY.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# BUILD_PR_LEVEL_11_130_TOOL_INPUT_CONTRACT_WITH_PALETTE_DEPENDENCY
2+
3+
## Purpose
4+
Extend the tool input contract to explicitly handle tools that require a palette, while preserving the direct JSON, schema-only, no-transform rules.
5+
6+
## Scope
7+
- testable
8+
- docs-first
9+
- no implementation code
10+
- no schema changes unless explicitly requested
11+
- applies to all tools that may depend on a palette
12+
13+
## Core Rule (unchanged)
14+
15+
Tool must:
16+
- receive direct JSON payload
17+
- validate against its own schema
18+
- render
19+
20+
Tool must NOT:
21+
- accept wrapper {tool,payload}
22+
- accept game/workspace JSON
23+
- build input
24+
- transform input
25+
- fallback to defaults
26+
27+
## 🔷 Palette Dependency Caveat (MANDATORY)
28+
29+
If a tool requires a palette:
30+
31+
### Allowed
32+
- Tool may receive:
33+
- its primary JSON payload
34+
- a reference to a palette JSON
35+
- Routing layer (sample/workspace manager) may pass:
36+
- palette JSON as a separate input
37+
38+
### Required Rules
39+
- Palette must be:
40+
- its own JSON file
41+
- validated by palette-browser.schema.json
42+
- Tool must NOT:
43+
- embed palette data into its own payload
44+
- transform palette JSON
45+
- infer palette if missing
46+
- fallback to default palette
47+
48+
### Data Flow
49+
50+
tool payload JSON → tool schema validate
51+
palette JSON → palette schema validate
52+
tool uses palette JSON as-is
53+
54+
### Error Behavior
55+
56+
If palette is required but missing or invalid:
57+
- show visible error
58+
- do NOT:
59+
- inject default palette
60+
- attempt repair
61+
- convert parent JSON
62+
63+
## Validation
64+
65+
For tools with palette dependency:
66+
67+
Test:
68+
1. valid payload + valid palette → PASS
69+
2. valid payload + missing palette → FAIL
70+
3. valid payload + invalid palette → FAIL
71+
4. wrapper JSON → FAIL
72+
5. parent JSON → FAIL
73+
74+
## Reports
75+
76+
docs/dev/reports/tool_palette_dependency_11_130.txt:
77+
- tools requiring palette
78+
- validation results
79+
- violations found
80+
81+
## Acceptance
82+
83+
- palette dependency handled without breaking direct JSON contract
84+
- palette remains independent JSON
85+
- no fallback/default palette used
86+
- no schema boundary violations introduced

0 commit comments

Comments
 (0)