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

62.3 KB
Raw Blame
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it as vitestIt, vi } from 'vitest';
import { createHash } from 'node:crypto';
import { closeSync, constants, openSync } from 'node:fs';
import { mkdir, readFile, rm, stat, symlink, truncate, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import express from 'express';
import sharp from 'sharp';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy, ownTestBodies } from '../../lib/mockPathsDataRoot.js';
import { request } from '../../lib/testHelper.js';
import { errorMiddleware } from '../../lib/errorHandler.js';
import { readZipArchive } from '../../lib/zipArchive.js';
import * as ffmpeg from '../../lib/ffmpeg.js';
import * as jsonIo from '../../lib/jsonIo.js';
import { findFfmpeg, findFfprobe, runFfmpegProcess } from '../../lib/ffmpeg.js';
import {
  FABLELOOM_EXPORT_LIMITS, inspectFableLoomExportCharacters,
} from '../../lib/fableLoomExport.js';
import { FABLELOOM_STATIC_PLAYER_FILES } from './staticPlayerFiles.js';
import { execFileSync } from '../../lib/childProcess.js';

vi.mock('../../lib/paths.js', async original => makePathsProxy(await original(), {
  dataRoot: () => lazyTempDataRoot('portos-fableloom-export-'),
}));
const exportBudget = vi.hoisted(() => ({ maxPackageBytes: null }));
vi.mock('../../lib/fableLoomExport.js', async original => {
  const module = await original();
  return { ...module, FABLELOOM_EXPORT_LIMITS: {
    ...module.FABLELOOM_EXPORT_LIMITS,
    get maxPackageBytes() { return exportBudget.maxPackageBytes ?? module.FABLELOOM_EXPORT_LIMITS.maxPackageBytes; },
  } };
});
vi.mock('./records.js', () => ({ getLoom: vi.fn() }));
vi.mock('../videoGen/history.js', () => ({ loadHistory: vi.fn() }));
vi.mock('../universeBuilder.js', () => ({ getUniverse: vi.fn() }));
vi.mock('../voice/profiles.js', () => ({ listVoiceProfiles: vi.fn() }));
vi.mock('./index.js', () => ({}));
vi.mock('./shotRuns.js', () => ({}));

import { PATHS } from '../../lib/paths.js';
import { getLoom } from './records.js';
import { loadHistory } from '../videoGen/history.js';
import { getUniverse } from '../universeBuilder.js';
import { listVoiceProfiles } from '../voice/profiles.js';
import * as media from './exportMedia.js';
import * as voiceReferences from './exportVoice.js';
import {
  __testing, preflightFableLoomExport, startFableLoomExport, getFableLoomExport, getFableLoomExportDownload,
} from './exports.js';
import routes from '../../routes/fableLoom.js';
import { fableLoomRunEvents } from './runEvents.js';

const owned = ownTestBodies(vitestIt);
const it = owned.it;
const bin = await findFfmpeg();
const probe = await findFfprobe();
const canPrepareVideo = Boolean(bin && probe);
const videoIt = canPrepareVideo ? it : vitestIt.skip;
const posixIt = process.platform === 'win32' ? vitestIt.skip : it;
const privateMarker = 'EXAMPLE_PRIVATE_SENTINEL';
const sourcePath = '/example-private/source';
let sourceImage;
let sourceVideo;
let loom;
const jobIds = [];
const hash = bytes => createHash('sha256').update(bytes).digest('hex');
const recordFile = id => join(PATHS.data, 'cache/fableloom-exports', id, 'job.json');
const app = () => express().use(express.json()).use('/api/fableloom', routes).use(errorMiddleware);
const conditioning = kind => ({
  version: 1, status: 'locked', capability: { kind, backend: 'example-provider', modelId: 'Example/Model' },
  render: { provider: 'example-provider', modelId: 'Example/Model', parameters: { seed: 42, secret: privateMarker } },
  adapters: [{ filename: sourcePath }], assets: [{ filename: sourcePath }],
  compiledPrompt: privateMarker, instanceId: privateMarker,
});
function episode(id, number = 1) {
  const nodes = [
    { id: id + '-start', title: 'At the gate', prose: 'A traveller reaches a quiet gate.',
      playbackMode: 'decision', audienceConnection: 'connected', protagonistPresence: 'offscreen',
      isEnding: false, endingLabel: '', image: 'still.png',
      visualCanon: { storyboardImageApproved: true }, visualConditioning: conditioning('image'),
      videoHistoryId: 'entry-record',
      playbackAssets: { entryVideoHistoryId: 'entry-record', holdLoopVideoHistoryIds: ['hold-record'],
        exitByTransition: { choose: 'exit-record' },
        visualConditioningByAsset: Object.fromEntries(['entry-record', 'hold-record', 'exit-record'].map(key => [key, conditioning('video')])),
        audioOccupancy: { 'hold-record': { durationMs: 1000, effects: [
          { startMs: 0, endMs: 500, blocking: false, name: privateMarker },
        ] } } },
      interactionWindow: { enabled: true, protagonistCharacterId: 'example-character', protagonistPresence: 'offscreen' },
      transitions: [
        { id: 'choose', intent: 'Open', triggers: ['open'], description: 'Open the gate.', targetNodeId: id + '-end' },
        { id: 'leave', intent: 'Leave', triggers: ['leave'], description: 'Take another path.', targetNodeId: id + '-end' },
      ], sessions: [privateMarker], apiKey: privateMarker },
    { id: id + '-end', title: 'Home', prose: 'The traveller finds a home.',
      playbackMode: 'cut', audienceConnection: 'connected', protagonistPresence: 'offscreen',
      isEnding: true, endingLabel: 'Home', image: 'still.png', videoHistoryId: 'entry-record',
      visualCanon: { storyboardImageApproved: true }, visualConditioning: conditioning('image'),
      playbackAssets: { entryVideoHistoryId: 'entry-record', visualConditioningByAsset: { 'entry-record': conditioning('video') } },
      transitions: [] },
  ];
  return { id, number, title: 'Example episode', synopsis: 'A journey.', startNodeId: nodes[0].id, nodes,
    storyOutline: { startKey: nodes[0].id, validation: { status: 'valid' },
      scenes: nodes.map(node => ({ ...node, key: node.id, summary: node.title,
        transitions: node.transitions.map(t => ({ ...t, targetKey: t.targetNodeId })) })) } };
}

async function begin(options = {}) {
  const result = await startFableLoomExport(loom.id, options);
  jobIds.push(result.jobId);
  return result.jobId;
}
async function terminal(id) {
  let result;
  await vi.waitFor(async () => {
    result = await getFableLoomExport(loom.id, id);
    expect(['completed', 'failed']).toContain(result.status);
  }, { timeout: 10_000, interval: 20 });
  return result;
}
async function archive(id) {
  const result = await terminal(id);
  expect(result, JSON.stringify(result)).toMatchObject({ status: 'completed' });
  const artifact = await getFableLoomExportDownload(loom.id, id);
  try {
    const bytes = await readFile(artifact.path);
    return { bytes, files: new Map(readZipArchive(bytes).map(e => [e.name, e.read()])) };
  } finally { artifact.release(); }
}

const packageSentinels = [
  privateMarker, sourcePath, 'SECRET_TOKEN_SENTINEL', 'SESSION_TRANSCRIPT_SENTINEL',
  'SECRET_CAST_SENTINEL', 'SECRET_ENGINE_SENTINEL', 'kokoro:SECRET_PRESET',
  'SECRET_APPROVED_AT', '/example-private/checkpoint', 'example-voice',
];
function assertPackageClean(packed) {
  for (const marker of packageSentinels) {
    expect(packed.bytes.includes(Buffer.from(marker)), marker).toBe(false);
    for (const bytes of packed.files.values()) expect(bytes.includes(Buffer.from(marker)), marker).toBe(false);
  }
}
function approvedCharacter(overrides = {}) {
  return {
    id: 'example-character', name: 'Ada Example',
    personality: 'Calm and precise.', speechAccent: 'Neutral example accent.',
    speechPattern: 'Short sentences.', mannerisms: 'Pauses before answers.',
    background: privateMarker, secrets: 'SECRET_TOKEN_SENTINEL', psychology: privateMarker,
    voiceId: 'kokoro:SECRET_PRESET', prompt: privateMarker,
    adapters: [{ filename: sourcePath }], loras: [sourcePath], imageRefs: [sourcePath],
    sessions: ['SESSION_TRANSCRIPT_SENTINEL'],
    voiceCanon: {
      version: 2, approved: true, sourcePolicy: 'designed',
      description: 'Warm mid register.', defaultDelivery: 'Measured.',
      emotionalRange: ['steady'], avoid: ['never shout'],
      pronunciations: [{ term: 'Fable', pronunciation: 'FAY-bul', recordingPath: sourcePath }],
      recordingPath: sourcePath,
    },
    ...overrides,
  };
}
function useCast(characters = [approvedCharacter()]) {
  loom.protagonistCharacterId = 'example-character';
  getUniverse.mockResolvedValue({
    id: 'example-universe',
    characters: [...characters, { id: 'unbound-extra', name: 'SECRET_CAST_SENTINEL', personality: privateMarker }],
  });
}
async function writeVoiceReference(bytes, filename = 'reference.wav') {
  const dir = join(PATHS.voiceProfiles, 'example-voice', 'source');
  await mkdir(dir, { recursive: true });
  await writeFile(join(dir, filename), bytes);
  return hash(bytes);
}
function voiceProfile({ sha256, filename = 'reference.wav', id = 'example-voice', kind = 'designed', sourceAssets } = {}) {
  return {
    id, kind, engine: 'SECRET_ENGINE_SENTINEL', voiceId: 'kokoro:SECRET_PRESET',
    binding: { universeId: 'example-universe', characterId: 'example-character' },
    approval: { status: 'approved', approvedAt: 'SECRET_APPROVED_AT' },
    routes: { interactive: { enabled: true } },
    inference: { checkpointPath: '/example-private/checkpoint' },
    sourceAssets: sourceAssets || [{
      filename, sha256, transcript: 'SESSION_TRANSCRIPT_SENTINEL',
      performerConsentConfirmed: false, licensePosture: 'generated-original-voice', path: sourcePath,
    }],
  };
}
async function expectVoiceRefusal(profiles, code, options = { includeCharacters: true, includeVoice: true }) {
  listVoiceProfiles.mockResolvedValue(profiles);
  const result = await terminal(await begin({ episodeIds: ['episode-one'], ...options }));
  expect(result).toMatchObject({ status: 'failed', error: { code: 'EXPORT_VALIDATION_FAILED' } });
  expect(result.findings).toContainEqual(expect.objectContaining({ code, severity: 'error' }));
  expect(result).not.toHaveProperty('downloadUrl');
  expect(JSON.stringify(result)).not.toContain(sourcePath);
  expect(JSON.stringify(result)).not.toContain('SESSION_TRANSCRIPT_SENTINEL');
  expect(JSON.stringify(result)).not.toContain('example-voice');
  expect(JSON.stringify(result)).not.toContain('/example-private/checkpoint');
  await expect(stat(join(PATHS.data, 'cache/fableloom-exports', jobIds.at(-1), 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });
  return result;
}

beforeAll(async () => {
  await mkdir(PATHS.images, { recursive: true });
  await mkdir(PATHS.videos, { recursive: true });
  sourceImage = await sharp({ create: { width: 32, height: 32, channels: 3, background: '#345678' } })
    .withMetadata({ exif: { IFD0: { ImageDescription: privateMarker + sourcePath } } }).png().toBuffer();
  await writeFile(join(PATHS.images, 'still.png'), sourceImage);
  if (canPrepareVideo) {
    const output = join(PATHS.videos, 'independent-name.mp4');
    const encoded = await runFfmpegProcess({ bin, timeoutMs: 10_000, args: [
      '-nostdin', '-y', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=blue:s=32x32:r=10:d=1',
      '-f', 'lavfi', '-i', 'anullsrc=r=44100:cl=mono', '-t', '1',
      '-c:v', 'libx264', '-c:a', 'aac', '-pix_fmt', 'yuv420p',
      '-bsf:v', 'h264_metadata=sei_user_data=0123456789abcdef0123456789abcdef+' + privateMarker,
      '-metadata', 'comment=' + privateMarker + sourcePath, output,
    ] });
    expect(encoded).toEqual({ ok: true });
    sourceVideo = await readFile(output);
    expect(sourceVideo.indexOf(privateMarker)).not.toBe(sourceVideo.lastIndexOf(privateMarker));
  }
});
beforeEach(async () => {
  await __testing.drain();
  vi.restoreAllMocks();
  loom = { id: 'example-loom', name: 'The quiet gate', logline: 'An unexpected journey.',
    participationMode: 'protagonist', audienceCommunicationMedium: 'Walkie-talkie', format: 'prose',
    universeId: 'example-universe', productionStatus: { deliveryApprovedAt: '2026-01-01T00:00:00.000Z' },
    episodes: [episode('episode-one'), episode('episode-two', 2)],
    sessionTranscripts: privateMarker, peerId: privateMarker, providerConfig: { apiKey: privateMarker } };
  getLoom.mockImplementation(async id => id === loom.id || id === 'another-loom' ? loom : null);
  getUniverse.mockResolvedValue({ characters: [{ id: 'example-character' }] });
  listVoiceProfiles.mockResolvedValue([]);
  await rm(PATHS.voiceProfiles, { recursive: true, force: true });
  loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({
    id, filename: 'independent-name.mp4', absolutePath: sourcePath, prompt: privateMarker, apiKey: privateMarker,
  })));
  jobIds.length = 0;
  await rm(join(PATHS.data, 'cache/fableloom-exports'), { recursive: true, force: true });
});
afterEach(async () => { await __testing.drain(); vi.restoreAllMocks(); exportBudget.maxPackageBytes = null; });
afterAll(async () => { await owned.drain(); await __testing.drain(); cleanupTempDataRoots(); });

describe('portable FableLoom export boundary', () => {
  videoIt('exports selected episodes deterministically, strips private data and embedded tags, and serves the ZIP', async () => {
    const started = await request(app()).post('/api/fableloom/example-loom/export').send({ episodeIds: ['episode-two'] });
    expect(started.status).toBe(202);
    jobIds.push(started.body.jobId);
    const first = await archive(started.body.jobId);
    const second = await archive(await begin({ episodeIds: ['episode-two'] }));
    expect(second.bytes.equals(first.bytes)).toBe(true);
    const manifest = JSON.parse(first.files.get('manifest.json'));
    expect(manifest).toMatchObject({ schemaVersion: '1.0.0', runtimeVersion: '1.0.0',
      loom: { name: 'The quiet gate', episodes: [{ id: 'episode-two' }] } });
    expect(manifest.loom.episodes).toHaveLength(1);
    const ordered = await archive(await begin({ episodeIds: ['episode-two', 'episode-one'] }));
    expect(JSON.parse(ordered.files.get('manifest.json')).loom.episodes.map(e => e.id)).toEqual(['episode-two', 'episode-one']);
    expect(manifest.characters).toBeUndefined();
    expect([...first.files.keys()].some(name => name.startsWith('characters/'))).toBe(false);
    const defaultProvenance = JSON.parse(first.files.get('provenance.json'));
    expect(defaultProvenance.characters).toBeUndefined();
    expect(defaultProvenance.voices).toBeUndefined();
    const defaultReadme = first.files.get('README.md').toString();
    expect(defaultReadme).toContain('does not grant PortOS access');
    expect(defaultReadme).toContain('Voice reference audio was not included');
    expect(defaultReadme).toContain('Your host owns free-text');
    expect(listVoiceProfiles).not.toHaveBeenCalled();
    const [start, end] = manifest.loom.episodes[0].nodes;
    expect(start.playbackAssets.holds[0]).toMatchObject({ loopable: true, durationMs: 1000,
      audioOccupancy: { safeForLiveVoice: true } });
    expect(start.playbackAssets.exits.choose).toMatchObject({ loopable: false, durationMs: 1000 });
    expect(end).toMatchObject({ isEnding: true, endingLabel: 'Home' });
    expect(first.files.has('runtime-v1.md')).toBe(true);
    const mediaFiles = [...first.files].filter(([name]) => name.startsWith('media/'));
    expect(mediaFiles).toHaveLength(2);
    for (const [name, bytes] of mediaFiles) expect(name).toContain(hash(bytes));
    for (const bytes of [first.bytes, ...first.files.values()]) {
      expect(bytes.includes(Buffer.from(privateMarker))).toBe(false);
      expect(bytes.includes(Buffer.from(sourcePath))).toBe(false);
    }
    expect(await readFile(join(PATHS.images, 'still.png'))).toEqual(sourceImage);
    expect(await readFile(join(PATHS.videos, 'independent-name.mp4'))).toEqual(sourceVideo);
    const status = await request(app()).get('/api/fableloom/example-loom/export/' + started.body.jobId);
    expect(status.body).toMatchObject({ status: 'completed', sizeReport: { mediaFiles: 2, archiveBytes: first.bytes.length } });
    const download = await request(app()).get(status.body.downloadUrl);
    expect(download.status).toBe(200);
    expect(download.headers['content-type']).toMatch(/zip/);
    expect(download.headers['content-disposition']).toMatch(/fableloom-[a-f0-9]{16}-v1.zip/);
    const wrongLoom = await request(app()).get('/api/fableloom/another-loom/export/' + started.body.jobId);
    expect(wrongLoom.status).toBe(404);
    await expect(getFableLoomExportDownload('another-loom', started.body.jobId)).rejects.toMatchObject({ status: 404 });
    const removed = await getFableLoomExportDownload(loom.id, started.body.jobId);
    try { await rm(removed.path); } finally { removed.release(); }
    const missingArtifact = await request(app()).get(status.body.downloadUrl);
    expect([missingArtifact.status, missingArtifact.body.code]).toEqual([409, 'EXPORT_ARTIFACT_INVALID']);
    expect(missingArtifact.text).not.toContain(removed.path);
  });

  videoIt('encodes bounded web media, normalizes audio, retains roles and reuses content/profile cache', async () => {
    const source = join(PATHS.videos, 'profile-fixture.mp4');
    expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: [
      '-nostdin', '-y', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=blue:s=1600x900:r=15:d=1',
      '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000:duration=1', '-af', 'volume=0.1',
      '-c:v', 'mpeg4', '-c:a', 'aac', '-threads', '1', source,
    ] })).toEqual({ ok: true });
    const original = await readFile(source);
    loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'profile-fixture.mp4' })));
    const encode = vi.spyOn(ffmpeg, 'runFfmpegProcess');
    const options = { episodeIds: ['episode-one'], mediaProfile: 'web-720p', includeWebm: true };
    const firstId = await begin(options);
    const first = await archive(firstId);
    const firstCount = encode.mock.calls.length;
    const repeat = await archive(await begin(options));
    expect(repeat.bytes).toEqual(first.bytes);
    expect(encode).toHaveBeenCalledTimes(firstCount);
    // Three distinct history IDs with identical source content encode only once.
    expect(encode.mock.calls.filter(([args]) => args.args.includes('libx264'))).toHaveLength(1);
    const manifest = JSON.parse(first.files.get('manifest.json'));
    const assets = manifest.loom.episodes[0].nodes[0].playbackAssets;
    expect(assets.holds[0]).toMatchObject({ loopable: true, audioOccupancy: { durationMs: 1000,
      effects: [{ startMs: 0, endMs: 500 }], safeForLiveVoice: true } });
    expect(assets.exits.choose.file).toBe(assets.entry.file);
    expect(first.files.has(assets.entry.poster.file)).toBe(true);
    expect(assets.entry.alternatives).toHaveLength(1);
    const inspect = (file) => JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-show_format', '-of', 'json', file], { timeout: 10_000 }).toString());
    const encodedFile = join(PATHS.videos, 'packaged.mp4');
    await writeFile(encodedFile, first.files.get(assets.entry.file));
    const measured = inspect(encodedFile);
    expect(measured.streams.find(s => s.codec_type === 'video')).toMatchObject({ codec_name: 'h264', pix_fmt: 'yuv420p', width: 1280, height: 720 });
    expect(measured.streams.find(s => s.codec_type === 'audio')).toMatchObject({ codec_name: 'aac', sample_rate: '48000' });
    expect(Number(measured.streams.find(s => s.codec_type === 'video').bit_rate)).toBeLessThanOrEqual(2_000_000);
    expect(Number(measured.streams.find(s => s.codec_type === 'audio').bit_rate)).toBeLessThanOrEqual(128_000);
    const analyzed = await runFfmpegProcess({ bin, timeoutMs: 10_000, returnStderr: true, stderrTailBytes: 8192,
      args: ['-nostdin', '-i', encodedFile, '-vn', '-af', 'loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json', '-f', 'null', '-'] });
    expect(analyzed.ok).toBe(true);
    const level = JSON.parse(analyzed.stderr.slice(analyzed.stderr.lastIndexOf('{'), analyzed.stderr.lastIndexOf('}') + 1));
    expect(Math.abs(Number(level.input_i) + 16)).toBeLessThan(1);
    expect(Number(level.input_tp)).toBeLessThanOrEqual(-1.4);
    const webm = join(PATHS.videos, 'packaged.webm');
    await writeFile(webm, first.files.get(assets.entry.alternatives[0].file));
    expect(inspect(webm).streams.map(s => s.codec_name)).toEqual(['vp9', 'opus']);
    const provenance = JSON.parse(first.files.get('provenance.json'));
    expect(provenance.assets.find(a => a.role === 'entry')).toMatchObject({ bytes: first.files.get(assets.entry.file).length,
      encoding: { sourceSha256: hash(original), profile: { id: 'web-720p', videoKbps: 2000, includeWebm: true },
        encoder: { ffmpeg: expect.any(String), buildHash: expect.stringMatching(/^[a-f0-9]{64}$/) } } });
    const mediaFiles = [...first.files].filter(([name]) => name.startsWith('media/'));
    for (const [name, bytes] of mediaFiles) expect(name).toContain(hash(bytes));
    expect((await terminal(firstId)).sizeReport.mediaBytes).toBe(mediaFiles.reduce((n, [, bytes]) => n + bytes.length, 0));
    const changed = await archive(await begin({ ...options, mediaProfile: 'web-1080p', includeWebm: false }));
    const changedAssets = JSON.parse(changed.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;
    expect(changedAssets.entry.file).not.toBe(assets.entry.file);
    expect(changedAssets.entry).not.toHaveProperty('alternatives');
    expect(encode.mock.calls.filter(([args]) => args.args.includes('libx264'))).toHaveLength(2);
    expect(await readFile(source)).toEqual(original);
  });

  videoIt('preserves silent soundtracks and clips without audio in web profiles', async () => {
    const outcomes = [];
    const realRun = ffmpeg.runFfmpegProcess;
    vi.spyOn(ffmpeg, 'runFfmpegProcess').mockImplementation(async options => {
      const result = await realRun(options);
      outcomes.push({ ok: result.ok, reason: result.reason });
      return result;
    });
    const silentId = await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' });
    expect((await terminal(silentId)).status, JSON.stringify(outcomes)).toBe('completed');
    const silent = await archive(silentId);
    const silentAssets = JSON.parse(silent.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;
    const output = join(PATHS.videos, 'without-audio.mp4');
    expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: ['-nostdin', '-y', '-v', 'error',
      '-i', join(PATHS.videos, 'independent-name.mp4'), '-an', '-c:v', 'copy', output] })).toEqual({ ok: true });
    loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'without-audio.mp4' })));
    const noAudio = await archive(await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' }));
    const noAudioAssets = JSON.parse(noAudio.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;
    expect(noAudioAssets.entry.file).not.toBe(silentAssets.entry.file);
    await writeFile(output, noAudio.files.get(noAudioAssets.entry.file));
    const streams = JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-of', 'json', output], { timeout: 10_000 }).toString()).streams;
    expect(streams.map(stream => stream.codec_type)).toEqual(['video']);
    expect(noAudioAssets.holds[0].audioOccupancy).toEqual(silentAssets.holds[0].audioOccupancy);
  });

  videoIt('normalizes short non-silent audio without padding its duration', async () => {
    const source = join(PATHS.videos, 'short-sfx.mp4');
    expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: [
      '-nostdin', '-y', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=blue:s=32x32:r=10:d=1',
      '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000:duration=0.2', '-af', 'volume=0.1',
      '-c:v', 'libx264', '-c:a', 'aac', '-threads', '1', source,
    ] })).toEqual({ ok: true });
    loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'short-sfx.mp4' })));
    const result = await archive(await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' }));
    const assets = JSON.parse(result.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;
    expect(assets.entry.durationMs).toBe(1000);
    const output = join(PATHS.videos, 'short-normalized.mp4');
    await writeFile(output, result.files.get(assets.entry.file));
    const streams = JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-of', 'json', output], { timeout: 10_000 }).toString()).streams;
    const audio = streams.find(stream => stream.codec_type === 'audio');
    expect(Number(audio.duration)).toBeGreaterThanOrEqual(0.2);
    expect(Number(audio.duration)).toBeLessThan(0.25);
    const analyzed = await runFfmpegProcess({ bin, timeoutMs: 10_000, returnStderr: true, stderrTailBytes: 8192,
      args: ['-nostdin', '-i', output, '-vn', '-af', 'loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json', '-f', 'null', '-'] });
    expect(analyzed.ok).toBe(true);
    const level = JSON.parse(analyzed.stderr.slice(analyzed.stderr.lastIndexOf('{'), analyzed.stderr.lastIndexOf('}') + 1));
    expect(Number(level.input_tp)).toBeGreaterThan(-3);
    expect(Number(level.input_tp)).toBeLessThan(0);
  });

  videoIt('measures retained streams when discarded subtitle tracks outlast picture and audio', async () => {
    const subtitle = join(PATHS.videos, 'extended.srt');
    await writeFile(subtitle, '1\n00:00:00,000 --> 00:00:03,000\nExample subtitle\n');
    const source = join(PATHS.videos, 'extended-subtitle.mp4');
    expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: ['-nostdin', '-y', '-v', 'error',
      '-i', join(PATHS.videos, 'independent-name.mp4'), '-i', subtitle, '-map', '0', '-map', '1:0',
      '-c', 'copy', '-c:s', 'mov_text', source] })).toEqual({ ok: true });
    const measured = JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-of', 'json', source], { timeout: 10_000 }).toString());
    expect(Number(measured.streams.find(stream => stream.codec_type === 'subtitle').duration)).toBe(3);
    loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'extended-subtitle.mp4' })));
    for (const mediaProfile of ['source', 'web-720p']) {
      const result = await archive(await begin({ episodeIds: ['episode-one'], mediaProfile }));
      const assets = JSON.parse(result.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets;
      expect(assets.entry.durationMs).toBe(1000);
      expect(assets.holds[0].audioOccupancy.durationMs).toBe(1000);
      const output = join(PATHS.videos, 'retained.mp4');
      await writeFile(output, result.files.get(assets.entry.file));
      const streams = JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-of', 'json', output], { timeout: 10_000 }).toString()).streams;
      expect(streams.map(stream => stream.codec_type)).toEqual(['video', 'audio']);
    }
  });

  videoIt('normalizes a common positive timestamp origin while retaining the audio delay', async () => {
    const source = join(PATHS.videos, 'offset-timeline.mp4');
    expect(await runFfmpegProcess({ bin, timeoutMs: 10_000, args: [
      '-nostdin', '-y', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=blue:s=32x32:r=10:d=1',
      '-itsoffset', '0.3', '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000:duration=0.4',
      '-t', '1', '-c:v', 'libx264', '-c:a', 'aac', '-threads', '1', '-output_ts_offset', '5', source,
    ] })).toEqual({ ok: true });
    const inspect = file => JSON.parse(execFileSync(probe, ['-v', 'error', '-show_streams', '-of', 'json', file], { timeout: 10_000 }).toString()).streams;
    const original = inspect(source);
    const originalDelay = Number(original.find(stream => stream.codec_type === 'audio').start_time)
      - Number(original.find(stream => stream.codec_type === 'video').start_time);
    expect(originalDelay).toBeGreaterThan(0.25);
    const audibleStart = file => {
      const pcm = execFileSync(bin, ['-nostdin', '-v', 'error', '-i', file, '-map', '0:a',
        '-af', 'aresample=async=1:first_pts=0', '-ar', '48000', '-ac', '1', '-f', 'f32le', '-'],
      { timeout: 10_000, maxBuffer: 1024 * 1024 });
      for (let offset = 0; offset < pcm.length; offset += 4) {
        if (Math.abs(pcm.readFloatLE(offset)) > 0.005) return offset / 4 / 48000;
      }
      throw new Error('Expected the authored delayed tone.');
    };
    const originalStart = audibleStart(source);
    loadHistory.mockResolvedValue(['entry-record', 'hold-record', 'exit-record'].map(id => ({ id, filename: 'offset-timeline.mp4' })));
    for (const mediaProfile of ['source', 'web-720p']) {
      const result = await archive(await begin({ episodeIds: ['episode-one'], mediaProfile }));
      const asset = JSON.parse(result.files.get('manifest.json')).loom.episodes[0].nodes[0].playbackAssets.entry;
      expect(asset.durationMs).toBe(1000);
      const output = join(PATHS.videos, 'normalized-timeline.mp4');
      await writeFile(output, result.files.get(asset.file));
      const streams = inspect(output);
      const picture = streams.find(stream => stream.codec_type === 'video');
      const audio = streams.find(stream => stream.codec_type === 'audio');
      expect(Number(picture.duration)).toBe(1);
      expect(Number(audio.duration)).toBeGreaterThanOrEqual(0.4);
      // AAC priming changes packet start timestamps; compare the audible
      // timeline with allowance for the loudness filter's short look-ahead.
      expect(Math.abs(audibleStart(output) - originalStart)).toBeLessThan(0.01);
    }
  });

  videoIt('drains cancelled and failed encoder children before exposing terminal failure without an artifact', async () => {
    const realRun = ffmpeg.runFfmpegProcess;
    const started = Promise.withResolvers();
    let drained = false;
    vi.spyOn(ffmpeg, 'runFfmpegProcess').mockImplementation(async options => {
      const pending = realRun({ ...options, args: ['-nostdin', '-v', 'error', '-f', 'lavfi', '-i',
        'color=c=blue:s=32x32:r=10', '-f', 'null', '-'] });
      started.resolve();
      const result = await pending;
      drained = true;
      return result;
    });
    const id = await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' });
    await started.promise;
    const cancelled = await request(app()).delete(`/api/fableloom/example-loom/export/${id}`);
    expect(cancelled.status).toBe(200);
    expect(cancelled.body).toMatchObject({ status: 'failed', error: { code: 'EXPORT_CANCELLED' } });
    expect(drained).toBe(true);
    expect(cancelled.body).not.toHaveProperty('downloadUrl');
    await expect(stat(join(PATHS.data, 'cache/fableloom-exports', id, 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });
    await expect(stat(join(PATHS.data, 'cache/fableloom-exports', id, 'work'))).rejects.toMatchObject({ code: 'ENOENT' });
    vi.spyOn(ffmpeg, 'runFfmpegProcess').mockImplementation(options => realRun({ ...options,
      args: ['-nostdin', '-v', 'error', '-f', 'lavfi', '-i', 'color=s=32x32:d=0.1', '-c:v', 'not-an-encoder', '-f', 'null', '-'] }));
    const failedId = await begin({ episodeIds: ['episode-one'], mediaProfile: 'web-720p' });
    expect(await terminal(failedId)).toMatchObject({ status: 'failed', error: { code: 'EXPORT_TRANSCODE_FAILED' } });
    await expect(getFableLoomExportDownload(loom.id, failedId)).rejects.toMatchObject({ code: 'EXPORT_NOT_READY' });
    await expect(stat(join(PATHS.data, 'cache/fableloom-exports', failedId, 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });
  });

  videoIt('refuses unapproved media by default and records draft flags only after explicit opt-in', async () => {
    const node = loom.episodes[0].nodes[0];
    node.visualCanon.storyboardImageApproved = false;
    node.playbackAssets.visualConditioningByAsset['asset-' + node.id + '-still'] = node.visualConditioning;
    node.visualConditioning = conditioning('video');
    node.visualConditioning.render.provider = 'example-video-provider';
    const refused = await terminal(await begin());
    expect(refused).toMatchObject({ status: 'failed', error: { code: 'EXPORT_VALIDATION_FAILED' } });
    expect(refused.findings).toContainEqual(expect.objectContaining({ gate: 'approval', severity: 'error' }));
    expect(refused).not.toHaveProperty('downloadUrl');
    const draft = await archive(await begin({ allowDraft: true }));
    const provenance = JSON.parse(draft.files.get('provenance.json'));
    expect(provenance.assets).toContainEqual(expect.objectContaining({
      role: 'still', approved: false, draftFlags: ['unapproved'], parametersHash: expect.stringMatching(/^[a-f0-9]{64}$/),
    }));
    expect(provenance.assets.every(a => a.provider === 'example-provider')).toBe(true);
  });

  it('keeps structural and required-media failures blocking under allowDraft', async () => {
    loom.episodes[0].nodes[0].transitions[0].targetNodeId = 'missing-node';
    const graph = await terminal(await begin({ allowDraft: true }));
    expect(graph).toMatchObject({ status: 'failed', error: { code: 'EXPORT_VALIDATION_FAILED' } });
    expect(graph.findings).toContainEqual(expect.objectContaining({ gate: 'graph', code: 'DANGLING_TRANSITION' }));
    loom.episodes = [episode('episode-one')];
    loom.episodes[0].nodes[0].image = null;
    const missing = await terminal(await begin({ allowDraft: true }));
    expect(missing.findings).toContainEqual(expect.objectContaining({ gate: 'media', code: 'EXPORT_MEDIA_MISSING', severity: 'error' }));
    await expect(getFableLoomExportDownload(loom.id, jobIds.at(-1))).rejects.toMatchObject({ code: 'EXPORT_NOT_READY' });
  });

  videoIt('uses an immutable record snapshot and refuses unsafe or missing live occupancy', async () => {
    const id = await begin({ episodeIds: ['episode-one'] });
    loom.name = 'Changed after admission';
    const output = await archive(id);
    expect(JSON.parse(output.files.get('manifest.json')).loom.name).toBe('The quiet gate');
    delete loom.episodes[0].nodes[0].playbackAssets.audioOccupancy['hold-record'];
    const unsafe = await terminal(await begin({ episodeIds: ['episode-one'], allowDraft: true }));
    expect(unsafe).toMatchObject({ status: 'failed', error: { code: 'EXPORT_OCCUPANCY_UNSAFE' } });
  });

  it('refuses unsupported and malformed options before creating jobs', async () => {
    for (const input of [
      { mediaProfile: 'webm' }, { includeWebm: true }, { includeWebm: 'yes' }, { mediaProfile: { width: 100 } }, { allowDraft: 'yes' },
      { episodeIds: [] }, { episodeIds: ['episode-one', 'episode-one'] }, { destination: sourcePath }]) {
      const response = await request(app()).post('/api/fableloom/example-loom/export').send(input);
      expect(response.status, JSON.stringify(input)).toBe(400);
    }
    const voiceOnly = await request(app()).post('/api/fableloom/example-loom/export').send({ includeVoice: true });
    expect(voiceOnly.status).toBe(400);
    expect(voiceOnly.body.code).toBe('EXPORT_VOICE_REQUIRES_CHARACTERS');
    expect(listVoiceProfiles).not.toHaveBeenCalled();
    await expect(startFableLoomExport(loom.id, { episodeIds: ['unknown-episode'] })).rejects.toMatchObject({ code: 'EXPORT_EPISODES_INVALID' });
  });

  videoIt('adds the reference player only when requested and keeps that directory free of private data', async () => {
    const plain = await archive(await begin({ episodeIds: ['episode-one'] }));
    expect([...plain.files.keys()].some((name) => name.startsWith('player/'))).toBe(false);
    expect(plain.files.get('README.md').toString('utf8')).toContain('does not include the reference player');
    const first = await archive(await begin({ episodeIds: ['episode-one'], includePlayer: true }));
    const second = await archive(await begin({ episodeIds: ['episode-one'], includePlayer: true }));
    expect(second.bytes.equals(first.bytes)).toBe(true);
    for (const name of FABLELOOM_STATIC_PLAYER_FILES) expect(first.files.has(`player/${name}`)).toBe(true);
    const playerText = [...first.files].filter(([name]) => name.startsWith('player/'))
      .map(([, bytes]) => bytes.toString('utf8')).join('\n');
    expect(playerText).not.toMatch(/https?:\/\//i);
    expect(playerText.toLowerCase().replaceAll('portos-allow-hidden-content', '')).not.toContain('portos');
    expect(playerText).not.toContain(privateMarker);
    expect(playerText.toLowerCase()).not.toContain('bearer');
    expect(first.files.get('player/index.html').toString('utf8')).not.toContain('contract-example');
    expect(first.files.get('README.md').toString('utf8')).toContain('player/index.html is a dependency-free');
    for (const bytes of first.files.values()) {
      expect(bytes.includes(Buffer.from(privateMarker))).toBe(false);
      expect(bytes.includes(Buffer.from(sourcePath))).toBe(false);
    }
  });

  it('limits the cast to the protagonist and reachable staged characters', () => {
    const episodes = [{
      startNodeId: 'a',
      nodes: [
        { id: 'a', visualCanon: { characterAppearances: [{ characterId: 'hero' }, { characterId: 'on-stage' }] },
          interactionWindow: { protagonistCharacterId: 'speaker' },
          transitions: [{ targetNodeId: 'b' }] },
        { id: 'b', transitions: [] },
        { id: 'orphan', visualCanon: { characterAppearances: [{ characterId: 'secret-extra' }] }, transitions: [] },
      ],
    }];
    const loomCast = { protagonistCharacterId: 'hero', format: 'prose' };
    const universe = { characters: [
      { id: 'hero', name: 'Ada Example', personality: 'Calm.', background: privateMarker,
        secrets: 'SECRET_TOKEN_SENTINEL', voiceId: 'kokoro:SECRET_PRESET',
        adapters: [sourcePath], sessions: ['SESSION_TRANSCRIPT_SENTINEL'],
        voiceCanon: { version: 2, approved: true, sourcePolicy: 'designed', description: 'Warm.',
          defaultDelivery: 'Measured.', emotionalRange: ['steady'], avoid: ['never shout'],
          pronunciations: [{ term: 'Fable', pronunciation: 'FAY-bul', recordingPath: sourcePath }],
          recordingPath: sourcePath } },
      { id: 'on-stage', name: 'Draft', voiceCanon: { approved: false, description: 'rough' } },
      { id: 'speaker', name: 'Speaker' },
      { id: 'secret-extra', name: 'SECRET_CAST_SENTINEL', personality: privateMarker },
    ]};
    const blocked = inspectFableLoomExportCharacters(loomCast, episodes, universe);
    expect(blocked.characters.map(character => character.id)).toEqual(['hero', 'on-stage', 'speaker']);
    expect(blocked.findings.map(finding => finding.characterId)).toEqual(['on-stage', 'speaker']);
    expect(blocked.findings.every(finding => finding.severity === 'error' && finding.code === 'EXPORT_CHARACTER_DRAFT')).toBe(true);
    const hero = blocked.characters.find(character => character.id === 'hero');
    expect(hero.approval).toEqual({ voiceCanonVersion: 2, approved: true, sourcePolicy: 'designed', draftFlags: [] });
    expect(hero.pronunciations).toEqual([{ term: 'Fable', pronunciation: 'FAY-bul' }]);
    expect(hero.playTurn).toMatchObject({ promptId: 'fableloom-play-turn', contractVersion: '1.0.0' });
    expect(hero.role).toBe('protagonist');
    const drafted = inspectFableLoomExportCharacters(loomCast, episodes, universe, { allowDraft: true });
    expect(drafted.findings.every(finding => finding.severity === 'warning')).toBe(true);
    expect(drafted.characters.find(character => character.id === 'on-stage').approval.draftFlags).toEqual(['unapproved']);
    expect(drafted.characters.find(character => character.id === 'speaker').approval.draftFlags).toEqual(['unknown']);
    const packed = JSON.stringify(drafted.characters);
    for (const marker of [privateMarker, sourcePath, 'SECRET_TOKEN_SENTINEL', 'SESSION_TRANSCRIPT_SENTINEL', 'SECRET_CAST_SENTINEL', 'kokoro:', 'recordingPath']) {
      expect(packed.includes(marker), marker).toBe(false);
    }
  });

  it('fails closed when character approval, membership or identifiers are not portable', async () => {
    const unapproved = await terminal(await begin({ episodeIds: ['episode-one'], includeCharacters: true }));
    expect(unapproved).toMatchObject({ status: 'failed', error: { code: 'EXPORT_VALIDATION_FAILED' } });
    expect(unapproved.findings).toContainEqual(expect.objectContaining({
      code: 'EXPORT_CHARACTER_DRAFT', severity: 'error', characterId: 'example-character',
    }));
    expect(listVoiceProfiles).not.toHaveBeenCalled();
    getUniverse.mockResolvedValue({ characters: [] });
    const missing = await terminal(await begin({ episodeIds: ['episode-one'], includeCharacters: true }));
    expect(missing.findings).toContainEqual(expect.objectContaining({ code: 'EXPORT_CHARACTER_MISSING', severity: 'error' }));
    loom.episodes = [episode('episode-one')];
    loom.episodes[0].nodes[0].interactionWindow.protagonistCharacterId = 'not/portable';
    const badId = await terminal(await begin({ episodeIds: ['episode-one'], includeCharacters: true }));
    const idFinding = badId.findings.find(finding => finding.code === 'EXPORT_CHARACTER_ID');
    expect(idFinding).toMatchObject({ severity: 'error', message: 'Character identifiers must be portable identifiers.' });
    expect(idFinding).not.toHaveProperty('characterId');
    expect(badId).not.toHaveProperty('downloadUrl');
    await expect(stat(join(PATHS.data, 'cache/fableloom-exports', jobIds.at(-1), 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });
    loom.episodes = [episode('episode-one')];
    loom.episodes[0].nodes[0].interactionWindow.protagonistCharacterId = '';
    const empty = await terminal(await begin({ episodeIds: ['episode-one'], includeCharacters: true }));
    expect(empty.findings).toContainEqual(expect.objectContaining({ code: 'EXPORT_CAST_MISSING', severity: 'error' }));
    await expect(getFableLoomExportDownload(loom.id, jobIds.at(-1))).rejects.toMatchObject({ code: 'EXPORT_NOT_READY' });
  });

  it('refuses unapproved, ambiguous, unconsented and unlabeled voice references even when drafts are allowed', async () => {
    useCast();
    const digest = 'ab'.repeat(32);
    await expectVoiceRefusal([], 'EXPORT_VOICE_UNAPPROVED', { includeCharacters: true, includeVoice: true, allowDraft: true });
    await expectVoiceRefusal([
      voiceProfile({ sha256: digest, id: 'example-voice' }),
      voiceProfile({ sha256: 'cd'.repeat(32), id: 'example-voice-two' }),
    ], 'EXPORT_VOICE_AMBIGUOUS');
    await expectVoiceRefusal([voiceProfile({
      sha256: digest, kind: 'cloned',
      sourceAssets: [{ filename: 'reference.wav', sha256: digest, performerConsentConfirmed: false,
        licensePosture: 'generated-original-voice', transcript: 'SESSION_TRANSCRIPT_SENTINEL', path: sourcePath }],
    })], 'EXPORT_VOICE_CONSENT_MISSING');
    await expectVoiceRefusal([voiceProfile({
      sha256: digest,
      sourceAssets: [{ filename: 'notes.txt', sha256: digest, transcript: 'SESSION_TRANSCRIPT_SENTINEL' }],
    })], 'EXPORT_VOICE_REFERENCE_MISSING');
    const invalidProfile = await expectVoiceRefusal([voiceProfile({
      sha256: digest, id: 'Not A Profile',
    })], 'EXPORT_VOICE_REFERENCE_INVALID');
    expect(JSON.stringify(invalidProfile)).not.toContain('Not A Profile');
    const wrongUniverse = voiceProfile({ sha256: digest });
    wrongUniverse.binding.universeId = 'other-universe';
    await expectVoiceRefusal([wrongUniverse], 'EXPORT_VOICE_UNAPPROVED');
  });

  it('keeps a voice-profile read failure path-free', async () => {
    useCast();
    const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
    listVoiceProfiles.mockRejectedValue(Object.assign(
      new Error('password at /example-private/voice.db'), { code: 'ECONNREFUSED' },
    ));
    const result = await terminal(await begin({
      episodeIds: ['episode-one'], includeCharacters: true, includeVoice: true,
    }));
    expect(result.findings).toContainEqual(expect.objectContaining({
      code: 'EXPORT_VOICE_UNAVAILABLE', severity: 'error',
    }));
    expect(result).not.toHaveProperty('downloadUrl');
    const visible = `${JSON.stringify(result)}\n${errorLog.mock.calls.flat().join('\n')}`;
    expect(visible).not.toContain('/example-private/voice.db');
    expect(visible).not.toContain('ECONNREFUSED');
    expect(visible).not.toContain('password');
    await expect(stat(join(PATHS.data, 'cache/fableloom-exports', jobIds.at(-1), 'package.zip'))).rejects.toMatchObject({ code: 'ENOENT' });
  });

  it('keeps a voice-reference hash mismatch and an escaping symlink out of the package', async () => {
    useCast();
    const bytes = Buffer.from('approved-reference-audio');
    const recorded = await writeVoiceReference(bytes);
    await expectVoiceRefusal([voiceProfile({ sha256: 'aa'.repeat(32) })], 'EXPORT_VOICE_REFERENCE_MISMATCH');
    expect(JSON.stringify(await getFableLoomExport(loom.id, jobIds.at(-1)))).not.toContain(recorded);
    await rm(PATHS.voiceProfiles, { recursive: true, force: true });
    const outsideDir = join(PATHS.data, 'outside-voice');
    await mkdir(outsideDir, { recursive: true });
    await writeFile(join(outsideDir, 'reference.wav'), bytes);
    await mkdir(join(PATHS.voiceProfiles, 'example-voice'), { recursive: true });
    await symlink(outsideDir, join(PATHS.voiceProfiles, 'example-voice', 'source'));
    const escaped = await expectVoiceRefusal([voiceProfile({ sha256: hash(bytes) })], 'EXPORT_VOICE_REFERENCE_INVALID');
    expect(JSON.stringify(escaped)).not.toContain('outside-voice');
    expect(JSON.stringify(escaped)).not.toContain('reference.wav');
  });

  videoIt('exports approved character inputs without voice bytes', async () => {
    useCast();
    const packed = await archive(await begin({ episodeIds: ['episode-one'], includeCharacters: true }));
    const character = JSON.parse(packed.files.get('characters/example-character.json'));
    expect(character).toMatchObject({
      schemaVersion: '1.0.0', id: 'example-character', name: 'Ada Example', role: 'protagonist',
      persona: { personality: 'Calm and precise.', speechAccent: 'Neutral example accent.',
        speechPattern: 'Short sentences.', mannerisms: 'Pauses before answers.' },
      speech: { description: 'Warm mid register.', defaultDelivery: 'Measured.', emotionalRange: ['steady'] },
      pronunciations: [{ term: 'Fable', pronunciation: 'FAY-bul' }],
      safety: { neverSay: ['never shout'] },
      playTurn: { promptId: 'fableloom-play-turn', contractVersion: '1.0.0', inputs: { characterId: 'example-character', role: 'protagonist' } },
      approval: { voiceCanonVersion: 2, approved: true, sourcePolicy: 'designed', draftFlags: [] },
    });
    expect(Object.keys(character.pronunciations[0]).sort()).toEqual(['pronunciation', 'term']);
    const manifest = JSON.parse(packed.files.get('manifest.json'));
    expect(manifest.characters).toEqual([{ id: 'example-character', role: 'protagonist', file: 'characters/example-character.json' }]);
    const provenance = JSON.parse(packed.files.get('provenance.json'));
    expect(provenance.characters).toEqual([{
      id: 'example-character', file: 'characters/example-character.json',
      approved: true, draftFlags: [], voiceCanonVersion: 2,
    }]);
    expect(provenance.voices).toBeUndefined();
    expect([...packed.files.keys()].filter(name => name.startsWith('media/'))).toHaveLength(2);
    expect([...packed.files.keys()].some(name => name.endsWith('.wav'))).toBe(false);
    const readme = packed.files.get('README.md').toString();
    expect(readme).toContain('characters/<id>.json');
    expect(readme).toContain('Voice reference audio was not included');
    expect(readme).toContain('does not grant PortOS access');
    expect(readme).toContain('Your host owns free-text');
    assertPackageClean(packed);
    expect(listVoiceProfiles).not.toHaveBeenCalled();
  });

  it('refuses an oversized voice package before reading its remaining references', async () => {
    useCast();
    const assets = [];
    for (let index = 0; index < 4; index++) {
      const filename = `reference-${index}.wav`;
      const sha256 = await writeVoiceReference(Buffer.from(`voice-reference-${index}`), filename);
      assets.push({ filename, sha256, licensePosture: 'generated-original-voice' });
    }
    listVoiceProfiles.mockResolvedValue([voiceProfile({ sourceAssets: assets })]);
    // A small budget exercises the same public worker boundary without large allocations.
    exportBudget.maxPackageBytes = 25;
    const readReference = vi.spyOn(voiceReferences, 'readFableLoomVoiceReference');
    const result = await terminal(await begin({
      episodeIds: ['episode-one'], includeCharacters: true, includeVoice: true,
    }));
    expect(result).toMatchObject({ status: 'failed', error: { code: 'EXPORT_PACKAGE_SIZE' } });
    expect(readReference).toHaveBeenCalledTimes(2);
    expect(result).not.toHaveProperty('downloadUrl');
    await expect(stat(join(PATHS.data, 'cache/fableloom-exports', jobIds.at(-1), 'package.zip')))
      .rejects.toMatchObject({ code: 'ENOENT' });
  });

  videoIt('deduplicates approved voice bytes across the cast within the package budget', async () => {
    useCast([approvedCharacter(), approvedCharacter({ id: 'example-support' })]);
    loom.episodes[0].nodes[0].visualCanon.characterAppearances = [{ characterId: 'example-support' }];
    const bytes = Buffer.alloc(32 * 1024, 7);
    const digest = await writeVoiceReference(bytes);
    const supportRoot = join(PATHS.voiceProfiles, 'support-voice', 'source');
    await mkdir(supportRoot, { recursive: true });
    await writeFile(join(supportRoot, 'reference.wav'), bytes);
    const protagonist = voiceProfile({ sha256: digest });
    const support = { ...voiceProfile({ sha256: digest, id: 'support-voice' }),
      binding: { universeId: 'example-universe', characterId: 'example-support' } };
    listVoiceProfiles.mockImplementation(async ({ characterId }) => [protagonist, support]
      .filter(profile => profile.binding.characterId === characterId));
    const options = { episodeIds: ['episode-one'], includeCharacters: true, includeVoice: true };
    const firstId = await begin(options);
    const first = await archive(firstId);
    const { sizeReport } = await getFableLoomExport(loom.id, firstId);
    // Enough for the actual package, but not another copy of the shared reference.
    exportBudget.maxPackageBytes = sizeReport.archiveBytes + 1;
    expect(exportBudget.maxPackageBytes).toBeLessThan(bytes.length * 2);
    const repeated = await archive(await begin(options));
    expect(repeated.bytes.equals(first.bytes)).toBe(true);
    expect([...repeated.files.keys()].filter(name => name.endsWith('.wav'))).toEqual([`media/${digest}.wav`]);
    expect(JSON.parse(repeated.files.get('provenance.json')).voices).toEqual([
      expect.objectContaining({ characterId: 'example-character', file: `media/${digest}.wav` }),
      expect.objectContaining({ characterId: 'example-support', file: `media/${digest}.wav` }),
    ]);
  });

  videoIt('exports approved voice references with provenance and stable hashes', async () => {
    useCast();
    const bytes = Buffer.from('approved-reference-audio');
    const digest = await writeVoiceReference(bytes);
    listVoiceProfiles.mockResolvedValue([voiceProfile({ sha256: digest })]);
    const options = { episodeIds: ['episode-one'], includeCharacters: true, includeVoice: true };
    const first = await archive(await begin(options));
    const second = await archive(await begin(options));
    expect(second.bytes.equals(first.bytes)).toBe(true);
    const provenance = JSON.parse(first.files.get('provenance.json'));
    expect(provenance.voices).toEqual([{
      characterId: 'example-character', file: `media/${digest}.wav`, sha256: digest, bytes: bytes.length,
      approved: true, draftFlags: [], consentConfirmed: false,
      licensePosture: 'generated-original-voice', sourcePolicy: 'designed',
    }]);
    expect(first.files.get(`media/${digest}.wav`).equals(bytes)).toBe(true);
    expect(hash(first.files.get(`media/${digest}.wav`))).toBe(digest);
    const readme = first.files.get('README.md').toString();
    expect(readme).toContain('your own TTS');
    expect(readme).toContain('does not grant PortOS access');
    expect(readme).toContain('no PortOS URL, credential, or callback');
    assertPackageClean(first);
    useCast([approvedCharacter({ voiceCanon: { approved: false, description: 'rough' } })]);
    const drafted = await archive(await begin({ episodeIds: ['episode-one'], includeCharacters: true, allowDraft: true }));
    const draftCharacter = JSON.parse(drafted.files.get('characters/example-character.json'));
    expect(draftCharacter.approval).toMatchObject({ approved: false, draftFlags: ['unapproved'] });
    expect(JSON.parse(drafted.files.get('provenance.json')).voices).toBeUndefined();
    expect([...drafted.files.keys()].some(name => name.endsWith('.wav'))).toBe(false);
    assertPackageClean(drafted);
    listVoiceProfiles.mockResolvedValue([]);
    const voiceDraft = await terminal(await begin({
      episodeIds: ['episode-one'], includeCharacters: true, includeVoice: true, allowDraft: true,
    }));
    expect(voiceDraft).toMatchObject({ status: 'failed', error: { code: 'EXPORT_VALIDATION_FAILED' } });
    expect(voiceDraft.findings).toContainEqual(expect.objectContaining({ code: 'EXPORT_VOICE_UNAPPROVED', severity: 'error' }));
    expect(voiceDraft.findings).toContainEqual(expect.objectContaining({ code: 'EXPORT_CHARACTER_DRAFT', severity: 'warning' }));
  });

  it('never follows a remote, traversing or escaping symlink source and keeps failures path-free', async () => {
    for (const bad of ['https://example.com/movie.mp4', '../private.mp4', sourcePath + '.mp4']) {
      loadHistory.mockResolvedValue([{ id: 'entry-record', filename: bad }]);
      const result = await terminal(await begin({ episodeIds: ['episode-one'] }));
      expect(result).toMatchObject({ status: 'failed', error: { code: 'EXPORT_MEDIA_PATH' } });
      expect(JSON.stringify(result)).not.toContain(bad);
    }
    const outside = join(PATHS.data, 'outside.png');
    await writeFile(outside, sourceImage);
    await symlink(outside, join(PATHS.images, 'escape.png'));
    loom.episodes[0].nodes[0].image = 'escape.png';
    const result = await terminal(await begin({ episodeIds: ['episode-one'], allowDraft: true }));
    expect(result).toMatchObject({ status: 'failed', error: { code: 'EXPORT_MEDIA_PATH' } });
    await rm(join(PATHS.images, 'escape.png'));
  });

  it('retains the terminal path refusal when a persisted status read crosses worker release', async () => {
    const sourceEntered = Promise.withResolvers();
    const releaseSource = Promise.withResolvers();
    const snapshotRead = Promise.withResolvers();
    const releaseRead = Promise.withResolvers();
    const readSource = media.readFableLoomExportSource;
    vi.spyOn(media, 'readFableLoomExportSource').mockImplementation(async (...args) => {
      sourceEntered.resolve();
      await releaseSource.promise;
      return readSource(...args);
    });
    const bad = 'https://example.com/movie.mp4';
    loadHistory.mockResolvedValue([{ id: 'entry-record', filename: bad }]);
    let pendingRead;
    try {
      const id = await begin({ episodeIds: ['episode-one'] });
      await sourceEntered.promise;
      const readJSONFile = jsonIo.readJSONFile;
      vi.spyOn(jsonIo, 'readJSONFile').mockImplementationOnce(async (...args) => {
        const snapshot = await readJSONFile(...args);
        snapshotRead.resolve(snapshot);
        await releaseRead.promise;
        return snapshot;
      });
      pendingRead = getFableLoomExport(loom.id, id);
      expect(await snapshotRead.promise).toMatchObject({ jobId: id, status: 'packing' });
      releaseSource.resolve();
      await __testing.drain();
      const terminalRecord = JSON.parse(await readFile(recordFile(id), 'utf8'));
      expect(terminalRecord).toMatchObject({ status: 'failed', error: { code: 'EXPORT_MEDIA_PATH' } });
      releaseRead.resolve();
      const result = await pendingRead;
      expect(result).toMatchObject({
        status: 'failed', revision: terminalRecord.revision, error: { code: 'EXPORT_MEDIA_PATH' },
      });
      expect(JSON.stringify(result)).not.toContain(bad);
      expect(JSON.parse(await readFile(recordFile(id), 'utf8'))).toEqual(terminalRecord);
    } finally {
      releaseSource.resolve();
      releaseRead.resolve();
      await pendingRead;
    }
  });

  it('persists actionable interruption and expiry states without treating malformed state as missing', async () => {
    loom.episodes[0].nodes[0].image = null;
    const id = await begin();
    await terminal(id);
    await __testing.drain();
    const stored = JSON.parse(await readFile(recordFile(id), 'utf8'));
    stored.status = 'packing';
    await writeFile(recordFile(id), JSON.stringify(stored));
    await expect(getFableLoomExport('another-loom', id)).rejects.toMatchObject({ status: 404 });
    expect(JSON.parse(await readFile(recordFile(id), 'utf8')).status).toBe('packing');
    expect(await getFableLoomExport(loom.id, id)).toMatchObject({ status: 'failed', error: { code: 'EXPORT_INTERRUPTED' } });
    stored.status = 'failed';
    stored.createdAt = Date.now() - FABLELOOM_EXPORT_LIMITS.maxAgeMs - 1;
    await writeFile(recordFile(id), JSON.stringify(stored));
    await expect(getFableLoomExport(loom.id, id)).rejects.toMatchObject({ code: 'EXPORT_EXPIRED', status: 410 });
    await begin();
    await expect(stat(recordFile(id))).rejects.toMatchObject({ code: 'ENOENT' });
    const last = jobIds.at(-1);
    await terminal(last);
    const valid = JSON.parse(await readFile(recordFile(last), 'utf8'));
    for (const invalid of ['{invalid-json', 'null', '{}', JSON.stringify({ ...valid, version: 2 }),
      JSON.stringify({ ...valid, status: 'completed', sizeReport: undefined })]) {
      await writeFile(recordFile(last), invalid);
      await expect(getFableLoomExport(loom.id, last)).rejects.toMatchObject({ code: 'EXPORT_STATE_INVALID', status: 503 });
    }
    await expect(getFableLoomExport(loom.id, '../../secret')).rejects.toMatchObject({ status: 404 });
  });

  videoIt('bounds the live queue and retains a leased download through terminal-job eviction', async () => {
    const prepare = media.prepareFableLoomExportMedia;
    const gate = Promise.withResolvers();
    vi.spyOn(media, 'prepareFableLoomExportMedia').mockImplementation(async (...args) => {
      await gate.promise;
      return prepare(...args);
    });
    const ids = [];
    try {
      ids.push(...await Promise.all(Array.from({ length: 4 }, () => begin({ episodeIds: ['episode-one'] }))));
      await expect(begin()).rejects.toMatchObject({ code: 'EXPORT_QUEUE_FULL', status: 429 });
    } finally { gate.resolve(); await __testing.drain(); }
    for (const [index, id] of ids.entries()) {
      expect(await getFableLoomExport(loom.id, id)).toMatchObject({ status: 'completed' });
      const stored = JSON.parse(await readFile(recordFile(id), 'utf8'));
      stored.createdAt = Date.now() - (ids.length - index) * 1000;
      await writeFile(recordFile(id), JSON.stringify(stored));
    }
    const lease = await getFableLoomExportDownload(loom.id, ids[0]);
    try {
      loom.episodes[0].nodes[0].image = null;
      await terminal(await begin());
      expect((await readFile(lease.path)).subarray(0, 2).toString()).toBe('PK');
      await expect(getFableLoomExport(loom.id, ids[1])).rejects.toMatchObject({ status: 404 });
    } finally { lease.release(); lease.release(); }
    await terminal(await begin());
    await expect(getFableLoomExport(loom.id, ids[0])).rejects.toMatchObject({ status: 404 });
  });

  it('rejects an oversized source before decoding or allocating its bytes', async () => {
    const filename = join(PATHS.images, 'oversized.png');
    await writeFile(filename, '');
    await truncate(filename, FABLELOOM_EXPORT_LIMITS.maxAssetBytes + 1);
    loom.episodes[0].nodes[0].image = 'oversized.png';
    const result = await terminal(await begin({ episodeIds: ['episode-one'] }));
    expect(result).toMatchObject({ status: 'failed', error: { code: 'EXPORT_MEDIA_SIZE' } });
    await rm(filename);
  });

  it('retains one bounded buffer for identical sources and gives ID caches only small descriptors', () => {
    const store = __testing.createMediaStore(4);
    const original = Buffer.from('abc');
    const descriptors = Array.from({ length: 50 }, (_, index) => store.add({
      bytes: index ? Buffer.from('abc') : original, extension: 'mp4', durationMs: 1000,
    }));
    expect(store.byteLength).toBe(3);
    expect(store.size).toBe(1);
    expect([...store.entries()][0][1]).toBe(original);
    expect(descriptors.every(d => !Object.values(d).some(Buffer.isBuffer))).toBe(true);
    expect(() => store.add({ bytes: Buffer.from('de'), extension: 'mp4', durationMs: 1000 }))
      .toThrow(expect.objectContaining({ code: 'EXPORT_PACKAGE_SIZE' }));
    expect(store.byteLength).toBe(3);
  });

  posixIt('rejects a named pipe without a writer and lets the next queued export progress', async ({ signal }) => {
    const pipe = join(PATHS.images, 'pipe.png');
    execFileSync('mkfifo', [pipe], { timeout: 5000 });
    const releaseBlockedReader = () => {
      try { closeSync(openSync(pipe, constants.O_WRONLY | constants.O_NONBLOCK)); }
      catch (failure) { if (!['ENXIO', 'ENOENT'].includes(failure.code)) throw failure; }
    };
    signal.addEventListener('abort', releaseBlockedReader, { once: true });
    try {
      loom.episodes[0].nodes[0].image = 'pipe.png';
      const result = await terminal(await begin({ episodeIds: ['episode-one'] }));
      expect(result).toMatchObject({ status: 'failed', error: { code: 'EXPORT_MEDIA_SIZE' } });
      loom.episodes[0].nodes[0].image = null;
      const next = await terminal(await begin({ episodeIds: ['episode-one'] }));
      expect(next).toMatchObject({ status: 'failed', error: { code: 'EXPORT_VALIDATION_FAILED' } });
    } finally {
      releaseBlockedReader();
      signal.removeEventListener('abort', releaseBlockedReader);
      await __testing.drain();
      await rm(pipe);
    }
  });
});

// Regression: a read-only preflight surfaces build gates without creating a job,
// and the selected package order and persisted snapshots survive the authoring flow.
it('preflights refusal and explicit draft gates without building, then streams selected job revisions', async () => {
  loom.episodes[0].nodes[0].visualCanon.storyboardImageApproved = false;
  const blocked = await request(app()).post(`/api/fableloom/${loom.id}/export/preflight`).send({ includePlayer: true });
  expect(blocked.status).toBe(200);
  expect(blocked.body.canBuild).toBe(false);
  expect(blocked.body.findings).toEqual(expect.arrayContaining([expect.objectContaining({ gate: 'approval', severity: 'error' })]));
  const allowed = await preflightFableLoomExport(loom.id, { allowDraft: true });
  expect(allowed.findings).toEqual(expect.arrayContaining([expect.objectContaining({ gate: 'approval', severity: 'warning' })]));
  const snapshots = [];
  const accept = value => snapshots.push(value);
  fableLoomRunEvents.on('export', accept);
  try {
    const id = await begin({ allowDraft: true });
    await terminal(id);
    await __testing.drain();
    const selected = snapshots.filter(job => job.jobId === id);
    expect(selected.length).toBeGreaterThan(1);
    expect(selected.every(job => job.loomId === loom.id)).toBe(true);
    expect(selected.map(job => job.revision)).toEqual([...selected.map(job => job.revision)].sort((a, b) => a - b));
    expect(['completed', 'failed']).toContain(selected.at(-1).status);
  } finally {
    fableLoomRunEvents.off('export', accept);
  }
});