Enforce sample metadata SSoT and remove renderer tool-link inference - PR 11.119

Author: DavidQ

docs/dev/codex_commands.md

@@ -4,81 +4,93 @@ Model: GPT-5.3-codex
 Reasoning: medium
 
 ## PR
-BUILD_PR_LEVEL_11_118_SAMPLE_TILE_LINK_SSOT_ENFORCEMENT
+BUILD_PR_LEVEL_11_119_SAMPLE_METADATA_SSOT_AND_RENDERER_GUARD_REMOVAL
 
 ## Execute
 
-This replaces PR 11.117. Do not run 11.117.
-
-1. Trace where visible sample tile "Open <tool>" links actually come from.
-
-2. Search candidate sources:
-   - samples/index.html
-   - samples index JSON/JS files
-   - generated sample registry files
-   - sample tile renderer data/config
-   - samples2tools data
-   - sample manifests
-   - per-sample metadata JSON
-   - generated static metadata used by samples page
-
-3. Identify the one active SSoT file for sample tile tool links.
-
-4. Enforce only one active source:
-   - update loader/index code to use only the SSoT if needed
-   - delete stale duplicate link files if safe
-   - otherwise disable them from runtime loading and report why
-
-5. Remove known-bad links from the SSoT and any active duplicates:
-   - 0201: remove unrelated Open Tool links
-   - 0202: remove unrelated Open Tool links
-   - 0204: remove unrelated Open Tool links
-   - 0210: remove unrelated Open Tool links
-   - 0220: remove unrelated Open Tool links
-   - 0221: remove 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
-   - 0226: remove unrelated Open Tool links
-   - 0227: remove unrelated Open Tool links
-   - 0303: remove unrelated Open Tool links
-   - 0305: remove 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
-   - 0901: remove Vector Map Editor
-   - 1204: remove SVG Asset Studio
-   - 1205: remove Vector Map Editor
-   - 1208: remove 3D Asset Viewer and SVG Asset Studio
-   - 1319: remove unrelated Open Tool links
-
-6. Delete bad/stale launcher data that is not the SSoT and can reintroduce bad links.
-
-7. Do not:
-   - delete samples
+1. Treat this as the correction to PR 11.118.
+
+2. Confirm the active sample tile renderer path:
+   - inspect `samples/index.render.js`
+   - inspect any imports/loaders used by that renderer
+
+3. Make this the only SSoT for sample tile tool roundtrip links:
+   - `samples/metadata/samples.index.metadata.json`
+
+4. Remove renderer/toolhint logic that can create roundtrip links from anything except:
+   - `toolHints`
+   - `roundtripToolPresets`
+   in the metadata SSoT file.
+
+5. Remove logic that:
+   - infers tool hints from sample ids
+   - infers tool hints from sample titles
+   - infers tool hints from sample paths
+   - infers tool hints from JSON files in sample folders
+   - uses fallback/default tool hint arrays
+   - uses samples2tools as active sample tile source
+   - restores stale/generated tool links
+
+6. Ensure empty arrays mean no rendered section:
+   - `toolHints: []`
+   - `roundtripToolPresets: []`
+   must render no `sample-tool-roundtrip` section.
+
+7. Delete or disable stale duplicate source files that can feed sample tile tool links outside the SSoT.
+   - If unsafe to delete, remove runtime loading and report why file remains.
+
+8. Validate these known-bad links cannot render:
+   - 0201: 3D Camera Path Editor or unrelated Open Tool links
+   - 0202: unrelated Open Tool links
+   - 0204: unrelated Open Tool links
+   - 0210: unrelated Open Tool links
+   - 0220: unrelated Open Tool links
+   - 0221: 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
+   - 0226: unrelated Open Tool links
+   - 0227: unrelated Open Tool links
+   - 0303: unrelated Open Tool links
+   - 0305: 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload
+   - 0901: Vector Map Editor
+   - 1204: SVG Asset Studio
+   - 1205: Vector Map Editor
+   - 1208: 3D Asset Viewer and SVG Asset Studio
+   - 1319: unrelated Open Tool links
+
+9. Do not add a runtime hardcoded denylist as the final fix.
+   - A temporary validation assertion is allowed only in tests/reports.
+
+10. Do not:
    - add fake data
    - add fallback/default/preset inputs
-   - reintroduce normalization or inference
+   - reintroduce normalization
+   - reintroduce inference
+   - delete samples
 
-8. Validate:
+11. Validate:
    - changed JSON parses
-   - changed JS/HTML/index files are syntactically valid where practical
-   - listed bad links no longer exist in active SSoT
+   - changed JS syntax is valid
+   - 0201 metadata empty arrays render no roundtrip section
+   - known-bad links absent from active runtime-loaded source
    - no second active source remains
-   - stale duplicate sources are deleted or disabled
 
-9. Write populated reports:
-   - docs/dev/reports/sample_tile_link_ssot_11_118.txt
-   - docs/dev/reports/sample_tile_bad_links_removed_11_118.txt
-   - docs/dev/reports/stale_launcher_sources_deleted_11_118.txt
-   - docs/dev/reports/validation_after_11_118.txt
+12. Write populated reports:
+   - docs/dev/reports/sample_metadata_ssot_11_119.txt
+   - docs/dev/reports/renderer_toolhint_cleanup_11_119.txt
+   - docs/dev/reports/stale_roundtrip_sources_11_119.txt
+   - docs/dev/reports/known_bad_links_validation_11_119.txt
 
-10. Reports must include:
-   - exact files searched
+13. Reports must include:
+   - files searched
+   - files changed
+   - exact removed logic
    - chosen SSoT
-   - exact entries removed
-   - stale files deleted/disabled
-   - validation command/result
-   - blockers
+   - validation evidence for 0201
+   - blockers if any
 
-11. Roadmap:
+14. Roadmap:
    - status-only update if execution-backed
    - do not rewrite roadmap text
    - do not delete roadmap text
 
-12. Package Codex output ZIP at:
-   tmp/PR_11_118_SAMPLE_TILE_LINK_SSOT_ENFORCEMENT.zip
+15. Package Codex output ZIP at:
+   tmp/PR_11_119_SAMPLE_METADATA_SSOT_AND_RENDERER_GUARD_REMOVAL.zip

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Enforce sample tile tool-link SSoT and delete stale bad launcher sources - PR 11.118
+Enforce sample metadata SSoT and remove renderer tool-link inference - PR 11.119

docs/dev/reports/known_bad_links_validation_11_119.txt

@@ -0,0 +1,43 @@
+PR 11.119 - Known-Bad Links Validation
+
+Validation commands and results
+- node --check samples/index.render.js
+  Result: PASS.
+- node --check samples/shared/sampleDetailPageEnhancement.js
+  Result: PASS.
+- node -e "const fs=require('fs');JSON.parse(fs.readFileSync('samples/metadata/samples.index.metadata.json','utf8'));console.log('PASS metadata json parse');"
+  Result: PASS metadata json parse.
+- Targeted renderer VM harness for samples/index.render.js
+  Result: PASS 0201 actual empty metadata and synthetic hint-only metadata render zero roundtrip links.
+- Targeted known-bad metadata and sample HTML scan
+  Result: PASS known bad links absent from metadata and sample HTML runtime sources.
+- rg -l "roundtripToolPresets|toolHints" samples
+  Result: samples/index.render.js, samples/metadata/samples.index.metadata.json, samples/shared/sampleDetailPageEnhancement.js.
+
+Known-bad validation coverage
+- 0201: no 3D Camera Path Editor or unrelated Open Tool links.
+- 0202: no unrelated Open Tool links.
+- 0204: no unrelated Open Tool links.
+- 0210: no unrelated Open Tool links.
+- 0220: no unrelated Open Tool links.
+- 0221: no 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload link.
+- 0226: no unrelated Open Tool links.
+- 0227: no unrelated Open Tool links.
+- 0303: no unrelated Open Tool links.
+- 0305: no 3D JSON Payload Normalizer / 3D JSON Payload / 3d-json-payload link.
+- 0901: no Vector Map Editor link.
+- 1204: no SVG Asset Studio link.
+- 1205: no Vector Map Editor link.
+- 1208: no 3D Asset Viewer or SVG Asset Studio link.
+- 1319: no unrelated Open Tool links.
+
+0201 proof
+- samples/metadata/samples.index.metadata.json currently has sample 0201 toolHints=[] and roundtripToolPresets=[].
+- Renderer harness built the 0201 sample row and found roundtripLinks.length = 0.
+- Renderer harness also tested a synthetic stale hint-only 0201 row and found links.length = 0.
+
+Full samples smoke test
+- Skipped. This PR changes targeted sample hub/detail rendering and one stale sample HTML link; the full samples suite is approximately 20 minutes.
+
+Blockers
+- None.

docs/dev/reports/renderer_toolhint_cleanup_11_119.txt

@@ -0,0 +1,38 @@
+PR 11.119 - Renderer Toolhint Cleanup
+
+Files searched
+- samples/index.render.js
+- samples/shared/sampleDetailPageEnhancement.js
+- tools/shared/toolLaunchSSoT.js
+- samples/metadata/samples.index.metadata.json
+
+Files changed
+- samples/index.render.js
+- samples/shared/sampleDetailPageEnhancement.js
+
+Problem path removed
+- Before: samples/index.render.js could call resolveSampleToolLaunchHref with samplePresetPath="" when a runtime sample row had toolHints but no matching roundtripToolPresets entry.
+- Effect: a stale hint-only row could render a link like /tools/3D%20Camera%20Path%20Editor/index.html?sampleId=0201&sampleTitle=Camera+Follow.
+- After: buildRoundtripLinks returns without creating a link when getExplicitRoundtripPresetPath(sample, toolId) returns empty.
+
+Related detail-page cleanup
+- samples/shared/sampleDetailPageEnhancement.js had the same hint-only behavior for sample detail pages.
+- It now skips tool links that lack an explicit presetPath.
+- This keeps sample detail pages aligned with the direct JSON contract and prevents stale hint-only links there too.
+
+Exact removed behavior
+- Removed renderer behavior that treated toolHints alone as enough to generate an Open <tool> link.
+- Removed detail-page behavior that generated a base tool URL without samplePresetPath.
+
+What remains intentionally
+- normalizeToken/normalizePresetPath helpers remain for safe string/path handling.
+- toolHints remains available for sample filter chips and tool filter indexing.
+- roundtripToolPresets remains the explicit source of launch JSON paths.
+
+Validation
+- node --check samples/index.render.js: PASS
+- node --check samples/shared/sampleDetailPageEnhancement.js: PASS
+- Targeted renderer harness: PASS 0201 actual empty metadata and synthetic hint-only metadata render zero roundtrip links.
+
+Blockers
+- None.

docs/dev/reports/sample_metadata_ssot_11_119.txt

@@ -0,0 +1,45 @@
+PR 11.119 - Sample Metadata SSoT
+
+Purpose
+Correct PR 11.118 by enforcing the active sample hub tile renderer contract directly.
+
+Chosen SSoT
+samples/metadata/samples.index.metadata.json
+
+Why this is the SSoT
+- samples/index.html loads samples/index.render.js.
+- samples/index.render.js fetches only ./metadata/samples.index.metadata.json for sample tile rows.
+- sample tile tool links are built from metadata fields toolHints and roundtripToolPresets.
+- No samples2tools file or generated link map is imported by samples/index.render.js.
+
+Files searched
+- docs/pr/BUILD_PR_LEVEL_11_119_SAMPLE_METADATA_SSOT_AND_RENDERER_GUARD_REMOVAL.md
+- samples/index.html
+- samples/index.render.js
+- samples/shared/sampleDetailPageEnhancement.js
+- samples/metadata/samples.index.metadata.json
+- samples/phase-12/1208/index.html
+- tools/shared/toolLaunchSSoT.js
+
+Files changed
+- samples/index.render.js
+- samples/shared/sampleDetailPageEnhancement.js
+- samples/phase-12/1208/index.html
+- docs/dev/reports/sample_metadata_ssot_11_119.txt
+- docs/dev/reports/renderer_toolhint_cleanup_11_119.txt
+- docs/dev/reports/stale_roundtrip_sources_11_119.txt
+- docs/dev/reports/known_bad_links_validation_11_119.txt
+
+SSoT rule enforced
+- The sample tile renderer still reads sample rows from samples/metadata/samples.index.metadata.json.
+- A visible sample tile roundtrip link now requires both:
+  - a tool id in toolHints
+  - a matching explicit presetPath in roundtripToolPresets
+- toolHints alone can no longer produce a tile Open <tool> link with only sampleId/sampleTitle.
+
+0201 evidence
+- Current metadata row for sample 0201 has toolHints=[] and roundtripToolPresets=[].
+- Targeted renderer harness result: PASS 0201 actual empty metadata and synthetic hint-only metadata render zero roundtrip links.
+
+Blockers
+- None.

docs/dev/reports/stale_roundtrip_sources_11_119.txt

@@ -0,0 +1,36 @@
+PR 11.119 - Stale Roundtrip Sources
+
+Files searched
+- samples/index.html
+- samples/index.render.js
+- samples/shared/sampleDetailPageEnhancement.js
+- samples/metadata/samples.index.metadata.json
+- samples/phase-12/1208/index.html
+- samples/**/*.html via targeted known-bad validation script
+
+Files changed
+- samples/phase-12/1208/index.html
+
+Stale source removed
+- Removed stale hardcoded Open SVG Asset Studio link from samples/phase-12/1208/index.html.
+- The valid 1208 hardcoded links for Tilemap Studio and Parallax Scene Studio remain.
+
+Duplicate source assessment
+- samples/index.render.js remains the sample tile renderer.
+- samples/metadata/samples.index.metadata.json remains the sample tile data SSoT.
+- samples/shared/sampleDetailPageEnhancement.js is not a tile source, but it is a runtime consumer of the same metadata, so it was aligned to require explicit presetPath.
+- phase-12 static sample HTML pages are sample detail pages, not tile data sources. Only the known-bad 1208 SVG Asset Studio link was removed in this PR.
+
+Deleted files
+- None.
+
+Disabled runtime loading
+- None.
+
+Why no file deletion
+- No separate generated/static sample tile link data file was found.
+- Existing sample detail HTML files are executable sample pages, not duplicate tile metadata files.
+- Deleting sample pages would violate the PR rule not to delete samples.
+
+Blockers
+- None.

docs/dev/restart_notes_11_119.md

@@ -0,0 +1,11 @@
+# Restart Notes — PR 11.119
+
+Evidence:
+- The bad link is rendered by `samples/index.render.js`.
+- `0201` metadata reportedly has empty `toolHints` and `roundtripToolPresets`.
+- Therefore the renderer/runtime is using stale data or inference.
+
+Fix:
+- `samples/metadata/samples.index.metadata.json` is the only SSoT.
+- Renderer must not infer/fallback tool links.
+- Empty arrays render no roundtrip section.