hanez/xtc
2
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Phase 28: add project diagnostics, dependency inspection and durability regressions

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-27 16:58:26 +01:00
commit ca6c869b0b
16 changed files with 495 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/RECOVERY.md
View file

@ -1,6 +1,6 @@
# Persistence and failure recovery
The project format remains v4. Readers migrate v1/v2/v3, validate bounded input
The project format is v10. Readers migrate v1–v9, validate bounded input
and atomically install a candidate only after complete success. Existing tests
cover exact migration/roundtrip, truncations, malformed references, counts,
IDs, nonfinite values and failed GUI/backend installation. Native processors
@ -10,22 +10,26 @@ process addresses or an unreadable project. See PROJECT_FORMAT.md.
Project Save writes a mode-0600 same-directory `NAME.tmp.XXXXXX`, flushes and
fsyncs it, closes and renames it over the destination. Before rename, handled
failures remove the temporary and retain the destination. POSIX rename gives
complete old-or-new destination contents during process failure. The directory
is not fsynced, so this is not a power-loss durability guarantee. Symlinks are
complete old-or-new destination contents during process failure. The containing directory is fsynced after rename. If that sync fails, Save
reports I/O failure but the complete new file may already be present. Preserve
and validate it before retrying; filesystem/hardware durability still varies. Symlinks are
replaced rather than followed at rename; original file permissions are not kept.
Recording similarly writes/finalizes a same-directory temporary, then renames
it. Stop must synchronize callbacks before draining/finalizing. Ring overflow
returns an explicit error and may finalize a partial take for manual recovery;
I/O failure retains the previous destination. A killed recorder does not finish
its WAV header. Source WAV files remain external absolute paths; Save As does
not collect them. Back up the project and assets together.
its WAV header. Source WAV files remain external; references inside the project folder are
saved relative to it. Save As does not collect them. Back up the project and assets together.
## After a crash
1. Preserve the destination and any `.tmp.*` files before attempting repair.
2. Run `xtc-check --validate project.xtc` for metadata validation without a GUI,
display or audio server. This does not verify assets or realtime preparation.
display or audio server. Run `xtc-check --inspect project.xtc` to list resolved
media/module paths and plugin identities: status 2 means missing/unreadable
references, 1 means invalid metadata/I/O, 0 means files are available. Neither
command verifies file contents, plugin initialization or realtime preparation.
3. A valid destination can be opened normally. If only a temporary contains useful
data, copy it to a separate candidate and validate that copy before replacing
anything. Partial project files are rejected; there is no salvage parser.
@ -75,3 +79,13 @@ retains the original graph, controls and history position. Cancel in the generic
parameter editor discards its temporary values. Reset defaults clears automation
only when applied. No host recovery can contain a crash or hang in trusted native
plugin code; LADSPA has no runtime error-return channel.
## Save diagnostics (Phase 28)
`make test-project-diagnostics` deterministically injects flush, file-sync, close,
rename and directory-sync errors. Pre-rename failures retain the previous bytes
and clean temporary files. Post-rename sync errors leave a complete new file and
return failure; there is no rollback after replacement. Load diagnostics identify
the expected record and syntax line, or line zero for whole-model/I/O stages.
Unknown versions report the supported range (1–10); unknown records/fields are
rejected without partially changing the current project.