Skip to content

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

fix: journal interrupted music video render retirement

[._.]/ Adam Eivy5c715e3771cf
diff --git a/client/src/components/musicVideo/stages/CleanupStage.jsx b/client/src/components/musicVideo/stages/CleanupStage.jsx
index cbd50cf165..67a9640ac4 100644
--- a/client/src/components/musicVideo/stages/CleanupStage.jsx
+++ b/client/src/components/musicVideo/stages/CleanupStage.jsx
@@ -89,7 +89,7 @@ export default function CleanupStage({ board }) {
{finals.length > 0 && <ul className="space-y-2" aria-label="Older final renders">
{finals.map(file => <li key={file.id} className="break-words rounded border border-port-border p-3 text-sm">
<p>{file.createdAt ? formatDateTime(file.createdAt) : 'Older final'} · {formatBytes(file.bytes)}</p>
- <p className="text-port-text-muted">{file.reason ? `Kept: ${file.reason}` : 'Superseded — safe to remove'}</p>
+ <p className="text-port-text-muted">{file.reason ? `Kept: ${file.reason}` : file.pending ? 'Cleanup incomplete — retry to remove remaining files' : 'Superseded — safe to remove'}</p>
</li>)}
</ul>}
</>}
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index 114e55f807..4cf0623f96 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -584,6 +584,10 @@ Apply this checklist to **every new feature that persists data**, and require it
Optional SDK environments under `data/venvs/` are machine-local, regenerable runtime files, not application records. Reactor provisions its pinned SDK, private Python and checksum-verified uv manager on the first authorized render (or optionally through `npm run setup:reactor`); no seed, migration, database table, or peer synchronization is needed. Data Manager identifies these environments but does not purge them while render processes may use them.
+### Music Video render retirement
+
+`data/videos/.music-video-render-cleanup.json` is machine-local, `file-primary` recovery metadata for generated video files. Version 1 holds pending retired final-render history records until their video, poster and proof bytes are removed. Cleanup writes this journal before changing the derived index or history, removes history entries before unlinking files, and retries pending entries from the journal on the next cleanup or successful final render. The Cleanup page includes pending bytes even after their media-library rows are gone. A global write queue and backup publication admission cover journal, history and file changes; normal data backups include the journal beside its videos. It has no search or cross-record query requirements and is never federated. Unknown/malformed versions fail closed. It is created only when retiring a render, needs no seed or migration, and disappears when empty. Source takes and cutting-room media are not journaled or removed.
+
### Music Video cover lettering
`data/cover-fonts/` is `file-primary`: the typefaces a director uploads for cover lettering (`<id>.ttf|otf|woff2`) plus a small `fonts.json` index (`{ id, family, ext, width, addedAt }`, width measured at upload). Machine-local and never federated: a font is a licensed binary the director chose for this install, and whether it renders depends on this machine's font system. It is included in normal data backups (no new exclude); it relates to no other record and needs no search, so it stays out of the DB. On macOS each font is also mirrored into `~/Library/Fonts/PortOS/`, because CoreText reads only Fonts folders; other platforms register the file with fontconfig through libvips. An upload is refused unless the renderer proves it can set text in it. The per-artist saved cover design is `settings.musicVideoPublishing.artistStyles` in the file-primary `data/settings.json` (keyed by lowercased artist name), beside the machine-local `platforms` choice; settings are not synced between machines. Neither needs a migration: a cover design stored before `titleStyle`/`tagLayout` existed normalizes to the previous look unchanged. Code: `server/services/musicVideo/coverFonts.js`, `publish/artistStyles.js`; layout: `server/lib/musicVideoCoverOverlay.js`.
diff --git a/server/services/musicVideo/renderCleanup.js b/server/services/musicVideo/renderCleanup.js
index d78b855586..24bad0739e 100644
--- a/server/services/musicVideo/renderCleanup.js
+++ b/server/services/musicVideo/renderCleanup.js
@@ -1,6 +1,8 @@
/** Retire regenerable renders without touching source takes or the cutting-room floor. */
import { unlink, stat } from 'node:fs/promises';
-import { PATHS } from '../../lib/fileUtils.js';
+import { PATHS, atomicWrite, readJSONFile } from '../../lib/fileUtils.js';
+import { join } from 'node:path';
+import { createFileWriteQueue } from '../../lib/fileWriteQueue.js';
import { safeUnder } from '../../lib/ffmpeg.js';
import { ServerError } from '../../lib/errorHandler.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
@@ -8,6 +10,21 @@ import { getProject, listProjects, withProjectMediaMutation } from './projects.j
import { musicVideoEvents } from './events.js';
import { loadHistory, mutateVideoHistory, HISTORY_UNCHANGED } from '../videoGen/history.js';
+// Filesystem recovery metadata is local to these generated videos, never federated.
+const JOURNAL = join(PATHS.videos, '.music-video-render-cleanup.json');
+const cleanupWrites = createFileWriteQueue();
+async function readPending() {
+ const journal = await readJSONFile(JOURNAL, { version: 1, entries: [] }, { strict: true });
+ if (journal?.version !== 1 || !Array.isArray(journal.entries)
+ || journal.entries.some(entry => !entry || typeof entry.id !== 'string' || typeof entry.filename !== 'string')) {
+ throw new ServerError('Render cleanup recovery metadata is unreadable', { status: 409, code: 'RENDER_CLEANUP_JOURNAL_INVALID' });
+ }
+ return journal.entries;
+}
+const savePending = pending => pending.size
+ ? atomicWrite(JOURNAL, { version: 1, entries: [...pending.values()] }) : remove(JOURNAL);
+const retirementEntries = (history, pending) => [...new Map([...pending, ...history].map(entry => [entry.id, entry])).values()];
+
const cleaning = new Set();
export function assertRenderCleanupIdle(projectId) {
if (cleaning.has(projectId)) throw new ServerError('Render cleanup is in progress. Try again when it finishes.', { status: 409, code: 'RENDER_CLEANUP_ACTIVE' });
@@ -30,7 +47,7 @@ const renderFiles = entry => [safeUnder(PATHS.videos, entry.filename),
...Array.from({ length: 9 }, (_, i) => safeUnder(PATHS.videoThumbnails, `${entry.id}-f${i + 1}.jpg`)),
].filter(Boolean);
-async function finalInventory(projectId, history) {
+async function finalInventory(projectId, history, pending = []) {
const project = await getProject(projectId);
if (!project) throw new ServerError('Project not found', { status: 404, code: 'NOT_FOUND' });
const [{ listCollections }, timeline, director] = await Promise.all([
@@ -45,45 +62,63 @@ async function finalInventory(projectId, history) {
const current = history.find(entry => entry.id === project.renderHistoryId);
const hasCurrent = current && await size(safeUnder(PATHS.videos, current.filename)) > 0;
const finals = [];
- for (const entry of history) {
+ const pendingIds = new Set(pending.map(entry => entry.id));
+ for (const entry of retirementEntries(history, pending)) {
// Only the full-render pipeline owns this tag. Source clips use musicVideo.projectId.
if (entry.musicVideoProjectId !== projectId || !['music-video', 'music-video-code', 'music-video-document', 'music-video-eidoverse'].includes(entry.modelId) || entry.id === project.renderHistoryId) continue;
const ids = new Set([entry.id, entry.filename]);
const referenced = owners.some(owner => references(owner, ids))
- || history.some(other => other !== entry && references(other, ids));
+ || history.some(other => other.id !== entry.id && references(other, ids));
const reason = !hasCurrent ? 'No completed replacement' : referenced ? 'Referenced by saved media or production records' : null;
- finals.push({ id: entry.id, filename: entry.filename, createdAt: entry.createdAt, bytes: (await Promise.all(renderFiles(entry).map(size))).reduce((a, b) => a + b, 0), reason });
+ finals.push({ id: entry.id, pending: pendingIds.has(entry.id), filename: entry.filename, createdAt: entry.createdAt, bytes: (await Promise.all(renderFiles(entry).map(size))).reduce((a, b) => a + b, 0), reason });
}
return { project, finals };
}
/** Called only after the replacement has been published. Failed writes keep old renders. */
export async function cleanupSupersededFinals(projectId, { replacementId = null } = {}) {
- return withBackupAssetPublication(() => withProjectMediaMutation(async () => {
- const deleted = [];
- await mutateVideoHistory(async history => {
- const { project, finals } = await finalInventory(projectId, history);
- if (replacementId && project.renderHistoryId !== replacementId) return HISTORY_UNCHANGED;
- const eligible = new Set(finals.filter(entry => !entry.reason).map(entry => entry.id));
- const retainedFiles = new Set(history.filter(entry => !eligible.has(entry.id)).flatMap(renderFiles));
- const index = eligible.size ? await import('../mediaAssetIndex/index.js') : null;
- for (const entry of history) {
- if (!eligible.has(entry.id)) continue;
- if (!safeUnder(PATHS.videos, entry.filename)) throw new ServerError('Invalid render filename', { status: 409, code: 'INVALID_VIDEO_PATH' });
- // Leave the row and bytes available to retry if its derived index cannot settle.
- await index.unindexVideo(entry.id, { strict: true });
- for (const path of renderFiles(entry)) if (!retainedFiles.has(path)) await remove(path);
- deleted.push(entry.id);
- }
- return deleted.length ? history.filter(entry => !eligible.has(entry.id)) : HISTORY_UNCHANGED;
- });
- if (deleted.length) musicVideoEvents.emit('render-cleanup', { projectId });
- return deleted.length;
- }));
+ // One writer owns the shared journal across history commits and file retirement.
+ return cleanupWrites(() => withBackupAssetPublication(() => withProjectMediaMutation(async () => {
+ const pending = new Map((await readPending()).map(entry => [entry.id, entry]));
+ let retiring = [];
+ let retainedFiles;
+ let removed = 0;
+ return (async () => {
+ await mutateVideoHistory(async history => {
+ const entries = retirementEntries(history, [...pending.values()]);
+ const { project, finals } = await finalInventory(projectId, history, [...pending.values()]);
+ if (replacementId && project.renderHistoryId !== replacementId) return HISTORY_UNCHANGED;
+ const eligible = new Set(finals.filter(entry => !entry.reason).map(entry => entry.id));
+ retiring = entries.filter(entry => eligible.has(entry.id));
+ if (!retiring.length) return HISTORY_UNCHANGED;
+ retainedFiles = new Set(entries.filter(entry => !eligible.has(entry.id)).flatMap(renderFiles));
+ for (const entry of retiring) {
+ if (!safeUnder(PATHS.videos, entry.filename)) throw new ServerError('Invalid render filename', { status: 409, code: 'INVALID_VIDEO_PATH' });
+ pending.set(entry.id, entry);
+ }
+ // Recovery evidence precedes every index/history/byte mutation. The
+ // history stops advertising a render before any of its bytes disappear.
+ await savePending(pending);
+ const { unindexVideo } = await import('../mediaAssetIndex/index.js');
+ for (const entry of retiring) await unindexVideo(entry.id, { strict: true });
+ return history.filter(entry => !eligible.has(entry.id));
+ });
+ if (!retiring.length) return 0;
+ await (async () => {
+ for (const entry of retiring) {
+ for (const path of renderFiles(entry)) if (!retainedFiles.has(path)) await remove(path);
+ pending.delete(entry.id);
+ removed += 1;
+ }
+ })().finally(() => savePending(pending));
+ return removed;
+ })().finally(() => { if (retiring.length) musicVideoEvents.emit('render-cleanup', { projectId }); });
+ })));
}
export async function getRenderCleanup(projectId) {
- const { finals } = await finalInventory(projectId, await loadHistory());
+ const [history, pending] = await Promise.all([loadHistory(), readPending()]);
+ const { finals } = await finalInventory(projectId, history, pending);
const { getSegmentCleanup } = await import('./shotSegments.js');
return { finals, segments: await getSegmentCleanup(projectId) };
}
diff --git a/server/services/musicVideo/renderCleanup.test.js b/server/services/musicVideo/renderCleanup.test.js
index 485fa3240c..0d08cde0c8 100644
--- a/server/services/musicVideo/renderCleanup.test.js
+++ b/server/services/musicVideo/renderCleanup.test.js
@@ -5,7 +5,14 @@ import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../li
const root = () => lazyTempDataRoot('mv-render-cleanup-');
vi.mock('../../lib/paths.js', async load => makePathsProxy(await load(), { dataRoot: root }));
-const state = { project: null, others: [], collections: [], timelines: [], director: [], active: false };
+const state = { project: null, others: [], collections: [], timelines: [], director: [], active: false, failHistory: false };
+vi.mock('../../lib/fileUtils.js', async load => {
+ const actual = await load();
+ return { ...actual, atomicWrite: async (path, data) => {
+ if (state.failHistory && path.endsWith('video-history.json')) throw new Error('History write failed');
+ return actual.atomicWrite(path, data);
+ } };
+});
vi.mock('./projects.js', () => ({
getProject: vi.fn(async () => state.project), listProjects: vi.fn(async () => [state.project, ...state.others]),
withProjectMediaMutation: async work => work({}),
@@ -31,7 +38,7 @@ beforeEach(async () => {
mkdirSync(PATHS.videos, { recursive: true });
mkdirSync(PATHS.videoThumbnails, { recursive: true });
state.project = { id: 'example-project', renderHistoryId: 'current' };
- state.others = []; state.collections = []; state.timelines = []; state.director = []; state.active = false;
+ state.others = []; state.collections = []; state.timelines = []; state.director = []; state.active = false; state.failHistory = false;
vi.clearAllMocks();
assertSegmentCleanupIdle.mockReset();
await saveHistory([]);
@@ -79,6 +86,19 @@ describe('derived render retention', () => {
expect(unindexVideo).toHaveBeenCalledTimes(2);
});
+ it('retains recovery metadata and all video bytes if history publication fails', async () => {
+ await seed([entry('current'), entry('old')]);
+ state.failHistory = true;
+ await expect(cleanupSupersededFinals('example-project')).rejects.toThrow('History write failed');
+ expect((await loadHistory()).map(item => item.id)).toContain('old');
+ expect(existsSync(join(PATHS.videos, 'old.mp4'))).toBe(true);
+ expect((await getRenderCleanup('example-project')).finals).toEqual([expect.objectContaining({ id: 'old', pending: true })]);
+ state.failHistory = false;
+ expect(await cleanupSupersededFinals('example-project')).toBe(1);
+ expect(existsSync(join(PATHS.videos, '.music-video-render-cleanup.json'))).toBe(false);
+ expect((await loadHistory()).map(item => item.id)).toEqual(['current']);
+ });
+
it('keeps the previous final when its replacement failed to become the current render, or its file is missing', async () => {
await seed([entry('current'), entry('new')]);
expect(await cleanupSupersededFinals('example-project', { replacementId: 'new' })).toBe(0);
@@ -104,13 +124,18 @@ describe('derived render retention', () => {
expect(() => assertRenderCleanupIdle('example-project')).not.toThrow();
});
- it('reports deletion and unreadable-history failures without claiming cleanup or deleting the current final', async () => {
- await seed([entry('current'), entry('old')]);
+ it('reconciles a partially deleted batch without leaving broken history rows, and reports unreadable history', async () => {
+ await seed([entry('current'), entry('retired'), entry('old')]);
rmSync(join(PATHS.videoThumbnails, 'old.jpg'));
mkdirSync(join(PATHS.videoThumbnails, 'old.jpg'));
await expect(cleanupSupersededFinals('example-project')).rejects.toThrow();
- expect((await loadHistory()).map(item => item.id)).toContain('old');
+ expect((await loadHistory()).map(item => item.id)).toEqual(['current']);
+ expect(existsSync(join(PATHS.videos, 'retired.mp4'))).toBe(false);
+ expect((await getRenderCleanup('example-project')).finals).toEqual([expect.objectContaining({ id: 'old', pending: true })]);
expect(existsSync(join(PATHS.videos, 'current.mp4'))).toBe(true);
+ rmSync(join(PATHS.videoThumbnails, 'old.jpg'), { recursive: true });
+ expect(await cleanupSupersededFinals('example-project')).toBe(1);
+ expect((await getRenderCleanup('example-project')).finals).toEqual([]);
writeFileSync(join(PATHS.data, 'video-history.json'), '{invalid');
await expect(cleanupSupersededFinals('example-project')).rejects.toThrow();
expect(existsSync(join(PATHS.videos, 'current.mp4'))).toBe(true);