prometeu-studio/discussion/lessons/DSC-0030-studio-scene-pack-runtime-binary-contract/LSN-0046-canonical-scene-owns-editorial-truth-while-pack-stays-request-driven.md

id	ticket	title	created	tags
LSN-0046	studio-scene-pack-runtime-binary-contract	Canonical scene owns editorial truth while pack stays request-driven	2026-05-01	studio packer runtime scene tiled import-export

Context

Scene Bank needed a stable path from Studio authoring to runtime SCENE bytes without letting editor-specific files become the product contract. The first accepted direction closed the studio -> packer -> runtime boundary correctly, but the initial editorial implementation still treated TMX as if it were the unit of truth. That created friction because the supported external editor (Tiled) was being modeled around the wrong ownership boundary.

The final state of DSC-0030 keeps the publication contract from DEC-0029 and replaces only the mistaken editorial model through DEC-0030.

Key Decisions

Request-driven publication boundary

What: Publication of Scene Bank assets uses a canonical studio -> packer request that packer compiles directly into runtime SCENE payload bytes.

Why: This keeps prometeu-packer isolated from TMX, TSX, and any future editor-specific format. It also preserves runtime ownership of glyph_asset_id -> slot resolution instead of leaking runtime operational details back into Studio.

Trade-offs: Studio must project editorial state into a separate publication representation, so the system carries more than one representation of the same scene on purpose.

Studio-owned canonical scene entity

What: The primary editorial source of truth is a Studio-native canonical scene entity, not TMX, not TSX, and not the pack request itself.

Why: The external editor format should remain replaceable. If TMX becomes the canonical model, Studio evolution gets trapped by Tiled semantics and every future interoperability choice becomes harder.

Trade-offs: Studio now owns more editorial modeling and validation logic internally instead of delegating shape decisions to external files.

Tiled as compatibility, not authority

What: TMX (Tiled) scene import/export and TSX (Tiled) glyph export are compatibility workflows around the canonical scene entity.

Why: This preserves interoperability with the supported wave-1 tooling while making it explicit that external files are adapters, not authoritative persistence.

Trade-offs: Import must reject unsupported structural mutations instead of silently absorbing arbitrary external edits.

Patterns and Algorithms

• Keep three representations distinct: Studio canonical scene entity, canonical pack request, and runtime SCENE bytes.
• Validate canonical scene integrity in Analyse and/or Pack, not by treating editor files as the lifecycle owner.
• Use import compatibility checks before mutating canonical state, and fail without partial rewrite on unsupported structural divergence.
• Keep packer request-driven so tests can prove scene packing succeeds without parsing TMX or TSX.

Pitfalls

• Do not let a supported editor file become a hidden canonical model just because it is easy to serialize.
• Do not collapse the canonical Studio scene entity into the pack request; publication shape and editorial shape serve different purposes.
• Do not reintroduce TMX per layer or any equivalent workflow that makes scene cohesion secondary.
• Do not relax the packer boundary by teaching packer to read editor-native files directly.

Takeaways

• Scene editorial truth belongs to Studio.
• Scene publication truth belongs to the canonical request.
• Runtime operational truth belongs to the runtime SCENE contract and slot resolution logic.
• Import/export support should stay replaceable as long as it materializes the same request boundary.