From 040a4aba11ed94bd74fc9916522e29bf2634f082 Mon Sep 17 00:00:00 2001 From: Aly Raffauf Date: Thu, 1 Oct 2026 22:34:35 -0400 Subject: [PATCH] docs(storage): explain maintenance ownership Document how cleanup and daemon startup share the home lock. --- robot-docs/migrations.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/robot-docs/migrations.md b/robot-docs/migrations.md index f0541cf..282fb08 100644 --- a/robot-docs/migrations.md +++ b/robot-docs/migrations.md @@ -7,6 +7,16 @@ extension-specific migration modules. ## startup order +`server.main` first claims `ALBEDO_HOME/daemon.lock` with `BEGIN EXCLUSIVE`. +Offline cleanup in `cli/internal/storage` takes the same lock after confirmation, +before it revalidates candidates. Its Python helper holds ownership through file +deletion and vacuum. Daemon startup refuses while maintenance owns the home, +before it touches application storage. Neither owner commits the lock transaction, +changes its journal mode, or replaces the lock file. Cleanup checks health for +diagnostics; only exclusive ownership permits offline mutation. CLI cancellation +or death stops the helper and releases ownership. Completed deletions remain +deleted if later deletion or vacuum fails. + `runtime.start` installs the extension registry before `server.prepare_storage`. for each installed extension, `extension.install` first calls its table initialiser, then applies its contributed `SchemaMigration` callbacks on the -- knotmirror 0.0.1