spine-rigc 0.2.1 → 0.4.0

package/docs/AUTHORING.md

@@ -18,13 +18,33 @@ that can see that, and a run that skips it has verified nothing about the motion
 - Formats and CLI reference: [README.md](../README.md)
 - The rig spec's own source-level documentation: [`src/rig.ts`](../src/rig.ts)
 - The motion spec and emitted shapes: [`src/types.ts`](../src/types.ts)
-- What the format holds and rigc covers: [SPEC_COVERAGE.md](SPEC_COVERAGE.md)
+- What the format holds and rigc covers: `docs/SPEC_COVERAGE.md` — 🚫 **not an
+  authoring input, and deliberately unlinked**: it inventories the benchmark corpus
+  skeleton by skeleton, so it is on the ladder run's forbidden list. Named here for a
+  maintainer, not offered to a run
 - Reproducing a shot you were given as pictures: **§8**, and read it *before* you
-  start measuring rather than after; then **§9** for the loop that closes it
+  start measuring rather than after; **§8.1** if the figure has more joints than you
+  can measure one at a time; then **§9** for the loop that closes it
 - The conventions an editor user follows without being told — one image per
   attachment, keying practice, curve kind, draw order — sourced from Spine's own
   public documentation: **§10**
 
+🔒 **A ladder run reads this guide in full and does not follow its references out of
+it.** The guide is allowed reading; not everything it cites is. Citations here are
+provenance for a reader of record — the loop that hit a trap, the issue that closed it —
+and following one can arrive at a stored candidate's own spec, at the corpus inventory,
+or at the gate a verdict is read against, none of which a run may open. 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](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
+outright, which is the copy that binds.
+
+If you were given no brief and no frames — you are rigging somebody's own art rather
+than reproducing a measured shot — none of this applies to you. It is the ladder's
+protocol, not a property of the tool.
+
 ## The vocabulary is Spine's
 
 Wherever rigc has no better abstraction it uses **Spine 4.3's own concept, its own
@@ -59,6 +79,7 @@ bun cli.ts check \
   --frames    path/to/reference/frames
 
 # read the table → fix the spec → build again → check again
+#   ↳ read its per-frame column before its MAE — §9.2
 ```
 
 `build` compiles, round-trips the result through `@esotericsoftware/spine-core`,
@@ -72,6 +93,18 @@ the animation is the one in the frames, and there is no assertion that could —
 §9. The two run in that order because `check` needs artifacts on disk and `build`
 only writes them when the gate is green.
 
+🚨 **Read `check`'s per-frame column before its MAE.** The table's headline figures
+are the MAE and the slot drift, and a reader who came for those will skip the
+`per-frame` line printed under them — but that line is the only thing in this
+toolchain that can see a **hold**, a **loop seam** or a **one-frame event**. Those
+defects are cheap in every single frame and wrong only in the relation between two,
+so an aggregate MAE, `diff` and the gate are all silent on them: a candidate can
+slope a line through a frame pair the reference holds perfectly still across, or
+end a cycle on a pose that is not the pose it began on, without moving a decimal
+anywhere else in the loop. **§9.2** documents the column. It is named here because
+§0 is where the loop is learned, and a run that opens a report for its chain table
+can come away with the column unread.
+
 What the flags mean:
 
 | Flag | Meaning |
@@ -81,7 +114,7 @@ What the flags mean:
 | `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths are written relative to it |
 | `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory) |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
-| `--profile` | `spine` = the 18 validity rules · `spine-html` = all 32 (**the default**) |
+| `--profile` | `spine` = the 20 validity rules · `spine-html` = all 34 (**the default**) |
 
 Pick the profile deliberately. `spine-html` adds one renderer's policy and one
 project's canvas budget, and those rules fire on perfectly correct Spine data
@@ -257,6 +290,14 @@ behind it writes literal `x`/`y` instead.
 `spec` must be exactly `"rigc-rig/1"`. `name` must be a non-empty string. `bones`
 must be non-empty. `slots` must be present (it may be empty).
 
+🚫 **Every example value below is invented.** Names, coordinates, vertex lists and
+payloads in this guide are written to illustrate a field, never copied out of a
+reference export — an example lifted from one would be handing an authoring agent an
+answer to the rung it is standing on, which is the rule §10.6 states and the honesty
+rule in [LADDER.md](LADDER.md) turns on. If a snippet here matches a reference file,
+that is a defect in this guide: report it. (It has happened — 2026-08-23; the incident
+is recorded in `bench/runs/README.md`, *What a run may read*.)
+
 ### 3.1 `skeleton` — the header
 
 | Field | Spine meaning | Default |
@@ -349,9 +390,9 @@ Geometry comes in one of two fields:
 
 ```json
 "weights": [
-  [{ "bone": "tail3", "x": 184.91, "y": -2.83, "weight": 0.006 },
-   { "bone": "tail4", "x": 92.72,  "y": -2.83, "weight": 0.994 }],
-  [{ "bone": "tail4", "x": 84.66,  "y": -8.47, "weight": 1 }]
+  [{ "bone": "link_a", "x": 40, "y": 0,  "weight": 0.25 },
+   { "bone": "link_b", "x": -20, "y": 0, "weight": 0.75 }],
+  [{ "bone": "link_b", "x": -60, "y": 12, "weight": 1 }]
 ]
 ```
 
@@ -393,6 +434,59 @@ they encode a deformation model rather than a table of numbers, which is why the
 are code invoked by data. A generator is for a skeleton with **no** manifest; a cut
 that has one invokes the same builders through the manifest's `mesh` block.
 
+**Bounding box** ([Spine: bounding boxes](http://esotericsoftware.com/spine-bounding-boxes))
+and **clipping** ([Spine: clipping](http://esotericsoftware.com/spine-clipping))
+attachments — a polygon, and nothing else.
+
+**When you need one:** a *bounding box* is a shape the game hit-tests against — a
+hurt box, a pick region, a trigger volume — that follows the skeleton and draws
+nothing. A *clipping* attachment is a **mask**: everything drawn from the slot
+carrying it up to and including `end` is clipped to the polygon, so a window, a
+portal or a wipe is one attachment rather than a second set of art.
+
+```json
+"hitbox_a": { "hitbox_a": { "type": "boundingbox", "vertexCount": 4,
+                            "vertices": [-30, -10, 30, -10, 30, 50, -30, 50] } },
+"mask_a": { "mask_a": { "type": "clipping", "end": "box", "vertexCount": 3,
+                        "vertices": [0, 0, 200, 0, 0, 160],
+                        "color": "ff00ffff" } }
+```
+
+Both polygons above are invented — an axis-aligned rectangle and a right triangle,
+in round numbers, so that nothing here can be mistaken for a shape measured off a
+reference. A real one is measured off your own art (§8) or drawn to the volume the
+game needs.
+
+| Field | Meaning |
+| --- | --- |
+| `vertexCount` | **required.** How many vertices the polygon has, stated outright — see the warning below |
+| `vertices` / `weights` | the same two encodings a mesh's geometry uses, with the same by-name default and the same `"boneIndexing": "raw"` opt-in |
+| `color` | `rrggbbaa`; the colour the editor draws the outline in |
+| `end` | clipping only. The **last** slot the clip applies to, by name |
+| `convex`, `inverse` | clipping only, 4.3, both default false |
+
+🚨 **`vertexCount` has no parser default and rigc will not infer one.** A mesh gets
+its count from `uvs.length`; a polygon has no uvs, and the parser reads
+`map.vertexCount << 1` as the number of coordinates to expect. With the field
+absent that is `undefined << 1` = **0**, so the coordinate array is decoded as a
+*weighted* run — bone counts and weights read out of your x/y pairs — and the
+attachment ends up holding nothing. It loads. Neither type draws a pixel, so
+nothing downstream notices. rigc requires the count and cross-checks it against
+whichever encoding you used; `A33_VERTEX_ATTACHMENT_GEOMETRY` checks it again on
+the artifact.
+
+⚠️ **A clipping `end` that names nothing is not an error to Spine.**
+`skeletonData.findSlot` returns `null` on a miss and the parser assigns that null
+without a word, so the clip never ends — it runs to the bottom of the draw order
+and takes every slot below it out of the frame. rigc refuses a name the rig does
+not declare. Omitting `end` entirely is the format's own way of saying "clip
+everything after this one", and is left alone.
+
+🚫 Under the default `spine-html` profile a clipping attachment is refused by
+`A11_NO_CLIPPING_ATTACHMENTS` — that renderer skips them silently, so a mask that
+was supposed to hide something would not. It is valid Spine and `--profile spine`
+accepts it; the refusal is policy, not validity.
+
 ### 3.5 `constraints` — 4.3's single typed array
 
 Spine 4.3 folds every constraint into one `constraints` array with a `type`
@@ -413,7 +507,38 @@ Field lists are in [`src/rig.ts`](../src/rig.ts); three traps worth carrying her
   them parses cleanly and does nothing at all. rigc refuses it up front, and `A23`
   catches it from the other side.
 
-### 3.6 `invariants` — what the artifact cannot say about itself
+### 3.6 `events` — names the animation can fire
+
+**When you need one:** something outside the skeleton has to happen on a
+particular frame — a footstep sound, a spawn, a hit window opening. Spine
+[events](http://esotericsoftware.com/spine-events) carry no rendering effect at
+all; they are a named signal the game listens for, with an optional payload.
+
+The **declaration** lives here, in the rig spec, because the name is structure.
+The **firings** live in the motion spec (§4.8), because when they happen is time.
+
+```json
+"events": {
+  "cue_a": {},
+  "cue_b": { "audio": "cue_b.ogg", "volume": 0.8, "string": "line-01" }
+}
+```
+
+An object keyed by event name — the one top-level collection in the format that
+is not an array. Every field is optional and each is the payload a firing
+**inherits** when it does not override it: `int` (0), `float` (0), `string`
+(`""`), `audio` (none), `volume` and `balance`.
+
+- **An empty object is the normal case, not a stub.** Most events carry no payload:
+  the name *is* the signal, and the declaration exists so the firings in §4.8 have
+  something to resolve against. Write `{}` and move on.
+- ⚠️ `volume` and `balance` are read **only when `audio` is set**. Without an
+  audio path the parser drops them without a word, so rigc refuses that pairing
+  rather than emitting two numbers no runtime will read.
+- An event that nothing fires is legitimate: a skeleton may declare the vocabulary
+  its game listens for and key only some of it in any one animation.
+
+### 3.7 `invariants` — what the artifact cannot say about itself
 
 Optional, and only meaningful for rigc's own formations: `meshSlots` and
 `meshTriangles` (the two halves of the mesh budget `A13` measures against),
@@ -456,6 +581,7 @@ time puts it here.
 | `note` | free text |
 | `tracks` | the timelines |
 | `drawOrder` | the draw-order timeline — §4.7. Not a track: it names no target |
+| `events` | the event timeline — §4.8. Not a track, for the same reason |
 
 `groups` (`name → [member, …]`) lets one track target several bones or slots at
 once; `lag` shifts every key of a track, and `stagger` adds a per-member delay in
@@ -496,6 +622,39 @@ stepped.
   Seconds, not frames: nothing requires a key to land on any frame grid, and a
   reference rendered at some rate says nothing about where its keys are. Put keys
   where the motion changes.
+- **Key times are quantised onto a 1e-6 s grid by rounding DOWN, never to
+  nearest.** A key time is a position against the sample grid a player will step,
+  and the two directions of a half-step error are not the same size. `2/12 s` and
+  `5/30 s` are both 0.16666666…; `0.166667` is *larger* than either, so a key
+  emitted there is applied at sample **3** of a 12 fps playback and not sample 2 —
+  a whole frame late, with nothing raised. On a **stepped** timeline (an attachment
+  timeline always is) that is the wrong picture rather than a slightly wrong value:
+  the spineboy run's muzzle flare fired a frame late for exactly this until the
+  run's own frame check caught it (issue #99). Rounding down cannot do that; the
+  worst it can do is put a key a millionth of a second early, on the sample it was
+  written for. ⚠️ What this does **not** protect you from is rounding your own
+  times before you write them — write `2/12`, not `0.1667`, and let the compiler
+  do the quantising.
+- 🚨 **Nor does it protect a stepped key whose time is ALREADY on the 1e-6 grid.**
+  Rounding down leaves such a time exactly where you wrote it, and the sampler does
+  not arrive there: a player — and `sampleAnimation`, and therefore `check` — reaches
+  sample *i* by accumulating `1/fps` *i* times, which for many *i* lands a few ULPs
+  **below** `i/fps`. `2/12` is saved by the rule above precisely because it is *not*
+  on the grid; `0.25`, `0.5`, `0.75`, `1` and every other multiple of `0.25 s` is, and
+  a stepped key there sits above the sample that was meant to see it. On an
+  interpolated timeline that costs a few ULPs of value and nothing else. On a
+  **stepped** one it is the whole frame — and on the last sample it is the whole
+  event, because there is no later sample to catch it. Measured on rung 5's 6.5 s
+  shot at 12 fps: **13 of its 78 sample times are affected** (f6, f15, f18, f21, f24,
+  f27, f60, f63, f66, f69, f72, f75, f78), and an attachment key written at the
+  declared duration `6.5` never fired at all against an accumulated
+  `6.499999999999994` — which read as a frame-change disagreement the pose series had
+  already fixed, and cost that run three builds
+  ([`2026-08-26-rung5-1`](../bench/runs/2026-08-26-rung5-1/LOOP.md), §8). ⇒ **For a
+  stepped timeline, write `T − 1e-6` rather than `T`.** One grid step early cannot
+  reach the previous sample — 83,333 µs away at 12 fps — and is always seen by the
+  sample it was written for; one ULP late loses the frame. This is the same asymmetry
+  the rule above turns on, one grid step further in.
 - **No key may land past the animation's `duration`.** Nothing that plays the
   animation for the duration it declares ever reaches such a key, so it is a
   compile error — checked on **every timeline**, not just on the latest key in the
@@ -578,6 +737,53 @@ the emitted file is the parser's requirement rather than a decision of yours, so
 you state the set of moves and rigc writes them in the order the parser needs.
 `A31_DRAW_ORDER_OFFSETS_RESOLVE` checks all four from the other side.
 
+### 4.8 `events` — firing a declared event
+
+The second timeline that names no target, and it sits on the animation for the
+same reason `drawOrder` does: 4.3 writes it as `animations.<a>.events`, beside
+`bones` and `slots`.
+
+```json
+"animations": {
+  "walk": {
+    "duration": 1.0666666,
+    "loop": true,
+    "events": [
+      { "t": 0, "name": "cue_a" },
+      { "t": 0.5333333, "name": "cue_a", "int": 2 }
+    ],
+    "tracks": []
+  }
+}
+```
+
+- `name` must be a key of the rig spec's `events` block (§3.6). A miss is a
+  compile error here; in raw JSON the parser **throws** `Event not found` in the
+  consumer's process, which is late.
+- `int`, `float` and `string` override the declaration's payload **for this firing
+  only**. Omit them and the firing inherits the declared defaults, which is what
+  the editor writes.
+- `volume` and `balance` are accepted only on an event that declares `audio`, for
+  the same reason as §3.6.
+- Event keys are **instantaneous** and carry no `ease` or `curve`.
+- Its last key counts towards the declared duration like any other (R7).
+
+rigc refuses three things here, and only the first is loud in the parser:
+
+| You wrote | You get |
+| --- | --- |
+| a name the rig spec does not declare | `event "X" is not declared in the rig spec's "events" block; declared: …` |
+| a key time earlier than the key before it | `key times must not go backwards (at t=0.25, after t=0.5)` |
+| `volume`/`balance` on an event with no `audio` | `volume is set but event "X" declares no "audio"` |
+
+The ordering rule is **non-decreasing**, not strictly increasing: two different
+events on one frame is an ordinary thing to want, and unlike a value track there
+is no contradiction in it. What is refused is going *backwards* —
+`readAnimation` fills frame `i` from key `i` in array order and never sorts, so a
+decreasing time builds an `EventTimeline` whose earlier firing is simply
+unreachable, with a perfectly clean load.
+`A32_EVENT_KEYS_RESOLVE` checks all three from the other side.
+
 ---
 
 ## 5. Reading a failure
@@ -609,6 +815,12 @@ the frequent ones, verbatim:
 | `animation "A" has two tracks on X.property; merge them into one track` | one timeline per target property |
 | `no stage size: give the rig spec a \`skeleton.width\`/\`skeleton.height\`` | §3.1 |
 | `drawOrder at t=…: slot "X" is not one this rig emits` / `is offset twice in one key` / `puts it at N, outside the … emitted slots` | §4.7 |
+| `events at t=…: event "X" is not declared in the rig spec's "events" block` | declare it in the rig spec (§3.6), or fix the name |
+| `events: key times must not go backwards` | put the firings in time order (§4.8) |
+| `events at t=…: volume is set but event "X" declares no "audio"` | drop `volume`/`balance`, or give the event an audio path |
+| `vertexCount is undefined; a polygon needs at least 3 vertices, stated outright` | give the bounding box or clipping attachment a `vertexCount` (§3.4) |
+| `vertexCount N wants M unweighted numbers and "vertices" holds K` | fix the count or the array; they decide the encoding between them |
+| `end names slot "X", which this rig does not declare` | fix the clipping attachment's `end`, or add the slot |
 | `bone "X" takes its position from …, which needs a cut manifest` | R8 — pass `--manifest`, or write literal `x`/`y` |
 
 ### 5.2 Assertions — the gate
@@ -668,6 +880,8 @@ The report prints one line per assertion:
 | `A29_STROKE_WITHIN_CONTACT_DEPTH` | archetype | the animation drives deeper than the manifest's measured contact depth |
 | `A30_STROKE_WITHIN_CAP_CONTAINMENT` | archetype | the animation drives past the measured containment ceiling, or scales a bone in the axis subtree |
 | `A31_DRAW_ORDER_OFFSETS_RESOLVE` | both | a draw-order key names a slot the skeleton does not have, offsets one slot twice, puts a slot outside the slots array, or lists its offsets out of slot order (§4.7). The only assertion that runs **before** `A00` — the last of those shapes makes the loader spin rather than return, so the round trip is refused instead of attempted |
+| `A32_EVENT_KEYS_RESOLVE` | both | an event key fires a name the skeleton's `events` block does not declare, sits earlier in time than the key before it, or sets `volume`/`balance` on an event with no `audio` (§4.8). **SKIP** when no animation carries an event timeline |
+| `A33_VERTEX_ATTACHMENT_GEOMETRY` | both | a bounding box or clipping polygon whose `vertexCount` is missing or disagrees with its vertex array, a weighted run that decodes to the wrong number of vertices or an out-of-range bone index, or a clipping `end` naming a slot the skeleton does not have (§3.4). **SKIP** when the skeleton carries neither type |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.
@@ -681,9 +895,14 @@ a **`NotImplementedError` naming the field**, because the parser's own behaviour
 worse: an unknown attachment `type` returns `null` and the attachment disappears,
 and a constraint entry with an unrecognised `type` matches no case and vanishes.
 
+Each is deferred for a stated reason, and the reason is the same one in every row:
+**not one of these types appears anywhere in the benchmark corpus** (SPEC_COVERAGE
+parts 3-1 and 4-2), so none of them is on the ladder's critical path. The message
+says so, because a deferral without its reason is a wall rather than a work item.
+
 | You wrote | You get |
 | --- | --- |
-| attachment `type` of `boundingbox`, `point`, `clipping`, `path`, `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh.` |
+| attachment `type` of `point`, `path`, `linkedmesh` | `attachment type "X" is in the Spine 4.3 format and rigc does not emit it yet. Implemented: region, mesh, boundingbox, clipping. point, path and linkedmesh are deliberately deferred: not one of them appears anywhere in the benchmark corpus …` |
 | constraint `type` of `path` or `slider` | `constraint type "X" … Implemented: ik, transform, physics.` |
 | mesh `generator.kind` of `contour` | `the "contour" generator would triangulate a part's own alpha mask, and src/mesh.ts has no triangulator` |
 
@@ -774,10 +993,98 @@ where one part's **interior detail** — a marking, a highlight, anything not on
 outline — lies inside the other part's area, and see which survives. Then write the
 slots in that order (R4), because there is no other place in the file to say it.
 
+**That reads the reference only, so it settles the edges the reference happens to
+show an interior detail on, and no more. There is a second test, and it decides more
+of them: render your own candidate both ways and measure the same feature on both
+sides.** Build the pair, render each back at the frames' own scale, and compare
+like with like. A part whose unoccluded size you can compute is a ruler — composite
+it alone, then read how much of it survives in the reference and how much survives
+in each build. If a part that measures 110 px on its own reads 100 px in the
+reference, the build that also reads 100 px is covering it the way the reference
+does and the build that reads 108 px is not, and that is the order. It costs two
+builds and it reaches edges the frames never show a marking on: on the ladder a brief
+has settled a single edge of a chain from interior detail and said outright that the
+frames did not show the rest, and rendering like-for-like settled three more of them
+— worth a measurable drop in window MAE, a convention the gate cannot see and the
+measures can.
+
+**Score that comparison over the pixels where the two builds differ. A whole-shot
+figure is the wrong feature.** Two builds that differ only in slot order are
+**bit-identical everywhere the two slots do not overlap**, so a whole-shot MAE
+divides the evidence by the whole figure and by every frame that carries none of
+it. What survives that division sits inside the objective's own scatter — real
+hypotheses and a deliberately reversed control alike land in there, pointing
+whichever way the noise does, and what has been condemned is the statistic and not
+the edge. ⇒ Take the pixels where the two renders differ **at all** and score both
+builds over exactly that set. Nothing outside it can contribute, so the dilution is
+gone by construction, and the reading needs no knowledge of which parts are involved
+— it is the same mechanical test on any structural pair. Read a frame-by-frame tally
+beside the figure too, because an edge the frames really decide wins shot after shot
+rather than on a couple of them.
+
+**Calibrate the band with a control on an edge the brief has already settled by
+measurement.** Run the same test on that edge, read how far apart the two builds
+come out over the pixels that decide it, and treat that separation as the scale a
+real answer is measured against. On the deciding pixels a settled edge separates by
+a wide margin where the whole-shot figure had it inside its own noise — which is
+what lets an edge the frames show no interior detail on stop being unanswerable and
+start being an edge the null-result rule below has no business firing on.
+
+⚠️ **A control that fails may be a wrong control — read the per-frame rows before
+you condemn the hypothesis.** A control is a **build**, and a build differs from
+base in everything the change implies, not only in the thing you meant to change:
+send one part behind another and it goes behind everything drawn between them too,
+so what you actually ran is one reversed edge plus several asserted ones. The
+aggregate will not say so, and it can favour the variant while the per-frame rows
+give base *every one* of the frames that carry most of the deciding pixels. That
+split — an aggregate one way, a consistent per-frame tally the other — is the
+signature of a control that asserts more than one thing, and reading the aggregate
+alone condemns an edge the brief settles by measurement. The rule the run protocol
+carries from the other side is the same one: a control that returns an impossible
+number has told you something, so read the number rather than the pass or fail.
+
+⚠️ **A render-back sweep whose spread is inside the objective's own scatter is
+*no answer*, not a weak one.** Rendering candidates back and keeping the best
+number is not a draw-order trick — it is how any structural choice the frames
+might decide gets decided, a scale, an offset, an attachment kind, an order — and
+every one of those sweeps can come back null. **Estimate the objective's own
+scatter first, or the sweep is not readable at all** — a spread smaller than that
+is noise wearing a decimal point. Two orders on one ladder shot came out **0.8 %
+apart over the whole shot and pointing opposite ways**, and a later run swept
+**three** structural choices and landed inside that scatter on every one of them.
+A difference that small is not a quiet vote for the winner; it means the frames do
+not decide this, and there are two honest ways on:
+
+- **find a second, independent way to get the number** — often by measuring the
+  *art* instead of the render, which needs no build at all. Two of those three
+  sweeps were settled that way.
+- **or ship it on reasoning, and say in the log that is what you did.** The third
+  one was. What makes that honest is the record — a number that arrived as an
+  argument must not later be read as a measurement.
+
 And the general form of all three: **when a reading implies a key, look for a second
 way to get the same number before you author it.** A wrong measurement costs one
 spurious key; a wrong measurement you believed costs the shape of the whole shot.
 
+⚠️ **A part that grows about a pivot that is not its own centre reads as a part
+that moves.** Fit a scale about the region centre when the reference scales it about
+somewhere else, and the residual stays *plausible* while the fitted centre walks
+along with the fitted scale — so the series looks like a translate you measured
+rather than a pivot you did not model. The tell is that shape and nothing else: **a
+per-frame centre that moves monotonically with the fitted scale is an unmodelled
+pivot.** Read it as motion and you author a translate timeline the reference does
+not have; read it as a pivot and it is an attachment offset (§3.4's `x`/`y`) with
+the bone's own scale carrying both the size and the centre drift — *one* keyed
+property, which is also what an editor rig has. Recover the offset by sweeping it
+against the frames where the part is unoccluded and taking the minimum; the minimum
+is sharp, and it is a structural constant rather than a per-frame value, so a
+handful of frames settle it. Measured on a shot with four such parts: MAE **3.13 →
+1.95** with not one key value re-measured, and those parts' chains from 10–13
+`MAE in it` down to 1.3–8.8. What made it believable rather than a lucky fit is the
+second trap's own cross-check — the four offsets came out the same **fraction of each
+part's own height**, from four independent fits, which is the quantity that had to
+agree between them and did.
+
 **A value is easier to get right than a curve.** The three traps above are all
 about measuring a *value*, and both ladder runs so far found that the values came
 out right early: rung 1's key values were exact at every keyframe on the second
@@ -797,16 +1104,188 @@ linear, stepped or bezier and never compares two handle shapes; `check` measures
 rendered result, so it can tell you a curve is *wrong* without telling you what it
 should have been. What does not follow is that omitting `ease` abstains. It authors
 constant speed on every span — the one shape a hand-animated reference almost never
-has (§10.4) — and the ladder has measured both sides of that bet. Rung 6 keyed
-everything linear for exactly the reasoning above and scored `curve_kinds` **34/539**,
-its single largest structural gap. Rung 3's second attempt — same brief, same frames —
-applied §10.4's rule instead and went 41/69 → 49/69, with `key_counts` rising beside
-it and every other section figure unchanged. ⇒ Take the curve *kind* from what the motion does — starts, stops,
-accelerates, settles, falls — rather than from how far apart the keys are; take its
+has (§10.4) — and the ladder has measured both sides of that bet. A run that keyed
+everything linear for exactly the reasoning above scored under a **sixteenth** of its
+`curve_kinds` measure, and that was its single largest structural gap. A second
+attempt at another rung — same brief, same frames, same model as its own first, with
+§10.4's rule added and nothing else — lifted `curve_kinds` by a fifth, with
+`key_counts` rising beside it and every other section figure unchanged. ⇒ Take the
+curve *kind* from what the motion does — starts, stops, accelerates, settles,
+falls — rather than from how far apart the keys are; take its
 shape from §10.4's automatic-handle advice and a small reused `easings` table; and
 leave `check` to catch the one thing no static reading can, an easing applied the
 wrong way round.
 
+### 8.1 Getting a pose for a figure with a dozen joints
+
+Everything above measures a *part*, and §9 checks a pose you already have. Between
+them sits the question neither answers — where do a dozen bones go on this frame —
+and on a character that gap is most of the run. What follows is not Spine's and no
+public page has an opinion about it, but it decides whether the search converges at
+all, so it sits here rather than being rediscovered once per figure.
+
+**Fit the rendered composite, never a part on its own.** The first trap above tells
+you to measure each part on pixels that can only be that part. On a figure with limbs
+there are no such pixels: an arm crosses a torso, one leg crosses the other, a held
+prop is drawn over both, and **every frame is a frame where parts are touching** — the
+trap with no way out of it. So the objective is the whole picture. Render your
+candidate through the same rasteriser that drew the reference, into the frames' own
+viewport, and minimise the difference over the bones' local transforms; that is §8's
+*"look for a second way to get the same number"* applied to a whole pose at once, and
+it is the render loop **§9.1** sends you into. Read §9.1's warning about where a
+bone's local transform lives *before* you write the first sweep — a fitter that is
+posing nothing reports a flat number and looks like a bad objective.
+
+⚠️ **Fitting one part at a time in sequence is the same mistake wearing a
+schedule.** A near arm solved against the composite while the far arm is still
+wrong is being scored on a picture the other arm is spoiling, and the minimum it
+walks to is not its own. The knobs come down together, coarse first — the next two
+rules are how.
+
+**Compare at a reduced resolution first. At full resolution the objective is flat
+over the range a joint has to travel.** Sweep one bone alone across the width of the
+figure against a single frame and watch the number: at full resolution it can wander
+inside a few percent for the whole sweep with no slope anywhere in it, because a
+limb fifty pixels from where it belongs overlaps the reference no better than one a
+hundred pixels away — both are *no overlap*, and the difference between them is
+aliasing. A coordinate search sees noise, reports no improvement, and leaves the frame
+at a pose that shares almost nothing with the picture. ⇒ **Box-average both sides
+before comparing them and run the search coarse to fine.** The coarsest level places
+the body, the next the limbs, the last two the pixels. The same sweep at the coarse
+level has a slope on it, because at that block size the two figures still overlap and
+the number knows which way to go.
+
+⚠️ **The coarsest level is for the body and nothing else.** A block big enough to
+give the whole figure a gradient is a block a shin is one cell of, and one cell
+cannot say which way a shin points. Place the root and the torso there, then decide
+each limb at a level whose cells are smaller than the part that level is moving.
+
+**Scan each knob's whole plausible range. Do not line-search out from where it sits.**
+A search that steps out from the current value cannot bring an arm 60° round, because
+the first step overlaps the reference no better than standing still did — so it
+reports no improvement and stops, correctly, on the objective it was given. A figure
+whose legs have folded under it is that failure with a picture attached: a real local
+minimum, sat in for as long as you care to iterate. ⇒ For each knob, evaluate the
+whole range that bone can plausibly take — a few dozen samples across it, which is
+nothing beside the frames you are fitting — take the best, and refine only after
+that. The cost is linear in the number of knobs, and it is the difference between a
+fit that converges and a fit that reports success on a folded figure.
+
+⚠️ **Some knobs only decide together.** A part hanging three rotations below a
+shoulder is placed by none of them alone: each single-knob scan finds its own best
+while the part is still nowhere near, because every value of that knob is wrong given
+the other two. Where a chain ends in something whose position you can actually see —
+a hand, a foot, a held prop — scan the two links above it as a **pair**, over the
+grid. That is the product of two ranges on a handful of chains, not on every bone.
+
+⚠️ **Two whole chains can share a minimum, and no paired scan reaches that one.**
+The case above is two knobs in one chain. The harder one is two *chains* sitting in
+the same pixels: an arm and the prop it holds lying across the part of the frame the
+reference fills with the legs. Every leg knob that would carry a leg there finds the
+pixels already inked and reports no improvement — correctly, on the objective it was
+given — and the frame keeps its limbs in a **different configuration** rather than a
+slightly wrong one. Pairing cannot help here, because the two knobs are in different
+chains and pairing every chain with every other is the whole product.
+
+**What reaches it is cheap: more than one start, screened coarsely.** Assemble a
+handful of candidate poses for the frame — the incumbent, the two neighbouring
+frames' solutions, a few poses spread across the shot, the setup pose — run all of
+them through the **coarse levels only**, and take the best two through the full
+schedule. **Keep the incumbent among the candidates**, so a frame can only improve
+on what it already had. The cost is a multiple of the coarse pass rather than of the
+fit, and the neighbour seed below is one start out of that set rather than a rule of
+its own. ⚠️ It also measures how far from converged a single-start fit can be while
+reporting success: repeat the *identical* search on one frame from different starts
+and the numbers walk down, step after step. That is not a tolerance being tightened,
+it is a different basin each time — so a search that stopped improving is evidence
+about the start it was given and about nothing else.
+
+**Cross-shot starts, for a configuration a shot cannot reach from its own frames.**
+Where every pose in one shot holds the prop low and the reference holds it out
+level, every start drawn from that shot's own frames is on the wrong side of the
+same two-chain minimum, and multi-start inside the shot barely moves the number.
+These shots are states of one character, so a configuration this shot never visits
+may be sitting in another one — take the start from there. ⇒ Borrow **only the bones
+of the chain in question**, never a whole foreign pose: a foreign pose puts the legs
+where this shot never goes, and the rest of the search then spends itself fighting
+what the borrow brought with it.
+
+**Re-fit the setup pose against frames drawn from every shot, not against one.** Every
+animation is measured from the setup pose, so an error in it is an error in all of
+them — and it is exactly the error one frame cannot show you. Fit an attachment's
+offset against a single frame and that frame's own rotations absorb whatever you got
+wrong: the picture comes out right, the offset is wrong, and every other shot pays
+for it. Across a spread it cannot hide, because a wrong offset would have to be
+absorbed by a *different* rotation in each frame and no one value of the offset does
+that. ⇒ Fit the setup pose against one clear frame to get near, then re-fit it
+against a handful of frames drawn from **every** animation at once, and hold it fixed
+while the per-frame poses are fitted. It is the spread that identifies it — a
+sequence of single-frame fits, one per shot, is not the same thing.
+
+**Seed each frame's search from its neighbour's solution — as one start among the
+full-range scans, never instead of them.** Adjacent frames are adjacent poses, so the
+answer next door is a better first guess than the middle of any range, and it costs one
+extra evaluation per knob to try it. What it must not do is *replace* the scans: the
+neighbouring frame's pose is precisely where a line search would have started, and a
+limb 60° out in one frame stays 60° out in the next for the reason the rule above
+gives — stepping away from it overlaps no better, so the whole series inherits one
+frame's local minimum and looks stable while it does. ⇒ Scan the whole range, add the
+neighbour's value to the starts, take the best of them. Fit outward from a frame you
+trust in both directions rather than only forward, so a bad frame seeds its neighbour
+and not every frame behind it.
+
+⚠️ **Then measure the adjacency drift, because a fit that lost a limb teleports.**
+Fitted frame by frame with nothing tying the frames together, a leg has two answers
+wherever the other leg is near it, and no single frame's number prefers the right one:
+some frames land on the wrong leg, every one of them cheap, and the series jumps back
+and forth between the two. That defect is invisible in any per-frame figure and loud in
+the relation between two — the reading §9.2's `Δpx` and `ref Δ` columns already make
+for the whole figure, and the chain table localises: a chain whose worst slot drift on
+one frame runs many times its own mean across the set did not travel that far, it was
+lost and refound somewhere else. **A limb that moves much further between two adjacent
+frames than the reference's own frame-to-frame change is a fit that lost it, not a limb
+that moved.** Read it per chain rather than per figure — one leg swapped for its twin
+is a small share of a whole-frame delta and vanishes into it.
+
+**Two near-identical parts need one calibrated separator, decided once and pinned.** A
+front limb and a rear one are often the same drawing twice, differing by a tint or by
+nothing at all; a search scoring a whole composite cannot tell which of the two it just
+placed, because exchanging them costs almost nothing on the frames where they overlap.
+Left to the per-frame fit, that assignment is re-decided on every frame — the teleport
+above, arriving by a second route. ⇒ Settle it the way §8 settles a draw-order edge:
+build both hypotheses, render each at the frames' own scale, and compare like with like
+— but calibrate on the frames where the two parts are *unambiguous*, the ones where
+they are far apart or only one of them is drawn, and read the separation there, where
+it is a real gap rather than a rounding difference. Then **pin the assignment for the
+run** and let no per-frame search reopen it. ⚠️ The same test knows when to stay silent
+here too: two hypotheses that come out inside the objective's own scatter mean the
+frames do not decide this, and you ship it on reasoning and say in the log that is what
+you did.
+
+**Spend each iteration on the worst chain, and stop re-fitting the ones already at the
+floor.** §9.2's chain table is this loop's work queue: it gives every limb a worst slot
+drift, an error per pixel, and a share of the set's error. ⇒ Take the next iteration to
+the worst **per-pixel** chain rather than the largest share — the share confounds
+*wrong* with *big*, as §9.2 says beside the table, and the chain holding most of a
+run's error is routinely the one that simply covers most of the figure. Then freeze the
+chains that have converged. Re-fitting them spends the budget the broken chain needed,
+and it is not merely wasteful: chains share parents, so a search free to move a
+converged limb's ancestors will walk it back off the floor to buy a fraction of a point
+somewhere else. ⚠️ **A blank where a drift should be is the loudest row in the table,
+not a quiet one.** The matcher refuses to name a distance past the part's own size
+(§9.2), so a limb far enough out reports no match rather than a large number — read
+that beside a high figure per pixel as the strongest signal the table has.
+
+**What comes out is a pose per frame, and a pose per frame is not a key.** Two things
+decide what survives the reduction, and **§10.3** states both: declare one tolerance
+in pixels at the end of what each bone swings rather than a figure in degrees, and
+deal with the gauges — the directions the pixels cannot see — *before* the series
+becomes keys, because a fitter will have wandered along every one of them; fold the
+exact ones out and penalise the rest. Then close
+the loop with **§9**: the fit's own number says how near this pose is to this frame,
+and only `check` says whether the shot is the shot. **§9.3** is the list of what even
+that cannot see.
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -816,25 +1295,29 @@ bun cli.ts check --candidate path/to/spine --frames path/to/reference/frames
 ```
 
 `--frames` takes either a **skeleton root** (the directory holding `frames.json`,
-which checks every animation of that shot) or **one animation directory** inside
-it. Everything else is optional: `--atlas` when the candidate's atlas is not beside
-its skeleton, `--as <name>` when your animation is called something the frame
-directory is not, `--all-frames` to list every frame instead of the worst by MAE,
-`--json <out>` for the whole per-frame, per-slot report.
-
-⚠️ **A frame set may be contact-sheets-only.** `check` only reads `fNNNN.png`
-files — a committed reference set that ships a contact sheet plus a couple of
-stills (rung 2's does: `f0000.png` and `f0310.png` per animation, the rest folded
-into `contact.png` so a 311-frame shot does not commit 311 near-duplicate PNGs)
-reports `frames 2 on disk, candidate samples 311, 2 compared` and means it: `check`
-compared exactly the committed stills, not the shot. That is not a defect to author
-around — the frame count line says so rather than pretending a fuller comparison
-happened — but it does mean a clean `check` table on a contact-sheet-only set says
-nothing about the frames between the stills. Whole-shot fidelity against a contact
-sheet needs a tile-wise comparison against the sheet's own grid, which `check` does
-not do yet (issue #36);
-[`bench/runs/2026-08-23-rung2-2/sheetcheck.ts`](../bench/runs/2026-08-23-rung2-2/sheetcheck.ts)
-is a working prototype, built in-run for exactly this gap.
+which checks every animation of that shot, framed per set — see the scope note
+below) or **one animation directory** inside it. Everything else is optional:
+`--atlas` when the candidate's atlas is not beside its skeleton, `--as <name>` when
+your animation is called something the frame directory is not, `--framing shared`
+to fit one framing across every set instead of one each, `--all-frames` to list
+every frame instead of the worst by MAE, `--json <out>` for the whole per-frame,
+per-slot report.
+
+⭐ **A frame set may ship a contact sheet instead of every frame, and the sheet is
+compared too.** A long shot does not commit 311 near-duplicate PNGs: rung 2's sets
+ship `f0000.png` and `f0310.png` plus a `contact.png` holding all 311 sampled
+frames, and spineboy's `@30fps` sets do the same. The frame table still says
+`frames 2 on disk, candidate samples 311, 2 compared` — those are the files — and a
+**`sheet` line under it** carries the other 309: your candidate sampled at the set's
+own rate, rendered into the same box the frames above were at the sheet's own scale,
+and compared tile by tile (issue #36 — the gap a rung-2 run had already prototyped a
+comparator for, in its own working directory, because the tool could not see its shot).
+
+⚠️ **Read it as a series, not as one number** — §9.2. And note what it does not
+carry: MAE only. The `Δpx` / `ref Δ` thresholds are calibrated at frame scale and a
+tile has a fraction of a frame's pixels, so the per-frame change measure stays on
+the committed stills, where it reports `no two compared frames are adjacent` and
+means it.
 
 `--fps <n>` exists for frame sets that have no `frames.json` beside them, which are
 sets rendered before the sidecar existed: it gives the rate those frames were
@@ -885,10 +1368,49 @@ pixels rather than quad corners (issue #34, closed by #39; see §9.2). Pin to a
 you can name a reason for, and read the unpinned framing line first when you are not
 sure whether you have one.
 
-⚠️ **The framing is over the frames you compare.** `--frames <root>` fits one
-framing across every set under it; `--frames <root>/<one-set>` fits one to that set
-alone. Both are right and they are not the same number, so compare like with like
-across builds.
+⚠️ **The framing is over the frames you compare, and `check` decides it PER SET.**
+Point it at a skeleton root and each animation directory under it is asked its own
+question first: *do this set's own drawn pixels land in the box `frames.json`
+records?* The sets that do are measured in that box, which is exact — it is not an
+estimate of where the frames were drawn, it is where they were drawn — and nothing
+another set does can move them. The sets that do not are measured in **one shared
+framing** fitted across every set, printed as the header's `shared box` line, plus
+their own whole-pixel MAE refinement off it (§9.2) — the fit is shared because more
+frames condition it better; the constant offset it still leaves is per set, and
+measured per set. Each set says which it got on its own `framed to` line.
+
+Why the split falls there, both halves measured on an 8-shot character (147 frames):
+
+- **Deciding the declared box per set is worth 15–25 MAE.** Over the union, one shot
+  that is not in the frames' coordinates puts the pooled correction over the
+  one-pixel threshold and the *whole root* falls back to a fit. Per set, the shots
+  that qualify read what pinning by hand reads: `idle` **18.77** where a whole-root
+  run read 41.59, with not one key different (issue #100).
+- **Fitting per set is worse, so `check` does not.** `fitFraming` registers extent,
+  and extent is not alignment (see the ⚠️ in §9.2), so on a shot whose silhouette
+  genuinely differs one shot's frames do not constrain the fit enough: `hit` reads
+  **92.36** fitted on its own against 60.59 in the shared fit, and a two-frame stills
+  set reads 101.94 against 42.98. More frames is a better-conditioned fit, so the
+  fallback is deliberately the shared one.
+
+`--framing shared` measures **every** set in the shared framing, which is what a
+whole-root run used to do. It answers one question and it is a good one — *does a
+single box serve every set?* — and it is the wrong number to read as one shot's
+fidelity.
+
+⚠️ The two are different measurements and their absolute numbers are not comparable.
+The `scope` line at the top of the report says which one you got. `--viewport` pins
+one box for the whole run whichever scope you ask for, because a pin is a claim
+about your candidate's own coordinates and those do not change between shots.
+
+⚠️ **`--frames <root>/<one-set>` is a third number for a set that cannot take the
+declared box**, and it is the least constrained of the three: the fit has only that
+set's frames to work from, where a root run's shared fit has every frame in the
+skeleton. Measured on the same character, `hit` reads 60.50 at the root and 92.41
+pointed at its own directory. A set that DOES take the declared box reads the same
+either way — that box is not fitted to anything — so pointing at one directory is
+exact for a shot you authored in the frames' coordinates and a rough estimate for
+one you did not.
 
 ### 9.1 Why this exists
 
@@ -910,6 +1432,58 @@ your run ceasing to be an honest authoring run. It is a loop, in the way `build`
 a loop. `bench` and `diff` against a rung's export are not — they read the answer,
 and [the ladder's honesty rule](LADDER.md) makes them a finish line you reach once.
 
+📌 **That is also why the MAE figures quoted through this section stay.** Every one of
+them is a candidate's own reading against rendered frames — the exam question, not the
+answer key — so none of them narrows a reference-side measure, and a guide that censored
+them would be teaching less for no gain in honesty. The criterion is under *The honesty
+rule* in [LADDER.md](LADDER.md) (issue #158); what it *does* seal is a score written
+over a reference's own count, and no such figure appears here.
+
+🚨 **If you drive the runtime yourself, a bone's local transform lives on
+`bone.pose`.** A shot whose poses have to be *fitted* rather than read sends you
+past `check` and into your own render loop over
+`@esotericsoftware/spine-core` — that is §8's *"look for a second way to get the
+same number"* applied to a whole pose, and it is a legitimate thing to build — §8.1
+is how that search is set up so it converges. The
+first thing it hits is not a subtlety. **spine-core 4.3 keeps a bone's local
+transform on `bone.pose`, not on the bone**, so `bone.rotation = …` — or `.x`,
+`.y`, `.scaleX` — is neither an error nor a rotation: it adds a property nothing
+reads, and every frame renders as the setup pose. Write `bone.pose.rotation`.
+Rung 8 lost a loop to it at a flat 17.3; driven through `bone.pose`, the same
+poses measured **2.76**.
+
+🚨 **That trap has a twin one level up: the *setup* transform lives on
+`bone.data.setupPose`, not on `bone.data`.** `BoneData` extends `PosedData`,
+which carries the whole setup transform on a `setupPose` object, so
+`bone.data.rotation` — or `.x`, `.y`, `.scaleX` — is `undefined`, and
+`bone.data.rotation + delta` is `NaN`. Read and write it as
+`bone.data.setupPose.rotation`. This one is worse to spot than the `bone.pose`
+trap, because nothing on the path raises: `undefined` propagates to `NaN`, and
+`NaN` serialises to `null`, so a fit writes `"px": null` into its own placements
+file, the next build reads those as zero, `validate` is green and `check` runs.
+⇒ **A `null` in your own placements dump is the signature of having read
+`bone.data` directly** — nothing in this format is ever legitimately null. On
+spineboy it cost the candidate MAE 13.0 → 114.6 with a green gate throughout
+(measured in a spineboy attempt's own loop log, §4.1). Note that the two names are not
+the same thing: `bone.data.setupPose` is
+the setup transform, while `bone.setupPose()` on a `Bone` is the method that
+resets `bone.pose` back to it.
+
+🚨 **A region attachment's own offsets are cached.** `attachment.x`, `.y`,
+`.rotation`, `.scaleX/.scaleY` are inputs to a quad spine-core computes once and
+stores; what gets drawn is that stored quad — `computeWorldVertices` reads
+`getOffsets(pose)`, never the fields — so writing them is, again, neither an
+error nor a move. **Call `attachment.updateSequence()` after every write**, or
+every frame renders the quad it was loaded with. A setup fit on spineboy ran
+4,500 renders and reported the same number for all of them before this surfaced
+(the same loop log, §4.2).
+
+⇒ **An MAE that is identical across every pose, and that does not move for any
+parameter you sweep — a bone's local transform, an attachment's offsets — is one
+of these inert writes and not a wrong animation.** The parameter you swept was
+never read; a wrong rig moves the number, a write to a field nothing reads
+cannot.
+
 ### 9.2 Reading the table
 
 ```
@@ -917,14 +1491,18 @@ and [the ladder's honesty rule](LADDER.md) makes them a finish line you reach on
   reference  256x116px  0.117628 px/unit  world x[-573.3 .. 1603.0] y[-81.2 .. 908.9]  (frames.json)
   content    candidate 234.6x95.5px at (11.3, 11.5)   reference 234.7x95.3px at (11.2, 11.7)   (union over 86 frame(s))
              ⤷ fit x0.999256  offset +0.05, -0.02 px   rms 0.42 px over 344 edge(s)   union residual -0.27 x +0.17 px   aspect -0.30%  (derived, 4 pass(es), settled)
+             ⭐ MAE-refined by -1, +1 px: 54.31 → 48.47 over the reference's own pixels (10.7% of the figure). …
   in units   candidate 1995.3 x 809.7   reference 1995.3 x 809.9   x0.9999
 
   ── heavy — candidate animation "heavy", 12 fps ──
      frames     65 on disk, candidate samples 65, 65 compared
      MAE        mean 23.10  worst 43.36 at f0029   (0..255 over the union alpha; …)
+                ⤷ over the REFERENCE's own drawn pixels, mean 23.90 — the union figure compares two builds …
      slot drift worst 2.1 px  "pendulum" at f0029
      per-frame 1 of 64 adjacent pair(s) change by a different amount than the reference does; worst
                f0018, yours moved 0 px where the reference moved 374
+     sheet      311 of 311 tile(s) of contact.png at 64x57px in 8 column(s)   MAE mean 4.30  worst 4.76 at f0047
+                ⤷ worst 8: f0047=4.8  f0048=4.7  f0045=4.7  f0039=4.7  f0149=4.7  f0044=4.6  f0046=4.6  f0043=4.6
 
      the 9 frames worth reading — worst by MAE, plus every frame whose own change disagrees, in index order
        frame      MAE   union px     Δpx  ref Δ   worst slot            drift   how       slots   note
@@ -986,6 +1564,12 @@ The lines, in order:
   does not, after the fit. This is the number that says *"something reaches
   somewhere nothing in the frames does, or is a different size"*, and a warning
   spells it out past a pixel.
+- the **MAE-refined** line, which is the last thing that happens to the box and the
+  paragraph below is what it is for. On a **fitted** framing it says what constant
+  whole-pixel offset was taken out and what that was worth (`⭐`), or that the
+  search ran and the identity won. On a box that is not an estimate — the frames'
+  own, or one you pinned — it never moves anything, and if it finds a constant there
+  it says so as a **finding about your rig** rather than about the framing.
 - `in units` — the same two boxes in world units. The framing absorbs a pure scale
   on purpose, so this is the only place one shows; it compares only if you measured
   the shot in the frames' own units.
@@ -996,10 +1580,31 @@ that is a little large — the best fit of the two extents is not quite the best
 alignment of the two pictures, and the fit spends a fraction of a pixel absorbing
 a difference that would have been cheaper to leave alone. Measured floor: about a
 third of a pixel on the ladder's shots. On most that is invisible; on a small
-high-contrast frame it is worth a point or two of MAE — rung 6 measured five. This
-is the floor the frames' own box has no share in, which is why `check` prefers that
-box whenever your pixels are measured to land in it; `--viewport` is how you stop
-it in the cases that box does not cover.
+high-contrast frame it is worth a point or two of MAE — rung 6 measured five, and
+on the spineboy sets a **constant** one or two pixels was worth 10–30 % of the
+figure (issue #146). This is the floor the frames' own box has no share in, which is
+why `check` prefers that box whenever your pixels are measured to land in it;
+`--viewport` is how you stop it in the cases that box does not cover.
+
+⭐ **What a fitted framing now does about it: one final whole-pixel pass.** After
+the fit settles (or cycles), `check` searches every whole-pixel offset within ±2 px
+for the lowest MAE over the reference's own drawn pixels and moves the box to the
+best one, when that is worth at least 1 % of the figure. So a fitted set's numbers
+are what is left **after** the best constant offset has been removed, rather than a
+constant offset read as motion — and the line says which offset and what it bought,
+in both directions, so nothing is quietly absorbed.
+
+Two things to know when you read it:
+
+- ⚠️ **A large refinement on a set whose drift is also large is not necessarily
+  framing.** The pass removes the best *constant*, and when one part carries much of
+  the shot's ink a constant can absorb part of that part's own displacement. Read
+  the offset beside the chain table: a big offset with a flat drift table is the
+  fit's floor; a big offset with one limb far out is that limb.
+- On a box that is not an estimate the pass declines and says why. `frames.json`'s
+  own box is where the frames were drawn, so a constant pixel *there* is your
+  figure sitting a pixel off inside the right box — a thing to fix, and the report
+  refuses to frame it away. A pinned box is your claim, and nothing overrules it.
 
 **MAE** is the mean absolute RGB difference, 0..255, over the pixels either side
 covers — the *union alpha*. It is not scored against a threshold, any more than a
@@ -1012,6 +1617,49 @@ because an ad-hoc re-render check naturally computes that one, and on every set
 measured so far it comes out ten to twenty-five times smaller and correspondingly
 blunter.
 
+⚠️ **Half of that denominator is yours, so do not optimise against it.** The union
+is the pixels *either* side drew, and a large, mostly transparent sprite adds many
+cheap pixels to it — so the *mean falls* on a candidate that got worse. That is not
+hypothetical: spineboy-2's muzzle flare walked its own scale to 13x under a fitting
+loop doing exactly this, and cost every set in that run its framing (issue #119).
+So the line under the MAE divides the same difference by the pixels the
+**reference** drew, a denominator nothing you do can grow. Read the union figure to
+compare two builds of your own rig, where both sides cover about the same ground,
+and the reference-denominator figure when you are deciding whether a change made
+the shot better; it is not bounded by 255. A set that draws more than half again as
+much ink as the reference does gets `⚠️ overdraw` beside those two numbers, with
+both pixel counts, because at that point the first figure is cheap for a reason
+that has nothing to do with your keys.
+
+🚨 **Part of your MAE is the texture, not the animation, and nothing in the report
+says so.** The reference frames are rendered through the example's **own packed
+atlas**, and a packed atlas may carry a `scale:` line — the ladder has one at
+`scale: 0.5`, whose 745x212 part is packed at 373x106. rigc has no packer (**§6**), so
+a candidate built from the loose PNGs samples a texture at twice that resolution and
+resamples every edge differently. The pixels are the same shape in the same place; they
+are filtered from a different source, and the difference lands on the outline of every
+part in every frame. It is a constant, it is invisible to `content`, `rms` and the
+`±2 px` refinement — a resampling difference is not an offset — and **no key you write
+can move it**.
+
+⇒ **When the MAE is flat across the whole set and the drift is already at the floor,
+check the atlas before you look for keys.** The example's `.atlas` is an allowed input
+in its own right (`bench/runs/README.md`, *What a run may read*, item 4), and one line
+of it answers the question. To size the floor, re-run `check` once with
+`--atlas <the example's own .atlas>`: same skeleton, same keys, the reference's own
+texture. Measured on rung 3, MAE **6.13 / 6.01** with the candidate's own
+full-resolution atlas against **2.25 / 2.30** with the supplied one — **two thirds of
+the figure was the texture**, and the run that did not know it would have spent its
+whole budget hunting a rig that was already right.
+
+⚠️ Two things about that diagnostic. It is a **diagnostic and not a better number**:
+the artifact `bench` validates ships its own atlas, so the first figure is the one
+that belongs in a run's record and the second is the explanation of where it went.
+And the coarser texture **loses** resolution the finer one has — on the same rung a
+pair the reference moves *one pixel* across stopped being visible at half scale, so
+the diagnostic run reported a frame-change disagreement the graded run does not have.
+Read it for the floor, never as the verdict.
+
 **`Δpx` and `ref Δ`** are the two columns that do **not** compare you against the
 reference. They compare each side against **itself one frame earlier**: how many
 pixels of your own frame moved since your own previous frame, and the same for the
@@ -1037,12 +1685,46 @@ 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.
 
+⚠️ **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
+**2k and 2k+2** of the fine series — and 2k+1 between them is free to move, and does.
+One ladder shot has a pair whose whole-frame change at the coarse rate is **exactly
+0** while both fine-rate pairs inside that same span change by 48 px: the subject
+shifts under three world units and comes back, so the two coarse samples land on the
+same pose either side of it. So §10.3's *key both ends of the hold* has to be applied
+**at each committed rate separately**, and equal values are not enough — the two
+samples have to be **keys**, or a planner reduces through one of them and an
+interpolant inside its own tolerance is not equality. That cost two builds on that
+run, the second of them for exactly that reason. ⇒ Measure the frames' own
+frame-to-frame change **once per committed rate**, and where a rate holds, pin both
+ends as keys whenever a finer rate moves between them.
+
 ⚠️ Only between **adjacent** frames. A set that ships stills rather than every frame
 — rung 2's contact-sheet sets — reports `no two compared frames are adjacent`, and
 means it: the difference between two frames 310 apart is not a frame-to-frame delta.
 A disagreement needs one side to hold *exactly* still while the other moves, or one
 side to move four times the other and at least two dozen pixels more; below that the
-two rasterisations differ by their own last bit and the column says nothing.
+two rasterisations differ by their own last bit and the column says nothing. Such a
+set gets the `sheet` line instead, which is MAE over every sampled frame and not a
+change measure — the two thresholds above are pixel counts at frame scale, and a
+tile has a fraction of a frame's pixels.
+
+**The `sheet` line is the whole shot**, on the sets that commit a couple of stills
+and fold every sampled frame into one `contact.png`. It says how many tiles were
+compared out of how many the sheet holds, the grid it measured off the sheet itself,
+the mean and worst tile, and the worst eight by MAE. Read the **series** rather than
+the mean, exactly as with the frame table: flat across the shot is framing or art,
+a spike is timing at that moment — rung 2's four shots read 4.30–4.41 flat over
+1,244 tiles, which is what says their trajectories, ring rates and attachment swaps
+land where and when they should. Two things to know:
+
+- it is measured in the **same box** the frame table was, at the sheet's scale. For
+  a stills-plus-sheet set that box was decided on the stills, so a set whose framing
+  is a fit carries that fit into these numbers as well;
+- a sheet whose dimensions are not a grid of this set's frame count at these frames'
+  aspect is **refused by name** rather than read wrong — the note names the file, and
+  the answer is to re-render the set.
 
 **Slot drift** is what you act on. For each of your slots, `check` measures where
 it landed and how far that is from where the reference put it. That names the part,
@@ -1052,8 +1734,15 @@ sentence you can take straight back to a key.
 There are two matchers and the `how` column says which one answered:
 
 - `component` — your slot sits on a connected component of the reference frame that
-  is its own size. The drift is the distance between the two centroids, and it is
-  the strongest answer available.
+  is its own size **and holds nothing else you drew**. The drift is the distance
+  between the two centroids, and it is the strongest answer available. All three
+  conditions are checked: a blob may not be much bigger than the slot, may not be
+  much wider than its box, and may not contain another of your parts' ink. The last
+  is the one a dominant part slips through otherwise — rung 2's course is 81 % of a
+  blob that also holds the water, the panel and both rings, so the blob is only
+  1.24x its ink and no wider than its box, and the reported *"course drift 11.2 px"*
+  was the distance to a five-part centroid (issue #37). It now falls to the matcher
+  below and reads 0.0 px.
 - `tmpl 0.62` — the reference merged your slot into a neighbour (they touch, or one
   is drawn over the other), so the fallback rendered **your slot on its own** and
   correlated it against the reference around where you drew it. The number is the
@@ -1074,6 +1763,39 @@ 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 `chains` block is the same two measures on the unit you actually repair.**
+
+```
+     chains     6 from the candidate's own bone tree — the roster is at the foot of the report
+       chain                 slots   worst slot drift                     mean   MAE in it   share
+       crest                   5/5   3.0 px "lantern" f0006              2.4 px       28.40    31.5%
+       prop-arm                6/6   2.0 px "prop" f0002                 1.5 px       44.90    33.0%
+       near-strut              3/3   15.0 px "strut-tip" f0004           7.0 px       51.30     8.5%
+```
+
+`check` cuts **your own** bone tree at every branch point — a chain runs from a
+root or a fork down to the next fork; a single-bone chain that is itself a fork
+folds into its parent, so a `hub` that branches three ways joins the trunk rather
+than becoming a row of its own; and each chain is named after the first bone in it
+that carries a slot. On a biped that lands on the parts you would name (`crest`,
+`near-strut` and `prop-arm` above); on a serial figure with no fork it is one chain,
+and the slot rows under it still say which link moved. Which bones and slots went
+where is printed as a roster at the foot of the report, so it is never a guess. `MAE
+share` divides the difference over the **reference's** own drawn pixels — the
+denominator from the line above, which nothing you draw can grow — and splits it by
+giving each of those pixels to the chain whose ink is nearest, so the shares
+partition the set and no chain can look better by drawing more: growing its ink
+only pulls more of the reference's pixels, and their error, into it. Read `MAE in
+it` beside the share, because the share alone confounds *wrong* with *big* — a head
+and its features cover a lot of a figure and can carry a third of the error at a
+below-average figure per pixel. Reference ink further from your ink than the part's
+own size is left `(unattributed)` rather than charged to a neighbour, and a chain
+reading 0 % on `0/3` slots drawn is missing, not clean. The rollup at the foot gives
+each chain one line across every set — the sentence a run's README quotes instead of
+a per-shot list. **§8.1** is how to act on it: the next iteration goes to the worst
+chain by error per pixel, and a chain already at the floor is frozen rather than
+re-fitted.
+
 ### 9.3 What it still cannot see
 
 - **Anything a frame does not contain.** Bone `length`, the setup `inherit` mode,
@@ -1086,15 +1808,40 @@ a part you have not authored, or one you have put somewhere else entirely.
   still cannot tell you is *how* a silhouette got its shape: a hull moved by a
   bone chain and the same hull moved by deform keys render to the same pixels, and
   the frames cannot separate them. Choose on what the rig has to do next, not on
-  what the frames appear to say.
+  what the frames appear to say. ⚠️ **But `bench` does see it.** Take a disc that
+  squashes as it travels: a region on a bone that scales, and a grid mesh weighted
+  1.0 to that same bone, draw the same pixels on every frame — and they are
+  different files. One has a region and one bone; the other has a hull, a
+  triangulation and a weight per vertex, and a rig that meshes one part usually
+  meshes its neighbour and carries the bones to drive them. `attachments.type_counts`,
+  `attachments.mesh_weighted`, `attachments.region_size` and the bone count that
+  comes with the choice all move on that decision, while `animations.deform` moves
+  for neither, because neither one deforms with keys — the whole difference is which
+  machinery renders identical pixels. That is not an argument for guessing: the
+  frames cannot choose, and this guide will not tell you which way any reference
+  went. It is an argument for **writing down which way you went and why at the
+  moment you decide it**, rather than meeting the decision again in the measures
+  after the run is over.
 - **Which of two explanations is right.** A slot 3 px low every frame and a slot
   3 px low at one frame have the same drift and opposite causes. The table gives
   you the frame index; §8's rule still applies — look for a second way to get the
   number before you author the key.
-- **What happens between two committed frames.** `Δpx` compares adjacent frames and
-  a set that ships stills has none, so a shot that is right at every committed frame
-  and wrong between them reads clean. That is the same gap `--frames` on a
-  contact-sheet set already has, and it is why the frame-count line is printed.
+- **What happens between two committed frames** — *unless the set ships a sheet.*
+  `Δpx` compares adjacent frames and a set that ships stills has none, so a shot
+  that is right at every committed frame and wrong between them reads clean in that
+  column. That is the same gap `--frames` on a contact-sheet set already has, and it
+  is why the frame-count line is printed. ⭐ What closes it is the **`sheet` line**:
+  on a set rendered at a higher rate than the frames on disk, every sampled frame is
+  compared, so the samples between two committed ones are measured there and
+  nowhere else.
+  🚨 **And when you go looking for one of them, do not assume it lies between its
+  neighbours.** A half-frame is not an interpolation — it is where the shot actually
+  was, and the interesting ones are interesting because it left the interval. Rung
+  4's ball makes contact entirely inside one twelfth of a second: the sheet puts it
+  **40 px below both 12 fps frames that bracket it**, while its x sits within their
+  own range. A search whose reach was scaled from those two frames' own step
+  therefore looked ±9 px for something 40 px away and reported the interpolation
+  back, twice, before the tile was read rather than inferred.
 
 ---
 
@@ -1143,6 +1890,31 @@ attachment name"* — [Images](http://esotericsoftware.com/spine-images). ⇒ in
 keep the placeholder equal to the PNG's basename and no `path` is written (R5). A
 `path` in the emitted file means the two disagreed.
 
+🧩 **⇒ When the art is named after the parts, the art's names are the rig's names —
+and this is the largest lever §10 has.** *One image → one slot → one attachment,
+named after the image* reads as a structural rule. It is also, and mostly, a
+**naming** rule, and naming is what whole sections of the measures are made of:
+five of `bones`'s eight name-matched measures (`names`, `parent_by_name`, `order`,
+`length_present`, `inherit_present`) and every `slots` measure but the count are
+scored over the names the two sides **share** ([`src/diff.ts`](../src/diff.ts)), so
+a rig whose names miss reads near zero on all of them however well it is built. ⇒
+carry each part's own name straight through — PNG basename → slot → attachment, and
+the bone that moves it — instead of inventing a scheme of your own.
+
+**Both directions are measured.** The one run whose art shipped a separate PNG per
+body part, each named for the part, applied this deliberately and posted `names`
+measures **an order of magnitude** above anything on the ladder before it — without
+either side seeing the other. Every honest run before it read near zero on the same
+measures. It is the largest single thing any run has got out of a convention.
+
+⚠️ **And the other half, which matters just as much: when the art is *not* named
+after the parts, no naming strategy beats any other and the measure is noise.** On a
+shot whose two PNGs are called things like `square` and `pendulum`, the names carry
+nothing a rig could inherit, every candidate name is as good as every other, and the
+name measures are reporting the honesty rule's own price rather than a defect in
+your rig. Do not spend a loop hunting for better names there, and do not read the
+low figure as a miss — say in the log that the art did not carry them.
+
 📗 **Housekeeping the format fixes for you.** The default skin *"always has the name
 `default`"* and *"bones are ordered so that the parent always comes before a child
 bone"* — [JSON format](http://esotericsoftware.com/spine-json-format). §3.4.
@@ -1200,7 +1972,79 @@ all the time"*, and Clean Up *"deletes all unnecessary keys … keying the same
 multiple times in a row, keying the same values as the setup pose"*, because *"often
 it is convenient to set keys liberally when designing an animation, then use Clean
 Up afterward"* — [Keys](http://esotericsoftware.com/spine-keys). ⇒ a shipped export
-is dense, but it does not repeat a value.
+is dense, and what it does not carry is a key its own neighbours already imply.
+
+🧩 **⇒ A hold still needs a key at both ends, and two equal values are not a
+repeat.** Clean Up's *"keying the same value multiple times in a row"* is about
+**three or more** — a run of keys whose interior ones their neighbours imply. Two
+keys of equal value imply nothing: they are the only way to say *nothing moves here*
+on an interpolated timeline, and deleting either one ramps the value through the
+hold. Stillness is a thing a shot does, sometimes for a twelfth of a second and
+sometimes for nine, and it is authored, not omitted. ⇒ Key the start of a hold and
+key its end, at the same value; drop the ones in between. This is §9.2's *"held pose
+that is not held"* from the other side, and the same place catches it — a sloped
+hold shows up in `check`'s per-frame column and nowhere else, because it is cheap in
+every single frame and wrong only in the relation between two.
+
+⚠️ **The key reducer has to key the plateau, because a plateau is neither an end nor
+a turn.** A planner that forces the series ends and every change of direction —
+which is exactly what the rule above asks for — will still author a slope straight
+through a run of still frames: not one sample in the middle of a hold is an end or
+a turning point, and a greedy span stays inside its own per-bone tolerance the whole
+way across. **A tolerance is not a hold.** Slow motion inside the tolerance is a
+tolerance question; stillness is a thing the shot *does*, and it survives the
+reduction only if the reduction is told to keep it. ⇒ Force **both ends of every run
+of equal values** as keys in their own right — a third kind of forced index beside
+the series ends and the turning points — and test on **exact** equality, so that a
+merely near-still span is deliberately not swept up with it. This is worth doing
+before you have any evidence you need it: a run whose *poses* are all right can fail
+this and see nothing wrong anywhere else, because `validate` has no opinion on it,
+`diff` never looks at a rendered frame, and an aggregate MAE is cheap in every
+single frame and wrong only in the relation between two.
+
+⚠️ **And a tolerance is not a *slow span* either — a key tolerance needs a relative
+floor beside its absolute one.** The rule above rescues exact stillness by forcing it,
+and deliberately leaves near-stillness to the tolerance. But **§9.2's per-frame column
+compares *changes*, not positions**, so on a span the shot barely moves across, an
+error well inside an absolute tolerance is most of the motion. Measured, on rung 3: the
+reference moves **0.109 px** between two frames; a greedy span deviated **0.098 px**
+there, legal under a 0.30 px tolerance and legal again under 0.15 px — and the column
+read **259 px against the reference's 40**, a six-fold disagreement authored by a span
+that was, at every keyframe, exactly right. The same tolerance that is generous on the
+fast part of the shot is a 90 % error on the slow part, because one figure in pixels
+cannot be both.
+
+⇒ Cap each span's deviation at **the smaller of the absolute tolerance and the
+smallest single-frame move inside that span**. It is one line in the planner, it costs
+a handful of keys, and it is the difference between a reduction that is accurate and
+one that is accurate *in proportion to what is happening*.
+
+⭐ **Then stop trusting the floor and close the loop on the frames, because a floor is
+a heuristic and the column is a measurement.** The floor above cut rung 3's
+disagreements from three to one and could not reach the last: **sample your own planned
+curves at the frames' own rate, render them, compare every adjacent pair against the
+reference's own change, force the offending frames as keys, and re-plan** — repeating
+until no pair is out of band. It terminates quickly (that shot needed one extra round
+on one animation and none on the other), it needs no build, and it is the only part of
+key planning that is verified rather than argued. ⚠️ The band is worth reading before
+you aim at it: `check` calls a pair a disagreement when one side is **exactly** still
+and the other is not, or when one side moves **four times** the other **and** at least
+**24 px** more (`src/check.ts`). So the wide middle of a shot is nearly free and the
+whole difficulty is the pairs where the reference barely moves — including, on that
+rung, one pair it moves a single pixel across, which no MAE and no drift figure in this
+toolchain can see.
+
+🚨 **But check that the shot holds at all first, because applying this to one that
+never does manufactures the defect it prevents.** The rule is about a *shot*, and a
+snap-to-still step in a planner does not cost nothing when there is nothing to snap:
+it will find some run of samples inside the fitter's own resolution and flatten it.
+Rung 4's shot has **no** still span — not one adjacent pair of its 155 reference
+frames is pixel-identical, and even its last two differ, because the chain is still
+settling at the final frame — and the snap duly flattened the tail and put a
+*"yours moved 0 px where the reference moved 28"* into the per-frame column: §9.2's
+held-pose defect arriving from the opposite direction. ⇒ Difference every adjacent
+pair of frames once, before the planner runs. It is one pass over the set, and it
+tells you whether this paragraph applies to you at all.
 
 📗 **Add a key when a curve cannot carry the shape.** *"If a curve is not smooth
 enough, it is easily remedied by adding another key"*, and the **Bounce** handle
@@ -1217,6 +2061,89 @@ minimal one-key-per-pose spec produces.
 one.** Reaching for a target density is guessing. The frames are the only thing that
 can say where the motion turns; §8 is how to read them.
 
+⚠️ **Two rules for a run that *fits* a pose series rather than reading it off the
+frames.** Neither is Spine's — no public page has an opinion about a fitter — but
+both decide where the keys above actually land, so they sit beside them. Both were
+paid for on the ladder. (**§8.1** is how the series gets fitted in the first place.)
+
+**A key tolerance on a rotation is not a number of degrees.** The same angular error
+costs a different number of pixels at every level of a hierarchy, because everything
+below the bone comes with it. Measured on rung 8's four-link chain: **a quarter of a
+degree on the last link moves the chain's end 0.15 px, and the same quarter degree
+on the plate the chain hangs from moves it 0.69 px.** One figure in degrees applied
+per property therefore keys the far end of the chain roughly four times too loosely
+while over-keying the near end — it is not one tolerance at all. ⇒ Declare **one**
+tolerance, **in pixels at the end of what the bone swings**, and convert it per bone
+by that bone's lever arm. With that, the whole trade reads as one curve and you can
+pick a point on it deliberately: that shot measured 0.6 px → 259 keys → 1.619 window
+MAE, 0.3 px → 300 → 1.402, 0.15 px → 377 → 1.305.
+
+⚠️ **Compute what a skipped sample costs before you declare that tolerance — on a
+fast subject the shot's own speed has already pinned it.** Skipping one sample means
+spanning it linearly, and the chord through its two neighbours sits at their mean, so
+the deviation at the sample skipped is **half** the series' second difference there:
+`|f(n−1) − 2·f(n) + f(n+1)| / 2`. That is an identity, not an approximation — check
+it on `f(n) = n²`, whose second difference is 2: the chord reads `n² + 1` where the
+curve reads `n²`, and the deviation is 1. So second-difference the fitted series,
+halve it, and read that number against the tolerance you were about to declare. If it
+is the larger of the two, the fitter keys nearly every frame, and no tolerance below
+it changes that — the key density is then a fact about the subject, not a choice you
+made. One ladder run is that case: its subject's median frame-to-frame second
+difference measured 6.4 px, so a span that skips one sample deviates about 3.2 px,
+ten times the 0.3 px tolerance the run declared, and the tolerance would have to be
+loosened past that 3.2 px before a span could afford to skip anything at all. What
+the trade bought there was accuracy and never sparsity — 0.6 px → 439 keys → 18.22
+MAE at 12 fps, 0.45 px → 482 → 17.54, 0.3 px → 521 → 17.26. ⇒ Do the arithmetic
+first. It tells you which of the two situations you are in: picking a point on the
+curve above, or discovering the point the shot has already put you on — and the
+second one is not a failure to reach the density this section asks for, it is what
+that density is here.
+
+🚨 **There is a third situation, and it is the one where nothing in the loop can
+help you: a tolerance under the accuracy of whatever produced the series.** The
+arithmetic above is about the *subject*; this is about the *estimator*. A fitted
+series is only as good as its objective's basin, and a tolerance below that width
+buys keys that encode the fitter's wander — and **`check` cannot see that it
+happened**, because two candidates that are both inside tolerance render the same
+pixels. `diff`'s `key_counts` sees it and `diff` is the finish line, so a run gets
+one shot at the number. Rung 4's is the recorded case: it declared 0.28 px, and its
+own objective's basin on the shortest lever in the chain measured **±1.5°**, which
+is ±0.5 px there — so the declared figure was under the noise, and it shipped about
+three times the reference's key count (`key_counts` 421/1339) with every other
+animation measure at or near 1.000. ⇒ **Measure the basin before you declare the
+tolerance**, which costs nothing and needs no reference: scan each knob around its
+converged value and read how far it moves before the objective does. Then declare a
+tolerance at or above the widest of them, and record both numbers.
+
+**A rig's parameters are not identified by its pixels — remove the gauges before you
+key.** A bone that carries no attachment is an exact gauge: turn it by δ, turn its
+children back by δ, and **not one pixel changes**. Anything optimising against pixels
+is free to wander along that direction, and it does. On the spineboy run the figure's
+topmost body bone carries no art and every moving bone sits under it, and a
+coordinate descent walked it to **+181°** against its child's **−184°** — a pose
+whose picture is right on every frame and whose key series spins the whole figure
+through a full turn between two of them. The rendered result is correct and the
+authored rig is nonsense, and no amount of further fitting finds it, because every
+point on the gauge orbit has identical error. ⇒ Fold each gauge out *before* the
+series becomes keys — for a rotation gauge, take the median of the values along the
+chain and fold it back. The same shape exists wherever a transform is unobservable: a
+bone with no art, a slot-less parent chain, a uniform scale split across two bones.
+
+⚠️ **That fold is exact only when the gauge bone's children sit at its own origin** —
+and a character's body bone almost never has them there, which is the very shape the
+paragraph above was written from. Turn the parent by δ and a child *at the origin*
+back by δ and the child is where it was; a child sitting 10 units off swings through
+an arc of that radius first, and the counter-turn only spins it on the spot. The fold
+moves art, so it **changes the picture**. Measured on the second spineboy run, whose
+`hip` carries no attachment and has three children 9–13 units off it: the fold cost
+**3 MAE on every `idle` frame** — mean 23.0 with it against 19.9 without, same search
+— and it was removed. ⇒ Read the children's offsets before you fold. At the origin,
+fold: it is exact and it is cheap. Off the origin the degeneracy is still there but
+it is **soft**, not exact, and a soft degeneracy is *regularised, not folded* — leave
+the values alone and add a penalty on the gauge direction to the objective instead.
+That run used **2e-5 per squared degree** of hip rotation: invisible at animator-sized
+angles, and still decisive against the +181° against −184° above.
+
 ### 10.4 Curves
 
 📗 **Linear is what a *new* key gets, and it does not survive contact with a curve.**
@@ -1250,6 +2177,35 @@ and **Ease in** (*"the value changes more slowly near the next key"*) —
 across the file, is how an editor rig reads. Raw `curve` is R6's escape hatch — one
 key needing a shape no other key has — not the normal way to write a curve.
 
+🚨 **The table is a constraint on where the keys go, not a formatting step applied
+afterwards — it has to exist while the keys are chosen.** A run that plans its keys
+by fitting each span's **own** handles, and then writes the nearest entry of a named
+table, has bought a key count at one tolerance and shipped it at another. Nothing in
+the loop can see that: the timeline count, the key count, the curve kinds and the
+duration are all unmoved, so `diff` does not shift and the gate stays green, while
+the rendered result changes by a multiple. Rung 8's first version did exactly this
+and went from **1.07 to 4.65 MAE** — four times its own fit's floor. ⇒ Two passes.
+Pass A fits freely and exists only to *discover* which shapes the shot uses; those
+are clustered into the table; pass B re-plans **every** timeline under the table it
+will actually write. Never fit free handles and substitute the nearest named shape
+after the fact. (The table's size then trades against the key count at a fixed
+tolerance — that shot ran 4 easings/368 keys, 8/314, 12/300, 16/284 — because a
+richer table holds more spans.) This is rung 6's clamp defect in another suit:
+**a constraint that is not enforced where the value is written is not a
+constraint.**
+
+🧩 **⇒ A span with no interior sample takes the automatic handles, not linear.** Two
+keys on adjacent samples leave pass B nothing to fit — the samples cannot constrain
+that span's shape at all — and a planner with nothing to fit leaves `ease` off, which
+is linear (§4.5): the one shape this section says to argue for rather than default to.
+"No information" is not an argument for constant speed. Take instead the tangents the
+keys either side imply — the editor's own **automatic handles**, quoted above — and
+snap *those* to the nearest table entry, exactly as you would a fitted span. Rung 8's
+second version did this for its adjacent pairs and the samples barely moved (**17.34 →
+17.26 MAE**) while `curve_kinds` changed wholesale: nil in the frames, large in the
+structure, which is the signature of a convention rather than a fidelity fix — and
+this section's whole subject.
+
 📗 **Handles are normalised, and that is the shape an `easings` entry takes.** For a
 Bezier key, *"the X axis is from 0 to 1 and represents the percent of time between
 the two keyframes. The Y axis is from 0 to 1 and represents the percent of the