gardens-of-nil-3d-u6/discussion/workflow/plans/PLN-0004-journey-commit-validation.md

id	ticket	title	status	created	decisions	tags
PLN-0004	world-editor-journey-spec	Journey Commit and Validation	review	2026-06-19	DEC-0001	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.