videobook 0.0.0-stage → 0.2.0

package/dist/jobs/plan-goal.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { registerJobHandler } from "../queue.js";
+import { requireApiKey } from "../api-key.js";
+import { buildIntelligenceResponses, firstResponseText, intelligenceRequest } from "../openai-intelligence.js";
+import { chatIntelligenceRequestOptions } from "../chat-models.js";
+import { goalBriefConstraints, goalPlannerResponseSchema, goalPromptBudgetIssues, compileFrameSteps, compileStoryboardSteps, compileVideoSteps } from "../goal-plan.js";
+import { goalPlannerBrief } from "../goal-characters.js";
+import { goalBriefStyle, goalStyle } from "../goal-styles.js";
+import { constrainGoalPlannerPlan, goalPlannerInstructions } from "../goal-planner-prompt.js";
+import { readAssetTagSummaries } from "../asset-tags.js";
+import { readGoal, requireGoalContent, saveGoal, writeGoalContent } from "../goal-store.js";
+import { withNotebookMutation } from "../notebook-mutations.js";
+import { assessToolCallEstimate } from "./cost-estimate-assessment.js";
+import { goalPlannerImages } from "../goal-reference-images.js";
+function sumEstimates(estimates) {
+    return {
+        usd: estimates.every(estimate => estimate.usd !== null)
+            ? estimates.reduce((sum, estimate) => sum + (estimate.usd ?? 0), 0) : null,
+        warnings: [...new Set(estimates.flatMap((estimate) => estimate.warnings))],
+    };
+}
+export async function estimateGoal(engine, plan, characters) {
+    const reference = characters[0]?.artifactId ?? "";
+    const pins = characters.map(character => ({ ...character, address: character.artifactId }));
+    const groups = {
+        frame: compileFrameSteps(plan, pins),
+        storyboards: compileStoryboardSteps(plan, pins, reference),
+        videos: compileVideoSteps("estimate", plan, plan.shots.map(() => reference), plan.frameContinuity ? plan.shots.map(() => reference) : []).filter(step => step.id !== "assemble"),
+    };
+    const estimated = await Promise.all(Object.values(groups).map(async (steps) => sumEstimates(await Promise.all(steps.map(async (step) => {
+        const estimate = await assessToolCallEstimate(engine, step.tool, { book_id: engine.book.get().bookId, ...step.params });
+        return { usd: estimate.available ? estimate.usd : null, warnings: estimate.warnings };
+    })))));
+    return { frame: estimated[0], storyboards: estimated[1], videos: estimated[2], total: sumEstimates(estimated) };
+}
+export function registerPlanGoalJob(engine) {
+    registerJobHandler("plan_goal", async (payload, context) => {
+        const goalId = String(payload.goalId);
+        const goal = readGoal(engine, goalId);
+        if (goal.planVersion !== 2 || goal.status !== "planning")
+            return { goalId };
+        try {
+            const { brief, characters, requestedStyle } = requireGoalContent(engine, goal);
+            const style = requestedStyle ?? goalBriefStyle(brief);
+            const constraints = goalBriefConstraints(brief);
+            const tags = readAssetTagSummaries(engine, characters.map(character => character.artifactId));
+            const notebook = engine.notebooks.read(goal.notebookId);
+            if (!notebook.ok)
+                throw new Error(notebook.error.message);
+            const responses = buildIntelligenceResponses(requireApiKey("OPENAI_API_KEY"), chatIntelligenceRequestOptions());
+            const request = {
+                instructions: goalPlannerInstructions(style, constraints),
+                input: [{ role: "user", content: [
+                            { type: "input_text", text: JSON.stringify({ brief: goalPlannerBrief(brief, characters, notebook.value).replace(/Character (\d+)/gu, "Reference $1"), style: { ...style, label: goalStyle(style.id).label }, references: characters.map((character, index) => ({ name: `Reference ${index + 1}`, label: character.label, tags: tags.get(character.artifactId)?.effective ?? [] })), ...constraints }) },
+                            ...await goalPlannerImages(engine, characters),
+                        ] }],
+                text: { format: { type: "json_schema", name: "video_goal_plan", strict: true, schema: z.toJSONSchema(goalPlannerResponseSchema.omit({ style: true })) } },
+                max_output_tokens: 2500,
+            };
+            const response = await responses(intelligenceRequest(request, chatIntelligenceRequestOptions()), context.signal);
+            let plan = goalPlannerResponseSchema.parse(JSON.parse(firstResponseText(response)));
+            const budgetIssues = goalPromptBudgetIssues(plan);
+            if (budgetIssues.length > 0) {
+                const revised = await responses(intelligenceRequest({
+                    ...request,
+                    input: [...request.input, { role: "user", content: `Shorten this plan while preserving its meaning: ${JSON.stringify(plan)}\nFix these word limits: ${budgetIssues.join(" ")}` }],
+                }, chatIntelligenceRequestOptions()), context.signal);
+                const parsed = goalPlannerResponseSchema.safeParse(JSON.parse(firstResponseText(revised)));
+                if (!parsed.success || goalPromptBudgetIssues(parsed.data).length > 0)
+                    throw new Error("The planner wrote prompts that are too long. Try planning again.");
+                plan = parsed.data;
+            }
+            plan = constrainGoalPlannerPlan(plan, brief, style);
+            plan.referenceRoles = characters.map((_, index) => plan.referenceRoles?.[index] ?? "reference");
+            const estimate = await estimateGoal(engine, plan, characters);
+            await withNotebookMutation(`goal:${goalId}`, async () => {
+                const current = readGoal(engine, goalId);
+                if (current.status !== "planning")
+                    return;
+                const content = requireGoalContent(engine, current);
+                await writeGoalContent(engine, current, { ...content, plan, estimate, revision: content.revision + 1 });
+                saveGoal(engine, { ...current, stage: "frame", status: "review", error: null });
+            });
+            return { goalId };
+        }
+        catch (error) {
+            await withNotebookMutation(`goal:${goalId}`, async () => {
+                const current = readGoal(engine, goalId);
+                if (current.status === "planning")
+                    saveGoal(engine, {
+                        ...current, status: "failed", error: error instanceof Error ? error.message : String(error),
+                    });
+            });
+            throw error;
+        }
+    });
+}

package/dist/jobs/post-record.js

@@ -0,0 +1,21 @@
+import { createPost, getPost, linkPost, updatePost } from "../posts/post-store.js";
+import { registerJobHandler } from "../queue.js";
+import { withNotebookMutation } from "../notebook-mutations.js";
+import { uploadPostToDropbox } from "../posts/dropbox-upload.js";
+import { savePostToICloud } from "../posts/icloud-drive.js";
+import { refreshPostMetrics } from "../posts/post-metrics.js";
+import { draftPostCopy, postCopyResponses, readPostCopyContext } from "../posts/post-copy.js";
+import { getApiKey } from "../api-key.js";
+export function registerPostRecordJobs(engine) {
+    registerJobHandler("post_create", async (payload) => createPost(engine, payload.args));
+    registerJobHandler("post_update", async (payload) => withNotebookMutation(`post:${payload.postCellId}`, () => updatePost(engine, String(payload.postCellId), payload.patch)));
+    registerJobHandler("post_link", async (payload) => withNotebookMutation(`post:${payload.postCellId}`, () => linkPost(engine, String(payload.postCellId), String(payload.url), String(payload.postedAt))));
+    registerJobHandler("post_dropbox", async (payload, context) => withNotebookMutation(`post:${payload.postCellId}`, () => uploadPostToDropbox(engine, String(payload.postCellId), { folder: typeof payload.folder === "string" ? payload.folder : undefined, caption: typeof payload.caption === "string" ? payload.caption : undefined, signal: context.signal })));
+    registerJobHandler("post_icloud", async (payload) => withNotebookMutation(`post:${payload.postCellId}`, () => savePostToICloud(engine, String(payload.postCellId), { folder: typeof payload.folder === "string" ? payload.folder : undefined, caption: typeof payload.caption === "string" ? payload.caption : undefined })));
+    registerJobHandler("post_copy", async (payload, context) => {
+        const post = getPost(engine, String(payload.postCellId));
+        const copyContext = await readPostCopyContext(engine, post);
+        return draftPostCopy(postCopyResponses(getApiKey("OPENAI_API_KEY") ?? undefined), copyContext, payload.request, context.signal);
+    });
+    registerJobHandler("post_metrics", async (payload, context) => withNotebookMutation(`post-metrics:${payload.postCellId}`, () => refreshPostMetrics(engine, String(payload.postCellId), { signal: context.signal })));
+}

package/dist/jobs/post-to-x.js

@@ -0,0 +1,21 @@
+import { registerJobHandler } from "../queue.js";
+import { postToX, prepareXPublication } from "../x/post-to-x.js";
+export function registerPostToXJob(engine) {
+    registerJobHandler("post_prepare_x", async (payload, context) => prepareXPublication({ engine, publicationKey: `job:${context.jobId}`, ...payload }));
+    registerJobHandler("post_to_x", async (payload, context) => {
+        const { assetId, postCellId, bookId, text, orientation, scheduleId, scheduledFor, followups, } = payload;
+        return await postToX({
+            engine,
+            publicationKey: scheduleId ? `schedule:${scheduleId}` : `job:${context.jobId}`,
+            signal: context.signal,
+            assetId,
+            postCellId,
+            bookId,
+            text,
+            orientation,
+            scheduleId,
+            scheduledFor,
+            followups,
+        });
+    });
+}

package/dist/jobs/prepare-search-reference.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import sharp from "sharp";
+import { findPrimaryMediaFile, findVideoFile, LOCAL_CLIP_MANIFEST, } from "videobook-engine";
+import { probeVideo, runFfmpeg } from "../ffmpeg.js";
+import { decodeHeicToPng } from "../image.js";
+import { registerLocalClipSearchProvider } from "../local-search-models.js";
+import { searchReferenceStore, } from "../search-reference-store.js";
+import { registerJobHandler } from "../queue.js";
+async function runPrepareSearchReference(engine, payload, context) {
+    try {
+        const uploadPath = payload.uploadPath;
+        const source = uploadPath
+            ? { path: uploadPath, objectHash: undefined, readBytes: () => readFile(uploadPath) }
+            : await existingAssetSource(engine, payload.assetId, payload.mediaKind);
+        const prepared = await prepareSearchReferenceFile(engine, source.path, payload.mediaKind, {
+            name: payload.name,
+            readBytes: source.readBytes,
+            ...(source.objectHash
+                ? { sourceObjectHash: source.objectHash }
+                : {}),
+            sourceStartMs: payload.sourceStartMs,
+            sourceDurationMs: payload.sourceDurationMs,
+            signal: context.signal,
+        });
+        return searchReferenceStore.put(prepared);
+    }
+    finally {
+        if (payload.cleanupRoot) {
+            await rm(payload.cleanupRoot, { recursive: true, force: true });
+        }
+    }
+}
+async function prepareSearchReferenceFile(engine, sourcePath, mediaKind, options) {
+    const provider = registerLocalClipSearchProvider(engine);
+    const registered = engine.temporalSearch.manifests.register(LOCAL_CLIP_MANIFEST);
+    if (!registered.ok)
+        throw new Error(registered.error.message);
+    await provider.prepare({ signal: options.signal });
+    options.signal?.throwIfAborted();
+    const name = options.name?.trim() || basename(sourcePath);
+    if (mediaKind === "image") {
+        let normalizedRoot;
+        try {
+            let imagePath = sourcePath;
+            let preview;
+            if (/\.hei[cf]$/iu.test(sourcePath)) {
+                const decoded = await decodeHeicToPng(await options.readBytes());
+                options.signal?.throwIfAborted();
+                normalizedRoot = await mkdtemp(join(tmpdir(), "videobook-search-image-"));
+                imagePath = join(normalizedRoot, "reference.png");
+                await writeFile(imagePath, decoded);
+                preview = await sharp(decoded).resize(512, 512, { fit: "inside", withoutEnlargement: true }).png().toBuffer();
+            }
+            const vector = await provider.embedImage(imagePath, { signal: options.signal });
+            options.signal?.throwIfAborted();
+            return {
+                kind: "image",
+                name,
+                ...(preview ? { preview } : {}),
+                reference: {
+                    kind: "image",
+                    embeddingSpace: provider.embeddingSpace,
+                    vector: [...vector],
+                    fingerprints: [{
+                            kind: "sha256",
+                            value: options.sourceObjectHash ?? await fileHash(sourcePath),
+                        }],
+                },
+            };
+        }
+        finally {
+            if (normalizedRoot)
+                await rm(normalizedRoot, { recursive: true, force: true });
+        }
+    }
+    const probe = await probeVideo(sourcePath, { signal: options.signal });
+    if (!probe.videoStream || probe.videoDuration <= 0) {
+        throw new Error("The selected reference has no usable video stream");
+    }
+    const fullDurationMs = Math.max(1, Math.round(probe.videoDuration * 1_000));
+    const sourceStartMs = boundedStart(options.sourceStartMs, fullDurationMs);
+    const availableMs = fullDurationMs - sourceStartMs;
+    const durationMs = boundedDuration(options.sourceDurationMs, availableMs);
+    const offsets = sampleOffsets(durationMs);
+    const frameRoot = await mkdtemp(join(tmpdir(), "videobook-search-frames-"));
+    try {
+        const samples = [];
+        for (const [index, offsetMs] of offsets.entries()) {
+            options.signal?.throwIfAborted();
+            const framePath = join(frameRoot, `${String(index).padStart(2, "0")}.jpg`);
+            await runFfmpeg([
+                "-ss",
+                ((sourceStartMs + offsetMs) / 1_000).toFixed(3),
+                "-i",
+                sourcePath,
+                "-frames:v",
+                "1",
+                "-q:v",
+                "2",
+                "-y",
+                framePath,
+            ], { signal: options.signal });
+            const vector = await provider.embedImage(framePath, { signal: options.signal });
+            samples.push({ offsetMs, vector: [...vector] });
+        }
+        return {
+            kind: "video",
+            name,
+            durationMs,
+            reference: {
+                kind: "video",
+                embeddingSpace: provider.embeddingSpace,
+                durationMs,
+                samples,
+            },
+        };
+    }
+    finally {
+        await rm(frameRoot, { recursive: true, force: true });
+    }
+}
+export function registerPrepareSearchReferenceJob(engine) {
+    registerJobHandler("prepare_search_reference", async (payload, context) => engine.withLocalMedia(() => runPrepareSearchReference(engine, payload, context)));
+}
+async function existingAssetSource(engine, assetId, mediaKind) {
+    if (!assetId)
+        throw new Error("Search reference asset ID is required");
+    const artifact = engine.artifacts.get(assetId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    if (mediaKind === "image"
+        ? artifact.value.kind !== "image"
+        : artifact.value.kind !== "video" && artifact.value.kind !== "final") {
+        throw new Error(`The selected asset is not a ${mediaKind}`);
+    }
+    const manifest = await engine.files.manifest(artifact.value.artifactId);
+    if (!manifest.ok)
+        throw Object.assign(new Error(manifest.error.message), { name: manifest.error.code, error: manifest.error });
+    const file = mediaKind === "video"
+        ? findVideoFile(manifest.value.files)
+            ?? findPrimaryMediaFile(manifest.value.files, artifact.value.kind)
+        : findPrimaryMediaFile(manifest.value.files, artifact.value.kind)
+            ?? manifest.value.files.find((candidate) => /\.hei[cf]$/iu.test(candidate.name));
+    if (!file)
+        throw new Error(`No ${mediaKind} file is available for this asset`);
+    return {
+        path: join(manifest.value.path, file.name),
+        objectHash: file.objectHash,
+        readBytes: async () => {
+            const read = await engine.files.read(artifact.value.artifactId, file.name);
+            if (!read.ok)
+                throw Object.assign(new Error(read.error.message), { name: read.error.code, error: read.error });
+            return read.value;
+        },
+    };
+}
+function boundedStart(value, durationMs) {
+    if (value === undefined)
+        return 0;
+    if (!Number.isFinite(value) || value < 0 || value >= durationMs) {
+        throw new Error("Reference start must fall within the video");
+    }
+    return Math.round(value);
+}
+function boundedDuration(value, availableMs) {
+    if (value === undefined)
+        return availableMs;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error("Reference duration must be positive");
+    }
+    return Math.max(1, Math.min(Math.round(value), availableMs));
+}
+function sampleOffsets(durationMs) {
+    if (durationMs <= 100)
+        return [0];
+    const count = Math.min(16, Math.max(2, Math.ceil(durationMs / 1_000)));
+    const finalOffset = Math.max(1, durationMs - Math.min(50, durationMs / 10));
+    return Array.from({ length: count }, (_, index) => Math.round(index * finalOffset / (count - 1)));
+}
+async function fileHash(filePath) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}

package/dist/jobs/prepare-temporal-search.js

@@ -0,0 +1,16 @@
+import { queue, registerJobHandler } from "../queue.js";
+export async function enqueueTemporalSearchPreparation(bookId) {
+    const job = await queue.enqueue(`prepare-temporal-search:${bookId}`, {
+        type: "prepare_temporal_search",
+        bookId,
+    });
+    return { bookId, jobId: job.id };
+}
+export function registerPrepareTemporalSearchJob(engine) {
+    registerJobHandler("prepare_temporal_search", async (_payload, context) => {
+        const result = await engine.temporalSearch.prepare({ signal: context.signal });
+        if (!result.ok)
+            throw new Error(result.error.message);
+        return result.value;
+    });
+}

package/dist/jobs/process-audio.js

@@ -0,0 +1,67 @@
+import { extractWaveform, probeVideo } from "../ffmpeg.js";
+import { enqueueAssetTagging } from "./tag-asset.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { getApiKey } from "../api-key.js";
+import { withLocalLease } from "./_lease.js";
+import { registerMediaStreams } from "./process-video.js";
+import { withTransientStorageRetry } from "./_storage-retry.js";
+export async function processAudioFile(engine, payload, signal) {
+    signal?.throwIfAborted();
+    const probe = await probeVideo(payload.audioPath, { signal });
+    if (!probe.audioStream) {
+        throw new Error(`process_audio requires an audio stream: ${payload.assetId}`);
+    }
+    await registerMediaStreams(engine, payload.assetId, payload.sourceFilename, probe);
+    const duration = probe.audioDuration ?? probe.duration;
+    await engine.metadata.artifacts.write(payload.assetId, "original", {
+        ...payload.provenance,
+        duration,
+        sampleRateHz: probe.audioStream.audio?.sampleRateHz,
+        channels: probe.audioStream.audio?.channels,
+    });
+    const waveform = await extractWaveform(payload.audioPath);
+    if (waveform.length > 0) {
+        const written = await engine.metadata.waveforms.write(payload.assetId, waveform);
+        if (!written.ok)
+            throw new Error(written.error.message);
+    }
+    if (process.env.NODE_ENV !== "test") {
+        await queue.enqueue(`semantic-index-${payload.assetId}-${Date.now()}`, {
+            type: "semantic_index",
+            assetId: payload.assetId,
+            bookId: payload.bookId,
+        });
+        if (getApiKey("ELEVENLABS_API_KEY")) {
+            await queue.enqueue(`transcribe-audio-${payload.assetId}-${Date.now()}`, {
+                type: "transcribe",
+                audioPath: payload.audioPath,
+                audioFilename: payload.sourceFilename,
+                tagAudioEvents: true,
+                diarize: true,
+                assetId: payload.assetId,
+                assetDir: payload.assetDir,
+                bookId: payload.bookId,
+            });
+        }
+        else if (getApiKey("OPENAI_API_KEY")) {
+            await queue.enqueue(`transcribe-audio-${payload.assetId}-${Date.now()}`, {
+                type: "transcribe_video_audio",
+                videoPath: payload.audioPath,
+                sourceFilename: payload.sourceFilename,
+                assetId: payload.assetId,
+                assetDir: payload.assetDir,
+                bookId: payload.bookId,
+            });
+        }
+    }
+    if (process.env.NODE_ENV !== "test") {
+        await enqueueAssetTagging(engine, payload.assetId);
+    }
+    return { success: true, duration };
+}
+export function registerProcessAudioJob(engine) {
+    registerJobHandler("process_audio", async (payload, ctx) => {
+        const input = payload;
+        return withLocalLease(engine, input.assetId, ctx, "process", async () => withTransientStorageRetry(() => processAudioFile(engine, input, ctx.signal), ctx.signal));
+    });
+}

package/dist/jobs/process-image.js

@@ -0,0 +1,58 @@
+import { enqueueAssetTagging } from "./tag-asset.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { withLocalLease } from "./_lease.js";
+import { probeImage, cropToFill, decodeHeicToPng } from "../image.js";
+import { withTransientStorageRetry } from "./_storage-retry.js";
+export const SKIP_CROP_EXTENSIONS = new Set([".svg", ".gif"]);
+export function registerProcessImageJob(engine) {
+    registerJobHandler("process_image", async (payload, ctx) => {
+        const { assetId, bookId, extension, provenance, } = payload;
+        return withLocalLease(engine, assetId, ctx, "process", async () => withTransientStorageRetry(async () => {
+            const readResult = await engine.files.read(assetId, `original${extension}`);
+            if (!readResult.ok)
+                throw new Error(`Failed to read original: ${readResult.error.message}`);
+            let buffer = Buffer.isBuffer(readResult.value) ? readResult.value : Buffer.from(readResult.value);
+            if (extension === ".heic" || extension === ".heif") {
+                buffer = await decodeHeicToPng(buffer);
+                const converted = await engine.files.write(assetId, "original.png", buffer);
+                if (!converted.ok)
+                    throw new Error(converted.error.message);
+            }
+            const { width, height } = await probeImage(buffer);
+            const metadata = await engine.metadata.artifacts.write(assetId, "original", { ...provenance, width, height });
+            if (!metadata.ok)
+                throw new Error(metadata.error.message);
+            if (!SKIP_CROP_EXTENSIONS.has(extension)) {
+                const [landscape, portrait, square] = await Promise.all([
+                    cropToFill(buffer, 1920, 1080),
+                    cropToFill(buffer, 1080, 1920),
+                    cropToFill(buffer, 1080, 1080),
+                ]);
+                const landscapeWrite = await engine.files.write(assetId, "landscape.jpg", landscape);
+                if (!landscapeWrite.ok)
+                    throw new Error(landscapeWrite.error.message);
+                const portraitWrite = await engine.files.write(assetId, "portrait.jpg", portrait);
+                if (!portraitWrite.ok)
+                    throw new Error(portraitWrite.error.message);
+                const squareWrite = await engine.files.write(assetId, "square.jpg", square);
+                if (!squareWrite.ok)
+                    throw new Error(squareWrite.error.message);
+            }
+            if (process.env.NODE_ENV !== "test") {
+                await queue.enqueue(`semantic-index-${assetId}-${Date.now()}`, {
+                    type: "semantic_index",
+                    assetId,
+                    bookId,
+                });
+            }
+            // Vision analysis for the reproduction prompt is still gated to slot
+            // drop in tools/assign-slot.ts. Tagging is not: an image that never
+            // reaches a timeline still has to be findable in the Library, and the
+            // tag job asks for the analysis it needs once per content hash.
+            if (process.env.NODE_ENV !== "test") {
+                await enqueueAssetTagging(engine, assetId);
+            }
+            return { success: true, width, height };
+        }, ctx.signal));
+    });
+}

package/dist/jobs/process-upload.js

@@ -0,0 +1,166 @@
+import * as path from "node:path";
+import { queue } from "../queue.js";
+const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".webm", ".avi", ".mkv"]);
+const AUDIO_EXTENSIONS = new Set([
+    ".mp3",
+    ".wav",
+    ".aac",
+    ".flac",
+    ".ogg",
+    ".m4a",
+    ".weba",
+]);
+const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".heic", ".heif"]);
+const SCRIPT_EXTENSIONS = new Set([".md"]);
+// process_image writes these alongside an original image. Their presence is
+// proof that processing already ran, so the upload sweep must never promote
+// one of them to `original.{ext}` — that's how a portrait PNG gets cropped
+// into a 1920x1080 landscape JPG when the sweep races a missing
+// native processing metadata.
+const IMAGE_VARIANT_FILENAMES = new Set(["landscape.jpg", "portrait.jpg", "square.jpg"]);
+// The artifact kind is authoritative for type — a video asset with a
+// promoted OG thumbnail (original.jpg) must not be classified as an image
+// upload just because the .jpg sorts before the .mp4. Returns null for asset
+// kinds that aren't candidates for the upload sweep (character/final/plan).
+function uploadShapeFor(type) {
+    switch (type) {
+        case "video": return { mediaType: "video", extensions: VIDEO_EXTENSIONS };
+        case "audio": return { mediaType: "audio", extensions: AUDIO_EXTENSIONS };
+        case "image": return { mediaType: "image", extensions: IMAGE_EXTENSIONS };
+        case "script": return { mediaType: "script", extensions: SCRIPT_EXTENSIONS };
+        default: return null;
+    }
+}
+export async function findUnprocessedUploads(engine, assets) {
+    const results = await Promise.all(assets.map(async (asset) => {
+        if (asset.kind === "final")
+            return null;
+        const shape = uploadShapeFor(asset.kind);
+        if (!shape)
+            return null;
+        // Parallelize the independent disk/db reads — each was ~5-20ms serially,
+        // multiplied by every asset on every sync.
+        const [manifest, originResult, locked, work] = await Promise.all([
+            engine.files.manifest(asset.artifactId),
+            engine.metadata.artifacts.read(asset.artifactId, "original"),
+            engine.jobs.locks.isLocked(asset.path),
+            engine.jobs.artifactWork.read(asset.artifactId),
+        ]);
+        if (!manifest.ok)
+            return null;
+        if (originResult.ok)
+            return null;
+        // Skip assets currently held by another job (splice/trim/render mid-write).
+        // Otherwise the sweep races the in-flight ffmpeg writing original.mp4 and
+        // hands a half-written file to process_video, producing a spurious
+        // runtime failure before the real owner finishes.
+        if (locked)
+            return null;
+        // Skip assets that already have an active job or a terminal failure.
+        // 'pending'/'working' WITH meta.kind = the upload's own process_video is
+        // already enqueued or in-flight — racing it produces duplicate jobs that
+        // re-run the full transcode pipeline (or, with the legacy delete-source
+        // flow, fail with "ffprobe missing original.mkv"). 'error' = a prior run
+        // failed and nothing has cleared the row; re-enqueuing without recovery
+        // just spins (the engine's lease guard rejects new work until the row
+        // is cleared via /clear-failed-tasks or equivalent).
+        //
+        // A 'pending' row with no meta.kind is the placeholder createAsset
+        // writes as a 5-minute cleanup marker — that's the exact case the
+        // sweep needs to pick up, not skip.
+        if (work.ok && work.value) {
+            const { status, meta } = work.value;
+            if (status === "error")
+                return null;
+            if ((status === "pending" || status === "working") && meta.kind != null)
+                return null;
+        }
+        // A queued job owns the asset before it acquires a lease or lock. This
+        // also covers registered job types without an artifact-work classification.
+        if (engine.jobs.queue.list({
+            artifactId: asset.artifactId,
+            states: ["queued", "running", "completing"],
+            limit: 1,
+        }).length > 0)
+            return null;
+        // Prefer a literal `original.{ext}` first — that's the canonical shape
+        // produced by upload-file and processExternalUpload itself. Only fall
+        // back to an arbitrary-name file (user dragged "photo.png" straight
+        // into the asset folder) when no `original.*` exists AND no
+        // process_image variant exists. Without that variant guard, missing
+        // processing metadata would cause the sweep to pick the alphabetically
+        // first variant (landscape.jpg) and rename it to original.jpg.
+        const originalFiles = manifest.value.files.filter((f) => {
+            const ext = path.extname(f.name).toLowerCase();
+            return shape.extensions.has(ext) && f.name === `original${ext}`;
+        });
+        let mediaFile = originalFiles.find((f) => !/\.(?:heic|heif)$/i.test(f.name)) ?? originalFiles.at(0);
+        if (!mediaFile) {
+            const hasImageVariant = shape.mediaType === "image"
+                && manifest.value.files.some((f) => IMAGE_VARIANT_FILENAMES.has(f.name));
+            if (hasImageVariant)
+                return null;
+            mediaFile = manifest.value.files.find((f) => {
+                const ext = path.extname(f.name).toLowerCase();
+                return shape.extensions.has(ext);
+            });
+        }
+        if (!mediaFile)
+            return null;
+        const ext = path.extname(mediaFile.name).toLowerCase();
+        return {
+            assetId: asset.artifactId,
+            assetDir: asset.path,
+            mediaFilename: mediaFile.name,
+            extension: ext,
+            mediaType: shape.mediaType,
+        };
+    }));
+    return results.filter((u) => u !== null);
+}
+export async function processExternalUpload(engine, upload, bookId) {
+    const targetFilename = `original${upload.extension}`;
+    if (upload.mediaFilename !== targetFilename) {
+        await engine.files.rename(upload.assetId, upload.mediaFilename, targetFilename);
+    }
+    await engine.jobs.failures.clear(upload.assetId);
+    const provenance = { origin: "external", processed_at: new Date().toISOString() };
+    if (upload.mediaType === "video") {
+        const videoPath = path.join(upload.assetDir, targetFilename);
+        const jobId = `process-video-${upload.assetId}-${Date.now()}`;
+        await queue.enqueue(jobId, {
+            type: "process_video",
+            videoPath,
+            assetId: upload.assetId,
+            assetDir: upload.assetDir,
+            bookId,
+            provenance,
+        });
+    }
+    else if (upload.mediaType === "image") {
+        const jobId = `process-image-${upload.assetId}-${Date.now()}`;
+        await queue.enqueue(jobId, {
+            type: "process_image",
+            assetId: upload.assetId,
+            bookId,
+            extension: upload.extension,
+            provenance,
+        });
+    }
+    else if (upload.mediaType === "audio") {
+        const audioPath = path.join(upload.assetDir, targetFilename);
+        const jobId = `process-audio-${upload.assetId}-${Date.now()}`;
+        await queue.enqueue(jobId, {
+            type: "process_audio",
+            audioPath,
+            sourceFilename: targetFilename,
+            assetId: upload.assetId,
+            assetDir: upload.assetDir,
+            bookId,
+            provenance,
+        });
+    }
+    else {
+        await engine.metadata.artifacts.write(upload.assetId, "original", provenance);
+    }
+}