--- id: PLN-0063 ticket: studio-scene-pack-runtime-binary-contract title: Introduce the Studio canonical scene entity and project it into analysis and pack requests status: done created: 2026-04-30 completed: 2026-04-30 tags: [studio, scene, canonical-model, analysis, pack-request] --- ## Objective Implement the Studio-owned canonical scene entity and make it the sole editorial source of truth for Scene Bank assets, including canonical validation during `Analyse` and projection into the `studio -> packer` request. ## Background DEC-0030 removes the old `TMX per layer` workflow and replaces it with a Studio-native canonical scene entity. The Studio must now own: - canonical scene persistence; - canonical scene analysis/diagnostics; - derivation of the canonical scene-pack request from canonical scene state. This is the core refactor that re-centers the domain model. External `TMX`/`TSX` interoperability is handled separately. ## Scope ### Included - Define and persist a canonical scene entity for Scene Bank assets. - Replace old scene validation state that depends on `TMX`/layer acceptance. - Move diagnostics and validation to the canonical scene entity in `Analyse` and asset-pack readiness surfaces. - Derive the canonical `studio -> packer` request from the canonical scene entity. - Remove or retire the old layer-level `validate/accept` workflow from Studio scene handling. ### Excluded - `TMX` scene import/export implementation details. - `TSX` export implementation details. - Changes to runtime `SCENE` binary decoding. ## Execution Steps ### Step 1 - Define canonical scene persistence and metadata model **What:** Introduce the persisted Studio-owned scene entity and associated metadata structures. **How:** Add or revise Scene Bank metadata classes and persistence so the canonical scene entity is stored independently of `TMX` and independently of the pack request artifact. Preserve explicit layer metadata and any required editorial fields without treating external files as the source of truth. **File(s):** `prometeu-studio` Scene Bank metadata models, persistence services, and asset details mappings. ### Step 2 - Replace old workflow state and actions **What:** Remove the old `validate layer`, `accept layer`, and `accept scene from TMX` lifecycle as the authoritative workflow. **How:** Delete or refactor workflow services, action wiring, and UI status logic so Scene Bank readiness is derived from canonical scene analysis rather than per-layer external-file fingerprints. **File(s):** `SceneBankWorkflowService`, asset details controls, scene layer controls, message/status models, and related UI wiring. ### Step 3 - Implement canonical analysis and diagnostics **What:** Make `Analyse` and pack-readiness diagnostics validate the canonical scene entity. **How:** Add validators that check canonical layer structure, glyph asset references, layer/tile invariants, and request derivation preconditions directly from canonical scene data. Ensure diagnostics remain explicit and actionable. **File(s):** Studio analysis services, scene diagnostics, asset details status surfaces, and any supporting validators. ### Step 4 - Project canonical scene state into the pack request **What:** Derive the `studio -> packer` request exclusively from the canonical scene entity. **How:** Replace the old `TMX`-driven request projection with canonical entity projection, preserving the existing request/runtime boundary. Persist the request artifact only as a publication projection, not as canonical editorial state. **File(s):** Scene request projection services, request serialization, asset workflow persistence, and related tests. ### Step 5 - Migrate or adapt project fixtures and internal examples **What:** Update test fixtures and example assets so they reflect the new canonical scene model. **How:** Replace sample assets, metadata fixtures, and scene workflow tests that currently depend on `TMX per layer` acceptance semantics. **File(s):** `test-projects/main`, Studio workflow tests, fixture generators, and scene sample assets. ## Test Requirements ### Unit Tests - Canonical scene persistence round-trip tests. - Canonical scene validation tests for blocking and non-blocking diagnostics. - Request projection tests proving the canonical scene entity, not `TMX`, drives the generated scene-pack request. ### Integration Tests - End-to-end Studio asset workflow tests covering scene analysis and pack-request artifact generation from canonical scene state. - Regression tests proving old layer acceptance files no longer define readiness. ### Manual Verification - Open a Scene Bank asset and confirm there is no primary `validate/accept TMX` workflow. - Run `Analyse` and verify diagnostics reflect canonical scene state. - Confirm pack-request generation occurs from canonical scene state and not from external editor files. ## Acceptance Criteria - [ ] Scene Bank assets persist a Studio-owned canonical scene entity distinct from both `TMX` and the pack request. - [ ] Studio readiness/diagnostics for scenes are driven by canonical scene analysis. - [ ] The old `validate/accept` layer-centric workflow no longer defines scene publication readiness. - [ ] The `studio -> packer` request is derived from canonical scene state only. - [ ] Existing request/runtime boundary semantics from DEC-0029 remain preserved. ## Dependencies - DEC-0030 accepted. - PLN-0062 should land first or in parallel so code aligns with updated specs. ## Risks - Hidden dependencies on old acceptance fingerprint files may remain in the UI or workspace services. - If canonical schema design is underspecified in code, the implementation may accidentally recreate a `TMX-shaped` persistence model under a different name. - Fixture migration may expose broad assumptions in tests and project samples.