prometeu-studio/discussion/workflow/plans/PLN-0059-scene-pack-contract-spec-propagation.md

id	ticket	title	status	created	completed	tags
PLN-0059	studio-scene-pack-runtime-binary-contract	Propagate DEC-0029 into Studio and packer normative specifications	done	2026-04-29	2026-04-29	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.