@rig-c/review 0.6.0 → 0.7.0

package/src/cut-edits.ts

@@ -0,0 +1,184 @@
+/**
+ * Cuts, patches and limbs (#115): the producer config's `assemble.cuts`, `assemble.patches` and `limbs` as the Setup
+ * Cuts block edits them on the stage. Every coordinate is rig px of the setup pose, y down — the space of `parts.json`
+ * and of the cut polygons and patch boxes (rig-parts AUTHORING §3, `assemble.cuts`: "non-negative integer rig pixels").
+ *
+ *  - a cut's polygon vertex is one anchor at `/assemble/cuts/<i>/polygon/<k>`, a `replace` op naming the cut by `into`;
+ *  - a patch's box is two corner anchors whose edit is one `replace` at `/assemble/patches/<i>/box` naming the patch;
+ *  - a limb segment below a joint has its `range` (`[min, max]` degrees from rest, `min <= 0 <= max`), a `replace` (or
+ *    `add` when the config states none, `remove` to drop it) at `/limbs/<limb>/segments/<k>/range` naming its `part`; its
+ *    joint is the lower bone's origin, which is a `bones` anchor (`src/bone-anchors.ts`) — a joint drag is a bone op;
+ *  - a new cut is `add /assemble/cuts/-` with `{from, into, polygon, draw, overlap}` (no `under`: review paints no image)
+ *    plus `add /regions/<into>` (the coverage rule wants every part a mesh or a region); a new patch is
+ *    `add /assemble/patches/-` with `{name, box, alpha, draw}` plus `add /regions/<name>` (a patch is always a region).
+ *
+ * What only the producer can judge (a polygon point past the rig, two cuts overlapping, a cut taking no pixel, an
+ * `under` no longer the polygon box's size, a name already taken, a range out of order) is the producer's refusal,
+ * shown verbatim. Review refuses before sending only what is not the loader's type: a non-integer or negative point, a
+ * polygon under three points, a range that is not two numbers. Pure: no IO, no DOM.
+ */
+import type { JsonValue, PatchOp } from './config-patch.ts';
+
+export type RigPoint = [number, number];
+export type PatchBox = [number, number, number, number];
+export type CutDraw = 'back' | 'front' | { before: string };
+export interface ConfigCut { index: number; from: string; into: string; polygon: RigPoint[]; draw: CutDraw; overlap: number; under: string | null }
+export interface ConfigPatchEntry { index: number; name: string; box: PatchBox; alpha: string; draw: CutDraw }
+export interface ConfigLimbSegment { limb: string; index: number; part: string; from: string; bone: string; joint: string | null; range: [number, number] | null }
+export interface CutsSource { cuts: ConfigCut[]; patches: ConfigPatchEntry[]; segments: ConfigLimbSegment[]; plan: string[]; skipped: string[] }
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const intPoint = (v: unknown): RigPoint | null => Array.isArray(v) && v.length === 2 && v.every(n => typeof n === 'number' && Number.isFinite(n)) ? [v[0] as number, v[1] as number] : null;
+const draw = (v: unknown): CutDraw | null => v === 'back' || v === 'front' ? v : isObject(v) && typeof v.before === 'string' ? { before: v.before } : null;
+
+/** The config's cuts, patches, limb segments and plan part names as written; an unreadable entry is named in `skipped`. */
+export function cutsSource(config: unknown): CutsSource {
+  const out: CutsSource = { cuts: [], patches: [], segments: [], plan: [], skipped: [] };
+  if (!isObject(config)) return out;
+  const assemble = isObject(config.assemble) ? config.assemble : {};
+  if (Array.isArray(assemble.plan)) for (const row of assemble.plan) if (Array.isArray(row) && typeof row[0] === 'string') out.plan.push(row[0]);
+  if (Array.isArray(assemble.cuts)) assemble.cuts.forEach((q, index) => {
+    const polygon = isObject(q) && Array.isArray(q.polygon) ? q.polygon.map(intPoint) : [];
+    const d = isObject(q) ? draw(q.draw) : null;
+    if (!isObject(q) || typeof q.from !== 'string' || typeof q.into !== 'string' || !d || typeof q.overlap !== 'number' || polygon.length < 3 || polygon.some(p => !p)) { out.skipped.push(`assemble.cuts[${index}] is not {from, into, polygon, draw, overlap}`); return; }
+    out.cuts.push({ index, from: q.from, into: q.into, polygon: polygon as RigPoint[], draw: d, overlap: q.overlap, under: typeof q.under === 'string' ? q.under : null });
+  });
+  if (Array.isArray(assemble.patches)) assemble.patches.forEach((q, index) => {
+    const d = isObject(q) ? draw(q.draw) : null;
+    if (!isObject(q) || typeof q.name !== 'string' || !Array.isArray(q.box) || q.box.length !== 4 || !q.box.every(n => typeof n === 'number' && Number.isFinite(n)) || typeof q.alpha !== 'string' || !d) { out.skipped.push(`assemble.patches[${index}] is not {name, box, alpha, draw}`); return; }
+    out.patches.push({ index, name: q.name, box: [...q.box] as PatchBox, alpha: q.alpha, draw: d });
+  });
+  if (isObject(config.limbs)) for (const [limb, entry] of Object.entries(config.limbs)) {
+    if (!isObject(entry) || !Array.isArray(entry.segments)) { out.skipped.push(`limbs.${limb} has no segments`); continue; }
+    entry.segments.forEach((sg, index) => {
+      if (!isObject(sg) || typeof sg.part !== 'string' || typeof sg.from !== 'string' || typeof sg.bone !== 'string') { out.skipped.push(`limbs.${limb}.segments[${index}] is not {part, from, bone}`); return; }
+      const range = Array.isArray(sg.range) && sg.range.length === 2 && sg.range.every(n => typeof n === 'number' && Number.isFinite(n)) ? [sg.range[0], sg.range[1]] as [number, number] : null;
+      out.segments.push({ limb, index, part: sg.part, from: sg.from, bone: sg.bone, joint: typeof sg.joint === 'string' ? sg.joint : null, range });
+    });
+  }
+  return out;
+}
+
+export class CutEditError extends Error { constructor(readonly code: string, detail: string) { super(`${code}: ${detail}`); } }
+
+/** One pending edit, keyed by its pointer; `value` is the whole new value at that pointer (or `null` to remove a range). */
+export type CutEdit =
+  | { kind: 'vertex'; path: string; name: string; label: string; from: RigPoint; value: RigPoint }
+  | { kind: 'box'; path: string; name: string; label: string; from: PatchBox; value: PatchBox }
+  | { kind: 'range'; path: string; name: string; label: string; from: [number, number] | null; value: [number, number] | null };
+/** A new cut or patch, placed on the stage; it becomes two `add` ops (the entry and its `regions` bone). */
+export type CutAdd =
+  | { kind: 'cut'; from: string; into: string; polygon: RigPoint[]; draw: CutDraw; overlap: number; bone: string }
+  | { kind: 'patch'; name: string; box: PatchBox; alpha: 'silhouette' | 'box'; draw: CutDraw; bone: string };
+
+export const vertexPath = (cut: number, k: number) => `/assemble/cuts/${cut}/polygon/${k}`;
+export const boxPath = (patch: number) => `/assemble/patches/${patch}/box`;
+export const rangePath = (limb: string, k: number) => `/limbs/${limb.replace(/~/g, '~0').replace(/\//g, '~1')}/segments/${k}/range`;
+
+/** A rig px value as the loader takes it: a non-negative integer (`CONFIG_FIELD_TYPE` otherwise). */
+function rigInt(v: number, what: string): number {
+  if (!Number.isInteger(v) || v < 0) throw new CutEditError('CUTS_VALUE_INVALID', `${what} must be a non-negative integer of rig px (the config's polygons and boxes are)`);
+  return v;
+}
+const same = (a: readonly number[] | null, b: readonly number[] | null) => a === b || (!!a && !!b && a.length === b.length && a.every((v, i) => v === b[i]));
+
+/** Set a cut vertex; a value equal to the config's removes the pending edit. */
+export function setVertex(edits: ReadonlyMap<string, CutEdit>, cut: ConfigCut, k: number, value: RigPoint): Map<string, CutEdit> {
+  const from = cut.polygon[k];
+  if (!from) throw new CutEditError('CUTS_VERTEX_UNKNOWN', `${cut.into} has no vertex ${k}`);
+  const v: RigPoint = [rigInt(value[0], `${cut.into} vertex ${k} x`), rigInt(value[1], `${cut.into} vertex ${k} y`)];
+  const next = new Map(edits), path = vertexPath(cut.index, k);
+  if (same(v, from)) next.delete(path); else next.set(path, { kind: 'vertex', path, name: cut.into, label: `${cut.into} vertex ${k}`, from: [...from], value: v });
+  return next;
+}
+/** Set a patch box (`[x0, y0, x1, y1]`, `x1`/`y1` exclusive); a box equal to the config's removes the edit. */
+export function setBox(edits: ReadonlyMap<string, CutEdit>, patch: ConfigPatchEntry, value: PatchBox): Map<string, CutEdit> {
+  const v = value.map((n, i) => rigInt(n, `${patch.name} box[${i}]`)) as PatchBox;
+  if (v[2] <= v[0] || v[3] <= v[1]) throw new CutEditError('CUTS_VALUE_INVALID', `${patch.name} box must have x1 > x0 and y1 > y0`);
+  const next = new Map(edits), path = boxPath(patch.index);
+  if (same(v, patch.box)) next.delete(path); else next.set(path, { kind: 'box', path, name: patch.name, label: `${patch.name} box`, from: [...patch.box] as PatchBox, value: v });
+  return next;
+}
+/** Set (or with null, drop) a segment's range; only a segment below a joint takes one (the loader's `CONFIG_KEY_KNOWN`). */
+export function setRange(edits: ReadonlyMap<string, CutEdit>, segment: ConfigLimbSegment, value: [number, number] | null): Map<string, CutEdit> {
+  if (!segment.joint) throw new CutEditError('CUTS_RANGE_UPPER', `${segment.part} is the upper segment of ${segment.limb}; only a segment below a joint takes a range`);
+  if (value && !value.every(n => typeof n === 'number' && Number.isFinite(n))) throw new CutEditError('CUTS_VALUE_INVALID', `${segment.part} range must be two numbers of degrees`);
+  const next = new Map(edits), path = rangePath(segment.limb, segment.index);
+  if (same(value, segment.range)) next.delete(path); else next.set(path, { kind: 'range', path, name: segment.part, label: `${segment.limb} ${segment.joint} range (${segment.part})`, from: segment.range ? [...segment.range] : null, value: value ? [...value] : null });
+  return next;
+}
+/** Where a vertex stands now: its pending value, else the config's. */
+export const vertexAt = (edits: ReadonlyMap<string, CutEdit>, cut: ConfigCut, k: number): RigPoint => (edits.get(vertexPath(cut.index, k)) as Extract<CutEdit, { kind: 'vertex' }> | undefined)?.value ?? cut.polygon[k]!;
+export const boxAt = (edits: ReadonlyMap<string, CutEdit>, patch: ConfigPatchEntry): PatchBox => (edits.get(boxPath(patch.index)) as Extract<CutEdit, { kind: 'box' }> | undefined)?.value ?? patch.box;
+export const rangeAt = (edits: ReadonlyMap<string, CutEdit>, s: ConfigLimbSegment): [number, number] | null => { const e = edits.get(rangePath(s.limb, s.index)) as Extract<CutEdit, { kind: 'range' }> | undefined; return e ? e.value : s.range; };
+
+/** A drag moves a point by the pointer's delta snapped to whole rig px. */
+export const dragPoint = (from: RigPoint, start: RigPoint, now: RigPoint): RigPoint => [0, 1].map(i => { const d = Math.round(now[i]! - start[i]!); return from[i]! + (d === 0 ? 0 : d); }) as RigPoint;
+
+/**
+ * The pending edits and additions as config patch ops, in order: the edits (each one op at its own pointer, naming its
+ * entry), then each addition's entry and its `regions` bone. A new name is not checked against the config: the
+ * producer's `CONFIG_PART_UNIQUE` says so, verbatim.
+ */
+export function cutOps(edits: ReadonlyMap<string, CutEdit>, adds: readonly CutAdd[], config: unknown): PatchOp[] {
+  const ops: PatchOp[] = [];
+  for (const e of edits.values()) {
+    if (e.kind === 'range') {
+      if (e.value === null) ops.push({ op: 'remove', path: e.path, name: e.name });
+      else ops.push({ op: e.from === null ? 'add' : 'replace', path: e.path, value: [...e.value], name: e.name });
+    } else ops.push({ op: 'replace', path: e.path, value: [...e.value], name: e.name });
+  }
+  const assemble = isObject(config) && isObject(config.assemble) ? config.assemble : {};
+  let cuts = Array.isArray(assemble.cuts) ? assemble.cuts.length : null, patches = Array.isArray(assemble.patches) ? assemble.patches.length : null;
+  let regions = isObject(config) && isObject(config.regions);
+  for (const a of adds) {
+    const list = a.kind === 'cut' ? 'cuts' : 'patches', has = a.kind === 'cut' ? cuts !== null : patches !== null;
+    const entry: JsonValue = a.kind === 'cut'
+      ? { from: a.from, into: a.into, polygon: a.polygon.map(p => [rigInt(p[0], `${a.into} x`), rigInt(p[1], `${a.into} y`)]), draw: a.draw as JsonValue, overlap: rigInt(a.overlap, `${a.into} overlap`) }
+      : { name: a.name, box: a.box.map((n, i) => rigInt(n, `${a.name} box[${i}]`)), alpha: a.alpha, draw: a.draw as JsonValue };
+    if (a.kind === 'cut' && a.polygon.length < 3) throw new CutEditError('CUTS_POLYGON_SHORT', `${a.into} needs at least three points`);
+    ops.push(has ? { op: 'add', path: `/assemble/${list}/-`, value: entry } : { op: 'add', path: `/assemble/${list}`, value: [entry] });
+    if (a.kind === 'cut') cuts = (cuts ?? 0) + 1; else patches = (patches ?? 0) + 1;
+    const name = a.kind === 'cut' ? a.into : a.name;
+    if (!regions) { ops.push({ op: 'add', path: '/regions', value: {} }); regions = true; }
+    ops.push({ op: 'add', path: `/regions/${name.replace(/~/g, '~0').replace(/\//g, '~1')}`, value: a.bone });
+  }
+  return ops;
+}
+
+/**
+ * A segment's range as an arc for the overlay: the joint (the lower bone's origin), the bone's rest direction (rig px,
+ * y down) and the two ends `min`, `max` turned counter-clockwise on screen (rigc's sense), sampled every `step` degrees.
+ */
+export function rangeArc(joint: RigPoint, toward: RigPoint, range: [number, number], radius: number, step = 5): RigPoint[] {
+  const rest = Math.atan2(toward[1] - joint[1], toward[0] - joint[0]);
+  const [lo, hi] = range[0] <= range[1] ? range : [range[1], range[0]];
+  const out: RigPoint[] = [[joint[0], joint[1]]];
+  for (let d = lo; ; d = Math.min(hi, d + step)) {
+    // Counter-clockwise on screen with y down is a negative angle in rig px.
+    const a = rest - (d * Math.PI) / 180;
+    out.push([joint[0] + radius * Math.cos(a), joint[1] + radius * Math.sin(a)]);
+    if (d >= hi) break;
+  }
+  return out;
+}
+
+export const CUTS_DRAFT_SCHEMA = 'rig-review-cuts-draft/1';
+export const cutsDraftText = (edits: ReadonlyMap<string, CutEdit>, adds: readonly CutAdd[]) => JSON.stringify({ schema: CUTS_DRAFT_SCHEMA, edits: [...edits.values()], adds });
+/** Edits back from a draft, kept only where the pointer still names the same entry with the same config value. */
+export function cutsDraft(text: string, source: CutsSource): { edits: Map<string, CutEdit>; adds: CutAdd[] } {
+  const empty = { edits: new Map<string, CutEdit>(), adds: [] as CutAdd[] };
+  let doc: unknown;
+  try { doc = JSON.parse(text); } catch { return empty; }
+  if (!isObject(doc) || doc.schema !== CUTS_DRAFT_SCHEMA || !Array.isArray(doc.edits)) return empty;
+  let edits = new Map<string, CutEdit>();
+  for (const e of doc.edits as CutEdit[]) {
+    try {
+      if (e.kind === 'vertex') { const m = /^\/assemble\/cuts\/(\d+)\/polygon\/(\d+)$/.exec(e.path); const cut = m ? source.cuts.find(c => c.index === Number(m[1])) : undefined; if (cut && cut.into === e.name && same(cut.polygon[Number(m![2])] ?? null, e.from)) edits = setVertex(edits, cut, Number(m![2]), e.value); }
+      else if (e.kind === 'box') { const patch = source.patches.find(q => boxPath(q.index) === e.path); if (patch && patch.name === e.name && same(patch.box, e.from)) edits = setBox(edits, patch, e.value); }
+      else if (e.kind === 'range') { const s = source.segments.find(g => rangePath(g.limb, g.index) === e.path); if (s && s.part === e.name && same(s.range, e.from)) edits = setRange(edits, s, e.value); }
+    } catch { /* a draft value the editor would refuse is dropped */ }
+  }
+  const adds = Array.isArray(doc.adds) ? (doc.adds as CutAdd[]).filter(a => isObject(a) && (a.kind === 'cut' || a.kind === 'patch')) : [];
+  return { edits, adds };
+}

package/src/environment.ts

@@ -51,7 +51,10 @@ export interface WindModel {
  setBase(value:number):void;setGustPeak(value:number):void;setGustDuration(value:number):void;
  setBreeze(value:boolean):void;setRepeat(value:boolean):void;triggerGust():void;
  advance(dt:number):WindReading;
+ /** The whole standing state, clock and active pulse included (#103: an Apply's reload resumes the same world). */
+ state():WindState;resume(value:WindState):void;
 }
+export interface WindState {snapshot:WindSnapshot;time:number;gustStart:number|null;gustDirection:number;nextGust:number|null;activeGustPeak:number;activeGustDuration:number}
 export const defaultWindSnapshot=():WindSnapshot=>({version:1,base:0,breeze:false,repeat:false,gustPeak:GUST_PEAK,gustDuration:GUST_DURATION});
 
 export function createWindModel():WindModel {
@@ -94,6 +97,11 @@ export function createWindModel():WindModel {
    if(repeat){if(read().gusting)nextGust=gustStart!+gustPeriod(activeGustDuration);else start(time);}
    else nextGust=null; // Finish the active pulse before returning to base.
   },
+  state:()=>({snapshot:{version:1,base,breeze,repeat,gustPeak,gustDuration},time,gustStart,gustDirection,nextGust,activeGustPeak,activeGustDuration}),
+  resume(value){
+   const saved=structuredClone(value);this.restore(saved.snapshot);
+   time=saved.time;gustStart=saved.gustStart;gustDirection=saved.gustDirection;nextGust=saved.nextGust;activeGustPeak=saved.activeGustPeak;activeGustDuration=saved.activeGustDuration;
+  },
   advance(dt){
    if(!Number.isFinite(dt)||dt<0||!Number.isFinite(time+dt))throw new RangeError('wind dt must be finite, non-negative and keep a finite clock');
    time+=dt;
@@ -157,14 +165,19 @@ export function physicsConstraints(document:unknown):PhysicsConstraints {
  return {available:true,rows};
 }
 
+/** The reviewed model document, its bytes hash-checked against the reviewed identity first. */
+export async function loadModelDocument(url:string,sha256:string,fetcher:typeof fetch=fetch):Promise<{ok:true;document:unknown}|{ok:false;reason:string}> {
+ const response=await fetcher(url);if(!response.ok)return {ok:false,reason:`model request failed (${response.status})`};
+ const bytes=await response.arrayBuffer();if(bytes.byteLength>128*1024*1024)return {ok:false,reason:'model exceeds 128 MiB'};
+ const hash=[...new Uint8Array(await crypto.subtle.digest('SHA-256',bytes))].map(v=>v.toString(16).padStart(2,'0')).join('');
+ if(hash!==sha256)return {ok:false,reason:'model bytes differ from reviewed SHA-256'};
+ try{return {ok:true,document:JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes))};}
+ catch(error){return {ok:false,reason:error instanceof Error?error.message:String(error)};}
+}
 /** Reads the reviewed model bytes (hash-checked against the reviewed identity) and lists its physics constraints. */
 export async function loadPhysicsConstraints(url:string,sha256:string,fetcher:typeof fetch=fetch):Promise<PhysicsConstraints> {
- const response=await fetcher(url);if(!response.ok)return {available:false,reason:`PHYSICS_CONSTRAINTS_UNAVAILABLE: model request failed (${response.status})`};
- const bytes=await response.arrayBuffer();if(bytes.byteLength>128*1024*1024)return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: model exceeds 128 MiB'};
- const hash=[...new Uint8Array(await crypto.subtle.digest('SHA-256',bytes))].map(v=>v.toString(16).padStart(2,'0')).join('');
- if(hash!==sha256)return {available:false,reason:'PHYSICS_CONSTRAINTS_UNAVAILABLE: model bytes differ from reviewed SHA-256'};
- try{return physicsConstraints(JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(bytes)));}
- catch(error){return {available:false,reason:`PHYSICS_CONSTRAINTS_UNAVAILABLE: ${error instanceof Error?error.message:String(error)}`};}
+ const loaded=await loadModelDocument(url,sha256,fetcher);
+ return loaded.ok?physicsConstraints(loaded.document):{available:false,reason:`PHYSICS_CONSTRAINTS_UNAVAILABLE: ${loaded.reason}`};
 }
 
 /** What a feedback record keeps of the environment it was written under. */

package/src/feedback-export.ts

@@ -5,6 +5,8 @@ import type { CompareSession } from './compare-session.ts';
 import type { FeedbackHistory, HistoryRetrieval } from './session-history.ts';
 import type { ReferenceBinding } from './reference.ts';
 import { environmentSummary, parseEnvironmentContext } from './environment.ts';
+import { appliedSummary } from './applied-context.ts';
+import { requirementsSummaryLine } from './requirements.ts';
 type Category = Feedback['category'];
 type Side = 'single' | 'a' | 'b';
 type ParsedFeedbackSession = FeedbackHistory<ReviewSession | CompareSession>;
@@ -162,6 +164,18 @@ function environmentLine(context: Json | undefined): string[] {
   try { const value = parseEnvironmentContext(context.environment); return [`- Environment: ${value === null ? 'no compiled model drawn' : feedbackMarkdownText(environmentSummary(value))}`]; }
   catch { return []; }
 }
+/** "Applied: patch … · check PASS": the build the note was written on, when the record carries a valid applied state. */
+function appliedLine(context: Json | undefined): string[] {
+  if (context === undefined || context === null || typeof context !== 'object' || Array.isArray(context) || !('applied' in context)) return [];
+  const text = appliedSummary(context.applied);
+  return text === null ? [] : [`- Applied: ${feedbackMarkdownText(text)}`];
+}
+/** "Requirements: 3 declared · requirements file sha256 … · requirements: …": the declared requirements the note carries (#113). */
+function requirementsLine(context: Json | undefined): string[] {
+  if (context === undefined || context === null || typeof context !== 'object' || Array.isArray(context) || !('requirements' in context)) return [];
+  const text = requirementsSummaryLine(context.requirements);
+  return text === null ? [] : [`- Requirements: ${feedbackMarkdownText(text)}`];
+}
 /** Local issue-ready text only. No issue creation, clock inference or source IO. */
 export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
   const model = groupFeedbackIssues(input), md = feedbackMarkdownText;
@@ -193,7 +207,9 @@ export function formatFeedbackIssues(input: ParsedFeedbackSession): string {
           `- Inclusive frames: ${item.frameStart}–${item.frameEnd}`,
           `- Side: ${item.side}`,
           `- Summary: ${md(item.summary)}`,
-          ...environmentLine(item.context), '',
+          ...environmentLine(item.context),
+          ...appliedLine(item.context),
+          ...requirementsLine(item.context), '',
           'Selected build identity:', '', jsonBlock(item.selectedSource));
         if (model.pairedBinding) lines.push('', 'Paired comparison binding:', '', jsonBlock(model.pairedBinding));
         if (item.warnings.length) lines.push('', 'Validation warnings (record retained):', '', jsonBlock(item.warnings));

package/src/front.ts

@@ -55,6 +55,17 @@ export function frontRoute(mode:'single'|'compare',method:string,path:string):Ro
  const reads=mode==='single'?['/api/review','/review-reference']:['/api/compare','/api/compare/reference-frames','/compare-reference'];
  if(reads.includes(path))return read?get:null;
  if((mode==='single'?/^\/assets\/[^/]/:/^\/compare-assets\/(a|b)\/[^/]/).test(path))return read?get:null;
+ // Apply · Rebuild (single only): status, one typed request, a job's status and its served scratch build.
+ if(mode==='single'&&path==='/api/rebuild')return read?get:method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&(/^\/api\/rebuild\/[a-f0-9]{64}$/.test(path)||/^\/rebuild\/[a-f0-9]{64}\/[^/]/.test(path)))return read?get:null;
+ // Bones check (#109, single only): one typed request {ops, configHash}, answered in the response.
+ if(mode==='single'&&path==='/api/bones-check')return method==='POST'?{mutation:true,limit:64*1024,timeoutMs:60000,control:false}:null;
+ // Readings (#108, single only): one typed request, then its job's status.
+ if(mode==='single'&&path==='/api/readings')return method==='POST'?{mutation:true,limit:16*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&/^\/api\/readings\/[a-f0-9]{64}$/.test(path))return read?get:null;
+ // Declared requirements (#113, single only): the stage's catalog, one typed request, then its job's status.
+ if(mode==='single'&&path==='/api/requirements')return read?get:method==='POST'?{mutation:true,limit:64*1024,timeoutMs:30000,control:false}:null;
+ if(mode==='single'&&/^\/api\/requirements\/[a-f0-9]{64}$/.test(path))return read?get:null;
  return null;
 }
 async function boundedBody(req:Request,limit:number,timeoutMs=10000):Promise<ArrayBuffer>{

package/src/handoff.ts

@@ -0,0 +1,208 @@
+/**
+ * Producer handoff (#101): which producer config, parts and inspected rig the package was built from, so an Apply can
+ * rebuild through the installed producer and the AI receiving the review can rebuild exactly that state.
+ *
+ * Declared first — `rig-review open <dir> --config <path> …`, else the `producer` block in review.json — then a fixed
+ * discovery order, never a search: `config.json`, then `rig/config.json` inside the opened folder, and as the last step
+ * `../config.json` beside an opened `out/`. That last one sits outside the opened folder, so the record names it
+ * `discovered` with `outside: true`, its path and its hash. Every path is literal and must stay inside its root (the
+ * package root; for the `../config.json` step, the folder that holds `out/`); a symlink that leaves it is refused by name.
+ * The record (paths relative to the package root, hashes, how it was found) is part of `reviewedSource`, so changing a
+ * handoff file's bytes starts a new pending session.
+ */
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+
+export const HANDOFF_SCHEMA = 'rig-review-handoff/1';
+/** The fixed discovery order, as the refusal names it. */
+export const DISCOVERY_PLACES = ['config.json', 'rig/config.json', '../config.json (beside an opened out/)'] as const;
+export const HANDOFF_DECLARATION = 'rig-review open <dir> --config <path> [--parts <dir>] or the review.json "producer" block';
+export const MODELING_INPUT_UNAVAILABLE = `MODELING_INPUT_UNAVAILABLE: config.json — looked at ${DISCOVERY_PLACES.join(', ')}; declare it with ${HANDOFF_DECLARATION}`;
+/** Files the producer reads by the config's own naming, resolved against the config's directory (rig-parts `relativeConfigPaths`). */
+export const CONFIG_NAMED_FILES = [['motion', 'animations_from'], ['generation', 'control', 'skeleton']] as const;
+/** What `rig-parts rig` writes into its --out and remesh reads from --rig: the rig spec, its motion, the mesh report and the part images. */
+export const RIG_FILES = ['rig.json', 'motion.json', 'mesh_report.json'] as const;
+const MAX_LISTED = 4096;
+
+export interface HandoffDeclaration { config: string; parts?: string; source?: string; full?: string; head?: string }
+export type HandoffFlags = HandoffDeclaration;
+export const HANDOFF_FLAGS = ['config', 'parts', 'source', 'full', 'head'] as const;
+export interface HandoffFile { path: string; sha256: string }
+/** The identity record: paths relative to the package root (`../` only for the discovered parent config), every hashed file. */
+export interface HandoffRecord {
+  schema: typeof HANDOFF_SCHEMA;
+  how: 'declared' | 'discovered';
+  via: 'open --config' | 'review.json producer' | 'discovery';
+  outside: boolean;
+  config: HandoffFile;
+  parts: string | null; rig: string | null; source: HandoffFile | null; full: string | null; head: string | null;
+  files: HandoffFile[];
+  missing: string[];
+}
+/** The record plus the absolute paths the producer is run with (never served, never in the identity). */
+/** `source` (#109): the declared source painting's absolute path, which `propose --from-config` reads; null when none was declared. */
+/** `full` / `head` (#115): the declared See-through runs' absolute paths, which `rig-parts build` reads; null when none was declared. */
+export interface Handoff { record: HandoffRecord; config: string; parts: string | null; rig: string | null; root: string; flags?: HandoffFlags; source?: string | null; full?: string | null; head?: string | null }
+
+export class HandoffError extends Error {
+  constructor(readonly code: string, readonly field: string, readonly detail: string) { super(`${code} ${field}: ${detail}`); }
+}
+const sha256 = (bytes: Uint8Array | string) => createHash('sha256').update(bytes).digest('hex');
+const inside = (base: string, path: string, allowSelf = false) => { const rel = relative(base, path); return rel === '' ? allowSelf : rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel); };
+const code = (e: unknown) => (e as NodeJS.ErrnoException).code ?? '';
+async function exists(path: string): Promise<boolean> { try { await lstat(path); return true; } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ENOTDIR') return false; throw e; } }
+
+/**
+ * One handoff path: it must exist, its canonical location must stay inside `base`, and it must be the expected kind.
+ * `lexicalInside` says whether the path as written was inside the root, so a canonical escape is named a symlink escape.
+ */
+async function contained(base: string, path: string, field: string, kind: 'file' | 'dir', lexicalInside: boolean): Promise<string> {
+  if (!(await exists(path))) throw new HandoffError('HANDOFF_INPUT_MISSING', field, `${path} does not exist`);
+  let real: string;
+  try { real = await realpath(path); } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ELOOP') throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', field, `${path} is a dangling or looping symlink`); throw e; }
+  if (!inside(base, real, kind === 'dir')) {
+    if (lexicalInside) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', field, `${path} resolves outside ${base} (symlinks may not escape)`);
+    throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${path} is outside ${base}`);
+  }
+  const info = await stat(real);
+  if (kind === 'file' ? !info.isFile() : !info.isDirectory()) throw new HandoffError('HANDOFF_INPUT_INVALID', field, `${path} is not a ${kind === 'file' ? 'regular file' : 'directory'}`);
+  return real;
+}
+/** A CLI path: written relative to the working directory or absolute; canonical inside the package root. */
+async function flagPath(root: string, value: string, field: string, kind: 'file' | 'dir'): Promise<string> {
+  const lexical = resolve(value);
+  // The parent chain is canonicalized so a platform alias (/tmp → /private/tmp) is not taken for an escape; the last
+  // component is left as written so a symlink there is named as one.
+  let parent: string;
+  try { parent = await realpath(dirname(lexical)); } catch (e) { if (code(e) === 'ENOENT' || code(e) === 'ENOTDIR') throw new HandoffError('HANDOFF_INPUT_MISSING', field, `${value} does not exist`); throw e; }
+  const written = join(parent, basename(lexical));
+  return contained(root, written, field, kind, inside(root, written, kind === 'dir'));
+}
+/** A review.json `producer` path: literal, portable, relative to the package root. */
+async function blockPath(root: string, value: unknown, field: string, kind: 'file' | 'dir'): Promise<string> {
+  if (typeof value !== 'string' || !value) throw new HandoffError('HANDOFF_PATH_INVALID', field, 'expected a nonempty literal relative path');
+  if (isAbsolute(value) || /^[a-zA-Z]:/.test(value) || value.split('/').includes('..')) throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${value} leaves the package root (absolute or ..)`);
+  if (/[:\\%?#\x00-\x1f]/.test(value) || value.split('/').some(s => !s || s === '.') || posix.normalize(value) !== value) throw new HandoffError('HANDOFF_PATH_INVALID', field, `${value} is not a literal portable relative path`);
+  return contained(root, join(root, value), field, kind, true);
+}
+
+/** `producer: {config, parts?, source?, full?, head?}` — strings only, no other key. Paths are checked at load. */
+export function parseHandoffDeclaration(value: unknown): HandoffDeclaration | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HandoffError('HANDOFF_PATH_INVALID', 'producer', 'expected an object {config, parts?, source?, full?, head?}');
+  const v = value as Record<string, unknown>;
+  for (const key of Object.keys(v)) if (!(HANDOFF_FLAGS as readonly string[]).includes(key)) throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'unknown key; expected config, parts, source, full, head');
+  if (typeof v.config !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', 'producer.config', 'required: the producer config path');
+  const out: HandoffDeclaration = { config: v.config };
+  for (const key of ['parts', 'source', 'full', 'head'] as const) if (v[key] !== undefined) { if (typeof v[key] !== 'string') throw new HandoffError('HANDOFF_PATH_INVALID', `producer.${key}`, 'expected a string path'); out[key] = v[key] as string; }
+  return out;
+}
+/** `--source` and `--full` travel together, `--head` only with them, and everything else only with `--config`. */
+export function checkHandoffFlags(flags: Partial<HandoffFlags>): string | null {
+  const present = HANDOFF_FLAGS.filter(f => flags[f] !== undefined);
+  if (!present.length) return null;
+  if (flags.config === undefined) return `--${present[0]}: requires --config <path>`;
+  if ((flags.source === undefined) !== (flags.full === undefined)) return `--${flags.source === undefined ? 'full' : 'source'}: --source <png> and --full <dir> are given together`;
+  if (flags.head !== undefined && flags.full === undefined) return '--head: requires --source <png> --full <dir>';
+  return null;
+}
+
+async function hashFile(path: string): Promise<string> { return sha256(await readFile(path)); }
+/** Regular files directly in `dir` (a fixed directory, not a search); each must stay inside `base`. */
+async function listed(base: string, dir: string, field: string): Promise<string[]> {
+  const entries = (await readdir(dir, { withFileTypes: true })).filter(e => !e.isDirectory()).map(e => e.name).sort();
+  if (entries.length > MAX_LISTED) throw new HandoffError('HANDOFF_INPUT_INVALID', field, `${dir} holds more than ${MAX_LISTED} files`);
+  const out: string[] = [];
+  for (const name of entries) { const real = await contained(base, join(dir, name), `${field}/${name}`, 'file', true).catch(e => { if (e instanceof HandoffError && e.code === 'HANDOFF_INPUT_INVALID') return null; throw e; }); if (real) out.push(real); }
+  return out;
+}
+
+/** Hash every handoff file and build the record. `root` is the package root (display paths are relative to it). */
+async function record(root: string, base: string, how: HandoffRecord['how'], via: HandoffRecord['via'], config: string, partsPath: string | null, extra: { source?: string; full?: string; head?: string }, partsDeclared: boolean): Promise<Handoff> {
+  const show = (path: string) => relative(root, path).split(sep).join('/') || '.';
+  const files = new Map<string, string>(), missing: string[] = [];
+  const add = async (path: string) => { files.set(show(path), await hashFile(path)); };
+  await add(config);
+  // Files the config names that the producer reads, resolved against the config's own directory.
+  let parsed: unknown = null;
+  try { parsed = JSON.parse(await readFile(config, 'utf8')); } catch { /* the producer refuses an unreadable config by name */ }
+  for (const keys of CONFIG_NAMED_FILES) {
+    let value: unknown = parsed;
+    for (const k of keys) value = value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>)[k] : undefined;
+    if (typeof value !== 'string' || !value) continue;
+    const field = `config ${keys.join('.')}`, lexical = resolve(dirname(config), value);
+    if (!inside(base, lexical)) throw new HandoffError('HANDOFF_PATH_OUTSIDE_ROOT', field, `${value} resolves outside ${base}`);
+    if (!(await exists(lexical))) { missing.push(`${keys.join('.')} ${show(lexical)}`); continue; }
+    await add(await contained(base, lexical, field, 'file', true));
+  }
+  let parts: string | null = null, rig: string | null = null;
+  if (partsPath && (partsDeclared || await exists(partsPath))) {
+    parts = await contained(base, partsPath, partsDeclared ? '--parts' : 'parts', 'dir', true);
+    const partsJson = join(parts, 'parts.json');
+    if (await exists(partsJson)) await add(await contained(base, partsJson, 'parts.json', 'file', true)); else missing.push(`parts.json ${show(partsJson)}`);
+    if (await exists(join(parts, 'parts'))) for (const file of await listed(base, await contained(base, join(parts, 'parts'), 'parts/', 'dir', true), 'parts')) await add(file);
+    const rigDir = join(parts, 'rig');
+    if (await exists(rigDir)) {
+      rig = await contained(base, rigDir, 'rig', 'dir', true);
+      for (const name of RIG_FILES) if (!(await exists(join(rig, name)))) missing.push(`rig ${show(join(rig, name))}`);
+      // Every file remesh carries over: the rig directory's regular files (rig.json, motion.json, mesh_report.json, sets.json, …) and images/.
+      for (const file of await listed(base, rig, 'rig')) await add(file);
+      if (await exists(join(rig, 'images'))) for (const file of await listed(base, await contained(base, join(rig, 'images'), 'rig/images', 'dir', true), 'rig/images')) await add(file);
+    } else missing.push(`rig ${show(rigDir)}`);
+  } else missing.push(`parts ${partsPath ? show(partsPath) : '(none)'}`);
+  let source: HandoffFile | null = null;
+  if (extra.source) { await add(extra.source); source = { path: show(extra.source), sha256: files.get(show(extra.source))! }; }
+  for (const dir of [extra.full, extra.head]) if (dir) for (const file of await listed(base, dir, show(dir))) await add(file);
+  const sorted = [...files].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([path, hash]) => ({ path, sha256: hash }));
+  return {
+    record: { schema: HANDOFF_SCHEMA, how, via, outside: !inside(root, config), config: { path: show(config), sha256: files.get(show(config))! }, parts: parts ? show(parts) : null, rig: rig ? show(rig) : null, source, full: extra.full ? show(extra.full) : null, head: extra.head ? show(extra.head) : null, files: sorted, missing },
+    config, parts, rig, root: base, source: extra.source ?? null, full: extra.full ?? null, head: extra.head ?? null,
+  };
+}
+
+/**
+ * The one handoff lookup (used by load, identity and `/api/rebuild`): CLI flags, else the review.json block, else the
+ * fixed discovery order. `root` is the canonical package root (the opened folder). A declared path that is missing,
+ * outside its root or a symlink escape is refused by name; nothing found is `{handoff: null}` with the refusal line.
+ */
+export async function resolveHandoff(root: string, declared: HandoffDeclaration | undefined, flags: HandoffFlags | undefined): Promise<{ handoff: Handoff | null; reason: string | null }> {
+  if (flags) {
+    const problem = checkHandoffFlags(flags);
+    if (problem) throw new HandoffError('HANDOFF_FLAGS_INVALID', problem.split(':')[0]!, problem);
+    const config = await flagPath(root, flags.config, '--config', 'file');
+    const parts = flags.parts !== undefined ? await flagPath(root, flags.parts, '--parts', 'dir') : join(dirname(config), 'out');
+    const source = flags.source !== undefined ? await flagPath(root, flags.source, '--source', 'file') : undefined;
+    const full = flags.full !== undefined ? await flagPath(root, flags.full, '--full', 'dir') : undefined;
+    const head = flags.head !== undefined ? await flagPath(root, flags.head, '--head', 'dir') : undefined;
+    const handoff = await record(root, root, 'declared', 'open --config', config, parts, { source, full, head }, flags.parts !== undefined);
+    // Canonical absolute flags: the background worker and later reloads read exactly these.
+    handoff.flags = { config, ...(flags.parts !== undefined ? { parts } : {}), ...(source ? { source } : {}), ...(full ? { full } : {}), ...(head ? { head } : {}) };
+    return { handoff, reason: null };
+  }
+  if (declared) {
+    const config = await blockPath(root, declared.config, 'producer.config', 'file');
+    const parts = declared.parts !== undefined ? await blockPath(root, declared.parts, 'producer.parts', 'dir') : join(dirname(config), 'out');
+    const source = declared.source !== undefined ? await blockPath(root, declared.source, 'producer.source', 'file') : undefined;
+    const full = declared.full !== undefined ? await blockPath(root, declared.full, 'producer.full', 'dir') : undefined;
+    const head = declared.head !== undefined ? await blockPath(root, declared.head, 'producer.head', 'dir') : undefined;
+    if ((source === undefined) !== (full === undefined) || (head !== undefined && full === undefined)) throw new HandoffError('HANDOFF_FLAGS_INVALID', 'producer', 'source and full are given together, head only with them');
+    return { handoff: await record(root, root, 'declared', 'review.json producer', config, parts, { source, full, head }, declared.parts !== undefined), reason: null };
+  }
+  for (const name of ['config.json', 'rig/config.json']) {
+    const path = join(root, name);
+    if (!(await exists(path))) continue;
+    const config = await contained(root, path, name, 'file', true);
+    return { handoff: await record(root, root, 'discovered', 'discovery', config, join(dirname(path), 'out'), {}, false), reason: null };
+  }
+  // The last step: an opened `out/` whose config sits beside it, one level up. Outside the folder, so named.
+  if (basename(root) === 'out') {
+    const parent = dirname(root), path = join(parent, 'config.json');
+    if (await exists(path)) {
+      const config = await contained(parent, path, '../config.json', 'file', true);
+      if (config !== path) throw new HandoffError('HANDOFF_SYMLINK_ESCAPE', '../config.json', `${path} is a symlink; only the file beside out/ is discovered`);
+      return { handoff: await record(root, parent, 'discovered', 'discovery', config, root, {}, false), reason: null };
+    }
+  }
+  return { handoff: null, reason: MODELING_INPUT_UNAVAILABLE };
+}