@rig-c/pose 0.35.0 → 0.36.0

package/README.md

@@ -16,7 +16,7 @@ Part of the rig-c toolchain: [core](https://github.com/rig-c/core) compiles and
 rig-pose retarget --rig examples/wave/rig --map examples/wave/map.json --sequence examples/wave/pose.json --out wave.motion.json --build wave-build
 ```
 
-`pose.json` is already cleaned (`make-pose.ts` passes it through `clean`). It prints the gate's verdict and where every mapped bone landed, then writes `wave.motion.json`, its report `wave.motion.report.json` and the gated build. `rigc preview --candidate wave-build` plays it in the Spine Web Player. A rig with no art shows only its bones.
+`pose.json` is already cleaned (`make-pose.ts` passes it through `clean`). It prints the gate's verdict and where every mapped bone landed, then writes `wave.motion.json`, its report `wave.motion.report.json` and the gated build, with its record `retarget.json` beside it ([below](#the-builds-record-retargetjson)). `rigc preview --candidate wave-build` plays it in the Spine Web Player. A rig with no art shows only its bones.
 
 ## What the rig needs
 
@@ -220,6 +220,31 @@ Both have a meaningless direction; only the first is a pose the rig cannot draw.
 
 Re-checked on a @rig-c/parts fixture rig with the short hold, the flip guard and clamped bends. On `dance-b` the three spreads the flip guard made out of end-on segments are SHORT holds now, not FLIPs: right upper arm 399–400, right thigh 368–369, right shin 368–371. Of the flip guard's other spreads only one is left, the left forearm at 322–323; every other one fell on frames under the cutoff and is a SHORT hold instead. No guarded bone of the gated build turns more than 81.4° in one frame (85.1° with the flip guard alone), and every bone lands. `endOn` there lists the right upper arm (395–401) and the right shin (365–370). It does not list the right thigh, which is under 0.35 on one frame only (369, 0.16). The plan before the run expected the thigh too, and that expectation was wrong. On `dance-a` `endOn` lists exactly S2's left upper arm (30–37); the three FLIPs are #15's, the largest one-frame turn is 78.2°, and every bone lands. When `dance-b`'s pelvis is mapped (`r_hip → l_hip`), its side-on turn (frames 463–491, body yaw +79.5°) foreshortens the hip line to 0.17 of standing and crosses `r_hip.x` past `l_hip.x` on frames 482–484 (+177.4° / −179.4°); `holdAcross` ([#184](https://github.com/rig-c/pose/issues/184)) holds `hip.rotate` across the unconfident span (`[−2.2°, +2.6°]` over 463–491, `0` `FLIP`s) without listing horizontal lines as limb `END-ON`. The default stays off: a default needs its own criterion and a third sequence.
 
+### The build's record: `retarget.json`
+
+`--build <dir>` keeps the gated build — rigc's own files, byte for byte as rigc wrote them — and beside them one more file, `retarget.json` (`rig-pose-retarget/1`, [#270](https://github.com/rig-c/pose/issues/270)): what made the build. It is written once the kept build is green and the inputs are re-read unchanged, and a `RECORD` line says so (`RECORD retarget.json written beside the build (reference: <path> | none given)`). Its keys, in this order:
+
+```json
+{
+  "spec": "rig-pose-retarget/1",
+  "pose": { "version": "<this package's version>" },
+  "rigc": { "version": "<the rig-c that gated the run, as the RIGC line names it>" },
+  "inputs": {
+    "rig": { "path": "<--rig as given>", "sha256": "<the rig spec's bytes>" },
+    "map": { "path": "<--map as given>", "sha256": "<the map's bytes>" },
+    "sequence": { "path": "<--sequence as given>", "sha256": "<the sequence's bytes>", "source": "<its \"source\", verbatim>" }
+  },
+  "flags": { "name": "<the animation>", "minScore": 0.3, "...": "every retarget option as resolved — the report's options, in their order" },
+  "reference": "<--reference as given>"
+}
+```
+
+- **Paths are as typed.** Each `path` is the argument as given on the command line — not resolved, not made relative, not normalised. Each `sha256` is the hex digest of the file's bytes the run read (the same bytes the report's `inputs` hash). `--rig` given as a directory or as a `rig.json` hashes the same file: the rig spec, `rig.json`, that rigc builds from. A `motion.json` read beside it (or `--base-motion`), a `sets.json` and the images are not in the hash, as they are not in the report's.
+- **`reference` is the author's, and only when given.** `--reference <path>` (with `--build`; without it the run is refused: `--reference needs --build: the record it goes in is written beside the build`) names what the motion was made to match — the video, say — and the record carries it exactly as typed. It is echoed, never read: the path is not checked to exist. Without `--reference` the record has no `reference` key — not `null`, and nothing is derived from the sequence's `source` or its path. (`compare --reference` is another flag.)
+- **Deterministic.** No clock, no host name, no absolute path the user did not type: the same inputs and flags write the same bytes into any build directory. 2-space JSON, a trailing newline.
+
+`rigc review` is the intended reader (rig-c's later card): it reads the build and, through this file, what made it.
+
 ### The legs: foreshortening and planted feet
 
 A knee bending toward the camera is seen from the front only as a shorter leg, and a rig with rigid legs cannot lower its hip without lifting its feet ([#47](https://github.com/rig-c/pose/issues/47)). Two flags, both off by default:

package/cli.ts

@@ -13,6 +13,7 @@ import { convertCoco17, readPoseSequence, writePoseSequence } from './src/pose.t
 import { parseWindows } from './src/compare.ts';
 import { lineOf, Refusal } from './src/problems.ts';
 import { runCompare, type CompareArgs } from './src/runcompare.ts';
+import { PROVENANCE_FILE } from './src/provenance.ts';
 import { runRetarget, type RetargetArgs } from './src/run.ts';
 
 const HELP = `rig-pose ${pkg.version} — motion from a pose sequence onto a rig-c rig
@@ -182,7 +183,13 @@ retarget
                         changes turn fastest, among those that newly show a set only on frames within
                         2 × the switch tolerance of its key skeleton (it stays when none qualifies)
   --profile spine|spine-html  rigc's gate profile (default: spine, rigc's own default)
-  --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here
+  --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here, with the record of
+                        what made it beside it: retarget.json (rig-pose-retarget/1 — both versions, each input
+                        as given with its sha256, the sequence's source, every option as resolved; rig-c/pose#270)
+  --reference <path>    with --build: written into retarget.json as "reference", exactly as given — the
+                        video or file the motion was made to match. Echoed, never read: the path is not
+                        checked to exist. Without it the record has no "reference" (compare's --reference
+                        is another flag)
   --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
   --parts <path>        @rig-c/parts' parts.json, or the directory holding it (its build's --out, beside rig/):
                         the neighbour pairs the seam reading reads — each limb's consecutive segments. Each
@@ -324,8 +331,9 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 const RETARGET_ALIASES = { sequence: 'pose', animation: 'name' } as const;
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'parts', 'report', 'camera', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance', 'floor'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head', 'reduce-keep-planted', 'verbose', 'summary'], RETARGET_ALIASES);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'reference', 'render', 'parts', 'report', 'camera', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance', 'floor'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head', 'reduce-keep-planted', 'verbose', 'summary'], RETARGET_ALIASES);
   if (f.has('verbose') && f.has('summary')) throw new Usage('--verbose and --summary are both given; --verbose prints every line in full and --summary one line per measure, so give one');
+  if (f.has('reference') && !f.has('build')) throw new Usage(`--reference needs --build: the record it goes in is written beside the build (${PROVENANCE_FILE})`);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -360,6 +368,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     switchAt,
     profile,
     build: f.get('build'),
+    reference: f.get('reference'),
     render: f.get('render'),
     parts: f.get('parts'),
     report: f.get('report'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.35.0",
+  "version": "0.36.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/provenance.ts

@@ -0,0 +1,52 @@
+/**
+ * rig-c/pose#270: the record `retarget --build` writes beside the build —
+ * `rig-pose-retarget/1`, what made it: this package's and rig-c's versions,
+ * each input as given on the command line with the sha256 of the bytes the run
+ * read, the sequence's own `source`, every retarget option as resolved, and the
+ * author's `--reference` echoed verbatim when one was given. Pure: the caller
+ * hashes and writes. No clock, no host, no path is normalised; a value the run
+ * was not given is absent, never derived.
+ */
+import pkg from '../package.json' with { type: 'json' };
+
+/** The record's file name inside the `--build` directory. */
+export const PROVENANCE_FILE = 'retarget.json';
+export const PROVENANCE_SPEC = 'rig-pose-retarget/1';
+
+export interface ProvenanceInput {
+  /** The path as given on the command line, and the sha256 (hex) of the file's bytes. */
+  path: string;
+  sha256: string;
+}
+
+export interface ProvenanceArgs {
+  /** rig-c's version, as `rigcVersion()` read it from the gate's own launcher. */
+  rigc: string;
+  /** `--rig` as given; the hash is of the rig spec (`rig.json`) rigc gated. */
+  rig: ProvenanceInput;
+  map: ProvenanceInput;
+  /** `--sequence` as given, with the document's `source` string verbatim. */
+  sequence: ProvenanceInput & { source: string };
+  /** The animation's name, then the report's `options` in their order. */
+  name: string;
+  options: Record<string, unknown>;
+  /** `--reference` exactly as given; absent when it was not. */
+  reference?: string;
+}
+
+/** The record's text: fixed key order, 2-space JSON, a trailing newline. */
+export function provenanceText(a: ProvenanceArgs): string {
+  const record = {
+    spec: PROVENANCE_SPEC,
+    pose: { version: pkg.version },
+    rigc: { version: a.rigc },
+    inputs: {
+      rig: { path: a.rig.path, sha256: a.rig.sha256 },
+      map: { path: a.map.path, sha256: a.map.sha256 },
+      sequence: { path: a.sequence.path, sha256: a.sequence.sha256, source: a.sequence.source },
+    },
+    flags: { name: a.name, ...a.options },
+    ...(a.reference === undefined ? {} : { reference: a.reference }),
+  };
+  return `${JSON.stringify(record, null, 2)}\n`;
+}

package/src/run.ts

@@ -22,6 +22,7 @@ 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, FreeAnkleShift, LegScale, LegSegmentRatio, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
 import { reportRenderDomain, writeReport, type ReportInput } from './report.ts';
+import { PROVENANCE_FILE, provenanceText } from './provenance.ts';
 import { bodyLine, faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -40,6 +41,11 @@ export interface RetargetArgs extends RetargetOptions {
   profile: 'spine' | 'spine-html';
   /** Keep the gated build here. */
   build?: string;
+  /**
+   * With `build`: echoed verbatim into the build's record (`retarget.json`, #270) as `reference`;
+   * never read, never checked to exist. Absent, the record has no `reference` key.
+   */
+  reference?: string;
   /** Keep rigc's render of the animation (frames, contact sheet, folds.json) here. */
   render?: string;
   /** @rig-c/parts' `parts.json` (or the directory holding it): the neighbour pairs the seam reading reads (#216). */
@@ -107,6 +113,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (!statSync(up).isDirectory()) args.add('ARG_PATH', up === dir ? `${flag} ${path} — ${dir} is not a directory` : `${flag} ${path} — ${up} is a file, so directory ${dir} cannot be made under it`);
     else if (up !== dir) makeDirs.set(dir, [...(makeDirs.get(dir) ?? []), `${flag} ${path}`]);
   }
+  if (a.reference !== undefined && a.build === undefined) args.add('ARG_REFERENCE', `--reference ${a.reference} needs --build: the record it goes in is written beside the build (${PROVENANCE_FILE})`);
   args.throwIfAny();
   const input = resolveRig(a.rig, a.baseMotion);
   const rigSnapshot = readReportInput(input.rig);
@@ -377,6 +384,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     for (const d of drift) say(`  REDUCE ${ankleDriftLine(d)}`);
 
     assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    // Every retarget option as resolved: the report's `options`, and with the name the build record's `flags` (#270).
+    const options = { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}) };
     const reportText = writeReport({
         spec: 'rig-pose-report/1',
         rigc,
@@ -385,7 +394,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         frames: seq.frames.length,
         duration: r.animation.duration,
         cleaned: seq.cleaned,
-        options: { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}) },
+        options,
         scale: r.scale,
         scaleFit: r.scaleFit,
         holds: r.holds,
@@ -448,6 +457,20 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     }
     // The kept build reads the rig again; its bytes must still match the report.
     assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
+    if (a.build !== undefined) {
+      // #270: what made the build, beside it — the inputs as given with the bytes' hashes (the ones just
+      // re-checked), the versions, the options; `reference` only when the author gave one.
+      writeFileSync(join(a.build, PROVENANCE_FILE), provenanceText({
+        rigc: rigc.version,
+        rig: { path: a.rig, sha256: rigSnapshot.identity.sha256 },
+        map: { path: a.map, sha256: mapSnapshot.identity.sha256 },
+        sequence: { path: a.pose, sha256: poseSnapshot.identity.sha256, source: seq.source },
+        name: a.name,
+        options,
+        ...(a.reference === undefined ? {} : { reference: a.reference }),
+      }));
+      say(`  RECORD ${PROVENANCE_FILE} written beside the build (reference: ${a.reference ?? 'none given'})`);
+    }
     for (const [dir, flags] of makeDirs) {
       mkdirSync(dir, { recursive: true });
       tell(madeLine(dir, flags));