# ADR 0042: Guarded Editor Shutdown And Document Savepoints

## Status

Accepted

## Context

Bevy's default native-window policy closes a requested window and exits after the final window is
gone. That policy bypasses Blacksite's scene-tab and project-switch confirmations, so a compositor
close request could silently discard dirty authored work. Reading `WindowCloseRequested` in another
system is insufficient because Bevy's default close system has its own message cursor and still
despawns the window.

Scene dirtiness was also independent of editor history. Every undo or redo marked the active scene
dirty, even when undo restored the exact state that had last loaded or saved. Undo depth alone is
not a valid savepoint: editor commands contain runtime entity IDs and are intentionally cleared when
tabs switch, while saves may establish a clean point in the middle of a timeline.

## Decision

- The full editor disables Bevy's automatic close-on-request behavior. The game and Project Browser
  keep their existing native-window policy.
- One editor shutdown coordinator owns native window close, **File > Quit**, project switching, and
  programmatic editor-exit requests. It coalesces duplicate requests and is the only normal path
  authorized to emit `AppExit`.
- Final authorization runs in a dedicated main schedule after Bevy's `Last` schedule. The guard
  rechecks dirty scene state after every editor authoring system, then clean-session persistence
  runs after that finalizer in the same post-`Last` schedule.
- A clean editor exits immediately. Dirty scene tabs enter one non-blocking native decision with
  explicit **Save All**, **Discard**, and **Cancel** actions. Save completion, including an untitled
  tab's Save As picker, is applied on the main thread. The coordinator exits only after every dirty
  tab saves or the user explicitly discards; cancel or failure retains the live session.
- Clean-session persistence accepts only an exit authorized by the coordinator. Crashes, forced
  termination, and unguarded `AppExit` retain the abnormal-session marker.
- Every scene tab owns a canonical authored-content checkpoint established by a successful load or
  save. The projection uses stable actor IDs, stable parent actor IDs, sorted component identities,
  and scene composition; it excludes transient Bevy entity numbers and runtime hydration.
- A committed edit marks the active tab dirty. Successful undo or redo compares the current
  canonical authored projection with that tab's checkpoint. Equality clears the dirty marker;
  divergence sets it. Failed saves and recovery restores do not advance the checkpoint.
- Editor command stacks remain active-document runtime state and are still cleared on tab switches.
  Checkpoint ownership belongs to the document tab, so dirty truth survives those clears.

## Consequences

- Native close can no longer silently discard authored scene tabs, and the editor remains responsive
  while confirmation or Save As dialogs are open.
- A normal exit requires an explicit editor-owned authorization. New code must request shutdown
  through the coordinator instead of writing `AppExit` directly.
- Undoing to the last saved authored state clears title and tab dirty indicators, including after a
  save at nonzero history depth. Redo or a divergent branch marks the document dirty again.
- Reconciliation serializes the authored projection after undo and redo. This is more work than a
  depth comparison, but it is bounded to explicit history navigation and remains correct across
  direct non-history repairs, entity respawns, and tab switches.
- Operating-system process kill and power loss cannot be confirmed; recovery and abnormal-session
  handling remain the safety boundary for those cases.
- [ADR 0047](0047-editor-authored-asset-documents.md) extends the guarded decision to dirty asset
  documents and project settings while derived processing remains resumable after source save.
