Skip to content

Commit 810e6a3

Browse files
author
DavidQ
committed
Normalize palette contract to manifest SSoT and remove tool-level schema drift - PR 10.6B
1 parent 5a7637c commit 810e6a3

10 files changed

Lines changed: 185 additions & 64 deletions

‎docs/dev/codex_commands.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,28 @@
1-
# Codex Commands — LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT
1+
# CODEX COMMANDS — LEVEL 10.6B Palette Contract Alignment
22

3-
## Model
4-
GPT-5.4
3+
Model: GPT-5.4
4+
Reasoning: high
55

6-
## Reasoning
7-
high
6+
## PR Purpose
7+
Normalize palette payload contracts so palette data in manifest inputs and tool JSON inputs use the same canonical shape.
88

9-
## Command
9+
## Codex Command
1010
```powershell
11-
codex exec --model gpt-5.4 --reasoning high "Read docs/dev/PLAN_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md and docs/dev/BUILD_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md. Implement the smallest scoped PR to close standalone sample/tool data-flow generic failures for Phase 10.6B. Do not add silent fallback data, hardcoded asset paths, new features, or repo-wide cleanup. Preserve sample -> schema -> normalized input -> tool -> UI/state. Run npm run test:launch-smoke:games and npm run test:sample-standalone:data-flow. Update docs/dev/reports/level_10_6b_standalone_generic_failure_closeout_report.md and docs/dev/reports/level_10_6b_tool_contract_matrix.md with validation-backed results."
11+
codex --model gpt-5.4 --reasoning high "Implement LEVEL_10_6B_PALETTE_CONTRACT_ALIGNMENT. One PR purpose only. Do not add new features, schemas, tools, fallback data, hardcoded asset paths, or silent default loading. Fix palette contract drift only. Ensure palette-bearing standalone samples pass explicit data flow: sample -> manifest -> normalized input -> tool -> UI/state. Manifest palette payloads and tool palette JSON files must share the same canonical palette object shape: schema, version, name, source, swatches. Remove legacy leading metadata such as $schema from runtime palette payloads where it causes mismatch. Replace source values such as engine/paletteList with manifest or another explicit manifest-derived source where appropriate. Palette Browser and palette-dependent tools must consume payload.palette directly, then bind state.palette to UI. Do not reshape, merge, inject defaults, or auto-load hidden palettes inside tools. Update the standalone data-flow report/status only as needed after running tests. Run npm run test:launch-smoke:games and npm run test:sample-standalone:data-flow."
1212
```
1313

14-
## Validation
14+
## Required Validation
1515
```powershell
1616
npm run test:launch-smoke:games
1717
npm run test:sample-standalone:data-flow
1818
```
19+
20+
## Report to Inspect
21+
```powershell
22+
docs/dev/reports/level_10_6_standalone_tool_data_flow_report.md
23+
```
24+
25+
## Commit Comment
26+
```text
27+
Normalize palette contract to manifest SSoT and remove tool-level schema drift - PR 10.6B
28+
```

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1 @@
1-
fix: close standalone sample tool data-flow generic failures
2-
3-
Phase 10.6B tightens standalone sample/tool contracts by ensuring explicit sample payloads flow through schema/normalization into tool UI state without silent fallback data or hardcoded asset paths.
4-
5-
Validation:
6-
- npm run test:launch-smoke:games
7-
- npm run test:sample-standalone:data-flow
1+
Normalize palette contract to manifest SSoT and remove tool-level schema drift - PR 10.6B

‎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-27T16:19:34.300Z
3+
Generated: 2026-04-27T16:35:23.621Z
44

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

‎docs/dev/reports/level_10_6B_palette_contract_alignment.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# LEVEL 10.6B — Palette Contract Alignment
2+
3+
## PR Purpose
4+
Close the largest standalone sample generic-failure cluster by removing palette contract drift between manifest payloads and tool palette JSON files.
5+
6+
## Scope
7+
This PR is limited to palette payload contract alignment for standalone sample/tool stability.
8+
9+
## Problem
10+
Palette-bearing samples fail because the palette object passed through the manifest does not match the shape used by tool palette JSON files.
11+
12+
Observed manifest shape:
13+
14+
```json
15+
"palette-browser": {
16+
"schema": "html-js-gaming.tool.palette-browser",
17+
"version": 1,
18+
"name": "Palette Browser",
19+
"source": "manifest",
20+
"palette": {
21+
"schema": "html-js-gaming.palette",
22+
"version": 1,
23+
"name": "Asteroids Palette",
24+
"source": "singleton-merged-from-tool-palettes",
25+
"swatches": []
26+
}
27+
}
28+
```
29+
30+
Observed tool JSON shape:
31+
32+
```json
33+
{
34+
"$schema": "../../../tools/schemas/palette.schema.json",
35+
"schema": "html-js-gaming.palette",
36+
"version": 1,
37+
"name": "Sample 0302 Palette",
38+
"source": "engine/paletteList",
39+
"swatches": []
40+
}
41+
```
42+
43+
The leading metadata and legacy `source` value cause standalone samples to look loaded while tool state/UI receives a mismatched contract.
44+
45+
## Canonical Runtime Palette Shape
46+
Palette runtime payloads should use one canonical shape:
47+
48+
```json
49+
{
50+
"schema": "html-js-gaming.palette",
51+
"version": 1,
52+
"name": "Asteroids Palette",
53+
"source": "manifest",
54+
"swatches": [
55+
{
56+
"symbol": "!",
57+
"hex": "#1CAC78",
58+
"name": "color-001"
59+
}
60+
]
61+
}
62+
```
63+
64+
## Contract Rule
65+
66+
```text
67+
sample -> manifest -> normalized input -> tool -> UI/state
68+
```
69+
70+
For palette tools:
71+
72+
```text
73+
payload.palette -> state.palette -> UI
74+
```
75+
76+
The tool must not silently reshape, merge, inject fallback palettes, or auto-load hidden palette data.
77+
78+
## Codex Implementation Requirements
79+
- Normalize palette-bearing sample/tool data to the canonical runtime palette shape.
80+
- Remove `$schema` from runtime palette payloads where it creates tool/manifest mismatch.
81+
- Remove legacy `source: engine/paletteList` runtime usage.
82+
- Ensure Palette Browser consumes `payload.palette` directly.
83+
- Ensure palette-dependent tools do not read `paletteList`, `colors`, or `data.palette` unless explicitly normalized before tool entry.
84+
- Preserve explicit empty state behavior when no palette is provided.
85+
- Do not introduce new features, schemas, tools, hardcoded asset paths, or fallback data.
86+
- Update standalone data-flow test/report expectations only where they enforce the corrected contract.
87+
88+
## Expected Validation
89+
```powershell
90+
npm run test:launch-smoke:games
91+
npm run test:sample-standalone:data-flow
92+
```
93+
94+
Expected direction:
95+
96+
```text
97+
Generic failure signals detected: 0
98+
```
99+
100+
If not zero, remaining failures should be non-palette path/event-stream issues and should be handled in the next PR.

‎samples/phase-02/0213/sample.0213.palette-browser.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
"schema": "html-js-gaming.palette",
88
"version": 1,
99
"name": "Sample 0213 Palette",
10-
"source": "engine/paletteList",
11-
"entries": [
10+
"source": "manifest",
11+
"swatches": [
1212
{
1313
"symbol": "!",
1414
"hex": "#1E1B4B",

‎samples/phase-03/0308/sample.0308.palette-browser.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
"schema": "html-js-gaming.palette",
88
"version": 1,
99
"name": "Sample 0308 Palette",
10-
"source": "generated-from-sample-colors",
11-
"entries": [
10+
"source": "manifest",
11+
"swatches": [
1212
{
1313
"symbol": "!",
1414
"hex": "#1E1B4B",

‎samples/phase-03/0313/sample.0313.palette-browser.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
"schema": "html-js-gaming.palette",
88
"version": 1,
99
"name": "Sample 0313 Palette",
10-
"source": "generated-from-sample-colors",
11-
"entries": [
10+
"source": "manifest",
11+
"swatches": [
1212
{
1313
"symbol": "!",
1414
"hex": "#111827",

‎tests/runtime/SampleStandaloneToolDataFlow.test.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1162,7 +1162,7 @@ export async function run() {
11621162
if (testCase.toolId === "palette-browser") {
11631163
const palette = testCase.presetPayload?.config?.palette;
11641164
const expectedPaletteName = String(palette?.name || "").trim();
1165-
const expectedSwatchCount = Array.isArray(palette?.entries) ? palette.entries.length : 0;
1165+
const expectedSwatchCount = Array.isArray(palette?.swatches) ? palette.swatches.length : 0;
11661166
assert.ok(expectedPaletteName, `Missing expected palette name in ${toPosixPath(path.relative(repoRoot, testCase.presetFilePath))}.`);
11671167
assert.ok(expectedSwatchCount > 0, `Missing expected palette entries in ${toPosixPath(path.relative(repoRoot, testCase.presetFilePath))}.`);
11681168
const result = await runTargetedPaletteBrowserAssertion(page, url, expectedPaletteName, expectedSwatchCount);

0 commit comments

Comments
 (0)