---
id: PLN-0005
ticket: world-stage-editor-sync
title: Stage World Sync Data Model
status: open
created: 2026-06-21
completed:
tags:
  - stage-editor
  - sync
  - data-model
---

## Objective

Add the passive World Editor sync contract data model to `StageDefinition` so a Stage Editor asset can store the world-derived contract required by `DEC-0002`.

## Background

`DEC-0002` requires `StageDefinition` to contain a dedicated `StageWorldSyncData` structure. The data must be editor-only, passive, and separate from authored stage geometry.

## Decisions of Origin

- `DEC-0002`: World Editor / Stage Editor Sync V1.

## Scope

### Included

- Add `StageWorldSyncData` to `StageDefinition`.
- Add endpoint sync record types for expected sockets, anchors, and lifts.
- Add enough data to compute or store world bounds.
- Add `contractVersion`, `syncedAt`, and `contractHash`.
- Keep endpoint ids stable and explicit for future marker work.

### Excluded

- World Editor UI button implementation.
- StageDefinition asset creation path logic.
- Stage Editor underlay rendering.
- Runtime Journey changes.
- Endpoint implementation markers.
- Migration compatibility for temporary prototype stage assets.

## Execution Steps

### Step 1 - Add sync data serializable types

**What:** Add serializable editor-only sync structures.

**How:** Extend `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs` with:

- `StageWorldSyncData`;
- `StageWorldSyncEndpoint`;
- optional helper enum or fields needed to represent stage kind and endpoint kind using existing world/Journey enums when accessible from editor code.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`

### Step 2 - Add sync field to StageDefinition

**What:** Store the world sync contract in `StageDefinition`.

**How:** Add a public serialized field such as `public StageWorldSyncData worldSync = new();`. Update `EnsureDefaults()` to initialize `worldSync`, endpoint lists, and footprint lists.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`

### Step 3 - Add derived bounds support

**What:** Support derived world bounds for underlay and validation.

**How:** Implement a method or property on `StageWorldSyncData` that computes `RectInt` bounds from synced `worldTiles`, or store a serialized bounds field that is refreshed by sync.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`

### Step 4 - Preserve authored data isolation

**What:** Ensure sync data remains separate from authored geometry.

**How:** Do not modify `StageFloorDefinition`, `LogicalCell`, or existing `StageObjectDefinition` semantics as part of this plan.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`

## Test Requirements

### Unit Tests

- None required for this plan unless an existing editor test framework is present.

### Integration Tests

- Compile `Assembly-CSharp-Editor`.

### Manual Verification

- Create or select a `StageDefinition` asset and confirm Unity serializes the new world sync field.
- Confirm existing `StageDefinition` assets still load.

## Acceptance Criteria

- [ ] `StageDefinition` contains a dedicated `StageWorldSyncData` field.
- [ ] `StageWorldSyncData` stores world layout id, world stage id, display name, kind, layer, tile size, layer height, footprint, endpoints, sync timestamp, contract version, and contract hash.
- [ ] Expected endpoint records store endpoint id, kind, world tile, socket face, required flag, and connection/debug context.
- [ ] Authored floors, cells, and objects are not changed by adding the data model.
- [ ] `Assembly-CSharp-Editor` compiles.

## Dependencies

- `DEC-0002`.

## Risks

- Referencing World Editor-only types too directly from Stage Editor data may create coupling. Keep fields serializable and editor-only.
- Field naming churn can make assets noisy; use stable names before implementation proceeds.
