prometeu-studio/discussion/workflow/plans/PLN-0063-studio-canonical-scene-entity-analysis-and-pack-request-projection.md

id	ticket	title	status	created	completed	tags
PLN-0063	studio-scene-pack-runtime-binary-contract	Introduce the Studio canonical scene entity and project it into analysis and pack requests	done	2026-04-30	2026-04-30	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.