---
id: PLN-0001
ticket: world-editor-journey-spec
title: World Editor / Journey V1 Spec
status: review
created: 2026-06-19
decisions:
  - DEC-0001
tags:
  - spec
  - world-editor
  - journey
---

## Briefing

Write the canonical English specification for the World Editor / Journey V1 contract accepted in DEC-0001. This plan produces documentation only. It does not implement Unity code.

## Source Decisions

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

## Target

Create or update the canonical spec location used by this repository with an English spec covering:

- `WorldLayoutSO` as editor authoring data.
- `JGraphSO` as runtime Journey data.
- `JStage`, `JEndpoint`, `JEndpointSocket`, `JEndpointAnchor`, `JEndpointLift`, and `JConnection`.
- World tile/layer defaults and configurability.
- Commit/publication boundary.
- Validation error and warning rules.
- V1 exclusions.

## Scope

- Inspect the repository for the canonical spec/docs location before editing.
- Add an English World Editor / Journey V1 spec if none exists.
- If a relevant spec already exists, update it instead of creating a parallel source of truth.
- Link the spec back to `DEC-0001`.
- Document that runtime Journey code lives outside `Assets/Scripts/Editor`.
- Document that Stage bake remains owned by the Stage Editor.

## Out Of Scope

- C# implementation.
- Unity Editor UI implementation.
- Stage Editor changes.
- Loading hints, concrete requirements, deep Stage marker sync, and editor unification.

## Execution Plan

1. Locate canonical docs/specs.
   - Use `rg --files` to find existing `spec`, `docs`, or design contract files.
   - Target the existing canonical location if present.
   - If no canonical spec location exists, create a minimal `specs/` or repository-approved equivalent only after confirming repo convention from nearby files.

2. Draft the V1 spec.
   - Add sections for authoring model, runtime model, endpoint model, connection model, commit flow, validation, and exclusions.
   - Use normative language: `MUST`, `MUST NOT`, `SHALL`, `SHOULD`, and `MAY`.
   - Keep the spec in English.

3. Define V1 data contracts in prose.
   - `WorldLayoutSO`: default `worldTileSize = 24m`, default `worldLayerHeight = 24m`, stages, occupied tiles, authoring endpoints, and editor metadata.
   - `JGraphSO`: `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, optional `contentHash`, `JStage[]`, `JEndpoint[]`, and `JConnection[]`.
   - `JStage`: logical runtime stage record, not scene generation data.

4. Define validation levels.
   - Errors block commit.
   - Warnings do not block commit.
   - Required endpoint without connection is an error.
   - Optional endpoint without connection is a warning.

5. Document non-goals.
   - No loading hints in V1.
   - No concrete requirements in V1.
   - No Stage scene generation from World Editor commit.
   - No automatic World Editor to Stage Editor integration in V1.

## Acceptance Criteria

- The spec is in English.
- The spec references `DEC-0001`.
- The spec names `WorldLayoutSO` and `JGraphSO`.
- The spec states that Journey elements use prefix `J`, and Journey ScriptableObjects use suffix `SO`.
- The spec states that World Editor commit publishes only logical Journey data.
- The spec states that runtime MUST consume `JGraphSO`, not `WorldLayoutSO` or `StageDefinition`.

## Validation

- Review the spec against every invariant in `DEC-0001`.
- Search the spec for residual Portuguese text before finalizing.
- Confirm no duplicate contradictory spec was created.
- No automated tests are required for this plan.

## Risks

- The repository may not yet have a canonical specs directory.
- If spec location is unclear, stop before creating a new documentation tree and ask for direction.
- Over-documenting future features could accidentally make them V1 commitments.