videobook 0.0.0-stage → 0.2.0

package/dist/jobs/_audio-chunks.js

@@ -0,0 +1,31 @@
+import { runFfmpeg } from "../ffmpeg.js";
+// Start offsets (seconds) of sequential fixed-size chunks covering `duration`.
+export function chunkStarts(duration, chunkSeconds) {
+    if (!Number.isFinite(duration) || duration <= 0)
+        return [0];
+    const count = Math.max(1, Math.ceil(duration / chunkSeconds));
+    return Array.from({ length: count }, (_, index) => index * chunkSeconds);
+}
+// Clamped length (seconds) of the chunk starting at `start`, with a 0.1s floor
+// so a near-zero tail still produces a decodable extract.
+export function chunkLength(duration, start, chunkSeconds) {
+    if (duration <= 0)
+        return 0;
+    return Math.max(0.1, Math.min(chunkSeconds, duration - start));
+}
+// Extract a mono 16kHz mp3 segment of `mediaPath` to `chunkPath`.
+export async function extractAudioChunk(mediaPath, start, duration, chunkPath) {
+    await runFfmpeg([
+        "-y",
+        ...(start > 0 ? ["-ss", String(start)] : []),
+        ...(duration > 0 ? ["-t", String(duration)] : []),
+        "-i", mediaPath,
+        "-vn",
+        "-ac", "1",
+        "-ar", "16000",
+        "-acodec", "libmp3lame",
+        "-q:a", "5",
+        "-f", "mp3",
+        chunkPath,
+    ]);
+}

package/dist/jobs/_download-into-asset.js

@@ -0,0 +1,15 @@
+// Fetch `url`, write the response bytes to the given asset file, and return
+// the buffer for callers that need it (e.g. for content-hash provenance).
+// `options.kind` only changes the error-message wording.
+export async function downloadUrlIntoAsset(engine, url, assetId, filename, options = {}) {
+    const response = await fetch(url, options.fetchInit);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${options.kind ?? "file"}: ${response.status} ${response.statusText}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const written = await engine.files.write(assetId, filename, buffer);
+    if (!written.ok) {
+        throw new Error(`Failed to persist ${options.kind ?? "file"}: ${written.error.message}`);
+    }
+    return buffer;
+}

package/dist/jobs/_fal-shared.js

@@ -0,0 +1,22 @@
+import { FalError } from "@apicity/fal";
+export function describeFalError(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (!(cause instanceof FalError))
+        return message;
+    if (!cause.body || typeof cause.body !== "object")
+        return message;
+    const raw = cause.body.detail;
+    const detail = typeof raw === "string" ? raw : Array.isArray(raw) ? raw.slice(0, 8).flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const { loc, msg } = item;
+        if (typeof msg !== "string")
+            return [];
+        const path = Array.isArray(loc) ? loc.filter((part) => typeof part === "string" || typeof part === "number")
+            .filter((part) => part !== "body").join(".") : "";
+        return [path ? `${path}: ${msg}` : msg];
+    }).join("; ") : "";
+    if (detail.length === 0 || message.includes(detail))
+        return message;
+    return `${message}: ${detail.slice(0, 2000)}`;
+}

package/dist/jobs/_fal-upload.js

@@ -0,0 +1,35 @@
+import { createFal } from "../usage-providers.js";
+import { uploadFile } from "@apicity/fal";
+import { prepareAssetForUpload, uploadBytesToFreeHost, } from "../upload.js";
+import { getApiKey } from "../api-key.js";
+import { logger } from "../logger.js";
+// Upload prepared bytes to fal's native CDN via @apicity/fal's uploadFile
+// helper. Returns a stable https://v3.fal.media/... URL. Falls back to the
+// free-host rotation on any native failure (missing key, network, non-2xx).
+async function uploadPreparedToFal(data, hashedFilename, contentType) {
+    const apiKey = getApiKey("FAL_API_KEY");
+    if (apiKey) {
+        try {
+            const provider = createFal({ apiKey, timeout: 60_000 });
+            return await uploadFile(provider, {
+                data,
+                filename: hashedFilename,
+                contentType,
+            });
+        }
+        catch (err) {
+            logger.warn("fal-upload-fallback", { error: err });
+        }
+    }
+    else {
+        logger.warn("fal-upload-unconfigured");
+    }
+    return uploadBytesToFreeHost(data, hashedFilename);
+}
+// Upload an asset file to fal's official CDN via storage.upload.initiate.
+// Returns a stable https://v3.fal.media/... URL that fal's own model endpoints
+// can fetch directly — no third-party free-host dependency.
+export async function uploadAssetToFal(engine, assetId, filename) {
+    const { data, hashedFilename, contentType } = await prepareAssetForUpload(engine, assetId, filename);
+    return uploadPreparedToFal(data, hashedFilename, contentType);
+}

package/dist/jobs/_image-edit-adapter.js

@@ -0,0 +1,213 @@
+import { createFal } from "../usage-providers.js";
+import { submitMediaJob } from "@apicity/kie";
+import { FalError } from "@apicity/fal";
+import { SeedreamProImageToImageRequestSchema } from "@apicity/kie/zod";
+import { setTimeout as delay } from "node:timers/promises";
+import sharp from "sharp";
+import { requireApiKey } from "../api-key.js";
+import { IMAGE_EDIT_MODELS } from "../image-edit-models.js";
+import { resolveModel } from "../media/descriptor.js";
+import { buildWireRequest } from "../media/request.js";
+import { mintKieOtp } from "./kie-paygate.js";
+import { uploadAssetToFal } from "./_fal-upload.js";
+import { uploadAssetToKie } from "./_kie-upload.js";
+import { KIE_RESULT_TIMEOUT_MS, kieProvider, parseResultUrls, waitForKieResult, } from "./_kie-poll.js";
+const FAL_RESULT_TIMEOUT_MS = 25 * 60_000;
+export const GROK_EXACT_MASK_ADAPTER_ID = "grok-imagine-image-2-0/image-edit";
+function closestAspectRatio(width, height) {
+    const target = width / height;
+    const candidates = [
+        ["1:1", 1],
+        ["4:3", 4 / 3],
+        ["3:4", 3 / 4],
+        ["16:9", 16 / 9],
+        ["9:16", 9 / 16],
+        ["2:3", 2 / 3],
+        ["3:2", 3 / 2],
+    ];
+    return candidates.reduce((best, candidate) => Math.abs(candidate[1] - target) < Math.abs(best[1] - target)
+        ? candidate
+        : best)[0];
+}
+export function seedreamRegionReplacementRequest(input) {
+    const parsed = SeedreamProImageToImageRequestSchema.parse({
+        model: "seedream/5-pro-image-to-image",
+        input: {
+            image_urls: [...input.imageUrls],
+            prompt: input.prompt,
+            aspect_ratio: closestAspectRatio(input.width, input.height),
+            quality: "basic",
+            output_format: "png",
+            nsfw_checker: false,
+        },
+    });
+    return { model: parsed.model, input: { ...parsed.input } };
+}
+export async function downloadResultImages(urls, signal, label) {
+    const images = [];
+    for (const [index, url] of urls.entries()) {
+        const response = await fetch(url, { signal });
+        if (!response.ok) {
+            throw new Error(`Failed to download ${label} ${index + 1}: ${response.status} ${response.statusText}`);
+        }
+        images.push(await sharp(Buffer.from(await response.arrayBuffer())).png().toBuffer());
+    }
+    return images;
+}
+function toProviderRequest(model, input) {
+    return { model, input };
+}
+function falNamespace(endpointId) {
+    return endpointId.split("/").slice(0, 2).join("/");
+}
+function falResultImageUrls(resultObject) {
+    const images = resultObject.images;
+    if (!Array.isArray(images))
+        return [];
+    return images
+        .map((image) => (typeof image === "object" && image !== null && "url" in image
+        ? image.url
+        : undefined))
+        .filter((url) => typeof url === "string");
+}
+function optionsFor(model, input) {
+    const options = {};
+    const aspect = model.options.find((option) => option.name === "aspect_ratio");
+    const closest = closestAspectRatio(input.width, input.height);
+    if (aspect?.enumValues.includes(closest))
+        options.aspect_ratio = closest;
+    const format = model.options.find((option) => option.name === "output_format");
+    if (format?.enumValues.includes("png"))
+        options.output_format = "png";
+    return options;
+}
+function catalogEditRequest(model, input) {
+    const built = buildWireRequest(model, {
+        prompt: input.prompt,
+        refUrls: { image: [...input.imageUrls] },
+        options: optionsFor(model, input),
+    });
+    if (!built.ok)
+        throw new Error(built.error);
+    return built.request;
+}
+function kieImageEditAdapter(model, build) {
+    const parse = (value) => model.wire.request.safeParse(value);
+    const buildRequest = build ?? ((input) => {
+        const request = catalogEditRequest(model, input);
+        return toProviderRequest(request.model, { ...request.input });
+    });
+    return {
+        id: model.apiId,
+        uploadAsset: (engine, artifactId, filename) => uploadAssetToKie(engine, artifactId, filename),
+        buildSemanticRequest: (input) => buildRequest({ ...input, imageUrls: [input.imageUrls[0]] }),
+        buildRegionRequest: buildRequest,
+        submit: async (engine, imageAssetId, request) => {
+            const parsed = parse(request);
+            if (!parsed.success)
+                throw new Error(`Invalid ${model.id} image edit request`);
+            const metadata = await engine.metadata.artifacts.write(imageAssetId, "generation-payload", parsed.data);
+            if (!metadata.ok)
+                throw new Error(metadata.error.message);
+            const taskId = await submitMediaJob(kieProvider(), parsed.data, {
+                otp: mintKieOtp(parsed.data),
+            });
+            const taskMetadata = await engine.metadata.artifacts.write(imageAssetId, "kie-task-id", { taskId });
+            if (!taskMetadata.ok)
+                throw new Error(taskMetadata.error.message);
+            return taskId;
+        },
+        awaitResult: async (taskId, signal) => {
+            const resultJson = await waitForKieResult(kieProvider(), taskId, signal, Date.now() + KIE_RESULT_TIMEOUT_MS, "subject-edit");
+            const urls = parseResultUrls(resultJson);
+            return downloadResultImages(urls, signal, `${model.apiId} edit`);
+        },
+        parseStoredPayload: (payload) => {
+            const parsed = parse(payload);
+            if (!parsed.success)
+                return null;
+            return toProviderRequest(parsed.data.model, { ...parsed.data.input });
+        },
+    };
+}
+async function awaitFalImages(model, taskId, signal) {
+    const provider = createFal({ apiKey: requireApiKey("FAL_API_KEY"), timeout: 30_000 });
+    const namespace = falNamespace(model.apiId);
+    const deadlineAt = Date.now() + FAL_RESULT_TIMEOUT_MS;
+    for (;;) {
+        if (Date.now() >= deadlineAt) {
+            throw new Error(`Fal task ${taskId} did not finish within 25 minutes`);
+        }
+        let status;
+        try {
+            status = await provider.v1.queue.status({ endpoint_id: namespace, request_id: taskId });
+        }
+        catch (cause) {
+            if (cause instanceof FalError && cause.status >= 400 && cause.status < 500)
+                throw cause;
+            await delay(Math.min(3_000, Math.max(1, deadlineAt - Date.now())), undefined, { signal });
+            continue;
+        }
+        if (status.status === "COMPLETED") {
+            if (status.error) {
+                throw new Error(`Fal image edit failed: ${status.error}`);
+            }
+            const result = await provider.v1.queue.result({ endpoint_id: namespace, request_id: taskId });
+            const urls = falResultImageUrls(result);
+            if (urls.length === 0)
+                throw new Error(`${model.apiId} image edit returned no image`);
+            return downloadResultImages(urls, signal, `${model.apiId} edit`);
+        }
+        await delay(Math.min(3_000, Math.max(1, deadlineAt - Date.now())), undefined, { signal });
+    }
+}
+function falImageEditAdapter(model) {
+    const parse = (value) => model.wire.input.safeParse(value);
+    const buildRequest = (input) => toProviderRequest(model.apiId, catalogEditRequest(model, input));
+    return {
+        id: model.apiId,
+        uploadAsset: (engine, artifactId, filename) => uploadAssetToFal(engine, artifactId, filename),
+        buildSemanticRequest: (input) => buildRequest({ ...input, imageUrls: [input.imageUrls[0]] }),
+        buildRegionRequest: buildRequest,
+        submit: async (engine, imageAssetId, request) => {
+            const parsed = parse(request.input);
+            if (!parsed.success)
+                throw new Error(`Invalid ${model.id} image edit request`);
+            const input = parsed.data;
+            const provider = createFal({ apiKey: requireApiKey("FAL_API_KEY"), timeout: 60_000 });
+            const metadata = await engine.metadata.artifacts.write(imageAssetId, "generation-payload", { endpoint_id: model.apiId, input });
+            if (!metadata.ok)
+                throw new Error(metadata.error.message);
+            const submitted = await provider.post.v1.queue.submit({ endpoint_id: model.apiId, input });
+            const taskMetadata = await engine.metadata.artifacts.write(imageAssetId, "kie-task-id", { taskId: submitted.request_id });
+            if (!taskMetadata.ok)
+                throw new Error(taskMetadata.error.message);
+            return submitted.request_id;
+        },
+        awaitResult: (taskId, signal) => awaitFalImages(model, taskId, signal),
+        parseStoredPayload: (payload) => {
+            if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+                return null;
+            if (!("endpoint_id" in payload) || payload.endpoint_id !== model.apiId)
+                return null;
+            if (!("input" in payload))
+                return null;
+            const parsed = parse(payload.input);
+            if (!parsed.success)
+                return null;
+            return toProviderRequest(model.apiId, { ...parsed.data });
+        },
+    };
+}
+function adapterForEditModel(info) {
+    const model = resolveModel(info.catalogModel);
+    if (info.provider === "fal")
+        return falImageEditAdapter(model);
+    if (model.apiId === "seedream/5-pro-image-to-image")
+        return kieImageEditAdapter(model, seedreamRegionReplacementRequest);
+    return kieImageEditAdapter(model);
+}
+export const IMAGE_EDIT_ADAPTERS = IMAGE_EDIT_MODELS.map(adapterForEditModel);
+export function imageEditAdapter(id) {
+    return IMAGE_EDIT_ADAPTERS.find((adapter) => adapter.id === id);
+}

package/dist/jobs/_kie-poll.js

@@ -0,0 +1,119 @@
+import { createKie } from "../usage-providers.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { requireApiKey } from "../api-key.js";
+import { subjectAnalysisProviderFailureMessage } from "../image-subject-map.js";
+import { ensurePaygateSecret } from "./kie-paygate.js";
+export const KIE_RESULT_TIMEOUT_MS = 25 * 60_000;
+export function kieProvider() {
+    return createKie({
+        apiKey: requireApiKey("KIE_API_KEY"),
+        timeout: 60_000,
+        paygate: { secret: ensurePaygateSecret() },
+    });
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function abortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    const error = new Error(typeof signal.reason === "string" ? signal.reason : "Operation aborted");
+    error.name = "AbortError";
+    return error;
+}
+function waitForOperation(operation, signal, deadlineAt, timeoutError) {
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    const remaining = deadlineAt - Date.now();
+    if (remaining <= 0)
+        return Promise.reject(timeoutError);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+        };
+        const resolveOnce = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const rejectOnce = (cause) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(cause);
+        };
+        const onAbort = () => rejectOnce(abortReason(signal));
+        const timer = setTimeout(() => rejectOnce(timeoutError), remaining);
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        void operation.then(resolveOnce, rejectOnce);
+    });
+}
+function kieResultFailureMessage(context, message, code) {
+    if (context === "subject-analysis") {
+        return subjectAnalysisProviderFailureMessage(message, code);
+    }
+    const detail = message || code || "Unknown provider error";
+    const codeDetail = code && code !== detail ? ` (${code})` : "";
+    return `Image subject edit provider failed: ${detail}${codeDetail}`;
+}
+export async function waitForKieResult(provider, taskId, signal, deadlineAt, context) {
+    const timeoutError = context === "subject-analysis"
+        ? new Error("Subject analysis did not finish within 25 minutes. Retry the analysis.")
+        : new Error(`Kie task ${taskId} did not finish within 25 minutes`);
+    while (Date.now() < deadlineAt) {
+        const result = await waitForOperation(provider.get.api.v1.jobs.recordInfo(taskId), signal, deadlineAt, timeoutError);
+        const state = result.data?.state?.toLowerCase();
+        if (state === "success") {
+            if (!result.data?.resultJson) {
+                throw new Error("Kie task succeeded without result JSON");
+            }
+            return result.data.resultJson;
+        }
+        if (state === "fail" || state === "failed") {
+            throw new Error(kieResultFailureMessage(context, stringValue(result.data?.failMsg), stringValue(result.data?.failCode)));
+        }
+        await delay(Math.min(3_000, Math.max(1, deadlineAt - Date.now())), undefined, {
+            signal,
+        });
+    }
+    throw timeoutError;
+}
+export function parseResultUrls(resultJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(resultJson);
+    }
+    catch {
+        throw new Error("Seedream returned invalid result JSON");
+    }
+    const root = record(parsed);
+    if (!root)
+        throw new Error("Seedream returned an invalid image result");
+    for (const value of [
+        root.resultUrls,
+        root.result_urls,
+        record(root.resultObject)?.resultUrls,
+        record(root.resultObject)?.result_urls,
+        record(root.result)?.resultUrls,
+        record(root.result)?.result_urls,
+    ]) {
+        if (!Array.isArray(value))
+            continue;
+        const urls = value.flatMap((entry) => stringValue(entry) ?? []);
+        if (urls.length > 0)
+            return urls;
+    }
+    throw new Error("Seedream image edit returned no downloadable images");
+}

package/dist/jobs/_kie-upload.js

@@ -0,0 +1,32 @@
+import { createKie } from "../usage-providers.js";
+import { uploadFile } from "@apicity/kie";
+import { prepareAssetForUpload, uploadBytesToFreeHost, } from "../upload.js";
+import { getApiKey } from "../api-key.js";
+import { logger } from "../logger.js";
+// Upload prepared bytes to Kie's native storage via POST /api/file-stream-upload.
+// Kie workers run in China — using their first-party CDN avoids the
+// InvalidParameter.DataInspection failures we'd hit when the free-host URL
+// is unreachable from their side. Falls back to the free-host rotation only
+// if the native endpoint fails (missing key, timeout, 5xx, etc.).
+async function uploadPreparedToKie(data, hashedFilename, contentType) {
+    const apiKey = getApiKey("KIE_API_KEY");
+    if (apiKey) {
+        try {
+            const provider = createKie({ apiKey, timeout: 120_000 });
+            const blob = new Blob([new Uint8Array(data)], { type: contentType });
+            return await uploadFile(provider, blob, hashedFilename);
+        }
+        catch (err) {
+            logger.warn("kie-upload-fallback", { error: err });
+        }
+    }
+    else {
+        logger.warn("kie-upload-unconfigured");
+    }
+    return uploadBytesToFreeHost(data, hashedFilename);
+}
+// Upload an asset to Kie's native storage.
+export async function uploadAssetToKie(engine, assetId, filename) {
+    const { data, hashedFilename, contentType } = await prepareAssetForUpload(engine, assetId, filename);
+    return uploadPreparedToKie(data, hashedFilename, contentType);
+}

package/dist/jobs/_lease.js

@@ -0,0 +1,163 @@
+import { logger } from "../logger.js";
+const HEARTBEAT_INTERVAL_MS = 20_000;
+const HEARTBEAT_EXTEND_MS = 60_000;
+const DEFAULT_LEASE_MS = 15 * 60_000;
+export const DOWNSTREAM_LEASE_WAIT_MS = 60_000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function beginLocalLease(engine, assetId, kind, options, signal) {
+    const started = Date.now();
+    const waitForActiveMs = options.waitForActiveMs ?? 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const lease = await engine.jobs.artifactWork.begin(assetId, {
+            kind,
+            ownerKind: "job",
+            durationMs: options.durationMs ?? DEFAULT_LEASE_MS,
+            ...(options.meta ? { meta: options.meta } : {}),
+        });
+        if (lease)
+            return lease;
+        if (Date.now() - started >= waitForActiveMs)
+            return null;
+        await leaseSleep(250);
+    }
+}
+/**
+ * Pattern A — Provider handoff. Claim a local job lease, run the submission
+ * work (upload/build/submit), then atomically hand off to the provider lease
+ * via `pendingTasks.write(expectedOwnerId)`. The handler returns the freshly
+ * minted task_id; this helper transitions the wrapper's lease token from
+ * `{kind:'owner'}` to `{kind:'task'}` so a late crash CAS-fails by task_id.
+ *
+ * `fn` receives the local owner_id; it must pass that as the
+ * `expectedOwnerId` to `pendingTasks.write` and return the task_id the
+ * provider returned.
+ */
+export async function withProviderHandoff(engine, assetId, ctx, kind, fn, options = {}) {
+    let ownerId = null;
+    let ownsLease = false;
+    try {
+        ownerId = ctx.getOwnerId();
+    }
+    catch {
+        ownerId = null;
+    }
+    if (!ownerId) {
+        const lease = await beginLocalLease(engine, assetId, kind, options, ctx.signal);
+        if (!lease) {
+            throw new Error(`could not claim local lease for ${assetId}: active owner already holds it`);
+        }
+        ownerId = lease.ownerId;
+        ownsLease = true;
+        ctx.setLease({ kind: "owner", ownerId });
+    }
+    const activeOwnerId = ownerId;
+    const heartbeat = ownsLease
+        ? setInterval(() => {
+            try {
+                engine.jobs.artifactWork.renew(assetId, activeOwnerId, HEARTBEAT_EXTEND_MS);
+            }
+            catch (error) {
+                logger.warn("heartbeat-failed", { assetId, error });
+            }
+        }, HEARTBEAT_INTERVAL_MS)
+        : null;
+    try {
+        const { taskId, result } = await fn(activeOwnerId);
+        ctx.setLease({ kind: "task", taskId });
+        return result;
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+    }
+}
+/**
+ * Pattern B — Local-work handler. Claim a job lease, run the work end-to-end,
+ * call `completeAssetWork` on success or `failAssetWork` on throw. The
+ * handler doesn't need to touch pending_tasks at all.
+ */
+export async function withLocalLease(engine, assetId, ctx, kind, fn, options = {}) {
+    const lease = await beginLocalLease(engine, assetId, kind, options, ctx.signal);
+    if (!lease) {
+        throw new Error(`could not claim local lease for ${assetId}: active owner already holds it`);
+    }
+    ctx.setLease({ kind: "owner", ownerId: lease.ownerId });
+    const heartbeat = setInterval(() => {
+        try {
+            engine.jobs.artifactWork.renew(assetId, lease.ownerId, HEARTBEAT_EXTEND_MS);
+        }
+        catch (error) {
+            logger.warn("heartbeat-failed", { assetId, error });
+        }
+    }, HEARTBEAT_INTERVAL_MS);
+    try {
+        const result = await fn(lease.ownerId);
+        await engine.jobs.artifactWork.complete(assetId, lease.ownerId);
+        return result;
+    }
+    catch (err) {
+        await engine.jobs.artifactWork.fail(assetId, lease.ownerId, {
+            message: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+}
+export const CLAIM_RETRY_INTERVAL_MS = 1_000;
+let leaseSleep = defaultSleep;
+export function configureLeaseClockForTests(options) {
+    leaseSleep = options?.sleep ?? defaultSleep;
+}
+/**
+ * Claim the asset dir lock AND a local job lease together, polling both until
+ * `options.waitForActiveMs` elapses. Waiting (instead of failing fast)
+ * serializes workers that target the same asset — e.g. the three
+ * per-orientation render jobs the render tool enqueues at once — so
+ * latecomers run after the current holder finishes rather than erroring.
+ *
+ * On success the caller owns both and must itself complete/fail the lease
+ * and release the lock.
+ */
+export async function claimLockedLease(engine, assetId, assetDir, kind, lock, options = {}) {
+    const started = Date.now();
+    const waitForActiveMs = options.waitForActiveMs ?? 0;
+    let reason = "could not claim asset";
+    while (true) {
+        const lockResult = await engine.jobs.locks.acquire(assetDir, lock);
+        if (lockResult.ok) {
+            const lease = await engine.jobs.artifactWork.begin(assetId, {
+                kind,
+                ownerKind: "job",
+                durationMs: options.durationMs ?? DEFAULT_LEASE_MS,
+                ...(options.meta ? { meta: options.meta } : {}),
+            });
+            if (lease)
+                return { ok: true, ownerId: lease.ownerId };
+            engine.jobs.locks.release(assetDir);
+            reason = "active owner already holds asset lease";
+        }
+        else {
+            reason = `Asset is locked: ${lockResult.error.message}`;
+        }
+        if (Date.now() - started >= waitForActiveMs)
+            return { ok: false, reason };
+        await leaseSleep(CLAIM_RETRY_INTERVAL_MS);
+    }
+}
+export async function withLockedLocalLease(engine, assetId, assetDir, ctx, kind, lock, fn, options = {}) {
+    const lockResult = await engine.jobs.locks.acquire(assetDir, lock);
+    if (!lockResult.ok) {
+        throw new Error(`Asset is locked: ${lockResult.error.message}`);
+    }
+    try {
+        return await withLocalLease(engine, assetId, ctx, kind, fn, options);
+    }
+    finally {
+        engine.jobs.locks.release(assetDir);
+    }
+}

package/dist/jobs/_persist-output.js

@@ -0,0 +1,19 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+export async function ingestWorkspaceOutputs(engine, artifact, paths, operation, details = {}) {
+    const result = await engine.files.ingestWorkspace(artifact, paths, operation, details);
+    if (!result.ok) {
+        throw new Error(`Failed to ingest ${artifact} workspace output: ${result.error.message}`);
+    }
+    return result.value;
+}
+export async function replaceArtifactFileFromPath(engine, artifact, targetFilename, sourcePath) {
+    const result = await engine.files.writeFromPath(artifact, targetFilename, sourcePath);
+    if (!result.ok) {
+        throw new Error(`Failed to persist ${artifact}/${targetFilename}: ${result.error.message}`);
+    }
+    if (resolve(sourcePath) !== resolve(result.value)) {
+        await rm(sourcePath, { force: true });
+    }
+    return result.value;
+}

package/dist/jobs/_storage-retry.js

@@ -0,0 +1,21 @@
+import { setTimeout as delay } from "node:timers/promises";
+const RETRY_DELAYS_MS = [50, 200, 800, 2_000];
+export function isTransientStorageConflict(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /commit conflict: another connection committed/i.test(message);
+}
+export async function withTransientStorageRetry(operation, signal) {
+    for (let attempt = 0;; attempt += 1) {
+        signal?.throwIfAborted();
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const retryDelay = RETRY_DELAYS_MS[attempt];
+            if (retryDelay === undefined || !isTransientStorageConflict(error)) {
+                throw error;
+            }
+            await delay(retryDelay, undefined, signal ? { signal } : undefined);
+        }
+    }
+}