Skip to content

Commit 62090d2

Browse files
author
DavidQ
committed
Create tool launch SSoT data layer
PR Details: - Adds/normalizes one authoritative launch metadata source. - Keeps sample actions labeled Open <tool>. - Keeps game actions labeled Open with Workspace Manager. - Routes sample and game launch targets through the SSoT. - Preserves external launch memory clear behavior. - Adds validation report for SSoT data-layer behavior.
1 parent f36d9bd commit 62090d2

9 files changed

Lines changed: 583 additions & 63 deletions

‎docs/dev/codex_rules.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@ These rules OVERRIDE all other instructions.
44

55
Codex must prefer the existing repo pattern over any new pattern, unless the PR explicitly says otherwise.
66

7-
## Required Spec
7+
## Required Inputs
88

99
Read and obey:
1010

1111
- docs/dev/specs/TOOL_LAUNCH_SSOT.md
12+
- docs/dev/reports/tool_launch_ssot_routing_validation.md if present
1213

1314
## Required UI Labels
1415

@@ -23,19 +24,21 @@ Games:
2324
## This PR
2425

2526
Allowed:
26-
- smallest implementation changes needed for launch routing SSoT
27+
- create or normalize one launch SSoT data source
28+
- replace duplicated launch-path reads only where needed
2729
- validation report
2830
- roadmap status marker update only if execution-backed
2931

3032
Forbidden:
3133
- broad cleanup
3234
- unrelated refactoring
33-
- new route systems
35+
- new route systems beyond SSoT
3436
- fallback/default behavior
3537
- implementation outside touched launch path
3638
- start_of_day changes
3739
- roadmap text rewrite
3840
- changing required UI label semantics
41+
- second source of truth
3942

4043
## Anti-Patterns Forbidden
4144

@@ -48,7 +51,7 @@ Forbidden:
4851
- duplicated launch paths
4952
- silent redirects
5053
- broad truthy/falsy behavior changes
51-
- magic strings or magic numbers outside existing SSoT/config pattern
54+
- magic strings or magic numbers outside SSoT/config pattern
5255
- duplicate event listeners
5356
- globals
5457
- new managers/factories/service layers unless already required by existing pattern
@@ -57,7 +60,7 @@ Forbidden:
5760

5861
## Required Failure Behavior
5962

60-
If launch context is missing or invalid:
63+
If launch SSoT data is missing or invalid:
6164
- fail visibly
6265
- report the missing field
6366
- do not guess

‎docs/dev/reports/tool_launch_ssot_data_layer_validation.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Tool Launch SSoT Data Layer Validation
2+
3+
## Exact SSoT File Path
4+
5+
- `tools/shared/toolLaunchSSoTData.js`
6+
7+
## Changed Files
8+
9+
- `tools/shared/toolLaunchSSoTData.js`
10+
- `tools/shared/toolLaunchSSoT.js`
11+
- `samples/index.render.js`
12+
- `games/index.render.js`
13+
- `docs/dev/reports/tool_launch_ssot_data_layer_validation.md`
14+
15+
## List of Launch IDs
16+
17+
Command output:
18+
19+
```text
20+
launchIdsCount 18
21+
launchIds [
22+
'tool.vector-map-editor',
23+
'tool.vector-asset-studio',
24+
'tool.tile-map-editor',
25+
'tool.parallax-editor',
26+
'tool.sprite-editor',
27+
'tool.skin-editor',
28+
'tool.asset-browser',
29+
'tool.palette-browser',
30+
'tool.state-inspector',
31+
'tool.replay-visualizer',
32+
'tool.performance-profiler',
33+
'tool.physics-sandbox',
34+
'tool.asset-pipeline-tool',
35+
'tool.tile-model-converter',
36+
'tool.3d-json-payload-normalizer',
37+
'tool.3d-asset-viewer',
38+
'tool.3d-camera-path-editor',
39+
'workspace-manager.game-to-workspace'
40+
]
41+
```
42+
43+
Launch id structure is defined in SSoT data layer:
44+
45+
- `tools/shared/toolLaunchSSoTData.js:55`
46+
- `tools/shared/toolLaunchSSoTData.js:65`
47+
48+
## Proof Sample Actions Still Say `Open <tool>`
49+
50+
- `samples/index.render.js:104`
51+
52+
```text
53+
const label = `Open ${normalize(tool.displayName) || normalize(tool.name) || toolId}`;
54+
```
55+
56+
## Proof Game Actions Still Say `Open with Workspace Manager`
57+
58+
- `games/index.render.js:263`
59+
60+
```text
61+
Open with Workspace Manager
62+
```
63+
64+
## Proof Sample Target Paths Come From SSoT
65+
66+
1. Sample launch resolution now reads launch metadata from SSoT data layer:
67+
68+
- `tools/shared/toolLaunchSSoT.js:68`
69+
- `tools/shared/toolLaunchSSoT.js:72`
70+
71+
2. Sample launch target path is defined in SSoT data layer as `targetPath`:
72+
73+
- `tools/shared/toolLaunchSSoTData.js:53`
74+
- `tools/shared/toolLaunchSSoTData.js:57`
75+
76+
3. Sample UI launch call passes source/type context and uses resolver:
77+
78+
- `samples/index.render.js:92`
79+
- `samples/index.render.js:93`
80+
- `samples/index.render.js:94`
81+
82+
Command output proof:
83+
84+
```text
85+
sampleDefinition {
86+
launchDefinition: {
87+
launchId: 'tool.sprite-editor',
88+
displayName: 'Sprite Editor',
89+
targetPath: '/tools/Sprite%20Editor/index.html',
90+
allowedLaunchSources: [ 'samples', 'tools', 'workspace', 'internal' ],
91+
allowedLaunchTypes: [ 'sample-to-tool', 'tool-internal', 'workspace-internal' ]
92+
},
93+
error: ''
94+
}
95+
sampleLaunch {
96+
href: '/tools/Sprite%20Editor/index.html?sampleId=1208&sampleTitle=Tool+Formatted+Tiles+Parallax',
97+
error: ''
98+
}
99+
```
100+
101+
## Proof Game Workspace Manager Target Path Comes From SSoT
102+
103+
1. Game launch resolution now reads workspace launch metadata from SSoT data layer:
104+
105+
- `tools/shared/toolLaunchSSoT.js:101`
106+
- `tools/shared/toolLaunchSSoT.js:105`
107+
108+
2. Workspace Manager target path is defined in SSoT data layer as `targetPath`:
109+
110+
- `tools/shared/toolLaunchSSoTData.js:67`
111+
112+
3. Game UI launch call passes source/type context and uses resolver:
113+
114+
- `games/index.render.js:148`
115+
- `games/index.render.js:149`
116+
- `games/index.render.js:150`
117+
118+
Command output proof:
119+
120+
```text
121+
gameDefinition {
122+
launchDefinition: {
123+
launchId: 'workspace-manager.game-to-workspace',
124+
displayName: 'Workspace Manager',
125+
targetPath: '/tools/Workspace%20Manager/index.html',
126+
allowedLaunchSources: [ 'games', 'workspace', 'internal' ],
127+
allowedLaunchTypes: [ 'game-to-workspace', 'workspace-internal' ]
128+
},
129+
error: ''
130+
}
131+
gameLaunch {
132+
href: '/tools/Workspace%20Manager/index.html?gameId=2001&mount=game',
133+
error: ''
134+
}
135+
```
136+
137+
## Proof External Launch Memory Clear Remains Intact
138+
139+
Code path remains:
140+
141+
- `tools/shared/toolLaunchSSoT.js:121`
142+
- `tools/shared/toolLaunchSSoT.js:138`
143+
- `samples/index.render.js:539`
144+
- `games/index.render.js:419`
145+
146+
Command output proof:
147+
148+
```text
149+
clearResult true
150+
localAfterClear [ [ 'keep.one', 'x' ] ]
151+
sessionAfterClear [ [ 'keep.two', 'y' ] ]
152+
launchResult true
153+
assignCalls [ '/tools/Workspace%20Manager/index.html?gameId=2001&mount=game' ]
154+
localAfterLaunch [ [ 'keep.one', 'x' ] ]
155+
sessionAfterLaunch [ [ 'keep.two', 'y' ] ]
156+
```
157+
158+
## Proof Missing Target Does Not Fallback
159+
160+
1. Missing/invalid SSoT launch target id does not route and returns visible error:
161+
162+
```text
163+
missingSsotTarget { href: '', error: 'Tool "not-a-real-tool" is not registered.' }
164+
```
165+
166+
2. Invalid source/type for an SSoT launch id does not route and returns visible error:
167+
168+
```text
169+
disallowedSource {
170+
href: '',
171+
error: 'Launch "workspace-manager.game-to-workspace" does not allow source "samples".'
172+
}
173+
```
174+
175+
3. Guard rails are explicit in SSoT data + resolver:
176+
177+
- `tools/shared/toolLaunchSSoTData.js:100`
178+
- `tools/shared/toolLaunchSSoTData.js:121`
179+
- `tools/shared/toolLaunchSSoT.js:69`
180+
- `tools/shared/toolLaunchSSoT.js:102`
181+
182+
## Static Validation
183+
184+
Commands run:
185+
186+
```bash
187+
node --check tools/shared/toolLaunchSSoTData.js
188+
node --check tools/shared/toolLaunchSSoT.js
189+
node --check samples/index.render.js
190+
node --check games/index.render.js
191+
```
192+
193+
All commands exited successfully.
194+
195+
## Anti-Pattern Self-Check
196+
197+
- One launch SSoT data layer added; no second launch-path source introduced in touched flow.
198+
- No fallback/default route/tool/workspace logic added.
199+
- No duplicate event listeners introduced.
200+
- No new globals/managers/factories/service layers introduced.
201+
- No unrelated cleanup or scope expansion.

‎docs/operations/dev/codex_commands.md‎

Lines changed: 29 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Codex Commands — BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2
1+
# Codex Commands — BUILD_PR_LEVEL_20_9_TOOL_LAUNCH_SSOT_DATA_LAYER
22

33
## Model
44
GPT-5.4 or GPT-5.3-codex
@@ -11,21 +11,28 @@ High
1111
```text
1212
Read docs/dev/codex_rules.md first.
1313
Read docs/dev/specs/TOOL_LAUNCH_SSOT.md second.
14+
Read docs/dev/reports/tool_launch_ssot_routing_validation.md if present.
1415
15-
Execute BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2.
16+
Execute BUILD_PR_LEVEL_20_9_TOOL_LAUNCH_SSOT_DATA_LAYER.
1617
1718
Goal:
18-
Implement the first runtime slice of TOOL_LAUNCH_SSOT with exact UI launch wording.
19+
Create or normalize one runtime launch SSoT data layer for tool/workspace launch targets.
1920
2021
Required behavior:
21-
- samples launch tools through tools/<tool>/index.html
22-
- sample launch actions must be labeled: Open <tool>
23-
- games launch workspace flows through tools/Workspace Manager/index.html
24-
- game launch actions must be labeled: Open with Workspace Manager
25-
- external launches from samples/games clear launch memory before loading
26-
- launch data comes from the existing single source of truth
22+
- samples continue to use label: Open <tool>
23+
- samples launch tools through SSoT target paths: tools/<tool>/index.html
24+
- games continue to use label: Open with Workspace Manager
25+
- games launch Workspace Manager through SSoT target path: tools/Workspace Manager/index.html
26+
- external launches from samples/games still clear launch memory before loading
2727
- no default/fallback route/tool/workspace behavior in touched launch flow
28-
- invalid or missing launch context fails visibly
28+
- invalid or missing SSoT target fails visibly
29+
30+
SSoT must define:
31+
- launch id
32+
- display name
33+
- target path
34+
- allowed launch sources
35+
- allowed launch types
2936
3037
Hard constraints:
3138
- smallest valid change
@@ -34,20 +41,22 @@ Hard constraints:
3441
- no start_of_day changes
3542
- no roadmap text rewrite except status markers
3643
- no anti-patterns listed in docs/dev/codex_rules.md
37-
- do not alter the required label meanings
44+
- no second source of truth
45+
- do not alter required label meanings
3846
3947
Validation:
40-
Create docs/dev/reports/tool_launch_ssot_routing_validation.md with:
48+
Create docs/dev/reports/tool_launch_ssot_data_layer_validation.md with:
49+
- exact SSoT file path
4150
- changed files
42-
- tested UAT paths
43-
- proof sample actions are labeled Open <tool>
44-
- proof samples route to tools/<tool>/index.html
45-
- proof game actions are labeled Open with Workspace Manager
46-
- proof games route to tools/Workspace Manager/index.html
47-
- proof external launch memory is cleared
48-
- proof missing context does not fallback
51+
- list of launch ids
52+
- proof sample actions still say Open <tool>
53+
- proof game actions still say Open with Workspace Manager
54+
- proof sample target paths come from SSoT
55+
- proof game Workspace Manager target path comes from SSoT
56+
- proof external launch memory clear remains intact
57+
- proof missing target does not fallback
4958
- anti-pattern self-check
5059
5160
Return ZIP at:
52-
tmp/BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2.zip
61+
tmp/BUILD_PR_LEVEL_20_9_TOOL_LAUNCH_SSOT_DATA_LAYER.zip
5362
```

‎docs/operations/dev/commit_comment.txt‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
Implement tool launch SSoT routing with exact launch labels
1+
Create tool launch SSoT data layer
22

33
PR Details:
4-
- Routes sample-launched tools through explicit tools/<tool>/index.html targets using Open <tool>.
5-
- Routes game workspace flows through tools/Workspace Manager/index.html using Open with Workspace Manager.
6-
- Clears launch memory for external sample/game launches.
7-
- Removes default/fallback behavior from touched launch flow.
8-
- Adds validation report for SSoT routing and launch labels.
4+
- Adds/normalizes one authoritative launch metadata source.
5+
- Keeps sample actions labeled Open <tool>.
6+
- Keeps game actions labeled Open with Workspace Manager.
7+
- Routes sample and game launch targets through the SSoT.
8+
- Preserves external launch memory clear behavior.
9+
- Adds validation report for SSoT data-layer behavior.

0 commit comments

Comments
 (0)