engine-dj-mcp 0.15.0 → 0.17.0

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

package/dist/store/track-metadata.js

@@ -0,0 +1,143 @@
+// src/store/track-metadata.ts
+//
+// update_track_metadata against a real library. The decisions live in
+// track-metadata-plan.ts; this module reads rows, applies a plan and verifies
+// it. Order (spec §6): hot journal, input rules, read-only pre-check, then --
+// only if something would change -- the shared write transaction, where every
+// row is read and planned AGAIN under the lock and that second reading decides.
+import { DatabaseSync } from "node:sqlite";
+import { err, isEngineError, libraryNeedsRecovery } from "../errors.js";
+import { redactPath } from "../paths.js";
+import { hasHotJournal } from "./connections.js";
+import { NOT_COMMITTED, mapWriteError, rollback, withWriteTransaction, } from "./write.js";
+import { planUpdates, sameStored, validateUpdates, TEXT_FIELDS, } from "./track-metadata-plan.js";
+const MAX_SAFE = Number.MAX_SAFE_INTEGER;
+/**
+ * Types and ranges are settled in SQL, before a value reaches JS: node:sqlite
+ * throws on an INTEGER beyond 2^53, and a REAL rating or a TEXT year is not a
+ * value this tool could put back. Such a column comes back null and is listed
+ * in `inexpressible`. The empty-origin test is the fix-origin trigger's own
+ * WHEN, evaluated by SQLite, so it agrees with the trigger on TEXT '' (spec §3.3).
+ */
+const READ_ROW = `SELECT id,
+  CASE WHEN typeof(genre) = 'text' THEN genre END AS genre, typeof(genre) AS genre_t,
+  CASE WHEN typeof(comment) = 'text' THEN comment END AS comment, typeof(comment) AS comment_t,
+  CASE WHEN typeof(label) = 'text' THEN label END AS label, typeof(label) AS label_t,
+  CASE WHEN typeof(year) = 'integer' AND year BETWEEN -${MAX_SAFE} AND ${MAX_SAFE} THEN year END AS year,
+  (typeof(year) = 'null' OR (typeof(year) = 'integer' AND year BETWEEN -${MAX_SAFE} AND ${MAX_SAFE})) AS year_ok,
+  CASE WHEN typeof(rating) = 'integer' AND rating BETWEEN 0 AND 255 THEN rating END AS rating,
+  (typeof(rating) = 'null' OR (typeof(rating) = 'integer' AND rating BETWEEN 0 AND 255)) AS rating_ok,
+  (IFNULL(originTrackId, 0) = 0 OR IFNULL(originDatabaseUuid, '') = '') AS origin_empty,
+  CAST(originDatabaseUuid AS TEXT) || '|' || CAST(originTrackId AS TEXT) AS origin
+  FROM Track WHERE id = ?`;
+function readRows(db, ids) {
+    const stmt = db.prepare(READ_ROW);
+    const out = new Map();
+    for (const id of ids) {
+        const r = stmt.get(id);
+        if (!r)
+            continue;
+        const inexpressible = [];
+        for (const f of TEXT_FIELDS) {
+            if (r[`${f}_t`] !== "text" && r[`${f}_t`] !== "null")
+                inexpressible.push(f);
+        }
+        if (!r.year_ok)
+            inexpressible.push("year");
+        if (!r.rating_ok)
+            inexpressible.push("rating");
+        out.set(id, {
+            id,
+            genre: r.genre,
+            comment: r.comment,
+            label: r.label,
+            year: r.year,
+            rating: r.rating,
+            inexpressible,
+            originEmpty: r.origin_empty === 1,
+            origin: r.origin,
+        });
+    }
+    return out;
+}
+export async function updateTrackMetadata(mdbPath, uuid, input, opts) {
+    const { updates } = input;
+    const ids = updates.map((u) => u.id);
+    const subject = `${updates.length} track${updates.length === 1 ? "" : "s"}`;
+    // First, before anything opens the file: see createPlaylist in write.ts.
+    if (hasHotJournal(mdbPath))
+        return { ...libraryNeedsRecovery(), detail: NOT_COMMITTED };
+    const invalid = validateUpdates(updates);
+    if (invalid)
+        return invalid;
+    // Not the authority -- the transaction re-plans. This only spares a
+    // snapshot for a call that is going to refuse anyway, or has nothing to do.
+    let pre;
+    let precheck;
+    try {
+        precheck = new DatabaseSync(mdbPath, { readOnly: true });
+        pre = planUpdates(updates, readRows(precheck, ids));
+    }
+    catch (e) {
+        return mapWriteError(e, subject, mdbPath);
+    }
+    finally {
+        try {
+            precheck?.close();
+        }
+        catch {
+            /* never opened */
+        }
+    }
+    if (isEngineError(pre))
+        return pre;
+    if (pre.writes.length === 0) {
+        // Spec §5.5: no transaction, no snapshot, so no backup_path -- and
+        // withWriteTransaction is not here to fill in `library`.
+        return {
+            updated: 0,
+            unchanged: pre.unchanged.length,
+            changed: [],
+            undo: [],
+            undo_complete: true,
+            library: { uuid, path: redactPath(mdbPath) },
+        };
+    }
+    return withWriteTransaction(mdbPath, uuid, subject, opts, (db) => {
+        // Under BEGIN IMMEDIATE. Engine may have changed any of these rows while
+        // the snapshot was being copied; what is read here decides (spec §6.5).
+        const rows = readRows(db, ids);
+        const plan = planUpdates(updates, rows);
+        if (isEngineError(plan)) {
+            rollback(db);
+            return plan;
+        }
+        for (const w of plan.writes) {
+            // Column names come from the FieldName union, never from caller text.
+            const assignments = w.fields.map((f) => `${f} = ?`).join(", ");
+            // Set as Engine sets it on its own tag edits (spec §3.9, measured).
+            db.prepare(`UPDATE Track SET ${assignments}, isMetadataOfPackedTrackChanged = 1 WHERE id = ?`).run(...w.fields.map((f) => w.set[f] ?? null), w.id);
+        }
+        const after = readRows(db, plan.writes.map((w) => w.id));
+        for (const w of plan.writes) {
+            const got = after.get(w.id);
+            const landed = got !== undefined &&
+                got.origin === rows.get(w.id).origin &&
+                w.fields.every((f) => sameStored(f, got[f], w.set[f] ?? null));
+            if (!landed) {
+                rollback(db);
+                return err("library_unreadable", `Track ${w.id} did not read back as written; nothing was changed.`, {
+                    detail: NOT_COMMITTED,
+                });
+            }
+        }
+        const result = {
+            updated: plan.writes.length,
+            unchanged: plan.unchanged.length,
+            changed: plan.writes.map((w) => ({ id: w.id, fields: w.fields })),
+            undo: plan.undo.length > 0 ? [{ tool: "update_track_metadata", arguments: { updates: plan.undo } }] : [],
+            undo_complete: true,
+        };
+        return result;
+    });
+}

package/dist/store/write.d.ts

@@ -65,6 +65,22 @@ export interface OriginRef {
     uuid: string;
     trackId: number;
 }
+/**
+ * `detail` discriminator values for the EngineError this module returns.
+ * Stable across releases so a caller can decide "is the library still what
+ * it was" without parsing message prose. Everything before COMMIT --
+ * including validation that never reaches the database at all -- collapses
+ * to the same NOT_COMMITTED answer. COMMITTED_UNVERIFIED is produced by
+ * exactly two things, and both mean "the playlist may be on disk": the
+ * post-commit check reporting anything but "ok", and anything thrown from
+ * the COMMIT itself onwards. It is also the only case that carries
+ * backup_path, because it is the only case where restoring from a snapshot
+ * is ever the right next step.
+ *
+ * These two strings are part of the tool's contract; see src/errors.ts.
+ */
+/** Exported for src/store/track-metadata*.ts; the string is part of the tool contract. */
+export declare const NOT_COMMITTED = "not_committed";
 /** Test seam only: forget this process's snapshots so a test can start clean. */
 export declare function resetSessionSnapshots(): void;
 /**
@@ -125,7 +141,74 @@ export declare function checkChain(rows: {
     id: number;
     next: number;
 }[]): ChainCheck;
+/**
+ * Roll back, swallowing a failure of the rollback itself.
+ *
+ * Every caller is already returning a specific error -- the chain did not read
+ * back, the library is busy -- and a ROLLBACK that throws on the way out would
+ * replace that reason with its own, telling the user about a failed rollback
+ * instead of what actually went wrong. Nothing is lost by ignoring it:
+ * db.close() in the finally block ends any transaction still open, and SQLite
+ * discards an uncommitted one on close.
+ */
+/** Exported for src/store/track-metadata.ts. */
+export declare function rollback(db: DatabaseSync): void;
 export declare function sameOrder(a: OriginRef[], b: OriginRef[]): boolean;
+/**
+ * Turns whatever node:sqlite throws into an EngineError. Shared by every op
+ * in this module -- the read-only pre-check and the write transaction below
+ * it both open a connection to the same file and can hit the same failure
+ * modes (the library gone missing mid-session, Engine holding the lock, a
+ * foreign or corrupt schema), and a caller whose promise is typed
+ * `Promise<... | EngineError>` must never see one of them escape as a
+ * rejection instead.
+ *
+ * `subject` is whatever this write is named for in its own messages -- a new
+ * playlist's title for createPlaylist, `playlist ${listId}` for an op that
+ * edits one that already exists.
+ *
+ * Every path that reaches this function is one where the library is
+ * unchanged: the transaction either never opened or is rolled back by the
+ * caller, and a failure at or after COMMIT is answered before this is ever
+ * called (see classifyWriteFailure, below). That is what lets the fallback
+ * below say "nothing was changed" without qualification -- it used to say
+ * `Writing "X" failed`, which reads as a half-write even when the failure was
+ * "file is not a database" and not one byte was attempted.
+ */
+/** Exported for src/store/track-metadata.ts. */
+export declare function mapWriteError(e: unknown, subject: string, mdbPath: string): EngineError;
+/**
+ * Owns everything past the read-only pre-check that every write op in this
+ * module does identically: snapshot, open, `PRAGMA foreign_keys = ON`,
+ * `BEGIN IMMEDIATE`, commit, verify, and classify whatever went wrong.
+ * `body` does the one thing that differs between ops -- the INSERTs and
+ * UPDATEs specific to what this write is -- against the open `db` it is
+ * handed, and returns either the result to hand back (minus `backup_path`,
+ * which this function fills in once it knows COMMIT succeeded) or an
+ * `EngineError`. A body that has already written something rolls back before
+ * returning that error, but this function rolls back on that branch too
+ * rather than relying on it: `rollback` is a no-op when there is no
+ * transaction left to undo, and a body that forgot would otherwise leave the
+ * open transaction to `db.close()` -- correct today, and only by accident.
+ *
+ * `isEngineError`, not a second return channel, is what tells `body`'s
+ * success value apart from its failure one: this module already exports
+ * that check for callers, so reusing it here means a body never has to wrap
+ * its result to disambiguate the two.
+ */
+/** Exported for src/store/track-metadata.ts. */
+export declare function withWriteTransaction<T extends object>(mdbPath: string, uuid: string, subject: string, opts: {
+    backupDir: string;
+    /**
+     * Test seam only. Runs after the snapshot and before the write connection
+     * opens -- the window in which Engine DJ can still change a row this call
+     * already pre-checked. No production caller passes it.
+     */
+    beforeLock?: () => void;
+}, body: (db: DatabaseSync) => T | EngineError): Promise<(T & {
+    library: LibraryRef;
+    backup_path: string;
+}) | EngineError>;
 export declare function createPlaylist(mdbPath: string, uuid: string, input: {
     title: string;
     trackIds: number[];

package/dist/store/write.js

@@ -1,7 +1,8 @@
 // src/store/write.ts
 //
-// The only code in this project that writes to a user's Engine library, and
-// it runs only when the server was started with --allow-writes.
+// Writes to a user's Engine library, together with src/store/track-metadata.ts
+// (which reuses withWriteTransaction, mapWriteError and rollback from here).
+// Both run only when the server was started with --allow-writes.
 //
 // The read path is deliberately not reused. Queries run in a forked child
 // whose connection is opened readOnly: true, and that guarantee is the
@@ -29,7 +30,8 @@ import { redactPath } from "../paths.js";
  *
  * These two strings are part of the tool's contract; see src/errors.ts.
  */
-const NOT_COMMITTED = "not_committed";
+/** Exported for src/store/track-metadata*.ts; the string is part of the tool contract. */
+export const NOT_COMMITTED = "not_committed";
 const COMMITTED_UNVERIFIED = "committed_unverified";
 /**
  * One snapshot per library per process, which is what "before the first write
@@ -266,7 +268,8 @@ function gateChain(db, listId) {
  * db.close() in the finally block ends any transaction still open, and SQLite
  * discards an uncommitted one on close.
  */
-function rollback(db) {
+/** Exported for src/store/track-metadata.ts. */
+export function rollback(db) {
     try {
         db.exec("ROLLBACK");
     }
@@ -298,7 +301,8 @@ export function sameOrder(a, b) {
  * `Writing "X" failed`, which reads as a half-write even when the failure was
  * "file is not a database" and not one byte was attempted.
  */
-function mapWriteError(e, subject, mdbPath) {
+/** Exported for src/store/track-metadata.ts. */
+export function mapWriteError(e, subject, mdbPath) {
     const msg = e.message ?? String(e);
     const isUniqueViolation = /UNIQUE constraint failed/i.test(msg);
     // The constraint's *name* never appears in the message SQLite raises --
@@ -409,7 +413,8 @@ function classifyWriteFailure(e, commit, subject, mdbPath, backupPath, db, open)
  * that check for callers, so reusing it here means a body never has to wrap
  * its result to disambiguate the two.
  */
-async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
+/** Exported for src/store/track-metadata.ts. */
+export async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
     // Snapshot here, before the write connection is even opened, not after
     // BEGIN IMMEDIATE. Taking it with RESERVED held meant a full-database copy
     // -- tens of seconds on a multi-gigabyte USB library -- ran while every
@@ -431,6 +436,7 @@ async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
     if (typeof snapshot !== "string")
         return { ...snapshot, detail: NOT_COMMITTED };
     const backupPath = snapshot;
+    opts.beforeLock?.();
     let db;
     let open = false;
     let commit = "not yet";
@@ -453,7 +459,29 @@ async function withWriteTransaction(mdbPath, uuid, subject, opts, body) {
         // Filled in here, alongside backup_path, for the same reason: it is the
         // one place that knows the write succeeded, and doing it per-op would let
         // a new op ship without it.
-        return { ...result, library: { uuid, path: redactPath(mdbPath) }, backup_path: backupPath };
+        const library = { uuid, path: redactPath(mdbPath) };
+        // Every undo step carries the library too, and for a sharper reason than
+        // symmetry: a caller replaying an undo sends `undo.arguments` and nothing
+        // else, so without it the replay resolves whatever library is the default
+        // at replay time. A USB drive and its copy hold the same playlist ids and
+        // the same track ids, so such a replay lands on the wrong disk and
+        // expect_track_ids agrees -- both sides having been edited the same way.
+        //
+        // By path, not by uuid: a library and its clone on a second drive share a
+        // uuid (see store/backup.ts, which tags snapshots by path for exactly
+        // that), and a uuid could not say which of the two to undo in. A path
+        // names one. If that drive has since moved, the replay fails loudly with
+        // library_not_found rather than quietly editing the other copy.
+        //
+        // Injected here rather than in each op so a new op cannot ship without it.
+        const withUndo = result;
+        if (Array.isArray(withUndo.undo)) {
+            withUndo.undo = withUndo.undo.map((step) => ({
+                ...step,
+                arguments: { library: library.path, ...step.arguments },
+            }));
+        }
+        return { ...result, library, backup_path: backupPath };
     }
     catch (e) {
         return classifyWriteFailure(e, commit, subject, mdbPath, backupPath, db, open);