43 lines
2.2 KiB
Markdown
43 lines
2.2 KiB
Markdown
# 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.
|