@rig-c/create 0.0.0-stage → 1.0.0

package/src/diff-classes.ts

@@ -0,0 +1,219 @@
+/** Group only producer fields; no image measurement takes place here. */
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from './check-reads.ts';
+import { join, resolve } from 'node:path';
+
+import { checkProject, readJsonObject, type Finding } from './check.ts';
+import { diffReportBytes, reportShape, resolveDiffMapPartsFile, validateDiffMapRecord } from './diff-map.ts';
+import { acquireBoundJobWrite } from './job-writer.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import type { JsonObject } from './templates.ts';
+
+type Component = { id: string; px: number; uncovered_px: number; coverage: string; borders: { part: string }[] };
+type Key = { coverage_band: string; border_parts: string[] };
+export type DiffClass = { id: string; key: Key; members: string[]; px_range: number[]; uncovered_fraction_range: number[] };
+const object = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+const status = (v: unknown): boolean => typeof v === 'string' && ['in-painting', 'fixed', 'left'].includes(v);
+const nonempty = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+
+/** Quarter-width mixed bands limit the within-class spread to less than 0.25. */
+export function deriveDiffClasses(report: unknown): DiffClass[] {
+  if (!object(report) || !reportShape(report)) refuse('DIFF_MAP_REPORT', 'diff_map.report: needs a well-shaped rig-parts-diff-components/1 report; regenerate the report');
+  const groups = new Map<string, { key: Key; components: Component[] }>();
+  const ids = new Set<string>();
+  for (const c of report.components as Component[]) {
+    const fraction = c.uncovered_px / c.px;
+    if (ids.has(c.id) || fraction > 1 || c.coverage === 'covered' && fraction !== 0 || c.coverage === 'uncovered' && fraction !== 1 || c.coverage === 'mixed' && (fraction <= 0 || fraction >= 1)) {
+      refuse('DIFF_MAP_REPORT', `diff_map.report.components ${c.id}: duplicate id or inconsistent coverage counts; regenerate the report`);
+    }
+    ids.add(c.id);
+    const band = Math.floor(fraction * 4);
+    const key = { coverage_band: c.coverage === 'mixed' ? `mixed:${(band / 4).toFixed(2)}-${((band + 1) / 4).toFixed(2)}` : c.coverage,
+      border_parts: [...new Set(c.borders.map(b => b.part))].sort() };
+    const encoded = JSON.stringify(key);
+    const group = groups.get(encoded) ?? { key, components: [] };
+    group.components.push(c);
+    groups.set(encoded, group);
+  }
+  return [...groups.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([encoded, { key, components }]) => ({
+    id: `class-${createHash('sha256').update(encoded).digest('hex')}`, key,
+    members: components.map(c => c.id).sort(),
+    px_range: [Math.min(...components.map(c => c.px)), Math.max(...components.map(c => c.px))],
+    uncovered_fraction_range: [Math.min(...components.map(c => c.uncovered_px / c.px)), Math.max(...components.map(c => c.uncovered_px / c.px))],
+  }));
+}
+
+function specific(why: string, key: Key): boolean {
+  const tokens = [key.coverage_band, ...key.border_parts];
+  return tokens.some(token => {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^\\p{L}\\p{N}_-])${escaped}($|[^\\p{L}\\p{N}_-])`, 'iu').test(why);
+  });
+}
+
+/** Strict decision-only input: callers cannot supply keys or member lists. */
+export function expandDiffTriage(report: unknown, triage: unknown, path: string): JsonObject {
+  const fail = (detail: string): never => refuse('DIFF_MAP_TRIAGE', `${path}: ${detail}; use diff-classes and provide only status and why for each class or component id`);
+  if (!object(triage) || Object.keys(triage).some(k => !['classes', 'components'].includes(k))) fail('needs classes and/or components decision maps');
+  const input = triage as Record<string, unknown>;
+  const derived = new Map(deriveDiffClasses(report).map(c => [c.id, c]));
+  const ids = new Set((report as { components: Component[] }).components.map(c => c.id));
+  const classes: JsonObject[] = [], components: JsonObject[] = [];
+  for (const kind of ['classes', 'components']) {
+    const entries = input[kind] ?? {};
+    if (!object(entries)) fail(`${kind} must be an id-to-decision object`);
+    for (const [id, value] of Object.entries(entries as Record<string, unknown>)) {
+      if (!object(value) || Object.keys(value).length !== 2 || !status(value.status) || !nonempty(value.why)) fail(`${id} needs only status and nonempty why`);
+      const decision = value as { status: string; why: string };
+      if (kind === 'classes') {
+        const c = derived.get(id);
+        if (!c) fail(`unknown class ${id}`);
+        const group = c!;
+        if (!specific(decision.why, group.key)) refuse('DIFF_MAP_CLASS_WHY', `${path}.${id}.why: name a border part or ${group.key.coverage_band}; inspect this class and state its measured property`);
+        classes.push({ id, key: group.key, ...decision, members: group.members });
+        components.push(...group.members.map(member => ({ id: member, ...decision, class_id: id })));
+      } else {
+        if (!ids.has(id)) fail(`unknown component ${id}`);
+        components.push({ id, ...decision });
+      }
+    }
+  }
+  return { classes, components };
+}
+
+/** Optional class records are audited by both the writer and check. */
+export function checkDiffClasses(report: unknown, map: Record<string, unknown>, path: string, push: (code: string, detail: string) => void): void {
+  const components = map.components as Record<string, unknown>[];
+  if (map.classes === undefined && !components.some(c => object(c) && c.class_id !== undefined)) return;
+  let derived: DiffClass[];
+  try { derived = deriveDiffClasses(report); }
+  catch (error) { push('DIFF_MAP_CLASS', `${path}: ${error instanceof Error ? error.message : String(error)}`); return; }
+  if (!Array.isArray(map.classes)) { push('DIFF_MAP_CLASS', `${path}.classes must be a list; regenerate classes with --triage-file`); return; }
+  const expected = new Map(derived.map(c => [c.id, c]));
+  const seen = new Set<string>(), owners = new Map<string, Record<string, unknown>>();
+  for (const c of map.classes) {
+    if (!object(c) || !nonempty(c.id)) { push('DIFF_MAP_CLASS', `${path}.classes: class needs an id`); continue; }
+    const group = expected.get(c.id);
+    if (!group || seen.has(c.id) || !object(c.key) || Object.keys(c.key).length !== 2
+      || c.key.coverage_band !== group.key.coverage_band || JSON.stringify(c.key.border_parts) !== JSON.stringify(group.key.border_parts)
+      || !Array.isArray(c.members) || c.members.length !== group.members.length || new Set(c.members).size !== c.members.length
+      || c.members.some(id => typeof id !== 'string' || !group.members.includes(id))) {
+      push('DIFF_MAP_CLASS', `${path}.classes ${c.id}: key or full member set differs from the derived class, or id repeats`);
+      continue;
+    }
+    seen.add(c.id);
+    if (!status(c.status) || !nonempty(c.why)) push('DIFF_MAP_CLASS', `${path}.classes ${c.id}: needs a valid status and nonempty why`);
+    else if (!specific(c.why, group.key)) push('DIFF_MAP_CLASS_WHY', `${path}.classes ${c.id}: why must name a border part or ${group.key.coverage_band}`);
+    for (const member of c.members as string[]) {
+      if (owners.has(member)) push('DIFF_MAP_CLASS', `${path}.classes ${c.id}: ${member} belongs to more than one class`);
+      owners.set(member, c);
+      const expanded = components.filter(v => object(v) && v.id === member);
+      if (expanded.length !== 1 || expanded[0].class_id !== c.id || expanded[0].status !== c.status || expanded[0].why !== c.why) {
+        push('DIFF_MAP_CLASS', `${path}.components ${member}: class id, status and why must equal its class`);
+      }
+    }
+  }
+  for (const c of components) if (object(c) && c.class_id !== undefined && (!nonempty(c.id) || owners.get(c.id)?.id !== c.class_id)) {
+    push('DIFF_MAP_CLASS', `${path}.components ${String(c.id)}: class_id has no matching class membership`);
+  }
+}
+
+export const DIFF_CLASSES_HELP = `diff-classes [<project dir>] --diff-report <path> [--triage-file <file> | --component '<id>=<status>:<why>'] [--by agent] [--json]
+  Read derived classes as JSON: id, key, members, member_count, px_range and uncovered_fraction_range.
+  With --triage-file, --component or --by: validate and record the agent's component classification in project.json.diff_map.
+  Triage JSON: {"classes":{"<class id>":{"status":"left","why":"<property and observation>"}},"components":{}}.
+  Mixed bands have width 0.25; the lower bound is inclusive and upper bound exclusive.`;
+
+export function diffClassesCommand(args: string[], now: number = Date.now()): { stdout: string; exit: number } {
+  let dir: string | undefined;
+  let report: string | undefined;
+  let triageFile: string | undefined;
+  let by: string | undefined;
+  const components: JsonObject[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--json') continue;
+    if (arg === '--diff-report' && report === undefined) report = args[++i];
+    else if (arg === '--triage-file' && triageFile === undefined) triageFile = args[++i];
+    else if (arg === '--by' && by === undefined) by = args[++i];
+    else if (arg === '--component') {
+      const value = args[++i] ?? '';
+      const eq = value.indexOf('=');
+      const colon = value.indexOf(':', eq + 1);
+      if (eq < 1 || colon < eq + 2) refuse('DIFF_MAP_STATUS', 'diff_map: --component needs <id>=<status>:<why>', USAGE_EXIT);
+      const id = value.slice(0, eq);
+      if (components.some((c) => c.id === id)) refuse('DIFF_MAP_STATUS', `diff_map: duplicate component ${id}`, USAGE_EXIT);
+      components.push({ id, status: value.slice(eq + 1, colon), why: value.slice(colon + 1) });
+    } else if (arg.startsWith('-') || dir !== undefined) {
+      refuse('DIFF_MAP_TRIAGE', `diff_map.report: ${DIFF_CLASSES_HELP}`, USAGE_EXIT);
+    } else {
+      dir = arg;
+    }
+  }
+  if (!report || triageFile === '' || by === '' || (triageFile !== undefined && components.length > 0)) {
+    refuse('DIFF_MAP_TRIAGE', `diff_map.report: ${DIFF_CLASSES_HELP}`, USAGE_EXIT);
+  }
+  const root = resolve(dir ?? process.cwd());
+  const isWrite = triageFile !== undefined || components.length > 0 || by !== undefined;
+  if (!isWrite) {
+    try {
+      const classes = deriveDiffClasses(JSON.parse(diffReportBytes(root, report).toString('utf8')));
+      return { stdout: JSON.stringify(classes.map(c => ({ ...c, member_count: c.members.length })), null, 2), exit: 0 };
+    } catch (error) {
+      refuse('DIFF_MAP_REPORT', `diff_map.report ${report}: ${error instanceof Error ? error.message : String(error)}; generate a report under the project and read it again`);
+    }
+  }
+  const author = (by ?? 'agent').trim();
+  if (author.toLowerCase() !== 'agent') {
+    refuse('DIFF_MAP_NOT_AGENT', `diff_map.by: component classification is agent-authored ('--by agent', never a person); received ${JSON.stringify(by)}`);
+  }
+  const projectFile = join(root, 'project.json');
+  if (!existsSync(projectFile)) {
+    refuse('PROJECT_JSON_MISSING', `${projectFile} does not exist; run diff-classes in a project folder or name one`);
+  }
+  const release = acquireBoundJobWrite(root);
+  try {
+    const read = readJsonObject(projectFile);
+    if (!read.ok) refuse('PROJECT_JSON_INVALID', `${projectFile}: ${read.error}`);
+    const project = read.value;
+    let reportBytes: Buffer;
+    let parsedReport: unknown;
+    try {
+      reportBytes = diffReportBytes(root, report);
+      parsedReport = JSON.parse(reportBytes.toString('utf8'));
+    } catch (error) {
+      refuse('DIFF_MAP_REPORT', `diff_map.report ${report}: ${error instanceof Error ? error.message : String(error)}; generate a report under the project`);
+    }
+    const expanded = triageFile !== undefined
+      ? expandDiffTriage(parsedReport, readDiffTriage(resolve(root, triageFile)), 'diff_map')
+      : { components };
+    const diffMap: JsonObject = {
+      by: 'agent',
+      at: new Date(now).toISOString(),
+      report: { path: report, sha256: createHash('sha256').update(reportBytes).digest('hex') },
+      ...expanded,
+    };
+    const partsFile = resolveDiffMapPartsFile(root, project);
+    const errors: Finding[] = [];
+    validateDiffMapRecord(root, diffMap, 'diff_map', partsFile, errors, {
+      requireAgent: true,
+      label: 'signoffs[parts-review] diff_map',
+    });
+    if (errors[0] !== undefined) refuse(errors[0].code, errors[0].message);
+    const asRead = structuredClone(project);
+    project.diff_map = diffMap;
+    const baseline = new Set(checkProject(root, asRead, { now, readOnly: true }).refusals.map(f => `${f.code}\0${f.path}\0${f.message}`));
+    const fresh = checkProject(root, project, { now, readOnly: true }).refusals.find(f => !baseline.has(`${f.code}\0${f.path}\0${f.message}`));
+    if (fresh !== undefined) refuse(fresh.code, fresh.message);
+    writeFileSync(projectFile, `${JSON.stringify(project, null, 2)}\n`);
+    return { stdout: JSON.stringify({ diff_map: diffMap }, null, 2), exit: 0 };
+  } finally {
+    release();
+  }
+}
+
+export function readDiffTriage(file: string): unknown {
+  try { return JSON.parse(readFileSync(file, 'utf8')); }
+  catch (error) { refuse('DIFF_MAP_TRIAGE', `diff_map --triage-file ${file}: ${error instanceof Error ? error.message : String(error)}; supply a readable JSON decision file`); }
+}

package/src/diff-map.ts

@@ -0,0 +1,248 @@
+/** Hash-bound inventory on the latest parts-review sign-off. create never measures differences. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from './check-reads.ts';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { checkDiffClasses } from './diff-classes.ts';
+import { recordedPartsFinding, recordedPartsVerdict } from './parts-verdict-record.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+
+import type { Finding } from './check.ts';
+import type { JsonObject } from './templates.ts';
+
+export const DIFF_MAP_SINCE = '2026-11-06T00:00:00Z';
+export const DIFF_MAP_AGENT_SINCE = '2026-11-09T00:00:00Z';
+export const DIFF_MAP_MAX_FLOOR_PX = 2;
+export const DIFF_MAP_MAX_THRESHOLD = 40;
+export const DIFF_MAP_REMEDY =
+  'generate rig-parts diff-components on the reviewed assembly and record agent component classification with rig-create diff-classes --diff-report <path> --triage-file <file> --by agent (or --component <id>=<status>:<why> --by agent)';
+const SPEC = 'rig-parts-diff-components/1';
+const SHA256 = /^[0-9a-f]{64}$/;
+const object = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+const nonempty = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+const hash = (v: unknown): v is string => typeof v === 'string' && SHA256.test(v);
+const integer = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+const binding = (v: unknown): boolean => object(v) && nonempty(v.path) && hash(v.sha256);
+
+export function reportShape(v: Record<string, unknown>): boolean {
+  const d = v.definition;
+  const b = v.below_floor;
+  return v.spec === SPEC && binding(v.stack) && binding(v.painting) && object(d)
+    && d.metric === 'max-absolute-rgb-channel' && d.comparison === '>' && d.connectivity === 8
+    && d.coordinates === 'native' && d.y === 'down' && d.origin === 'top-left' && d.resampling === 'none'
+    && d.covered_alpha_above === 128 && integer(d.width) && d.width > 0 && integer(d.height) && d.height > 0
+    && integer(d.floor_px) && d.floor_px > 0 && typeof d.threshold === 'number' && Number.isFinite(d.threshold) && d.threshold >= 0 && d.threshold <= 255
+    && (d.inside_sha256 === null || hash(d.inside_sha256))
+    && integer(v.error_px) && integer(v.uncovered_error_px)
+    && object(b) && integer(b.count) && integer(b.px) && integer(b.uncovered_px)
+    && Array.isArray(v.components) && v.components.every((c) => object(c) && nonempty(c.id) && integer(c.px) && c.px > 0
+      && object(c.box) && integer(c.box.x) && integer(c.box.y) && integer(c.box.w) && c.box.w > 0 && integer(c.box.h) && c.box.h > 0
+      && typeof c.coverage === 'string' && ['covered', 'uncovered', 'mixed'].includes(c.coverage) && integer(c.uncovered_px)
+      && Array.isArray(c.borders) && c.borders.every((p) => object(p) && nonempty(p.part) && integer(p.px)));
+}
+
+/** A project-relative regular file, contained as written and with links followed. */
+export function diffReportBytes(dir: string, path: string): Buffer {
+  if (isAbsolute(path)) throw new Error('report path must be project-relative');
+  const file = resolve(dir, path);
+  const contained = (root: string, target: string): boolean => {
+    const rel = relative(root, target);
+    return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+  };
+  if (!contained(resolve(dir), file) || !contained(realpathSync(dir), realpathSync(file))) throw new Error('report must be under the project');
+  return readFileSync(file);
+}
+
+/** parts cli.ts assemble --out uses rig/ and render/; src/build.ts writes both beside one another. */
+export function diffStackCandidates(partsFile: string): string[] {
+  const dir = dirname(partsFile);
+  const candidates = [resolve(dir, 'recomposite_rig.png')];
+  if (basename(dir) === 'rig') candidates.push(resolve(dir, '..', 'render', 'recomposite_rig.png'));
+  return candidates;
+}
+
+/** Resolve the reviewed parts.json for stack checking from the latest live parts-review sign-off or latest draft. */
+export function resolveDiffMapPartsFile(dir: string, project: JsonObject): string | undefined {
+  const reopens = collectReopens(project, []);
+  const signoffs = Array.isArray(project.signoffs)
+    ? project.signoffs.filter((v): v is JsonObject => object(v))
+    : [];
+  let latest: JsonObject | undefined;
+  let bestAt = -Infinity;
+  for (const s of signoffs) {
+    if (s.stage !== 'parts-review' || (s.checkpoint ?? null) !== null) continue;
+    const at = typeof s.at === 'string' ? Date.parse(s.at) : NaN;
+    if (!liveSignoff(reopens, 'parts-review', at)) continue;
+    const score = Number.isNaN(at) ? -Infinity : at;
+    if (latest === undefined || score >= bestAt) {
+      latest = s;
+      bestAt = score;
+    }
+  }
+  if (latest !== undefined && !recordedPartsFinding(dir, project, latest, 'signoffs')) {
+    try {
+      return recordedPartsVerdict(dir, project, latest.draft_id, latest.evidence, { requireAvailable: false }).partsFile;
+    } catch {
+      // Fall through to draft lookup when receipt bytes are unavailable.
+    }
+  }
+  const drafts = Array.isArray(project.drafts)
+    ? project.drafts.filter((v): v is JsonObject => object(v))
+    : [];
+  const latestDraft = drafts.at(-1);
+  if (latestDraft !== undefined && typeof latestDraft.id === 'string') {
+    try {
+      return recordedPartsVerdict(dir, project, latestDraft.id, undefined, { requireAvailable: false }).partsFile;
+    } catch {
+      if (object(latestDraft.parts) && typeof latestDraft.parts.path === 'string') {
+        const candidate = resolve(dir, latestDraft.parts.path, 'parts.json');
+        if (existsSync(candidate) || diffStackCandidates(candidate).some((file) => existsSync(file))) return candidate;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function validateDiffMapRecord(
+  dir: string,
+  map: unknown,
+  path: string,
+  partsFile: string | undefined,
+  refusals: Finding[],
+  options: { requireAgent?: boolean; label?: string } = {},
+): void {
+  const label = options.label ?? path;
+  const push = (code: string, detail: string): void => {
+    refusals.push({ code, path, message: `${label}: ${detail}; ${DIFF_MAP_REMEDY}` });
+  };
+  if (!object(map)) {
+    push('DIFF_MAP_REPORT', 'report needs a project-relative path and lowercase sha256');
+    return;
+  }
+  if (options.requireAgent) {
+    if (map.by !== 'agent') {
+      push('DIFF_MAP_NOT_AGENT', `by is ${JSON.stringify(map.by ?? null)}, but component classification is agent-authored ('by': 'agent', never a person)`);
+      return;
+    }
+    if (map.at !== undefined && (typeof map.at !== 'string' || !Number.isFinite(Date.parse(map.at)))) {
+      push('DIFF_MAP_NOT_AGENT', 'at must be a readable ISO timestamp');
+      return;
+    }
+  }
+  if (!object(map.report) || !nonempty(map.report.path) || !hash(map.report.sha256)) {
+    push('DIFF_MAP_REPORT', 'report needs a project-relative path and lowercase sha256');
+    return;
+  }
+  let report: unknown;
+  try {
+    const bytes = diffReportBytes(dir, map.report.path);
+    if (createHash('sha256').update(bytes).digest('hex') !== map.report.sha256) throw new Error('sha256 differs from diff_map.report.sha256');
+    report = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    push('DIFF_MAP_REPORT', `${map.report.path}: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  if (!object(report) || !reportShape(report)) {
+    push('DIFF_MAP_REPORT', `${map.report.path}: needs a well-shaped ${SPEC} report`);
+    return;
+  }
+  const components = report.components as { id: string }[];
+  const ids = new Set(components.map((c) => c.id));
+  if (ids.size !== components.length) {
+    push('DIFF_MAP_REPORT', `${map.report.path}: duplicate report component ids`);
+    return;
+  }
+  const definition = report.definition as { floor_px: number; threshold: number };
+  if (definition.floor_px > DIFF_MAP_MAX_FLOOR_PX || definition.threshold > DIFF_MAP_MAX_THRESHOLD) {
+    push('DIFF_MAP_POLICY', `${map.report.path}: floor_px ${definition.floor_px} must be <= ${DIFF_MAP_MAX_FLOOR_PX} and threshold ${definition.threshold} must be <= ${DIFF_MAP_MAX_THRESHOLD}`);
+  }
+  if (partsFile !== undefined) {
+    const candidates = diffStackCandidates(partsFile);
+    const present = candidates.filter((file) => existsSync(file));
+    try {
+      if (present.length !== 1) throw new Error(present.length === 0 ? 'neither candidate is on disk' : 'both candidates are on disk, ambiguous');
+      const bytes = diffReportBytes(dir, relative(dir, present[0]));
+      if (createHash('sha256').update(bytes).digest('hex') !== (report.stack as { sha256: string }).sha256) throw new Error('sha256 differs from report.stack.sha256');
+    } catch (error) {
+      push('DIFF_MAP_STACK_MISMATCH', `${candidates.map((file) => relative(dir, file)).join(', ')} for ${map.report.path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (!Array.isArray(map.components)) {
+    push('DIFF_MAP_STATUS', `${map.report.path}: diff_map.components must be a list of {id, status, why}`);
+    return;
+  }
+  const listed = new Set<string>();
+  for (const c of map.components) {
+    if (!object(c) || !nonempty(c.id)) {
+      push('DIFF_MAP_STATUS', `${map.report.path}: component needs an id, status and why`);
+      continue;
+    }
+    if (!ids.has(c.id)) push('DIFF_MAP_COMPONENT_UNKNOWN', `${map.report.path}: unknown component ${c.id}`);
+    if (listed.has(c.id)) push('DIFF_MAP_STATUS', `${map.report.path}: component ${c.id} is listed more than once`);
+    listed.add(c.id);
+    if (typeof c.status !== 'string' || !['in-painting', 'fixed', 'left'].includes(c.status) || !nonempty(c.why)) {
+      push('DIFF_MAP_STATUS', `${map.report.path}: component ${c.id} needs status in-painting, fixed or left and nonempty why`);
+    }
+  }
+  for (const id of ids) if (!listed.has(id)) push('DIFF_MAP_COMPONENT_UNLISTED', `${map.report.path}: component ${id} is unlisted`);
+  checkDiffClasses(report, map, path, push);
+}
+
+/** `partsFile` is returned only by the successful parts-verdict reader. */
+export function checkDiffMap(
+  dir: string,
+  signoff: JsonObject,
+  at: string,
+  partsFile: string | undefined,
+  refusals: Finding[],
+  warnings: Finding[],
+  project?: JsonObject,
+): void {
+  const signoffPath = `${at}.diff_map`;
+  const date = typeof signoff.at === 'string' ? Date.parse(signoff.at) : NaN;
+  const predatesAgent = Number.isFinite(date) && date < Date.parse(DIFF_MAP_AGENT_SINCE);
+  if (signoff.diff_map !== undefined) {
+    if (predatesAgent) {
+      warnings.push({
+        code: 'DIFF_MAP_ON_SIGNOFF_LEGACY',
+        path: signoffPath,
+        message: `${at} ${signoffPath}: parts-review sign-off predates ${DIFF_MAP_AGENT_SINCE} and carries component classifications on the human sign-off; preserve this legacy record and record future classifications with rig-create diff-classes --diff-report <path> --triage-file <file> --by agent`,
+      });
+      if (project?.diff_map === undefined) {
+        validateDiffMapRecord(dir, signoff.diff_map, signoffPath, partsFile, refusals, {
+          requireAgent: false,
+          label: `${at} ${signoffPath}`,
+        });
+        return;
+      }
+    } else {
+      refusals.push({
+        code: 'SIGNOFF_DIFF_MAP_REMOVED',
+        path: signoffPath,
+        message: `${at} ${signoffPath}: component classification is agent-authored since ${DIFF_MAP_AGENT_SINCE} and cannot sit on a person's parts-review sign-off; remove diff_map from ${at} and record classification with rig-create diff-classes --diff-report <path> --triage-file <file> --by agent`,
+      });
+      if (project?.diff_map === undefined) return;
+    }
+  }
+  const map = project?.diff_map;
+  if (map === undefined) {
+    if (Number.isFinite(date) && date < Date.parse(DIFF_MAP_SINCE)) {
+      warnings.push({
+        code: 'DIFF_MAP_PREDATES',
+        path: 'diff_map',
+        message: `${at} diff_map: no diff_map, sign-off predates ${DIFF_MAP_SINCE}; preserve this record and record classification with rig-create diff-classes --diff-report <path> --triage-file <file> --by agent when parts are reviewed again`,
+      });
+    } else {
+      refusals.push({
+        code: 'DIFF_MAP_MISSING',
+        path: 'diff_map',
+        message: `${at} diff_map: no agent component classification recorded in project.json; ${DIFF_MAP_REMEDY}`,
+      });
+    }
+    return;
+  }
+  validateDiffMapRecord(dir, map, 'diff_map', partsFile, refusals, {
+    requireAgent: true,
+    label: `${at} diff_map`,
+  });
+}

package/src/direction-citation.ts

@@ -0,0 +1,13 @@
+/** The fixed-camera N/A exception is identical for direction and provenance readers. */
+import { isObject, type Item } from './check.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export function fixedNotApplicableCamera(section: string, item: Item | undefined, citation: Json | undefined, document: JsonObject | undefined): boolean {
+  const camera = document?.camera;
+  return section === 'camera'
+    && item?.state.state === 'not_applicable'
+    && isObject(citation) && typeof citation.quote === 'string'
+    && typeof item.state.answer.verbatim === 'string'
+    && item.state.answer.verbatim.includes(citation.quote)
+    && isObject(camera) && Array.isArray(camera.keys) && camera.keys.length === 1;
+}

package/src/direction-writers.ts

@@ -0,0 +1,119 @@
+/** Immutable direction publication; project.json is the single commit point. */
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { asArray, checkProject, collectItems, collectSignoffs, loadCollection, isObject, type Finding } from './check.ts';
+import { DIRECTION_CONTRACT, DirectionError, checkDirections, directionBinding, directionBytes, directionContract, directionFail, directionHash, directionIdleBytes, directionIdlePath, directionJson, directionPath, directionVersion, objects, patchDirection, readDirection, requireDirectionScene, validateDirectionCitations, validateDirectionRig, validateDirectionScene, validateDirectionShape } from './direction.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { REVIEW_ACCEPTS } from './stages.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { baselineOf, newFindings } from './refusal-baseline.ts';
+import { parseFeedbackAnswers } from './feedback.ts';
+import { handoff } from './review.ts';
+import { acquireBoundJobWrite, prepareVersionIntent, publishCommittedVersion } from './job-writer.ts';
+import { cancelUncommittedIntent, type PendingPublication } from './job-outbox.ts';
+import type { JsonObject } from './templates.ts';
+
+export const DIRECTION_HELP = `direction --adopt [<dir>]
+direction write <N> [<dir>] --file <retained JSON> --rig <R> [--answers <version>:<verdict>]
+direction patch <N> [<dir>] --patch-file <retained direction-patch/1> [--answers <version>:<verdict>]
+direction check <N> [<dir>] [--json]
+  Documents are immutable evidence/direction/v<N>.json. No rendering or producer builds.
+  Capture a made correction with correction record --direction-patch-file before patch ingestion;
+  resolve it against the result post. Review exports patches, never invokes this writer.`;
+function usage(why:string):never {refuse('DIRECTION_USAGE',`direction: ${why}; ${DIRECTION_HELP}`,USAGE_EXIT);}
+function openReview(project:JsonObject):void {
+  const reopens=collectReopens(project,[]);
+  if(collectSignoffs(project,[]).some(s=>s.stage==='direction-review'&&s.checkpoint===null&&liveSignoff(reopens,s.stage,s.at)) || objects(project.versions).some(v=>v.kind===REVIEW_ACCEPTS['direction-review']&&objects(v.verdicts).some(d=>d.review==='direction-review'&&d.verdict==='accepted'&&liveSignoff(reopens,'direction-review',Date.parse(String(d.at))))))directionFail('DIRECTION_REVIEW_CLOSED','signoffs','reopen direction-review before authoring');
+}
+function ownValidation(dir:string,project:JsonObject,now:number):void {const refusals:Finding[]=[];checkDirections({dir,project,refusals},now);if(refusals[0]){const f=refusals[0];directionFail(f.code,f.path,f.message);}}
+function prospective(dir:string,before:JsonObject,next:JsonObject,now:number):void {
+  const f=newFindings(baselineOf(checkProject(dir,before,{now})),checkProject(dir,next,{now}).refusals)[0];if(f)directionFail(f.code,f.path,f.message);
+}
+/** A narrow seam for fault-injected transaction tests; CLI never supplies a hook. */
+export interface DirectionWriteHooks { beforeCommit?:()=>void; }
+export function directionCommand(args:string[],now:number,hooks:DirectionWriteHooks={}):{stdout:string;exit:number} {
+  try{return command(args,now,hooks);}catch(e){if(e instanceof DirectionError)refuse(e.code,e.message,e.code==='DIRECTION_USAGE'?USAGE_EXIT:1);throw e;}
+}
+function command(args:string[],now:number,hooks:DirectionWriteHooks):{stdout:string;exit:number} {
+  const action=args[0];const positional:string[]=[];const opts:Record<string,string>={};const answerValues:string[]=[];let json=false;
+  for(let i=1;i<args.length;i++){const arg=args[i] as string;if(arg==='--answers'){const value=args[++i];if(!value||value.startsWith('--'))usage('--answers needs version:verdict');answerValues.push(value);}else if(arg==='--json'){if(json)usage('duplicate json');json=true;}else if(['--file','--rig','--patch-file'].includes(arg)){const value=args[++i];if(!value||value.startsWith('--')||opts[arg]!==undefined)usage(`invalid ${arg}`);opts[arg]=value;}else if(arg.startsWith('-'))usage(`unknown ${arg}`);else positional.push(arg);}
+  if(!['--adopt','write','patch','check'].includes(action??'')||positional.length>(action==='--adopt'?1:2))usage('unknown action/directory count');
+  const n=Number(positional[0]);if(action!=='--adopt'&&(!Number.isSafeInteger(n)||n<1))usage('N must be positive integer');
+  if(action==='write' ? !opts['--file']||!opts['--rig']||Boolean(opts['--patch-file']) : action==='patch' ? !opts['--patch-file']||Boolean(opts['--file']||opts['--rig']) : Object.keys(opts).length>0)usage('flags do not match action');
+  if(answerValues.length && action!=='write' && action!=='patch')usage('--answers is write/patch-only');
+  if(json&&action!=='check')usage('json is check-only');
+  const dir=resolve(positional[action==='--adopt'?0:1]??process.cwd());
+  // Root selected by the caller; record itself is still a literal regular file.
+  const file=join(dir,'project.json');const original=directionBytes(dir,'project.json');const project=directionJson(original,'project.json');
+  if(project.schema!=='rig-create/project@0')directionFail('DIRECTION_SCHEMA','project.json.schema','expected rig-create/project@0');
+  const collectionRoot=basename(dirname(dir))==='members'?dirname(dirname(dir)):null;
+  const collectionBytes=collectionRoot&&existsSync(join(collectionRoot,'collection.json'))?directionBytes(collectionRoot,'collection.json'):null;
+  if(action==='check'){
+    const v=directionVersion(project,n);if(v.kind!=='post')directionFail('DIRECTION_VERSION','versions','direction check needs a post');
+    const errors:Finding[]=[];checkDirections({dir,project,refusals:errors},now,n);if(errors[0])directionFail(errors[0].code,errors[0].path,errors[0].message);
+    const doc=readDirection(dir,project,n,false);
+    return{stdout:json?JSON.stringify({schema:'rig-create/direction-check@1',post:n,direction:(v.provenance as JsonObject).direction,document:doc}):`direction: v${n} valid`,exit:0};
+  }
+  const lock=join(dir,'.direction.lock');let fd:number;
+  try{fd=openSync(lock,'wx');}catch{directionFail('DIRECTION_SOURCE_CHANGED','project.json','another direction writer holds the lock');}
+  let published:string|null=null;const staged:string[]=[];
+  let releasePublication = () => {};
+  let publicationIntent: PendingPublication | null = null;
+  try{
+    releasePublication = acquireBoundJobWrite(dir);
+    const next=structuredClone(project);const contract=directionContract(project,now);
+    let bytes:Buffer|undefined;let doc:JsonObject|undefined;const snapshots=new Map<string,Buffer>([['project.json',original]]);
+    const snapshot=(path:string):Buffer=>{const value=directionBytes(dir,path);snapshots.set(path,value);return value;};
+    if(action==='--adopt'){
+      if(contract)return{stdout:'direction: already adopted; original adoption preserved',exit:0};
+      next.direction_contract={schema:DIRECTION_CONTRACT,adopted_at:new Date(now).toISOString(),grandfathered_posts:objects(project.versions).filter(v=>v.kind==='post').map(v=>v.n as number).sort((a,b)=>a-b)};
+    }else{
+      if(!contract)directionFail('DIRECTION_CONTRACT_INVALID','direction_contract','adopt direction explicitly first');
+      openReview(project);
+      if(objects(project.versions).some(v=>Number(v.n)>=n))directionFail('DIRECTION_VERSION','versions','new post number must be unique and later than all versions');
+      const answersFeedback=parseFeedbackAnswers(project,n,answerValues);
+      if(action==='write'){
+        bytes=snapshot(opts['--file'] as string);doc=directionJson(bytes,opts['--file'] as string);validateDirectionShape(doc);
+        if(!Number.isSafeInteger(Number(opts['--rig']))||Number(opts['--rig'])!==(doc.rig as JsonObject).version)directionFail('DIRECTION_RIG_UNKNOWN','direction.rig','--rig must name the document rig');
+      }else{
+        const patchBytes=snapshot(opts['--patch-file'] as string);const patch=directionJson(patchBytes,opts['--patch-file'] as string);
+        const source=readDirection(dir,project,patch.source_post,true);const sourceVersion=directionVersion(project,patch.source_post);snapshot(String(((sourceVersion.provenance as JsonObject).direction as JsonObject).path));
+        const latest=Math.max(0,...objects(project.versions).filter(v=>v.kind==='post').map(v=>Number(v.n)));
+        if(patch.source_post!==latest)directionFail('DIRECTION_PATCH','direction.patch.source_post','patch must target current post');
+        doc=patchDirection(project,source,patch);bytes=Buffer.from(`${JSON.stringify(doc,null,2)}\n`);
+      }
+      // Retain the option evidence read by the citation validator, not only the project bytes.
+      for(const item of collectItems(project,{collection:loadCollection(dir)}).filter(i=>['camera_depth','post_timing'].includes(i.id))){
+        const answers=[item.raw,...asArray(item.record.history)];
+        if(item.state.state==='user'||item.state.state==='delegated')answers.push(item.state.answer);
+        for(const answer of answers)if(isObject(answer)&&isObject(answer.choice)&&isObject(answer.choice.set)&&typeof answer.choice.set.path==='string')snapshot(answer.choice.set.path);
+      }
+      requireDirectionScene(doc, now, 'direction.schema');
+      validateDirectionScene(dir, project, doc, true, snapshots);
+      validateDirectionRig(dir,project,doc,true);validateDirectionCitations(dir,project,doc,true);
+      handoff(dir,Number((doc.rig as JsonObject).version),now);
+      snapshot(String(((doc.rig as JsonObject).model as JsonObject).path));
+
+      const binding={path:directionPath(n),sha256:directionHash(bytes)};
+      const version:JsonObject={n,kind:'post',rig_version:(doc.rig as JsonObject).version as number,at:new Date(now).toISOString(),built_by:'agent',built_with:{create:String(doc.schema).slice('rig-create/'.length)},changed:'Authored camera and timing direction',outputs:[binding],evidence:[],verdicts:[],answers_feedback:answersFeedback,review_origin:null,provenance:{config:binding,direction:binding,sections:{camera:[{entry:'camera',...((doc.citations as JsonObject).camera as JsonObject)}],timing:[{entry:'timing',...((doc.citations as JsonObject).timing as JsonObject)}]}}};
+      if(action==='patch'){const patch=directionJson(snapshots.get(opts['--patch-file'] as string) as Buffer,'direction.patch');version.direction_origin={source_post:patch.source_post as number,patch:directionBinding(dir,opts['--patch-file'] as string),result:binding};}
+      next.versions=[...asArray(next.versions),version];
+      // Validate using the exact staged bytes at their final immutable path, before committing the record.
+      const parent=dirname(join(dir,binding.path));let current=dir;
+      for(const part of ['evidence','direction']){current=join(current,part);if(existsSync(current)){if(!lstatSync(current).isDirectory()||lstatSync(current).isSymbolicLink())directionFail('DIRECTION_FILE',binding.path,'document parent must be a real directory');}else mkdirSync(current);}
+      if(existsSync(join(dir,binding.path)))directionFail('DIRECTION_SOURCE_CHANGED',binding.path,'immutable document already exists');
+      const temp=join(parent,`.direction-${crypto.randomUUID()}.tmp`);staged.push(temp);writeFileSync(temp,bytes,{flag:'wx'});renameSync(temp,join(dir,binding.path));published=join(dir,binding.path);
+    }
+    ownValidation(dir,next,now);prospective(dir,project,next,now);
+    hooks.beforeCommit?.();
+    if(collectionRoot && collectionBytes && !directionBytes(collectionRoot,'collection.json').equals(collectionBytes))directionFail('DIRECTION_SOURCE_CHANGED','collection.json','inherited answer context changed during publication');
+    // The scene's idle frames are re-read through the record binding that admitted them, not as a retained path.
+    for(const[path,expected]of snapshots)if(!(doc&&directionIdlePath(path)?directionIdleBytes(dir,project,Number((doc.rig as JsonObject).version),{path,sha256:directionHash(expected)}):directionBytes(dir,path)).equals(expected))directionFail('DIRECTION_SOURCE_CHANGED',path,'source bytes changed during publication');
+    if(bytes&&doc){const target=directionPath(n);if(!directionBytes(dir,target).equals(bytes))directionFail('DIRECTION_SOURCE_CHANGED',target,'published document changed before commit');}
+    const recordBytes = Buffer.from(`${JSON.stringify(next,null,2)}\n`);
+    if (action !== '--adopt') publicationIntent = prepareVersionIntent(dir, recordBytes, n);
+    const temp=join(dir,`.direction-${crypto.randomUUID()}.tmp`);staged.push(temp);writeFileSync(temp,recordBytes,{flag:'wx'});renameSync(temp,file);published=null;
+    if (action !== '--adopt') publishCommittedVersion(dir, n);
+    return{stdout:action==='--adopt'?'direction: adopted; historical posts preserved':`direction: v${n} recorded; stage unchanged`,exit:0};
+  }finally{cancelUncommittedIntent(dir,publicationIntent);if(published)rmSync(published,{force:true});for(const path of staged)rmSync(path,{force:true});closeSync(fd);rmSync(lock);releasePublication();}
+}