M1.7: crash-recovery journal and restore dialog

Dirty buffers are written atomically to <data_dir>/recovery/<project-id>/
about 1 s after the last edit (at most 2 s while typing), from pump_vfs,
never per keystroke. Entries are removed on save, close (also force),
forced project close/open and recovery.discard. project.open emits
recoveryAvailable; recovery.list/restore/discard; restored buffers are
dirty and keep line ending and BOM. Corrupt entries are moved aside and
reported as warning notifications.

UI: restore dialog in ui/src/components/recovery (Restore all, Restore
selected, Discard, time, changed-on-disk hint), catalog keys and runtime
allow-list. Tests: crash/restore with CRLF + BOM, corrupt entries, removal
paths, property test of random edits, headless control-channel test,
Vitest for the dialog. Docs: architecture, parity, gaps, ROADMAP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-16 15:54:52 +02:00
parent 6d976ed03e
commit 0b40eb90f8
27 changed files with 2222 additions and 27 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings and themes documented · **Last updated:** 2026-10-16
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes and the recovery journal documented · **Last updated:** 2026-10-16
## Overview
@ -78,7 +78,7 @@ Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS cus
### Events
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`. Events say what changed; clients fetch data with `project.children` and `buffer.get`.
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`, `recoveryAvailable {entries}` (M1.7, see Recovery journal). Events say what changed; clients fetch data with `project.children` and `buffer.get`.
Changes on disk reach the engine through `Engine::pump_vfs()`, which hosts call regularly (the desktop's pump thread every 100 ms; tests call it directly). It maps VFS events to `treeChanged` for the parent directories, reloads a clean buffer whose file changed (unless the file already matches, as after our own save) with `bufferChanged`, and reports `fileChangedOnDisk` for a dirty buffer, which keeps its text, or for a removed file. At most 10,000 VFS events are handled per pump.
@ -132,6 +132,16 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- Accessibility: `ui/tests/theme/contrast.test.ts` checks every text/background pair the components draw with against WCAG AA (4.5:1 text, 3:1 cursor and modified dot) in both themes. It reads `ui/tests/theme/themes.json`, which the Rust test `theme::tests::ui_snapshot_is_current` keeps equal to the Rust definition (`LUTRA_UPDATE_SNAPSHOTS=1` rewrites it). `ui/tests/theme/theme.test.ts` fails on a `var(--lt-x)` the themes lack and on a fallback for a token they define.
- Not themed yet: the native title bar follows the OS, not the Lutra theme; spacing and size tokens (`--lt-space-*`, `--lt-radius`, `--lt-row-height`…) are still CSS fallbacks in components; `editor.fontSize` does not drive `--lt-font-size-editor` yet.
### Recovery journal (M1.7)
- **Storage:** `<data_dir>/recovery/<project-id>/<entry-id>.json`. The project id is the FNV-1a 64-bit hash of the canonical project root, the entry id the same hash of the project-relative path, each as 16 hex digits (FNV instead of `std`'s hasher, whose output may change between Rust versions). One file per dirty buffer: `{path, text, lineEnding, bom, savedAt}`; `text` is the buffer text as held in memory (mixed line breaks included), `lineEnding` the ending it saves with, `savedAt` milliseconds since the Unix epoch. Engines without a config (`Engine::new`) keep no journal. Code: `crates/engine/src/journal.rs`, commands in `cmd/recovery.rs`.
- **Writing:** `buffer.edit` only records the edit time. `Engine::pump_vfs` (the desktop's pump thread, every 100 ms) writes a buffer once it has been idle for 1 s, or 2 s after its first unwritten edit while typing continues, so an entry is on disk at most ~1.1 s after the last edit and never per keystroke. Writes use `lutra_vfs::write_atomic`. `Engine::flush_journal()` writes everything now (tests, hosts about to stop). Cost for a 1 MiB buffer (measured on Windows 11, `journal_write_cost_for_a_one_megabyte_buffer`): median 8.5 ms in a release build, 67 ms in a debug build, under the engine lock; a keystroke arriving meanwhile waits that long. Moving the write to a background thread is a follow-up if large files make it noticeable.
- **Removal:** `file.save`/`file.saveAll`, `buffer.close` (also `force`), `project.close`/`project.open` with `force` and `recovery.discard` remove entries. Save and close remove only entries this session wrote or restored; entries left by a crashed session stay until restored or discarded. Editing such a file without restoring it overwrites its entry.
- **Commands and event:** after `project.open`, `recoveryAvailable {entries: [{path, savedAt, diskChanged}]}` when the journal is not empty. `recovery.list` → `{entries}`; `recovery.restore {paths?}` → `{restored: [{path, id}], failed: [{path, message}]}` opens each file as a dirty buffer (version 1, saved version 0) with the journal text, line ending and BOM, or puts the text into a clean open buffer; a buffer with unsaved changes is newer than the journal and is left alone (`failed`); a file gone from disk is restored too and saving recreates it. `recovery.discard {paths?}` → `{discarded}`; a discarded entry of an open dirty buffer is written again on the next tick. `diskChanged` is true when the file's modification time is after `savedAt` or the file is gone.
- **Untrusted input:** entries are read with a 512 MiB cap, at most 1,000 per project. An entry that is not valid JSON of that shape, whose path escapes the project or does not match its file name is renamed to `<entry>.bad`, skipped, and reported once as `notification {level: warning, messageKey: "notification.recovery.corrupt", params: {file, reason}}`. A failed write is reported once until a write succeeds (`notification.recovery.writeFailed {path, reason}`); an unreadable journal directory gives `notification.recovery.unavailable {reason}`. Neither stops editing or opening.
- **UI:** `ui/src/components/recovery/` (store `recovery.ts`, `RecoveryDialog.vue`, mounted in `App.vue`). The list comes from `recoveryAvailable` and, because that event is not replayed after a page reload, from `recovery.list` on `projectOpened`. Restore all, Restore selected (the rest stay listed) and Discard always pass explicit paths; Escape closes and keeps the journal for the next open.
- **Limits:** two Lutra instances on the same project share one journal directory; `diskChanged` misses a disk change that happened before the last journal write.
## Decisions (M0)
| Question | Decision | Why |
@ -149,6 +159,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-16 | minor | M1.7: recovery journal (storage, debounce, removal, commands, recoveryAvailable, restore dialog) |
| 2026-10-16 | minor | M1.10: themes (light theme, editor tokens, theme.list, theme.systemPreference, themeChanged, init script from the setting, live switch, contrast test) |
| 2026-10-16 | minor | M1.9a: engine construction (EngineConfig, with_config) and settings (file, commands, settingsChanged, notification) |
| 2026-10-15 | minor | M1.11: message catalog (`t`, lint rule, catalog test, engine messages stay English) |