engine-dj-mcp 0.11.3 → 0.15.0

package/dist/playlists.js

@@ -353,6 +353,28 @@ function describe(items) {
         ? `${shown}; and ${items.length - NAMED_IN_ERROR} more (call get_playlists to see them all)`
         : shown;
 }
+/**
+ * "No such playlist", for both branches resolvePlaylist can reach it from.
+ *
+ * The default `invalid_argument` code has no write-path contract on
+ * `detail` (see errors.ts), so the candidate listing lives there, exactly as
+ * before. `playlist_not_found` is different: a write tool's caller reads
+ * `detail` to learn whether the library changed (see errors.ts), and every
+ * other `playlist_not_found` -- raised inside store/write.ts once an id
+ * reaches it -- carries `detail: "not_committed"`. Nothing was attempted
+ * here either, so this must match, which leaves no room in `detail` for the
+ * candidate listing; it moves into `message` instead, so a human still sees
+ * it.
+ */
+function notFoundError(names, reason, items) {
+    const candidates = items.length
+        ? `Playlists (id -- path): ${describe(items)}`
+        : "This library has no playlists.";
+    if (names.notFound) {
+        return err(names.notFound, `${reason}. ${candidates}`, { detail: "not_committed" });
+    }
+    return err("invalid_argument", reason, { detail: candidates });
+}
 /**
  * Turns "id or name" into one specific playlist, or an actionable error.
  *
@@ -361,10 +383,14 @@ function describe(items) {
  * whole function exists to prevent. The error names every candidate with its
  * id and its full path, so the retry is a copy-paste rather than a guess.
  *
- * Deliberately reuses `invalid_argument` rather than adding an error code:
- * the taxonomy is closed (see errors.ts), and "the playlist you named is not
- * in this library" is a problem with the argument, reported the same way an
- * unknown field name is -- with the recognised values in `detail`.
+ * Reuses `invalid_argument` by default rather than adding an error code: the
+ * taxonomy is closed (see errors.ts), and for a reader "the playlist you
+ * named is not in this library" is a problem with the argument, reported the
+ * same way an unknown field name is -- with the recognised values in
+ * `detail`. A caller that already owns a more accurate code for that one
+ * case passes it as `names.notFound`; the write tools do, so their documented
+ * `playlist_not_found` is what a client actually sees. Ambiguity is never
+ * reported through it.
  */
 export async function resolvePlaylist(qp, sel, names = { id: "playlist_id", name: "playlist_name" }) {
     const hasId = sel.id !== undefined && sel.id !== null;
@@ -385,11 +411,7 @@ export async function resolvePlaylist(qp, sel, names = { id: "playlist_id", name
     if (hasId) {
         const found = tree.items.find((i) => i.id === sel.id);
         if (!found) {
-            return err("invalid_argument", `No playlist with ${names.id} ${sel.id} in this library`, {
-                detail: tree.items.length
-                    ? `Playlists (id -- path): ${describe(tree.items)}`
-                    : "This library has no playlists.",
-            });
+            return notFoundError(names, `No playlist with ${names.id} ${sel.id} in this library`, tree.items);
         }
         return { playlist: found, warnings: tree.warnings };
     }
@@ -397,11 +419,7 @@ export async function resolvePlaylist(qp, sel, names = { id: "playlist_id", name
     if (matches.length === 1)
         return { playlist: matches[0], warnings: tree.warnings };
     if (matches.length === 0) {
-        return err("invalid_argument", `No playlist named "${sel.name}" in this library`, {
-            detail: tree.items.length
-                ? `Playlists (id -- path): ${describe(tree.items)}`
-                : "This library has no playlists.",
-        });
+        return notFoundError(names, `No playlist named "${sel.name}" in this library`, tree.items);
     }
     return err("invalid_argument", `"${sel.name}" names ${matches.length} playlists in this library`, {
         detail: `Playlist names are unique only within a folder. Pass ${names.id}, or pass the full ` +

package/dist/semantics.js

@@ -85,6 +85,11 @@ export function keyDistance(a, b) {
 export function registerFunctions(db, mdbPath) {
     const opts = { deterministic: true };
     db.function("camelot", opts, (key) => camelot(key === null ? null : Number(key)));
+    // A comparison key for text: one Unicode normalization form, lower-cased by
+    // Unicode rules. SQLite's own LOWER folds ASCII only -- LOWER('ЭЙФОРИЯ')
+    // comes back unchanged -- which made audit_library's duplicates find a
+    // capitalised Latin title and miss a capitalised Cyrillic one (#9).
+    db.function("fold", opts, (text) => text === null || text === undefined ? null : String(text).normalize("NFC").toLowerCase());
     db.function("key_name", opts, (key) => keyName(key === null ? null : Number(key)));
     db.function("tempo", opts, (a, b) => tempo(a === null ? null : Number(a), b === null ? null : Number(b)));
     db.function("key_distance", opts, (a, b) => a === null || b === null ? null : keyDistance(String(a), String(b)));

package/dist/server.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { discoverLibraries, defaultRoots, probeLibraries } from "./discovery.js";
 import { libraryCandidates, libraryTag, sidecarDir } from "./paths.js";
-import { LibraryArg, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
+import { LibraryArg, ambiguousLibrary, defaultLibraryTies, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
 import { hasHotJournal } from "./store/connections.js";
 import { QueryProcess } from "./proc/query-client.js";
 import { IndexManager } from "./store/index-manager.js";
@@ -17,10 +17,24 @@ import { auditLibrary, AuditInput, AUDIT_CHECKS } from "./tools/audit.js";
 import { runSql, RunSqlInput } from "./tools/sql.js";
 import { listLibraries } from "./tools/libraries.js";
 import { refreshIndex } from "./tools/refresh.js";
-import { CreatePlaylistInput, runCreatePlaylist } from "./tools/write-playlist.js";
+import { CreatePlaylistInput, runCreatePlaylist, AddTracksToPlaylistInput, runAddTracksToPlaylist, RemoveTracksFromPlaylistInput, runRemoveTracksFromPlaylist, ReorderPlaylistInput, runReorderPlaylist, } from "./tools/write-playlist.js";
 import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
 const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+/**
+ * A write that only ever *adds*. `destructiveHint: false` is a claim with a
+ * defined meaning in MCP -- "this tool performs only additive updates" -- and
+ * clients use it to decide whether to confirm with the user first. True of
+ * create_playlist (a new playlist, nothing else touched) and of
+ * add_tracks_to_playlist (new entries, existing ones left where they are).
+ */
 const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: false };
+/**
+ * A write that can destroy or reorganise what is already there:
+ * remove_tracks_from_playlist deletes entries, reorder_playlist rewrites the
+ * order of a list a DJ may be playing from live. Advertising either as
+ * additive told a client it need not ask before calling.
+ */
+const RW_DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
 /**
  * name/version reported to every client on initialize. Read from
  * package.json rather than typed here, so the two cannot re-diverge the way
@@ -42,9 +56,34 @@ const PACKAGE_INFO = JSON.parse(readFileSync(new URL("../package.json", import.m
  * this repeats the essentials in the description because some clients show a
  * model the description and not the per-property schema documentation.
  */
+/**
+ * Every write result names the library it landed in, and every undo is scoped
+ * to that one library. Engine DJ propagates a playlist change to another
+ * connected library by itself -- measured 2026-09-01: an edit made to the
+ * library on the computer appeared on the USB drive after Engine was next
+ * launched, the copy carrying the very timestamp this server's INSERT had
+ * written. An undo call cannot reach that copy, and reports success anyway,
+ * because within its own library it did exactly what it promised.
+ *
+ * Stated in the description, not just the README, because the caller who has
+ * to act on it is the model holding the undo.
+ */
+const UNDO_SCOPE_NOTE = "`undo` reverses this edit in ONE library: the one the result's `library` field names. " +
+    "Engine DJ copies playlist changes between connected libraries on its own, so launching it " +
+    "with a second library attached can leave a copy of this edit there -- and no undo call " +
+    "reaches that copy. With two libraries connected (a USB drive and its copy on the computer " +
+    "is the usual case), undo separately against each. ";
 const LIBRARY_SELECTION_NOTE = "With more than one library connected, pass `library` (a uuid or path from list_libraries, " +
     "either the ~/... form or the absolute one) to choose which one; the default is the " +
     "supported library with the most tracks.";
+/**
+ * Appended to the write tools only. A tie in the default rule is a refusal
+ * there and a free choice on the read side, so the shared note above cannot
+ * carry it without being wrong for one of the two.
+ */
+const WRITE_LIBRARY_TIE_NOTE = " If two supported libraries hold the same most tracks -- what a USB drive and its copy on " +
+    "the computer produce -- this tool refuses with ambiguous_library rather than picking one, " +
+    "and lists both; nothing is written. Ask the user which one, then retry with `library` set -- do not pick for them, since one of the two may be the drive they perform from.";
 function reply(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -208,6 +247,47 @@ export async function createServer(opts = {}) {
             return state;
         return fresh;
     };
+    /**
+     * `acquire` for the write tools: identical, except that an omitted
+     * `library` must resolve to exactly one candidate.
+     *
+     * `pickDefaultLibrary` breaks a tie on root-scan order, which is
+     * deterministic and, for a read, fine -- libraries tie because one is a
+     * copy of the other, so either answer is very nearly the same answer, and
+     * making a read demand a `library` it does not care about would be noise.
+     *
+     * A write is not that. The choice decides which physical disk changes, and
+     * one of the two is the drive the DJ performs from; root-scan order is not
+     * a reason to pick it. Measured 2026-09-01: the computer's library and the
+     * USB drive both held 257 tracks, tied precisely because one was a copy of
+     * the other.
+     *
+     * Only the omitted case refuses. A caller who named a library gets it, tie
+     * or no tie -- the ambiguity being refused here is the server's, not theirs.
+     *
+     * Rescans first, because `knownList()` is a cache that deliberately keeps a
+     * library a later scan cannot see -- so a momentarily locked drive does not
+     * vanish from list_libraries. For a tie check that is wrong in the
+     * direction that bites: pull the USB drive and one library is left, but the
+     * cache still holds two, and the write is refused naming a drive that is no
+     * longer there. rescanLibraries() forgets a candidate whose path is gone,
+     * which is exactly the distinction wanted here, and it also lets a drive
+     * plugged in mid-session be seen at all.
+     *
+     * The cost is one filesystem probe per write, against a write that is about
+     * to copy the entire database for its pre-write snapshot. Reads are left
+     * alone: they run far more often and a stale pick between two copies is not
+     * worth a probe apiece.
+     */
+    const acquireForWrite = async (requested) => {
+        if (requested === undefined) {
+            rescanLibraries();
+            const tied = defaultLibraryTies(knownList());
+            if (tied.length > 1)
+                return ambiguousLibrary(tied);
+        }
+        return acquire(requested);
+    };
     /**
      * Shared by the engine://libraries resource and the list_libraries tool so
      * the two cannot drift in shape, while differing in exactly one respect:
@@ -357,6 +437,10 @@ export async function createServer(opts = {}) {
         title: "Audit the collection",
         description: `Run collection health checks. Available: ${AUDIT_CHECKS.join(", ")}. ` +
             `missing_files resolves each track against the selected library's own folder. ` +
+            `path_form_mismatch finds files that are there, but under a name in a different Unicode ` +
+            `normalization form from the stored path -- macOS opens them anyway, Linux does not ` +
+            `(measured on its exFAT driver), and Engine OS on a player is Linux, so these may fail ` +
+            `to load on hardware while missing_files on a Mac reports nothing. ` +
             `no_cues means "no hot cue is set" -- the quickCues blob is decoded for this, since ` +
             `Engine writes one to every analysed track whether or not a pad is used -- while ` +
             `no_beatgrid means the beatData blob is absent or empty. ` +
@@ -429,7 +513,13 @@ export async function createServer(opts = {}) {
                 "write of this session; it is a recovery route for a damaged library, NOT an undo. " +
                 "Restoring it reverts the entire library to that moment, discarding everything " +
                 "Engine DJ has written since (play counts, imports, cue and beatgrid edits). " +
-                "No existing playlist or entry is ever modified; this only adds a new one. " +
+                "The result's `library` field names which library this went into. Engine DJ copies " +
+                "playlist changes between connected libraries on its own (measured for an edit to an " +
+                "existing playlist), so with a second library attached the new playlist may appear " +
+                "there too. " +
+                "No existing playlist is renamed, reordered, emptied or deleted, and no track, cue or " +
+                "beatgrid is touched. The one existing row that moves is the previous last playlist's " +
+                "link, and Engine's own insert trigger is what moves it. " +
                 "Fails with playlist_exists if a top-level playlist already has that title, and " +
                 "with library_busy if Engine DJ or a player is holding a conflicting lock on the " +
                 "library right then -- nothing is written in that case, so retry rather than " +
@@ -437,15 +527,115 @@ export async function createServer(opts = {}) {
                 "library is unchanged and \"committed_unverified\" when the write may have gone " +
                 "through but could not be verified. track_ids may be empty (an empty playlist); a " +
                 "track id may appear at most once. " +
-                LIBRARY_SELECTION_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
             inputSchema: { ...CreatePlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
-            const state = await acquire(args.library);
+            const state = await acquireForWrite(args.library);
             if (isEngineError(state))
                 return reply(state);
             return reply(await runCreatePlaylist(state.lib.path, state.lib.uuid, args, opts.backupBaseDir ?? join(homedir(), ".engine-dj-mcp", "backups")));
         });
+        const backupDirFor = () => opts.backupBaseDir ?? join(homedir(), ".engine-dj-mcp", "backups");
+        server.registerTool("add_tracks_to_playlist", {
+            title: "Add tracks to a playlist",
+            description: "Add one or more tracks to an EXISTING playlist -- this edits that playlist's " +
+                "contents, it does NOT create a new one (use create_playlist for that). Name the " +
+                "playlist with playlist_id or playlist_name, exactly one of the two, resolved the " +
+                "same way get_playlist_tracks does: a name matching more than one playlist in this " +
+                "library is refused, listing every candidate's id and full path, rather than guessed " +
+                "at. track_ids are ids from search_tracks or get_tracks; a track already in the " +
+                "playlist is refused as duplicate_track, since Engine allows a track in a playlist " +
+                "only once. at chooses where the new tracks land, using the playlist's current " +
+                "1-based positions (the same numbering get_playlist_tracks reports): \"start\", " +
+                "\"end\" (the default), or { after_position: n }. If this playlist's entry chain is " +
+                "already damaged, the write is refused outright rather than repaired -- nothing is " +
+                "added, and the error names what is broken. " +
+                "On success, the result's `undo` is the exact remove_tracks_from_playlist call that " +
+                "reverses this edit -- the positions the new tracks landed at, plus expect_track_ids " +
+                "naming the tracks that landed there, so a list someone changed in the meantime is " +
+                "refused rather than having the wrong rows removed -- and `undo_complete` is true. " +
+                "Call it to undo " +
+                "rather than restoring backup_path, which reverts the WHOLE library to before this " +
+                "session's first write, discarding every play count, import, cue and beatgrid change " +
+                "Engine DJ has recorded since -- not just this one edit. backup_path is only a " +
+                "last-resort recovery route for a damaged library, never an undo. " +
+                UNDO_SCOPE_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+            inputSchema: { ...AddTracksToPlaylistInput.shape, library: LibraryArg },
+            annotations: RW,
+        }, async (args) => {
+            const state = await acquireForWrite(args.library);
+            if (isEngineError(state))
+                return reply(state);
+            return reply(await runAddTracksToPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
+        });
+        server.registerTool("remove_tracks_from_playlist", {
+            title: "Remove tracks from a playlist",
+            description: "Remove one or more tracks from an EXISTING playlist by position -- this edits that " +
+                "playlist's contents; it never touches any other playlist. Name the playlist with " +
+                "playlist_id or playlist_name, exactly one of the two, resolved the same way " +
+                "get_playlist_tracks does (an ambiguous name is refused with every candidate listed, " +
+                "not guessed at). positions are the 1-based positions get_playlist_tracks reports " +
+                "for THIS playlist right now -- they include entries whose track is missing from the " +
+                "library (get_playlist_tracks marks those missing: true), and removing one of those " +
+                "is a legitimate way to clean up a hole -- but it is the one removal that cannot be " +
+                "undone: such an entry names no track id, so no add_tracks_to_playlist call can put " +
+                "it back, and the result says so with undo_complete: false plus an undo_note naming " +
+                "those positions. expect_track_ids is optional and, when " +
+                "given, must have one entry per position: it verifies each named position still " +
+                "holds the track expected before anything is removed, refusing the whole call " +
+                "otherwise; null there means \"this position should hold an entry whose track is " +
+                "missing\", not \"no expectation\". If this playlist's entry chain is already " +
+                "damaged, the write is refused outright rather than repaired. " +
+                "On success, the result's `undo` is a SEQUENCE of add_tracks_to_playlist calls, one " +
+                "per removed track THAT CAN BE RESTORED -- run them IN THE ORDER GIVEN, never in " +
+                "parallel and never " +
+                "reversed: each step's target position is computed against the list as it stands " +
+                "after the previous step has already run, so firing them out of order or " +
+                "concurrently puts tracks back in the wrong places. Check `undo_complete`: false " +
+                "means one or more removed entries had no track to name and are gone for good -- " +
+                "`undo_note` says which positions, and the remaining steps still restore everything " +
+                "else. Preferred over restoring " +
+                "backup_path, which reverts the WHOLE library to before this session's first write, " +
+                "discarding everything Engine DJ has recorded since -- not just this edit. " +
+                UNDO_SCOPE_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+            inputSchema: { ...RemoveTracksFromPlaylistInput.shape, library: LibraryArg },
+            annotations: RW_DESTRUCTIVE,
+        }, async (args) => {
+            const state = await acquireForWrite(args.library);
+            if (isEngineError(state))
+                return reply(state);
+            return reply(await runRemoveTracksFromPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
+        });
+        server.registerTool("reorder_playlist", {
+            title: "Reorder a playlist",
+            description: "Reorder an EXISTING playlist's tracks -- this changes the order of that playlist's " +
+                "existing entries; it adds nothing and removes nothing. Name the playlist with " +
+                "playlist_id or playlist_name, exactly one of the two, resolved the same way " +
+                "get_playlist_tracks does (an ambiguous name is refused with every candidate listed, " +
+                "not guessed at). order must be a full permutation of 1..n, n being the playlist's " +
+                "current entry count: order[i] names the CURRENT 1-based position (from " +
+                "get_playlist_tracks) of the track that should end up at position i + 1. A partial " +
+                "'move x to y' instruction is not accepted -- name every position, including ones " +
+                "that do not move. If this playlist's entry chain is already damaged, the write is " +
+                "refused outright rather than repaired. " +
+                "On success, the result's `undo` is the exact inverse permutation, as a single " +
+                "reorder_playlist call, and `undo_complete` is true; prefer it over restoring " +
+                "backup_path, which reverts the " +
+                "WHOLE library to before this session's first write, discarding everything Engine DJ " +
+                "has recorded since -- not just this reorder. " +
+                UNDO_SCOPE_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+            inputSchema: { ...ReorderPlaylistInput.shape, library: LibraryArg },
+            annotations: RW_DESTRUCTIVE,
+        }, async (args) => {
+            const state = await acquireForWrite(args.library);
+            if (isEngineError(state))
+                return reply(state);
+            return reply(await runReorderPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
+        });
     }
     /**
      * There was previously no way to shut this down at all: createServer
@@ -517,6 +707,18 @@ other.
 - \`Track.path\` is relative to the \`Engine Library\` folder and usually
   contains \`..\`. The SQL function \`abs_path(path)\` resolves it against
   this library's location; the home prefix comes back folded to \`~\`.
+- \`Track.streamingSource\`, \`uri\` and \`streamingFlags\` are reported to
+  decide whether Engine OS streams a track (from Dropbox) instead of reading
+  the file. Not measured here: on both reference libraries \`streamingSource\`
+  and \`uri\` are NULL on every track, and \`streamingFlags\` is 5 on about
+  half of them -- tracks that load and play -- so \`streamingFlags\` on its own
+  says nothing about whether a track will load. Selectable as the fields
+  \`streaming_source\`, \`streaming_flags\` and \`uri\`; \`uri\` is redacted like
+  \`path\`, including a home directory percent-encoded inside it.
+- SQLite's \`LOWER()\` folds ASCII only: \`LOWER('ЭЙФОРИЯ')\` comes back
+  unchanged. To compare names regardless of case in any script, use
+  \`fold(text)\` -- one Unicode normalization form, lower-cased by Unicode
+  rules. It runs per row, like every function here.
 - A track's natural key across drives is \`(originDatabaseUuid, originTrackId)\`.
 - \`PerformanceData\`'s blob columns are binary and cannot be read with SQL.
   Engine writes \`quickCues\`, \`loops\`, \`beatData\` and

package/dist/store/backup.d.ts

@@ -1,3 +1,4 @@
+import { backup } from "node:sqlite";
 import { type EngineError } from "../errors.js";
 /**
  * The snapshots to delete, oldest first, from a directory listing.
@@ -23,4 +24,21 @@ import { type EngineError } from "../errors.js";
  * predate the tagged scheme, so they predate anything written since.
  */
 export declare function evictable(names: string[], uuid: string, tag: string): string[];
-export declare function snapshotLibrary(mdbPath: string, uuid: string, baseDir: string): Promise<string | EngineError>;
+/**
+ * Partial copies in this library's namespace whose writer is gone.
+ *
+ * A snapshot is copied to `<final name>.partial-<pid>` and renamed into place
+ * only once backup() has resolved (see snapshotLibrary). A process killed
+ * mid-copy never gets to clean up after itself, so its partial stays behind:
+ * harmless to rotation, which counts only `.db` names, but a full-size file
+ * nobody will ever finish.
+ *
+ * The pid is what separates such an orphan from another server's copy that is
+ * being written right now -- two servers can snapshot one library at once --
+ * so only a pid with no live process behind it is reclaimed. `prefix` keeps it
+ * to this library, exactly as rotation is kept to it.
+ */
+export declare function abandonedPartials(names: string[], prefix: string, isAlive?: (pid: number) => boolean): string[];
+export declare function snapshotLibrary(mdbPath: string, uuid: string, baseDir: string, deps?: {
+    backup?: typeof backup;
+}): Promise<string | EngineError>;

package/dist/store/backup.js

@@ -9,7 +9,7 @@
 // Engine Library folder -- the rule that no file is created there holds for
 // writes exactly as it did for reads.
 import { DatabaseSync, backup } from "node:sqlite";
-import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { err } from "../errors.js";
 import { libraryTag } from "../paths.js";
@@ -74,7 +74,49 @@ export function evictable(names, uuid, tag) {
     mine.sort((a, b) => (a.old !== b.old ? (a.old ? -1 : 1) : a.stamp < b.stamp ? -1 : a.stamp > b.stamp ? 1 : 0));
     return mine.slice(0, Math.max(0, mine.length - KEEP)).map((x) => x.name);
 }
-export async function snapshotLibrary(mdbPath, uuid, baseDir) {
+/** Whether a process with this pid exists. EPERM means it does and is not ours to signal. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/**
+ * Partial copies in this library's namespace whose writer is gone.
+ *
+ * A snapshot is copied to `<final name>.partial-<pid>` and renamed into place
+ * only once backup() has resolved (see snapshotLibrary). A process killed
+ * mid-copy never gets to clean up after itself, so its partial stays behind:
+ * harmless to rotation, which counts only `.db` names, but a full-size file
+ * nobody will ever finish.
+ *
+ * The pid is what separates such an orphan from another server's copy that is
+ * being written right now -- two servers can snapshot one library at once --
+ * so only a pid with no live process behind it is reclaimed. `prefix` keeps it
+ * to this library, exactly as rotation is kept to it.
+ */
+export function abandonedPartials(names, prefix, isAlive = processAlive) {
+    // With or without `-journal`: SQLite keeps a rollback journal beside the
+    // copy while backup() runs (measured -- it exists mid-copy and is gone once
+    // backup() resolves), so a process killed partway leaves both behind. They
+    // share the pid, so a live copy's journal is spared along with the copy.
+    const partial = /\.db\.partial-(\d+)(-journal)?$/;
+    return names.filter((name) => {
+        if (!name.startsWith(prefix))
+            return false;
+        const m = partial.exec(name);
+        return m !== null && !isAlive(Number(m[1]));
+    });
+}
+export async function snapshotLibrary(mdbPath, uuid, baseDir, 
+// Injectable so a test can make the copy fail after it has started writing
+// -- the one failure that matters here, and one no real error reachable
+// from a test produces (they all fail before the destination is touched).
+deps = {}) {
+    const copy = deps.backup ?? backup;
     // node:sqlite stopped needing a flag in 22.13, which is where this
     // project's floor used to sit -- but backup() only arrived in 22.16. On
     // 22.13 through 22.15 the read path works perfectly and this one throws
@@ -82,11 +124,12 @@ export async function snapshotLibrary(mdbPath, uuid, baseDir) {
     // run against the declared floor. `engines` now says 22.16, and npm only
     // enforces that under engine-strict, so the check is here too: a version
     // number a user can act on beats a TypeError from inside a dependency.
-    if (typeof backup !== "function") {
+    if (typeof copy !== "function") {
         return err("library_unreadable", `This Node cannot snapshot a library before writing to it: node:sqlite gained backup() in ` +
             `22.16.0 and this is ${process.version}. Upgrade Node, or run without --allow-writes.`);
     }
     let src;
+    let partial;
     try {
         mkdirSync(baseDir, { recursive: true });
         src = new DatabaseSync(mdbPath, { readOnly: true });
@@ -98,16 +141,41 @@ export async function snapshotLibrary(mdbPath, uuid, baseDir) {
         // the same tag server.ts's sidecarBaseFor uses to keep two such
         // libraries' indexes apart (see paths.ts).
         const prefix = `${uuid}-${libraryTag(mdbPath)}-`;
+        // Before copying, not after: a copy that died because the disk filled up
+        // left its partial behind, and this is exactly when that space is wanted.
+        for (const dead of abandonedPartials(readdirSync(baseDir), prefix)) {
+            rmSync(join(baseDir, dead), { force: true });
+        }
+        // Copied under a name rotation does not count and nobody would restore,
+        // then renamed into place only once backup() has resolved. Written
+        // straight to the final name, a copy that died partway was an incomplete
+        // database indistinguishable from a good one: rotation took it for the
+        // newest and evicted a real snapshot for it, and "restore the latest
+        // backup" would have restored it (#3). rename() within one directory is
+        // atomic, so the final name only ever holds a finished copy.
         const dest = join(baseDir, `${prefix}${stamp()}.db`);
-        await backup(src, dest);
+        partial = `${dest}.partial-${process.pid}`;
+        await copy(src, partial);
         src.close();
         src = undefined;
+        renameSync(partial, dest);
+        partial = undefined;
         for (const stale of evictable(readdirSync(baseDir), uuid, libraryTag(mdbPath))) {
             rmSync(join(baseDir, stale), { force: true });
         }
         return dest;
     }
     catch (e) {
+        // Safe to delete, which the destination itself never was: this name
+        // carries this process's pid and a stamp whose counter never repeats
+        // within a process, so whatever is there was created by this call. The
+        // earlier objection to cleaning up on failure -- deleting a file at a path
+        // we may not have created -- does not apply to a path no one else can
+        // produce.
+        if (partial) {
+            rmSync(partial, { force: true });
+            rmSync(`${partial}-journal`, { force: true });
+        }
         return err("library_unreadable", `Could not snapshot ${mdbPath} before writing: ${String(e)}`);
     }
     finally {