funoteka 0.1.0

package/dist/db/migrations/027_lookup_indexes.sql

@@ -0,0 +1,30 @@
+-- Two lookups that were scanning a table to answer a question about one row.
+--
+-- Both were found by measuring the playlist-file stage, and neither is about
+-- playlists: they are lookups the API and the importer make, and both grew with
+-- the size of the collection rather than with the size of the question.
+
+-- A file by its path.
+--
+-- The unique index on `file (root_id, rel_path)` is declared with the default
+-- BINARY collation, and the importer compares paths with `COLLATE NOCASE` on
+-- Windows — which names the same file there (`01.FLAC` and `01.flac` do not
+-- both exist in one folder). A comparison whose collation differs from the
+-- index's cannot use it, so each entry of a `.m3u` walked every file of the
+-- root: measured on this collection, 80 µs for a path near the start of the
+-- walk and 1083 µs near the end — a list of 5000 entries cost 14 seconds, and a
+-- collection three times larger would have cost three times that with no new
+-- playlist files at all.
+--
+-- On other platforms the importer compares without `COLLATE` and keeps using
+-- the unique index; this one is simply not chosen there, and costs the space it
+-- takes.
+CREATE INDEX file_rel_path_nocase ON file (root_id, rel_path COLLATE NOCASE);
+
+-- A playlist by its name.
+--
+-- Asked once per imported `.m3u`, to tell two lists with the same file name
+-- apart (`playlist/import.ts`). Nothing indexed `name`, so each question read
+-- the whole table: quadratic in the number of playlists, cheap today and not
+-- worth leaving as the third such leg.
+CREATE INDEX playlist_name ON playlist (name);

package/dist/db/migrations/028_annotations.sql

@@ -0,0 +1,47 @@
+-- What the listener marked: stars and ratings.
+--
+-- The second half of the listener's own layer — playlists are the first — and
+-- it shares their rule: a scan does not touch it, because nothing on disk says
+-- what somebody thought of a record.
+--
+-- It differs from a playlist in the one way that decides the schema. A playlist
+-- is a thing of its own; an annotation is *about a row of the model*, so what it
+-- needs is a foreign key to that row and a cascade from it. A star on a track
+-- whose file left the disk is a star on nothing, and nothing is what should be
+-- left of it.
+--
+-- **Three tables rather than one with a `kind` column**, and that is the whole
+-- reason: a polymorphic column cannot carry a foreign key, so `annotation(kind,
+-- item_id)` would leave the cascade to a hand-written sweep somewhere — and a
+-- sweep is a thing that can be forgotten, while `ON DELETE CASCADE` cannot.
+-- The three are written once here and spoken of once in `annotation/store.ts`,
+-- which is where the duplication costs something.
+--
+-- A row exists only while it says something: unstarring the last star and
+-- setting the rating back to zero delete it rather than leaving a row of NULLs,
+-- so `starred_at IS NOT NULL` and `rating` say the same thing in the table as
+-- they do in an answer.
+CREATE TABLE track_annotation (
+  track_id   INTEGER PRIMARY KEY REFERENCES track(id) ON DELETE CASCADE,
+  starred_at TEXT,
+  rating     INTEGER
+);
+
+CREATE TABLE album_annotation (
+  album_id   INTEGER PRIMARY KEY REFERENCES album(id) ON DELETE CASCADE,
+  starred_at TEXT,
+  rating     INTEGER
+);
+
+CREATE TABLE artist_annotation (
+  artist_id  INTEGER PRIMARY KEY REFERENCES artist(id) ON DELETE CASCADE,
+  starred_at TEXT,
+  rating     INTEGER
+);
+
+-- The starred listings are the one query that reads a whole table here rather
+-- than a row, and they order by when: an index keeps that from sorting every
+-- annotation of every kind.
+CREATE INDEX track_annotation_starred ON track_annotation (starred_at);
+CREATE INDEX album_annotation_starred ON album_annotation (starred_at);
+CREATE INDEX artist_annotation_starred ON artist_annotation (starred_at);

package/dist/db/migrations/029_scan_state_root_run.sql

@@ -0,0 +1,28 @@
+-- The ledger question `current()` asks, indexed.
+--
+-- `db/ledger.ts` asks whether a ledger row was written by the run that last
+-- walked its root, and it asks by comparing that row's run against the newest
+-- one for the same root:
+--
+--   ss.last_seen_run_id = (SELECT MAX(e.last_seen_run_id) FROM scan_state e
+--                           WHERE e.root_id = ss.root_id)
+--
+-- Nothing indexed `(root_id, last_seen_run_id)` on `scan_state`, so that `MAX`
+-- read every row of the root — and the fragment is a predicate inside a lookup,
+-- not a query of its own, so it was asked once per lookup rather than once per
+-- stage. That is the whole difference: measured on the live collection, the cue
+-- stage's stored-probe lookup made **3347** calls and cost **1050 ms** of a
+-- 1756 ms stage. With this index the same stage takes **709 ms**, and the lookup
+-- no longer appears among the stage's costs at all (task:2880).
+--
+-- `folder`, `album` and `release` were given this index in 005, for the same
+-- reason — "did this run see it" is a question about the newest run for a root.
+-- `scan_state` was left out, and that cost nothing while the ledger was read
+-- once per root. It stopped being free when a stage began asking it per file:
+-- `tags` asks it to decide which files to read, and the cue stage asks it
+-- whether a stored measurement is still good.
+--
+-- The pair is the shape the question has, in that order: `root_id` is the
+-- equality, `last_seen_run_id` the aggregate — so the `MAX` is answered by the
+-- last entry of the range rather than by reading it.
+CREATE INDEX scan_state_root_run ON scan_state (root_id, last_seen_run_id);

package/dist/db/migrations/030_history.sql

@@ -0,0 +1,108 @@
+-- What was played, what is playing, and the queue a listener left behind.
+--
+-- The listener's own layer again, and the third part of it: playlists are what
+-- they arranged, stars are what they thought, and these are what they *did*.
+-- Nothing on disk states any of it, so no scan writes here — and, like the other
+-- two, a scan that takes a row away takes what hangs off it through the cascade.
+--
+-- Five tables rather than two, and the split is the protocol's own. A `play` is
+-- history: it happened, and the row is the only record that it did. `now_playing`
+-- is state: one row per player, replaced as the player moves. The queue is state
+-- too, but the listener's rather than a player's — it exists so a queue can be
+-- resumed on another device, which is why `getPlayQueue` takes no player and why
+-- its entries are a table of their own (`play_queue_entry`) beside it. `player`
+-- is the fifth, and it is not one of the three states but the row that turns a
+-- client's own name into the integer the protocol asks for — see below.
+--
+-- The count is stated because it was wrong here: this said four while creating
+-- five, and a reader counting the tables found a comment that disagreed with the
+-- file beside it.
+
+-- Who is playing. The protocol requires a `playerId` (an integer) and an
+-- optional `playerName` on every now-playing entry, and **no endpoint accepts
+-- either**: the server is meant to derive them. A client names itself with the
+-- protocol's own `c` parameter, so that is the name, and this table is what
+-- turns it into the stable small integer the protocol asks for. Deriving the
+-- number from the name by hashing would be the other way; a row is simpler and
+-- it can be read back.
+CREATE TABLE player (
+  id   INTEGER PRIMARY KEY,
+  name TEXT    NOT NULL UNIQUE
+);
+
+-- A play that happened.
+--
+-- **`ON DELETE CASCADE` on the track**, which is a decision rather than an
+-- obvious truth: a scrobble is a statement about a *file*, and Last.fm would
+-- keep it after the file left. This meta layer's rule is the other one — every
+-- row below `root` is a reading of what is on disk, and a reading of a file that
+-- is not there is a reading of nothing. A history that outlived its collection
+-- would also have nowhere to point: `track_id` is NOT NULL, so the alternatives
+-- were a nullable column and a client that has to be told what a row without a
+-- track means.
+CREATE TABLE play (
+  id        INTEGER PRIMARY KEY,
+  track_id  INTEGER NOT NULL REFERENCES track(id) ON DELETE CASCADE,
+  player_id INTEGER NOT NULL REFERENCES player(id),
+  -- When the play happened, as far as this server knows. The protocol lets a
+  -- client state it — `time`, optional, and the only thing that dates a play a
+  -- client made offline — and when it does not, this is when the server was told.
+  played_at TEXT    NOT NULL
+);
+
+CREATE INDEX play_track ON play (track_id);
+CREATE INDEX play_played_at ON play (played_at);
+
+-- What each player is playing now, and how far in.
+--
+-- One row per player and not per user, because the protocol's question is "what
+-- is being played by all users" and the only thing that tells two of them apart
+-- here is the client. `state`, `position_ms` and `playback_rate` come from
+-- `reportPlayback` (the `playbackReport` extension) and are what `getNowPlaying`
+-- reports back when a server supports it.
+--
+-- **Nothing expires a row.** An entry stays until its player says otherwise, so
+-- a client that vanishes mid-track leaves one behind and `minutesAgo` is what
+-- tells a reader how old it is. That is the honest reading of the protocol —
+-- which describes `minutesAgo` as "last update" and leaves the reader to judge —
+-- and the alternative, a timeout, would be this server inventing a rule about
+-- how long a track is that no client agrees with.
+CREATE TABLE now_playing (
+  player_id     INTEGER PRIMARY KEY REFERENCES player(id),
+  track_id      INTEGER NOT NULL REFERENCES track(id) ON DELETE CASCADE,
+  updated_at    TEXT    NOT NULL,
+  state         TEXT,
+  position_ms   INTEGER,
+  playback_rate REAL
+);
+
+-- The queue, and there is one of it.
+--
+-- `savePlayQueue`/`getPlayQueue` are per *user*, and this server has one — so
+-- the row is single, like `playlist_sequence`'s counter, and for the same
+-- reason: a table that could hold two rows would be a table where a caller has
+-- to know which one it meant.
+--
+-- `current_index` is the protocol's `currentIndex` — a 0-based position in the
+-- entries — and `getPlayQueue`, which addresses the current track by *id*
+-- instead, is answered by looking that id up at this position. The two endpoints
+-- read one queue because the extension exists to fix the older one's ambiguity
+-- (a queue may hold the same song twice), not to keep a second queue.
+CREATE TABLE play_queue (
+  only_row      INTEGER PRIMARY KEY CHECK (only_row = 1),
+  current_index INTEGER,
+  position_ms   INTEGER NOT NULL DEFAULT 0,
+  changed_at    TEXT    NOT NULL,
+  changed_by    TEXT    NOT NULL
+);
+
+-- A song's place in the queue. `position` is the order, laid out from zero by
+-- every save — and a track deleted by a sweep leaves its number unused, exactly
+-- as it does in `playlist_track`. That is what makes the number stable, and the
+-- stability is load-bearing: the queue's current track is stored *as* one of
+-- these numbers (031), so it has to mean the same seat after a deletion as it
+-- did before one.
+CREATE TABLE play_queue_entry (
+  position INTEGER PRIMARY KEY,
+  track_id INTEGER NOT NULL REFERENCES track(id) ON DELETE CASCADE
+);

package/dist/db/migrations/031_queue_position_and_plays.sql

@@ -0,0 +1,46 @@
+-- The queue's current track is a seat, not an index, and what plays add up to.
+--
+-- Three corrections to `030_history.sql`, all found by the two review axes of
+-- the same change (task:2863) — one of them independently reproduced.
+
+-- **`current_index` was a position read as an index.**
+--
+-- The column was meant as a position in the saved order, but `queue()` hands
+-- back the entries that survived a sweep, compacted, and the API read one as the
+-- other. A track deleted *ahead* of the current one shifts every ordinal after
+-- it, so `getPlayQueue` announced a different song as playing; delete the
+-- current track itself and the stored number ran past the end, so the field was
+-- dropped while the queue was not empty — breaking the specification's own
+-- "must ensure that `current` exists" for exactly the case it describes.
+--
+-- Reproduced against the module: queue `[tr:1…tr:5]` with `current=tr:3`,
+-- `tr:1` deleted → `current: "tr:4"`.
+--
+-- `play_queue_entry.position` does not shift: a deleted entry leaves its number
+-- unused, which is the whole reason the entries are numbered rather than
+-- indexed. So this is the number to store, and `currentIndex` — the ordinal the
+-- extension reports — is derived by counting the survivors before it.
+ALTER TABLE play_queue RENAME COLUMN current_index TO current_position;
+
+-- **What each track's plays add up to**, for the two fields the protocol puts on
+-- every `Child`: `playCount` and `played`.
+--
+-- `play` is the history and stays the record of what happened. This is a rollup
+-- of it, and it exists because the alternative is an aggregate per row in every
+-- listing: `SONG_SELECT` feeds `getAlbum`, `getArtist`, `search3`, the folder
+-- tree and both starred listings, and a correlated count there is one query
+-- multiplied by whatever the listing returns — the cost this project has paid
+-- for twice already (task:2806, task:2807).
+CREATE TABLE track_play (
+  track_id   INTEGER PRIMARY KEY REFERENCES track(id) ON DELETE CASCADE,
+  play_count INTEGER NOT NULL DEFAULT 0,
+  played_at  TEXT
+);
+
+-- **An index with no reader.**
+--
+-- Nothing orders or filters by `played_at`: a track's history is read by track
+-- (`track_play` for the fields, `play_track` for the cascade), and no query asks
+-- "what was played between these times" yet. An index nobody reads is space and
+-- a write cost on every scrobble, so it goes until a query claims it.
+DROP INDEX play_played_at;

package/dist/db/migrations/032_bookmarks.sql

@@ -0,0 +1,27 @@
+-- Where the listener stopped.
+--
+-- The fourth part of the listener's own layer — playlists are what they
+-- arranged, stars what they thought, plays what they did, and this is how far
+-- they got. Nothing on disk states it, so no scan writes here, and what a scan
+-- takes away goes through the cascade.
+--
+-- **Keyed by the song, with no id of its own.** One listener, one place per
+-- track, which is the protocol's own rule in its own words: "if a bookmark
+-- already exists for this file it will be overwritten". A second column of
+-- identity would be a second bookmark per song, and a client with two resume
+-- points and no way to choose between them.
+--
+-- `position_ms` is where in the *song* — which for a track cut out of a cue
+-- image is the track's own timeline and not the image's, exactly as `duration`
+-- is: a position is what a client seeks to, and it seeks within what it was
+-- given.
+CREATE TABLE bookmark (
+  track_id    INTEGER PRIMARY KEY REFERENCES track(id) ON DELETE CASCADE,
+  position_ms INTEGER NOT NULL,
+  comment     TEXT,
+  -- Both, and they part company on the second write: a client that moves the
+  -- mark has not made a new one, and the difference is the only thing that says
+  -- whether a bookmark is the one somebody left or one they keep moving.
+  created_at  TEXT    NOT NULL,
+  changed_at  TEXT    NOT NULL
+);

package/dist/db/migrations/033_bookmark_order.sql

@@ -0,0 +1,14 @@
+-- The order bookmarks are read in, indexed.
+--
+-- `bookmark/store.ts` reads the whole table `ORDER BY changed_at DESC, track_id`
+-- — a list of where somebody stopped is a list of what they are in the middle
+-- of, and the one they last listened to is the first — and `032_bookmarks.sql`
+-- declared no index at all. So the listing sorted the table every time, which is
+-- the shape `028_annotations.sql` names for its own three tables and `029` for
+-- the ledger: a reader that orders by a column is a reader that wants it
+-- indexed.
+--
+-- `track_id` is in the index and not only in the query because SQLite has to
+-- break a tie by something, and a tie broken by a column the index does not
+-- carry is a rowid walk per equal pair.
+CREATE INDEX bookmark_changed ON bookmark (changed_at DESC, track_id);

package/dist/db/migrations/034_junk.sql

@@ -0,0 +1,33 @@
+-- What the collection holds that is not a record, and who said so.
+--
+-- The contract asks for a junk filter that hides what is not music from the
+-- default view and **never deletes anything** (requirements:47 §11). Two halves,
+-- stored apart because they have different owners:
+--
+--   1. `album.junk_reason` is *derived*, like every other column classify
+--      writes: it is re-computed from the folder on every pass, so it follows
+--      the disk and a rescan can change its mind. NULL means "a record".
+--   2. `junk_mark` is *said*, and only a person says it. It is what the
+--      contract calls the allow/block edit, and it outlives everything: it is
+--      keyed on the path and not on the album row, so a folder that vanishes
+--      and comes back is still marked, and a mark for a folder that is gone is
+--      kept rather than swept — a statement about a path does not stop being
+--      true because the disk is unavailable.
+--
+-- The two are not equal partners: classify reads the marks and lets them win
+-- over its own reading, which is why `source` is on the row. The rule the
+-- project keeps for every derived field (Q15, brainstorm:190) is that the
+-- *owner* of a field decides and never "whoever wrote last" — here the owner is
+-- the person, and the scan is the default they override.
+
+-- Why an album is not a record, or NULL when it is one. Written by classify.
+ALTER TABLE album ADD COLUMN junk_reason TEXT;
+
+CREATE TABLE junk_mark (
+  root_id   INTEGER NOT NULL,
+  rel_path  TEXT    NOT NULL,
+  verdict   TEXT    NOT NULL CHECK (verdict IN ('junk', 'trust')),
+  note      TEXT,
+  marked_at TEXT    NOT NULL,
+  PRIMARY KEY (root_id, rel_path)
+);

package/dist/db/migrations/035_api_key.sql

@@ -0,0 +1,38 @@
+-- The keys a client may present instead of a password, and the one that is not here.
+--
+-- The OpenSubsonic extension `apiKeyAuthentication` is not a parameter, it is a
+-- pair of promises: a key that arrives is a whole credential, and a server that
+-- accepts one **must** offer a way to see the keys it is accepting and to take
+-- one back. This project honoured the first half from the beginning — the
+-- parameter worked, once `auth.ts` stopped demanding `u` beside it — and had no
+-- way at all to do the second: the key lived in a variable in `start.cmd`,
+-- readable only by reading that file on the server, and revocable only by
+-- editing it and restarting the daemon (task:2915).
+--
+-- So this is the registry that makes the second half true. A key added here can
+-- be listed and revoked while the server is running, which is what taking a key
+-- back from a device somebody lost has to mean.
+--
+-- **The environment's key is deliberately not in this table.** `FUNOTEKA_APIKEY`
+-- stays exactly what it was — checked first, always valid — and it is the
+-- credential that must survive a database. A key whose only copy lives in the
+-- database cannot recover that database, and a bootstrap credential that
+-- `revoke` could silently undo on the next restart would be worse than none. The
+-- CLI reports it as what it is and says where it is revoked.
+--
+-- A revoked row is kept rather than deleted. Its `secret` stays under the unique
+-- index, so a key that was taken back cannot be added again by accident and
+-- quietly become valid — and "when was this taken back" is a question the
+-- registry should be able to answer, which a deleted row cannot.
+CREATE TABLE api_key (
+  id         INTEGER PRIMARY KEY,
+  -- What the person called it: "the tablet", "Symfonium on the phone". A key
+  -- nobody can tell from another is a key nobody dares revoke.
+  label      TEXT    NOT NULL,
+  secret     TEXT    NOT NULL,
+  created_at TEXT    NOT NULL,
+  revoked_at TEXT
+);
+
+-- Unique across revoked rows too — see the note above.
+CREATE UNIQUE INDEX api_key_secret ON api_key (secret);

package/dist/db/migrations/036_file_tag_first.sql

@@ -0,0 +1,88 @@
+-- The eight tags a song listing asks for, as one row a file.
+--
+-- A listing builds a `Child` per song, and eight of that payload's fields come
+-- from `file_tag`: the genre, the track artist, the two advisories, and the four
+-- ReplayGain numbers. **A page of five hundred songs costs 10.04 ms reading them
+-- the obvious way — one correlated subquery per name, which is what the API did
+-- — and 6.37 ms reading them off this row**, measured 2026-09-16 on a copy of the
+-- live collection, the two statements interleaved in one run (task:2925).
+--
+-- **That shape is not the defect, and the measurement says so.** A correlated
+-- scalar subquery here is one index seek through
+-- `sqlite_autoindex_file_tag_1 (file_id, name, position)`, with `ORDER BY
+-- position LIMIT 1` free, and an absent name costs a seek that finds nothing.
+-- Every alternative was measured and every one is worse: the same eight as one
+-- `json_group_object` is no faster and answers differently; a `LEFT JOIN` to a
+-- derived pivot — the shape `ALBUM_GENRES` uses — cannot be restricted to the
+-- page, so it materialises over the whole tag table and multiplies the page's
+-- cost by an order of magnitude (51 ms against 11.29 in the run that measured
+-- the alternatives); a covering index `(file_id, name, position, value)` is 13
+-- times worse forced (the planner will not choose it: it gives up the free
+-- ordering); and `WITHOUT ROWID` is 5 times worse. What is left is that eight
+-- seeks per song are eight seeks per song.
+--
+-- So the values move out of the tag table, and a file's row is joined the way
+-- `audio_probe` already is — one primary-key lookup on a table of one row per
+-- file. The join is not quite free: a page with no tag columns at all is 6.56 ms
+-- in the run that put the eight subqueries at 11.29.
+--
+-- **The rule is the API's own, copied exactly**, because these columns are what
+-- a `Child` is shown: the *first value by position* of each name, trimmed of the
+-- whitespace a tag can hide in, with an empty result treated as no value at all
+-- so that a second line falls through to a first. `TRIM` is spelled with its
+-- character set and not with SQLite's one-argument form, which removes spaces
+-- and leaves a tab — the same trap `meta.ts` spells out beside `trimmed`.
+--
+-- Written by the tags stage from this migration onward (`tags/first.ts` holds
+-- the live statement; this is the frozen backfill), so a file whose tags are
+-- read again gets its row rewritten in the same transaction that rewrote the
+-- tags. A file that has never been read has no row, and the join answers null —
+-- which is what the subquery answered too.
+CREATE TABLE file_tag_first (
+  file_id          INTEGER PRIMARY KEY REFERENCES file(id) ON DELETE CASCADE,
+  genre            TEXT,
+  track_artist     TEXT,
+  advisory_itunes  TEXT,
+  advisory_mp4     TEXT,
+  rg_track_gain    TEXT,
+  rg_album_gain    TEXT,
+  rg_track_peak    TEXT,
+  rg_album_peak    TEXT
+);
+
+-- The collection as it stands, once. From here the stage keeps it.
+INSERT INTO file_tag_first (
+  file_id, genre, track_artist, advisory_itunes, advisory_mp4,
+  rg_track_gain, rg_album_gain, rg_track_peak, rg_album_peak
+)
+SELECT file_id,
+       MAX(CASE WHEN name = 'genre'                 THEN value END),
+       MAX(CASE WHEN name = 'artist'                THEN value END),
+       MAX(CASE WHEN name = 'itunesadvisory'        THEN value END),
+       MAX(CASE WHEN name = 'rtng'                  THEN value END),
+       MAX(CASE WHEN name = 'replaygain_track_gain' THEN value END),
+       MAX(CASE WHEN name = 'replaygain_album_gain' THEN value END),
+       MAX(CASE WHEN name = 'replaygain_track_peak' THEN value END),
+       MAX(CASE WHEN name = 'replaygain_album_peak' THEN value END)
+  FROM (
+    SELECT ft.file_id,
+           ft.name,
+           TRIM(ft.value, ' ' || CHAR(9) || CHAR(10) || CHAR(13) || CHAR(160) || CHAR(12288)) AS value,
+           ROW_NUMBER() OVER (PARTITION BY ft.file_id, ft.name ORDER BY ft.position) AS rn
+      FROM file_tag ft
+     WHERE ft.name IN ('genre', 'artist', 'itunesadvisory', 'rtng',
+                       'replaygain_track_gain', 'replaygain_album_gain',
+                       'replaygain_track_peak', 'replaygain_album_peak')
+       AND TRIM(ft.value, ' ' || CHAR(9) || CHAR(10) || CHAR(13) || CHAR(160) || CHAR(12288)) <> ''
+  )
+ WHERE rn = 1
+ GROUP BY file_id;
+
+-- The `MAX` above is exact rather than a choice: `rn = 1` leaves one row per
+-- (file, name), so the aggregate has nothing to choose between. That is the
+-- whole reason for the window function — the cheaper-looking `MIN(position)`
+-- beside a bare `value` reads the value out of whichever row the aggregate
+-- happened to keep, which SQLite guarantees only while the subquery holds
+-- exactly one aggregate. `albumGenres` in `meta.ts` declines that form at
+-- length; this declines it for the same reason and pays the same few
+-- milliseconds for it, once.

package/dist/db/migrations/037_admin_idempotency.sql

@@ -0,0 +1,31 @@
+-- What a mutation answered, kept by the key the caller gave it.
+--
+-- A control surface is called by an agent or a script over a network, and a
+-- network gives two answers that look alike from the caller's side: the request
+-- that was never received, and the answer that was lost on the way back. A
+-- caller that retries cannot tell them apart, and for `config set` a retry is
+-- harmless while for a rotation it is not. An `Idempotency-Key` header is how
+-- the caller says "this is the same request", and this table is where the first
+-- answer is kept so the second one can be given it instead of doing the work
+-- twice.
+--
+-- In the database rather than in memory, and that is not a detail: `POST
+-- /restart` exists, it is in this same surface, and a server that had just
+-- restarted would have forgotten every key it had ever been given — which is
+-- exactly the moment a client retries.
+--
+-- The body is stored as the text that was sent, with its status, because a
+-- replay has to be indistinguishable from the answer it repeats: a caller that
+-- got a different body the second time would be right to conclude the operation
+-- ran twice.
+CREATE TABLE admin_idempotency (
+  key        TEXT PRIMARY KEY,
+  method     TEXT NOT NULL,
+  path       TEXT NOT NULL,
+  status     INTEGER NOT NULL,
+  body       TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+-- Pruning is by age, and age is the only thing it is ever asked for.
+CREATE INDEX admin_idempotency_age ON admin_idempotency (created_at);

package/dist/db/migrations/038_cue_audio_index.sql

@@ -0,0 +1,24 @@
+-- The cue that plays an audio file, found by that file.
+--
+-- `cue.audio_file_id` is what every reader of a cue track joins on: the
+-- inventory's performer column, its "audio files with no track or cue" counter,
+-- and the artist stage's own binding of a cue to the file it came from. The
+-- table carried only its own primary key, so each of those questions was a full
+-- scan of `cue` — and one of them is asked once per track.
+--
+-- Measured on a 472-album collection, 5054 tracks against 302 cues: the
+-- inventory's performer subquery cost 120.7 ms of the dump's 171.0 ms, because
+-- every track read all 302 cues. With this index the same subquery is 28.4 ms
+-- and the whole dump 72.7 ms.
+--
+-- **The review that found this attributed the cost to the wrong thing**, and the
+-- correction is worth keeping: `GET /inventory` ran 1416 statements (three per
+-- album) and the dump was read as "73% statement executions". Executing the same
+-- three statements once for the whole collection — which is a real improvement
+-- and is kept — bought only about 20%. The executions were expensive for the
+-- rows they read, not for their number, and the rows were expensive because this
+-- index was missing.
+--
+-- Nothing about the answers changes: this is an index, not a redefinition, so no
+-- reader's output moves by a byte.
+CREATE INDEX idx_cue_audio_file ON cue (audio_file_id);

package/dist/db/sweep.js

@@ -0,0 +1,109 @@
+/**
+ * The tables, in the order they may be emptied.
+ *
+ * `album` before `release`, because an album's `release_id` names a release and
+ * a release emptied first would leave the albums of that box behind. The rest
+ * is the order the two stages have always emptied their tables in, and it is
+ * free to be arbitrary: nothing constrains `file` and `folder`, which are
+ * joined by path rather than by key.
+ */
+const DERIVED = [
+    {
+        table: 'file',
+        lateStamp: false,
+        detach: [
+            { action: 'delete', from: 'track', column: 'file_id' },
+            { action: 'null', from: 'cue', column: 'audio_file_id' },
+        ],
+    },
+    { table: 'folder', lateStamp: true, detach: [] },
+    { table: 'scan_state', lateStamp: false, detach: [] },
+    { table: 'album', lateStamp: true, detach: [] },
+    {
+        table: 'release',
+        lateStamp: true,
+        // Belt and braces, and said plainly rather than dressed up: nothing reaches
+        // this today. Every album that outlives the sweep above was re-derived from
+        // a surviving folder on this run, and re-deriving an album writes its
+        // `release_id` itself — so no surviving album can still name a doomed
+        // release. Removing this changes no test. It stays because the foreign key
+        // is declared without a cascade, and the cost of being wrong about the
+        // reachability is a run that fails on its last step.
+        detach: [{ action: 'null', from: 'album', column: 'release_id' }],
+    },
+];
+/** What a walk leaves behind, and what the scan takes away when it is gone. */
+export const SWEPT_BY_SCAN = ['file', 'folder', 'scan_state'];
+/** What classification derives from the folders the walk left standing. */
+export const SWEPT_BY_CLASSIFY = ['album', 'release'];
+/** `root_id = ? AND <the stamp is not this run's>`, bound in that order. */
+function vanished(derived) {
+    return derived.lateStamp
+        ? 'root_id = ? AND (last_seen_run_id IS NULL OR last_seen_run_id <> ?)'
+        : 'root_id = ? AND last_seen_run_id <> ?';
+}
+/**
+ * A statement releasing one reference, scoped by the rows that are going.
+ *
+ * The table and the column are this module's own literals — never a caller's
+ * string and never a name off disk — which is what makes interpolating them
+ * here the same kind of statement the sweep was written as before.
+ */
+function releaseSql(detach, derived) {
+    const doomed = `(SELECT id FROM ${derived.table} WHERE ${vanished(derived)})`;
+    return detach.action === 'delete'
+        ? `DELETE FROM ${detach.from} WHERE ${detach.column} IN ${doomed}`
+        : `UPDATE ${detach.from} SET ${detach.column} = NULL WHERE ${detach.column} IN ${doomed}`;
+}
+export function prepareSweep(db, tables) {
+    const owned = DERIVED.filter((derived) => tables.includes(derived.table));
+    const steps = owned.map((derived) => ({
+        markSeen: db.prepare(`UPDATE ${derived.table} SET last_seen_run_id = ?
+        WHERE root_id = ? AND (rel_path = ? OR substr(rel_path, 1, ?) = ?)`),
+        // What a row of this table says before a held path is stamped, so the stamp
+        // can be handed back afterwards. Read and written with the same matcher as
+        // `markSeen`, so the two cannot come to disagree about which rows are which.
+        // Keyed by the natural key rather than by `id`, which `folder` and
+        // `scan_state` do not have: what every table here shares is `root_id` and
+        // `rel_path`, which is why the matcher is spelled that way in the first place.
+        remember: db.prepare(`SELECT rel_path, last_seen_run_id AS stamp FROM ${derived.table}
+        WHERE root_id = ? AND (rel_path = ? OR substr(rel_path, 1, ?) = ?)`),
+        restore: db.prepare(`UPDATE ${derived.table} SET last_seen_run_id = ? WHERE root_id = ? AND rel_path = ?`),
+        detach: derived.detach.map((detach) => db.prepare(releaseSql(detach, derived))),
+        drop: db.prepare(`DELETE FROM ${derived.table} WHERE ${vanished(derived)}`),
+    }));
+    return {
+        run(rootId, runId, kept = [], held = []) {
+            for (const step of steps) {
+                // Before this table's rows are judged, not after: a row under a path the
+                // walk could not enter has to say it was seen, or the delete below
+                // reads it as gone. Each table is stamped before its own delete, which
+                // is all the ordering the amnesty needs — nothing else reads the stamp
+                // of another table mid-sweep.
+                for (const path of kept) {
+                    const below = `${path}/`;
+                    step.markSeen.run(runId, rootId, path, below.length, below);
+                }
+                // A held path is stamped for the same reason and unstamped for the
+                // opposite one: it has not vanished, and this run did not look at it.
+                // What survives the delete is the row; what must not survive is the
+                // claim, because that claim is the scope every stage selects its work
+                // by. Restored after the delete rather than instead of it — a row whose
+                // stamp says some older run is a row this delete would take.
+                const wasSaid = [];
+                for (const path of held) {
+                    const below = `${path}/`;
+                    for (const row of step.remember.all(rootId, path, below.length, below)) {
+                        wasSaid.push(row);
+                    }
+                    step.markSeen.run(runId, rootId, path, below.length, below);
+                }
+                for (const statement of step.detach)
+                    statement.run(rootId, runId);
+                step.drop.run(rootId, runId);
+                for (const row of wasSaid)
+                    step.restore.run(row.stamp, rootId, row.rel_path);
+            }
+        },
+    };
+}