102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
---
|
|
id: PLN-0062
|
|
ticket: studio-scene-pack-runtime-binary-contract
|
|
title: Propagate DEC-0030 into Studio and packer specifications
|
|
status: done
|
|
created: 2026-04-30
|
|
completed: 2026-04-30
|
|
tags: [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.
|