prometeu-studio/discussion/workflow/plans/PLN-0051-scene-artifact-and-assets-handoff-contract.md

id	ticket	title	status	created	completed	tags
PLN-0051	studio-scene-workspace	Build scene artifact identity, save flow, and Assets handoff contract	abandoned	2026-04-14		studio scene asset binding save

Objective

Implement the Studio-local data contract that gives scenes a stable authoring identity, supports save for the intermediate scene artifact, and allows explicit handoff between Scene Workspace and Assets.

Background

DEC-0026 requires a stable scene artifact identity, a save-oriented scene-authoring lifecycle, and an explicit binding between scene artifact and SCENE asset that does not rely primarily on path inference.

Scope

Included

• Define and implement the scene artifact model used by Scene Workspace.
• Add Studio-local binding metadata between scene artifact and SCENE asset.
• Implement scene save/load for the intermediate authoring artifact.
• Add Assets handoff behavior after SCENE asset creation.

Excluded

• Final packer publication logic.
• Advanced editing tools.
• Future aspect tabs.

Execution Steps

Step 1 - Define the scene artifact DTO and persistence boundary

What: Create a Studio-owned scene artifact model with stable identity and wave-1 tilemap data.

How: Add DTOs and persistence helpers that capture:

• scene identity;
• linked SCENE asset identity when present;
• four layers;
• per-layer dimensions;
• per-layer tileset reference;
• tile presence and editable tile data.

Keep the format explicitly intermediate and Studio-owned.

File(s):

• new files under prometeu-studio/src/main/java/p/studio/workspaces/scene/model/
• new files under prometeu-studio/src/main/java/p/studio/workspaces/scene/persistence/

Step 2 - Implement save/load for the scene artifact

What: Make Scene Workspace able to save and reopen the intermediate scene artifact.

How: Build a dedicated repository/service for reading and writing scene artifacts using the chosen Studio-local format and metadata contract. Ensure identity survives rename/relocation independently of path.

File(s):

• new persistence/service classes under prometeu-studio/src/main/java/p/studio/workspaces/scene/
• tests under prometeu-studio/src/test/java/p/studio/workspaces/scene/

Step 3 - Implement explicit scene-to-asset binding

What: Introduce the explicit binding required by the decision.

How: Store a stable scene artifact id and the linked SCENE asset reference in Studio metadata or equivalent explicit state. Avoid primary reliance on path inference. Make the binding readable from both Scene Workspace and Assets.

File(s):

• scene metadata / persistence files under prometeu-studio/src/main/java/p/studio/workspaces/scene/
• prometeu-studio/src/main/java/p/studio/projectstate/ only if the accepted metadata home belongs there

Step 4 - Add Assets-to-Scene handoff behavior

What: Allow Assets to create a SCENE asset and then hand off authoring to Scene Workspace.

How: Extend the asset-creation flow with the minimal family support needed for SCENE, then trigger explicit open/handoff into Scene Workspace without embedding editor controls into Assets.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/AddAssetWizard.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java
• new event/message classes under prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/events/ and/or workspaces/scene/messages/

Test Requirements

Unit Tests

• Scene artifact serialization/deserialization tests.
• Binding-identity stability tests across rename-like path changes.
• Asset handoff event tests.

Integration Tests

• End-to-end test: create SCENE asset, hand off to Scene Workspace, save scene artifact, reopen and preserve binding.

Manual Verification

• Create a scene from Scene Workspace and verify a linked SCENE asset exists.
• Create a SCENE asset from Assets and verify the UI hands off to Scene Workspace.
• Rename or relocate the scene artifact and verify semantic linkage still resolves.

Acceptance Criteria

• The scene authoring artifact has a stable identity independent of raw path.
• Scene Workspace can save and reopen the intermediate scene artifact.
• The binding between scene artifact and SCENE asset is explicit and stable.
• Assets can create a SCENE asset and hand off authoring without embedding scene editing.

Dependencies

• DEC-0026-studio-scene-workspace.md
• PLN-0049-scene-workspace-spec-and-boundary-propagation.md
• PLN-0050-scene-workspace-shell-and-project-state-foundations.md

Risks

• Choosing the wrong metadata home could make binding brittle or leak scene ownership into the wrong layer.
• Reusing asset-oriented DTOs for scene authoring could erase the boundary that the decision just locked.
• Save/load work can sprawl if the intermediate format is not kept intentionally narrow for wave 1.

Abandonment

Abandoned on 2026-04-15 because the parent decision DEC-0026 was explicitly abandoned by the user.