funoteka 0.1.0

package/dist/cue/track-name.js

@@ -0,0 +1,120 @@
+/**
+ * The title a file's own name states, for a track nothing else names.
+ *
+ * A collection is not all tags. One of its parts arrives folder-organized with
+ * a `readme` and nothing else (requirements:39 §1, the Kroogi sample), and the
+ * name of the file is then the only witness left. The contract's chain is cue →
+ * tag → *this*: a document about the album speaks with authority, a tag speaks
+ * for its own file, and a file name is the weakest of the three — which is why
+ * it is asked last and never overrides either.
+ *
+ * ## What a name carries that is not the track
+ *
+ * Three things, and each is dropped only on evidence:
+ *
+ *   - **The track number.** `01-`, `01. `, `01 - ` — a leading count, never part
+ *     of a title. Dropped on sight, because nothing else in a file name looks
+ *     like it: no title in these collections opens with two digits and a dot.
+ *   - **The artist.** The scene writes `Artist - Title` in front of every track,
+ *     and a split record gives each track a *different* one, so the album's own
+ *     artist cannot find these. The album's folder **name** can: it lists every
+ *     player on the record, and a field whose words all appear there is the
+ *     album's, not the track's.
+ *   - **The release group.** `-kroogi` glued to the tail is the same class as
+ *     `-Kroogi.com` in the folder name — where the rip came from, not what the
+ *     record is.
+ *
+ * Two rules were narrowed by measuring the rule against the collection's 850
+ * audio files (88 fields dropped, all of them credits: `Cock E.S.P.` ×45,
+ * `Emil Hagstrom` ×8, `Suffering Bastard` ×7, …), and both narrowings answer a
+ * real file:
+ *
+ *   - **Only a *leading* field is a field.** `Кино - Спасём мир (MASHCD-148)`
+ *     sits in `1986 ● Концерт «Спасём мир» …`, and the folder agrees with its
+ *     tail word for word. Dropping a trailing ` - ` field because the folder
+ *     agrees leaves `Кино` as the title of a song called `Кино - Спасём мир`:
+ *     an album named after the piece it holds is the ordinary case, not the
+ *     exception, so the tail of a name is never a field.
+ *   - **The scene's own marks need the scene's written separator.** `_` for a
+ *     space and a glued `-site` tail are conventions of one layout, and `_-_`
+ *     is where that layout declares itself — the same "written, not incidental"
+ *     test `SCENE` in `classify/folder-name.ts` rests on. Without it,
+ *     `Amp-Destroyer` is a hyphen in a title, and `my_cool_track` keeps its
+ *     underscore.
+ *
+ * Nothing is invented. A name written in lower case stays in lower case: that
+ * is what the file says, and a title with its capitals belongs to a source that
+ * has them (a tag, or the `readme` tracklist — [[task:2710]]).
+ */
+import { stemOf } from "../util/names.js";
+/** `01-`, `01.`, `01 - ` — a leading count and the separator after it. */
+const TRACK_NUMBER = /^\d{1,2}\s*[.\-_)\]]\s*/;
+/** The separator the scene layout writes between artist and title. */
+const SCENE_SEPARATOR = '_-_';
+/**
+ * A word glued to the tail by a dash — `archangelsk-kroogi`.
+ *
+ * The lookbehind is the whole of the rule: a dash with a space in front of it
+ * opens a field, and a field is never the release group it was measured against.
+ * Letters, digits, marks and dots only, so `(MASHCD-148)` — a bracket and a
+ * number — cannot be read as one.
+ */
+const GLUED_TAIL = /(?<=\S)-([\p{L}\p{N}\p{M}.]+)$/u;
+/**
+ * The words a name is made of, folded for comparison.
+ *
+ * Unicode-aware for the same reason `artistName` is: `Кино` has to survive, and
+ * `\p{M}` matters because a tree ripped on macOS stores `Björk` decomposed.
+ */
+function words(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}]+/gu, ' ')
+        .trim()
+        .split(' ')
+        .filter((word) => word !== '');
+}
+/**
+ * The title this file's name states.
+ *
+ * `albumName` is the album's own folder name — the whole of the external
+ * evidence, and null when nothing supplies one. Without it the file still
+ * speaks; it is simply not corroborated, so no field of it is claimed as the
+ * album's.
+ */
+export function titleFromFileName(fileName, albumName) {
+    const stem = stemOf(fileName);
+    // Both of the scene's marks stand or fall with its separator, so it is read
+    // once, before the folding that loses it.
+    const scene = stem.includes(SCENE_SEPARATOR);
+    const rest = scene ? stem.replace(/_/g, ' ') : stem;
+    const evidence = new Set(words(albumName ?? ''));
+    const stated = (field) => {
+        const found = words(field);
+        return found.length > 0 && found.every((word) => evidence.has(word));
+    };
+    let text = rest.trim();
+    // The number goes first: it is the one mark that is proof in itself, and the
+    // fields below are read on what is left of the name.
+    const number = TRACK_NUMBER.exec(text);
+    if (number !== null && number[0].length < text.length)
+        text = text.slice(number[0].length).trim();
+    // Never the whole name: a file called `01.mp3` states a number and nothing
+    // else, and eating it would leave no title at all.
+    let fields = text.split(/\s+-\s+/);
+    while (fields.length > 1 && stated(fields[0] ?? '') && fields.slice(1).join(' - ').trim() !== '') {
+        fields = fields.slice(1);
+    }
+    text = fields.join(' - ');
+    // The scene's tail: the dash is glued to the word, so it never opened a field.
+    const glued = scene ? GLUED_TAIL.exec(text) : null;
+    if (glued !== null && stated(glued[1] ?? '') && text.slice(0, glued.index).trim() !== '') {
+        text = text.slice(0, glued.index).trim();
+    }
+    // The underscore fold is a rewrite of somebody's name, so the spacing it
+    // leaves behind is this module's to tidy. Nothing else is collapsed: a double
+    // space in a name nobody folded is what was written.
+    if (scene)
+        text = text.replace(/\s+/g, ' ');
+    return text === '' ? stem : text;
+}

package/dist/db/index.js

@@ -0,0 +1,163 @@
+import { DatabaseSync } from 'node:sqlite';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Access to the meta layer.
+ *
+ * This module is the single seam between the scanner and SQLite: everything
+ * else talks to it through `DatabaseSync`, so swapping the driver (say, to
+ * better-sqlite3) stays a one-file change. We use the built-in `node:sqlite`
+ * because it ships with Node 24 already compiled with FTS5, which keeps the
+ * project dependency-free.
+ */
+const MIGRATIONS_DIR = join(import.meta.dirname, 'migrations');
+export const SCHEMA_VERSION = 38;
+/**
+ * Where the meta layer lives when nobody says otherwise.
+ *
+ * The scanner and the server both open it, so the name is the meta layer's own
+ * and not either command's: a server started with no arguments has to find the
+ * database the scan wrote, or the two halves of the project would need telling
+ * about each other.
+ */
+export const DEFAULT_DB = 'funoteka.db';
+/** Migrations are `NNN_name.sql`; the leading number is the target version. */
+function migrations() {
+    return readdirSync(MIGRATIONS_DIR)
+        .filter((name) => name.endsWith('.sql'))
+        .map((name) => ({ version: Number.parseInt(name.slice(0, 3), 10), path: join(MIGRATIONS_DIR, name) }))
+        .filter((m) => Number.isInteger(m.version))
+        .sort((a, b) => a.version - b.version);
+}
+/**
+ * Bring the database up to `SCHEMA_VERSION`.
+ *
+ * Idempotent by design: every scan opens the database, so running this against
+ * an already-migrated file has to be a no-op rather than an error.
+ */
+export function migrate(db) {
+    let current = db.prepare('PRAGMA user_version').get().user_version;
+    for (const migration of migrations()) {
+        if (migration.version <= current)
+            continue;
+        // `IMMEDIATE`, like every other transaction in this project — the rule is
+        // stated below `withTransaction`, and this one broke it. It was survivable
+        // only by accident: each file here happens to write first (020 opens with a
+        // bare `ANALYZE`), and a deferred transaction whose *first* statement is a
+        // write does ask the busy handler. A later migration that reads before it
+        // writes would have been refused at once instead — and this runs inside
+        // `openDb`, before any caller has had a chance to raise the timeout.
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            db.exec(readFileSync(migration.path, 'utf8'));
+            db.exec(`PRAGMA user_version = ${migration.version}`);
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                // Already unwound; the original error is what matters.
+            }
+            throw err;
+        }
+        current = migration.version;
+    }
+}
+/**
+ * Open the meta layer, creating and migrating it if needed.
+ *
+ * Pass ':memory:' for an ephemeral database (tests). On disk we use WAL so a
+ * scan can write while the API reads.
+ */
+export function openDb(path) {
+    const db = new DatabaseSync(path);
+    // Per-connection, and required for the ON DELETE CASCADE rules to fire.
+    db.exec('PRAGMA foreign_keys = ON');
+    if (path !== ':memory:')
+        db.exec('PRAGMA journal_mode = WAL');
+    // How long a writer waits for the other writer.
+    //
+    // Two things write this file: the scan, which is a process of its own, and the
+    // API, which writes playlists. SQLite's default answer to the second arriving
+    // while the first holds the lock is to give up at once, and "at once" is about
+    // 20 ms: measured on two connections to one file, the save failed with
+    // "database is locked" while the other held the lock.
+    //
+    // **Short, because the wait is served by blocking the thread.** `node:sqlite`
+    // is synchronous, so this sleep is not a sleep this server can take while
+    // answering anybody else: measured with the second writer holding the lock for
+    // seven seconds, a `ping` sent during the wait came back after 5133 ms — the
+    // whole daemon, stopped, for one client's save.
+    //
+    // A quarter of a second is set against how long the scan now holds the lock,
+    // which is no longer a root: `scan.ts` writes in batches and lets go between
+    // them — measured on the live collection, one batch holds the write lock **12
+    // ms at the median and 96 ms at its worst**. So a save that meets a scan waits
+    // out a single batch and gets in, which is what this number was always meant
+    // to buy and could not buy while a scan held the lock for its whole run.
+    //
+    // The scan's own connection is the other half of this, and takes ten seconds
+    // (`cli.ts`): there the wait holds up nobody, because a scan answers nobody.
+    // What is left owed here is the length of the *stages* — `cues` still writes
+    // one transaction of about two seconds, and a save arriving inside it is
+    // refused (task:2880).
+    db.exec('PRAGMA busy_timeout = 250');
+    migrate(db);
+    return db;
+}
+/**
+ * A mutation, as one transaction.
+ *
+ * **Measured, and it is the whole of why this exists.** On a copy of the live
+ * meta layer, a hundred entries written one statement at a time — which is what
+ * SQLite does without a transaction, each commit a write to disk — took
+ * **4452 ms**. The same hundred inside one transaction took **74 ms**, and a
+ * single statement costs about 26 ms on its own. A server that answers every
+ * request in one thread cannot spend four seconds of that on one client's save.
+ *
+ * The figures come from the live database and not from the suite on purpose: on
+ * an empty database a commit costs about nothing, so both forms measure under a
+ * millisecond there and a test cannot see the difference this makes. What it
+ * costs is paid in proportion to a database that exists.
+ *
+ * **`IMMEDIATE`, and the word is load-bearing.** A plain `BEGIN` is deferred:
+ * the transaction takes its read snapshot first and only tries to become a
+ * writer at the first write — and a write that has to *upgrade* a snapshot when
+ * somebody else holds the lock is refused at once, without consulting the busy
+ * handler `PRAGMA busy_timeout` installs. Measured against a second connection
+ * holding the lock: deferred `BEGIN` failed in 2.6–17 ms, while `BEGIN
+ * IMMEDIATE` (which asks for the lock up front, where waiting is allowed) and a
+ * bare `DELETE` both waited as configured. The writers here read before they
+ * write — a counter, a list of entries — so a deferred begin would refuse every
+ * save made while a scan was running, which is the one moment this arrangement
+ * exists for.
+ *
+ * Nested calls join the outer transaction rather than opening a second: SQLite
+ * has no nested `BEGIN`, and a stage that fell over halfway through should leave
+ * nothing of itself behind.
+ */
+export function withTransaction(db, work) {
+    if (db.isTransaction)
+        return work();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = work();
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (err) {
+        // Guarded, and the guard is the point: whatever threw may have unwound the
+        // transaction already (`SQLITE_FULL`, a constraint that aborts), and a
+        // `ROLLBACK` with nothing to roll back throws its own error — which would
+        // replace the reason the caller needs with a complaint about the clean-up.
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            // Already unwound; the original error is what matters.
+        }
+        throw err;
+    }
+}

package/dist/db/issue.js

@@ -0,0 +1,73 @@
+/**
+ * Clear the issues a stage owns, so it can write the current run's.
+ *
+ * A stage that *derives* its rows must call this or it grows without bound:
+ * every reader scopes by run, so an earlier run's rows are read by nobody and
+ * removed by nobody. A collection rescanned daily grew one run's worth per day.
+ *
+ * A stage that records *events* must not. A healed root path and a twin whose
+ * rows were dropped happen once, and an unchanged root raises nothing on the
+ * next run — clearing would not replace those rows with an equal report, it
+ * would delete the only record that the event happened.
+ *
+ * Which of the two a row is decides the scope, and there are three:
+ *
+ *   - the whole stage, for `cues` and `artists`, which walk every root on every
+ *     run and re-derive all of it;
+ *   - one kind, for `scan`, which does both: its root-settlement issues are
+ *     events, while `walk_skipped` is re-read off the filesystem every time —
+ *     the symlink it could not follow is still there next run;
+ *   - one file, for `tags` and `playlists`, which re-read only the files the
+ *     ledger reports changed or never read. Their rows describe the last
+ *     attempt on that file, so the replacement is per file — and a file left
+ *     unstamped on purpose (a permission error is transient, so the next scan
+ *     retries) is reported again each run, which is exactly what a per-file
+ *     clear keeps bounded.
+ */
+/**
+ * Write a stage failure down, and say the run it belongs to is not ok.
+ *
+ * `scan_run.status` is a property of the whole run, and `scan` settles it when
+ * its own walk is done — which is right for the walk and wrong for the run: the
+ * stages after it can throw, and each rolls back only its own transaction, so
+ * the database is left holding some stages and not others under a row that says
+ * `ok`. A reader of that dump sees a healthy run over albums with no tracks, and
+ * cannot tell it from a collection that really is that empty. The status is
+ * settled here instead, and the failure is written down as well as raised:
+ * stderr is gone by the time anyone opens the database.
+ *
+ * `scan` is the other caller, and the reason this cannot simply live in the run:
+ * it throws before its transaction too — a statement that will not compile, a
+ * disk that will not read — and the run row is inserted before that transaction,
+ * so no rollback reaches it. The run id is what `scan` returns, so the caller
+ * cannot file the failure either. Left unwritten, the database says the scan is
+ * still going, indefinitely.
+ *
+ * The row is an *event*, not a derivation — nothing re-reads a stage failure off
+ * the filesystem — so no stage clears it wholesale. It describes one attempt,
+ * and it is scoped to the run that made it, which is what every reader scopes
+ * by. A later run that succeeds supersedes it in the only sense that matters.
+ */
+export function recordStageFailure(db, runId, stage, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    db.prepare(`INSERT INTO issue (scan_run_id, stage, root_id, rel_path, kind, severity, detail)
+     VALUES (?, ?, NULL, NULL, ?, 'warn', ?)`).run(runId, stage, `${stage}-failed`, `${stage} threw: ${message}`);
+    db.prepare('UPDATE scan_run SET status = ? WHERE id = ?').run('failed', runId);
+}
+export function clearIssues(db, stage, scope = {}) {
+    const conditions = ['stage = ?'];
+    const values = [stage];
+    if (scope.kind !== undefined) {
+        conditions.push('kind = ?');
+        values.push(scope.kind);
+    }
+    if (scope.rootId !== undefined) {
+        conditions.push('root_id = ?');
+        values.push(scope.rootId);
+    }
+    if (scope.relPath !== undefined) {
+        conditions.push('rel_path = ?');
+        values.push(scope.relPath);
+    }
+    db.prepare(`DELETE FROM issue WHERE ${conditions.join(' AND ')}`).run(...values);
+}

package/dist/db/ledger.js

@@ -0,0 +1,84 @@
+/**
+ * The ledger: what the last walk observed of each file, and what that is worth.
+ *
+ * `scan_state` is written by the scan and read by stages that own nothing of
+ * it. Tags asks which files need reading, the cue stage whether a stored
+ * measurement is still good, the dump whether a run found anything unmoved —
+ * and each of them used to join the table and decide for itself what `changed`
+ * and the run stamp meant, which made one rule with four copies (task:2683).
+ * The key, the verdict, and the currency of a verdict live here; a reader asks
+ * for the fragment it needs by the alias it gave the ledger.
+ *
+ * The sweep of the same table is the other reading of the same stamp, and lives
+ * in `sweep.ts`: this module asks what a row says about a file that is still
+ * there, that one asks what to do with a row whose file is not.
+ */
+/**
+ * Join a file to the ledger entry describing it.
+ *
+ * A file and its entry are keyed alike — the root and the relative path — and
+ * that pair is the whole of the relationship, so it is written once and asked
+ * for by alias. Whether the caller writes `JOIN` or `LEFT JOIN` stays the
+ * caller's business: a file the walk has not seen twice has no entry at all,
+ * and whether that disqualifies it depends on the question being asked.
+ */
+export function ledgerEntry(file, ledger) {
+    return `${ledger}.root_id = ${file}.root_id AND ${ledger}.rel_path = ${file}.rel_path`;
+}
+/**
+ * The recorded verdict that the filesystem reported the file exactly as the
+ * previous observation left it.
+ *
+ * Read, never recomputed. The comparison against the filesystem happened once,
+ * in the walk, where the size and the mtime were already in hand — `movedSince`
+ * is that comparison, and a reader that made it again would be stat-ing a file
+ * the walk has just walked. False for a file with no entry: nothing was
+ * observed, so nothing is known to be unchanged.
+ */
+export function unmoved(ledger) {
+    return `${ledger}.changed = 0`;
+}
+/** The recorded verdict that the file moved since the previous observation. */
+export function moved(ledger) {
+    return `${ledger}.changed = 1`;
+}
+/**
+ * The currency of a verdict: the entry was written by the run that last walked
+ * this file's root.
+ *
+ * A verdict is only worth anything while the run that wrote it is the run that
+ * last walked *that root*: naming one root in an invocation says nothing about
+ * another, and a verdict from a run that never saw the file would be worse than
+ * none. Asking for this is the caller's call — a stored whole-file duration is
+ * forgiven a stale verdict, the closing bound of a cue split is not.
+ */
+export function current(ledger) {
+    const earlier = `earlier_${ledger}`;
+    return (`${ledger}.last_seen_run_id = ` +
+        `(SELECT MAX(${earlier}.last_seen_run_id) FROM scan_state ${earlier} ` +
+        `WHERE ${earlier}.root_id = ${ledger}.root_id)`);
+}
+/**
+ * Did the file move since the ledger recorded it?
+ *
+ * The comparison behind `changed`, and the only place it is made. It is then
+ * *stored* rather than left to readers, because the walk has already read the
+ * filesystem's answer and every later stage would have to read it again to
+ * reach the same verdict — which is the whole cost the ledger exists to avoid.
+ * A file the ledger holds no observation of has moved as far as anyone knows.
+ */
+export function movedSince(previous, observed) {
+    return previous === undefined || previous.size !== observed.size || previous.mtime_ms !== observed.mtimeMs;
+}
+/**
+ * How many files the given run found exactly as the previous one left them.
+ *
+ * Scoped by the run named, not by the root: this answers "what did this run
+ * report", which is what a dump of that run is about.
+ */
+export function unchangedCount(db, runId) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM scan_state WHERE last_seen_run_id = ? AND ${unmoved('scan_state')}`)
+        .get(runId);
+    return row.n;
+}

package/dist/db/migrations/001_init.sql

@@ -0,0 +1,196 @@
+-- Meta layer (v1) — the classified model the API will read from.
+--
+-- Two rules shape this schema and both come straight from the contract
+-- (requirements:39):
+--
+--   1. Album identity is the PATH (root-qualified). Nothing is ever merged by
+--      tags or content, so pressings of the same album, or a copy of one album
+--      sitting in two roots, are distinct rows.
+--   2. The filesystem is raw truth. Every row here is derived from it, and the
+--      collection files themselves are never mutated — this layer is an overlay.
+
+-- Scan bookkeeping -----------------------------------------------------------
+
+CREATE TABLE scan_run (
+  id          INTEGER PRIMARY KEY,
+  started_at  TEXT    NOT NULL,
+  finished_at TEXT,
+  status      TEXT    NOT NULL,          -- running | ok | failed
+  roots_json  TEXT    NOT NULL           -- JSON array of the configured root paths
+);
+
+-- Sources --------------------------------------------------------------------
+
+CREATE TABLE root (
+  id         INTEGER PRIMARY KEY,
+  path       TEXT    NOT NULL UNIQUE,    -- absolute, as configured by the user
+  alias      TEXT,
+  created_at TEXT    NOT NULL
+);
+
+-- Folders, with the classification role the classifier assigns (album /
+-- category / box / disc). NULL until the classifier has run over this folder.
+CREATE TABLE folder (
+  id              INTEGER PRIMARY KEY,
+  root_id         INTEGER NOT NULL REFERENCES root(id) ON DELETE CASCADE,
+  rel_path        TEXT    NOT NULL,      -- '' is the root itself
+  parent_rel_path TEXT,
+  role            TEXT,
+  UNIQUE (root_id, rel_path)
+);
+
+-- Every file met on disk. Audio files are the primary truth; the rest are
+-- sidecars (cue/nfo/log), artwork, playlists, or noise.
+CREATE TABLE file (
+  id                INTEGER PRIMARY KEY,
+  root_id           INTEGER NOT NULL REFERENCES root(id) ON DELETE CASCADE,
+  rel_path          TEXT    NOT NULL,
+  folder_rel_path   TEXT    NOT NULL,
+  name              TEXT    NOT NULL,
+  kind              TEXT    NOT NULL,    -- audio | cue | image | nfo | log | playlist | other
+  ext               TEXT    NOT NULL,
+  size              INTEGER NOT NULL,
+  mtime_ms          INTEGER NOT NULL,
+  first_seen_run_id INTEGER REFERENCES scan_run(id),
+  last_seen_run_id  INTEGER REFERENCES scan_run(id),
+  UNIQUE (root_id, rel_path)
+);
+
+CREATE INDEX idx_file_kind ON file (root_id, kind);
+CREATE INDEX idx_file_folder ON file (root_id, folder_rel_path);
+
+-- ffprobe results. `probe_ok = 0` with a `probe_err` is a legitimate state:
+-- ffprobe is optional, and a missing probe must degrade, not abort the scan.
+CREATE TABLE audio_probe (
+  file_id     INTEGER PRIMARY KEY REFERENCES file(id) ON DELETE CASCADE,
+  duration_ms INTEGER,
+  codec       TEXT,
+  sample_rate INTEGER,
+  channels    INTEGER,
+  bitrate     INTEGER,
+  probe_ok    INTEGER NOT NULL DEFAULT 0,
+  probe_err   TEXT
+);
+
+-- Artists. `name_key` is the normalised merge key (Cure / The Cure / Cure, The
+-- collapse to one). It stays UNIQUE, so one row still cannot be two artists at
+-- once — but a homonym no longer has to share a key: the second artist folder to
+-- claim a name gets `nirvana#2`, which cannot collide with a bare key because a
+-- key carrying `#` has no letter or digit in it (`qualifiedKey`, src/artist).
+--
+-- `ambiguous = 1` therefore records that a row's identity is a *guess*, whichever
+-- way it was reached: a key that merged spellings which fold differently, or a
+-- key split apart because two artist folders both claimed it ("разные арт-папки
+-- = разные артисты", wiki:3498 §3). An artist that won its name outright is the
+-- only kind left unflagged; `artist-homonym` issues name what a split threw
+-- together, and `ambiguous` alone never says which of the two happened.
+CREATE TABLE artist (
+  id        INTEGER PRIMARY KEY,
+  name      TEXT    NOT NULL,
+  name_key  TEXT    NOT NULL UNIQUE,
+  sort_key  TEXT,
+  ambiguous INTEGER NOT NULL DEFAULT 0
+);
+
+-- A box set: one release spanning several discs, which also projects each disc
+-- as its own album row. Discs show up two ways — as CD subfolders, or, when the
+-- rip is flat, as one image+cue pair per disc.
+CREATE TABLE release (
+  id        INTEGER PRIMARY KEY,
+  root_id   INTEGER NOT NULL REFERENCES root(id) ON DELETE CASCADE,
+  rel_path  TEXT    NOT NULL,
+  title     TEXT,
+  artist_id INTEGER REFERENCES artist(id),
+  UNIQUE (root_id, rel_path)
+);
+
+CREATE TABLE album (
+  id         INTEGER PRIMARY KEY,
+  root_id    INTEGER NOT NULL REFERENCES root(id) ON DELETE CASCADE,
+  rel_path   TEXT    NOT NULL,           -- identity — see rule 1 above
+  title      TEXT,
+  artist_id  INTEGER REFERENCES artist(id),
+  release_id INTEGER REFERENCES release(id),
+  disc_number INTEGER,
+  UNIQUE (root_id, rel_path)
+);
+
+CREATE INDEX idx_album_release ON album (release_id);
+
+-- Cue documents. `audio_file_id` is resolved by matching the audio files that
+-- are actually present, NOT by the cue's FILE tag — real rips carry a stale tag
+-- (a .m4a declared as WAVE). NULL means no audio in the folder matched.
+CREATE TABLE cue (
+  id                  INTEGER PRIMARY KEY,
+  file_id             INTEGER NOT NULL UNIQUE REFERENCES file(id) ON DELETE CASCADE,
+  encoding            TEXT,
+  encoding_confidence REAL,
+  audio_file_id       INTEGER REFERENCES file(id)
+);
+
+-- Raw cue TRACK entries, in file order. Times are milliseconds; `index00_ms` is
+-- the pregap and may legitimately be absent.
+CREATE TABLE cue_track (
+  id          INTEGER PRIMARY KEY,
+  cue_id      INTEGER NOT NULL REFERENCES cue(id) ON DELETE CASCADE,
+  ordinal     INTEGER NOT NULL,
+  title       TEXT,
+  performer   TEXT,
+  index00_ms  INTEGER,
+  index01_ms  INTEGER NOT NULL,
+  UNIQUE (cue_id, ordinal)
+);
+
+-- Playable units. A whole-file track leaves the segment NULL; a cue-split track
+-- points at the image file and carries a time segment. Note that the *last*
+-- split track has no following index to bound it — its end comes from the audio
+-- file's real duration, which is why audio_probe exists.
+CREATE TABLE track (
+  id               INTEGER PRIMARY KEY,
+  album_id         INTEGER REFERENCES album(id) ON DELETE CASCADE,
+  artist_id        INTEGER REFERENCES artist(id),
+  ordinal          INTEGER NOT NULL,
+  title            TEXT,
+  file_id          INTEGER NOT NULL REFERENCES file(id),
+  segment_start_ms INTEGER,
+  segment_end_ms   INTEGER,
+  duration_ms      INTEGER,
+  UNIQUE (album_id, ordinal)
+);
+
+CREATE INDEX idx_track_file ON track (file_id);
+
+-- Incremental rescan bookkeeping: a file whose size and mtime are unchanged is
+-- not re-read.
+CREATE TABLE scan_state (
+  root_id          INTEGER NOT NULL REFERENCES root(id) ON DELETE CASCADE,
+  rel_path         TEXT    NOT NULL,
+  size             INTEGER NOT NULL,
+  mtime_ms         INTEGER NOT NULL,
+  last_seen_run_id INTEGER NOT NULL REFERENCES scan_run(id),
+  PRIMARY KEY (root_id, rel_path)
+);
+
+-- "What the scanner did not understand." Every guess, skip and unmatched cue
+-- lands here so a scan can never lose information silently.
+CREATE TABLE issue (
+  id          INTEGER PRIMARY KEY,
+  scan_run_id INTEGER REFERENCES scan_run(id) ON DELETE CASCADE,
+  root_id     INTEGER REFERENCES root(id),
+  rel_path    TEXT,
+  kind        TEXT    NOT NULL,
+  severity    TEXT    NOT NULL DEFAULT 'warn',
+  detail      TEXT
+);
+
+CREATE INDEX idx_issue_run ON issue (scan_run_id, kind);
+
+-- Search layer (spec §2) ----------------------------------------------------
+-- Populated by a later stage; declared here so the meta layer is complete.
+
+CREATE VIRTUAL TABLE track_fts USING fts5 (
+  title,
+  artist,
+  album,
+  tokenize = 'unicode61 remove_diacritics 2'
+);

package/dist/db/migrations/002_cue_track_flexible.sql

@@ -0,0 +1,35 @@
+-- Two things a cue sheet can legally do, neither of which the first schema
+-- could store. Both crashed a scan outright rather than being reported.
+--
+--   1. Declare a TRACK with no INDEX 01. The parser reports this honestly as a
+--      null index, and the planner already flags it — but `index01_ms` was
+--      NOT NULL, so the insert threw and took the whole run down with it.
+--
+--   2. Span several files, restarting TRACK numbering at each FILE. The matrix
+--      calls this out explicitly ("FILE CD1.flac" + "FILE CD2.flac") and the
+--      parser records the file index, but the old UNIQUE (cue_id, ordinal)
+--      saw the second FILE's TRACK 01 as a duplicate and threw.
+--
+-- SQLite cannot alter a constraint, so the table is rebuilt.
+
+CREATE TABLE cue_track_new (
+  id          INTEGER PRIMARY KEY,
+  cue_id      INTEGER NOT NULL REFERENCES cue(id) ON DELETE CASCADE,
+  -- Which FILE of the cue this track belongs to; 0 for the common single-file
+  -- case, so numbering restarts legitimately per file.
+  file_index  INTEGER NOT NULL DEFAULT 0,
+  ordinal     INTEGER NOT NULL,
+  title       TEXT,
+  performer   TEXT,
+  index00_ms  INTEGER,
+  -- Nullable: a declared track may have no index. Callers report it.
+  index01_ms  INTEGER,
+  UNIQUE (cue_id, file_index, ordinal)
+);
+
+INSERT INTO cue_track_new (id, cue_id, file_index, ordinal, title, performer, index00_ms, index01_ms)
+  SELECT id, cue_id, 0, ordinal, title, performer, index00_ms, index01_ms FROM cue_track;
+
+DROP TABLE cue_track;
+
+ALTER TABLE cue_track_new RENAME TO cue_track;