Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
codex/non-blocking-native-dialogs
Blacksite/docs/adr/0024-versioned-editor-session-state.md
Rbanh 0553a85220
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Build production-ready editor authoring workflows
2026-07-11 12:41:04 -04:00

2.0 KiB
Raw Permalink Blame History

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; normal AppExit writes the final document with clean_shutdown: true.
  • 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.