engine-dj-mcp 0.11.2 → 0.12.0

package/README.md

@@ -1,5 +1,6 @@
 # engine-dj-mcp
 
+[![CI](https://github.com/Venut-Labs/engine-dj-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Venut-Labs/engine-dj-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/engine-dj-mcp)](https://www.npmjs.com/package/engine-dj-mcp)
 [![licence](https://img.shields.io/npm/l/engine-dj-mcp)](./LICENSE)
 
@@ -58,16 +59,19 @@ the configuration you are reading:
 }
 ```
 
-**Requirements:** Node.js 22.13 or newer (for the unflagged `node:sqlite`;
+**Requirements:** Node.js 22.16 or newer (`node:sqlite` stopped needing a
+flag in 22.13, but the pre-write snapshot uses its `backup()`, added in
+22.16;
 there are no native dependencies), and an Engine DJ library at schema 3.0.0
 through 3.0.2 — Engine DJ 4.5 and 5.x.
 
 ## Tools
 
-Nine read-only tools, and a tenth — `create_playlist` — that appears only
-when you start the server with `--allow-writes`. Every tool that reads
-library data also accepts an optional `library` argument — see
-[Choosing a library](#choosing-a-library).
+Nine read-only tools, and four that write — `create_playlist`,
+`add_tracks_to_playlist`, `remove_tracks_from_playlist` and
+`reorder_playlist` — that appear only when you start the server with
+`--allow-writes`. Every tool that reads library data also accepts an
+optional `library` argument — see [Choosing a library](#choosing-a-library).
 
 ### `search_tracks`
 
@@ -201,7 +205,7 @@ server checks staleness itself before answering.
 
 ### `create_playlist`
 
-The only tool that writes, and the only one that is not registered at all
+The first of the four tools that write, none of which is registered at all
 unless the server was started with `--allow-writes`.
 
 Creates one new top-level playlist from track ids — `track_ids` sets both
@@ -234,6 +238,100 @@ library is exactly what it was, and `committed_unverified` — the rare one —
 means the write may have landed but could not be verified afterwards, and is
 the only case that hands back a `backup_path`.
 
+### `add_tracks_to_playlist`
+
+Adds one or more tracks to an **existing** playlist — this edits that
+playlist's contents, it does not create a new one (`create_playlist` does
+that). If the playlist's entry chain is already damaged, the write is
+refused outright rather than repaired, and nothing is added.
+
+A playlist that is a **folder** (`is_folder: true` — it has child lists) is
+edited like any other: Engine has no separate folder type, a folder can hold
+entries of its own, and all three edit tools add to, remove from and reorder
+those entries without complaint. The lists inside it are untouched either
+way.
+
+| Argument | What it does |
+| --- | --- |
+| `playlist_id` / `playlist_name` | Exactly one of the two, resolved the same way `get_playlist_tracks` does: a name matching more than one playlist is refused with every candidate's id and full path listed, not guessed at. |
+| `track_ids` | Ids from `search_tracks` or `get_tracks`, in the order they should appear. A track already in the playlist is refused as `duplicate_track` — Engine allows a track in a playlist only once. |
+| `at` | Where the new tracks land, against the playlist's current 1-based positions (the same numbering `get_playlist_tracks` reports): `"start"`, `"end"` (the default), or `{ after_position: n }`. |
+
+The result carries `playlist_id`, `tracks_added`, `positions` — where the
+new tracks landed — `undo`, `undo_complete` (always `true` here) and
+`backup_path`. `undo` is the exact `remove_tracks_from_playlist` call that
+reverses this edit: the positions the tracks landed at, plus
+`expect_track_ids` naming the tracks that landed there, so a playlist
+something else changed in the meantime is refused rather than having the
+wrong rows removed. Call it to undo rather than restoring `backup_path` —
+see [Restoring a snapshot](#restoring-a-snapshot). Refusals add
+`playlist_not_found`, `playlist_chain_damaged` and `invalid_position` to
+`create_playlist`'s own list; `detail` works the same way.
+
+### `remove_tracks_from_playlist`
+
+Removes one or more tracks from an **existing** playlist by position — this
+edits that playlist's contents; it never touches any other playlist. If the
+entry chain is already damaged, the write is refused outright rather than
+repaired.
+
+| Argument | What it does |
+| --- | --- |
+| `playlist_id` / `playlist_name` | Exactly one of the two, resolved the same way `get_playlist_tracks` does. |
+| `positions` | 1-based positions `get_playlist_tracks` reports for this playlist right now. Includes entries whose track is missing from the library (`missing: true`) — removing one is a legitimate way to clean up a hole, and the one removal `undo` cannot reverse (see below). |
+| `expect_track_ids` | Optional, one entry per position: verifies each named position still holds the track expected before anything is removed, refusing the whole call otherwise. `null` means "this position should hold an entry whose track is missing", not "no expectation". |
+
+The result carries `playlist_id`, `tracks_removed`, `removed` — each
+position's `track_id`, `null` for a missing one — `undo`, `undo_complete` and
+`backup_path`. `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 puts tracks back in the wrong places.
+Preferred over restoring `backup_path` for the same reason as above.
+
+`undo_complete` is `false` when the removal included an entry whose track is
+missing from the library: that entry named a track this library does not
+have, so no `add_tracks_to_playlist` call can put it back, and an
+`undo_note` names those positions. The steps that are returned still run and
+still restore everything else; the missing entries are recoverable only from
+`backup_path`, which reverts the whole library.
+
+Refusals: `playlist_not_found`, `playlist_chain_damaged`, and
+`invalid_position` — for a repeated or out-of-range position, or one that
+does not hold what `expect_track_ids` expected.
+
+`playlist_chain_damaged` always means the same thing for all three edit
+tools: the playlist's entry chain was already broken **before** the edit,
+which is why the edit refused to touch it. If instead the check each edit
+runs on its own work disagrees — the chain did not read back as it was
+written — the transaction is rolled back and that comes back as
+`library_unreadable`, with `detail: "not_committed"`. Both leave the library
+exactly as it was; only the second one is this server saying it does not
+understand what the library just did.
+
+### `reorder_playlist`
+
+Reorders an **existing** playlist's tracks — this changes the order of that
+playlist's existing entries; it adds nothing and removes nothing. If the
+entry chain is already damaged, the write is refused outright rather than
+repaired.
+
+| Argument | What it does |
+| --- | --- |
+| `playlist_id` / `playlist_name` | Exactly one of the two, resolved the same way `get_playlist_tracks` does. |
+| `order` | 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. |
+
+The result carries `playlist_id`, `undo`, `undo_complete` (always `true`
+here) and `backup_path`. `undo` is the exact inverse permutation, as a single
+`reorder_playlist` call. Refusals: `playlist_not_found`,
+`playlist_chain_damaged`, and `invalid_position` if `order` is not a full
+permutation of the playlist's current positions.
+
+Reordering to the order a playlist is already in is accepted and rewrites no
+entry: it still stamps the playlist's `lastEditTime`, and still costs this
+session's snapshot if nothing had been written yet.
+
 ## Resources
 
 - **`engine://schema`** — the field semantics an assistant needs before
@@ -275,11 +373,32 @@ created inside your `Engine Library` folder. The search index lives in
 Without `--allow-writes` the server has no tool that can write, and the
 paragraph above holds exactly as written: SQLite itself refuses.
 
-With the flag, one tool appears — `create_playlist`. It adds a new playlist
-and nothing else: no existing playlist is renamed, reordered, emptied or
-deleted, and no track, cue or beatgrid is touched. The single change to an
-existing row is the previous last playlist's link, made by Engine's own
-trigger.
+With the flag, four tools appear. `create_playlist` adds a new playlist and
+nothing else. `add_tracks_to_playlist`, `remove_tracks_from_playlist` and
+`reorder_playlist` go further: with the flag, an **existing** playlist can
+now be changed, not only created — its tracks added to, removed from, or put
+in a different order. What each one touches is the named playlist's own
+entries, plus exactly two rows elsewhere: that playlist's own row, whose
+`lastEditTime` every edit stamps so Engine sees the change, and — for
+`create_playlist` only — the previous last playlist's link, made by Engine's
+own insert trigger. No other playlist is renamed, emptied or deleted, and no
+track, cue or beatgrid is touched by any of the four.
+
+Every edit returns `undo` — the exact tool call that reverses it, expressed
+against the positions the edit itself produced — and `undo_complete`, saying
+whether replaying it puts the playlist back exactly as it was. Replaying
+`undo` is the right way back from an edit; restoring `backup_path` is not,
+because it 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, along with the one edit you actually wanted undone.
+See [Restoring a snapshot](#restoring-a-snapshot).
+
+There is exactly one edit `undo` cannot reverse, and it says so rather than
+pretending otherwise: removing an entry whose track is missing from the
+library (`missing: true`). Such an entry names a track this library does not
+have, so there is no track id to add back — the result comes back with
+`undo_complete: false` and an `undo_note` naming those positions, and the
+steps it does return still restore everything else.
 
 Before the first write of a session the database is snapshotted to
 `~/.engine-dj-mcp/backups/`, and every write of that session returns its
@@ -308,14 +427,18 @@ Engine will show the new playlist after it next re-reads the library.
 `backup_path` is not an undo. It is a copy of the **whole** `m.db` from
 before the session's first write, so putting it back reverts the entire
 library to that moment: every play count, import, cue, beatgrid and rating
-Engine DJ has written since is discarded along with the playlist you wanted
-gone. Reach for it only if the library itself is damaged — the case where
-`create_playlist` comes back with `detail: "committed_unverified"`.
-
-**To undo a playlist, delete it in Engine DJ.** Engine's own delete trigger
-repairs the playlist chain and cascades the entries away, which is exactly
-what removing it should do and is not something restoring a snapshot does
-better.
+Engine DJ has written since is discarded along with the one edit you wanted
+gone. Reach for it only if the library itself is damaged — the case where a
+write comes back with `detail: "committed_unverified"`.
+
+**To undo a playlist you created, delete it in Engine DJ.** Engine's own
+delete trigger repairs the playlist chain and cascades the entries away,
+which is exactly what removing it should do and is not something restoring
+a snapshot does better. **To undo an edit to an existing playlist, replay
+the `undo` the edit returned instead** — it names the precise
+`add_tracks_to_playlist`, `remove_tracks_from_playlist` or
+`reorder_playlist` call that puts the playlist back exactly as it was,
+without touching anything else Engine DJ has recorded since.
 
 `run_sql` accepts arbitrary SQL, but only the first statement is ever
 executed, and `VACUUM`, `ATTACH` and `DETACH` are rejected outright, so a
@@ -324,7 +447,7 @@ chained or exfiltrating statement cannot slip past the read-only connection.
 If Engine DJ was closed uncleanly and left an unrecovered journal, this
 server will not open the library to "fix" it, with or without
 `--allow-writes` — rolling a journal forward is a repair on someone else's
-file, and `create_playlist` refuses such a library outright rather than
+file, and every write tool refuses such a library outright rather than
 letting SQLite do it on the way in. It reports `library_needs_recovery` and
 asks you to launch Engine DJ once so it can recover its own library.
 
@@ -371,9 +494,9 @@ still test for the blob: `beatData` has no "written but empty" state.
 
 **It writes nothing but playlists, and only when you ask for it.** Without
 `--allow-writes` the library is opened read-only at the OS level and there is
-no tool that could write. With the flag, `create_playlist` adds playlists —
-and that is the whole list. Not a cue, not a tag, not a rating, and not even
-the recovery of a journal Engine DJ left behind.
+no tool that could write. With the flag, the four write tools add, edit and
+reorder playlists — and that is the whole list. Not a cue, not a tag, not a
+rating, and not even the recovery of a journal Engine DJ left behind.
 
 **It does not read play history.** `Track.timeLastPlayed` answers "what have I
 not played in six months?", but the separate Engine history database —
@@ -389,11 +512,12 @@ flag — a folder is simply a playlist that other playlists sit under — so
 `is_folder` means "has child lists". A folder you have emptied is
 indistinguishable from a playlist with no tracks.
 
-**Playlists can be created, not edited.** With `--allow-writes` a new
-playlist can be added; there is no reordering, renaming, deleting, or adding
-a track to a playlist that already exists, and no set lists or suggested
-transitions. It answers questions about the collection and writes down the
-answer if you ask; the mixing is yours.
+**A playlist's tracks can be edited; the playlist itself cannot.** With
+`--allow-writes` a new playlist can be created, and an existing one can have
+tracks added, removed or reordered — but not renamed, deleted, moved between
+folders, or turned into a folder itself, and there are no set lists or
+suggested transitions. It answers questions about the collection and writes
+down the answer if you ask; the mixing is yours.
 
 **Schema 3.0.0 through 3.0.2 only.** Older and newer libraries are listed with
 their version and reported as unsupported rather than read on a guess.

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery", "playlist_exists", "unknown_track", "duplicate_track"];
+export declare const ERROR_CODES: readonly ["library_busy", "library_not_found", "library_unreadable", "unsupported_schema", "query_timeout", "query_process_crashed", "index_stale", "decode_failed", "invalid_argument", "library_needs_recovery", "playlist_exists", "unknown_track", "duplicate_track", "playlist_chain_damaged", "playlist_not_found", "invalid_position"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;

package/dist/errors.js

@@ -27,6 +27,12 @@ export const ERROR_CODES = [
     "playlist_exists",
     "unknown_track",
     "duplicate_track",
+    // Editing an existing playlist. playlist_chain_damaged is the one that
+    // matters: a chain with a cycle or a severed link cannot be edited without
+    // making it worse, and the edit would not notice.
+    "playlist_chain_damaged",
+    "playlist_not_found",
+    "invalid_position",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/playlists.d.ts

@@ -1,4 +1,4 @@
-import { type EngineError } from "./errors.js";
+import { type EngineError, type ErrorCode } from "./errors.js";
 import type { QueryProcess } from "./proc/query-client.js";
 /**
  * Engine stores both playlist order and playlist-entry order as singly
@@ -191,6 +191,16 @@ export interface PlaylistSelector {
 export interface SelectorNames {
     id: string;
     name: string;
+    /**
+     * The code for "this library has no such playlist", when the caller has a
+     * more accurate one than the default `invalid_argument`. The write tools
+     * pass `playlist_not_found`, which their own store functions already
+     * return for an id that reaches them -- without this, that code was
+     * unreachable through MCP, because resolution runs first and every miss
+     * came back as invalid_argument. Ambiguity is never reported through this:
+     * a name matching several playlists really is a problem with the argument.
+     */
+    notFound?: ErrorCode;
 }
 export interface ResolvedPlaylist {
     playlist: PlaylistItem;
@@ -205,10 +215,14 @@ export interface ResolvedPlaylist {
  * 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 declare function resolvePlaylist(qp: QueryProcess, sel: PlaylistSelector, names?: SelectorNames): Promise<ResolvedPlaylist | EngineError>;
 /** One entry of a playlist, in playlist order. */

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/server.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
@@ -429,7 +443,9 @@ 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. " +
+                "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 " +
@@ -446,6 +462,103 @@ export async function createServer(opts = {}) {
                 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. " +
+                LIBRARY_SELECTION_NOTE,
+            inputSchema: { ...AddTracksToPlaylistInput.shape, library: LibraryArg },
+            annotations: RW,
+        }, async (args) => {
+            const state = await acquire(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. " +
+                LIBRARY_SELECTION_NOTE,
+            inputSchema: { ...RemoveTracksFromPlaylistInput.shape, library: LibraryArg },
+            annotations: RW_DESTRUCTIVE,
+        }, async (args) => {
+            const state = await acquire(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. " +
+                LIBRARY_SELECTION_NOTE,
+            inputSchema: { ...ReorderPlaylistInput.shape, library: LibraryArg },
+            annotations: RW_DESTRUCTIVE,
+        }, async (args) => {
+            const state = await acquire(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

package/dist/store/backup.d.ts

@@ -1,2 +1,26 @@
 import { type EngineError } from "../errors.js";
+/**
+ * The snapshots to delete, oldest first, from a directory listing.
+ *
+ * Two name shapes live here: the tagged `${uuid}-${tag}-${stamp}.db` written
+ * now, and the untagged `${uuid}-${stamp}.db` an earlier version wrote.
+ * Without the second, those sat outside every namespace and were never
+ * reclaimed -- up to KEEP full copies of a library, kept forever, on any
+ * upgrading user. Two libraries sharing a uuid is precisely why the tag
+ * exists, and an untagged file cannot say which of them it came from, so
+ * ageing them out under whichever library writes next is the only thing left
+ * to do with them.
+ *
+ * Ordering is by the stamp alone, never by the whole filename. Sorting the
+ * names as text compares a tag against a year at the same offset, and a tag
+ * is hex: `1e269292c523` sorts *before* `2026-...`, so a library whose path
+ * happens to hash to a tag starting 0 or 1 had its newest snapshot land at
+ * the head of the list and be deleted -- the file the caller had just been
+ * handed as its way back. Measured: it passed locally under the tag
+ * `cf11e2d00f88` and failed in CI under `1e269292c523`, same code.
+ *
+ * Untagged files sort before every tagged one regardless of stamp: they
+ * 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>;

package/dist/store/backup.js

@@ -33,7 +33,59 @@ function stamp() {
     const iso = new Date().toISOString().replace(/[:.]/g, "-");
     return `${iso}-${String(++counter).padStart(10, "0")}`;
 }
+/**
+ * The snapshots to delete, oldest first, from a directory listing.
+ *
+ * Two name shapes live here: the tagged `${uuid}-${tag}-${stamp}.db` written
+ * now, and the untagged `${uuid}-${stamp}.db` an earlier version wrote.
+ * Without the second, those sat outside every namespace and were never
+ * reclaimed -- up to KEEP full copies of a library, kept forever, on any
+ * upgrading user. Two libraries sharing a uuid is precisely why the tag
+ * exists, and an untagged file cannot say which of them it came from, so
+ * ageing them out under whichever library writes next is the only thing left
+ * to do with them.
+ *
+ * Ordering is by the stamp alone, never by the whole filename. Sorting the
+ * names as text compares a tag against a year at the same offset, and a tag
+ * is hex: `1e269292c523` sorts *before* `2026-...`, so a library whose path
+ * happens to hash to a tag starting 0 or 1 had its newest snapshot land at
+ * the head of the list and be deleted -- the file the caller had just been
+ * handed as its way back. Measured: it passed locally under the tag
+ * `cf11e2d00f88` and failed in CI under `1e269292c523`, same code.
+ *
+ * Untagged files sort before every tagged one regardless of stamp: they
+ * predate the tagged scheme, so they predate anything written since.
+ */
+export function evictable(names, uuid, tag) {
+    const tagged = `${uuid}-${tag}-`;
+    const legacy = new RegExp(`^${uuid}-(\\d{4}-.*)\\.db$`);
+    const mine = [];
+    for (const name of names) {
+        if (!name.endsWith(".db"))
+            continue;
+        if (name.startsWith(tagged)) {
+            mine.push({ name, old: false, stamp: name.slice(tagged.length, -3) });
+            continue;
+        }
+        const m = legacy.exec(name);
+        if (m)
+            mine.push({ name, old: true, stamp: m[1] });
+    }
+    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) {
+    // 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
+    // "backup is not a function", which is what CI reported on its very first
+    // 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") {
+        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;
     try {
         mkdirSync(baseDir, { recursive: true });
@@ -50,21 +102,8 @@ export async function snapshotLibrary(mdbPath, uuid, baseDir) {
         await backup(src, dest);
         src.close();
         src = undefined;
-        // Snapshots this library owns: the tagged shape above, plus the untagged
-        // `${uuid}-${stamp}.db` an earlier version wrote. Without the second,
-        // those sat outside every namespace and were never reclaimed -- up to
-        // KEEP full copies of a library, kept forever, on any upgrading user.
-        // They predate the tag and therefore predate everything written since,
-        // which is why folding them into one window evicts them first. Two
-        // libraries sharing a uuid is precisely why the tag exists, and an
-        // untagged file cannot say which of them it came from -- ageing them out
-        // under whichever library writes next is the only thing left to do.
-        const legacy = new RegExp(`^${uuid}-\\d{4}-`);
-        const mine = readdirSync(baseDir)
-            .filter((f) => f.endsWith(".db") && (f.startsWith(prefix) || legacy.test(f)))
-            .sort();
-        for (const old of mine.slice(0, Math.max(0, mine.length - KEEP))) {
-            rmSync(join(baseDir, old), { force: true });
+        for (const stale of evictable(readdirSync(baseDir), uuid, libraryTag(mdbPath))) {
+            rmSync(join(baseDir, stale), { force: true });
         }
         return dest;
     }