Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix(music): make album and track membership mutations atomic (#11568)
[._.]/abbca39e240e
diff --git a/scripts/lib/dbTestFiles.js b/scripts/lib/dbTestFiles.jsindex 04693b4617..82c792cf48 100644--- a/scripts/lib/dbTestFiles.js+++ b/scripts/lib/dbTestFiles.js@@ -9,6 +9,7 @@ import { posix } from 'node:path';* listed explicitly below (the drift guard fails the build if you forget).*/export const DB_TEST_INCLUDE = [+ 'services/trackAlbumMembership.db.test.js','services/stackerNews.db.test.js','services/peerExecutionLedger.db.test.js','services/voice/profiles.db.test.js',diff --git a/server/routes/albums.js b/server/routes/albums.jsindex fe25fa8816..3b116906d4 100644--- a/server/routes/albums.js+++ b/server/routes/albums.js@@ -17,7 +17,7 @@ import { z } from 'zod';import { asyncHandler, ServerError } from '../lib/errorHandler.js';import { validateRequest, isPaginationRequested, paginateArray } from '../lib/validation.js';import * as albums from '../services/albums/index.js';-import * as tracks from '../services/tracks/index.js';+import { createAlbumWithTracks, updateAlbumWithTracks, deleteAlbumWithTracks } from '../services/trackAlbumMembership.js';const router = Router();@@ -53,58 +53,6 @@ const patchSchema = z.object({trackIds: trackIdsField.optional(),}).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' });-// Membership single-source-of-truth reconcile. The album's `trackIds` carry the-// ORDER; each track's `albumId` is the membership pointer the Tracks API reports.-// After an album write, stamp `albumId` on its member tracks and clear it on any-// track that used to belong to this album but was dropped — so the two views-// never disagree (a track removed from the album stops reporting that albumId,-// and an added track starts). Best-effort per track: a missing/deleted track id-// in `trackIds` is simply skipped (updateTrack 404s are swallowed). Runs after-// the album persists so a rejected album write doesn't mutate track membership.-async function reconcileAlbumMembership(album) {- const desired = new Set(album.trackIds || []);- const all = await tracks.listTracks().catch(() => []);- const byId = new Map(all.map((t) => [t.id, t]));- const ops = [];- // A listed track that currently belongs to a DIFFERENT album is being moved- // here — drop it from that other album's ordered `trackIds` so the old album- // stops listing it (it now reports a different `albumId`). Call the album- // SERVICE (not this route) so the write can't re-enter reconcile and loop.- // Coalesce per-source-album removals into one update each.- const removalsByAlbum = new Map();- // Clear albumId on tracks that point here but are no longer listed.- for (const t of all) {- if (t.albumId === album.id && !desired.has(t.id)) {- ops.push(tracks.updateTrack(t.id, { albumId: '' }).catch(() => {}));- }- }- // Stamp albumId on listed tracks that don't already point here, and record any- // prior album they're being stolen from.- for (const id of desired) {- const t = byId.get(id);- if (t && t.albumId !== album.id) {- ops.push(tracks.updateTrack(id, { albumId: album.id }).catch(() => {}));- if (t.albumId) {- const set = removalsByAlbum.get(t.albumId) || new Set();- set.add(id);- removalsByAlbum.set(t.albumId, set);- }- }- }- await Promise.all(ops);- // Now prune each stolen track from its former album's list (one write per- // source album; skips the album being saved and any missing/deleted album).- await Promise.all([...removalsByAlbum.entries()].map(async ([srcAlbumId, stolen]) => {- if (srcAlbumId === album.id) return;- const src = await albums.getAlbum(srcAlbumId).catch(() => null);- if (!src) return;- const nextIds = (src.trackIds || []).filter((id) => !stolen.has(id));- if (nextIds.length !== (src.trackIds || []).length) {- await albums.updateAlbum(srcAlbumId, { trackIds: nextIds }).catch(() => {});- }- }));-}-// Backward-compatible by default: returns the full albums array. When a client// passes `limit`/`offset`, the response becomes the bounded// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.@@ -116,8 +64,7 @@ router.get('/', asyncHandler(async (req, res) => {router.post('/', asyncHandler(async (req, res) => {const body = validateRequest(createSchema, req.body ?? {});- const album = await albums.createAlbum(body);- await reconcileAlbumMembership(album);+ const album = await createAlbumWithTracks(body);res.status(201).json(album);}));@@ -129,17 +76,12 @@ router.get('/:id', asyncHandler(async (req, res) => {router.patch('/:id', asyncHandler(async (req, res) => {const body = validateRequest(patchSchema, req.body ?? {});- const album = await albums.updateAlbum(req.params.id, body);- // Only reconcile when the membership list was part of this write.- if ('trackIds' in body) await reconcileAlbumMembership(album);+ const album = await updateAlbumWithTracks(req.params.id, body);res.json(album);}));router.delete('/:id', asyncHandler(async (req, res) => {- const result = await albums.deleteAlbum(req.params.id);- // Orphan the album's tracks (clear their albumId) so they revert to singles- // rather than pointing at a tombstoned album.- await reconcileAlbumMembership({ id: req.params.id, trackIds: [] });+ const result = await deleteAlbumWithTracks(req.params.id);res.json(result);}));diff --git a/server/routes/tracks.js b/server/routes/tracks.jsindex e95048dd93..066dcee437 100644--- a/server/routes/tracks.js+++ b/server/routes/tracks.js@@ -50,7 +50,7 @@ import { PATHS } from '../lib/fileUtils.js';import { probeVideoDuration } from '../lib/ffmpeg.js';import * as tracks from '../services/tracks/index.js';import { attachAudioAsRender } from '../services/trackAudioAttach.js';-import { createTrackWithAlbum, updateTrackWithAlbum, removeTrackFromAlbum } from '../services/trackAlbumMembership.js';+import { createTrackWithAlbum, updateTrackWithAlbum, deleteTrackWithAlbum } from '../services/trackAlbumMembership.js';import {listMusicLibrary, importUploadedTrack, statMusicTrack,isSupportedMusicUpload, assertSafeMusicFilename, MUSIC_UPLOAD_MAX_BYTES,@@ -225,17 +225,12 @@ router.get('/:id', asyncHandler(async (req, res) => {router.patch('/:id', asyncHandler(async (req, res) => {const body = validateRequest(patchSchema, req.body ?? {});- const prev = await requireTrack(req.params.id);- const track = await updateTrackWithAlbum(prev, body);+ const track = await updateTrackWithAlbum({ id: req.params.id }, body);res.json(track);}));router.delete('/:id', asyncHandler(async (req, res) => {- const prev = await tracks.getTrack(req.params.id).catch(() => null);- const result = await tracks.deleteTrack(req.params.id);- // Drop the deleted track from its album's ordered list so the album doesn't- // render a dangling (missing) entry.- if (prev?.albumId) await removeTrackFromAlbum(req.params.id, prev.albumId);+ const result = await deleteTrackWithAlbum(req.params.id);res.json(result);}));diff --git a/server/services/albums/db.js b/server/services/albums/db.jsindex 89c673ec7d..6717e8c6c6 100644--- a/server/services/albums/db.js+++ b/server/services/albums/db.js@@ -46,15 +46,17 @@ async function persist(exec, album) {return album;}-export async function listAlbums({ includeDeleted = false } = {}) {+export async function listAlbums({ includeDeleted = false, client } = {}) {+ const exec = client ? client.query.bind(client) : query;const { rows } = includeDeleted- ? await query(`SELECT data FROM albums ORDER BY title ASC`)- : await query(`SELECT data FROM albums WHERE deleted = FALSE ORDER BY title ASC`);+ ? await exec(`SELECT data FROM albums ORDER BY title ASC`)+ : await exec(`SELECT data FROM albums WHERE deleted = FALSE ORDER BY title ASC`);return rows.map(rowToAlbum);}-export async function getAlbum(id, { includeDeleted = false } = {}) {- const { rows } = await query(`SELECT data FROM albums WHERE id = $1`, [id]);+export async function getAlbum(id, { includeDeleted = false, client } = {}) {+ const exec = client ? client.query.bind(client) : query;+ const { rows } = await exec(`SELECT data FROM albums WHERE id = $1${client ? ' FOR UPDATE' : ''}`, [id]);const album = rowToAlbum(rows[0]);if (!album) return null;return includeDeleted || !album.deleted ? album : null;@@ -68,16 +70,16 @@ export async function listAlbumIds({ includeDeleted = false } = {}) {return rows.map((r) => r.id);}-export async function createAlbum(input) {+export async function createAlbum(input, { client } = {}) {const album = buildAlbumRecord(input, { id: `album-${randomUUID()}`, now: new Date().toISOString() });if (!album) throw new ServerError('Invalid album payload', { status: 400, code: 'VALIDATION' });- await persist(query, album);+ await persist(client ? client.query.bind(client) : query, album);console.log(`💿 Created album: ${album.id} (${album.title})`);return album;}-export async function updateAlbum(id, patch) {- return withTransaction(async (client) => {+export async function updateAlbum(id, patch, { client: transactionClient } = {}) {+ const mutate = async (client) => {const sel = await client.query(`SELECT data FROM albums WHERE id = $1 FOR UPDATE`, [id]);const current = rowToAlbum(sel.rows[0]);if (!current || current.deleted) throw new ServerError('Album not found', { status: 404, code: 'NOT_FOUND' });@@ -85,11 +87,12 @@ export async function updateAlbum(id, patch) {if (!next) throw new ServerError('Invalid album payload', { status: 400, code: 'VALIDATION' });await persist(client.query.bind(client), next);return next;- });+ };+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);}-export async function deleteAlbum(id) {- return withTransaction(async (client) => {+export async function deleteAlbum(id, { client: transactionClient } = {}) {+ const mutate = async (client) => {const sel = await client.query(`SELECT data FROM albums WHERE id = $1 FOR UPDATE`, [id]);const current = rowToAlbum(sel.rows[0]);if (!current || current.deleted) throw new ServerError('Album not found', { status: 404, code: 'NOT_FOUND' });@@ -97,7 +100,8 @@ export async function deleteAlbum(id) {const next = { ...current, deleted: true, deletedAt: now, updatedAt: now };await persist(client.query.bind(client), next);return { id };- });+ };+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);}/**diff --git a/server/services/albums/file.js b/server/services/albums/file.jsindex 6e98371f1f..0dd0f8b82a 100644--- a/server/services/albums/file.js+++ b/server/services/albums/file.js@@ -10,6 +10,7 @@import { join } from 'path';import { randomUUID } from 'crypto';import { PATHS, readJSONFile, atomicWrite, ensureDir } from '../../lib/fileUtils.js';+import { readMusicFile, writeMusicFile } from '../musicMembershipMutation.js';import { ServerError } from '../../lib/errorHandler.js';import { sanitizeAlbum, buildAlbumRecord, applyAlbumPatch, mergeAlbumRecord } from './logic.js';import {@@ -20,14 +21,18 @@ import {const ALBUMS_FILE = join(PATHS.data, 'albums.json');async function loadAll() {- // Albums are durable user records; never save an empty fallback over unreadable bytes.- const raw = await readJSONFile(ALBUMS_FILE, [], { strict: true });- return (Array.isArray(raw) ? raw : []).map(sanitizeAlbum).filter(Boolean);+ return readMusicFile('albums', async () => {+ // Albums are durable user records; never save an empty fallback over unreadable bytes.+ const raw = await readJSONFile(ALBUMS_FILE, [], { strict: true });+ return (Array.isArray(raw) ? raw : []).map(sanitizeAlbum).filter(Boolean);+ });}async function saveAll(albums) {- await ensureDir(PATHS.data);- await atomicWrite(ALBUMS_FILE, albums);+ return writeMusicFile('albums', albums, async (records) => {+ await ensureDir(PATHS.data);+ await atomicWrite(ALBUMS_FILE, records);+ });}const byTitle = (a, b) => (a.title || '').localeCompare(b.title || '');diff --git a/server/services/albums/index.js b/server/services/albums/index.jsindex 38f96b69c5..197f904d42 100644--- a/server/services/albums/index.js+++ b/server/services/albums/index.js@@ -11,6 +11,7 @@*/import { createRecordStoreBackendSelector } from '../../lib/pgFileFacade.js';+import { withMusicMutation, musicMutationClient, afterMusicCommit } from '../musicMembershipMutation.js';import { emitRecordUpdated, emitRecordDeleted, autoSubscribeRecordToAllPeers } from '../sharing/recordEvents.js';export {@@ -37,6 +38,9 @@ const { selectBackend, getBackendName, reset } = createRecordStoreBackendSelectorequireDbMessage: 'Albums require PostgreSQL — run `npm run setup:db` (dev/test only: set MEMORY_BACKEND=file in .env for the unsupported file backend)',});+// The shared mutation boundary prepares both stores before reserving a client.+export { selectBackend as prepareAlbumsBackend };+/** Name of the active backend, or null before first call (for diagnostics/tests). */export function getAlbumsBackendName() {return getBackendName();@@ -48,7 +52,7 @@ export function _resetAlbumsBackend() {}export async function listAlbums(options = {}) {- return (await selectBackend()).listAlbums(options);+ return (await selectBackend()).listAlbums({ ...options, client: musicMutationClient() });}export async function listAlbumIds(options = {}) {@@ -56,7 +60,7 @@ export async function listAlbumIds(options = {}) {}export async function getAlbum(id, options = {}) {- return (await selectBackend()).getAlbum(id, options);+ return (await selectBackend()).getAlbum(id, { ...options, client: musicMutationClient() });}function announceNewAlbum(id) {@@ -65,21 +69,27 @@ function announceNewAlbum(id) {}export async function createAlbum(input) {- const album = await (await selectBackend()).createAlbum(input);- announceNewAlbum(album.id);- return album;+ return withMusicMutation(async () => {+ const album = await (await selectBackend()).createAlbum(input, { client: musicMutationClient() });+ afterMusicCommit(() => announceNewAlbum(album.id));+ return album;+ });}export async function updateAlbum(id, patch) {- const next = await (await selectBackend()).updateAlbum(id, patch);- emitRecordUpdated('album', next.id);- return next;+ return withMusicMutation(async () => {+ const next = await (await selectBackend()).updateAlbum(id, patch, { client: musicMutationClient() });+ afterMusicCommit(() => emitRecordUpdated('album', next.id));+ return next;+ });}export async function deleteAlbum(id) {- const result = await (await selectBackend()).deleteAlbum(id);- emitRecordDeleted('album', result.id);- return result;+ return withMusicMutation(async () => {+ const result = await (await selectBackend()).deleteAlbum(id, { client: musicMutationClient() });+ afterMusicCommit(() => emitRecordDeleted('album', result.id));+ return result;+ });}/** Merge an incoming batch of album records from a peer (LWW, tombstone-aware). */diff --git a/server/services/musicMembershipMutation.js b/server/services/musicMembershipMutation.jsnew file mode 100644index 0000000000..75dcc3dfdc--- /dev/null+++ b/server/services/musicMembershipMutation.js@@ -0,0 +1,88 @@+/** Local album/track unit of work. Federation retains its per-record LWW path. */+import { AsyncLocalStorage } from 'node:async_hooks';+import { withTransaction } from '../lib/db.js';+import { isFileBackend } from '../lib/pgFileFacade.js';+import { ServerError } from '../lib/errorHandler.js';+import { createFileWriteQueue } from '../lib/fileWriteQueue.js';++const mutations = new AsyncLocalStorage();+const queueFiles = createFileWriteQueue();++export const musicMutationClient = () => mutations.getStore()?.client;++export function afterMusicCommit(announce) {+ const context = mutations.getStore();+ if (context) context.events.push(announce);+ else announce();+}++// The unsupported file backend stages both arrays before touching disk. A+// failed second write restores the first, making an ordinary retry safe. This+// is NOT crash atomic: production requires PostgreSQL.+export async function readMusicFile(key, load) {+ const context = mutations.getStore();+ if (!context?.files) return load();+ if (!context.files.has(key)) {+ const original = await load();+ context.files.set(key, { original, records: structuredClone(original), save: null });+ }+ return structuredClone(context.files.get(key).records);+}++export async function writeMusicFile(key, records, save) {+ const context = mutations.getStore();+ if (!context?.files) return save(records);+ const entry = context.files.get(key);+ entry.records = records;+ entry.save = save;+}++async function commitFiles(files) {+ const written = [];+ try {+ for (const entry of files.values()) {+ if (!entry.save) continue;+ await entry.save(entry.records);+ written.push(entry);+ }+ } catch (error) {+ const restored = await Promise.allSettled(written.map((entry) => entry.save(entry.original)));+ if (restored.some((result) => result.status === 'rejected')) {+ throw new ServerError('Music membership file recovery failed. Reconcile albums.json and tracks.json before retrying; use PostgreSQL for atomic writes.', {+ code: 'MUSIC_MEMBERSHIP_RECONCILIATION_REQUIRED',+ });+ }+ throw new ServerError('Music membership was not saved. Previous records were restored; retry the request.', {+ code: 'MUSIC_MEMBERSHIP_WRITE_FAILED', context: { cause: error.code || 'WRITE_FAILED' },+ });+ }+}++export function withMusicMutation(operation) {+ if (mutations.getStore()) return operation();+ const run = async () => {+ const context = { events: [] };+ let result;+ if (isFileBackend()) {+ context.files = new Map();+ result = await mutations.run(context, operation);+ await commitFiles(context.files);+ } else {+ // Backend selection performs pool-based health/schema work. Finish it+ // BEFORE checking out a transaction client: a cold burst can otherwise+ // reserve the entire pool while its lock holder needs one more client.+ const [albums, tracks] = await Promise.all([import('./albums/index.js'), import('./tracks/index.js')]);+ await Promise.all([albums.prepareAlbumsBackend(), tracks.prepareTracksBackend()]);+ result = await withTransaction(async (client) => {+ // One domain lock, acquired before any row lock or membership read.+ // All LOCAL writers share it, including track metadata saves.+ await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', ['portos:music-membership']);+ context.client = client;+ return mutations.run(context, operation);+ });+ }+ for (const announce of context.events) announce();+ return result;+ };+ return isFileBackend() ? queueFiles(run) : run();+}diff --git a/server/services/musicMembershipStartup.test.js b/server/services/musicMembershipStartup.test.jsnew file mode 100644index 0000000000..93324d70b7--- /dev/null+++ b/server/services/musicMembershipStartup.test.js@@ -0,0 +1,49 @@+import { describe, expect, it, vi } from 'vitest';++const pool = vi.hoisted(() => ({ reserved: 0, capacity: 20 }));+// A bounded pool stand-in rejects instead of waiting ten seconds when cold+// backend health checks compete for a fully reserved transaction pool.+vi.mock('../lib/db.js', () => ({+ checkHealth: async () => {+ if (pool.reserved === pool.capacity) throw new Error('Synthetic pool exhausted during backend initialization');+ return { connected: true };+ },+ ensureSchema: async () => {},+ withTransaction: async (operation) => {+ pool.reserved++;+ await Promise.resolve();+ try {+ return await operation({ query: async () => ({ rows: [] }) });+ } finally {+ pool.reserved--;+ }+ },+}));+vi.mock('../lib/pgFileFacade.js', async (importOriginal) => {+ const actual = await importOriginal();+ return {+ ...actual,+ isFileBackend: () => false,+ createRecordStoreBackendSelector: (options) => actual.createRecordStoreBackendSelector({ ...options, isTestMode: () => false }),+ };+});+vi.mock('./albums/db.js', () => ({}));+vi.mock('./tracks/db.js', () => ({+ createTrack: async (input) => ({ id: `track-${input.title}`, ...input }),+}));++import { createTrackWithAlbum } from './trackAlbumMembership.js';++describe('cold music store startup', () => {+ it('completes a full pool of concurrent first writes without starving backend initialization', async () => {+ vi.stubEnv('MEMORY_BACKEND', '');+ try {+ const saved = await Promise.all(Array.from({ length: pool.capacity }, (_, i) =>+ createTrackWithAlbum({ title: `example-${i}` })));+ expect(new Set(saved.map(({ track }) => track.id)).size).toBe(pool.capacity);+ expect(saved.every(({ track }) => track.albumId === '')).toBe(true);+ } finally {+ vi.unstubAllEnvs();+ }+ });+});diff --git a/server/services/trackAlbumMembership.db.test.js b/server/services/trackAlbumMembership.db.test.jsnew file mode 100644index 0000000000..9084102091--- /dev/null+++ b/server/services/trackAlbumMembership.db.test.js@@ -0,0 +1,194 @@+/** Real transactions against portos_test; no live database or media/provider work. */+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';+import express from 'express';+import { checkHealth, query, close } from '../lib/db.js';+import { requireDbOrSkip } from '../lib/dbTestGate.js';+import { request } from '../lib/testHelper.js';+import { errorMiddleware } from '../lib/errorHandler.js';++const fixture = await vi.hoisted(async () => {+ const { randomUUID } = await import('node:crypto');+ return { schema: 'music_membership_' + randomUUID().replaceAll('-', ''), created: false };+});+const fault = vi.hoisted(() => ({ failWrite: 0, writes: 0 }));+// Every connection in this suite's pool has ONLY the invocation-owned schema+// in its search path. Never initialize or clean up the shared public schema.+vi.mock('pg', async (importOriginal) => {+ const actual = await importOriginal();+ return { ...actual, default: {+ ...actual.default,+ Pool: function Pool(options) {+ return new actual.default.Pool({ ...options, options: '-csearch_path=' + fixture.schema });+ },+ } };+});+// Only inject a persistence failure. BEGIN/COMMIT/ROLLBACK, row locks, advisory+// locks, reads and every other write still execute on the real PostgreSQL pool.+vi.mock('../lib/db.js', async (importOriginal) => {+ const actual = await importOriginal();+ return {+ ...actual,+ ensureSchema: async () => {+ if (!fixture.created) throw new Error('Fixture schema must exist before initializing music stores');+ const { libraryDdl } = await import('../lib/db/schema/library.js');+ for (const sql of libraryDdl) await actual.query(sql);+ },+ withTransaction: (operation) => actual.withTransaction((client) => operation({+ query: async (sql, params) => {+ if (/^INSERT INTO (albums|tracks)\b/.test(sql) && ++fault.writes === fault.failWrite) {+ // A real SQL error aborts this PostgreSQL transaction.+ return client.query('SELECT 1 / 0');+ }+ return client.query(sql, params);+ },+ })),+ };+});+vi.mock('../lib/pgFileFacade.js', async (importOriginal) => {+ const actual = await importOriginal();+ return {+ ...actual,+ isFileBackend: () => false,+ createRecordStoreBackendSelector: (options) => actual.createRecordStoreBackendSelector({ ...options, isTestMode: () => false }),+ };+});++const health = await checkHealth();+const runDb = requireDbOrSkip('trackAlbumMembership.db.test', health.connected, health.error);+const prefix = 'Example membership fixture';+const events = [];+const subscribe = vi.fn(async () => {});+let albums;+let tracks;+let membership;+let bus;+let app;+const onUpdated = (event) => events.push(['updated', event]);+const onDeleted = (event) => events.push(['deleted', event]);++const createAlbum = (input = {}) => membership.createAlbumWithTracks({ title: prefix, ...input });+const createTrack = async (albumId = '') => (await membership.createTrackWithAlbum({ title: prefix, albumId })).track;+const snapshot = async () => ({+ albums: (await query('SELECT data FROM albums WHERE title = $1 ORDER BY id', [prefix])).rows,+ tracks: (await query('SELECT data FROM tracks WHERE title = $1 ORDER BY id', [prefix])).rows,+});++async function cleanup() {+ await query('DELETE FROM tracks WHERE title = $1', [prefix]);+ await query('DELETE FROM albums WHERE title = $1', [prefix]);+}++describe.skipIf(!runDb)('atomic local album membership on PostgreSQL', () => {+ beforeAll(async () => {+ expect((await query('SELECT current_database() AS name')).rows[0].name).toBe('portos_test');+ vi.stubEnv('MEMORY_BACKEND', '');+ await query(`CREATE SCHEMA ${fixture.schema}`);+ fixture.created = true;+ expect((await query('SHOW search_path')).rows[0].search_path).toBe(fixture.schema);+ albums = await import('./albums/index.js');+ tracks = await import('./tracks/index.js');+ membership = await import('./trackAlbumMembership.js');+ await albums.prepareAlbumsBackend();+ await tracks.prepareTracksBackend();+ bus = await import('./sharing/recordEvents.js');+ bus.recordEvents.on('updated', onUpdated);+ bus.recordEvents.on('deleted', onDeleted);+ bus.registerSubscriptionAdapter({ autoSubscribeRecordToAllPeers: subscribe });+ const { default: routes } = await import('../routes/albums.js');+ app = express();+ app.use(express.json());+ app.use('/api/albums', routes);+ app.use(errorMiddleware);+ });+ beforeEach(async () => {+ await cleanup();+ fault.failWrite = 0;+ fault.writes = 0;+ events.length = 0;+ subscribe.mockClear();+ });+ afterAll(async () => {+ if (bus) {+ bus.recordEvents.off('updated', onUpdated);+ bus.recordEvents.off('deleted', onDeleted);+ bus.__resetSubscriptionAdapter();+ }+ try {+ if (fixture.created) await query(`DROP SCHEMA ${fixture.schema} CASCADE`);+ } finally {+ vi.unstubAllEnvs();+ await close();+ }+ });++ it('retains competing additions and admits only one claimant for the final slot', async () => {+ const album = await createAlbum();+ const additions = await Promise.all([createTrack(album.id), createTrack(album.id)]);+ expect((await albums.getAlbum(album.id)).trackIds.sort()).toEqual(additions.map((t) => t.id).sort());+ const full = await createAlbum({ trackIds: Array.from({ length: albums.TRACK_IDS_MAX - 1 }, (_, i) => `track-example-${i}`) });+ const results = await Promise.allSettled([createTrack(full.id), createTrack(full.id)]);+ expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);+ expect(results.find((result) => result.status === 'rejected').reason.code).toBe('ALBUM_FULL');+ expect((await albums.getAlbum(full.id)).trackIds).toHaveLength(albums.TRACK_IDS_MAX);+ const saved = (await snapshot()).tracks.map(({ data }) => data);+ expect(saved.filter((track) => track.albumId === full.id)).toHaveLength(1);+ });++ // Each case represents a different public mutation whose partial commit+ // would require a different repair (duplicate create, stale move or tombstone).+ it.each(['album create', 'album edit', 'album delete', 'track create', 'track move', 'track delete'])(+ 'rolls back %s on a later write failure, emits nothing, and succeeds on retry', async (operation) => {+ const source = await createAlbum({ description: 'Preserved metadata' });+ const destination = await createAlbum();+ const track = await createTrack(source.id);+ const before = await snapshot();+ const actions = {+ 'album create': () => request(app).post('/api/albums').send({ title: prefix, trackIds: [track.id] }),+ 'album edit': () => request(app).patch(`/api/albums/${source.id}`).send({ trackIds: [] }),+ 'album delete': () => request(app).delete(`/api/albums/${source.id}`),+ 'track create': () => createTrack(source.id),+ 'track move': () => membership.updateTrackWithAlbum(track, { albumId: destination.id }),+ 'track delete': () => membership.deleteTrackWithAlbum(track.id),+ };+ fault.writes = 0;+ fault.failWrite = operation === 'track move' ? 3 : 2;+ events.length = 0;+ subscribe.mockClear();+ if (operation.startsWith('album')) {+ const response = await actions[operation]();+ expect(response.status).toBe(500);+ expect(response.body).toMatchObject({ code: expect.any(String), error: expect.any(String) });+ } else {+ await expect(actions[operation]()).rejects.toThrow('division by zero');+ }+ expect(await snapshot()).toEqual(before);+ expect(events).toEqual([]);+ expect(subscribe).not.toHaveBeenCalled();+ fault.failWrite = 0;+ const result = await actions[operation]();+ if (operation.startsWith('album')) expect(result.status).toBe(operation === 'album create' ? 201 : 200);+ expect(events.length).toBeGreaterThan(0);+ if (operation === 'album create') expect((await snapshot()).albums).toHaveLength(3);+ if (operation === 'track create') expect((await snapshot()).tracks).toHaveLength(2);+ if (operation === 'album delete') expect((await tracks.getTrack(track.id)).albumId).toBe('');+ if (operation === 'track delete') expect((await albums.getAlbum(source.id)).trackIds).toEqual([]);+ },+ );++ it('shares the lock across album edits and stale track moves without replacing metadata', async () => {+ const source = await createAlbum();+ const destination = await createAlbum({ genre: 'Example genre' });+ const third = await createAlbum();+ const track = await createTrack(source.id);+ const neighbor = await createTrack(destination.id);+ await membership.updateAlbumWithTracks(destination.id, { trackIds: [neighbor.id, track.id] });+ await Promise.all([+ membership.updateTrackWithAlbum(track, { albumId: third.id }),+ membership.updateAlbumWithTracks(destination.id, { description: 'Example description' }),+ ]);+ expect(await albums.getAlbum(destination.id)).toMatchObject({ trackIds: [neighbor.id], genre: 'Example genre', description: 'Example description' });+ expect((await albums.getAlbum(source.id)).trackIds).toEqual([]);+ expect((await tracks.getTrack(track.id)).albumId).toBe(third.id);+ expect((await albums.getAlbum(third.id)).trackIds).toEqual([track.id]);+ });+});diff --git a/server/services/trackAlbumMembership.js b/server/services/trackAlbumMembership.jsindex 1d174b282a..5ad0e36d4e 100644--- a/server/services/trackAlbumMembership.js+++ b/server/services/trackAlbumMembership.js@@ -7,6 +7,7 @@ import { ServerError } from '../lib/errorHandler.js';import { TRACK_IDS_MAX } from './albums/logic.js';import * as albums from './albums/index.js';import * as tracks from './tracks/index.js';+import { withMusicMutation } from './musicMembershipMutation.js';async function destinationAlbum(albumId, trackId) {if (!albumId) return null;@@ -26,7 +27,7 @@ async function appendTrackToAlbum(trackId, album) {await albums.updateAlbum(album.id, { trackIds: [...(album.trackIds || []), trackId] });}-export async function removeTrackFromAlbum(trackId, albumId) {+async function removeTrackFromAlbum(trackId, albumId) {if (!albumId) return;const album = await albums.getAlbum(albumId);if (album?.trackIds?.includes(trackId)) {@@ -36,22 +37,78 @@ export async function removeTrackFromAlbum(trackId, albumId) {/** Completed audio may survive an unavailable destination as a single. */export async function createTrackWithAlbum(input, { preserveUnassigned = false } = {}) {- let albumAssignmentError = null;- const album = await destinationAlbum(input.albumId).catch((err) => {- if (!preserveUnassigned || !['ALBUM_FULL', 'ALBUM_NOT_FOUND'].includes(err.code)) throw err;- albumAssignmentError = { code: err.code, message: err.message };- return null;+ return withMusicMutation(async () => {+ let albumAssignmentError = null;+ const album = await destinationAlbum(input.albumId).catch((err) => {+ if (!preserveUnassigned || !['ALBUM_FULL', 'ALBUM_NOT_FOUND'].includes(err.code)) throw err;+ albumAssignmentError = { code: err.code, message: err.message };+ return null;+ });+ const track = await tracks.createTrack({ ...input, albumId: album?.id || '' });+ await appendTrackToAlbum(track.id, album);+ return { track, albumAssignmentError };});- const track = await tracks.createTrack({ ...input, albumId: album?.id || '' });- await appendTrackToAlbum(track.id, album);- return { track, albumAssignmentError };}export async function updateTrackWithAlbum(current, patch) {- if (!('albumId' in patch)) return tracks.updateTrack(current.id, patch);- const album = await destinationAlbum(patch.albumId, current.id);- const track = await tracks.updateTrack(current.id, patch);- await appendTrackToAlbum(track.id, album);- if (current.albumId !== track.albumId) await removeTrackFromAlbum(track.id, current.albumId);- return track;+ return withMusicMutation(async () => {+ // Callers may have read the track before another move/delete committed.+ const fresh = await tracks.getTrack(current.id);+ if (!fresh) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });+ if (!('albumId' in patch)) return tracks.updateTrack(fresh.id, patch);+ const album = await destinationAlbum(patch.albumId, fresh.id);+ const track = await tracks.updateTrack(fresh.id, patch);+ await appendTrackToAlbum(track.id, album);+ if (fresh.albumId !== track.albumId) await removeTrackFromAlbum(track.id, fresh.albumId);+ return track;+ });+}++export async function deleteTrackWithAlbum(id) {+ return withMusicMutation(async () => {+ const track = await tracks.getTrack(id);+ if (!track) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });+ await removeTrackFromAlbum(id, track.albumId);+ return tracks.deleteTrack(id);+ });+}++async function reconcileAlbumMembership(album) {+ const desired = new Set(album.trackIds || []);+ const all = await tracks.listTracks();+ for (const track of all) {+ if (desired.has(track.id)) {+ if (track.albumId === album.id) continue;+ await removeTrackFromAlbum(track.id, track.albumId);+ await tracks.updateTrack(track.id, { albumId: album.id });+ } else if (track.albumId === album.id) {+ await tracks.updateTrack(track.id, { albumId: '' });+ }+ }+ // Missing/deleted ids remain tolerated, as in the existing album contract.+ // Read/write failures propagate and roll back the entire mutation.+}++export async function createAlbumWithTracks(input) {+ return withMusicMutation(async () => {+ const album = await albums.createAlbum(input);+ await reconcileAlbumMembership(album);+ return album;+ });+}++export async function updateAlbumWithTracks(id, patch) {+ return withMusicMutation(async () => {+ const album = await albums.updateAlbum(id, patch);+ if ('trackIds' in patch) await reconcileAlbumMembership(album);+ return album;+ });+}++export async function deleteAlbumWithTracks(id) {+ return withMusicMutation(async () => {+ const result = await albums.deleteAlbum(id);+ await reconcileAlbumMembership({ id, trackIds: [] });+ return result;+ });}diff --git a/server/services/trackAlbumMembership.test.js b/server/services/trackAlbumMembership.test.jsindex 3012d11182..af04444285 100644--- a/server/services/trackAlbumMembership.test.js+++ b/server/services/trackAlbumMembership.test.js@@ -1,125 +1,171 @@-import { beforeEach, describe, expect, it, vi } from 'vitest';-import { buildAlbumRecord, TRACK_IDS_MAX } from './albums/logic.js';-import { buildTrackRecord } from './tracks/logic.js';+import { beforeEach, afterAll, describe, expect, it, vi } from 'vitest';+import express from 'express';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { request } from '../lib/testHelper.js';+import { errorMiddleware } from '../lib/errorHandler.js';-const records = vi.hoisted(() => ({ albums: new Map(), tracks: new Map() }));--// Exercise the real stored shapes: returning a patch verbatim would hide the-// album sanitizer silently dropping the appended 201st track while the caller-// still reports success.-vi.mock('./albums/index.js', async () => {- const { applyAlbumPatch } = await import('./albums/logic.js');- return {- getAlbum: async (id) => records.albums.get(id) || null,- updateAlbum: async (id, patch) => {- const next = applyAlbumPatch(records.albums.get(id), patch);- records.albums.set(id, next);- return next;- },- };-});-vi.mock('./tracks/index.js', async () => {- const logic = await import('./tracks/logic.js');+const failure = vi.hoisted(() => ({ writes: [], reads: null }));+const dataRoot = mkdtempSync(join(tmpdir(), 'music-membership-'));+vi.mock('../lib/fileUtils.js', async (importOriginal) => {+ const actual = await importOriginal();return {- ...logic,- getTrack: async (id) => records.tracks.get(id) || null,- createTrack: async (input) => {- const next = logic.buildTrackRecord(input, { id: 'track-new', now: '2026-01-01T00:00:00.000Z' });- records.tracks.set(next.id, next);- return next;+ ...actual,+ PATHS: { ...actual.PATHS, data: dataRoot },+ readJSONFile: async (path, ...args) => {+ if (failure.reads && path.endsWith(failure.reads)) throw new Error('Synthetic read failure');+ return actual.readJSONFile(path, ...args);},- updateTrack: async (id, patch) => {- const next = logic.applyTrackPatch(records.tracks.get(id), patch);- records.tracks.set(id, next);- return next;+ atomicWrite: async (path, records) => {+ if (failure.writes.length && path.endsWith(failure.writes[0])) {+ failure.writes.shift();+ throw new Error('Synthetic write failure');+ }+ return actual.atomicWrite(path, records);},};});-import { createTrackWithAlbum, updateTrackWithAlbum, removeTrackFromAlbum } from './trackAlbumMembership.js';--const now = '2026-01-01T00:00:00.000Z';+const albums = await import('./albums/index.js');+const tracks = await import('./tracks/index.js');+const membership = await import('./trackAlbumMembership.js');+const { recordEvents, registerSubscriptionAdapter, __resetSubscriptionAdapter } = await import('./sharing/recordEvents.js');+const { default: routes } = await import('../routes/albums.js');+const app = express();+app.use(express.json());+app.use('/api/albums', routes);+app.use(errorMiddleware);+const events = [];+const updated = (...args) => events.push(['updated', ...args]);+const deleted = (...args) => events.push(['deleted', ...args]);+recordEvents.on('updated', updated);+recordEvents.on('deleted', deleted);+const subscribe = vi.fn(async () => {});-function seedAlbum(id, count) {- const album = buildAlbumRecord({- title: 'Example Album', trackIds: Array.from({ length: count }, (_, i) => `track-example-${i}`),- }, { id, now });- records.albums.set(id, album);- return album;-}+beforeEach(() => {+ rmSync(dataRoot, { recursive: true, force: true });+ failure.writes = [];+ failure.reads = null;+ events.length = 0;+ subscribe.mockClear();+ registerSubscriptionAdapter({ autoSubscribeRecordToAllPeers: subscribe });+});+afterAll(() => {+ recordEvents.off('updated', updated);+ recordEvents.off('deleted', deleted);+ __resetSubscriptionAdapter();+ rmSync(dataRoot, { recursive: true, force: true });+});-function seedAssignedTrack() {- const track = buildTrackRecord({ title: 'Example Track', albumId: 'album-old' }, { id: 'track-existing', now });- const album = buildAlbumRecord({ title: 'Previous Album', trackIds: [track.id] }, { id: track.albumId, now });- records.tracks.set(track.id, track);- records.albums.set(album.id, album);- return { track, album };-}+const createAlbum = (input = {}) => membership.createAlbumWithTracks({ title: 'Example Album', ...input });+const createTrack = async (albumId = '') => (await membership.createTrackWithAlbum({ title: 'Example Track', albumId })).track;-describe('track album membership through the stored record contract', () => {- beforeEach(() => {- records.albums.clear();- records.tracks.clear();+describe('local membership workflows through real file persistence (not a PostgreSQL guarantee)', () => {+ it('retains concurrent additions in order and enforces the final slot without an orphan', async () => {+ const album = await createAlbum();+ const added = await Promise.all([createTrack(album.id), createTrack(album.id)]);+ expect((await albums.getAlbum(album.id)).trackIds).toEqual(added.map((track) => track.id));+ const full = await createAlbum({ trackIds: Array.from({ length: albums.TRACK_IDS_MAX - 1 }, (_, i) => `track-example-${i}`) });+ const results = await Promise.allSettled([createTrack(full.id), createTrack(full.id)]);+ expect(results.map((r) => r.status)).toEqual(['fulfilled', 'rejected']);+ expect(results[1].reason.code).toBe('ALBUM_FULL');+ expect((await tracks.listTracks()).filter((track) => track.albumId === full.id)).toHaveLength(1);+ expect((await albums.getAlbum(full.id)).trackIds).toHaveLength(albums.TRACK_IDS_MAX);+ await membership.updateTrackWithAlbum(results[0].value, { albumId: full.id });});- it('rejects a create into a full album before persisting a track', async () => {- const album = seedAlbum('album-full', TRACK_IDS_MAX);- await expect(createTrackWithAlbum({ title: 'New Track', albumId: album.id }))- .rejects.toMatchObject({ status: 409, code: 'ALBUM_FULL' });- expect(records.tracks.size).toBe(0);- expect(records.albums.get(album.id)).toEqual(album);+ it('serializes album edits, stale track moves and deletion while preserving metadata and order', async () => {+ const source = await createAlbum();+ const destination = await createAlbum({ genre: 'example genre' });+ const third = await createAlbum();+ const track = await createTrack(source.id);+ const neighbor = await createTrack(destination.id);+ const saved = await request(app).patch(`/api/albums/${destination.id}`).send({ trackIds: [neighbor.id, track.id] });+ expect(saved.status).toBe(200);+ await membership.updateTrackWithAlbum(track, { albumId: third.id, title: 'Example edit' });+ expect((await albums.getAlbum(source.id)).trackIds).toEqual([]);+ expect(await albums.getAlbum(destination.id)).toMatchObject({ trackIds: [neighbor.id], genre: 'example genre' });+ await Promise.all([+ membership.deleteTrackWithAlbum(track.id),+ request(app).patch(`/api/albums/${third.id}`).send({ description: 'Example description' }),+ ]);+ expect(await tracks.getTrack(track.id)).toBeNull();+ expect(await albums.getAlbum(third.id)).toMatchObject({ trackIds: [], description: 'Example description' });});- it('preserves the prior track and both albums when moving into a full album', async () => {- const { track, album: prior } = seedAssignedTrack();- const full = seedAlbum('album-full', TRACK_IDS_MAX);- await expect(updateTrackWithAlbum(track, { title: 'Changed', albumId: full.id }))- .rejects.toMatchObject({ status: 409, code: 'ALBUM_FULL' });- expect(records.tracks.get(track.id)).toEqual(track);- expect(records.albums.get(prior.id)).toEqual(prior);- expect(records.albums.get(full.id)).toEqual(full);+ it('rolls back a failed album PATCH, reports the standard error envelope, and permits retry', async () => {+ const album = await createAlbum();+ const track = await createTrack(album.id);+ events.length = 0;+ failure.writes = ['tracks.json'];+ const response = await request(app).patch(`/api/albums/${album.id}`).send({ trackIds: [] });+ expect(response.status).toBe(500);+ expect(response.body.code).toBe('MUSIC_MEMBERSHIP_WRITE_FAILED');+ expect((await albums.getAlbum(album.id)).trackIds).toEqual([track.id]);+ expect((await tracks.getTrack(track.id)).albumId).toBe(album.id);+ expect(events).toEqual([]);+ expect((await request(app).patch(`/api/albums/${album.id}`).send({ trackIds: [] })).status).toBe(200);+ expect((await tracks.getTrack(track.id)).albumId).toBe('');});- it('fills the last slot and accepts re-selecting that member in the full album', async () => {- const album = seedAlbum('album-last-slot', TRACK_IDS_MAX - 1);- const { track } = await createTrackWithAlbum({ title: 'Last Track', albumId: album.id });- expect(track.albumId).toBe(album.id);- const reselected = await updateTrackWithAlbum(track, { albumId: album.id });- expect(reselected.albumId).toBe(album.id);- expect(records.albums.get(album.id).trackIds).toEqual([...album.trackIds, track.id]);+ it('does not strand a failed album DELETE behind a tombstone', async () => {+ const album = await createAlbum();+ const track = await createTrack(album.id);+ failure.writes = ['tracks.json'];+ expect((await request(app).delete(`/api/albums/${album.id}`)).status).toBe(500);+ expect(await albums.getAlbum(album.id)).not.toBeNull();+ expect((await request(app).delete(`/api/albums/${album.id}`)).status).toBe(200);+ expect(await albums.getAlbum(album.id)).toBeNull();+ expect((await tracks.getTrack(track.id)).albumId).toBe('');});- it('rejects a missing destination without removing existing membership', async () => {- const { track, album } = seedAssignedTrack();- await expect(updateTrackWithAlbum(track, { albumId: 'album-missing' }))- .rejects.toMatchObject({ status: 404, code: 'ALBUM_NOT_FOUND' });- expect(records.tracks.get(track.id)).toEqual(track);- expect(records.albums.get(album.id)).toEqual(album);+ it('discards failed creates without emitting events or leaving duplicate records on retry', async () => {+ const track = await createTrack();+ events.length = 0;+ subscribe.mockClear();+ failure.writes = ['tracks.json'];+ const input = { title: 'Example retry', trackIds: [track.id] };+ expect((await request(app).post('/api/albums').send(input)).status).toBe(500);+ expect(await albums.listAlbums()).toEqual([]);+ expect(events).toEqual([]);+ expect(subscribe).not.toHaveBeenCalled();+ expect((await request(app).post('/api/albums').send(input)).status).toBe(201);+ expect(await albums.listAlbums()).toHaveLength(1);+ expect(events.length).toBeGreaterThan(0);+ expect(subscribe).toHaveBeenCalledTimes(1);});- it('moves a track between albums, appending to the destination and dropping the source', async () => {- const { track, album: prior } = seedAssignedTrack();- const next = seedAlbum('album-next', 2);- const moved = await updateTrackWithAlbum(track, { albumId: next.id });- expect(moved.albumId).toBe(next.id);- expect(records.albums.get(next.id).trackIds).toEqual([...next.trackIds, track.id]);- expect(records.albums.get(prior.id).trackIds).toEqual([]);+ it('distinguishes missing/deleted tracks from storage failures', async () => {+ const removed = await createTrack();+ await membership.deleteTrackWithAlbum(removed.id);+ const response = await request(app).post('/api/albums').send({ title: 'Example legacy', trackIds: ['track-missing', removed.id] });+ expect(response.status).toBe(201);+ failure.reads = 'tracks.json';+ expect((await request(app).patch(`/api/albums/${response.body.id}`).send({ trackIds: [] })).status).toBe(500);+ failure.reads = null;+ expect((await albums.getAlbum(response.body.id)).trackIds).toEqual(['track-missing', removed.id]);});- it('keeps completed audio as a single when its destination album is unavailable', async () => {- const { track, albumAssignmentError } = await createTrackWithAlbum(- { title: 'Rendered Track', albumId: 'album-missing' },- { preserveUnassigned: true },- );- expect(track.albumId).toBe('');- expect(albumAssignmentError).toEqual({ code: 'ALBUM_NOT_FOUND', message: 'Album not found' });- expect(records.tracks.get(track.id)).toEqual(track);+ it('preserves completed audio for full/missing destinations but propagates arbitrary storage failures', async () => {+ const full = await createAlbum({ trackIds: Array.from({ length: albums.TRACK_IDS_MAX }, (_, i) => `track-example-${i}`) });+ for (const albumId of [full.id, 'album-missing']) {+ const result = await membership.createTrackWithAlbum({ title: 'Example completed', albumId, audioFilename: 'example.wav' }, { preserveUnassigned: true });+ expect(result.track).toMatchObject({ albumId: '', audioFilename: 'example.wav' });+ expect(result.albumAssignmentError.code).toBe(albumId === full.id ? 'ALBUM_FULL' : 'ALBUM_NOT_FOUND');+ }+ failure.reads = 'albums.json';+ await expect(membership.createTrackWithAlbum({ title: 'Example failed', albumId: full.id }, { preserveUnassigned: true })).rejects.toThrow('Synthetic read failure');+ expect(await tracks.listTracks()).toHaveLength(2);});- it('removes a track from its album and ignores an album that no longer exists', async () => {- const { track, album } = seedAssignedTrack();- await removeTrackFromAlbum(track.id, album.id);- expect(records.albums.get(album.id).trackIds).toEqual([]);- await expect(removeTrackFromAlbum(track.id, 'album-missing')).resolves.toBeUndefined();+ it('explicitly requires reconciliation when a failed file write cannot be restored', async () => {+ const album = await createAlbum();+ await createTrack(album.id);+ failure.writes = ['tracks.json', 'albums.json'];+ const response = await request(app).delete(`/api/albums/${album.id}`);+ expect(response.status).toBe(500);+ expect(response.body.code).toBe('MUSIC_MEMBERSHIP_RECONCILIATION_REQUIRED');+ expect(response.body.error).toContain('before retrying');});});diff --git a/server/services/tracks/db.js b/server/services/tracks/db.jsindex 0196d9802c..fa40783be8 100644--- a/server/services/tracks/db.js+++ b/server/services/tracks/db.js@@ -52,15 +52,17 @@ async function persist(exec, track) {return track;}-export async function listTracks({ includeDeleted = false } = {}) {+export async function listTracks({ includeDeleted = false, client } = {}) {+ const exec = client ? client.query.bind(client) : query;const { rows } = includeDeleted- ? await query(`SELECT data FROM tracks ORDER BY created_at ASC`)- : await query(`SELECT data FROM tracks WHERE deleted = FALSE ORDER BY created_at ASC`);+ ? await exec(`SELECT data FROM tracks ORDER BY created_at ASC${client ? ' FOR UPDATE' : ''}`)+ : await exec(`SELECT data FROM tracks WHERE deleted = FALSE ORDER BY created_at ASC${client ? ' FOR UPDATE' : ''}`);return rows.map(rowToTrack);}-export async function getTrack(id, { includeDeleted = false } = {}) {- const { rows } = await query(`SELECT data FROM tracks WHERE id = $1`, [id]);+export async function getTrack(id, { includeDeleted = false, client } = {}) {+ const exec = client ? client.query.bind(client) : query;+ const { rows } = await exec(`SELECT data FROM tracks WHERE id = $1${client ? ' FOR UPDATE' : ''}`, [id]);const track = rowToTrack(rows[0]);if (!track) return null;return includeDeleted || !track.deleted ? track : null;@@ -74,16 +76,16 @@ export async function listTrackIds({ includeDeleted = false } = {}) {return rows.map((r) => r.id);}-export async function createTrack(input) {+export async function createTrack(input, { client } = {}) {const track = buildTrackRecord(input, { id: `track-${randomUUID()}`, now: new Date().toISOString() });if (!track) throw new ServerError('Invalid track payload', { status: 400, code: 'VALIDATION' });- await persist(query, track);+ await persist(client ? client.query.bind(client) : query, track);console.log(`🎵 Created track: ${track.id} (${track.title})`);return track;}-export async function updateTrack(id, patch) {- return withTransaction(async (client) => {+export async function updateTrack(id, patch, { client: transactionClient } = {}) {+ const mutate = async (client) => {const sel = await client.query(`SELECT data FROM tracks WHERE id = $1 FOR UPDATE`, [id]);const current = rowToTrack(sel.rows[0]);if (!current || current.deleted) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });@@ -91,11 +93,12 @@ export async function updateTrack(id, patch) {if (!next) throw new ServerError('Invalid track payload', { status: 400, code: 'VALIDATION' });await persist(client.query.bind(client), next);return next;- });+ };+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);}-export async function deleteTrack(id) {- return withTransaction(async (client) => {+export async function deleteTrack(id, { client: transactionClient } = {}) {+ const mutate = async (client) => {const sel = await client.query(`SELECT data FROM tracks WHERE id = $1 FOR UPDATE`, [id]);const current = rowToTrack(sel.rows[0]);if (!current || current.deleted) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });@@ -103,7 +106,8 @@ export async function deleteTrack(id) {const next = { ...current, deleted: true, deletedAt: now, updatedAt: now };await persist(client.query.bind(client), next);return { id };- });+ };+ return transactionClient ? mutate(transactionClient) : withTransaction(mutate);}/**diff --git a/server/services/tracks/file.js b/server/services/tracks/file.jsindex 70478f5515..44240b85e7 100644--- a/server/services/tracks/file.js+++ b/server/services/tracks/file.js@@ -10,6 +10,7 @@import { join } from 'path';import { randomUUID } from 'crypto';import { PATHS, readJSONFile, atomicWrite, ensureDir } from '../../lib/fileUtils.js';+import { readMusicFile, writeMusicFile } from '../musicMembershipMutation.js';import { ServerError } from '../../lib/errorHandler.js';import { sanitizeTrack, buildTrackRecord, applyTrackPatch, mergeTrackRecord } from './logic.js';import {@@ -20,14 +21,18 @@ import {const TRACKS_FILE = join(PATHS.data, 'tracks.json');async function loadAll() {- // Tracks are durable user records; never save an empty fallback over unreadable bytes.- const raw = await readJSONFile(TRACKS_FILE, [], { strict: true });- return (Array.isArray(raw) ? raw : []).map(sanitizeTrack).filter(Boolean);+ return readMusicFile('tracks', async () => {+ // Tracks are durable user records; never save an empty fallback over unreadable bytes.+ const raw = await readJSONFile(TRACKS_FILE, [], { strict: true });+ return (Array.isArray(raw) ? raw : []).map(sanitizeTrack).filter(Boolean);+ });}async function saveAll(tracks) {- await ensureDir(PATHS.data);- await atomicWrite(TRACKS_FILE, tracks);+ return writeMusicFile('tracks', tracks, async (records) => {+ await ensureDir(PATHS.data);+ await atomicWrite(TRACKS_FILE, records);+ });}// Tracks list in creation order (the album's trackIds drive display order).diff --git a/server/services/tracks/index.js b/server/services/tracks/index.jsindex 9482e25a26..8571ddc1f3 100644--- a/server/services/tracks/index.js+++ b/server/services/tracks/index.js@@ -12,6 +12,7 @@import { randomUUID } from 'crypto';import { createRecordStoreBackendSelector } from '../../lib/pgFileFacade.js';+import { withMusicMutation, musicMutationClient, afterMusicCommit } from '../musicMembershipMutation.js';import { emitRecordUpdated, emitRecordDeleted, autoSubscribeRecordToAllPeers } from '../sharing/recordEvents.js';import { makeRender as makeRenderLogic } from './logic.js';@@ -82,6 +83,9 @@ export function appendActiveTake(trackId, { audioFilename, engine, prompt, duratreturn run;}+// The shared mutation boundary prepares both stores before reserving a client.+export { selectBackend as prepareTracksBackend };+/** Name of the active backend, or null before first call (for diagnostics/tests). */export function getTracksBackendName() {return getBackendName();@@ -93,7 +97,7 @@ export function _resetTracksBackend() {}export async function listTracks(options = {}) {- return (await selectBackend()).listTracks(options);+ return (await selectBackend()).listTracks({ ...options, client: musicMutationClient() });}export async function listTrackIds(options = {}) {@@ -101,7 +105,7 @@ export async function listTrackIds(options = {}) {}export async function getTrack(id, options = {}) {- return (await selectBackend()).getTrack(id, options);+ return (await selectBackend()).getTrack(id, { ...options, client: musicMutationClient() });}function announceNewTrack(id) {@@ -110,21 +114,27 @@ function announceNewTrack(id) {}export async function createTrack(input) {- const track = await (await selectBackend()).createTrack(input);- announceNewTrack(track.id);- return track;+ return withMusicMutation(async () => {+ const track = await (await selectBackend()).createTrack(input, { client: musicMutationClient() });+ afterMusicCommit(() => announceNewTrack(track.id));+ return track;+ });}export async function updateTrack(id, patch) {- const next = await (await selectBackend()).updateTrack(id, patch);- emitRecordUpdated('track', next.id);- return next;+ return withMusicMutation(async () => {+ const next = await (await selectBackend()).updateTrack(id, patch, { client: musicMutationClient() });+ afterMusicCommit(() => emitRecordUpdated('track', next.id));+ return next;+ });}export async function deleteTrack(id) {- const result = await (await selectBackend()).deleteTrack(id);- emitRecordDeleted('track', result.id);- return result;+ return withMusicMutation(async () => {+ const result = await (await selectBackend()).deleteTrack(id, { client: musicMutationClient() });+ afterMusicCommit(() => emitRecordDeleted('track', result.id));+ return result;+ });}/** Merge an incoming batch of track records from a peer (LWW, tombstone-aware). */