feat(pipeline): render queue, worker service and automated preview generation

One "Queue Export" click now renders the EXR sequence, then rebuilds the shot
headlessly with the studio slate/overlay template to produce the delivery MOV
and review MP4. Implements RenderPipeline2 phases 1-2 plus the preview stage.

Server:
- New models Export, RenderJob, ExportEvent, Machine, WorkerHeartbeat, plus
  Project.deliveryConfig and per-submission slate fields (Export.vfxScope,
  Export.submissionNote, inherited from the shot's previous export).
  Both migrations are purely additive; no existing column is touched.
- lib/render-pipeline: server-enforced state machine, transactional version
  increment with supersede, atomic FOR UPDATE SKIP LOCKED claim gated by
  machine availability windows, and a lease reaper run from instrumentation.ts.
- /api/ext/* endpoints for the panel and workers; session-auth mirrors under
  /api/render and /api/machines for the web UI.
- Pipeline pages: render queue, export detail, machine monitoring, plus an
  Exports tab on shot detail.

RenderWorker (.NET 8 Windows service, new):
- Registration, heartbeat as cancel channel, claim loop, aerender runner with
  progress parsing and stall watchdog, crash recovery and disk-spooled
  reporting that survives server downtime.
- Preview stage: headless AE assembles the preview comp into a throwaway AEP
  with both output modules queued, then a single aerender pass renders them.
  Preview jobs are not claimed while an interactive AE session is open, so an
  artist's project is never taken over.

AE panel: Queue Export with live status polling, urgent flag, retry, and the
VFX Scope / Submission Note fields. Every existing panel action is unchanged.

Preview chaining ships disabled behind SystemConfig preview.enabled.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app/api/ext/exports/[exportId]/retry/route.ts

@@ -0,0 +1,32 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { retryExport } from "@/lib/render-pipeline/exports";
+
+// ── POST /api/ext/exports/{exportId}/retry (E14) ─────────────────────────────
+//
+// Retry a *_FAILED export from the AE panel: new RenderJob attempt, back to QUEUED.
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ exportId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { exportId } = await params;
+  let note: string | undefined;
+  try {
+    const body = await req.json();
+    if (typeof body?.note === "string") note = body.note;
+  } catch {
+    // empty body is fine
+  }
+  try {
+    const result = await retryExport(exportId, { type: "USER", note: note ?? "Retry from AE panel" });
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body, status } = toErrorResponse(err);
+    return NextResponse.json(body, { status });
+  }
+}

app/api/ext/exports/[exportId]/route.ts

@@ -0,0 +1,26 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { getExportDetail } from "@/lib/render-pipeline/exports";
+
+// ── GET /api/ext/exports/{exportId} (E3) ─────────────────────────────────────
+//
+// Export detail incl. render attempts and audit events (validations/QC join in
+// later phases).
+
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ exportId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { exportId } = await params;
+  try {
+    const result = await getExportDetail(exportId);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body, status } = toErrorResponse(err);
+    return NextResponse.json(body, { status });
+  }
+}

app/api/ext/exports/latest/route.ts

@@ -0,0 +1,28 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { getLatestExport } from "@/lib/render-pipeline/exports";
+
+// ── GET /api/ext/exports/latest?shotCode=&projectCode= (E2) ──────────────────
+//
+// Latest export + status for the AE panel status header. Returns
+// { "export": null } when the shot has never been exported.
+
+export async function GET(req: NextRequest) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { searchParams } = new URL(req.url);
+  const shotCode = searchParams.get("shotCode")?.trim();
+  const projectCode = searchParams.get("projectCode")?.trim();
+  if (!shotCode) {
+    return NextResponse.json({ error: "shotCode query param is required" }, { status: 400 });
+  }
+  try {
+    const result = await getLatestExport(shotCode, projectCode);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body, status } = toErrorResponse(err);
+    return NextResponse.json(body, { status });
+  }
+}

app/api/ext/exports/route.ts

@@ -0,0 +1,47 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { createExport } from "@/lib/render-pipeline/exports";
+
+// ── POST /api/ext/exports (E1 — Queue Export) ────────────────────────────────
+//
+// Body: { manifest: RenderManifest, submittedByEmail?, priority?, force? }
+// The server decides the new version number, updates Shot.shotVersion/exrOutput,
+// supersedes older non-terminal exports, and creates Export(QUEUED) + RenderJob.
+
+export async function POST(req: NextRequest) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  let body: {
+    manifest?: unknown;
+    submittedByEmail?: string;
+    priority?: number;
+    force?: boolean;
+    vfxScope?: string | null;
+    submissionNote?: string | null;
+  };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body.manifest) {
+    return NextResponse.json({ error: "manifest is required" }, { status: 400 });
+  }
+  try {
+    const result = await createExport({
+      manifest: body.manifest,
+      submittedByEmail: body.submittedByEmail ?? null,
+      priority: typeof body.priority === "number" ? body.priority : undefined,
+      force: body.force === true,
+      // undefined inherits the shot's previous export values
+      vfxScope: body.vfxScope,
+      submissionNote: body.submissionNote,
+    });
+    return NextResponse.json(result, { status: 201 });
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/render/jobs/[jobId]/artifact-presign/route.ts

@@ -0,0 +1,57 @@
+import { NextRequest, NextResponse } from "next/server";
+import { randomUUID } from "crypto";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse, PipelineError } from "@/lib/render-pipeline/errors";
+import { db } from "@/lib/db";
+import { generateHetznerPresignedUploadUrl, sanitizeFileName } from "@/lib/storage";
+
+// ── POST /api/ext/render/jobs/{jobId}/artifact-presign (E20) ─────────────────
+//
+// Presigned upload URL for worker artifacts. Kinds map to the existing object
+// storage folder layout: preview → videos/, thumbnail → image/,
+// metadata/log → renders/.
+
+const KIND_FOLDERS: Record<string, string> = {
+  preview: "videos",
+  thumbnail: "image",
+  metadata: "renders",
+  log: "renders",
+};
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ jobId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { jobId } = await params;
+  let body: { machineId?: string; kind?: string; fileName?: string; contentType?: string };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  try {
+    if (!body.machineId) throw new PipelineError(400, "machineId is required");
+    if (!body.fileName) throw new PipelineError(400, "fileName is required");
+    if (!body.contentType) throw new PipelineError(400, "contentType is required");
+    const folder = KIND_FOLDERS[body.kind ?? ""];
+    if (!folder) {
+      throw new PipelineError(422, `kind must be one of: ${Object.keys(KIND_FOLDERS).join(", ")}`);
+    }
+
+    const job = await db.renderJob.findUnique({ where: { id: jobId }, select: { machineId: true } });
+    if (!job) throw new PipelineError(404, "Render job not found");
+    if (job.machineId !== body.machineId) {
+      throw new PipelineError(409, "Job is not held by this machine (lease reassigned?)");
+    }
+
+    const key = `${folder}/${randomUUID()}-${sanitizeFileName(body.fileName)}`;
+    const presignedUrl = await generateHetznerPresignedUploadUrl(key, body.contentType);
+    return NextResponse.json({ presignedUrl, key, url: `/api/files/${key}` });
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/render/jobs/[jobId]/complete-render/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { completeRender } from "@/lib/render-pipeline/jobs";
+
+// ── POST /api/ext/render/jobs/{jobId}/complete-render (E11) ──────────────────
+//
+// aerender finished with exit 0. Phase 2 interim: Export goes to a provisional
+// READY_FOR_QC; Phase 3 inserts VALIDATING between (§17.3).
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ jobId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { jobId } = await params;
+  let body: {
+    machineId?: string;
+    renderSeconds?: number;
+    logFileKey?: string;
+    logTail?: string;
+    exrFileCount?: number;
+    exrTotalBytes?: number;
+  };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body.machineId) {
+    return NextResponse.json({ error: "machineId is required" }, { status: 400 });
+  }
+  try {
+    const result = await completeRender(jobId, body.machineId, body);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/render/jobs/[jobId]/fail/route.ts

@@ -0,0 +1,43 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { reportFail } from "@/lib/render-pipeline/jobs";
+
+// ── POST /api/ext/render/jobs/{jobId}/fail (E10) ─────────────────────────────
+//
+// Failure report. If retryable and attempts remain the server auto-creates the
+// next attempt and returns autoRequeued: true.
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ jobId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { jobId } = await params;
+  let body: {
+    machineId?: string;
+    stage?: string;
+    exitCode?: number;
+    errorMessage?: string;
+    logTail?: string;
+    logFileKey?: string;
+    retryable?: boolean;
+  };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body.machineId) {
+    return NextResponse.json({ error: "machineId is required" }, { status: 400 });
+  }
+  try {
+    const result = await reportFail(jobId, body.machineId, body);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/render/jobs/[jobId]/finalize/route.ts

@@ -0,0 +1,38 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { finalizePreview, type FinalizeInput } from "@/lib/render-pipeline/preview";
+
+// ── POST /api/ext/render/jobs/{jobId}/finalize (E13) ─────────────────────────
+//
+// Preview artifacts uploaded → register the review MP4 as an internal-only
+// Version and move the Export to READY_FOR_QC. Never shares to the client
+// portal and never changes task/shot status (§10.0).
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ jobId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { jobId } = await params;
+
+  let body: FinalizeInput & { machineId?: string };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body.machineId) {
+    return NextResponse.json({ error: "machineId is required" }, { status: 400 });
+  }
+
+  try {
+    const result = await finalizePreview(jobId, body.machineId, body);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/render/jobs/[jobId]/progress/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { reportProgress } from "@/lib/render-pipeline/jobs";
+
+// ── PATCH /api/ext/render/jobs/{jobId}/progress (E9) ─────────────────────────
+//
+// Progress/ETA report; renews the job lease. Response carries cancelRequested
+// so a worker learns about cancellation without any server→worker connection.
+
+export async function PATCH(
+  req: NextRequest,
+  { params }: { params: Promise<{ jobId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { jobId } = await params;
+  let body: {
+    machineId?: string;
+    progress?: number;
+    currentFrame?: number;
+    totalFrames?: number;
+    etaSeconds?: number;
+    logTail?: string;
+  };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body.machineId) {
+    return NextResponse.json({ error: "machineId is required" }, { status: 400 });
+  }
+  try {
+    const result = await reportProgress(jobId, body.machineId, body);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/render/jobs/claim/route.ts

@@ -0,0 +1,33 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { claimNextJob } from "@/lib/render-pipeline/jobs";
+
+// ── POST /api/ext/render/jobs/claim (E8) ─────────────────────────────────────
+//
+// Atomically claim the next queued job (FOR UPDATE SKIP LOCKED). Enforces
+// machine availability windows / Render Now / urgent priority server-side
+// (§7.10). 204 when nothing is claimable.
+
+export async function POST(req: NextRequest) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  let body: { machineId?: string; types?: string[] };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body.machineId) {
+    return NextResponse.json({ error: "machineId is required" }, { status: 400 });
+  }
+  try {
+    const result = await claimNextJob(body.machineId, body.types);
+    if (!result) return new NextResponse(null, { status: 204 });
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/workers/[machineId]/heartbeat/route.ts

@@ -0,0 +1,33 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { recordHeartbeat } from "@/lib/render-pipeline/machines";
+
+// ── POST /api/ext/workers/{machineId}/heartbeat (E7) ─────────────────────────
+//
+// Heartbeat + the server→worker command channel: cancellation piggybacks on
+// the response (`commands: [{ type: "CANCEL_JOB", jobId }]`) so no server→
+// worker connection is ever needed.
+
+export async function POST(
+  req: NextRequest,
+  { params }: { params: Promise<{ machineId: string }> }
+) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { machineId } = await params;
+  let body: { cpuPercent?: number; memPercent?: number; diskFreeGb?: number; currentJobId?: string | null } = {};
+  try {
+    body = await req.json();
+  } catch {
+    // heartbeat with empty body is fine
+  }
+  try {
+    const result = await recordHeartbeat(machineId, body);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}

app/api/ext/workers/register/route.ts

@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from "next/server";
+import { isExtAuthorized } from "@/lib/render-pipeline/ext-auth";
+import { toErrorResponse } from "@/lib/render-pipeline/errors";
+import { registerMachine } from "@/lib/render-pipeline/machines";
+
+// ── POST /api/ext/workers/register (E6) ──────────────────────────────────────
+//
+// Idempotent register/upsert on machine name. Returns the server-supplied
+// worker config (SystemConfig) so fleet tuning never touches worker installs.
+
+export async function POST(req: NextRequest) {
+  if (!isExtAuthorized(req)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  let body: {
+    name?: string;
+    hostname?: string;
+    workerVersion?: string;
+    aeVersion?: string;
+    capabilities?: unknown;
+  };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  try {
+    const result = await registerMachine(body);
+    return NextResponse.json(result);
+  } catch (err) {
+    const { body: errBody, status } = toErrorResponse(err);
+    return NextResponse.json(errBody, { status });
+  }
+}