The id dt allocates in dir: YYYY-MM-DD-HH-MM-SS in UTC, advanced one second at a time while a backup file already exists at that id. Serialized by the lock, so this almost never iterates.

Public ONLY so the collision branch is directly testable. The scan is load-bearing beyond id hygiene: VACUUM INTO refuses an existing target, so reusing an id would fail the capture and send create/1 down its cleanup path, which removes the file at that id — the pre-existing backup's.

Captures a backup: one id, one VACUUM INTO, then a prune to retain/0 oldest-first. Returns {:ok, entry} — the same shape list/0 rows carry — {:error, :operation_in_progress} if a capture or restore is already running, {:error, :notebook_down} if the notebook is not running once the repo's own bounded wait has passed (a capture reads the live database, so a stopped repo has nothing to read; a repo inside a supervised restart is waited for and then read), {:error, :notebook_not_serving} if it is running and the node cannot open the store (the same is true, one layer down), or {:error, :backup_failed} if the file cannot be written, in which case the partial output is removed so a corrupt backup never appears in list/0.

{:error, :notebook_down} is also the answer when YmerNode.Notebook.Backup.Lock stays unreachable past its own restart window — its with_lock/2 names the two exits behind that answer. The notebook may be serving on that route — it is the lock that is unreachable, not the repo — but no capture or restore can be serialised without the lock, and a node restart is the one action that brings it back, which is what the message asks for.

Options:

• :prune — set false to keep every existing backup.
• :exempt — ids this call's prune must never drop. The restore passes the id being restored: at the retention limit the safety capture would otherwise prune the very backup being restored, which resolve/1 has already turned into a path, failing the swap mid-restore.

Path-opacity boundary: a File/Exqlite error is logged server-side and never reaches the caller as a path.

Absolute path to the backups directory (config :ymer_node, YmerNode.Notebook.Backup, :directory).

Lists backups, newest first: %{id, created_at, size_bytes}. Returns {:error, :backups_failed} if the backups directory cannot be read — a path-opacity boundary, since the underlying File errors embed absolute paths.

Drops the oldest backups beyond retain/0. Ids in exempt are never dropped, even when they are the oldest.

Public ONLY so retention is directly testable; it is called by create/1 after a successful capture — never before, so a failed capture cannot cost an existing backup. A removal failure is tolerated: pruning must never turn a successful capture into an error.

Maps an opaque backup id to its file path. Returns {:ok, path}, {:error, :invalid_backup_id} when the id is not a bare YYYY-MM-DD-HH-MM-SS token, or {:error, :backup_not_found}. The strict pattern and the in-directory check together make path traversal unrepresentable — the argument arrives from the worker.

Restores notebook.db from backup id. DESTRUCTIVE: replaces the whole database. Captures the safety backup first — an ordinary backup of the pre-restore state, whose id is what the caller restores to undo this restore — then stops the repo and swaps the file. Returns {:ok, %{restored: id, safety_backup: id}}.

Every answer past that capture that could have changed the store names the safety backup, because once the swap has started overwriting it is not a nicety: the old database has lost its -wal, so a commit made shortly before the restore survives only there.

• {:error, {:restored_notebook_down, %{restored: id, safety_backup: id}}} — the swap landed and the repo did not come back.
• {:error, {:restored_notebook_not_serving, %{restored: id, safety_backup: id}}} — the swap landed, the repo came back, and it cannot open the store it now has.
• {:error, {:backup_unreadable, %{safety_backup: id}}} — the chosen backup does not open as a database and the notebook is serving as it was: nothing was overwritten, and another backup is the way forward.
• {:error, {:restore_incomplete, %{safety_backup: id}}} — the swap failed after it had begun overwriting, so the safety backup is the recovery.
• {:error, {:restore_not_started, %{safety_backup: id}}} — nothing was touched and the notebook is serving as it was, so retrying is safe: either the repo could not be stopped, or the copy or its check stopped before the live database was overwritten.

When nothing was overwritten and the notebook did not come back, the answer is the bare {:error, :notebook_down} or {:error, :notebook_not_serving} instead: "retry" and "choose another backup" are instructions that cannot come true for a notebook that cannot take a call, the store is as it was, and the safety backup is an ordinary backup in list/0 with nothing to undo.

Before that capture there is no id to name: {:error, :operation_in_progress}, {:error, :invalid_backup_id}, {:error, :backup_not_found}, {:error, :notebook_down} when the notebook is not running once the repo's bounded wait has passed — or when YmerNode.Notebook.Backup.Lock stays unreachable past its own restart window (its with_lock/2 names the exits behind that answer), where the notebook may be serving but nothing can be serialised and a node restart is the one action that brings the lock back — {:error, :notebook_not_serving} when it is running and the node cannot open the store — nothing is captured and nothing is overwritten, and recovering such a store is the operator's, by hand — and {:error, :restore_failed} from the rescue below. That rescue sits on this function rather than inside the swap, so a File/Exqlite error is logged server-side and never reaches the caller as a path, whichever step raised it — the swap's own raise is caught earlier, where the safety backup's id is still in scope.

Combines a with_repo_down/2 outcome for the swap with the ids the restore holds — restored, the backup asked for, and safety_backup, the one taken just before the swap — into the answer the caller gets.

A swap that did not land splits by what it left on disk, which its reason carries. Two reasons mean nothing was overwritten — :backup_unreadable, the copy was refused before the first removal, and :swap_not_started, the copy or its check stopped before it — and for those the notebook's state after the restart decides the answer: serving, and the caller is told what was wrong with this attempt — a different backup is the way forward for one, a retry is honest for the other; not serving or down, and the bare :notebook_not_serving / :notebook_down answers go back instead, because "retry" and "choose another backup" are instructions that cannot come true for a notebook that did not come back, and the store is as it was, so there is nothing for a safety backup's id to undo. Any other reason means the old database is no longer whole, and the safety backup is the recovery whatever the notebook then did.

A swap that did land splits by the notebook's serving state, and the two failure answers go to different observers: :down is a process that is gone and an app restart brings it back onto the restored data; :not_serving is a file the operator has to look at, because the restart landed and the pool still cannot open the store it now has. With the pre-swap check in front of it that second answer is the residual of residuals — a copy that opened off-pool and that the restarted pool still cannot serve — and it is answered rather than folded into the first precisely because the two ask for different things.

Public ONLY so every answer is directly testable. Two of the INPUTS cannot be forced through restore/1 from a test: Supervisor.restart_child/2 answers {:ok, pid} even for a repo pointed at a database it cannot open, because the pool's connections fail later and asynchronously, so a restart cannot be made to fail from outside the window; and Supervisor.terminate_child/2's only error needs an absent child spec, which the safety capture's own liveness check has already refused by the time the swap runs. Two of the ANSWERS are reachable regardless: {:restore_not_started, …} is also what a copy that failed before anything was overwritten gets, and {:backup_unreadable, …} is what any file that is not a database gets — an unreadable source forces both from a test.

How many backups to keep (config :ymer_node, YmerNode.Notebook.Backup, :retain, default 40). The oldest beyond the limit are pruned after each successful capture.

Replaces the live database with the bytes of backup src, in two phases. Up to the point of no return: clears anything an earlier restore left at the temp path beside the store, copies src there, and checks that the copy opens as a database by switching it to mode, one of the journal modes YmerNode.Notebook.Repo.is_journal_mode/1 admits. Past it: removes the stale -wal/-shm, then renames the temp into place atomically on the same filesystem. Order is load-bearing — see the module doc.

Returns :ok; {:error, :backup_unreadable} when the copy does not open, in which case nothing has been overwritten and the refused copy is removed again, so the store's directory is left exactly as it was found; or {:error, :swap_not_started} when anything else stopped the first phase — a leftover the node could not clear, a copy that failed — which is the same promise about the store with a different way forward. Only the second phase RAISES: removing the WAL is mandatory, and removal fails loudly on a real (non-:enoent) error so a restore fails rather than corrupts. The caller MUST have stopped the repo first. The original src is preserved — the check runs on the copy, so no member on disk is ever mutated.

Stops repo, closing the pool so nothing holds the file, runs fun with the repo DOWN, then restarts it — always, whatever fun answered or raised.

The body's outcome and the notebook's serving state are separate facts and come back as separate facts:

• {:done, value, :serving | :not_serving | :down} — fun returned value, and the notebook came back serving, came back registered but unable to open its store, or did not come back at all. A failed restart is logged server-side; it never replaces value.

• {:not_started, reason} — the repo could not be stopped, so fun never ran and nothing was touched. Supervisor.terminate_child/2's only error is :not_found, so in practice this means the child spec has gone.

The third value is three-valued because registration is not service: Supervisor.restart_child/2 answers {:ok, pid} for a repo whose connections will fail asynchronously, so the restart is followed by one statement through the pool — see restart_repo/1.

A raising fun is re-raised with its original kind and stacktrace after the restart attempt, so an unexpected failure is never quietly converted. The restore path catches the swap's raise in its own body before it reaches here, which is what keeps the safety backup's id on that answer.

Public ONLY so the outcome split can be unit-tested directly; it has no MCP exposure and is called by the restore path alone. Best-effort, not an absolute guarantee — the module doc states the residual and its recovery.