Blacksite/docs/adr/0006-scene-schema-versioning.md

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 fails on unknown versions.

Consequences

• Breaking component changes require a migration step and version bump.
• Editor save may wrap scenes with schema header in a follow-up change.
• The current storage format remains DynamicScene RON; SceneDocument is not a BSN/JSN migration.