@rig-c/create 1.0.2 → 1.1.0

package/src/rig-version.ts

@@ -8,7 +8,7 @@ import { partsFileReferences } from '@rig-c/parts/src/parts.ts';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, posix, relative, resolve, sep, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { asArray, checkProject, isObject, type Finding } from './check.ts';
+import { asArray, checkProject, collectItems, isObject, type Finding } from './check.ts';
 import { literalFile } from './choices.ts';
 import { configInputReferences } from './config-inputs.ts';
 import { parseFeedbackAnswers, readProject } from './feedback.ts';
@@ -18,7 +18,9 @@ import { collectReopens, reopenTime } from './reopen.ts';
 import { prepareRigReviewPackage } from './review-package.ts';
 import { rigVersionDateFinding } from './rig-version-date.ts';
 import { checkRegisteredRuns, RUN_RECORD_SINCE, RunRecordError, validateRunRecord, type RunSpec } from './run-record.ts';
-import { approvedStructureDelta, structurePathIsIgnored } from './structure.ts';
+import { approvedStructureDelta, latestPartsApproval, structurePathIsIgnored } from './structure.ts';
+import { stageOfStep } from './stages.ts';
+import { HEAD_TURN_SINCE } from './waypoints.ts';
 import type { Json, JsonObject } from './templates.ts';
 
 const sha = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
@@ -38,6 +40,9 @@ const RESERVED_REGISTRATION_NAMES = new Set([
   'package-lock.json',
   'path-adapter.json',
   'citations.json',
+  'depth-manifest.json',
+  'depth-report.json',
+  'depth-source-parts.json',
 ]);
 function isValidAdaptedTarget(target: string): boolean {
   return literal(target)
@@ -389,13 +394,137 @@ function collectRequirementsAssetRefs(requirements: JsonObject, portableRequirem
   return refs;
 }
 
-/** Only explicitly registered versions opt in. Older version contracts are unchanged. */
-export function rigRegistrationFindings(dir: string, project: JsonObject, warnings: Finding[] = []): Finding[] {
+/** A declared depth/turn config is the existing registration's depth input branch. */
+function usesDepth(config: JsonObject): boolean {
+  const turn = isObject(config.turn) ? config.turn : {};
+  const body = isObject(turn.body) ? turn.body : {};
+  return isObject(config.depth) || [turn.roles, body.roles].some(roles => isObject(roles) && Object.keys(roles).length > 0);
+}
+
+/** Reads only producer declarations and bytes, never producer measurements. */
+function depthBindingFindings(dir: string, version: JsonObject, config: JsonObject, record: JsonObject | undefined, warnings: Finding[]): Finding[] {
+  if (!usesDepth(config) && record?.depth === undefined) return [];
+  const path = `versions[v${String(version.n)}].registration.depth`;
   const findings: Finding[] = [];
+  const missing = (why: string): void => {
+    const finding = { code: 'RIG_DEPTH_BINDING_MISSING', path, message: `${path}: ${why}; retain rig's depth_sheets.json and, for per-part maps, --depth-manifest and parts' depth-report.json when registering a new rig version` };
+    (typeof version.at === 'string' && Date.parse(version.at) < Date.parse(HEAD_TURN_SINCE) ? warnings : findings).push(finding);
+  };
+  const depth = record?.depth;
+  if (!isObject(depth)) { missing('no producer depth binding'); return findings; }
+  if (!isObject(depth.sheets) || depth.route === 'per-part' && (!isObject(depth.manifest) || !isObject(depth.report))) {
+    missing('incomplete producer depth binding'); return findings;
+  }
+  try {
+    if (depth.route !== 'per-part' && depth.route !== 'per-layer') throw Error('expected per-part or per-layer route');
+    if (depth.route === 'per-layer' && (depth.manifest !== undefined || depth.report !== undefined)) throw Error('per-part reports require the per-part route');
+    const read = (binding: Json | undefined, spec: string, output = false): JsonObject => {
+      const inventory = asArray(output ? version.outputs : record?.files).filter(isObject);
+      if (!isObject(binding) || !inventory.some(row => row.path === binding.path && row.sha256 === binding.sha256)) throw Error('depth file is absent from the retained inventory');
+      const doc: Json = JSON.parse(bytesAt(dir, binding, output).toString('utf8'));
+      if (!isObject(doc) || doc.spec !== spec || !Array.isArray(doc.parts)) throw Error(`expected ${spec} with parts[]`);
+      return doc;
+    };
+    const digest = (value: Json | undefined, field: string): string => {
+      if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) throw Error(`${field}: expected producer SHA-256`);
+      return value;
+    };
+    const namedRows = (value: Json | undefined, label: string): JsonObject[] => {
+      if (!Array.isArray(value) || value.length === 0 || value.some(row => !isObject(row) || typeof row.part !== 'string' || !row.part)) throw Error(`${label}: expected nonempty named parts[]`);
+      const rows = value as JsonObject[];
+      if (new Set(rows.map(row => row.part)).size !== rows.length) throw Error(`${label}: duplicate part`);
+      return rows;
+    };
+    const outputRoot = `outputs/v${String(version.n)}/out`;
+    const outputs = asArray(version.outputs).filter(isObject);
+    const outputBytes = (path: string): Buffer => {
+      const binding = outputs.find(row => row.path === path);
+      if (!binding) throw Error(`${path}: absent from retained outputs`);
+      return bytesAt(dir, binding, true);
+    };
+    const parts: Json = JSON.parse(outputBytes(`${outputRoot}/parts.json`).toString('utf8'));
+    if (!isObject(parts) || !Array.isArray(parts.parts)) throw Error('retained assembled parts.json has no parts[]');
+    const mappedParts = parts.parts.filter(isObject);
+    const sourceList = (raw: Json | undefined, label: string): JsonObject[] => {
+      if (!Array.isArray(raw) || raw.length === 0 || raw.some(row => !isObject(row))) throw Error(`${label}: expected depth sources[]`);
+      const rows = raw as JsonObject[];
+      for (const row of rows) {
+        digest(row.sha256, `${label}.sha256`);
+        if (typeof row.from !== 'string' || !row.from || typeof row.image !== 'string' || !literal(row.image)
+          || !Array.isArray(row.crop) || row.crop.length !== 4 || row.crop.some(v => typeof v !== 'number' || !Number.isFinite(v))) throw Error(`${label}: invalid declared depth source`);
+      }
+      return rows;
+    };
+    const sheets = namedRows(read(depth.sheets, 'rig-parts-depth-sheets/1', true).parts, 'rig sheets');
+    for (const row of sheets) {
+      const ref = row.depth;
+      if (!isObject(ref) || typeof ref.image !== 'string' || !literal(ref.image) || ref.image.includes('/')
+        || !['white', 'black'].includes(String(ref.near)) || typeof ref.zScale !== 'number' || !(ref.zScale > 0) || !Number.isFinite(ref.zScale)
+        || !Array.isArray(row.size) || row.size.length !== 2 || row.size.some(v => typeof v !== 'number' || !Number.isSafeInteger(v) || v < 1)) throw Error('invalid consumed sheet metadata');
+      const sources = sourceList(ref.sources, 'rig sheet sources');
+      // Rig may pad/crop a sheet. Its declared source provenance must still match
+      // an assembled part; comparing the padded sheet hash to apply's would be wrong.
+      if (!mappedParts.some(part => isObject(part.depth) && part.depth.near === ref.near && part.depth.zScale === ref.zScale
+        && isDeepStrictEqual(sourceList(part.depth.sources, 'assembled sheet sources'), sources))) throw Error('rig sheet sources do not bind the retained assembled parts');
+      outputBytes(`${outputRoot}/rig/images/${ref.image}`);
+    }
+    if (depth.route === 'per-part') {
+      const manifest = read(depth.manifest, 'rig-parts-depth-inputs/1');
+      const report = read(depth.report, 'rig-parts-depth-report/1');
+      for (const field of ['partsSha256', 'recipeSha256'] as const) {
+        if (digest(report[field], `report.${field}`) !== digest(manifest[field], `manifest.${field}`)) throw Error(`producer ${field} declarations disagree`);
+      }
+      digest(report.rigConfigSha256, 'report.rigConfigSha256');
+      if (digest(report.manifestSha256, 'report.manifestSha256') !== (depth.manifest as JsonObject).sha256) throw Error('producer report does not bind the retained prepare manifest');
+      if (depth.source_parts !== undefined) {
+        const binding = depth.source_parts;
+        if (!isObject(binding) || !asArray(record?.files).filter(isObject).some(f => f.path === binding.path && f.sha256 === binding.sha256)
+          || digest(binding.sha256, 'source parts') !== manifest.partsSha256) throw Error('prepare manifest does not bind the retained source parts');
+        bytesAt(dir, binding);
+      }
+      const prepared = namedRows(manifest.parts, 'prepared parts');
+      const applied = namedRows(report.parts, 'applied parts');
+      if (!isDeepStrictEqual(prepared.map(row => row.part).sort(), applied.map(row => row.part).sort())) throw Error('prepare/apply part sets disagree');
+      for (const row of applied) {
+        const input = prepared.find(p => p.part === row.part)!;
+        const part = mappedParts.find(p => p.name === row.part);
+        if (!part || !isObject(part.depth) || typeof part.name !== 'string' || !literal(part.name) || part.name.includes('/')
+          || typeof part.depth.image !== 'string' || !literal(part.depth.image) || part.depth.image.includes('/')) throw Error('report part has no retained assembled depth declaration');
+        const partDepth = part.depth;
+        for (const field of ['sourceSha256', 'inputSha256'] as const) {
+          if (digest(row[field], `report.${field}`) !== digest(input[field], `manifest.${field}`)) throw Error(`producer ${field} declarations disagree`);
+        }
+        if (digest(row.sourceSha256, 'report.sourceSha256') !== sha(outputBytes(`${outputRoot}/parts/${part.name}.png`))) throw Error('applied part art differs from the retained assembled part');
+        if (digest(row.sheetSha256, 'report.sheetSha256') !== sha(outputBytes(`${outputRoot}/parts/${partDepth.image}`))) throw Error('applied sheet differs from the retained assembled sheet');
+        const map = digest(row.mapSha256, 'report.mapSha256');
+        const sources = sourceList(partDepth.sources, 'applied sheet sources');
+        if (!sources.some(source => source.sha256 === map && source.from === part.from)) throw Error('applied map hash is absent from the assembled depth sources');
+        if (row.near !== partDepth.near || row.zScale !== partDepth.zScale) throw Error('applied depth units disagree with the assembled declaration');
+        if (!sheets.some(sheet => isObject(sheet.depth) && isDeepStrictEqual(sheet.depth.sources, sources)
+          && sheet.depth.near === partDepth.near && sheet.depth.zScale === partDepth.zScale)) throw Error('rig consumed no sheet from the reported applied part');
+      }
+    }
+  } catch (error) {
+    findings.push({ code: 'RIG_DEPTH_BINDING_INVALID', path, message: `${path}: ${String(error)}; restore the exact producer files or register a new rig version` });
+  }
+  return findings;
+}
+
+/** Only explicitly registered versions opt in. Older version contracts are unchanged. */
+export function rigRegistrationFindings(dir: string, project: JsonObject, warnings: Finding[] = [], collection: JsonObject | null = null): Finding[] {
+  const findings: Finding[] = depthPlanFindings(project, warnings, collection);
   const allVersions = asArray(project.versions).filter(isObject);
   const registeredNumbers = new Set(allVersions.map(v => v.n).filter((n): n is number => typeof n === 'number' && Number.isSafeInteger(n)));
   for (const [index, version] of allVersions.entries()) {
-    if (version.registration === undefined) continue;
+    if (version.registration === undefined) {
+      if (version.kind === 'rig' && version.pre_interview !== true && isObject(version.provenance)) {
+        try {
+          const config: Json = JSON.parse(bytesAt(dir, version.provenance.config).toString('utf8'));
+          if (isObject(config)) findings.push(...depthBindingFindings(dir, version, config, undefined, warnings));
+        } catch { /* Existing provenance checks own unreadable config evidence. */ }
+      }
+      continue;
+    }
     const path = `versions[v${String(version.n)}]`;
     const add = (code: string, field: string, why: string): void => { findings.push({ code, path: `${path}.${field}`, message: `${path}.${field}: ${why}; restore the retained registration inputs or register a new rig version` }); };
     const record = version.registration;
@@ -457,6 +586,7 @@ export function rigRegistrationFindings(dir: string, project: JsonObject, warnin
       const configSourceRaw = JSON.parse(bytesAt(dir, record.config_source).toString()) as Json;
       const portable = JSON.parse(bytesAt(dir, config).toString()) as Json;
       if (!isObject(configSourceRaw) || !isObject(portable)) throw Error('config-source and portable config must be JSON objects');
+      findings.push(...depthBindingFindings(dir, version, configSourceRaw, record, warnings));
       const checkPortable = (value: Json, document: string, requirementsDocument = false, location: string[] = []): void => {
         if (typeof value === 'string' && absolute(value)) {
           const field = `${document}#/${location.map(escapePointerToken).join('/')}`;
@@ -635,7 +765,7 @@ export function rigRegistrationFindings(dir: string, project: JsonObject, warnin
 
 export const RIG_VERSION_HELP = `rig-version <n> [<dir>] --parts <dir> --rig <dir> --build <dir> --idle <render dir>
   --config <file> --path-adapter <file> --compile-report <file> --toolchain-lock <package-lock.json>
-  --at-source <dated JSON file> --at-pointer </pointer> --by <registrant> [--run-record <run.json>]... [--citations <sections JSON>] [--json]
+  --at-source <dated JSON file> --at-pointer </pointer> --by <registrant> [--run-record <run.json>]... [--citations <sections JSON>] [--depth-manifest <prepare manifest>] [--json]
   Copy and hash frozen producer outputs. Retain an explicitly declared npm lock, producer run records and UTC not-after date.
   Idle requires rigc render's frames.json. No build, acceptance or stage advance runs.
   Repeat --answers <version>:<verdict> to answer earlier human bounced feedback.
@@ -648,7 +778,7 @@ export function rigVersionCommand(args: string[], now: number): { stdout: string
   const options: Record<string, string> = {};
   const runRecords: string[] = [];
   const answerValues: string[] = [];
-  const flags = ['--parts', '--rig', '--build', '--idle', '--config', '--path-adapter', '--compile-report', '--toolchain-lock', '--at-source', '--at-pointer', '--by', '--citations'];
+  const flags = ['--parts', '--rig', '--build', '--idle', '--config', '--path-adapter', '--compile-report', '--toolchain-lock', '--at-source', '--at-pointer', '--by', '--citations', '--depth-manifest'];
   let json = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
@@ -669,7 +799,7 @@ export function rigVersionCommand(args: string[], now: number): { stdout: string
     else positional.push(arg);
   }
   const n = Number(positional[0]?.replace(/^v/, ''));
-  if (!Number.isSafeInteger(n) || n < 1 || positional.length > 2 || flags.filter(f => f !== '--citations').some(f => !options[f])) refuse('RIG_REGISTRATION_USAGE', RIG_VERSION_HELP, USAGE_EXIT);
+  if (!Number.isSafeInteger(n) || n < 1 || positional.length > 2 || flags.filter(f => f !== '--citations' && f !== '--depth-manifest').some(f => !options[f])) refuse('RIG_REGISTRATION_USAGE', RIG_VERSION_HELP, USAGE_EXIT);
   const dir = realpathSync(resolve(positional[1] ?? process.cwd()));
   let { file, project } = readProject(dir);
   let original = readFileSync(file);
@@ -973,6 +1103,27 @@ export function rigVersionCommand(args: string[], now: number): { stdout: string
     const partsDir = resolve(dir, options['--parts']!);
     copyTree(join(partsDir, 'parts.json'), `${out}/out/parts.json`, true);
     copyTree(join(partsDir, 'parts'), `${out}/out/parts`, true);
+    // Keep the producer's complete depth reports in this same frozen registration.
+    // The config.depth image references above still use the ordinary path adapter.
+    let depthBinding: JsonObject | undefined;
+    const depthReport = join(partsDir, 'depth-report.json');
+    if (usesDepth(config) || options['--depth-manifest'] || existsSync(depthReport)) {
+      const perPart = options['--depth-manifest'] !== undefined || existsSync(depthReport) || !isObject(config.depth);
+      const sheets = join(dir, out, 'out/rig/depth_sheets.json');
+      // Rig files are copied below; bind the exact frozen source now.
+      const sourceSheets = resolve(dir, options['--rig']!, 'depth_sheets.json');
+      depthBinding = { route: perPart ? 'per-part' : 'per-layer' };
+      const approval = latestPartsApproval(project, Date.parse(String(at)));
+      const draft = asArray(project.drafts).filter(isObject).find(d => d.id === approval?.draft_id);
+      if (perPart && approval && isObject(draft?.parts) && typeof draft.parts.path === 'string') {
+        const originalParts = resolve(dir, draft.parts.path, 'parts.json');
+        if (!existsSync(originalParts)) fail('RIG_DEPTH_BINDING_MISSING', `versions[v${n}].registration.depth.source_parts`, 'restore the accepted assembled parts manifest before registering the depth-enriched version');
+        depthBinding.source_parts = retain(`${evidence}/depth-source-parts.json`, sourceBytes(originalParts));
+      }
+      if (existsSync(sourceSheets)) depthBinding.sheets = { path: relative(dir, sheets).split(sep).join('/'), sha256: sha(sourceBytes(sourceSheets)) };
+      if (options['--depth-manifest']) depthBinding.manifest = input('--depth-manifest', 'depth-manifest.json');
+      if (existsSync(depthReport)) depthBinding.report = retain(`${evidence}/depth-report.json`, sourceBytes(depthReport));
+    }
     const partReferences = partsFileReferences(partsDir);
     for (const reference of partReferences) {
       const target = `${out}/out/${reference.path}`;
@@ -1005,6 +1156,7 @@ export function rigVersionCommand(args: string[], now: number): { stdout: string
       changed: 'Registered frozen producer outputs', provenance: { config: configBinding, sections, ...(structureChanges.length ? { structure_delta: structureChanges } : {}) },
       registration: { kind: 'frozen-rig/1', at: registrationAt, toolchain: { kind: 'npm-lock-v3', source: toolchain },
         ...(runs.length ? { runs } : {}),
+        ...(depthBinding ? { depth: depthBinding } : {}),
         ...(skipped.length ? { skipped } : {}),
         files: retained, config_source: configSource,
         ...(requirementsSourceBinding ? { requirements_source: requirementsSourceBinding } : {}),
@@ -1012,6 +1164,8 @@ export function rigVersionCommand(args: string[], now: number): { stdout: string
         path_adapter: { ...adapterBinding, ...(pointerAdapted ? { format: 'json-pointer/1' } : {}) }, idle, compile,
         copied: { files: outputFiles.length, bytes: outputFiles.reduce((total, f) => total + Number(f.bytes), 0) } } };
     const candidate = { ...project, versions: [...project.versions, version] };
+    const depthProblem = depthBindingFindings(dir, { ...version, at: new Date(now).toISOString() }, config, version.registration as JsonObject, [])[0];
+    if (depthProblem) refuse(depthProblem.code, depthProblem.message);
     const problem = rigRegistrationFindings(dir, candidate)[0];
     if (problem) refuse(problem.code, problem.message);
     created.push(join(dir, pkg));
@@ -1045,3 +1199,60 @@ export function rigVersionCommand(args: string[], now: number): { stdout: string
     releasePublication();
   }
 }
+
+/** The optional plan step consumes approved parts before the ordinary rig step. */
+export function depthPlanMoves(project: JsonObject, collection: JsonObject | null = null): { role: 'agent'; field: string; awaits: string; command: null; act: string }[] {
+  const { answer, mode } = depthAnswer(project, collection);
+  if (mode !== 'depth') return [];
+  const answerAt = typeof answer.at === 'string' ? Date.parse(answer.at) : -Infinity;
+  const rig = asArray(project.versions).filter(isObject).find(v => v.kind === 'rig' && typeof v.at === 'string' && Date.parse(v.at) >= answerAt && isObject(v.registration) && isObject(v.registration.depth));
+  if (rig) return [];
+  const steps = ["Record the chosen depth route and reason in the turn plan step text. Default per-part sequence: rig-parts depth-prepare --parts <accepted assembled parts> --config <depth recipe> --out <inference directory>",
+    "Run the supplied depth model on each prepared image; retain raw rig-parts-map/1 maps (face normals, scalar depth for other parts).",
+    "rig-parts depth-apply --parts <accepted assembled parts> --manifest <inference/manifest.json> --config <depth recipe> --rig-config <config.json> --out <mapped directory>; then rig-parts rig --parts <mapped directory> --config <mapped/config.json> --out <rig directory>. Register with rig-version --parts <mapped directory> --rig <rig directory> --config <mapped/config.json> --depth-manifest <inference/manifest.json>."];
+  return steps.map((act, i) => ({ role: 'agent', field: `plan.steps[turn].moves[${i}]`, awaits: 'versions[].registration.depth', command: null, act }));
+}
+
+function depthAnswer(project: JsonObject, collection: JsonObject | null = null): { answer: JsonObject; mode: Json | undefined } {
+  const item = collectItems(project, { collection }).find(item => item.id === 'turn');
+  const answer = item?.state.state === 'user' || item?.state.state === 'delegated' ? item.state.answer : {};
+  const decision = answer.delegated === true && isObject(answer.agent_decision) ? answer.agent_decision.value : answer.value;
+  return { answer, mode: isObject(decision) ? decision.mode : undefined };
+}
+
+/** The optional depth step is drafted before its rigging-interview approval, just like the other rig steps. */
+export function depthPlanFindings(project: JsonObject, warnings: Finding[], collection: JsonObject | null = null): Finding[] {
+  const { answer, mode } = depthAnswer(project, collection);
+  if (mode !== 'depth') return [];
+  const answerAt = typeof answer.at === 'string' ? Date.parse(answer.at) : NaN;
+  const approved = asArray(project.signoffs).filter(isObject).some(s => s.stage === 'rigging-interview' && (s.checkpoint ?? null) === null && Date.parse(String(s.at)) >= answerAt);
+  if (!approved && !['rigging', 'rig-review', 'post-interview', 'post', 'direction-review', 'accepted'].includes(String(project.stage))) return [];
+  const plan = isObject(project.plan) ? project.plan : {};
+  const steps = asArray(plan.steps).filter(isObject);
+  const depth = steps.find(s => s.id === 'turn' && s.phase === 'rig' && asArray(s.rests_on).includes('turn'));
+  if (depth && steps.filter(s => s !== depth && s.phase === 'rig' && stageOfStep('rig', String(s.id)) === 'rigging').every(s => Number(depth.order) < Number(s.order))) return [];
+  const path = 'plan.steps[turn]';
+  const finding = { code: 'RIG_DEPTH_PLAN_MISSING', path, message: `${path}: a depth turn needs a rig-phase depth step resting on turn, ordered before the rig steps; draft it with plan add turn and approve it at rigging-interview before running rig` };
+  if (answerAt < Date.parse(HEAD_TURN_SINCE)) { warnings.push(finding); return []; }
+  return [finding];
+}
+
+/** Depth-apply may enrich only depth declarations; accepted art/geometry/measurements stay identical. */
+export function registeredDepthPartsMatch(dir: string, version: JsonObject, acceptedSha256: string, packagedSha256: string): boolean {
+  try {
+    const record = version.registration;
+    if (!isObject(record) || !isObject(record.depth) || record.depth.route !== 'per-part' || !isObject(record.depth.source_parts)
+      || record.depth.source_parts.sha256 !== acceptedSha256) return false;
+    const binding = asArray(version.outputs).filter(isObject).find(f => f.path === `outputs/v${String(version.n)}/out/parts.json` && f.sha256 === packagedSha256);
+    if (!binding) return false;
+    const config: Json = JSON.parse(bytesAt(dir, record.config_source).toString('utf8'));
+    if (!isObject(config) || depthBindingFindings(dir, version, config, record, []).length > 0) return false;
+    const withoutDepth = (bytes: Buffer): JsonObject => {
+      const doc: Json = JSON.parse(bytes.toString('utf8'));
+      if (!isObject(doc) || !Array.isArray(doc.parts) || doc.parts.some(p => !isObject(p))) throw Error('invalid parts manifest');
+      for (const part of doc.parts as JsonObject[]) delete part.depth;
+      return doc;
+    };
+    return isDeepStrictEqual(withoutDepth(bytesAt(dir, record.depth.source_parts)), withoutDepth(bytesAt(dir, binding, true)));
+  } catch { return false; }
+}

package/src/scene-writers.ts

@@ -10,13 +10,15 @@ import { SCENE_CHOICE_MISMATCH, resolveAgentCitationSpec } from './scene-authori
 import { SCENE_SPEC, SceneError, checkScenes, plateRegistration, pngDimensions, sceneBytes, sceneEntries, sceneFail, scenePath, sceneRig, validateScene } from './scene.ts';
 import type { JsonObject } from './templates.ts';
 
-export const SCENE_HELP = `scene write --rig <R> --background <path> [--foreground <path>]
+export const SCENE_HELP = `scene write --rig <R> --background <path> [--foreground <path>] [--animation <name>]
   [--background-rect x,y,w,h] [--foreground-rect x,y,w,h]
   --citations-file <retained project-relative JSON> [<dir>]
   Retain citations inside the project, for example evidence/scene-src/citations.json; absolute paths are refused.
   Citations are a role map {background: citation, foreground?: citation}.
   Each citation names post_composition, asks:["post_composition"], and quote or delegated:true.
   Paths and rects must match the current ingested post_composition choice.
+  Animation defaults to idle and must name a clip in the accepted bound model.
+  Only idle binds registration.idle frames; other clips omit optional frames.
   Records by:agent; typed --by is refused. Earlier human scenes remain readable.
   Appends evidence/scene/s<N>.json and scenes[]; stage stays unchanged.`;
 export interface SceneWriteHooks { beforeCommit?: () => void; }
@@ -31,7 +33,7 @@ function writeScene(args: string[], now: number, hooks: SceneWriteHooks): { stdo
   if (args[0] !== 'write') usage();
   for (let index = 1; index < args.length; index++) {
     const arg = args[index]!;
-    if (['--rig', '--background', '--foreground', '--background-rect', '--foreground-rect', '--citations-file', '--by'].includes(arg)) {
+    if (['--rig', '--background', '--foreground', '--background-rect', '--foreground-rect', '--citations-file', '--animation', '--by'].includes(arg)) {
       const value = args[++index];
       if (!value || value.startsWith('--') || opts[arg] !== undefined) usage();
       opts[arg] = value;
@@ -62,7 +64,7 @@ function writeScene(args: string[], now: number, hooks: SceneWriteHooks): { stdo
   try {
     const entries = sceneEntries(project);
     const n = entries.length + 1;
-    const binding = sceneRig(dir, project, Number(opts['--rig']), snapshots);
+    const binding = sceneRig(dir, project, Number(opts['--rig']), snapshots, opts['--animation']);
     const citationsBytes = sceneBytes(dir, opts['--citations-file']!, 'SCENE_CITATION_MISSING', snapshots);
     let citations: JsonObject;
     try { citations = JSON.parse(citationsBytes.toString('utf8')) as JsonObject; }

package/src/scene.ts

@@ -175,7 +175,17 @@ function modelForRig(dir: string, version: JsonObject, snapshots?: Map<string, B
   const binding = { path, sha256: row.sha256 };
   return { binding, model: json(boundBytes(dir, binding, 'SCENE_MODEL_MISMATCH', snapshots), path) };
 }
-export function sceneRig(dir: string, project: JsonObject, n: number, snapshots?: Map<string, Buffer>): { rig: JsonObject; stage: JsonObject } {
+/** New non-idle scenes omit frames. Retain the old reader's exact idle binding as legacy metadata. */
+function validateSceneAnimation(model: JsonObject, animation: JsonObject, registration: JsonObject): void {
+  if (!objects(model.animations).some(value => value.name === animation.name)) sceneFail('SCENE_ANIMATION_MISSING', 'scene.rig.animation.name', 'choose an animation named by the bound model', 'pass --animation with a name from the accepted model and run scene write');
+  if (registration.idle !== undefined && !sceneBinding(registration.idle)) sceneFail('SCENE_MALFORMED', 'scene.rig.animation.frames', 'registration.idle must be a frames binding');
+  if (animation.name === 'idle') {
+    if (!equal(animation.frames, registration.idle)) sceneFail('SCENE_MALFORMED', 'scene.rig.animation.frames', 'idle frames must be present exactly when registration.idle exists and equal that binding');
+  } else if (animation.frames !== undefined && !equal(animation.frames, registration.idle)) {
+    sceneFail('SCENE_ANIMATION_FRAMES_UNBOUND', 'scene.rig.animation.frames', 'frames differ from the only legacy binding, registration.idle', 'omit frames for a non-idle animation and record a new scene with scene write --animation <name>');
+  }
+}
+export function sceneRig(dir: string, project: JsonObject, n: number, snapshots?: Map<string, Buffer>, animation = 'idle'): { rig: JsonObject; stage: JsonObject } {
   const { version } = rigVersion(project, n);
   const reopens = collectReopens(project, []);
   const signature = collectSignoffs(project, []).filter(value => value.stage === 'rig-review' && value.checkpoint === null && liveSignoff(reopens, value.stage, value.at)
@@ -185,7 +195,8 @@ export function sceneRig(dir: string, project: JsonObject, n: number, snapshots?
   const { binding, model } = modelForRig(dir, version, snapshots);
   const registration = isObject(version.registration) ? version.registration : {};
   const rig: JsonObject = { version: n, acceptance: { signoff: { stage: 'rig-review', checkpoint: null, at: signature.record.at! }, verdict: target.verdict!, review_package: target.review_package! },
-    model: binding, animation: { name: 'idle', ...(registration.idle === undefined ? {} : { frames: registration.idle }) } };
+    model: binding, animation: { name: animation, ...(animation !== 'idle' || registration.idle === undefined ? {} : { frames: registration.idle }) } };
+  validateSceneAnimation(model, rig.animation as JsonObject, registration);
   validateSceneCurrent(project, rig, true);
   if (model.stage === null || model.stage === undefined) sceneFail('SCENE_STAGE_MISSING', String(binding.path), 'compile a model with a stage box');
   return { rig, stage: model.stage as JsonObject };
@@ -218,9 +229,8 @@ export function validateScene(dir: string, project: JsonObject, doc: JsonObject,
   const { binding, model } = modelForRig(dir, version, snapshots);
   if (!equal(rig.model, binding)) sceneFail('SCENE_MODEL_MISMATCH', 'scene.rig.model', 'use the accepted package model path and hash');
   const animation = rig.animation as JsonObject;
-  if (!objects(model.animations).some(value => value.name === animation.name)) sceneFail('SCENE_ANIMATION_MISSING', 'scene.rig.animation.name', 'choose an animation named by the model');
   const registration = isObject(version.registration) ? version.registration : {};
-  if (registration.idle !== undefined && !sceneBinding(registration.idle) || !equal(animation.frames, registration.idle)) sceneFail('SCENE_MALFORMED', 'scene.rig.animation.frames', 'frames must be present exactly when registration.idle exists and equal that binding');
+  validateSceneAnimation(model, animation, registration);
   if (isObject(animation.frames)) boundBytes(dir, animation.frames, 'SCENE_FILE_CHANGED', snapshots);
   if (model.stage === null || model.stage === undefined) sceneFail('SCENE_STAGE_MISSING', String(binding.path), 'compile a model with a stage box');
   if (!boxShape(model.stage) || !Object.values(model.stage).every(finite) || Number(model.stage.width) <= 0 || Number(model.stage.height) <= 0) sceneFail('SCENE_MALFORMED', `${String(binding.path)}.stage`, 'the model stage must be a finite positive box');

package/src/signable.ts

@@ -8,6 +8,7 @@ import { JOB_PLAN_BOUND_SIGNOFF_STAGES, type JobSelector, type JobSubject } from
 import { asArray, collectSignoffs, isObject, type CheckReport } from './check.ts';
 import { refuse } from './refusal.ts';
 import { collectReopens, liveSignoff } from './reopen.ts';
+import { acceptedReviewVerdict } from './review.ts';
 import { SIGNOFF_TARGET_KINDS } from './review-act.ts';
 import { STAGES, stageOfStep } from './stages.ts';
 import type { JsonObject } from './templates.ts';
@@ -27,7 +28,7 @@ export function assertInterviewRecordSignable(project: JsonObject, report: Check
 }
 
 /** Why `signoff <stage> --checkpoint <id>` refuses the step, or null when it can sign it. */
-export function checkpointProblem(project: JsonObject, stage: string, id: string): string | null {
+export function checkpointProblem(project: JsonObject, stage: string, id: string, now = Infinity): string | null {
   const spec = STAGES.find(spec => spec.id === stage);
   const matches = asArray(isObject(project.plan) ? project.plan.steps : undefined)
     .filter((step): step is JsonObject => isObject(step) && step.id === id);
@@ -35,7 +36,28 @@ export function checkpointProblem(project: JsonObject, stage: string, id: string
   if (matches.length !== 1 || spec?.phase === undefined || step.phase !== spec.phase || stageOfStep(spec.phase, id) !== stage) {
     return `${id}: no unique step runs in stage ${stage}`;
   }
-  return checkpointRequired(project, step) ? null : `${id}: checkpoint must be enabled before it can be signed`;
+  return checkpointRequired(project, step, now) ? null : `${id}: checkpoint must be enabled before it can be signed`;
+}
+
+/** An enabled, unwithdrawn checkpoint in `stage` that has no live checkpoint signature yet. */
+export function checkpointSignable(project: JsonObject, stage: string | null, id: string, now = Infinity): boolean {
+  if (stage === null || checkpointProblem(project, stage, id, now) !== null) return false;
+  const reopens = collectReopens(project, []);
+  return !collectSignoffs(project, []).some(signature => signature.stage === stage && signature.checkpoint === id
+    && liveSignoff(reopens, signature.stage, signature.at));
+}
+
+/** Whether the displayed version still needs a live accepted review verdict for `stage`. */
+export function reviewVerdictSignable(project: JsonObject, n: number, stage: 'rig-review' | 'direction-review'): boolean {
+  const version = asArray(project.versions).filter(isObject).find(v => v.n === n);
+  if (!version) return true;
+  const index = acceptedReviewVerdict(version, stage);
+  const verdict = index >= 0 ? asArray(version.verdicts)[index] : undefined;
+  if (!isObject(verdict)) return true;
+  const reopens = collectReopens(project, []);
+  const versionAt = Date.parse(String(version.at));
+  return (Number.isFinite(versionAt) && !liveSignoff(reopens, stage === 'direction-review' ? 'post' : 'rig-review', versionAt))
+    || !liveSignoff(reopens, stage, Date.parse(String(verdict.at)));
 }
 
 /** A stage closed by a sign-off that has no live stage-level signature yet. */
@@ -56,7 +78,7 @@ export function stageSignable(project: JsonObject, stage: string | null): boolea
 export function packageSignSubjects(project: JsonObject, stage: string | null, selector: JobSelector, planSteps: number): JobSubject[] {
   if (stage === null) return [];
   const subjects: JobSubject[] = asArray(isObject(project.plan) ? project.plan.steps : undefined)
-    .filter((step): step is JsonObject => isObject(step) && typeof step.id === 'string' && checkpointProblem(project, stage, step.id) === null)
+    .filter((step): step is JsonObject => isObject(step) && typeof step.id === 'string' && checkpointSignable(project, stage, step.id))
     .map(step => ({ kind: 'checkpoint', checkpointId: String(step.id) }));
   const target = SIGNOFF_TARGET_KINDS[stage];
   if (stageSignable(project, stage) && (target === undefined || selector.kind === target)

package/src/signoff-checkpoint-act.ts

@@ -2,13 +2,11 @@
 import { randomUUID } from 'node:crypto';
 import { readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import { asArray, isObject } from './check.ts';
 import { jobHash } from './job-outbox.ts';
-import { jobRuntimeExecArgv } from './job-writer.ts';
 import { refuse } from './refusal.ts';
-import { assertActSubjectDeclared, checkpointActSignoff, decodeReviewAct, reviewActFindings, reviewActTransport, type CheckpointAct, type ReviewActTransport } from './review-act.ts';
+import { assertActSubjectDeclared, checkpointActSignoff, decodeReviewAct, fetchReviewActBytes, reviewActFindings, reviewActTransport, type CheckpointAct, type ReviewActTransport } from './review-act.ts';
 import { stepHash } from './step-hash.ts';
 import { readCheckpointEvidence } from './checkpoint-evidence.ts';
 import type { JsonObject } from './templates.ts';
@@ -29,24 +27,12 @@ export interface CheckpointIngest {
   replay?: JsonObject;
 }
 
-function fetchBytes(transport: ReviewActTransport, hooks: SignoffHooks): string {
-  if (hooks.fetch) return hooks.fetch(transport).bytes;
-  const child = Bun.spawnSync([process.execPath, ...jobRuntimeExecArgv(), fileURLToPath(new URL('./review-act-runtime.ts', import.meta.url))], {
-    stdin: Buffer.from(JSON.stringify(transport)), stdout: 'pipe', stderr: 'pipe',
-  });
-  let response: { ok: boolean; bytes: string; code: string; message: string };
-  try { response = JSON.parse(child.stdout.toString()); }
-  catch { return refuse('REVIEW_ACT_FETCH_REFUSED', 'project.json.review_acts: fetch adapter failed; restore the live Review job'); }
-  if (!response.ok || child.exitCode) refuse(response.code, response.message);
-  return response.bytes;
-}
-
 /** Fetches, decodes and binds the act to the `--checkpoint` step the command already accepted. */
 export function ingestCheckpointAct(dir: string, project: JsonObject, actId: string, checkpointId: string, now: number, hooks: SignoffHooks): CheckpointIngest {
   const invalid = reviewActFindings(project)[0];
   if (invalid) refuse(invalid.code, invalid.message);
   const transport: ReviewActTransport = { ...reviewActTransport(dir, actId), kind: 'checkpoint' };
-  const bytes = fetchBytes(transport, hooks);
+  const bytes = hooks.fetch ? hooks.fetch(transport).bytes : fetchReviewActBytes(transport);
   const act = decodeReviewAct(bytes, 'checkpoint');
   if (act.jobId !== transport.jobId || act.actId !== transport.actId || Date.parse(act.at) > now) {
     refuse('REVIEW_ACT_INVALID', `signoffs.checkpoint ${checkpointId}: fetched act identity or date differs from the request; fetch the checkpoint act again`);

package/src/signoff.ts

@@ -6,13 +6,12 @@ import { assertDirectionApproval } from './direction.ts';
 import { assertCorrectionApproval } from './correction-writers.ts';
 import { createHash } from 'node:crypto';
 import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { acquireBoundJobWrite, jobRuntimeExecArgv } from './job-writer.ts';
+import { acquireBoundJobWrite } from './job-writer.ts';
 import { assertInterviewRecordSignable, checkpointProblem } from './signable.ts';
 import { checkpointReceipt, commitIngestedSignoff, ingestCheckpointAct, type CheckpointIngest, type SignoffHooks } from './signoff-checkpoint-act.ts';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { jobHash } from './job-outbox.ts';
-import { assertActSubjectDeclared, decodeReviewAct, isRecordDirectionSignoff, isRecordInterviewSignoff, recordSignoffActVersion, PLAN_BOUND_SIGNOFF_STAGES, reviewActFindings, reviewActSignoff, reviewActTransport, SIGNOFF_TARGET_KINDS, signoffActIdentity, signoffActVersion, type ReviewActTransport, type SignoffAct } from './review-act.ts';
+import { assertActSubjectDeclared, decodeReviewAct, fetchReviewActBytes, isRecordDirectionSignoff, isRecordInterviewSignoff, recordSignoffActVersion, PLAN_BOUND_SIGNOFF_STAGES, reviewActFindings, reviewActSignoff, reviewActTransport, SIGNOFF_TARGET_KINDS, signoffActIdentity, signoffActVersion, type ReviewActTransport, type SignoffAct } from './review-act.ts';
 
 import { asArray, checkProject, classify, collectItems, collectSignoffs, isObject, loadCollection, postNotPassed, type Finding } from './check.ts';
 import { checkDiffMap } from './diff-map.ts';
@@ -52,18 +51,7 @@ function fetchSignoffAct(dir: string, stage: string, actId: string, now: number,
   const invalid = reviewActFindings(readProject(dir).project)[0];
   if (invalid) refuse(invalid.code, invalid.message);
   const transport: ReviewActTransport = { ...reviewActTransport(dir, actId), kind: 'signoff' };
-  let bytes: string;
-  if (hooks.fetch) bytes = hooks.fetch(transport).bytes;
-  else {
-    const child = Bun.spawnSync([process.execPath, ...jobRuntimeExecArgv(), fileURLToPath(new URL('./review-act-runtime.ts', import.meta.url))], {
-      stdin: Buffer.from(JSON.stringify(transport)), stdout: 'pipe', stderr: 'pipe',
-    });
-    let response: { ok: boolean; bytes: string; code: string; message: string };
-    try { response = JSON.parse(child.stdout.toString()); }
-    catch { return refuse('REVIEW_ACT_FETCH_REFUSED', 'project.json.review_acts: fetch adapter failed; restore the live Review job'); }
-    if (!response.ok || child.exitCode) refuse(response.code, response.message);
-    bytes = response.bytes;
-  }
+  const bytes = hooks.fetch ? hooks.fetch(transport).bytes : fetchReviewActBytes(transport);
   const act = decodeReviewAct(bytes, 'signoff');
   if (act.jobId !== transport.jobId || act.actId !== transport.actId || Date.parse(act.at) > now) {
     refuse('REVIEW_ACT_INVALID', 'project.json.review_acts: fetched signoff identity or date differs from the request; fetch the correct signoff act');

package/src/waypoints.ts

@@ -17,7 +17,6 @@ export type Placement =
   | { readonly kind: 'none'; readonly why: string };
 
 const wp = (waypoint: string): Placement => ({ kind: 'waypoint', waypoint });
-const post = (item: string): Placement => ({ kind: 'post', item });
 const none = (why: string): Placement => ({ kind: 'none', why });
 
 export const SECTION_PLACEMENT: Readonly<Record<string, Placement>> = {
@@ -33,8 +32,8 @@ export const SECTION_PLACEMENT: Readonly<Record<string, Placement>> = {
   stops: wp('constraints'),
   cloth: wp('constraints'),
   motion: wp('motion'),
-  turn: post('camera_depth'),
-  depth: post('camera_depth'),
+  turn: wp('turn'),
+  depth: wp('turn'),
   key: none('a name'),
   generation: none('a record of a run'),
   proposed_rig_scale: none('a value the tool proposes'),
@@ -49,17 +48,16 @@ export const SECTION_PLACEMENT: Readonly<Record<string, Placement>> = {
 };
 
 /** Pipeline order of the rig waypoints; a waypoint not listed here sorts last, by name. */
-export const WAYPOINT_ORDER: readonly string[] = ['seethrough', 'assemble', 'bones', 'meshes', 'constraints', 'motion'];
+export const WAYPOINT_ORDER: readonly string[] = ['seethrough', 'assemble', 'bones', 'meshes', 'constraints', 'turn', 'motion'];
 
 /** The framing questions asked before the waypoints (INTERVIEW.md F1, F2). */
 export const FRAMING_IDS: readonly string[] = ['rig_type', 'reference'];
 
 /**
  * Post items with no config section of their own (INTERVIEW.md § Post-production).
- * `camera_depth` is not listed: it is derived from the `turn` and `depth`
- * sections through the table above.
+ * Camera framing remains post; rig depth and turn are asked before rigging.
  */
-export const SECTIONLESS_POST_ITEMS: readonly string[] = ['post_timing', 'post_composition'];
+export const SECTIONLESS_POST_ITEMS: readonly string[] = ['camera_depth', 'post_timing', 'post_composition'];
 
 export interface DerivedWaypoint {
   readonly id: string;
@@ -86,12 +84,13 @@ function byOrder(a: string, b: string): number {
 }
 
 /** Places every section parts has; the result is what a project's interview is checked against. */
-export function deriveWaypoints(sections: readonly string[]): DerivedSet {
+export function deriveWaypoints(sections: readonly string[], turnInterview = true): DerivedSet {
   const waypoints = new Map<string, string[]>();
   const items = new Map<string, string[]>();
   const unplaced: string[] = [];
   for (const section of sections) {
-    const placement = SECTION_PLACEMENT[section];
+    const placement = !turnInterview && (section === 'turn' || section === 'depth')
+      ? { kind: 'post' as const, item: 'camera_depth' } : SECTION_PLACEMENT[section];
     if (placement === undefined) {
       unplaced.push(section);
     } else if (placement.kind === 'waypoint') {
@@ -117,6 +116,17 @@ export interface WaypointAsk {
   readonly required_for?: 'fullscreen.game_logic' | 'other';
 }
 
+/** New depth obligations are dated by the rig build; old fixed-view records retain their mapping. */
+export const TURN_QUESTION_SPEC = 'rig-create/turn-question@1';
+export const HEAD_TURN_SINCE = '2026-11-14T00:00:00Z';
+export const TURN_QUESTION = 'Should this rig keep the painted view, or turn its head with depth?';
+export const TURN_OPTIONS = [
+  { id: 'fixed', kind: 'value', label: 'Fixed view', effect: 'Keep the painted view.', fragment: { mode: 'fixed' } },
+  { id: 'turn', kind: 'value', label: 'Head turn', effect: 'The head turns with depth, like the head-turn demo.', fragment: { mode: 'depth' } },
+  { id: 'other', kind: 'other', label: 'Other', effect: 'Describe the view you want.' },
+  { id: 'auto', kind: 'auto', label: 'Let the agent decide', effect: 'The agent records its decision before approval.' },
+] as const;
+
 export const WAYPOINT_ASKS: Readonly<Record<string, readonly WaypointAsk[]>> = {
   seethrough: [
     { id: 'layers', text: 'What must the layer split keep together or apart?' },
@@ -134,6 +144,7 @@ export const WAYPOINT_ASKS: Readonly<Record<string, readonly WaypointAsk[]>> = {
     { id: 'occluders', text: 'What is kept under occluders?' },
     { id: 'outfits', text: 'Which outfit sets exist?' },
   ],
+  turn: [{ id: 'view', text: TURN_QUESTION }],
   bones: [
     { id: 'chains', text: 'Which parts get chains or stay rigid?' },
     { id: 'placement', text: 'Where do bones sit?' },