# ADR 0006: Scene Schema Versioning

## Status

Accepted

## Context

Levels under `assets/levels/` need forward-compatible migrations as authoring components evolve (M5).

## Decision

- Track `schema_version` in scene files (wrapper or sidecar during transition).
- Provide `scene_schema` module with `migrate_scene_text` and `validate_level_file`.
- Route editor save/load through `scene::document::SceneDocument`, an internal Bevy-free seam that preserves DynamicScene RON while exposing stable actor/component document identities and patch operations for tools.
- CI / `xtask validate-levels` loads all committed levels and recursively validates every committed
  prefab graph, failing on unknown versions or invalid links/override payloads.
- Keep `scene` Bevy-free. A narrow loader adapter in `game` validates and migrates `.scn.ron`
  assets through `scene`, strips the schema envelope in memory, and then invokes Bevy's
  `WorldDeserializer`. The packaged game and editor therefore hydrate the same versioned prefab
  files that authoring and CI validate.

## Consequences

- Breaking component changes require a migration step and version bump.
- Editor saves wrap levels and prefabs with the schema header; the runtime adapter removes only the
  envelope before Bevy deserialization.
- The current storage format remains DynamicScene RON; `SceneDocument` is not a BSN/JSN migration.