engine-dj-mcp 0.12.0 → 0.17.0

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, writeNeedsLibrary, 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";
@@ -18,6 +18,7 @@ import { runSql, RunSqlInput } from "./tools/sql.js";
 import { listLibraries } from "./tools/libraries.js";
 import { refreshIndex } from "./tools/refresh.js";
 import { CreatePlaylistInput, runCreatePlaylist, AddTracksToPlaylistInput, runAddTracksToPlaylist, RemoveTracksFromPlaylistInput, runRemoveTracksFromPlaylist, ReorderPlaylistInput, runReorderPlaylist, } from "./tools/write-playlist.js";
+import { UpdateTrackMetadataInput, runUpdateTrackMetadata } from "./tools/write-track-metadata.js";
 import { err, isEngineError, libraryNeedsRecovery } from "./errors.js";
 const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
 /**
@@ -35,6 +36,12 @@ const RW = { readOnlyHint: false, destructiveHint: false, idempotentHint: false
  * additive told a client it need not ask before calling.
  */
 const RW_DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false };
+/**
+ * A write that overwrites or clears what is there -- so destructive -- but
+ * that a repeat of the same call leaves alone: a track already holding the
+ * requested values is not written again. update_track_metadata.
+ */
+const RW_OVERWRITE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true };
 /**
  * name/version reported to every client on initialize. Read from
  * package.json rather than typed here, so the two cannot re-diverge the way
@@ -56,9 +63,48 @@ 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. More than one library 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_NOTE = " With two or more supported libraries connected, this tool refuses with ambiguous_library " +
+    "rather than picking one, and lists them; nothing is written. That is so whatever their track " +
+    "counts are -- the count never said which disk should change. Ask the user which one, then " +
+    "retry with `library` set; do not pick for them, since one of them may be the drive they " +
+    "perform from.";
+/**
+ * Not UNDO_SCOPE_NOTE: that one says Engine copies *playlist* changes between
+ * libraries, which was measured. For track tags, a fresh Engine launch was
+ * measured NOT copying a tag edit made on the USB library to the computer's
+ * library (spec §3.9); the other direction has not been measured for tags,
+ * so repeating the playlist claim here would state a guess as fact.
+ */
+const TRACK_UNDO_NOTE = "`undo` reverses this edit in ONE library: the one the result's `library` field names, and each " +
+    "undo step carries it. It restores the values of the fields that changed; it does not restore " +
+    "lastEditTime, which Engine DJ's own trigger sets on every edit. Keep the undo from the first " +
+    "response: repeating a call that already succeeded finds nothing to change and returns an empty " +
+    "undo. For work spread over several calls, replay their undos in REVERSE order. ";
 function reply(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
@@ -222,6 +268,59 @@ 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.
+     */
+    /**
+     * The library a write may land in, without touching its search index. A
+     * tool that addresses tracks by id needs no index, and building one right
+     * before a write only makes it stale the moment the write commits.
+     * acquireForWrite adds the index for the tools that resolve playlists.
+     */
+    const selectForWrite = (requested) => {
+        if (requested === undefined) {
+            rescanLibraries();
+            const choices = writeNeedsLibrary(knownList());
+            if (choices.length > 0)
+                return ambiguousLibrary(choices);
+        }
+        return selectLibrary(requested);
+    };
+    const acquireForWrite = async (requested) => {
+        const lib = selectForWrite(requested);
+        if (isEngineError(lib))
+            return lib;
+        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 +470,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 +546,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 +560,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_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 +593,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_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 +632,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_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,15 +659,51 @@ 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_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()));
         });
+        server.registerTool("update_track_metadata", {
+            title: "Edit track tags",
+            description: "Change genre, comment, label, year or rating on tracks in this Engine DJ library -- the " +
+                "values Engine shows in its columns. This WRITES to the library's database, not to the audio " +
+                "files' tags. Each entry names a track by id (from search_tracks or get_tracks) and only the " +
+                'fields to change; "" clears a text field; rating_stars is 0-5 (Engine stores 0-100). Up to ' +
+                "200 tracks per call, all or nothing. A track already holding the requested values is left " +
+                "alone and counted in `unchanged`; `changed` lists which fields changed on which tracks. " +
+                "Each refusal names every offending track of its kind -- invalid_argument, unknown_track, " +
+                "track_not_editable (the track cannot be edited without harm -- say so to the user and leave it; " +
+                "do not search for it again), stale_value -- and kinds are reported one at a time, in that order: " +
+                "fix the one reported first and retry to see the next, if any -- except stale_value, which is not " +
+                "something to just retry: see below. stale_value means the track " +
+                "changed after the values in `expect` were read; tell the user which tracks and fields changed. " +
+                "Do NOT rebuild `expect` from a fresh read to force the write -- that would silently overwrite " +
+                "an edit the DJ made since, without their consent. " +
+                "Search results may keep showing the old values while Engine DJ holds the library open; " +
+                "refresh_index cannot help until Engine lets go. " +
+                TRACK_UNDO_NOTE +
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
+            inputSchema: { ...UpdateTrackMetadataInput.shape, library: LibraryArg },
+            annotations: RW_OVERWRITE,
+        }, async (args) => {
+            const lib = selectForWrite(args.library);
+            if (isEngineError(lib))
+                return reply(lib);
+            // ensureFresh is what refuses an unsupported schema for every other
+            // tool; this path skips it, so it must refuse here.
+            if (!lib.supported) {
+                return reply(err("unsupported_schema", `Schema ${lib.schema.join(".")} is not supported`, {
+                    detail: "Supported versions are 3.0.0, 3.0.1 and 3.0.2",
+                }));
+            }
+            return reply(await runUpdateTrackMetadata(lib.path, lib.uuid, args, backupDirFor()));
+        });
     }
     /**
      * There was previously no way to shut this down at all: createServer
@@ -627,9 +772,33 @@ other.
   \`bpmAnalyzed\` to within 0.68, and Engine's own interface displays 102 for
   the track stored as 102). \`side.track_derived.tempo\` holds the resolved
   value and is indexed.
+- \`Track.rating\` is 0, 20, 40, 60, 80 or 100 -- one step per star, measured
+  against Engine's own display. The \`rating\` field returns it as stored and
+  \`rating_stars\` returns 0..5; the \`rating\` **filter** takes stars. A value
+  from other software (ID3's POPM is 0..255) is kept exactly in \`rating\` and
+  rounded to the nearest star in \`rating_stars\`.
 - \`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.
+- \`Track\` carries two Engine triggers. \`trigger_after_update_only_Track_timestamp\`
+  sets \`lastEditTime\` (epoch seconds) whenever genre, comment, label, year,
+  rating or a dozen other columns are updated -- even to the same value.
+  \`trigger_after_update_Track_fix_origin\` fires on ANY update and rewrites an
+  empty \`(originDatabaseUuid, originTrackId)\` to this library's uuid and the
+  track's own id; in SQLite \`'' = 0\` is false, so a TEXT '' originTrackId does
+  not count as empty.
 - 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/track-metadata-plan.d.ts

@@ -0,0 +1,82 @@
+import { type EngineError } from "../errors.js";
+export type FieldName = "genre" | "comment" | "label" | "year" | "rating";
+export declare const TEXT_FIELDS: readonly ["genre", "comment", "label"];
+export type TextField = (typeof TEXT_FIELDS)[number];
+export interface TrackExpect {
+    genre?: string;
+    comment?: string;
+    label?: string;
+    year?: number;
+    rating_raw?: number;
+}
+export interface TrackUpdate {
+    id: number;
+    genre?: string;
+    comment?: string;
+    label?: string;
+    year?: number;
+    rating_stars?: number;
+    rating_raw?: number;
+    expect?: TrackExpect;
+}
+export declare const MAX_UPDATES = 200;
+export declare const MAX_TEXT = 1000;
+/** The columns an update writes, in a fixed order. Both rating inputs write `rating`. */
+export declare function writtenFields(u: TrackUpdate): FieldName[];
+/**
+ * A refusal names every offender, not the first (spec §7.3): one vanished
+ * track must not cost two hundred round trips. Capped so the message stays
+ * readable.
+ */
+export declare function listProblems(problems: string[]): string;
+/**
+ * Rules that need no database. Ranges check NEW values only: a field written
+ * together with `expect` on the same field is a restore -- typically a replayed
+ * undo -- and must be able to put back whatever was there, however odd
+ * (spec §5.3). rating_raw is the exception that proves the rule: it exists only
+ * for restoring, so it always needs expect.rating_raw, and its 0-255 bound (the
+ * ID3 scale) always applies.
+ */
+export declare function validateUpdates(updates: TrackUpdate[]): EngineError | undefined;
+export type StoredValue = string | number | null;
+/** One track as read from the library, already classified (see src/store/track-metadata.ts). */
+export interface CurrentRow {
+    id: number;
+    genre: string | null;
+    comment: string | null;
+    label: string | null;
+    year: number | null;
+    rating: number | null;
+    /** Columns whose stored value this tool could not put back (spec §5.3). */
+    inexpressible: FieldName[];
+    /** The fix-origin trigger's own WHEN, evaluated by SQLite (spec §3.3). */
+    originEmpty: boolean;
+}
+export interface RowWrite {
+    id: number;
+    set: Partial<Record<FieldName, StoredValue>>;
+    fields: FieldName[];
+}
+export interface Plan {
+    writes: RowWrite[];
+    unchanged: number[];
+    undo: TrackUpdate[];
+}
+/** The value a field will hold once written. `""` is NULL; stars are Engine's 0-100. */
+export declare function targetOf(u: TrackUpdate, f: FieldName): StoredValue;
+/**
+ * Spec §5.1: NULL and '' are one empty for text, NULL and 0 for numbers.
+ * Otherwise exact -- no Unicode folding, because hiding a real difference is
+ * worse than reporting a confusing one (describeValue spells those out).
+ * Done in JS: in SQL, NULL = '' is neither true nor false.
+ */
+export declare function sameStored(f: FieldName, a: StoredValue, b: StoredValue): boolean;
+/**
+ * Decide, for rows already read, what each update writes. Order matters and
+ * follows spec §5.2 and §6: a row already at its target is unchanged before
+ * anything else is asked of it -- expect included, since expect guards writes
+ * and this row is not written. Refusals are collected across all rows and
+ * reported by class: unknown ids first, then tracks that cannot be edited,
+ * then stale expectations.
+ */
+export declare function planUpdates(updates: TrackUpdate[], rows: ReadonlyMap<number, CurrentRow>): Plan | EngineError;