upscale4k 0.0.0-stage → 0.1.0

package/dist/api-contract.js

@@ -0,0 +1,24 @@
+/** Upscale4K REST v1 wire types and paths; align future server changes here. */
+export const DEFAULT_API_URL = "https://upscale4k.io";
+export const VERSION = "0.1.0";
+export const MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
+export const MIN_LONG_SIDE = 500;
+export const MAX_LONG_SIDE = 2560;
+export const paths = {
+    me: "/api/v1/me",
+    jobs: "/api/v1/jobs",
+    job: (id) => `/api/v1/jobs/${encodeURIComponent(id)}`,
+    submit: (id) => `${paths.job(id)}/submit`,
+    cancel: (id) => `${paths.job(id)}/cancel`,
+    retry: (id) => `${paths.job(id)}/retry`,
+    download: (id) => `${paths.job(id)}/download`,
+    multipart: (id) => `${paths.job(id)}/multipart`,
+};
+export const errorCodes = [
+    "invalid_api_key", "api_locked", "account_suspended", "rate_limited", "validation_error",
+    "duration_limit", "resolution_limit", "frame_rate_limit", "no_credits", "daily_limit", "active_limit",
+    "idempotency_required", "idempotency_mismatch", "not_found", "conflict", "expired",
+    "locked_for_review", "uploads_closed", "consent_required", "consent_outdated",
+    "range_not_satisfiable", "upgrade_required", "storage_unavailable", "engine_unavailable", "key_limit",
+];
+export const jobStates = ["uploading", "queued", "claimed", "running", "done", "failed", "rejected", "canceled", "expired"];

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/** Upscale4K terminal entry point; MCP mode reserves stdout for protocol messages. */
+import { parseArgs } from "node:util";
+import { ApiClient, ApiError } from "./api-client.js";
+import { VERSION } from "./api-contract.js";
+import { assertAccess, authenticated, logout, maskKey, saveConfig } from "./config-store.js";
+import { formatAccountLimits, formatJobLine, formatJobs } from "./job-status-format.js";
+import { startMcpServer } from "./mcp-server.js";
+import { ask, agree } from "./terminal-prompts.js";
+import { upscale } from "./upscale-runner.js";
+import { scanVideos } from "./scan-videos.js";
+const help = `upscale4k ${VERSION} — upscale local MP4/MOV videos to 4K
+Usage:
+  upscale4k login
+  upscale4k upscale <file|dir> --self-likeness <yes|no>
+    [--yes-self-likeness-consent] [--out <dir>] [--concurrency 3]
+    [--wait|--no-wait] [--json]
+  upscale4k status [job_id] [--json]
+  upscale4k credits [--json]
+  upscale4k logout
+  upscale4k mcp
+  upscale4k --version | --help
+Environment: UPSCALE4K_API_KEY, UPSCALE4K_API_URL
+Agents without a terminal: set UPSCALE4K_API_KEY; no login needed.
+Deprecated --accept-terms is accepted but has no effect.
+`;
+async function main() {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+            help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
+            "self-likeness": { type: "string" }, "yes-self-likeness-consent": { type: "boolean" },
+            out: { type: "string" }, concurrency: { type: "string" }, wait: { type: "boolean" },
+            "no-wait": { type: "boolean" }, json: { type: "boolean" }, "accept-terms": { type: "boolean" },
+        } });
+    if (values.version) {
+        console.log(VERSION);
+        return;
+    }
+    if (values.help || positionals.length === 0) {
+        console.log(help);
+        return;
+    }
+    const [command, input] = positionals;
+    if (command === "mcp") {
+        await startMcpServer();
+        return;
+    }
+    if (command === "logout") {
+        await logout();
+        console.log("Local login removed. UPSCALE4K_API_KEY, if set, still overrides local config.");
+        return;
+    }
+    if (command === "login") {
+        if (!process.env.UPSCALE4K_API_KEY && !process.stdin.isTTY)
+            throw new Error("Set UPSCALE4K_API_KEY to log in without a terminal.");
+        const key = process.env.UPSCALE4K_API_KEY || await ask("Upscale4K API key (hidden): ", true);
+        if (!/^cx_live_[A-Za-z0-9_-]+$/.test(key))
+            throw new Error("Invalid API key format.");
+        const account = await new ApiClient(key).me();
+        assertAccess(account);
+        await saveConfig({ key });
+        console.log(`Logged in (${maskKey(key)}).`);
+        return;
+    }
+    if (!["upscale", "status", "credits"].includes(command))
+        throw new Error(`Unknown command: ${command}. Use --help.`);
+    if (positionals.length > (command === "credits" ? 1 : 2))
+        throw new Error("Too many arguments. Use --help.");
+    if (command === "upscale" && (!input || !["yes", "no"].includes(values["self-likeness"] ?? ""))) {
+        throw new Error("Usage: upscale4k upscale <file|dir> --self-likeness <yes|no>");
+    }
+    if (values.wait && values["no-wait"])
+        throw new Error("Choose --wait or --no-wait.");
+    const controller = new AbortController();
+    const interrupt = () => controller.abort();
+    if (command === "upscale")
+        process.on("SIGINT", interrupt);
+    // Request timeouts use unref'd timers; without this a stalled fetch lets Node exit 0 mid-upload.
+    const keepAlive = setInterval(() => undefined, 60_000);
+    try {
+        const scan = command === "upscale" ? await scanVideos(input, values.out) : undefined;
+        const { client, account } = await authenticated({ signal: controller.signal });
+        if (command === "credits") {
+            console.log(JSON.stringify(account));
+            return;
+        }
+        if (command === "status") {
+            const value = input ? await client.getJob(input) : await client.listJobs();
+            if (!values.json && !input)
+                console.log(formatAccountLimits(account));
+            console.log(values.json ? JSON.stringify(value) : "jobs" in value ? formatJobs(value) : formatJobLine(value));
+            return;
+        }
+        const selfLikeness = values["self-likeness"] === "yes";
+        if (selfLikeness) {
+            if (!values["yes-self-likeness-consent"])
+                await agree(account.consent.self_likeness_statement);
+            else
+                process.stderr.write(`${account.consent.self_likeness_statement}\n`);
+        }
+        const result = await upscale(client, account, {
+            path: input, selfLikeness, selfLikenessConsent: selfLikeness,
+            outputDir: values.out, concurrency: values.concurrency === undefined ? 3 : Number(values.concurrency),
+            wait: !values["no-wait"], signal: controller.signal, scan,
+            onEvent: (event) => { console.log(values.json ? JSON.stringify(event) : `${event.event}: ${JSON.stringify(Object.fromEntries(Object.entries(event).filter(([key]) => key !== "event")))}`); },
+        });
+        if (result.stopped || result.results.some((item) => item.state === "failed"))
+            process.exitCode = 1;
+    }
+    finally {
+        clearInterval(keepAlive);
+        process.removeListener("SIGINT", interrupt);
+    }
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Command failed";
+    const code = error instanceof ApiError ? error.code : "cli_error";
+    if (process.argv.includes("--json") && !process.argv.includes("mcp"))
+        console.log(JSON.stringify({ event: "failed", code, message }));
+    else
+        process.stderr.write(`${code}: ${message}\n`);
+    process.exitCode = 1;
+});

package/dist/config-store.d.ts

@@ -0,0 +1,23 @@
+import { ApiClient } from "./api-client.js";
+import type { Account } from "./api-contract.js";
+export interface Config {
+    key: string;
+    terms_version?: string;
+    policy_version?: string;
+    accepted_at?: string;
+}
+export declare function configPath(): string;
+export declare function readConfig(path?: string): Promise<Config | undefined>;
+export declare function saveConfig(config: Config, path?: string): Promise<void>;
+export declare function logout(path?: string): Promise<void>;
+export declare const maskKey: (key: string) => string;
+export declare function assertAccess(account: Account): void;
+export declare function authenticated(options?: {
+    configFile?: string;
+    baseUrl?: string;
+    acceptTerms?: boolean;
+    signal?: AbortSignal;
+}): Promise<{
+    client: ApiClient;
+    account: Account;
+}>;

package/dist/config-store.js

@@ -0,0 +1,54 @@
+/** Store credentials locally; environment credentials take precedence. */
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { ApiClient, ApiError } from "./api-client.js";
+export function configPath() {
+    return process.platform === "win32"
+        ? join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "upscale4k", "config.json")
+        : join(homedir(), ".config", "upscale4k", "config.json");
+}
+export async function readConfig(path = configPath()) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error("Cannot read Upscale4K config; run npx upscale4k login.");
+    }
+}
+export async function saveConfig(config, path = configPath()) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    if (process.platform !== "win32")
+        await chmod(temporary, 0o600);
+    await rename(temporary, path);
+    if (process.platform !== "win32")
+        await chmod(path, 0o600);
+}
+export async function logout(path = configPath()) { await rm(path, { force: true }); }
+export const maskKey = (key) => `${key.slice(0, 12)}…`;
+export function assertAccess(account) {
+    if (!account.access.unlocked)
+        throw new ApiError("api_locked", account.access.reason ?? "API access is locked; check your Upscale4K account.");
+}
+export async function authenticated(options = {}) {
+    // An environment credential is sufficient, even when an old local config is unreadable.
+    const key = process.env.UPSCALE4K_API_KEY || (await readConfig(options.configFile))?.key;
+    if (!key)
+        throw new ApiError("invalid_api_key", "Set UPSCALE4K_API_KEY or run npx upscale4k login in a terminal first.");
+    const client = new ApiClient(key, { baseUrl: options.baseUrl });
+    try {
+        const account = await client.me(options.signal);
+        assertAccess(account);
+        return { client, account };
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.code === "invalid_api_key") {
+            throw new ApiError(error.code, "The API key was rejected; create a new key in your Upscale4K account and set UPSCALE4K_API_KEY.");
+        }
+        throw error;
+    }
+}

package/dist/job-status-format.d.ts

@@ -0,0 +1,6 @@
+/** Human-readable job status lines for `upscale4k status` without --json. */
+import type { Account, Job, JobList } from "./api-contract.js";
+export declare function formatAccountLimits(account: Account): string;
+/** One line per job: state first, then whatever the user can act on next. */
+export declare function formatJobLine(job: Job): string;
+export declare function formatJobs(list: JobList): string;

package/dist/job-status-format.js

@@ -0,0 +1,23 @@
+const when = (value) => value === undefined || value === null ? null : new Date(value).toLocaleString();
+const failure = (error) => !error ? null : typeof error === "string" ? error : error.message;
+export function formatAccountLimits(account) {
+    return `Active jobs: ${account.active_count} / ${account.max_active === null ? "unlimited" : account.max_active}`;
+}
+/** One line per job: state first, then whatever the user can act on next. */
+export function formatJobLine(job) {
+    const details = [
+        job.state === "queued" && job.queue_position != null ? `queue #${job.queue_position}` : null,
+        ["claimed", "running"].includes(job.state) && job.progress != null ? `${job.progress}%` : null,
+        job.state === "done" && job.expires_at != null ? `download before ${when(job.expires_at)}` : null,
+        failure(job.error),
+    ].filter(Boolean);
+    return `${job.state.padEnd(9)} ${job.id}  ${job.filename ?? "(no name)"}${details.length ? `  (${details.join(", ")})` : ""}`;
+}
+export function formatJobs(list) {
+    if (list.jobs.length === 0)
+        return "No jobs yet.";
+    const lines = list.jobs.map(formatJobLine);
+    if (list.next_cursor)
+        lines.push("More jobs exist; use --json for the full list cursor.");
+    return lines.join("\n");
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+interface Options {
+    configFile?: string;
+    baseUrl?: string;
+    pollMs?: number;
+    acceptTerms?: boolean;
+}
+export declare function createMcpServer(options?: Options): McpServer;
+export declare function startMcpServer(options?: Options): Promise<void>;
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,65 @@
+/** Expose five consent-aware tools over MCP without writing application logs to stdout. */
+import { basename, extname, join, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ApiError } from "./api-client.js";
+import { jobStates, VERSION } from "./api-contract.js";
+import { authenticated } from "./config-store.js";
+import { upscale } from "./upscale-runner.js";
+import { scanVideos } from "./scan-videos.js";
+export function createMcpServer(options = {}) {
+    const server = new McpServer({ name: "upscale4k", version: VERSION });
+    const context = (signal) => authenticated({ ...options, signal });
+    // Text keeps older clients working; structuredContent must be an object, so list results are wrapped.
+    const content = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }],
+        structuredContent: (value !== null && typeof value === "object" && !Array.isArray(value) ? value : { results: value }) });
+    async function guarded(operation) {
+        try {
+            return content(await operation());
+        }
+        catch (error) {
+            return { ...content({ error: { code: error instanceof ApiError ? error.code : "local_error", message: error instanceof Error ? error.message : "Tool failed" } }), isError: true };
+        }
+    }
+    server.registerTool("upscale_video", {
+        description: "Upscale local MP4/MOV files or a folder. Ask the user whether this upload contains their own likeness/voice (self_likeness); never guess. If true, obtain explicit self_likeness_consent to the account's statement. Authenticate with UPSCALE4K_API_KEY or npx upscale4k login.",
+        inputSchema: {
+            path: z.string().min(1), self_likeness: z.boolean(), self_likeness_consent: z.boolean().optional(),
+            output_dir: z.string().min(1).optional(), wait: z.boolean().default(true),
+        },
+    }, async (args, extra) => guarded(async () => {
+        const scan = await scanVideos(args.path, args.output_dir);
+        const { client, account } = await context(extra.signal);
+        let progress = 0;
+        const result = await upscale(client, account, {
+            path: args.path, selfLikeness: args.self_likeness, selfLikenessConsent: args.self_likeness_consent,
+            outputDir: args.output_dir, wait: args.wait, pollMs: options.pollMs, signal: extra.signal, scan,
+            onEvent: async (event) => {
+                const token = extra._meta?.progressToken;
+                if (args.wait && token !== undefined)
+                    await extra.sendNotification({ method: "notifications/progress",
+                        params: { progressToken: token, progress: ++progress, message: JSON.stringify(event) } });
+            },
+        });
+        const locked = result.results.find((item) => item.error?.startsWith("state_locked: "));
+        if (locked)
+            throw new ApiError("state_locked", locked.error.slice("state_locked: ".length));
+        return result.results;
+    }));
+    server.registerTool("get_job", { description: "Get Upscale4K job status.", inputSchema: { job_id: z.string().min(1) } }, ({ job_id }) => guarded(async () => (await context()).client.getJob(job_id)));
+    server.registerTool("list_jobs", { description: "List this account's Upscale4K jobs.", inputSchema: { state: z.enum(jobStates).optional(), limit: z.number().int().min(1).max(100).optional() } }, (args) => guarded(async () => (await context()).client.listJobs(args)));
+    server.registerTool("get_account", { description: "Get credits, tier, caps and exact consent statements. Ask the user about self_likeness for every upload; never guess.", inputSchema: {} }, () => guarded(async () => (await context()).account));
+    server.registerTool("download_result", { description: "Download a completed Upscale4K job to a local directory.", inputSchema: { job_id: z.string().min(1), output_dir: z.string().min(1) } }, ({ job_id, output_dir }) => guarded(async () => {
+        const { client } = await context(), job = await client.getJob(job_id);
+        if (job.state !== "done")
+            throw new ApiError("conflict", `Job is ${job.state}; wait until done.`);
+        // The server returns the sanitized original name; fall back to the job id for older responses.
+        const stem = job.filename ? basename(job.filename, extname(job.filename)) : encodeURIComponent(job_id);
+        const output = join(resolve(output_dir), `${stem} 4K.mp4`);
+        await client.download(job_id, output, job.download_url);
+        return { job_id, output_path: output, state: "done" };
+    }));
+    return server;
+}
+export async function startMcpServer(options = {}) { await createMcpServer(options).connect(new StdioServerTransport()); }

package/dist/probe-video.d.ts

@@ -0,0 +1,3 @@
+import type { VideoInfo } from "./api-contract.js";
+export declare function probeBmff(path: string): Promise<VideoInfo>;
+export declare function probeVideo(path: string): Promise<VideoInfo>;

package/dist/probe-video.js

@@ -0,0 +1,98 @@
+/** Probe MP4/QuickTime metadata through bounded reads, with ffprobe as a fallback. */
+import { open } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+async function read(file, position, size) {
+    const buffer = Buffer.alloc(size);
+    const { bytesRead } = await file.read(buffer, 0, size, position);
+    if (bytesRead !== size)
+        throw new Error("Truncated movie metadata");
+    return buffer;
+}
+async function boxes(file, start, end) {
+    const result = [];
+    for (let pos = start; pos + 8 <= end;) {
+        const header = await read(file, pos, 8);
+        let size = header.readUInt32BE(0), headerSize = 8;
+        if (size === 1) {
+            const large = (await read(file, pos + 8, 8)).readBigUInt64BE();
+            if (large > BigInt(Number.MAX_SAFE_INTEGER))
+                throw new Error("Box exceeds safe file offsets");
+            size = Number(large);
+            headerSize = 16;
+        }
+        else if (size === 0)
+            size = end - pos;
+        if (size < headerSize || pos + size > end)
+            throw new Error("Invalid movie box size");
+        result.push({ type: header.toString("ascii", 4, 8), start: pos + headerSize, end: pos + size });
+        pos += size;
+    }
+    return result;
+}
+function valid(info) {
+    if (!Object.values(info).every((n) => Number.isFinite(n) && n > 0))
+        throw new Error("Unreadable video metadata");
+    return info;
+}
+export async function probeBmff(path) {
+    const file = await open(path, "r");
+    try {
+        const top = await boxes(file, 0, (await file.stat()).size);
+        const moov = top.find((box) => box.type === "moov");
+        if (!moov)
+            throw new Error("Missing moov box");
+        const children = await boxes(file, moov.start, moov.end);
+        const mvhd = children.find((box) => box.type === "mvhd");
+        if (!mvhd)
+            throw new Error("Missing mvhd box");
+        const version = (await read(file, mvhd.start, 1))[0];
+        if (version !== 0 && version !== 1)
+            throw new Error("Unsupported mvhd version");
+        const length = version === 1 ? 32 : 20;
+        if (mvhd.end - mvhd.start < length)
+            throw new Error("Truncated mvhd");
+        const movie = await read(file, mvhd.start, length);
+        const timescale = movie.readUInt32BE(version === 1 ? 20 : 12);
+        const ticks = version === 1 ? Number(movie.readBigUInt64BE(24)) : movie.readUInt32BE(16);
+        for (const track of children.filter((box) => box.type === "trak")) {
+            const trackBoxes = await boxes(file, track.start, track.end);
+            const mdia = trackBoxes.find((box) => box.type === "mdia");
+            if (!mdia)
+                continue;
+            const handler = (await boxes(file, mdia.start, mdia.end)).find((box) => box.type === "hdlr");
+            if (!handler || handler.end - handler.start < 12 || (await read(file, handler.start + 8, 4)).toString("ascii") !== "vide")
+                continue;
+            const tkhd = trackBoxes.find((box) => box.type === "tkhd");
+            if (!tkhd)
+                continue;
+            const trackVersion = (await read(file, tkhd.start, 1))[0];
+            if (trackVersion !== 0 && trackVersion !== 1)
+                throw new Error("Unsupported tkhd version");
+            const offset = trackVersion === 1 ? 88 : 76;
+            if (tkhd.end - tkhd.start < offset + 8)
+                throw new Error("Truncated tkhd");
+            const dimensions = await read(file, tkhd.start + offset, 8);
+            return valid({ duration: ticks / timescale, width: dimensions.readUInt32BE(0) / 65536, height: dimensions.readUInt32BE(4) / 65536 });
+        }
+        throw new Error("Missing video track");
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function probeVideo(path) {
+    try {
+        return await probeBmff(path);
+    }
+    catch {
+        try {
+            const { stdout } = await promisify(execFile)("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height,duration:format=duration", "-of", "json", path], { timeout: 15_000, maxBuffer: 1024 * 1024, windowsHide: true });
+            const data = JSON.parse(stdout);
+            return valid({ duration: Number(data.format?.duration ?? data.streams?.[0]?.duration), width: Number(data.streams?.[0]?.width), height: Number(data.streams?.[0]?.height) });
+        }
+        catch {
+            throw new Error("Cannot probe video. Use a readable MP4/MOV, or install ffprobe on PATH.");
+        }
+    }
+}

package/dist/resume-state.d.ts

@@ -0,0 +1,22 @@
+import type { CreateJobBody } from "./api-contract.js";
+import { type LockOptions } from "./state-lock.js";
+export interface ResumeEntry {
+    source: string;
+    size: number;
+    mtime: number;
+    output: string;
+    idempotency_key: string;
+    job_id?: string;
+    created_at: number;
+    body: CreateJobBody;
+    api_key_prefix?: string;
+}
+export declare class ResumeState {
+    readonly path: string;
+    private readonly lockOptions?;
+    constructor(path: string, lockOptions?: LockOptions | undefined);
+    private update;
+    prepare(source: string, size: number, mtime: number, output: string, body: CreateJobBody, replace?: ResumeEntry, apiKeyPrefix?: string): Promise<ResumeEntry>;
+    setJob(entry: ResumeEntry, id: string): Promise<void>;
+    withSource(source: string, operation: () => Promise<void>): Promise<boolean>;
+}

package/dist/resume-state.js

@@ -0,0 +1,90 @@
+/** Atomically persist request identity before any remote job creation. */
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { ApiError } from "./api-client.js";
+import { acquireStateLock, withStateLock } from "./state-lock.js";
+const sourceIdentity = (source) => process.platform === "win32" ? source.toLowerCase() : source;
+export class ResumeState {
+    path;
+    lockOptions;
+    constructor(path, lockOptions) {
+        this.path = path;
+        this.lockOptions = lockOptions;
+    }
+    async update(operation, signal) {
+        return withStateLock(`${this.path}.lock`, async () => {
+            let entries = [];
+            try {
+                const data = JSON.parse(await readFile(this.path, "utf8"));
+                if (data.version !== 1 || !Array.isArray(data.entries))
+                    throw new Error("Unsupported state format");
+                entries = data.entries;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const result = operation(entries);
+            const temporary = `${this.path}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify({ version: 1, entries }, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+                await rename(temporary, this.path);
+            }
+            finally {
+                await unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+                    throw error; });
+            }
+            return result;
+        }, { ...this.lockOptions, signal, refreshMs: 0 });
+    }
+    async prepare(source, size, mtime, output, body, replace, apiKeyPrefix) {
+        return this.update((entries) => {
+            const index = entries.findIndex((entry) => sourceIdentity(entry.source) === sourceIdentity(source) && entry.size === size && entry.mtime === mtime);
+            const existing = entries[index];
+            if (existing && (!replace || existing.idempotency_key !== replace.idempotency_key)) {
+                if (existing.body.consent.selfLikeness !== body.consent.selfLikeness ||
+                    Boolean(existing.body.consent.selfLikenessConsent) !== Boolean(body.consent.selfLikenessConsent)) {
+                    throw new ApiError("conflict", "Saved job has different consent. Resume with the original explicit choice or inspect/cancel that job first.");
+                }
+                existing.output = output;
+                return existing;
+            }
+            const entry = { source, size, mtime, output, body, idempotency_key: randomUUID(), created_at: Date.now() };
+            if (apiKeyPrefix !== undefined)
+                entry.api_key_prefix = apiKeyPrefix.slice(0, 12);
+            if (index < 0)
+                entries.push(entry);
+            else
+                entries[index] = entry;
+            return entry;
+        }, this.lockOptions?.signal);
+    }
+    async setJob(entry, id) {
+        await this.update((entries) => {
+            const saved = entries.find((candidate) => candidate.idempotency_key === entry.idempotency_key);
+            if (!saved || saved.job_id && saved.job_id !== id)
+                throw new ApiError("conflict", "Saved job identity changed during resume.");
+            saved.job_id = id;
+        });
+        entry.job_id = id;
+    }
+    async withSource(source, operation) {
+        const hash = createHash("sha256").update(sourceIdentity(source)).digest("hex");
+        let release;
+        try {
+            release = await acquireStateLock(`${this.path}.${hash}.lock`, { refreshMs: 30_000, ...this.lockOptions, waitMs: 0 });
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.code === "state_locked")
+                return false;
+            throw error;
+        }
+        try {
+            await operation();
+            return true;
+        }
+        finally {
+            await release();
+        }
+    }
+}

package/dist/run-file.d.ts

@@ -0,0 +1,19 @@
+/** Resume, upload, submit and optionally wait for one durable job. */
+import { ApiClient } from "./api-client.js";
+import type { CreateJobBody } from "./api-contract.js";
+import type { ResumeEntry, ResumeState } from "./resume-state.js";
+export interface RunEvent {
+    event: "scan" | "skipped" | "created" | "uploaded" | "queued" | "progress" | "done" | "failed" | "summary";
+    [key: string]: unknown;
+}
+export interface FileResult {
+    source: string;
+    output_path?: string;
+    job_id?: string;
+    state: string;
+    error?: string;
+    reason?: string;
+    message?: string;
+}
+export type Emit = (event: RunEvent) => void | Promise<void>;
+export declare function runFile(client: ApiClient, store: ResumeState, entry: ResumeEntry, output: string, wait: boolean, emit: Emit, pollMs: number, currentBody?: CreateJobBody, signal?: AbortSignal): Promise<FileResult>;

package/dist/run-file.js

@@ -0,0 +1,72 @@
+/** Resume, upload, submit and optionally wait for one durable job. */
+import { ApiError, sleep, throwIfCancelled } from "./api-client.js";
+import { outputExists } from "./scan-videos.js";
+import { withStateLock } from "./state-lock.js";
+export async function runFile(client, store, entry, output, wait, emit, pollMs, currentBody = entry.body, signal) {
+    throwIfCancelled(signal);
+    let job;
+    let old = Date.now() - entry.created_at >= 24 * 60 * 60 * 1000;
+    if (entry.job_id) {
+        try {
+            job = await client.getJob(entry.job_id, signal);
+        }
+        catch (error) {
+            if (!(error instanceof ApiError && error.code === "not_found" && entry.api_key_prefix !== undefined && entry.api_key_prefix !== client.keyPrefix))
+                throw error;
+        }
+        if (job && old && ["failed", "canceled", "expired"].includes(job.state)) {
+            // Only these terminal states permit a new request after server deduplication expires.
+            const previousId = entry.job_id;
+            entry = await store.prepare(entry.source, entry.size, entry.mtime, output, currentBody, entry, client.keyPrefix);
+            job = entry.job_id && entry.job_id !== previousId ? await client.getJob(entry.job_id, signal) : undefined;
+            old = Date.now() - entry.created_at >= 24 * 60 * 60 * 1000;
+        }
+    }
+    if (!job || job.state === "uploading") {
+        if (entry.api_key_prefix !== undefined && entry.api_key_prefix !== client.keyPrefix) {
+            throw new ApiError("resume_ambiguous", `This run was started with another API key. Inspect/cancel the old job${entry.job_id ? ` (${entry.job_id})` : ""} or rerun with the original key; refusing a possible duplicate.`);
+        }
+        if (old) {
+            // No refresh endpoint exists once an uploading job's idempotency record expires.
+            throw new ApiError("resume_ambiguous", "Saved upload is older than 24 hours. Inspect/cancel the old job before retrying; refusing a possible duplicate.");
+        }
+        const created = await client.create(entry.body, entry.idempotency_key, signal);
+        if (entry.job_id && entry.job_id !== created.id)
+            throw new ApiError("conflict", "Server changed an existing idempotent job identity.");
+        await store.setJob(entry, created.id);
+        await emit({ event: "created", source: entry.source, job_id: created.id });
+        if (created.upload_method === "multipart") {
+            // Completing a long upload is its admission; there is no separate submit.
+            const completed = await client.uploadLong(created, entry.source, entry.size, signal);
+            await emit({ event: "uploaded", source: entry.source, job_id: created.id });
+            job = { id: created.id, state: completed.state };
+        }
+        else {
+            await client.upload(created, entry.source, entry.size, signal);
+            await emit({ event: "uploaded", source: entry.source, job_id: created.id });
+            const submitted = await client.submit(created.id, signal);
+            job = { id: created.id, ...submitted };
+        }
+        await emit({ event: "queued", source: entry.source, job_id: job.id, state: job.state, queue_position: job.queue_position });
+    }
+    throwIfCancelled(signal);
+    if (!wait)
+        return { source: entry.source, job_id: job.id, state: job.state };
+    while (["queued", "claimed", "running", "uploading"].includes(job.state)) {
+        await emit({ event: "progress", source: entry.source, job_id: job.id, state: job.state, progress: job.progress, queue_position: job.queue_position });
+        await sleep(pollMs, signal);
+        job = await client.getJob(job.id, signal);
+    }
+    if (job.state !== "done") {
+        const message = typeof job.error === "string" ? job.error : job.error?.message ?? `Job ${job.state}`;
+        throw new ApiError(job.error && typeof job.error === "object" ? job.error.code : job.state, message);
+    }
+    // Serialize the final existence check and transfer across concurrent runs.
+    await withStateLock(`${output}.upscale4k-download.lock`, async () => {
+        throwIfCancelled(signal);
+        if (!await outputExists(entry.source, output))
+            await client.download(job.id, output, job.download_url, signal);
+    }, { signal, refreshMs: 30_000 });
+    await emit({ event: "done", source: entry.source, job_id: job.id, output_path: output });
+    return { source: entry.source, output_path: output, job_id: job.id, state: "done" };
+}