engine-dj-mcp 0.12.0 → 0.15.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.15.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;
@@ -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`
 
@@ -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,43 @@ 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.
 
+### 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 two libraries tie for the default. Lists both — 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 +387,26 @@ 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.
+
+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
@@ -418,9 +470,49 @@ 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.** Engine DJ
+moves playlist changes between connected libraries by itself, so a copy of
+your edit can 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,6 +523,13 @@ 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

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"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export interface EngineError {
     error: ErrorCode;

package/dist/errors.js

@@ -33,6 +33,12 @@ 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",
 ];
 export function err(error, message, extra = {}) {
     return { error, message, ...extra };

package/dist/library-select.d.ts

@@ -34,6 +34,42 @@ export declare const LibraryArg: z.ZodOptional<z.ZodString>;
  * supported library" would otherwise collapse into.
  */
 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function defaultLibraryTies(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. 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.";
 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,55 @@ 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function defaultLibraryTies(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 : [];
+}
+/**
+ * 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 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" });
+}
 /**
  * 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)));

package/dist/server.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { discoverLibraries, defaultRoots, probeLibraries } from "./discovery.js";
 import { libraryCandidates, libraryTag, sidecarDir } from "./paths.js";
-import { LibraryArg, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
+import { LibraryArg, ambiguousLibrary, defaultLibraryTies, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
 import { hasHotJournal } from "./store/connections.js";
 import { QueryProcess } from "./proc/query-client.js";
 import { IndexManager } from "./store/index-manager.js";
@@ -56,9 +56,34 @@ const PACKAGE_INFO = JSON.parse(readFileSync(new URL("../package.json", import.m
  * this repeats the essentials in the description because some clients show a
  * model the description and not the per-property schema documentation.
  */
+/**
+ * Every write result names the library it landed in, and every undo is scoped
+ * to that one library. Engine DJ propagates a playlist change to another
+ * connected library by itself -- measured 2026-09-01: an edit made to the
+ * library on the computer appeared on the USB drive after Engine was next
+ * launched, the copy carrying the very timestamp this server's INSERT had
+ * written. An undo call cannot reach that copy, and reports success anyway,
+ * because within its own library it did exactly what it promised.
+ *
+ * Stated in the description, not just the README, because the caller who has
+ * to act on it is the model holding the undo.
+ */
+const UNDO_SCOPE_NOTE = "`undo` reverses this edit in ONE library: the one the result's `library` field names. " +
+    "Engine DJ copies playlist changes between connected libraries on its own, so launching it " +
+    "with a second library attached can leave a copy of this edit there -- and no undo call " +
+    "reaches that copy. With two libraries connected (a USB drive and its copy on the computer " +
+    "is the usual case), undo separately against each. ";
 const LIBRARY_SELECTION_NOTE = "With more than one library connected, pass `library` (a uuid or path from list_libraries, " +
     "either the ~/... form or the absolute one) to choose which one; the default is the " +
     "supported library with the most tracks.";
+/**
+ * Appended to the write tools only. A tie in the default rule is a refusal
+ * there and a free choice on the read side, so the shared note above cannot
+ * carry it without being wrong for one of the two.
+ */
+const WRITE_LIBRARY_TIE_NOTE = " If two supported libraries hold the same most tracks -- what a USB drive and its copy on " +
+    "the computer produce -- this tool refuses with ambiguous_library rather than picking one, " +
+    "and lists both; nothing is written. Ask the user which one, then retry with `library` set -- do not pick for them, since one of the two may be the drive they perform from.";
 function reply(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -222,6 +247,47 @@ export async function createServer(opts = {}) {
             return state;
         return fresh;
     };
+    /**
+     * `acquire` for the write tools: identical, except that an omitted
+     * `library` must resolve to exactly one candidate.
+     *
+     * `pickDefaultLibrary` breaks a tie on root-scan order, which is
+     * deterministic and, for a read, fine -- libraries tie because one is a
+     * copy of the other, so either answer is very nearly the same answer, and
+     * making a read demand a `library` it does not care about would be noise.
+     *
+     * A write is not that. The choice decides which physical disk changes, and
+     * one of the two is the drive the DJ performs from; root-scan order is not
+     * a reason to pick it. Measured 2026-09-01: the computer's library and the
+     * USB drive both held 257 tracks, tied precisely because one was a copy of
+     * the other.
+     *
+     * Only the omitted case refuses. A caller who named a library gets it, tie
+     * or no tie -- the ambiguity being refused here is the server's, not theirs.
+     *
+     * Rescans first, because `knownList()` is a cache that deliberately keeps a
+     * library a later scan cannot see -- so a momentarily locked drive does not
+     * vanish from list_libraries. For a tie check that is wrong in the
+     * direction that bites: pull the USB drive and one library is left, but the
+     * cache still holds two, and the write is refused naming a drive that is no
+     * longer there. rescanLibraries() forgets a candidate whose path is gone,
+     * which is exactly the distinction wanted here, and it also lets a drive
+     * plugged in mid-session be seen at all.
+     *
+     * The cost is one filesystem probe per write, against a write that is about
+     * to copy the entire database for its pre-write snapshot. Reads are left
+     * alone: they run far more often and a stale pick between two copies is not
+     * worth a probe apiece.
+     */
+    const acquireForWrite = async (requested) => {
+        if (requested === undefined) {
+            rescanLibraries();
+            const tied = defaultLibraryTies(knownList());
+            if (tied.length > 1)
+                return ambiguousLibrary(tied);
+        }
+        return acquire(requested);
+    };
     /**
      * Shared by the engine://libraries resource and the list_libraries tool so
      * the two cannot drift in shape, while differing in exactly one respect:
@@ -371,6 +437,10 @@ export async function createServer(opts = {}) {
         title: "Audit the collection",
         description: `Run collection health checks. Available: ${AUDIT_CHECKS.join(", ")}. ` +
             `missing_files resolves each track against the selected library's own folder. ` +
+            `path_form_mismatch finds files that are there, but under a name in a different Unicode ` +
+            `normalization form from the stored path -- macOS opens them anyway, Linux does not ` +
+            `(measured on its exFAT driver), and Engine OS on a player is Linux, so these may fail ` +
+            `to load on hardware while missing_files on a Mac reports nothing. ` +
             `no_cues means "no hot cue is set" -- the quickCues blob is decoded for this, since ` +
             `Engine writes one to every analysed track whether or not a pad is used -- while ` +
             `no_beatgrid means the beatData blob is absent or empty. ` +
@@ -443,6 +513,10 @@ 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). " +
+                "The result's `library` field names which library this went into. Engine DJ copies " +
+                "playlist changes between connected libraries on its own (measured for an edit to an " +
+                "existing playlist), so with a second library attached the new playlist may appear " +
+                "there too. " +
                 "No existing playlist is renamed, reordered, emptied or deleted, and no track, cue or " +
                 "beatgrid is touched. The one existing row that moves is the previous last playlist's " +
                 "link, and Engine's own insert trigger is what moves it. " +
@@ -453,11 +527,11 @@ export async function createServer(opts = {}) {
                 "library is unchanged and \"committed_unverified\" when the write may have gone " +
                 "through but could not be verified. track_ids may be empty (an empty playlist); a " +
                 "track id may appear at most once. " +
-                LIBRARY_SELECTION_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
             inputSchema: { ...CreatePlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
-            const state = await acquire(args.library);
+            const state = await acquireForWrite(args.library);
             if (isEngineError(state))
                 return reply(state);
             return reply(await runCreatePlaylist(state.lib.path, state.lib.uuid, args, opts.backupBaseDir ?? join(homedir(), ".engine-dj-mcp", "backups")));
@@ -486,11 +560,12 @@ export async function createServer(opts = {}) {
                 "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,
+                UNDO_SCOPE_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
             inputSchema: { ...AddTracksToPlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
-            const state = await acquire(args.library);
+            const state = await acquireForWrite(args.library);
             if (isEngineError(state))
                 return reply(state);
             return reply(await runAddTracksToPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
@@ -524,11 +599,12 @@ export async function createServer(opts = {}) {
                 "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,
+                UNDO_SCOPE_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
             inputSchema: { ...RemoveTracksFromPlaylistInput.shape, library: LibraryArg },
             annotations: RW_DESTRUCTIVE,
         }, async (args) => {
-            const state = await acquire(args.library);
+            const state = await acquireForWrite(args.library);
             if (isEngineError(state))
                 return reply(state);
             return reply(await runRemoveTracksFromPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
@@ -550,11 +626,12 @@ export async function createServer(opts = {}) {
                 "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,
+                UNDO_SCOPE_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
             inputSchema: { ...ReorderPlaylistInput.shape, library: LibraryArg },
             annotations: RW_DESTRUCTIVE,
         }, async (args) => {
-            const state = await acquire(args.library);
+            const state = await acquireForWrite(args.library);
             if (isEngineError(state))
                 return reply(state);
             return reply(await runReorderPlaylist(state.qp, state.lib.path, state.lib.uuid, args, backupDirFor()));
@@ -630,6 +707,18 @@ other.
 - \`Track.path\` is relative to the \`Engine Library\` folder and usually
   contains \`..\`. The SQL function \`abs_path(path)\` resolves it against
   this library's location; the home prefix comes back folded to \`~\`.
+- \`Track.streamingSource\`, \`uri\` and \`streamingFlags\` are reported to
+  decide whether Engine OS streams a track (from Dropbox) instead of reading
+  the file. Not measured here: on both reference libraries \`streamingSource\`
+  and \`uri\` are NULL on every track, and \`streamingFlags\` is 5 on about
+  half of them -- tracks that load and play -- so \`streamingFlags\` on its own
+  says nothing about whether a track will load. Selectable as the fields
+  \`streaming_source\`, \`streaming_flags\` and \`uri\`; \`uri\` is redacted like
+  \`path\`, including a home directory percent-encoded inside it.
+- SQLite's \`LOWER()\` folds ASCII only: \`LOWER('ЭЙФОРИЯ')\` comes back
+  unchanged. To compare names regardless of case in any script, use
+  \`fold(text)\` -- one Unicode normalization form, lower-cased by Unicode
+  rules. It runs per row, like every function here.
 - A track's natural key across drives is \`(originDatabaseUuid, originTrackId)\`.
 - \`PerformanceData\`'s blob columns are binary and cannot be read with SQL.
   Engine writes \`quickCues\`, \`loops\`, \`beatData\` and

package/dist/store/backup.d.ts

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

package/dist/store/backup.js

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

package/dist/store/write.d.ts

@@ -4,8 +4,24 @@ export interface CreatePlaylistResult {
     playlist_id: number;
     title: string;
     tracks_added: number;
+    library: LibraryRef;
     backup_path: string;
 }
+/**
+ * Which library a write actually landed in. Two connected libraries -- a USB
+ * drive and its copy on the computer -- is the ordinary setup, so "which one
+ * did that go to" is a question every write result has to answer on its own,
+ * without the caller re-deriving it from an argument it may not have passed.
+ *
+ * It is also the context `undo` needs: an undo reverses the edit in this
+ * library and cannot reach a copy Engine DJ has since propagated to another
+ * one (measured 2026-09-01, see README).
+ */
+export interface LibraryRef {
+    uuid: string;
+    /** The m.db path, in the `~/...` form list_libraries prints. */
+    path: string;
+}
 /**
  * What editing an existing playlist's entries returns. One shape for
  * add/remove/reorder alike -- each op leaves the fields it did not touch
@@ -37,6 +53,7 @@ export interface EditResult {
     undo_complete: boolean;
     /** Set only when `undo_complete` is false: which positions have no way back, and why. */
     undo_note?: string;
+    library: LibraryRef;
     backup_path: string;
 }
 /** One step of the tool call that would undo an edit, in the shape a client replays it. */

package/dist/store/write.js

@@ -14,6 +14,7 @@ import { DatabaseSync } from "node:sqlite";
 import { err, isEngineError, libraryNeedsRecovery } from "../errors.js";
 import { snapshotLibrary } from "./backup.js";
 import { hasHotJournal } from "./connections.js";
+import { redactPath } from "../paths.js";
 /**
  * `detail` discriminator values for the EngineError this module returns.
  * Stable across releases so a caller can decide "is the library still what
@@ -449,7 +450,10 @@ async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
         const verifyErr = verifyAfterCommit(db, subject, backupPath);
         if (verifyErr)
             return verifyErr;
-        return { ...result, backup_path: backupPath };
+        // Filled in here, alongside backup_path, for the same reason: it is the
+        // one place that knows the write succeeded, and doing it per-op would let
+        // a new op ship without it.
+        return { ...result, library: { uuid, path: redactPath(mdbPath) }, backup_path: backupPath };
     }
     catch (e) {
         return classifyWriteFailure(e, commit, subject, mdbPath, backupPath, db, open);
@@ -1157,8 +1161,10 @@ export async function reorderPlaylist(mdbPath, uuid, input, opts) {
     return withWriteTransaction(mdbPath, uuid, subject, opts, (db) => {
         // Re-read: BEGIN IMMEDIATE is the first moment nothing else can change
         // the chain, and gating on the pre-check's read alone would be trusting
-        // one that could already be stale.
-        const gate = gateChain(db, listId);
+        // one that could already be stale. Read once and kept: the links rewritten
+        // below are exactly the ones this check passed, not a second read of them.
+        const rows = readChain(db, listId);
+        const gate = checkChain(rows);
         if (!gate.ok) {
             rollback(db);
             return err("playlist_chain_damaged", `Playlist ${listId}: ${gate.reason}. Nothing was changed.`, {
@@ -1183,7 +1189,7 @@ export async function reorderPlaylist(mdbPath, uuid, input, opts) {
         // returns; each entry's new successor is the id that follows it there,
         // or 0 for the new tail.
         const newSeq = requestedOrder.map((p) => gate.order[p - 1]);
-        const currentNext = new Map(readChain(db, listId).map((r) => [r.id, r.next]));
+        const currentNext = new Map(rows.map((r) => [r.id, r.next]));
         const link = db.prepare("UPDATE PlaylistEntity SET nextEntityId = ? WHERE id = ?");
         for (let i = 0; i < newSeq.length; i++) {
             const entryId = newSeq[i];

package/dist/tools/audit.d.ts

@@ -1,7 +1,35 @@
 import { z } from "zod";
 import { type EngineError } from "../errors.js";
 import type { QueryProcess } from "../proc/query-client.js";
-export declare const AUDIT_CHECKS: readonly ["missing_files", "unavailable", "unanalyzed", "no_cues", "no_beatgrid", "missing_key", "suspicious_bpm", "duplicates", "empty_metadata", "orphan_entries"];
+export declare const AUDIT_CHECKS: readonly ["missing_files", "unavailable", "unanalyzed", "no_cues", "no_beatgrid", "missing_key", "suspicious_bpm", "duplicates", "empty_metadata", "orphan_entries", "path_form_mismatch"];
+/**
+ * The checks that read the filesystem rather than the database: each needs
+ * the stored paths themselves, and each answers something no SQL can.
+ */
+export declare const FILESYSTEM_CHECKS: readonly ["missing_files", "path_form_mismatch"];
+/**
+ * Whether a stored path resolves on disk only by ignoring Unicode
+ * normalization.
+ *
+ * Measured 2026-09-11 on Linux 6.17's in-kernel exFAT driver: a path in NFC
+ * does not find a file whose name was written in NFD, while a path that
+ * differs only in case does. macOS forgives both, which is why missing_files
+ * -- asking the host's own lookup -- reports nothing on a Mac for a file that
+ * Linux, and so plausibly Engine OS on a player, would not open. On the
+ * maintainer's USB drive that was 8 tracks: file and folder names macOS wrote
+ * in NFD behind the NFC paths Engine stored.
+ *
+ * Walks the path one component at a time against the real listings, so it
+ * answers the same on every host. A component matching exactly, or in case
+ * only, is fine -- exFAT and Windows ignore case, so reporting it would be
+ * noise. One found only when both sides are brought to NFC marks the path.
+ * One not found at all ends the walk unmarked: that file is missing, which is
+ * missing_files' business, not this check's.
+ *
+ * `listDir` is injected so the comparison can be exercised against an exact
+ * listing on any host; the audit passes a cached readdirSync.
+ */
+export declare function onlyFoundByIgnoringForm(absPath: string, listDir: (dir: string) => string[] | null): boolean;
 export declare const AuditInput: z.ZodObject<{
     checks: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;

package/dist/tools/audit.js

@@ -1,5 +1,6 @@
 // src/tools/audit.ts
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { join, parse, sep } from "node:path";
 import { z } from "zod";
 import { err, isEngineError } from "../errors.js";
 import { absTrackPath } from "../paths.js";
@@ -15,7 +16,56 @@ export const AUDIT_CHECKS = [
     "duplicates",
     "empty_metadata",
     "orphan_entries",
+    "path_form_mismatch",
 ];
+/**
+ * The checks that read the filesystem rather than the database: each needs
+ * the stored paths themselves, and each answers something no SQL can.
+ */
+export const FILESYSTEM_CHECKS = ["missing_files", "path_form_mismatch"];
+/**
+ * Whether a stored path resolves on disk only by ignoring Unicode
+ * normalization.
+ *
+ * Measured 2026-09-11 on Linux 6.17's in-kernel exFAT driver: a path in NFC
+ * does not find a file whose name was written in NFD, while a path that
+ * differs only in case does. macOS forgives both, which is why missing_files
+ * -- asking the host's own lookup -- reports nothing on a Mac for a file that
+ * Linux, and so plausibly Engine OS on a player, would not open. On the
+ * maintainer's USB drive that was 8 tracks: file and folder names macOS wrote
+ * in NFD behind the NFC paths Engine stored.
+ *
+ * Walks the path one component at a time against the real listings, so it
+ * answers the same on every host. A component matching exactly, or in case
+ * only, is fine -- exFAT and Windows ignore case, so reporting it would be
+ * noise. One found only when both sides are brought to NFC marks the path.
+ * One not found at all ends the walk unmarked: that file is missing, which is
+ * missing_files' business, not this check's.
+ *
+ * `listDir` is injected so the comparison can be exercised against an exact
+ * listing on any host; the audit passes a cached readdirSync.
+ */
+export function onlyFoundByIgnoringForm(absPath, listDir) {
+    const { root } = parse(absPath);
+    let dir = root;
+    let formDiffered = false;
+    for (const want of absPath.slice(root.length).split(sep).filter(Boolean)) {
+        const names = listDir(dir);
+        if (!names)
+            return false;
+        const upper = want.toUpperCase();
+        let hit = names.find((n) => n === want) ?? names.find((n) => n.toUpperCase() === upper);
+        if (hit === undefined) {
+            const key = want.normalize("NFC").toUpperCase();
+            hit = names.find((n) => n.normalize("NFC").toUpperCase() === key);
+            if (hit === undefined)
+                return false;
+            formDiffered = true;
+        }
+        dir = join(dir, hit);
+    }
+    return formDiffered;
+}
 export const AuditInput = z.object({ checks: z.array(z.string()).optional() });
 /**
  * Counts plus a small sample, never rows: this result lands in an LLM's
@@ -79,8 +129,10 @@ const SQL_CHECKS = {
     },
     duplicates: {
         id: "t.id",
-        body: `FROM Track t WHERE LOWER(TRIM(t.artist)) || '|' || LOWER(TRIM(t.title)) IN (
-             SELECT LOWER(TRIM(artist)) || '|' || LOWER(TRIM(title)) FROM Track
+        // fold(), not LOWER(): LOWER is ASCII-only, so a Cyrillic title and the
+        // same title in capitals were not grouped (#9). See semantics.ts.
+        body: `FROM Track t WHERE fold(TRIM(t.artist)) || '|' || fold(TRIM(t.title)) IN (
+             SELECT fold(TRIM(artist)) || '|' || fold(TRIM(title)) FROM Track
              WHERE artist IS NOT NULL AND title IS NOT NULL
              GROUP BY 1 HAVING COUNT(*) > 1)`,
     },
@@ -138,6 +190,33 @@ export async function auditLibrary(qp, mdbPath, raw) {
             out.push({ name, count: missing.length, sample_ids: missing.slice(0, SAMPLE) });
             continue;
         }
+        if (name === "path_form_mismatch") {
+            // Only a path with a character outside printable ASCII can have a second
+            // normalization form, so only those cross the process boundary -- 22 of
+            // 257 on the reference library -- and each directory is listed once.
+            const res = await qp.run(`SELECT id, path FROM Track WHERE path GLOB '*[^ -~]*' ORDER BY id`);
+            if (isEngineError(res))
+                return res;
+            const listings = new Map();
+            const listDir = (d) => {
+                if (!listings.has(d)) {
+                    try {
+                        listings.set(d, readdirSync(d));
+                    }
+                    catch {
+                        listings.set(d, null);
+                    }
+                }
+                return listings.get(d);
+            };
+            const marked = [];
+            for (const row of res.rows) {
+                if (onlyFoundByIgnoringForm(absTrackPath(mdbPath, String(row[1])), listDir))
+                    marked.push(Number(row[0]));
+            }
+            out.push({ name, count: marked.length, sample_ids: marked.slice(0, SAMPLE) });
+            continue;
+        }
         const check = SQL_CHECKS[name];
         const counted = await qp.run(`SELECT COUNT(*) AS c ${check.body}`);
         if (isEngineError(counted))

package/dist/tools/playlists.js

@@ -1,9 +1,8 @@
 // src/tools/playlists.ts
 import { z } from "zod";
 import { err, isEngineError } from "../errors.js";
-import { redactPath } from "../paths.js";
 import { loadPlaylistEntries, loadPlaylistTree, resolvePlaylist, } from "../playlists.js";
-import { DEFAULT_FIELDS, FIELD_SQL } from "./search.js";
+import { DEFAULT_FIELDS, FIELD_SQL, presentField } from "./search.js";
 /**
  * Playlists returned in one call. Higher than any real library needs (the
  * reference library has 16) but the result still goes into a model's
@@ -160,15 +159,7 @@ export async function getPlaylistTracks(qp, raw) {
             return res;
         const idx = Object.fromEntries(res.columns.map((c, i) => [c, i]));
         for (const row of res.rows) {
-            const track = Object.fromEntries(fields.map((f) => {
-                const value = row[idx[f]];
-                return [
-                    f,
-                    input.redact_paths && f === "path" && typeof value === "string"
-                        ? redactPath(value)
-                        : value,
-                ];
-            }));
+            const track = Object.fromEntries(fields.map((f) => [f, presentField(f, row[idx[f]], input.redact_paths)]));
             byKey.set(entryKey(String(row[idx.__uuid]), Number(row[idx.__origin])), track);
         }
     }

package/dist/tools/search.d.ts

@@ -10,6 +10,13 @@ export declare const DEFAULT_FIELDS: readonly ["id", "artist", "title", "bpm", "
  * validating fields can never drift from this one.
  */
 export declare const FIELD_SQL: Record<string, string>;
+/**
+ * How one projected value is handed back. The single place a path-bearing
+ * field is redacted: search_tracks, get_tracks and get_playlist_tracks each
+ * carried their own copy of the `path` check, which is how a new path-bearing
+ * field ends up redacted in two of the three.
+ */
+export declare function presentField(field: string, value: unknown, redact: boolean): unknown;
 export declare const SearchInput: z.ZodObject<{
     q: z.ZodOptional<z.ZodString>;
     bpm: z.ZodOptional<z.ZodObject<{

package/dist/tools/search.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { createHash } from "node:crypto";
 import { err, isEngineError } from "../errors.js";
 import { camelotNeighbours } from "../semantics.js";
-import { redactPath } from "../paths.js";
+import { redactPath, redactUri } from "../paths.js";
 import { ENTRY_TRACK_MATCH, resolvePlaylist } from "../playlists.js";
 export const DEFAULT_FIELDS = ["id", "artist", "title", "bpm", "camelot", "rating"];
 const MAX_LIMIT = 200;
@@ -47,7 +47,29 @@ export const FIELD_SQL = {
     date_added: "t.dateAdded",
     last_played: "t.timeLastPlayed",
     is_analyzed: "t.isAnalyzed",
+    // Reported to decide whether Engine OS streams a track (from Dropbox)
+    // rather than reading it from disk -- not measured here: NULL, NULL and a
+    // mix of NULL/0/5 on both reference libraries, whose tracks all load. Opt-in
+    // only, for diagnosing a track that will not load (#8).
+    streaming_source: "t.streamingSource",
+    streaming_flags: "t.streamingFlags",
+    uri: "t.uri",
 };
+/**
+ * How one projected value is handed back. The single place a path-bearing
+ * field is redacted: search_tracks, get_tracks and get_playlist_tracks each
+ * carried their own copy of the `path` check, which is how a new path-bearing
+ * field ends up redacted in two of the three.
+ */
+export function presentField(field, value, redact) {
+    if (!redact || typeof value !== "string")
+        return value;
+    if (field === "path")
+        return redactPath(value);
+    if (field === "uri")
+        return redactUri(value);
+    return value;
+}
 export const SearchInput = z.object({
     q: z.string().optional(),
     bpm: z
@@ -354,12 +376,7 @@ export async function searchTracks(qp, raw) {
     if (isEngineError(res))
         return res;
     const idx = Object.fromEntries(res.columns.map((c, i) => [c, i]));
-    const tracks = res.rows.map((row) => Object.fromEntries(fields.map((f) => {
-        const value = row[idx[f]];
-        return [f, input.redact_paths && f === "path" && typeof value === "string"
-                ? redactPath(value)
-                : value];
-    })));
+    const tracks = res.rows.map((row) => Object.fromEntries(fields.map((f) => [f, presentField(f, row[idx[f]], input.redact_paths)])));
     let next_cursor;
     if (res.rows.length === limit) {
         const last = res.rows[res.rows.length - 1];

package/dist/tools/tracks.js

@@ -1,8 +1,7 @@
 // src/tools/tracks.ts
 import { z } from "zod";
 import { err, isEngineError } from "../errors.js";
-import { DEFAULT_FIELDS, FIELD_SQL } from "./search.js";
-import { redactPath } from "../paths.js";
+import { DEFAULT_FIELDS, FIELD_SQL, presentField } from "./search.js";
 export const GetTracksInput = z.object({
     ids: z.array(z.number().int().positive()).min(1).max(200),
     fields: z.array(z.string()).optional(),
@@ -38,10 +37,7 @@ export async function getTracks(qp, raw) {
     const idx = Object.fromEntries(res.columns.map((c, i) => [c, i]));
     const byId = new Map();
     for (const row of res.rows) {
-        const track = Object.fromEntries(fields.map((f) => {
-            const value = row[idx[f]];
-            return [f, redact_paths && f === "path" && typeof value === "string" ? redactPath(value) : value];
-        }));
+        const track = Object.fromEntries(fields.map((f) => [f, presentField(f, row[idx[f]], redact_paths)]));
         byId.set(Number(row[idx.__id]), track);
     }
     // Preserve the caller's ordering; missing ids are simply absent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engine-dj-mcp",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "description": "MCP server for an Engine DJ library: search and audit it, read cues and beatgrids, and build playlists when you ask. Not affiliated with inMusic or Denon DJ.",
   "keywords": [
     "mcp",