funoteka 0.1.0

package/dist/db/migrations/003_cue_metadata.sql

@@ -0,0 +1,14 @@
+-- The cue's own metadata, which was parsed and then dropped on the floor.
+--
+-- wiki:3499 §8: "CATALOG in cue is the source of the catalogue number, with
+-- priority over the folder name". The parser has always filled `doc.rem`, but
+-- nothing read it and there was nowhere to put it, so every album got the raw
+-- folder name — `[2026-08-28] VA - A State Of Trance_Ibiza 2026 (...)[ARDI4701]`
+-- when the cue plainly says `TITLE "A State Of Trance: Ibiza 2026"`.
+
+ALTER TABLE cue ADD COLUMN catalog TEXT;
+
+-- The whole REM block, so a later stage can reach DATE / GENRE / DISCID /
+-- COMMENT without another migration. JSON, because REM keys are open-ended —
+-- real rips carry whatever the ripper felt like.
+ALTER TABLE cue ADD COLUMN rem_json TEXT;

package/dist/db/migrations/004_cue_performer.sql

@@ -0,0 +1,12 @@
+-- The cue's album-level PERFORMER, which was parsed and then dropped.
+--
+-- `applyCues` has always filled `doc.performer` — in a cue sheet the performer
+-- written above the first TRACK names the record's artist, and the per-track
+-- ones below it name each track — but there was nowhere to put it. The result
+-- was an artist stage with nothing to go on: the per-track PERFORMER survived
+-- in `cue_track`, while the album's own went in the bin.
+--
+-- Nullable, and legitimately so: a cue need not name a performer at all, and a
+-- compilation often names only the tracks.
+
+ALTER TABLE cue ADD COLUMN performer TEXT;

package/dist/db/migrations/005_incremental.sql

@@ -0,0 +1,23 @@
+-- Incremental rescan (plan:32 этап 6, requirements:39 §8).
+
+-- scan_state is the ledger of the last observation of each file: a scan writes
+-- what it saw and whether that differed from the run before it. The verdict has
+-- to be taken during the walk, not read back afterwards — scan writes the file
+-- row and this ledger from the same observation, so comparing the two later
+-- always agrees and tells nothing.
+--
+-- Defaults to 1 (changed): assuming movement costs a re-read, assuming stillness
+-- costs correctness.
+ALTER TABLE scan_state ADD COLUMN changed INTEGER NOT NULL DEFAULT 1;
+
+-- The "did this run see it" stamp `file` has carried since 001, extended to the
+-- rows a rescan must also let go of. Without it, dropping what is no longer on
+-- disk means matching path prefixes in SQL, which is both slower and wrong at
+-- the boundaries (`Album` would swallow `Album 2`).
+ALTER TABLE folder  ADD COLUMN last_seen_run_id INTEGER REFERENCES scan_run(id);
+ALTER TABLE album   ADD COLUMN last_seen_run_id INTEGER REFERENCES scan_run(id);
+ALTER TABLE release ADD COLUMN last_seen_run_id INTEGER REFERENCES scan_run(id);
+
+CREATE INDEX idx_folder_last_seen ON folder (root_id, last_seen_run_id);
+CREATE INDEX idx_album_last_seen ON album (root_id, last_seen_run_id);
+CREATE INDEX idx_release_last_seen ON release (root_id, last_seen_run_id);

package/dist/db/migrations/006_tags.sql

@@ -0,0 +1,57 @@
+-- Tags, and where a title came from ([[task:2667]]).
+--
+-- Until now the collection's own metadata was parsed and dropped: `file` knew
+-- a file's size and mtime and nothing about what it called itself. 279 of 291
+-- files across four sample roots show as `(untitled)` / `--:--` while carrying
+-- perfectly good ID3 and Vorbis comments.
+
+-- The encoding a tag's text was read as, and how sure the reader was.
+--
+-- The same pair `cue` carries, for the same reason and with the same shape: a
+-- ripper that writes CP1251 bytes under a Latin-1 declaration produces a title
+-- that looks like a title, and "I guessed windows-1251" is the finding that
+-- makes it visible. CERTAIN means nothing was inferred.
+ALTER TABLE file ADD COLUMN encoding TEXT;
+ALTER TABLE file ADD COLUMN encoding_confidence REAL;
+
+-- Which run last read this file's tags.
+--
+-- The ledger alone is not enough to make this stage incremental. `scan_state`
+-- says a file's bytes moved or did not; it cannot say whether anything ever
+-- *read* them, because until this migration nothing did. And "no rows in
+-- file_tag" cannot stand in for it either: a file with no tags at all is a
+-- completely ordinary thing — an untagged rip — and it would be re-read on
+-- every scan forever while never producing a row to show for it. So the read
+-- is stamped, and NULL means never read.
+--
+-- Nullable on purpose: every file already on disk has NULL here, which is
+-- exactly the backfill condition - the tags of the existing collection get read
+-- once, on the first scan after this migration.
+ALTER TABLE file ADD COLUMN tags_read_run_id INTEGER REFERENCES scan_run(id);
+
+-- Where an album's or release's title came from: 'folder' | 'cue' | 'tag'.
+--
+-- A source, written down, instead of a guess from emptiness. `album.title` is
+-- never NULL — classify fills it from the folder name or the file's stem — so
+-- a tag cannot decide whether it is looking at a placeholder or at a name a cue
+-- deliberately chose. With the source recorded, the priority is explicit: a tag
+-- overrides the folder and never overrides a cue.
+ALTER TABLE album   ADD COLUMN title_source TEXT;
+ALTER TABLE release ADD COLUMN title_source TEXT;
+
+-- One tag of one file.
+--
+-- `position` exists because Vorbis comments repeat a name: two ARTIST lines in
+-- one file is how a collaboration is written, and collapsing them would keep
+-- one name and silently drop the other.
+CREATE TABLE file_tag (
+  file_id  INTEGER NOT NULL REFERENCES file(id) ON DELETE CASCADE,
+  name     TEXT    NOT NULL,   -- folded to lower case, as the reader reports it
+  value    TEXT    NOT NULL,
+  position INTEGER NOT NULL,
+  PRIMARY KEY (file_id, name, position)
+);
+
+-- Reading a tag by name is the only lookup the filling stages do: "the ALBUM
+-- of this file", "the ARTIST of this file".
+CREATE INDEX idx_file_tag_name ON file_tag (name);

package/dist/db/migrations/007_artist_credit.sql

@@ -0,0 +1,35 @@
+-- An artist credit is a list, not a name ([[task:2684]]).
+--
+-- Until now an album pointed at exactly one artist. A collaboration is not one
+-- artist: `Cock E.S.P. + Thirdorgan`, `Suffering Bastard + Cock E.S.P.` — and on
+-- the sample this showed up as 11 of 28 albums with no artist at all, because
+-- the per-track ARTIST values inside a split disagree and no majority exists
+-- (`2011 - Demonologists + Cock E.S.P.` is 10 to 1, and calling that album
+-- `Cock E.S.P.` would be confidently wrong).
+--
+-- The shape is OpenSubsonic's `artists[]` with `joinPhrase`: an ordered list,
+-- each entry carrying the phrase that joined it to the one before.
+
+CREATE TABLE artist_credit (
+  album_id    INTEGER NOT NULL REFERENCES album(id) ON DELETE CASCADE,
+  position    INTEGER NOT NULL,
+  artist_id   INTEGER NOT NULL REFERENCES artist(id) ON DELETE CASCADE,
+  -- Verbatim, whitespace and all, so `a + b` rebuilds as `a + b` and not
+  -- `a+b`. Empty for the first entry: nothing joined it to anything.
+  join_phrase TEXT    NOT NULL DEFAULT '',
+  PRIMARY KEY (album_id, position)
+);
+
+-- What the source said, before it was read as a list.
+--
+-- The list is lossless — it reassembles exactly — so this is not a backup. It
+-- is the thing a human audits: a rule that splits `Smell & Quim` into two
+-- artists cannot be argued with unless the original is still on the row, and
+-- the rule that split it is a guess that has to stay visible.
+ALTER TABLE album ADD COLUMN credit_raw    TEXT;
+ALTER TABLE album ADD COLUMN credit_source TEXT;  -- 'cue' | 'folder' | 'tag'
+
+-- Pruning reads this table: an artist named only by a credit is still an
+-- artist. Without that, `pruneArtists` would delete the row and the cascade
+-- above would silently take the credit with it.
+CREATE INDEX idx_artist_credit_artist ON artist_credit (artist_id);

package/dist/db/migrations/008_issue_stage.sql

@@ -0,0 +1,39 @@
+-- Which stage filed each issue, so a stage can clear its own rows.
+--
+-- Most stages derive their report from the present: `cues` and `artists` walk
+-- every root on every run, so an earlier run's rows are dead weight — every
+-- reader scopes by run, and nothing removed them. Without ownership, a
+-- collection rescanned daily grows this table by one run's worth per day, and
+-- any reader that forgets the scope counts duplicates.
+--
+-- Two stages are not like that. `scan` records a healed root path and a twin
+-- whose rows were dropped, which happen once and raise nothing on a later run;
+-- `tags` reads only the files the ledger reports changed, so a row describes the
+-- last time that file was read. Clearing those would not replace the rows with
+-- an equal report — it would delete the only record that the thing happened.
+--
+-- Ownership is by stage and never by a list of kinds: a hand-kept list is a list
+-- that drifts, and the cue stage's kinds are born in two files.
+
+ALTER TABLE issue ADD COLUMN stage TEXT NOT NULL DEFAULT '';
+
+-- Rows that predate the column. The two stages that clear replace theirs on the
+-- next run, so only `scan` and `tags` rows survive this mapping — and those are
+-- the two the rules below get right.
+--
+-- The empty default exists for this backfill alone. Every writer binds a stage,
+-- and the value it binds is a union type, so omitting one is a compile error
+-- rather than a row no `clearIssues` will ever match.
+UPDATE issue SET stage = CASE
+  WHEN kind LIKE 'artist-%' THEN 'artists'
+  WHEN kind LIKE 'tag-%'    THEN 'tags'
+  WHEN kind LIKE 'cue-%'    THEN 'cues'
+  WHEN kind IN ('ripper-marker-titles', 'track-without-index',
+                'album-without-audio', 'track-count-mismatch') THEN 'cues'
+  ELSE 'scan'
+END;
+
+-- Serves both scopes a clear uses: the stage alone (a prefix of this index) and
+-- the per-file delete `tags` does, which is one statement per file read and
+-- would otherwise scan the stage's rows each time.
+CREATE INDEX idx_issue_stage ON issue (stage, root_id, rel_path);

package/dist/db/migrations/009_cue_title.sql

@@ -0,0 +1,20 @@
+-- The cue's own TITLE, which was parsed and then dropped on the floor.
+--
+-- 003 did exactly this for CATALOG, and gave the reason in almost these words.
+-- It stopped one column short: `doc.title` is read on every run — it is what
+-- names a release better than the folder name does — and nothing persisted it,
+-- so the moment a run ended the only record of what a cue said was gone.
+--
+-- That is visible wherever the priority chain *turns a title away*. Both of the
+-- Wall's cues write `The Wall [Disc 1]` and `The Wall [1994 Remaster](Disc 2)`:
+-- EAC writes a disc's own label into TITLE, each label names a disc rather than
+-- the record, and the release keeps its folder name. The decision is right and
+-- is reported as an issue — but a refusal is a judgement about a value, and
+-- without this column the value did not survive the judgement, so there was
+-- nothing left to review the decision against.
+--
+-- Kept for every cue, not only the turned-away ones. Which titles are refused
+-- is a rule that will move, and a column that only holds the refusals of today's
+-- rule cannot show what tomorrow's would have done differently.
+
+ALTER TABLE cue ADD COLUMN title TEXT;

package/dist/db/migrations/010_duration_source.sql

@@ -0,0 +1,31 @@
+-- Where an `audio_probe` length came from, measured or worked out.
+--
+-- The project's rule is that a value has to say whether it is knowledge or a
+-- guess — `title_source`, `ambiguous`, `encoding_confidence`, and
+-- `TagRead.durationRefused` are all that rule applied elsewhere. Duration was
+-- the one place it was not: `probeFile` puts ffprobe's `format.duration` into
+-- this table the same way the tag readers put the container's own statement
+-- there, and the two are not the same kind of answer.
+--
+-- They differ exactly where it matters. ffprobe reads a length when the
+-- container states one, but an mp3 that states no frame count — no Xing/Info
+-- header — leaves it nothing to read, and it derives the number from the file
+-- size and the bitrate instead. Measured on the collection's own
+-- `02. 218 Tracks.mp3`: the stored 165 778 ms is `size * 8 / bitrate` to the
+-- millisecond. That the value happens to be close to the truth does not make
+-- it a measurement, and nothing downstream could tell.
+--
+-- Two values, because two things are worth telling apart and no more:
+--
+--   'container'  the file's own bytes state it — FLAC STREAMINFO, MP4 mvhd, an
+--                mp3's stated frame count, or a walk over an mp3's frames.
+--                Everything the tag stage seeds is this.
+--   'ffprobe'    ffprobe's answer, which is a reading for some containers and
+--                a derivation for others. It is only ever reached for a file
+--                the reader could not measure, and it is named rather than
+--                judged: `tag-duration-estimated` carries the detail.
+--
+-- NULL for rows written before this column, which is honest — they were
+-- written when the distinction was not being made.
+
+ALTER TABLE audio_probe ADD COLUMN duration_source TEXT;

package/dist/db/migrations/011_track_title_source.sql

@@ -0,0 +1,28 @@
+-- Where a track's title came from — the cue, the file's tag, or its name.
+--
+-- The project's rule is that a value has to say whether it is knowledge or a
+-- guess — `title_source` on album and release, `duration_source` on
+-- `audio_probe`, `encoding_confidence`, `ambiguous`. Track titles were the one
+-- place the chain could not say: three sources now feed it and two of them are
+-- weaker than the first.
+--
+-- The distinction is not academic. A cue is a document about *this* record and
+-- a tag is a statement somebody made about the track, while a title read off a
+-- file name is a hint the filesystem happens to carry — `back to archangelsk`
+-- written in lower case, with the artist's name and the release group cut off
+-- it by a rule that guessed where they ended. That is a name worth having
+-- where there is nothing else, and worth being able to tell apart from one
+-- somebody wrote.
+--
+--   'cue'   a TITLE in a cue that describes these files. The authority.
+--   'tag'   the file's own TITLE tag. Beats the folder, loses to the cue.
+--   'name'  read off the file name (see `cue/track-name.ts`). The last word,
+--           and the one that says out loud that it is a guess.
+--
+-- NULL where no source named the track — which includes a source that spoke and
+-- was rejected as a ripper's marker (`(empty)`, `(silence)`), because the value
+-- the row would carry is not a name at all. Also NULL for rows written before
+-- this column, which is honest: they were written when the distinction was not
+-- being made.
+
+ALTER TABLE track ADD COLUMN title_source TEXT;

package/dist/db/migrations/012_file_container.sql

@@ -0,0 +1,25 @@
+-- The container the tag reader recognised in a file, NULL when it recognised
+-- none ([[task:2706]]).
+--
+-- `tag-format-unknown` is an aggregate on purpose — one finding per root and
+-- extension, because 309 `m4a` files are a fact about the collection and not 309
+-- facts — and it was counted over the files the stage opened *this run*. That
+-- made the number a property of the run rather than of the collection: a second
+-- run opens nothing, so it was not recomputed at all, and a run that opened one
+-- new file reported one while an older row still claimed two.
+--
+-- Counting it over the whole collection needs the reader's verdict to outlive
+-- the run that reached it, which is what this column is. Read its NULL two ways,
+-- told apart by `tags_read_run_id`: never read, and read with nothing
+-- recognised. A file whose ripper wrote no tags at all is neither — its
+-- container is named and it has simply stated nothing, which is a different
+-- thing from a format nothing here can open.
+ALTER TABLE file ADD COLUMN tags_container TEXT;
+
+-- Every file already on disk predates the column, so its NULL means "not
+-- recorded", which is not the same as "the reader recognised nothing". Left
+-- alone, the whole collection would be counted as a format nothing can read.
+-- Clearing the stamp is what makes the next scan open those files again and
+-- write the verdict down — the same backfill migration 006 chose, for the same
+-- reason and at the same cost: one full read of the collection's tags.
+UPDATE file SET tags_read_run_id = NULL;

package/dist/db/migrations/013_cover_art.sql

@@ -0,0 +1,28 @@
+-- The cover a file carries, as a place in the file rather than a copy.
+--
+-- A picture inside a file is the answer for a record whose folder holds none —
+-- measured on the live collection, 54 of the 59 albums without a folder image
+-- carry their art inside their files, 47 of them as an MP4 `covr` and 7 as an
+-- ID3v2 `APIC`. Copying those bytes into the meta layer would mean gigabytes of
+-- something already on the disk, and a copy that goes stale the moment somebody
+-- edits the file's tags — so what is written down is where the image is.
+--
+-- `picture_type` is the file's own numbering, where 3 is a front cover: it says
+-- which picture this is, and it is what `betterPicture` chose between when a
+-- file carried more than one.
+CREATE TABLE cover_art (
+  file_id      INTEGER PRIMARY KEY REFERENCES file(id) ON DELETE CASCADE,
+  mime         TEXT    NOT NULL,
+  picture_type INTEGER NOT NULL,
+  offset       INTEGER NOT NULL,
+  length       INTEGER NOT NULL
+);
+
+-- A table a stage derives is empty until that stage runs again, and the tags
+-- stage only reads files the ledger reports as moved or never read — so on the
+-- scan after this migration every file would keep its old `tags_read_run_id`,
+-- the stage would skip all of them, and this table would stay empty while the
+-- collection it describes is full of covers. Clearing the stamp is what makes
+-- the next scan read them once more; it costs one full read of the collection
+-- and its absence costs the feature.
+UPDATE file SET tags_read_run_id = NULL WHERE kind = 'audio';

package/dist/db/migrations/014_album_year.sql

@@ -0,0 +1,17 @@
+-- The year a record was released, which the classifier has been parsing and
+-- throwing away.
+--
+-- `parseFolderName` reads a folder's name once for the pieces a collector puts
+-- in it — the year, the artist, the format note — and only the title has ever
+-- been used (`classify.ts`). A release called `1988. Группа крови` was filed
+-- under `Группа крови` and the 1988 was lost, which is why no client could show
+-- a release date: 236 of the 241 albums in the live collection name a year in
+-- their path, and the meta layer held none of them.
+--
+-- `year_source` records which statement the number is, the way `title_source`
+-- does: `folder` when the name slot carried it, `tag` when the only thing that
+-- said so was a file's own DATE. Local sources own the year until an external
+-- one arrives (v1.5, brainstorm:190 Q13) — and the folder outranks the tag for
+-- the same reason it outranks it for a title: it is what the collector wrote.
+ALTER TABLE album ADD COLUMN year INTEGER;
+ALTER TABLE album ADD COLUMN year_source TEXT;

package/dist/db/migrations/015_probe_method.sql

@@ -0,0 +1,14 @@
+-- Which reading of a file a probe row is.
+--
+-- A row in this table is an answer about a file *as read by a particular
+-- method*, and until now nothing in the row said which one — so a change of
+-- method left readings behind that were no longer readings, and the collection
+-- carried them as facts. (It did: `codec` was filled with the container's name
+-- rather than a codec, `mp4` and `id3v2`, for two thousand files.)
+--
+-- Zero is "a method older than the one this code reads with", which is what
+-- every row written before this migration is. `PROBE_METHOD` in
+-- `src/probe/ffprobe.ts` is the number rows carry from here on, and raising it
+-- is how a change of method is announced: every row below it stops being an
+-- answer, and the next scan takes those files again.
+ALTER TABLE audio_probe ADD COLUMN probe_method INTEGER NOT NULL DEFAULT 0;

package/dist/db/migrations/016_tags_method.sql

@@ -0,0 +1,20 @@
+-- Which reading of a file's tags a file row is.
+--
+-- The same defect `probe_method` was added in 015 to fix, one table over. A file
+-- row carries the verdict of whichever reader last opened it — `tags_container`,
+-- from 012, is that verdict — and until now nothing said *which* reader it was.
+-- So a change of reader left verdicts behind that were no longer verdicts, and
+-- the collection carried them as facts.
+--
+-- It did, and this migration is the repair. The Ogg reader landed on 2026-09-13
+-- and the eighty `.ogg` files of the collection stayed read-and-empty: an
+-- earlier scan had stamped them with a reader that did not know the format, the
+-- files had not moved since, and the stage's own incrementality is what kept the
+-- new reader away from them. Nothing was wrong with the reader; nothing could
+-- reach it. The FLAC sweep before it had the same shape and was fixed by hand.
+--
+-- Zero is "a method older than the one this code reads with", which is what
+-- every row written before this migration is. `TAGS_METHOD` in `src/tags/read.ts`
+-- is the number rows carry from here on, and raising it is how a change of
+-- reader is announced: every file below it is read again, once.
+ALTER TABLE file ADD COLUMN tags_method INTEGER NOT NULL DEFAULT 0;

package/dist/db/migrations/017_cover_indirect.sql

@@ -0,0 +1,23 @@
+-- What kind of place a cover's `offset` and `length` name.
+--
+-- Until now there was one kind and no need to say so: the range was the image,
+-- a run of the audio file a client could be sent. A picture carried as a
+-- `METADATA_BLOCK_PICTURE` comment — which is how an Ogg file holds a cover at
+-- all, and how all eighty of this collection's `.ogg` files hold theirs — is a
+-- different kind of place. It is base64 of a picture block inside a packet that
+-- the lacing rule scatters across pages, so no range of the file *is* the image;
+-- what can be written down is a range worth reading.
+--
+-- So the column says which of the two a row means:
+--
+--   'image'     [offset, length) is the picture. Every row written before this
+--               migration, and every reader that names a picture's own bytes —
+--               MP4 `covr`, ID3v2 `APIC`, a FLAC PICTURE block.
+--   'indirect'  [offset, length) is a region that holds the picture and must be
+--               read and parsed to get it. `src/cover/picture.ts` does that.
+--
+-- The picture was already being read and thrown away by this collection's
+-- reader — it arrived as just another comment and left as a tag of a hundred and
+-- eighty kilobytes of base64 — so nothing here is a new discovery. What is new
+-- is that it goes somewhere useful.
+ALTER TABLE cover_art ADD COLUMN kind TEXT NOT NULL DEFAULT 'image';

package/dist/db/migrations/018_release_year.sql

@@ -0,0 +1,14 @@
+-- The year a box was released, which the classifier has been reading and
+-- throwing away.
+--
+-- `014_album_year.sql` gave the year a column on `album` because the folder name
+-- states it and nothing kept it. A box is the case that column cannot hold: its
+-- discs are named `CD1 ● Альбом`, `CD2 ● …` — the year is in the *box* folder's
+-- name (`1988 ● Группа крови (2019, Maschina Records, MKK881CD, 3CD)`), and the
+-- disc rows state nothing. So every record of every box came back with no year,
+-- while the name the client was shown began with one.
+--
+-- `release` is the row that owns the box folder, so the year goes here, beside
+-- the title it was parsed from. Nothing is backfilled: the next scan writes it,
+-- the same way the title is written on every run.
+ALTER TABLE release ADD COLUMN year INTEGER;

package/dist/db/migrations/019_file_tag_name_file_value.sql

@@ -0,0 +1,20 @@
+-- The genre a file states, findable without reading the file's row.
+--
+-- `ALBUM_GENRES` drives from `file_tag` filtered by name — 2702 rows on this
+-- collection — and then reads each row to get its `file_id` and its value.
+-- `idx_file_tag_name` answers the name and stops there, so every one of those
+-- rows costs a table read. Carrying `file_id` and `value` in the index makes the
+-- scan covering, and measured on a copy of the live collection, warm and
+-- interleaved with the baseline so that drift touches both equally, it halves the
+-- join: 8.32 ms to 4.18. `ALBUM_GENRES` as a whole goes from 14.98 to 12.11 ms,
+-- the window function being what is left.
+--
+-- It is not free: the index carries every tag value, and `VACUUM`ed the database
+-- grows from 12.3 MB to 14.2. Fifteen per cent of the meta layer for about three
+-- milliseconds on a listing route. That is a small win and it is written down as
+-- one rather than dressed up.
+--
+-- `(name, file_id)` without the value was measured too and buys nothing — 8.05
+-- against 8.32 — because what the join saves is the table read, and the value is
+-- what it wanted from the table.
+CREATE INDEX idx_file_tag_name_file_value ON file_tag (name, file_id, value);

package/dist/db/migrations/020_analyze_after_index.sql

@@ -0,0 +1,16 @@
+-- The statistics a new index invalidates, refreshed.
+--
+-- `019_file_tag_name_file_value.sql` added an index, and a migration is not a
+-- scan: `runStages` refreshes the planner's statistics at the end of every run
+-- (`run.ts`, the 'planner' stage) and it never ran here. So SQLite kept the
+-- estimates it had made while that index did not exist and chose its plan for the
+-- listing accordingly. Measured on a copy of the live collection, 500-record
+-- `getAlbumList2` went from 29.8 ms to 68.6 ms the moment the index appeared, and
+-- back to 24.7 ms once `ANALYZE` had run — better than it was without the index at
+-- all, which is what the index was for.
+--
+-- This is the trap `run.ts` already describes, arriving through a door that file
+-- does not cover: the planner's numbers are derived from the data, and anything
+-- that changes the data *or the graph above it* has to say so. A future migration
+-- that adds an index owes the same line.
+ANALYZE;

package/dist/db/migrations/021_cue_index_files.sql

@@ -0,0 +1,15 @@
+-- Which FILE each cue mark was written in.
+--
+-- `cue_track` carried one `file_index` — the file the track opens — and two times,
+-- and nothing said which file each time was counted from. A cue writes the pregap
+-- of a track that opens a file at the *end* of the file before it, so `INDEX 00`
+-- can sit in one FILE and `INDEX 01` in the next; the row then read
+-- `index00_ms 895173, index01_ms 0`, which says the track ends before it begins.
+-- Measured on this collection: 31 rows of 1001, across six cues.
+--
+-- Nothing in v1 reads those two columns directly, and every segmented album here
+-- has a single `file_index`, so no output changes. The columns are added because
+-- a schema that cannot say what its numbers are counted from is a schema the next
+-- reader — the MCP surface v1.1 — would read as a lie.
+ALTER TABLE cue_track ADD COLUMN index00_file_index INTEGER;
+ALTER TABLE cue_track ADD COLUMN index01_file_index INTEGER;

package/dist/db/migrations/022_sidecar_text.sql

@@ -0,0 +1,19 @@
+-- The text a sidecar file holds, decoded.
+--
+-- An `.nfo` and an EAC `.log` are the record's own documentation, and a FLAC rip
+-- already carries both *inside* itself: `logfile` and `cuesheet` are tags that 41
+-- files of this collection state. A rip that keeps them as files beside the audio
+-- had them nowhere — the scanner recorded their kind and their size and never
+-- opened them, so `file.encoding` was NULL for all 417 of them and the meta layer
+-- could not be read across the two shapes (task:2757).
+--
+-- The text is here rather than in `file_tag`, and that is the point of a table of
+-- its own. A tag is something a file states about itself and is queried by name;
+-- a whole document under a name is what once put 562 KB of base64 into
+-- `file_tag`, one value at a time (TAGS_METHOD 2). These run to 15 KB each. The
+-- encoding and how much it was a guess are the `file` row's, beside every other
+-- file's.
+CREATE TABLE sidecar_text (
+  file_id INTEGER PRIMARY KEY REFERENCES file(id) ON DELETE CASCADE,
+  text    TEXT NOT NULL
+);

package/dist/db/migrations/023_track_credit.sql

@@ -0,0 +1,23 @@
+-- Who a track is by, when that is not who the record is by.
+--
+-- An album's credit is a list with join phrases (`artist_credit`), because a
+-- record can be by two people and the source says which word joined them. A
+-- track's is the same shape, for the same reason — and `track.artist_id` cannot
+-- hold it: one column holds one artist, and `Кино & Джоанна Стингрей` is two.
+--
+-- What this is for, measured on the live collection: of 2626 tracks whose cue
+-- states a performer, 1862 state the record's own credit again, 218 differ —
+-- and 534 have no album row at all, so for them the performer is not a
+-- refinement of the record's credit but the only credit that exists (task:2729).
+--
+-- `position` is the order the source stated, and `join_phrase` is the word it
+-- joined them with, exactly as `artist_credit` keeps both.
+CREATE TABLE track_credit (
+  track_id    INTEGER NOT NULL REFERENCES track(id) ON DELETE CASCADE,
+  position    INTEGER NOT NULL,
+  artist_id   INTEGER NOT NULL REFERENCES artist(id) ON DELETE CASCADE,
+  join_phrase TEXT,
+  PRIMARY KEY (track_id, position)
+);
+
+CREATE INDEX track_credit_artist ON track_credit (artist_id);

package/dist/db/migrations/024_playlists.sql

@@ -0,0 +1,63 @@
+-- Server-side playlists: the one thing in this database that is not derived
+-- from the filesystem.
+--
+-- Every other table here is an overlay over the collection — a row exists
+-- because a file exists, and a scan can rebuild all of it. A playlist is the
+-- listener's own statement and is nowhere on disk: it is the first thing the
+-- API writes, and the first thing a scan must leave alone.
+--
+-- That is why the two tables live in the meta layer rather than beside it. They
+-- share the one file with the classified model, and the model's rule — the
+-- scanner is the only writer — is narrowed rather than broken: the scanner
+-- writes the model, and this is the one part of the file it never touches.
+
+CREATE TABLE playlist (
+  id         INTEGER PRIMARY KEY,
+  name       TEXT    NOT NULL,
+  comment    TEXT,
+  -- The protocol's `public`, kept although one listener cannot tell the
+  -- difference: there is no second account to share with, and a server that
+  -- dropped what a client set would hand that client back a playlist claiming
+  -- not to be public — the client's own setting, denied to it.
+  public     INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT    NOT NULL,
+  -- When anything about the playlist last moved: its name, its comment, or a
+  -- song. The protocol shows both timestamps to a client, and a client that
+  -- syncs by them needs this one to change on an edit — a `changed` that only
+  -- moved when songs were added would tell such a client its stale copy of the
+  -- name was current.
+  changed_at TEXT    NOT NULL
+);
+
+-- A song's place in a playlist.
+--
+-- `position` is the order the client is shown, and every write lays it out from
+-- zero with no holes — because the protocol addresses entries by their index,
+-- and `songIndexToRemove` counts on the same density. A song taken out by the
+-- cascade below does leave its number unused until the next write, and nothing
+-- minds: the number is read as an order (the rows are sorted by it), never as
+-- the position a client means.
+--
+-- The same song may sit at two positions. The protocol says nothing against it,
+-- a listener may well want it, and a schema that forbade it would be inventing
+-- a rule the client cannot see.
+--
+-- `ON DELETE CASCADE` on the track is the whole of what "a playlist survives a
+-- rescan" costs. A track still on disk keeps its id — the scanner upserts on
+-- `(album_id, ordinal)` rather than re-inserting — so its entries stay exactly
+-- where they were. A track whose file is gone is dropped by the sweep, and its
+-- entries go with it instead of pointing at a row that is no longer there.
+--
+-- The cascade on the playlist is the obvious half: a deleted playlist holds
+-- nothing. It is also what makes `deletePlaylist` one statement.
+CREATE TABLE playlist_track (
+  playlist_id INTEGER NOT NULL REFERENCES playlist(id) ON DELETE CASCADE,
+  position    INTEGER NOT NULL,
+  track_id    INTEGER NOT NULL REFERENCES track(id) ON DELETE CASCADE,
+  PRIMARY KEY (playlist_id, position)
+);
+
+-- The sweep deletes tracks, and SQLite has to find this table's rows to cascade
+-- into them; without this it scans every entry of every playlist per deleted
+-- track.
+CREATE INDEX playlist_track_track ON playlist_track (track_id);

package/dist/db/migrations/025_playlist_sequence.sql

@@ -0,0 +1,27 @@
+-- A playlist id is handed out once and never handed out again.
+--
+-- `playlist.id` is an INTEGER PRIMARY KEY, which in SQLite is the rowid: the
+-- next row takes the highest number ever used plus one, so a row deleted and a
+-- row created afterwards are given the *same* number — the highest ever used
+-- went down when the first was deleted. Measured: create, delete, create, and
+-- the second playlist is `pl:1` as well.
+--
+-- That is invisible to a client holding nothing and wrong for one holding a
+-- playlist. An id this server handed out names a different playlist after the
+-- original is deleted, and nothing in the answer says so — a player with the
+-- old one open shows the new one, a bookmark opens somebody else's list.
+--
+-- `AUTOINCREMENT` is SQLite's own answer to exactly this, and it needs the
+-- table rebuilt, which this migration deliberately is not: the table is already
+-- deployed and may already hold a listener's playlists. A counter in a table of
+-- its own says the same thing — the number is handed out, written down, and
+-- never read back out of the rows.
+CREATE TABLE playlist_sequence (
+  only_row INTEGER PRIMARY KEY CHECK (only_row = 1),
+  next     INTEGER NOT NULL
+);
+
+-- Seeded past whatever is already there, so an id already handed out is not
+-- handed out again by this either.
+INSERT INTO playlist_sequence (only_row, next)
+VALUES (1, (SELECT COALESCE(MAX(id), 0) + 1 FROM playlist));

package/dist/db/migrations/026_playlist_source_file.sql

@@ -0,0 +1,19 @@
+-- A playlist that a file asked for.
+--
+-- A `.m3u` sitting in the collection is a list somebody made, and one whose
+-- songs come from different folders is a list this server should offer rather
+-- than a folder it should browse. Importing it means writing a row here — so
+-- the row has to say which file it came from, or the next scan would import the
+-- same list again under a second name, and the one after that under a third.
+--
+-- `ON DELETE CASCADE` is the other half: the file is the list, and a list whose
+-- file is gone is a list nobody asked for. The sweep deletes files; this makes
+-- the imported playlist go with its own.
+--
+-- Rows written by the listener have no file and keep this NULL — the column
+-- says where a playlist *came from*, not what it is, and the two kinds are told
+-- apart by whether anything is there.
+ALTER TABLE playlist ADD COLUMN source_file_id INTEGER REFERENCES file(id) ON DELETE CASCADE;
+
+-- The import asks this question once per file, on every scan that re-reads one.
+CREATE INDEX playlist_source_file ON playlist (source_file_id);