@skyphusion-labs/vivijure-core 0.9.0

package/dist/renders-db.js

@@ -0,0 +1,752 @@
+// Storyboard render history persistence (v0.34.0).
+//
+// One row per RunPod job submitted via POST /api/storyboard/render. The row is
+// inserted at submit time and updated by the poll + cancel handlers with the
+// latest status, output, error, and timing fields. GET /api/storyboard/renders
+// lists rows newest first.
+//
+// Ownership: the studio is single-operator; list/get/patch/delete are scoped by
+// row id (and optional project_id on list) only. Edge auth is Cloudflare Access.
+// (The legacy per-operator identity column was removed in the identity strip; memory:
+// vivijure-user-email-strip -- the studio is single-operator, nothing scopes by identity.)
+// Poll / cancel proxy to RunPod regardless of DB state (so jobs submitted before
+// v0.34.0 are still pollable directly via their jobId); the row UPDATE is a no-op
+// when no row exists for that jobId.
+import { writeRenderLog } from "./render-log.js";
+import { withD1Retry } from "./d1-retry.js";
+import { newPublicId } from "./public-id.js";
+// Surface a corrupted *_json column instead of swallowing it silently (issue #15).
+// The empty / NULL case is handled by a length guard BEFORE the parse, so this only
+// fires on a row whose column HAS content that will not parse -- a genuine anomaly
+// worth a log line. The caller keeps its own safe fallback; this just makes the
+// corruption diagnosable rather than invisible.
+function warnCorruptColumn(column, e) {
+    console.warn(`renders: corrupt ${column} JSON in a row, using fallback: ${e instanceof Error ? e.message : String(e)}`);
+}
+export function toPublicRenderRow(row) {
+    const { id: _internalId, project_id: _internalProjectId, parent_id: _internalParentId, public_id, project_public_id, parent_public_id, ...rest } = row;
+    return { ...rest, id: public_id, project_id: project_public_id, parent_id: parent_public_id };
+}
+// The one column list every full-row SELECT uses, so the SQL and RawRenderRow
+// cannot drift apart independently in two call sites.
+const RENDER_ROW_COLUMNS = `
+      r.id, r.public_id, r.job_id, r.project, r.bundle_key, r.quality_tier,
+      r.render_overrides, r.status, r.output_key, r.output_json AS output,
+      r.error, r.execution_time_ms, r.delay_time_ms,
+      r.submitted_at, r.updated_at, r.completed_at, r.label, r.keyframes_json, r.mode,
+      r.locked_shots_json, r.project_id, r.folder_path, r.tags_json, r.parent_id,
+      p.public_id AS project_public_id, pr.public_id AS parent_public_id`;
+// The FROM + LEFT JOINs that resolve the FK columns to their referents' public ids. Kept as one
+// constant so the two full-row read sites (getRenderByIdForUser / listRendersForUser) cannot drift.
+// LEFT JOIN so a NULL FK (or a since-deleted referent) yields a NULL public id, never a dropped row.
+const RENDER_ROW_FROM = `
+    FROM renders r
+    LEFT JOIN storyboard_projects p ON r.project_id = p.id
+    LEFT JOIN renders pr ON r.parent_id = pr.id`;
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+// v0.55.0: parse + validate a project_id intake (from the request body
+// or query string). Pure so vitest can assert the contract without env.
+// Returns null for any non-positive-integer input, which the caller
+// then treats as "no project filter" / "transient submit".
+export function normalizeProjectIdInput(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (typeof raw === "number") {
+        return Number.isInteger(raw) && raw > 0 ? raw : null;
+    }
+    if (typeof raw === "string") {
+        const n = Number(raw);
+        return Number.isInteger(n) && n > 0 ? n : null;
+    }
+    return null;
+}
+const TERMINAL_STATUSES = new Set([
+    "COMPLETED",
+    "FAILED",
+    "CANCELLED",
+    "TIMED_OUT",
+]);
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+// v0.136.0: how long after submit we keep treating a RunPod "job not found"
+// (404 on /status) as a momentary post-submit propagation race rather than a
+// dropped job. RunPod's /run can return IN_QUEUE before /status can see the
+// job; we show "SUBMITTED" during this window and only fail the row once the
+// 404 persists past it. Generous on purpose: false-failing a real job is worse
+// than a slightly delayed phantom verdict.
+export const PHANTOM_GRACE_SECONDS = 150;
+export function classifyMissingJob(rowStatus, submittedAtSec, nowSec, graceSec = PHANTOM_GRACE_SECONDS) {
+    if (isTerminalStatus(rowStatus))
+        return "terminal";
+    return nowSec - submittedAtSec < graceSec ? "confirming" : "phantom";
+}
+/** Build the bound INSERT for a render row, idempotent on job_id (ON CONFLICT DO NOTHING).
+ *  Returned UNEXECUTED so a caller can `.run()` it directly (insertRender) or compose several
+ *  into one all-or-nothing `env.DB.batch([...])` -- the atomic scatter submit (#289). */
+export function buildInsertRenderStmt(env, row) {
+    const now = nowSeconds();
+    const overrides = row.renderOverrides ? JSON.stringify(row.renderOverrides) : null;
+    const mode = row.mode ?? "full";
+    const projectId = typeof row.projectId === "number" && row.projectId > 0
+        ? row.projectId
+        : null;
+    const parentId = typeof row.parentId === "number" && row.parentId > 0
+        ? row.parentId
+        : null;
+    return env.DB.prepare(`INSERT INTO renders (
+      public_id, job_id, project, bundle_key, quality_tier,
+      render_overrides, status, submitted_at, updated_at, mode,
+      project_id, parent_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(job_id) DO NOTHING`).bind(newPublicId(), row.jobId, row.project, row.bundleKey, row.qualityTier, overrides, row.status, now, now, mode, projectId, parentId);
+}
+export async function insertRender(env, row) {
+    await buildInsertRenderStmt(env, row).run();
+}
+// Best-effort UPDATE from a poll / cancel response. No-op when no row
+// exists for the jobId (matches the "back-compat for pre-v0.34.0 jobs"
+// policy). Ownership is NOT checked here; the route handler enforces
+// authn via Cloudflare Access at the edge; the single-operator studio does no per-identity
+// authz (the list endpoint is unscoped).
+export async function updateRenderFromView(env, view, ctx) {
+    const now = nowSeconds();
+    const completed = TERMINAL_STATUSES.has(view.status) ? now : null;
+    // Pull output_key out of the GPU side's COMPLETED envelope when present.
+    let outputKey = null;
+    let keyframesJson = null;
+    let modeFromOutput = null;
+    if (view.output &&
+        typeof view.output === "object" &&
+        !Array.isArray(view.output)) {
+        const o = view.output;
+        if (typeof o.output_key === "string" && o.output_key.length > 0) {
+            outputKey = o.output_key;
+        }
+        // v0.39.0: extract the keyframes list (GPU 0.4.0+) so we can render
+        // thumbnails in the history row without re-parsing output_json.
+        const refs = normalizeKeyframes(o.keyframes);
+        if (refs.length > 0)
+            keyframesJson = JSON.stringify(refs);
+        // v0.40.0: GPU 0.4.2+ surfaces the run mode in the envelope. We mirror
+        // it into the row so the UI can render the keyframes-only flow even
+        // if the row was inserted before the mode column had a value.
+        // v0.42.0: also recognize "finalized" mode from the GPU's finalize
+        // action; same COALESCE-write pattern.
+        if (typeof o.mode === "string" && o.mode.length > 0) {
+            modeFromOutput = o.mode;
+        }
+    }
+    const outputJson = view.output !== undefined ? JSON.stringify(view.output) : null;
+    // Advance hot path: retry a transient D1 blip so a sweep tick self-heals instead of aborting.
+    await withD1Retry(() => env.DB.prepare(`UPDATE renders SET
+      status = ?,
+      output_key = COALESCE(?, output_key),
+      output_json = ?,
+      error = ?,
+      execution_time_ms = ?,
+      delay_time_ms = ?,
+      updated_at = ?,
+      completed_at = COALESCE(?, completed_at),
+      keyframes_json = COALESCE(?, keyframes_json),
+      mode = COALESCE(?, mode)
+    WHERE job_id = ?`)
+        .bind(view.status, outputKey, outputJson, view.error ?? null, view.executionTimeMs ?? null, view.delayTimeMs ?? null, now, completed, keyframesJson, modeFromOutput, view.jobId)
+        .run());
+    // v0.141.0: on terminal status, persist a per-render log to R2 (conventional
+    // key renders/logs/<jobId>.txt) so History can offer a "view logs" link.
+    // Best-effort: this never blocks or breaks the render-resolve path. When an
+    // ExecutionContext is supplied (the poll route) the R2 write runs via
+    // ctx.waitUntil, OFF the poll hot path -- the caller's response no longer waits
+    // on an R2 PUT (issue #15). Without ctx (tests / other callers) it falls back to
+    // awaiting so behavior is unchanged. A failure is logged rather than swallowed
+    // silently, so a persistently failing log write is diagnosable instead of invisible.
+    if (completed !== null) {
+        const logTask = (async () => {
+            try {
+                await writeRenderLog(env, view);
+            }
+            catch (e) {
+                console.warn(`render log write failed for job ${view.jobId}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        })();
+        if (ctx)
+            ctx.waitUntil(logTask);
+        else
+            await logTask;
+    }
+}
+// v0.146.0: cloud-animate progress feedback. A cloud animation runs one
+// provider call per shot for several minutes, so write a lightweight
+// "done of total" marker into output_json as each shot lands; the History row
+// surfaces "animating shot k/N" while the job is in flight. Guarded to
+// non-terminal rows so it can never clobber a row that already finished (the
+// finalize step overwrites output_json with the real output at COMPLETED).
+export async function setCloudAnimateProgress(env, jobId, done, total) {
+    const now = nowSeconds();
+    const json = JSON.stringify({ mode: "cloud-finalized", progress: { done, total } });
+    await env.DB.prepare(`UPDATE renders SET output_json = ?, updated_at = ?
+       WHERE job_id = ?
+         AND status NOT IN ('COMPLETED', 'FAILED', 'CANCELLED', 'TIMED_OUT')`)
+        .bind(json, now, jobId)
+        .run();
+}
+export async function setHybridProgress(env, jobId, lanes) {
+    const now = nowSeconds();
+    const done = lanes.gpu.done + lanes.cloud.done;
+    const total = lanes.gpu.total + lanes.cloud.total;
+    const json = JSON.stringify({
+        mode: "cloud-finalized",
+        progress: { done, total, gpu: lanes.gpu, cloud: lanes.cloud },
+    });
+    await env.DB.prepare(`UPDATE renders SET output_json = ?, updated_at = ?
+       WHERE job_id = ?
+         AND status NOT IN ('COMPLETED', 'FAILED', 'CANCELLED', 'TIMED_OUT')`)
+        .bind(json, now, jobId)
+        .run();
+}
+export async function getRenderForPoll(env, jobId) {
+    const r = await env.DB.prepare(`SELECT status, submitted_at, output_json AS output, output_key, error
+     FROM renders WHERE job_id = ?`)
+        .bind(jobId)
+        .first();
+    if (!r)
+        return null;
+    let output = null;
+    const opRaw = r.output;
+    if (typeof opRaw === "string" && opRaw.length > 0) {
+        try {
+            output = JSON.parse(opRaw);
+        }
+        catch (e) {
+            warnCorruptColumn("output_json", e);
+            output = opRaw;
+        }
+    }
+    return {
+        status: String(r.status),
+        submitted_at: Number(r.submitted_at),
+        output,
+        output_key: r.output_key ? String(r.output_key) : null,
+        error: r.error ? String(r.error) : null,
+    };
+}
+// v0.136.0: fail a render row by jobId (used when RunPod has no record of the
+// job past the grace window). Guarded so it never clobbers a row that already
+// reached a terminal state. Returns true iff a non-terminal row was flipped.
+export async function markRenderFailedByJobId(env, jobId, error) {
+    const now = nowSeconds();
+    const res = await withD1Retry(() => env.DB.prepare(`UPDATE renders SET
+       status = 'FAILED',
+       error = ?,
+       completed_at = COALESCE(completed_at, ?),
+       updated_at = ?
+     WHERE job_id = ?
+       AND status NOT IN ('COMPLETED', 'FAILED', 'CANCELLED', 'TIMED_OUT')`)
+        .bind(error.slice(0, 2000), now, now, jobId)
+        .run());
+    return (res.meta?.changes ?? 0) > 0;
+}
+// v0.122.0: off-GPU finish bookkeeping. When a render used finish_offloaded, the
+// pod returns clips (no assembled MP4); the Worker assembles via the video-finish
+// container on poll-completion. finish_state (NULL -> 'finishing' -> 'done' |
+// 'failed') is the idempotency lock so concurrent polls don't double-run the
+// container.
+// Atomically claim the finish for this job. Returns true iff THIS caller won the
+// claim (flipped finish_state to 'finishing'); a concurrent poll that lost gets
+// false and should report "still finishing". 'failed' is re-claimable (retry).
+export async function claimFinish(env, jobId) {
+    const now = nowSeconds();
+    const res = await withD1Retry(() => env.DB.prepare(`UPDATE renders SET finish_state = 'finishing', updated_at = ?
+     WHERE job_id = ? AND COALESCE(finish_state, '') NOT IN ('finishing', 'done')`)
+        .bind(now, jobId)
+        .run());
+    return (res.meta?.changes ?? 0) === 1;
+}
+export async function markFinishDone(env, jobId, outputKey, outputJson) {
+    const now = nowSeconds();
+    await withD1Retry(() => env.DB.prepare(`UPDATE renders SET output_key = ?, output_json = ?, status = 'COMPLETED',
+       finish_state = 'done', completed_at = COALESCE(completed_at, ?), updated_at = ?
+     WHERE job_id = ?`)
+        .bind(outputKey, outputJson, now, now, jobId)
+        .run());
+}
+export async function claimRenderNotify(env, jobId) {
+    const now = nowSeconds();
+    const res = await env.DB.prepare(`UPDATE renders SET notified_at = ?
+       WHERE job_id = ? AND notified_at IS NULL
+         AND status IN ('COMPLETED', 'FAILED')
+         AND COALESCE(mode, 'full') != 'keyframes-only'`)
+        .bind(now, jobId)
+        .run();
+    if ((res.meta?.changes ?? 0) !== 1)
+        return null;
+    const row = await env.DB.prepare(`SELECT project, status, output_key, error, execution_time_ms, mode
+       FROM renders WHERE job_id = ?`)
+        .bind(jobId)
+        .first();
+    return row ?? null;
+}
+// S4 (migration 0007): film-advance lease. advanceFilmJob does an unlocked read-modify-write on
+// the R2 film-job doc and is driven concurrently by the 1-minute cron sweep AND every client
+// status poll; two drivers in the same tick can each submit the next phase's external work (clip
+// start, dialogue batch, per-shot finish/speech/master steps, mux, notify) -- duplicated GPU
+// spend -- and clobber each other's doc writes (a lost poll token orphans a RunPod job). Same
+// conditional-UPDATE discipline as claimFinish: one winner per tick, checked via meta.changes.
+// The lease value (its expiry, unix ms) doubles as the holder's token, so a release can never
+// clear a successor's lease. Expiry makes a crashed winner's claim re-grantable instead of
+// wedging the job: the first driver past the expiry wins it fresh (the sweep re-drives every
+// minute, so the worst-case stall after a crash is the TTL).
+export { FILM_ADVANCE_LEASE_TTL_SECONDS, claimFilmAdvance, releaseFilmAdvance, } from "./film-advance-lease.js";
+// v0.139.0: jobs to resolve in the background (the cron sweep) so a fire-and-
+// forget API render still reaches terminal + emails its owner without a client
+// polling. Only non-terminal rows recent enough to still be live on RunPod;
+// keyframe previews excluded (never emailed). Bounded so one tick is cheap.
+// v0.161.1: scatter shard children (parent_id IS NOT NULL) are excluded -- the
+// parent's gather owns their lifecycle + the single notify, so a shard must not
+// be swept (RunPod-polled + emailed) on its own. Scatter PARENTS (parent_id NULL)
+// stay in the sweep; the scheduled handler drives their gather, never RunPod-polls.
+export async function listUnresolvedNotifiableJobs(env, maxAgeSeconds, limit = 25) {
+    const cutoff = nowSeconds() - Math.max(0, maxAgeSeconds);
+    const res = await env.DB.prepare(`SELECT job_id FROM renders
+       WHERE status NOT IN ('COMPLETED', 'FAILED', 'CANCELLED')
+         AND notified_at IS NULL
+         AND COALESCE(mode, 'full') != 'keyframes-only'
+         AND parent_id IS NULL
+         AND submitted_at >= ?
+       ORDER BY submitted_at ASC
+       LIMIT ?`)
+        .bind(cutoff, Math.min(Math.max(1, limit), 100))
+        .all();
+    return (res.results ?? []).map((r) => String(r.job_id)).filter((s) => s.length > 0);
+}
+// Stranded post-clips film jobs the normal age-windowed sweep no longer picks up.
+// Once a film's clips are rendered (phase is finish/assemble/mux), the only work
+// left is the CPU-only ffmpeg concat in video-finish, which never expires -- so a
+// job that stalled at assemble (e.g. the client stopped polling, or a transient
+// container outage outlasted a poll) should self-heal even past SWEEP_MAX_AGE_SECONDS,
+// rather than abandoning a fully-rendered film over its final CPU step. The age cutoff
+// exists to stop chasing RunPod jobs the platform has GC'd; that does not apply here,
+// because the finished clips are already in R2 and addressable from the film-job doc.
+// We gate on the persisted poll phase (output_json) so we never re-drive a job that
+// never got past the GPU stage; the caller additionally confirms the film-job doc still
+// exists in R2 before advancing. Bounded + ordered oldest-first so one tick stays cheap.
+export async function listStrandedPostClipsFilmJobs(env, maxAgeSeconds, limit = 25) {
+    const cutoff = nowSeconds() - Math.max(0, maxAgeSeconds);
+    const res = await env.DB.prepare(`SELECT job_id FROM renders
+       WHERE status NOT IN ('COMPLETED', 'FAILED', 'CANCELLED')
+         AND notified_at IS NULL
+         AND COALESCE(mode, 'full') != 'keyframes-only'
+         AND parent_id IS NULL
+         AND submitted_at < ?
+         AND (
+           output_json LIKE '%"phase":"assemble"%'
+           OR output_json LIKE '%"phase":"finish"%'
+           OR output_json LIKE '%"phase":"mux"%'
+         )
+       ORDER BY submitted_at ASC
+       LIMIT ?`)
+        .bind(cutoff, Math.min(Math.max(1, limit), 100))
+        .all();
+    return (res.results ?? []).map((r) => String(r.job_id)).filter((s) => s.length > 0);
+}
+export async function markFinishFailed(env, jobId, error) {
+    const now = nowSeconds();
+    await withD1Retry(() => env.DB.prepare(`UPDATE renders SET finish_state = 'failed', error = ?, updated_at = ? WHERE job_id = ?`)
+        .bind(error.slice(0, 2000), now, jobId)
+        .run());
+}
+export async function getFinishState(env, jobId) {
+    const row = await withD1Retry(() => env.DB.prepare(`SELECT finish_state, output_key FROM renders WHERE job_id = ?`)
+        .bind(jobId)
+        .first());
+    return row ?? null;
+}
+// v0.42.0: defensive parse of a locked-shots array stored as JSON in
+// the renders.locked_shots_json column OR coming in over the wire on
+// a PATCH. Drops non-string + empty + duplicate entries; clamps the
+// list length to a sane upper bound so a malformed client cannot
+// stuff arbitrary blobs into the row.
+const MAX_LOCKED_SHOTS = 200;
+export function normalizeLockedShots(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string")
+            continue;
+        const trimmed = entry.trim();
+        if (!trimmed || trimmed.length > 80)
+            continue;
+        if (seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+        if (out.length >= MAX_LOCKED_SHOTS)
+            break;
+    }
+    return out;
+}
+// v0.126.0: normalize a free-form folder path. Splits on "/", trims each
+// segment, drops empties (so leading / trailing / doubled slashes collapse),
+// rejoins, and caps length. Returns null for "unfiled" (empty / non-string).
+export function normalizeFolderPath(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const parts = raw
+        .split("/")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (parts.length === 0)
+        return null;
+    const joined = parts.join("/");
+    return joined.length > 200 ? joined.slice(0, 200) : joined;
+}
+const MAX_TAGS = 24;
+const MAX_TAG_LEN = 40;
+// v0.126.0: normalize a tag list. Lowercase + trim each, drop empties, cap
+// each tag's length and the total count, dedupe (order-preserving). Mirrors
+// normalizeLockedShots; used on both the PATCH write path and the read path.
+export function normalizeTags(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string")
+            continue;
+        const tag = entry.trim().toLowerCase().slice(0, MAX_TAG_LEN);
+        if (!tag)
+            continue;
+        if (seen.has(tag))
+            continue;
+        seen.add(tag);
+        out.push(tag);
+        if (out.length >= MAX_TAGS)
+            break;
+    }
+    return out;
+}
+// Best-effort coerce `output.keyframes` from a job envelope into a
+// well-formed KeyframeRef[]. Anything that does not look like an
+// object with string `shot_id` + `key` is dropped silently; that
+// way a GPU side that adds future fields to each entry does not
+// crash the UPDATE.
+export function normalizeKeyframes(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (typeof e.shot_id !== "string" || e.shot_id.length === 0)
+            continue;
+        if (typeof e.key !== "string" || e.key.length === 0)
+            continue;
+        out.push({ shot_id: e.shot_id, key: e.key });
+    }
+    return out;
+}
+// Fetch one row by D1 PK. Returns null when the row does not exist.
+// v0.136.4: point a finished render at a new MP4 that has audio muxed in
+// (produced off-GPU by the video-finish container). Updates output_key plus the
+// output_json's output_key / has_audio / seconds so the History download link
+// and the audio badge reflect the muxed version.
+export async function setRenderAudioOutput(env, id, outputKey, seconds) {
+    const now = nowSeconds();
+    const res = await env.DB.prepare(`UPDATE renders SET
+       output_key = ?,
+       output_json = json_set(
+         COALESCE(output_json, '{}'),
+         '$.output_key', ?,
+         '$.has_audio', json('true'),
+         '$.seconds', ?
+       ),
+       updated_at = ?
+     WHERE id = ?`)
+        .bind(outputKey, outputKey, seconds, now, id)
+        .run();
+    return (res.meta?.changes ?? 0) > 0;
+}
+// Resolve an opaque public id to the internal integer PK (the :id route boundary for renders).
+// Null when no render carries that public_id -- a bare sequential integer matches nothing, so the
+// route 404s. INDEX-backed (idx_renders_public_id) unique lookup, mirroring getRenderIdByJobId.
+export async function getRenderIdByPublicId(env, publicId) {
+    const r = await env.DB.prepare(`SELECT id FROM renders WHERE public_id = ? LIMIT 1`)
+        .bind(publicId)
+        .first();
+    return r ? Number(r.id) : null;
+}
+export async function getRenderByIdForUser(env, id) {
+    const r = await env.DB.prepare(`SELECT${RENDER_ROW_COLUMNS}${RENDER_ROW_FROM}
+    WHERE r.id = ?`)
+        .bind(id)
+        .first();
+    if (!r)
+        return null;
+    return normalizeRow(r);
+}
+// Update one row's label. Empty / null clears it.
+export async function setRenderLabel(env, id, label) {
+    const now = Math.floor(Date.now() / 1000);
+    const result = await env.DB.prepare(`UPDATE renders SET label = ?, updated_at = ? WHERE id = ?`)
+        .bind(label, now, id)
+        .run();
+    const changes = result.meta?.changes ?? 0;
+    return changes > 0;
+}
+// True when at least one OTHER row references the same output_key. Used
+// to gate R2 artifact deletion: re-renders of the same project can share
+// an output filename (rp_handler.py writes `renders/<project>/<name>.mp4`,
+// so a re-render at the same name would overwrite), and we never want to
+// strand a still-referenced artifact.
+export async function countOtherRowsWithOutputKey(env, id, outputKey) {
+    const r = await env.DB.prepare(`SELECT COUNT(*) AS n FROM renders WHERE output_key = ? AND id != ?`)
+        .bind(outputKey, id)
+        .first();
+    return Number(r?.n ?? 0);
+}
+// Delete one row by D1 PK. Returns true when a row was removed.
+export async function deleteRenderRow(env, id) {
+    const result = await env.DB.prepare(`DELETE FROM renders WHERE id = ?`)
+        .bind(id)
+        .run();
+    const changes = result.meta?.changes ?? 0;
+    return changes > 0;
+}
+/** The renders-list page size when a caller passes no `limit`. ONE source of truth for both the
+ *  GET /api/storyboard/renders route and this function's default, so they cannot drift (#670: the route
+ *  said 100, this signature said 50). 50 is a sensible API/MCP page (well under the 200 clamp below);
+ *  the frontend always sends its own explicit limit, so this governs headless/API/MCP consumers. */
+export const DEFAULT_RENDERS_LIMIT = 50;
+export async function listRendersForUser(env, limit = DEFAULT_RENDERS_LIMIT, projectId = null) {
+    // Clamp limit so a runaway client cannot drain the DB binding.
+    const cap = Math.min(Math.max(1, Math.floor(limit)), 200);
+    const baseSelect = `SELECT${RENDER_ROW_COLUMNS}${RENDER_ROW_FROM}`;
+    const stmt = projectId !== null && projectId > 0
+        ? env.DB.prepare(`${baseSelect}
+         WHERE r.project_id = ? OR r.project_id IS NULL
+         ORDER BY r.submitted_at DESC
+         LIMIT ?`).bind(projectId, cap)
+        : env.DB.prepare(`${baseSelect}
+         ORDER BY r.submitted_at DESC
+         LIMIT ?`).bind(cap);
+    const result = await stmt.all();
+    return (result.results ?? []).map(normalizeRow);
+}
+// D1 returns JSON columns as opaque strings; parse them back. A malformed
+// stored JSON falls back to null (overrides) or the raw string (output) so
+// a corrupted row never crashes a list response. The RawRenderRow type is a
+// compile-time claim only, so every guard below still handles a missing
+// (undefined) or wrongly-typed field at runtime (`== null` covers both
+// SQL NULL and an absent column).
+function normalizeRow(r) {
+    let overrides = null;
+    const oRaw = r.render_overrides;
+    if (typeof oRaw === "string" && oRaw.length > 0) {
+        try {
+            const parsed = JSON.parse(oRaw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                overrides = parsed;
+            }
+        }
+        catch (e) {
+            warnCorruptColumn("render_overrides", e);
+            overrides = null;
+        }
+    }
+    let output = null;
+    const opRaw = r.output;
+    if (typeof opRaw === "string" && opRaw.length > 0) {
+        try {
+            output = JSON.parse(opRaw);
+        }
+        catch (e) {
+            warnCorruptColumn("output_json", e);
+            output = opRaw;
+        }
+    }
+    let keyframes = null;
+    const kfRaw = r.keyframes_json;
+    if (typeof kfRaw === "string" && kfRaw.length > 0) {
+        try {
+            const parsed = JSON.parse(kfRaw);
+            const refs = normalizeKeyframes(parsed);
+            if (refs.length > 0)
+                keyframes = refs;
+        }
+        catch (e) {
+            warnCorruptColumn("keyframes_json", e);
+            keyframes = null;
+        }
+    }
+    return {
+        id: Number(r.id),
+        public_id: String(r.public_id),
+        job_id: String(r.job_id),
+        // D1 returns a SQL-NULL column as JS null, and String(null) === "null":
+        // the literal "null" string is truthy and defeats every downstream falsy
+        // guard (planner labels, download names, and re-render eligibility gating
+        // that keys off a truthy bundle_key). The schema permits these three to be
+        // NULL (migrations/0001_init.sql), so coerce SQL NULL to "" here to keep
+        // the RenderRow non-null string contract with a falsy empty value.
+        project: r.project == null ? "" : String(r.project),
+        bundle_key: r.bundle_key == null ? "" : String(r.bundle_key),
+        quality_tier: r.quality_tier == null ? "" : String(r.quality_tier),
+        render_overrides: overrides,
+        status: String(r.status),
+        output_key: r.output_key ? String(r.output_key) : null,
+        output,
+        error: r.error ? String(r.error) : null,
+        execution_time_ms: r.execution_time_ms == null ? null : Number(r.execution_time_ms),
+        delay_time_ms: r.delay_time_ms == null ? null : Number(r.delay_time_ms),
+        submitted_at: Number(r.submitted_at),
+        updated_at: Number(r.updated_at),
+        completed_at: r.completed_at == null ? null : Number(r.completed_at),
+        label: typeof r.label === "string" && r.label.length > 0 ? r.label : null,
+        keyframes,
+        // v0.40.0: collapse NULL / unknown values to 'full' so callers do
+        // not need to do this themselves. Legacy rows pre-dating the mode
+        // column read as NULL and are therefore 'full'.
+        // v0.42.0 adds 'finalized' as a third recognized value.
+        mode: r.mode === "keyframes-only"
+            ? "keyframes-only"
+            : r.mode === "finalized"
+                ? "finalized"
+                : r.mode === "cloud-finalized"
+                    ? "cloud-finalized"
+                    : "full",
+        // v0.42.0: parse the locked_shots_json column back into a string
+        // array; NULL / empty / malformed -> null (read as "nothing
+        // locked"). The normalizer keeps the same MAX_LOCKED_SHOTS cap as
+        // the write path so a corrupted row cannot bloat a list response.
+        locked_shots: (() => {
+            const lsRaw = r.locked_shots_json;
+            if (typeof lsRaw !== "string" || lsRaw.length === 0)
+                return null;
+            try {
+                const parsed = JSON.parse(lsRaw);
+                const arr = normalizeLockedShots(parsed);
+                return arr.length > 0 ? arr : null;
+            }
+            catch (e) {
+                warnCorruptColumn("locked_shots_json", e);
+                return null;
+            }
+        })(),
+        // v0.55.0: NULL for legacy rows or transient (no-project) submits.
+        project_id: r.project_id == null ? null : Number(r.project_id),
+        // v0.126.0: organization fields. folder_path is stored verbatim (already
+        // normalized on the write path); tags_json is a JSON array re-normalized
+        // on read so a hand-edited / corrupted row can never bloat a list.
+        folder_path: typeof r.folder_path === "string" && r.folder_path.length > 0
+            ? r.folder_path
+            : null,
+        tags: (() => {
+            const tRaw = r.tags_json;
+            if (typeof tRaw !== "string" || tRaw.length === 0)
+                return [];
+            try {
+                return normalizeTags(JSON.parse(tRaw));
+            }
+            catch (e) {
+                warnCorruptColumn("tags_json", e);
+                return [];
+            }
+        })(),
+        // v0.145.2: NULL on top-level renders; set on finalize / animate-cloud
+        // children to the keyframes-only preview render they derive from.
+        parent_id: r.parent_id == null ? null : Number(r.parent_id),
+        // S9 (F13): FK public ids from the LEFT JOIN; NULL when the FK is NULL or the referent is gone.
+        project_public_id: r.project_public_id == null ? null : String(r.project_public_id),
+        parent_public_id: r.parent_public_id == null ? null : String(r.parent_public_id),
+    };
+}
+// v0.42.0: PATCH locked_shots on a row.
+export async function setRenderLockedShots(env, id, lockedShots) {
+    const now = Math.floor(Date.now() / 1000);
+    const json = lockedShots.length > 0 ? JSON.stringify(lockedShots) : null;
+    const result = await env.DB.prepare(`UPDATE renders SET locked_shots_json = ?, updated_at = ? WHERE id = ?`)
+        .bind(json, now, id)
+        .run();
+    const changes = result.meta?.changes ?? 0;
+    return changes > 0;
+}
+// v0.161.0: the integer id for a job_id. The scatter submit inserts a parent
+// row keyed by a synthetic scatter-<uuid> job_id, then needs its autoincrement
+// id to link the child shard rows via parent_id. job_id is UNIQUE + unguessable,
+// so this is not user-scoped (the same capability model as getRenderForPoll).
+export async function getRenderIdByJobId(env, jobId) {
+    const r = await env.DB.prepare(`SELECT id FROM renders WHERE job_id = ?`)
+        .bind(jobId)
+        .first();
+    return r ? Number(r.id) : null;
+}
+// v0.161.0: the child shard rows of a scatter parent (job_id + last status),
+// for the gather watcher to poll each shard and decide finish/wait/fail. A
+// scatter parent's children are exactly its shards (no finalize/animate child
+// ever points at a scatter parent), so parent_id alone is the right filter.
+export async function getScatterChildren(env, parentId) {
+    const rs = await env.DB.prepare(`SELECT job_id, status FROM renders WHERE parent_id = ? ORDER BY id ASC`)
+        .bind(parentId)
+        .all();
+    return (rs.results ?? []).map((r) => ({ job_id: String(r.job_id), status: String(r.status) }));
+}
+// v0.126.0: PATCH the folder_path on a row. null / '' clears it (unfiled).
+export async function setRenderFolder(env, id, folderPath) {
+    const now = Math.floor(Date.now() / 1000);
+    const result = await env.DB.prepare(`UPDATE renders SET folder_path = ?, updated_at = ? WHERE id = ?`)
+        .bind(folderPath, now, id)
+        .run();
+    const changes = result.meta?.changes ?? 0;
+    return changes > 0;
+}
+// v0.126.0: PATCH the tags on a row. An empty list stores NULL (untagged).
+export async function setRenderTags(env, id, tags) {
+    const now = Math.floor(Date.now() / 1000);
+    const json = tags.length > 0 ? JSON.stringify(tags) : null;
+    const result = await env.DB.prepare(`UPDATE renders SET tags_json = ?, updated_at = ? WHERE id = ?`)
+        .bind(json, now, id)
+        .run();
+    const changes = result.meta?.changes ?? 0;
+    return changes > 0;
+}
+// v0.126.0: the distinct tags this user has applied across all their renders,
+// most-used first (then alphabetical), for the history tag-filter autocomplete.
+// Cap the tag-autocomplete scan to the most recent tagged renders instead of loading EVERY render's
+// tags_json (issue #12). Autocomplete only needs a representative set; the newest tagged renders are
+// the relevant ones, and the count-sort below still ranks within that window.
+const TAG_SCAN_LIMIT = 500;
+export async function listUserTags(env) {
+    const result = await env.DB.prepare(`SELECT tags_json FROM renders
+      WHERE tags_json IS NOT NULL
+      ORDER BY submitted_at DESC
+      LIMIT ?`)
+        .bind(TAG_SCAN_LIMIT)
+        .all();
+    const rows = result.results ?? [];
+    const counts = new Map();
+    for (const row of rows) {
+        if (typeof row.tags_json !== "string")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(row.tags_json);
+        }
+        catch (e) {
+            warnCorruptColumn("tags_json", e);
+            continue;
+        }
+        for (const tag of normalizeTags(parsed)) {
+            counts.set(tag, (counts.get(tag) ?? 0) + 1);
+        }
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([tag]) => tag);
+}
+//# sourceMappingURL=renders-db.js.map