# Never-delete guarantee

> Your reviews are never irreparably deleted, and are snapshotted automatically.

**The server (and the CLI) can't irreparably delete anything in `~/.local-review`.** Writes are atomic and never
clobber another file, none of your files is ever unlinked or truncated, and `projects/` is snapshotted hourly whenever it changes.
A test fails the build if any code gains a way around that.

## The guarantees

- **Every write is atomic.** A new temp file in the same directory (opened with `wx`, so never over an existing file),
  then renamed over the target. A failed write leaves the old file as it was, and removes only its own temp file.
  `local-review init` only creates: its rename is a no-clobber one (below), so it never replaces a `project.yaml`.
- **Writes are operations, not files.** They're applied to a fresh read of the file, never a whole file from the
  browser, so a concurrent edit by an agent is kept ([how](/agents/comment-files/#concurrent-edits)). A file that
  isn't valid YAML is never overwritten (HTTP 409; fix it by hand).
- **No file's contents are ever unlinked or truncated.** A superseded file (after a
  [rebase re-match](/concepts/following-rebases/)) is renamed to `*.superseded-by-<sha8>.yaml.bak`, and a rename never
  replaces an existing file: it's a hard link (which fails if the name is taken) followed by dropping the old name, or,
  on file systems without hard links, an existence check under the per-file lock.
- **Images are created once.** An image in a project's `assets/` folder is named by its content and written
  create-only, so it's never replaced, and nothing removes one. Adding the same image again is a no-op; a file under
  the same name with different bytes (changed by hand) is left alone and reported.
- **The example projects are created, never cleared.** Adding them only creates files and four new git repos under
  `examples/` (a folder left incomplete by an interrupted attempt is left alone, and the repos go to the next free
  name; one that another process is still building, say `local-review examples` while the UI's Add runs, is waited
  for and shared). "Remove examples" renames each example's `project.yaml` to a `.bak` (no-clobber), so it drops out of the list
  with all its files still there; adding them again renames it back.
- **Moving review data copies, then renames.** [`local-review move`](/reference/cli/#local-review-move) writes each
  file into the other project create-only (and moves nothing if any is already there), and only then renames the
  original to `<sha>.moved-to-<project>.yaml.bak`. It takes a snapshot first (unless nothing changed since the newest
  one, or snapshots are off).
- **The service doesn't touch your data.** [`local-review service install`](/getting-started/service/) writes its own
  file *outside* `~/.local-review` (a LaunchAgent in `~/Library/LaunchAgents`, or a systemd user unit in
  `~/.config/systemd/user`, or under `$XDG_CONFIG_HOME`) and only creates `logs/` in the data home. `local-review service uninstall` removes that
  one file, after checking its name and directory, and nothing in `~/.local-review`, not even the logs.
- **The service's log is rotated, and that's the only log anything removes.** `logs/service.log` is what launchd or
  systemd appends Local Review's output to, not your data. Past 8 MB, Local Review copies it to `service.log.1` and
  truncates it in place (the service manager holds it open), shifting older copies down to `service.log.3`; the oldest
  copy goes.
- **`cache/` is Local Review's own, disposable data**, not yours: what git said about commits, rewritten atomically as
  git answers come in and never snapshotted. You can delete it any time; it's rebuilt as needed.
- **`runtime.json` is Local Review's own note to itself**, not yours: while it runs, its pid, port, URL and version,
  for [`local-review busy`](/reference/cli/#local-review-busy). It's removed when Local Review exits, but only while
  it still names that process, so it can't remove another instance's.
- **`local-review update` writes only its own two files** in the data home: `update-check.json` (what npm said, written
  to a temporary file and renamed into place) and `update.lock` (its pid while it runs, removed when it ends, or by
  the next `update` once that pid has gone). The rest of what it changes is the global install of `local-review`
  itself, through npm. Its check that npm's global folder is writable makes an empty directory there and removes it
  at once.
- **The only deletion of anything else in `~/.local-review` is snapshot pruning**, guarded as below.

The one thing that removes your words is you: deleting your own comment in the UI removes it from the file, as you'd
expect. The previous version is in the snapshots. (An agent's comments can't be deleted from the UI at all.)

## Snapshots

When the server starts, and then every hour while it runs, it copies `projects/` to `backups/<timestamp>/` (with file
times preserved), but only if something changed since the newest snapshot. A snapshot is copied under a hidden
`.partial-…` name and renamed when complete, so every timestamped directory is a full copy. Images are hard-linked
rather than copied, since they never change (see [Snapshots](/reference/data-directory/#snapshots)); pruning a
snapshot drops only its link, never the image in `projects/`.

It keeps the 50 most recent snapshots plus the first snapshot of each day for 30 days. Pruning only ever removes
directories directly inside `backups/` whose names are snapshot timestamps (not symlinks, not anything else you put
there), and never the newest.

Restoring is copying files back by hand: see [Restoring](/reference/data-directory/#restoring).

## How it's enforced

All of this lives in `server/safefs.ts` and `server/backups.ts`. `test/fsguard.test.ts` statically scans
`server/**/*.ts` (and `demo/lib`, `demo/world`: the code that builds the example projects, which is allowed none of
these) and fails if any other code (or more code there) calls `unlink`, `rm`, `rmdir`, `truncate`,
`writeFile`, `rename`, `copyFile`/`cp`, or shells out to `rm`/`mv`/…. The other calls it allows are
`service uninstall`'s single `unlink` in `server/service/manager.ts`, and the test checks that it sits behind the check
that the file is the service's own (`local-review.server.plist` or `local-review-server.service`, in the service
directory); and `runtime.json`'s write, rename and removal in `server/contract/runtime-file.ts`, where the test checks
that the removal is of `runtime.json` only, after checking its pid. `update`'s files in `server/contract/` have theirs
too: `lock.ts` creates `update.lock` with `O_EXCL` and removes only it, and only once its pid is ours or gone;
`update-check.ts` writes a temporary file, renames it to `update-check.json`, and removes only that temporary file;
`package-manager.ts` removes only the empty directory it has just made for the writability check. `rotate.ts` copies,
truncates, shifts and drops only the service's log and its numbered copies, and `serve` gives it only
`logs/service.log`. The test pins each.

Contributors: if the guard fails on your change, route the write through `server/safefs.ts`; don't widen the test.
