engine-dj-mcp 0.15.0 → 0.17.1

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, ambiguousLibrary, defaultLibraryTies, findLibrary, libraryNotFound, pickDefaultLibrary, } from "./library-select.js";
+import { LibraryArg, ambiguousLibrary, writeNeedsLibrary, findLibrary, namedWriteLibrary, 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
@@ -77,13 +84,28 @@ const LIBRARY_SELECTION_NOTE = "With more than one library connected, pass `libr
     "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.
+ * 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. A library copied onto another drive keeps its uuid, so naming a uuid that " +
+    "two connected libraries share is refused the same way -- pass the path.";
+/**
+ * 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 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.";
+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) }],
@@ -225,6 +247,13 @@ export async function createServer(opts = {}) {
         rescanLibraries();
         return findLibrary(knownList(), requested) ?? libraryNotFound(requested, knownList());
     };
+    /** Resolves `library` the read way -- see selectLibrary -- then prepares it. */
+    const acquire = async (requested) => {
+        const lib = selectLibrary(requested);
+        if (isEngineError(lib))
+            return lib;
+        return prepare(lib);
+    };
     /**
      * `index_stale` is swallowed only when an index is genuinely attached:
      * "the previous index is still in use" is a reason to answer anyway, but
@@ -235,10 +264,7 @@ export async function createServer(opts = {}) {
      * string "no such table: side.track_derived", instead of `index_stale`
      * with a `retry_after_ms` the model can act on.
      */
-    const acquire = async (requested) => {
-        const lib = selectLibrary(requested);
-        if (isEngineError(lib))
-            return lib;
+    const prepare = async (lib) => {
         const state = stateFor(lib);
         const fresh = await state.mgr.ensureFresh();
         if (!isEngineError(fresh))
@@ -248,8 +274,13 @@ export async function createServer(opts = {}) {
         return fresh;
     };
     /**
-     * `acquire` for the write tools: identical, except that an omitted
-     * `library` must resolve to exactly one candidate.
+     * 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.
+     *
+     * Selection differs from a read's in that it must name exactly one
+     * physical library, whether `library` was omitted or given.
      *
      * `pickDefaultLibrary` breaks a tie on root-scan order, which is
      * deterministic and, for a read, fine -- libraries tie because one is a
@@ -262,31 +293,51 @@ export async function createServer(opts = {}) {
      * 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.
+     * A named library is taken as named -- unless the name is a uuid two
+     * connected libraries share. Copying an Engine Library folder onto another
+     * drive copies its uuid, and resolving that uuid to the first match would
+     * be the same order-of-discovery pick the omitted case refuses, reached by
+     * a caller who had no way to know it was ambiguous. namedWriteLibrary refuses it and asks
+     * for the path, which tells the copies apart.
+     *
+     * Rescans first, in both cases, 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 -- including a
+     * copy that makes a named uuid ambiguous.
      *
-     * 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.
+     * A copy that has never once been readable since startup -- a hot journal,
+     * no permission -- is still not counted: its uuid was never read, so there
+     * is nothing to match. rescanLibraries keeps only libraries it has read.
      *
-     * 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 cost is one discovery scan per write: every candidate library under
+     * the roots is opened read-only and its header and track count read, the
+     * same scan list_libraries runs. That is small 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 scan apiece.
      */
+    const selectForWrite = (requested) => {
+        rescanLibraries();
+        if (requested !== undefined)
+            return namedWriteLibrary(knownList(), requested);
+        const choices = writeNeedsLibrary(knownList());
+        if (choices.length > 0)
+            return ambiguousLibrary(choices);
+        return selectLibrary();
+    };
     const acquireForWrite = async (requested) => {
-        if (requested === undefined) {
-            rescanLibraries();
-            const tied = defaultLibraryTies(knownList());
-            if (tied.length > 1)
-                return ambiguousLibrary(tied);
-        }
-        return acquire(requested);
+        const lib = selectForWrite(requested);
+        if (isEngineError(lib))
+            return lib;
+        // The library just resolved, not `requested` again by the read rules:
+        // today both give the same answer, but only this one was checked for a
+        // uuid shared between copies.
+        return prepare(lib);
     };
     /**
      * Shared by the engine://libraries resource and the list_libraries tool so
@@ -527,7 +578,7 @@ 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 + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...CreatePlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
@@ -561,7 +612,7 @@ export async function createServer(opts = {}) {
                 "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. " +
                 UNDO_SCOPE_NOTE +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...AddTracksToPlaylistInput.shape, library: LibraryArg },
             annotations: RW,
         }, async (args) => {
@@ -600,7 +651,7 @@ 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 edit. " +
                 UNDO_SCOPE_NOTE +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...RemoveTracksFromPlaylistInput.shape, library: LibraryArg },
             annotations: RW_DESTRUCTIVE,
         }, async (args) => {
@@ -627,7 +678,7 @@ export async function createServer(opts = {}) {
                 "WHOLE library to before this session's first write, discarding everything Engine DJ " +
                 "has recorded since -- not just this reorder. " +
                 UNDO_SCOPE_NOTE +
-                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_TIE_NOTE,
+                LIBRARY_SELECTION_NOTE + WRITE_LIBRARY_NOTE,
             inputSchema: { ...ReorderPlaylistInput.shape, library: LibraryArg },
             annotations: RW_DESTRUCTIVE,
         }, async (args) => {
@@ -636,6 +687,41 @@ export async function createServer(opts = {}) {
                 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
@@ -704,6 +790,11 @@ 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 \`~\`.
@@ -719,6 +810,13 @@ other.
   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/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;

package/dist/store/track-metadata-plan.js

@@ -0,0 +1,236 @@
+// src/store/track-metadata-plan.ts
+//
+// The pure half of update_track_metadata (spec docs/superpowers/specs/
+// 2026-09-14-track-metadata-design.md). No database access, so every rule can
+// be tested against an exact row.
+import { err } from "../errors.js";
+import { NOT_COMMITTED } from "./write.js";
+export const TEXT_FIELDS = ["genre", "comment", "label"];
+export const MAX_UPDATES = 200;
+export const MAX_TEXT = 1000;
+const LIST_LIMIT = 20;
+/** The columns an update writes, in a fixed order. Both rating inputs write `rating`. */
+export function writtenFields(u) {
+    const out = [];
+    for (const f of TEXT_FIELDS)
+        if (u[f] !== undefined)
+            out.push(f);
+    if (u.year !== undefined)
+        out.push("year");
+    if (u.rating_stars !== undefined || u.rating_raw !== undefined)
+        out.push("rating");
+    return out;
+}
+/**
+ * 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 function listProblems(problems) {
+    const shown = problems.slice(0, LIST_LIMIT).join("; ");
+    const rest = problems.length - LIST_LIMIT;
+    return rest > 0 ? `${shown}; and ${rest} more` : shown;
+}
+const isWhole = (n, lo, hi) => Number.isInteger(n) && n >= lo && n <= hi;
+/**
+ * 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 function validateUpdates(updates) {
+    if (updates.length === 0) {
+        return err("invalid_argument", "updates is empty; name at least one track to change. Nothing was written.", {
+            detail: NOT_COMMITTED,
+        });
+    }
+    const problems = [];
+    if (updates.length > MAX_UPDATES)
+        problems.push(`${updates.length} updates, more than the ${MAX_UPDATES} allowed per call`);
+    const seen = new Set();
+    const repeated = new Set();
+    for (const u of updates) {
+        if (seen.has(u.id))
+            repeated.add(u.id);
+        seen.add(u.id);
+    }
+    if (repeated.size > 0) {
+        problems.push(`track id${repeated.size > 1 ? "s" : ""} ${[...repeated].join(", ")} named more than once`);
+    }
+    for (const u of updates) {
+        const at = `track ${u.id}`;
+        const fields = writtenFields(u);
+        const expect = u.expect ?? {};
+        if (fields.length === 0)
+            problems.push(`${at}: no field to change`);
+        if (u.rating_stars !== undefined && u.rating_raw !== undefined) {
+            problems.push(`${at}: rating_stars and rating_raw together`);
+        }
+        if (u.rating_raw !== undefined && expect.rating_raw === undefined) {
+            problems.push(`${at}: rating_raw restores an exact value and needs expect.rating_raw; to set a rating use rating_stars`);
+        }
+        for (const key of Object.keys(expect)) {
+            if (expect[key] === undefined)
+                continue;
+            const writes = key === "rating_raw" ? fields.includes("rating") : fields.includes(key);
+            if (!writes)
+                problems.push(`${at}: expect.${key} names a field this update does not change`);
+        }
+        if (u.rating_stars !== undefined && !isWhole(u.rating_stars, 0, 5)) {
+            problems.push(`${at}: rating_stars must be a whole number 0-5`);
+        }
+        if (u.rating_raw !== undefined && !isWhole(u.rating_raw, 0, 255)) {
+            problems.push(`${at}: rating_raw must be a whole number 0-255`);
+        }
+        if (u.year !== undefined) {
+            if (!Number.isInteger(u.year))
+                problems.push(`${at}: year must be a whole number`);
+            else if (expect.year === undefined && u.year !== 0 && !isWhole(u.year, 1000, 2200)) {
+                problems.push(`${at}: year must be 0 (unknown) or 1000-2200`);
+            }
+        }
+        for (const f of TEXT_FIELDS) {
+            const v = u[f];
+            // A lone surrogate passes every other check here, reaches SQLite, and
+            // comes back mangled -- caught downstream as library_unreadable
+            // "did not read back as written" instead of the invalid_argument this
+            // is. Checked on both the new value and its expect counterpart, and
+            // regardless of whether this is a restore: MAX_TEXT is waived for a
+            // restore (spec §5.3), but a value that is not valid Unicode text at
+            // all is never something this tool could have written or read back.
+            if (v !== undefined && !v.isWellFormed())
+                problems.push(`${at}: ${f} is not valid Unicode text`);
+            const ev = expect[f];
+            if (ev !== undefined && !ev.isWellFormed())
+                problems.push(`${at}: expect.${f} is not valid Unicode text`);
+            if (v !== undefined && expect[f] === undefined && v.length > MAX_TEXT) {
+                problems.push(`${at}: ${f} is longer than ${MAX_TEXT} characters`);
+            }
+        }
+    }
+    if (problems.length === 0)
+        return undefined;
+    return err("invalid_argument", `${problems.length} problem${problems.length > 1 ? "s" : ""} with updates, nothing was written: ${listProblems(problems)}`, { detail: NOT_COMMITTED });
+}
+/** The value a field will hold once written. `""` is NULL; stars are Engine's 0-100. */
+export function targetOf(u, f) {
+    if (f === "rating")
+        return u.rating_raw !== undefined ? u.rating_raw : u.rating_stars * 20;
+    if (f === "year")
+        return u.year;
+    const v = u[f];
+    return v === "" ? null : v;
+}
+/**
+ * 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 function sameStored(f, a, b) {
+    if (f === "year" || f === "rating")
+        return (a ?? 0) === (b ?? 0);
+    return (a ?? "") === (b ?? "");
+}
+const codePoints = (s) => [...s].map((c) => "U+" + c.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")).join(" ");
+function describeMismatch(m) {
+    const show = (v) => (v === null ? "empty" : JSON.stringify(v));
+    let line = `track ${m.id} ${m.field}: expected ${show(m.expected)}, found ${show(m.actual)}`;
+    if (typeof m.expected === "string" && typeof m.actual === "string" &&
+        m.expected !== m.actual && m.expected.normalize("NFC") === m.actual.normalize("NFC")) {
+        line += ` (same text in a different Unicode form: expected ${codePoints(m.expected)}, found ${codePoints(m.actual)})`;
+    }
+    return line;
+}
+/**
+ * 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 function planUpdates(updates, rows) {
+    const plan = { writes: [], unchanged: [], undo: [] };
+    const unknown = [];
+    const notEditable = [];
+    const mismatches = [];
+    for (const u of updates) {
+        const current = rows.get(u.id);
+        if (!current) {
+            unknown.push(u.id);
+            continue;
+        }
+        // An inexpressible field is read as null, so comparing it would call a stored
+        // 999 "already 0 stars". It always counts as different, which routes it to
+        // the track_not_editable refusal below instead of a false "unchanged".
+        const differs = writtenFields(u).filter((f) => current.inexpressible.includes(f) || !sameStored(f, current[f], targetOf(u, f)));
+        if (differs.length === 0) {
+            plan.unchanged.push(u.id);
+            continue;
+        }
+        if (current.originEmpty) {
+            notEditable.push(`track ${u.id}: its origin is empty, and Engine's own trigger rewrites an empty origin on any ` +
+                `update, which would detach it from playlist entries on other drives; edit it in Engine DJ instead`);
+        }
+        for (const f of differs) {
+            if (current.inexpressible.includes(f)) {
+                notEditable.push(`track ${u.id}: ${f} holds a stored value this tool could not put back`);
+            }
+        }
+        const expect = u.expect ?? {};
+        for (const key of Object.keys(expect)) {
+            const expected = expect[key];
+            if (expected === undefined)
+                continue;
+            const field = key === "rating_raw" ? "rating" : key;
+            // Spec §5.2 (field-level): expect guards writes, so an expect on a
+            // field this row will not write is skipped. Otherwise undoing a
+            // "genre + comment" edit would refuse the whole row because genre was
+            // already put back by hand, though comment still needs restoring.
+            if (!differs.includes(field))
+                continue;
+            const want = field === "year" || field === "rating" ? expected : expected || null;
+            if (!sameStored(field, current[field], want)) {
+                mismatches.push({ id: u.id, field: key, expected, actual: current[field] });
+            }
+        }
+        const write = { id: u.id, set: {}, fields: differs };
+        const back = { id: u.id, expect: {} };
+        for (const f of differs) {
+            const now = targetOf(u, f);
+            write.set[f] = now;
+            const was = current[f];
+            if (f === "rating") {
+                back.rating_raw = was ?? 0;
+                back.expect.rating_raw = now ?? 0;
+            }
+            else if (f === "year") {
+                back.year = was ?? 0;
+                back.expect.year = now ?? 0;
+            }
+            else {
+                back[f] = was ?? "";
+                back.expect[f] = now ?? "";
+            }
+        }
+        plan.writes.push(write);
+        plan.undo.push(back);
+    }
+    if (unknown.length > 0) {
+        return err("unknown_track", `${unknown.length} track id${unknown.length > 1 ? "s are" : " is"} not in this library, nothing was written: ` +
+            listProblems(unknown.map(String)), { detail: NOT_COMMITTED });
+    }
+    if (notEditable.length > 0) {
+        return err("track_not_editable", `${notEditable.length} edit${notEditable.length > 1 ? "s" : ""} cannot be made, nothing was written: ${listProblems(notEditable)}`, { detail: NOT_COMMITTED });
+    }
+    if (mismatches.length > 0) {
+        return err("stale_value", `${mismatches.length} expected value${mismatches.length > 1 ? "s" : ""} no longer match, nothing was written. ` +
+            `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 without the user's consent: ` +
+            `${listProblems(mismatches.map(describeMismatch))}`, { detail: NOT_COMMITTED, mismatches: mismatches.slice(0, LIST_LIMIT) });
+    }
+    return plan;
+}

package/dist/store/track-metadata.d.ts

@@ -0,0 +1,22 @@
+import { type EngineError } from "../errors.js";
+import { type LibraryRef, type UndoStep } from "./write.js";
+import { type FieldName, type TrackUpdate } from "./track-metadata-plan.js";
+export interface TrackMetadataResult {
+    updated: number;
+    unchanged: number;
+    changed: {
+        id: number;
+        fields: FieldName[];
+    }[];
+    undo: UndoStep[];
+    undo_complete: true;
+}
+export declare function updateTrackMetadata(mdbPath: string, uuid: string, input: {
+    updates: TrackUpdate[];
+}, opts: {
+    backupDir: string;
+    beforeLock?: () => void;
+}): Promise<(TrackMetadataResult & {
+    library: LibraryRef;
+    backup_path?: string;
+}) | EngineError>;