spine-rigc 0.3.0 → 0.4.0

package/docs/AUTHORING.md

@@ -18,7 +18,10 @@ 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; **§8.1** if the figure has more joints than you
   can measure one at a time; then **§9** for the loop that closes it
@@ -26,6 +29,22 @@ that can see that, and a run that skips it has verified nothing about the motion
   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
@@ -60,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`,
@@ -73,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 |
@@ -263,8 +295,8 @@ 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, see
-[`bench/runs/README.md`](../bench/runs/README.md), *What a run may read*.)
+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
 
@@ -603,6 +635,26 @@ stepped.
   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
@@ -956,17 +1008,83 @@ frames did not show the rest, and rendering like-for-like settled three more of
 — worth a measurable drop in window MAE, a convention the gate cannot see and the
 measures can.
 
-⚠️ **The same test knows when to stay silent, and you have to let it.** Run on
-another shot, two orders came out **0.8 % apart over the whole shot and pointing
-opposite ways** — a gap well inside the objective's own scatter, which
-is correctly *no answer*. A difference that small is not a quiet vote for the
-winner; it means the frames do not decide this edge, and you ship it on reasoning
-and say in the log that is what you did.
+**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
@@ -1060,6 +1178,38 @@ the other two. Where a chain ends in something whose position you can actually s
 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
@@ -1153,19 +1303,21 @@ 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 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.
+⭐ **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
@@ -1222,8 +1374,10 @@ 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. Each
-set says which it got on its own `framed to` line.
+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):
 
@@ -1278,6 +1432,13 @@ 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
@@ -1303,8 +1464,8 @@ 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
-([`bench/runs/2026-08-23-spineboy-2/LOOP.md`](../bench/runs/2026-08-23-spineboy-2/LOOP.md),
-§4.1). Note that the two names are not the same thing: `bone.data.setupPose` is
+(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.
 
@@ -1315,8 +1476,7 @@ stores; what gets drawn is that stored quad — `computeWorldVertices` reads
 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
-([`bench/runs/2026-08-23-spineboy-2/LOOP.md`](../bench/runs/2026-08-23-spineboy-2/LOOP.md),
-§4.2).
+(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
@@ -1331,6 +1491,7 @@ cannot.
   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 ──
@@ -1340,6 +1501,8 @@ cannot.
      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
@@ -1401,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.
@@ -1411,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
@@ -1441,6 +1631,35 @@ much ink as the reference does gets `⚠️ overdraw` beside those two numbers,
 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
@@ -1466,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,
@@ -1481,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
@@ -1508,19 +1768,19 @@ a part you have not authored, or one you have put somewhere else entirely.
 ```
      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
-       neck                    5/5   3.0 px "goggles" f0004              2.3 px       30.37    24.3%
-       rear-upper-arm          6/6   2.2 px "gun" f0000                  1.4 px       46.26    34.6%
-       front-thigh             3/3   16.3 px "front-shin" f0003          7.2 px       48.18     9.0%
+       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 `torso` that branches three ways joins the trunk rather
+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 (`neck`,
-`front-thigh`, the gun arm); 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
+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
@@ -1566,10 +1826,22 @@ re-fitted.
   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.
 
 ---
 
@@ -1714,6 +1986,66 @@ that is not held"* from the other side, and the same place catches it — a slop
 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
 preset exists for *"changing directions abruptly, such as when a ball bounces"* —
@@ -1746,6 +2078,43 @@ by that bone's lever arm. With that, the whole trade reads as one curve and you
 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