---
id: LSN-0046
ticket: studio-scene-pack-runtime-binary-contract
title: Canonical scene owns editorial truth while pack stays request-driven
created: 2026-05-01
tags: [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.