Guard editor shutdown and track clean savepoints

This commit is contained in:
Rbanh committed 2026-07-13 05:12:43 -04:00
1 parent 62b538999d
commit 4b33f32357
19 files changed
+1944 -129

No files matched your search

@@ -34,12 +34,19 @@ assets, mark a scene clean, enter source control, or silently replace authored w
or Discard removes that scene's recovery generations. Save Recovery Copy As writes the snapshot
to a separate transactional scene file without changing the active scene or recovery lifecycle.
- A successful manual save retires recovery generations for that scene.
- A successful load or manual save establishes that tab's canonical authored-content checkpoint.
Undo and redo compare the current stable authored projection with this checkpoint to derive dirty
state. Failed writes, cancelled Save As, and recovery restores do not advance it.
- Native editor exit is authorized only after all dirty scene tabs save successfully or the user
explicitly discards them. See [ADR 0042](0042-guarded-editor-shutdown-and-document-savepoints.md).
## Consequences
- Interrupted manual writes retain the previous complete destination on filesystems with atomic
same-directory rename semantics.
- Recovery is machine-local and does not pollute builds or source control.
- Undoing exactly to the last loaded or saved authored state clears the dirty marker without
weakening recovery after direct edits or failed saves.
- Autosave still performs authored serialization and hydration rebuild work. Performance
instrumentation and background snapshotting remain follow-up work under the production roadmap.
- Unsaved new scenes do not yet have a stable recovery identity; they require a later session-ID
@@ -20,8 +20,10 @@ untrusted serialized ECS state.
- 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`.
- 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.
@@ -0,0 +1,57 @@
# 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.