@timqi/pier 0.1.0 → 0.1.1

package/dist/db.js

@@ -1,44 +1,25 @@
-// The one connection, and the one place the schema is written down.
-//
-// Every store used to open `pier.db` for itself and create its own tables with
-// `CREATE TABLE IF NOT EXISTS`. That works exactly once: it can add a table but
-// never change one, so the first column an upgrade needed would have left every
-// existing instance with a schema nothing could repair. `user_version` is a
-// single number per *database*, not per table, which is why the schema cannot
-// stay spread across five modules — and five connections to one file is also
-// five writers competing for the same lock.
-//
-// So: one connection, one ordered list of migrations, applied in one
-// transaction before any store exists. A store receives the handle and owns
-// only its queries.
+// The one connection, and the one place the schema is written down: one ordered
+// list of migrations, applied in one transaction before any store exists.
+// `user_version` is per database, not per table, so the schema cannot be
+// spread across modules.
 import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { logger } from "./log.js";
 import { PIER_DB } from "./paths.js";
 const log = logger("db");
-/** Snapshots to keep *of each kind*. Three is two upgrades of regret plus one:
- *  they are full copies of the database, and the one that matters is the
- *  newest. Counted per kind because the two kinds answer different questions —
- *  a run of releases must not evict the pre-migration copies. */
+/** Per kind, because full copies are large and a run of releases must not
+ *  evict the pre-migration copies. */
 const KEEP_BACKUPS = 3;
-/** How long a second process may wait for the write lock before failing. Two
- *  Pier processes on one PIER_HOME contend exactly once — at boot, when both
- *  want to migrate — and failing instantly there turns a restart race into a
- *  crash loop. */
+/** Two Pier processes on one PIER_HOME contend at boot, when both want to
+ *  migrate; failing instantly turns a restart race into a crash loop. */
 const BUSY_TIMEOUT_MS = 5_000;
-/**
- * Append-only, never edited: index + 1 is the `user_version` a database is at
- * once that entry has run. An entry that shipped is history — fix a mistake
- * with the next one, because somebody's database already ran the old one.
- *
- * Migration 1 is the whole schema as of 0.0.1 and assumes nothing before it:
- * pre-release databases are not upgraded, they are deleted.
- */
+/** Append-only, never edited: index + 1 is the `user_version` after that entry.
+ *  Fix a mistake with the next one — somebody's database already ran the old one. */
 const MIGRATIONS = [
     // 1 — the 0.0.1 schema.
     `
-  -- The single credential in front of every HTTP surface (web/auth.ts).
+  -- The single credential in front of every HTTP surface.
   CREATE TABLE auth (
     id INTEGER PRIMARY KEY CHECK (id = 1),
     salt TEXT NOT NULL,
@@ -46,15 +27,13 @@ const MIGRATIONS = [
     created_at INTEGER NOT NULL
   );
 
-  -- Instance facts that are neither a credential nor per-session; one row per
-  -- setting, so the next setting is not the next table.
+  -- Instance facts that are neither a credential nor per-session.
   CREATE TABLE settings (
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
   );
 
-  -- Workbench bookkeeping: pinned = listed under Projects, unread = a turn
-  -- finished that no client has acknowledged.
+  -- Workbench bookkeeping; unread = a turn finished that no client acknowledged.
   CREATE TABLE session_state (
     session_id TEXT PRIMARY KEY,
     pinned INTEGER NOT NULL DEFAULT 0,
@@ -87,8 +66,8 @@ const MIGRATIONS = [
     PRIMARY KEY (platform, chat_id, message_id)
   );
 
-  -- Scheduled work. The row keeps its whole JSON document; the columns beside
-  -- it are only what a query filters or orders by.
+  -- Scheduled work: the JSON is the document, the columns beside it are only
+  -- what a query filters or orders by.
   CREATE TABLE tasks (
     id TEXT PRIMARY KEY,
     updated_at INTEGER NOT NULL,
@@ -119,10 +98,9 @@ const MIGRATIONS = [
     json TEXT NOT NULL
   );
   `,
-    // 2 — provider credentials move from <agentDir>/auth.json into the database.
+    // 2 — provider credentials.
     `
   -- One row per provider (key = provider id), value sealed by secrets.ts.
-  -- Owned by agent/credentials.ts.
   CREATE TABLE credentials (
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
@@ -130,8 +108,7 @@ const MIGRATIONS = [
   `,
     // 3 — what a restart's drain deadline cut off, told to the chat at next boot.
     `
-  -- Written only when a graceful restart aborts a still-running turn; the next
-  -- boot delivers each row and clears it once delivered. Owned by drain.ts.
+  -- Turns a graceful restart cut off; each row is delivered at next boot, then cleared.
   CREATE TABLE restart_ledger (
     id INTEGER PRIMARY KEY,
     channel_id TEXT NOT NULL,
@@ -146,10 +123,9 @@ const MIGRATIONS = [
   ALTER TABLE session_state ADD COLUMN title TEXT;
   ALTER TABLE session_state ADD COLUMN created_at INTEGER;
   `,
-    // 5 — the workbench can reach a browser that is not open (web/push.ts).
+    // 5 — Web Push.
     `
-  -- One row per browser that asked to be notified, exactly as the Push API
-  -- described it; a dead endpoint is deleted when its service says so.
+  -- One row per browser that asked to be notified, as the Push API described it.
   CREATE TABLE push_subscriptions (
     endpoint TEXT PRIMARY KEY,
     p256dh TEXT NOT NULL,
@@ -158,8 +134,8 @@ const MIGRATIONS = [
     created_at INTEGER NOT NULL
   );
 
-  -- This instance's VAPID identity: one key pair, minted on first use. Every
-  -- subscription above is bound to it, so it is never rotated on its own.
+  -- This instance's VAPID key pair; every subscription is bound to it, so it
+  -- is never rotated on its own.
   CREATE TABLE push_identity (
     id INTEGER PRIMARY KEY CHECK (id = 1),
     public_key TEXT NOT NULL,
@@ -167,21 +143,16 @@ const MIGRATIONS = [
     created_at INTEGER NOT NULL
   );
   `,
-    // 6 — Projects keeps the order the workbench was put in, by hand.
+    // 6 — manual order in the rail.
     `
-  -- Manual order, both nullable: a row nobody has dragged sorts on top of the
-  -- list it belongs to, so a fresh database needs no backfill. sort places a
-  -- session inside its project; project_sort places the project, carried on
-  -- every one of its rows because a project is a cwd, not a table.
+  -- NULL sorts on top, so a fresh database needs no backfill.
   ALTER TABLE session_state ADD COLUMN sort INTEGER;
   ALTER TABLE session_state ADD COLUMN project_sort INTEGER;
   `,
-    // 7 — the session listing, so a transcript is read once (agent/listing.ts).
+    // 7 — the session listing, so a transcript is read once.
     `
-  -- One row per session file. (size, mtime) is what makes the row usable
-  -- without opening the file; parsed_bytes is where reading resumes when it
-  -- grew, and is always a line boundary. Derived from disk and disposable: a
-  -- deleted row costs one re-read, never a fact.
+  -- One row per session file, derived from disk and disposable. A row whose
+  -- (size, mtime) match is trusted unopened; parsed_bytes is where reading resumes, always a line boundary.
   CREATE TABLE session_index (
     path TEXT PRIMARY KEY,
     id TEXT NOT NULL,
@@ -194,73 +165,39 @@ const MIGRATIONS = [
     parsed_bytes INTEGER NOT NULL
   );
   `,
-    // 8 — Projects holds a working set: what is warm, plus what is kept.
+    // 8 — working-set lease columns (dropped again in 9 and 11).
     `
-  -- Membership was permanent, so every throwaway session stayed in the rail
-  -- until someone removed it by hand. last_active is the lease: the end of a
-  -- turn renews it, and web/session-state.ts stops listing a row that ran out.
-  -- kept opts one row out of expiry entirely — what the pin control now means.
   ALTER TABLE session_state ADD COLUMN kept INTEGER NOT NULL DEFAULT 0;
   ALTER TABLE session_state ADD COLUMN last_active INTEGER;
-  -- Left NULL on purpose: the honest value is when the transcript was last
-  -- written, which only a listing knows. web/server.ts pays one for a database
-  -- carrying rows without it, the same gate the pin backfill already uses, so
-  -- the first rail after an upgrade is dated by use and not by creation.
   `,
-    // 9 — the summary a transcript already carries is read, not mirrored.
+    // 9 — drop the columns that mirrored the transcript.
     `
-  -- Dropped rather than left unread: a column nobody writes still answers when
-  -- somebody selects it, and the next reader has no way to tell a stale title
-  -- from a current one. The pre-migration backup beside the database is the
-  -- way back, not a row of fossils. cwd stays — it is the key a project's
-  -- manual place is stamped on, and it never changes for a session.
   ALTER TABLE session_state DROP COLUMN title;
   ALTER TABLE session_state DROP COLUMN created_at;
   ALTER TABLE session_state DROP COLUMN last_active;
   `,
-    // 10 — taking a session into Projects is itself an act, and it is dated.
+    // 10 — pinned_at (dropped again in 11).
     `
-  -- When a hand last put this session in Projects (pin, or a keep toggle).
-  -- Not the mirror migration 9 removed: last_active was a copy of a fact the
-  -- transcript owns, while this one exists nowhere else — pinning a cold
-  -- session back is a statement that it is warm again, and without a record of
-  -- *when* it was made the row is dropped by the same read that drew it.
-  -- NULL for every row that predates this: never pinned within a lease.
   ALTER TABLE session_state ADD COLUMN pinned_at INTEGER;
   `,
-    // 11 — Projects holds what a hand put there, for as long as the hand says.
+    // 11 — the lease is gone, so both of its columns are.
     `
-  -- The lease is gone, so both of its columns are. It expired nothing: a row
-  -- it dropped kept its transcript, its place and its ownership, and one more
-  -- turn brought it back — so what it actually did was hide rows nobody asked
-  -- it to hide, and kept existed only to opt out of that. On the instance this
-  -- was decided on, the lease had never dropped a row: 20 pinned sessions,
-  -- none past seven days, one kept. Removing a row from Projects is the ✓ on
-  -- the row, and it stays the only way out.
   ALTER TABLE session_state DROP COLUMN kept;
   ALTER TABLE session_state DROP COLUMN pinned_at;
   `,
-    // 12 — one row is how two processes take turns (src/tools.ts).
+    // 12 — the cross-process tools sync lock.
     `
-  -- The tools sync, held across processes: the token says who holds it, the
-  -- heartbeat says they are still alive. Both processes already open this
-  -- database, and BEGIN IMMEDIATE is real mutual exclusion — a lock file with
-  -- a pid in it is neither, which is what this replaces. One row, because
-  -- there is one thing to serialize; the second lock can bring its own table
-  -- and its own reason for existing.
+  -- One row: token says who holds the lock, heartbeat_at says they are still alive.
   CREATE TABLE tools_sync_lock (
     id INTEGER PRIMARY KEY CHECK (id = 1),
     token TEXT NOT NULL,
     heartbeat_at INTEGER NOT NULL
   );
   `,
-    // 13 — a signed-in browser can be signed out on its own (web/auth.ts).
+    // 13 — web sessions.
     `
-  -- One row per signed-in browser. The cookie carries "<id>.<token>" and only
-  -- the token's SHA-256 is stored, so a copy of this database cannot be turned
-  -- into a session — and deleting a row is what revocation is. seen_at is the
-  -- whole lifetime: the session ends one TTL after it, so there is no second
-  -- column that can disagree about when.
+  -- One row per signed-in browser; only the cookie token's SHA-256 is stored,
+  -- deleting a row is revocation, and the session ends one TTL after seen_at.
   CREATE TABLE web_sessions (
     id TEXT PRIMARY KEY,
     token_hash TEXT NOT NULL,
@@ -270,15 +207,9 @@ const MIGRATIONS = [
     agent TEXT NOT NULL
   );
   `,
-    // 14 — signing a browser out also stops notifying it (web/push.ts).
+    // 14 — a push subscription belongs to the web session that made it.
     `
-  -- A subscription belongs to the web session that made it, and dies with it:
-  -- the cascade is the rule, so no code has to remember to run it — revoking a
-  -- session, changing the password and recovering it all reach here for free.
-  -- Rebuilt rather than altered because a foreign key cannot be added to an
-  -- existing table; nothing is carried over, since migration 13 invalidated
-  -- every cookie and each of these rows belongs to a browser that is now
-  -- signed out. A browser re-subscribes on its next load.
+  -- Rebuilt: a foreign key cannot be added to an existing table.
   DROP TABLE push_subscriptions;
   CREATE TABLE push_subscriptions (
     endpoint TEXT PRIMARY KEY,
@@ -289,23 +220,14 @@ const MIGRATIONS = [
     session_id TEXT NOT NULL REFERENCES web_sessions(id) ON DELETE CASCADE
   );
   `,
-    // 15 — the scheduler's tick stops reading the rows it cannot deliver.
+    // 15 — indexes for the scheduler's once-a-second sweep.
     `
-  -- Once a second, tasks/ asks for the runs whose callback is still owed and
-  -- the messages whose injection has not landed. Both are a handful of rows
-  -- filtered on one low-cardinality column, and without an index both are a
-  -- full scan of a table that only grows — the sweep got slower with every
-  -- run that finished cleanly and can never match again.
   CREATE INDEX task_runs_callback_state ON task_runs(callback_state);
   CREATE INDEX task_messages_state ON task_messages(state);
   `,
-    // 16 — the same tick stops parsing every task document to find none due.
+    // 16 — an indexable next-due value, with the JSON still the only record.
     `
-  -- When a task is next due is the one field the scheduler asks about once a
-  -- second, and it lived only inside the JSON: answering meant reading and
-  -- parsing every definition, due or not. A generated column keeps the JSON
-  -- as the only record while giving the query planner a value it can index; a
-  -- disabled or archived task has no next run, so NULLs stay out of the index.
+  -- A disabled or archived task has no next run, so NULLs stay out of the index.
   ALTER TABLE tasks ADD COLUMN next_run_at INTEGER
     GENERATED ALWAYS AS (json_extract(json, '$.nextRunAt')) VIRTUAL;
   CREATE INDEX tasks_due ON tasks(next_run_at) WHERE next_run_at IS NOT NULL;
@@ -316,79 +238,43 @@ const MIGRATIONS = [
   CREATE INDEX task_runs_visible_time ON task_runs(queued_at DESC, id DESC)
     WHERE NOT (state = 'succeeded' AND json_extract(json, '$.matched') IS 0);
   `,
-    // 18 — opening a session lists every run it delegated, not the last hour's.
+    // 18 — runs by delegating session.
     `
-  -- The run cards are the messages a session sent, so the transcript wants
-  -- all of them: the query is by the delegating session, which lived only in
-  -- the JSON — without this every session open was a full scan of task_runs.
   CREATE INDEX task_runs_invoked_by ON task_runs(json_extract(json, '$.invokedBySessionId'), queued_at DESC);
   `,
-    // 19 — the rail is one flat list, and pinned means "stuck to the top".
+    // 19 — pinned now means "stuck to the top"; nobody put a historical session there.
     `
-  -- pinned used to mean "listed under Projects", and every session created in
-  -- the workbench was. Now it means on top of the list, and nobody put a
-  -- historical session there: kept as-is, every web session ever made would
-  -- land in the pinned section. project_sort stays as a column nothing reads
-  -- — a SQLite column drop rewrites the table for a NULL nobody pays for.
   UPDATE session_state SET pinned = 0;
   `,
-    // 20 — the top of the rail is maintained, not arranged: no pin, no drag.
+    // 20 — sort becomes the rank in the working set the rail keeps on top; pinned goes.
     `
-  -- sort was the place a hand dragged a pinned row to; it is now the rank in
-  -- the working set the rail keeps on top, which a session enters by being
-  -- spoken to and leaves by being pushed out of the last slot. The pinned rows
-  -- are that set's first members — they are what somebody was working on — in
-  -- the order they were arranged in; never-dragged ones sorted first, so -1 is
-  -- the rank that keeps them there.
+  -- Pinned rows seed the set at rank -1, capped at the set's size (8).
   UPDATE session_state SET sort = -1 WHERE pinned = 1 AND sort IS NULL;
   UPDATE session_state SET sort = NULL WHERE pinned = 0;
-  -- The set has a size (web/session-state.ts); more pins than that is a list
-  -- the promotion rule would never have built.
   UPDATE session_state SET sort = NULL WHERE session_id IN (
     SELECT session_id FROM session_state WHERE sort IS NOT NULL
     ORDER BY sort, session_id LIMIT -1 OFFSET 8
   );
   ALTER TABLE session_state DROP COLUMN pinned;
   `,
-    // 21 — unread is the workbench's own attention, so it is only its own rows.
+    // 21 — unread is only written for web sessions now; clear the marks nobody could ack.
     `
-  -- The flag was written for every session whose turn ended, including the
-  -- ones no browser is the reader of: an IM session answers its chat, a run's
-  -- session answers its supervisor. Both are now skipped at the write
-  -- (web/server.ts), and neither could ever be acked — that needs the session
-  -- on screen — so the rows they left would stay set forever. On the instance
-  -- this was decided on, 195 of 196 marks were those. Cleared wholesale rather
-  -- than by owner: the one real row is a turn from before an upgrade nobody
-  -- was watching for, and a false amber dot costs less than the join.
   UPDATE session_state SET unread = 0;
   `,
-    // 22 — the palette finds what was said, not only what a session is called.
+    // 22 — message search.
     `
-  -- One row per user message and per assistant reply, keyed by the transcript
-  -- it came from so a file that is rewritten or gone drops its rows in one
-  -- statement (agent/listing.ts). Trigram tokens: a substring match with no
-  -- word segmentation, which CJK text has none of and a path or an identifier
-  -- in a prompt has too much of. Steps stay out — tool calls, their output,
-  -- thinking are the bulk of a transcript and nobody searches for what ran.
+  -- One row per user message and assistant reply, keyed by transcript path.
+  -- Trigram: substring match with no word segmentation, which CJK text has none of.
   CREATE VIRTUAL TABLE session_fts USING fts5(
     text, session_id UNINDEXED, path UNINDEXED, role UNINDEXED, at UNINDEXED,
     tokenize = 'trigram'
   );
-  -- Derived and disposable (migration 7): every row goes, so the next scan
-  -- reads every transcript from its first byte and fills the table above.
-  -- Resetting parsed_bytes alone would not — a row whose (size, mtime) still
-  -- match is trusted without opening the file.
+  -- Every row goes so the next scan re-reads each transcript and fills the table above.
   DELETE FROM session_index;
   `,
 ];
-/**
- * Several writes as one, or none. `BEGIN IMMEDIATE` because every writer here
- * competes with another Pier process on the same file: taking the write lock
- * up front turns a race into a wait, where deferred would turn it into
- * SQLITE_BUSY halfway through. The rollback is the reason this is shared —
- * three modules had written the same seven lines, and a `catch` that forgets
- * to roll back leaves the connection in a transaction forever.
- */
+/** `BEGIN IMMEDIATE`: taking the write lock up front turns a race with another
+ *  Pier process into a wait, where deferred would be SQLITE_BUSY halfway through. */
 export function transact(db, work) {
     db.exec("BEGIN IMMEDIATE");
     try {
@@ -401,15 +287,8 @@ export function transact(db, work) {
         throw err;
     }
 }
-/**
- * Prepared statements, memoized by their SQL. `prepare()` compiles, and the
- * callers here hand it the same handful of strings forever — twice per
- * authenticated request, once a second per scheduler sweep. A `StatementSync`
- * is reusable with different bound parameters, so one per SQL string per
- * connection is the whole cache. Bound to the connection because a statement
- * belongs to the database that compiled it; SQL built per call does not
- * belong in here, since the cache would then grow without a bound.
- */
+/** Prepared statements memoized by SQL; callers hand it the same handful of
+ *  strings forever. SQL built per call does not belong here: the cache is unbounded. */
 export function statements(db) {
     const cache = new Map();
     return (sql) => {
@@ -420,28 +299,15 @@ export function statements(db) {
     };
 }
 let shared;
-/**
- * The process's one connection, opened and migrated on first use. Every store
- * defaults to it; a test passes `openDb(":memory:")` instead.
- */
+/** The process's one connection; a test passes `openDb(":memory:")` instead. */
 export const pierDb = () => (shared ??= openDb(PIER_DB));
-/** A release-level restore point, taken for every release even when it has no
- * schema migration. The previous complete copies stay put if writing this one
- * fails, and the service may be running while it is written: `copyDatabase`
- * reads through a read-only connection, so what it writes is one consistent
- * snapshot of a live database rather than a torn `cp`.
- *
- * `version` is the Pier that produced this database, not the one being
- * installed: the updater runs this from the tree it is about to replace, and
- * restoring a database means reinstalling the code that speaks its schema
- * (`migrate` refuses one from a newer Pier). So the name carries the other half
- * of the pair. Backing up twice at one version replaces that version's copy —
- * the pairing is identical, so a second name for it would say nothing. */
+/** A restore point per release, schema migration or not. `version` is the Pier
+ *  that produced the database: restoring one means reinstalling the code that
+ *  speaks its schema, so the name carries that half of the pair. */
 export function backupDb(version, path = PIER_DB) {
     if (!existsSync(path))
         return undefined;
-    // In a filename, so it may not carry a separator or a traversal; a version
-    // this malformed is a broken install, not something to guess at.
+    // In a filename, so no separator or traversal.
     const safe = version.replaceAll(/[^0-9A-Za-z.+-]/g, "_") || "unknown";
     const bak = join(backupsDir(path, true), `${basename(path)}.release-${safe}.bak`);
     copyDatabase(path, bak);
@@ -449,67 +315,49 @@ export function backupDb(version, path = PIER_DB) {
     prune(releases(path));
     return bak;
 }
-/** Open a database, bring it to the current schema, and lock down its files.
- *  `migrations` is injectable only so tests can exercise an upgrade — there is
- *  exactly one real list. */
+/** `migrations` is injectable only so tests can exercise an upgrade. */
 export function openDb(path, migrations = MIGRATIONS) {
     if (path !== ":memory:")
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const db = new DatabaseSync(path);
     // Timeout first: two processes booting together contend on the WAL switch
-    // itself. Outside the transaction below: journal_mode is a property of the
-    // file, and SQLite refuses to change it inside one.
+    // itself, and journal_mode cannot change inside a transaction.
     db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
     db.exec("PRAGMA journal_mode = WAL");
-    // WAL's default leaves every commit waiting on an fsync, and DatabaseSync is
-    // synchronous — that wait is the event loop's. NORMAL still survives a
-    // process crash; only a power loss can cost the last transactions, which for
-    // routing state and task bookkeeping is a fair trade for not blocking.
+    // DatabaseSync is synchronous, so WAL's per-commit fsync would be the event
+    // loop's wait. NORMAL survives a process crash; only power loss costs anything.
     db.exec("PRAGMA synchronous = NORMAL");
-    // Off by default in SQLite, and a declared relationship nothing enforces is
-    // a comment. Set before migrate(): it is a per-connection switch and a no-op
-    // inside a transaction. Nothing older declares a key, so this changes the
-    // behaviour of exactly one table — push_subscriptions, whose rows must not
-    // outlive the session that made them.
+    // Off by default in SQLite; per connection, and a no-op inside a transaction.
     db.exec("PRAGMA foreign_keys = ON");
     migrate(db, path, migrations);
     if (path !== ":memory:")
         restrict(path);
     return db;
 }
-/**
- * Upgrades only. `user_version` counts up and nothing counts it back down, so a
- * database from a newer Pier is refused rather than served: the old code would
- * happily write the new schema's tables and lose whatever it did not know
- * about. The way back is the `.bak` this function writes before upgrading.
- */
+/** Upgrades only: a database from a newer Pier is refused, since old code would
+ *  write the new schema's tables and lose what it did not know about. */
 function migrate(db, path, migrations) {
     const { user_version: at } = db.prepare("PRAGMA user_version").get();
     const target = migrations.length;
     if (at > target) {
-        // Name the snapshot that exists rather than a pattern: the operator is
-        // reading this because the service will not start.
+        // Name the snapshot that exists: the operator is reading this because the
+        // service will not start.
         const newest = path === ":memory:" ? undefined : snapshots(path)[0]?.file;
         throw new Error(`${path} is at schema ${at}, this Pier speaks ${target}: a database is ` +
             `never downgraded. Restore ${newest ?? `a copy from ${backupsDir(path)}`}, or run the newer Pier.`);
     }
-    // Version 0 with tables is a database from before versioning existed.
-    // Migration 1 assumes an empty file, so the collision it would hit says
-    // "table already exists" — this says what is actually wrong and what to do.
+    // Version 0 with tables predates versioning; migration 1 assumes an empty file.
     if (at === 0 && db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' LIMIT 1").get()) {
         throw new Error(`${path} predates schema versioning and cannot be upgraded — nothing was changed. ` +
             `Move the file aside and restart; channel credentials, tasks and the password start over.`);
     }
     if (at === target)
         return;
-    // One transaction for the statements *and* the version number: a crash
-    // between them would leave a database whose version describes a schema it
-    // does not have, which is worse than a crash.
+    // Statements and version number in one transaction: a version describing a
+    // schema the database does not have is worse than a crash.
     db.exec("BEGIN IMMEDIATE");
-    // Re-read inside the lock. Two processes starting together both saw work to
-    // do; the one that waited for the lock would otherwise replay migrations the
-    // winner already committed and die on "table already exists", with a healthy
-    // database in front of it.
+    // Re-read inside the lock: the process that waited must not replay what the
+    // winner already committed.
     const { user_version: locked } = db.prepare("PRAGMA user_version").get();
     if (locked >= target) {
         db.exec("ROLLBACK");
@@ -519,9 +367,8 @@ function migrate(db, path, migrations) {
         log.info(`schema already at ${locked}, migrated by another process`);
         return;
     }
-    // Keep the write lock while a second, read-only connection copies the last
-    // committed state. That connection may VACUUM while this one holds a RESERVED
-    // lock; other Pier starts wait here instead of racing on the shared .tmp.
+    // Under the write lock: a read-only connection may VACUUM while this one
+    // holds RESERVED, and other Pier starts wait instead of racing on the .tmp.
     if (locked > 0 && path !== ":memory:") {
         try {
             snapshot(path, locked);
@@ -540,32 +387,22 @@ function migrate(db, path, migrations) {
     }
     catch (err) {
         db.exec("ROLLBACK");
-        // Which one, and that the database is untouched: the operator's next move
-        // is to restore a backup or to report the migration, and a bare SQLite
-        // error says neither.
+        // Which one, and that the database is untouched: a bare SQLite error says neither.
         throw new Error(`migration ${step + 1} failed on ${path} — nothing was changed: ${String(err)}`, { cause: err });
     }
     log.info(locked === 0 ? `schema created at version ${target}` : `schema ${locked} → ${target}`);
     if (path !== ":memory:")
         prune(snapshots(path).map(({ file }) => file));
 }
-/**
- * The copy that exists because `user_version` only counts up: the transaction
- * above protects against a migration that *failed*, and this against one that
- * succeeded and should not have. `VACUUM INTO`, not `cp`: under WAL the
- * committed tail of the database lives in the `-wal` sidecar.
- *
- * Written under a temporary name and renamed into place. `VACUUM INTO` refuses
- * an existing target, so the alternative is deleting the previous snapshot
- * first — which means the likely failure here, a full disk, leaves neither the
- * old snapshot nor a complete new one. A rename is atomic: the `.bak` name only
- * ever refers to a finished copy.
- */
+/** The transaction protects against a migration that failed; this against one
+ *  that succeeded and should not have. */
 function snapshot(path, at) {
     const bak = join(backupsDir(path, true), `${basename(path)}.v${at}.bak`);
     copyDatabase(path, bak);
     log.info(`pre-migration backup: ${bak}`);
 }
+/** `VACUUM INTO`, not `cp`: under WAL the committed tail lives in the `-wal`
+ *  sidecar. Temp name plus rename, so a full disk leaves the old copy intact. */
 function copyDatabase(path, bak) {
     const tmp = `${bak}.tmp`;
     rmSync(tmp, { force: true }); // a previous crash may have left one
@@ -579,16 +416,9 @@ function copyDatabase(path, bak) {
     chmodSync(tmp, 0o600); // it holds everything the 0600 database holds
     renameSync(tmp, bak);
 }
-/**
- * One directory for every copy of this database, `db/backups/`. Beside the
- * database was fine while there was one snapshot per schema; a restore point
- * per release turns that into a listing where the live file and its sidecars
- * are hard to pick out, and "which of these do I not delete" is the wrong
- * question to make an operator answer under pressure.
- *
- * `create` also adopts what an older Pier wrote next to the database, so the
- * restore procedure names one location instead of two forever.
- */
+/** `db/backups/`, so the live file and its sidecars are never in the listing an
+ *  operator prunes under pressure. `create` adopts copies an older Pier left
+ *  beside the database. */
 function backupsDir(path, create = false) {
     const dir = join(dirname(path), "backups");
     if (!create)
@@ -603,8 +433,7 @@ function backupsDir(path, create = false) {
     }
     return dir;
 }
-/** The copies of one kind: `v<schema>` or `release-<version>`. Disjoint
- *  prefixes, so each kind is counted and pruned on its own. */
+/** `v<schema>` or `release-<version>`: disjoint prefixes, pruned per kind. */
 function listBackups(path, kind) {
     const dir = backupsDir(path);
     if (!existsSync(dir))
@@ -612,8 +441,7 @@ function listBackups(path, kind) {
     const prefix = `${basename(path)}.${kind}`;
     return readdirSync(dir).filter((name) => name.startsWith(prefix) && name.endsWith(".bak"));
 }
-/** Pre-migration snapshots, newest schema first — the number in the name is an
- *  ordinal, so it orders them without asking the filesystem. */
+/** Pre-migration snapshots, newest schema first. */
 function snapshots(path) {
     const prefix = `${basename(path)}.v`;
     return listBackups(path, "v")
@@ -624,39 +452,27 @@ function snapshots(path) {
         .filter(({ version }) => Number.isInteger(version))
         .sort((a, b) => b.version - a.version);
 }
-/** Release restore points, newest copy first. Ordered by mtime: the name holds
- *  a Pier version, and comparing those means reimplementing semver here — while
- *  two updates of one instance are never in flight at the same moment. Legacy
- *  `pier.db.release.bak` shares the prefix, so it ages out like the rest. */
+/** Release restore points, newest first by mtime: ordering by the version in
+ *  the name would mean reimplementing semver here. */
 function releases(path) {
     return listBackups(path, "release")
         .map((name) => join(backupsDir(path), name))
         .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
 }
-/** Keep the newest few, oldest first out. Nobody restores a database from four
- *  upgrades ago, and every one of these is the size of the whole database. */
 function prune(newestFirst) {
     for (const file of newestFirst.slice(KEEP_BACKUPS)) {
         rmSync(file, { force: true });
         log.info(`removed superseded backup: ${file}`);
     }
 }
-/**
- * The database holds the password hash, so it is not world-readable — and
- * neither are the sidecars, where a 0644 `-wal` would leak exactly what the
- * 0600 database is hiding. Done after the migration, so the sidecars that
- * writing created exist by now; SQLite gives later ones the database's mode.
- * The directory too: it exists only to hold this database and its sidecars
- * (paths.ts puts them under their own `db/`, away from the boards PIER_HOME
- * also holds), so nothing else needs to see into it.
- */
+/** The database holds the password hash; a 0644 `-wal` would leak what the
+ *  0600 database hides. After the migration, so the sidecars exist by now. */
 function restrict(path) {
     for (const file of [path, `${path}-wal`, `${path}-shm`]) {
         if (existsSync(file))
             chmodSync(file, 0o600);
     }
     chmodSync(dirname(path), 0o700);
-    // Full copies of the same secrets, one directory down.
     if (existsSync(backupsDir(path)))
         chmodSync(backupsDir(path), 0o700);
 }