prometeu-studio/discussion/workflow/plans/PLN-0062-scene-canonical-model-revision-spec-propagation.md

id	ticket	title	status	created	completed	tags
PLN-0062	studio-scene-pack-runtime-binary-contract	Propagate DEC-0030 into Studio and packer specifications	done	2026-04-30	2026-04-30	studio packer runtime scene specs import-export

Objective

Update the normative documentation surfaces so DEC-0030 is fully represented before or alongside code changes. The resulting specs must make the Studio-owned canonical scene entity, import/export workflow, and request separation unambiguous.

Background

DEC-0030 supersedes the editorial-model portion of DEC-0029. The publication boundary locked by DEC-0029 remains valid, but the Studio editorial model changes materially:

• Studio owns a canonical scene entity;
• TMX/TSX become import/export compatibility formats;
• validation moves to the canonical scene entity in Analyse and Pack;
• the scene asset model remains distinct from the studio -> packer request.

The existing specs currently describe or imply the older TMX per layer and validate/accept workflow and therefore require explicit propagation.

Scope

Included

• Update Studio specs to define the canonical scene entity as the primary editorial model.
• Update Studio specs to define TMX and TSX as import/export formats, not canonical persistence.
• Update packer specs to reaffirm that packer consumes only the canonical request derived from the canonical scene entity.
• Cross-reference DEC-0029 and DEC-0030 with explicit note about what changed and what remains locked.
• Define the validation surface shift from editor files to canonical scene analysis/pack validation.

Excluded

• Code changes in prometeu-studio.
• Code changes in prometeu-packer.
• Final canonical scene schema details beyond what DEC-0030 already locks.

Execution Steps

Step 1 - Update Studio normative scene workflow documentation

What: Rewrite the Studio scene authoring spec so it names the Studio-owned canonical scene entity as the source of truth. How: Replace language that describes TMX generation, per-layer TMX, or validate/accept as the editorial workflow. Introduce import/export wizard language and preserve the distinction between canonical scene entity and external compatibility files. File(s): docs/studio/specs/... files that currently define Scene Bank workflow and Tiled integration.

Step 2 - Update Studio validation and interoperability specification

What: Document import compatibility checks, export overwrite semantics, and validation ownership. How: Add normative statements for:

• import compatibility failure on unsupported structural mutations;
• diagnostic/logging requirements for failed imports;
• TMX export overwrite/create behavior;
• TSX export overwrite/create behavior for glyph tilesets;
• canonical scene validation during Analyse and Pack. File(s): Studio scene and glyph tileset spec files.

Step 3 - Update packer normative boundary documentation

What: Reaffirm the packer contract after DEC-0030. How: Clarify that packer still consumes only the canonical scene-pack request and remains isolated from editor-native formats, even though Studio now owns an additional canonical scene entity layer upstream. File(s): docs/packer/specs/... scene packing contract files.

Step 4 - Record supersession and preserved rules

What: Make the DEC-0029 to DEC-0030 relationship explicit in the relevant specs. How: Note that DEC-0030 replaces only the old editorial-model assumptions, while preserving the canonical publication boundary, runtime ownership, and request compilation model. File(s): Updated Studio and packer spec references.

Test Requirements

Unit Tests

No code tests. Editorial review only.

Integration Tests

No runtime integration tests. Validate consistency across affected spec surfaces.

Manual Verification

• Read updated Studio and packer specs side by side with DEC-0030.
• Confirm there is no remaining normative language that presents TMX/TSX as canonical scene persistence.
• Confirm there is no remaining normative language that treats validate/accept of external editor files as the scene editorial lifecycle.

Acceptance Criteria

• Every normative requirement in DEC-0030 is represented in at least one spec surface.
• Studio specs clearly distinguish canonical scene entity, external import/export files, and pack request.
• Packer specs clearly preserve the editor-agnostic request compilation boundary.
• Spec language no longer implies TMX per layer or validate/accept over TMX as the primary workflow.

Dependencies

• DEC-0030 accepted.

Risks

• Leaving mixed old/new vocabulary in specs would create implementation ambiguity.
• Over-specifying the canonical scene schema here would preempt downstream implementation design that DEC-0030 intentionally leaves for planning.