---
id: PLN-0059
ticket: studio-scene-pack-runtime-binary-contract
title: Propagate DEC-0029 into Studio and packer normative specifications
status: done
created: 2026-04-29
completed: 2026-04-29
tags:
  - studio
  - packer
  - specs
  - scene
  - runtime-contract
---

## Objective

Update the normative documentation surfaces so DEC-0029 is fully reflected in Studio and packer specs before or alongside code implementation.

## Background

DEC-0029 locks the canonical publication contract for `Scene Bank` assets around a `studio -> packer` request that compiles directly into runtime `SCENE` bytes. It also locks `TMX`/`TSX` as supported but non-canonical editorial surfaces.

The current codebase already contains wave-1 Tiled support and Scene Bank validation flows, but the normative specs do not yet describe:

- the canonical scene-pack request,
- the non-canonical status of `TMX`/`TSX`,
- the `Accept` projection boundary,
- or packer ownership of binary `SCENE` compilation from a request rather than from editor files.

## Scope

### Included
- Update Studio specs to describe Scene Bank editorial ownership, validation, `Accept`, and canonical request projection.
- Update packer specs to describe request-owned publication, `SCENE/tilemap_v1`, and the prohibition on direct parsing of editor-specific formats by packer.
- Cross-link Studio and packer specs to DEC-0029 and to the existing Scene Bank asset-first wave.

### Excluded
- Java implementation changes in `prometeu-studio`.
- Java implementation changes in `prometeu-packer`.
- Lesson or housekeeping work for DSC-0030.

## Execution Steps

### Step 1 - Update Studio asset workspace specification

**What:** Add normative Scene Bank language to the Studio `Assets` workspace spec.

**How:** Extend the asset-family-specific rules in the Studio spec so Scene Bank authoring is explicitly asset-owned, `TMX`/`TSX` are editorial integrations rather than canonical publication artifacts, and `Accept` is defined as the projection point into the canonical pack request.

**File(s):**
- `docs/specs/studio/4. Assets Workspace Specification.md`

### Step 2 - Update packer declaration and build-boundary specifications

**What:** Describe the canonical request and packer-owned build behavior in packer specs.

**How:** Amend the common asset contract spec and the operational/build specs so `SCENE/tilemap_v1` is documented as a runtime-oriented format whose packer input is the canonical scene-pack request produced by Studio, not raw editor files. Make explicit that editor-specific files remain tooling/editorial surfaces and MUST NOT be parsed directly by packer.

**File(s):**
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`

### Step 3 - Record canonical field semantics

**What:** Add the canonical scene-pack request fields and rules.

**How:** Document the fixed four-layer request shape, layer-level `glyph_asset_id`, `tile_size`, `parallax_factor`, `width`, `height`, tile-level `active`, `glyph_id`, `palette_id`, `flip_x`, `flip_y`, and the rule that `tile_count` is derived from dimensions. Lock the default-plus-override semantics for `palette_id`.

**File(s):**
- `docs/specs/studio/4. Assets Workspace Specification.md`
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`

### Step 4 - Align gating and future-editor rules

**What:** Ensure the specs preserve future editor substitution without weakening the current wave.

**How:** Add explicit normative text that any future editor may replace or coexist with Tiled-backed editing only if it emits the same canonical request and passes the same validation and `Accept` rules. Preserve the wave-1 single-tileset-per-layer restriction.

**File(s):**
- `docs/specs/studio/4. Assets Workspace Specification.md`
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`

## Test Requirements

### Unit Tests

- No code unit tests are required for this editorial plan.

### Integration Tests

- No automated integration tests are required for this editorial plan.

### Manual Verification

- Review the updated specs side by side with DEC-0029 and confirm that every normative rule in the decision has a corresponding spec statement.
- Confirm there is no spec language implying that packer parses `TMX` or `TSX` directly.
- Confirm the specs do not describe Tiled as deprecated or temporary.

## Acceptance Criteria

- [ ] The Studio spec defines Scene Bank `Accept` as the projection boundary into the canonical scene-pack request.
- [ ] The packer specs define `SCENE/tilemap_v1` publication in terms of the canonical request, not editor files.
- [ ] The specs state that `TMX`/`TSX` are supported but non-canonical editorial surfaces.
- [ ] The specs allow future additional editors only through the same canonical request and validation path.
- [ ] Every normative requirement in DEC-0029 is represented in at least one spec file.

## Dependencies

- DEC-0029 accepted.

## Risks

- Editorial drift between Studio and packer specs could reintroduce ambiguity about who owns the canonical request.
- If the specs omit the field semantics for `palette_id` precedence or tile/layer `active`, code plans may diverge during implementation.