@rig-c/pose 0.29.1 → 0.30.0

package/README.md

@@ -147,7 +147,10 @@ and what the run cannot decide for you it lists:
 - `BODY` — per-frame body yaw read from the camera-normalised shoulder width (`r_shoulder + l_shoulder`) and hip width (`r_hip + l_hip`) projected perpendicular to the trunk against the sequence's standing width (`yaw ≈ acos(w / w_standing)`, [#173](https://github.com/rig-c/pose/issues/173)): its overall and opening (`frames 0–47`) range, every span with `|yaw| ≥ 45°`, and, when `body.yaw` or `body.sets` is declared in the map, its knee-mapped dial keys and every yaw-switched set's entered spans, swap count, and any `hides` slot keyed by another track, written as `body` in `--report`.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `frames`, `duration`, `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `posture`, `folds`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `legScale`, `pivot`, `feet` (`planted`, `legLength`, `supports`, `jumps`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `inputs` (consumed rig spec, map and pose files, each with invocation-relative `path` and exact-byte `sha256`; a folder rig resolves to its actual rig.json; these three identities do not claim to bind optional base motion, sets or images), `frames`, `duration`, `frameTimes` (the exact motion-key time for each pose frame; never FPS inferred from duration), `render` (the separate renderer sampling domain, `{ fps, frames }` from frame-set metadata, or `null` when not measured), `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `posture`, `folds`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `legScale`, `pivot`, `feet` (`planted`, `legLength`, `supports`, `jumps`, `jumpEvents`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths), `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+
+Report event objects with a pose `frame` or inclusive `frames` also carry exact `t` or `times` from `frameTimes`; existing `seconds` remain span lengths, with additive `spanSeconds`. Holds preserve their frame-index `from`/`to`. Existing scan joint/chain identities remain beside map-derived `bone` (a unique mapped target) or `bones` (all actual mapped targets); no joint-name heuristic chooses a target. `feet.jumps` stays an array of original frame pairs; `feet.jumpEvents` adds matching `{ frames, times }` objects. Fold and uncovered rows preserve their discrete `times` and gaps, declare `domain: "render"`, and use the separate root `render` domain, never fabricated nearest pose-frame indices. The run hashes map/pose from the exact buffers passed to their readers, snapshots the resolved rig file before its gate, and rechecks all three before user-output writes. The writer validates coordinates before output writes and never changes motion keys. The switch diagnostic `moved.frame` is a selected-to-keyed pair with signed `frames`/`seconds` displacement; it is preserved as diagnostic data, not reinterpreted as an inclusive interval. An explicitly supplied uniform writer clock requires both positive `fps` and seconds offset `frame0`; canonical pose input does not yet declare FPS, so the retarget producer always writes exact `frameTimes`.
+
 
 | field | each entry |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/report.ts

@@ -0,0 +1,88 @@
+/** Add report coordinates without touching the retarget or any source value. */
+import type { JointMap } from './map.ts';
+import { isObject, Problems, Refusal } from './problems.ts';
+
+export type ReportClock={frameTimes:readonly number[]}|{fps:number;frame0:number;frames:number};
+export interface RenderDomain {fps:number;frames:number}
+export interface ReportInput {path:string;sha256:string}
+export interface ReportInputs {rig:ReportInput;map:ReportInput;pose:ReportInput}
+function fail(field:string,text:string):never {throw new Refusal([{code:'REPORT_TIMEBASE',text:`${field}: ${text}`}]);}
+function finite(value:unknown,field:string):number {if(typeof value!=='number'||!Number.isFinite(value)||value<0)return fail(field,`found ${String(value)}; expected finite seconds >= 0`);return value;}
+function integer(value:unknown,field:string):number {const n=finite(value,field);if(!Number.isSafeInteger(n))fail(field,`found ${n}; expected nonnegative safe integer`);return n;}
+export function reportFrameTimes(clock:ReportClock):number[] {
+  if('frameTimes' in clock){
+    if(!Array.isArray(clock.frameTimes))fail('frameTimes','expected an explicit array');
+    const values=clock.frameTimes.map((time,i)=>finite(time,`frameTimes[${i}]`));
+    if(!values.length)fail('frameTimes','expected at least one explicit frame');
+    for(let i=1;i<values.length;i++)if(values[i]!<=values[i-1]!)fail(`frameTimes[${i}]`,`found ${values[i]}; must follow ${values[i-1]}`);return values;
+  }
+  const fps=finite(clock.fps,'fps');if(fps===0)fail('fps','expected positive explicit rate');const frame0=finite(clock.frame0,'frame0'),count=integer(clock.frames,'frames');
+  if(count===0)fail('frames','expected at least one frame');const times=Array.from({length:count},(_,i)=>frame0+i/fps);
+  for(let i=0;i<times.length;i++){finite(times[i],`frame ${i}`);if(i>0&&times[i]!<=times[i-1]!)fail(`frame ${i}`,'uniform clock cannot represent distinct frame samples');}return times;
+}
+export function reportRenderDomain(input:unknown,animation:string):RenderDomain {
+  if(!isObject(input)||!Array.isArray(input.sets))fail('render.sets','expected renderer frame-set metadata');
+  const set=input.sets.find((value:unknown)=>isObject(value)&&value.animation===animation);
+  if(!isObject(set))fail('render.animation',`missing ${JSON.stringify(animation)} frame-set metadata`);
+  const fps=finite(set.fps,'render.fps'),frames=integer(set.sampled,'render.frames');if(fps===0||frames===0)fail('render','expected positive declared fps and sampled frame count');return {fps,frames};
+}
+function clone(value:unknown):unknown {if(Array.isArray(value))return value.map(clone);if(isObject(value))return Object.fromEntries(Object.entries(value).map(([key,item])=>[key,clone(item)]));return value;}
+
+export function enrichReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null=null,inputs?:ReportInputs):Record<string,unknown> {
+  const times=reportFrameTimes(clock),report=clone(input) as Record<string,unknown>;
+  if(render!==null){const fps=finite(render.fps,'render.fps'),frames=integer(render.frames,'render.frames');if(fps===0||frames===0)fail('render','expected positive declared fps and sampled frame count');}
+  if(report.frames!==times.length)fail('frames',`report has ${String(report.frames)}, clock has ${times.length}`);
+  const problems=new Problems();
+  const time=(frame:unknown,where:string):number=>{const n=integer(frame,where);if(n>=times.length)fail(where,`frame ${n} outside ${times.length} declared frames`);return times[n]!;};
+  const add=(row:Record<string,unknown>,key:string,value:unknown,where:string)=>{
+    if(row[key]!==undefined&&JSON.stringify(row[key])!==JSON.stringify(value))problems.add('REPORT_COORDINATE',`${where}.${key}: supplied ${JSON.stringify(row[key])}, expected ${JSON.stringify(value)}`);
+    else row[key]=value;
+  };
+  // A joint can influence several mapped segments. Preserve all actual matches;
+  // only a unique match may occupy the singular bone field.
+  const bonesFor=(joint:string)=>{const bones=new Set<string>();if(map.translate?.joint===joint)bones.add(map.translate.bone);for(const chain of map.chains)for(let i=0;i<chain.bones.length;i++)if(chain.joints[i]===joint||chain.joints[i+1]===joint)bones.add(chain.bones[i]!);return [...bones];};
+  const pair=(value:unknown,where:string):[number,number]=>{if(!Array.isArray(value)||value.length!==2)fail(where,'expected inclusive [first,last] frame pair');const first=integer(value[0],where+'[0]'),last=integer(value[1],where+'[1]');if(last<first)fail(where,`found [${first},${last}]; inclusive last must be >= first`);return [first,last];};
+  const poseEvent=(where:string)=>/^report\.(?:holds|short|endOn|bends|flips|turns|range|artRange|raised|byHip|landings|shear|switches|cleaned\.(?:holds|seams|spikes\.found)|feet\.(?:supports|changes|steps|lowered|tracked|shifts)|stance\.(?:runs|over))\[\d+\]$/.test(where);
+  const targets=(row:Record<string,unknown>,where:string)=>{
+    if(row.bone!==undefined||row.slot!==undefined)return;
+    const joints=typeof row.joint==='string'?[row.joint]:typeof row.point==='string'?[row.point]:Array.isArray(row.joints)?row.joints.filter((v):v is string=>typeof v==='string'):[];
+    const chain=typeof row.chain==='string'?map.chains.find(c=>c.name===row.chain):undefined;
+    const bones=[...new Set(chain?chain.bones:joints.flatMap(bonesFor))];
+    if(bones.length===1)add(row,'bone',bones[0],where);else if(bones.length>1)add(row,'bones',bones,where);
+    // Multiple affected targets remain explicit lists, never a guessed winner.
+    if(typeof row.point==='string')add(row,'joint',row.point,where);
+  };
+  const visit=(value:unknown,where:string):void=>{
+    if(Array.isArray(value)){value.forEach((row,i)=>visit(row,`${where}[${i}]`));return;}
+    if(!isObject(value))return;
+    // Preserve uncovered's discrete renderer times; they do not index the pose.
+    if(where.startsWith('report.uncovered[')||where.startsWith('report.folds[')){
+      if(!render)fail(where,'render-domain event requires declared renderer metadata');
+      add(value,'domain','render',where);return;
+    }
+    let coordinates=false;
+    if(poseEvent(where)&&value.frame!==undefined&&typeof value.frame!=='number')fail(where+'.frame','expected nonnegative integer pose frame');
+    if(typeof value.frame==='number'){add(value,'t',time(value.frame,where+'.frame'),where);coordinates=true;}
+    if((poseEvent(where)&&value.frames!==undefined)||(Array.isArray(value.frames)&&value.frames.length===2&&value.frames.every(frame=>typeof frame==='number'))){const frames=pair(value.frames,where+'.frames');add(value,'times',frames.map((frame,i)=>time(frame,`${where}.frames[${i}]`)),where);coordinates=true;}
+    if(where.startsWith('report.holds[')&&typeof value.from==='number'&&typeof value.to==='number'){
+      pair([value.from,value.to],where+'.from/to');add(value,'frames',[value.from,value.to],where);add(value,'times',[time(value.from,where+'.from'),time(value.to,where+'.to')],where);coordinates=true;
+    }
+    if(coordinates){if(typeof value.seconds==='number')add(value,'spanSeconds',value.seconds,where);targets(value,where);}
+    // Recurse over the original fields only; added time/target arrays are data.
+    for(const [key,item] of Object.entries(value))if(!['t','times','bones','spanSeconds'].includes(key))visit(item,where+'.'+key);
+  };
+  visit(report,'report');
+  if(isObject(report.feet)&&Array.isArray(report.feet.jumps)){
+    add(report.feet,'jumpEvents',report.feet.jumps.map((frames:unknown,index:number)=>{
+      const interval=pair(frames,`feet.jumps[${index}]`);
+      return {frames:[...interval],times:interval.map((frame,i)=>time(frame,`feet.jumps[${index}][${i}]`))};
+    }),'report.feet');
+  }
+  // The actual producer uses frameTimes. Uniform clocks exist only when a
+  // caller explicitly supplies fps/frame0, never inferred from samples.
+  if('frameTimes' in clock)add(report,'frameTimes',[...times],'report');else{add(report,'fps',clock.fps,'report');add(report,'frame0',clock.frame0,'report');}
+  add(report,'render',render,'report');
+  if(inputs!==undefined){if(!isObject(inputs))throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);for(const key of ['rig','map','pose'] as const){const entry=inputs[key];if(!isObject(entry)||typeof entry.path!=='string'||!entry.path||entry.path.startsWith('/')||entry.path.charCodeAt(0)===92||/^[A-Za-z]:/.test(entry.path)||typeof entry.sha256!=='string'||! /^[a-f0-9]{64}$/.test(entry.sha256))throw new Refusal([{code:'REPORT_INPUTS',text:`inputs.${key}: expected invocation-relative consumed file path and exact SHA-256`}]);}add(report,'inputs',clone(inputs),'report');}
+  problems.throwIfAny();return report;
+}
+export function writeReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null,inputs:ReportInputs):string {if(inputs===undefined)throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);return JSON.stringify(enrichReport(input,map,clock,render,inputs),null,2)+'\n';}

package/src/retarget.ts

@@ -1582,9 +1582,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
   };
   /**
-   * #188: For a `set.symmetric === true` gesture set, normalise its two two-bone arm chains
-   * on frame `i` to the set's `drawn` symmetry centre so `|elbow_l.y - elbow_r.y| == 0` and
-   * clamp both forearms so the wrists stay inside the head silhouette.
+   * #188 / #207: For a `set.symmetric === true` gesture set, solve its two two-bone arm chains
+   * on frame `i` in the chest-local frame so the diamond is symmetric about the torso axis and
+   * torso lean carries the whole diamond without collapsing one arm into the ±20° turn clamp.
    */
   const solveSymmetricFrame = (set: (typeof map.alternates)[number], i: number): { cR: Chain; cL: Chain; wR: Pt; wL: Pt; hc: Pt; ed: number } | null => {
     if (set.chains.length !== 2) return null;
@@ -1626,6 +1626,21 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         ed = d;
       }
     }
+    let hc0: Pt = [(SR0[0] + SL0[0]) / 2, (SR0[1] + SL0[1]) / 2 + 0.85 * Math.hypot(SL0[0] - SR0[0], SL0[1] - SR0[1])];
+    let ed0 = Math.max(1e-3, 0.30 * Math.hypot(SL0[0] - SR0[0], SL0[1] - SR0[1]));
+    if (gestureHead !== null) {
+      const ha0 = rigPoint(rest, gestureHead.points[0]);
+      const hb0 = rigPoint(rest, gestureHead.points[1]);
+      if (ha0 !== null && hb0 !== null) {
+        const d0 = Math.hypot(hb0[0] - ha0[0], hb0[1] - ha0[1]);
+        if (d0 > 1e-6) {
+          hc0 = [(ha0[0] + hb0[0]) / 2, (ha0[1] + hb0[1]) / 2];
+          ed0 = d0;
+        }
+      }
+    }
+    const above0 = mappedAbove(bR0);
+    const chestTurn = above0 === null ? 0 : turn(above0, i);
     const drawnR0 = set.drawn[bR0]!;
     const drawnR1 = set.drawn[bR1]!;
     const drawnL0 = set.drawn[bL0]!;
@@ -1634,19 +1649,39 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     const turnR1 = set.turn[bR1] ?? [-20, 20];
     const turnL0 = set.turn[bL0] ?? [-20, 20];
     const turnL1 = set.turn[bL1] ?? [-20, 20];
-    const rawR0 = rawTargets.get(bR0)?.[i] ?? drawnR0;
-    const rawL0 = rawTargets.get(bL0)?.[i] ?? drawnL0;
-    const offR0 = wrap(rawR0 - drawnR0);
-    const offL0 = wrap(rawL0 - drawnL0);
-    let cOpen = Math.max(-4, Math.min(2, 0.15 * 0.5 * (offR0 - offL0)));
-    const solveTilt = (open: number): { aR0: number; aL0: number; exR: number; eyR: number; exL: number; eyL: number } => {
+    const erDrawnX = SR0[0] + lR0 * Math.cos((drawnR0 + dR0) / DEG);
+    const elDrawnX = SL0[0] + lL0 * Math.cos((drawnL0 + dL0) / DEG);
+    let aR0_c: number;
+    let aL0_c: number;
+    let aR1_c: number;
+    let aL1_c: number;
+    if (Math.abs(wrap(drawnR0 + drawnL0 - 180)) > 1 && (hc0[0] - erDrawnX > lR1 || elDrawnX - hc0[0] > lL1)) {
+      const eyTarget = hc0[1] - 0.30 * ed0;
+      const sR = Math.max(-1, Math.min(1, (eyTarget - SR0[1]) / Math.max(1e-6, lR0)));
+      const sL = Math.max(-1, Math.min(1, (eyTarget - SL0[1]) / Math.max(1e-6, lL0)));
+      const wantR0 = wrap(180 - Math.asin(sR) * DEG - dR0);
+      const wantL0 = wrap(Math.asin(sL) * DEG - dL0);
+      const offR0_c = Math.min(Math.max(wrap(wantR0 - drawnR0), turnR0[0]), turnR0[1]);
+      const offL0_c = Math.min(Math.max(wrap(wantL0 - drawnL0), turnL0[0]), turnL0[1]);
+      aR0_c = wrap(drawnR0 + offR0_c);
+      aL0_c = wrap(drawnL0 + offL0_c);
+      const offR1_c = Math.min(Math.max(-0.35 * offR0_c, turnR1[0]), turnR1[1]);
+      const offL1_c = Math.min(Math.max(-0.35 * offL0_c, turnL1[0]), turnL1[1]);
+      aR1_c = wrap(drawnR1 + offR1_c);
+      aL1_c = wrap(drawnL1 + offL1_c);
+    } else {
+      const rawR0 = wrap((rawTargets.get(bR0)?.[i] ?? drawnR0) - chestTurn);
+      const rawL0 = wrap((rawTargets.get(bL0)?.[i] ?? drawnL0) - chestTurn);
+      const offR0 = wrap(rawR0 - drawnR0);
+      const offL0 = wrap(rawL0 - drawnL0);
+      const cOpen = Math.max(-4, Math.min(2, 0.15 * 0.5 * (offR0 - offL0)));
       const evalDiff = (deg: number) => {
         const dR = deg < 0 ? 0.25 * deg : deg;
         const dL = deg > 0 ? 0.25 * deg : deg;
-        const ar = drawnR0 + Math.min(Math.max(open + dR, turnR0[0]), turnR0[1]);
-        const al = drawnL0 + Math.min(Math.max(-open + dL, turnL0[0]), turnL0[1]);
-        const eyr = sr[1] + lR0 * Math.sin((ar + dR0) / DEG);
-        const eyl = sl[1] + lL0 * Math.sin((al + dL0) / DEG);
+        const ar = drawnR0 + Math.min(Math.max(cOpen + dR, turnR0[0]), turnR0[1]);
+        const al = drawnL0 + Math.min(Math.max(-cOpen + dL, turnL0[0]), turnL0[1]);
+        const eyr = SR0[1] + lR0 * Math.sin((ar + dR0) / DEG);
+        const eyl = SL0[1] + lL0 * Math.sin((al + dL0) / DEG);
         return eyl - eyr;
       };
       let lo = -45;
@@ -1671,68 +1706,73 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
       const dR = deg < 0 ? 0.25 * deg : deg;
       const dL = deg > 0 ? 0.25 * deg : deg;
-      let aR0 = drawnR0 + Math.min(Math.max(open + dR, turnR0[0]), turnR0[1]);
-      let aL0 = drawnL0 + Math.min(Math.max(-open + dL, turnL0[0]), turnL0[1]);
-      const eyR0 = sr[1] + lR0 * Math.sin((aR0 + dR0) / DEG);
-      const eyL0 = sl[1] + lL0 * Math.sin((aL0 + dL0) / DEG);
+      aR0_c = drawnR0 + Math.min(Math.max(cOpen + dR, turnR0[0]), turnR0[1]);
+      aL0_c = drawnL0 + Math.min(Math.max(-cOpen + dL, turnL0[0]), turnL0[1]);
+      const eyR0 = SR0[1] + lR0 * Math.sin((aR0_c + dR0) / DEG);
+      const eyL0 = SL0[1] + lL0 * Math.sin((aL0_c + dL0) / DEG);
       if (Math.abs(eyL0 - eyR0) > 1e-4) {
-        const sL = Math.max(-1, Math.min(1, (eyR0 - sl[1]) / Math.max(1e-6, lL0)));
+        const sL = Math.max(-1, Math.min(1, (eyR0 - SL0[1]) / Math.max(1e-6, lL0)));
         const candL = wrap(Math.asin(sL) * DEG - dL0);
         const tL = wrap(candL - drawnL0);
-        if (tL >= turnL0[0] && tL <= turnL0[1]) aL0 = candL;
+        if (tL >= turnL0[0] && tL <= turnL0[1]) aL0_c = candL;
       }
-      const rR0 = (aR0 + dR0) / DEG;
-      const rL0 = (aL0 + dL0) / DEG;
-      return {
-        aR0: wrap(aR0),
-        aL0: wrap(aL0),
-        exR: sr[0] + lR0 * Math.cos(rR0),
-        eyR: sr[1] + lR0 * Math.sin(rR0),
-        exL: sl[0] + lL0 * Math.cos(rL0),
-        eyL: sl[1] + lL0 * Math.sin(rL0),
-      };
-    };
-    const upper = solveTilt(cOpen);
-    const aimFore = (ex: number, ey: number, l1: number, d1: number, drawn1: number, turn1: readonly [number, number], tx: number, ty: number): [number, Pt] => {
-      const want = wrap(Math.atan2(ty - ey, tx - ex) * DEG - d1);
-      const off = Math.min(Math.max(wrap(want - drawn1), turn1[0]), turn1[1]);
-      let a1 = wrap(drawn1 + off);
-      let r1 = (a1 + d1) / DEG;
-      let wx = ex + l1 * Math.cos(r1);
-      let wy = ey + l1 * Math.sin(r1);
-      const xMin = hc[0] - 0.30 * ed;
-      const xMax = hc[0] + 0.30 * ed;
-      const yMin = hc[1] + 0.15 * ed;
-      const yMax = hc[1] + 0.95 * ed;
-      if (wx < xMin || wx > xMax || wy < yMin || wy > yMax) {
-        let bestA = a1;
-        let bestErr = Infinity;
-        for (let step = -200; step <= 200; step++) {
-          const candOff = turn1[0] + ((turn1[1] - turn1[0]) * (step + 200)) / 400;
-          const candA = wrap(drawn1 + candOff);
-          const cr = (candA + d1) / DEG;
-          const cwx = ex + l1 * Math.cos(cr);
-          const cwy = ey + l1 * Math.sin(cr);
-          const ox = cwx < xMin ? xMin - cwx : cwx > xMax ? cwx - xMax : 0;
-          const oy = cwy < yMin ? yMin - cwy : cwy > yMax ? cwy - yMax : 0;
-          const err = (ox + oy) * 1000 + Math.hypot(cwx - tx, cwy - ty);
-          if (err < bestErr) {
-            bestErr = err;
-            bestA = candA;
+      aR0_c = wrap(aR0_c);
+      aL0_c = wrap(aL0_c);
+      const rR0_c = (aR0_c + dR0) / DEG;
+      const rL0_c = (aL0_c + dL0) / DEG;
+      const exR_c = SR0[0] + lR0 * Math.cos(rR0_c);
+      const eyR_c = SR0[1] + lR0 * Math.sin(rR0_c);
+      const exL_c = SL0[0] + lL0 * Math.cos(rL0_c);
+      const eyL_c = SL0[1] + lL0 * Math.sin(rL0_c);
+      const aimFore0 = (ex: number, ey: number, l1: number, d1: number, drawn1: number, turn1: readonly [number, number], tx: number, ty: number): number => {
+        const want = wrap(Math.atan2(ty - ey, tx - ex) * DEG - d1);
+        const off = Math.min(Math.max(wrap(want - drawn1), turn1[0]), turn1[1]);
+        let a1 = wrap(drawn1 + off);
+        const r1 = (a1 + d1) / DEG;
+        const wx = ex + l1 * Math.cos(r1);
+        const wy = ey + l1 * Math.sin(r1);
+        const xMin = hc0[0] - 0.30 * ed0;
+        const xMax = hc0[0] + 0.30 * ed0;
+        const yMin = hc0[1] + 0.15 * ed0;
+        const yMax = hc0[1] + 0.95 * ed0;
+        if (wx < xMin || wx > xMax || wy < yMin || wy > yMax) {
+          let bestA = a1;
+          let bestErr = Infinity;
+          for (let step = -200; step <= 200; step++) {
+            const candOff = turn1[0] + ((turn1[1] - turn1[0]) * (step + 200)) / 400;
+            const candA = wrap(drawn1 + candOff);
+            const cr = (candA + d1) / DEG;
+            const cwx = ex + l1 * Math.cos(cr);
+            const cwy = ey + l1 * Math.sin(cr);
+            const ox = cwx < xMin ? xMin - cwx : cwx > xMax ? cwx - xMax : 0;
+            const oy = cwy < yMin ? yMin - cwy : cwy > yMax ? cwy - yMax : 0;
+            const err = (ox + oy) * 1000 + Math.hypot(cwx - tx, cwy - ty);
+            if (err < bestErr) {
+              bestErr = err;
+              bestA = candA;
+            }
           }
+          a1 = bestA;
         }
-        a1 = bestA;
-        r1 = (a1 + d1) / DEG;
-        wx = ex + l1 * Math.cos(r1);
-        wy = ey + l1 * Math.sin(r1);
-      }
-      return [a1, [wx, wy]];
-    };
-    const [aR1, wR] = aimFore(upper.exR, upper.eyR, lR1, dR1, drawnR1, turnR1, hc[0] - 0.20 * ed, hc[1] + 0.65 * ed);
-    const [aL1, wL] = aimFore(upper.exL, upper.eyL, lL1, dL1, drawnL1, turnL1, hc[0] + 0.20 * ed, hc[1] + 0.65 * ed);
-    targets.get(bR0)![i] = upper.aR0;
+        return a1;
+      };
+      aR1_c = aimFore0(exR_c, eyR_c, lR1, dR1, drawnR1, turnR1, hc0[0] - 0.20 * ed0, hc0[1] + 0.65 * ed0);
+      aL1_c = aimFore0(exL_c, eyL_c, lL1, dL1, drawnL1, turnL1, hc0[0] + 0.20 * ed0, hc0[1] + 0.65 * ed0);
+    }
+    const carry = 0.35 * chestTurn;
+    const aR0 = wrap(aR0_c + carry);
+    const aR1 = wrap(aR1_c + carry);
+    const aL0 = wrap(aL0_c + carry);
+    const aL1 = wrap(aL1_c + carry);
+    const rR0 = (aR0 + dR0) / DEG;
+    const rR1 = (aR1 + dR1) / DEG;
+    const rL0 = (aL0 + dL0) / DEG;
+    const rL1 = (aL1 + dL1) / DEG;
+    const wR: Pt = [sr[0] + lR0 * Math.cos(rR0) + lR1 * Math.cos(rR1), sr[1] + lR0 * Math.sin(rR0) + lR1 * Math.sin(rR1)];
+    const wL: Pt = [sl[0] + lL0 * Math.cos(rL0) + lL1 * Math.cos(rL1), sl[1] + lL0 * Math.sin(rL0) + lL1 * Math.sin(rL1)];
+    targets.get(bR0)![i] = aR0;
     targets.get(bR1)![i] = aR1;
-    targets.get(bL0)![i] = upper.aL0;
+    targets.get(bL0)![i] = aL0;
     targets.get(bL1)![i] = aL1;
     return { cR, cL, wR, wL, hc, ed };
   };

package/src/run.ts

@@ -4,9 +4,10 @@
  * measure where the rig landed, read the folds (and which no switch covers),
  * and write — only when every check passed.
  */
-import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { knownSetsOf, readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { cleanLine, inferredSource } from './clean.ts';
 import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type CameraFrame } from './pose.ts';
@@ -19,6 +20,7 @@ import { landed, measureFeet, measureLanding, measurePosture, measureShear, pose
 import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, smoothTrunk, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
 import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import { reportRenderDomain, writeReport, type ReportInput } from './report.ts';
 import { bodyLine, faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -82,6 +84,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   }
   args.throwIfAny();
   const input = resolveRig(a.rig, a.baseMotion);
+  const rigSnapshot = readReportInput(input.rig);
   const base = baseMotionOf(input);
   const animations = base.animations as Record<string, unknown>;
   if (a.name in animations) refuse([{ code: 'MOTION_NAME_FREE', text: `the rig's motion spec already has an animation "${a.name}" (it has ${Object.keys(animations).join(', ')}); name this one with --name` }]);
@@ -90,8 +93,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     refuse([{ code: 'IDLE_NAME', text: `${a.idle !== undefined ? `--idle "${idleName}"` : '--carry-idle reads the animation "idle", and'} the rig's motion spec ${input.motion === null ? '— there is none, so it has no animations' : `${input.motion} has no animation "${idleName}" (it has ${Object.keys(animations).join(', ') || 'none'})`}; name the rig's idle with --idle` }]);
   }
   const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
-  const map = readMap(readFileSync(a.map, 'utf8'), a.map);
-  const poseText = readFileSync(a.pose, 'utf8');
+  const mapSnapshot = readReportInput(a.map), poseSnapshot = readReportInput(a.pose);
+  const map = readMap(mapSnapshot.bytes.toString('utf8'), a.map);
+  const poseText = poseSnapshot.bytes.toString('utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
   if (seq.cleaned === undefined) refuse([{ code: 'POSE_NOT_CLEANED', text: notCleaned(a.pose, a.coco) }]);
   const frames = personTrack(seq, a.person, a.pose);
@@ -305,48 +309,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const u of uncovered) say(`  UNCOVERED mesh "${u.attachment}" (slot "${u.slot}"; chains ${u.chains.length === 0 ? 'none' : u.chains.join(', ')}) folds with no switch covering it on ${u.times.length} frame(s): t=${spans(u.times, 1 / fps)}`);
     }
 
-    if (a.build !== undefined) {
-      // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
-      rmSync(a.build, { recursive: true, force: true });
-      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile, undefined, a.images);
-      if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
-    }
-    writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
-    if (a.camera !== undefined) {
-      const ss = r.figureScale.frames.map((x) => x.s);
-      const minS = ss.length === 0 ? 1 : Math.min(...ss);
-      const maxS = ss.length === 0 ? 1 : Math.max(...ss);
-      writeFileSync(a.camera, `${JSON.stringify({
-        spec: 'rig-pose-camera/1',
-        rig: input.name,
-        animation: a.name,
-        frames: r.figureScale.frames.map((f, i) => {
-          const cam = seq.camera?.[i];
-          const camS = cam?.s ?? 1;
-          return {
-            frame: f.frame,
-            t: f.t,
-            s: f.s,
-            rawS: f.rawS,
-            tx: cam?.tx ?? 0,
-            ty: cam?.ty ?? 0,
-            videoS: Number((f.s * camS).toFixed(6)),
-          };
-        }),
-        summary: {
-          minS,
-          maxS,
-          maxStep: r.figureScale.maxStep,
-          endOverStart: r.figureScale.endOverStart,
-        },
-      }, null, 2)}\n`);
-    }
-    if (a.render !== undefined && f.meshes !== null && f.frames !== '') {
-      rmSync(a.render, { recursive: true, force: true });
-      cpSync(f.frames, a.render, { recursive: true });
-    }
-    if (a.report !== undefined) {
-      writeFileSync(a.report, `${JSON.stringify({
+    if (a.report !== undefined) assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    const reportText = a.report === undefined ? null : writeReport({
         spec: 'rig-pose-report/1',
         rigc,
         rig: input.name,
@@ -403,8 +367,51 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         idleKeptOut: idle === null ? null : idle.keptOut,
         merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
         reduce: reduced === null ? null : { tolerance: a.reduce, hipTolerance: a.reduceHip ?? null, rows: reduced.rows },
+      }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : null, {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
+    if (a.build !== undefined) {
+      // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
+      rmSync(a.build, { recursive: true, force: true });
+      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile, undefined, a.images);
+      if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
+    }
+    // The kept build reads the rig again; its bytes must still match the report.
+    if (a.report !== undefined) assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
+    if (a.camera !== undefined) {
+      const ss = r.figureScale.frames.map((x) => x.s);
+      const minS = ss.length === 0 ? 1 : Math.min(...ss);
+      const maxS = ss.length === 0 ? 1 : Math.max(...ss);
+      writeFileSync(a.camera, `${JSON.stringify({
+        spec: 'rig-pose-camera/1',
+        rig: input.name,
+        animation: a.name,
+        frames: r.figureScale.frames.map((f, i) => {
+          const cam = seq.camera?.[i];
+          const camS = cam?.s ?? 1;
+          return {
+            frame: f.frame,
+            t: f.t,
+            s: f.s,
+            rawS: f.rawS,
+            tx: cam?.tx ?? 0,
+            ty: cam?.ty ?? 0,
+            videoS: Number((f.s * camS).toFixed(6)),
+          };
+        }),
+        summary: {
+          minS,
+          maxS,
+          maxStep: r.figureScale.maxStep,
+          endOverStart: r.figureScale.endOverStart,
+        },
       }, null, 2)}\n`);
     }
+    if (a.render !== undefined && f.meshes !== null && f.frames !== '') {
+      rmSync(a.render, { recursive: true, force: true });
+      cpSync(f.frames, a.render, { recursive: true });
+    }
+    if (a.report !== undefined && reportText !== null) writeFileSync(a.report, reportText);
+
     if (a.camera !== undefined) say(`  wrote ${a.camera} — camera track (${r.figureScale.frames.length} frames)`);
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
     return { lines, written: true };
@@ -794,3 +801,14 @@ export function notCleaned(pose: string, coco: boolean): string {
   const what = coco ? `${pose} is COCO-17 (--coco), which carries no "cleaned" record` : `${pose} has no "cleaned" record`;
   return `${what}; retarget reads a sequence rig-pose clean wrote (spikes, occlusion, smoothing; there is no flag to skip it). Run \`rig-pose clean ${coco ? '--coco ' : ''}--pose ${pose} --out ${out}\` (add --loop for one cycle of a gait) and retarget --pose ${out}`;
 }
+
+/** File-bound identities are assembled only in this existing IO boundary. */
+export interface ReportInputSnapshot {file:string;bytes:Buffer;identity:ReportInput;size:number;mtimeMs:number}
+export function readReportInput(file:string):ReportInputSnapshot {
+  const path=realpathSync(resolve(file)),before=statSync(path),bytes=readFileSync(path),after=statSync(path);
+  if(!before.isFile()||before.size!==after.size||before.mtimeMs!==after.mtimeMs)throw new Refusal([{code:'REPORT_INPUTS',text:`${file}: input changed while reading; expected one stable regular file`}]);
+  return {file:resolve(file),bytes,identity:{path:relative(process.cwd(),path).split('\\').join('/'),sha256:createHash('sha256').update(bytes).digest('hex')},size:after.size,mtimeMs:after.mtimeMs};
+}
+export function assertReportInputs(inputs:readonly ReportInputSnapshot[]):void {
+  for(const expected of inputs){const current=readReportInput(expected.file);if(current.identity.path!==expected.identity.path||current.identity.sha256!==expected.identity.sha256)throw new Refusal([{code:'REPORT_INPUTS_CHANGED',text:`${expected.identity.path}: consumed input changed before output writes; expected SHA-256 ${expected.identity.sha256}, found ${current.identity.sha256}`}]);}
+}