funoteka 0.1.0

package/dist/scan/scan.js

@@ -0,0 +1,503 @@
+import { realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { withTransaction } from "../db/index.js";
+import { clearIssues, recordStageFailure } from "../db/issue.js";
+import { movedSince } from "../db/ledger.js";
+import { prepareSweep, SWEPT_BY_SCAN } from "../db/sweep.js";
+import { stillMoving } from "./settle.js";
+import { walkRoot } from "./walk.js";
+/** This stage's name in `issue.stage`. Bound to the insert and to the clear. */
+const STAGE = 'scan';
+const ALL_KINDS = ['audio', 'cue', 'image', 'nfo', 'log', 'playlist', 'other'];
+/** Directory holding `relPath`, in forward-slash terms; '' for a top-level entry. */
+function parentOf(relPath) {
+    const cut = relPath.lastIndexOf('/');
+    return cut === -1 ? '' : relPath.slice(0, cut);
+}
+/**
+ * Is `inner` a strict subdirectory of `outer`?
+ *
+ * Both are canonical keys from `rootKey`, so case and separators are already
+ * settled the platform's way. The separator is not a nicety: a bare prefix test
+ * reads `C:\Music Hall` as living under `C:\Music`, which is the difference
+ * between the finding this exists for and a false alarm on every sibling.
+ */
+function below(outer, inner) {
+    return inner.startsWith(outer.endsWith(sep) ? outer : outer + sep);
+}
+/**
+ * The filesystem's own answer for a root, so that one directory is one root.
+ *
+ * `path.resolve` alone would settle separators and `.`/`..` but stop there:
+ * `C:/x` and `C:\x` name one directory, `C:\x` and `c:\x` name one directory on
+ * a filesystem that folds case, and a junction names a directory that may
+ * already be configured. `realpath` settles all three, which is why root
+ * identity asks the filesystem instead of trusting the typed string.
+ *
+ * A root that is not on disk cannot be resolved at all. That degrades to the
+ * resolved path and lets the walk report the miss, exactly as it did before.
+ */
+function canonicalRoot(rawPath) {
+    const absolute = resolve(rawPath);
+    try {
+        return realpathSync.native(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/**
+ * Comparison key for a stored root path, canonicalisation included.
+ *
+ * Applied to a path already in the table, this answers "is this the same
+ * directory?" for rows written back when the typed string was the identity —
+ * a trailing separator, a `.` segment, a junction, a different case. Asking
+ * the filesystem of the stored path is the point: those rows have no other way
+ * of being recognised as the same place.
+ *
+ * Case is folded on top only where the filesystem folds it, for the paths
+ * `realpath` could not answer for: on a case-sensitive volume `/music` and
+ * `/Music` really are two directories, and merging them would destroy the
+ * distinction the contract exists to protect.
+ */
+export function rootKey(rootPath) {
+    const canonical = canonicalRoot(rootPath);
+    return process.platform === 'win32' ? canonical.toLowerCase() : canonical;
+}
+/**
+ * The id of `path`'s root, created if it is new.
+ *
+ * A root is the identity every album hangs off, so this is the one place that
+ * has to be certain two spellings of one directory never become two rows.
+ * Rows written before canonicalisation are healed in place: the surviving twin
+ * is the one already holding the canonical path, or the oldest rewritten to
+ * it, and the rest are dropped. Their derived rows go with them under
+ * `ON DELETE CASCADE`, and the walk that follows puts them back under the
+ * surviving root — safe precisely because everything below `root` is derived
+ * from the filesystem.
+ *
+ * A root that merely *contains* another is a different case and is not healed:
+ * the two are different directories, so both stay, and the doubling they cause
+ * is reported instead. Collapsing them would delete a root the operator
+ * configured.
+ */
+function upsertRoot(db, path, nowIso, nestedReported) {
+    const rows = db.prepare('SELECT id, path FROM root ORDER BY id').all();
+    const key = rootKey(path);
+    const twins = rows.filter((row) => rootKey(row.path) === key);
+    // One directory read twice. The contract holds two roots apart on purpose —
+    // two copies of an album are two albums, and acceptance checks exactly that —
+    // and a root sitting *inside* another is not two copies. Nothing downstream
+    // can see it: both albums have tracks, so `unaccounted` reads the collection
+    // as healthy and only the file count is quietly larger than the disk. The
+    // pair is reported and both roots stay: collapsing them would delete a root
+    // the operator configured (task:2709).
+    //
+    // Both roots stay, which is why the pair is found twice — once from each side
+    // — and why `nestedReported` exists. On a second scan both are already in the
+    // table, and without it the reader would be told the same fact about the same
+    // two directories twice. The set is the run's, like the cue engine's sets for
+    // a report that is about a record rather than a file.
+    const nested = [];
+    for (const row of rows) {
+        const other = rootKey(row.path);
+        // The same directory is the twin case below, and it is reported there.
+        if (other === key)
+            continue;
+        // Which of the two is the inner one. Read from both ends, so the finding
+        // does not depend on which root the scan met first — and named in the same
+        // order whichever end raised it, or the two discoveries would describe one
+        // relationship as two different ones.
+        const isInner = below(other, key);
+        const isOuter = below(key, other);
+        if (!isInner && !isOuter)
+            continue;
+        const outerKey = isInner ? other : key;
+        const innerKey = isInner ? key : other;
+        const pair = `${outerKey}\u0000${innerKey}`;
+        if (nestedReported.has(pair))
+            continue;
+        nestedReported.add(pair);
+        const outer = isInner ? row.path : path;
+        const inner = isInner ? path : row.path;
+        nested.push({
+            kind: 'root_nested',
+            severity: 'warn',
+            detail: `${inner} is inside ${outer}, which is also a root — everything below it is read twice, once under each`,
+        });
+    }
+    // A row already holding the canonical path is the one to keep: it needs no
+    // rewrite, and its derived rows are the ones this scan is about to touch
+    // anyway. Finding it is not a reason to stop — a twin beside it is still the
+    // same directory, and leaving that one in place is the doubling this exists
+    // to prevent.
+    const survivor = rows.find((row) => row.path === path) ?? twins[0];
+    if (survivor === undefined) {
+        const inserted = db
+            .prepare('INSERT INTO root (path, created_at) VALUES (?, ?)')
+            .run(path, nowIso);
+        return { id: Number(inserted.lastInsertRowid), issues: nested };
+    }
+    const issues = [...nested];
+    if (survivor.path !== path) {
+        db.prepare('UPDATE root SET path = ? WHERE id = ?').run(path, survivor.id);
+        issues.push({
+            kind: 'root_path_canonicalised',
+            severity: 'info',
+            detail: `${survivor.path} → ${path}`,
+        });
+    }
+    // The twins' own diagnostics describe this same directory, so they move to
+    // the survivor rather than blocking the delete on the foreign key.
+    const repoint = db.prepare('UPDATE issue SET root_id = ? WHERE root_id = ?');
+    const drop = db.prepare('DELETE FROM root WHERE id = ?');
+    for (const redundant of twins) {
+        if (redundant.id === survivor.id)
+            continue;
+        repoint.run(survivor.id, redundant.id);
+        drop.run(redundant.id);
+        issues.push({
+            kind: 'root_duplicate_collapsed',
+            severity: 'warn',
+            detail: `${redundant.path} was the same directory as ${path}; its rows were dropped and re-read by this scan`,
+        });
+    }
+    return { id: survivor.id, issues };
+}
+/**
+ * How many rows one transaction carries.
+ *
+ * Measured, because this number is the whole of what the stage promises: on the
+ * live collection a batch of five hundred holds the write lock **12 ms at the
+ * median and 96 ms at its worst**, across the thirty batches of one run. The
+ * budget it is held to is the 250 ms a listener's save waits with
+ * (`busy_timeout`, `db/index.ts`) — so a save can lose the race for one batch
+ * and still get in on the next.
+ *
+ * Rows and not files: one file writes two of them (`insertFile` and the ledger
+ * row beside it), so five hundred rows is two hundred and fifty files.
+ */
+const ROWS_PER_TRANSACTION = 500;
+/**
+ * Write `rows`, a transaction at a time.
+ *
+ * Each batch is committed before the next begins, which is the whole of what
+ * this is for: the lock is held for a batch rather than for the stage, so a
+ * listener's save waiting on it gets in between them.
+ *
+ * A batch that throws unwinds only itself — what came before it stays, and the
+ * run is marked `failed` with its reason filed. That is the recovery the stages
+ * already promise (`run.ts`): a rerun after a failure reaches the state a clean
+ * run would.
+ */
+function inBatches(db, rows, write, onBatch) {
+    for (let start = 0; start < rows.length; start += ROWS_PER_TRANSACTION) {
+        const batch = rows.slice(start, start + ROWS_PER_TRANSACTION);
+        withTransaction(db, () => {
+            for (const row of batch)
+                write(row);
+        });
+        onBatch?.(batch.length);
+    }
+}
+/**
+ * Read the given roots into the meta layer.
+ *
+ * This stage records what is on disk and nothing more — no tag reading, no cue
+ * parsing, no classification. It is a faithful inventory, and the classifier
+ * layers on top of it.
+ *
+ * Files are matched by (root, relative path), so rescanning updates rows in
+ * place and keeps `first_seen_run_id` pointing at the run that found them.
+ */
+export function scan(db, rootPaths, options = {}) {
+    const walk = options.walk ?? walkRoot;
+    const now = options.now ?? (() => new Date());
+    // One directory is one root: the same directory named twice in one run —
+    // by a second spelling or a second argument — is walked once.
+    const roots = [...new Set(rootPaths.map(canonicalRoot))];
+    const startedAt = now().toISOString();
+    const run = db
+        .prepare('INSERT INTO scan_run (started_at, status, roots_json) VALUES (?, ?, ?)')
+        .run(startedAt, 'running', JSON.stringify(roots));
+    const scanRunId = Number(run.lastInsertRowid);
+    // The ledger is emptied first, so that every file the walk meets is one
+    // nothing was observed about — which is the same state as a file that has
+    // just appeared, and is what makes `full` reach every stage downstream
+    // without any of them knowing this option exists. Before the walk and not
+    // after: a run that dies halfway leaves part of the library due for a
+    // re-read, and a re-read is the safe direction to be wrong in.
+    if (options.full === true)
+        db.exec('DELETE FROM scan_state');
+    // One finding per pair of overlapping roots, whatever order the scan met them
+    // in — see `upsertRoot`.
+    const nestedReported = new Set();
+    const byKind = Object.fromEntries(ALL_KINDS.map((k) => [k, 0]));
+    let folders = 0;
+    let files = 0;
+    const perRoot = [];
+    let audioFiles = 0;
+    let skipped = 0;
+    let ignored = 0;
+    let ignoredAudio = 0;
+    let issues = 0;
+    let changed = 0;
+    let unchanged = 0;
+    const finish = (status) => {
+        db.prepare('UPDATE scan_run SET finished_at = ?, status = ? WHERE id = ?').run(now().toISOString(), status, scanRunId);
+    };
+    // Everything that can throw lives inside the guard, statement preparation
+    // included. A prepare compiles against the live schema, so a table it cannot
+    // find throws there — and it used to run before the `try`, which left
+    // `scan_run` saying `running` with nothing to correct it: the row is inserted
+    // before the transaction, so no rollback reaches it, and the stages after this
+    // one never run to file the failure either. `recordStageFailure` is what
+    // writes it down; the run id it needs is the one this function returns, which
+    // is exactly what a caller does not have when this throws.
+    try {
+        // **Written in batches, and the batching is the point of this stage's shape.**
+        //
+        // The scan and the server are two connections to one file, and SQLite gives
+        // one writer at a time. This stage used to open a single transaction around
+        // everything — every root, every folder, every file — and hold the write
+        // lock from its first row to its last: measured on the live collection,
+        // **1854 ms** for 11 541 files, against a `busy_timeout` of 250 ms
+        // (`db/index.ts`). A listener's save arriving anywhere in those 1854 ms was
+        // refused, and the save that matters most arrives exactly then: people
+        // listen to music while a scan runs.
+        //
+        // Half of that window was not writing at all. `walk` reads the filesystem —
+        // 929 ms of the 1854 — and reading a disk needs no write lock, so the walk
+        // now happens with nothing open. What is left to write goes in batches, each
+        // its own `BEGIN IMMEDIATE` (`db/index.ts` has why that word is
+        // load-bearing), so the lock is let go between them and a save waiting on it
+        // gets in.
+        //
+        // **The run is no longer one transaction, and that is the trade.**
+        //
+        // A failure part-way through a root leaves the batches before it committed
+        // instead of unwinding the root. What it does not leave is a root half-swept:
+        // `sweep` runs last, in a transaction of its own, so a run that dies before
+        // reaching it has taken nothing away. Recovery is the one the stages already
+        // promise — `run.ts`: "a rerun after a failure reaches the state a clean run
+        // would" — and the run is marked `failed` with its reason filed.
+        //
+        // The other half of the trade is what a *reader* sees. Nothing this stage
+        // wrote used to be visible until its single `COMMIT`, so a client browsing
+        // during a run browsed the library as it was before the run. Now each batch
+        // is visible as it commits, so the same client sees the root being walked in
+        // its new state and the roots after it in the old one — a library that is
+        // part-way, which is a true description of it. The sweep staying whole per
+        // root is what keeps that from being a library that is *wrong*: no row is
+        // taken away until everything under that root has been written.
+        // The stamp is the whole point of the upsert: a folder seen this run has to
+        // say so, or the sweep below deletes it as something that is no longer there.
+        const insertFolder = db.prepare(`INSERT INTO folder (root_id, rel_path, parent_rel_path, last_seen_run_id)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (root_id, rel_path) DO UPDATE SET last_seen_run_id = excluded.last_seen_run_id`);
+        // Letting go of what vanished, and the predicate that decides it, live in
+        // `db/sweep.ts` — the scan only says which tables are its to empty.
+        const sweep = prepareSweep(db, SWEPT_BY_SCAN);
+        // first_seen_run_id is deliberately absent from the UPDATE branch: it is
+        // what makes "when did this file first appear" answerable after a rescan.
+        const insertFile = db.prepare(`INSERT INTO file (root_id, rel_path, folder_rel_path, name, kind, ext, size, mtime_ms,
+                         first_seen_run_id, last_seen_run_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (root_id, rel_path) DO UPDATE SET
+         folder_rel_path  = excluded.folder_rel_path,
+         name             = excluded.name,
+         kind             = excluded.kind,
+         ext              = excluded.ext,
+         size             = excluded.size,
+         mtime_ms         = excluded.mtime_ms,
+         last_seen_run_id = excluded.last_seen_run_id`);
+        const selectScanState = db.prepare('SELECT rel_path, size, mtime_ms FROM scan_state WHERE root_id = ?');
+        const upsertScanState = db.prepare(`INSERT INTO scan_state (root_id, rel_path, size, mtime_ms, last_seen_run_id, changed)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT (root_id, rel_path) DO UPDATE SET
+         size             = excluded.size,
+         mtime_ms         = excluded.mtime_ms,
+         last_seen_run_id = excluded.last_seen_run_id,
+         changed          = excluded.changed`);
+        const insertIssue = db.prepare(`INSERT INTO issue (scan_run_id, stage, root_id, rel_path, kind, severity, detail)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        // Only the derived kinds, because this stage files both sorts of row. The
+        // root-settlement issues are events and stay — a healed spelling, a twin
+        // that was dropped, both of which happen once — while a skipped walk, an
+        // ignored directory and a root that sits inside another are read again
+        // every run, from the filesystem and from the configured root set, and
+        // would otherwise leave one more row behind on every scan. `db/issue.ts`
+        // has the rule.
+        withTransaction(db, () => {
+            clearIssues(db, STAGE, { kind: 'walk_skipped' });
+            clearIssues(db, STAGE, { kind: 'walk_ignored_audio' });
+            clearIssues(db, STAGE, { kind: 'walk_ignored' });
+            clearIssues(db, STAGE, { kind: 'root_nested' });
+        });
+        for (const rootPath of roots) {
+            // The root and whatever registering it found. Small, quick, and has to be
+            // in place before any row below can name it.
+            const root = withTransaction(db, () => {
+                const registered = upsertRoot(db, rootPath, startedAt, nestedReported);
+                for (const rootIssue of registered.issues) {
+                    insertIssue.run(scanRunId, STAGE, registered.id, null, rootIssue.kind, rootIssue.severity, rootIssue.detail);
+                    issues += 1;
+                }
+                return registered;
+            });
+            // With nothing open. This is the filesystem, and the write lock is not for
+            // the filesystem — it is the longest part of the stage and it now holds up
+            // nobody.
+            //
+            // **Read before the walk and handed to the gate, which is the walk's own
+            // clock and not this line's.** The gate asks whether a file was quiet when
+            // the walk met it, and a walk of a real collection takes seconds — so the
+            // reading taken *after* it would make the first file met the oldest in the
+            // run rather than the freshest, and a file a copy was halfway through when
+            // the walk passed it would be recorded at the size it had reached by then.
+            const walkedAtMs = now().getTime();
+            const result = walk(rootPath);
+            // **The half-write gate.** A file the disk has not been quiet about for
+            // five seconds is not a file yet, so this run does not record it. The rule
+            // and the number are `scan/settle.ts`'s, which are also the watcher's — the
+            // same clause of the contract, held the same way on both paths.
+            //
+            // **Reported as skipped and held back from the sweep, and those are two
+            // different statements.** Skipped is what the issue is recorded from, so
+            // `GET /issues` says why the file is not in the library this run. Held is
+            // what the sweep is told, and it is the *opposite* of the amnesty a skipped
+            // path otherwise gets: a file being rewritten in place keeps the rows the
+            // previous run gave it, and does not come out of the sweep claiming this
+            // run stands behind it — because it does not, and every stage selects its
+            // work by exactly that claim. Handing it over as `kept` was the bug this
+            // shape fixes: the file was read, and the tags of half a song landed in
+            // `file_tag`. A file that was not there before has no rows to keep, so it
+            // simply arrives on a later scan, once it has stopped moving.
+            const held = new Set(stillMoving(rootPath, result.files, walkedAtMs, options.settleMs ?? 0));
+            for (const relPath of held) {
+                result.skipped.push({
+                    relPath,
+                    reason: 'still being written: its size or mtime moved between two looks',
+                });
+            }
+            const walked = held.size === 0 ? result.files : result.files.filter((f) => !held.has(f.relPath));
+            // The amnesty is what the walk met and could not look into; what the gate
+            // held back is not it. Split here rather than filtered at the sweep, so
+            // that a path cannot be in both lists and neither list can grow a second
+            // meaning later.
+            const amnesty = result.skipped.filter((skip) => !held.has(skip.relPath));
+            const withheld = result.skipped.filter((skip) => held.has(skip.relPath));
+            // **The count is what this run recorded, not what the walk handed over.**
+            // The two differ only when the gate held something, and that difference is
+            // the whole point — but it is legible in `skipped` and in the issue, not
+            // here, so this reads as "0 files" for a root where everything was held
+            // exactly as it does for an empty directory.
+            perRoot.push({ path: rootPath, folders: result.folders.length, files: walked.length });
+            // The ledger as the previous run left it. Reading it before this run
+            // writes its own is the only moment the comparison still means anything:
+            // afterwards the file row and the ledger hold the same observation.
+            const previous = new Map(selectScanState.all(root.id).map((row) => [row.rel_path, row]));
+            inBatches(db, result.folders, (folder) => {
+                insertFolder.run(root.id, folder, parentOf(folder), scanRunId);
+                folders += 1;
+            }, options.onBatch);
+            inBatches(db, walked, (file) => {
+                const moved = movedSince(previous.get(file.relPath), file);
+                if (moved)
+                    changed += 1;
+                else
+                    unchanged += 1;
+                insertFile.run(root.id, file.relPath, file.folderRelPath, file.name, file.kind, file.ext, file.size, file.mtimeMs, scanRunId, scanRunId);
+                upsertScanState.run(root.id, file.relPath, file.size, file.mtimeMs, scanRunId, moved ? 1 : 0);
+                files += 1;
+                byKind[file.kind] += 1;
+                if (file.kind === 'audio')
+                    audioFiles += 1;
+            }, options.onBatch);
+            // What the walk met but did not walk, and the end of the root — the last
+            // transaction of this root, with the sweep in it. `sweep` is the stage's
+            // only destructive step, and it goes in the same commit as the rows it
+            // judges rather than after them; the reason is in the comment at the top
+            // of this function.
+            withTransaction(db, () => {
+                for (const skip of result.skipped) {
+                    insertIssue.run(scanRunId, STAGE, root.id, skip.relPath, 'walk_skipped', 'warn', skip.reason);
+                    skipped += 1;
+                    issues += 1;
+                }
+                // An ignored directory is a guess made from a name, and it stays ignored:
+                // a Synology thumbnail tree is not a collection, and walking one into the
+                // result invents a phantom album per track. What may not stay silent is
+                // that the guess was made, or that it was made about music — `#recycle`
+                // holds whatever was deleted. Both are counted either way, so `files N`
+                // can be reconciled with the filesystem.
+                for (const dir of result.ignored) {
+                    ignored += 1;
+                    ignoredAudio += dir.audio;
+                    if (dir.audio === 0)
+                        continue;
+                    insertIssue.run(scanRunId, STAGE, root.id, dir.relPath, 'walk_ignored_audio', 'warn', `ignored by name, but it holds ${dir.audio} audio file(s) — they are not in the collection`);
+                    issues += 1;
+                }
+                // The count itself, once for the root. Each directory above says what it
+                // is only when the guess was wrong about music; the guess being made at
+                // all is what a reader reconciling `files N` with the filesystem needs,
+                // and it was on stdout alone — gone by the time anyone opens the database.
+                // Aggregated rather than one row per directory because the tree a NAS
+                // writes holds hundreds of entries, and the report is about one root.
+                if (result.ignored.length > 0) {
+                    const dirs = result.ignored.length;
+                    const beneath = dirs === 1 ? 'it' : 'them';
+                    const audio = result.ignored.reduce((sum, dir) => sum + dir.audio, 0);
+                    insertIssue.run(scanRunId, STAGE, root.id, null, 'walk_ignored', 'info', `ignored ${dirs} ${dirs === 1 ? 'directory' : 'directories'} by name; ${audio === 0
+                        ? `no audio beneath ${beneath}`
+                        : `${audio} audio file(s) beneath ${beneath} are not in the collection`}`);
+                    issues += 1;
+                }
+                // A root nobody could read reports no folders and no files — which reads
+                // exactly like an empty collection, with the run still calling itself ok.
+                // The walk says so as a skip at '', and a path of '' would keep nothing:
+                // what has to survive is the whole root, and no path below it was seen to
+                // name. So the root is left alone entirely rather than handed a keep-list.
+                const rootUnreadable = result.skipped.some((skip) => skip.relPath === '');
+                // Only for the roots actually walked: a root nobody scanned has not been
+                // seen to lose anything, and its rows are not ours to drop.
+                if (!rootUnreadable) {
+                    sweep.run(root.id, scanRunId, amnesty.map((skip) => skip.relPath), withheld.map((skip) => skip.relPath));
+                }
+            });
+        }
+    }
+    catch (err) {
+        // Nothing to unwind here, and that is worth saying rather than guarding: a
+        // batch that threw was already rolled back by `withTransaction`, which is
+        // the only thing in this function that opens a transaction. A rollback here
+        // would be a second one, and a rollback with nothing to roll back throws.
+        try {
+            recordStageFailure(db, scanRunId, STAGE, err);
+        }
+        catch {
+            // The failure is already on its way to the caller. A trace that cannot be
+            // written must not replace the reason it was being written for.
+        }
+        finish('failed');
+        throw err;
+    }
+    finish('ok');
+    return {
+        scanRunId,
+        roots: roots.length,
+        rootPaths: roots,
+        perRoot,
+        changed,
+        unchanged,
+        folders,
+        files,
+        audioFiles,
+        byKind,
+        skipped,
+        ignored,
+        ignoredAudio,
+        issues,
+    };
+}

package/dist/scan/schedule.js

@@ -0,0 +1,132 @@
+import { readFileSync } from 'node:fs';
+import { PROBE_METHOD } from "../probe/ffprobe.js";
+import { TAGS_METHOD } from "../tags/read.js";
+/**
+ * The instant a scan may next start, or nothing when this server does not scan
+ * by itself at all.
+ *
+ * Two rules and they compose in one direction: the interval says *when* the
+ * reading is old enough, and the quiet hours say *when* it is allowed to happen.
+ * A due time that lands inside the quiet window is pushed to the end of it — not
+ * skipped, because skipping would mean a deployment that is always in a quiet
+ * window never scans again.
+ *
+ * The window may cross midnight (`23` to `6`), which is the shape it has for
+ * anybody who works late, and `from === to` is an empty window rather than a
+ * whole-day one.
+ */
+export function dueAt(lastStartedAt, now, schedule) {
+    if (schedule.intervalMinutes <= 0)
+        return null;
+    const last = lastStartedAt === null ? null : Date.parse(lastStartedAt);
+    const base = last === null || Number.isNaN(last) ? now.getTime() : last + schedule.intervalMinutes * 60_000;
+    const due = new Date(Math.max(base, now.getTime()));
+    return quietUntil(due, schedule);
+}
+/** The same instant, moved out of the quiet hours when it lands inside them. */
+export function quietUntil(when, schedule) {
+    if (!quiet(when, schedule))
+        return when;
+    const end = new Date(when);
+    end.setMinutes(0, 0, 0);
+    end.setHours(schedule.quietTo);
+    // A window that crosses midnight is entered before it ends, so the end is
+    // tomorrow's — and an hour of `to` that is *behind* the hour of `when` is
+    // exactly that case and not a window that has already passed.
+    if (end.getTime() <= when.getTime())
+        end.setDate(end.getDate() + 1);
+    return end;
+}
+/** Whether an instant falls in the quiet hours. */
+export function quiet(when, schedule) {
+    const hour = when.getHours();
+    const { quietFrom: from, quietTo: to } = schedule;
+    if (from === to)
+        return false;
+    // `23` to `6`: the hours that are quiet are the ones at or after `from`, or
+    // before `to` — the window is the union rather than the interval between.
+    if (from > to)
+        return hour >= from || hour < to;
+    return hour >= from && hour < to;
+}
+/**
+ * Whether watching this directory for changes is worth trying at all.
+ *
+ * **The honest answer is "not always", so it is asked rather than assumed.**
+ * Filesystem notifications on a network share are the classic thing that appears
+ * to work and does not: inotify has no way to hear about a change made on
+ * another machine, and on Windows a UNC path has no change journal this process
+ * can subscribe to. A watcher that is silent there is worse than no watcher,
+ * because the deployment believes it has one — so a share is recognised and the
+ * interval takes over, which is what the contract asks for and what the log
+ * says happened.
+ *
+ * What this cannot answer is a *mapped* drive letter on Windows pointing at a
+ * share: telling that apart from a local disk needs a syscall Node does not
+ * expose. The runtime covers that case instead — `fs.watch` on such a path
+ * either throws or delivers nothing, and the engine falls back with a line
+ * saying so.
+ */
+export function watchable(rootPath) {
+    if (/^[\\/]{2}/.test(rootPath)) {
+        return { ok: false, why: 'a network path: nothing this process can subscribe to reports changes made elsewhere' };
+    }
+    // Linux says what a mount is; the others do not have a file that answers it.
+    if (process.platform === 'linux') {
+        const mounted = mountTypeOf(rootPath);
+        if (mounted !== null && NETWORK_FILESYSTEMS.some((kind) => mounted.startsWith(kind))) {
+            return { ok: false, why: `a ${mounted} mount: no inotify event arrives for a change made on another machine` };
+        }
+    }
+    return { ok: true };
+}
+/** The filesystems whose notifications do not cross a network. */
+const NETWORK_FILESYSTEMS = ['nfs', 'cifs', 'smbfs', 'smb3', 'fuse.sshfs', 'fuse.rclone', '9p'];
+/**
+ * The filesystem type a path is on, as `/proc/mounts` describes it.
+ *
+ * The longest matching mount point wins, because `/` and `/mnt/media` are both
+ * mounts and a file under the second is not on the first. Nothing here throws: a
+ * machine without `/proc` (a container, another platform) simply does not
+ * answer, and the fallback above is the interval either way.
+ */
+function mountTypeOf(path) {
+    let mounts;
+    try {
+        mounts = readFileSync('/proc/mounts', 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const normal = path.replace(/\/+$/, '');
+    let best = null;
+    for (const line of mounts.split('\n')) {
+        const [device, point, type] = line.split(' ');
+        if (point === undefined || type === undefined)
+            continue;
+        const decoded = point.replace(/\\040/g, ' ');
+        if (normal === decoded || normal.startsWith(`${decoded.replace(/\/+$/, '')}/`)) {
+            if (best === null || decoded.length > best.point.length)
+                best = { point: decoded, type };
+        }
+    }
+    return best?.type ?? null;
+}
+/**
+ * How much of the library is read by a method older than this build's.
+ *
+ * **This is the classifier-version trigger, and it is a question rather than a
+ * mechanism.** The stages already re-read a file whose stamp is behind
+ * (`tags/apply.ts` selects `f.tags_method <> ?` among the reasons a file is due),
+ * so a changed reader is picked up by the next scan without anyone arranging it
+ * — what was missing is anybody *knowing* that the next scan is not an ordinary
+ * one. An operator sees a number here, and the engine uses it to scan now
+ * instead of in six hours.
+ */
+export function staleReadings(db) {
+    const count = (sql, method) => db.prepare(sql).get(method).n;
+    return {
+        tags: count("SELECT COUNT(*) AS n FROM file WHERE kind = 'audio' AND tags_method <> ?", TAGS_METHOD),
+        probes: count('SELECT COUNT(*) AS n FROM audio_probe WHERE probe_method <> ?', PROBE_METHOD),
+    };
+}