# ADR 0024: Versioned Editor Session State

## Status

Accepted

## Context

User preferences already preserve dock layout and hierarchy options, while scene recovery preserves
dirty authored data. Neither establishes whether the editor exited cleanly, and several productive
session details such as the active scene, panel visibility, and viewport bookmarks were memory-only.
Restoring those details from an abnormal session must not revive a modal tool, dirty preview, or
untrusted serialized ECS state.

## Decision

- Store a separate, versioned `session.ron` under `$XDG_STATE_HOME/blacksite-editor` or
  `~/.local/state/blacksite-editor`. User preferences remain in the user config directory and scene
  recovery remains a separate generation store.
- Session schema v1 allowlists metadata only: project root, active scene path, saved dock-layout
  text, hierarchy expansion paths, non-destructive panel visibility, and finite camera bookmark
  transforms.
- Write the session transactionally. Startup immediately writes `clean_shutdown: false`; only an
  editor-shutdown-coordinator-authorized `AppExit` writes the final document with
  `clean_shutdown: true`. Direct `AppExit`, forced termination, and process failure retain the
  abnormal marker. See [ADR 0042](0042-guarded-editor-shutdown-and-document-savepoints.md).
- A clean prior session may restore its active scene and non-destructive UI state automatically.
  An abnormal prior session starts from the normal safe scene and requires explicit confirmation
  before opening the prior scene.
- Never serialize scene contents, modal operator state, unsaved preview geometry, environment
  variables, credentials, or access tokens into session state.
- Missing schema version migrates to v1. Newer unknown schemas are rejected rather than guessed.

## Consequences

- Session restore is independent of project source control and cannot modify project files merely
  by starting the editor.
- A process killed before `AppExit` leaves an actionable abnormal marker on the next launch.
- Dock/hierarchy preference persistence remains backward-compatible, while session state can evolve
  through explicit schema migrations.
- Diagnostics bundles may report allowlisted session metadata, but must maintain the same privacy
  boundary.
