funoteka 0.1.0

package/deploy/systemd/funoteka.env.example

@@ -0,0 +1,41 @@
+# /etc/funoteka/env — install as 0600, root-owned.
+#
+# This is where a native Linux deployment keeps its settings, and it is the same
+# vocabulary as `.env.example` for Docker and the Windows service wrapper behind
+# it. The environment wins over a config file, so anything written here is the
+# last word.
+
+# ---- the meta layer ----------------------------------------------------------
+# `StateDirectory=funoteka` in the unit makes /var/lib/funoteka for you, and the
+# unit lets the service write there and nowhere else under a read-only /.
+FUNOTEKA_DB=/var/lib/funoteka/funoteka.db
+
+# ---- who may listen ----------------------------------------------------------
+FUNOTEKA_HOST=0.0.0.0
+FUNOTEKA_PORT=4533
+FUNOTEKA_USER=demo
+FUNOTEKA_PASSWORD=change-me
+# Or a key instead of a password (OpenSubsonic `apiKeyAuthentication`).
+# FUNOTEKA_APIKEY=
+
+# ---- who may operate ---------------------------------------------------------
+# The admin surface does not exist without a token. Generate one:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+FUNOTEKA_ADMIN_TOKEN=
+FUNOTEKA_ADMIN_PORT=4534
+
+# ---- the collection ----------------------------------------------------------
+# The roots the scanner reads live in the meta layer, not here: `POST /roots`
+# adds one on the admin port and `POST /scan` reads it (DEPLOY.md §4). By hand,
+# once, it is the CLI — which records the root as it scans:
+#   sudo -u funoteka /usr/bin/node /opt/funoteka/src/cli.ts scan /srv/music
+
+# ---- the rest, when the defaults do not fit ----------------------------------
+# ffmpeg is only needed to cut cue tracks out of an m4a/MP4 image. Without it
+# those tracks are refused with a reason and everything else works.
+# FUNOTEKA_FFMPEG=/usr/bin/ffmpeg
+# The journal already collects this server's output; a file of its own is for
+# the machines where nobody reads the journal.
+# FUNOTEKA_LOG_FILE=/var/lib/funoteka/funoteka.log
+# One line per request — how "why will this phone not sync" gets answered.
+# FUNOTEKA_LOG_REQUESTS=1

package/deploy/systemd/funoteka.service

@@ -0,0 +1,77 @@
+# funoteka as a Linux service.
+#
+#   sudo install -Dm644 deploy/systemd/funoteka.service /etc/systemd/system/funoteka.service
+#   sudo install -Dm600 deploy/systemd/funoteka.env.example /etc/funoteka/env
+#   sudo editor /etc/funoteka/env          # credentials, admin token, MUSIC path
+#   sudo useradd --system --home /var/lib/funoteka funoteka
+#   sudo systemctl daemon-reload && sudo systemctl enable --now funoteka
+#
+# The unit is written for the *native* deployment — Node and ffmpeg installed on
+# the machine. If Docker is available, `docker compose up -d` is the shorter road
+# and this file is not needed.
+#
+# **`Restart=always` is what makes `POST /restart` a restart.** The admin surface
+# answers 200 and exits; systemd is what brings it back. `FUNOTEKA_SUPERVISED=1`
+# below is the server being told so, and without both halves the route refuses
+# with a reason rather than stopping the service.
+
+[Unit]
+Description=funoteka — Subsonic-compatible music library
+Documentation=https://github.com/ (see DEPLOY.md)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=funoteka
+Group=funoteka
+WorkingDirectory=/opt/funoteka
+
+# Secrets live here and not in this unit: the file is 0600 and root-owned, while
+# a unit file is world-readable and ends up in `systemctl cat` output.
+EnvironmentFile=/etc/funoteka/env
+# What tells the server that something will start it again — see the note above.
+Environment=FUNOTEKA_SUPERVISED=1
+# **Where the config file is, and it has to be somewhere the service may write.**
+# Without this the file resolves against the working directory — `/opt/funoteka`
+# — which `ProtectSystem=strict` makes read-only, so `POST /config` and
+# `POST /user` would fail on a native deployment while working in a container.
+# The state directory below is the one place this service may write.
+Environment=FUNOTEKA_CONFIG=/var/lib/funoteka/funoteka.json
+
+# `/usr/bin/node` rather than `node`: a service does not read a login shell's
+# PATH, and a unit that silently fails to find its interpreter is a service that
+# is "not running" with nothing in the journal but an exit code.
+ExecStart=/usr/bin/node /opt/funoteka/src/cli.ts serve
+
+Restart=always
+RestartSec=5s
+
+# A stop waits for the process to close its sockets and its meta layer rather
+# than killing it: the server handles SIGTERM, and what it does with it is
+# exactly what a clean shutdown is. The timeout is the backstop for a client
+# holding a stream open.
+KillSignal=SIGTERM
+TimeoutStopSec=20s
+
+# The state directory, created and owned by systemd, and the only place under a
+# read-only filesystem this service may write. Point FUNOTEKA_DB here.
+StateDirectory=funoteka
+ReadWritePaths=/var/lib/funoteka
+
+# A server that only reads a collection and writes one directory has no use for
+# the privileges of a person. Each of these closes a way out of the service if
+# the process is ever made to do something it was not meant to.
+NoNewPrivileges=true
+ProtectSystem=strict
+# `read-only` and not `yes`: this collection frequently lives under /home, and a
+# unit that could not read it would be a service that started and served nothing.
+ProtectHome=read-only
+PrivateTmp=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+
+[Install]
+WantedBy=multi-user.target

package/deploy/windows/funoteka-service.xml

@@ -0,0 +1,58 @@
+<!--
+  funoteka as a Windows service — WinSW's configuration.
+
+  Do not copy this file to the service by hand: `install-service.ps1` fills in
+  the placeholders below and installs it, because the paths it needs are the ones
+  only that script knows (where node is, where this checkout is, where the data
+  directory is).
+
+  **Every secret lives in the config file and not here.** A WinSW XML sits beside
+  the wrapped executable and is readable by whoever can read that directory,
+  while `FUNOTEKA_CONFIG` points at a file whose ACL the install script restricts
+  to the service's own account. That is the same split the systemd unit makes
+  with its `EnvironmentFile`, and for the same reason.
+
+  **`<onfailure action="restart"/>` is what makes `POST /restart` a restart.**
+  The admin surface answers 200 and exits with 75 (`EX_TEMPFAIL`), which is a
+  failure as far as this file is concerned — that is exactly why the code is not
+  0, and why the other two deployments need nothing special: Docker and systemd
+  restart on a clean exit too.
+-->
+<service>
+  <id>funoteka</id>
+  <name>funoteka</name>
+  <description>Subsonic-compatible music library — smart scanner, Subsonic API, admin surface</description>
+
+  <executable>{{NODE}}</executable>
+  <arguments>"{{REPO}}\src\cli.ts" serve</arguments>
+  <workingdirectory>{{DATA}}</workingdirectory>
+
+  <startmode>Automatic</startmode>
+  <!-- Gives the network and any mounted collection time to be there; a service
+       that starts before the disk it serves would scan an empty directory. -->
+  <delayedAutoStart>true</delayedAutoStart>
+
+  <!-- The meta layer, the log and the config, all in one directory — and the
+       only directory this service needs to write. -->
+  <env name="FUNOTEKA_CONFIG" value="{{DATA}}\funoteka.json" />
+  <env name="FUNOTEKA_DB" value="{{DATA}}\funoteka.db" />
+  <env name="FUNOTEKA_LOG_FILE" value="{{DATA}}\funoteka.log" />
+  <!-- What tells the server something will start it again — see the note above. -->
+  <env name="FUNOTEKA_SUPERVISED" value="1" />
+
+  <onfailure action="restart" delay="10 sec" />
+  <!-- A service that has restarted cleanly for an hour is no longer failing, so
+       one later crash is treated as the first. -->
+  <resetfailure>1 hour</resetfailure>
+
+  <!-- A stop waits for the sockets and the meta layer to be closed: the server
+       handles SIGTERM, and Windows delivers it to a process WinSW asks politely.
+       The timeout is the backstop for a client holding a stream open. -->
+  <stoptimeout>20 sec</stoptimeout>
+  <!-- The server spawns ffmpeg for cue segments; that child must not outlive the
+       service, and killing the parent first is what leaves it orphaned. -->
+  <stopparentprocessfirst>false</stopparentprocessfirst>
+
+  <logmode>append</logmode>
+  <logpath>{{DATA}}\logs</logpath>
+</service>

package/deploy/windows/install-service.ps1

@@ -0,0 +1,158 @@
+<#
+.SYNOPSIS
+  Install funoteka as a Windows service, or take it away.
+
+.DESCRIPTION
+  Wraps this checkout's `node src/cli.ts serve` in a Windows service using WinSW
+  — a small executable that does the one thing Node cannot: talk to the Service
+  Control Manager. Node has no way to be a service on its own, and the
+  alternatives are all worse for a project with no dependencies: a .NET project
+  to build, or a scheduled task that only starts when somebody logs in.
+
+  Run it from an **elevated** PowerShell. Nothing is downloaded without its hash
+  being checked, and nothing is written outside the data directory and the
+  service's own folder.
+
+  **This script has not been run end to end by the person who wrote it.** It
+  installs a service, which needs an elevated shell and a machine to keep the
+  service on; the Docker path is the one that was verified. Treat the first run
+  as the verification, and read what it says.
+
+.EXAMPLE
+  .\install-service.ps1 -Data 'C:\ProgramData\funoteka'
+
+.EXAMPLE
+  .\install-service.ps1 -Remove
+#>
+[CmdletBinding()]
+param(
+    # Everything this deployment owns: the meta layer, the log, the config and
+    # WinSW's own files. Defaults to C:\ProgramData\funoteka, which is where a
+    # machine-wide service's state belongs.
+    [string] $Data = (Join-Path $env:ProgramData 'funoteka'),
+
+    # Where WinSW is put. Its own directory because the service's executable is
+    # one of its files, and a service looking for its wrapper among the sources
+    # is a service that breaks on the next `git pull`.
+    [string] $ServiceDir = (Join-Path $env:ProgramData 'funoteka\service'),
+
+    # The service's display name; also the XML's id.
+    [string] $Name = 'funoteka',
+
+    [switch] $Remove,
+
+    [switch] $SkipDownload
+)
+
+$ErrorActionPreference = 'Stop'
+
+# WinSW 2.12.0, pinned — and the hash is of the asset as published on that
+# release, computed after downloading it from GitHub. A version without a hash is
+# a download that can change under the same name; a hash without a version is one
+# nobody can look up.
+$WinSwVersion = '2.12.0'
+$WinSwUrl = "https://github.com/winsw/winsw/releases/download/v$WinSwVersion/WinSW-x64.exe"
+$WinSwSha256 = '05b82d46ad331cc16bdc00de5c6332c1ef818df8ceefcd49c726553209b3a0da'
+
+function Assert-Admin {
+    $identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $principal = New-Object Security.Principal.WindowsPrincipal($identity)
+    if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+        throw 'This needs an elevated PowerShell: installing a service writes to the machine, not to your profile.'
+    }
+}
+
+function Get-WinSw {
+    param([string] $Where)
+
+    if ($SkipDownload) {
+        if (-not (Test-Path $Where)) { throw "-SkipDownload was given but there is no WinSW at $Where" }
+        return
+    }
+
+    Write-Host "Downloading WinSW $WinSwVersion ..."
+    $temp = Join-Path $env:TEMP "winsw-$WinSwVersion.exe"
+    Invoke-WebRequest -Uri $WinSwUrl -OutFile $temp -UseBasicParsing
+
+    $hash = (Get-FileHash -Algorithm SHA256 -Path $temp).Hash.ToLowerInvariant()
+    if ($hash -ne $WinSwSha256) {
+        Remove-Item -Force $temp
+        throw "WinSW $WinSwVersion did not match its published hash.`n  expected $WinSwSha256`n  got      $hash`nNothing was installed."
+    }
+
+    New-Item -ItemType Directory -Force -Path (Split-Path $Where) | Out-Null
+    Move-Item -Force $temp $Where
+    Write-Host "  hash ok: $hash"
+}
+
+# ---------------------------------------------------------------- uninstall --
+if ($Remove) {
+    Assert-Admin
+    $exe = Join-Path $ServiceDir "$Name.exe"
+    if (Test-Path $exe) {
+        Write-Host "Stopping and uninstalling $Name ..."
+        # WinSW uninstalls itself; a service file removed by hand leaves the SCM
+        # holding an entry that points at nothing.
+        & $exe stop 2>$null
+        & $exe uninstall 2>$null
+    } else {
+        Write-Host "No service wrapper at $exe — nothing to uninstall."
+    }
+    Write-Host "The data in $Data was left alone. Remove it by hand if you mean to."
+    return
+}
+
+# ------------------------------------------------------------------ install --
+Assert-Admin
+
+$repo = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+$node = (Get-Command node -ErrorAction Stop).Source
+
+Write-Host "funoteka service"
+Write-Host "  repo  $repo"
+Write-Host "  node  $node"
+Write-Host "  data  $Data"
+
+New-Item -ItemType Directory -Force -Path $Data | Out-Null
+New-Item -ItemType Directory -Force -Path $ServiceDir | Out-Null
+
+# The config file, from the example, only if there is not one already: this
+# script installs a service, and overwriting a deployment's credentials would be
+# it deciding something that is not its business.
+$config = Join-Path $Data 'funoteka.json'
+if (-not (Test-Path $config)) {
+    Copy-Item (Join-Path $repo 'funoteka.json.example') $config
+    Write-Host ""
+    Write-Host "  Wrote $config from the example."
+    Write-Host "  **Edit it before starting the service**: it needs FUNOTEKA_USER/PASSWORD and an admin token."
+    Write-Host ""
+}
+
+Get-WinSw -Where (Join-Path $ServiceDir "$Name.exe")
+
+$template = Get-Content -Raw (Join-Path $PSScriptRoot 'funoteka-service.xml')
+$xml = $template.
+    Replace('{{NODE}}', $node).
+    Replace('{{REPO}}', $repo).
+    Replace('{{DATA}}', $Data)
+$xmlPath = Join-Path $ServiceDir "$Name.xml"
+Set-Content -Path $xmlPath -Value $xml -Encoding utf8
+Write-Host "  wrote $xmlPath"
+
+$exe = Join-Path $ServiceDir "$Name.exe"
+& $exe install
+if ($LASTEXITCODE -ne 0) { throw "WinSW could not install the service (exit $LASTEXITCODE)" }
+
+# The config carries the credentials, so it is readable by the account the
+# service runs as and by administrators — and by nobody else. This is the one
+# thing on Windows that stands in for the systemd unit's 0600 EnvironmentFile.
+icacls $config /inheritance:r /grant:r 'SYSTEM:(R)' /grant:r 'Administrators:(R)' | Out-Null
+
+Write-Host ""
+Write-Host "Installed. Then:"
+Write-Host "  Start-Service $Name"
+Write-Host "  Get-Service $Name"
+Write-Host "  Invoke-RestMethod http://127.0.0.1:4533/health"
+Write-Host ""
+Write-Host "The first run has nothing to serve — scan the collection once:"
+Write-Host "  & '$node' '$repo\src\cli.ts' scan 'D:\Music'"

package/dist/annotation/store.js

@@ -0,0 +1,67 @@
+import { withTransaction } from "../db/index.js";
+const SUBJECTS = {
+    track: { table: 'track_annotation', column: 'track_id' },
+    album: { table: 'album_annotation', column: 'album_id' },
+    artist: { table: 'artist_annotation', column: 'artist_id' },
+};
+/**
+ * The mark on one subject, or nothing when there is none.
+ *
+ * Starring twice keeps the first date: a client that re-sends what it already
+ * said has not changed when it said it, and a timestamp that moved on every
+ * sync would be a `starred` a client keeps re-reading.
+ */
+export function star(db, kind, id) {
+    const { table, column } = SUBJECTS[kind];
+    db.prepare(`INSERT INTO ${table} (${column}, starred_at, rating) VALUES (?, ?, NULL)
+     ON CONFLICT (${column}) DO UPDATE SET starred_at = COALESCE(${table}.starred_at, excluded.starred_at)`).run(id, new Date().toISOString());
+}
+/**
+ * Take the star off, and leave the rating alone.
+ *
+ * The two are independent in the protocol — a client may rate without starring
+ * and unstar without unrating — so this clears one field and then drops the row
+ * only if that left it saying nothing.
+ */
+export function unstar(db, kind, id) {
+    const { table, column } = SUBJECTS[kind];
+    withTransaction(db, () => {
+        db.prepare(`UPDATE ${table} SET starred_at = NULL WHERE ${column} = ?`).run(id);
+        db.prepare(`DELETE FROM ${table} WHERE ${column} = ? AND rating IS NULL`).run(id);
+    });
+}
+/**
+ * Set the rating — zero means "no rating", which is the protocol's own spelling.
+ *
+ * Refused outside 1..5 by the caller (`api/annotation.ts`), not clamped here: a
+ * rating of 7 is a client with a bug, and quietly storing 5 would tell it the
+ * number it sent was accepted.
+ */
+export function setRating(db, kind, id, rating) {
+    const { table, column } = SUBJECTS[kind];
+    withTransaction(db, () => {
+        if (rating <= 0) {
+            db.prepare(`UPDATE ${table} SET rating = NULL WHERE ${column} = ?`).run(id);
+        }
+        else {
+            db.prepare(`INSERT INTO ${table} (${column}, starred_at, rating) VALUES (?, NULL, ?)
+         ON CONFLICT (${column}) DO UPDATE SET rating = excluded.rating`).run(id, rating);
+        }
+        db.prepare(`DELETE FROM ${table} WHERE ${column} = ? AND rating IS NULL AND starred_at IS NULL`).run(id);
+    });
+}
+/**
+ * Everything starred of one kind, most recently starred first.
+ *
+ * The order is the protocol's suggestion and the only one that means anything
+ * here: a starred list is a list of what somebody liked lately, and the
+ * timestamps are the only thing the table says about when.
+ */
+export function starredIds(db, kind) {
+    const { table, column } = SUBJECTS[kind];
+    return db
+        .prepare(`SELECT ${column} AS id FROM ${table}
+          WHERE starred_at IS NOT NULL
+          ORDER BY starred_at DESC, ${column}`)
+        .all().map((row) => row.id);
+}

package/dist/api/admin-export.js

@@ -0,0 +1,227 @@
+/** Every statement a rescan cannot rebuild, as one document. */
+export function exportState(db, schema, now = new Date()) {
+    return {
+        funoteka: 'export',
+        version: 1,
+        at: now.toISOString(),
+        schema,
+        naming: 'a track is (root path, file path within it, segment start in ms — null for a whole file)',
+        notIncluded: {
+            scan: 'albums, tracks and everything derived from the files: a rescan rebuilds them and the files are on disk',
+            secrets: 'the password and the bootstrap api key — they are in the config file, which is one small file to copy',
+            history: 'play counts and the play queue: activity rather than decisions, and it grows without bound',
+        },
+        sensitive: 'the api keys below are credentials: this document is worth as much as they are',
+        playlists: db
+            .prepare('SELECT id, name, comment, public, created_at, changed_at FROM playlist ORDER BY id')
+            .all()
+            .map((row) => {
+            const one = row;
+            return {
+                name: one.name,
+                comment: one.comment,
+                public: one.public === 1,
+                createdAt: one.created_at,
+                changedAt: one.changed_at,
+                entries: db
+                    .prepare(`SELECT r.path AS root, f.rel_path AS file, t.segment_start_ms AS at
+                 FROM playlist_track pt JOIN track t ON t.id = pt.track_id
+                 JOIN file f ON f.id = t.file_id JOIN root r ON r.id = f.root_id
+                WHERE pt.playlist_id = ? ORDER BY pt.position`)
+                    .all(one.id),
+            };
+        }),
+        starred: {
+            tracks: db
+                .prepare(`SELECT r.path AS root, f.rel_path AS file, t.segment_start_ms AS at,
+                  a.starred_at AS starredAt, a.rating AS rating
+             FROM track_annotation a JOIN track t ON t.id = a.track_id
+             JOIN file f ON f.id = t.file_id JOIN root r ON r.id = f.root_id
+            ORDER BY a.track_id`)
+                .all(),
+            albums: db
+                .prepare(`SELECT r.path AS root, a.rel_path AS rel, an.starred_at AS starredAt, an.rating AS rating
+             FROM album_annotation an JOIN album a ON a.id = an.album_id
+             JOIN root r ON r.id = a.root_id ORDER BY an.album_id`)
+                .all(),
+            artists: db
+                .prepare(`SELECT ar.name AS name, an.starred_at AS starredAt, an.rating AS rating
+             FROM artist_annotation an JOIN artist ar ON ar.id = an.artist_id ORDER BY an.artist_id`)
+                .all(),
+        },
+        bookmarks: db
+            .prepare(`SELECT r.path AS root, f.rel_path AS file, t.segment_start_ms AS at,
+                b.position_ms AS positionMs, b.comment AS comment,
+                b.created_at AS createdAt, b.changed_at AS changedAt
+           FROM bookmark b JOIN track t ON t.id = b.track_id
+           JOIN file f ON f.id = t.file_id JOIN root r ON r.id = f.root_id
+          ORDER BY b.track_id`)
+            .all(),
+        junkMarks: db
+            .prepare(`SELECT r.path AS root, m.rel_path AS rel, 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(),
+        apiKeys: db
+            .prepare('SELECT label, secret, created_at AS createdAt, revoked_at AS revokedAt FROM api_key ORDER BY id')
+            .all(),
+    };
+}
+/**
+ * Write the document back, by natural key, and say what it could not place.
+ *
+ * **A merge, not a replacement.** A restore is run on a library that already has
+ * something in it — that is the situation it exists for — and deleting what is
+ * there first would be this route deciding that the document is the truth. It
+ * adds what is missing and leaves what is not in the document alone.
+ *
+ * **Every entry that cannot be placed is counted and described.** A restore that
+ * silently dropped the third of a playlist whose files have moved would look
+ * exactly like one that worked, and the operator would find out by listening.
+ * `skipped` is where that loss is stated, and it names the key rather than a
+ * count of them.
+ */
+export function restoreState(db, doc) {
+    const placed = {
+        playlists: 0,
+        playlistEntries: 0,
+        trackStars: 0,
+        albumStars: 0,
+        artistStars: 0,
+        bookmarks: 0,
+        junkMarks: 0,
+        apiKeys: 0,
+    };
+    const skipped = [];
+    // **Prepared once, and not once per entry — this is the whole cost of a
+    // restore.** Measured on a copy of the live deployment with a document of
+    // 8.11 MB / 45 000 entries: preparing the statements inside the loops below
+    // was **2848 ms of the 3459 ms** the restore took, and the music port is
+    // frozen for the whole of it — 3.2 s during which no client is answered.
+    // Hoisted, the same restore measured **771 ms**.
+    const sql = {
+        playlistByName: db.prepare('SELECT id FROM playlist WHERE name = ?'),
+        insertPlaylist: db.prepare('INSERT INTO playlist (name, comment, public, created_at, changed_at) VALUES (?, ?, ?, ?, ?)'),
+        nextPosition: db.prepare('SELECT COALESCE(MAX(position), -1) + 1 AS next FROM playlist_track WHERE playlist_id = ?'),
+        insertEntry: db.prepare('INSERT OR IGNORE INTO playlist_track (playlist_id, position, track_id) VALUES (?, ?, ?)'),
+        // The join a whole file and a segment of one are told apart by. `IS` and not
+        // `=`: a whole file's key is `null`, and `segment_start_ms = NULL` is never
+        // true — it would have found nothing for every ordinary song.
+        findTrack: db.prepare(`SELECT t.id AS id FROM track t JOIN file f ON f.id = t.file_id JOIN root r ON r.id = f.root_id
+        WHERE r.path = ? AND f.rel_path = ? AND t.segment_start_ms IS ?`),
+        trackStar: db.prepare(`INSERT INTO track_annotation (track_id, starred_at, rating) VALUES (?, ?, ?)
+       ON CONFLICT (track_id) DO UPDATE SET starred_at = excluded.starred_at, rating = excluded.rating`),
+        albumStar: db.prepare(`INSERT INTO album_annotation (album_id, starred_at, rating) VALUES (?, ?, ?)
+       ON CONFLICT (album_id) DO UPDATE SET starred_at = excluded.starred_at, rating = excluded.rating`),
+        artistStar: db.prepare(`INSERT INTO artist_annotation (artist_id, starred_at, rating) VALUES (?, ?, ?)
+       ON CONFLICT (artist_id) DO UPDATE SET starred_at = excluded.starred_at, rating = excluded.rating`),
+        albumByPath: db.prepare('SELECT a.id FROM album a JOIN root r ON r.id = a.root_id WHERE r.path = ? AND a.rel_path = ?'),
+        artistByName: db.prepare('SELECT id FROM artist WHERE name = ?'),
+        bookmark: db.prepare(`INSERT INTO bookmark (track_id, position_ms, comment, created_at, changed_at) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT (track_id) DO UPDATE SET position_ms = excluded.position_ms, comment = excluded.comment,
+         changed_at = excluded.changed_at`),
+        rootByPath: db.prepare('SELECT id FROM root WHERE path = ?'),
+        junkMark: 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`),
+        albumJunk: db.prepare("UPDATE album SET junk_reason = CASE WHEN ? = 'junk' THEN 'marked junk by hand' ELSE NULL END WHERE root_id = ? AND rel_path = ?"),
+        keyBySecret: db.prepare('SELECT id FROM api_key WHERE secret = ?'),
+        insertKey: db.prepare('INSERT INTO api_key (label, secret, created_at, revoked_at) VALUES (?, ?, ?, ?)'),
+    };
+    /** The track a key names, or nothing when this library does not have it. */
+    const resolveTrack = (key) => sql.findTrack.get(key.root, key.file, key.at)?.id ?? null;
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const list of doc.playlists ?? []) {
+            const existing = sql.playlistByName.get(list.name);
+            const id = existing?.id ??
+                Number(sql.insertPlaylist.run(list.name, list.comment, list.public ? 1 : 0, list.createdAt, list.changedAt)
+                    .lastInsertRowid);
+            if (existing === undefined)
+                placed.playlists = (placed.playlists ?? 0) + 1;
+            let position = Number(sql.nextPosition.get(id).next);
+            for (const key of list.entries ?? []) {
+                const trackId = resolveTrack(key);
+                if (trackId === null) {
+                    skipped.push({ what: `${list.name}: ${key.file}`, why: 'no such file (or segment) in this library' });
+                    continue;
+                }
+                sql.insertEntry.run(id, position, trackId);
+                position += 1;
+                placed.playlistEntries = (placed.playlistEntries ?? 0) + 1;
+            }
+        }
+        for (const star of doc.starred?.tracks ?? []) {
+            const trackId = resolveTrack(star);
+            if (trackId === null) {
+                skipped.push({ what: `star: ${star.file}`, why: 'no such file (or segment) in this library' });
+                continue;
+            }
+            sql.trackStar.run(trackId, star.starredAt, star.rating);
+            placed.trackStars = (placed.trackStars ?? 0) + 1;
+        }
+        for (const star of doc.starred?.albums ?? []) {
+            const album = sql.albumByPath.get(star.root, star.rel);
+            if (album === undefined) {
+                skipped.push({ what: `star: ${star.rel}`, why: 'no such album (or root) in this library' });
+                continue;
+            }
+            sql.albumStar.run(album.id, star.starredAt, star.rating);
+            placed.albumStars = (placed.albumStars ?? 0) + 1;
+        }
+        for (const star of doc.starred?.artists ?? []) {
+            const artist = sql.artistByName.get(star.name);
+            if (artist === undefined) {
+                skipped.push({ what: `star: ${star.name}`, why: 'no such artist in this library' });
+                continue;
+            }
+            sql.artistStar.run(artist.id, star.starredAt, star.rating);
+            placed.artistStars = (placed.artistStars ?? 0) + 1;
+        }
+        for (const mark of doc.bookmarks ?? []) {
+            const trackId = resolveTrack(mark);
+            if (trackId === null) {
+                skipped.push({ what: `bookmark: ${mark.file}`, why: 'no such file (or segment) in this library' });
+                continue;
+            }
+            sql.bookmark.run(trackId, mark.positionMs, mark.comment, mark.createdAt, mark.changedAt);
+            placed.bookmarks = (placed.bookmarks ?? 0) + 1;
+        }
+        for (const mark of doc.junkMarks ?? []) {
+            const root = sql.rootByPath.get(mark.root);
+            if (root === undefined) {
+                skipped.push({ what: `junk mark: ${mark.rel}`, why: 'the root it was made under is not configured here' });
+                continue;
+            }
+            sql.junkMark.run(root.id, mark.rel, mark.verdict, mark.note, mark.markedAt);
+            // The album's own verdict is re-derived from the mark the same way `mark`
+            // does it, so a restored deployment hides what the old one hid.
+            sql.albumJunk.run(mark.verdict, root.id, mark.rel);
+            placed.junkMarks = (placed.junkMarks ?? 0) + 1;
+        }
+        for (const key of doc.apiKeys ?? []) {
+            if (sql.keyBySecret.get(key.secret) !== undefined)
+                continue;
+            sql.insertKey.run(key.label, key.secret, key.createdAt, key.revokedAt);
+            placed.apiKeys = (placed.apiKeys ?? 0) + 1;
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            // Already unwound; the original error is what matters.
+        }
+        throw err;
+    }
+    return { placed, skipped };
+}
+/** Whether a parsed body is one of ours, before anything is written. */
+export function isExport(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const doc = value;
+    return doc.funoteka === 'export' && typeof doc.version === 'number';
+}