@rig-c/parts 1.43.0 → 1.44.0

package/cli.ts

@@ -31,6 +31,7 @@ import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DE
 import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, serializeBasis } from './src/diagnostics.ts';
 import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
 import { PROVENANCE_FILE, REMESH_SPEC, remeshStage } from './src/remesh.ts';
+import { RETUNE_FILE, RETUNE_SPEC, retuneStage } from './src/retune.ts';
 import { checkPainting } from './src/paintcheck.ts';
 import { readPng, writePng } from './src/raster/png.ts';
 import { REQUIREMENTS_SENTENCE } from './src/requirements.ts';
@@ -384,6 +385,30 @@ usage:
       REMESH_DELTA_TOPOLOGY). No config entry is built: the baseline is the
       input itself; the splice, the gate and check are as for --mesh.
 
+  rig-parts retune --rig <dir> --config <config.json> --parts <dir> --out <dir>
+                   [--requirements <file.json>] [--idle-keys ctl|direct]
+                   [--page-edges pot|free] [--pack-shape rect|polygon]
+      Splice the constraints and the idle a config states onto a gated rig
+      (the directory rig writes) and write a new revision into --out, which
+      must not exist (RETUNE_OUT_FRESH); the input is never written. The
+      config is built once through the rig stage (RETUNE_CONFIG_REFUSED,
+      quoting each problem), and that build must state the input's stops,
+      bones, slots, skeleton, images, every invariant but detached and every
+      byte of motion.json but animations.idle (RETUNE_REQUEST_HELD): a moved
+      bone, a redrawn image, a stops change or an animations_from change is
+      no retune. No attachment is compared — the input's meshes are carried
+      over as bytes, repairs included, and a meshes change in the config is
+      never read (remesh is a mesh's producer). rig.json takes the build's
+      constraints and invariants.detached, motion.json its animations.idle,
+      every other byte is the input's (RETUNE_PRESERVED); rigc's build gate
+      passes over the revision (RETUNE_RIGC_GREEN); check measures every bar
+      on it that it measures on the input and fails none the input meets
+      (RETUNE_CHECK_HELD). --out receives the revision and ${RETUNE_FILE}
+      (spec "${RETUNE_SPEC}": the request, both versions, every input file's
+      SHA-256, what was held, which constraint fields and idle tracks changed,
+      both checks and their scope) — no path and no clock, so the same request
+      writes the same bytes. Prints what changed and a hash table of every file.
+
   rig-parts check --rig <dir> --out <dir> [--parts <dir>] [--source <painting.png>]
                     [--page-edges pot|free] [--pack-shape rect|polygon]
                     [--requirements <file.json>] [--seam-pairs] [--keep-stills]
@@ -848,6 +873,7 @@ const TAKES = {
   compose: { valued: ['--scene', '--out', '--requirements', '--accept'], switches: [] },
   'mesh-draft': { valued: ['--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: ['--more-triangles'] },
   remesh: { valued: ['--rig', '--config', '--parts', '--part', '--mesh', '--delta', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
+  retune: { valued: ['--rig', '--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
   painting: { valued: ['--keypoints', '--person'], switches: [] },
 } as const satisfies Record<string, { valued: readonly string[]; switches: readonly string[] }>;
 
@@ -1700,6 +1726,45 @@ function cmdRemesh(args: string[]): number {
   }
 }
 
+/** `retune` (issue #527): the constraints and the idle a config states, spliced onto a gated rig, into a new revision. */
+function cmdRetune(args: string[]): number {
+  const f = flags(args, 'retune', ['--rig', '--config', '--parts', '--out']);
+  if (typeof f === 'string') return usage(f);
+  const keys = idleKeysOf(f.get('--idle-keys'));
+  if (!isIdleKeys(keys)) return usage(keys);
+  const edges = pageEdgesOf(f.get('--page-edges'));
+  if (!isPageEdges(edges)) return usage(edges);
+  const shape = packShapeOf(f.get('--pack-shape'));
+  if (!isPackShape(shape)) return usage(shape);
+  let bin: string;
+  try {
+    bin = findRigc(import.meta.dir, process.env.PATH ?? '');
+  } catch (err) {
+    return printRefusal(err);
+  }
+  const runner = rigcRunner(bin);
+  const said = runner(['--version']);
+  const rigcVersion = said.status === 0 ? (said.out.trim().split('\n')[0] ?? '') : '';
+  if (rigcVersion === '') return printRefusal(new PartsError([{ code: 'RETUNE_RIGC_GREEN', object: 'rigc --version', detail: `exited ${said.status}${rigcRanClause(said)}; the provenance names the rigc that gated the revision, so its version is required` }]));
+  const scratch = mkdtempSync(join(tmpdir(), 'rig-parts-retune-'));
+  try {
+    const req = f.get('--requirements');
+    retuneStage(
+      { rig: f.get('--rig') as string, config: f.get('--config') as string, parts: f.get('--parts') as string, out: f.get('--out') as string, idleKeys: keys, pageEdges: edges, packShape: shape, ...(req === undefined ? {} : { requirements: req }) },
+      runner,
+      bin,
+      { parts: version(), rigc: rigcVersion },
+      scratch,
+      console.log,
+    );
+    return EXIT_OK;
+  } catch (err) {
+    return printRefusal(err);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
 /**
  * `painting --keypoints <k.json> [--person <id>] <painting.png>` (issue #350): what the painting must be before
  * See-through runs on it, read off its pixels and the body-18 joints `propose --keypoints` reads. Writes nothing.
@@ -1770,6 +1835,7 @@ function main(argv: string[]): number | Promise<number> {
   if (command === 'compose') return cmdCompose(rest);
   if (command === 'mesh-draft') return cmdMeshDraft(rest);
   if (command === 'remesh') return cmdRemesh(rest);
+  if (command === 'retune') return cmdRetune(rest);
   if (command === 'painting') return cmdPainting(rest);
   if (command === 'guide') return cmdGuide(rest);
   const later = LATER.find(([name]) => name === command);

package/docs/AUTHORING.md

@@ -2979,6 +2979,38 @@ gate and `check` are the `--mesh` path's. A constraint is a statement about this
 revision's triangulation only: the rig spec has no field for it, so a later edit of the
 revision reads it as any other edge.
 
+### retune
+
+| rule | means | change |
+| --- | --- | --- |
+| <a id="RETUNE_OUT_FRESH"></a>`RETUNE_OUT_FRESH` | `--out` exists, or lies inside `--rig`: a revision is a new directory beside the input, never written over it | name a directory that does not exist yet |
+| <a id="RETUNE_INPUT_PRESENT"></a>`RETUNE_INPUT_PRESENT` | `--rig` is not the directory `rig` writes: `rig.json`, `motion.json`, `mesh_report.json` or `images/` is missing | point `--rig` at a `rig` output (`build`'s `rig/`, or a `remesh` or `retune` revision) |
+| <a id="RETUNE_INPUT_WRITTEN"></a>`RETUNE_INPUT_WRITTEN` | `rig.json` or `motion.json` is not the text this package's writer prints for its value (reformatted, or written by something else); the revision is spliced as text, so it could not carry every other byte over | use the files as `rig` wrote them |
+| <a id="RETUNE_CONFIG_REFUSED"></a>`RETUNE_CONFIG_REFUSED` | the rig stage refused the config as written — the loader, a mesh's own checks, an `auto` mesh's motion gate under the new idle, or rigc's gate; each problem is quoted, and nothing was written | change the field the quoted problem names |
+| <a id="RETUNE_REQUEST_HELD"></a>`RETUNE_REQUEST_HELD` | the config's build does not state the input's `stops`, `bones` (a bone moved, renamed, added, re-inherited, or a `<bone>_ctl` added or dropped), `slots`, `skeleton`, `images`, an image file, an `invariants` entry other than `detached`, or a byte of `motion.json` outside `animations.idle` (`animations_from`, the groups, the easings, the face deform); the first differing leaf is named | make it a config change and rebuild with `rig --config` |
+| <a id="RETUNE_PRESERVED"></a>`RETUNE_PRESERVED` | the spliced revision differs from the input outside `rig.json`'s `constraints` and `invariants.detached` and `motion.json`'s `animations.idle`; the file and the path that moved are named | a defect in this package: report it with the line |
+| <a id="RETUNE_RIGC_GREEN"></a>`RETUNE_RIGC_GREEN` | rigc's build gate refused the revision (its lines quoted), or `rigc --version` named no version for the provenance | read rigc's line; nothing was written |
+| <a id="RETUNE_CHECK_HELD"></a>`RETUNE_CHECK_HELD` | `check` on the revision did not measure a bar it measured on the input, or failed a bar the input met; the revision's own FAIL line is quoted | soften the constraint or the idle track the line names |
+
+A retune replaces a rig's physics and its idle and nothing else. The config is built
+once through the rig stage; from that build `rig.json` takes `constraints` and
+`invariants.detached` (which the rig stage derives from the constraints), and
+`motion.json` takes `animations.idle`. Every other byte is the input's: every
+attachment and image, every `mesh_report.json` row and every other animation, so a
+mesh the config does not reproduce — a `remesh` revision, or a repair accepted after
+the config was written — is carried over as it is. What the build must state as the
+input does is held, and a config that moves it is refused rather than half-applied:
+a `stops` change (it rewires bones, slots and weights onto the drawn links
+`<link>_d`, so it is outside what a retune holds byte for byte), a moved, renamed or
+re-`inherit`ed bone, a new control bone under `--idle-keys ctl`, a redrawn image, or a
+change to `animations_from`. No mesh is compared or written, so a `meshes` change in
+the config is left out of the revision — `retune.json`'s `held.not_compared` says so;
+`remesh` is the producer of a mesh. `retune.json` names the input's SHA-256 per file,
+what was held, which constraint fields changed (and which constraints were added or
+removed), how many idle tracks changed and the idle's duration before and after, both
+versions and both checks, and quotes `check`'s own physics line as the scope of the
+revision's check.
+
 ### rig-c's mesh refusals, quoted in a line
 
 rig-c's mesh library refuses a malformed input by throwing with a code of its own. This

package/docs/STABILITY.md

@@ -62,6 +62,7 @@ defaults are the help's too, and none is guessed from the art.
 | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
 | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--more-triangles` |
 | `remesh` | `--rig`, `--config`, `--parts`, `--part`, `--out`, and one of `--mesh` or `--delta` (issue #526); optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
+| `retune` | `--rig`, `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
 | `painting` | one positional path, the painting; `--keypoints`; optional `--person` |
 | `guide` | one positional argument: a rule name, `§<n>`, `§<n>.<m>` or `§<n>.<m>.<k>` |
 | (none) | `--version`, `--help` |
@@ -199,6 +200,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
 | `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw`, and `faint` only when an island was left out as faint — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
 | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `remesh.json` | `remesh` | the input revision's files, `rig.json` and `mesh_report.json` with the part's attachment and row replaced (under `--delta` the row is the input's with its counts, `bones` and influences recomputed and `mode` "delta"), every other file byte for byte; `remesh.json` is spec `rig-parts-remesh/1`: `request` (`part`, `mesh`, `mesh_sha256`, `idle_keys`, `page_edges`, `pack_shape`; under `--delta`, issue #526: `part`, `delta` — the mesh edit as read — `delta_sha256`, `ops`, `applied` — `moved`, `added`, `removed`, `constrained` — `idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `baseline` (`reproduced`, `not_compared`; under `--delta` `reproduced` holds one sentence: no config is built, the input is the baseline), `target` (`before`, `after`: `vertices`, `triangles`, `hull`), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`; `scope`) |
+| `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `retune.json` | `retune` | the input revision's files, `rig.json` with `constraints` and `invariants.detached` replaced and `motion.json` with `animations.idle` replaced by the config's build, every other file byte for byte; `retune.json` is spec `rig-parts-retune/1`: `request` (`idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `held` (`compared`, `not_compared`), `changed` (`constraints` — each `name`, `type`, `fields` — `added`, `removed`, `idle`: `tracks_changed`, `duration` as before and after), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`; `scope`) |
 | the scene report | `compose` | spec `spine-parts-scene-report/1` |
 | `idle.png`, `idle-indexed.png`, `idle.gif` | `loop`, `build --loop` | APNG and GIF encodings of the rendered idle |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/remesh.ts

@@ -447,6 +447,12 @@ export function preservedProblems(input: FileTree, revision: FileTree, part: str
   return out;
 }
 
+/** The codes the shared readings below refuse with, by the revising command that runs them (`remesh`, `retune`). */
+export const REVISION_CODES = {
+  remesh: { inputPresent: 'REMESH_INPUT_PRESENT', inputWritten: 'REMESH_INPUT_WRITTEN', checkHeld: 'REMESH_CHECK_HELD' },
+  retune: { inputPresent: 'RETUNE_INPUT_PRESENT', inputWritten: 'RETUNE_INPUT_WRITTEN', checkHeld: 'RETUNE_CHECK_HELD' },
+} as const;
+
 /** One side of the check block, read off a check report. */
 export function checkSide(r: CheckReport): CheckSide {
   return {
@@ -458,19 +464,23 @@ export function checkSide(r: CheckReport): CheckSide {
   };
 }
 
-/** Step 7: every bar the input measured is measured on the revision, and no bar the input met is failed by it. */
-export function checkHeldProblems(input: CheckSide, revision: CheckSide, problems: readonly Problem[]): Problem[] {
+/**
+ * Step 7: every bar the input measured is measured on the revision, and no bar the input met is failed by it. `op`
+ * names the revising command (`retune` reuses this reading under its own code, `RETUNE_CHECK_HELD`).
+ */
+export function checkHeldProblems(input: CheckSide, revision: CheckSide, problems: readonly Problem[], op: 'remesh' | 'retune' = 'remesh'): Problem[] {
+  const code = REVISION_CODES[op].checkHeld;
   const out: Problem[] = [];
   for (const bar of input.measured) {
     if (!revision.measured.includes(bar)) {
       const why = revision.skipped.find((s) => s.bar === bar)?.reason ?? 'not measured';
-      out.push({ code: 'REMESH_CHECK_HELD', object: `check bar ${bar}`, detail: `measured on the input and not on the revision (${why}); the revision is held to every bar the input was` });
+      out.push({ code, object: `check bar ${bar}`, detail: `measured on the input and not on the revision (${why}); the revision is held to every bar the input was` });
     }
   }
   for (const bar of revision.not_met) {
     if (input.not_met.includes(bar)) continue;
     const quoted = problems.filter((p) => p.code.includes(bar) || p.object.includes(bar)).map(problemLine);
-    out.push({ code: 'REMESH_CHECK_HELD', object: `check bar ${bar}`, detail: `met on the input and not on the revision${quoted.length > 0 ? `: ${quoted.join(' | ')}` : ''}; a remesh may not fail a bar its input meets` });
+    out.push({ code, object: `check bar ${bar}`, detail: `met on the input and not on the revision${quoted.length > 0 ? `: ${quoted.join(' | ')}` : ''}; a ${op} may not fail a bar its input meets` });
   }
   return out;
 }
@@ -511,24 +521,29 @@ export function modelAttachmentHash(modelText: string, part: string): string | n
   return entry === undefined ? null : createHash('sha256').update(JSON.stringify(entry)).digest('hex');
 }
 
-/** Step 1's tree rules: the files `rig` writes are present, and the two the splice rewrites are this writer's bytes. */
-export function inputTreeProblems(tree: FileTree, root: string): Problem[] {
+/**
+ * Step 1's tree rules: the files `rig` writes are present, and the ones the splice rewrites (`spliced`) are this
+ * writer's bytes. `op` names the revising command, whose codes these are (`retune` splices `rig.json` and `motion.json`).
+ */
+export function inputTreeProblems(tree: FileTree, root: string, op: 'remesh' | 'retune' = 'remesh', spliced: readonly string[] = ['rig.json', 'mesh_report.json']): Problem[] {
+  const present = REVISION_CODES[op].inputPresent;
+  const writtenCode = REVISION_CODES[op].inputWritten;
   const out: Problem[] = [];
   for (const f of RIG_TREE_FILES) {
-    if (!tree.has(f)) out.push({ code: 'REMESH_INPUT_PRESENT', object: `${root}/${f}`, detail: 'is absent; the input revision is the directory rig writes — rig.json, motion.json, mesh_report.json and images/' });
+    if (!tree.has(f)) out.push({ code: present, object: `${root}/${f}`, detail: 'is absent; the input revision is the directory rig writes — rig.json, motion.json, mesh_report.json and images/' });
   }
-  if (![...tree.keys()].some((k) => k.startsWith('images/'))) out.push({ code: 'REMESH_INPUT_PRESENT', object: `${root}/images/`, detail: 'holds no image; the input revision is the directory rig writes' });
-  for (const f of ['rig.json', 'mesh_report.json']) {
+  if (![...tree.keys()].some((k) => k.startsWith('images/'))) out.push({ code: present, object: `${root}/images/`, detail: 'holds no image; the input revision is the directory rig writes' });
+  for (const f of spliced) {
     const b = tree.get(f);
     if (b === undefined) continue;
     let value: unknown;
     try {
       value = JSON.parse(text(b));
     } catch (err) {
-      out.push({ code: 'REMESH_INPUT_WRITTEN', object: `${root}/${f}`, detail: `does not parse as JSON: ${(err as Error).message}` });
+      out.push({ code: writtenCode, object: `${root}/${f}`, detail: `does not parse as JSON: ${(err as Error).message}` });
       continue;
     }
-    if (rigJsonText(value) !== text(b)) out.push({ code: 'REMESH_INPUT_WRITTEN', object: `${root}/${f}`, detail: 'is not the text this package\'s writer prints for its value; the revision is spliced as text, so an input reformatted by hand cannot be carried over byte for byte' });
+    if (rigJsonText(value) !== text(b)) out.push({ code: writtenCode, object: `${root}/${f}`, detail: 'is not the text this package\'s writer prints for its value; the revision is spliced as text, so an input reformatted by hand cannot be carried over byte for byte' });
   }
   return out;
 }

package/src/retune.ts

@@ -0,0 +1,418 @@
+/**
+ * `rig-parts retune` (issue #527): splice the constraints and the idle a config states onto an existing, gated rig,
+ * and write a new package revision beside the input — every other byte of the input carried over, the input never
+ * written. The remesh (`src/remesh.ts`) of physics and motion: a reviewer's damping, wind, strength or
+ * idle-track change reaches the rig without a whole rebuild, which would drop every repair the config does not
+ * reproduce.
+ *
+ * ## The steps, each one a refusal by name
+ *
+ * 1. **The input** ({@link readTree}): `--rig` holds `rig.json`, `motion.json`, `mesh_report.json` and `images/`, as
+ *    `rig` writes them; `rig.json` and `motion.json` must be the bytes this package's writer prints for what they
+ *    parse to (`RETUNE_INPUT_WRITTEN`), since the revision is spliced as text. `--out` must not exist
+ *    (`RETUNE_OUT_FRESH`).
+ * 2. **The rebuild**: the config as written is built through the rig stage — one build, every check it owns — and a
+ *    refusal there is quoted (`RETUNE_CONFIG_REFUSED`).
+ * 3. **The hold** ({@link holdProblems}): the rebuild must state the input's `stops`, `bones` (names, parents,
+ *    transforms, `inherit`), `slots`, `skeleton` and `images`, every image file, every `invariants` entry but
+ *    `detached`, and every byte of `motion.json` but `animations.idle` (`RETUNE_REQUEST_HELD`, naming the first
+ *    difference). A `stops` change rewires bones, slots and weights onto drawn links, so it is no retune. No
+ *    attachment is compared: the input's meshes may be repairs the config does not reproduce, and they are carried
+ *    over as bytes — so a `meshes` change in the config is never read into the revision (`remesh` is its producer).
+ * 4. **The splice** ({@link spliceRevision}): the input's `rig.json` with `constraints` and `invariants.detached`
+ *    (derived from the constraints, rig.ts's `detachedRules`) the rebuild's, and its `motion.json` with
+ *    `animations.idle` the rebuild's; every other file is the input's bytes.
+ * 5. **The preserve assertion** ({@link preservedProblems}): every file but those two byte-identical to the input's;
+ *    `rig.json` identical outside `constraints` and `invariants.detached`, `motion.json` outside `animations.idle`
+ *    (`RETUNE_PRESERVED`, naming the first path that moved).
+ * 6. **The gate and check**: the revision goes through rigc's build gate (`RETUNE_RIGC_GREEN`) and through `check`
+ *    beside the input; every bar the input measured is measured, none the input met is failed (`RETUNE_CHECK_HELD`).
+ * 7. **The write**: `--out` receives the revision's files and {@link RETUNE_FILE} — spec {@link RETUNE_SPEC} — with
+ *    no path and no clock in it, so a second identical request writes the same bytes.
+ *
+ * Pure in the sense `src/` is held to: rigc runs as a process, but the process is injected, as `src/build.ts` takes it.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { checkStage, gateThroughRigc, type Log, rigStage } from './build.ts';
+import { type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackShape, type PageEdges, rigcRanClause, type RigcRunner } from './check.ts';
+import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
+import { type CheckSide, checkHeldProblems, checkSide, checkScope, type FileTree, firstDifference, type HashRow, hashRows, inputTreeProblems, perturbed, readTree, sha256 } from './remesh.ts';
+import { DEFAULT_IDLE_KEYS, type IdleKeys, rigJsonText } from './rig.ts';
+
+/** The provenance file's spec. */
+export const RETUNE_SPEC = 'rig-parts-retune/1';
+
+/** The provenance file, at the revision's root beside `rig.json`. */
+export const RETUNE_FILE = 'retune.json';
+
+/** The two files the splice rewrites; every other file of the input is carried over as bytes. */
+export const RETUNE_SPLICED = ['rig.json', 'motion.json'] as const;
+
+/** What the hold compares between the input and the rebuild (step 3), as the provenance lists it. */
+export const RETUNE_HELD = ['rig.json stops', 'rig.json bones', 'rig.json slots', 'rig.json skeleton', 'rig.json images', 'rig.json invariants but detached', 'images/', 'motion.json but animations.idle'] as const;
+
+/** The provenance's sentence for what the hold does not compare. */
+export const RETUNE_NOT_COMPARED =
+  'every attachment and every mesh_report.json row: carried over from the input as bytes, whether or not the config reproduces it; a meshes change in the config is never read into the revision (remesh is the producer of a mesh)';
+
+export interface RetuneInput {
+  /** The input revision: the directory `rig` wrote (`rig.json`, `motion.json`, `mesh_report.json`, `images/`). */
+  rig: string;
+  /** The config whose constraints and idle the revision takes; every other field must reproduce the input. */
+  config: string;
+  /** The directory holding `parts.json` and `parts/` the input was built from. */
+  parts: string;
+  /** The new revision's directory; it must not exist. */
+  out: string;
+  idleKeys?: IdleKeys;
+  pageEdges?: PageEdges;
+  packShape?: PackShape;
+  requirements?: string;
+}
+
+/**
+ * Planted faults for the selftest (issue #527) — never set by the CLI: `perturb` changes the first uv of the named
+ * part's attachment in the revision after the splice, `skipPreserve` takes the preserve assertion out and `skipHold`
+ * the hold, so the selftest can show what each one stops and what stops the revision without it.
+ */
+export interface RetunePlant {
+  perturb?: string;
+  skipPreserve?: boolean;
+  skipHold?: boolean;
+}
+
+/** One constraint the request changed: its name and type, and each field whose value moved, in the rebuild's order. */
+export interface ConstraintChange {
+  name: string;
+  type: string;
+  fields: string[];
+}
+
+/** `retune.json` (spec {@link RETUNE_SPEC}). */
+export interface RetuneProvenance {
+  spec: typeof RETUNE_SPEC;
+  request: { idle_keys: IdleKeys; page_edges: PageEdges; pack_shape: PackShape };
+  versions: { parts: string; rigc: string };
+  input: { rig: HashRow[]; config_sha256: string; parts_json_sha256: string };
+  held: { compared: string[]; not_compared: string };
+  changed: { constraints: ConstraintChange[]; added: string[]; removed: string[]; idle: { tracks_changed: number; duration: [number, number] } };
+  preserved: { identical: string[]; spliced: string[] };
+  revision: HashRow[];
+  check: { input: CheckSide; revision: CheckSide; scope: string };
+}
+
+export interface RetuneResult {
+  provenance: RetuneProvenance;
+  written: string[];
+}
+
+type Json = Record<string, unknown>;
+
+const isRecord = (v: unknown): v is Json => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (b: Uint8Array): string => new TextDecoder().decode(b);
+const bytesOf = (s: string): Uint8Array => new TextEncoder().encode(s);
+const bytesEqual = (a: Uint8Array | undefined, b: Uint8Array | undefined): boolean => a !== undefined && b !== undefined && a.length === b.length && a.every((x, i) => x === b[i]);
+
+/** A rig's files as the hold and the splice read them: `rig.json` and `motion.json` parsed, `images/` by file. */
+export interface RigFiles {
+  rig: Json;
+  motion: Json;
+  images: Map<string, Uint8Array>;
+}
+
+/** {@link RigFiles} off a tree read by {@link readTree}. */
+export function rigFiles(tree: FileTree): RigFiles {
+  const images = new Map<string, Uint8Array>();
+  for (const [k, b] of tree) if (k.startsWith('images/')) images.set(k, b);
+  return { rig: JSON.parse(text(tree.get('rig.json') as Uint8Array)) as Json, motion: JSON.parse(text(tree.get('motion.json') as Uint8Array)) as Json, images };
+}
+
+/** `invariants` without `detached`, or undefined when nothing else is in it. */
+function invariantsBut(inv: unknown): Json | undefined {
+  if (!isRecord(inv)) return undefined;
+  const rest: Json = {};
+  for (const [k, v] of Object.entries(inv)) if (k !== 'detached') rest[k] = v;
+  return Object.keys(rest).length === 0 ? undefined : rest;
+}
+
+/** `rig.json` without `constraints` and `invariants.detached` — what the preserve assertion holds byte for byte. */
+export function rigOutsideRetune(rig: Json): Json {
+  const out: Json = {};
+  for (const [k, v] of Object.entries(rig)) {
+    if (k === 'constraints') continue;
+    if (k === 'invariants') {
+      const rest = invariantsBut(v);
+      if (rest !== undefined) out[k] = rest;
+      continue;
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+/** `motion.json` without `animations.idle` — what the hold and the preserve assertion hold byte for byte. */
+export function motionOutsideIdle(motion: Json): Json {
+  const out: Json = {};
+  for (const [k, v] of Object.entries(motion)) {
+    if (k !== 'animations' || !isRecord(v)) {
+      out[k] = v;
+      continue;
+    }
+    out[k] = Object.fromEntries(Object.entries(v).filter(([name]) => name !== 'idle'));
+  }
+  return out;
+}
+
+/**
+ * Step 3: what the rebuild must state as the input does. `stops` first, so a stops change is named as one rather than
+ * as the bones it rewires. Each difference names its first leaf; every one is collected.
+ */
+export function holdProblems(input: RigFiles, rebuilt: RigFiles): Problem[] {
+  const out: Problem[] = [];
+  const held = (object: string, what: string, why: string): void => {
+    out.push({ code: 'RETUNE_REQUEST_HELD', object, detail: `the config changes it (${what}); ${why}, so nothing is written — make it a rebuild with rig --config` });
+  };
+  const top = 'a retune replaces constraints and the idle and holds every other byte of the input';
+  const stops = firstDifference(input.rig.stops, rebuilt.rig.stops, 'stops');
+  if (stops !== null) held('rig.json stops', `input vs rebuilt: ${stops}`, 'a stops change rewires bones, slots and weights onto drawn links (<link>_d), which a retune holds');
+  for (const key of ['bones', 'slots', 'skeleton', 'images']) {
+    const d = firstDifference(input.rig[key], rebuilt.rig[key], key);
+    if (d !== null) held(`rig.json ${key}`, `input vs rebuilt: ${d}`, key === 'bones' ? `${top}; a moved, renamed, added or re-inherited bone (a <bone>_ctl among them) moves every weight bound to it` : top);
+  }
+  const inv = firstDifference(invariantsBut(input.rig.invariants), invariantsBut(rebuilt.rig.invariants), 'invariants');
+  if (inv !== null) held('rig.json invariants', `input vs rebuilt: ${inv}`, `${top}; only invariants.detached derives from the constraints`);
+  for (const path of [...new Set([...input.images.keys(), ...rebuilt.images.keys()])].sort()) {
+    const a = input.images.get(path);
+    const b = rebuilt.images.get(path);
+    if (bytesEqual(a, b)) continue;
+    held(path, a === undefined ? 'the rebuild writes it and the input has none' : b === undefined ? 'the input has it and the rebuild writes none' : `input ${a.length} bytes ${sha256(a).slice(0, 12)}… vs rebuilt ${b.length} bytes ${sha256(b).slice(0, 12)}…`, top);
+  }
+  const mi = motionOutsideIdle(input.motion);
+  const mr = motionOutsideIdle(rebuilt.motion);
+  if (rigJsonText(mi) !== rigJsonText(mr)) {
+    held('motion.json', `input vs rebuilt outside animations.idle: ${firstDifference(mi, mr) ?? 'the same value, different bytes'}`, `${top}; spec, archetype, cut, easings, groups and every animation but idle (animations_from, the face deform) are held`);
+  }
+  return out;
+}
+
+/**
+ * Step 4: the revision — the input tree with `rig.json`'s `constraints` and `invariants.detached` and `motion.json`'s
+ * `animations.idle` the rebuild's, each key in the place the rig stage writes it. Every other entry is the input's
+ * own bytes, by reference.
+ */
+export function spliceRevision(input: FileTree, rebuilt: RigFiles): FileTree {
+  const inRig = JSON.parse(text(input.get('rig.json') as Uint8Array)) as Json;
+  const inMotion = JSON.parse(text(input.get('motion.json') as Uint8Array)) as Json;
+  const detached = isRecord(rebuilt.rig.invariants) ? rebuilt.rig.invariants.detached : undefined;
+  const invariantsOf = (inv: unknown): Json | undefined => {
+    // The rig stage writes `detached` after `idleDrivesMeshes` and before `deformMayFold` and `axes` (src/rig.ts).
+    const rest = invariantsBut(inv) ?? {};
+    const out: Json = {};
+    if ('idleDrivesMeshes' in rest) out.idleDrivesMeshes = rest.idleDrivesMeshes;
+    if (detached !== undefined) out.detached = detached;
+    for (const [k, v] of Object.entries(rest)) if (k !== 'idleDrivesMeshes') out[k] = v;
+    return Object.keys(out).length === 0 ? undefined : out;
+  };
+  const rig: Json = {};
+  const put = (k: string, v: unknown): void => {
+    if (v !== undefined) rig[k] = v;
+  };
+  for (const [k, v] of Object.entries(inRig)) {
+    if (k === 'constraints') put(k, rebuilt.rig.constraints);
+    else if (k === 'invariants') put(k, invariantsOf(v));
+    else rig[k] = v;
+    if (k === 'skins' && !('constraints' in inRig)) put('constraints', rebuilt.rig.constraints);
+  }
+  if (!('invariants' in inRig)) put('invariants', invariantsOf(undefined));
+  const animations = inMotion.animations as Json;
+  const motion: Json = { ...inMotion, animations: Object.fromEntries(Object.entries(animations).map(([k, v]) => [k, k === 'idle' ? (rebuilt.motion.animations as Json).idle : v])) };
+  const out: FileTree = new Map(input);
+  out.set('rig.json', bytesOf(rigJsonText(rig)));
+  out.set('motion.json', bytesOf(rigJsonText(motion)));
+  return out;
+}
+
+/** Where two values differ by top-level key, or by attachment under `skins`, so a moved part is named as the part it is. */
+function movedPaths(a: Json, b: Json): Array<{ where: string; diff: string }> {
+  const out: Array<{ where: string; diff: string }> = [];
+  for (const k of [...new Set([...Object.keys(a), ...Object.keys(b)])]) {
+    if (k !== 'skins' || !isRecord(a.skins) || !isRecord(b.skins)) {
+      const d = firstDifference(a[k], b[k], k);
+      if (d !== null) out.push({ where: k, diff: d });
+      continue;
+    }
+    const sa = a.skins;
+    const sb = b.skins;
+    for (const skin of [...new Set([...Object.keys(sa), ...Object.keys(sb)])]) {
+      const pa = isRecord(sa[skin]) ? (sa[skin] as Json) : {};
+      const pb = isRecord(sb[skin]) ? (sb[skin] as Json) : {};
+      for (const slot of [...new Set([...Object.keys(pa), ...Object.keys(pb)])]) {
+        const xa = isRecord(pa[slot]) ? (pa[slot] as Json) : {};
+        const xb = isRecord(pb[slot]) ? (pb[slot] as Json) : {};
+        for (const name of [...new Set([...Object.keys(xa), ...Object.keys(xb)])]) {
+          const where = `skins.${skin}.${slot}.${name}`;
+          const d = firstDifference(xa[name], xb[name], where);
+          if (d !== null) out.push({ where, diff: d });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Step 5, the preserve assertion: every file but `rig.json` and `motion.json` byte-identical in the revision and none
+ * added or dropped; `rig.json` identical outside `constraints` and `invariants.detached`, `motion.json` outside
+ * `animations.idle`, each moved path named.
+ */
+export function preservedProblems(input: FileTree, revision: FileTree): Problem[] {
+  const out: Problem[] = [];
+  const moved = (object: string, detail: string): void => {
+    out.push({ code: 'RETUNE_PRESERVED', object, detail: `${detail}; a retune carries every byte but the constraints and the idle over from the input, so nothing is written` });
+  };
+  const outside: Record<string, { strip: (v: Json) => Json; what: string }> = {
+    'rig.json': { strip: rigOutsideRetune, what: 'constraints and invariants.detached' },
+    'motion.json': { strip: motionOutsideIdle, what: 'animations.idle' },
+  };
+  for (const path of [...new Set([...input.keys(), ...revision.keys()])].sort()) {
+    const a = input.get(path);
+    const b = revision.get(path);
+    if (a === undefined || b === undefined) {
+      moved(path, a === undefined ? 'is in the revision and not in the input' : 'is in the input and not in the revision');
+      continue;
+    }
+    const o = outside[path];
+    if (o === undefined) {
+      if (!bytesEqual(a, b)) moved(path, `is not the input's bytes (input ${a.length} bytes ${sha256(a).slice(0, 12)}…, revision ${b.length} bytes ${sha256(b).slice(0, 12)}…)`);
+      continue;
+    }
+    const x = o.strip(JSON.parse(text(a)) as Json);
+    const y = o.strip(JSON.parse(text(b)) as Json);
+    if (rigJsonText(x) === rigJsonText(y)) continue;
+    const where = movedPaths(x, y);
+    if (where.length === 0) moved(path, `differs from the input outside ${o.what} in its bytes, though not in its value`);
+    for (const w of where) moved(`${path} ${w.where}`, `differs from the input outside ${o.what} — input vs revision at ${w.diff}`);
+  }
+  return out;
+}
+
+/** What the request changed, for the provenance: constraints by name and field, and the idle's tracks and duration. */
+export function changedOf(input: RigFiles, rebuilt: RigFiles): RetuneProvenance['changed'] {
+  const list = (r: Json): Json[] => (Array.isArray(r.constraints) ? (r.constraints as unknown[]).filter(isRecord) : []);
+  const before = new Map(list(input.rig).map((c) => [String(c.name), c]));
+  const after = list(rebuilt.rig);
+  const afterNames = new Set(after.map((c) => String(c.name)));
+  const constraints: ConstraintChange[] = [];
+  for (const c of after) {
+    const was = before.get(String(c.name));
+    if (was === undefined) continue;
+    const keys = [...new Set([...Object.keys(c), ...Object.keys(was)])];
+    const fields = keys.filter((k) => JSON.stringify(c[k]) !== JSON.stringify(was[k]));
+    if (fields.length > 0) constraints.push({ name: String(c.name), type: String(c.type), fields });
+  }
+  const idleOf = (m: Json): { duration: number; tracks: unknown[] } => (m.animations as Json).idle as { duration: number; tracks: unknown[] };
+  const ia = idleOf(input.motion);
+  const ib = idleOf(rebuilt.motion);
+  let tracks = 0;
+  for (let i = 0; i < Math.max(ia.tracks.length, ib.tracks.length); i++) if (JSON.stringify(ia.tracks[i]) !== JSON.stringify(ib.tracks[i])) tracks++;
+  return {
+    constraints,
+    added: after.map((c) => String(c.name)).filter((n) => !before.has(n)),
+    removed: [...before.keys()].filter((n) => !afterNames.has(n)),
+    idle: { tracks_changed: tracks, duration: [ia.duration, ib.duration] },
+  };
+}
+
+/**
+ * The stage: steps 1–7 of the module header. Writes `input.out` only when every step is green; refuses with every
+ * problem of the first step that found one.
+ */
+export function retuneStage(input: RetuneInput, rigc: RigcRunner, checkBin: string, versions: { parts: string; rigc: string }, scratch: string, log: Log, plant: RetunePlant = {}): RetuneResult {
+  const idleKeys = input.idleKeys ?? DEFAULT_IDLE_KEYS;
+  const pageEdges = input.pageEdges ?? DEFAULT_PAGE_EDGES;
+  const packShape = input.packShape ?? DEFAULT_PACK_SHAPE;
+  // 1. The input and the out.
+  const outAt = resolve(input.out);
+  const rigAt = resolve(input.rig);
+  if (existsSync(outAt)) throw new PartsError([{ code: 'RETUNE_OUT_FRESH', object: input.out, detail: 'exists; a revision is written into a new directory, never over the input or an earlier revision' }]);
+  if (!existsSync(rigAt) || !statSync(rigAt).isDirectory()) throw new PartsError([{ code: 'RETUNE_INPUT_PRESENT', object: input.rig, detail: 'is not a directory; the input revision is the directory rig writes' }]);
+  if (outAt.startsWith(`${rigAt}${sep}`)) throw new PartsError([{ code: 'RETUNE_OUT_FRESH', object: input.out, detail: `is inside the input ${input.rig}; a revision is written beside the input, never into it` }]);
+  const tree = readTree(rigAt);
+  refuseIfAny(inputTreeProblems(tree, input.rig, 'retune', RETUNE_SPLICED));
+  const inFiles = rigFiles(tree);
+  // 2. The rebuild.
+  log(`rig-parts retune: ${input.rig}, ${tree.size} file(s); the rebuild is the config as written`);
+  const rebuiltAt = join(scratch, 'rebuild', 'rig');
+  try {
+    rigStage({ config: input.config, parts: input.parts, out: rebuiltAt, idleKeys, pageEdges, packShape }, rigc, join(scratch, 'rebuild', 'gate'), (l) => log(`[rebuild:rig] ${l}`));
+  } catch (err) {
+    if (!(err instanceof PartsError)) throw err;
+    throw new PartsError(err.problems.map((p) => ({ code: 'RETUNE_CONFIG_REFUSED', object: `${input.config} as written`, detail: `the rig stage refuses it, nothing is written: ${problemLine(p)}` })));
+  }
+  const rebuilt = rigFiles(readTree(rebuiltAt));
+  // 3. The hold.
+  if (plant.skipHold !== true) refuseIfAny(holdProblems(inFiles, rebuilt));
+  log(`  held: ${RETUNE_HELD.join(', ')} — the rebuild states each as the input does; no attachment is compared`);
+  const changed = changedOf(inFiles, rebuilt);
+  // 4–5. The splice and the preserve assertion.
+  let revision = spliceRevision(tree, rebuilt);
+  if (plant.perturb !== undefined) revision = perturbed(revision, plant.perturb);
+  if (plant.skipPreserve !== true) refuseIfAny(preservedProblems(tree, revision));
+  const spliced: string[] = [...RETUNE_SPLICED];
+  const identical = [...tree.keys()].filter((k) => !spliced.includes(k));
+  for (const c of changed.constraints) log(`  constraint ${c.name} (${c.type}): ${c.fields.join(', ')} changed`);
+  if (changed.added.length > 0) log(`  constraints added: ${changed.added.join(', ')}`);
+  if (changed.removed.length > 0) log(`  constraints removed: ${changed.removed.join(', ')}`);
+  log(`  idle: ${changed.idle.tracks_changed} track(s) changed, duration ${changed.idle.duration[0]} -> ${changed.idle.duration[1]}`);
+  log(`  preserved: ${identical.length} file(s) byte-identical to the input; rig.json identical outside constraints and invariants.detached; motion.json identical outside animations.idle`);
+  // 6. The gate and check.
+  const pngs = [...revision].filter(([k]) => k.startsWith('images/')).map(([k, b]) => [k.slice('images/'.length), b] as const);
+  const texts = [...revision].filter(([k]) => !k.startsWith('images/')).map(([k, b]) => [k, text(b)] as const);
+  const gate = gateThroughRigc(pngs, texts, rigc, join(scratch, 'gate'), { pageEdges, packShape });
+  for (const g of gate) {
+    log(`  rigc ${g.label}, the revision: exit ${g.status}`);
+    for (const l of g.lines) log(`    ${l.trim()}`);
+  }
+  refuseIfAny(gate.filter((g) => g.status !== 0).map((g) => ({ code: 'RETUNE_RIGC_GREEN', object: `rigc ${g.label} over the revision`, detail: `exited ${g.status}${g.lines.length > 0 ? `: ${g.lines.map((l) => l.trim()).join(' | ')}` : ''}${rigcRanClause(g)}; exit 0 is required before anything is written, and nothing was` })));
+  const staged = join(scratch, 'revision');
+  for (const [k, b] of revision) {
+    mkdirSync(dirname(join(staged, k)), { recursive: true });
+    writeFileSync(join(staged, k), b);
+  }
+  const checkOf = (rig: string, name: string): CheckReport =>
+    checkStage({ rig, parts: input.parts, out: join(scratch, name), pageEdges, packShape, ...(input.requirements === undefined ? {} : { requirements: input.requirements }) }, rigc, checkBin, (l) => log(`[${name}] ${l}`));
+  const inCheck = checkOf(rigAt, 'check-input');
+  const revCheck = checkOf(staged, 'check-revision');
+  const sides = { input: checkSide(inCheck), revision: checkSide(revCheck) };
+  refuseIfAny(checkHeldProblems(sides.input, sides.revision, revCheck.problems, 'retune'));
+  const scope = checkScope(sides.revision.physics);
+  log(`  check: input ${sides.input.pass ? 'PASS' : `FAIL (${sides.input.not_met.join(', ')})`}, revision ${sides.revision.pass ? 'PASS' : `FAIL (${sides.revision.not_met.join(', ')})`}, the same ${sides.revision.measured.length} bar(s) measured; ${scope}`);
+  // 7. The write.
+  const provenance: RetuneProvenance = {
+    spec: RETUNE_SPEC,
+    request: { idle_keys: idleKeys, page_edges: pageEdges, pack_shape: packShape },
+    versions,
+    input: { rig: hashRows(tree), config_sha256: sha256(new Uint8Array(readFileSync(input.config))), parts_json_sha256: sha256(new Uint8Array(readFileSync(join(input.parts, 'parts.json')))) },
+    held: { compared: [...RETUNE_HELD], not_compared: RETUNE_NOT_COMPARED },
+    changed,
+    preserved: { identical, spliced },
+    revision: hashRows(revision),
+    check: { ...sides, scope },
+  };
+  const written: string[] = [];
+  mkdirSync(outAt, { recursive: true });
+  for (const [k, b] of revision) {
+    mkdirSync(dirname(join(outAt, k)), { recursive: true });
+    writeFileSync(join(outAt, k), b);
+    written.push(k);
+  }
+  writeFileSync(join(outAt, RETUNE_FILE), rigJsonText(provenance));
+  written.push(RETUNE_FILE);
+  log('  file                                     sha256 (input)     sha256 (revision)');
+  const inHash = new Map(hashRows(tree).map((r) => [r.path, r.sha256]));
+  for (const r of provenance.revision) log(`  ${r.path.padEnd(40)} ${(inHash.get(r.path) ?? 'absent').slice(0, 16)}   ${r.sha256.slice(0, 16)}${inHash.get(r.path) === r.sha256 ? '' : '  (spliced)'}`);
+  log(`rig-parts retune: wrote ${written.length} file(s) under ${input.out}, the provenance in ${RETUNE_FILE}`);
+  rmSync(staged, { recursive: true, force: true });
+  return { provenance, written };
+}