videobook 0.0.0-stage → 0.2.0

package/dist/tools/doctor.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { gcEngineCatalog } from "../catalog-gc.js";
+import { queue } from "../queue.js";
+function error(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+// assets-table statuses that count as "in progress" — a row sitting in one of
+// these past its deadline is wedged, not legitimately working.
+const STUCK_WORK_STATUSES = new Set(["working", "pending"]);
+/**
+ * Read-only health scan. Type-agnostic: it iterates every asset returned by
+ * listAssets and asks the engine's own computeArtifactStatus (via getAssetStatus)
+ * for each, so all seven asset types are covered without special-casing.
+ */
+async function diagnose(engine, bookId, onlyAssetId) {
+    const all = await engine.artifacts.list();
+    const assets = onlyAssetId ? all.filter((a) => a.artifactId === onlyAssetId) : all;
+    const errorsRes = await engine.jobs.failures.findAll();
+    const errorByAsset = new Map();
+    if (errorsRes.ok)
+        for (const e of errorsRes.value)
+            errorByAsset.set(e.artifactId, e);
+    const workRes = await engine.jobs.artifactWork.list();
+    const workByAsset = new Map();
+    if (workRes.ok)
+        for (const w of workRes.value)
+            workByAsset.set(w.artifactId, w);
+    const nowMs = Date.now();
+    const broken = [];
+    const stuck = [];
+    let healthy = 0;
+    await Promise.all(assets.map(async (a) => {
+        const statusRes = await engine.status.get(a.artifactId);
+        const status = statusRes.ok ? statusRes.value : "error";
+        const work = workByAsset.get(a.artifactId);
+        if (status === "error") {
+            const ge = errorByAsset.get(a.artifactId);
+            broken.push({
+                asset_id: a.artifactId,
+                type: a.kind,
+                error: ge
+                    ? { message: ge.message, fail_code: ge.failCode ?? null, failed_at: ge.failedAt }
+                    : null,
+            });
+        }
+        else if (work &&
+            STUCK_WORK_STATUSES.has(work.status) &&
+            work.deadlineAt != null &&
+            work.deadlineAt < nowMs) {
+            stuck.push({
+                asset_id: a.artifactId,
+                type: a.kind,
+                work_status: work.status,
+                deadline_at: work.deadlineAt,
+                minutes_overdue: Math.round((nowMs - work.deadlineAt) / 60000),
+            });
+        }
+        else {
+            healthy += 1;
+        }
+    }));
+    const report = {
+        book_id: bookId,
+        total: assets.length,
+        healthy,
+        broken,
+        stuck,
+    };
+    if (broken.length > 0 || stuck.length > 0) {
+        report.hint =
+            "Re-run with { asset_id, fix: true } to restore a specific asset to its last usable state.";
+    }
+    return report;
+}
+export function doctorDef(engine) {
+    return {
+        name: "doctor",
+        description: "Report assets stuck in an error state or past their work deadline. fix with an asset_id restores that one asset (clears a stale error or lease, otherwise restores it from history); fix alone only reports. gc reclaims catalog storage for this book.",
+        schema: {
+            book_id: z.string().describe("Book id"),
+            asset_id: z
+                .string()
+                .optional()
+                .describe("Limit diagnosis to one asset by artifact id; REQUIRED when fix is true"),
+            fix: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Restore the given asset_id to its last usable state. Requires asset_id."),
+            gc: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Run catalog GC on this book and report bytes/chunks reclaimed."),
+        },
+        handler: async (args) => {
+            const { book_id, asset_id, fix, gc } = args;
+            const assetId = asset_id?.replace(/^@/, "");
+            if (fix) {
+                if (!assetId) {
+                    return error("doctor fix requires an explicit asset_id — it never bulk-fixes a project. " +
+                        "Run doctor without fix to see which assets need attention.");
+                }
+                const jobId = `doctor-fix-${assetId}-${Date.now()}`;
+                try {
+                    const result = await queue.enqueueAndWait(jobId, {
+                        type: "doctor_fix",
+                        bookId: book_id,
+                        assetId,
+                    });
+                    return ok(result);
+                }
+                catch (e) {
+                    return error(`doctor fix failed for ${assetId}: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            const report = await diagnose(engine, book_id, assetId);
+            if (gc)
+                report.catalog_gc = gcEngineCatalog(engine);
+            return ok(report);
+        },
+    };
+}

package/dist/tools/download-video.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { join } from "node:path";
+import { queue } from "../queue.js";
+import { parseTime } from "../time-parse.js";
+const SOURCE_PREFIX_MAP = {
+    "youtube.com": "yt",
+    "youtu.be": "yt",
+    "twitter.com": "x",
+    "x.com": "x",
+    "instagram.com": "ig",
+    "tiktok.com": "tt",
+    "vimeo.com": "vm",
+    "reddit.com": "rd",
+    "facebook.com": "fb",
+    "fb.watch": "fb",
+    "twitch.tv": "tw",
+    "dailymotion.com": "dm",
+};
+function sourcePrefix(url) {
+    try {
+        const hostname = new URL(url).hostname.replace(/^www\./, "");
+        if (SOURCE_PREFIX_MAP[hostname])
+            return SOURCE_PREFIX_MAP[hostname];
+        const base = hostname.split(".").slice(-2, -1)[0];
+        return base ? base.slice(0, 3) : "dl";
+    }
+    catch {
+        return "dl";
+    }
+}
+export function downloadVideoDef(engine) {
+    return {
+        name: "download_video",
+        description: "Download a video or requested time range from a URL (YouTube, Twitter/X, etc.) into a Videobook as original.mp4. Supports auto-exports in 16:9 and 9:16.",
+        schema: {
+            url: z.string().describe("Video URL (YouTube, Twitter/X, Instagram, TikTok, etc.)"),
+            start_time: z.union([z.string(), z.number()]).optional().describe("Range start in seconds or timestamp notation (e.g. '30', '1:30', '2m20s')"),
+            end_time: z.union([z.string(), z.number()]).optional().describe("Range end in seconds or timestamp notation (e.g. '60', '2:00', '3m')"),
+            book_id: z.string().describe("Book UUID"),
+            export_videos: z.boolean().optional().default(false).describe("Auto-export 16:9 and 9:16 versions (default: off)"),
+            full: z.boolean().optional().default(false).describe("Deprecated; omit start_time and end_time to keep the full source"),
+        },
+        handler: async (args) => {
+            const { url, start_time, end_time, book_id, export_videos } = args;
+            let startSecs;
+            let endSecs;
+            try {
+                startSecs = parseTime(start_time);
+                endSecs = parseTime(end_time);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                return { isError: true, content: [{ type: "text", text: msg }] };
+            }
+            if ((startSecs !== undefined && startSecs < 0)
+                || (endSecs !== undefined && endSecs <= 0)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "start_time must be >= 0 and end_time must be > 0." }],
+                };
+            }
+            if (startSecs !== undefined && endSecs !== undefined && startSecs >= endSecs) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "start_time must be less than end_time." }],
+                };
+            }
+            const requestedRange = startSecs !== undefined || endSecs !== undefined
+                ? {
+                    ...(startSecs !== undefined ? { start: startSecs } : {}),
+                    ...(endSecs !== undefined ? { end: endSecs } : {}),
+                }
+                : undefined;
+            const normalizedUrl = /^https?:\/\//i.test(url) ? url : `https://${url}`;
+            const prefix = sourcePrefix(normalizedUrl);
+            const title = new URL(normalizedUrl).pathname.split("/").filter(Boolean).pop() ?? "video";
+            const assetName = `${prefix} ${title}`;
+            const assetResult = await engine.artifacts.create("video", assetName);
+            if (!assetResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error creating asset: ${assetResult.error.message}` }],
+                };
+            }
+            const { artifactId, path: assetDir, } = assetResult.value;
+            const assetId = artifactId;
+            const outputPath = join(assetDir, "original.mp4");
+            const jobId = `download-${assetId}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "download_video",
+                url: normalizedUrl,
+                outputPath,
+                assetId,
+                assetDir,
+                bookId: book_id,
+                exportVideos: export_videos ?? false,
+                full: true,
+                sourcePrefix: prefix,
+                ...(requestedRange ? { requestedRange } : {}),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            artifact_id: artifactId,
+                            assetId,
+                            job_id: jobId,
+                            status: "enqueued",
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/duplicate-asset.js

@@ -0,0 +1,184 @@
+import { NOTEBOOK_GRID_ROW_COUNT, notebookOccupiedSlots, notebookGridTag, parseNotebookGridAddress, } from "videobook-engine/notebook-grid";
+import { NOTEBOOK_GRID_ADDRESS_SOURCE } from "videobook-engine/notebook-mentions";
+import { z } from "zod";
+import { EMPTY_TRANSFER_SUMMARY, transferAssetTags } from "../asset-tags.js";
+import { enqueueSearchIndex } from "../jobs/enqueue-search-index.js";
+import { mutateNotebook } from "../notebook-mutations.js";
+import { sourceCellForPostedArtifact } from "../notebook-published-post.js";
+const destinationSchema = z.string()
+    .regex(new RegExp(`^@?${NOTEBOOK_GRID_ADDRESS_SOURCE}$`, "iu"))
+    .describe("Optional empty destination cell from a1 through bl8");
+function mediaCellType(kind) {
+    if (kind === "final")
+        return "video";
+    return kind === "audio" || kind === "image" || kind === "video"
+        ? kind
+        : null;
+}
+function sourceCellForArtifact(notebook, artifactId, cellType) {
+    return sourceCellForPostedArtifact(notebook, artifactId, cellType);
+}
+function duplicateDestination(notebook, source, requested) {
+    const destination = requested
+        ? parseNotebookGridAddress(requested)
+        : source && source.slot.row + 1 < NOTEBOOK_GRID_ROW_COUNT
+            ? { row: source.slot.row + 1, column: source.slot.column }
+            : null;
+    if (!destination) {
+        throw new Error(source
+            ? `${notebookGridTag(source.slot)} has no cell below it; choose a destination`
+            : "Choose a destination because the source asset is not in this notebook");
+    }
+    const occupied = notebookOccupiedSlots(notebook.cells).some((slot) => slot.row === destination.row && slot.column === destination.column);
+    if (occupied) {
+        throw new Error(`Notebook cell ${notebookGridTag(destination)} is occupied`);
+    }
+    return destination;
+}
+function failure(message) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+    };
+}
+async function copyOriginalMetadata(engine, sourceAssetId, destinationAssetId) {
+    const sourceMetadata = await engine.metadata.artifacts.read(sourceAssetId, "original");
+    if (!sourceMetadata.ok) {
+        if (sourceMetadata.error.code === "NOT_FOUND")
+            return;
+        throw new Error(sourceMetadata.error.message);
+    }
+    const metadataWrite = await engine.metadata.artifacts.write(destinationAssetId, "original", sourceMetadata.value);
+    if (!metadataWrite.ok)
+        throw new Error(metadataWrite.error.message);
+}
+export function duplicateAssetDef(engine) {
+    return {
+        name: "duplicate_asset",
+        description: "Duplicate a media asset and place its notebook cell at an optional destination or directly below the source",
+        schema: {
+            asset_id: z.string().describe("Artifact id to duplicate"),
+            book_id: z.string().describe("Book UUID"),
+            new_name: z.string().optional().describe("Optional custom name for the copy"),
+            notebook_id: z.string().uuid().optional().describe("Open notebook receiving the duplicate cell"),
+            destination: destinationSchema.optional(),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id: _book_id, destination, new_name, notebook_id, } = args;
+            const sourceArtifact = engine.artifacts.get(asset_id);
+            if (!sourceArtifact.ok) {
+                return failure(sourceArtifact.error.message);
+            }
+            const manifestResult = await engine.files.manifest(asset_id);
+            if (!manifestResult.ok) {
+                return failure(manifestResult.error.message);
+            }
+            const name = new_name
+                ?? (sourceArtifact.value.label ? `${sourceArtifact.value.label} copy` : undefined);
+            const cellType = mediaCellType(sourceArtifact.value.kind);
+            if (destination && !notebook_id) {
+                return failure("A duplicate destination requires notebook_id");
+            }
+            if (notebook_id) {
+                if (!cellType) {
+                    return failure(`A ${sourceArtifact.value.kind} artifact cannot be placed in a media cell`);
+                }
+                const notebook = engine.notebooks.read(notebook_id);
+                if (!notebook.ok)
+                    return failure(notebook.error.message);
+                try {
+                    duplicateDestination(notebook.value, sourceCellForArtifact(notebook.value, asset_id, cellType), destination);
+                }
+                catch (cause) {
+                    return failure(cause instanceof Error ? cause.message : String(cause));
+                }
+            }
+            const createResult = await engine.artifacts.create({
+                kind: sourceArtifact.value.kind,
+                ...(name ? { label: name } : {}),
+            });
+            if (!createResult.ok) {
+                return failure(createResult.error.message);
+            }
+            const newAssetId = createResult.value.artifactId;
+            for (const file of manifestResult.value.files) {
+                const readResult = await engine.files.read(asset_id, file.name);
+                if (!readResult.ok) {
+                    await engine.artifacts.delete(newAssetId);
+                    return failure(readResult.error.message);
+                }
+                const writeResult = await engine.files.write(newAssetId, file.name, readResult.value);
+                if (!writeResult.ok) {
+                    await engine.artifacts.delete(newAssetId);
+                    return failure(writeResult.error.message);
+                }
+            }
+            // Tags transfer after the bytes: the engine only lets automatic
+            // evidence cross when the copy actually carries the analyzed content.
+            const tagTransfer = { value: EMPTY_TRANSFER_SUMMARY };
+            try {
+                await copyOriginalMetadata(engine, asset_id, newAssetId);
+                tagTransfer.value = await transferAssetTags({ engine, artifactId: asset_id }, { engine, artifactId: newAssetId });
+            }
+            catch (cause) {
+                await engine.artifacts.delete(newAssetId);
+                return failure(cause instanceof Error ? cause.message : String(cause));
+            }
+            const placement = { cell: null };
+            if (notebook_id && cellType) {
+                try {
+                    const notebookResult = await mutateNotebook(engine, notebook_id, "duplicate_asset", (notebook) => {
+                        const slot = duplicateDestination(notebook, sourceCellForArtifact(notebook, asset_id, cellType), destination);
+                        placement.cell = engine.notebooks.createCell({
+                            type: cellType,
+                            ...(name ? { label: name } : {}),
+                            slot,
+                            inputs: {
+                                sourceOperation: "duplicate_asset",
+                                sourceArtifactId: asset_id,
+                                state: "completed",
+                            },
+                            outputArtifactId: newAssetId,
+                        });
+                        return {
+                            ...notebook,
+                            cells: [...notebook.cells, placement.cell],
+                        };
+                    }, {
+                        sourceArtifactId: asset_id,
+                        newArtifactId: newAssetId,
+                        destination: destination ?? null,
+                    }, { artifactId: newAssetId });
+                    if (!notebookResult.ok)
+                        throw new Error(notebookResult.error.message);
+                }
+                catch (cause) {
+                    await engine.artifacts.delete(newAssetId);
+                    return failure(cause instanceof Error ? cause.message : String(cause));
+                }
+            }
+            await enqueueSearchIndex(engine, newAssetId);
+            const createdCell = placement.cell;
+            const address = createdCell ? notebookGridTag(createdCell.slot) : null;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            source_asset_id: asset_id,
+                            new_asset_id: newAssetId,
+                            kind: sourceArtifact.value.kind,
+                            tags: tagTransfer.value,
+                            ...(createdCell && notebook_id
+                                ? {
+                                    notebook_id,
+                                    cell_id: createdCell.id,
+                                    address,
+                                    message: `Duplicated as ${address}`,
+                                }
+                                : { message: "Asset duplicated" }),
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/edit-timeline.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { timelineFailure, timelineSuccess, writeTimeline, } from "../timeline-helpers.js";
+const slotSchema = z.object({
+    id: z.string().uuid().optional(),
+    artifact_id: z.string().uuid(),
+    volume: z.number().min(0).optional(),
+    audioFadeIn: z.number().min(0).optional(),
+    audioFadeOut: z.number().min(0).optional(),
+});
+const audioSchema = z.object({
+    id: z.string().uuid().optional(),
+    artifact_id: z.string().uuid(),
+    startFrame: z.number().int().min(0),
+    durationFrames: z.number().int().positive(),
+    volume: z.number().min(0).optional(),
+    fadeIn: z.number().min(0).optional(),
+    fadeOut: z.number().min(0).optional(),
+});
+export function setTimelineDef(engine) {
+    return {
+        name: "set_timeline",
+        description: "Replace a book's typed v2 timeline using stable artifact UUIDs",
+        schema: {
+            book_id: z.string().uuid(),
+            render: z.enum(["landscape", "portrait", "square"]),
+            slots: z.array(slotSchema).optional(),
+            audio: z.array(audioSchema).optional(),
+        },
+        handler: async (args) => {
+            const slots = args.slots;
+            const audio = args.audio;
+            const input = {
+                render: args.render,
+                ...(slots === undefined ? {} : {
+                    slots: slots.map((slot) => ({
+                        ...(slot.id ? { id: slot.id } : {}),
+                        artifactId: slot.artifact_id,
+                        ...(slot.volume === undefined ? {} : { volume: slot.volume }),
+                        ...(slot.audioFadeIn === undefined ? {} : { audioFadeIn: slot.audioFadeIn }),
+                        ...(slot.audioFadeOut === undefined ? {} : { audioFadeOut: slot.audioFadeOut }),
+                    })),
+                }),
+                ...(audio === undefined ? {} : {
+                    audio: audio.map((clip) => ({
+                        ...(clip.id ? { id: clip.id } : {}),
+                        artifactId: clip.artifact_id,
+                        startFrame: clip.startFrame,
+                        durationFrames: clip.durationFrames,
+                        ...(clip.volume === undefined ? {} : { volume: clip.volume }),
+                        ...(clip.fadeIn === undefined ? {} : { fadeIn: clip.fadeIn }),
+                        ...(clip.fadeOut === undefined ? {} : { fadeOut: clip.fadeOut }),
+                    })),
+                }),
+            };
+            const result = await writeTimeline(engine, input);
+            return result.ok ? timelineSuccess(result.value) : timelineFailure(result.error.message);
+        },
+    };
+}

package/dist/tools/editing-moments.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { findPrimaryMediaFile } from "videobook-engine";
+import { MOMENTS_MAX_SCAN_SECONDS, MOMENTS_MIN_MOMENT_SECONDS, editingMomentsId, readEditingMoments, } from "../editing-moments.js";
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function failure(error) {
+    return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+}
+const readSchema = z.object({ book_id: z.string().uuid(), asset_id: z.string().uuid() });
+const analyzeSchema = readSchema.extend({
+    start_seconds: z.number().nonnegative().optional(),
+    end_seconds: z.number().positive().optional(),
+    force: z.boolean().optional(),
+});
+export function editingMomentsDefs(engine) {
+    const schema = { book_id: z.string().uuid(), asset_id: z.string().uuid() };
+    return [
+        {
+            name: "analyze_editing_moments",
+            description: "Analyze footage for editing in a background job: shot boundaries, per-shot motion, subject changes, usable ranges and ranked source moments, reused for unchanged sources. Read the results with get_editing_moments.",
+            scope: "book",
+            schema: {
+                ...schema,
+                start_seconds: z.number().nonnegative().optional(),
+                end_seconds: z.number().positive().optional(),
+                force: z.boolean().optional(),
+            },
+            handler: async (input) => {
+                try {
+                    const args = analyzeSchema.parse(input);
+                    const source = await momentsSource(engine, args.asset_id, {
+                        startSeconds: args.start_seconds, endSeconds: args.end_seconds,
+                    });
+                    if (!args.force && await readEditingMoments(engine, args.asset_id, source.momentsId)) {
+                        return json(await readState(engine, args.asset_id, args.start_seconds, args.end_seconds));
+                    }
+                    await queue.enqueue(`editing-moments-${source.momentsId}`, {
+                        type: "analyze_editing_moments", bookId: args.book_id, assetId: args.asset_id,
+                        startSeconds: source.startSeconds, endSeconds: source.endSeconds,
+                    });
+                    return json(await readState(engine, args.asset_id, args.start_seconds, args.end_seconds));
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            },
+        },
+        {
+            name: "get_editing_moments",
+            description: "Read cached editing moments (shot boundaries, motion, ranked source moments) for the current video source",
+            scope: "book", schema,
+            handler: async (args) => {
+                try {
+                    return json(await readState(engine, String(args.asset_id)));
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            },
+        },
+    ];
+}
+async function momentsSource(engine, artifactId, args = {}) {
+    const artifact = engine.artifacts.get(artifactId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    if (!["video", "final"].includes(artifact.value.kind))
+        throw new Error("Choose a video source to analyze");
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const file = findPrimaryMediaFile(manifest.value.files, artifact.value.kind);
+    const streams = engine.streams.list(artifactId);
+    if (!streams.ok)
+        throw new Error(streams.error.message);
+    const stream = streams.value.find((item) => item.kind === "video" && item.sourcePath === file?.name
+        && item.objectHash === file?.objectHash);
+    if (!stream || !file)
+        throw new Error("Wait for the current video source to finish processing");
+    const durationSeconds = stream.durationTicks * stream.timeBase.numerator / stream.timeBase.denominator;
+    if (!(durationSeconds > 0) || durationSeconds > MOMENTS_MAX_SCAN_SECONDS) {
+        throw new Error(`Moment analysis supports video up to ${MOMENTS_MAX_SCAN_SECONDS / 60} minutes`);
+    }
+    const startSeconds = Math.min(Math.max(0, args.startSeconds ?? 0), Math.max(0, durationSeconds - MOMENTS_MIN_MOMENT_SECONDS));
+    const endSeconds = args.endSeconds === undefined ? durationSeconds : Math.min(Math.max(startSeconds + MOMENTS_MIN_MOMENT_SECONDS, args.endSeconds), durationSeconds);
+    const momentsId = editingMomentsId({ objectHash: stream.objectHash, streamIndex: stream.streamIndex, startSeconds, endSeconds });
+    return { momentsId, startSeconds, endSeconds };
+}
+async function readState(engine, artifactId, startSeconds, endSeconds) {
+    const source = await momentsSource(engine, artifactId, { startSeconds, endSeconds });
+    const cached = await readEditingMoments(engine, artifactId, source.momentsId);
+    const jobs = engine.jobs.queue.list({ type: "analyze_editing_moments", limit: 500 });
+    const job = jobs.filter((item) => item.payload.assetId === artifactId)
+        .sort((left, right) => right.id - left.id)[0];
+    const pending = job && ["queued", "running", "completing"].includes(job.state);
+    const status = cached ? "ready"
+        : pending ? job.state === "queued" ? "queued" : "analyzing"
+            : job?.state === "aborted" ? "cancelled" : job?.state === "failed" ? "failed" : "missing";
+    return {
+        status, momentsId: source.momentsId, jobId: job?.id ?? null,
+        error: job?.error?.message ?? null, moments: cached,
+    };
+}