engine-dj-mcp 0.12.0 → 0.17.0

package/README.md

@@ -54,11 +54,15 @@ the configuration you are reading:
 ```json
 {
   "mcpServers": {
-    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp", "--allow-writes"] }
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp@0.17.0", "--allow-writes"] }
   }
 }
 ```
 
+Pin the version in this one. Unpinned, `npx` fetches whatever is newest at
+every launch, and this configuration gives that code write access to your
+library. Pinned, a new release reaches it only when you change the number.
+
 **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;
@@ -83,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). |
@@ -156,7 +160,7 @@ Positions are sample offsets; cue and loop items also carry seconds.
 
 ### `audit_library`
 
-Ten collection health checks. Returns a count and a small sample of ids per
+Eleven collection health checks. Returns a count and a small sample of ids per
 check, never the full result set — a library with thousands of unanalysed
 tracks should not fill an assistant's context.
 
@@ -169,11 +173,12 @@ tracks should not fill an assistant's context.
 | `no_beatgrid` | Tracks with no beatgrid data |
 | `missing_key` | Tracks with no key detected |
 | `suspicious_bpm` | Analysed and tagged tempo disagree, or tempo is outside 60–200 |
-| `duplicates` | Same artist and title, or same size and length |
+| `duplicates` | Same artist and title, compared regardless of case in any script |
 | `empty_metadata` | No artist or no title |
 | `orphan_entries` | Playlist entries pointing at tracks not in this library — `get_playlist_tracks` shows where each one sits |
+| `path_form_mismatch` | The file is on disk, but its name there — or a folder's on the way — is in a different Unicode form from the path Engine stored. macOS finds it anyway; Linux does not (measured on the kernel's exFAT driver), and Engine OS on a player is Linux, so these may fail to load on hardware. Differences in case alone are not counted: exFAT and Windows ignore case |
 
-`checks` — omit it to run all ten.
+`checks` — omit it to run all eleven.
 
 ### `run_sql`
 
@@ -205,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
@@ -224,19 +229,14 @@ Each entry stores the track's origin identity — `(originDatabaseUuid,
 originTrackId)`, the pair Engine matches on — not the local row id, so a
 playlist built here reads the same way Engine's own does.
 
-The result carries `playlist_id`, `tracks_added` and `backup_path`. **To undo
+The result carries `playlist_id`, `tracks_added`, `library` and `backup_path`. **To undo
 it, delete the playlist in Engine DJ**; `backup_path` is a whole-library
 snapshot for the case where something went wrong at a lower level, not an
 undo — see [Restoring a snapshot](#restoring-a-snapshot).
 
-Refusals name themselves: `playlist_exists` for a taken title,
-`unknown_track` for an id this library does not have, `duplicate_track` for
-the same id twice, `library_busy` if something else holds a conflicting lock
-right then, `library_needs_recovery` if Engine DJ left an unrecovered
-journal behind. Every error also carries `detail`: `not_committed` means the
-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`.
+Its own refusals: `playlist_exists` for a taken title, `unknown_track` for an
+id this library does not have, `duplicate_track` for the same id twice — plus
+the ones [every write tool shares](#refusals-every-write-tool-shares).
 
 ### `add_tracks_to_playlist`
 
@@ -258,15 +258,18 @@ way.
 | `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
+new tracks landed — `undo`, `undo_complete` (always `true` here), `library`
+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.
+see [Restoring a snapshot](#restoring-a-snapshot), and
+[An undo covers one library](#an-undo-covers-one-library) for what it does
+not reach. Its own refusals: `playlist_not_found`, `playlist_chain_damaged`,
+`invalid_position`, and `unknown_track` / `duplicate_track` as for
+`create_playlist` — plus the ones
+[every write tool shares](#refusals-every-write-tool-shares).
 
 ### `remove_tracks_from_playlist`
 
@@ -282,8 +285,8 @@ repaired.
 | `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,
+position's `track_id`, `null` for a missing one — `undo`, `undo_complete`,
+`library` 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
@@ -297,9 +300,10 @@ have, so no `add_tracks_to_playlist` call can put it back, and an
 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
+Its own 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.
+does not hold what `expect_track_ids` expected — plus the ones
+[every write tool shares](#refusals-every-write-tool-shares).
 
 `playlist_chain_damaged` always means the same thing for all three edit
 tools: the playlist's entry chain was already broken **before** the edit,
@@ -323,15 +327,103 @@ repaired.
 | `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`,
+here), `library` and `backup_path`. `undo` is the exact inverse permutation, as a single
+`reorder_playlist` call. Its own refusals: `playlist_not_found`,
 `playlist_chain_damaged`, and `invalid_position` if `order` is not a full
-permutation of the playlist's current positions.
+permutation of the playlist's current positions — plus the ones
+[every write tool shares](#refusals-every-write-tool-shares).
 
 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,
+bringing its index up to date, resolving the playlist — and from the write's
+own checks.
+
+| Code | Means | Nothing written? |
+| --- | --- | --- |
+| `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 more than one supported library is connected. 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 |
+| `index_stale` | The index could not be built yet, typically because Engine holds a lock on a first run. Carries `retry_after_ms`. | yes |
+| `query_timeout`, `query_process_crashed` | The lookup that resolves a playlist failed. Edit tools only. | yes |
+| `library_unreadable` | The library could not be read; the snapshot taken before the first write could not be made (a full disk, or a Node older than 22.16); or a write's own read-back disagreed with what it wrote, and it was rolled back. | see `detail` |
+
+**`detail` on these errors.** Once the write itself has started, `detail` is
+exactly one of two strings, and a client can read it to decide whether the
+library changed: `not_committed` — the library is what it was — or
+`committed_unverified` — the rare one: the write may have landed but could not
+be confirmed, and only this case hands back a `backup_path`. Refusals raised
+*before* that point — every row above marked "yes" — never opened the library
+for writing, whatever their `detail` says: it may be absent, `not_committed`,
+or explanatory text such as the candidates an ambiguous `playlist_name` lists.
+
 ## Resources
 
 - **`engine://schema`** — the field semantics an assistant needs before
@@ -355,6 +447,28 @@ 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.
 
+That rule is enough for a read, which changes nothing: with two libraries
+connected a read picks one, and the `library` field in the result says 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.
+
+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,
+which puts the write back on an arbitrary disk and makes the refusal
+pointless.
+
 Each library gets its own index and its own connection, opened the first time
 you ask that library something. Comparing two libraries against each other —
 *"what is on this drive but not that one?"* — is **not** something this server
@@ -373,20 +487,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
@@ -418,9 +536,56 @@ and without `--allow-writes` not even this.
 The write takes SQLite's own write lock for the length of one transaction and
 does not wait for it: if something else — Engine DJ mid-save, a player — is
 holding a conflicting lock at that moment, the write is refused with
-`library_busy` and nothing is changed. Merely having Engine DJ *open* is not
-usually a conflict, and the write normally succeeds with Engine running;
-Engine will show the new playlist after it next re-reads the library.
+`library_busy` and nothing is changed.
+
+**Quit Engine DJ before writing.** Having Engine open is not usually a lock
+conflict, so the write itself will normally go through — but what Engine then
+does with a change made underneath it has never been measured here. Every
+acceptance check of a write was run with Engine closed. What *has* been
+measured is that Engine does its own work on the library as it loads: it
+renumbers playlist entries, and it copies playlist changes to another
+connected library (see below). Quit, write, relaunch — Engine reads the
+library on startup and shows the change.
+
+Quit, not close. On macOS, closing Engine's window leaves the application
+running: observed 2026-09-01 with the main process and seven
+`OfflineAnalyzer` workers — which write to the database — still alive
+afterwards. Use ⌘Q.
+
+### An undo covers one library
+
+Every write result carries a `library` field — the `uuid` and `path` of the
+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.** 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
+same playlist on the USB came back with the same track added — the copy
+carrying the very `lastEditTime` this server's `INSERT` had written. The
+`undo` was then run and reversed the edit on the computer. The USB kept it.
+
+Nothing was damaged: both libraries stayed sound. But the two had diverged,
+and the `undo` reported success, correctly, because within its own library it
+did exactly what it promised.
+
+So: if a second library is connected, look at the `library` field, and undo
+against each library separately. Undoing before Engine DJ next runs avoids
+the problem entirely.
+
+Which library a change propagates to, and in which direction, is Engine's own
+business — this project does not model it and will not guess at it.
 
 ### Restoring a snapshot
 
@@ -431,12 +596,19 @@ 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"`.
 
+Snapshots live in `~/.engine-dj-mcp/backups/`, ten per library. Only a name
+ending in `.db` is a snapshot. A file ending in `.partial-<number>` — with or
+without `-journal` after it — is a copy still being written, or one whose
+process died before it finished: **never restore one of those**. A copy is
+renamed to its `.db` name only once it is complete, and an abandoned one is
+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"];
+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,6 +33,20 @@ 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.
+    "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

@@ -34,6 +34,39 @@ export declare const LibraryArg: z.ZodOptional<z.ZodString>;
  * supported library" would otherwise collapse into.
  */
 export declare function pickDefaultLibrary(libs: readonly LibraryInfo[]): LibraryInfo | null;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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 writeNeedsLibrary(libs: readonly LibraryInfo[]): LibraryInfo[];
+/**
+ * The refusal for an ambiguous default on a write.
+ *
+ * Every candidate is named, with its track count, because the caller has to
+ * pick one and cannot do that from "it was ambiguous" -- the same reason
+ * get_playlist_tracks lists candidates for an ambiguous playlist name.
+ *
+ * The list goes in `message`, never in `detail`. This is only ever returned
+ * from a write tool, and on that path `detail` carries exactly
+ * `"not_committed"` or `"committed_unverified"` -- a client reads it to
+ * decide whether its library changed. Prose there would break that read for
+ * the one error whose answer is least in doubt: nothing was opened, let alone
+ * written.
+ */
+export declare function ambiguousLibrary(tied: readonly LibraryInfo[]): EngineError;
 /**
  * Resolves a caller-supplied `library` value: uuid first, then filesystem
  * path. Returns null when it matches neither -- the caller decides what

package/dist/library-select.js

@@ -14,7 +14,10 @@ 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.";
+    "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.";
 export const LibraryArg = z.string().min(1).optional().describe(LIBRARY_ARG_DESCRIPTION);
 /**
  * The default when no `library` was given: the supported library with the
@@ -47,6 +50,48 @@ export function pickDefaultLibrary(libs) {
     }
     return best ?? libs[0] ?? null;
 }
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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 writeNeedsLibrary(libs) {
+    const supported = libs.filter((l) => l.supported);
+    return supported.length > 1 ? supported : [];
+}
+/**
+ * The refusal for an ambiguous default on a write.
+ *
+ * Every candidate is named, with its track count, because the caller has to
+ * pick one and cannot do that from "it was ambiguous" -- the same reason
+ * get_playlist_tracks lists candidates for an ambiguous playlist name.
+ *
+ * The list goes in `message`, never in `detail`. This is only ever returned
+ * from a write tool, and on that path `detail` carries exactly
+ * `"not_committed"` or `"committed_unverified"` -- a client reads it to
+ * decide whether its library changed. Prose there would break that read for
+ * the one error whose answer is least in doubt: nothing was opened, let alone
+ * written.
+ */
+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 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 -- ` +
+        `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" });
+}
 /**
  * Resolves a caller-supplied `library` value: uuid first, then filesystem
  * path. Returns null when it matches neither -- the caller decides what

package/dist/paths.d.ts

@@ -19,6 +19,17 @@ export declare function libraryCandidates(root: string): string[];
  * shipped to a model provider, so the home prefix is folded to `~` by default.
  */
 export declare function redactPath(p: string): string;
+/**
+ * redactPath for a URI. A uri carries its path after a scheme and usually
+ * percent-encoded -- the home directory shows up as `%2FUsers%2F<name>`, not
+ * as a leading `/Users/<name>` -- so redactPath's prefix check would never fire
+ * on one, and a "redacted" uri would leak exactly what redaction is there to
+ * hide. Folds every occurrence, raw or encoded, either case of hex digit since
+ * encoders differ. Only a whole path component: the home directory must be
+ * followed by a separator or the end, so a sibling account whose name merely
+ * starts the same is left alone.
+ */
+export declare function redactUri(u: string): string;
 /**
  * The inverse of redactPath, for values coming back *in*. Every library path
  * this server reports has been through redactPath, so the most obvious way

package/dist/paths.js

@@ -34,6 +34,26 @@ export function redactPath(p) {
     const home = homedir();
     return p === home || p.startsWith(home + "/") ? "~" + p.slice(home.length) : p;
 }
+/**
+ * redactPath for a URI. A uri carries its path after a scheme and usually
+ * percent-encoded -- the home directory shows up as `%2FUsers%2F<name>`, not
+ * as a leading `/Users/<name>` -- so redactPath's prefix check would never fire
+ * on one, and a "redacted" uri would leak exactly what redaction is there to
+ * hide. Folds every occurrence, raw or encoded, either case of hex digit since
+ * encoders differ. Only a whole path component: the home directory must be
+ * followed by a separator or the end, so a sibling account whose name merely
+ * starts the same is left alone.
+ */
+export function redactUri(u) {
+    const home = homedir();
+    if (!home || home === "/")
+        return u;
+    const esc = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const raw = new RegExp(`${esc(home)}(?=/|$)`, "g");
+    const encoded = esc(encodeURIComponent(home)).replace(/%([0-9A-F])([0-9A-F])/g, (_, a, b) => `%[${a}${a.toLowerCase()}][${b}${b.toLowerCase()}]`);
+    const enc = new RegExp(`${encoded}(?=%2[Ff]|$)`, "g");
+    return u.replace(raw, "~").replace(enc, "~");
+}
 /**
  * The inverse of redactPath, for values coming back *in*. Every library path
  * this server reports has been through redactPath, so the most obvious way

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)));