funoteka 0.1.0

package/dist/history/store.js

@@ -0,0 +1,151 @@
+import { withTransaction } from "../db/index.js";
+/**
+ * What the listener did: plays that happened, what is on now, and the queue they
+ * left behind.
+ *
+ * The third part of the listener's own layer — playlists are what they arranged,
+ * stars are what they thought — and the same rule holds: nothing on disk states
+ * any of it, so no scan writes here, and what a scan takes away goes through the
+ * cascade (`030_history.sql`).
+ *
+ * The five tables are the protocol's own split and not an accident of storage:
+ * a **play** is history and the row is the only record it happened; **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, which is
+ * why `getPlayQueue` takes no player at all; the queue's entries are their own
+ * table beside it; and **player** is the row that turns a client's own name into
+ * the integer the protocol asks for.
+ */
+/**
+ * The row for a client, by the name it gave.
+ *
+ * The protocol requires a `playerId` — an integer — on every now-playing entry
+ * and no endpoint accepts one, so the server derives it. A client names itself
+ * with the protocol's `c` parameter; this turns that name into the row the
+ * integer is, and finds it again on the next call.
+ */
+export function player(db, name) {
+    const found = db.prepare('SELECT id FROM player WHERE name = ?').get(name);
+    if (found !== undefined)
+        return found.id;
+    const inserted = db.prepare('INSERT INTO player (name) VALUES (?)').run(name);
+    return Number(inserted.lastInsertRowid);
+}
+/**
+ * That a track was played, in the history and in the rollup.
+ *
+ * Both, because they answer different questions and neither can answer the
+ * other's: `play` is what happened (which track, which client, when) and
+ * `track_play` is what the protocol *shows* — `playCount` and `played` are
+ * fields on every `Child`, and a field on every Child cannot be an aggregate
+ * over a listing (`031_queue_position_and_plays.sql`).
+ *
+ * One transaction around the pair, so the history and the rollup cannot
+ * disagree: a scrobble that wrote one and not the other would leave a count that
+ * does not match the rows behind it.
+ */
+export function recordPlay(db, playerId, played) {
+    withTransaction(db, () => {
+        const insert = db.prepare('INSERT INTO play (track_id, player_id, played_at) VALUES (?, ?, ?)');
+        const roll = db.prepare(`INSERT INTO track_play (track_id, play_count, played_at) VALUES (?, 1, ?)
+       ON CONFLICT (track_id) DO UPDATE SET
+         play_count = track_play.play_count + 1,
+         played_at  = excluded.played_at`);
+        // Each play carries its own time: the protocol pairs `time` with `id` one
+        // for one, so a client uploading a day of offline listening dates each of
+        // them separately and they must not all be stamped now.
+        for (const play of played) {
+            insert.run(play.trackId, playerId, play.at);
+            roll.run(play.trackId, play.at);
+        }
+    });
+}
+/**
+ * What a player is on, and how far in.
+ *
+ * One row per player, replaced rather than accumulated: the protocol's question
+ * is what is playing *now*, and a table that kept every track a client had
+ * opened would be a history with a different name.
+ *
+ * The three fields beside the track come from `reportPlayback` and are all the
+ * server's to remember — the client is told them back by a *different* client
+ * through `getNowPlaying`, which is the whole reason they are stored rather than
+ * answered from the request.
+ */
+export function markPlaying(db, playerId, trackId, at, details = {}) {
+    db.prepare(`INSERT INTO now_playing (player_id, track_id, updated_at, state, position_ms, playback_rate)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT (player_id) DO UPDATE SET
+       track_id      = excluded.track_id,
+       updated_at    = excluded.updated_at,
+       state         = excluded.state,
+       position_ms   = excluded.position_ms,
+       playback_rate = excluded.playback_rate`).run(playerId, trackId, at, details.state ?? null, details.positionMs ?? null, details.playbackRate ?? null);
+}
+/**
+ * What every player is on, most recently updated first.
+ *
+ * A row whose track is gone is gone with it — the cascade — so nothing here has
+ * to be filtered: what comes back is a list of tracks that are still in the
+ * collection.
+ */
+export function nowPlaying(db) {
+    return db
+        .prepare(`SELECT np.player_id     AS playerId,
+              p.name           AS playerName,
+              np.track_id      AS trackId,
+              np.updated_at    AS updatedAt,
+              np.state         AS state,
+              np.position_ms   AS positionMs,
+              np.playback_rate AS playbackRate
+         FROM now_playing np
+         JOIN player p ON p.id = np.player_id
+        ORDER BY np.updated_at DESC, np.player_id`)
+        .all();
+}
+/**
+ * The queue, seat by seat.
+ *
+ * The seats are returned with their numbers rather than as a bare list, because
+ * the current track is stored as one of those numbers and a caller has to be
+ * able to find it. Reading the list and indexing it would work until a deletion
+ * ahead of the current seat moved everything after it — which is what happened
+ * (task:2863).
+ */
+export function queue(db) {
+    const row = db
+        .prepare(`SELECT current_position AS currentPosition, position_ms AS positionMs,
+              changed_at AS changedAt, changed_by AS changedBy
+         FROM play_queue WHERE only_row = 1`)
+        .get();
+    if (row === undefined)
+        return null;
+    const entries = db
+        .prepare('SELECT position, track_id AS trackId FROM play_queue_entry ORDER BY position')
+        .all();
+    return { ...row, entries };
+}
+/**
+ * Replace the queue, whole.
+ *
+ * Every save lays the positions out from zero again, the rule every other
+ * ordered write in this project follows: a queue is addressed by index, so a
+ * save that appended would leave the numbers meaning something the client did
+ * not send. An empty list is a queue with nothing in it — how a client says
+ * "forget this" — and it is saved rather than deleted, so `changedBy` still says
+ * who did it.
+ */
+export function saveQueue(db, input, at) {
+    withTransaction(db, () => {
+        db.prepare('DELETE FROM play_queue_entry').run();
+        const insert = db.prepare('INSERT INTO play_queue_entry (position, track_id) VALUES (?, ?)');
+        input.trackIds.forEach((trackId, position) => insert.run(position, trackId));
+        db.prepare(`INSERT INTO play_queue (only_row, current_position, position_ms, changed_at, changed_by)
+       VALUES (1, ?, ?, ?, ?)
+       ON CONFLICT (only_row) DO UPDATE SET
+         current_position = excluded.current_position,
+         position_ms      = excluded.position_ms,
+         changed_at       = excluded.changed_at,
+         changed_by       = excluded.changed_by`).run(input.currentPosition, input.positionMs, at, input.changedBy);
+    });
+}

package/dist/inventory/inventory.js

@@ -0,0 +1,294 @@
+import { unchangedCount } from "../db/ledger.js";
+import { hidden } from "../junk/marks.js";
+/**
+ * Render the classified collection as a document a human reads.
+ *
+ * This is the acceptance instrument (requirements:39 §9): every check v1 is
+ * judged by — pressings staying separate albums, a box reading as one release
+ * with its discs, the same album in two roots staying two, a cue album listing
+ * N tracks rather than one, Cyrillic surviving the trip, and the counters
+ * adding up — has to be visible here, or it is not checkable by the person the
+ * contract answers to.
+ *
+ * Read-only, and deterministic by construction: same database, same bytes.
+ * Two dumps of an untouched collection differ only in the lines naming the run
+ * they describe, which is what makes "the rescan changed nothing" something one
+ * looks at rather than something one believes. The ledger line says how much of
+ * the collection the last walk found unmoved, so that claim is legible from the
+ * dump alone.
+ *
+ * The machine-readable form remains the database itself.
+ */
+/** Minutes and seconds, or an explicit dash when nothing measured it. */
+function duration(ms) {
+    if (ms === null || ms < 0)
+        return '--:--';
+    const total = Math.round(ms / 1000);
+    const seconds = total % 60;
+    const minutes = Math.floor(total / 60) % 60;
+    const hours = Math.floor(total / 3600);
+    const tail = `${minutes}:${String(seconds).padStart(2, '0')}`;
+    return hours > 0
+        ? `${hours}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`
+        : tail;
+}
+/** `label total  (key n, key n)`, omitting the keys that are zero. */
+function breakdown(total, label, counts = {}) {
+    const parts = Object.entries(counts)
+        .filter(([, n]) => n > 0)
+        .map(([key, n]) => `${key} ${n}`);
+    return `  ${label.padEnd(9)}${String(total).padEnd(7)}${parts.length === 0 ? '' : `(${parts.join(', ')})`}`;
+}
+function tally(rows) {
+    return Object.fromEntries(rows.map((row) => [row.key ?? 'none', row.n]));
+}
+function count(db, sql, ...args) {
+    return db.prepare(sql).get(...args).n;
+}
+/**
+ * Every row of an album-keyed query, gathered under its album.
+ *
+ * **One query for the collection rather than one per album.** Three of the things
+ * the dump asks for are per-album reads, and asking them inside the loop below
+ * is what made `GET /inventory` cost **233.9 ms** on a 472-album collection: 1416
+ * statement executions, three for every album. Grouped here, the same three
+ * queries are executed three times in all.
+ *
+ * The order inside a group is the order the query was written with, which is
+ * what keeps the dump byte-identical — the promise this file opens with.
+ */
+function byAlbum(rows) {
+    const out = new Map();
+    for (const row of rows) {
+        const list = out.get(row.albumId);
+        if (list === undefined)
+            out.set(row.albumId, [row]);
+        else
+            list.push(row);
+    }
+    return out;
+}
+export function inventory(db, options = {}) {
+    const lines = [];
+    const where = options.dbPath === undefined ? '' : ` — ${options.dbPath}`;
+    lines.push(`funoteka inventory${where}`);
+    const run = db
+        .prepare('SELECT id, status, started_at FROM scan_run ORDER BY id DESC LIMIT 1')
+        .get();
+    if (run === undefined) {
+        lines.push('', 'No scan has run against this database.', '');
+        return lines.join('\n');
+    }
+    lines.push(`run ${run.id} · ${run.status} · ${run.started_at}`, '');
+    const roots = db.prepare('SELECT id, path FROM root ORDER BY id').all();
+    // Albums carry the root they belong to, and identity is root-qualified, so a
+    // short marker is what lets two roots hold the same relative path and stay
+    // legibly two albums.
+    const marks = new Map(roots.map((root, index) => [root.id, `#${index + 1}`]));
+    const perRoot = (sql) => new Map(db.prepare(sql).all().map((row) => [row.root_id, row.n]));
+    const foldersByRoot = perRoot('SELECT root_id, COUNT(*) AS n FROM folder GROUP BY root_id');
+    const filesByRoot = perRoot('SELECT root_id, COUNT(*) AS n FROM file GROUP BY root_id');
+    const albumsByRoot = perRoot('SELECT root_id, COUNT(*) AS n FROM album GROUP BY root_id');
+    lines.push('roots');
+    for (const root of roots) {
+        lines.push(`  ${(marks.get(root.id) ?? '?').padEnd(4)}${root.path}`, `      folders ${foldersByRoot.get(root.id) ?? 0}   files ${filesByRoot.get(root.id) ?? 0}   albums ${albumsByRoot.get(root.id) ?? 0}`);
+    }
+    const fileTotal = count(db, 'SELECT COUNT(*) AS n FROM file');
+    const unmoved = unchangedCount(db, run.id);
+    lines.push('', 'counters');
+    lines.push(breakdown(count(db, 'SELECT COUNT(*) AS n FROM folder'), 'folders', tally(db.prepare('SELECT role AS key, COUNT(*) AS n FROM folder GROUP BY role').all())));
+    lines.push(breakdown(fileTotal, 'files', tally(db.prepare('SELECT kind AS key, COUNT(*) AS n FROM file GROUP BY kind').all())));
+    // `scanned = visible + hidden`, stated here because the dump is where the
+    // contract promised it would be (Q14, brainstorm:190) and because a filter
+    // nobody can see the size of is a filter nobody can check. What is hidden is
+    // named below the counters, with its reason — a count alone cannot tell a rule
+    // that overreached from a folder somebody marked.
+    const hiddenAlbums = hidden(db);
+    lines.push(breakdown(count(db, 'SELECT COUNT(*) AS n FROM album'), 'albums', {
+        hidden: hiddenAlbums.length,
+    }));
+    lines.push(breakdown(count(db, 'SELECT COUNT(*) AS n FROM track'), 'tracks'));
+    lines.push(breakdown(count(db, 'SELECT COUNT(*) AS n FROM release'), 'releases'));
+    lines.push(breakdown(count(db, 'SELECT COUNT(*) AS n FROM artist'), 'artists', {
+        ambiguous: count(db, 'SELECT COUNT(*) AS n FROM artist WHERE ambiguous = 1'),
+    }));
+    lines.push(breakdown(count(db, 'SELECT COUNT(*) AS n FROM issue WHERE scan_run_id = ?', run.id), 'issues', tally(db
+        .prepare('SELECT severity AS key, COUNT(*) AS n FROM issue WHERE scan_run_id = ? GROUP BY severity')
+        .all(run.id))));
+    // What the last walk found unmoved. Without it the dump cannot say whether a
+    // rescan did anything, which is half of what it is for.
+    lines.push(`  ${'ledger'.padEnd(9)}${unmoved} of ${fileTotal} files unmoved since the last walk`);
+    // "No silent loss", stated as the things that must be zero. An audio file is
+    // accounted for when the meta layer can name it: a whole-file track points at
+    // it, or it is the image a cue splits.
+    lines.push('', 'unaccounted');
+    const unaccounted = [
+        ['folders with no role', count(db, 'SELECT COUNT(*) AS n FROM folder WHERE role IS NULL')],
+        [
+            'albums with no track',
+            count(db, 'SELECT COUNT(*) AS n FROM album a WHERE NOT EXISTS (SELECT 1 FROM track t WHERE t.album_id = a.id)'),
+        ],
+        [
+            'audio files with no track or cue',
+            count(db, `SELECT COUNT(*) AS n FROM file f
+          WHERE f.kind = 'audio'
+            AND NOT EXISTS (SELECT 1 FROM track t WHERE t.file_id = f.id)
+            AND NOT EXISTS (SELECT 1 FROM cue c WHERE c.audio_file_id = f.id)`),
+        ],
+    ];
+    for (const [label, n] of unaccounted)
+        lines.push(`  ${label.padEnd(34)}${n}`);
+    // What the filter keeps out, by name. Printed before the collection rather
+    // than after, because it is the one part of the dump that is an *absence*:
+    // everything below is what is there, and a reader who does not see this
+    // section cannot tell a hidden folder from a folder that never existed.
+    lines.push('', `hidden (${hiddenAlbums.length})`);
+    if (hiddenAlbums.length === 0) {
+        lines.push('  none');
+    }
+    for (const row of hiddenAlbums) {
+        const where = row.relPath === '' ? '(the root itself)' : row.relPath;
+        lines.push(`  ${(row.source === 'hand' ? 'hand' : 'scan').padEnd(6)}${(marks.get(row.rootId) ?? '?').padEnd(4)}${where.padEnd(44)}${row.title ?? ''}  —  ${row.junkReason}`);
+    }
+    const albums = db
+        .prepare(`SELECT a.id AS id, a.root_id AS root_id, a.rel_path AS rel_path, a.title AS title,
+              a.disc_number AS disc_number, rel.title AS release_title,
+              a.credit_raw AS credit_raw,
+              a.artist_id AS artist_id, ar.name AS artist_name, ar.name_key AS artist_key
+         FROM album a
+         LEFT JOIN artist ar ON ar.id = a.artist_id
+         LEFT JOIN release rel ON rel.id = a.release_id
+        ORDER BY (ar.name_key IS NULL), ar.name_key, a.root_id, a.rel_path`)
+        .all();
+    // Counted once rather than rescanning the album list per artist, and counted
+    // by id rather than by name: two artists can share a name — that is the whole
+    // point of the folder split — and counting by name would show them as one
+    // artist owning both, hiding the split exactly where a human looks for it.
+    const ownedByArtist = new Map();
+    for (const album of albums) {
+        ownedByArtist.set(album.artist_id, (ownedByArtist.get(album.artist_id) ?? 0) + 1);
+    }
+    // Only ever read to show a credit that is more than one name: a single name
+    // is already on the album's line, and repeating it would be noise on every
+    // one of the collection's albums.
+    const creditOf = byAlbum(db
+        .prepare(`SELECT ac.album_id AS albumId, ar.name AS name, ac.join_phrase AS join_phrase
+           FROM artist_credit ac JOIN artist ar ON ar.id = ac.artist_id
+          ORDER BY ac.album_id, ac.position`)
+        .all());
+    // A track's credit, resolved to the rows the artist stage made of it. Written
+    // only where the track says something the record does not — see that stage —
+    // so a track with no row here is one whose record already speaks for it.
+    const trackCreditOf = byAlbum(db
+        .prepare(`SELECT t.album_id AS albumId, tc.track_id AS track_id, ar.name AS name,
+                tc.join_phrase AS join_phrase
+           FROM track_credit tc
+           JOIN track t ON t.id = tc.track_id
+           JOIN artist ar ON ar.id = tc.artist_id
+          ORDER BY t.album_id, tc.track_id, tc.position`)
+        .all());
+    // A track's own PERFORMER, reached through the cue bound to the file it plays
+    // from. That binding is the one `applyCues` settled: a second cue naming the
+    // same audio is diagnosed and left unbound (`cue-unmatched`), so there is one
+    // answer here rather than a choice between documents.
+    //
+    // The raw string and not an artist: `artist/apply.ts` argues why
+    // `track.artist_id` stays empty, and what a reader needs to see is that the
+    // parser did not drop what the cue said. A compilation is where that matters
+    // — the record is credited `Various Artists`, which is true of the record and
+    // false of every track on it (task:2727 §6).
+    const tracksOf = byAlbum(db
+        .prepare(`SELECT t.album_id AS albumId, t.id AS id, t.ordinal AS ordinal, t.title AS title,
+                t.segment_start_ms AS start_ms, t.segment_end_ms AS end_ms,
+                t.duration_ms AS duration_ms, f.rel_path AS file_rel_path,
+                (SELECT ct.performer
+                   FROM cue c JOIN cue_track ct ON ct.cue_id = c.id
+                  WHERE c.audio_file_id = t.file_id AND ct.ordinal = t.ordinal
+                  ORDER BY c.id LIMIT 1) AS performer
+           FROM track t JOIN file f ON f.id = t.file_id
+          ORDER BY t.album_id, t.ordinal`)
+        .all());
+    lines.push('', 'artists');
+    let currentArtist;
+    for (const album of albums) {
+        if (album.artist_id !== currentArtist) {
+            currentArtist = album.artist_id;
+            const owned = ownedByArtist.get(currentArtist) ?? 0;
+            // A suffixed key is the one mark that tells two same-named artists apart,
+            // and the dump shows only the display name — so without this a split
+            // prints as two identical blocks and the reader cannot tell which is
+            // which. The key is noise for every artist that won its name outright,
+            // so it is shown only when it carries the split's `#`.
+            const key = album.artist_key;
+            const mark = key === null || !key.includes('#') ? '' : `  [${key}]`;
+            lines.push('', `  ${(album.artist_name ?? '(unattributed)').padEnd(40)}  ${owned} album${owned === 1 ? '' : 's'}${mark}`);
+        }
+        const tracks = tracksOf.get(album.id) ?? [];
+        const split = tracks.some((track) => track.start_ms !== null);
+        const label = album.rel_path === '' ? '(the root itself)' : album.rel_path;
+        const disc = album.disc_number === null ? '' : `  disc ${album.disc_number}`;
+        const box = album.release_title === null ? '' : ` of ${album.release_title}`;
+        // What varies in length — the path, the title, the release — goes last.
+        // Padded columns read better until a name outgrows them, at which point
+        // they run into the next column and the dump stops being readable exactly
+        // where the interesting records are.
+        const facts = `${tracks.length} track${tracks.length === 1 ? '' : 's'}${split ? '  split' : ''}${disc}${box}`;
+        lines.push(`    ${(marks.get(album.root_id) ?? '?').padEnd(4)}${facts.padEnd(30)}  ·  ${label}  —  ${album.title ?? ''}`);
+        const credit = creditOf.get(album.id) ?? [];
+        if (credit.length > 1) {
+            // Rebuilt from the parts rather than echoed from `credit_raw`, so what is
+            // printed proves the list and its phrases really do reassemble.
+            const rebuilt = credit.map((entry) => entry.join_phrase + entry.name).join('');
+            lines.push(`        credit  ${rebuilt}`);
+        }
+        // The tracks whose credit is not the record's, resolved to people. A track
+        // line that showed the cue's own string would be showing a string where the
+        // meta layer holds an identity — and where the stage declined to resolve one
+        // (the 120 names only a track states), the string is what is left and is
+        // shown instead, so a refusal is visible rather than an empty column
+        // (task:2729).
+        const trackCredits = new Map();
+        for (const row of trackCreditOf.get(album.id) ?? []) {
+            const soFar = trackCredits.get(row.track_id) ?? '';
+            trackCredits.set(row.track_id, soFar + row.join_phrase + row.name);
+        }
+        for (const track of tracks) {
+            const segment = track.start_ms === null ? '' : `  [${duration(track.start_ms)}–${duration(track.end_ms)}]`;
+            // Only where the track says something the record does not. Eleven of the
+            // sample's albums state one performer and it is the record's own; printing
+            // it on every line is the repetition the credit has already refused to
+            // make, and it would bury the tracks that do differ — a compilation's
+            // every track, a live disc's `Публика` — in a column of the same name.
+            //
+            // The resolved credit is what is shown when there is one, because that is
+            // what the meta layer holds: a row in `artist`, which search and the tree
+            // can follow. The cue's own string is the fallback — a name the stage
+            // declined to resolve, or one it refused as a note about the room — and it
+            // is shown rather than dropped so the refusal is visible here too.
+            const credit = trackCredits.get(track.id);
+            const performer = credit !== undefined
+                ? `  ·  ${credit}`
+                : track.performer !== null &&
+                    track.performer.trim() !== '' &&
+                    track.performer !== album.credit_raw
+                    ? `  ·  ${track.performer}`
+                    : '';
+            lines.push(`        ${`${String(track.ordinal).padStart(2, '0')}.`.padEnd(5)}${duration(track.duration_ms).padEnd(7)}` +
+                `·  ${track.title ?? '(untitled)'}  ·  ${track.file_rel_path}${segment}${performer}`);
+        }
+    }
+    const issues = db
+        .prepare(`SELECT kind, severity, rel_path, root_id, detail FROM issue
+        WHERE scan_run_id = ?
+        ORDER BY severity DESC, kind, root_id, rel_path`)
+        .all(run.id);
+    lines.push('', `issues (run ${run.id})`);
+    if (issues.length === 0)
+        lines.push('  none');
+    for (const issue of issues) {
+        const mark = issue.root_id === null ? '' : (marks.get(issue.root_id) ?? '');
+        lines.push(`  ${issue.severity.padEnd(6)}${issue.kind.padEnd(24)}${mark.padEnd(4)}${(issue.rel_path ?? '').padEnd(40)}${issue.detail ?? ''}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/junk/marks.js

@@ -0,0 +1,143 @@
+import { withTransaction } from "../db/index.js";
+import { junkReason } from "./rule.js";
+/**
+ * A filesystem path, as the root and relative path the meta layer keys on.
+ *
+ * The operator names a folder the way the disk does — `D:\music\Telegram
+ * Desktop` — and identity here is `(root, rel_path)`. Resolution is by the
+ * deepest root that contains the path, so a root inside another root still
+ * answers about itself, and the comparison is on separators normalised to `/`
+ * because that is what `scan/walk.ts` writes.
+ *
+ * Nothing is resolved by guessing: a path under no root is not an error about
+ * the collection, it is a path this server has never heard of, and the caller is
+ * told so by `undefined` rather than by a mark on something else.
+ */
+export function resolvePath(db, path) {
+    const normal = path.replace(/\\/g, '/').replace(/\/+$/, '');
+    const roots = db.prepare('SELECT id, path FROM root ORDER BY LENGTH(path) DESC').all();
+    for (const root of roots) {
+        const prefix = root.path.replace(/\\/g, '/').replace(/\/+$/, '');
+        if (normal === prefix)
+            return { rootId: root.id, relPath: '' };
+        if (normal.toLowerCase().startsWith(`${prefix.toLowerCase()}/`)) {
+            return { rootId: root.id, relPath: normal.slice(prefix.length + 1) };
+        }
+    }
+    return undefined;
+}
+/**
+ * The album a mark is about, and what the rule makes of the files under it.
+ *
+ * Both verbs below open with exactly this and differ only in the verdict they
+ * hand the rule: a person's word for `mark`, nothing for `unmark`, which is how
+ * the rule gets to speak again. It is written once because the refusal in it is
+ * the part that must not drift — a path that names no album is a statement about
+ * nothing, and both verbs owe the operator that sentence rather than a mark
+ * quietly landing on something else.
+ */
+function albumAndReason(db, rootId, relPath, mark) {
+    const row = db
+        .prepare('SELECT id FROM album WHERE root_id = ? AND rel_path = ?')
+        .get(rootId, relPath);
+    if (row === undefined) {
+        throw new Error(`no album at that path: ${relPath === '' ? '(the root itself)' : relPath}`);
+    }
+    const files = db
+        .prepare('SELECT kind FROM file WHERE root_id = ? AND folder_rel_path = ?')
+        .all(rootId, relPath);
+    return { albumId: row.id, reason: junkReason(files, mark) };
+}
+/**
+ * Record what a person said about a folder, and make it so at once.
+ *
+ * Returns the reason the album now carries, or null when there is none — so a
+ * caller reads the outcome off one value instead of two: `trust` on a folder the
+ * rule would hide gives null, and `junk` on anything at all gives the sentence
+ * the listings are keeping it out by. What differs between the two verdicts is
+ * *which* answer comes back, not whether one does.
+ *
+ * A folder that is not an album at all is refused by name: the mark is keyed on
+ * a path, and a path with no album row under it is a statement about nothing —
+ * a typo the operator would otherwise never hear about.
+ */
+export function mark(db, rootId, relPath, verdict, note) {
+    const { albumId, reason } = albumAndReason(db, rootId, relPath, verdict);
+    withTransaction(db, () => {
+        db.prepare(`INSERT INTO junk_mark (root_id, rel_path, verdict, note, marked_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT (root_id, rel_path) DO UPDATE SET
+         verdict   = excluded.verdict,
+         note      = excluded.note,
+         marked_at = excluded.marked_at`).run(rootId, relPath, verdict, note, new Date().toISOString());
+        db.prepare('UPDATE album SET junk_reason = ? WHERE id = ?').run(reason, albumId);
+    });
+    return reason;
+}
+/**
+ * Take a hand mark back, and let the rule speak again.
+ *
+ * The third verb, and the one that makes the other two reversible: `block` and
+ * `allow` write a person's word over the rule's, and without this there is no
+ * way to withdraw it — the album would carry "marked junk by hand" for ever, in
+ * a database nobody remembers to edit.
+ *
+ * The row is re-derived here exactly as `mark` re-derives it, from the same
+ * function and in the same transaction, so the two cannot disagree about what a
+ * folder is: one rule, one caller of it, whichever way the mark moved.
+ */
+export function unmark(db, rootId, relPath) {
+    const { albumId, reason } = albumAndReason(db, rootId, relPath);
+    withTransaction(db, () => {
+        db.prepare('DELETE FROM junk_mark WHERE root_id = ? AND rel_path = ?').run(rootId, relPath);
+        db.prepare('UPDATE album SET junk_reason = ? WHERE id = ?').run(reason, albumId);
+    });
+    return reason;
+}
+/**
+ * The hand edits themselves, whether or not they hid anything.
+ *
+ * `hidden` answers "what is being kept out", which is not the same list: an
+ * `allow` on a folder the rule would have hidden keeps nothing out, and it is
+ * exactly the mark an operator wants to find again to take back. Listing the
+ * marks is also how a deployment's own judgement becomes readable — the rule's
+ * answers are derivable from the files, and these are not.
+ */
+export function marks(db) {
+    return db
+        .prepare(`SELECT m.root_id AS rootId, r.path AS rootPath, m.rel_path AS relPath,
+                m.verdict AS verdict, m.note AS note, m.marked_at AS markedAt
+           FROM junk_mark m JOIN root r ON r.id = m.root_id
+          ORDER BY r.path, m.rel_path`)
+        .all();
+}
+/**
+ * Every album the filter is keeping out, and why it is out.
+ *
+ * The reason and the source both, because "hidden" alone is not checkable: a
+ * rule that overreached and a person who marked something look identical from a
+ * count, and the difference is the whole of what an operator checking the
+ * filter's work needs. `source` is the album's own reason matching the hand
+ * mark's text — the two readings are distinguishable because `rule.ts` writes
+ * one sentence and the mark writes another, and neither is ever a substring of
+ * the other.
+ */
+export function hidden(db) {
+    return db
+        .prepare(`SELECT al.root_id AS rootId, r.path AS rootPath, al.rel_path AS relPath,
+                al.title AS title, al.junk_reason AS junkReason,
+                EXISTS (SELECT 1 FROM junk_mark m
+                         WHERE m.root_id = al.root_id AND m.rel_path = al.rel_path
+                           AND m.verdict = 'junk') AS marked
+           FROM album al JOIN root r ON r.id = al.root_id
+          WHERE al.junk_reason IS NOT NULL
+          ORDER BY r.path, al.rel_path`)
+        .all().map((row) => ({
+        rootId: row.rootId,
+        rootPath: row.rootPath,
+        relPath: row.relPath,
+        title: row.title,
+        junkReason: row.junkReason,
+        source: row.marked === 1 ? 'hand' : 'scan',
+    }));
+}