---
id: PLN-0004
ticket: world-editor-journey-spec
title: Journey Commit and Validation
status: done
created: 2026-06-19
decisions:
  - DEC-0001
tags:
  - editor
  - validation
  - journey
---

## Briefing

Implement the explicit World Editor commit action that validates `WorldLayoutSO` and publishes only logical Journey data into `JGraphSO`.

## Source Decisions

- `DEC-0001`: World Editor / Journey V1.

## Target

Create the publication pipeline from `WorldLayoutSO` to `JGraphSO`:

- validation service,
- error/warning reporting,
- commit button behavior,
- deterministic conversion to runtime logical Journey data,
- publication metadata.

## Scope

- Editor-only validation and commit code.
- Conversion from World Editor authoring records to runtime `JGraphSO`.
- Generate/update `JStage`, `JEndpoint`, and `JConnection` records.
- Preserve stable ids across repeated commits.
- Block commit on errors.
- Allow commit with warnings.

## Out Of Scope

- Stage scene generation.
- Stage bake.
- Loading hints.
- Concrete requirements.
- Runtime traversal behavior.
- Automatic Stage Editor sync.
- Unified editor shell.

## Execution Plan

1. Add validation types.
   - Target `Assets/Scripts/Editor/GON/WorldEditor`.
   - Create severity enum: error and warning.
   - Create validation message record with severity, message, and optional authoring object id.

2. Add `WorldLayoutValidator`.
   - Validate same-layer tile overlap.
   - Validate connection endpoints exist.
   - Validate connection does not connect an endpoint to itself.
   - Validate endpoint type compatibility.
   - Validate socket cardinality: at most one connection.
   - Validate socket face is a free Stage tile face.
   - Validate sockets connect opposite faces on adjacent tiles when physically connected.
   - Validate anchor/lift cannot coexist on same WorldTile.
   - Validate lift alignment by x/y and differing layer.
   - Validate lift cardinality: exactly one connection when required, at most one connection in all cases.
   - Validate required endpoint without connection as error.
   - Validate optional endpoint without connection as warning.

3. Add `JourneyCommitter`.
   - Input: `WorldLayoutSO` and target `JGraphSO`.
   - Run validation before writing.
   - If errors exist, abort without modifying `JGraphSO`.
   - If only warnings exist, allow commit and show warnings.
   - Write `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, and optional deterministic `contentHash`.
   - Write `JStage`, endpoint, and connection records only.
   - Do not create Stage scenes, Stage geometry, Stage objects, or Stage bake artifacts.

4. Wire commit into `WorldEditorWindow`.
   - Add or enable commit button.
   - Let the user choose/create a target `JGraphSO`.
   - Display validation messages after commit attempt.
   - Mark changed assets dirty and save through Unity asset APIs.

5. Add validation display.
   - Reuse UI Toolkit patterns from the Stage Editor inspector/top bar where practical.
   - Show errors and warnings clearly.
   - Keep visual polish secondary to correctness for V1.

## Acceptance Criteria

- Commit button publishes `JGraphSO` only.
- Commit button never generates Stage scenes or Stage bake output.
- Commit aborts when validation errors exist.
- Commit can proceed with warnings.
- Required endpoint without connection is an error.
- Optional endpoint without connection is a warning.
- `JGraphSO` publication metadata is written on successful commit.
- Repeated commits preserve stable ids rather than regenerating ids from names or positions.

## Validation

- Unity compile succeeds.
- Manually verify commit of a minimal valid layout with two stages and a socket connection.
- Manually verify commit aborts when two stages overlap on the same WorldLayer tile.
- Manually verify commit aborts when a required endpoint has no connection.
- Manually verify commit allows an optional unconnected endpoint and reports a warning.
- Manually verify no Stage scene, Stage geometry, or Stage bake output is created by commit.
- No automated tests are required for this phase.

## Risks

- Id preservation can be broken if conversion derives ids from mutable fields; use stored stable ids from authoring data.
- Validation and commit can become coupled to UI; keep validation and conversion in separate services.
- Content hash can become noisy if it includes non-deterministic ordering or timestamps; omit or narrow it if deterministic hashing is not cheap.