serato-dj-mcp 0.1.0

package/dist/apply/root.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { err } from "../errors.js";
+import { ANCHOR_SPACE_NAME } from "../read/crates.js";
+/** The tables root.sqlite must have for this protocol to write to it. */
+export const REQUIRED_ROOT_TABLES = [
+    "serato",
+    "master",
+    "space",
+    "container",
+    "container_asset",
+    "space_asset",
+    "asset",
+];
+const refuse = (reason, message, extra = {}) => err("write_refused", message, { reason, rejected_track_ids: [], ...extra });
+export function checkRootSchema(root) {
+    const tables = new Set(root.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name));
+    const missing = REQUIRED_ROOT_TABLES.filter((t) => !tables.has(t));
+    const seratoColumns = tables.has("serato")
+        ? root.prepare("PRAGMA table_info('serato')").all().map((r) => r.name)
+        : [];
+    if (missing.length > 0 || !seratoColumns.includes("revision")) {
+        return refuse("root_schema_unsupported", "root.sqlite does not have the schema this protocol writes", {
+            missing_tables: missing,
+            serato_has_revision: seratoColumns.includes("revision"),
+        });
+    }
+    return null;
+}
+/**
+ * Both queries mirror how Serato itself resolves them. The space by name
+ * (space is UNIQUE on name COLLATE NOCASE, so 0 or 1 rows); the root
+ * container by parent_id = 0, never by name -- its name is generated as
+ * "<space> root", and UNIQUE (parent_id, name, type) does not stop a user
+ * crate of that name at another type.
+ */
+export function findAnchors(root) {
+    const spaces = root
+        .prepare("SELECT id FROM space WHERE name = ? COLLATE NOCASE")
+        .all(ANCHOR_SPACE_NAME);
+    if (spaces.length !== 1) {
+        return refuse("anchor_space_missing", `root.sqlite has no "${ANCHOR_SPACE_NAME}" space`, {
+            found: spaces.length,
+        });
+    }
+    const containers = root
+        .prepare("SELECT c.id FROM space s JOIN container c ON s.id = c.space_id WHERE s.id = ? AND c.parent_id = 0")
+        .all(spaces[0].id);
+    if (containers.length !== 1) {
+        return refuse("anchor_container_ambiguous", "the space's root container is not exactly one row", {
+            found: containers.length,
+        });
+    }
+    return { spaceId: spaces[0].id, rootContainerId: containers[0].id };
+}
+/**
+ * portable_id -> root.asset.id (unique index on portable_id COLLATE NOCASE,
+ * so this is one index probe per track) -> space_asset.id by (asset_id,
+ * space_id). A track without that space_asset row is unresolvable: this
+ * server's write path only ever inserts container and container_asset rows,
+ * never asset or space_asset ones.
+ */
+export function resolveSpaceAssets(root, spaceId, portableIds) {
+    const stmt = root.prepare(`SELECT sa.id FROM asset a JOIN space_asset sa ON sa.asset_id = a.id
+      WHERE a.portable_id = ? COLLATE NOCASE AND sa.space_id = ?`);
+    const resolved = new Map();
+    const missing = [];
+    for (const portableId of portableIds) {
+        const row = stmt.get(portableId, spaceId);
+        if (row === undefined)
+            missing.push(portableId);
+        else
+            resolved.set(portableId, row.id);
+    }
+    return { resolved, missing };
+}
+/** Folds case the way container's UNIQUE(parent_id, name COLLATE NOCASE,
+ *  type) does -- measured on a copy of a real library: 'sErAtO dEmO tRaCkS'
+ *  collides with 'Serato Demo Tracks'. */
+export function existingCrateId(root, rootContainerId, name) {
+    const row = root
+        .prepare("SELECT id FROM container WHERE parent_id = ? AND name = ? COLLATE NOCASE AND type = 1")
+        .get(rootContainerId, name);
+    return row === undefined ? null : row.id;
+}
+/**
+ * Informational only, not a gate: apply re-validates what the crate depends
+ * on instead of refusing on this value, and reports a change as a warning.
+ * Reads serato.revision only -- never the master table, whose
+ * last_sync_secret does not fit a JavaScript number (measured 2026-09-14).
+ */
+export function rootGeneration(root, rootPath, libraryId) {
+    const { revision } = root.prepare("SELECT revision FROM serato").get();
+    const st = statSync(rootPath);
+    return createHash("sha256")
+        .update(`${libraryId}|${revision}|${st.mtimeMs}|${st.size}`)
+        .digest("hex")
+        .slice(0, 12);
+}

package/dist/apply/serato.d.ts

@@ -0,0 +1,28 @@
+import { type SeratoError } from "../errors.js";
+export type LockRow = {
+    owner_process_id: number | null;
+    owner_process_name: string | null;
+};
+export type ProcessProbe = {
+    isAlive(pid: number): boolean;
+    nameOf(pid: number): string | null;
+};
+export declare const systemProbe: ProcessProbe;
+/**
+ * Reads master.sqlite's lock table from the LIVE file, read-only. Every other
+ * read in this server goes through a snapshot copy; this one cannot, because
+ * a snapshot describes the past and "is Serato running now" is a question
+ * about the present.
+ */
+export declare function readLockRows(masterPath: string): LockRow[] | SeratoError;
+/**
+ * A lock row counts only if its process is alive AND is still called what
+ * the row says. The row survives an unclean shutdown -- measured 2026-09-03
+ * after SIGTERM, and live on 2026-09-14 for pid 73438 -- and the OS recycles
+ * pids, so either check alone gives a permanent false "running".
+ */
+export declare function findLiveSerato(rows: LockRow[], probe: ProcessProbe): {
+    pid: number;
+    name: string;
+} | null;
+export declare function checkSeratoClosed(masterPath: string, probe?: ProcessProbe): null | SeratoError;

package/dist/apply/serato.js

@@ -0,0 +1,102 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { err } from "../errors.js";
+export const systemProbe = {
+    isAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            // EPERM: the process exists and belongs to another user -- that is a
+            // live process, not a dead one.
+            return e.code === "EPERM";
+        }
+    },
+    nameOf(pid) {
+        try {
+            const out = execFileSync("ps", ["-p", String(pid), "-o", "comm="], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            return out.trim() === "" ? null : out.trim();
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * Reads master.sqlite's lock table from the LIVE file, read-only. Every other
+ * read in this server goes through a snapshot copy; this one cannot, because
+ * a snapshot describes the past and "is Serato running now" is a question
+ * about the present.
+ */
+export function readLockRows(masterPath) {
+    let db;
+    try {
+        db = new DatabaseSync(masterPath, { readOnly: true });
+        db.exec("PRAGMA busy_timeout = 3000");
+        const hasTable = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lock'")
+            .get();
+        if (hasTable === undefined)
+            return [];
+        return db.prepare("SELECT owner_process_id, owner_process_name FROM lock").all();
+    }
+    catch (e) {
+        // Unable to tell whether Serato is running is a refusal to write, never a
+        // guess that it is not.
+        return err("write_refused", `cannot read master.sqlite's lock table: ${String(e)}`, {
+            reason: "lock_unreadable",
+            rejected_track_ids: [],
+        });
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * A lock row counts only if its process is alive AND is still called what
+ * the row says. The row survives an unclean shutdown -- measured 2026-09-03
+ * after SIGTERM, and live on 2026-09-14 for pid 73438 -- and the OS recycles
+ * pids, so either check alone gives a permanent false "running".
+ */
+export function findLiveSerato(rows, probe) {
+    for (const row of rows) {
+        const pid = row.owner_process_id;
+        const expected = row.owner_process_name;
+        if (pid === null || expected === null)
+            continue;
+        if (!probe.isAlive(pid))
+            continue;
+        const actual = probe.nameOf(pid);
+        if (actual === null) {
+            // The name could not be read. If the process died in between, the row
+            // is stale; if it is still alive, not knowing what it is must refuse,
+            // never guess -- the same rule readLockRows follows.
+            if (probe.isAlive(pid))
+                return { pid, name: expected };
+            continue;
+        }
+        // `ps -o comm=` prints the full executable path for an app bundle on
+        // macOS; the row holds the bare application name.
+        if (actual === expected || basename(actual) === expected || actual.endsWith(`/${expected}`)) {
+            return { pid, name: expected };
+        }
+    }
+    return null;
+}
+export function checkSeratoClosed(masterPath, probe = systemProbe) {
+    const rows = readLockRows(masterPath);
+    if (!Array.isArray(rows))
+        return rows;
+    const live = findLiveSerato(rows, probe);
+    if (live === null)
+        return null;
+    return err("serato_running", `${live.name} is running; quit it before applying changes`, {
+        owner_process_id: live.pid,
+        owner_process_name: live.name,
+    });
+}

package/dist/apply/sqlite.d.ts

@@ -0,0 +1,2 @@
+/** SQLITE_BUSY is primary result code 5; its extended variants mask down to it in the low byte. */
+export declare function isSqliteBusy(e: unknown): boolean;

package/dist/apply/sqlite.js

@@ -0,0 +1,4 @@
+/** SQLITE_BUSY is primary result code 5; its extended variants mask down to it in the low byte. */
+export function isSqliteBusy(e) {
+    return ((e.errcode ?? -1) & 0xff) === 5;
+}

package/dist/apply/transaction.d.ts

@@ -0,0 +1,34 @@
+import type { Warning } from "../envelope.js";
+import { type SeratoError } from "../errors.js";
+import type { StagedCrate } from "../stage/store.js";
+import type { BackupPaths } from "./backup.js";
+import { type ProcessProbe } from "./serato.js";
+/** SQLITE_BUSY becomes busy with retry_after_ms equal to this. */
+export declare const BUSY_TIMEOUT_MS = 3000;
+export type AppliedCrate = {
+    staged_id: string;
+    name: string;
+    container_id: number;
+    track_count: number;
+};
+export type ApplyOutcome = {
+    applied: AppliedCrate[];
+    revision: number;
+    warnings: Warning[];
+};
+export type ApplyInput = {
+    rootPath: string;
+    masterPath: string;
+    libraryId: string;
+    crates: StagedCrate[];
+    stagedRootGeneration: string;
+    backupPaths: BackupPaths;
+    probe?: ProcessProbe;
+};
+export declare function applyCrates(input: ApplyInput): ApplyOutcome | SeratoError;
+/**
+ * After COMMIT, on a NEW connection -- the only thing that makes
+ * committed_unverified a reachable state rather than a hope. A failure here
+ * means the data may well be in the file; the caller gets the backup paths.
+ */
+export declare function verifyCommitted(input: ApplyInput, outcome: ApplyOutcome): SeratoError | null;

package/dist/apply/transaction.js

@@ -0,0 +1,330 @@
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { err, isSeratoError } from "../errors.js";
+import { sameCrateName } from "../stage/name.js";
+import { checkRootSchema, existingCrateId, findAnchors, resolveSpaceAssets, rootGeneration, } from "./root.js";
+import { checkSeratoClosed, systemProbe } from "./serato.js";
+import { isSqliteBusy } from "./sqlite.js";
+/** SQLITE_BUSY becomes busy with retry_after_ms equal to this. */
+export const BUSY_TIMEOUT_MS = 3000;
+/** node:sqlite's extended code for a UNIQUE violation, measured 2026-09-14.
+ *  The primary code 19 is shared with NOT NULL (1299), CHECK and FK, so only
+ *  the extended code identifies a name collision. */
+const SQLITE_CONSTRAINT_UNIQUE = 2067;
+export function applyCrates(input) {
+    const written = writeInTransaction(input);
+    if (isSeratoError(written))
+        return written;
+    return verifyCommitted(input, written) ?? written;
+}
+function writeInTransaction(input) {
+    const probe = input.probe ?? systemProbe;
+    const notCommitted = (stage, message, extra = {}) => err("write_failed_not_committed", message, { stage, ...extra });
+    // Checked before opening: `new DatabaseSync(path)` creates a 0-byte
+    // root.sqlite for a path that does not exist yet, which must never happen.
+    if (!existsSync(input.rootPath)) {
+        return err("write_refused", "this library has no root.sqlite to write crates into", {
+            reason: "root_missing",
+            rejected_track_ids: [],
+        });
+    }
+    let db;
+    try {
+        db = new DatabaseSync(input.rootPath);
+    }
+    catch (e) {
+        return notCommitted("open", `cannot open root.sqlite: ${String(e)}`);
+    }
+    const rollback = () => {
+        try {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+        }
+        catch {
+            // A failed ROLLBACK leaves nothing to add: SQLite rolls back an open
+            // transaction when the connection closes, which the finally does.
+        }
+    };
+    try {
+        // Explicit even though node:sqlite enables foreign keys by default: the
+        // protocol must not depend on a binding's default.
+        db.exec("PRAGMA foreign_keys = ON");
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        try {
+            db.exec("BEGIN IMMEDIATE");
+        }
+        catch (e) {
+            if (isSqliteBusy(e)) {
+                return err("busy", `root.sqlite is locked by another writer: ${String(e)}`, {
+                    retry_after_ms: BUSY_TIMEOUT_MS,
+                });
+            }
+            // A file that is not a database fails the same way every time, so it
+            // must never invite a retry.
+            return notCommitted("begin", `cannot start the write transaction: ${String(e)}`);
+        }
+        // Checked again, now that we hold the write lock: Serato may have
+        // started between the caller's first check and this BEGIN.
+        const running = checkSeratoClosed(input.masterPath, probe);
+        if (running !== null) {
+            rollback();
+            return running;
+        }
+        const schema = checkRootSchema(db);
+        if (schema !== null) {
+            rollback();
+            return schema;
+        }
+        const anchors = findAnchors(db);
+        if (isSeratoError(anchors)) {
+            rollback();
+            return anchors;
+        }
+        // The triggers only ever raise space.revision TO serato.revision, so a
+        // space already ahead of it stays ahead after this write's bump: the
+        // pre-COMMIT check below would then refuse every apply behind a
+        // misleading "revision unmoved" failure, forever. Never observed: the
+        // space revision has been seen equal to the library's (72/72 on the live
+        // library) and one behind it (13/12 in an earlier run, both moved to 14
+        // by that write), never ahead of it -- but cheap to rule out up front.
+        const revisionsBefore = db
+            .prepare("SELECT (SELECT revision FROM serato) AS serato, (SELECT revision FROM space WHERE id = ?) AS space")
+            .get(anchors.spaceId);
+        if (revisionsBefore.space > revisionsBefore.serato) {
+            rollback();
+            return err("write_refused", "the crate space's revision is already ahead of serato's", {
+                reason: "space_revision_ahead",
+                rejected_track_ids: [],
+                serato_revision: revisionsBefore.serato,
+                space_revision: revisionsBefore.space,
+            });
+        }
+        const warnings = [];
+        // Informational only: what the crate actually depends on is re-validated
+        // below instead.
+        if (rootGeneration(db, input.rootPath, input.libraryId) !== input.stagedRootGeneration) {
+            warnings.push({
+                code: "root_generation_changed",
+                message: "root.sqlite changed since these crates were staged; everything they depend on was re-checked and still holds",
+                details: { staged_root_generation: input.stagedRootGeneration },
+            });
+        }
+        for (let i = 0; i < input.crates.length; i += 1) {
+            for (let j = 0; j < i; j += 1) {
+                if (sameCrateName(input.crates[i].name, input.crates[j].name)) {
+                    rollback();
+                    return err("invalid_crate_name", `two staged crates are both named "${input.crates[i].name}"`, {
+                        reason: "duplicate_in_batch",
+                        staged_ids: [input.crates[j].staged_id, input.crates[i].staged_id],
+                    });
+                }
+            }
+        }
+        // Re-validation: name conflicts first, because a conflict makes the whole
+        // batch meaningless regardless of tracks.
+        const resolvedByCrate = new Map();
+        const unresolvable = [];
+        for (const crate of input.crates) {
+            const conflict = existingCrateId(db, anchors.rootContainerId, crate.name);
+            if (conflict !== null) {
+                rollback();
+                return err("crate_name_conflict", `a crate named "${crate.name}" already exists`, {
+                    existing_container_id: conflict,
+                    crate_name: crate.name,
+                    staged_id: crate.staged_id,
+                });
+            }
+            const { resolved, missing } = resolveSpaceAssets(db, anchors.spaceId, crate.tracks.map((t) => t.portable_id));
+            resolvedByCrate.set(crate.staged_id, resolved);
+            const missingSet = new Set(missing);
+            for (const t of crate.tracks)
+                if (missingSet.has(t.portable_id))
+                    unresolvable.push(t.track_id);
+        }
+        if (unresolvable.length > 0) {
+            rollback();
+            return err("write_refused", "some staged tracks are no longer in the Serato Library space", {
+                reason: "tracks_no_longer_resolve",
+                rejected_track_ids: [...new Set(unresolvable)],
+            });
+        }
+        // The foreign-key check is about THIS write, so it is a count before and
+        // after rather than a demand for zero: a library that already carries an
+        // orphan row would otherwise refuse every apply forever, over damage the
+        // write did not cause. (The live root had none on 2026-09-15.)
+        const foreignKeyViolations = () => db.prepare("PRAGMA foreign_key_check(container)").all().length +
+            db.prepare("PRAGMA foreign_key_check(container_asset)").all().length;
+        const fkBefore = foreignKeyViolations();
+        // (A) revision first. The space-revision triggers ASSIGN
+        // space.revision := serato.revision under space.revision < serato.revision,
+        // so bumping after the inserts would leave the space revision unmoved and
+        // the crate invisible to Serato.
+        db.exec("UPDATE serato SET revision = COALESCE(revision, 0) + 1");
+        const { revision } = db.prepare("SELECT revision FROM serato").get();
+        const insertContainer = db.prepare(`INSERT INTO container (revision, parent_id, name, type, list_order, space_id, expanded, portable_id, color)
+       VALUES (?, ?, ?, 1,
+               (SELECT COALESCE(MAX(list_order), 0) + 1 FROM container WHERE parent_id = ?),
+               ?, 0, '', NULL)`);
+        const insertTrack = db.prepare("INSERT INTO container_asset (revision, container_id, space_asset_id, list_order) VALUES (?, ?, ?, ?)");
+        const applied = [];
+        for (const crate of input.crates) {
+            let containerId;
+            try {
+                // (B) no explicit id: AUTOINCREMENT keeps sqlite_sequence right, and an
+                // explicit id could collide with ids Serato hands out later. The rowid
+                // is read from THIS statement's result, before any other insert can
+                // overwrite last_insert_rowid.
+                containerId = Number(insertContainer.run(revision, anchors.rootContainerId, crate.name, anchors.rootContainerId, anchors.spaceId).lastInsertRowid);
+            }
+            catch (e) {
+                if (e.errcode === SQLITE_CONSTRAINT_UNIQUE) {
+                    // Read before rollback: a collision with a crate this same batch
+                    // inserted earlier only still has an id while that insert stands.
+                    const existingContainerId = existingCrateId(db, anchors.rootContainerId, crate.name);
+                    rollback();
+                    return err("crate_name_conflict", `a crate named "${crate.name}" already exists`, {
+                        existing_container_id: existingContainerId,
+                        crate_name: crate.name,
+                        staged_id: crate.staged_id,
+                    });
+                }
+                rollback();
+                throw e;
+            }
+            const resolved = resolvedByCrate.get(crate.staged_id) ?? new Map();
+            // (C) list_order 1..N in the staged order, which is the running order.
+            crate.tracks.forEach((track, index) => {
+                const spaceAssetId = resolved.get(track.portable_id);
+                if (spaceAssetId === undefined) {
+                    throw new Error(`staged track ${track.portable_id} lost its resolution mid-transaction`);
+                }
+                insertTrack.run(revision, containerId, spaceAssetId, index + 1);
+            });
+            applied.push({
+                staged_id: crate.staged_id,
+                name: crate.name,
+                container_id: containerId,
+                track_count: crate.tracks.length,
+            });
+        }
+        // Before COMMIT: targeted checks instead of quick_check over the whole
+        // database.
+        const problems = [];
+        const fkAfter = foreignKeyViolations();
+        if (fkAfter > fkBefore) {
+            problems.push(`foreign_key_check found ${fkAfter - fkBefore} new violation(s)`);
+        }
+        const space = db.prepare("SELECT revision FROM space WHERE id = ?").get(anchors.spaceId);
+        if (space.revision !== revision) {
+            problems.push(`space.revision is ${space.revision}, expected ${revision}`);
+        }
+        for (const a of applied) {
+            const found = db
+                .prepare("SELECT 1 FROM container WHERE id = ? AND type = 1 AND parent_id = ?")
+                .get(a.container_id, anchors.rootContainerId);
+            const { n } = db
+                .prepare("SELECT count(*) AS n FROM container_asset WHERE container_id = ?")
+                .get(a.container_id);
+            if (found === undefined)
+                problems.push(`container ${a.container_id} is not readable`);
+            if (n !== a.track_count)
+                problems.push(`container ${a.container_id} has ${n} tracks, expected ${a.track_count}`);
+        }
+        if (problems.length > 0) {
+            rollback();
+            return notCommitted("verify_in_transaction", "the write did not check out and was rolled back", {
+                problems,
+            });
+        }
+        try {
+            db.exec("COMMIT");
+        }
+        catch (e) {
+            if (db.isTransaction) {
+                // SQLite kept the transaction open: nothing was committed. Busy here
+                // is the expected cause -- a reader on another connection holds
+                // SHARED, e.g. stage_crate on a second server instance -- so it is
+                // contention, not failure, and gets a retry hint like any other.
+                rollback();
+                if (isSqliteBusy(e)) {
+                    return err("busy", `COMMIT is blocked by another reader: ${String(e)}`, {
+                        retry_after_ms: BUSY_TIMEOUT_MS,
+                    });
+                }
+                return notCommitted("commit", `COMMIT failed and the write was rolled back: ${String(e)}`);
+            }
+            // SQLite has already rolled back on its own here -- measured for
+            // IOERR_DELETE, which leaves a hot journal for the next opener.
+            return notCommitted("commit", `COMMIT failed and the write was rolled back: ${String(e)}`);
+        }
+        return { applied, revision, warnings };
+    }
+    catch (e) {
+        rollback();
+        if (isSqliteBusy(e)) {
+            // Defensive, not observed: measured with 200k container_asset rows
+            // inserted while a reader held SHARED for 60s, a page-cache spill does
+            // not surface as busy -- the transaction waited 60.4s under
+            // busy_timeout and committed, rather than throwing here. Kept in case
+            // some other mid-transaction contention does throw busy at this point.
+            return err("busy", `root.sqlite became busy mid-transaction: ${String(e)}`, {
+                retry_after_ms: BUSY_TIMEOUT_MS,
+            });
+        }
+        return notCommitted("transaction", `the write failed and was rolled back: ${String(e)}`);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * After COMMIT, on a NEW connection -- the only thing that makes
+ * committed_unverified a reachable state rather than a hope. A failure here
+ * means the data may well be in the file; the caller gets the backup paths.
+ */
+export function verifyCommitted(input, outcome) {
+    const unverified = (message, problems = []) => err("write_failed_committed_unverified", message, {
+        stage: "verify_after_commit",
+        backup_paths: input.backupPaths,
+        problems,
+    });
+    let db;
+    try {
+        db = new DatabaseSync(input.rootPath, { readOnly: true });
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+        const problems = [];
+        const { revision } = db.prepare("SELECT revision FROM serato").get();
+        if (revision !== outcome.revision)
+            problems.push(`serato.revision is ${revision}, expected ${outcome.revision}`);
+        if (outcome.applied.length > 0) {
+            // The applied crates all share one space (findAnchors resolves exactly
+            // one), so the first container's own space_id identifies it, without
+            // this read-only connection re-deriving anchors a second way.
+            const spaceRevision = db
+                .prepare("SELECT revision FROM space WHERE id = (SELECT space_id FROM container WHERE id = ?)")
+                .get(outcome.applied[0].container_id);
+            if (spaceRevision?.revision !== outcome.revision) {
+                problems.push(`space.revision is ${spaceRevision?.revision}, expected ${outcome.revision}`);
+            }
+        }
+        for (const a of outcome.applied) {
+            const row = db.prepare("SELECT name FROM container WHERE id = ?").get(a.container_id);
+            const { n } = db
+                .prepare("SELECT count(*) AS n FROM container_asset WHERE container_id = ?")
+                .get(a.container_id);
+            if (row?.name !== a.name)
+                problems.push(`container ${a.container_id} does not read back as "${a.name}"`);
+            if (n !== a.track_count)
+                problems.push(`container ${a.container_id} reads back ${n} tracks`);
+        }
+        return problems.length === 0
+            ? null
+            : unverified("the committed write did not read back", problems);
+    }
+    catch (e) {
+        return unverified(`the committed write could not be read back: ${String(e)}`);
+    }
+    finally {
+        db?.close();
+    }
+}

package/dist/args.d.ts

@@ -0,0 +1,25 @@
+import type { z } from "zod";
+import { type SeratoError } from "./errors.js";
+/**
+ * The single place raw tool arguments become typed ones, deliberately the
+ * only one: engine-dj-mcp's defect was that some tools called .parse() and
+ * others safeParse(), so one class of problem -- a malformed argument --
+ * reached the model in two different shapes.
+ *
+ * Every failure comes back as an `invalid_argument` value carrying the
+ * mandatory `reason`, never as a throw: a thrown ZodError is converted by
+ * the MCP layer into prose with no code at all (measured 2026-09-06:
+ * `{"sql":"","limit":1000}` came back as isError text reading "MCP error
+ * -32602: Input validation error: Invalid arguments for tool run_sql: Too
+ * small ..."), which the model cannot dispatch on and which contradicts the
+ * taxonomy in errors.ts.
+ *
+ * `reason` defaults to "schema_violation" but a check can name its own by
+ * passing `params: { reason: "..." }` to .refine()/.superRefine(). That is
+ * how this server's cross-field refusals -- `around` together with
+ * `min`/`max`, `crate.id` together with `crate.name`, a cursor that does not
+ * match its query -- get their specific reason without a second error path:
+ * they are refinements on the tool's own schema, and they land here like any
+ * other issue.
+ */
+export declare function parseToolArgs<T extends z.ZodType>(schema: T, raw: unknown): z.output<T> | SeratoError;