REFERENCE / 03
A data-safety-critical tool should behave like one. Every save passes four checkpoints, and the file it replaces is kept as a full snapshot you can diff and restore.
01 / PIPELINE
proper-lockfile takes a lock beside the target path, with retries and a stale timeout. Concurrent saves to the same config are serialized.
Ajv 2020-12 compiles the canonical schema once, then validates the complete config. If validation fails, a typed error is thrown before any write call — no partial file on invalid input.
write-file-atomic writes to a temp file in the same directory, fsyncs it, then renames it over the target. The rename is atomic, so a crash leaves either the old file or the new one — never a half-written one.
The lock is released in a finally block. After a successful save, the previous on-disk content is recorded as a snapshot. A snapshot failure is reported as a warning and never invalidates the save.
A temp file on another filesystem would turn the final rename into a non-atomic copy-plus-delete (and risk EXDEV). The writer deliberately never overrides the library's same-directory default.
02 / FAILURE MODES
Each failure has a defined, non-destructive outcome. Nothing silently resets your history.
| Situation | Outcome |
|---|---|
| The document fails schema validation | The save is blocked and the field errors are returned. The file on disk is untouched. |
| The process crashes during a write | The target is never modified in place; the atomic rename means the previous complete file survives. |
| The file changed on disk while you were editing | The save carries the revision you started from. A mismatch returns HTTP 409 and asks you to review the current file rather than overwrite it. |
| Two helpers or two tabs save at once | An advisory lock plus an in-process path queue and a cross-process transaction lock serialize the whole read → write → snapshot sequence, so history entries are not dropped. |
| Snapshot recording fails | The save still succeeds; the caller receives a warning built only from the error code and message. No config content is logged. |
| The config has keys the schema does not know | Validation does not reject unknown keys — the schema never sets additionalProperties: false. Unknown and future keys are preserved on save and shown in the editor. |
| Windows briefly locks the target during rename | Transient EPERM, EBUSY and EACCES errors are retried up to five times with exponential backoff starting at 50 ms. |
03 / SNAPSHOTS
One complete JSON file per snapshot, plus a per-config index.json. Each index entry carries:
<seq>.jsonSnapshots are written under the OS app-data directory, keyed by the SHA-256 of the config's absolute path — never inside your project or its .git.
The default policy keeps the last 50 snapshots per config and skips recording when the content hash matches the most recent snapshot. The index format carried sequence, timestamp and hash from the beginning, so retention changes need no migration.
A malformed index throws rather than silently resetting: history degrades to a warning, it is not erased.
{ … }seq · time · sha256{ … }04 / RESTORE
Restore does not copy bytes behind the editor's back. The selected snapshot is loaded, validated against the active schema, and written through the same lock → validate → atomic-write pipeline as an ordinary save.
It also requires the current revision you were shown. If the file changed since, the restore is rejected with a conflict instead of overwriting a newer edit.
Before any of that, the UI computes a structural diff between the snapshot and the current document — key-by-key, not text-line-by-line — so reordering or formatting noise does not masquerade as a change.
Nothing is touched until you confirm the restore. The confirmation flow restores focus on cancel and supports Escape.
A brand-new config has no prior content, so there is nothing to snapshot. A stub file is touched only to satisfy the advisory lock; the real write still runs through validation and atomic replacement.
05 / GUARANTEES