rig-create 0.0.0-stage → 1.0.0

package/src/review-package.ts

@@ -0,0 +1,524 @@
+import { recordedPartsVerdict, recordedPartsFinding } from './parts-verdict-record.ts';
+import { configInputReferences, configInputsLegacy, DIRECTORY_INPUT_RECEIPT, plateReceiptSpec, receiptSpec, type ConfigInputsWarning } from './config-inputs.ts';
+import { DirectionError, objects as directionObjects, readDirection } from './direction.ts';
+/** Frozen producer inputs in review's fixed discovery layout (create#38). */
+import { createHash } from 'node:crypto';
+import { closeSync, openSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from './check-reads.ts';
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { asArray, isObject, readJsonObject, type Ctx } from './check.ts';
+import { draftFileUnavailable, draftVersionFindings } from './drafts.ts';
+import { Refusal, refuse, USAGE_EXIT } from './refusal.ts';
+import { assertRigVersionDate, rigVersionDateFinding } from './rig-version-date.ts';
+import { latestPartsApproval, retainedJson } from './structure.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+const hash = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
+export const BUILD_IDENTITY_SINCE = '2026-11-06T00:00:00Z';
+export const PART_FILE_IDENTITY_SINCE = '2026-11-06T00:00:00Z';
+
+/** Compare declared identities even when regenerable package bytes are absent. */
+function checkBuildIdentity(ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'>, version: JsonObject, record: JsonObject): void {
+  const at = Date.parse(String(version.at));
+  const findings = Number.isFinite(at) && at >= Date.parse(BUILD_IDENTITY_SINCE) ? ctx.refusals : ctx.warnings;
+  const path = `versions[v${String(version.n)}].review_package`;
+  const mismatch = (code: string, field: string, expected: string, actual: string): void => {
+    findings.push({ code, path: `${path}.${field}`, message: `${path}.${field}: package sha256 ${actual} differs from recorded build sha256 ${expected}; preserve the historical package and record a new version from the same config and accepted parts` });
+  };
+  const provenance = isObject(version.provenance) ? version.provenance : {};
+  const config = isObject(provenance.config) ? provenance.config : {};
+  if (typeof config.sha256 === 'string' && isObject(record.config) && typeof record.config.sha256 === 'string' && config.sha256 !== record.config.sha256) {
+    mismatch('REVIEW_PACKAGE_CONFIG_MISMATCH', 'config', config.sha256, record.config.sha256);
+  }
+  const approval = latestPartsApproval(ctx.project, Number.isFinite(at) ? at : Infinity);
+  if (!approval) return;
+  const approvalPath = `signoffs[${asArray(ctx.project.signoffs).indexOf(approval)}]`;
+  const finding = recordedPartsFinding(ctx.dir, ctx.project, approval, approvalPath);
+  if (finding) {
+    if (finding.code === 'PARTS_VERDICT_FILE_LEGACY') {
+      if (!ctx.warnings.some(existing => existing.code === finding.code && existing.path === finding.path)) ctx.warnings.push(finding);
+    } else findings.push({ code: 'REVIEW_PACKAGE_PARTS_UNREAD', path: `${path}.files[out/parts.json]`,
+      message: `${path}.files[out/parts.json]: accepted parts receipt is unavailable (${finding.code}); restore its recorded API response and selected draft before packaging this version` });
+    return;
+  }
+  recordedPartsVerdict(ctx.dir, ctx.project, approval.draft_id, approval.evidence, { requireAvailable: false });
+  const draft = asArray(ctx.project.drafts).find(draft => isObject(draft) && draft.id === approval.draft_id) as JsonObject;
+  const parts = draft.parts as JsonObject;
+  const files = asArray(parts.files).filter(isObject);
+  const manifest = files.find(file => file.path === `${parts.path}/parts.json`);
+  const packaged = asArray(record.files).find(f => isObject(f) && f.path === 'out/parts.json');
+  if (isObject(manifest) && typeof manifest.sha256 === 'string' && isObject(packaged) && typeof packaged.sha256 === 'string' && manifest.sha256 !== packaged.sha256) {
+    mismatch('REVIEW_PACKAGE_PARTS_MISMATCH', 'files[out/parts.json]', manifest.sha256, packaged.sha256);
+  }
+  if (!isObject(manifest) || typeof manifest.path !== 'string') return;
+  const legacy = !Number.isFinite(at) || at < Date.parse(PART_FILE_IDENTITY_SINCE);
+  if (draftFileUnavailable(ctx.dir, manifest.path, `derived/drafts/${String(draft.id)}`)) return;
+  const declaration = retainedJson(ctx.dir, manifest);
+  const painting = isObject(declaration.painting_in_rig) && typeof declaration.painting_in_rig.path === 'string'
+    ? posix.join(String(parts.path), declaration.painting_in_rig.path) : undefined;
+  for (const image of files) {
+    if (!isObject(image) || typeof image.path !== 'string' || typeof image.sha256 !== 'string' || image === manifest || image.path === painting) continue;
+    const name = posix.join('out', posix.relative(posix.dirname(manifest.path), image.path));
+    const file = asArray(record.files).find(f => isObject(f) && f.path === name);
+    const actual = isObject(file) && typeof file.sha256 === 'string' ? file.sha256 : 'missing';
+    if (actual === image.sha256) continue;
+    const field = `${path}.files[${name}]`;
+    (legacy ? ctx.warnings : ctx.refusals).push({
+      code: legacy ? 'REVIEW_PACKAGE_PART_FILE_LEGACY' : 'REVIEW_PACKAGE_PART_FILE_MISMATCH', path: field,
+      message: `${field}: package sha256 ${actual} differs from accepted part ${image.path} sha256 ${image.sha256}; preserve the package and record a new version from the reviewed part files`,
+    });
+  }
+}
+const word = (s: string): string => `'${s.replaceAll("'", "'\\''")}'`;
+const packagePath = (n: number): string => `derived/review/v${n}`;
+const openCommand = (n: number): string => `rig-review open ${word(`${packagePath(n)}/out`)}`;
+const required = ['parts.json', 'parts', 'rig', 'check/build'] as const;
+const inside = (root: string, file: string): boolean => {
+  const rel = relative(root, file);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
+
+interface FileHash { path: string; sha256: string }
+
+/** Named files are separate from producer outputs and required by their reader's date. */
+export function reviewConfigInputs(record: JsonObject, dir: string, n: number, missing?: (path: string) => void, unavailable?: ConfigInputsWarning, pkgDir = join(dir, packagePath(n))): JsonObject[] {
+  const path = join(pkgDir, 'config.json');
+  if (!existsSync(path)) return [];
+  const config = JSON.parse(readFileSync(path, 'utf8'));
+  const refs = configInputReferences(dir, config, unavailable);
+  const declared = new Set(refs.flatMap(ref => {
+    const name = relative(dirname(path), resolve(dirname(path), ref.value)).split(sep).join('/');
+    return [name, `${name}/${DIRECTORY_INPUT_RECEIPT}`];
+  }));
+  if (isObject(config) && typeof config.requirements === 'string') {
+    const reqFile = resolve(dirname(path), config.requirements);
+    if (existsSync(reqFile) && lstatSync(reqFile).isFile()) {
+      try {
+        const doc = JSON.parse(readFileSync(reqFile, 'utf8'));
+        const setup = isObject(doc) && isObject(doc.setup_painting) ? doc.setup_painting : {};
+        for (const key of ['figure_mask', 'backdrop'] as const) {
+          const entry = isObject(setup[key]) ? setup[key] : undefined;
+          if (typeof entry?.path === 'string' && entry.path.trim()) {
+            declared.add(relative(dirname(path), resolve(dirname(reqFile), entry.path)).split(sep).join('/'));
+          }
+        }
+      } catch { /* Handled by figure-mask checks. */ }
+    }
+  }
+  return refs.flatMap(ref => {
+    const name = relative(dirname(path), resolve(dirname(path), ref.value)).split(sep).join('/');
+    const file = asArray(record.files).find(f => isObject(f) && f.path === name);
+    if (isObject(file)) return [file];
+    const bound = `${name}/${DIRECTORY_INPUT_RECEIPT}`;
+    const receipt = asArray(record.files).find(f => isObject(f) && f.path === bound);
+    if (isObject(receipt)) {
+      if (asArray(record.files).some(f => isObject(f) && typeof f.path === 'string' && f.path.startsWith(`${name}/`) && f.path !== bound && !declared.has(f.path))) {
+        throw new Error(`config.${ref.at}: directory input ${name} must bind only ${bound}`);
+      }
+      const spec = plateReceiptSpec(dir);
+      const receiptFile = join(dirname(path), bound);
+      if (existsSync(receiptFile)) {
+        const declaredSpec = receiptSpec(readFileSync(receiptFile));
+        if (declaredSpec !== spec) throw new Error(`config.${ref.at}: ${bound} declares spec ${JSON.stringify(declaredSpec)}; a directory input binds a ${spec} receipt, such as a comfy plate --mode occluder output`);
+      }
+      return [receipt];
+    }
+    if (!missing) throw new Error(`config.${ref.at}: named input ${name} is missing from source package`);
+    missing(name);
+    return [{ path: name, sha256: null }];
+  });
+}
+export function reviewHandoffInputs(record: JsonObject, dir: string, n: number, named = reviewConfigInputs(record, dir, n)): JsonObject[] {
+  const base = asArray(record.files).filter((file): file is JsonObject => isObject(file) && typeof file.path === 'string'
+    && (file.path === 'config.json' || file.path.startsWith('out/') && !file.path.startsWith('out/check/')));
+  return [...base, ...named.filter(file => !base.some(f => f.path === file.path))];
+}
+
+function packageExists(path: string): boolean {
+  try { lstatSync(path); return true; } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+/** Check each existing ancestor before creating the next directory. */
+function makePackageParent(dir: string): void {
+  let parent = dir;
+  for (const name of ['derived', 'review']) {
+    parent = join(parent, name);
+    if (!packageExists(parent)) mkdirSync(parent);
+    if (!lstatSync(parent).isDirectory()) refuse('REVIEW_PACKAGE_PATH_INVALID', 'derived/review requires real directories without symlinks');
+  }
+}
+
+function validFiles(value: JsonObject['files']): boolean {
+  if (!Array.isArray(value) || value.length === 0) return false;
+  let previous = '';
+  for (const entry of value) {
+    if (!isObject(entry) || typeof entry.path !== 'string' || typeof entry.sha256 !== 'string'
+      || !/^[a-f0-9]{64}$/.test(entry.sha256) || entry.path <= previous
+      || isAbsolute(entry.path) || entry.path.split('/').some((part) => part === '..' || part === '.' || part === '')) return false;
+    previous = entry.path;
+  }
+  return value.some((entry) => isObject(entry) && entry.path === 'config.json');
+}
+
+function sourceFiles(out: string, imagePaths: readonly string[]): FileHash[] {
+  const files = required.flatMap((entry) => entry === 'parts.json'
+    ? [{ path: entry, sha256: hash(readFileSync(join(out, entry))) }]
+    : filesAt(join(out, entry)).map((file) => ({ ...file, path: `${entry}/${file.path}` })));
+  const seen = new Set(files.map(file => file.path));
+  for (const path of imagePaths) {
+    const copiedTree = required.some(entry => entry !== 'parts.json' && path.startsWith(`${entry}/`));
+    if (seen.has(path) || copiedTree) continue;
+    const absolute = resolve(out, path);
+    if (!inside(out, absolute) || path.split('/').some(segment => !segment || segment === '.' || segment === '..')
+      || realpathSync(absolute) !== absolute || !lstatSync(absolute).isFile()) refuse('REVIEW_PACKAGE_PATH_INVALID', `${path}: restore the retained regular image before packaging`);
+    files.push({ path, sha256: hash(readFileSync(absolute)) });
+    seen.add(path);
+  }
+  return files;
+}
+
+/** Reject symlinks throughout the copied tree, including otherwise-contained ones. */
+function filesAt(root: string, prefix = ''): FileHash[] {
+  const files: FileHash[] = [];
+  for (const name of readdirSync(join(root, prefix)).sort()) {
+    const path = prefix ? `${prefix}/${name}` : name;
+    const info = lstatSync(join(root, path));
+    if (info.isDirectory()) files.push(...filesAt(root, path));
+    else if (info.isFile()) files.push({ path, sha256: hash(readFileSync(join(root, path))) });
+    else refuse('REVIEW_PACKAGE_INPUT_INVALID', `${path}: expected a regular file or directory, without symlinks`);
+  }
+  return files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+
+function requireLayout(out: string): void {
+  for (const entry of required) {
+    const file = join(out, entry);
+    if (!existsSync(file)) refuse('REVIEW_PACKAGE_INPUT_MISSING', `${entry}: required in the declared build out directory`);
+    const stat = lstatSync(file);
+    if (entry === 'parts.json' ? !stat.isFile() : !stat.isDirectory()) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${entry}: wrong file kind`);
+  }
+  if (!lstatSync(join(out, 'check')).isDirectory()) refuse('REVIEW_PACKAGE_INPUT_INVALID', 'check: expected a real directory');
+  for (const file of ['rig/rig.json', 'rig/motion.json', 'rig/mesh_report.json']) {
+    if (!existsSync(join(out, file)) || !lstatSync(join(out, file)).isFile()) refuse('REVIEW_PACKAGE_INPUT_MISSING', `${file}: required producer rig file`);
+  }
+  const model = join(out, 'check/build/skeleton.model.json');
+  if (!existsSync(model) || !lstatSync(model).isFile()) refuse('REVIEW_PACKAGE_INPUT_MISSING', 'check/build/skeleton.model.json: required compiled model');
+}
+
+function regeneration(n: number, record: JsonObject | null): string {
+  return `rig-create review-package ${n} --config ${word(isObject(record?.config) && typeof record.config.path === 'string' ? record.config.path : '<config>')} --from ${word(typeof record?.from === 'string' ? record.from : '<build out dir>')}`;
+}
+
+/** Hash the complete package, so added files cannot silently change discovery. */
+export function checkReviewPackages(ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'>): void {
+  for (const version of asArray(ctx.project.versions)) {
+    if (!isObject(version) || version.kind !== 'rig') continue;
+    const dateFinding = rigVersionDateFinding(version);
+    if (dateFinding) ctx.refusals.push(dateFinding);
+    if (version.pre_interview === true) continue;
+    const path = `versions[v${String(version.n)}].review_package`;
+    const record = isObject(version.review_package) ? version.review_package : null;
+    if (!Number.isSafeInteger(version.n) || (version.n as number) < 1) continue;
+    const n = version.n as number;
+    const pkg = join(ctx.dir, packagePath(n));
+    if (version.review_package === undefined || version.review_package === null) {
+      ctx.warnings.push({ code: 'REVIEW_PACKAGE_MISSING', path, message: `${path}: no package recorded, so the figure mask has no verdict; write it with ${regeneration(n, null)}` });
+      continue;
+    }
+    if (record === null || !isObject(record.config) || typeof record.config.path !== 'string' || typeof record.config.sha256 !== 'string'
+      || !/^[a-f0-9]{64}$/.test(record.config.sha256) || record.config.path.trim() === '' || isAbsolute(record.config.path) || !inside(ctx.dir, resolve(ctx.dir, record.config.path))
+      || typeof record.from !== 'string' || record.from.trim() === '' || isAbsolute(record.from) || !inside(ctx.dir, resolve(ctx.dir, record.from)) || !validFiles(record.files)
+      || record.open !== openCommand(n)) {
+      ctx.refusals.push({ code: 'REVIEW_PACKAGE_MALFORMED', path, message: `${path}: expected config {path, sha256}, from, sorted files {path, sha256} and the package open command` });
+      continue;
+    }
+    checkBuildIdentity(ctx, version, record);
+    if (!packageExists(pkg)) {
+      ctx.warnings.push({ code: 'REVIEW_PACKAGE_MISSING', path, message: `${path}: package absent, so the figure mask has no verdict; regenerate with ${regeneration(n, record)}` });
+      continue;
+    }
+    try {
+      if (!inside(realpathSync(ctx.dir), realpathSync(pkg)) || lstatSync(pkg).isSymbolicLink()) throw new Error('package leaves its project or is a symlink');
+      requireLayout(join(pkg, 'out'));
+      const actual = filesAt(pkg);
+      if (!isDeepStrictEqual(actual, record.files) || hash(readFileSync(join(pkg, 'config.json'))) !== record.config.sha256) throw new Error('package files differ from recorded hashes');
+    } catch (error) {
+      ctx.refusals.push({ code: 'REVIEW_PACKAGE_CHANGED', path, message: `${path}: ${error instanceof Error ? error.message : String(error)}` });
+      continue;
+    }
+    // The project-level loader diagnostic already owns this unavailable dependency.
+    if (ctx.refusals.some(f => f.code === 'PARTS_SECTIONS_UNREADABLE' || f.code === 'PARTS_NOT_INSTALLED')) continue;
+    try {
+      const missing = (name: string): void => {
+        const finding = { code: 'REVIEW_PACKAGE_INPUT_MISSING', path, message: `${path}: config-named input ${name} is missing from the frozen package inventory; preserve the package and record the complete inputs on the next build` };
+        (configInputsLegacy(version.at) ? ctx.warnings : ctx.refusals).push(finding);
+      };
+      const unavailable = (error: Error): void => {
+        const finding = { code: 'REVIEW_PACKAGE_INPUT_INVALID', path, message: `${path}: ${error.message}` };
+        (configInputsLegacy(version.at) ? ctx.warnings : ctx.refusals).push(finding);
+      };
+      reviewConfigInputs(record, ctx.dir, n, missing, unavailable);
+    } catch (error) { ctx.refusals.push({ code: 'REVIEW_PACKAGE_INPUT_INVALID', path, message: `${path}: ${error instanceof Error ? error.message : String(error)}; restore the frozen package config` }); }
+  }
+}
+
+export const REVIEW_PACKAGE_HELP = `review-package <n> [<project dir>] --config <path> --from <build out dir> [--json]
+  Copy frozen producer inputs into derived/review/v<n>; record hashes and the open command.
+  Source paths are relative to the project and must stay inside it. Run the open command there.`;
+
+export function reviewPackageCommand(args: string[]): { stdout: string; exit: number } {
+  return packageCommand(args);
+}
+
+/** Prepare the normal package against a candidate, without publishing project.json. */
+export function prepareRigReviewPackage(args: string[], project: JsonObject, imagePaths?: readonly string[]): void {
+  packageCommand(args, project, imagePaths);
+}
+
+function packageCommand(args: string[], candidate?: JsonObject, imagePaths?: readonly string[]): { stdout: string; exit: number } {
+  const positional: string[] = [];
+  const options: Record<string, string> = {};
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === '--json') json = true;
+    else if (arg === '--config' || arg === '--from') {
+      const value = args[++i];
+      if (!value || value.startsWith('--') || options[arg] !== undefined) refuse('REVIEW_PACKAGE_USAGE', `${arg} needs one value`, USAGE_EXIT);
+      options[arg] = value;
+    } else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `review-package does not take ${arg}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  const n = Number(positional[0]?.replace(/^v/, ''));
+  if (!Number.isSafeInteger(n) || n < 1 || positional.length > 2 || !options['--config'] || !options['--from']) refuse('REVIEW_PACKAGE_USAGE', REVIEW_PACKAGE_HELP, USAGE_EXIT);
+  const dir = realpathSync(resolve(positional[1] ?? process.cwd()));
+  const projectFile = join(dir, 'project.json');
+  if (!existsSync(projectFile)) refuse('PROJECT_JSON_MISSING', 'project.json is absent');
+  const lock = `${projectFile}.review-package.lock`;
+  let descriptor: number;
+  try { descriptor = openSync(lock, 'wx'); } catch { refuse('REVIEW_PACKAGE_BUSY', 'another package writer holds the project lock'); }
+  try {
+    const original = readFileSync(projectFile, 'utf8');
+    const read = readJsonObject(projectFile);
+    if (!read.ok) refuse('PROJECT_JSON_INVALID', read.error);
+    const project = candidate ?? read.value;
+    if (project.schema !== 'rig-create/project@0') refuse('SCHEMA_UNKNOWN', 'review-package reads rig-create/project@0');
+    const version = asArray(project.versions).find((v) => isObject(v) && v.n === n);
+    if (!isObject(version)) refuse('REVIEW_PACKAGE_VERSION_UNKNOWN', `no version ${n}`);
+    assertRigVersionDate(version);
+    const draftProblem = draftVersionFindings(dir, { ...project, versions: [version] })[0];
+    if (draftProblem !== undefined) refuse(draftProblem.code, draftProblem.message);
+    if (version.kind !== 'rig' || version.pre_interview === true) refuse('REVIEW_PACKAGE_VERSION_INVALID', 'review packages are for create-built rig versions');
+    const source = (value: string): string => {
+      const file = resolve(dir, value);
+      if (isAbsolute(value) || !inside(dir, file)) refuse('REVIEW_PACKAGE_PATH_INVALID', `${value}: expected a project-relative source`);
+      if (!existsSync(file)) refuse('REVIEW_PACKAGE_INPUT_MISSING', `${value}: source absent`);
+      const canonical = realpathSync(file);
+      if (!inside(dir, canonical)) refuse('REVIEW_PACKAGE_PATH_INVALID', `${value}: source resolves outside the project`);
+      return canonical;
+    };
+    const declaredDraft = draftVersionFindings(dir, { ...project, versions: [{ kind: 'rig', source_dir: options['--from'], config: { path: options['--config'] } }] })[0];
+    if (declaredDraft !== undefined) refuse(declaredDraft.code, declaredDraft.message);
+    const config = source(options['--config']);
+    const from = source(options['--from']);
+    if (!lstatSync(config).isFile() || !lstatSync(from).isDirectory()) refuse('REVIEW_PACKAGE_INPUT_INVALID', 'config must be a file and --from a directory');
+    requireLayout(from);
+    const configBytes = readFileSync(config);
+    try { if (!isObject(JSON.parse(configBytes.toString()))) throw new Error(); } catch { refuse('REVIEW_PACKAGE_INPUT_INVALID', 'config must be a JSON object'); }
+    let named: { path: string; source: string; bytes: Buffer }[];
+    const directories = new Set<string>();
+    try {
+      named = configInputReferences(dir, JSON.parse(configBytes.toString())).map(ref => {
+        const path = relative(dirname(config), resolve(dirname(config), ref.value)).split(sep).join('/');
+        if (isAbsolute(ref.value) || !path || path.split('/').some(part => part === '..' || part === '.' || part === '')) refuse('REVIEW_PACKAGE_PATH_INVALID', `config.${ref.at}: ${ref.value} cannot be retained inside the package; use a config-relative input inside its directory`);
+        const file = source(relative(dir, resolve(dirname(config), ref.value)));
+        if (lstatSync(file).isDirectory()) {
+          const receipt = join(file, DIRECTORY_INPUT_RECEIPT);
+          const bound = `${path}/${DIRECTORY_INPUT_RECEIPT}`;
+          if (!existsSync(receipt) || !lstatSync(receipt).isFile()) {
+            refuse('REVIEW_PACKAGE_INPUT_INVALID', `config.${ref.at}: named input directory ${path} holds no regular-file ${DIRECTORY_INPUT_RECEIPT}; a directory input binds its producer's receipt, such as a comfy plate --mode occluder output`);
+          }
+          const bytes = readFileSync(receipt);
+          const spec = plateReceiptSpec(dir);
+          const declared = receiptSpec(bytes);
+          if (declared !== spec) {
+            refuse('REVIEW_PACKAGE_INPUT_INVALID', `config.${ref.at}: ${bound} declares spec ${JSON.stringify(declared)}; a directory input binds a ${spec} receipt, such as a comfy plate --mode occluder output`);
+          }
+          directories.add(path);
+          return { path: bound, source: receipt, bytes };
+        }
+        if (!lstatSync(file).isFile()) refuse('REVIEW_PACKAGE_INPUT_INVALID', `config.${ref.at}: ${path} must be a regular file`);
+        return { path, source: file, bytes: readFileSync(file) };
+      });
+    } catch (error) { if (error instanceof Refusal) throw error; refuse('REVIEW_PACKAGE_INPUT_INVALID', `versions[v${n}].review_package.config: ${error instanceof Error ? error.message : String(error)}`); }
+    // Registered builds retain adapter-relocated runtime inputs as well as the
+    // loader's three config-file declarations. Preserve them on regeneration.
+    if (isObject(version.registration) && version.registration.kind === 'frozen-rig/1') {
+      const configDir = relative(dir, dirname(config)).split(sep).join('/');
+      const prefix = `${configDir}/`;
+      const runFiles = new Set(asArray(version.registration.runs).flatMap(r => isObject(r) && isObject(r.source) && typeof r.source.path === 'string' ? [r.source.path] : []));
+      const metadataNames = new Set(['at-source.json', 'compile-report.json', 'config-source.json', 'requirements-source.json', 'config.json', 'package-lock.json', 'path-adapter.json', 'citations.json']);
+      for (const binding of asArray(version.registration.files)) {
+        if (!isObject(binding) || typeof binding.path !== 'string' || !binding.path.startsWith(prefix)) continue;
+        const rel = binding.path.slice(prefix.length);
+        if (metadataNames.has(rel) || runFiles.has(binding.path)) continue;
+        if ([...directories].some(d => rel.startsWith(`${d}/`)) && !named.some(input => input.path === rel)) continue;
+        const file = source(binding.path);
+        const bytes = readFileSync(file);
+        if (hash(bytes) !== binding.sha256) refuse('REVIEW_PACKAGE_SOURCE_CHANGED', `${binding.path}: registered runtime input changed`);
+        const path = relative(dirname(config), file).split(sep).join('/');
+        const existing = named.find(input => input.path === path);
+        if (existing && !existing.bytes.equals(bytes)) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${path}: runtime input collides with a named input`);
+        if (!existing) named.push({ path, source: file, bytes });
+      }
+    }
+    const configObject = JSON.parse(configBytes.toString()) as JsonObject;
+    if (typeof configObject.requirements === 'string') {
+      const requirementsPath = relative(dirname(config), resolve(dirname(config), configObject.requirements)).split(sep).join('/');
+      const requirements = named.find(input => input.path === requirementsPath);
+      if (requirements) {
+        let document: Json;
+        try { document = JSON.parse(requirements.bytes.toString()); }
+        catch { refuse('REVIEW_PACKAGE_INPUT_INVALID', `${requirements.path}: restore readable requirements JSON`); }
+        const setup = isObject(document) && isObject(document.setup_painting) ? document.setup_painting : {};
+        if (setup.figure_mask !== undefined) {
+          const mask = setup.figure_mask;
+          if (!isObject(mask) || typeof mask.path !== 'string' || !mask.path.trim()
+            || typeof mask.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(mask.sha256)) {
+            refuse('FIGURE_MASK_MISSING', `${requirements.path}: declare setup_painting.figure_mask {path, sha256} before packaging`);
+          }
+          const maskFile = resolve(dirname(config), dirname(requirements.path), mask.path);
+          const maskPath = relative(dirname(config), maskFile).split(sep).join('/');
+          if (isAbsolute(mask.path) || !maskPath || maskPath.split('/').some(part => part === '..' || part === '.' || part === '')) {
+            refuse('REVIEW_PACKAGE_PATH_INVALID', `${requirements.path}: figure mask ${mask.path} must stay inside the config directory`);
+          }
+          let current = dirname(config);
+          for (const part of maskPath.split('/')) {
+            current = join(current, part);
+            if (existsSync(current) && lstatSync(current).isSymbolicLink()) refuse('REVIEW_PACKAGE_PATH_INVALID', `${maskPath}: retain a figure mask without symlinks`);
+          }
+          let regularFile = false;
+          try { regularFile = lstatSync(maskFile).isFile(); } catch { /* Missing paths are refused below. */ }
+          if (!regularFile) refuse('FIGURE_MASK_CHANGED', `${maskPath}: restore the declared mask as a readable PNG file before packaging`);
+          let bytes: Buffer;
+          try { bytes = readFileSync(maskFile); }
+          catch { refuse('FIGURE_MASK_CHANGED', `${maskPath}: cannot read the declared mask; restore its PNG before packaging`); }
+          if (hash(bytes) !== mask.sha256) refuse('FIGURE_MASK_CHANGED', `${maskPath}: bytes differ from the declared sha256; restore the mask or record its corrected declaration before packaging`);
+          if (maskPath === 'config.json' && !bytes.equals(configBytes)) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${maskPath}: figure mask collides with the packaged config`);
+          const existing = named.find(input => input.path === maskPath);
+          if (existing && !existing.bytes.equals(bytes)) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${maskPath}: figure mask collides with a named input`);
+          if (!existing) named.push({ path: maskPath, source: maskFile, bytes });
+        }
+        const legacyUnadaptedReg = isObject(version.registration) && version.registration.kind === 'frozen-rig/1' && version.registration.requirements_source === undefined;
+        if (setup.backdrop !== undefined && !legacyUnadaptedReg) {
+          const backdrop = setup.backdrop;
+          if (!isObject(backdrop) || typeof backdrop.path !== 'string' || !backdrop.path.trim()
+            || typeof backdrop.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(backdrop.sha256)) {
+            refuse('REVIEW_PACKAGE_INPUT_INVALID', `${requirements.path}: declare setup_painting.backdrop {path, sha256} before packaging`);
+          }
+          const backdropFile = resolve(dirname(config), dirname(requirements.path), backdrop.path);
+          const backdropPath = relative(dirname(config), backdropFile).split(sep).join('/');
+          if (isAbsolute(backdrop.path) || !backdropPath || backdropPath.split('/').some(part => part === '..' || part === '.' || part === '')) {
+            refuse('REVIEW_PACKAGE_PATH_INVALID', `${requirements.path}: backdrop ${backdrop.path} must stay inside the config directory`);
+          }
+          let current = dirname(config);
+          for (const part of backdropPath.split('/')) {
+            current = join(current, part);
+            if (existsSync(current) && lstatSync(current).isSymbolicLink()) refuse('REVIEW_PACKAGE_PATH_INVALID', `${backdropPath}: retain a backdrop without symlinks`);
+          }
+          let regularFile = false;
+          try { regularFile = lstatSync(backdropFile).isFile(); } catch { /* Missing paths are refused below. */ }
+          if (!regularFile) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${backdropPath}: restore the declared backdrop as a readable PNG file before packaging`);
+          let bytes: Buffer;
+          try { bytes = readFileSync(backdropFile); }
+          catch { refuse('REVIEW_PACKAGE_INPUT_INVALID', `${backdropPath}: cannot read the declared backdrop; restore its PNG before packaging`); }
+          if (hash(bytes) !== backdrop.sha256) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${backdropPath}: bytes differ from the declared sha256; restore the backdrop or record its corrected declaration before packaging`);
+          if (backdropPath === 'config.json' && !bytes.equals(configBytes)) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${backdropPath}: backdrop collides with the packaged config`);
+          const existing = named.find(input => input.path === backdropPath);
+          if (existing && !existing.bytes.equals(bytes)) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${backdropPath}: backdrop collides with a named input`);
+          if (!existing) named.push({ path: backdropPath, source: backdropFile, bytes });
+        }
+      }
+    }
+    // A compiled model already cited by an authored take cannot be rebound by packaging.
+    for (const post of directionObjects(project.versions)) {
+      if (post.kind !== 'post' || post.rig_version !== n || !isObject(post.provenance) || post.provenance.direction === undefined) continue;
+      try {
+        const document = readDirection(dir, project, post.n, false);
+        const expected = ((document.rig as JsonObject).model as JsonObject).sha256;
+        if (hash(readFileSync(join(from, 'check/build/skeleton.model.json'))) !== expected) refuse('DIRECTION_RIG_STALE', `versions[v${n}].review_package: this model is bound by a direction document; preserve it and author a new rig version`);
+      } catch (error) { if (error instanceof DirectionError) refuse(error.code, error.message); throw error; }
+    }
+    // Regeneration uses the existing declaration, preserving historical packages
+    // that omitted sibling images. New registration supplies official rows.
+    const recordedFiles = isObject(version.review_package) ? asArray(version.review_package.files) : [];
+    const namedPaths = new Set(named.map(input => input.path));
+    const retainedImages = imagePaths ?? recordedFiles.filter(isObject).flatMap(file =>
+      typeof file.path === 'string' && file.path.startsWith('out/') && !namedPaths.has(file.path) ? [file.path.slice(4)] : []);
+    const inputs = sourceFiles(from, retainedImages);
+    const pkg = join(dir, packagePath(n));
+    makePackageParent(dir);
+    const scratch = mkdtempSync(join(dirname(pkg), `.v${n}-`));
+    let published = false;
+    try {
+      writeFileSync(join(scratch, 'config.json'), configBytes);
+      for (const input of named) {
+        const dest = join(scratch, input.path);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, input.bytes);
+      }
+      for (const entry of required) {
+        if (entry !== 'parts.json') mkdirSync(join(scratch, 'out', entry), { recursive: true });
+      }
+      for (const file of inputs) {
+        const bytes = readFileSync(join(from, file.path));
+        if (hash(bytes) !== file.sha256) refuse('REVIEW_PACKAGE_SOURCE_CHANGED', `${file.path}: source changed during copy`);
+        const dest = join(scratch, 'out', file.path);
+        if (existsSync(dest) && !readFileSync(dest).equals(bytes)) refuse('REVIEW_PACKAGE_INPUT_INVALID', `${file.path}: config input collides with a producer output`);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, bytes);
+      }
+      if (!isDeepStrictEqual(sourceFiles(from, retainedImages), inputs) || hash(readFileSync(config)) !== hash(configBytes)) {
+        refuse('REVIEW_PACKAGE_SOURCE_CHANGED', 'producer inputs changed during copy');
+      }
+      for (const input of named) if (!readFileSync(input.source).equals(input.bytes)) refuse('REVIEW_PACKAGE_SOURCE_CHANGED', `${input.path}: config input changed during copy`);
+      const files = filesAt(scratch);
+      const record: JsonObject = { config: { path: relative(dir, config), sha256: hash(configBytes) }, from: relative(dir, from), files: files.map((f) => ({ ...f })), open: openCommand(n) };
+      const identity = { dir, project, refusals: [] as Ctx['refusals'], warnings: [] as Ctx['warnings'] };
+      checkBuildIdentity(identity, version, record);
+      if (identity.refusals[0]) refuse(identity.refusals[0].code, identity.refusals[0].message);
+      try { reviewConfigInputs(record, dir, n, undefined, undefined, scratch); }
+      catch (error) { refuse('REVIEW_PACKAGE_INPUT_INVALID', `versions[v${n}].review_package: ${error instanceof Error ? error.message : String(error)}`); }
+      if (packageExists(pkg)) {
+        if (lstatSync(pkg).isSymbolicLink() || realpathSync(pkg) !== pkg) refuse('REVIEW_PACKAGE_PATH_INVALID', 'existing package must have no symlink parents');
+        if (!isDeepStrictEqual(filesAt(pkg), files)) refuse('REVIEW_PACKAGE_EXISTS', 'existing package differs; preserve it and inspect the recorded version before regenerating');
+      } else {
+        renameSync(scratch, pkg);
+        published = true;
+      }
+      if (readFileSync(projectFile, 'utf8') !== original) refuse('REVIEW_PACKAGE_RECORD_CHANGED', 'project.json changed during copying; retry from the current record');
+      version.review_package = record;
+      if (candidate !== undefined) {
+        published = false;
+        return { stdout: JSON.stringify(record), exit: 0 };
+      }
+      const pending = join(scratch, 'project.json');
+      mkdirSync(scratch, { recursive: true });
+      writeFileSync(pending, `${JSON.stringify(project, null, 2)}\n`);
+      renameSync(pending, projectFile);
+      published = false;
+      return { stdout: json ? JSON.stringify(record, null, 2) : `review-package: v${n} copied; ${openCommand(n)}`, exit: 0 };
+    } finally {
+      if (published) rmSync(pkg, { recursive: true });
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  } finally {
+    closeSync(descriptor);
+    rmSync(lock);
+  }
+}