rig-create 0.0.0-stage → 1.0.1

package/src/run-record.ts

@@ -0,0 +1,232 @@
+/** Bind producer run records (rig-run/1 and rigc-run/1) by raw SHA-256 and spec shape without re-running or recomputing producer measurements. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from './check-reads.ts';
+import { isAbsolute, win32 } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, isObject, type Finding } from './check.ts';
+import { literalFile } from './choices.ts';
+import { structurePathIsIgnored } from './structure.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const RUN_RECORD_SINCE = '2026-11-08T00:00:00Z';
+export const RUN_SPECS = ['rig-run/1', 'rigc-run/1'] as const;
+export type RunSpec = (typeof RUN_SPECS)[number];
+export const RIGC_INPUT_ROLES = ['rig', 'motion', 'manifest', 'cuts'] as const;
+export const RIGC_REQUIRED_ROLES = ['rig', 'motion'] as const;
+
+const TOP_KEYS: Record<RunSpec, readonly string[]> = {
+  'rig-run/1': ['spec', 'package', 'command', 'started_at', 'finished_at', 'config', 'outputs'],
+  'rigc-run/1': ['spec', 'package', 'command', 'started_at', 'finished_at', 'inputs', 'outputs'],
+};
+
+const sha = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
+const absolute = (path: string): boolean => isAbsolute(path) || win32.isAbsolute(path);
+const literal = (path: string): boolean => !!path && !absolute(path) && !path.includes('\\') && !path.includes(':') && path.split('/').every(p => p !== '' && p !== '.' && p !== '..');
+const relativeRunPath = (path: Json | undefined): path is string =>
+  typeof path === 'string' && path.length > 0 && !absolute(path) && !path.startsWith('~') && !path.includes('\\') && !path.includes(':')
+  && path.split('/').every(segment => segment !== '' && segment !== '.');
+const hex64 = (value: Json | undefined): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const runTimestamp = (value: Json | undefined): value is string =>
+  typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value)
+  && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+
+export class RunRecordError extends Error {
+  constructor(readonly code: string, readonly path: string, readonly why: string) {
+    super(`${path}: ${why}; retain the producer run.json with --run-record and register a new rig version`);
+  }
+}
+
+function fail(code: string, path: string, why: string): never {
+  throw new RunRecordError(code, path, why);
+}
+
+export function isRunSpec(value: Json | undefined): value is RunSpec {
+  return value === 'rig-run/1' || value === 'rigc-run/1';
+}
+
+export function validateRunRecord(bytes: Buffer, path: string): { spec: RunSpec; record: JsonObject } {
+  let parsed: Json;
+  try { parsed = JSON.parse(bytes.toString('utf8')) as Json; }
+  catch { fail('RUN_RECORD_MALFORMED', path, 'expected valid UTF-8 JSON'); }
+  if (!isObject(parsed)) fail('RUN_RECORD_MALFORMED', path, 'expected a JSON object');
+  if (!isRunSpec(parsed.spec)) {
+    fail('RUN_RECORD_SPEC_UNKNOWN', `${path}.spec`, `unknown producer run spec ${JSON.stringify(parsed.spec ?? null)}; expected rig-run/1 or rigc-run/1`);
+  }
+  const spec = parsed.spec;
+  if (!isDeepStrictEqual(Object.keys(parsed), [...TOP_KEYS[spec]])) {
+    fail('RUN_RECORD_MALFORMED', path, `keys must be in published ${spec} order (${TOP_KEYS[spec].join(', ')})`);
+  }
+  const pkg = parsed.package;
+  if (!isObject(pkg) || !isDeepStrictEqual(Object.keys(pkg), ['name', 'version'])) {
+    fail('RUN_RECORD_MALFORMED', `${path}.package`, 'package must have keys name, version in that order');
+  }
+  const expectedNames = spec === 'rig-run/1' ? ['@rig-c/parts'] : ['@rig-c/core', 'rig-c'];
+  if (!expectedNames.includes(String(pkg.name)) || typeof pkg.version !== 'string' || !pkg.version.trim()) {
+    fail('RUN_RECORD_MALFORMED', `${path}.package`, `expected package.name ${expectedNames.map(name => JSON.stringify(name)).join(' or ')} and a nonempty version`);
+  }
+  if (spec === 'rig-run/1' ? (parsed.command !== 'rig' && parsed.command !== 'assemble') : parsed.command !== 'build') {
+    fail('RUN_RECORD_MALFORMED', `${path}.command`, `invalid ${spec} command ${JSON.stringify(parsed.command ?? null)}`);
+  }
+  if (!runTimestamp(parsed.started_at)) fail('RUN_RECORD_MALFORMED', `${path}.started_at`, 'expected a UTC ISO-8601 millisecond timestamp ending in Z');
+  if (!runTimestamp(parsed.finished_at)) fail('RUN_RECORD_MALFORMED', `${path}.finished_at`, 'expected a UTC ISO-8601 millisecond timestamp ending in Z');
+
+  if (spec === 'rig-run/1') {
+    const config = parsed.config;
+    if (!isObject(config) || !isDeepStrictEqual(Object.keys(config), ['path', 'sha256']) || !relativeRunPath(config.path) || !hex64(config.sha256)) {
+      fail('RUN_RECORD_MALFORMED', `${path}.config`, 'config must have relative path and 64-hex sha256 in that order');
+    }
+  } else {
+    const inputs = parsed.inputs;
+    if (!Array.isArray(inputs)) fail('RUN_RECORD_MALFORMED', `${path}.inputs`, 'inputs must be an array');
+    const seenRoles = new Set<string>();
+    let prevRoleOrder = -1;
+    let prevPath = '';
+    for (const [i, item] of inputs.entries()) {
+      const itemPath = `${path}.inputs[${i}]`;
+      if (!isObject(item)) fail('RUN_RECORD_MALFORMED', itemPath, 'input entry must be an object');
+      if (typeof item.role !== 'string' || !RIGC_INPUT_ROLES.includes(item.role as (typeof RIGC_INPUT_ROLES)[number])) {
+        fail('RUN_RECORD_ROLE_INVALID', `${itemPath}.role`, `unknown input role ${JSON.stringify(item.role ?? null)}; expected one of ${RIGC_INPUT_ROLES.join(', ')}`);
+      }
+      if (!isDeepStrictEqual(Object.keys(item), ['role', 'path', 'sha256']) || !relativeRunPath(item.path) || !hex64(item.sha256)) {
+        fail('RUN_RECORD_MALFORMED', itemPath, 'input entry must have keys role, path, sha256 in that order with a relative path and 64-hex sha256');
+      }
+      const roleOrder = RIGC_INPUT_ROLES.indexOf(item.role as (typeof RIGC_INPUT_ROLES)[number]);
+      if (roleOrder < prevRoleOrder) {
+        fail('RUN_RECORD_ROLE_INVALID', `${itemPath}.role`, `input roles must sort in fixed order (${RIGC_INPUT_ROLES.join(', ')})`);
+      }
+      if (roleOrder === prevRoleOrder && !(prevPath < item.path)) {
+        fail('RUN_RECORD_MALFORMED', `${itemPath}.path`, 'inputs with the same role must sort by path in UTF-16 code-unit order');
+      }
+      seenRoles.add(item.role);
+      prevRoleOrder = roleOrder;
+      prevPath = item.path;
+    }
+    for (const required of RIGC_REQUIRED_ROLES) {
+      if (!seenRoles.has(required)) {
+        fail('RUN_RECORD_ROLE_INVALID', `${path}.inputs`, `rigc-run/1 requires input role ${required}`);
+      }
+    }
+  }
+
+  const outputs = parsed.outputs;
+  if (!Array.isArray(outputs) || outputs.length === 0) {
+    fail('RUN_RECORD_MALFORMED', `${path}.outputs`, 'outputs must be a nonempty array');
+  }
+  let prevOutputPath = '';
+  for (const [i, out] of outputs.entries()) {
+    const outPath = `${path}.outputs[${i}]`;
+    if (!isObject(out) || !isDeepStrictEqual(Object.keys(out), ['path', 'sha256']) || !relativeRunPath(out.path) || !hex64(out.sha256)) {
+      fail('RUN_RECORD_MALFORMED', outPath, 'output entry must have keys path, sha256 in that order with a relative path and 64-hex sha256');
+    }
+    if (i > 0 && !(prevOutputPath < out.path)) {
+      fail('RUN_RECORD_MALFORMED', `${outPath}.path`, 'outputs must sort by path in UTF-16 code-unit order');
+    }
+    prevOutputPath = out.path;
+  }
+
+  return { spec, record: parsed };
+}
+
+export function checkRegisteredRuns(
+  dir: string,
+  versionPath: string,
+  record: JsonObject,
+  refusals: Finding[],
+  warnings: Finding[],
+): Set<string> {
+  const runPaths = new Set<string>();
+  const runsPath = `${versionPath}.registration.runs`;
+  if (record.runs === undefined) {
+    const finding: Finding = {
+      code: 'RUN_RECORD_REQUIRED',
+      path: runsPath,
+      message: `${runsPath}: version registered from the npm lock alone; retain producer run.json records with --run-record and register a new rig version`,
+    };
+    const at = Date.parse(String(record.at));
+    if (Number.isFinite(at) && at < Date.parse(RUN_RECORD_SINCE)) warnings.push(finding);
+    else refusals.push(finding);
+    return runPaths;
+  }
+  if (!Array.isArray(record.runs) || record.runs.length === 0) {
+    refusals.push({
+      code: 'RUN_RECORD_MALFORMED',
+      path: runsPath,
+      message: `${runsPath}: expected a nonempty list of bound producer run records; retain the producer run.json with --run-record and register a new rig version`,
+    });
+    return runPaths;
+  }
+  const files = asArray(record.files);
+  const seenSpecs = new Set<string>();
+  for (const [i, entry] of record.runs.entries()) {
+    const entryPath = `${runsPath}[${i}]`;
+    if (isObject(entry) && isObject(entry.source) && typeof entry.source.path === 'string') {
+      runPaths.add(entry.source.path);
+    }
+    if (!isObject(entry) || !('spec' in entry) || !('source' in entry) || Object.keys(entry).length !== 2) {
+      refusals.push({
+        code: 'RUN_RECORD_MALFORMED',
+        path: entryPath,
+        message: `${entryPath}: expected { spec, source }; restore the retained registration inputs or register a new rig version`,
+      });
+      continue;
+    }
+    if (!isRunSpec(entry.spec)) {
+      refusals.push({
+        code: 'RUN_RECORD_SPEC_UNKNOWN',
+        path: `${entryPath}.spec`,
+        message: `${entryPath}.spec: unknown producer run spec ${JSON.stringify(entry.spec ?? null)}; retain a rig-run/1 or rigc-run/1 run.json and register a new rig version`,
+      });
+      continue;
+    }
+    if (seenSpecs.has(entry.spec)) {
+      refusals.push({
+        code: 'RUN_RECORD_MALFORMED',
+        path: `${entryPath}.spec`,
+        message: `${entryPath}.spec: duplicate run record for spec ${entry.spec}; supply at most one --run-record per spec and register a new rig version`,
+      });
+      continue;
+    }
+    seenSpecs.add(entry.spec);
+    const source = entry.source;
+    let bytes: Buffer;
+    try {
+      if (!isObject(source) || typeof source.path !== 'string' || !literal(source.path)
+        || !hex64(source.sha256) || (source.bytes !== undefined && (typeof source.bytes !== 'number' || !Number.isSafeInteger(source.bytes) || source.bytes < 0))) {
+        throw Error('expected literal retained path, sha256 and byte count');
+      }
+      if (structurePathIsIgnored(dir, source.path)) throw Error('run record is under an ignored root');
+      const file = literalFile(dir, source.path);
+      bytes = readFileSync(file);
+      if (sha(bytes) !== source.sha256 || (typeof source.bytes === 'number' && bytes.length !== source.bytes)) {
+        throw Error(`${source.path} bytes differ from bound sha256`);
+      }
+      if (!files.some(f => isObject(f) && f.path === source.path && f.sha256 === source.sha256)) {
+        throw Error(`${source.path} is absent from registration.files or its sha256 disagrees`);
+      }
+    } catch (error) {
+      refusals.push({
+        code: 'RUN_RECORD_HASH_MISMATCH',
+        path: `${entryPath}.source`,
+        message: `${entryPath}.source: ${error instanceof Error ? error.message : String(error)}; restore the retained registration inputs or register a new rig version`,
+      });
+      continue;
+    }
+    try {
+      const validated = validateRunRecord(bytes, entryPath);
+      if (validated.spec !== entry.spec) {
+        fail('RUN_RECORD_MALFORMED', `${entryPath}.spec`, `declared spec ${entry.spec} disagrees with retained record spec ${validated.spec}`);
+      }
+    } catch (error) {
+      if (error instanceof RunRecordError) {
+        refusals.push({ code: error.code, path: error.path, message: error.message });
+      } else {
+        refusals.push({
+          code: 'RUN_RECORD_MALFORMED',
+          path: entryPath,
+          message: `${entryPath}: ${error instanceof Error ? error.message : String(error)}; restore the retained registration inputs or register a new rig version`,
+        });
+      }
+    }
+  }
+  return runPaths;
+}

package/src/scene-authority.ts

@@ -0,0 +1,410 @@
+/** Agent scene authority: every agent-authored scene derives from a recorded post_composition choice or decided delegation. */
+import { isDeepStrictEqual as equal } from 'node:util';
+import { asArray, collectItems, isObject, loadCollection, type Ctx, type Finding } from './check.ts';
+import { CHOICE_SPEC, OPTIONS_SPEC, choiceVerbatim, assembleFragments, optionFile, selection } from './choices.ts';
+import { closed } from './direction.ts';
+import { checkPlateReceipt } from './plate-receipt.ts';
+import { answersOf } from './provenance.ts';
+import { sceneBytes, sceneFail } from './scene.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const SCENE_CHOICE_MISSING = 'SCENE_CHOICE_MISSING';
+export const SCENE_CHOICE_MISMATCH = 'SCENE_CHOICE_MISMATCH';
+
+const MISSING_REMEDY =
+  'record a post_composition choice in the Review tool (or complete its delegated agent_decision) whose value.scene binds {background:{path,rect:{x,y,width,height}},foreground?:{path,rect:{x,y,width,height}}} and run scene write';
+const MISMATCH_REMEDY =
+  'match the exact roles, paths and rects from the cited post_composition choice in the Review tool (or record a new post_composition choice in the Review tool) and run scene write';
+
+const text = (value: unknown): value is string => typeof value === 'string' && value.trim().length > 0;
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const pathShape = (value: unknown): value is string =>
+  text(value) &&
+  !value.startsWith('/') &&
+  !value.includes('\\') &&
+  !/^[A-Za-z]:/.test(value) &&
+  value.split('/').every(part => part !== '' && part !== '.' && part !== '..');
+const boxShape = (value: unknown): value is JsonObject =>
+  closed(value, ['x', 'y', 'width', 'height']) && Object.values(value).every(v => typeof v === 'number');
+
+export const sceneAuthor = (value: unknown): value is string =>
+  value === 'agent' || (text(value) && value.toLowerCase() !== 'agent');
+
+export interface AgentRoleSpec {
+  path: string;
+  rect: JsonObject;
+}
+export interface AgentSceneSpec {
+  background: AgentRoleSpec;
+  foreground?: AgentRoleSpec;
+}
+
+function parseRoleSpec(role: 'background' | 'foreground', raw: Json | undefined, valuePath: string): AgentRoleSpec {
+  const rolePath = `${valuePath}.scene.${role}`;
+  if (!isObject(raw)) {
+    sceneFail(SCENE_CHOICE_MISSING, rolePath, `post_composition value.scene.${role} must be a closed {path,rect} object`, MISSING_REMEDY);
+  }
+  if (!('path' in raw) || raw.path === undefined) {
+    sceneFail(SCENE_CHOICE_MISSING, `${rolePath}.path`, `post_composition value.scene.${role} must declare a project-relative path`, MISSING_REMEDY);
+  }
+  if (!('rect' in raw) || raw.rect === undefined) {
+    sceneFail(SCENE_CHOICE_MISSING, `${rolePath}.rect`, `post_composition value.scene.${role} must declare rect:{x,y,width,height}`, MISSING_REMEDY);
+  }
+  if (!closed(raw, ['path', 'rect'])) {
+    sceneFail(SCENE_CHOICE_MISSING, rolePath, `post_composition value.scene.${role} allows only path and rect`, MISSING_REMEDY);
+  }
+  if (!pathShape(raw.path)) {
+    sceneFail(SCENE_CHOICE_MISSING, `${rolePath}.path`, `post_composition value.scene.${role}.path must be a literal project-relative path`, MISSING_REMEDY);
+  }
+  const rect = raw.rect;
+  if (!boxShape(rect) || !Object.values(rect).every(finite) || Number(rect.width) <= 0 || Number(rect.height) <= 0) {
+    sceneFail(SCENE_CHOICE_MISSING, `${rolePath}.rect`, `post_composition value.scene.${role}.rect must be a finite positive {x,y,width,height} box`, MISSING_REMEDY);
+  }
+  return { path: raw.path, rect };
+}
+
+export function parseAgentSceneValue(value: Json | undefined, valuePath: string): AgentSceneSpec {
+  if (!isObject(value) || !isObject(value.scene)) {
+    sceneFail(
+      SCENE_CHOICE_MISSING,
+      `${valuePath}.scene`,
+      'post_composition choice value must declare scene:{background:{path,rect},foreground?:{path,rect}}',
+      MISSING_REMEDY,
+    );
+  }
+  const scene = value.scene;
+  if (!('background' in scene) || scene.background === undefined) {
+    sceneFail(SCENE_CHOICE_MISSING, `${valuePath}.scene.background`, 'post_composition value.scene must declare background:{path,rect}', MISSING_REMEDY);
+  }
+  if (!closed(scene, ['background'], ['foreground'])) {
+    sceneFail(SCENE_CHOICE_MISSING, `${valuePath}.scene`, 'post_composition value.scene allows only background and optional foreground', MISSING_REMEDY);
+  }
+  const background = parseRoleSpec('background', scene.background, valuePath);
+  const foreground = scene.foreground === undefined ? undefined : parseRoleSpec('foreground', scene.foreground, valuePath);
+  return { background, ...(foreground ? { foreground } : {}) };
+}
+
+function matchesCitationSurface(answer: JsonObject, citation: JsonObject): boolean {
+  if (citation.delegated === true) {
+    return (
+      answer.delegated === true ||
+      asArray(answer.asks).some(ask => isObject(ask) && ask.id === 'post_composition' && ask.state === 'delegated') ||
+      isObject(answer.agent_decision)
+    );
+  }
+  if (typeof citation.quote === 'string' && citation.quote.trim().length > 0) {
+    return (
+      (typeof answer.verbatim === 'string' && answer.verbatim.includes(citation.quote)) ||
+      asArray(answer.additions).some(add => isObject(add) && typeof add.verbatim === 'string' && add.verbatim.includes(String(citation.quote)))
+    );
+  }
+  return false;
+}
+
+function resolveAnswerValue(
+  dir: string,
+  itemPath: string,
+  answer: JsonObject,
+  citation: JsonObject,
+  snapshots?: Map<string, Buffer>,
+): { value: Json | undefined; valuePath: string } {
+  if (!isObject(answer.choice) || answer.choice.spec !== CHOICE_SPEC) {
+    sceneFail(
+      SCENE_CHOICE_MISSING,
+      `${itemPath}.choice`,
+      'agent scene assembly requires a recorded Review interview-choice@1 on post_composition',
+      MISSING_REMEDY,
+    );
+  }
+  if (!isObject(answer.choice.set) || typeof answer.choice.set.path !== 'string') {
+    sceneFail(SCENE_CHOICE_MISSING, `${itemPath}.choice.set`, 'post_composition choice requires a retained option set binding', MISSING_REMEDY);
+  }
+  if (snapshots) sceneBytes(dir, answer.choice.set.path, 'SCENE_CITATION_MISSING', snapshots);
+  let set: JsonObject;
+  try {
+    set = optionFile(dir, answer.choice.set).set;
+  } catch {
+    return sceneFail(SCENE_CHOICE_MISSING, `${itemPath}.choice.set`, 'post_composition option set is missing or changed', MISSING_REMEDY);
+  }
+  let selected: ReturnType<typeof selection>;
+  try {
+    if (set.schema !== OPTIONS_SPEC || set.question !== 'post_composition' || !text(answer.by) || answer.by.toLowerCase() === 'agent'
+      || !text(answer.at) || !Number.isFinite(Date.parse(answer.at))) throw Error('invalid human choice identity');
+    selected = selection(set, answer.choice);
+    if (answer.delegated !== selected.delegated || !equal(answer.asks, selected.asks)
+      || answer.verbatim !== choiceVerbatim(asArray(answer.choice.picks).filter(isObject), answer.choice.note)) throw Error('choice projection differs');
+  } catch {
+    return sceneFail(SCENE_CHOICE_MISSING, `${itemPath}.choice`, 'post_composition choice does not match its retained option set', MISSING_REMEDY);
+  }
+  if (citation.delegated === true) {
+    if (!selected.delegated || !selected.autos.includes('post_composition')) {
+      sceneFail(SCENE_CHOICE_MISSING, `${itemPath}.choice`, 'cited post_composition choice did not delegate post_composition', MISSING_REMEDY);
+    }
+    const decision = answer.agent_decision;
+    if (
+      !isObject(decision) ||
+      decision.by !== 'agent' ||
+      !text(decision.at) ||
+      !Number.isFinite(Date.parse(decision.at)) ||
+      !text(decision.reasoning) ||
+      decision.value === undefined ||
+      decision.value === null ||
+      !Array.isArray(decision.fragments)
+    ) {
+      sceneFail(
+        SCENE_CHOICE_MISSING,
+        `${itemPath}.agent_decision`,
+        'complete the delegated post_composition agent_decision before assembling an agent scene',
+        MISSING_REMEDY,
+      );
+    }
+    const frag = decision.fragments.filter(isObject).find(entry => entry.ask === 'post_composition');
+    if (!frag || frag.fragment === undefined) {
+      sceneFail(
+        SCENE_CHOICE_MISSING,
+        `${itemPath}.agent_decision.fragments`,
+        'delegated post_composition decision must supply a post_composition fragment',
+        MISSING_REMEDY,
+      );
+    }
+    const rule = isObject(set.assembly) && typeof set.assembly.rule === 'string' ? set.assembly.rule : 'single';
+    let assembled: Json;
+    try {
+      assembled = assembleFragments(rule, [frag.fragment]);
+    } catch {
+      return sceneFail(SCENE_CHOICE_MISSING, `${itemPath}.agent_decision.value`, 'delegated post_composition fragment cannot be assembled', MISSING_REMEDY);
+    }
+    if (!equal(decision.value, assembled)) {
+      sceneFail(
+        SCENE_CHOICE_MISSING,
+        `${itemPath}.agent_decision.value`,
+        'delegated post_composition decision value differs from its assembled fragment',
+        MISSING_REMEDY,
+      );
+    }
+    return { value: decision.value, valuePath: `${itemPath}.agent_decision.value` };
+  }
+  if (selected.delegated || selected.pending.length > 0 || selected.value === undefined || selected.value === null || !equal(answer.value, selected.value)) {
+    sceneFail(
+      SCENE_CHOICE_MISSING,
+      `${itemPath}.value`,
+      'post_composition choice must have a resolved non-pending value from the retained option set',
+      MISSING_REMEDY,
+    );
+  }
+  if (typeof answer.verbatim !== 'string' || !answer.verbatim.includes(String(citation.quote))) {
+    sceneFail(
+      SCENE_CHOICE_MISSING,
+      `${itemPath}.verbatim`,
+      'agent scene citation quote must match the recorded Review choice verbatim',
+      MISSING_REMEDY,
+    );
+  }
+  return { value: answer.value, valuePath: `${itemPath}.value` };
+}
+
+function assertPlatesMatchSpec(plates: JsonObject[], spec: AgentSceneSpec): void {
+  const bgIndex = plates.findIndex(plate => plate.role === 'background');
+  const bgPlate = plates[bgIndex]!;
+  if (bgPlate.path !== spec.background.path) {
+    sceneFail(
+      SCENE_CHOICE_MISMATCH,
+      `scene.plates[${bgIndex}].path`,
+      'background plate path differs from post_composition value.scene.background.path',
+      MISMATCH_REMEDY,
+    );
+  }
+  if (!equal(bgPlate.rect, spec.background.rect)) {
+    sceneFail(
+      SCENE_CHOICE_MISMATCH,
+      `scene.plates[${bgIndex}].rect`,
+      'background plate rect differs from post_composition value.scene.background.rect',
+      MISMATCH_REMEDY,
+    );
+  }
+  const fgIndex = plates.findIndex(plate => plate.role === 'foreground');
+  const fgPlate = fgIndex >= 0 ? plates[fgIndex] : undefined;
+  if (spec.foreground !== undefined && !fgPlate) {
+    sceneFail(
+      SCENE_CHOICE_MISMATCH,
+      'scene.plates',
+      'post_composition value.scene declares a foreground plate that is absent from scene.plates',
+      MISMATCH_REMEDY,
+    );
+  }
+  if (spec.foreground === undefined && fgPlate) {
+    sceneFail(
+      SCENE_CHOICE_MISMATCH,
+      `scene.plates[${fgIndex}]`,
+      'scene declares a foreground plate not present in post_composition value.scene',
+      MISMATCH_REMEDY,
+    );
+  }
+  if (spec.foreground !== undefined && fgPlate) {
+    if (fgPlate.path !== spec.foreground.path) {
+      sceneFail(
+        SCENE_CHOICE_MISMATCH,
+        `scene.plates[${fgIndex}].path`,
+        'foreground plate path differs from post_composition value.scene.foreground.path',
+        MISMATCH_REMEDY,
+      );
+    }
+    if (!equal(fgPlate.rect, spec.foreground.rect)) {
+      sceneFail(
+        SCENE_CHOICE_MISMATCH,
+        `scene.plates[${fgIndex}].rect`,
+        'foreground plate rect differs from post_composition value.scene.foreground.rect',
+        MISMATCH_REMEDY,
+      );
+    }
+  }
+}
+
+/** Resolve the cited post_composition scene spec for an agent scene write before falling back to any stage rect. */
+export function resolveAgentCitationSpec(
+  dir: string,
+  project: JsonObject,
+  citation: Json,
+  snapshots?: Map<string, Buffer>,
+): AgentSceneSpec {
+  const collection = loadCollection(dir);
+  const items = collectItems(project, { collection });
+  const item = items.find(value => value.id === 'post_composition');
+  if (!item) sceneFail('SCENE_CITATION_MISSING', 'scene.plates[0].citation', 'cite a recorded post_composition answer or decided delegation');
+  if (
+    !isObject(citation) ||
+    !((closed(citation, ['guide', 'asks', 'quote']) && text(citation.quote)) ||
+      (closed(citation, ['guide', 'asks', 'delegated']) && citation.delegated === true)) ||
+    citation.guide !== 'post_composition' ||
+    !equal(citation.asks, ['post_composition'])
+  ) {
+    sceneFail('SCENE_CITATION_MISSING', 'scene.plates[0].citation', 'cite post_composition with asks and a quote or delegated:true');
+  }
+  const currentAnswer =
+    item.state.state === 'user' || item.state.state === 'delegated'
+      ? item.state.answer
+      : isObject(item.raw)
+        ? item.raw
+        : null;
+  if (!currentAnswer) {
+    sceneFail('SCENE_CITATION_MISSING', 'scene.plates[0].citation', 'cite a recorded post_composition answer or decided delegation');
+  }
+  if (!matchesCitationSurface(currentAnswer, citation)) {
+    const ctx: Ctx = {
+      dir,
+      project,
+      collection,
+      items,
+      refusals: [],
+      warnings: [],
+      signoffs: [],
+      steps: [],
+      stage: String(project.stage),
+      effectiveStage: String(project.stage),
+      predatesPartsReview: null,
+    };
+    const historical = answersOf(item, ctx).some(answer => matchesCitationSurface(answer, citation));
+    if (historical) {
+      sceneFail(SCENE_CHOICE_MISMATCH, 'scene.plates[0].citation', 'agent scene must cite the current post_composition choice or decided delegation', MISMATCH_REMEDY);
+    }
+    sceneFail('SCENE_CITATION_MISSING', 'scene.plates[0].citation', 'cite a recorded post_composition answer or decided delegation');
+  }
+  const { value, valuePath } = resolveAnswerValue(dir, item.path, currentAnswer, citation, snapshots);
+  return parseAgentSceneValue(value, valuePath);
+}
+
+export function validateAgentSceneAuthority(
+  dir: string,
+  project: JsonObject,
+  doc: JsonObject,
+  ctx: Ctx,
+  snapshots?: Map<string, Buffer>,
+  current = false,
+): void {
+  const plates = doc.plates as JsonObject[];
+  for (const [index, plate] of plates.entries()) {
+    const registration = plate.registered as JsonObject;
+    if (registration.kind === 'input') {
+      const match = /^inputs\[(\d+)\]$/.exec(String(registration.ref));
+      const entry = match ? asArray(project.inputs)[Number(match[1])] : undefined;
+      const bytes = sceneBytes(dir, String(plate.path), 'SCENE_PLATE_CHANGED', snapshots);
+      if (!isObject(entry) || entry.bytes !== bytes.length || !Number.isSafeInteger(entry.bytes)
+        || !text(entry.origin) || !text(entry.at) || !Number.isFinite(Date.parse(entry.at))) {
+        sceneFail('SCENE_INPUT_RECEIPT_MISSING', `scene.plates[${index}].registered`,
+          'candidate lacks input-writer metadata {path,sha256,bytes,origin,at}',
+          'register a new source name with input add <path> --origin … and select it through the Review choice');
+      }
+    }
+    if (registration.kind === 'derived') {
+      const match = /^derived\[(\d+)\]$/.exec(String(registration.ref));
+      const entry = match ? asArray(project.derived)[Number(match[1])] : undefined;
+      if (!isObject(entry) || !isObject(entry.receipt) || typeof entry.receipt.path !== 'string') {
+        sceneFail('SCENE_PLATE_UNREGISTERED', `scene.plates[${index}].registered`, 'agent scene derived plate requires a bound rig-parts-plate-receipt/1 receipt');
+      }
+      if (snapshots) sceneBytes(dir, entry.receipt.path, 'SCENE_FILE_CHANGED', snapshots);
+      const receiptFindings: Finding[] = [];
+      checkPlateReceipt({ dir, refusals: receiptFindings }, entry, `derived[${match![1]}]`);
+      if (receiptFindings.length > 0) {
+        sceneFail('SCENE_PLATE_UNREGISTERED', `scene.plates[${index}].registered`, 'agent scene derived plate has an invalid rig-parts-plate-receipt/1 receipt');
+      }
+    }
+  }
+  const item = ctx.items.find(value => value.id === 'post_composition');
+  if (!item) sceneFail('SCENE_CITATION_MISSING', 'scene.plates[0].citation', 'cite a recorded post_composition answer or decided delegation');
+  if (plates.length === 2) {
+    const first = plates[0]!.citation as JsonObject;
+    const second = plates[1]!.citation as JsonObject;
+    if (Boolean(first.delegated) !== Boolean(second.delegated)) {
+      sceneFail(
+        SCENE_CHOICE_MISMATCH,
+        'scene.plates[1].citation',
+        'background and foreground plates must cite the same post_composition choice or decided delegation',
+        MISMATCH_REMEDY,
+      );
+    }
+  }
+  const allAnswers = answersOf(item, ctx);
+  const currentPool =
+    item.state.state === 'user' || item.state.state === 'delegated'
+      ? [item.state.answer]
+      : isObject(item.raw)
+        ? [item.raw]
+        : [];
+  const pool = current ? currentPool : allAnswers.length > 0 ? allAnswers : currentPool;
+  const matching = pool.filter(answer => plates.every(plate => matchesCitationSurface(answer, plate.citation as JsonObject)));
+  if (matching.length === 0) {
+    if (current && allAnswers.some(answer => plates.every(plate => matchesCitationSurface(answer, plate.citation as JsonObject)))) {
+      sceneFail(SCENE_CHOICE_MISMATCH, 'scene.plates[0].citation', 'agent scene must cite the current post_composition choice or decided delegation', MISMATCH_REMEDY);
+    }
+    if (plates.length === 2 && pool.some(a => matchesCitationSurface(a, plates[0]!.citation as JsonObject)) && pool.some(a => matchesCitationSurface(a, plates[1]!.citation as JsonObject))) {
+      sceneFail(
+        SCENE_CHOICE_MISMATCH,
+        'scene.plates[1].citation',
+        'background and foreground plates must cite the same post_composition choice or decided delegation',
+        MISMATCH_REMEDY,
+      );
+    }
+    sceneFail('SCENE_CITATION_MISSING', 'scene.plates[0].citation', 'cite a recorded post_composition answer or decided delegation');
+  }
+  const validSpecs: AgentSceneSpec[] = [];
+  let firstError: unknown;
+  for (const answer of matching) {
+    try {
+      const { value, valuePath } = resolveAnswerValue(dir, item.path, answer, plates[0]!.citation as JsonObject, snapshots);
+      validSpecs.push(parseAgentSceneValue(value, valuePath));
+    } catch (error) {
+      if (!firstError) firstError = error;
+    }
+  }
+  if (validSpecs.length === 0) throw firstError;
+  let firstMismatch: unknown;
+  for (const spec of validSpecs) {
+    try {
+      assertPlatesMatchSpec(plates, spec);
+      return;
+    } catch (error) {
+      if (!firstMismatch) firstMismatch = error;
+    }
+  }
+  throw firstMismatch;
+}