engine-dj-mcp 0.15.0 → 0.17.1

package/README.md

@@ -1,6 +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)
+[![CI](https://github.com/Venut-Technologies/engine-dj-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Venut-Technologies/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)
 
@@ -54,7 +54,7 @@ the configuration you are reading:
 ```json
 {
   "mcpServers": {
-    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.15.0", "--allow-writes"] }
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.17.1", "--allow-writes"] }
   }
 }
 ```
@@ -87,7 +87,7 @@ tempo, key, rating, when a track was added and when it was last played.
 | `q` | Full text over title, artist, album, genre, comment and label. Diacritics are folded, so `bjork` matches `Björk` — Engine's own search does not. |
 | `bpm` | `{ min, max }` or `{ around, tolerance_pct }`. Resolved tempo, so an analysed BPM wins over the tag. |
 | `key` | `{ camelot: [...] }` for exact keys, `{ compatible_with: "8A" }` for harmonic neighbours, `{ mode: "minor" }` for a whole side of the wheel. |
-| `rating` | `{ min, max }`, 0–5. |
+| `rating` | `{ min, max }`, in stars, 0–5. Engine stores 0, 20, 40, 60, 80, 100; the filter converts, so `{ min: 4 }` means four stars and up. The `rating` field hands back the stored number, and `rating_stars` the same thing in stars. |
 | `played` | `{ never: true }`, or `{ before, after }` taking an ISO date or a relative form like `-6 months`. |
 | `added` | `{ before, after }`, same date forms. |
 | `flags` | `analyzed`, `available`, `has_cues`, `has_beatgrid`. `has_cues` means a hot cue is genuinely set — see [Limitations](#limitations). |
@@ -210,7 +210,7 @@ server checks staleness itself before answering.
 
 ### `create_playlist`
 
-The first of the four tools that write, none of which is registered at all
+The first of the five 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
@@ -337,6 +337,66 @@ 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.
 
+### `update_track_metadata`
+
+Changes genre, comment, label, year or rating on tracks — the values Engine
+DJ shows in its columns. It writes to Engine's database, **not to the audio files' tags**. Engine itself writes a comment into the file when you edit it
+there, but not a genre or a rating, so other software reading the tags will
+not see these edits either way.
+
+| Argument | |
+| --- | --- |
+| `updates` | Up to 200 entries, each `{ id, genre?, comment?, label?, year?, rating_stars? }`. Only the named fields change. `""` clears a text field; `year: 0` means unknown, as Engine stores it; `rating_stars` is 0–5. |
+| `library` | Required when more than one library is connected — see [Choosing a library](#choosing-a-library). |
+
+A track that already holds the requested values is not written, so repeating
+a call changes nothing; it is counted in `unchanged`. The result carries
+`updated`, `unchanged`, `changed` — which fields changed on which tracks —
+`undo`, `undo_complete` (always `true`), `library`, and `backup_path` whenever
+the write transaction ran — which can include `updated: 0`, if the tracks had
+already changed to the requested values by the time the write lock was taken.
+
+**Undo.** `undo` is one `update_track_metadata` call that restores the
+previous values of exactly the fields that changed, and names the library.
+It restores values, not `lastEditTime`: Engine's own trigger stamps every
+edit, the undo included. Each entry carries `expect` set to what this call
+wrote, so an undo replayed after someone edited the track again is refused as
+`stale_value` instead of overwriting that edit. `rating_raw` and `expect`
+exist for this; an ordinary edit needs neither.
+
+Keep the undo from the first response. Repeating a call that already went
+through finds nothing to change and returns an empty undo. For work spread
+over several calls, replay the undos in reverse order.
+
+Its own refusals: `unknown_track`; `track_not_editable` — a track whose origin
+is empty (Engine's trigger rewrites an empty origin on any update, which would
+detach it from playlist entries on other drives), or a field holding a value
+this tool could not put back, such as a rating outside 0–255; `stale_value` —
+the track changed after the values in `expect` were read (up to 20 mismatches
+come back in a structured `mismatches` field, with the total count in the
+prose message); and `invalid_argument`. On `stale_value`, tell the user which
+tracks and fields changed — do not rebuild `expect` from a fresh read to force
+the write without the user's consent, or it silently overwrites the edit the
+DJ made since. Plus the ones
+[every write tool shares](#refusals-every-write-tool-shares), except
+`index_stale` and the query errors: this tool addresses tracks by id and never
+touches the search index.
+
+**Searching right after an edit.** Genre, comment and label are in the search
+index, which is rebuilt on the next read. While Engine DJ holds the library
+open it cannot be rebuilt, so a search can keep showing the old values, and
+`refresh_index` cannot help until Engine lets go. The edit itself is in the
+database.
+
+**Smart playlists.** A smart playlist whose rules match on genre changes what
+it contains when a genre is renamed, though none of its own rows were touched.
+
+**Two connected libraries.** Do not assume a tag edit propagates the way a
+playlist edit does (see [An undo covers one library](#an-undo-covers-one-library)):
+measured once, a tag edit made on the USB library was not copied to the
+computer's library on a fresh Engine DJ launch. The other direction has not
+been measured for tags. Edited tracks are marked for sync (`isMetadataOfPackedTrackChanged`) the same way Engine DJ marks its own tag edits — measured 2026-09-15. That an explicit sync to a drive then carries the edit is what the flag appears to be for, but it has not been measured.
+
 ### Refusals every write tool shares
 
 These come from what happens before the write itself — choosing the library,
@@ -347,7 +407,7 @@ own checks.
 | --- | --- | --- |
 | `invalid_argument` | The arguments do not make sense — both `playlist_id` and `playlist_name`, an empty list where one is required, or a `playlist_name` that matches several playlists (every candidate is listed). | yes |
 | `library_not_found` | `library` names nothing connected — the refusal lists what is — or the library's header could not be read. | yes |
-| `ambiguous_library` | No `library` given, and two libraries tie for the default. Lists both — see [Choosing a library](#choosing-a-library). | yes |
+| `ambiguous_library` | No `library` given, and more than one supported library is connected — or the uuid given is shared by copies on different drives. Lists them — see [Choosing a library](#choosing-a-library). | yes |
 | `unsupported_schema` | The library's version is outside what this server supports. | yes |
 | `library_needs_recovery` | Engine DJ left an unrecovered journal. Launch Engine once. | yes |
 | `library_busy` | Something holds a conflicting lock right now. Retry. | yes |
@@ -387,20 +447,33 @@ tracks**. That matters: the local library Engine DJ creates on install is
 scanned first and is often empty, so "the first one found" would hide the
 drive you actually work from.
 
-When two supported libraries hold the *same* highest number of tracks, that
-rule names no winner — and a tie is the ordinary case, not an exotic one: a
-USB drive and its copy on the computer tie precisely because one is a copy of
-the other. Measured 2026-09-01, both real libraries reported 257 tracks.
-
-**A read still chooses for itself.** Tied libraries hold the same tracks, so
-either answer is very nearly the same answer, and making you name a library
-you have no reason to care about would be noise.
-
-**A write refuses**, with `ambiguous_library` listing every candidate and its
-track count, and `detail: "not_committed"`. The choice decides which physical
-disk changes, and one of the two may be the drive you perform from; scan
-order is not a reason to pick it. Name a library and the write goes through,
-tie or not — the ambiguity being refused is the server's, not yours.
+That rule is enough for a read, which changes nothing: with two libraries
+connected a read picks one. Pass `library` when it matters which.
+
+**A write refuses instead**, as soon as more than one supported library is
+connected — whatever their track counts. `ambiguous_library` lists every
+candidate with its track count, and `detail: "not_committed"`.
+
+The count was never the right question. An earlier version refused only an
+exact tie, reasoning that a USB drive and its copy tie precisely because one
+is a copy of the other — measured 2026-09-01, both real libraries at 257. But
+import one track on one side and the tie is gone, and the default quietly
+takes the larger. A playlist written to the wrong drive is at least visible
+there; a track's genre is not, and you are left believing the edit did not
+work.
+
+With a single library nothing changes: you never have to name it.
+
+**Copies share a uuid.** Copy an `Engine Library` folder onto another drive —
+a spare stick for a gig — and the copy keeps the original's uuid, so with both
+connected one uuid names two libraries. A write naming that uuid is refused the
+same way, with `ambiguous_library` listing both paths, rather than landing on
+whichever drive was scanned first. Pass the path instead — it tells the copies
+apart — and re-read from that path anything the write depends on, since a read
+naming the uuid may have come from the other copy. Reads naming a shared uuid
+are not refused: they answer from one of the copies. Before every write the
+drives are scanned again, so a copy plugged in after the server started is
+counted — as long as its library can be read.
 
 The refusal tells the assistant to **ask you** rather than choose. Otherwise
 "pass `library`, here are the two" is an invitation to take the first one,
@@ -425,20 +498,24 @@ 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, four tools appear. `create_playlist` adds a new playlist and
+With the flag, five 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
+in a different order. What these four playlist tools touch 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 these four. `update_track_metadata`
+changes genre, comment, label, year and rating on the tracks named — see its
+section above — and nothing else: no playlist, cue, beatgrid, title, artist,
+album, path or file is touched.
+
+Every edit returns `undo` — the exact tool call that reverses it — and
+`undo_complete`; for the playlist tools, `undo` is expressed against the
+positions the edit itself produced, and `undo_complete` says 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
@@ -493,9 +570,16 @@ library the write actually landed in. Two libraries connected at once is the
 ordinary setup: a USB drive and its copy on the computer. This is where you
 check which of them a write went to.
 
-**`undo` reverses the edit in that one library, and only there.** Engine DJ
-moves playlist changes between connected libraries by itself, so a copy of
-your edit can end up somewhere `undo` cannot reach.
+**`undo` reverses the edit in that one library, and only there.** Each undo
+step names it — by path, in the step's own `library` argument — so replaying
+a step verbatim goes back to the library the edit was made in, not to whatever
+the default is at replay time. That matters because a USB drive and its copy
+hold the same playlist ids and the same track ids: a replay that resolved the
+default could land on the wrong disk, and its `expect_track_ids` would agree,
+both sides having been edited the same way.
+
+Engine DJ moves playlist changes between connected libraries by itself, so a
+copy of your edit can still end up somewhere `undo` cannot reach.
 
 Measured 2026-09-01. A track was added to a playlist in the library on the
 computer. Engine DJ was then launched with the USB drive attached, and the
@@ -533,9 +617,9 @@ cleared the next time that library is snapshotted.
 **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
+a snapshot does better. **For the playlist tools, 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.
 

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", "playlist_chain_damaged", "playlist_not_found", "invalid_position", "ambiguous_library"];
+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", "ambiguous_library", "stale_value", "track_not_editable"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;
@@ -24,6 +24,20 @@ export interface EngineError {
      * taken.
      */
     backup_path?: string;
+    /**
+     * Set only on stale_value: every `expect` that no longer matched, capped at
+     * 20 entries (the message carries the total). Structured so a caller can
+     * tell the user precisely which tracks and fields changed instead of
+     * parsing prose -- not so it can re-read and retry: the track changed
+     * after `expect` was read, and overwriting that silently, without the
+     * user's consent, is exactly what stale_value refuses.
+     */
+    mismatches?: {
+        id: number;
+        field: string;
+        expected: string | number | null;
+        actual: string | number | null;
+    }[];
 }
 export declare function err(error: ErrorCode, message: string, extra?: Omit<EngineError, "error" | "message">): EngineError;
 /**

package/dist/errors.js

@@ -33,12 +33,21 @@ export const ERROR_CODES = [
     "playlist_chain_damaged",
     "playlist_not_found",
     "invalid_position",
-    // No `library` was passed and the default rule names no single winner --
-    // two supported libraries hold the same, highest track count. Its own code
-    // rather than invalid_argument because the useful client response is
-    // specific: ask which drive, then retry with `library` set. Only writes
-    // raise it; see library-select.ts for why reads still choose.
+    // A write cannot tell which physical library to change: no `library` was
+    // passed and more than one supported library is connected, or the uuid
+    // passed is shared by copies on different drives. Its own code rather than
+    // invalid_argument because the useful client response is specific: ask
+    // which drive, then retry with its path. Only writes raise it; see
+    // library-select.ts for why reads still choose.
     "ambiguous_library",
+    // update_track_metadata (spec §7.2). stale_value: an `expect` no longer
+    // matches what is in the library. track_not_editable: this track, or one
+    // field of it, cannot be edited without harm -- an empty origin the Track
+    // trigger would rewrite, or a stored value this tool could not restore.
+    // Not unknown_track: the track exists, and telling a model it does not sends
+    // it back to search for a track it will find again.
+    "stale_value",
+    "track_not_editable",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/library-select.d.ts

@@ -35,26 +35,23 @@ export declare const LibraryArg: z.ZodOptional<z.ZodString>;
  */
 export declare function pickDefaultLibrary(libs: readonly LibraryInfo[]): LibraryInfo | null;
 /**
- * The supported libraries tied for the default pick -- more than one holding
- * the same, highest track count. Empty when the default is unambiguous, which
- * includes the single-library case every DJ starts from.
+ * The libraries a write must be told apart between: every supported one, as
+ * soon as there is more than one. Empty when there is nothing to choose --
+ * one supported library, or none -- so a DJ with a single library never has
+ * to name it.
  *
- * A tie is not an exotic shape: it is what a USB drive and its copy on the
- * computer produce, and they tie *because* one is a copy of the other.
- * Measured 2026-09-01, both real libraries reported 257 tracks.
+ * This used to ask a narrower question: which libraries *tied* for the
+ * default pick on track count. That was wrong, and measurably so. A USB drive
+ * and its copy tie only until one of them gains a track; at 258 against 257
+ * the tie is gone and `pickDefaultLibrary` silently takes the larger. For a
+ * playlist that is at least visible on the wrong drive. For a track's genre
+ * it is invisible, and the DJ is left believing the edit did not work.
  *
- * For a read, either answer is very nearly the same answer -- the two are
- * copies -- so `pickDefaultLibrary` keeps choosing, and a read never has to
- * name a library it does not care about. For a write the choice decides which
- * physical disk changes, and one of them is the drive the DJ performs from.
- * Hence: reads choose, writes refuse. Callers wanting the strict behaviour
- * check this first.
- *
- * Skips unsupported libraries for the same reason `pickDefaultLibrary` does:
- * one can never be chosen while a supported library exists, so it is not a
- * competing candidate and must not make a write refuse.
+ * The count was never the question. Which physical disk changes is the
+ * caller's to say, and only reads -- which change nothing -- may be spared
+ * the question.
  */
-export declare function defaultLibraryTies(libs: readonly LibraryInfo[]): LibraryInfo[];
+export declare function writeNeedsLibrary(libs: readonly LibraryInfo[]): LibraryInfo[];
 /**
  * The refusal for an ambiguous default on a write.
  *
@@ -84,8 +81,29 @@ export declare function ambiguousLibrary(tied: readonly LibraryInfo[]): EngineEr
  *
  * A path match is exact on the m.db file, not a prefix: a value that merely
  * *contains* a library path must not select it.
+ *
+ * A uuid shared by several libraries resolves to the first of them in this
+ * server's list of known libraries -- root-scan order at startup, arrival
+ * order for a drive plugged in later, but no order a caller can rely on. That
+ * is tolerable for a read, which changes no disk, and never for a write: see
+ * namedWriteLibrary.
  */
 export declare function findLibrary(libs: readonly LibraryInfo[], requested: string): LibraryInfo | null;
+/**
+ * Every library a `library` value names, in the order of `libs`.
+ * More than one only for a uuid: copying an Engine Library folder onto another
+ * drive copies its uuid with it, while each library's path is its own.
+ */
+export declare function findLibraries(libs: readonly LibraryInfo[], requested: string): LibraryInfo[];
+/**
+ * The one library a write names, or the refusal.
+ *
+ * findLibrary would hand back the first of two libraries sharing a uuid, and
+ * which is first is only discovery order -- the very thing ambiguousLibrary
+ * exists so that a write does not rest on. A named uuid is no better an answer
+ * than an omitted `library` when it names both a USB drive and its copy.
+ */
+export declare function namedWriteLibrary(libs: readonly LibraryInfo[], requested: string): LibraryInfo | EngineError;
 /**
  * The error for a `library` value that matched nothing. It names what was
  * passed and lists what is actually selectable, because the two ways to get

package/dist/library-select.js

@@ -14,10 +14,12 @@ import { expandHome, redactPath } from "./paths.js";
  */
 export const LIBRARY_ARG_DESCRIPTION = "Which library to use: either the uuid or the path reported by list_libraries " +
     "(the reported ~/... form is accepted, as is the absolute path). Omit it to use " +
-    "the supported library holding the most tracks. If two supported libraries hold " +
-    "the same most tracks -- what a USB drive and its copy on the computer produce -- " +
-    "a read still picks one, but a WRITE refuses with ambiguous_library listing both, " +
-    "since the choice decides which disk changes; ask the user which, then pass it here.";
+    "the supported library holding the most tracks. A READ may always omit it. A WRITE " +
+    "may omit it only when a single supported library is connected: with two or more, a " +
+    "write refuses with ambiguous_library listing them, since the choice decides which " +
+    "disk changes; ask the user which, then pass it here. A library copied onto another drive " +
+    "keeps its uuid, so a uuid can name two connected libraries: a write naming such a uuid " +
+    "refuses with ambiguous_library as well. Pass the path to write to one of them.";
 export const LibraryArg = z.string().min(1).optional().describe(LIBRARY_ARG_DESCRIPTION);
 /**
  * The default when no `library` was given: the supported library with the
@@ -51,32 +53,25 @@ export function pickDefaultLibrary(libs) {
     return best ?? libs[0] ?? null;
 }
 /**
- * The supported libraries tied for the default pick -- more than one holding
- * the same, highest track count. Empty when the default is unambiguous, which
- * includes the single-library case every DJ starts from.
+ * The libraries a write must be told apart between: every supported one, as
+ * soon as there is more than one. Empty when there is nothing to choose --
+ * one supported library, or none -- so a DJ with a single library never has
+ * to name it.
  *
- * A tie is not an exotic shape: it is what a USB drive and its copy on the
- * computer produce, and they tie *because* one is a copy of the other.
- * Measured 2026-09-01, both real libraries reported 257 tracks.
+ * This used to ask a narrower question: which libraries *tied* for the
+ * default pick on track count. That was wrong, and measurably so. A USB drive
+ * and its copy tie only until one of them gains a track; at 258 against 257
+ * the tie is gone and `pickDefaultLibrary` silently takes the larger. For a
+ * playlist that is at least visible on the wrong drive. For a track's genre
+ * it is invisible, and the DJ is left believing the edit did not work.
  *
- * For a read, either answer is very nearly the same answer -- the two are
- * copies -- so `pickDefaultLibrary` keeps choosing, and a read never has to
- * name a library it does not care about. For a write the choice decides which
- * physical disk changes, and one of them is the drive the DJ performs from.
- * Hence: reads choose, writes refuse. Callers wanting the strict behaviour
- * check this first.
- *
- * Skips unsupported libraries for the same reason `pickDefaultLibrary` does:
- * one can never be chosen while a supported library exists, so it is not a
- * competing candidate and must not make a write refuse.
+ * The count was never the question. Which physical disk changes is the
+ * caller's to say, and only reads -- which change nothing -- may be spared
+ * the question.
  */
-export function defaultLibraryTies(libs) {
+export function writeNeedsLibrary(libs) {
     const supported = libs.filter((l) => l.supported);
-    if (supported.length < 2)
-        return [];
-    const best = Math.max(...supported.map((l) => l.trackCount ?? -1));
-    const tied = supported.filter((l) => (l.trackCount ?? -1) === best);
-    return tied.length > 1 ? tied : [];
+    return supported.length > 1 ? supported : [];
 }
 /**
  * The refusal for an ambiguous default on a write.
@@ -94,10 +89,13 @@ export function defaultLibraryTies(libs) {
  */
 export function ambiguousLibrary(tied) {
     const list = tied.map((l) => `${l.uuid} -- ${redactPath(l.path)} (${l.trackCount} tracks)`).join("; ");
-    return err("ambiguous_library", `More than one library holds the most tracks, so there is no default to write to: ${list}. ` +
-        `Nothing was written. ASK which one to write to, then retry with \`library\` set -- ` +
-        `do not choose for them. These are usually a USB drive and its copy on the computer, ` +
-        `and one of them may be the drive they perform from.`, { detail: "not_committed" });
+    return err("ambiguous_library", `More than one library is connected, so there is no default to write to: ${list}. ` +
+        `Nothing was written. ASK which one to write to, then retry with \`library\` set to that ` +
+        `library's path -- do not choose for them. A copy keeps its uuid, so a uuid may name more ` +
+        `than one of these. They are usually a USB drive and its copy on the computer, ` +
+        `and one of them may be the drive they perform from. A read without \`library\` may have ` +
+        `come from a different one of these, so re-read anything the write depends on (track and ` +
+        `playlist ids, positions, current values) from the chosen library first.`, { detail: "not_committed" });
 }
 /**
  * Resolves a caller-supplied `library` value: uuid first, then filesystem
@@ -113,19 +111,66 @@ export function ambiguousLibrary(tied) {
  *
  * A path match is exact on the m.db file, not a prefix: a value that merely
  * *contains* a library path must not select it.
+ *
+ * A uuid shared by several libraries resolves to the first of them in this
+ * server's list of known libraries -- root-scan order at startup, arrival
+ * order for a drive plugged in later, but no order a caller can rely on. That
+ * is tolerable for a read, which changes no disk, and never for a write: see
+ * namedWriteLibrary.
  */
 export function findLibrary(libs, requested) {
+    return findLibraries(libs, requested)[0] ?? null;
+}
+/**
+ * Every library a `library` value names, in the order of `libs`.
+ * More than one only for a uuid: copying an Engine Library folder onto another
+ * drive copies its uuid with it, while each library's path is its own.
+ */
+export function findLibraries(libs, requested) {
     const wanted = requested.trim();
     if (!wanted)
-        return null;
-    const byUuid = libs.find((l) => l.uuid && l.uuid.toLowerCase() === wanted.toLowerCase());
-    if (byUuid)
+        return [];
+    const byUuid = libs.filter((l) => l.uuid && l.uuid.toLowerCase() === wanted.toLowerCase());
+    if (byUuid.length > 0)
         return byUuid;
     // resolve() turns a relative value into something rooted at the process
     // cwd, which matches no library path -- exactly the intended outcome for
     // a value that is neither a uuid nor a real path.
     const wantedPath = resolve(expandHome(wanted));
-    return libs.find((l) => resolve(l.path) === wantedPath) ?? null;
+    return libs.filter((l) => resolve(l.path) === wantedPath);
+}
+/**
+ * The one library a write names, or the refusal.
+ *
+ * findLibrary would hand back the first of two libraries sharing a uuid, and
+ * which is first is only discovery order -- the very thing ambiguousLibrary
+ * exists so that a write does not rest on. A named uuid is no better an answer
+ * than an omitted `library` when it names both a USB drive and its copy.
+ */
+export function namedWriteLibrary(libs, requested) {
+    const matches = findLibraries(libs, requested);
+    if (matches.length > 1)
+        return sharedUuid(requested, matches);
+    if (matches[0])
+        return matches[0];
+    // The same refusal a read gets, with its list moved into `message`: on a
+    // write `detail` is reserved, for the reason given at ambiguousLibrary.
+    const miss = libraryNotFound(requested, libs);
+    return { ...miss, message: `${miss.message}. ${miss.detail}`, detail: "not_committed" };
+}
+/**
+ * The refusal for a uuid naming more than one library. Lists paths, since the
+ * uuid is the one thing the candidates do not differ in; `detail` stays
+ * exactly "not_committed" for the reason given at ambiguousLibrary.
+ */
+function sharedUuid(requested, matches) {
+    const list = matches.map((l) => `${redactPath(l.path)} (${l.trackCount} tracks)`).join("; ");
+    return err("ambiguous_library", `"${requested.trim()}" names more than one connected library -- a library copied onto another ` +
+        `drive keeps its uuid: ${list}. Nothing was written. ASK which one to write to, then retry ` +
+        `with \`library\` set to that one's path -- do not choose for them. One of them may be the ` +
+        `drive they perform from. A read naming this uuid may have come from another of these copies, ` +
+        `so re-read anything the write depends on (track and playlist ids, positions, current values) ` +
+        `from that path first.`, { detail: "not_committed" });
 }
 /**
  * The error for a `library` value that matched nothing. It names what was