engine-dj-mcp 0.9.1 → 0.10.0

package/dist/server.js

@@ -11,6 +11,7 @@ import { QueryProcess } from "./proc/query-client.js";
 import { IndexManager } from "./store/index-manager.js";
 import { searchTracks, SearchInput } from "./tools/search.js";
 import { getTracks, GetTracksInput } from "./tools/tracks.js";
+import { getPlaylists, GetPlaylistsInput, getPlaylistTracks, GetPlaylistTracksInput, } from "./tools/playlists.js";
 import { getTrackPerformance, PerformanceInput } from "./tools/performance.js";
 import { auditLibrary, AuditInput, AUDIT_CHECKS } from "./tools/audit.js";
 import { runSql, RunSqlInput } from "./tools/sql.js";
@@ -54,9 +55,10 @@ function reply(value) {
  * design (a permissions error on one candidate must not blank out every
  * other one). That means a hot journal on the *only* library on this
  * machine looks identical to no library existing at all -- both come back
- * as an empty list, verified: opening it raises "attempt to write a
- * readonly database", which readLibraryInfo currently folds into
- * unsupported_schema and then drops entirely.
+ * as an empty list, verified: readLibraryInfo (discovery.ts) does report a
+ * hot journal precisely, as library_needs_recovery, but discoverLibraries()
+ * still drops it along with every other unreadable candidate, by that same
+ * design.
  *
  * This walks the same candidate paths independently, purely to tell those
  * two cases apart, so `ready()` below can report library_needs_recovery
@@ -220,18 +222,30 @@ export async function createServer(opts = {}) {
      * null, not as "generation zero". A library nobody has queried yet has no
      * IndexManager at all and reports null for the same reason: listing the
      * libraries must not fork a query child per drive to fill in a number.
+     *
+     * Reads each known IndexManager's generation via peekGeneration(), not
+     * ensureFresh(): ensureFresh() also rebuilds when the library has
+     * changed, which is exactly right for a tool that is about to query the
+     * index and exactly wrong here. list_libraries is what a user reaches
+     * for when something looks broken, and list_libraries re-scans on every
+     * call (see below) -- so making it pay for a first, or renewed, index
+     * build on a big or currently-locked library would make the one
+     * diagnostic tool that must stay fast the one most likely to block.
+     * peekGeneration() only reads the sidecar already on disk, so this stays
+     * honest (a real, current generation number, never a fabricated one) and
+     * never forces work list_libraries does not itself need to answer.
      */
-    const libraryReport = async (discovered) => {
+    const libraryReport = (discovered) => {
         const generations = new Map();
         for (const state of states.values()) {
-            await state.mgr.ensureFresh(); // best effort: keeps a live library's generation accurate
-            if (state.mgr.generation > 0)
-                generations.set(state.lib.uuid, state.mgr.generation);
+            const generation = state.mgr.peekGeneration();
+            if (generation > 0)
+                generations.set(state.lib.uuid, generation);
         }
         return listLibraries(generations, discovered);
     };
     server.registerResource("schema", "engine://schema", { title: "Engine DJ schema and semantics", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, text: SCHEMA_NOTE }] }));
-    server.registerResource("libraries", "engine://libraries", { title: "Discovered Engine DJ libraries", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, text: JSON.stringify(await libraryReport(libs), null, 2) }] }));
+    server.registerResource("libraries", "engine://libraries", { title: "Discovered Engine DJ libraries", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, text: JSON.stringify(libraryReport(libs), null, 2) }] }));
     server.registerTool("search_tracks", {
         title: "Search tracks",
         description: "Search the Engine DJ library by text, tempo, key, rating, play history and analysis " +
@@ -241,6 +255,8 @@ export async function createServer(opts = {}) {
             "flags.has_cues means a hot cue is actually set (the blob is decoded when the index " +
             "is built), not merely that Engine analysed the track; flags.has_beatgrid means a " +
             "beatData blob is present. " +
+            "playlist: {id} or {name} narrows the search to one playlist -- results still come " +
+            "back by relevance or id, not in playlist order; use get_playlist_tracks for that. " +
             LIBRARY_SELECTION_NOTE,
         inputSchema: { ...SearchInput.shape, library: LibraryArg },
         annotations: RO,
@@ -262,19 +278,64 @@ export async function createServer(opts = {}) {
             return reply(state);
         return reply(await getTracks(state.qp, args));
     });
+    server.registerTool("get_playlists", {
+        title: "List playlists",
+        description: "The library's playlist tree, in the order Engine DJ displays it -- taken from the " +
+            "Playlist.nextListId chain, which is where that order actually lives (the PlaylistPath " +
+            "view's `position` column runs the other way). " +
+            "Flat and in pre-order, so reading top to bottom is exactly the sidebar: `depth` and " +
+            "`path` carry the nesting, `parent_id` names the folder. " +
+            "is_folder means the list has child lists (Engine has no folder flag; a folder is a " +
+            "playlist other playlists sit under), so an emptied folder reads as an empty playlist. " +
+            "track_count is entries in that list alone, never rolled up from children, and " +
+            "missing_count is how many of them name a track that is not in this library. " +
+            "`warnings` appears when a link chain is broken or cyclic; nothing is ever dropped " +
+            "from the list because of one. " +
+            LIBRARY_SELECTION_NOTE,
+        inputSchema: { ...GetPlaylistsInput.shape, library: LibraryArg },
+        annotations: RO,
+    }, async (args) => {
+        const state = await acquire(args.library);
+        if (isEngineError(state))
+            return reply(state);
+        return reply(await getPlaylists(state.qp, args));
+    });
+    server.registerTool("get_playlist_tracks", {
+        title: "Get the tracks in a playlist",
+        description: "The tracks of one playlist, in playlist order -- from the PlaylistEntity.nextEntityId " +
+            "chain, not from row ids, so a track dragged up the list comes back where the DJ put it. " +
+            "Name the playlist with playlist_id, or with playlist_name (exactly one of the two). A " +
+            "name that matches several playlists is refused with every candidate's id and full path " +
+            "rather than picked between -- names are unique only within a folder, so pass the full " +
+            "`path` from get_playlists to disambiguate. " +
+            "Each row carries `position`, its 1-based place in the playlist. An entry whose track is " +
+            "not in this library comes back as { position, entry_id, track_id, missing: true } and " +
+            "keeps its slot, so entry_count still matches the playlist's own length; missing_count " +
+            "says how many of those there are. That is ordinary, not corruption -- entries outlive " +
+            "their tracks and arrive from other drives (see audit_library's orphan_entries). " +
+            "Same fields, limit and cursor conventions as search_tracks. " +
+            LIBRARY_SELECTION_NOTE,
+        inputSchema: { ...GetPlaylistTracksInput.shape, library: LibraryArg },
+        annotations: RO,
+    }, async (args) => {
+        const state = await acquire(args.library);
+        if (isEngineError(state))
+            return reply(state);
+        return reply(await getPlaylistTracks(state.qp, args));
+    });
     server.registerTool("get_track_performance", {
         title: "Get cues, loops and beatgrid",
         description: "Decode PerformanceData for one track: hot cues, the main cue, saved loops, the " +
             "beatgrid and a coarse waveform profile. Each field carries its own decode status " +
             "and its own layout marker. " +
-            "layout: \"verified\" (cues, beatgrid, waveform_summary) means the binary layout was " +
+            "layout: \"verified\" (every field) means the binary layout was " +
             "confirmed against a real Engine DJ library -- cue positions land inside the track, " +
-            "the beatgrid's implied tempo matches the analysed BPM, and the waveform's declared " +
-            "point spacing multiplies back out to the track's sample count -- so status: \"ok\" " +
-            "there is a claim about the values, not just about the parse. " +
-            "layout: \"unverified\" (loops) still means only that the bytes parsed: the loop slot " +
-            "structure is known, but no library was available with a loop actually saved, so " +
-            "loop bounds must not be reported to a user as fact. " +
+            "the beatgrid's implied tempo matches the analysed BPM, the waveform's declared " +
+            "point spacing multiplies back out to the track's sample count, and a saved loop " +
+            "spans a whole number of beats at that same analysed BPM -- so status: \"ok\" " +
+            "is a claim about the values, not just about the parse. " +
+            "layout: \"unverified\" would mean only that the bytes parsed; no field returns it " +
+            "today. " +
             "Positions are sample offsets; sample_rate at the top level converts them to " +
             "seconds, and cue/loop items carry the seconds already. Only hot-cue and loop slots " +
             "that hold something are listed -- slots is how many the track has in total, so " +
@@ -335,7 +396,7 @@ export async function createServer(opts = {}) {
             "library; without it they use the supported library holding the most tracks.",
         inputSchema: {},
         annotations: RO,
-    }, async () => reply(await libraryReport(rescanLibraries())));
+    }, async () => reply(libraryReport(rescanLibraries())));
     server.registerTool("refresh_index", {
         title: "Refresh the search index",
         description: "Rebuild the search index if the library has changed. " + LIBRARY_SELECTION_NOTE,
@@ -387,8 +448,9 @@ Tables live in \`m.db\` (attached as \`main\`); the search index lives in \`side
 More than one library can be connected at once — the local one under
 \`~/Music\` and one per USB drive. \`list_libraries\` reports each with a
 \`uuid\` and a \`path\`, and every tool that reads library data
-(\`search_tracks\`, \`get_tracks\`, \`get_track_performance\`,
-\`audit_library\`, \`run_sql\`, \`refresh_index\`) takes an optional
+(\`search_tracks\`, \`get_tracks\`, \`get_playlists\`,
+\`get_playlist_tracks\`, \`get_track_performance\`, \`audit_library\`,
+\`run_sql\`, \`refresh_index\`) takes an optional
 \`library\` argument naming one of them: either the \`uuid\` or the
 \`path\`, in the \`~/...\` form \`list_libraries\` prints or the absolute
 one. A value matching neither comes back as \`library_not_found\` listing
@@ -417,8 +479,6 @@ 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 \`~\`.
-- Playlists are singly linked lists: order lives in \`Playlist.nextListId\`
-  and \`PlaylistEntity.nextEntityId\`, not in any position column.
 - 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
@@ -428,6 +488,41 @@ other.
   \`get_track_performance\` decodes one track's blobs; for the whole library,
   \`side.track_derived.has_cues\` below holds the decoded answer.
 
+## Playlists
+Order is a **singly linked list**, in both directions of the structure, and
+there is no position column anywhere:
+- \`Playlist.nextListId\` orders sibling lists within one \`parentListId\`.
+- \`PlaylistEntity.nextEntityId\` orders the entries within one \`listId\`.
+Both chains terminate at \`0\`.
+
+The schema ships a \`PlaylistPath\` view with a column named \`position\`.
+**Do not use it for display order.** Its \`OrderedList\` CTE anchors on
+\`WHERE nextListId = 0\` and counts upwards from the *tail*, so ordering by
+it yields the sidebar reversed — measured on a real library of 16 playlists,
+\`PlaylistPath\` order is exactly the reverse of the chain, and the chain is
+what Engine DJ draws. \`get_playlists\` and \`get_playlist_tracks\` walk the
+chains; write the same recursive walk if you go via \`run_sql\`, and never
+\`ORDER BY id\` — ids happen to agree with the chain until the first time
+someone drags a track up a playlist.
+
+Nesting is \`Playlist.parentListId\` (\`0\` at the top level). There is no
+folder flag: an Engine folder is just a \`Playlist\` row that other rows
+name as their parent. \`Playlist.isPersisted\` marks a list saved to the
+device rather than a transient one; both values occur on lists Engine
+displays, so nothing is filtered on it. Titles are unique only within a
+parent (\`UNIQUE (title, parentListId)\`), so a bare name can match several
+playlists — the full \`path\` \`get_playlists\` reports is unique.
+
+\`PlaylistEntity.trackId\` may name a track that is not in this library:
+entries outlive their tracks and travel between drives (\`databaseUuid\`
+records which library an entry came from). On the reference library 105 of
+202 entries are such holes. \`audit_library\`'s \`orphan_entries\` counts
+them; \`get_playlist_tracks\` keeps them in place, flagged \`missing\`.
+
+Rule-based **smartlists** live in a separate \`Smartlist\` table, keyed by
+uuid with its own \`nextListUuid\` ordering and a JSON \`rules\` column.
+Nothing here reads it — a smartlist is not reported by \`get_playlists\`.
+
 ## SQL functions
 Registered on the query connection, all deterministic:
 \`camelot(key)\`, \`key_name(key)\`, \`tempo(bpmAnalyzed, bpm)\`,

package/dist/store/index-manager.d.ts

@@ -25,5 +25,17 @@ export declare class IndexManager {
     constructor(lib: LibraryInfo, qp: QueryProcess, baseDir?: string);
     get generation(): number;
     get path(): string;
+    /**
+     * The generation of whatever index currently exists on disk, read
+     * directly from the sidecar's own index_meta table -- never built,
+     * rebuilt or attached. This is the cheap half of ensureFresh() (the part
+     * that does not open the main library at all), used by list_libraries so
+     * that asking "what libraries do I have" is never the call that pays for
+     * a first (or renewed) index build: that cost belongs to whichever tool
+     * call actually needs a fresh index, through ensureFresh(). Returns 0,
+     * the same "not a real generation" value ensureFresh() reports before
+     * ever building one, when no usable sidecar exists yet.
+     */
+    peekGeneration(): number;
     ensureFresh(): Promise<FreshResult | EngineError>;
 }

package/dist/store/index-manager.js

@@ -33,6 +33,21 @@ export class IndexManager {
     get path() {
         return join(this.baseDir, this.lib.uuid, "index.db");
     }
+    /**
+     * The generation of whatever index currently exists on disk, read
+     * directly from the sidecar's own index_meta table -- never built,
+     * rebuilt or attached. This is the cheap half of ensureFresh() (the part
+     * that does not open the main library at all), used by list_libraries so
+     * that asking "what libraries do I have" is never the call that pays for
+     * a first (or renewed) index build: that cost belongs to whichever tool
+     * call actually needs a fresh index, through ensureFresh(). Returns 0,
+     * the same "not a real generation" value ensureFresh() reports before
+     * ever building one, when no usable sidecar exists yet.
+     */
+    peekGeneration() {
+        this.#storedCounter();
+        return this.#generation;
+    }
     /**
      * The change counter the sidecar on disk was built from, or null when
      * there is no usable sidecar — which forces a rebuild.

package/dist/tools/audit.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { z } from "zod";
 import { err, isEngineError } from "../errors.js";
 import { absTrackPath } from "../paths.js";
+import { ENTRY_TRACK_MATCH } from "../playlists.js";
 export const AUDIT_CHECKS = [
     "missing_files",
     "unavailable",
@@ -83,9 +84,19 @@ const SQL_CHECKS = {
              WHERE artist IS NOT NULL AND title IS NOT NULL
              GROUP BY 1 HAVING COUNT(*) > 1)`,
     },
+    // "No track answers to this entry" — asked on the natural key
+    // `(databaseUuid, trackId)` -> `(originDatabaseUuid, originTrackId)`, never
+    // on `Track.id`. ENTRY_TRACK_MATCH carries the measurement: on the
+    // reference library the id join reported 105 orphans of 202 entries on a
+    // library that has none, which is this check's whole user-visible failure
+    // mode — a DJ told their playlists are full of holes.
+    //
+    // NOT EXISTS rather than a LEFT JOIN so the count is entries, not matched
+    // pairs, whatever the file on disk happens to contain.
     orphan_entries: {
         id: "e.id",
-        body: `FROM PlaylistEntity e LEFT JOIN Track t ON t.id = e.trackId WHERE t.id IS NULL`,
+        body: `FROM PlaylistEntity e
+           WHERE NOT EXISTS (SELECT 1 FROM Track t WHERE ${ENTRY_TRACK_MATCH})`,
     },
 };
 export async function auditLibrary(qp, mdbPath, raw) {

package/dist/tools/playlists.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { type EngineError } from "../errors.js";
+import { type PlaylistItem } from "../playlists.js";
+import type { QueryProcess } from "../proc/query-client.js";
+export declare const GetPlaylistsInput: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type GetPlaylistsInput = z.input<typeof GetPlaylistsInput>;
+export interface GetPlaylistsResult {
+    playlists: PlaylistItem[];
+    total: number;
+    truncated: boolean;
+    warnings?: string[];
+}
+/**
+ * The library's playlist tree, in the order Engine DJ displays it.
+ *
+ * Flat, in pre-order, with `depth` and `path` carrying the nesting -- see
+ * buildPlaylistTree for why that beats nested `children` arrays here.
+ */
+export declare function getPlaylists(qp: QueryProcess, raw: GetPlaylistsInput): Promise<GetPlaylistsResult | EngineError>;
+export declare const GetPlaylistTracksInput: z.ZodObject<{
+    playlist_id: z.ZodOptional<z.ZodNumber>;
+    playlist_name: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    redact_paths: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GetPlaylistTracksInput = z.input<typeof GetPlaylistTracksInput>;
+/**
+ * A row of a playlist. Either a track (the requested `fields`, plus its
+ * position) or a hole where a track used to be.
+ *
+ * A hole is a real, ordinary state, not corruption: `PlaylistEntity` rows
+ * survive their track, which is why `audit_library` has an `orphan_entries`
+ * check at all. What a hole is *not* is an entry that merely came from
+ * another drive — those resolve perfectly well through the natural key (see
+ * ENTRY_TRACK_MATCH), and on the reference USB library all 202 entries do,
+ * including the 178 stamped with a third library's uuid.
+ *
+ * Genuine holes are kept in the list rather than filtered out, at their real
+ * positions, precisely so `tracks.length` still equals the playlist's own
+ * length and position 12 is still the twelfth thing the DJ sees in Engine.
+ * Dropping them would make a 43-entry playlist silently return fewer rows
+ * and look like a paging bug.
+ */
+export type PlaylistTrackRow = Record<string, unknown>;
+export interface GetPlaylistTracksResult {
+    playlist: PlaylistItem;
+    tracks: PlaylistTrackRow[];
+    /** Entries in the whole playlist, not in this page. */
+    entry_count: number;
+    /** Entries in the whole playlist whose track is not in this library. */
+    missing_count: number;
+    next_cursor?: string;
+    warnings?: string[];
+}
+export declare function getPlaylistTracks(qp: QueryProcess, raw: GetPlaylistTracksInput): Promise<GetPlaylistTracksResult | EngineError>;

package/dist/tools/playlists.js

@@ -0,0 +1,206 @@
+// 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";
+/**
+ * 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
+ * context, so it is a cap rather than "everything".
+ */
+const MAX_PLAYLIST_PAGE = 1000;
+/** Matches search_tracks: the largest page of tracks any tool will return. */
+const MAX_TRACK_LIMIT = 200;
+export const GetPlaylistsInput = z.object({
+    limit: z.number().int().positive().default(200),
+});
+/**
+ * The library's playlist tree, in the order Engine DJ displays it.
+ *
+ * Flat, in pre-order, with `depth` and `path` carrying the nesting -- see
+ * buildPlaylistTree for why that beats nested `children` arrays here.
+ */
+export async function getPlaylists(qp, raw) {
+    const parsed = GetPlaylistsInput.safeParse(raw);
+    if (!parsed.success)
+        return err("invalid_argument", "limit must be a positive integer");
+    const limit = Math.min(parsed.data.limit, MAX_PLAYLIST_PAGE);
+    const tree = await loadPlaylistTree(qp);
+    if (isEngineError(tree))
+        return tree;
+    const playlists = tree.items.slice(0, limit);
+    // Two independent reasons the answer can be short: more playlists exist
+    // than this page holds, and more exist than loadPlaylistTree would read at
+    // all. Both mean "this is not the whole tree", so both set the same flag.
+    const truncated = tree.truncated || playlists.length < tree.items.length;
+    return {
+        playlists,
+        total: tree.total,
+        truncated,
+        ...(tree.warnings.length ? { warnings: tree.warnings } : {}),
+    };
+}
+export const GetPlaylistTracksInput = z.object({
+    playlist_id: z.number().int().positive().optional(),
+    playlist_name: z.string().min(1).optional(),
+    fields: z.array(z.string()).optional(),
+    limit: z.number().int().positive().default(25),
+    cursor: z.string().optional(),
+    redact_paths: z.boolean().default(true),
+});
+/**
+ * A cursor here is just "resume at position N of playlist P".
+ *
+ * It carries the playlist id so a cursor from one playlist cannot page
+ * through another: unlike search_tracks, whose cursor encodes a keyset that
+ * could be silently misapplied to a different filter set, position N means
+ * something in every playlist, so the wrong-playlist mistake would page
+ * perfectly happily through the wrong list.
+ */
+function encodeCursor(playlistId, position) {
+    return Buffer.from(JSON.stringify([playlistId, position])).toString("base64url");
+}
+/**
+ * A track's natural key, flattened for use as a Map key.
+ *
+ * `\u0000` cannot occur inside an Engine uuid, so no two distinct pairs
+ * flatten to the same string — which a plain `uuid + trackId` concatenation
+ * could not promise.
+ */
+function entryKey(databaseUuid, trackId) {
+    return `${databaseUuid}\u0000${trackId}`;
+}
+function decodeCursor(cursor) {
+    try {
+        const v = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!Array.isArray(v) || v.length !== 2)
+            return null;
+        const [listId, position] = v;
+        if (typeof listId !== "number" || typeof position !== "number")
+            return null;
+        if (!Number.isInteger(listId) || !Number.isInteger(position) || position < 1)
+            return null;
+        return [listId, position];
+    }
+    catch {
+        return null;
+    }
+}
+export async function getPlaylistTracks(qp, raw) {
+    const parsed = GetPlaylistTracksInput.safeParse(raw);
+    if (!parsed.success) {
+        return err("invalid_argument", "Invalid arguments for get_playlist_tracks", {
+            detail: parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "),
+        });
+    }
+    const input = parsed.data;
+    // Same allowlist and same two failure messages as search_tracks and
+    // get_tracks: a field name becomes SQL text, so it is checked against
+    // FIELD_SQL rather than interpolated, and an empty list is a named error
+    // instead of a raw SQLite syntax error.
+    const requestedFields = input.fields ?? [...DEFAULT_FIELDS];
+    if (requestedFields.length === 0)
+        return err("invalid_argument", "No fields requested");
+    const unknownFields = requestedFields.filter((f) => !(f in FIELD_SQL));
+    if (unknownFields.length) {
+        return err("invalid_argument", `Unknown field(s): ${unknownFields.join(", ")}`, {
+            detail: `Recognised fields: ${Object.keys(FIELD_SQL).join(", ")}`,
+        });
+    }
+    const fields = requestedFields;
+    const resolved = await resolvePlaylist(qp, { id: input.playlist_id, name: input.playlist_name });
+    if (isEngineError(resolved))
+        return resolved;
+    const playlist = resolved.playlist;
+    let from = 1;
+    if (input.cursor) {
+        const cur = decodeCursor(input.cursor);
+        if (!cur)
+            return err("invalid_argument", "Malformed cursor");
+        if (cur[0] !== playlist.id) {
+            return err("invalid_argument", "This cursor belongs to a different playlist. Page with the playlist it came from, " +
+                "or start again without a cursor.");
+        }
+        from = cur[1];
+    }
+    const ordered = await loadPlaylistEntries(qp, playlist);
+    if (isEngineError(ordered))
+        return ordered;
+    const limit = Math.min(input.limit, MAX_TRACK_LIMIT);
+    const page = ordered.entries.slice(from - 1, from - 1 + limit);
+    // One lookup for the page, then reordered in memory -- SQL has no ordering
+    // to offer here, since playlist order lives in a linked list and not in
+    // any column that could appear in ORDER BY.
+    //
+    // Looked up by the natural key (see ENTRY_TRACK_MATCH), never by Track.id.
+    // An entry's `trackId` is a row id in *its own* library, so on a drive that
+    // has travelled -- which is the ordinary case -- resolving it as a local id
+    // finds nothing for most entries and, where a foreign id happens to collide
+    // with a local one, confidently returns an entirely different track.
+    //
+    // An entry with no databaseUuid is skipped rather than bound: SQL equality
+    // never matches NULL, so it is a hole by construction and a bind slot spent
+    // on it could only find the wrong row.
+    const wanted = new Map();
+    for (const e of page) {
+        if (e.trackId > 0 && e.databaseUuid !== null) {
+            wanted.set(entryKey(e.databaseUuid, e.trackId), { uuid: e.databaseUuid, trackId: e.trackId });
+        }
+    }
+    const byKey = new Map();
+    if (wanted.size) {
+        const keys = [...wanted.values()];
+        const select = fields.map((f) => `${FIELD_SQL[f]} AS "${f}"`).join(", ");
+        const res = await qp.run(`SELECT ${select}, t.originDatabaseUuid AS __uuid, t.originTrackId AS __origin
+         FROM main.Track t JOIN side.track_derived d ON d.track_id = t.id
+        WHERE (t.originDatabaseUuid, t.originTrackId)
+              IN (VALUES ${keys.map(() => "(?,?)").join(",")})`, keys.flatMap((k) => [k.uuid, k.trackId]));
+        if (isEngineError(res))
+            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,
+                ];
+            }));
+            byKey.set(entryKey(String(row[idx.__uuid]), Number(row[idx.__origin])), track);
+        }
+    }
+    const tracks = page.map((entry) => {
+        const track = entry.databaseUuid === null ? undefined : byKey.get(entryKey(entry.databaseUuid, entry.trackId));
+        return track
+            ? { position: entry.position, ...track }
+            : {
+                position: entry.position,
+                entry_id: entry.id,
+                // Both halves of the key, because neither is meaningful alone:
+                // track_id is a row id in the library database_uuid names, and the
+                // same number means a different track in every other library.
+                track_id: entry.trackId,
+                database_uuid: entry.databaseUuid,
+                // Named, not implied by absent fields: a model must be able to tell
+                // "this slot has no track in this library" from "this track has no
+                // artist tag".
+                missing: true,
+            };
+    });
+    const last = page[page.length - 1];
+    const next_cursor = last && last.position < ordered.entries.length
+        ? encodeCursor(playlist.id, last.position + 1)
+        : undefined;
+    const warnings = [...resolved.warnings, ...ordered.warnings];
+    return {
+        playlist,
+        tracks,
+        entry_count: ordered.entries.length,
+        missing_count: playlist.missing_count,
+        ...(next_cursor ? { next_cursor } : {}),
+        ...(warnings.length ? { warnings } : {}),
+    };
+}

package/dist/tools/search.d.ts

@@ -30,6 +30,10 @@ export declare const SearchInput: z.ZodObject<{
         min: z.ZodOptional<z.ZodNumber>;
         max: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    playlist: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     played: z.ZodOptional<z.ZodObject<{
         never: z.ZodOptional<z.ZodBoolean>;
         before: z.ZodOptional<z.ZodString>;
@@ -57,4 +61,10 @@ export declare function searchTracks(qp: QueryProcess, raw: SearchInput): Promis
     total?: number;
     total_capped?: boolean;
     next_cursor?: string;
+    /** Echoed only when the playlist filter was used: which list it resolved to. */
+    playlist?: {
+        id: number;
+        name: string;
+        path: string;
+    };
 } | EngineError>;

package/dist/tools/search.js

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { err, isEngineError } from "../errors.js";
 import { camelotNeighbours } from "../semantics.js";
 import { redactPath } 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;
 /**
@@ -65,6 +66,29 @@ export const SearchInput = z.object({
     })
         .optional(),
     rating: z.object({ min: z.number().optional(), max: z.number().optional() }).optional(),
+    /**
+     * Restricts the search to one playlist.
+     *
+     * An object, like every other filter here (`bpm`, `key`, `rating`,
+     * `played`, `added`, `flags`), rather than a flat `playlist_id` /
+     * `playlist_name` pair as get_playlist_tracks uses: this schema's shape is
+     * "one named object per dimension you can narrow on", each grouping its own
+     * alternative ways of expressing that dimension -- exactly what id-or-name
+     * is. Two more top-level keys would put playlist selection at a different
+     * altitude from every other filter and leave no room to grow (an
+     * `exclude` sits naturally inside this object; `playlist_exclude` does
+     * not). get_playlist_tracks is flat for the opposite reason: there the
+     * playlist is the subject of the call, not one filter among eight.
+     *
+     * Ordering is unaffected -- results still come back by relevance or id, not
+     * in playlist order. get_playlist_tracks is the tool that preserves order.
+     */
+    playlist: z
+        .object({
+        id: z.number().int().positive().optional(),
+        name: z.string().min(1).optional(),
+    })
+        .optional(),
     played: z
         .object({
         never: z.boolean().optional(),
@@ -183,6 +207,39 @@ export async function searchTracks(qp, raw) {
         filterWhere.push("f.fts_track MATCH ?");
         filterParams.push(sanitizeFtsQuery(input.q));
     }
+    // Resolved to an id before the SQL is built, so an unknown or ambiguous
+    // name comes back as the same actionable error get_playlist_tracks gives
+    // (naming every candidate), rather than as an empty result set that reads
+    // like "you own nothing at 128 BPM in that playlist".
+    //
+    // The subquery is a semi-join on PlaylistEntity, not a join: a track
+    // appears once in a playlist (UNIQUE (listId, databaseUuid, trackId)), but
+    // an entry may point at a track that is gone, and joining would then be
+    // one more way for row counts to drift. Membership is the whole question
+    // here.
+    //
+    // It matches on the natural key (see ENTRY_TRACK_MATCH), not on
+    // `t.id = e.trackId`: an entry made on another drive carries that drive's
+    // track id, so the id form both drops the playlist's real members and
+    // admits unrelated local tracks whose row id happens to collide with a
+    // foreign one.
+    let resolvedPlaylist;
+    if (input.playlist) {
+        const resolved = await resolvePlaylist(qp, input.playlist, {
+            id: "playlist.id",
+            name: "playlist.name",
+        });
+        if (isEngineError(resolved))
+            return resolved;
+        resolvedPlaylist = {
+            id: resolved.playlist.id,
+            name: resolved.playlist.name,
+            path: resolved.playlist.path,
+        };
+        filterWhere.push(`EXISTS (SELECT 1 FROM main.PlaylistEntity e
+                WHERE e.listId = ? AND ${ENTRY_TRACK_MATCH})`);
+        filterParams.push(resolved.playlist.id);
+    }
     if (input.bpm) {
         // Key and tempo filters go through the indexed side.track_derived
         // columns (d.tempo / d.camelot below), never through the camelot() or
@@ -322,6 +379,7 @@ export async function searchTracks(qp, raw) {
     }
     return {
         tracks,
+        ...(resolvedPlaylist ? { playlist: resolvedPlaylist } : {}),
         ...(total !== undefined ? { total, total_capped } : {}),
         ...(next_cursor ? { next_cursor } : {}),
     };