@rig-c/review 0.5.0 → 0.7.0

package/src/physics-tuning.ts

@@ -0,0 +1,236 @@
+/**
+ * Physics tuning (#103), the pure half: which constraint rows of the inspected model the handoff config declares (so a
+ * field can be patched at `/constraints/<i>/<field>`), the pending edits as config patch ops that record the constraint's
+ * name beside its index, the constraint chains read from bone parentage with their root → tip ramp, and the check
+ * readout lines. No DOM, no IO, no clock; the producer judges every value (a mass of 0 is rigc's `A23` to refuse).
+ */
+import { formatPointer, type PatchOp } from './config-patch.ts';
+import type { CheckSummary } from './applied-context.ts';
+
+/** rig-c's `RigPhysicsConstraint` tuning fields (rig-c `src/rig.ts`; defaults 0.5 / 100 / 0.85 / 1 / 0 / 0 / 1). */
+export const TUNING_FIELDS = ['strength', 'damping', 'inertia', 'mass', 'wind', 'gravity', 'mix'] as const;
+export type TuningField = typeof TUNING_FIELDS[number];
+/** The components the panel toggles; rig-c stores each as a number (0 = off). `scaleX` and `shearX` are not offered. */
+export const COMPONENT_FIELDS = ['x', 'y', 'rotate'] as const;
+export type ComponentField = typeof COMPONENT_FIELDS[number];
+export type PhysicsField = TuningField | ComponentField;
+/** Slider extents; the number field beside each slider takes any finite value and the slider widens to hold it. */
+export const FIELD_RANGE: Readonly<Record<TuningField, { min: number; max: number; step: number }>> = {
+  strength: { min: 0, max: 1000, step: 1 }, damping: { min: 0, max: 1, step: 0.01 }, inertia: { min: 0, max: 1, step: 0.01 },
+  mass: { min: 0, max: 5, step: 0.05 }, wind: { min: -20, max: 20, step: 0.1 }, gravity: { min: -20, max: 20, step: 0.1 }, mix: { min: 0, max: 1, step: 0.01 },
+};
+/** The check bars whose lines the readout shows before and after an Apply. */
+export const READOUT_BARS = ['ANIMATIONS_DO_NOT_FOLD', 'TEXTURE_STRETCH'] as const;
+
+export interface TuningRow {
+  name: string; kind: string; bone: string | null;
+  /** Index in the inspected model's `constraints`, or null for a config entry the model does not have. */
+  modelIndex: number | null;
+  /** Index in the handoff config's `constraints`: the pointer's index. Null when the config does not declare the row. */
+  configIndex: number | null;
+  editable: boolean;
+  /** Why a row is not editable, by name; null when it is. */
+  reason: string | null;
+  /** The config's numeric values for the panel's fields, exactly as written; an absent field stays absent. */
+  values: Partial<Record<PhysicsField, number>>;
+}
+export type TuningTable = { available: true; rows: TuningRow[] } | { available: false; reason: string };
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const FIELDS: readonly PhysicsField[] = [...TUNING_FIELDS, ...COMPONENT_FIELDS];
+const numberOf = (v: unknown) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+
+/**
+ * The inspected model's constraints, each matched to the config entry of the same name and kind (the config's `type`
+ * is the model's `kind`). A row is editable only when it is a physics constraint the config declares and every field
+ * this panel edits (and the bone) reads the same on both sides — the config field maps 1:1 onto what the model holds.
+ */
+export function tuningRows(configConstraints: unknown, modelDocument: unknown): TuningTable {
+  if (!isObject(modelDocument) || !Array.isArray(modelDocument.constraints)) return { available: false, reason: 'PHYSICS_TUNING_UNAVAILABLE: the inspected model declares no constraints list' };
+  if (!Array.isArray(configConstraints)) return { available: false, reason: 'PHYSICS_TUNING_UNAVAILABLE: the handoff config has no constraints list' };
+  const config = configConstraints.map((entry, index) => ({ entry: isObject(entry) ? entry : {}, index }));
+  const used = new Set<number>();
+  const rows: TuningRow[] = [];
+  modelDocument.constraints.forEach((raw, modelIndex) => {
+    const m = isObject(raw) ? raw : {};
+    const name = typeof m.name === 'string' ? m.name : `#${modelIndex}`, kind = typeof m.kind === 'string' ? m.kind : 'unknown';
+    const bone = typeof m.bone === 'string' ? m.bone : null;
+    const found = config.find(c => !used.has(c.index) && c.entry.name === name && c.entry.type === kind);
+    if (!found) {
+      rows.push({ name, kind, bone, modelIndex, configIndex: null, editable: false, values: {}, reason: `PHYSICS_ROW_UNDECLARED: the model has ${kind} "${name}" but config.constraints does not declare it; it was added at the rig stage (e.g. the \`turn\` twins), so there is no config field to patch` });
+      return;
+    }
+    used.add(found.index);
+    const values: Partial<Record<PhysicsField, number>> = {};
+    for (const field of FIELDS) { const v = numberOf(found.entry[field]); if (v !== undefined) values[field] = v; }
+    if (kind !== 'physics') { rows.push({ name, kind, bone, modelIndex, configIndex: found.index, editable: false, values, reason: `PHYSICS_ROW_NOT_PHYSICS: config.constraints[${found.index}] is a ${kind} constraint; this panel tunes physics constraints only` }); return; }
+    const differs = [...FIELDS, 'bone'].find(field => JSON.stringify(found.entry[field]) !== JSON.stringify(m[field]));
+    if (differs) { rows.push({ name, kind, bone, modelIndex, configIndex: found.index, editable: false, values, reason: `PHYSICS_ROW_UNMAPPED: config.constraints[${found.index}].${differs} is ${JSON.stringify(found.entry[differs]) ?? 'absent'}, the model holds ${JSON.stringify(m[differs]) ?? 'absent'}; the config does not map 1:1 onto this row` }); return; }
+    rows.push({ name, kind, bone, modelIndex, configIndex: found.index, editable: true, reason: null, values });
+  });
+  for (const c of config) if (!used.has(c.index)) {
+    const name = typeof c.entry.name === 'string' ? c.entry.name : `#${c.index}`, kind = typeof c.entry.type === 'string' ? c.entry.type : 'unknown';
+    rows.push({ name, kind, bone: typeof c.entry.bone === 'string' ? c.entry.bone : null, modelIndex: null, configIndex: c.index, editable: false, values: {}, reason: `PHYSICS_ROW_NOT_IN_MODEL: config.constraints[${c.index}] ${kind} "${name}" is not in the inspected model` });
+  }
+  return { available: true, rows };
+}
+
+/** One pending edit: the patch op it becomes, with the field, the config's value before it and the constraint's name. */
+export interface PendingEdit { op: 'replace' | 'add'; path: string; value: number; name: string; configIndex: number; field: PhysicsField; from: number | null }
+export const pointerFor = (row: Pick<TuningRow, 'configIndex'>, field: PhysicsField) => formatPointer(['constraints', row.configIndex!, field]);
+
+/**
+ * The edit setting `field` of an editable row to `value`: `replace` when the config declares the field, `add` when it
+ * does not. Null when the value is the config's own (the edit reverts). Refused by name for a row that is not editable.
+ */
+export function editFor(row: TuningRow, field: PhysicsField, value: number): PendingEdit | null {
+  if (!row.editable || row.configIndex === null) throw new Error(row.reason ?? `PHYSICS_ROW_NOT_EDITABLE: ${row.name}`);
+  if (!FIELDS.includes(field)) throw new Error(`PHYSICS_FIELD_UNKNOWN: ${field}`);
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(`PHYSICS_VALUE_INVALID: ${row.name}.${field} must be a finite number`);
+  const from = row.values[field] ?? null;
+  if (from === value) return null;
+  return { op: from === null ? 'add' : 'replace', path: pointerFor(row, field), value, name: row.name, configIndex: row.configIndex, field, from };
+}
+
+/** Pending edits by pointer: a later edit of the same field replaces the earlier one; an edit back to the config's value drops it. */
+export function setEdit(edits: ReadonlyMap<string, PendingEdit>, row: TuningRow, field: PhysicsField, value: number): Map<string, PendingEdit> {
+  const next = new Map(edits), edit = editFor(row, field, value), path = pointerFor(row, field);
+  if (edit) next.set(path, edit); else next.delete(path);
+  return next;
+}
+
+/** The ops a patch carries, in edit order, each naming its constraint so the server resolves it by name as well as index. */
+export const patchOps = (edits: ReadonlyMap<string, PendingEdit>): PatchOp[] => [...edits.values()].map(e => ({ op: e.op, path: e.path, value: e.value, name: e.name }));
+
+/** A component's toggle: on keeps (or restores) the config's own weight, else 1; off is 0. */
+export function componentValue(row: TuningRow, field: ComponentField, on: boolean): number {
+  const declared = row.values[field];
+  return on ? (declared !== undefined && declared > 0 ? declared : 1) : 0;
+}
+
+/** Which components a row moves (non-zero x, y, rotate), as a chain groups links: "rotate", "x+y", … */
+export const componentSignature = (row: TuningRow) => COMPONENT_FIELDS.filter(f => (row.values[f] ?? 0) !== 0).join('+') || 'none';
+
+export interface PhysicsChain { id: string; label: string; signature: string; links: TuningRow[] }
+/**
+ * Chains of editable physics rows read from bone parentage: a link's parent link is the row on its bone's parent bone
+ * that moves the same components. Every root → tip path of two or more links is a chain (a fork gives one per branch).
+ */
+export function physicsChains(rows: readonly TuningRow[], bones: readonly { name: string; parent?: string | null }[]): PhysicsChain[] {
+  const parent = new Map(bones.map(b => [b.name, b.parent ?? null]));
+  const links = rows.filter(r => r.editable && r.kind === 'physics' && r.bone !== null);
+  const at = new Map<string, TuningRow[]>();
+  for (const row of links) { const key = `${componentSignature(row)}|${row.bone}`; at.set(key, [...(at.get(key) ?? []), row]); }
+  const one = (signature: string, bone: string | null) => { if (bone === null) return null; const found = at.get(`${signature}|${bone}`); return found && found.length === 1 ? found[0]! : null; };
+  const parentLink = (row: TuningRow) => one(componentSignature(row), parent.get(row.bone!) ?? null);
+  const children = new Map<TuningRow, TuningRow[]>();
+  for (const row of links) { const up = parentLink(row); if (up) children.set(up, [...(children.get(up) ?? []), row]); }
+  const chains: PhysicsChain[] = [];
+  const walk = (path: TuningRow[]) => {
+    const next = children.get(path.at(-1)!) ?? [];
+    if (!next.length) { if (path.length >= 2) { const signature = componentSignature(path[0]!); chains.push({ id: path.map(r => r.name).join('>'), signature, label: `${path[0]!.bone} → ${path.at(-1)!.bone} · ${signature} · ${path.length} links`, links: path }); } return; }
+    for (const child of next) walk([...path, child]);
+  };
+  for (const row of links) if (!parentLink(row)) walk([row]);
+  return chains;
+}
+
+/** Link i of n (0 at the root) takes root + (tip − root)·i/(n − 1): exactly one edit per link, linear root → tip. */
+export function rampValues(n: number, root: number, tip: number): number[] {
+  if (!Number.isInteger(n) || n < 2) throw new Error('PHYSICS_CHAIN_SHORT: a ramp needs two or more links');
+  return Array.from({ length: n }, (_, i) => root + (tip - root) * i / (n - 1));
+}
+/** The ramp as edits over the pending set: every link's `field` set once, root → tip. */
+export function applyRamp(edits: ReadonlyMap<string, PendingEdit>, chain: PhysicsChain, field: PhysicsField, root: number, tip: number): Map<string, PendingEdit> {
+  const values = rampValues(chain.links.length, root, tip);
+  let next = new Map(edits);
+  chain.links.forEach((row, i) => { next = setEdit(next, row, field, values[i]!); });
+  return next;
+}
+
+/**
+ * One readout line for a bar: check's own printed line for it (`  NAME: STATUS — …`) from the job's lines, else the
+ * bar's status from the summary, else "not in check summary" by name. Nothing is inferred.
+ */
+export function barLine(name: string, lines: readonly string[] | null, check: CheckSummary | null): string {
+  const printed = lines?.map(l => l.trim()).find(l => l.startsWith(`${name}: `));
+  if (printed) return printed;
+  const status = check?.bars[name];
+  return status ? `${name}: ${status} (status from check.json; check printed no line for it)` : `${name}: not in check summary`;
+}
+
+/** The inspected build's stored check (#108, HQ ruling) as `GET /api/rebuild` returns it. */
+export interface InspectedCheckView { status: 'running' | 'checked' | 'refused' | 'failed'; lines: string[]; check: CheckSummary | null; line: string }
+export const INSPECTED_NOT_CHECKED = (name: string) => `${name}: not in check summary (the inspected build; review ran no check on it)`;
+/**
+ * BEFORE: the build that was on the stage when Apply was pressed. A scratch build: its own check lines. The inspected
+ * build: the stored background check of it — labelled "check running…" while it runs (never a value), its line
+ * verbatim when check refused, and "not in check summary" only when no check exists (the baseline did not reproduce).
+ */
+export function beforeLine(name: string, stage: { lines: readonly string[]; check: CheckSummary | null } | null, inspected: InspectedCheckView | null): string {
+  if (stage) return barLine(name, stage.lines, stage.check);
+  if (!inspected) return INSPECTED_NOT_CHECKED(name);
+  if (inspected.status === 'running') return `${name}: check running… (rig-parts check of the inspected build, in the background)`;
+  if (inspected.status !== 'checked') return inspected.line;
+  return barLine(name, inspected.lines, inspected.check);
+}
+/** The readout rows after an Apply: BEFORE per `beforeLine`, AFTER from the job just built; `bars` defaults to the physics panel's. */
+export function readoutRows(stage: { lines: readonly string[]; check: CheckSummary | null } | null, inspected: InspectedCheckView | null, after: { lines: readonly string[]; check: CheckSummary | null }, bars: readonly string[] = READOUT_BARS) {
+  return bars.map(name => ({ name, before: beforeLine(name, stage, inspected), after: barLine(name, after.lines, after.check) }));
+}
+
+/** A control the row editor draws: a slider with its number field (a tuning field) or a toggle (a component). */
+export type RowControl =
+  | { kind: 'slider'; field: TuningField; value: number; base: number; min: number; max: number; step: number; pending: boolean }
+  | { kind: 'toggle'; field: ComponentField; on: boolean; base: number | null; pending: boolean };
+/**
+ * What the row editor shows for a row: for an editable row a slider per tuning field the config declares (an absent
+ * field is the producer's default, shown as absent and not offered) and the x / y / rotate toggles; for a row that is
+ * not editable no control at all, only the reason.
+ */
+export function rowControls(row: TuningRow, edits: ReadonlyMap<string, PendingEdit>): { editable: true; controls: RowControl[] } | { editable: false; reason: string } {
+  if (!row.editable || row.configIndex === null) return { editable: false, reason: row.reason ?? `PHYSICS_ROW_NOT_EDITABLE: ${row.name}` };
+  const current = (field: PhysicsField) => edits.get(pointerFor(row, field))?.value;
+  const controls: RowControl[] = [];
+  for (const field of TUNING_FIELDS) {
+    const base = row.values[field];
+    if (base === undefined && current(field) === undefined) continue;
+    const value = current(field) ?? base!, range = FIELD_RANGE[field];
+    controls.push({ kind: 'slider', field, value, base: base ?? value, min: Math.min(range.min, value), max: Math.max(range.max, value), step: range.step, pending: current(field) !== undefined });
+  }
+  for (const field of COMPONENT_FIELDS) {
+    const value = current(field) ?? row.values[field] ?? 0;
+    controls.push({ kind: 'toggle', field, on: value !== 0, base: row.values[field] ?? null, pending: current(field) !== undefined });
+  }
+  return { editable: true, controls };
+}
+
+/** The chain whose link bone lies nearest a click on the stage, within `radius` px; null when none does. */
+export function nearestChain(chains: readonly PhysicsChain[], points: ReadonlyMap<string, { x: number; y: number }>, click: { x: number; y: number }, radius = 24): PhysicsChain | null {
+  let best: { chain: PhysicsChain; d: number } | null = null;
+  for (const chain of chains) for (const link of chain.links) {
+    const p = link.bone ? points.get(link.bone) : undefined;
+    if (!p) continue;
+    const d = Math.hypot(p.x - click.x, p.y - click.y);
+    if (d <= radius && (!best || d < best.d)) best = { chain, d };
+  }
+  return best?.chain ?? null;
+}
+
+/** The draft's record of the panel: the pending edits (in order) as the patch ops they become. */
+export const PHYSICS_DRAFT_SCHEMA = 'rig-review-physics-draft/1';
+export function draftText(edits: ReadonlyMap<string, PendingEdit>): string { return JSON.stringify({ schema: PHYSICS_DRAFT_SCHEMA, edits: [...edits.values()] }); }
+/** Edits back from a draft, kept only where the row still resolves (same name at the same index, still editable). */
+export function draftEdits(text: string, rows: readonly TuningRow[]): Map<string, PendingEdit> {
+  let doc: unknown;
+  try { doc = JSON.parse(text); } catch { return new Map(); }
+  if (!isObject(doc) || doc.schema !== PHYSICS_DRAFT_SCHEMA || !Array.isArray(doc.edits)) return new Map();
+  let edits = new Map<string, PendingEdit>();
+  for (const raw of doc.edits) {
+    if (!isObject(raw) || typeof raw.value !== 'number' || typeof raw.field !== 'string') continue;
+    const row = rows.find(r => r.editable && r.configIndex === raw.configIndex && r.name === raw.name);
+    if (!row || !FIELDS.includes(raw.field as PhysicsField)) continue;
+    try { edits = setEdit(edits, row, raw.field as PhysicsField, raw.value); } catch { /* a value the panel would refuse is not restored */ }
+  }
+  return edits;
+}

package/src/producer-files.ts

@@ -0,0 +1,11 @@
+/**
+ * What `rig-parts rig` (and `remesh`) writes into a rig directory, as review compares it (#125): the JSON documents by
+ * name, and the part images under `images/` by hash. The baseline (`src/baseline.ts`, does the handoff reproduce the
+ * inspected rig?) and the applied-state diff (`src/rebuild.ts`, what did the patch change?) both read this one list, so a
+ * document the producer starts writing is one line here. Pure: no imports, no IO.
+ */
+export const PRODUCER_DOCUMENTS = ['rig.json', 'motion.json', 'sets.json', 'mesh_report.json'] as const;
+export type ProducerDocument = typeof PRODUCER_DOCUMENTS[number];
+/** The part images' directory inside a rig directory; compared by hash, file by file. */
+export const PRODUCER_IMAGES_DIR = 'images';
+export const isProducerFile = (path: string): boolean => (PRODUCER_DOCUMENTS as readonly string[]).includes(path) || path.startsWith(`${PRODUCER_IMAGES_DIR}/`);

package/src/producer.ts

@@ -0,0 +1,158 @@
+/**
+ * The installed producer (`@rig-c/parts`' `rig-parts`) and the compiler it gates with (`rig-c`'s `rigc`), resolved the
+ * way `rigc review` resolves `rig-review`: the package's own `package.json` under the nearest `node_modules` walking
+ * up from each start directory, its `bin` entry read from that manifest. No PATH lookup, no install, no prompt.
+ * Review builds nothing itself: it runs these binaries as child processes with arguments it composes from a typed
+ * request, and reports what they printed.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const PRODUCER_PACKAGE = '@rig-c/parts';
+export const PRODUCER_BIN = 'rig-parts';
+export const COMPILER_PACKAGE = 'rig-c';
+export const COMPILER_BIN = 'rigc';
+/** The first `@rig-c/parts` release with `rig-parts remesh` (its CHANGELOG: 1.40.0, "remesh: re-fit one part of a gated rig"). */
+export const REMESH_SINCE = '1.40.0';
+/**
+ * The first `@rig-c/parts` release whose `rig-parts remesh` reads `--delta <mesh-edit.json>` in place of `--mesh` (its
+ * CHANGELOG: 1.43.0, "remesh: --delta replays rig-c/review's mesh edit over one part's mesh", parts#528). Edit Mesh's
+ * Apply · Rebuild (#135) needs it; the version is read off the installed producer's own `package.json`.
+ */
+export const REMESH_DELTA_SINCE = '1.43.0';
+export const MODELING_PRODUCER_NOT_INSTALLED = `MODELING_PRODUCER_NOT_INSTALLED: ${PRODUCER_PACKAGE} is not installed beside the package or beside review, and review does not install it — bun add -d ${PRODUCER_PACKAGE}`;
+export const modelingProducerTooOld = (found: string, required: string, what = 'rig-parts remesh') => `MODELING_PRODUCER_TOO_OLD ${found} ${required}: ${what} needs ${PRODUCER_PACKAGE} ${required} or later — bun add -d ${PRODUCER_PACKAGE}@latest`;
+export const MODELING_COMPILER_NOT_INSTALLED = `MODELING_COMPILER_NOT_INSTALLED: ${COMPILER_PACKAGE} is not installed beside ${PRODUCER_PACKAGE}, which gates its rigs with it — reinstall ${PRODUCER_PACKAGE} (bun add -d ${PRODUCER_PACKAGE})`;
+
+export interface InstalledTool { package: string; version: string; root: string; bin: string }
+export type ProducerResolution = { ok: true; producer: InstalledTool; compiler: InstalledTool } | { ok: false; error: string };
+
+/** The nearest `node_modules/<name>/package.json` walking up from each start, first start first. */
+export function findPackage(name: string, starts: readonly string[], exists: (path: string) => boolean = existsSync): string | null {
+  for (const start of starts) {
+    for (let dir = resolve(start); ; dir = dirname(dir)) {
+      const manifest = join(dir, 'node_modules', name, 'package.json');
+      if (exists(manifest)) return manifest;
+      if (dirname(dir) === dir) break;
+    }
+  }
+  return null;
+}
+
+/** `X.Y.Z` → [X, Y, Z]; anything else is null (a pre-release tag is not compared, it is refused as unread). */
+export function parseVersion(text: unknown): [number, number, number] | null {
+  const match = typeof text === 'string' ? /^(\d+)\.(\d+)\.(\d+)$/.exec(text.trim()) : null;
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+export function versionAtLeast(found: string, required: string): boolean {
+  const a = parseVersion(found), b = parseVersion(required);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i]! > b[i]!;
+  return true;
+}
+
+function readTool(manifest: string, binName: string): InstalledTool | { error: string } {
+  let value: Record<string, unknown>;
+  try { value = JSON.parse(readFileSync(manifest, 'utf8')); } catch { return { error: `${manifest} is not readable JSON` }; }
+  const bins = value.bin, relative = typeof bins === 'object' && bins !== null ? (bins as Record<string, unknown>)[binName] : undefined;
+  const root = dirname(manifest), version = typeof value.version === 'string' ? value.version : '';
+  if (typeof relative !== 'string') return { error: `${String(value.name)} at ${root} declares no "${binName}" bin` };
+  const bin = resolve(root, relative);
+  try { if (!statSync(bin).isFile()) throw new Error(); } catch { return { error: `${String(value.name)} at ${root} declares the "${binName}" bin ${relative}, which is not there` }; }
+  return { package: typeof value.name === 'string' ? value.name : '', version, root, bin };
+}
+
+/**
+ * Producer: walking up from the inspected package, then from review's working directory. Compiler: walking up from
+ * the producer's own package directory, which is where `rig-parts` itself finds the `rigc` it gates remesh with.
+ */
+export function resolveProducer(starts: readonly string[], exists: (path: string) => boolean = existsSync): ProducerResolution {
+  const manifest = findPackage(PRODUCER_PACKAGE, starts, exists);
+  if (!manifest) return { ok: false, error: MODELING_PRODUCER_NOT_INSTALLED };
+  const producer = readTool(manifest, PRODUCER_BIN);
+  if ('error' in producer) return { ok: false, error: `${MODELING_PRODUCER_NOT_INSTALLED} (${producer.error})` };
+  if (!versionAtLeast(producer.version, REMESH_SINCE)) return { ok: false, error: modelingProducerTooOld(producer.version || 'unknown', REMESH_SINCE) };
+  const compilerManifest = findPackage(COMPILER_PACKAGE, [producer.root], exists);
+  if (!compilerManifest) return { ok: false, error: MODELING_COMPILER_NOT_INSTALLED };
+  const compiler = readTool(compilerManifest, COMPILER_BIN);
+  if ('error' in compiler) return { ok: false, error: `${MODELING_COMPILER_NOT_INSTALLED} (${compiler.error})` };
+  return { ok: true, producer, compiler };
+}
+
+export interface RemeshRequest { rig: string; config: string; parts: string; part: string; mesh: string; out: string }
+/** `rig-parts remesh` flags as its help states them; every value a path the server composed, never a client string. */
+export const remeshArgs = (r: RemeshRequest): string[] => ['remesh', '--rig', r.rig, '--config', r.config, '--parts', r.parts, '--part', r.part, '--mesh', r.mesh, '--out', r.out];
+export interface RemeshDeltaRequest { rig: string; config: string; parts: string; part: string; delta: string; out: string }
+/** `rig-parts remesh … --delta <mesh-edit.json>` (#135): the same flags with `--delta` in place of `--mesh`, as its help states. */
+export const remeshDeltaArgs = (r: RemeshDeltaRequest): string[] => ['remesh', '--rig', r.rig, '--config', r.config, '--parts', r.parts, '--part', r.part, '--delta', r.delta, '--out', r.out];
+export interface CompileRequest { rig: string; motion: string; out: string; pageEdges: 'pot' | 'free'; packShape: 'rect' | 'polygon' }
+/** remesh writes a rig spec (rig.json + motion.json); this is the compile its own gate ran, with the revision's pack flags. */
+export const compileArgs = (r: CompileRequest): string[] => ['build', '--rig', r.rig, '--motion', r.motion, '--out', r.out, '--profile', 'rig-play', '--pack', '--page-edges', r.pageEdges, '--pack-shape', r.packShape];
+
+/** The producer's first named refusal line, verbatim (trimmed): `FAIL  CODE: …`, or a `CODE: …` line, or `refused: …`. */
+export function firstRefusal(lines: readonly string[]): string | null {
+  for (const line of lines) if (/^\s*FAIL\s+[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/.test(line)) return line.trim();
+  for (const line of lines) if (/^\s*[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+:\s/.test(line)) return line.trim();
+  for (const line of lines) if (/^\s*refused:/.test(line)) return line.trim();
+  return null;
+}
+
+export interface ProcessResult { exitCode: number; lines: string[]; stdout: string[]; wallMs: number }
+/**
+ * One child process: `bun <bin> …args` with cwd = the scratch directory, stdout and stderr read line by line (each
+ * line handed to `onLine` as it arrives), the exit code and a wall-clock duration. Nothing is read from a manifest.
+ */
+export async function runTool(bin: string, args: readonly string[], options: { cwd: string; onLine?: (line: string) => void; env?: Record<string, string | undefined> }): Promise<ProcessResult> {
+  const started = performance.now(), lines: string[] = [], stdout: string[] = [];
+  const child = Bun.spawn([process.execPath, bin, ...args], { cwd: options.cwd, stdout: 'pipe', stderr: 'pipe', stdin: 'ignore', env: options.env ?? process.env });
+  const pump = async (stream: ReadableStream<Uint8Array>, own: string[] | null) => {
+    const decoder = new TextDecoder(); let rest = '';
+    const reader = stream.getReader();
+    for (let next = await reader.read(); !next.done; next = await reader.read()) {
+      rest += decoder.decode(next.value, { stream: true });
+      let at: number;
+      while ((at = rest.indexOf('\n')) >= 0) { const line = rest.slice(0, at).replace(/\r$/, ''); rest = rest.slice(at + 1); lines.push(line); own?.push(line); options.onLine?.(line); }
+    }
+    rest += decoder.decode();
+    if (rest) { lines.push(rest); own?.push(rest); options.onLine?.(rest); }
+  };
+  await Promise.all([pump(child.stdout, stdout), pump(child.stderr, null)]);
+  const exitCode = await child.exited;
+  // `lines` is the merged stream in arrival order (what the status area shows); `stdout` keeps the tool's own
+  // report channel apart so a last line is never a stderr line that happened to arrive late.
+  return { exitCode, lines, stdout, wallMs: Math.round(performance.now() - started) };
+}
+
+/** #108: the compiler alone (its readings need no producer op) — beside `@rig-c/parts` when that resolves, else walking up from each start. */
+export const READINGS_COMPILER_NOT_INSTALLED = `READINGS_COMPILER_NOT_INSTALLED: ${COMPILER_PACKAGE} is not installed beside the package, beside ${PRODUCER_PACKAGE} or beside review, and review does not install it — bun add -d ${COMPILER_PACKAGE}`;
+export const readingsCompilerTooOld = (found: string, required: string) => `READINGS_COMPILER_TOO_OLD ${found} ${required}: rigc render's readings (--folds, --pass-through, --seam, --overlaps, --angle-range) need ${COMPILER_PACKAGE} ${required} or later — bun add -d ${COMPILER_PACKAGE}@latest`;
+export function resolveCompiler(starts: readonly string[], since: string, exists: (path: string) => boolean = existsSync): { ok: true; compiler: InstalledTool } | { ok: false; error: string } {
+  const pair = resolveProducer(starts, exists);
+  let compiler: InstalledTool | { error: string } | null = pair.ok ? pair.compiler : null;
+  if (!compiler) { const manifest = findPackage(COMPILER_PACKAGE, starts, exists); compiler = manifest ? readTool(manifest, COMPILER_BIN) : null; }
+  if (!compiler) return { ok: false, error: READINGS_COMPILER_NOT_INSTALLED };
+  if ('error' in compiler) return { ok: false, error: `${READINGS_COMPILER_NOT_INSTALLED} (${compiler.error})` };
+  if (!versionAtLeast(compiler.version, since)) return { ok: false, error: readingsCompilerTooOld(compiler.version || 'unknown', since) };
+  return { ok: true, compiler };
+}
+
+/**
+ * #114: the installed pose producer (`@rig-c/pose`' `rig-pose`), resolved as `@rig-c/parts` is — walking up from the
+ * package, then from review's working directory — and the `rigc` beside it, which gates and poses its retarget and
+ * compiles its scratch motion here. Refused by name when absent; review never installs it.
+ */
+export const POSE_PACKAGE = '@rig-c/pose';
+export const POSE_BIN = 'rig-pose';
+export const RETARGET_PRODUCER_NOT_INSTALLED = `RETARGET_PRODUCER_NOT_INSTALLED: ${POSE_PACKAGE} is not installed beside the package or beside review, and review does not install it — bun add -d ${POSE_PACKAGE}`;
+export const RETARGET_COMPILER_NOT_INSTALLED = `RETARGET_COMPILER_NOT_INSTALLED: ${COMPILER_PACKAGE} is not installed beside ${POSE_PACKAGE}, which gates and poses its retarget with it — reinstall ${POSE_PACKAGE} (bun add -d ${POSE_PACKAGE})`;
+export function resolvePose(starts: readonly string[], exists: (path: string) => boolean = existsSync): ProducerResolution {
+  const manifest = findPackage(POSE_PACKAGE, starts, exists);
+  if (!manifest) return { ok: false, error: RETARGET_PRODUCER_NOT_INSTALLED };
+  const producer = readTool(manifest, POSE_BIN);
+  if ('error' in producer) return { ok: false, error: `${RETARGET_PRODUCER_NOT_INSTALLED} (${producer.error})` };
+  const compilerManifest = findPackage(COMPILER_PACKAGE, [producer.root], exists);
+  if (!compilerManifest) return { ok: false, error: RETARGET_COMPILER_NOT_INSTALLED };
+  const compiler = readTool(compilerManifest, COMPILER_BIN);
+  if ('error' in compiler) return { ok: false, error: `${RETARGET_COMPILER_NOT_INSTALLED} (${compiler.error})` };
+  return { ok: true, producer, compiler };
+}

package/src/readings-run.ts

@@ -0,0 +1,129 @@
+/**
+ * `POST /api/readings` (issue #108): the requested readings run, one `rigc render` each, on the inspected build (the
+ * package's compiled model directory, read only) and on the session's latest scratch build (if any), each into
+ * `<state>/readings/<package hash>/<build>/<reading key>/` — no clock in any name, and an identical reading on the same
+ * build and compiler reuses its stored result. Only the reading's JSON and frames.json are kept; the rendered frames are
+ * removed. Nothing is written into the package (checked again after the run); no path comes from the client.
+ */
+import { createHash } from 'node:crypto';
+import { copyFile, lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { safeFile, type ReviewPackage } from './manifest.ts';
+import { resolveCompiler, runTool, type InstalledTool } from './producer.ts';
+import { environmentSchedule, helpHasEnvironment, parseReadingsRequest, READING_FILE, readingLabel, readingResult, READINGS_SCHEMA, READINGS_SINCE, ReadingsError, renderArgs, type ReadingBuild, type ReadingRequest, type ReadingResult, type ReadingsRequest } from './readings.ts';
+
+const sha256 = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+async function exists(path: string): Promise<boolean> { try { await lstat(path); return true; } catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return false; throw e; } }
+
+export interface ReadingsBuildRun { build: ReadingBuild; id: string; modelHash: string; results: ReadingResult[] }
+export interface ReadingsJob {
+  schema: typeof READINGS_SCHEMA; id: string; status: 'running' | 'done' | 'failed'; error: string | null;
+  request: ReadingsRequest;
+  /** Whether the schedule went to rigc: only when one was asked for and this rigc's `render --help` lists `--environment`. */
+  environment: { requested: boolean; flag: boolean; passed: boolean };
+  compiler: { package: string; version: string };
+  runs: ReadingsBuildRun[];
+}
+export interface ReadingsOptions {
+  stateDir: string; starts: readonly string[]; unchanged: () => Promise<void>;
+  /** The session's latest built scratch build: its id, its build directory and its model hash. */
+  latest: () => { id: string; build: string; modelHash: string } | null;
+}
+export const readingsRoot = (stateDir: string, sourceHash: string) => join(stateDir, 'readings', sourceHash);
+/** Deterministic: the reading, the animation, the schedule passed (or none), the compiler and the build's model bytes. */
+export const readingKey = (r: ReadingRequest, animation: string, schedule: unknown, compiler: string, modelHash: string) => sha256(JSON.stringify([READINGS_SCHEMA, readingLabel(r), animation, schedule, compiler, modelHash]));
+
+/** One reading on one build: reuse its stored result, or run `rigc render` and keep its JSON beside the result. */
+export async function runReading(r: ReadingRequest, animation: string, candidate: string, dir: string, key: string, compiler: InstalledTool, schedule: unknown): Promise<ReadingResult> {
+  const resultFile = join(dir, 'result.json');
+  try { const stored = JSON.parse(await readFile(resultFile, 'utf8')) as { key: string; result: ReadingResult }; if (stored.key === key) return stored.result; } catch { /* not run yet */ }
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  if (schedule) await writeFile(join(dir, 'environment.json'), JSON.stringify(schedule, null, 1) + '\n', { mode: 0o600 });
+  const run = await runTool(compiler.bin, renderArgs(r, animation, { candidate, out: 'render', environment: schedule ? 'environment.json' : null }), { cwd: dir });
+  let json: unknown = null, fps: number | null = null;
+  if (run.exitCode === 0) {
+    try {
+      const frames = JSON.parse(await readFile(join(dir, 'render', 'frames.json'), 'utf8')) as { sets?: { dir: string; animation: string | null; fps: number }[] };
+      const set = frames.sets?.find(s => s.animation === animation);
+      if (set) {
+        fps = set.fps;
+        const file = READING_FILE[r.kind];
+        if (file) { json = JSON.parse(await readFile(join(dir, 'render', set.dir, file), 'utf8')); await copyFile(join(dir, 'render', set.dir, file), join(dir, file)); }
+      }
+      await copyFile(join(dir, 'render', 'frames.json'), join(dir, 'frames.json'));
+    } catch { /* readingResult says what it could not read */ }
+  }
+  const result = readingResult(r, run, json, fps);
+  // The frames and plates are rigc's pictures of the reading, not its result; the JSON is kept.
+  await rm(join(dir, 'render'), { recursive: true, force: true });
+  await writeFile(resultFile, JSON.stringify({ key, result }, null, 1) + '\n', { mode: 0o600 });
+  return result;
+}
+
+export function createReadings(p: ReviewPackage, options: ReadingsOptions) {
+  const jobs = new Map<string, ReadingsJob>(), help = new Map<string, boolean>();
+  let running: string | null = null;
+  const snapshot = (job: ReadingsJob): ReadingsJob => JSON.parse(JSON.stringify(job)) as ReadingsJob;
+  function assertStateOutside(): void {
+    for (const root of [p.root, ...(p.handoff ? [p.handoff.root] : [])]) {
+      const inside = relative(root, options.stateDir);
+      if (inside === '' || !inside.startsWith('..') && !isAbsolute(inside)) throw new ReadingsError('READINGS_STATE_INSIDE_PACKAGE', 'the review state directory is inside the inspected package; set RIG_REVIEW_STATE_DIR outside it');
+    }
+  }
+  /** Whether this rigc's `render --help` lists `--environment`, asked once per compiler. */
+  async function environmentFlag(compiler: InstalledTool): Promise<boolean> {
+    const key = `${compiler.bin}@${compiler.version}`;
+    if (!help.has(key)) { await mkdir(options.stateDir, { recursive: true, mode: 0o700 }); const run = await runTool(compiler.bin, ['render', '--help'], { cwd: options.stateDir }); help.set(key, helpHasEnvironment(run.lines)); }
+    return help.get(key)!;
+  }
+
+  async function execute(job: ReadingsJob, compiler: InstalledTool, builds: { build: ReadingBuild; key: string; candidate: string }[], schedule: unknown): Promise<void> {
+    try {
+      for (const [i, b] of builds.entries()) {
+        const run = job.runs[i]!;
+        for (const r of job.request.readings) {
+          const key = readingKey(r, job.request.animation, schedule, `${compiler.package}@${compiler.version}`, run.modelHash);
+          run.results.push(await runReading(r, job.request.animation, b.candidate, join(readingsRoot(options.stateDir, p.sourceHash), b.key, key), key, compiler, schedule));
+        }
+      }
+      try { await options.unchanged(); } catch { throw new ReadingsError('READINGS_INPUTS_CHANGED', 'the package changed while the readings ran'); }
+      job.status = 'done';
+    } catch (error) { job.status = 'failed'; job.error = error instanceof Error ? error.message : String(error); }
+  }
+
+  /** Refusals come before anything is run; a refusal of the compiler's is an outcome (200), a malformed request a 400. */
+  async function start(input: unknown): Promise<{ status: number; body: unknown }> {
+    const request = parseReadingsRequest(input);
+    assertStateOutside();
+    await options.unchanged();
+    if (!p.manifest.model) throw new ReadingsError('READINGS_NO_MODEL', 'the package names no compiled model; readings run on a compiled build');
+    const resolved = resolveCompiler(options.starts, READINGS_SINCE);
+    if (!resolved.ok) return { status: 200, body: { status: 'refused', error: resolved.error } };
+    const compiler = resolved.compiler;
+    const modelPath = await safeFile(p.root, p.manifest.model), modelHash = sha256(await readFile(modelPath));
+    const latest = options.latest();
+    const flag = await environmentFlag(compiler), passed = !!request.environment && flag, schedule = passed ? environmentSchedule(request.environment!) : null;
+    const id = sha256(JSON.stringify([READINGS_SCHEMA, p.sourceHash, request, modelHash, latest?.id ?? null, `${compiler.package}@${compiler.version}`, passed]));
+    const current = jobs.get(id);
+    if (current && current.status !== 'failed') return { status: current.status === 'running' ? 202 : 200, body: snapshot(current) };
+    if (running) return { status: 200, body: { status: 'refused', error: `READINGS_BUSY: readings ${running} are still running` } };
+    const builds: { build: ReadingBuild; key: string; candidate: string }[] = [{ build: 'inspected', key: `inspected-${modelHash}`, candidate: dirname(modelPath) }];
+    if (latest && await exists(join(latest.build, 'skeleton.json'))) builds.push({ build: 'scratch', key: `scratch-${latest.id}`, candidate: latest.build });
+    const job: ReadingsJob = {
+      schema: READINGS_SCHEMA, id, status: 'running', error: null, request,
+      environment: { requested: !!request.environment, flag, passed },
+      compiler: { package: compiler.package, version: compiler.version },
+      runs: builds.map(b => ({ build: b.build, id: b.build === 'inspected' ? modelHash : latest!.id, modelHash: b.build === 'inspected' ? modelHash : latest!.modelHash, results: [] })),
+    };
+    jobs.set(id, job); running = id;
+    void execute(job, compiler, builds, schedule).finally(() => { if (running === id) running = null; });
+    return { status: 202, body: snapshot(job) };
+  }
+  function read(id: string): ReadingsJob {
+    const job = jobs.get(id);
+    if (!job) throw new ReadingsError('READINGS_NOT_FOUND', id);
+    return snapshot(job);
+  }
+  return { start, read, running: () => running };
+}