spine-rigc 0.25.4 → 0.25.6

package/docs/AUTHORING.md

@@ -56,14 +56,18 @@ provenance for a reader of record — the loop that hit a trap, the issue that c
 and following one can arrive at a stored candidate's own spec, at the corpus inventory,
 or at the **derivation** of the gate a verdict is read against, none of which a run may
 open. ⭐ The gate's **clause statements** are a different matter and a run may read them:
-they are in `docs/GATE.md`, item 11 of the allowed list (owner ruling 2026-08-29) — the
+they are in
+[GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md), which is
+repository material and not in the published package — item 11 of the allowed list (owner ruling 2026-08-29) — the
 measure, the comparator, the number and the SKIP semantics, with no recorded figure in it.
 So: read the
 document, take its numbered sections as the input, and leave its footprints to whoever
 is maintaining it. The rule this states is that an **allowed-reading surface has to be
 closed under reading**; the criterion behind it is under *The honesty rule* in
 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md), and the enumerated allowed and forbidden lists are in
-`bench/runs/README.md`, *What a run may read* — the prompt that starts a run quotes them
+[bench/runs/README.md](https://github.com/firejune/rigc/blob/main/bench/runs/README.md),
+which is also repository material and not in the published package,
+*What a run may read* — the prompt that starts a run quotes them
 outright, which is the copy that binds.
 
 ## The vocabulary is Spine's
@@ -156,13 +160,15 @@ What the flags mean:
 | `--rig` | the rig spec — skeleton structure |
 | `--motion` | the motion spec — time |
 | `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths and `skeleton.images` are written relative to it |
-| `--copy-images` | `build` only: also copies every referenced page PNG into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (issue #370; §3.1 says why it is spelled `../<out>/` and not `./`). Default is unchanged — page paths still point at the source art (issue #217) |
+| `--copy-images` | `build` only: also copies every page **the emitted atlas names** into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (issue #370; §3.1 says why it is spelled `../<out>/` and not `./`). Under `--atlas-in` those pages are the pack's, not one per part (issue #693 — **§0.2**). Default is unchanged — page paths still point at the source art (issue #217) |
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. Default is unchanged (issue #4) — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1** |
 | `--padding` | `build --pack` only: the gutter each region reserves on every side (default `2`), filled by extending the region's own edge pixels outwards. `0` is not a legal-but-tight choice, it is bleed — **§0.1** |
-| `--atlas-in` | `build` only: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; the atlas is re-emitted into `--out`, re-anchored — **§0.2** |
+| `--atlas-in` | `build` and `explain`: resolve every part against the **regions of a pre-packed `.atlas`** instead of against loose PNGs. Region geometry is read from the file and sizes are descaled by the page's `scale:`; `build` re-emits the atlas into `--out`, re-anchored, and `explain` writes nothing and poses through it — **§0.2**. On `explain` it is the flag that makes a **size-only** spec readable at all (`ingest --art none`), because posing resolves every attachment against an atlas; without it that pair is refused by name rather than thrown through ([#697](https://github.com/firejune/rigc/issues/697), §5.1) |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order. For `chainfit` it is only where each attachment's image name **resolves**: the candidate decides what the parts are, so extra PNGs are unused and a missing name is refused by name (§12.3) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
+| `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
+| `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 28 validity rules (**the default**) · `spine-html` = all 43, opt-in |
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
@@ -231,7 +237,8 @@ a gap:
 
 - **no resampling, no scaling.** A region's pixels are the loose PNG's pixels.
   rigc writes no `scale:` line, so a pack cannot be coarser than its drawings the
-  way the shipped examples' packs are (§9.4).
+  way the shipped examples' packs are — what a `scale:` costs on the way back in
+  is §0.2.
 - **no trimming.** `offsets:` always states a zero inset and the drawing's full
   size. Stripping transparent border would shrink pages, and it would also make
   every region attachment's quad depend on the packer — measure it yourself if you
@@ -312,6 +319,17 @@ texel count beside it so both numbers are visible:
 measures the PNG. Reach for `--atlas-in` when the pack is what you were handed, or
 when drawing through the pack's own texels is the point.
 
+**What `--out` holds afterwards:** `skeleton.json` and a `skeleton.atlas` that is
+the pack, page paths pointing back at the pack's own PNGs — so `rigc validate
+<that directory>` reads it green with no flags, exactly as it reads a loose
+build's. Add `--copy-images` and the pack's page PNGs are copied in beside the
+skeleton and the page names become their basenames, which is the same directory
+with nothing outside it left to resolve. ⚠️ Until
+[#693](https://github.com/firejune/rigc/issues/693) that flag rebuilt the atlas
+from the parts the rig declared instead of from the pack, and a rebuild through
+`ingest --art none` declares none: the file written was **zero bytes**, on a build
+that printed `PASS` for all four atlas assertions.
+
 The emitted `skeleton.atlas` **is** the imported one, verbatim except for its page
 name lines, which are paths and have to be re-anchored to `--out`. Fields rigc
 does not re-serialise (`format:`, `repeat:`, and `scale:` itself) survive the trip
@@ -335,6 +353,28 @@ One limit, stated rather than discovered:
   pack is a `DROP`, not a refusal — the same documented absence a missing PNG has
   always been, and the line names the atlas rather than a file nobody opened.
 
+⭐ **The missing PNG it is the same rule as, spelled out**, because it was left
+implicit here and the two halves are read together. A `states:` entry whose PNG is
+not on disk is a `DROP` too, and the line names the file rather than the pack:
+
+```bash
+# --atlas-in:  DROP  lens_l/shut: no region "lens_l_shut" in export/atlas.atlas (state not emitted)
+# loose PNGs:  DROP  lens_l/shut: no PNG at parts/lens_l_shut.png (state not emitted)
+```
+
+Either way the slot is emitted **empty** and the build is green — which is right
+while nothing poses that state, and wrong the moment something does. So when the
+setup pose names it, the build is refused, and the refusal names the state and
+what was consulted for it rather than the slot alone (§5.1). ⚠️ Its remedy is
+**not** the `null` the neighbouring message offers: posing `null` builds a rig
+with that part missing, at exit 0 and a green gate. Restore the art, or fix the
+path the manifest states.
+
+🔑 **A refused build prints its `DROP` lines too**, under the refusal on stderr,
+and did not before [#671](https://github.com/firejune/rigc/issues/671): they were
+reported from the compile result and a refusal returns none, so the one output
+naming the file was missing from exactly the run that failed over it.
+
 A **turned** region is not one of them, and used to be (issue #570). A pack made
 by somebody else routinely rotates a region to save space — `rotate: 90`,
 `rotate: 180`, `rotate: 270`, or the format's older `rotate: true` — and rigc
@@ -489,6 +529,17 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   extremes, how far each vertex moved and whether the winding survived
   (**§4.11.2**). It takes no `--profile`, it never gates, and it does not write
   anything — so the figures are readable on a build the gate is refusing.
+
+  ⭐ **It reads what `ingest` writes, given the pack** — `--atlas-in <pack.atlas>`,
+  with `build`'s meaning (§0.2). That matters more here than it looks: printing the
+  `DEFORM` block means **posing** the rig, a pose resolves *every* attachment
+  against the atlas whether or not anything deforms it, and a spec written by
+  `ingest --art none` states sizes and names no image. So the size-only pair
+  `build --atlas-in` gates green is readable here through the same flag, and
+  without it the pair is refused by name at exit 2 rather than posed
+  ([#697](https://github.com/firejune/rigc/issues/697), §5.1). ⚠️ `--profile`,
+  `--pack`, `--page-size`, `--padding` and `--copy-images` are `build`'s and are
+  not here: four of them decide what is *written*, and this command writes nothing.
 - **`diff`** compares two skeletons and reports **a ratio per measure** in six
   sections (bones, slots, attachments, constraints, animations, events). It
   deliberately does not combine them into a score: a rig with the right skeleton
@@ -935,6 +986,12 @@ A skin can also say which bones and constraints it **switches on**, and that nee
 one more level, so a skin entry has a second spelling — see §3.4.1. The short one
 above is unchanged and is what almost every rig wants.
 
+🔸 **`default` is a name, not a requirement.** A rig may put every attachment in
+named skins and declare no `default` at all, which is what an editor export of a
+multi-skin character gives back; rigc still emits a `default` skin, empty, because
+it always does. An animation keying such a slot resolves its attachment names
+against every skin there is — §4.4 states that rule and §5.1 the one refusal left.
+
 🔸 **A skin may fill no slot with anything that needs art, and that build is
 green.** The atlas is built out of what the skins reference, so a rig whose skins
 name no `image` — an empty `default`, or one carrying only a `boundingbox`, a
@@ -1153,6 +1210,110 @@ placed with its centre on the bone the slot names — which is also exactly wher
 plain region attachment with no `x`/`y` would have drawn it. Measured on a ring, a
 ribbon and a moved bone by `CT05` in the selftest (issue #1).
 
+#### `ring` — an aperture that opens inside a pinned seam
+
+**When you need one:** a part with a hole in it that a bone opens and closes — an
+eye, a mouth, an iris. The silhouette stays exactly where the art put it and only
+the inside moves, which is the one thing a `contour` cannot do and authored
+`weights` can only do a vertex at a time.
+
+Three rings and a hub, and every one of them is geometry rigc builds: the part
+window edge and the seam contour are pinned to the slot bone at weight 1, and the
+inner ring is shared with the control bone by a smoothstep falloff — flat at both
+ends, so the deformation dies into the pinned rim instead of creasing against it
+([`src/mesh.ts`](../src/mesh.ts)).
+
+```json
+"generator": {
+  "kind": "ring",
+  "hull": [[24, 8], [40, 8], [56, 24], [56, 40], [40, 56], [24, 56], [8, 40], [8, 24]],
+  "center": [32, 32],
+  "inner": 0.45,
+  "size": [64, 64],
+  "controls": ["iris_aperture"]
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `hull` | **required.** The seam contour, in part-local pixels, y down — the closed outline the aperture sits inside. At least 6 points, every one inside the window, and star-shaped about `center` |
+| `center` | **required.** The aperture centre, part-local pixels, y down |
+| `inner` | **required.** Where the moving ring sits between the centre (`0`) and the hull (`1`), strictly inside that interval. No default: a ring with no number here is refused, not centred |
+| `size` | **required.** The part window, `[w, h]` in pixels, which the UVs and the emitted `width`/`height` are taken from |
+| `bias` | optional; absent means authority is radial only. `{ "axis_deg": <screen degrees, y down>, "ramp": [d0, d1] }` — a line through `center` at that angle, with control authority 0 on its negative side and 1 on its positive side, smoothstepped across the signed distances `d0 < d1`. It is what lets a mouth open downward with the upper lip left pinned |
+| `controls` | **required.** The control bones, by name, at least one. Each must be a bone the rig declares. **More than one splits the ring by angle**, and the angle of each is measured from where the rig put that bone relative to `center` — so the split is a consequence of the skeleton and never a number you write here |
+
+⚠️ **`size` is stated here, not measured.** A `contour` and a `grid` take the
+window off the attachment's own `image`; a `ring` and a `ribbon` are built from
+the numbers in this block and rigc compares neither to the PNG. The emitted
+`width`/`height` are this `size`, so a `size` that is not the art's own scales the
+drawing — measured: a 240x240 part declared `"size": [64, 64]` builds green under
+`--profile spine-html`. That is R1 rather than a gap: the compiler emits the
+number the spec states and does not re-measure a plate to overrule it.
+
+⭐ **Several grips split the ring by where the rig put them, on this route as on
+the manifest one.** Each control bone's angle about `center` is measured from its
+own rest position — the window is centred on the slot bone (the ⭐ above), so a
+bone sitting below the aperture owns the arc below it — and authority is
+smoothstepped between the two bones either side of a vertex, so no grip creases
+against the next. Measured on a two-control ring whose grips sit 12px above and
+below the centre: 25 vertices, both grips bound, and of the 8 shared vertices off
+the centre line all 8 take more weight from the grip on their own side. Splitting
+**moves** authority rather than adding it: every vertex gives its controls the
+same total with one grip, two or three.
+
+⚠️ **This route used to bind only the first name**
+([#684](https://github.com/firejune/rigc/issues/684)). It passed no angles at all,
+so the split collapsed onto `controls[0]` and the rest of the names reached the
+`MESH` line, the bone list and nothing else — and the gate was green, because a
+bone no vertex binds is in no weight, no sum and no index. `A20_MESH_WEIGHTS_COHERENT`
+now names it, so a ring that declares a grip and does not use it is a failure
+rather than a quiet stiffness.
+
+**Stated limits, each a named refusal rather than a mesh that loads wrong:**
+
+| The input | What you get |
+| --- | --- |
+| fewer than 6 hull points | `hull needs at least 6 points, got 4` |
+| `inner` at either end | `inner must be in (0,1), got 1` — at the hull it is the seam, at the centre it is a point |
+| a hull point outside the window | `hull point (99,8) is outside the 64x64 part window` |
+| a hull the centre cannot see all of | `hull is not star-shaped about the aperture centre; the inner ring would fold` — the inner ring is the hull scaled toward `center`, so an edge hidden from it crosses the rim and renders as folded meat |
+| a `bias` ramp that does not increase | `bias ramp must increase, got [16, 4]` |
+| a control bone the rig does not declare | `mesh bone "nobody" is not in the rig's bone list` |
+| two or more `controls`, one of them ON `center` | `control bone "iris_aperture" sits on the aperture centre, so it has no radial direction` — the position a lone control is supposed to occupy is the one position a split cannot use. With a single control it is never asked, so this refusal cannot fire on one |
+| two `controls` at the same angle about `center` | `two control bones share the angle 90 degrees about the aperture centre` — further out is not elsewhere: the arc between them is empty and one of them would bind nothing |
+
+#### `ribbon` — a strip of cross rows riding a bone chain
+
+**When you need one:** a part that hangs and swings off a chain — a tail, a
+strap, a lock of hair, a drip. The strip spans the part window and each cross row
+blends linearly between the two chain knots it falls between, so the whole part
+follows the chain with no weight written by hand.
+
+The entry row is pinned to the slot bone at weight 1, which is what keeps the
+strip's origin where it was authored while the rest of it falls; that is the
+branch `A21_MESH_RIM_PINNED` measures on a ribbon, and
+`A28_RIBBON_ROWS_SHARE_WEIGHTS` is what holds both vertices of a row to the same
+blend.
+
+```json
+"generator": { "kind": "ribbon", "size": [24, 180], "rows": 7, "chain": ["strap_a", "strap_b", "strap_c"] }
+```
+
+| Field | Meaning |
+| --- | --- |
+| `size` | **required.** The part window, `[w, h]` in pixels; the strip spans it, entry row at the top. Stated rather than measured, exactly as a `ring`'s is |
+| `rows` | **required.** How many cross rows, entry row first. A whole number, at least 3; the strip is `2 * (rows - 1)` triangles and `2 * rows` vertices, all of them on the outline |
+| `chain` | **required.** The bone chain the strip rides, **root first**, at least one name. The knots sit evenly along the strip, so the chain's order is the order the part falls in |
+
+**Stated limits:**
+
+| The input | What you get |
+| --- | --- |
+| fewer than 3 rows | `ribbon needs at least 3 rows, got 2` — two rows is one quad and has nothing to bend |
+| an empty `chain` | `ribbon needs at least one chain bone, got 0` |
+| a chain bone the rig does not declare | `mesh bone "nobody" is not in the rig's bone list` |
+
 #### `contour` — the mesh is the art's own silhouette
 
 **When you need one:** the part's outline is the interesting thing and a
@@ -1804,7 +1965,7 @@ rigc emits all five: `ik`
 ([transform constraints](http://esotericsoftware.com/spine-transform-constraints)),
 `path` ([path constraints](http://esotericsoftware.com/spine-path-constraints)),
 `physics` ([physics constraints](http://esotericsoftware.com/spine-physics-constraints))
-and `slider`. Field lists are in [`src/rig.ts`](../src/rig.ts); three traps worth
+and `slider`. Field lists are in [`src/rig.ts`](../src/rig.ts); the traps worth
 carrying here:
 
 - A transform constraint's `properties` names come from a fixed six — `rotate`,
@@ -1819,7 +1980,25 @@ carrying here:
   `scaleY`, spelled `"none"`, `"uniform"` or `"volume"`. It is an enum resolved by
   `Utils.enumValue`, so only the first letter's case is free and an unrecognised
   name is assigned as `undefined` with no error; rigc checks it, like the three
-  path modes below. ⚠️ `src/rig.ts` called the physics one **`scaleYMode`** until
+  path modes below.
+- A physics constraint carries seven **`*Global`** booleans —
+  `inertiaGlobal`, `strengthGlobal`, `dampingGlobal`, `massGlobal`, `windGlobal`,
+  `gravityGlobal` and `mixGlobal` — and "global" is not a scale or a space. Spine
+  4.3 lets a physics timeline name **no** constraint (`animations.<a>.physics[""]`,
+  which the parser reads as constraint index `-1`, `SkeletonJson.js:1048-1053`);
+  such a timeline drives every active physics constraint whose matching flag is
+  `true` and leaves the rest alone (`Animation.js:2066-2072`). So the flag is one
+  constraint's **opt-in to being driven in bulk**, per tuning value, and it does
+  nothing on its own. The parser's default for all seven is `false`.
+  ⚠️ **rigc emits them and cannot emit the timeline that reads them.** Every
+  physics track in a motion spec names its constraint and that name is resolved
+  against the rig — the empty name is refused, `animation "A" keys unknown physics
+  constraint "" (the rig declares: …)` — so the flags are for a player, or a
+  later hand-edit, that supplies one. What rigc does with them is **pass them
+  through**, `false` included: measured, a constraint stating none emits none, and
+  one stating `"windGlobal": false` emits `"windGlobal": false` rather than
+  dropping it the way the motion spec's `physics` table drops a default (§4.6).
+- ⚠️ `src/rig.ts` called the physics `ScaleYMode` key **`scaleYMode`** until
   issue #545 — the runtime's field name rather than the format's key — and nothing
   read it, so a spec that wrote `scaleYMode` set no mode and said nothing. A rig
   that still writes it is now refused by name, with `scaleY` beside it.
@@ -2383,7 +2562,7 @@ that SKIP, because the profile excludes an archetype assertion before its body
 could notice the missing field (§5.2).
 
 🚨 **The exception: `meshSlots` is required by a rig that invokes a mesh
-generator** (`ring`, `ribbon`, `contour` — §3.4), and it is a **compile-time**
+generator** (`ring`, `ribbon`, `contour`, `grid` — §3.4), and it is a **compile-time**
 refusal rather than an assertion. Undeclared means a budget of zero, so the build
 stops before the gate with `N mesh slot(s) emitted but the rig "X" allows 0`.
 Geometry rigc built is geometry rigc will not ship unmeasured; geometry the author
@@ -2391,6 +2570,20 @@ drew is exempt, because rigc did not draw it. So `A13`'s **SKIP** means *this ri
 is unmeasured*, not *this budget is inert* — those are two code paths with one
 name, and reading the SKIP as the whole story is what issue #274 was.
 
+🔗 **`detached` is a list of forbidden parentages**, and its shape is
+`[{ "bone": …, "notUnder": …, "why"?: … }]`. `A25_DETACHED_BONE_PARENTAGE` walks
+`bone`'s parent chain and fails if `notUnder` is anywhere on it — an **ancestor**
+rule, not a direct-parent one, because a bone dragged by its grandparent is
+dragged just the same. A `bone` the rig does not declare is its own failure
+(`the rig declares "X" detached from "Y" but has no such bone`), so a rename that
+leaves this block behind is loud rather than quietly vacuous. `why` is optional
+here — unlike `deformMayFold`'s, which is required, and the difference is what
+each field does: this one turns a check ON for a pair, so an empty reason costs
+nothing but a reader's time. What it is for is a bone whose wrong parentage still
+loads and still animates and merely lies — something released into the world that
+must not ride the part that released it. [RIGGING.md](RIGGING.md) §10.3 has a
+worked one.
+
 🚨 **`deformMayFold` is the one field here that turns a check OFF**, so it is the
 one field whose own shape is refused rather than skipped. It is
 `[{ "slot": …, "why": … }]`, it exempts that slot from
@@ -2715,6 +2908,36 @@ different curves. The same applies to `scale`/`scalex`/`scaley` and
 An `attachment` key carries no easing — attachment timelines are inherently
 stepped.
 
+🔑 **An attachment key resolves against every skin, not against `default` alone.**
+A slot's `attachment` timeline carries a name and **no skin** — the format has no
+field for one — so the names a key may use are the union of every skin's
+placeholders for that slot, the default skin's included.
+`Skeleton.getAttachment` resolves the keyed name at run time through the skin the
+skeleton is **wearing** and, failing that, through `defaultSkin` (spine-core
+4.3.13 `Skeleton.js:335-346`), so which skin's art a key lands on is the
+consumer's, decided by dressing the skeleton rather than by the animation.
+
+- **A name some skins fill and others do not is accepted, and that is the
+  format's own semantics** rather than a hole in the check: under a skin that
+  lacks it the slot shows nothing, which is exactly what a `null` key says and a
+  thing a rig may well mean. What is refused is a name **no** skin holds, and the
+  refusal says which skins were searched and what the slot does have (§5.1).
+- A rig with **no `default` skin at all** — every attachment in named skins,
+  which is the shape an editor export of a multi-skin character gives back — is
+  therefore a rig whose attachment keys work. Until
+  [#695](https://github.com/firejune/rigc/issues/695) it was not: keys were
+  checked against the default skin alone, so a named-skin name was refused as
+  unknown, and a rig with no default skin had **every** attachment key refused,
+  including ones whose art is in the first named skin. The setup pose resolved
+  across skins the whole time (§4.2), so the two halves of one slot disagreed —
+  `slots[].attachment: "plain"` was accepted and a key naming `plain` on that
+  same slot was not.
+- ⚠️ **A `deform` track is the other way round and names its skin outright**
+  (§4.11.5), because the format keys a deform timeline on a `skin/slot/attachment`
+  triple and a deform run is geometry for one attachment object. An attachment
+  timeline has no such field, which is why this one is a union and that one is a
+  lookup.
+
 ### 4.5 `keys` — times, values, curves
 
 - `t` is in seconds and **must strictly increase** after `lag`/`stagger` are added.
@@ -4076,6 +4299,19 @@ at setup, key it somewhere.
 
 Failures arrive in two layers, and they read differently.
 
+📥 **A third surface is `ingest`'s, and it is not a failure at all.** What a skeleton
+holds and the spec format cannot say is **recorded** rather than refused — one coded
+line per finding, and a non-zero exit only when one of them is a blocker (§0.3's gutter
+table is the three kinds); both specs are written either way. So there is no file to
+change for one of those, there is a decision to make. (`ingest` does refuse one thing,
+and it is not about the file's contents: an *option* that contradicts the file, such as
+`--stage` beside a box the skeleton declares.)
+Every code it can print, with its gutter, whether it changes the exit code, what it
+means and what to do, is the finding-code table in `docs/INGEST.md` §2.0. (Spelled
+rather than linked, like the references at the top of this page: that page cites the
+corpus inventory, and a ladder run reads this guide without following its references
+out of it.)
+
 ### 5.1 Compile errors — before the gate
 
 A `CompileError` names the object and the field, and nothing is written.
@@ -4112,6 +4348,40 @@ a real key in the wrong case leads the list), and the shape's whole key set is
 printed after. What it will *not* do is guess — a key four edits from anything gets
 no suggestion, only the set.
 
+⭐ **The scan runs before the required keys are asked for, in both files**, and
+that is what decides which message a *misspelled* required key gets. Misspelling
+one is the commonest way to lose it, so it is refused as the typo it is rather than
+as the thing it lost:
+
+```
+rigc compile error: rig.json: this rig spec has a key this compiler does not read:
+"slot" (did you mean "slots"?). Nothing reads such a key, so it would be dropped
+from the emitted skeleton in silence — fix the spelling or remove it. Known here:
+bones, constraints, events, images, invariants, name, note, skeleton, skins, slots,
+spec.
+```
+
+A key that is **genuinely** absent has no near miss to name, so the scan finds
+nothing and the required-key message below it is what arrives — `a rig spec needs a
+"slots" array (it may be empty; its ORDER is the draw order)` here, and
+`` `animations` is absent; … `` in a motion spec. Read the two apart by that:
+**"does not read"** means the key *is* in your file, spelt some other way, and
+**"needs a …"** / **"is absent"** means it is not in the file at all. Where both
+are true at once — a typo beside a key that really is missing — the typo is named
+first, because it is the one you can fix without re-reading the file. Until
+[#672](https://github.com/firejune/rigc/issues/672) the rig spec's required-key
+checks ran *above* its scan, so `"slot"` for `"slots"` printed the sentence asking
+for an array the file already had, one character off, and never named the stray
+key; the motion spec has always had this order.
+
+⚠️ One check stays above the scan in both parsers: the `spec` version tag. The
+version is what decides *which* key set applies, so a file declaring a version this
+compiler does not know is refused as that — `unknown rig spec version "rigc-rig/2",
+expected "rigc-rig/1"` — rather than key by key against a set it never claimed. The
+price is paid by one spelling: a misspelt `spec` key itself reads as `unknown rig
+spec version undefined, expected "rigc-rig/1"`, which is true and one line short of
+naming the typo.
+
 ⚠️ There is **no forward-compatibility escape**, and no `note` field except where
 one is listed: a rig spec's root, a motion spec's root, an animation, and a
 `physics` tuning entry. Prose anywhere else has to go in a document, because a key
@@ -4163,11 +4433,15 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 
 | Message | What to change |
 | --- | --- |
+| `a rig spec needs a "name" — a motion spec names it to pick this rig` | §3 — name the rig, and make the motion spec's `archetype` equal it |
+| `a rig spec needs a non-empty "bones" array` | §3.2 — a rig with no bones has nothing to hang a slot on; every one has at least a root |
+| `a rig spec needs a "slots" array (it may be empty; its ORDER is the draw order)` | §3.3 — write `[]` for a rig that draws nothing. ⚠️ These three arrive only when the key is really absent: **misspelt**, it is the unknown-key refusal above, naming what you wrote |
 | `bone "X" names parent "Y", which is not declared before it` | move `Y` earlier in `bones` |
 | `two bones are called "X"` | bone names are the join key; rename one |
 | `slot "X" names bone "Y", which this rig does not declare` | add the bone, or fix the slot's `bone` |
 | `no setup pose for slot "X": give the motion spec a \`setup\` entry or the rig slot an \`attachment\`` | R3 — pick one file and declare it there. A slot **nothing** fills is exempt: its setup pose can only be "show nothing" and is not asked for |
-| `the setup pose shows attachment "A" on slot "X", which no skin and no manifest part fills` | §3.3 — the slot is emitted empty, so `A` resolves to nothing. Give the slot an attachment (a skin entry or a manifest part), or state the setup pose as `null` |
+| `the setup pose shows attachment "A" on slot "X", which no skin and no manifest part fills` | §3.3 — the slot is emitted empty and nothing was ever going to fill it, so `A` resolves to nothing. Give the slot an attachment (a skin entry or a manifest part), or state the setup pose as `null` |
+| `the setup pose shows attachment "A" on slot "X", and the slot is emitted empty because the one manifest state that fills it has no art: "s" (no PNG at p)` | §0.2 — a **different** fault with a similar shape: a manifest part does fill this slot and its art was not where the manifest pointed, so every state of it was dropped. **Restore the file or fix the path** — posing `null` compiles, but it ships the rig with that part missing and the gate green. The path printed is the one rigc tried, which is what tells a deleted file from a misspelt `states:` entry; `all N manifest states that fill it have no art` is the same message where the part has more than one. Under `--atlas-in` the same sentence reads `no region "R" in <atlas>` and asks you to add the region to the pack — no file was opened ([#671](https://github.com/firejune/rigc/issues/671)) |
 | `a region needs width and height — give them, or give an "image" and rigc will measure the PNG` | add `image`, or both sizes |
 | `a mesh needs width and height — give them, or give an "image" and rigc will measure the PNG` | §3.4 — the same rule for a mesh |
 | `"type" is null, which is not a name. An attachment's type is one of region, mesh, linkedmesh, … or the key is absent and reads as "region"` | §6 — **remove the key**. Absent is the format's own default; present-and-null matches no parser case and the attachment is dropped in silence |
@@ -4177,13 +4451,18 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `hull vertices must come first; vertex i is on the boundary and vertex j is not. The triangles' outline runs …: list those K vertices first, in that order, then the M interior vertices` | §3.4 — renumber the vertices: the printed walk first, then the interior |
 | `hull vertices must trace the outline in order; the triangles' outline runs …, so vertex a has to follow vertex b in the list, and vertex c does` | §3.4 — renumber along the printed walk |
 | `the triangles do not tile the outline: …` / `the triangles' outline is not one closed loop: …` | §3.4 — a doubled triangle, an unused vertex, a pinch or a hole in `triangles` |
+| `vertex N binds bone "X", which the rig does not declare as a bone` | §3.4 — an authored mesh's `weights` bind by NAME, like everything else in a rig spec. Fix the spelling, or declare the bone. The message names the skin, the slot, the placeholder and the vertex, because an index would name none of them |
 | `image "X.png" is not on disk at …` | fix the name, or point `--images` at the right directory |
+| `parts/iris_open.png is 96x64 but slot "iris" declares 96x60` | R5 — a manifest `states:` entry whose art is not the window the part declares. Re-export the PNG, or fix the part's `size`; a quad sized against art of another size is the silence `A06` exists for, and the window is what the quad is built from |
+| `plates/00_stage.png is 256x256 but the manifest window for "stage" is 250x256` | R5 — the same check on the part's unconditional `image`, against the window the crop gives it |
+| `region "00_stage" of <pack>.atlas (declared 256x256 by its offsets) is 256x256 but the manifest window for "stage" is 250x256` | R5 — the row above under `--atlas-in`, and the prefix is the whole point: it says which of the two rigc **measured**, because the remedy differs. A bare path is a loose PNG it opened and you re-export; a `region … of <pack>` was read out of the pack, and you repack or aim the part at another region. This is the size row of §0.2's four, with the message it actually prints |
 | `duplicate region name "X"` | two PNGs share a basename; one part, one page, one name |
 | `"b/X.png" and the art already atlased as region "X" are two different files — … Rename one of the PNGs.` | R5 — the region name is the basename, so only one of the two can hold it. Rename a file (not a placeholder: the placeholder is free to repeat) |
-| `the image "X.png" was never added to the atlas, so there is no region "X" …` | nothing in the spec — every image an attachment names is measured, so this says rigc skipped one. Report it ([#555](https://github.com/firejune/rigc/issues/555)) |
+| `the image "X.png" was never added to the atlas, so there is no region "X" …` | nothing in the spec — every image an attachment names is measured and atlased, one per file whichever skin names it, so this says rigc skipped one. Report it on [the tracker](https://github.com/firejune/rigc/issues). The `#555` the message itself cites is the change that made one-per-file an invariant, not a place to file against |
 | `motion spec names archetype "A" but the rig spec at … is called "B"` | make `archetype` equal the rig's `name` |
 | `animation "A" declares duration Ns but its last key is at Ms` | R7 — fix whichever of the two you meant |
 | `animation "A" slot "X" attachment: key at Ns is Ms past the declared duration Ds` | §4.5 — the key is past the end of the animation and nothing will sample it. Move the key onto `duration`, or raise `duration` |
+| `animation "A" slot "X" attachment: attachment "N" is not in slot "X" under any skin (searched: default, alt) — the slot has: plain, trim` | §4.4 — the keyed name is in **no** skin, and the two clauses say where the compiler looked and what it would have taken. Fix the spelling, or give some skin a placeholder called `N`. A name only a NAMED skin fills is not this error and never was one to fix — it compiles, and the slot shows nothing under the skins that lack it. Before [#695](https://github.com/firejune/rigc/issues/695) the message read `attachment "N" is not in slot "X"` and was raised against the **default skin alone**, so it fired on correct rigs: any key into named-skin art, and every key in a rig with no default skin. `the slot has no attachments at all` is the same message where nothing fills the slot |
 | `animation "A" keys unknown bone "X"` | the track's `bone` is not in the rig |
 | `animation "A" bone "X" translatex: key value must be an array of 1 number(s)` | the value shape must match the property (§4.4) |
 | `animation "A" physics constraint "C" mass key at t=… is 0 (massInverse Infinity); must be > 0 — …` | §4.4 — a keyed physics value the runtime cannot use. The message names the bound and the `PhysicsConstraint.js` lines that make it one: `mass` and `strength` are `> 0`, `damping` is inside `(0, 1)`, `mix` is `0` or more, and `inertia`/`wind`/`gravity` are bounded nowhere ([#610](https://github.com/firejune/rigc/issues/610)) |
@@ -4254,6 +4533,35 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `slot "patch": placeholder "patch" is filled by the "default" skin AND by skins "zulu", "mike", and the Spine editor has no way to hold that … Move the default skin's entry for this slot into a named skin — call it "base"` | **R12** — do what it says: move that entry out of `default` into a named skin. The editor has no representation for a placeholder the default skin shares with a named one, in either spelling, and §3.4.2 has both measurements. Renaming the placeholder does not help; the shape is what is refused |
 | `N attachment name collision(s): a placeholder that more than one skin fills is emitted with the name "<skin>/<placeholder>" … slot "patch": skin "base" placeholder "zulu/patch" and skin "zulu" placeholder "patch" would both be named "zulu/patch"` | **R12** — rename the placeholder or the skin. rigc composes an attachment name for every placeholder more than one skin fills (§3.4.2), and this fires when a composed name is one another entry in the same slot already answers to — including a plain name in the default skin, which composed nothing. Both sites are named; either rename ends it |
 
+⚠️ **One refusal in this section is not a `CompileError`, and it is `explain`'s.**
+`explain` prints the `DEFORM` block by **posing** the rig, and a pose resolves every
+attachment against the atlas — so it needs the art `build` needs, reached the same
+two ways (§0.2). A pair whose art it cannot resolve is refused **before a line of
+the report**, at **exit 2**, in rigc's own sentence:
+
+```
+rigc explain: skin "default" slot "lamp" placeholder "shade": attachment "shade"
+wants region "shade", which this build's atlas does not have (it declares no region
+at all). `explain` poses the rig to measure its deform keys and a pose resolves
+every attachment against the atlas, so there is nothing to pose it against. Art
+reaches a compile two ways and this run took neither: `--atlas-in <pack.atlas>`
+resolves the parts against a pack somebody already made, and an "image" per
+attachment resolves them as loose PNGs under `--images <dir>` — a spec that states
+a size and names no image is what `ingest --art none` writes, and `--atlas-in` is
+what reads it. 1 of 1 attachment lookup(s) here resolve to no region.
+```
+
+Both halves of it are measured rather than fixed text: the count is this pair's, and
+where the atlas has a **near miss** the sentence prints that too, in `A08`'s own
+clause and `A08`'s own words. When `--atlas-in` **was** given and the region is still
+absent, the second half names the pack instead and asks you to fix the spec's region
+name or point the flag at the pack that has it. Until
+[#697](https://github.com/firejune/rigc/issues/697) there was no rigc sentence at
+all: the report printed in full and the run then died inside `AtlasAttachmentLoader`
+with `Region not found in atlas: shade (attachment: shade)` and a spine-core stack
+trace, at exit 1 — the runtime's message about rigc's internals standing in for
+rigc's message about your two files.
+
 ### 5.2 Assertions — the gate
 
 The report prints one line per assertion:
@@ -4334,7 +4642,7 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) — as it is for `A06`, `A19` and `A27`; see `A07` ([#608](https://github.com/firejune/rigc/issues/608)) |
 | `A18_DETERMINISTIC_EMIT` | both | a second compile of the same inputs differed. That is a compiler bug, not a spec bug — report it |
 | `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art ([#266](https://github.com/firejune/rigc/issues/266)) **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) |
-| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, or a binding at weight 0. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
+| `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not ([#684](https://github.com/firejune/rigc/issues/684)). Fix the rig spec's `controls`/`chain`, or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, a ribbon's entry row, or a contour's outline (which is all of it) is not pinned to its anchor bone at weight 1 |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A23_PHYSICS_CONSTRAINT_EFFECTIVE` | both | a physics constraint that drives no component, is muted by `mix: 0`, has `mass: 0`, has `strength: 0`, or has `damping` outside `(0, 1)` so it never settles — **at rest, and on every physics timeline key** ([#610](https://github.com/firejune/rigc/issues/610)). The timeline arm reads each key through the runtime's own `PhysicsConstraint*Timeline.set`, so a keyed `mass` is judged as the `massInverse` it becomes, and the detail names the animation, the constraint, the key time, the value and the bound. One difference between the two arms, and the runtime is the reason for it: a **key** of `mix: 0` is accepted, because `update` opens with `if (mix === 0) return;` and muting a constraint for a stretch is what a mix timeline is for — the editor's own `sack-pro` example keys it there on 24 of its 36 mix keys. `inertia`, `wind`, `gravity` and the top of `mix` are bounded nowhere, at rest or keyed. **SKIP** when the skeleton declares no physics constraint ([#580](https://github.com/firejune/rigc/issues/580)) — the same sentence `A36` and `A37` have always printed for their own constraint types |
@@ -5657,6 +5965,11 @@ line whenever the MAE is flat and something still looks wrong: a flat MAE says t
 framing and the art agree, and it says nothing at all about whether your shot holds
 and blinks where the reference does.
 
+⭐ **And read it when the MAE is loud, because it is what says *which kind* of loud.**
+It is the only column that separates a wrong curve from a key moved in time — the two
+builds under *The floor every figure here is read against* are that pair, and the
+drift column reports 31.1 px and 32.1 px for them.
+
 ⚠️ **Each set is compared against ITSELF, so on a shot committed at two rates a hold
 can exist in one set and not the other.** The coarse set samples every other frame of
 the fine one, so a pair the coarse set holds across is a constraint between samples
@@ -5721,6 +6034,13 @@ There are two matchers and the `how` column says which one answered:
   confidence: how much better the winning position was than the best rival inside
   the search window. This is what gives a shot like a chain of touching links any
   drift at all — under connected components alone, every frame of it is ambiguous.
+  ⭐ **Only the pixels of it your own composite lets show are correlated**: a
+  template pixel you draw something over cannot match the reference wherever the
+  slot really is, so it adds the same residual at every offset — and, because
+  sliding the template moves those samples onto other pixels, their gradient
+  decides the winner wherever the visible basin is shallow. That is not a
+  hypothetical: it is what made four of the seven examples in this repository
+  report 0.8–2.2 px against frames rendered from themselves (issue #698).
 
 ⚠️ **Both matchers are capped, and a blank is a real answer.** A part can be
 displaced by about its own size and still be that part in the picture; past that,
@@ -5730,11 +6050,157 @@ the 47 px course as its drift. The bar rises with the distance being claimed: a
 peak sitting where you already drew the slot only has to confirm it, a peak
 claiming the part moved most of a radius has to be distinctive to be believed.
 
+⚠️ **And a slot you cover completely has no drift to report at all.** If every
+pixel a slot draws is painted over by something later in your own draw order,
+none of its ink reaches the picture, so there is nothing to correlate — `check`
+says so by name and counts it out, rather than correlating hidden pixels against
+whatever is on top of them:
+
+```
+its drift is not measurable — every one of the 2116 px this 48x54 px slot draws is
+covered by something the candidate draws over it, so none of its own ink reaches the
+picture to be correlated against
+```
+
+That is a fact about the shot and not an error: a part behind another part is
+still where the rig put it, and the answer to *where did it land* is that this
+run cannot say. Read it beside the `slots` column, which counts it as
+unattributed.
+
 The `slots` column is how many of the slots you drew got an answer at all, and the
 summary line carries the same denominator. `N reference component(s) no slot
 reaches` means the reference frame contains something none of your slots overlaps:
 a part you have not authored, or one you have put somewhere else entirely.
 
+🚩 **The floor every figure here is read against, and how to measure it.** `check`
+grades nothing — `rigc check --help` says so, and the exit code is 0 on any run that
+could be made — so a figure means something only beside one you took yourself. The
+cheapest one to take is the **identity run**: a build compared against frames
+rendered from that same build. It is what this instrument says when the true answer
+is *nothing moved*.
+
+```bash
+bun cli.ts build  --rig gallery/squash/rig.json --motion gallery/squash/motion.json --out <build>
+bun cli.ts render --candidate <build> --animation bounce --fps 12 --out <frames>
+bun cli.ts check  --candidate <build> --frames <frames>
+```
+
+```
+  ── bounce — candidate animation "bounce", 12 fps ──
+     frames     11 on disk, candidate samples 11, 11 compared
+     MAE        mean 0.00  worst 0.00 (exact: none of the 11 compared frame(s) differs from the reference)   (0..255 over the union alpha; over the whole frame, mean 0.00)
+                ⤷ over the REFERENCE's own drawn pixels, mean 0.00 — the union figure compares two builds of the same rig; this one is the one to optimise against, because the union is yours to grow.
+     slot drift worst 0.5 px  "plate" at f0004
+                ⤷ bounded by 0.71 px — the correlation put this slot where the candidate drew it, so the whole figure is the sub-pixel step, clamped to 0.5 px on each axis
+     per-frame all 10 adjacent pair(s) change by as much as the reference's own frames do
+```
+
+⚠️ **The MAE floor is zero and the slot-drift floor is not**, and the second half of
+that is the instrument's own arithmetic rather than anything about your rig. Both
+sides are the same pixels, so every frame's MAE is exactly 0 — which is why the line
+says `(exact)` instead of naming a frame. The drift is a **correlation**: it finds
+the whole-pixel offset that matches best and then fits a parabola through three
+whole-pixel residuals for the fraction, clamped to half a pixel on each axis.
+
+🔑 **So the bound has two halves, and the run states both of them for you.** The
+`⤷ bounded by` line is not a constant off this page: it is `hypot(|dx| + 0.5,
+|dy| + 0.5)` for that match's own whole-pixel winner `(dx, dy)`. A winner at the
+offset you drew — which is the answer on every frame of a correct rig — bounds the
+whole figure at `hypot(0.5, 0.5) = 0.71 px`, and the line says the figure is the
+sub-pixel step and nothing else. A winner one pixel out bounds it at 1.58 px and
+says the correlation moved the part. ⇒ **Read a drift against the line under it,
+never against a number from a page about another rig.** A component match prints
+the other sentence — two centroids have no such bound, only the search radius.
+
+🚨 **The clamp bounds the figure only while the whole-pixel winner is the
+identity, and for a while nothing checked that second half.** Issue #698: four of
+the seven examples in this repository read **0.81, 1.11, 2.13 and 2.21 px** against
+frames rendered from themselves, because the template carried the pixels the
+candidate draws *over itself*. Those match nothing wherever the slot really is, so
+they add a residual at every offset — and sliding the template moves them onto
+other pixels, so their gradient walks the winner off the origin wherever the
+visible basin is shallow. The exhaustive whole-pixel field for `flex`'s backdrop
+had its minimum at `(2, 0)` scoring 7.75 against the identity offset's 8.76.
+Correlating only what shows put all seven back on `(0, 0)`, and `C25`–`C30` of
+the repository's own selftest gate that over every example it ships — so the next
+one is gated by arriving.
+
+🔸 The same page said `3.7 px` before issue #678, for an unrelated reason worth
+keeping: the coarse sweep started at `−radius` and stepped by its stride, so the
+identity offset was on the lattice only when the stride divided the radius, and
+the `±1` refinement around a winner two pixels out could not reach back to it.
+
+**A second example, and the one the repair was measured on.** `gallery/flex` draws
+a banner and a leaf over a full-stage backdrop, so almost every slot of it reaches
+the template matcher:
+
+```bash
+bun cli.ts build  --rig gallery/flex/rig.json --motion gallery/flex/motion.json --out <build>
+bun cli.ts render --candidate <build> --animation wave --fps 12 --out <frames>
+bun cli.ts check  --candidate <build> --frames <frames>
+```
+
+```
+  ── wave — candidate animation "wave", 12 fps ──
+     frames     30 on disk, candidate samples 30, 30 compared
+     MAE        mean 0.00  worst 0.00 (exact: none of the 30 compared frame(s) differs from the reference)   (0..255 over the union alpha; over the whole frame, mean 0.00)
+                ⤷ over the REFERENCE's own drawn pixels, mean 0.00 — the union figure compares two builds of the same rig; this one is the one to optimise against, because the union is yours to grow.
+     slot drift worst 0.2 px  "plate" at f0009
+                ⤷ bounded by 0.71 px — the correlation put this slot where the candidate drew it, so the whole figure is the sub-pixel step, clamped to 0.5 px on each axis
+     per-frame all 29 adjacent pair(s) change by as much as the reference's own frames do
+```
+
+That figure was **2.21 px** on the same command before #698, on the same slot.
+
+⭐ **And the same frames plus two deliberately wrong builds are what say which column
+answers which question.** Each differs from the build above in exactly one way —
+every easing reversed `(x1,y1,x2,y2) → (1−x2,1−y2,1−x1,1−y1)`, and the ball's bottom
+key moved from 0.4 s to 0.62 s — and each is checked against the same identity
+frames. Both gate green and both exit 0.
+
+**No run reproduces this:** the candidate is `gallery/squash` with the three curves in its `easings` block reflected through the diagonal, which is an edit to a spec this repository does not carry a second copy of
+
+```
+  ── bounce — candidate animation "bounce", 12 fps ──
+     frames     11 on disk, candidate samples 11, 11 compared
+     MAE        mean 6.69  worst 11.71 at f0007   (0..255 over the union alpha; over the whole frame, mean 5.74)
+                ⤷ over the REFERENCE's own drawn pixels, mean 6.69 — the union figure compares two builds of the same rig; this one is the one to optimise against, because the union is yours to grow.
+     slot drift worst 31.1 px  "ball" at f0006
+     per-frame 1 of 10 adjacent pair(s) change by a different amount than the reference does; worst f0010, yours moved 4152 px where the reference moved 912
+```
+
+**No run reproduces this:** the candidate is `gallery/squash` with the ball's `translatey` key at 0.4 s moved to 0.62 s, which is an edit to a spec this repository does not carry a second copy of
+
+```
+  ── bounce — candidate animation "bounce", 12 fps ──
+     frames     11 on disk, candidate samples 11, 11 compared
+     MAE        mean 2.15  worst 6.38 at f0007   (0..255 over the union alpha; over the whole frame, mean 1.84)
+                ⤷ over the REFERENCE's own drawn pixels, mean 2.15 — the union figure compares two builds of the same rig; this one is the one to optimise against, because the union is yours to grow.
+     slot drift worst 32.1 px  "ball" at f0007
+     per-frame all 10 adjacent pair(s) change by as much as the reference's own frames do
+```
+
+⇒ **`per-frame` is the column that separates a wrong curve from a moved key, and it
+is the only one of the three that does.** The `MAE` says both are wrong and says it
+threefold louder for the curve (6.69 against 2.15). `slot drift` cannot tell them
+apart at all — 31.1 px against 32.1 px, the same part, a frame either side — because
+both put the ball somewhere it is not at the moment being compared. `per-frame` fires
+on the reversed easings alone, and it is measuring the one thing the two defects do
+not share: how far each side moved **since its own previous frame**. A key moved in
+time changes *when* the poses arrive and not how fast the shot travels between two
+samples, so the column is correctly silent on it. ⇒ Read the pair together: a loud
+MAE with `per-frame` silent is a pose in the wrong place or at the wrong moment; a
+loud MAE with `per-frame` firing is a **speed**, which is a curve.
+
+🔸 Neither block above reprints its own `⤷ bounded by` line, for the same reason
+both carry the declaration: the spec edits are not in the tree, so those two lines
+would be hand-written rather than taken. What the gate measures on them is stated
+instead — the worst match of each sits at whole-pixel `(0, −31)` and `(0, −32)`,
+which bounds them at **31.50 px** and **32.50 px**. That is the contrast worth
+carrying away: a correct rig's drift is bounded by the clamp because its winner is
+the identity, and these two are bounded by nothing of the kind because a part
+really moved.
+
 **The `chains` block is the same two measures on the unit you actually repair.**
 
 ```