feat(render-pipeline): validation, QC and delivery builder

Completes RenderPipeline2 phases 3-5. Additive throughout: with
validation.enabled=false the pipeline behaves exactly as before.

Validation (§8) runs on the worker straight after a render, while it
still holds the job and the files are local. Everything is read from the
EXR header — one 64 KB read per sampled frame, no pixel decode — so the
engine needs no oiiotool. The render job deliberately stays open through
the stage, so a worker that dies there is reaped and retried instead of
stranding the export in VALIDATING.

Timecode is the primary check and is anchored on the plate, never the
API: measured on the live show, Shot.timecodeStart is the editorial
in-point and sits one handle-length (8f) ahead of the plate, so checking
against it would pass the defective exports and fail the correct ones.
Reference precedence is manifest timing plate -> plate found on disk ->
API value, and the API rank is WARN-only. The panel now resolves plate
provenance by walking the comp's own footage layers, so the worker never
guesses which element carries the comp's timing.

Verified against real studio renders via the new --validate mode: it
catches both defect classes seen in shipped work — the +8 handle offset
and frame-derived timecode (00:00:41:17 = frame 1001 at 24fps).

QC (§10) is one service behind two front doors, API-key for the panel
and session for the web. PASS means ready to upload and nothing else;
FAIL sets the comp task to CHANGES. The panel gains a QC section that
imports the real EXR sequence at full res rather than the H.264.

Delivery (§11) rides the existing queue as a DELIVERY_BUILD job: hard
links with a copy fallback, verification by re-hashing delivered bytes
against the validation-time digest, manifest.json and the CSV report.
fsutil hardlink list is unavailable over SMB, so link identity is never
queried — reading the bytes back covers links and copies alike.

Also fixes ApiClient.ProgressAsync throwing on transport failure, which
would have aborted work in flight during a brief server outage; progress
reporting is best-effort by contract.

Removes the stale RenderWorker/ rule from the root .gitignore. The
worker's source is tracked like the rest of the repo and its own
.gitignore already covers bin/, obj/ and publish/; the rule silently
excluded new files while the existing 20 stayed tracked.

Not yet applied: migration 20260813000000 was hand-written because the
dev database was unavailable — run prisma migrate deploy and verify
before relying on it. None of this has run against a live server.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
twotalesanimation
2026-08-13 13:49:51 +02:00
parent 7f2f5e1005
commit feb1c7b3e9
48 changed files with 5786 additions and 238 deletions
+32 -9
View File
@@ -12,7 +12,20 @@ export const PIPELINE_CONFIG_DEFAULTS = {
"render.stallTimeoutSeconds": 600,
"render.urgentPriorityThreshold": 20,
"render.outputRoot": "//SAN",
// Validation stage (§8). Disabling it restores the pre-Phase-3 flow
// (render → preview) without a redeploy, for a bad engine release.
"validation.enabled": "true",
"validation.sampleEvery": 25,
/** Per-check severity overrides, e.g. {"exr_type":"warn"} (§17.3). */
"validation.overrides": "{}",
/** Frames of head handle the plates carry; only used for the API timecode fallback (§8.1a). */
"validation.handleFrames": 8,
/**
* Studio-wide delivery defaults (§11.2). A project's own `deliveryConfig`
* column overrides these key by key; `{}` falls through to the built-ins in
* lib/render-pipeline/deliveries.ts.
*/
"delivery.defaultConfig": "{}",
"preview.maxWidth": 1920,
// Preview stage (§9): headless AE rebuild of the render with slate/burn-ins
"preview.enabled": "true",
@@ -71,13 +84,23 @@ export async function getPreviewConfig() {
/** Worker-facing config bundle returned by E6 registration. */
export async function getWorkerConfig() {
const [pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds] =
await Promise.all([
getConfigNumber("render.pollSeconds"),
getConfigNumber("render.heartbeatSeconds"),
getConfigNumber("render.leaseSeconds"),
getConfigNumber("render.maxAttempts"),
getConfigNumber("render.stallTimeoutSeconds"),
]);
return { pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds };
const [
pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds,
validationEnabled, validationSampleEvery, validationHandleFrames,
] = await Promise.all([
getConfigNumber("render.pollSeconds"),
getConfigNumber("render.heartbeatSeconds"),
getConfigNumber("render.leaseSeconds"),
getConfigNumber("render.maxAttempts"),
getConfigNumber("render.stallTimeoutSeconds"),
getConfigBoolean("validation.enabled"),
getConfigNumber("validation.sampleEvery"),
getConfigNumber("validation.handleFrames"),
]);
return {
pollSeconds, heartbeatSeconds, leaseSeconds, maxAttempts, stallTimeoutSeconds,
// Whether the validation stage runs is the server's call, so switching it
// off is a config change here rather than a redeploy of every worker (§8).
validationEnabled, validationSampleEvery, validationHandleFrames,
};
}
+611
View File
@@ -0,0 +1,611 @@
import { DeliveryStatus, Prisma } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigNumber, getConfigValue } from "./config";
/**
* Delivery builder (RenderPipeline2 §11). The web app decides *what* goes in a
* package and records it; a worker does the file work through the same queue
* and claim path as a render.
*
* Version locking: a package references Export rows and denormalises
* shotCode/versionString at creation, so a later re-render can never mutate
* delivery history.
*/
// ── Config (§11.2) ───────────────────────────────────────────────────────────
export interface DeliveryConfig {
packageNameTemplate: string;
layout: { packageDir: string; shotDir: string; reportFile: string };
deliveryRoot: string;
includeMovs: boolean;
checksumAlgo: string;
reportFormats: string[];
copyMode: "auto" | "always-copy";
}
export const DELIVERY_CONFIG_DEFAULT: DeliveryConfig = {
packageNameTemplate: "{yymmdd}_Delivery",
layout: {
packageDir: "{deliveryRoot}/{episode}/{packageName}",
shotDir: "{packageDir}/{shotCode}",
reportFile: "{packageDir}/{packageName}_report.csv",
},
deliveryRoot: "//SAN/DELIVERY",
includeMovs: true,
checksumAlgo: "xxh64",
reportFormats: ["csv", "json"],
copyMode: "auto",
};
/**
* Project config → SystemConfig default → built-in. Merged shallowly per top
* level key so a project can override just `deliveryRoot` without restating the
* whole layout.
*/
export async function resolveDeliveryConfig(projectDeliveryConfig: unknown): Promise<DeliveryConfig> {
let systemDefault: Partial<DeliveryConfig> = {};
const raw = await getConfigValue("delivery.defaultConfig");
if (raw?.trim() && raw.trim() !== "{}") {
try {
systemDefault = JSON.parse(raw) as Partial<DeliveryConfig>;
} catch {
console.error("[render-pipeline] delivery.defaultConfig is not valid JSON — ignoring");
}
}
const project = (projectDeliveryConfig ?? {}) as Partial<DeliveryConfig>;
return {
...DELIVERY_CONFIG_DEFAULT,
...systemDefault,
...project,
layout: {
...DELIVERY_CONFIG_DEFAULT.layout,
...(systemDefault.layout ?? {}),
...(project.layout ?? {}),
},
};
}
export interface TokenValues {
showId: string;
episode: string;
yymmdd: string;
yyyymmdd: string;
packageName: string;
packageDir: string;
deliveryRoot: string;
shotCode: string;
versionString: string;
packageNumber: string;
}
export function applyTokens(template: string, tokens: Partial<TokenValues>): string {
return template.replace(/\{(\w+)\}/g, (whole, key: string) => {
const value = (tokens as Record<string, string | undefined>)[key];
return value === undefined ? whole : value;
});
}
export function dateTokens(date: Date) {
const yyyy = String(date.getFullYear());
const mm = String(date.getMonth() + 1).padStart(2, "0");
const dd = String(date.getDate()).padStart(2, "0");
return { yymmdd: `${yyyy.slice(2)}${mm}${dd}`, yyyymmdd: `${yyyy}${mm}${dd}` };
}
// ── E18: what is ready ───────────────────────────────────────────────────────
/**
* READY_FOR_DELIVERY exports grouped by episode. Only the newest ready export
* per shot is offered: an older ready version of the same shot is history, not
* a second thing to ship.
*/
export async function getReadyForDelivery(projectId: string, episode?: string | null) {
const rows = await db.export.findMany({
where: {
projectId,
status: "READY_FOR_DELIVERY",
...(episode ? { shot: { episode } } : {}),
},
orderBy: [{ shotId: "asc" }, { versionNumber: "desc" }],
include: {
shot: { select: { id: true, shotCode: true, episode: true } },
qcReviews: { orderBy: { createdAt: "desc" }, take: 1, select: { result: true, reviewerName: true, createdAt: true } },
},
});
const newestPerShot = new Map<string, (typeof rows)[number]>();
for (const row of rows) {
if (!newestPerShot.has(row.shotId)) newestPerShot.set(row.shotId, row);
}
const byEpisode = new Map<string, ReturnType<typeof serialiseReady>[]>();
for (const row of newestPerShot.values()) {
const key = row.shot.episode ?? "";
if (!byEpisode.has(key)) byEpisode.set(key, []);
byEpisode.get(key)!.push(serialiseReady(row));
}
return {
episodes: [...byEpisode.entries()]
.sort((a, b) => a[0].localeCompare(b[0]))
.map(([ep, exports]) => ({
episode: ep,
count: exports.length,
exports: exports.sort((a, b) => a.shotCode.localeCompare(b.shotCode)),
})),
};
}
function serialiseReady(row: {
id: string;
versionString: string;
outputDir: string;
exrFileCount: number | null;
exrTotalBytes: bigint | null;
deliveryMovPath: string | null;
checksum: string | null;
frameStart: number;
frameEnd: number;
shot: { id: string; shotCode: string; episode: string | null };
qcReviews: { result: string; reviewerName: string | null; createdAt: Date }[];
}) {
return {
exportId: row.id,
shotId: row.shot.id,
shotCode: row.shot.shotCode,
episode: row.shot.episode ?? "",
versionString: row.versionString,
outputDir: row.outputDir,
frameStart: row.frameStart,
frameEnd: row.frameEnd,
fileCount: row.exrFileCount,
totalBytes: row.exrTotalBytes == null ? null : Number(row.exrTotalBytes),
deliveryMovPath: row.deliveryMovPath,
hasChecksum: row.checksum != null,
qc: row.qcReviews[0]
? { result: row.qcReviews[0].result, reviewer: row.qcReviews[0].reviewerName, at: row.qcReviews[0].createdAt }
: null,
};
}
// ── E16: create a package ────────────────────────────────────────────────────
export const createDeliverySchema = z.object({
projectId: z.string().min(1),
episode: z.string().max(50).optional().nullable(),
/** Omitted → every ready export in the episode. */
exportIds: z.array(z.string().min(1)).max(500).optional(),
options: z
.object({
date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
name: z.string().max(120).optional(),
includeMovs: z.boolean().optional(),
copyMode: z.enum(["auto", "always-copy"]).optional(),
})
.optional(),
});
export type CreateDeliveryInput = z.infer<typeof createDeliverySchema>;
export async function createDeliveryPackage(input: CreateDeliveryInput, userId: string) {
const project = await db.project.findUnique({
where: { id: input.projectId },
select: { id: true, code: true, showId: true, deliveryConfig: true },
});
if (!project) throw new PipelineError(404, "Project not found");
const config = await resolveDeliveryConfig(project.deliveryConfig);
if (input.options?.includeMovs !== undefined) config.includeMovs = input.options.includeMovs;
if (input.options?.copyMode) config.copyMode = input.options.copyMode;
const buildDate = input.options?.date ? new Date(`${input.options.date}T00:00:00`) : new Date();
if (Number.isNaN(buildDate.getTime())) throw new PipelineError(422, "options.date is not a valid date");
const maxAttempts = await getConfigNumber("render.maxAttempts");
return db.$transaction(async (tx) => {
const exports = await tx.export.findMany({
where: {
projectId: project.id,
status: "READY_FOR_DELIVERY",
...(input.exportIds?.length ? { id: { in: input.exportIds } } : {}),
...(input.episode ? { shot: { episode: input.episode } } : {}),
},
include: { shot: { select: { id: true, shotCode: true, episode: true } } },
orderBy: { shotId: "asc" },
});
if (exports.length === 0) {
throw new PipelineError(422, "No READY_FOR_DELIVERY exports match — nothing to package");
}
if (input.exportIds?.length && exports.length !== input.exportIds.length) {
const found = new Set(exports.map((e) => e.id));
throw new PipelineError(
409,
"Some exports are no longer ready for delivery (re-rendered or already packaged?)",
{ missing: input.exportIds.filter((id) => !found.has(id)) }
);
}
// One export per shot: two versions of the same shot in one package is
// always a mistake, and it is cheaper to refuse than to ship it.
const shotIds = new Set<string>();
for (const e of exports) {
if (shotIds.has(e.shotId)) {
throw new PipelineError(422, `Two versions of ${e.shot.shotCode} selected — pick one`);
}
shotIds.add(e.shotId);
}
const episode = input.episode ?? exports[0].shot.episode ?? "";
const dates = dateTokens(buildDate);
const showId = project.showId || project.code;
const lastNumber = await tx.deliveryPackage.aggregate({
where: { projectId: project.id },
_max: { packageNumber: true },
});
const packageNumber = (lastNumber._max.packageNumber ?? 0) + 1;
const tokens: TokenValues = {
showId,
episode,
...dates,
packageName: "",
packageDir: "",
deliveryRoot: config.deliveryRoot,
shotCode: "",
versionString: "",
packageNumber: String(packageNumber),
};
tokens.packageName = input.options?.name ?? applyTokens(config.packageNameTemplate, tokens);
tokens.packageDir = applyTokens(config.layout.packageDir, tokens);
const pkg = await tx.deliveryPackage.create({
data: {
projectId: project.id,
episode,
name: tokens.packageName,
packageNumber,
status: "QUEUED",
rootPath: tokens.packageDir,
// Snapshot: historic packages always show the rules they were built with.
configSnapshot: { ...config, tokens } as unknown as Prisma.InputJsonValue,
createdById: userId,
},
});
await tx.deliveryItem.createMany({
data: exports.map((e) => ({
packageId: pkg.id,
exportId: e.id,
shotId: e.shotId,
shotCode: e.shot.shotCode,
versionString: e.versionString,
})),
});
const manifest = await buildDeliveryJobManifest(tx, pkg.id);
const job = await tx.renderJob.create({
data: {
type: "DELIVERY_BUILD",
deliveryId: pkg.id,
attempt: 1,
maxAttempts,
// Deliveries are interactive: someone is waiting on the folder, and the
// work is file copying rather than hours of CPU, so it jumps renders.
priority: 10,
manifest: manifest as unknown as Prisma.InputJsonValue,
},
});
return {
package: {
id: pkg.id,
name: pkg.name,
packageNumber,
episode,
status: pkg.status,
rootPath: pkg.rootPath,
itemCount: exports.length,
},
renderJob: { id: job.id },
};
});
}
// ── The DELIVERY_BUILD manifest ──────────────────────────────────────────────
export interface DeliveryManifestItem {
itemId: string;
exportId: string;
shotCode: string;
versionString: string;
sourceDir: string;
outputPattern: string;
frameStart: number;
frameEnd: number;
fileCount: number | null;
checksum: string | null;
deliveryMovPath: string | null;
shotDir: string;
}
export interface DeliveryManifest {
stage: "DELIVERY";
packageId: string;
packageName: string;
packageNumber: number;
episode: string;
packageDir: string;
reportFile: string;
includeMovs: boolean;
copyMode: string;
checksumAlgo: string;
reportFormats: string[];
items: DeliveryManifestItem[];
}
export async function buildDeliveryJobManifest(
tx: Prisma.TransactionClient,
packageId: string
): Promise<DeliveryManifest> {
const pkg = await tx.deliveryPackage.findUniqueOrThrow({
where: { id: packageId },
include: {
items: { include: { export: true } },
project: { select: { code: true, showId: true } },
},
});
const snapshot = pkg.configSnapshot as unknown as DeliveryConfig & { tokens: TokenValues };
const baseTokens: TokenValues = {
...snapshot.tokens,
packageName: pkg.name,
packageDir: pkg.rootPath ?? snapshot.tokens.packageDir,
episode: pkg.episode,
};
return {
stage: "DELIVERY",
packageId: pkg.id,
packageName: pkg.name,
packageNumber: pkg.packageNumber,
episode: pkg.episode,
packageDir: baseTokens.packageDir,
reportFile: applyTokens(snapshot.layout.reportFile, baseTokens),
includeMovs: snapshot.includeMovs,
copyMode: snapshot.copyMode ?? "auto",
checksumAlgo: snapshot.checksumAlgo,
reportFormats: snapshot.reportFormats,
items: pkg.items.map((item) => ({
itemId: item.id,
exportId: item.exportId,
shotCode: item.shotCode,
versionString: item.versionString,
sourceDir: item.export.outputDir,
outputPattern: item.export.outputPattern,
frameStart: item.export.frameStart,
frameEnd: item.export.frameEnd,
fileCount: item.export.exrFileCount,
checksum: item.export.checksum,
deliveryMovPath: snapshot.includeMovs ? item.export.deliveryMovPath : null,
shotDir: applyTokens(snapshot.layout.shotDir, {
...baseTokens,
shotCode: item.shotCode,
versionString: item.versionString,
}),
})),
};
}
// ── Worker reporting ─────────────────────────────────────────────────────────
export const deliveryReportSchema = z.object({
machineId: z.string().min(1),
items: z
.array(
z.object({
itemId: z.string().min(1),
status: z.enum(["COPIED", "VERIFIED", "FAILED"]),
exrPath: z.string().max(1000).optional().nullable(),
movPath: z.string().max(1000).optional().nullable(),
fileCount: z.number().int().nonnegative().optional(),
totalBytes: z.number().nonnegative().optional(),
checksum: z.string().max(200).optional().nullable(),
linkMode: z.enum(["hardlink", "copy"]).optional().nullable(),
errorMessage: z.string().max(2000).optional().nullable(),
})
)
.max(500),
manifest: z.unknown().optional(),
reportKey: z.string().max(500).optional().nullable(),
rootPath: z.string().max(1000).optional().nullable(),
errorMessage: z.string().max(2000).optional().nullable(),
/** false → the package failed as a whole. */
ok: z.boolean(),
});
export type DeliveryReport = z.infer<typeof deliveryReportSchema>;
/**
* The worker finished (or gave up on) a DELIVERY_BUILD job. Exports move to
* PACKAGED only for items that actually verified — a package with a failed item
* is FAILED, and nothing about it is silently treated as delivered.
*/
export async function reportDeliveryBuild(jobId: string, body: DeliveryReport) {
return db.$transaction(async (tx) => {
const job = await tx.renderJob.findUnique({ where: { id: jobId } });
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?)");
}
if (!job.deliveryId) throw new PipelineError(422, "Job has no delivery package");
const pkg = await tx.deliveryPackage.findUnique({
where: { id: job.deliveryId },
include: { items: true },
});
if (!pkg) throw new PipelineError(404, "Delivery package not found");
if (pkg.status === "READY" || pkg.status === "DELIVERED") {
return { package: { id: pkg.id, status: pkg.status }, alreadyApplied: true };
}
await tx.renderJob.update({
where: { id: job.id },
data: {
status: body.ok ? "COMPLETED" : "FAILED",
progress: 1,
finishedAt: new Date(),
errorMessage: body.errorMessage ?? null,
},
});
for (const reported of body.items) {
await tx.deliveryItem.updateMany({
where: { id: reported.itemId, packageId: pkg.id },
data: {
status: reported.status,
exrPath: reported.exrPath ?? null,
movPath: reported.movPath ?? null,
fileCount: reported.fileCount ?? null,
totalBytes: reported.totalBytes == null ? null : BigInt(Math.round(reported.totalBytes)),
checksum: reported.checksum ?? null,
linkMode: reported.linkMode ?? null,
errorMessage: reported.errorMessage ?? null,
},
});
}
const verified = body.items.filter((i) => i.status === "VERIFIED");
const failed = body.items.filter((i) => i.status === "FAILED");
const success = body.ok && failed.length === 0 && verified.length === pkg.items.length;
if (success) {
for (const item of pkg.items) {
const exportRow = await tx.export.findUnique({ where: { id: item.exportId }, select: { id: true, status: true } });
if (exportRow?.status === "READY_FOR_DELIVERY") {
await applyTransition(tx, exportRow, "PACKAGED", {
type: "WORKER",
id: body.machineId,
note: `Packaged into #${pkg.packageNumber} ${pkg.name}`,
});
}
}
}
const updated = await tx.deliveryPackage.update({
where: { id: pkg.id },
data: {
status: success ? "READY" : "FAILED",
builtAt: new Date(),
rootPath: body.rootPath ?? pkg.rootPath,
manifest: (body.manifest ?? undefined) as Prisma.InputJsonValue | undefined,
reportKey: body.reportKey ?? pkg.reportKey,
errorMessage: success
? null
: (body.errorMessage ??
(failed.length ? `${failed.length} item(s) failed: ${failed.map((f) => f.itemId).join(", ")}` : "Build did not complete")),
},
});
return {
package: { id: updated.id, status: updated.status },
verified: verified.length,
failed: failed.length,
alreadyApplied: false,
};
});
}
// ── E17 / E19 / cancel ───────────────────────────────────────────────────────
export async function listDeliveryPackages(filter: { projectId?: string; episode?: string; status?: DeliveryStatus }) {
const packages = await db.deliveryPackage.findMany({
where: {
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.episode ? { episode: filter.episode } : {}),
...(filter.status ? { status: filter.status } : {}),
},
orderBy: { createdAt: "desc" },
include: {
items: { select: { id: true, shotCode: true, versionString: true, status: true, fileCount: true, linkMode: true, errorMessage: true } },
project: { select: { id: true, name: true, code: true } },
},
});
return {
packages: packages.map((p) => ({
id: p.id,
packageNumber: p.packageNumber,
name: p.name,
episode: p.episode,
status: p.status,
rootPath: p.rootPath,
errorMessage: p.errorMessage,
projectName: p.project.name,
projectCode: p.project.code,
createdAt: p.createdAt,
builtAt: p.builtAt,
deliveredAt: p.deliveredAt,
itemCount: p.items.length,
verifiedCount: p.items.filter((i) => i.status === "VERIFIED").length,
items: p.items,
})),
};
}
/** E19 — the human uploaded the folder to the client and is confirming it. */
export async function markDelivered(packageId: string, userId: string) {
return db.$transaction(async (tx) => {
const pkg = await tx.deliveryPackage.findUnique({ where: { id: packageId }, include: { items: true } });
if (!pkg) throw new PipelineError(404, "Delivery package not found");
if (pkg.status === "DELIVERED") {
return { package: { id: pkg.id, status: pkg.status }, alreadyApplied: true };
}
if (pkg.status !== "READY") {
throw new PipelineError(409, `Package is ${pkg.status} — only a READY package can be marked delivered`);
}
for (const item of pkg.items) {
const exportRow = await tx.export.findUnique({ where: { id: item.exportId }, select: { id: true, status: true } });
if (exportRow?.status === "PACKAGED") {
await applyTransition(tx, exportRow, "DELIVERED", {
type: "USER",
id: userId,
note: `Delivered in #${pkg.packageNumber} ${pkg.name}`,
});
}
}
const updated = await tx.deliveryPackage.update({
where: { id: pkg.id },
data: { status: "DELIVERED", deliveredAt: new Date(), deliveredById: userId },
});
return { package: { id: updated.id, status: updated.status }, alreadyApplied: false };
});
}
/** A mistaken package is cancelled, never deleted (§11.5). */
export async function cancelDeliveryPackage(packageId: string, userId: string) {
return db.$transaction(async (tx) => {
const pkg = await tx.deliveryPackage.findUnique({ where: { id: packageId } });
if (!pkg) throw new PipelineError(404, "Delivery package not found");
if (!["DRAFT", "QUEUED", "FAILED"].includes(pkg.status)) {
throw new PipelineError(409, `Package is ${pkg.status} — only DRAFT, QUEUED or FAILED packages can be cancelled`);
}
await tx.renderJob.updateMany({
where: { deliveryId: pkg.id, status: { in: ["QUEUED", "CLAIMED", "RUNNING"] } },
data: { status: "CANCELLED", finishedAt: new Date(), errorMessage: "Delivery package cancelled" },
});
const updated = await tx.deliveryPackage.update({
where: { id: pkg.id },
data: { status: "CANCELLED", errorMessage: `Cancelled by user ${userId}` },
});
return { package: { id: updated.id, status: updated.status } };
});
}
+20 -3
View File
@@ -1,7 +1,7 @@
import { ExportStatus, Prisma } from "@prisma/client";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { renderManifestSchema, type RenderManifest } from "./manifest";
import { describePlateProvenance, renderManifestSchema, type RenderManifest } from "./manifest";
import { applyTransition, type TransitionActor } from "./transitions";
import { getConfigNumber, getConfigValue } from "./config";
@@ -227,6 +227,9 @@ export async function createExport(input: CreateExportInput) {
},
});
// Plate provenance is recorded at queue time so a suspect export is
// visible in the queue before it renders (§8.1a).
const provenance = describePlateProvenance(resolvedManifest);
await tx.exportEvent.create({
data: {
exportId: created.id,
@@ -234,7 +237,9 @@ export async function createExport(input: CreateExportInput) {
toStatus: "QUEUED",
actorType: "USER",
actorId: submittedBy?.id ?? null,
note: `Queue Export ${versionString}${input.force ? " (force)" : ""}`,
note:
`Queue Export ${versionString}${input.force ? " (force)" : ""} — ` +
`${provenance.ok ? "" : "WARNING: "}${provenance.note}`,
},
});
@@ -333,10 +338,22 @@ export async function getExportDetail(exportId: string) {
include: { machine: { select: { id: true, name: true } } },
},
events: { orderBy: { createdAt: "asc" } },
validations: { orderBy: { createdAt: "asc" } },
qcReviews: { orderBy: { createdAt: "desc" } },
deliveryItems: {
include: {
package: { select: { id: true, name: true, episode: true, status: true, packageNumber: true } },
},
},
},
});
if (!exp) throw new PipelineError(404, "Export not found");
return { export: serializeExport(exp) };
return {
export: {
...serializeExport(exp),
deliveryItems: exp.deliveryItems.map((i) => ({ ...i, totalBytes: i.totalBytes == null ? null : Number(i.totalBytes) })),
},
};
}
/**
+39 -6
View File
@@ -74,6 +74,14 @@ export async function claimNextJob(machineId: string, types?: string[]) {
});
}
// Delivery packages have their own small lifecycle on the same queue.
if (job.deliveryId) {
await db.deliveryPackage.updateMany({
where: { id: job.deliveryId, status: "QUEUED" },
data: { status: "BUILDING" },
});
}
return {
job: {
id: job.id,
@@ -232,8 +240,11 @@ export async function reportFail(
/**
* E11 — aerender finished OK.
* Phase 2 interim (§17.3): transitions straight to a provisional READY_FOR_QC;
* Phase 3 will insert VALIDATING between (see transitions.ts note).
*
* Hands off to validation (§8) when it is enabled: the worker then runs the
* checks and reports them via E12, which queues the preview stage. With
* validation disabled the old direct handoff to the preview stage is used, so
* the kill switch restores the pre-Phase-3 flow exactly.
*/
export async function completeRender(
jobId: string,
@@ -255,12 +266,17 @@ export async function completeRender(
throw new PipelineError(409, `Job is ${job.status} — contradictory complete report rejected`);
}
// With validation to follow, the job deliberately stays open and keeps its
// lease: a worker that dies mid-validation is then reaped and retried like
// any other stalled job, instead of leaving the Export stuck in VALIDATING.
const validationEnabled = job.export ? await getConfigBoolean("validation.enabled") : false;
await tx.renderJob.update({
where: { id: job.id },
data: {
status: "COMPLETED",
status: validationEnabled ? "RUNNING" : "COMPLETED",
progress: 1,
finishedAt: new Date(),
...(validationEnabled ? {} : { finishedAt: new Date() }),
exitCode: 0,
logFileKey: body.logFileKey ?? job.logFileKey,
logTail: body.logTail?.slice(-20000) ?? job.logTail,
@@ -277,8 +293,25 @@ export async function completeRender(
...(body.exrTotalBytes != null ? { exrTotalBytes: BigInt(Math.round(body.exrTotalBytes)) } : {}),
};
// The EXR render is only the first stage: hand off to the preview stage
// (headless AE rebuild → delivery MOV + review MP4) when it is enabled.
// The EXR render is only the first stage. Validation comes next when
// enabled; the worker reports its results via E12 on the same job.
if (validationEnabled) {
const exp = await applyTransition(tx, job.export, "VALIDATING", {
type: "WORKER",
id: machineId,
note: `Render complete in ${body.renderSeconds ?? "?"}s — validating`,
}, stats);
return {
job: { id: job.id, status: "RUNNING" },
export: { id: exp.id, status: exp.status },
previewJob: null,
validationRequired: true,
alreadyApplied: false,
};
}
// Validation disabled: hand off to the preview stage (headless AE rebuild
// → delivery MOV + review MP4) exactly as before Phase 3.
const previewEnabled = await getConfigBoolean("preview.enabled");
if (previewEnabled) {
const manifest = await buildPreviewManifest(exportRow);
+64
View File
@@ -9,6 +9,20 @@ import { z } from "zod";
* generates them from the shot's exrOutput convention and the NEW version
* number it decides (§6.4 E1).
*/
/**
* A plate element imported into the comp, resolved by the panel from the comp's
* own footage layers — not re-derived from a path convention (§6.2).
*/
export const plateRefSchema = z.object({
element: z.string().optional(),
/** First frame of the sequence on disk; the timecode reference file. */
path: z.string().min(1),
frameStart: z.number().int().optional(),
frameEnd: z.number().int().optional(),
});
export type PlateRef = z.infer<typeof plateRefSchema>;
export const renderManifestSchema = z
.object({
manifestVersion: z.number().int().min(1).default(1),
@@ -37,6 +51,30 @@ export const renderManifestSchema = z
timecodeStart: z.string().optional(),
})
.optional(),
/**
* Plate provenance for the timecode check (§8.1a). Optional so
* manifestVersion 1 panels keep working — validation then degrades to a
* worker-derived plate, and finally to the API value as a WARN.
*/
source: z
.object({
/**
* The element the comp's start time was anchored to (the panel's
* primaryFootage). A shot's elements carry unrelated camera timecodes,
* so the timing reference must be named rather than guessed.
*/
timingPlate: plateRefSchema.optional(),
plates: z.array(plateRefSchema).optional(),
/**
* Verbatim from the panel's start-frame resolution: "footage metadata"
* (trustworthy) or "API timecode …" (fallback, suspect). Known at queue
* time, so a suspect export is flagged before it burns render hours.
*/
startSource: z.string().optional(),
startFrames: z.number().int().optional(),
handleFrames: z.number().int().optional(),
})
.optional(),
preview: z
.object({
template: z.string().optional(),
@@ -50,3 +88,29 @@ export const renderManifestSchema = z
});
export type RenderManifest = z.infer<typeof renderManifestSchema>;
/**
* Queue-time read of the manifest's plate provenance (§8.1a). A comp whose
* start time came from the API rather than the plate's own metadata is very
* likely to fail the timecode check — worth recording before the render burns
* machine hours, not after.
*/
export function describePlateProvenance(manifest: RenderManifest): { ok: boolean; note: string } {
const src = manifest.source;
if (!src?.timingPlate?.path) {
return {
ok: false,
note: "no timing plate in manifest — timecode will be checked against a worker-derived plate",
};
}
// Only warn on a start source we positively know to be the API fallback. An
// absent startSource means the comp predates this session (an AEP opened from
// disk), which is normal — the worker still does the authoritative check.
if (src.startSource && /\bAPI\b/i.test(src.startSource)) {
return {
ok: false,
note: `comp start came from "${src.startSource}", not the plate's own metadata — timecode check likely to fail`,
};
}
return { ok: true, note: `timing plate ${src.timingPlate.element ?? src.timingPlate.path}` };
}
+173
View File
@@ -0,0 +1,173 @@
import { Prisma, QCResult } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
/**
* QC workflow (RenderPipeline2 §10) — technical/final-delivery QC on shots the
* client has usually already approved. One service, two front doors: the AE
* panel (API key) and the web QC page (session).
*
* PASS means "ready to upload" and nothing else: it never shares to the client
* portal, never changes approval state, never creates client-visible media
* (§10.0). FAIL does move the comp task to CHANGES — the shot genuinely needs
* rework, and the existing REVISIONS derivation should surface that.
*/
export const qcSubmitSchema = z.object({
result: z.enum(["PASS", "FAIL"]),
notes: z.string().max(4000).optional().nullable(),
/** Panel sends the artist's email; web callers pass the session user instead. */
reviewerEmail: z.string().email().optional().nullable(),
reviewerName: z.string().max(200).optional().nullable(),
});
export type QCSubmitInput = z.infer<typeof qcSubmitSchema>;
export interface QCActor {
source: "AE_PANEL" | "WEB";
userId?: string | null;
name?: string | null;
}
/** Statuses a QC decision can be recorded from. */
const QC_ELIGIBLE = ["READY_FOR_QC", "QC_FAILED", "READY_FOR_DELIVERY"] as const;
export async function submitQCReview(exportId: string, input: QCSubmitInput, actor: QCActor) {
const reviewer = input.reviewerEmail
? await db.user.findUnique({ where: { email: input.reviewerEmail }, select: { id: true, name: true } })
: null;
const reviewedById = actor.userId ?? reviewer?.id ?? null;
const reviewerName = actor.name ?? reviewer?.name ?? input.reviewerName ?? input.reviewerEmail ?? null;
return db.$transaction(async (tx) => {
const exportRow = await tx.export.findUnique({
where: { id: exportId },
include: { shot: { select: { shotCode: true } } },
});
if (!exportRow) throw new PipelineError(404, "Export not found");
if (!QC_ELIGIBLE.includes(exportRow.status as (typeof QC_ELIGIBLE)[number])) {
throw new PipelineError(
409,
`Export is ${exportRow.status} — QC can only be recorded on ${QC_ELIGIBLE.join(", ")}`
);
}
const result = input.result as QCResult;
const review = await tx.qCReview.create({
data: {
exportId,
result,
notes: input.notes?.trim() || null,
reviewedById,
reviewerName,
source: actor.source,
},
});
const who = reviewerName ?? "unknown reviewer";
let taskUpdated: { id: string; status: string } | null = null;
if (result === "PASS") {
// Re-passing an export that is already READY_FOR_DELIVERY is a no-op
// transition-wise; the QCReview row is still the record of the decision.
const updated =
exportRow.status === "READY_FOR_DELIVERY"
? exportRow
: await applyTransition(tx, exportRow, "READY_FOR_DELIVERY", {
type: "USER",
id: reviewedById,
note: `QC PASS by ${who}${input.notes ? ` — ${input.notes.slice(0, 200)}` : ""}`,
});
return {
export: { id: updated.id, status: updated.status },
review: { id: review.id, result, createdAt: review.createdAt },
task: null,
};
}
// FAIL — the shot needs rework, so the comp task goes back to CHANGES.
const updated =
exportRow.status === "QC_FAILED"
? exportRow
: await applyTransition(tx, exportRow, "QC_FAILED", {
type: "USER",
id: reviewedById,
note: `QC FAIL by ${who}${input.notes ? ` — ${input.notes.slice(0, 200)}` : ""}`,
});
if (exportRow.taskId) {
const task = await tx.task.findUnique({ where: { id: exportRow.taskId }, select: { id: true, status: true } });
if (task && task.status !== "CHANGES") {
await tx.task.update({ where: { id: task.id }, data: { status: "CHANGES" } });
taskUpdated = { id: task.id, status: "CHANGES" };
}
}
return {
export: { id: updated.id, status: updated.status },
review: { id: review.id, result, createdAt: review.createdAt },
task: taskUpdated,
};
});
}
export interface QCQueueFilter {
projectCode?: string | null;
projectId?: string | null;
episode?: string | null;
limit?: number;
}
/**
* E5 — everything waiting for a human. QC_FAILED is deliberately excluded: a
* failed export is the artist's problem until they queue a new version.
*/
export async function getQCQueue(filter: QCQueueFilter) {
const limit = Math.min(200, Math.max(1, filter.limit ?? 50));
const where: Prisma.ExportWhereInput = {
status: "READY_FOR_QC",
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.projectCode ? { shot: { project: { code: filter.projectCode } } } : {}),
...(filter.episode
? { shot: { ...(filter.projectCode ? { project: { code: filter.projectCode } } : {}), episode: filter.episode } }
: {}),
};
const rows = await db.export.findMany({
where,
orderBy: { statusChangedAt: "asc" }, // oldest first — nothing should sit in QC
take: limit,
include: {
shot: { select: { id: true, shotCode: true, episode: true, scene: true, project: { select: { code: true, name: true } } } },
validations: { where: { status: { in: ["FAIL", "WARN"] } }, select: { checkName: true, status: true, message: true } },
},
});
return {
queue: rows.map((e) => ({
exportId: e.id,
shotCode: e.shot.shotCode,
episode: e.shot.episode,
scene: e.shot.scene,
projectCode: e.shot.project.code,
versionString: e.versionString,
readySince: e.statusChangedAt,
// Everything the panel needs to import the actual EXRs for full-res QC
outputDir: e.outputDir,
outputPattern: e.outputPattern,
frameStart: e.frameStart,
frameEnd: e.frameEnd,
fps: e.fps,
deliveryMovPath: e.deliveryMovPath,
thumbnailUrl: e.thumbnailKey ? `/api/files/${e.thumbnailKey}` : null,
previewUrl: e.previewMovKey ? `/api/files/${e.previewMovKey}` : null,
// Warnings the automated pass raised — the human should look harder at these
warnings: e.validations.map((v) => ({ checkName: v.checkName, status: v.status, message: v.message })),
})),
};
}
+22 -4
View File
@@ -29,6 +29,21 @@ export async function reapExpiredLeases() {
where: { id: job.id },
data: { status: "EXPIRED", finishedAt: new Date(), errorMessage: "Lease expired (worker unreachable)" },
});
// A delivery build that died leaves a half-written folder, so it is
// failed rather than silently retried: someone should look at what
// landed on the delivery volume before it is rebuilt.
if (job.deliveryId) {
await tx.deliveryPackage.updateMany({
where: { id: job.deliveryId, status: "BUILDING" },
data: {
status: "FAILED",
errorMessage: "Worker became unreachable mid-build — check the package folder before rebuilding",
},
});
return;
}
if (!job.export) return;
if (job.attempt < job.maxAttempts) {
@@ -42,16 +57,19 @@ export async function reapExpiredLeases() {
manifest: job.manifest as Prisma.InputJsonValue,
},
});
if (job.export.status === "RENDERING") {
// VALIDATING counts too: the worker holds the same job through the
// validation stage, so dying there means the render must be redone —
// nothing was established about the EXRs either way.
if (["RENDERING", "VALIDATING"].includes(job.export.status)) {
await applyTransition(tx, job.export, "QUEUED", {
type: "SYSTEM",
note: `Lease expired on attempt ${job.attempt} — requeued as attempt ${next.attempt}`,
note: `Lease expired on attempt ${job.attempt} during ${job.export.status} — requeued as attempt ${next.attempt}`,
});
}
} else if (job.export.status === "RENDERING") {
} else if (["RENDERING", "VALIDATING"].includes(job.export.status)) {
await applyTransition(tx, job.export, "RENDER_FAILED", {
type: "SYSTEM",
note: `Lease expired on attempt ${job.attempt}/${job.maxAttempts} — no retries remain`,
note: `Lease expired on attempt ${job.attempt}/${job.maxAttempts} during ${job.export.status} — no retries remain`,
});
}
});
+8 -6
View File
@@ -5,22 +5,24 @@ import { PipelineError } from "./errors";
* Export lifecycle state machine (RenderPipeline2 §4).
* The server is the sole authority on state; workers *request* transitions.
*
* NOTE (Phase 2 interim): RENDERING → READY_FOR_QC is temporarily legal.
* Phase 3 inserts VALIDATING between them (§17.3) — remove READY_FOR_QC from
* RENDERING's list when the validation engine ships.
* RENDERING → GENERATING_PREVIEW / READY_FOR_QC are the `validation.enabled=false`
* paths (the Phase 3 kill switch, §8), not interim edges: with validation on,
* a completed render always goes RENDERING → VALIDATING first.
*/
export const EXPORT_TRANSITIONS: Record<ExportStatus, ExportStatus[]> = {
QUEUED: ["RENDERING", "CANCELLED", "SUPERSEDED", "READY_FOR_QC"], // READY_FOR_QC: manual mark-done only
RENDERING: [
"VALIDATING",
"GENERATING_PREVIEW", // interim: preview stage runs before validation exists
"GENERATING_PREVIEW", // validation disabled
"RENDER_FAILED",
"QUEUED", // lease expiry / retryable fail with attempts remaining (T5)
"CANCELLED",
"READY_FOR_QC", // preview disabled / manual mark-done
"READY_FOR_QC", // preview + validation disabled / manual mark-done
],
RENDER_FAILED: ["QUEUED", "SUPERSEDED"],
VALIDATING: ["VALIDATION_FAILED", "GENERATING_PREVIEW"],
// QUEUED/RENDER_FAILED: the worker died *during* validation, so the render is
// retried — nothing was learned about the EXRs either way (reaper).
VALIDATING: ["VALIDATION_FAILED", "GENERATING_PREVIEW", "READY_FOR_QC", "QUEUED", "RENDER_FAILED", "CANCELLED"],
VALIDATION_FAILED: ["QUEUED", "SUPERSEDED"],
GENERATING_PREVIEW: ["PREVIEW_FAILED", "READY_FOR_QC"],
PREVIEW_FAILED: ["GENERATING_PREVIEW", "SUPERSEDED"],
+284
View File
@@ -0,0 +1,284 @@
import { Prisma, ValidationStatus } from "@prisma/client";
import { z } from "zod";
import { db } from "@/lib/db";
import { PipelineError } from "./errors";
import { applyTransition } from "./transitions";
import { getConfigBoolean, getConfigValue, getPreviewConfig } from "./config";
import { buildPreviewManifest, createPreviewJob } from "./preview";
/**
* Validation engine results (RenderPipeline2 §8). The worker runs the checks —
* it has the files — and reports every result in one call. The server decides
* what they mean: it is the only thing that moves an Export's state.
*/
export const validationCheckSchema = z.object({
checkName: z.string().min(1).max(64),
status: z.enum(["PASS", "FAIL", "WARN", "SKIPPED"]),
expected: z.string().max(500).optional().nullable(),
actual: z.string().max(500).optional().nullable(),
message: z.string().max(2000).optional().nullable(),
details: z.unknown().optional(),
});
export const validationReportSchema = z.object({
machineId: z.string().min(1),
checks: z.array(validationCheckSchema).min(1).max(200),
/** Sequence-level digest reused by the delivery builder for copy verification. */
checksum: z.string().max(200).optional(),
checksumAlgo: z.string().max(32).optional(),
exrFileCount: z.number().int().nonnegative().optional(),
exrTotalBytes: z.number().nonnegative().optional(),
validationSeconds: z.number().nonnegative().optional(),
});
export type ValidationReport = z.infer<typeof validationReportSchema>;
/**
* Per-check severity overrides, e.g. `{"exr_type":"warn"}` (§17.3 risk row).
* A false FAIL blocks an artist, so a check can be demoted without a redeploy.
* `timecode_plate_match` is deliberately overridable too — but demoting it
* should be a considered, temporary act: it is the check the engine exists for.
*/
async function getSeverityOverrides(): Promise<Record<string, ValidationStatus>> {
const raw = await getConfigValue("validation.overrides");
if (!raw?.trim()) return {};
try {
const parsed = JSON.parse(raw) as Record<string, string>;
const out: Record<string, ValidationStatus> = {};
for (const [check, level] of Object.entries(parsed)) {
const up = String(level).toUpperCase();
if (up === "PASS" || up === "FAIL" || up === "WARN" || up === "SKIPPED") {
out[check] = up as ValidationStatus;
}
}
return out;
} catch {
console.error("[render-pipeline] validation.overrides is not valid JSON — ignoring");
return {};
}
}
function summarise(checks: { checkName: string; status: ValidationStatus }[]): string {
const counts = { PASS: 0, FAIL: 0, WARN: 0, SKIPPED: 0 };
for (const c of checks) counts[c.status] += 1;
return `${counts.PASS} passed, ${counts.FAIL} failed, ${counts.WARN} warned, ${counts.SKIPPED} skipped`;
}
/**
* E12 — the worker reports every check from one validation run.
*
* Any FAIL stops the pipeline (§8.2): Export → VALIDATION_FAILED with the exact
* reasons queryable as rows. Otherwise the preview stage is queued, exactly as
* a successful render used to do directly.
*/
export async function reportValidation(jobId: string, body: ValidationReport) {
const overrides = await getSeverityOverrides();
const previewEnabled = (await getPreviewConfig()).enabled;
const effective = body.checks.map((c) => ({
...c,
status: (overrides[c.checkName] ?? c.status) as ValidationStatus,
overridden: overrides[c.checkName] != null && overrides[c.checkName] !== c.status,
}));
return db.$transaction(async (tx) => {
const job = await tx.renderJob.findUnique({
where: { id: jobId },
include: { export: 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 exportRow = job.export;
if (!exportRow) throw new PipelineError(422, "Job has no export to validate");
// Replayed report (worker retried the call after a network cut): the rows
// for this attempt already exist, so don't duplicate them or re-transition.
const existing = await tx.validationResult.count({
where: { exportId: exportRow.id, renderJobId: job.id },
});
if (existing > 0) {
return {
export: { id: exportRow.id, status: exportRow.status },
results: existing,
failed: exportRow.status === "VALIDATION_FAILED",
alreadyApplied: true,
};
}
if (exportRow.status !== "VALIDATING") {
throw new PipelineError(
409,
`Export is ${exportRow.status} — validation results are only accepted while VALIDATING`
);
}
// The render job was held open through validation (see completeRender) so a
// worker dying here is still reaped; the work is finished now.
await tx.renderJob.update({
where: { id: job.id },
data: { status: "COMPLETED", progress: 1, finishedAt: new Date() },
});
await tx.validationResult.createMany({
data: effective.map((c) => ({
exportId: exportRow.id,
renderJobId: job.id,
checkName: c.checkName,
status: c.status,
expected: c.expected ?? null,
actual: c.actual ?? null,
message: c.overridden
? `${c.message ?? "check reported " + c.status} [severity overridden by config]`
: (c.message ?? null),
details: (c.details ?? undefined) as Prisma.InputJsonValue | undefined,
})),
});
const failures = effective.filter((c) => c.status === "FAIL");
const stats = {
...(body.exrFileCount != null ? { exrFileCount: body.exrFileCount } : {}),
...(body.exrTotalBytes != null ? { exrTotalBytes: BigInt(Math.round(body.exrTotalBytes)) } : {}),
...(body.checksum ? { checksum: body.checksum } : {}),
};
const summary = summarise(effective);
if (failures.length > 0) {
const reasons = failures
.slice(0, 5)
.map((f) => `${f.checkName}: ${f.message ?? `expected ${f.expected}, got ${f.actual}`}`)
.join("; ");
const updated = await applyTransition(
tx,
exportRow,
"VALIDATION_FAILED",
{
type: "WORKER",
id: body.machineId,
note: `Validation failed (${summary}) — ${reasons}${failures.length > 5 ? ` (+${failures.length - 5} more)` : ""}`,
},
stats
);
return {
export: { id: updated.id, status: updated.status },
results: effective.length,
failed: true,
failures: failures.map((f) => f.checkName),
alreadyApplied: false,
};
}
// Passed: hand off to the preview stage, the same handoff completeRender
// used to make directly before validation existed.
if (!previewEnabled) {
const updated = await applyTransition(
tx,
exportRow,
"READY_FOR_QC",
{ type: "WORKER", id: body.machineId, note: `Validation passed (${summary}); preview stage disabled` },
stats
);
return {
export: { id: updated.id, status: updated.status },
results: effective.length,
failed: false,
previewJob: null,
alreadyApplied: false,
};
}
const manifest = await buildPreviewManifest(exportRow);
const previewJob = await createPreviewJob(tx, exportRow, manifest, job.maxAttempts, job.priority);
const updated = await applyTransition(
tx,
exportRow,
"GENERATING_PREVIEW",
{ type: "WORKER", id: body.machineId, note: `Validation passed (${summary}) — queued preview build` },
stats
);
return {
export: { id: updated.id, status: updated.status },
results: effective.length,
failed: false,
previewJob: { id: previewJob.id, type: previewJob.type },
alreadyApplied: false,
};
});
}
/** Whether the validation stage runs at all (kill switch for a bad engine release). */
export async function isValidationEnabled(): Promise<boolean> {
return getConfigBoolean("validation.enabled");
}
export interface ValidationBrowserFilter {
projectId?: string;
episode?: string;
checkName?: string;
status?: ValidationStatus;
page?: number;
limit?: number;
}
/**
* Cross-export browser (§13) — the point is spotting a systemic fault
* ("every shot this week failed timecode_plate_match"), not one bad render.
*/
export async function listValidationResults(filter: ValidationBrowserFilter) {
const page = Math.max(1, filter.page ?? 1);
const limit = Math.min(200, Math.max(1, filter.limit ?? 50));
const where: Prisma.ValidationResultWhereInput = {
...(filter.checkName ? { checkName: filter.checkName } : {}),
...(filter.status ? { status: filter.status } : { status: { in: ["FAIL", "WARN"] } }),
...(filter.projectId || filter.episode
? {
export: {
...(filter.projectId ? { projectId: filter.projectId } : {}),
...(filter.episode ? { shot: { episode: filter.episode } } : {}),
},
}
: {}),
};
const [total, rows] = await Promise.all([
db.validationResult.count({ where }),
db.validationResult.findMany({
where,
orderBy: { createdAt: "desc" },
skip: (page - 1) * limit,
take: limit,
include: {
export: {
select: {
id: true,
versionString: true,
status: true,
shot: { select: { shotCode: true, episode: true } },
},
},
},
}),
]);
return {
pagination: { page, limit, total, pages: Math.ceil(total / limit) },
results: rows.map((r) => ({
id: r.id,
checkName: r.checkName,
status: r.status,
expected: r.expected,
actual: r.actual,
message: r.message,
details: r.details,
createdAt: r.createdAt,
exportId: r.exportId,
versionString: r.export.versionString,
exportStatus: r.export.status,
shotCode: r.export.shot.shotCode,
episode: r.export.shot.episode,
})),
};
}