Guard editor shutdown and track clean savepoints
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user