@rig-c/create 0.0.0-stage → 1.0.1

package/src/review-read.ts

@@ -0,0 +1,238 @@
+/** Read Review through its CLI and retain the exact response bytes owned by create.
+ * Every Review read (feedback and parts) spawns through one path and is bound at check time by one stored-read validator. */
+import { createHash } from 'node:crypto';
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, realpathSync } from './check-reads.ts';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { REVIEW_COMMENTS_SESSION_SCHEMA, REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA,
+    parseCommentsSession, parseCommentsCompareSession, projectSelectedCommentsFeedback } from '@rig-c/review/job-host';
+import { jobRuntimeExecArgv } from './job-writer.ts';
+import type { JsonObject } from './templates.ts';
+export const REVIEW_READ_SINCE = '2026-11-08T00:00:00Z';
+/** `unavailable`: the stored file is missing or not a regular file; `changed`: its bytes differ from the binding. */
+export type ReviewReadReason = 'invalid' | 'unavailable' | 'changed';
+export class ReviewReadError extends Error {
+    readonly code = 'REVIEW_READ_INVALID';
+    constructor(readonly why: string, readonly reason: ReviewReadReason = 'invalid') {
+        super(`evidence/review-reads: ${why}; retrieve the saved result through rig-review feedback --format json and retain its CLI receipt`);
+    }
+}
+export interface ReviewReadResult {
+    stdout: Buffer;
+    stderr: string;
+    exitCode: number;
+    tool: {
+        name: string;
+        version: string;
+    };
+}
+export type ReviewReadRunner = (dir: string, argv: string[]) => ReviewReadResult;
+export interface StoredReviewRead {
+    path: string;
+    sha256: string;
+}
+const object = (value: unknown): value is JsonObject => value !== null && typeof value === 'object' && !Array.isArray(value);
+const sha = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
+const invalid = (why: string, reason?: ReviewReadReason): never => { throw new ReviewReadError(why, reason); };
+const message = (error: unknown): string => error instanceof Error ? error.message : String(error);
+function safePath(dir: string, path: string): string {
+    if (isAbsolute(path) || path.includes('\\') || path.split('/').some(part => !part || part === '.' || part === '..'))
+        invalid('expected a literal project-relative response path');
+    let file = realpathSync(dir);
+    for (const [index, part] of path.split('/').entries()) {
+        file = join(file, part);
+        let stat;
+        try { stat = lstatSync(file); }
+        catch { return invalid(`${path} is unavailable`, 'unavailable'); }
+        if (stat.isSymbolicLink() || (index === path.split('/').length - 1 ? !stat.isFile() : !stat.isDirectory()))
+            invalid('response path contains a symlink or nonregular entry', 'unavailable');
+    }
+    return file;
+}
+function syncDirectory(path: string): void {
+    const fd = openSync(path, 'r');
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+function session(bytes: Buffer): JsonObject {
+    let value: unknown;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        return invalid('CLI stdout is not JSON');
+    }
+    if (object(value) && value.schema === REVIEW_COMMENTS_SESSION_SCHEMA)
+        return parseCommentsSession(value) as unknown as JsonObject;
+    if (object(value) && value.schema === REVIEW_COMMENTS_COMPARE_SESSION_SCHEMA)
+        return parseCommentsCompareSession(value) as unknown as JsonObject;
+    if (!object(value) || value.schema !== 'rig-review-session/1' || !Array.isArray(value.feedback))
+        return invalid('CLI stdout must contain a single review session');
+    return value;
+}
+/** The single-build source required by Create's existing Apply adapters. */
+export function reviewSessionSource(value: JsonObject): JsonObject | null {
+    return (value.schema === 'rig-review-session/1' || value.schema === REVIEW_COMMENTS_SESSION_SCHEMA) && object(value.reviewedSource)
+        ? value.reviewedSource : null;
+}
+
+/** Select canonical feedback rows while retaining the original session and bytes. */
+export function selectedReviewFeedback(value: JsonObject, itemId: string): JsonObject[] {
+    if (value.schema === REVIEW_COMMENTS_SESSION_SCHEMA) {
+        const parsed = parseCommentsSession(value);
+        const matches = parsed.comments.filter(comment => comment.anchor && 'frameStart' in comment.anchor && comment.anchor.id === itemId);
+        if (matches.length !== 1) return [];
+        const selected = projectSelectedCommentsFeedback(parsed, itemId);
+        return [{ ...selected.anchor, summary: selected.summary } as unknown as JsonObject];
+    }
+    return Array.isArray(value.feedback)
+        ? value.feedback.filter(object).filter(item => item.id === itemId) : [];
+}
+
+/** Review is resolved from the project, then its collection, then create's own installation. */
+function reviewRoot(dir: string): string | undefined {
+    const collection = basename(dirname(dir)) === 'members' ? [join(dirname(dirname(dir)), 'node_modules/@rig-c/review')] : [];
+    let installed: string[] = [];
+    try { installed = [dirname(fileURLToPath(import.meta.resolve('@rig-c/review/package.json')))]; }
+    catch { /* Not installed with create. */ }
+    return [join(dir, 'node_modules/@rig-c/review'), ...collection, ...installed].find(path => existsSync(join(path, 'package.json')));
+}
+function runReview(dir: string, argv: string[]): ReviewReadResult {
+    const root = reviewRoot(dir);
+    if (!root)
+        return invalid('install @rig-c/review before querying it');
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+        name: string;
+        version: string;
+        bin: Record<string, string>;
+    };
+    if (pkg.name !== '@rig-c/review' || typeof pkg.version !== 'string' || typeof pkg.bin?.['rig-review'] !== 'string')
+        return invalid('installed Review has no rig-review CLI');
+    const result = Bun.spawnSync([process.execPath, ...jobRuntimeExecArgv(), join(root, pkg.bin['rig-review']), ...argv.slice(1)], { cwd: dir, stdout: 'pipe', stderr: 'pipe', timeout: 60_000 });
+    return { stdout: result.stdout, stderr: result.stderr.toString('utf8'), exitCode: result.exitCode, tool: { name: pkg.name, version: pkg.version } };
+}
+/** The one spawn path: resolve Review, run `rig-review <argv>`, then check its exit code and tool identity. */
+function runReviewCli(dir: string, argv: string[], runner: ReviewReadRunner): ReviewReadResult {
+    let result: ReviewReadResult;
+    try {
+        result = runner(dir, [...argv]);
+    }
+    catch (error) {
+        if (error instanceof ReviewReadError)
+            throw error;
+        return invalid(`${argv[1]} could not run: ${message(error)}`);
+    }
+    if (result.exitCode !== 0)
+        return invalid(`${argv[1]} exited ${result.exitCode}: ${result.stderr.trim() || 'no diagnostic returned'}`);
+    if (result.tool?.name !== '@rig-c/review' || typeof result.tool.version !== 'string' || !result.tool.version.trim())
+        return invalid('CLI tool name and version are required');
+    return result;
+}
+/** Retain stdout once under its sha256. `created` is false when the same bytes were already stored. */
+export function storeReviewRead(dir: string, bytes: Buffer): { file: StoredReviewRead; created: boolean } {
+    const digest = sha(bytes);
+    const path = `evidence/review-reads/${digest}.json`;
+    // Create one directory at a time, checking each ancestor before using it.
+    let parent = realpathSync(dir);
+    for (const part of ['evidence', 'review-reads']) {
+        parent = join(parent, part);
+        let made = false;
+        try {
+            mkdirSync(parent);
+            made = true;
+        }
+        catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'EEXIST')
+                throw error;
+        }
+        const stat = lstatSync(parent);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return invalid('response store must use real directories');
+        if (made)
+            syncDirectory(dirname(parent));
+    }
+    const temporary = join(parent, `.review-read-${process.pid}-${crypto.randomUUID()}.tmp`);
+    let created = false;
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try { writeFileSync(fd, bytes); fsyncSync(fd); } finally { closeSync(fd); }
+        try {
+            linkSync(temporary, join(parent, `${digest}.json`));
+            created = true;
+        }
+        catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        }
+    } finally {
+        rmSync(temporary, { force: true });
+    }
+    if (created)
+        syncDirectory(parent);
+    if (!readFileSync(safePath(dir, path)).equals(bytes))
+        return invalid('existing content-addressed response differs from stdout');
+    return { file: { path, sha256: digest }, created };
+}
+/** The one stored-read validator. Check consumes only create's stored stdout and never invokes Review. */
+export function storedReviewRead(dir: string, stdout: unknown): Buffer {
+    try {
+        if (!object(stdout) || typeof stdout.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(stdout.sha256)
+            || stdout.path !== `evidence/review-reads/${stdout.sha256}.json`)
+            return invalid('stdout binding must name its content-addressed response');
+        const bytes = readFileSync(safePath(dir, stdout.path));
+        if (sha(bytes) !== stdout.sha256)
+            return invalid('stored stdout differs from its sha256', 'changed');
+        return bytes;
+    }
+    catch (error) {
+        if (error instanceof ReviewReadError)
+            throw error;
+        return invalid(message(error), 'unavailable');
+    }
+}
+/** Parts read: `rig-review parts <args> --format json`. Decoding and the draft binding belong to the parts route. */
+export function readPartsReview(dir: string, args: string[], runner: ReviewReadRunner = runReview): ReviewReadResult {
+    return runReviewCli(dir, ['rig-review', 'parts', ...args, '--format', 'json'], runner);
+}
+export function readReview(dir: string, input: string, runner: ReviewReadRunner = runReview): {
+    receipt: JsonObject;
+    value: JsonObject;
+    file: JsonObject;
+} {
+    try {
+        const argv = ['rig-review', 'feedback', input, '--format', 'json'];
+        const result = runReviewCli(dir, argv, runner);
+        const value = session(result.stdout);
+        const { file } = storeReviewRead(dir, result.stdout);
+        const receipt: JsonObject = { route: 'cli', argv, stdout: { ...file }, tool: result.tool };
+        return { receipt, value, file: { ...file } };
+    }
+    catch (error) {
+        if (error instanceof ReviewReadError)
+            throw error;
+        return invalid(message(error));
+    }
+}
+/** A feedback read's inline receipt, bound through the shared stored-read validator. */
+export function retainedReviewRead(dir: string, receipt: unknown, expected?: unknown): JsonObject {
+    try {
+        if (!object(receipt) || Object.keys(receipt).sort().join(',') !== 'argv,route,stdout,tool' || receipt.route !== 'cli'
+            || !Array.isArray(receipt.argv) || receipt.argv.length !== 5 || receipt.argv.some(arg => typeof arg !== 'string')
+            || receipt.argv[0] !== 'rig-review' || receipt.argv[1] !== 'feedback' || !receipt.argv[2] || receipt.argv[3] !== '--format' || receipt.argv[4] !== 'json'
+            || !object(receipt.tool) || Object.keys(receipt.tool).sort().join(',') !== 'name,version' || receipt.tool.name !== '@rig-c/review' || typeof receipt.tool.version !== 'string' || !receipt.tool.version.trim()
+            || !object(receipt.stdout) || Object.keys(receipt.stdout).sort().join(',') !== 'path,sha256' || typeof receipt.stdout.sha256 !== 'string'
+            || !/^[a-f0-9]{64}$/.test(receipt.stdout.sha256) || receipt.stdout.path !== `evidence/review-reads/${receipt.stdout.sha256}.json`)
+            return invalid('invalid CLI receipt');
+        if (expected !== undefined && (!object(expected) || Object.keys(expected).sort().join(',') !== 'path,sha256' || expected.path !== receipt.stdout.path || expected.sha256 !== receipt.stdout.sha256))
+            return invalid('record binding differs from the CLI stdout binding');
+        return session(storedReviewRead(dir, receipt.stdout));
+    }
+    catch (error) {
+        if (error instanceof ReviewReadError)
+            throw error;
+        return invalid(message(error));
+    }
+}
+export function reviewReadLegacy(at: unknown): boolean {
+    const time = typeof at === 'string' ? Date.parse(at) : Number.NaN;
+    return !Number.isFinite(time) || time < Date.parse(REVIEW_READ_SINCE);
+}

package/src/review.ts

@@ -0,0 +1,432 @@
+import { assertCorrectionApproval } from './correction-writers.ts';
+import { assertFigureMaskApproval } from './figure-mask.ts';
+/**
+ * The two reviews and the hand-off between them (rig-c/create#8,
+ * docs/PROJECT.md § Stages, § The rig review rests on a still frame,
+ * § The hand-off to post-production).
+ *
+ * The rig is accepted first, on a still frame with a fixed camera; post work
+ * (camera, 2.5D depth, timing, composition) runs only on the rig version that
+ * acceptance names. What is recorded where:
+ *
+ * - **Which rig version was accepted** is the human `accepted` verdict with
+ *   `review: "rig-review"` on that `versions[]` entry (kind `rig`). The
+ *   `{ stage: "rig-review" }` sign-off moves the stage; the verdict names the
+ *   version. Both are written in the same turn.
+ * - **What the acceptance rested on** is a `kind: "still"` entry in that
+ *   version's `evidence[]`: `path`, `sha256`, `camera: "fixed"`, `frame`.
+ * - **Which rig the post work is on** is a post version's `rig_version`, and
+ *   `rig-create handoff` is what post tooling asks before it runs.
+ *
+ * `checkReviews` runs inside `interview --check`; `handoff` is the command.
+ * Both read the record only: nothing is rendered or signed here.
+ */
+import { existsSync, readFileSync } from './check-reads.ts';
+import { join, resolve } from 'node:path';
+
+import { draftVersionFindings } from './drafts.ts';
+import { checkPreInterview } from './pre-interview.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { collectReopens, liveSignoff, reopenIndex, reopenTime, type Reopen } from './reopen.ts';
+import { PAUSED_STAGE, RIG_REVIEW, stageIndex } from './stages.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+/** The part of `interview --check`'s context this module reads and writes. */
+export interface ReviewCtx {
+  readonly project: JsonObject;
+  readonly effectiveStage: string;
+  readonly refusals: { code: string; path: string; message: string }[];
+}
+
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export interface Acceptance {
+  readonly verdict: number;
+  readonly by: string;
+  readonly at: string;
+  readonly verbatim: string | null;
+  readonly source?: string;
+  readonly note?: string;
+}
+
+export interface Still {
+  readonly evidence: number;
+  readonly path: string;
+  readonly sha256: string;
+  /** Seconds into the motion, or `setup`: the renderer's setup pose, which an idle may pass through rather than start at. */
+  readonly frame: number | 'setup';
+}
+
+export interface RigVersion {
+  readonly preInterview: boolean;
+  readonly configLost?: { readonly note: string; readonly source: string };
+  readonly outputsLost?: { readonly note: string; readonly source: string };
+  readonly live: boolean;
+  readonly n: number;
+  readonly path: string;
+  /** When the version was built; a reopen or amendment after it makes the version history (`live: false`). */
+  readonly at: string | null;
+  /** The last human `accepted` verdict at `rig-review`, or `null`. */
+  readonly accepted: Acceptance | null;
+  /** The well-formed still-frame evidence entries. */
+  readonly stills: Still[];
+  readonly malformedStills: { index: number; why: string }[];
+}
+
+export interface PostVersion {
+  readonly n: number;
+  readonly path: string;
+  readonly at: string | null;
+  readonly live: boolean;
+  readonly rigVersion: Json | undefined;
+}
+
+export interface Versions {
+  readonly rigs: RigVersion[];
+  readonly posts: PostVersion[];
+  readonly malformed: { path: string; why: string }[];
+}
+
+function isObject(v: Json | undefined): v is JsonObject {
+  return v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v);
+}
+function asArray(v: Json | undefined): Json[] {
+  return Array.isArray(v) ? v : [];
+}
+function asString(v: Json | undefined): string | null {
+  return typeof v === 'string' ? v : null;
+}
+function isHuman(by: string | null): by is string {
+  return by !== null && by.toLowerCase() !== 'agent';
+}
+
+/** Human, non-provisional verdicts retain their original array indices. */
+export function humanReviewVerdicts(value: Json | undefined, stage: string): { index: number; record: JsonObject }[] {
+  return asArray(value).flatMap((record, index) =>
+    isObject(record) && record.review === stage && isHuman(asString(record.by)) && record.verdict !== 'provisional'
+      ? [{ index, record }] : []);
+}
+
+/** A later human verdict withdraws any earlier acceptance. */
+export function acceptedReviewVerdict(version: JsonObject, stage: string): number {
+  const last = humanReviewVerdicts(version.verdicts, stage).at(-1);
+  return last?.record.verdict === 'accepted' ? last.index : -1;
+}
+
+function readStill(e: JsonObject): Still | string {
+  const missing = ['path', 'sha256'].filter((k) => asString(e[k]) === null);
+  if (missing.length > 0) return `missing ${missing.join(', ')}`;
+  if (!SHA256.test(e.sha256 as string)) return 'sha256 is not 64 lowercase hex digits';
+  if (e.camera !== 'fixed') return `camera is ${JSON.stringify(e.camera ?? null)}; the rig review is on a fixed camera ("camera": "fixed")`;
+  if (e.frame === 'setup') return { evidence: -1, path: e.path as string, sha256: e.sha256 as string, frame: 'setup' };
+  if (typeof e.frame !== 'number' || !Number.isFinite(e.frame) || e.frame < 0) {
+    return `frame is ${JSON.stringify(e.frame ?? null)}; it is "setup" for the renderer's setup pose, or the time in seconds into the motion the still is posed at (0 is the motion's start, not necessarily the setup pose)`;
+  }
+  return { evidence: -1, path: e.path as string, sha256: e.sha256 as string, frame: e.frame };
+}
+
+/** Reads `versions[]` into rig and post versions, in record order. Paths name a version by its number: `versions[v2]`. */
+export function readVersions(project: JsonObject): Versions {
+  const reopens = collectReopens(project, []);
+  const rigs: RigVersion[] = [];
+  const posts: PostVersion[] = [];
+  const malformed: { path: string; why: string }[] = [];
+  asArray(project.versions).forEach((v, index) => {
+    if (!isObject(v) || typeof v.n !== 'number' || !Number.isInteger(v.n)) {
+      malformed.push({ path: `versions[${index}]`, why: 'a version is an object with an integer n' });
+      return;
+    }
+    const path = `versions[v${v.n}]`;
+    if (v.kind === 'post') {
+      posts.push({ n: v.n, path, at: asString(v.at), rigVersion: v.rig_version, live: liveSignoff(reopens, 'post', Date.parse(asString(v.at) ?? '')) });
+      return;
+    }
+    if (v.kind !== 'rig') {
+      malformed.push({ path, why: `kind is 'rig' or 'post', got ${JSON.stringify(v.kind ?? null)}` });
+      return;
+    }
+    if (v.rig_version !== null && v.rig_version !== undefined) {
+      malformed.push({ path: `${path}.rig_version`, why: 'a rig version has rig_version null; only a post version names the rig it is built on' });
+    }
+    // The LAST human rig-review verdict decides: a later bounce withdraws an
+    // earlier acceptance. An acceptance must be dated, or the post-before-
+    // acceptance order cannot be checked.
+    let accepted: Acceptance | null = null;
+    for (const { index: verdict, record: d } of humanReviewVerdicts(v.verdicts, RIG_REVIEW)) {
+      if (d.verdict !== 'accepted') {
+        accepted = null;
+        continue;
+      }
+      const at = asString(d.at);
+      if (at === null || !Number.isFinite(Date.parse(at))) {
+        malformed.push({ path: `${path}.verdicts[${verdict}].at`, why: 'an acceptance carries a valid `at`; an undated acceptance authorises nothing' });
+        accepted = null;
+        continue;
+      }
+      accepted = { verdict, by: d.by as string, at, verbatim: asString(d.verbatim) ?? '' };
+      if (v.pre_interview === true) {
+        accepted = { ...accepted, verbatim: asString(d.verbatim), source: asString(d.source) ?? '', note: asString(d.note) ?? undefined };
+      }
+    }
+    const stills: Still[] = [];
+    const malformedStills: { index: number; why: string }[] = [];
+    asArray(v.evidence).forEach((e, i) => {
+      if (!isObject(e) || e.kind !== 'still') return;
+      const read = readStill(e);
+      if (typeof read === 'string') malformedStills.push({ index: i, why: read });
+      else stills.push({ ...read, evidence: i });
+    });
+    const outputsLost = v.pre_interview === true && isObject(v.outputs_lost)
+      ? { note: asString(v.outputs_lost.note) ?? '', source: asString(v.outputs_lost.source) ?? '' } : undefined;
+    const configLost = v.pre_interview === true && isObject(v.config_lost)
+      ? { note: asString(v.config_lost.note) ?? '', source: asString(v.config_lost.source) ?? '' } : undefined;
+    rigs.push({ configLost, outputsLost, n: v.n, path, at: asString(v.at), live: liveSignoff(reopens, RIG_REVIEW, Date.parse(asString(v.at) ?? '')), preInterview: v.pre_interview === true, accepted, stills, malformedStills });
+  });
+  return { rigs, posts, malformed };
+}
+
+/** The rig version with the highest number, accepted or not. */
+function latestRig(versions: Versions): RigVersion | null {
+  return versions.rigs.filter(r => r.live).reduce<RigVersion | null>((a, r) => (a === null || r.n > a.n ? r : a), null);
+}
+/** The accepted rig version with the highest number. */
+export function latestAccepted(versions: Versions): RigVersion | null {
+  return versions.rigs.filter((r) => r.live && r.accepted !== null).reduce<RigVersion | null>((a, r) => (a === null || r.n > a.n ? r : a), null);
+}
+
+/**
+ * When no live rig is accepted but an older one was: that accepted rig, and the first reopen or amendment after
+ * its build that made it history, named by its record path. An acceptance that lapsed this way is not a missing verdict.
+ */
+function lapsedAcceptance(project: JsonObject, versions: Versions): string | null {
+  const rig = versions.rigs.filter(r => !r.live && r.accepted !== null).reduce<RigVersion | null>((a, r) => (a === null || r.n > a.n ? r : a), null);
+  if (rig === null || rig.accepted === null) return null;
+  const built = Date.parse(rig.at ?? '');
+  const cutoff = collectReopens(project, []).filter(r => stageIndex(r.stage) <= stageIndex(RIG_REVIEW) && !(built > r.at))
+    .reduce<Reopen | null>((a, r) => (a === null || r.at < a.at ? r : a), null);
+  if (cutoff === null) return null;
+  const when = new Date(cutoff.at).toISOString();
+  // collectReopens appends amendment cutoffs, which carry their amendments[] index.
+  const amendment = 'index' in cutoff && typeof cutoff.index === 'number' ? cutoff.index : -1;
+  const reopen = reopenIndex(project, cutoff);
+  const by = amendment >= 0 ? `the amendment at ${when} (amendments[${amendment}])`
+    : `the reopen to ${cutoff.stage} at ${when} (reopens[${reopen}])`;
+  return `${rig.path}.verdicts[${rig.accepted.verdict}]: rig v${rig.n} was accepted at ${rig.accepted.at}, but ${by} made it history, so no live rig version is accepted; register a new rig version with rig-create rig-version <n> and accept it with rig-create review <n> --verdict accepted --review rig-review`;
+}
+
+/**
+ * A rig-review signature never rests on a lapsed acceptance (rig-c/create#243): refused before the write when no live
+ * rig version is accepted and a reopen or amendment made the accepted one history. With no acceptance at all, the
+ * target selection refuses (SIGNOFF_TARGET_STALE).
+ */
+export function assertRigReviewSignable(project: JsonObject, path: string): void {
+  const versions = readVersions(project);
+  if (latestAccepted(versions) !== null) return;
+  const lapsed = lapsedAcceptance(project, versions);
+  if (lapsed !== null) refuse('RIG_VERSION_UNACCEPTED', `${path}: rig-review would be signed on a lapsed acceptance: ${lapsed}, then sign rig-review`);
+}
+
+/** Why a post version's `rig_version` is not an accepted rig, or `null` when it is. */
+function postBasisProblem(post: PostVersion, versions: Versions): string | null {
+  const rv = post.rigVersion;
+  if (typeof rv !== 'number' || !Number.isInteger(rv)) {
+    return `${post.path}.rig_version is ${JSON.stringify(rv ?? null)}; a post version names the n of the accepted rig version it is built on`;
+  }
+  const rig = versions.rigs.find((r) => r.n === rv);
+  if (rig === undefined) return `${post.path}.rig_version=v${rv} names no rig version`;
+  if (rig.configLost !== undefined) return `${post.path}.rig_version=v${rv}: ${rig.path}.config_lost records a lost config; build and accept a new rig with its retained config before post work`;
+  if (rig.outputsLost !== undefined) return `${post.path}.rig_version=v${rv}: ${rig.path}.outputs_lost records lost outputs; build and accept a new rig with surviving frozen outputs before post work`;
+  if (rig.accepted === null) {
+    return `${post.path}.rig_version=v${rv}: rig v${rv} has no accepted rig-review verdict; post work runs only on a rig version the user accepted at rig-review`;
+  }
+  const builtAt = post.at === null ? Number.NaN : Date.parse(post.at);
+  const acceptedAt = Date.parse(rig.accepted.at);
+  if (!Number.isFinite(builtAt)) {
+    return `${post.path}.at is ${JSON.stringify(post.at)}; a post version is dated, or it cannot be shown to follow rig v${rv}'s acceptance`;
+  }
+  if (builtAt < acceptedAt) {
+    return `${post.path}.rig_version=v${rv}: v${post.n} was built at ${post.at}, before rig v${rv} was accepted at ${rig.accepted.at}`;
+  }
+  return null;
+}
+
+// ------------------------------------------------------- interview --check
+
+/** The review-order refusals, appended to `ctx.refusals` (codes in docs/CHECKS.md § Refusals). */
+export function checkReviews(ctx: ReviewCtx): void {
+  const versions = readVersions(ctx.project);
+  const push = (code: string, path: string, message: string): void => {
+    ctx.refusals.push({ code, path, message });
+  };
+  for (const m of versions.malformed) push('VERSION_MALFORMED', m.path, `${m.path}: ${m.why}`);
+
+  for (const rig of versions.rigs) {
+    for (const m of rig.malformedStills) {
+      const path = `${rig.path}.evidence[${m.index}]`;
+      push('STILL_MALFORMED', path, `${path}: a still-frame record is { kind: "still", path, sha256, camera: "fixed", frame }; ${m.why}`);
+    }
+    if (rig.accepted !== null && rig.stills.length === 0) {
+      const path = `${rig.path}.verdicts[${rig.accepted.verdict}]`;
+      push(
+        'RIG_ACCEPTED_WITHOUT_STILL',
+        path,
+        `${path}: rig v${rig.n} is accepted at rig-review, but its evidence[] has no still-frame record ({ kind: "still", path, sha256, camera: "fixed", frame }); the rig review rests on a still frame`,
+      );
+    }
+  }
+
+  for (const post of versions.posts) {
+    const problem = postBasisProblem(post, versions);
+    const since = reopenTime(collectReopens(ctx.project, []), RIG_REVIEW);
+    const basis = versions.rigs.find(r => r.n === post.rigVersion);
+    if (post.live && since !== -Infinity && basis !== undefined && !basis.live) {
+      push('POST_ON_SUPERSEDED_RIG', `${post.path}.rig_version`, `${post.path}: historical rig cannot authorise new post work; build and accept a new rig version`);
+    }
+    if (problem !== null) push('POST_ON_UNACCEPTED_RIG', `${post.path}.rig_version`, problem);
+  }
+
+  // Past rig-review, the rig the project stands on is the latest one, and it is accepted.
+  const reviewIdx = stageIndex(RIG_REVIEW);
+  const cur = stageIndex(ctx.effectiveStage);
+  if (ctx.effectiveStage !== PAUSED_STAGE && cur > reviewIdx) {
+    const latest = latestRig(versions);
+    const lapsed = latest === null ? lapsedAcceptance(ctx.project, versions) : null;
+    if (lapsed !== null) {
+      push('RIG_VERSION_UNACCEPTED', 'versions', `stage is past rig-review on a lapsed acceptance: ${lapsed}, at rig-review`);
+    } else if (latest === null) {
+      push('RIG_VERSION_UNACCEPTED', 'versions', `stage is past rig-review, but versions[] has no rig version for the review to have accepted`);
+    } else if (latest.accepted === null) {
+      push(
+        'RIG_VERSION_UNACCEPTED',
+        latest.path,
+        `rig v${latest.n} is the latest rig version and has no accepted rig-review verdict, but the stage is past rig-review; a rig change after rig-review is a new first review — the stage goes back to rig-review`,
+      );
+    }
+  }
+
+  // The current post version is on the current accepted rig; older post versions are history.
+  const accepted = latestAccepted(versions);
+  const currentPost = versions.posts.filter(p => p.live).reduce<PostVersion | null>((a, p) => (a === null || p.n > a.n ? p : a), null);
+  if (accepted !== null && currentPost !== null && postBasisProblem(currentPost, versions) === null && currentPost.rigVersion !== accepted.n) {
+    push(
+      'POST_ON_SUPERSEDED_RIG',
+      `${currentPost.path}.rig_version`,
+      `${currentPost.path}.rig_version=v${String(currentPost.rigVersion)}: rig v${accepted.n} was accepted since; the post work built on the old rig is redone on v${accepted.n}`,
+    );
+  }
+}
+
+// ------------------------------------------------------------------ handoff
+
+export interface Handoff {
+  readonly ok: true;
+  readonly project_dir: string;
+  readonly rig_version: number;
+  readonly pre_interview: boolean;
+  readonly accepted: Acceptance;
+  readonly still: Still;
+  readonly outputs_lost?: readonly { readonly version: number; readonly note: string; readonly source: string }[];
+}
+
+/**
+ * The hand-off: the one rig version post work may run on, or a named refusal.
+ * With `rig`, also refuses when that is not the version.
+ */
+export function handoff(projectDirArg: string, rig: number | null, now: number): Handoff {
+  const dir = resolve(projectDirArg);
+  const file = join(dir, 'project.json');
+  if (!existsSync(file)) refuse('PROJECT_JSON_MISSING', `${file} does not exist; run in a project folder or name one`);
+  let project: unknown;
+  try {
+    project = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    refuse('PROJECT_JSON_INVALID', `${file}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!isObject(project as Json)) refuse('PROJECT_JSON_INVALID', `${file}: not a JSON object`);
+  const record = project as JsonObject;
+  assertCorrectionApproval(dir, record, RIG_REVIEW, now);
+  const historyRefusals: ReviewCtx['refusals'] = draftVersionFindings(dir, record);
+  checkPreInterview({ dir, project: record, refusals: historyRefusals, warnings: [] });
+  const first = historyRefusals[0];
+  if (first !== undefined) refuse(first.code, first.message);
+
+  const reopens = collectReopens(record, historyRefusals);
+  if (historyRefusals[0] !== undefined) refuse(historyRefusals[0].code, historyRefusals[0].message);
+  const signed = asArray(record.signoffs).some(
+    (s) => isObject(s) && liveSignoff(reopens, RIG_REVIEW, Date.parse(asString(s.at) ?? '')) && s.stage === RIG_REVIEW && (s.checkpoint ?? null) === null && isHuman(asString(s.by)) && asString(s.verbatim) !== null,
+  );
+  if (!signed) refuse('RIG_REVIEW_UNSIGNED', `no human { "stage": "rig-review" } sign-off: no rig version has been handed to post-production`);
+
+  const versions = readVersions(record);
+  const accepted = latestAccepted(versions);
+  const latest = latestRig(versions);
+  if (accepted === null || accepted.accepted === null) {
+    const lapsed = lapsedAcceptance(record, versions);
+    refuse('RIG_VERSION_UNACCEPTED', lapsed !== null ? `rig-review is signed on a lapsed acceptance: ${lapsed} before post work runs`
+      : `rig-review is signed, but no rig version has an accepted rig-review verdict naming it`);
+  }
+  if (latest !== null && latest.n !== accepted.n) {
+    refuse(
+      'RIG_VERSION_UNACCEPTED',
+      `${latest.path}: rig v${latest.n} was built after rig v${accepted.n} was accepted and has no rig-review acceptance of its own; review it on its still frame before post work runs`,
+    );
+  }
+  if (accepted.configLost !== undefined) {
+    refuse('PRE_INTERVIEW_CONFIG_LOST', `${accepted.path}.config_lost: ${accepted.configLost.note}; source: ${accepted.configLost.source}; build and accept a new rig with its retained config before post work`);
+  }
+  if (accepted.outputsLost !== undefined) {
+    refuse('PRE_INTERVIEW_OUTPUTS_LOST', `${accepted.path}.outputs_lost: ${accepted.outputsLost.note}; source: ${accepted.outputsLost.source}; build and accept a new rig with surviving frozen outputs before post work`);
+  }
+  const still = accepted.stills[0];
+  if (still === undefined) {
+    refuse('RIG_ACCEPTED_WITHOUT_STILL', `${accepted.path}: rig v${accepted.n} is accepted with no still-frame record in its evidence[]`);
+  }
+  if (rig !== null && rig !== accepted.n) {
+    const named = versions.rigs.find((r) => r.n === rig);
+    if (named !== undefined && named.accepted !== null) {
+      refuse('POST_ON_SUPERSEDED_RIG', `versions[v${rig}]: rig v${rig} was accepted, but rig v${accepted.n} was accepted since; post work runs on v${accepted.n}`);
+    }
+    refuse('POST_ON_UNACCEPTED_RIG', `versions[v${rig}]: ${named === undefined ? 'no rig version has that number' : `rig v${rig} has no accepted rig-review verdict`}; post work runs on rig v${accepted.n}`);
+  }
+  assertFigureMaskApproval(dir, record, accepted.n);
+  const losses = asArray(record.versions).flatMap((v) => isObject(v) && v.pre_interview === true && isObject(v.outputs_lost)
+    ? [{ version: v.n as number, note: v.outputs_lost.note as string, source: v.outputs_lost.source as string }] : []);
+  return { ...(losses.length > 0 ? { outputs_lost: losses } : {}), ok: true, project_dir: dir, rig_version: accepted.n, pre_interview: accepted.preInterview, accepted: accepted.accepted, still };
+}
+
+export const HANDOFF_HELP = `handoff:
+  [<project dir>]  the project folder (default: the current directory)
+  --rig <n>        refuse unless rig version <n> is the one post work may run on
+  --json           print the hand-off as JSON (rig_version, accepted, still)
+  Post-production tooling runs this first. Exit 0 prints the accepted rig version; exit 1 is a named refusal
+  (RIG_REVIEW_UNSIGNED, RIG_VERSION_UNACCEPTED, RIG_ACCEPTED_WITHOUT_STILL, POST_ON_UNACCEPTED_RIG, POST_ON_SUPERSEDED_RIG).`;
+
+export function handoffCommand(args: string[], now: number): { stdout: string; exit: number } {
+  let json = false;
+  let rig: number | null = null;
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === '--json') json = true;
+    else if (arg === '--rig') {
+      const value = args[++i];
+      const n = value === undefined ? Number.NaN : Number(value.replace(/^v/, ''));
+      if (!Number.isInteger(n) || n < 1) refuse('HANDOFF_RIG_INVALID', `--rig takes a rig version number, got ${value ?? 'nothing'}`, USAGE_EXIT);
+      rig = n;
+    } else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `handoff does not take ${arg}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (positional.length > 1) refuse('HANDOFF_TOO_MANY_ARGUMENTS', `handoff takes one folder, got ${positional.join(' ')}`, USAGE_EXIT);
+  const h = handoff(positional[0] ?? process.cwd(), rig, now);
+  if (json) return { stdout: JSON.stringify(h, null, 2), exit: 0 };
+  return {
+    stdout: [
+      `handoff: post work is on rig v${h.rig_version}${h.pre_interview ? ' (pre-interview)' : ''}`,
+      `  accepted at rig-review by ${h.accepted.by} at ${h.accepted.at}: ${h.accepted.verbatim === null ? `record of the user: ${h.accepted.note}` : `"${h.accepted.verbatim}"`}`,
+      ...(h.pre_interview ? [`  source: ${h.accepted.source}`] : []),
+      ...(h.outputs_lost ?? []).map((loss) => `  v${loss.version} (pre-interview) outputs lost: ${loss.note}; source: ${loss.source}`),
+      `  still frame ${h.still.path} (sha256 ${h.still.sha256}, fixed camera, ${h.still.frame === 'setup' ? 'setup pose' : `${h.still.frame} s`})`,
+    ].join('\n'),
+    exit: 0,
+  };
+}