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

40.6 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { resolve as resolvePath } from 'path';

// These assertions describe the COMPOSITION of a staged path, not its
// separator. prepareParams builds them with path.join/resolve, which emit '\'
// on Windows, so compare against a separator-normalized copy.
const posix = (p) => String(p).split('\\').join('/');

const probeVideoDuration = vi.hoisted(() => vi.fn(async () => 41.041281));
vi.mock('../../lib/ffmpeg.js', async (importOriginal) => ({
  ...(await importOriginal()),
  probeVideoDuration,
}));

vi.mock('../settings.js', () => ({
  getSettings: vi.fn(async () => ({
    imageGen: { local: { pythonPath: '/usr/bin/python3' }, grok: { enabled: true, grokPath: '/usr/bin/grok', aspectRatio: '16:9' } },
  })),
}));

vi.mock('../musicVideo/projects.js', () => ({ getProject: vi.fn() }));
vi.mock('../tracks/index.js', () => ({ getTrack: vi.fn() }));

vi.mock('./local.js', () => ({
  listVideoModels: vi.fn(() => [{ id: 'ltx2_unified', name: 'LTX-2 Unified', runtime: 'ltx2' }]),
  defaultVideoModelId: vi.fn(() => 'ltx2_unified'),
  loadHistory: vi.fn(async () => []),
  BYOV_VIDEO_RUNTIMES: new Set(['ltx2', 'ltx25', 'wan22', 'minimax_h3']),
  DEFAULT_NUM_FRAMES: 121,
}));

const { unlinkMock, copyFileMock, assertManifestMock } = vi.hoisted(() => ({
  unlinkMock: vi.fn(async () => {}),
  copyFileMock: vi.fn(async () => {}),
  assertManifestMock: vi.fn(async () => {}),
}));

vi.mock('../../lib/fileUtils.js', () => ({
  PATHS: {
    root: '/mock',
    data: '/mock/data',
    images: '/mock/images',
    videos: '/mock/videos',
    uploads: '/mock/uploads',
    music: '/mock/music',
  },
  ensureDir: vi.fn(async () => {}),
  resolveGalleryImage: vi.fn((name) => {
    if (typeof name !== 'string' || !name) return null;
    const safe = name.split(/[/\\]/).pop();
    if (!safe || safe === '.' || safe === '..') return null;
    return `/mock/images/${safe}`;
  }),
  unlinkGuarded: unlinkMock,
  copyFileGuarded: copyFileMock,
  assertFileNotMediaManifest: assertManifestMock,
}));

vi.mock('fs', () => ({ existsSync: vi.fn(() => true) }));
vi.mock('fs/promises', () => ({
  unlink: unlinkMock,
  copyFile: copyFileMock,
}));

import { unlink } from 'fs/promises';
import { resolveGalleryImage } from '../../lib/fileUtils.js';
import { getProject as getMusicVideoProject } from '../musicVideo/projects.js';
import { getTrack } from '../tracks/index.js';
import { getSettings } from '../settings.js';
import { listVideoModels, defaultVideoModelId, loadHistory } from './local.js';
import {
  prepareVideoGenParams,
  validateVideoRetryParams,
  withStagedRollback,
  cleanupMultipartTemp,
} from './prepareParams.js';

// Field names the route owns Zod schemas for; the service only needs the keys
// to decide grok eligibility. Mirrors LOCAL_ONLY_VIDEO_PARAMS in the route.
const LOCAL_ONLY_KEYS = ['numFrames', 'fps', 'steps', 'guidanceScale', 'seed', 'imageStrength', 'i2vReferenceMode', 'tiling'];

const upload = (fieldname, name = 'frame.png') => ({
  fieldname,
  originalname: name,
  path: `/tmp/multipart-${fieldname}-${name}`,
});

const prepare = (body, uploads = {}) => prepareVideoGenParams({
  body: { prompt: 'a clip', width: 704, height: 448, ...body },
  uploads,
  localOnlyParamKeys: LOCAL_ONLY_KEYS,
});

const H3_TERMS = 'minimax-h3-community-license-2026-08-02';
const H3_MODEL = {
  id: 'minimax_h3_8bit',
  name: 'MiniMax H3 MLX 8-bit',
  runtime: 'minimax_h3',
  supportedModes: ['text', 'image', 'fflf'],
  defaultFrames: 124,
  frameOptions: [107, 124, 141, 158],
  fpsOptions: [24],
  termsGate: { id: H3_TERMS },
};

// Paths unlinked under PATHS.uploads — i.e. the durable copies the service
// staged, as opposed to the OS temp files the multipart parser wrote.
// Normalize BEFORE filtering: the staged paths are built with path.join, so on
// Windows they are '\mock\uploads\…' and a startsWith('/mock/uploads/') filter
// matches nothing — which silently emptied this list and made every assertion
// below compare against [] instead of the paths it meant to check.
const unlinkedDurablePaths = () => unlink.mock.calls
  .map(([p]) => posix(p))
  .filter((p) => typeof p === 'string' && p.startsWith('/mock/uploads/'));

describe('withStagedRollback', () => {
  it('returns the value and skips cleanup when nothing throws', async () => {
    const cleanup = vi.fn(async () => {});
    await expect(withStagedRollback(cleanup, async () => 'ok')).resolves.toBe('ok');
    expect(cleanup).not.toHaveBeenCalled();
  });

  it('cleans up and rethrows the original error on a rejected await', async () => {
    const cleanup = vi.fn(async () => {});
    const boom = new Error('db down');
    await expect(withStagedRollback(cleanup, async () => { throw boom; })).rejects.toBe(boom);
    expect(cleanup).toHaveBeenCalledTimes(1);
  });

  it('cleans up and rethrows when the callback throws synchronously', async () => {
    // enqueueJob is synchronous — a sync throw must unwind exactly like a
    // rejection, otherwise the route's guard is decorative.
    const cleanup = vi.fn(async () => {});
    const boom = new Error('queue full');
    await expect(withStagedRollback(cleanup, () => { throw boom; })).rejects.toBe(boom);
    expect(cleanup).toHaveBeenCalledTimes(1);
  });
});

describe('cleanupMultipartTemp', () => {
  it('unlinks every multipart temp path and tolerates an empty/absent map', async () => {
    const uploads = { sourceImage: upload('sourceImage'), lastImage: upload('lastImage', 'end.png') };
    await cleanupMultipartTemp(uploads);
    expect(unlink).toHaveBeenCalledWith('/tmp/multipart-sourceImage-frame.png');
    expect(unlink).toHaveBeenCalledWith('/tmp/multipart-lastImage-end.png');
    await cleanupMultipartTemp(uploads);
    expect(unlink).toHaveBeenCalledTimes(2);
    await expect(cleanupMultipartTemp(undefined)).resolves.toBeUndefined();
  });
});

describe('prepareVideoGenParams', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    probeVideoDuration.mockResolvedValue(41.041281);
    listVideoModels.mockReturnValue([{
      id: 'ltx2_unified', name: 'LTX-2 Unified', runtime: 'ltx2', supportedModes: ['text', 'image', 'fflf'],
    }]);
    loadHistory.mockResolvedValue([]);
  });

  describe('happy paths', () => {
    it('returns local params with the resolved model, chunks and staged upload path', async () => {
      const prepared = await prepare({ mode: 'image', chunks: 2 }, { sourceImage: upload('sourceImage') });
      expect(prepared.backend).toBe('local');
      expect(prepared.effectiveModelId).toBe('ltx2_unified');
      expect(prepared.effectiveModel.supportedModes).toEqual(['text', 'image', 'fflf']);
      expect(prepared.effectiveChunks).toBe(2);
      expect(posix(prepared.sourceImagePath)).toMatch(/^\/mock\/uploads\/video-source-.*\.png$/);
      // The start-frame upload rides the legacy single field so already-persisted
      // jobs from before the array field still clean up correctly.
      expect(prepared.uploadedTempPath).toBe(prepared.sourceImagePath);
      expect(prepared.uploadedTempPaths).toEqual([]);
      expect(unlinkedDurablePaths()).toEqual([]);

      await prepared.discardSourceImage();
      expect(unlinkedDurablePaths()).toEqual([posix(prepared.uploadedTempPath)]);
      expect(unlink).toHaveBeenCalledWith('/tmp/multipart-sourceImage-frame.png');
    });

    it('uses the saved local video model when a request omits modelId', async () => {
      const preferredModel = {
        id: 'preferred-video-model', name: 'Preferred model', runtime: 'ltx2', supportedModes: ['text'],
      };
      getSettings.mockResolvedValueOnce({ videoGen: { defaultModelId: preferredModel.id } });
      listVideoModels.mockReturnValue([preferredModel]);
      defaultVideoModelId.mockImplementationOnce((_capabilities, preferredId) => preferredId || 'ltx2_unified');

      const prepared = await prepare({});

      expect(prepared.effectiveModelId).toBe(preferredModel.id);
      expect(defaultVideoModelId).toHaveBeenCalledWith(expect.any(Object), preferredModel.id);
    });

    it('probes LTX-2.5 audio and derives a full-duration 8n+1 frame canvas', async () => {
      const ltx25 = {
        id: 'ltx25_mlx_q8',
        name: 'LTX-2.5 MLX Q8',
        runtime: 'ltx25',
        supportedModes: ['text', 'image', 'fflf', 'extend', 'a2v'],
        audioDurationDriven: true,
        frameStride: 8,
        maxNumFrames: 1017,
      };
      listVideoModels.mockReturnValue([ltx25]);

      const prepared = await prepare(
        { modelId: ltx25.id, mode: 'a2v', fps: 24, numFrames: 121 },
        { sourceImage: upload('sourceImage'), audioFile: upload('audioFile', 'awakening.wav') },
      );

      expect(probeVideoDuration).toHaveBeenCalledWith(prepared.audioFilePath);
      expect(prepared.effectiveNumFrames).toBe(985);
      expect(posix(prepared.sourceImagePath)).toMatch(/^\/mock\/uploads\/video-source-.*\.png$/);
      expect(posix(prepared.audioFilePath)).toMatch(/^\/mock\/uploads\/video-audio-.*\.wav$/);
    });

    // The a2v duration probe would otherwise open a playlist posing as audio.
    it('refuses a staged upload whose bytes are a media playlist before copying or probing it', async () => {
      const ltx25 = {
        id: 'ltx25_mlx_q8', name: 'LTX-2.5 MLX Q8', runtime: 'ltx25',
        supportedModes: ['a2v'], audioDurationDriven: true, frameStride: 8, maxNumFrames: 1017,
      };
      listVideoModels.mockReturnValue([ltx25]);
      assertManifestMock.mockRejectedValueOnce(Object.assign(new Error('File content is a hls playlist'), { status: 400, code: 'INVALID_FILE_TYPE' }));

      await expect(prepare(
        { modelId: ltx25.id, mode: 'a2v', fps: 24, numFrames: 121 },
        { audioFile: upload('audioFile', 'song.wav') },
      )).rejects.toMatchObject({ status: 400, code: 'INVALID_FILE_TYPE' });
      expect(assertManifestMock).toHaveBeenCalledWith('/tmp/multipart-audioFile-song.wav');
      expect(copyFileMock).not.toHaveBeenCalledWith('/tmp/multipart-audioFile-song.wav', expect.anything());
      expect(probeVideoDuration).not.toHaveBeenCalled();
    });

    it('rejects and cleans up LTX-2.5 audio beyond the single-pass boundary', async () => {
      const ltx25 = {
        id: 'ltx25_mlx_q8',
        name: 'LTX-2.5 MLX Q8',
        runtime: 'ltx25',
        supportedModes: ['a2v'],
        audioDurationDriven: true,
        frameStride: 8,
        maxNumFrames: 1017,
      };
      listVideoModels.mockReturnValue([ltx25]);
      probeVideoDuration.mockResolvedValue(60);

      await expect(prepare(
        { modelId: ltx25.id, mode: 'a2v', fps: 24, numFrames: 121 },
        { audioFile: upload('audioFile', 'one-minute.wav') },
      )).rejects.toMatchObject({ status: 400, code: 'VIDEO_GEN_AUDIO_TOO_LONG' });
      expect([...new Set(unlinkedDurablePaths())]).toEqual([
        expect.stringMatching(/^\/mock\/uploads\/video-audio-.*\.wav$/),
      ]);
    });

    it('keeps the scene canvas and prefers uploaded audio over the project song', async () => {
      listVideoModels.mockReturnValue([{
        id: 'ltx25_mlx_q8', name: 'LTX-2.5', runtime: 'ltx25',
        supportedModes: ['a2v'], audioDurationDriven: true,
        frameStride: 8, maxNumFrames: 1017,
      }]);
      const prepared = await prepare({
        modelId: 'ltx25_mlx_q8', mode: 'a2v', numFrames: 121,
        sourceImageFile: 'reference.png',
        musicVideo: { projectId: 'project-example', sceneId: 'scene-example' },
      }, { audioFile: upload('audioFile', 'override.wav') });

      expect(prepared.effectiveNumFrames).toBe(121);
      expect(prepared.uploadedTempPaths).toEqual([prepared.audioFilePath]);
      expect(copyFileMock).toHaveBeenCalledWith('/tmp/multipart-audioFile-override.wav', prepared.audioFilePath);
      expect(getMusicVideoProject).not.toHaveBeenCalled();
      expect(probeVideoDuration).not.toHaveBeenCalled();
      await prepared.cleanupStaged();
      expect(unlinkedDurablePaths()).toEqual([posix(prepared.audioFilePath)]);
    });

    // Uniquely catches a local Music Video clip falling back to the model's
    // 768x512 (3:2) default, which crops its still and leaves side gaps in the
    // 16:9 video, and an end-frame clip losing length to the FFLF pixel budget.
    it('sizes an unsized local Music Video clip to the project aspect', async () => {
      getMusicVideoProject.mockResolvedValue({ treatment: { brief: { aspectRatio: '16:9' } }, scenes: [] });
      const musicVideo = { projectId: 'project-example', sceneId: 'scene-example' };
      const body = { prompt: 'a clip', backend: 'local', mode: 'image', sourceImageFile: 'still.png', musicVideo };
      await prepareVideoGenParams({ body, uploads: {}, localOnlyParamKeys: LOCAL_ONLY_KEYS });
      expect([body.width, body.height]).toEqual([1024, 576]);

      const endFrame = { ...body, width: undefined, height: undefined, mode: 'fflf', lastImageFile: 'end.png' };
      await prepareVideoGenParams({ body: endFrame, uploads: {}, localOnlyParamKeys: LOCAL_ONLY_KEYS });
      expect([endFrame.width, endFrame.height]).toEqual([896, 512]);

      const picked = { ...body, width: 768, height: 512 };
      await prepareVideoGenParams({ body: picked, uploads: {}, localOnlyParamKeys: LOCAL_ONLY_KEYS });
      expect([picked.width, picked.height]).toEqual([768, 512]);
    });

    // Uniquely catches an audio-only model (MiniMax H3 Ref2VA) failing a local
    // lip-sync shot on the image-mode contract before its song slice exists,
    // and a cutaway on it failing with the bare mode error instead of the fix.
    it('lets Ref2VA render a lip-sync shot and points a cutaway at an image model', async () => {
      listVideoModels.mockReturnValue([{
        id: 'ref2va_example', name: 'MiniMax H3 Ref2VA', runtime: 'minimax_h3_ref2va', supportedModes: ['a2v'],
        requiresSourceImageForA2v: true, frameOptions: [124], defaultFrames: 124, supportsDisableAudio: false,
      }]);
      const project = (shotMode) => ({ treatment: { brief: { aspectRatio: '16:9' } }, scenes: [{ sceneId: 'scene-example', shotMode }] });
      const musicVideo = { projectId: 'project-example', sceneId: 'scene-example' };
      const body = { prompt: 'she sings', backend: 'local', mode: 'image', modelId: 'ref2va_example', sourceImageFile: 'still.png', disableAudio: true, musicVideo };

      getMusicVideoProject.mockResolvedValue(project('performance'));
      const lipSync = { ...body };
      const prepared = await prepareVideoGenParams({ body: lipSync, uploads: {}, localOnlyParamKeys: LOCAL_ONLY_KEYS });
      expect(prepared.backend).toBe('local');
      expect(lipSync.disableAudio).toBeUndefined();

      getMusicVideoProject.mockResolvedValue(project('cutaway'));
      await expect(prepareVideoGenParams({ body: { ...body }, uploads: {}, localOnlyParamKeys: LOCAL_ONLY_KEYS }))
        .rejects.toMatchObject({ code: 'MUSIC_VIDEO_MODEL_NEEDS_PERFORMANCE_SHOT' });
    });

    it('short-circuits for grok without staging local-only inputs', async () => {
      const prepared = await prepare({ backend: 'grok', sourceImageFile: 'still.png' });
      expect(prepared.backend).toBe('grok');
      expect(prepared.grok.grokPath).toBe('/usr/bin/grok');
      expect(prepared.sourceImagePath).toBe('/mock/images/still.png');
      expect(prepared.effectiveModel).toMatchObject({ id: 'grok', supportedModes: ['text', 'image'] });
      // The local-only fields are absent entirely — the route must not read them.
      expect(prepared.effectiveChunks).toBeUndefined();
      expect(prepared.loras).toBeUndefined();
    });

    it.each(['fal', 'reactor'])('returns the complete %s prepared contract without credentials', async (backend) => {
      getSettings.mockResolvedValueOnce({ videoGen: { [backend]: { apiKey: 'example-secret' } } });
      const prepared = await prepare({ backend, sourceImageFile: 'still.png' });
      expect(prepared).toStrictEqual({
        backend,
        effectiveModel: { id: backend, supportedModes: ['text', 'image'] },
        sourceImagePath: '/mock/images/still.png',
        uploadedTempPath: null,
        discardSourceImage: expect.any(Function),
        cleanupStaged: expect.any(Function),
      });
    });

    it('normalizes the parallel lora arrays and defaults a missing scale', async () => {
      const prepared = await prepare({ loraFilenames: ['a.safetensors', 'b.safetensors'], loraScales: [0.4] });
      expect(prepared.loras).toEqual([
        { filename: 'a.safetensors', scale: 0.4 },
        { filename: 'b.safetensors', scale: 1.0 },
      ]);
    });

    it('defaults mode to fflf and pins chunks to 1 for an IC remix', async () => {
      const keyframed = await prepare({ keyframes: [{ file: 'a.png', index: 0 }, { file: 'b.png', index: 40 }] });
      expect(keyframed.mode).toBe('fflf');
      expect(keyframed.resolvedKeyframes).toEqual([
        { path: '/mock/images/a.png', index: 0 },
        { path: '/mock/images/b.png', index: 40 },
      ]);

      loadHistory.mockResolvedValue([{ id: '11111111-1111-4111-8111-111111111111', filename: 'prior.mp4' }]);
      const ic = await prepare({ mode: 'ic-control', icReferenceVideoIds: ['11111111-1111-4111-8111-111111111111'] });
      expect(ic.effectiveChunks).toBe(1);
      // resolve() stamps a drive letter on Windows, so build the expectation the
      // same way rather than hardcoding a POSIX absolute path.
      expect(ic.icReferencePaths).toEqual([resolvePath('/mock/videos/prior.mp4')]);
    });
  });

  describe('per-chunk prompt beats (#3695)', () => {
    it('preserves nonblank beats as authored and keeps a blank entry in position as a fallback marker', async () => {
      const prepared = await prepare({ mode: 'image', chunks: 3, chunkPrompts: ['  opens the door\n\t', '', 'the storm breaks'] });
      expect(prepared.effectiveChunkPrompts).toEqual(['  opens the door\n\t', null, 'the storm breaks']);
    });

    it('truncates a stale overlong list to the resolved chunk count', async () => {
      // The user typed four beats, then lowered Chunks to 2 — the extra beats
      // must not ride along and desync the list from the chain.
      const prepared = await prepare({ mode: 'image', chunks: 2, chunkPrompts: ['a', 'b', 'c', 'd'] });
      expect(prepared.effectiveChunkPrompts).toEqual(['a', 'b']);
    });

    it('leaves a short list short — uncovered chunks fall back to the main prompt', async () => {
      const prepared = await prepare({ mode: 'image', chunks: 3, chunkPrompts: ['a'] });
      expect(prepared.effectiveChunkPrompts).toEqual(['a']);
    });

    it('drops the list entirely for a single-chunk render', async () => {
      const prepared = await prepare({ mode: 'image', chunks: 1, chunkPrompts: ['a', 'b'] });
      expect(prepared.effectiveChunkPrompts).toBeUndefined();
    });

    it('drops the list for a mode pinned to one chunk', async () => {
      // An IC remix anchors a single clip, so chunks is pinned to 1 — a beat
      // list sent anyway must not persist into job params.
      loadHistory.mockResolvedValue([{ id: '11111111-1111-4111-8111-111111111111', filename: 'prior.mp4' }]);
      const prepared = await prepare({
        mode: 'ic-control',
        icReferenceVideoIds: ['11111111-1111-4111-8111-111111111111'],
        chunkPrompts: ['a', 'b'],
      });
      expect(prepared.effectiveChunks).toBe(1);
      expect(prepared.effectiveChunkPrompts).toBeUndefined();
    });

    it('collapses an all-blank list to undefined', async () => {
      // "every beat cleared" and "no beats sent" must persist identically —
      // otherwise a resume replays an array of nulls into the form.
      const prepared = await prepare({ mode: 'image', chunks: 3, chunkPrompts: ['', '  ', ''] });
      expect(prepared.effectiveChunkPrompts).toBeUndefined();
    });

    it('is undefined when no beats were supplied', async () => {
      const prepared = await prepare({ mode: 'image', chunks: 2 });
      expect(prepared.effectiveChunkPrompts).toBeUndefined();
    });
  });

  describe('rejected-await rollback (#3326)', () => {
    // Each case stages a durable copy, then makes the NEXT await reject. Without
    // the withStagedRollback guard the rejection bubbles past every explicit
    // cleanupAllStaged() call and the durable copy is orphaned forever.
    const musicVideo = { projectId: 'proj-1', sceneId: 'scene-1' };

    it('unwinds the staged source frame when the music-video project lookup rejects', async () => {
      const boom = new Error('project store unavailable');
      getMusicVideoProject.mockRejectedValue(boom);

      await expect(prepare({ mode: 'a2v', musicVideo }, { sourceImage: upload('sourceImage') }))
        .rejects.toBe(boom);

      expect(unlinkedDurablePaths()).toEqual([expect.stringMatching(/^\/mock\/uploads\/video-source-.*\.png$/)]);
    });

    it('unwinds the staged source frame when the track lookup rejects', async () => {
      const boom = new Error('track store unavailable');
      getMusicVideoProject.mockResolvedValue({ scenes: [{ sceneId: 'scene-1' }], trackId: 'track-1' });
      getTrack.mockRejectedValue(boom);

      await expect(prepare({ mode: 'a2v', musicVideo }, { sourceImage: upload('sourceImage') }))
        .rejects.toBe(boom);

      expect(unlinkedDurablePaths()).toEqual([expect.stringMatching(/^\/mock\/uploads\/video-source-.*\.png$/)]);
    });

    it('unwinds the staged source frame when the history read rejects', async () => {
      const boom = new Error('history file corrupt');
      loadHistory.mockRejectedValue(boom);

      await expect(prepare(
        { extendFromVideoId: '22222222-2222-4222-8222-222222222222' },
        { sourceImage: upload('sourceImage') },
      )).rejects.toBe(boom);

      expect(unlinkedDurablePaths()).toEqual([expect.stringMatching(/^\/mock\/uploads\/video-source-.*\.png$/)]);
    });

    it('unwinds EVERY staged copy, not just the last one', async () => {
      const boom = new Error('history file corrupt');
      loadHistory.mockRejectedValue(boom);

      await expect(prepare(
        { extendFromVideoId: '33333333-3333-4333-8333-333333333333' },
        { sourceImage: upload('sourceImage'), lastImage: upload('lastImage', 'end.png') },
      )).rejects.toBe(boom);

      const durable = unlinkedDurablePaths();
      expect(durable).toHaveLength(2);
      expect(durable).toEqual(expect.arrayContaining([
        expect.stringMatching(/^\/mock\/uploads\/video-source-.*\.png$/),
        expect.stringMatching(/^\/mock\/uploads\/video-last-.*\.png$/),
      ]));
    });

  });

  describe('explicit validation throws still clean up', () => {
    it('rejects an unknown modelId and drops the multipart temp file', async () => {
      await expect(prepare({ modelId: 'nope' }, { sourceImage: upload('sourceImage') }))
        .rejects.toMatchObject({ status: 400, code: 'VIDEO_GEN_UNKNOWN_MODEL' });
      expect(unlink).toHaveBeenCalledWith('/tmp/multipart-sourceImage-frame.png');
      // Rejected BEFORE staging, so nothing durable was written.
      expect(unlinkedDurablePaths()).toEqual([]);
    });

    it('rejects a music-video render whose reference frame will not resolve', async () => {
      await expect(prepare({ musicVideo: { projectId: 'p', sceneId: 's' }, sourceImageFile: '..' }))
        .rejects.toMatchObject({ status: 400, code: 'MUSIC_VIDEO_SOURCE_REQUIRED' });
    });

    // Rejected here rather than in the worker: the request that named the bad
    // conditioner is the only place that can report it, and a persisted job
    // would otherwise sit in the queue only to die on dispatch.
    it('rejects a text encoder the selected model cannot load, before staging', async () => {
      await expect(prepare(
        { textEncoderId: 'heretic-bf16' },
        { sourceImage: upload('sourceImage') },
      )).rejects.toMatchObject({ status: 400, code: 'VIDEO_TEXT_ENCODER_UNSUPPORTED' });
      expect(unlink).toHaveBeenCalledWith('/tmp/multipart-sourceImage-frame.png');
      expect(unlinkedDurablePaths()).toEqual([]);
    });

    // 'stock' and absence are the same request, so neither may reject — the
    // route drops the sentinel from persisted params, which means a resumed
    // render sends absence where the original sent 'stock'.
    it.each([undefined, 'stock'])('accepts %j on a model with no substitutions', async (textEncoderId) => {
      await expect(prepare({ textEncoderId })).resolves.toMatchObject({ effectiveModelId: 'ltx2_unified' });
    });

    it('rejects a history id that is not in the render history', async () => {
      await expect(prepare({ extendFromVideoId: '22222222-2222-4222-8222-222222222222' }))
        .rejects.toMatchObject({ status: 404, code: 'EXTEND_SOURCE_NOT_FOUND' });
    });

    it('rejects an unsupported Wan mode before staging its upload', async () => {
      listVideoModels.mockReturnValue([{
        id: 'wan_t2v', name: 'Wan T2V', runtime: 'wan22',
        supportedModes: ['text'], frameStride: 4,
      }]);

      await expect(prepare(
        { modelId: 'wan_t2v', mode: 'image' },
        { sourceImage: upload('sourceImage') },
      )).rejects.toMatchObject({ status: 400, code: 'WAN22_MODE_UNSUPPORTED' });

      expect(unlinkedDurablePaths()).toEqual([]);
      expect(unlink).toHaveBeenCalledWith('/tmp/multipart-sourceImage-frame.png');
    });

    it('rejects a non-4n+1 Wan frame count before enqueue', async () => {
      listVideoModels.mockReturnValue([{
        id: 'wan_ti2v', name: 'Wan TI2V', runtime: 'wan22',
        supportedModes: ['text', 'image'], frameStride: 4,
      }]);

      await expect(prepare({ modelId: 'wan_ti2v', mode: 'text', numFrames: 120 }))
        .rejects.toMatchObject({ status: 400, code: 'WAN22_INVALID_FRAME_COUNT' });
    });

    it('rejects Wan image mode without a declared source before staging', async () => {
      listVideoModels.mockReturnValue([{
        id: 'wan_ti2v', name: 'Wan TI2V', runtime: 'wan22',
        supportedModes: ['text', 'image'], frameStride: 4,
      }]);

      await expect(prepare({ modelId: 'wan_ti2v', mode: 'image', numFrames: 121 }))
        .rejects.toMatchObject({ status: 400, code: 'WAN22_I2V_REQUIRES_IMAGE' });
      expect(unlinkedDurablePaths()).toEqual([]);
    });

    it('rejects Wan image mode when its gallery source no longer resolves', async () => {
      listVideoModels.mockReturnValue([{
        id: 'wan_ti2v', name: 'Wan TI2V', runtime: 'wan22',
        supportedModes: ['text', 'image'], frameStride: 4,
      }]);
      vi.mocked(resolveGalleryImage).mockReturnValueOnce(null);

      await expect(prepare({
        modelId: 'wan_ti2v', mode: 'image', numFrames: 121, sourceImageFile: 'missing.png',
      })).rejects.toMatchObject({ status: 400, code: 'WAN22_I2V_REQUIRES_IMAGE' });
    });

    it('rejects an explicit Wan text render that also supplies a source', async () => {
      listVideoModels.mockReturnValue([{
        id: 'wan_ti2v', name: 'Wan TI2V', runtime: 'wan22',
        supportedModes: ['text', 'image'], frameStride: 4,
      }]);

      await expect(prepare(
        { modelId: 'wan_ti2v', mode: 'text', numFrames: 121 },
        { sourceImage: upload('sourceImage') },
      )).rejects.toMatchObject({ status: 400, code: 'WAN22_TEXT_MODE_SOURCE_CONFLICT' });
      expect(unlink).toHaveBeenCalledWith('/tmp/multipart-sourceImage-frame.png');
    });

    it('rejects chunks on a T2V-only Wan model before staging', async () => {
      listVideoModels.mockReturnValue([{
        id: 'wan_t2v', name: 'Wan T2V', runtime: 'wan22',
        supportedModes: ['text'], frameStride: 4,
      }]);

      await expect(prepare({ modelId: 'wan_t2v', mode: 'text', numFrames: 121, chunks: 2 }))
        .rejects.toMatchObject({ status: 400, code: 'WAN22_CHAIN_REQUIRES_IMAGE_MODE' });
      expect(unlinkedDurablePaths()).toEqual([]);
    });
  });
});

describe.each(['wan22', 'wan22_cuda'])('Wan frame admission — %s', (runtime) => {
  beforeEach(() => {
    listVideoModels.mockReturnValue([{
      id: 'wan_test', name: 'Test Wan', runtime,
      supportedModes: ['text'], frameStride: 4, defaultFrames: 120,
    }]);
  });

  it('rejects explicit and default off-grid frames in prepare and retry', async () => {
    const params = { modelId: 'wan_test', mode: 'text' };
    const error = {
      status: 400, code: 'WAN22_INVALID_FRAME_COUNT',
      message: 'Test Wan requires a 4n+1 frame count; got 120.',
    };
    await expect(prepare(params)).rejects.toMatchObject(error);
    await expect(validateVideoRetryParams(params)).rejects.toMatchObject(error);
    await expect(prepare({ ...params, numFrames: 120 })).rejects.toMatchObject(error);
    await expect(validateVideoRetryParams({ ...params, numFrames: 120 })).rejects.toMatchObject(error);
  });

  it('persists the resolved model default and falls back when absent', async () => {
    const model = { id: 'wan_test', name: 'Test Wan', runtime, supportedModes: ['text'], frameStride: 4 };
    listVideoModels.mockReturnValue([{ ...model, defaultFrames: 81 }]);
    await expect(prepare({ modelId: model.id })).resolves.toMatchObject({ effectiveNumFrames: 81 });
    listVideoModels.mockReturnValue([model]);
    await expect(prepare({ modelId: model.id })).resolves.toMatchObject({ effectiveNumFrames: 121 });
  });

  it('accepts an explicit grid count instead of an invalid model default', async () => {
    const params = { modelId: 'wan_test', mode: 'text', numFrames: 81 };
    await expect(prepare(params)).resolves.toMatchObject({ effectiveNumFrames: 81 });
    await expect(validateVideoRetryParams(params)).resolves.toBeUndefined();
  });
});

it('leaves omitted frame counts unset for other runtimes', async () => {
  listVideoModels.mockReturnValue([{
    id: 'ltx_test', name: 'Test LTX', runtime: 'ltx2', defaultFrames: 81,
  }]);
  await expect(prepare({ modelId: 'ltx_test' })).resolves.toMatchObject({ effectiveNumFrames: undefined });
});

describe('validateVideoRetryParams', () => {
  it('keeps an explicit null model sentinel unknown instead of selecting the default', async () => {
    await expect(validateVideoRetryParams({ modelId: null })).rejects.toMatchObject({
      status: 400,
      code: 'VIDEO_GEN_UNKNOWN_MODEL',
    });
  });
});

describe('prepareVideoGenParams — MiniMax H3 contract', () => {
  // H3 is license-gated, and the only authorization is the acknowledgement
  // recorded in settings — so every test below that is about H3's *mode*
  // contract runs on an install that has already accepted its terms.
  const settingsWith = (acceptedModelTerms) => ({
    imageGen: {
      local: { pythonPath: '/usr/bin/python3' },
      grok: { enabled: true, grokPath: '/usr/bin/grok', aspectRatio: '16:9' },
    },
    videoGen: { acceptedModelTerms },
  });
  beforeEach(() => {
    vi.clearAllMocks();
    listVideoModels.mockReturnValue([H3_MODEL]);
    loadHistory.mockResolvedValue([]);
    getSettings.mockResolvedValue(settingsWith([H3_TERMS]));
  });

  it('prepares an H3 text render without a recorded license acknowledgement', async () => {
    getSettings.mockResolvedValueOnce(settingsWith(undefined));
    const prepared = await prepare({ modelId: H3_MODEL.id, mode: 'text' });
    expect(prepared.effectiveModelId).toBe(H3_MODEL.id);
    expect(prepared.effectiveChunks).toBe(1);
  });

  it('does not apply the local MiniMax gate to an explicit Grok render', async () => {
    defaultVideoModelId.mockReturnValueOnce(H3_MODEL.id);
    const prepared = await prepare({ backend: 'grok' });
    expect(prepared.backend).toBe('grok');
    expect(prepared.grok).toMatchObject({ grokPath: '/usr/bin/grok' });
  });

  it.each([
    [{ mode: 'extend' }, 'MINIMAX_H3_MODE_UNSUPPORTED'],
    [{ extendFromVideoId: '00000000-0000-4000-8000-000000000001' }, 'MINIMAX_H3_MODE_UNSUPPORTED'],
    [{ mode: 'image' }, 'MINIMAX_H3_I2V_REQUIRES_IMAGE'],
    [{ mode: 'text', sourceImageFile: 'first.png' }, 'MINIMAX_H3_TEXT_MODE_SOURCE_CONFLICT'],
    [{ mode: 'image', sourceImageFile: 'first.png', lastImageFile: 'last.png' }, 'MINIMAX_H3_I2V_LAST_IMAGE_CONFLICT'],
    [{ mode: 'fflf' }, 'MINIMAX_H3_FFLF_REQUIRES_IMAGE'],
    [{ negativePrompt: 'blur' }, 'MINIMAX_H3_NEGATIVE_PROMPT_UNSUPPORTED'],
    [{ disableAudio: true }, 'MINIMAX_H3_AUDIO_REQUIRED'],
    [{ tiling: 'full' }, 'MINIMAX_H3_TILING_UNSUPPORTED'],
    [{ numFrames: 125 }, 'MINIMAX_H3_INVALID_FRAME_COUNT'],
    [{ fps: 30 }, 'MINIMAX_H3_INVALID_FPS'],
  ])('rejects an unsupported H3 request (%o)', async (fields, code) => {
    await expect(prepare({
      modelId: H3_MODEL.id,

      ...fields,
    })).rejects.toMatchObject({ status: 400, code });
  });

  it('rejects chunks > 1 only while the entry lacks image-to-video', async () => {
    listVideoModels.mockReturnValue([{ ...H3_MODEL, supportedModes: ['text'] }]);
    await expect(prepare({
      modelId: H3_MODEL.id, mode: 'text', chunks: 2,
    })).rejects.toMatchObject({ status: 400, code: 'VIDEO_CHAIN_REQUIRES_IMAGE_MODE' });

    listVideoModels.mockReturnValue([H3_MODEL]);
    const prepared = await prepare({
      modelId: H3_MODEL.id, mode: 'text', chunks: 2,
    });
    expect(prepared.effectiveChunks).toBe(2);
  });

  it.each([
    ['image', { mode: 'image', sourceImageFile: 'first.png' }],
    ['fflf', { mode: 'fflf', sourceImageFile: 'first.png', lastImageFile: 'last.png' }],
  ])('accepts %s keyframe conditioning', async (_label, fields) => {
    const prepared = await prepare({
      modelId: H3_MODEL.id,

      ...fields,
    });
    expect(prepared.effectiveModelId).toBe(H3_MODEL.id);
    expect(prepared.sourceImagePath).toBe('/mock/images/first.png');
  });

  it('accepts another supported temporal shape at fixed 24 fps', async () => {
    const prepared = await prepare({
      modelId: H3_MODEL.id,
      mode: 'text',

      numFrames: 158,
      fps: 24,
    });
    expect(prepared.effectiveModelId).toBe(H3_MODEL.id);
  });
});

// The reference-mode promise (#4874) at the REQUEST boundary — rejected before
// any durable upload is staged, so a doomed job never reaches the persisted
// queue and the cleanup stays cheap.
describe('prepareVideoGenParams — i2v reference mode (#4874)', () => {
  const LTX25 = { id: 'ltx25_mlx_q8', name: 'LTX-2.5 MLX Q8', runtime: 'ltx25' };
  const LTX2 = { id: 'ltx2_unified', name: 'LTX-2 Unified', runtime: 'ltx2' };

  beforeEach(() => {
    vi.clearAllMocks();
    listVideoModels.mockReturnValue([LTX2, LTX25]);
    loadHistory.mockResolvedValue([]);
  });

  it('accepts a loose reference on an LTX-2.5 image render', async () => {
    const prepared = await prepare(
      { modelId: 'ltx25_mlx_q8', mode: 'image', i2vReferenceMode: 'inspire' },
      { sourceImage: upload('sourceImage') },
    );
    expect(prepared.mode).toBe('image');
    expect(unlinkedDurablePaths()).toEqual([]);
  });

  it.each([undefined, '', 'anchor'])('never rejects a request that left the field at %s', async (i2vReferenceMode) => {
    await expect(prepare({ modelId: 'ltx2_unified', i2vReferenceMode })).resolves.toBeTruthy();
  });

  it('rejects a loose reference on a runtime that pins frame one, before staging', async () => {
    await expect(prepare(
      { modelId: 'ltx2_unified', mode: 'image', i2vReferenceMode: 'inspire' },
      { sourceImage: upload('sourceImage') },
    )).rejects.toMatchObject({ status: 400, code: 'I2V_REFERENCE_MODE_UNSUPPORTED' });
    // Nothing durable was written, so nothing had to be rolled back.
    expect(unlinkedDurablePaths()).toEqual([]);
  });

  // The model gate alone is not enough: an explicit grok backend never reaches
  // the chosen model's runtime at all, and its short-circuit drops every
  // local-only knob — so a loose reference would come back anchored from the
  // cloud lane with nothing having reported it.
  it('rejects a loose reference on an explicit grok backend, even with an LTX-2.5 model', async () => {
    await expect(prepare(
      { backend: 'grok', modelId: 'ltx25_mlx_q8', mode: 'image', sourceImageFile: 'frame.png', i2vReferenceMode: 'inspire' },
    )).rejects.toMatchObject({ status: 400, code: 'I2V_REFERENCE_MODE_UNSUPPORTED' });
  });

  it('still routes a default-reference request through the grok backend', async () => {
    const prepared = await prepare({ backend: 'grok', mode: 'image', sourceImageFile: 'frame.png', i2vReferenceMode: 'anchor' });
    expect(prepared.backend).toBe('grok');
  });

  it('rejects a loose reference on a text render', async () => {
    await expect(prepare({ modelId: 'ltx25_mlx_q8', i2vReferenceMode: 'inspire' }))
      .rejects.toMatchObject({ status: 400, code: 'I2V_REFERENCE_MODE_REQUIRES_IMAGE' });
  });

  it('rejects a loose reference whose gallery pick failed to resolve', async () => {
    // The declared pass sees a filename and lets it through; the resolved pass
    // is what catches an i2v request that has quietly become text-to-video.
    vi.mocked(resolveGalleryImage).mockReturnValueOnce(null);
    await expect(prepare({
      modelId: 'ltx25_mlx_q8', mode: 'image', sourceImageFile: 'missing.png', i2vReferenceMode: 'inspire',
    })).rejects.toMatchObject({ status: 400, code: 'I2V_REFERENCE_MODE_REQUIRES_IMAGE' });
  });
});

describe('prepareVideoGenParams — fal end frame catalog check (#10700)', () => {
  const falSettings = () => ({ imageGen: { local: { pythonPath: '/usr/bin/python3' } }, videoGen: { fal: { apiKey: 'test-key' } } });
  beforeEach(() => { copyFileMock.mockClear(); unlinkMock.mockClear(); });

  it('refuses an end frame for a fal model whose catalog entry takes none, and removes the temp upload', async () => {
    getSettings.mockResolvedValueOnce(falSettings());
    const lastImage = upload('lastImage', 'end.png');
    await expect(prepare(
      { backend: 'fal', falModelId: 'fal-ai/veo3.1/fast/image-to-video', mode: 'image', sourceImageFile: 'face.png' },
      { lastImage },
    )).rejects.toMatchObject({
      status: 400,
      code: 'VALIDATION_ERROR',
      message: expect.stringContaining('takes no end frame'),
    });
    expect(unlinkMock).toHaveBeenCalledWith(lastImage.path);
    expect(copyFileMock).not.toHaveBeenCalled();
  });

  it('stages a catalogued end frame durably and hands it to the hosted job', async () => {
    getSettings.mockResolvedValueOnce(falSettings());
    const prepared = await prepare(
      { backend: 'fal', mode: 'image', sourceImageFile: 'face.png' },
      { lastImage: upload('lastImage', 'end.png') },
    );
    expect(posix(prepared.lastImagePath)).toMatch(/^\/mock\/uploads\/video-last-.+\.png$/);
    expect(prepared.uploadedTempPaths).toEqual([prepared.lastImagePath]);
  });
});

describe('prepareVideoGenParams — standalone fal lip sync', () => {
  const LIPSYNC = 'minimax/h3-max/lip-sync/image-to-video';
  const falSettings = () => ({ imageGen: { local: { pythonPath: '/usr/bin/python3' } }, videoGen: { fal: { apiKey: 'test-key' } } });
  beforeEach(() => { copyFileMock.mockClear(); unlinkMock.mockClear(); });

  it('stages the uploaded voice clip next to the frame and hands both to the hosted job', async () => {
    getSettings.mockResolvedValueOnce(falSettings());
    const prepared = await prepare(
      { backend: 'fal', falModelId: LIPSYNC, mode: 'image', sourceImageFile: 'face.png' },
      { audioFile: upload('audioFile', 'line.wav') },
    );
    expect(prepared.backend).toBe('fal');
    expect(posix(prepared.sourceImagePath)).toBe('/mock/images/face.png');
    expect(posix(prepared.audioFilePath)).toMatch(/^\/mock\/uploads\/video-audio-.+\.wav$/);
    expect(prepared.uploadedTempPaths).toEqual([prepared.audioFilePath]);
  });

  it('refuses a lip-sync model without a voice clip, and a voice clip without a lip-sync model', async () => {
    getSettings.mockResolvedValueOnce(falSettings());
    await expect(prepare({ backend: 'fal', falModelId: LIPSYNC, mode: 'image', sourceImageFile: 'face.png' }))
      .rejects.toMatchObject({ status: 400, code: 'VIDEO_GEN_AUDIO_REQUIRED' });
    getSettings.mockResolvedValueOnce(falSettings());
    await expect(prepare(
      { backend: 'fal', falModelId: 'fal-ai/minimax/hailuo-02/standard/image-to-video', mode: 'image', sourceImageFile: 'face.png' },
      { audioFile: upload('audioFile', 'line.wav') },
    )).rejects.toMatchObject({ status: 400, code: 'VIDEO_GEN_AUDIO_MODE_MISMATCH' });
  });

  it('refuses a voice clip fal would reject before anything is submitted', async () => {
    getSettings.mockResolvedValueOnce(falSettings());
    probeVideoDuration.mockResolvedValueOnce(3.2);
    await expect(prepare(
      { backend: 'fal', falModelId: LIPSYNC, mode: 'image', sourceImageFile: 'face.png' },
      { audioFile: upload('audioFile', 'line.wav') },
    )).rejects.toMatchObject({ status: 400, code: 'VIDEO_GEN_AUDIO_LENGTH' });
    getSettings.mockResolvedValueOnce(falSettings());
    probeVideoDuration.mockResolvedValueOnce(null);
    await expect(prepare(
      { backend: 'fal', falModelId: LIPSYNC, mode: 'image', sourceImageFile: 'face.png' },
      { audioFile: upload('audioFile', 'line.wav') },
    )).rejects.toMatchObject({ status: 400, code: 'VIDEO_GEN_AUDIO_DURATION_UNREADABLE' });
    expect(unlinkMock).toHaveBeenCalled(); // the staged clip is rolled back
  });

  it('needs a reference frame for the lip sync', async () => {
    getSettings.mockResolvedValueOnce(falSettings());
    await expect(prepare({ backend: 'fal', falModelId: LIPSYNC, mode: 'text' }, { audioFile: upload('audioFile', 'line.wav') }))
      .rejects.toMatchObject({ status: 400, code: 'VALIDATION_ERROR' });
  });
});