spine-rigc 0.3.0 → 0.5.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,111 @@ 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.
+
+⭐ **That dilution has a *temporal* cousin, and it bites inside a single shot's own
+per-frame fit.** The paragraph above is about two builds and a whole-shot figure; this is
+about one build and a whole-*figure* objective. Where a passage's motion is **a small
+part moving against a large, nearly still body** — a hand, a head, a prop, while
+everything else holds — the moving part is a tiny share of the ink, so a whole-figure
+score is dominated by the still majority. Every frame then reports a good number
+*individually*, the fit converges, and the passage comes out **static**: the mover was
+never worth enough of the objective to pull the search toward it.
+
+⚠️ **Nothing else in the loop catches this.** The MAE is fine, the drift is fine on every
+part that is not moving, and `validate` and `diff` never look at a rendered frame. What
+does see it is §10.3's change column, in its **under-change** direction — and by the time
+it tells you, the poses are already wrong, because a key plan cannot add motion the poses
+do not have.
+
+⇒ **Weight the objective by the reference's own frame-to-frame change.** Build a mask
+from where the reference *changes* between the two frames bracketing the one you are
+fitting, and weight the score by it — so the pixels that carry the passage's motion carry
+the passage's objective. It costs one extra difference per frame, needs nothing but the
+frames, and it turns an untrackable passage into an ordinary one.
+
+📌 **Read the mask itself before you trust the fit, because it also tells you what is
+actually moving** — which is frequently not what the shot looks like it is about. A
+passage that reads as one limb waving can turn out to carry most of its change somewhere
+else entirely (a body-wide micro-rocking, a shadow, a trailing part), and a fitter aimed
+at the limb would have been chasing the minority of the evidence. The mask is the cheap
+way to find that out first.
+
+**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 +1206,58 @@ 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.
+
+🚨 **Before you fit a chain at all, check that it can *reach* the extremes the shot
+visits — a reach deficit is invisible to every per-frame fit.** This is the precondition
+the borrow rule assumes and the loop does not check. If a chain's segment lengths are
+short — read off a pose where the chain is **folded**, which is the easiest reading to
+take and the one most likely to be wrong — then every frame where the chain is folded
+fits beautifully, and the fitter *silently absorbs* the deficit on every other frame by
+rotating the parts it does have. Nothing reports a failure. The number is merely a little
+worse everywhere, which reads like an ordinary residual, until a passage needs the full
+extension and then no start converges anywhere near it — and multi-start does not help,
+because the pose being searched for is **outside the chain's reachable set**.
+
+⇒ **The check is arithmetic and needs no fit.** Take the chain's total reach from your own
+rig; take the longest excursion the shot's own frames show that chain's end travelling —
+a pendulum's full swing, a limb's extreme, a prop's sweep — and compare. If the shot asks
+for markedly more than the chain has, the rig is wrong and no amount of searching will say
+so. ⭐ **A frames-side reading beats a rig-side one here**: the shot's own extremes are a
+measurement, while segment lengths taken off a folded pose are an estimate — so when they
+disagree, suspect the estimate. And do this **per chain, before its first fit**, because
+the surgery to fix it invalidates every pose already fitted with the short chain.
+
 **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
@@ -1072,6 +1270,47 @@ against a handful of frames drawn from **every** animation at once, and hold it
 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.
 
+🚨 **That rule is not sufficient for a *joint*, and the difference is not a matter of
+degree.** An attachment offset is identified by a spread of *rotations*; a **pivot** — the
+point one bone turns about relative to its parent — is identified only by frames whose
+**relative rotation across that joint actually differs**. So a spread can draw frames from
+every single shot, satisfy the paragraph above to the letter, and still be
+**ill-conditioned**: if every shot holds that joint at much the same relative angle, the
+pivot is barely constrained, and a wrong one re-solves far away *at equal residuals*. Equal
+residuals is the trap — nothing in the fit reports a problem, because there genuinely is no
+better answer within the data you gave it.
+
+🚫 **And a structural descent that holds the fitted poses fixed cannot recover a
+mis-triangulated pivot at all.** This is the part worth internalising, because it looks
+like the obvious repair and it is inert: the per-frame poses were *fitted against the wrong
+pivot*, so they have already absorbed its error. Move the pivot with those poses held and
+every frame gets worse; hold the pivot and refit the poses and they re-absorb it. **The
+gradient at fixed poses points nowhere**, so the descent reports convergence on the wrong
+geometry — and multi-start does not help either, because the defect is not a basin you
+failed to reach, it is a parameter the objective is no longer a function of.
+
+⇒ **Triangulate a joint from part template matches across *configurations*, not from the
+whole-figure objective.** Match the two parts the joint connects — each is its own art file
+and its own reading — on frames that put the joint in **genuinely different relative
+angles**, and solve for the one point that is fixed in both parts' own coordinates. Then
+refit the poses against the corrected pivot. Two practical notes:
+
+- ⭐ **"Different configurations" means what the shot list looks like, not how many frames
+  you took.** A figure standing, walking and running may hold one joint at nearly the same
+  angle throughout; a figure **lying down**, or inverted, or reaching across itself, is what
+  makes that joint observable. Pick frames for *angular diversity across the joint*, and if
+  the shot list has only one configuration, say in the log that the pivot is a prior.
+- 📌 **Check the conditioning rather than trusting the fit**: re-solve the joint from a
+  subset that excludes the diverse configurations and see how far the answer moves. If it
+  moves a long way at comparable residuals, the diverse frames were carrying the whole
+  identification — which is exactly the state in which an earlier triangulation goes wrong
+  silently.
+- ⚠️ **Sequence matters, because the surgery invalidates work.** Correcting a pivot
+  invalidates every pose fitted under the old one, so do it **before** the per-frame fitting
+  budget is spent, not after. When it has to be done late, expect to re-settle every channel
+  hung off that joint — and freeze the ones that are not, so the two effects stay separable
+  in the record.
+
 **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
@@ -1126,6 +1365,23 @@ not a quiet one.** The matcher refuses to name a distance past the part's own si
 (§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.
 
+⚠️ **Excess adjacency change has a second diagnosis, and the rule above assumes the
+first.** *A limb has left its place* is one cause — a fit that teleported, which is what
+a blank drift and a high figure per pixel together point at. The other is **two
+independent per-frame residuals adding**: every pose inside its own accuracy, nothing
+lost, and the *difference* between two neighbours nonetheless several times the
+reference's. The fixes are opposite — the first wants the search bounded or restarted,
+the second wants the neighbouring poses drawn toward each other (§10.3's own note on
+this) — so guessing costs a round either way.
+
+⇒ **Separate them by asking how much freedom the neighbour-mean step actually had.**
+Measure, over every neighbouring pair in the shot, how many of those steps your own
+constraints left **free** to move: if the answer is a percent or two of them, then the
+search was not free to teleport anything, and the excess is residuals adding rather than
+a lost limb. It is one count over data the
+fit already produced, and it is worth more than an afternoon of restarts aimed at the
+wrong cause.
+
 **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
@@ -1153,19 +1409,42 @@ 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.
+
+⭐ **Do not treat such a set's two stills as bookends. They are full-resolution frames
+at their own rate, and one of them is routinely a pose no other set on disk carries.**
+The temptation is to read a strided set as *a sheet, plus two files that fix the
+framing* — the sheet is where the shot is, so the stills look like plumbing. But the
+last still is the animation's **own last sample at that rate**, and a finer rate lands
+on a different instant: a shot whose length is not a multiple of the coarse interval
+ends *between* two coarse samples, so the coarse set's last frame is not the end of the
+shot and the finer set's is. If the shot is still moving there — and an end pose usually
+is the part that moves most — that pose exists in exactly one file, at full resolution,
+and it is worth fitting like any other frame.
+
+⇒ **Two consequences for a run.** ① **Fit every committed still**, at every rate, and
+do not let a "sheets are for timing" habit skip them; a pose you never fitted is a pose
+you guessed, and a hold written across the gap because nothing on disk contradicted it
+is a **fabrication** rather than a simplification. ② This is the same fact a brief
+states from the timing side when it warns you against declaring the coarse set's
+rounded length: the rounding and the missing pose are one arithmetic, seen twice. If
+your shot's length is not a whole number of coarse intervals, expect **both** — a
+duration the coarse sidecar understates, and a terminal pose only the finer set shows
+you.
 
 `--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 +1501,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 +1559,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 +1591,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 +1603,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
@@ -1324,6 +1611,145 @@ 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.
 
+🚨 **And the mirror image of all three: an objective that *improves by removing the
+subject*.** The traps above are each *"the number will not move"*, and they train you
+to distrust a still figure. The twin is a figure that moves, in the right direction,
+for the wrong reason — and it is the more dangerous one, because progress is what it
+looks like.
+
+The shape is arithmetic, not a bug. **Any symmetric error over two silhouettes charges
+a mismatch in both directions**, so it charges your ink that the reference has none
+under *and* the reference's ink you leave bare. Give it a candidate that draws
+**nothing** and only the second term survives: the score is the reference's own ink,
+once, and it is a *finite, respectable-looking number*. A part that is present but
+badly posed pays both terms and can score **worse than absence**. ⇒ A search with a
+free enough range finds the cliff and walks off it, and every step of the walk reports
+as an improvement. Synthetic illustration of the whole failure in three rows — one
+part, one objective, nothing else changed:
+
+| what the candidate does | part error |
+| --- | --- |
+| posed roughly right | 2.15 |
+| posed badly — overlapping the wrong reference ink | 2.48 |
+| **translated clean off the frame** | **1.00** |
+
+The search reports **1.00 against 2.15** and calls it a 53 % gain. What it found was
+the absence of a subject. ⚠️ **1.00 is not a coincidence in that table, it is the
+construction**: absence pays the reference's ink exactly once, so on any objective
+normalised by that ink, *"draw nothing"* sits at 1.0 by arithmetic — which is why it is
+worth evaluating deliberately rather than discovering.
+
+⇒ **Four defences, and the first is the cheap one.**
+
+- **Bound the search to the frame.** A part cannot legitimately leave the picture on a
+  shot whose frames all draw it, so a translation range wide enough to exit the
+  viewport is a range that contains a false optimum. Bound each parameter by what the
+  frames can *show*, not by what the format permits.
+  - ⚠️ **And its converse, which is the easier half to get wrong: a bound has to
+    *reach* what the frames show, not merely stop where they stop.** The two failures
+    look nothing alike — a bound that is too wide loses a fit to the cliff, a bound
+    that is too narrow loses one to a wall it never reports hitting. Bounding a
+    vertical channel to the range the *rest* pose occupies is the classic case: a shot
+    that drops its subject in from hundreds of pixels above the standing pose puts its
+    own entry outside the search entirely, and the fitter returns the best pose *it was
+    allowed*, which is the top of the box, silently. ⇒ **Take each channel's range from
+    the brief and the frames — the extremes the shot actually visits — and then check
+    afterwards how many converged values are sitting on a bound.** A knob resting
+    exactly on its limit is the signature, and it costs one line to print.
+- **Assert the part is drawn, every iteration.** Count your own ink for that part and
+  reject any candidate whose count is zero or a small fraction of the reference's. This
+  is one comparison and it makes the cliff unreachable rather than merely unattractive.
+  - ⚠️ **Write it at the resolution the level is actually being evaluated at.** On a
+    coarse-to-fine pyramid, a threshold expressed in full-resolution pixel counts
+    refuses **every** coarse pose — and a rejection that fires on everything is
+    indistinguishable from an objective with no gradient. You get `Infinity`, or a
+    figure far worse than the same search reaches with the assert switched off, and
+    nothing in either says *"your guard is the problem"*. ⇒ Express the count as a
+    **fraction of the reference's ink at that same level**, so the test means the same
+    thing at every rung of the pyramid.
+- **Charge ink that leaves the window, because the cliff has a second entrance.** If
+  your objective is computed inside a window around the reference's own drawn box —
+  and it usually is, since that is what makes it cheap — then ink outside the window
+  costs **nothing**, and the three defences above do not reach that: the part is still
+  drawn, its count is still healthy, and the score still falls. The fitter hangs a part
+  a few hundred pixels below the frame and reports progress every step. ⇒ **Count your
+  own ink further than a small margin outside the reference's drawn box and charge it.**
+  One line, in the same place as the ink count, and it closes the entrance the bound
+  closes only when the bound happens to be tight enough.
+- **Read the objective's floor before you trust its direction.** Evaluate *"draw
+  nothing"* once, deliberately, and keep the figure. Any score at or below it is the
+  cliff, whatever the search says — and if your best honest pose is *above* that floor,
+  the objective is ranking absence over effort and needs an asymmetry (charge bare
+  reference ink more than stray candidate ink) before it is safe to optimise against.
+
+📌 **`check` itself is not exposed to this** — its `MAE in it` and `share` columns
+divide over the **reference's** own drawn pixels and a chain that draws nothing reads
+0 % on 0 slots, which §9.2 says is the loudest row in the table and not the quietest.
+The trap lives in the objectives **you** write inside a fit, where the denominator is
+yours to choose.
+
+🚨 **The cliff's nearest cousin, and the one that survives all four defences:
+*sacrificial cover*.** Every defence above protects a part from being **removed**. None
+protects a part from being **moved somewhere wrong on purpose**. A whole-figure objective
+scores one number over every pixel, so when part A is mis-placed and leaves reference ink
+bare, the cheapest available improvement is frequently to drag **part B off its own correct
+place to cover that ink**. Both parts are drawn, both counts are healthy, nothing leaves
+the window — and the score genuinely falls, because covering bare ink is worth more to a
+blunt objective than B's own displacement costs it.
+
+⚠️ **What makes it expensive is that the objective is not lying.** The pose it prefers
+really is better *by that measure*. So the loop offers no signal at all: the fit converges,
+the number improves, and what you have is one part visibly out of place standing in for
+another. It surfaces later as a **drift** on the sacrificed part — a slot several pixels
+from where the frames put it inside a pose whose overall figure looks fine — which is the
+one measure that reads parts individually.
+
+⇒ **Two ways to catch it, and the first is nearly free.**
+
+- **Read a per-part residual beside the composite, never only the composite.** Score each
+  part against its own template match as well, and flag any frame where the composite
+  improves while a part's own residual worsens. That divergence *is* the signature; the
+  composite alone cannot express it.
+- **Seed the parts analytically from their own measured features, then refine jointly with
+  the sacrificed part pinned.** If a part's place is independently measurable — a colour
+  feature, a template peak, a contact row the brief gives you — put it there first rather
+  than letting the composite negotiate it, and hold the part that was being abused fixed
+  while the rest re-settles.
+
+⚖️ **Expect the corrected pose to score *worse* on the composite, and record that as a
+trade.** A few percent worse on your own objective while decisively better on every
+frame-derived placement instrument is the **expected** shape of this repair, not a
+regression — the composite's preference was the defect. Declare an accept threshold before
+you need it, say how often you used it, and name the frames. ⭐ **And prefer the
+frame-derived instruments when they disagree with the composite about a single part's
+place**: the composite is one number over everything, while a template match on that part's
+own art is a measurement of the thing in question.
+
+🚨 **One more inert-write trap, and it is on the way *out* of the fit rather than
+inside it: your compiled animation is not your pose series.** Everything above is about
+a search that reads the wrong thing; this is about a search that was right and an
+emission that was not. The formats differ in a way that is easy to miss — **a translate
+key is an offset from the setup pose, while a fitter almost always drives the absolute
+local position** — so writing the fitted numbers straight into keys applies the setup
+offset a second time and displaces the whole figure by it.
+
+⚠️ **What makes it expensive is how it presents.** `build` is green: the numbers are
+finite, the durations agree, nothing is degenerate. And `check` does not say *"your keys
+are offset"* — it says the union box is a fifth larger than the reference's, the MAE is
+several times anything a wrong pose produces, and no slot is attributable anywhere.
+That reads like a **wrong rig**, so the hours go into the rig.
+
+⇒ **Before reading a single measure, sample your own compiled animation and diff it
+against the pose series the fitter produced.** `sampleAnimation` in
+[`src/render.ts`](../src/render.ts) is the same stepper the frames were made with, so
+this is a handful of lines and it is exact: for every frame, for every bone, the local
+transform the file plays back against the local transform you fitted. A constant offset
+per channel is this bug; a constant *factor* is a unit or lever mistake; zeros
+everywhere are §9.1's `bone.pose` trap one level earlier. ⭐ **The general rule: a
+pipeline with a fit at one end and a file at the other needs one check that the file
+plays what the fit found**, and it belongs before the measures rather than after a day
+of them.
+
 ### 9.2 Reading the table
 
 ```
@@ -1331,6 +1757,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 +1767,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 +1830,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 +1846,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 +1897,110 @@ 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.
+
+🚨 **And a third, which decides whether the recipe measures anything at all: `--atlas`
+substitutes region *geometry* as well as texture.** The diagnostic's logic is *"same
+skeleton, same keys, the reference's own texture"* — but an atlas entry is not only a
+page and a rectangle. It also carries how the region was packed: **`rotate`**, and the
+trim offsets that say where the opaque part sits inside the original image. Swap the
+atlas and your attachments are re-seated on those, so the quads change too.
+
+⇒ **The recipe measures a floor only when the substitution is *"same quads, coarser
+texture"*.** Where the supplied atlas packs its regions **rotated or trimmed** and your
+attachments were measured off the loose PNGs, it is not — and the tell is unmistakable:
+**the number goes the wrong way.** A texture floor can only *explain* error, so a
+diagnostic that sends the MAE **up** on every set has substituted geometry, not just
+pixels, and the run's own atlas was the more faithful of the two.
+
+⚠️ **Then the honest verdict is *inconclusive*, not *no floor*.** Both readings stay
+open — there may be a texture floor this diagnostic cannot isolate — so record the
+figures, say the substitution changed the quads, and do **not** convert a failed
+diagnostic into a claim about the shot. ⇒ Check the atlas's own entries for `rotate` and
+for trim before you run it; that is one look at a text file, and it tells you in advance
+whether the number you are about to take will mean anything.
+
+🚨 **The precondition the advice above does not state: a floor measured with another
+part misplaced is not a floor.** Measuring at the rest pose is right — it is the one
+pose you can often *prove*, because the setup pose is the art at its own scale and the
+frames state the standing dimensions — but "the pose is provably right" is a claim
+about **one part**, and the floor you read is a whole-figure number. Any other part
+that can occlude the one you are measuring is inside that number too, and a part
+sitting tens of units off its place occludes the **wrong** pixels: the ones it hides
+count as yours-and-not-theirs, the ones it should have hidden count as
+theirs-and-not-yours, and both land on the part you thought you were isolating.
+
+The damage is that you then hold a *plausible* floor and calibrate against it. A
+synthetic case with the same shape — one part measured three ways, nothing about that
+part changed between the rows:
+
+| what else is placed | silhouette IoU read for the measured part |
+| --- | --- |
+| a neighbour still tens of units out of place | 0.74 |
+| that neighbour placed | **0.95** |
+| (the difference) | 0.21, all of it the neighbour |
+
+A fifth of an IoU is larger than most of what a fit is trying to buy, so two or three
+experiments get read against the wrong baseline before anything exposes it — and what
+usually exposes it is the setup fit finishing, which is *after* you needed the number.
+
+⇒ **Before believing a floor, check that every part which can occlude the one you are
+measuring is already placed** — and prefer a frame where the parts are **far apart or
+only one is drawn** to one where they overlap, which is §8.1's rule for calibrating a
+two-part assignment applied to a floor. If no such frame exists, say in the log that
+the floor is an upper bound on the error rather than a floor under it. ⚠️ This is the
+same failure as capturing a guard's expected value from a screen that is already
+broken: the baseline records the defect, and then the *repair* is what looks wrong.
+
+⚖️ **`frames.json`'s own box can be refused for a reason that is not a coordinate
+error, and there is an honest answer.** The test is on **extent**: a candidate authored
+in the frames' own world units — one whose setup box lands on the reference's to the
+pixel — still fails it if its union content box differs by a few pixels at the
+extremes, because one part reaching somewhere nothing in the frames reaches is enough.
+`check` then fits its own box, and on a multi-shot root the fitted framing costs every
+set some MAE against the declared one — the same order as the shared-versus-per-set gap
+the `--framing` flag's own help quotes, and easily more than a round of fitting buys.
+That cost is real and it is **not** a sign you got the coordinates wrong.
+
+⇒ **Report both, label which is which, and say what separates them.** Run `check`
+unaided — that is the figure the artifact produces on its own and the one that belongs
+in a run's record — then run it once more with `--viewport` on the declared box and keep
+that output as a **named diagnostic file** beside the first. The gap between them is the
+framing; what is left is the keys, which is the only reason to want the second number.
+🚫 **The pinned run is never the record.** `--viewport` is a claim about your own
+coordinates and `check` says so above every figure it prints under one: *nothing checks
+it*. And do not chase the refusal by shrinking a part to fit the box — that trades a
+framing cost for a wrong silhouette, which is worse in every column that matters.
+Instead read the `content` line's own advice: it names how much wider and shorter you
+cover, and **which part reaches too far is a drift question**, not a framing one.
+
 **`Δ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 +2026,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 +2075,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 +2109,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
@@ -1536,6 +2137,19 @@ a per-shot list. **§8.1** is how to act on it: the next iteration goes to the w
 chain by error per pixel, and a chain already at the floor is frozen rather than
 re-fitted.
 
+⚠️ **One exception to "0 % is the loudest row", and on a mesh rig it is the common
+case: a chain whose roster reads `(draws nothing)` rather than `0/n`.** Those are two
+different states and the table prints them differently. `0 %` on `0/3` **slots drawn**
+means three slots exist on that chain and none of them put ink on the frame — that is
+the loud row, and it is a missing part. `(draws nothing)` in the **bones** roster means
+the chain carries **no slot at all**, and a mesh's control bones are exactly that: the
+mesh attachment lives on the slot of the bone the mesh hangs from, so the bones that
+*deform* it own nothing to draw. ⇒ **On a mesh rig that row is normal and quiet.** Read
+the roster at the foot of the report before reacting to a chain's share: if the chain's
+slots column is a parenthesis rather than a fraction, the deformation it carries is
+already being scored inside the chain that owns the slot, and the row is telling you
+about your bone tree rather than about a hole in your figure.
+
 ### 9.3 What it still cannot see
 
 - **Anything a frame does not contain.** Bone `length`, the setup `inherit` mode,
@@ -1566,10 +2180,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 +2340,146 @@ 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*.
+
+⚠️ **The opposite defect exists and forcing keys makes it worse.** Everything above is
+one direction — *my curve slopes through a plateau the reference holds* — and its fix is
+to force both ends as keys. The other direction is *my candidate moves several times
+what the reference does on a pair the reference barely moves across*, and if you reach
+for the same fix you will pin the excess in place instead of removing it. **The cause is
+different**: there the key plan was smoothing away motion the shot has; here the key
+plan is faithful and what disagrees is the **per-frame residual** — two neighbouring
+poses each a little off, in opposite directions, so the *difference* between them is
+several times either error. Forcing both as keys asks the planner to reproduce exactly
+the two poses whose disagreement is the problem.
+
+⭐ **Diagnose it before you fix it, with one comparison.** Take the two frames the column
+flags and ask whether your **poses** at those two frames are each inside your own fitting
+accuracy. If they are — and the pair still disagrees — the defect is the residual and not
+the plan. Synthetic case, one pair:
+
+| | reference moves | candidate moves | each pose's own error |
+| --- | --- | --- | --- |
+| a quiet pair | 0.8 px | 4.1 px | 1.6 px and 1.7 px, opposite signs |
+
+Both poses are ordinary; the pair is a five-fold disagreement built out of them.
+
+⇒ **The fix has the same shape as the relative floor above: make the smoothing slack
+relative to the reference's own local change.** Where the reference barely moves,
+contract your neighbouring poses toward each other until your own frame-to-frame change
+is inside the band — accepting a small, *bounded* loss of fidelity on those frames in
+exchange for the one measure that can see a hold. ⚠️ **That is a trade and it is recorded
+as a trade**: name the frames, name the cost per frame, and say in the log that you took
+it. A contraction reported as a fit is the same dishonesty as a hold reported as a
+measurement, and the cost is real — the frames you contracted are slightly less faithful
+than they were.
+
+🚨 **Contract the *planned curves*, not the pose series — the report never sees the pose
+series.** This is one sentence and it is worth two builds: the change column measures
+your **compiled animation sampled at the frames' own rate**, and between your poses and
+that lie the key reduction and the curves. Contract before the reduction and you have
+adjusted a series nothing downstream reads — the planner then re-fits its spans through
+the adjusted poses, the interpolants land where the tolerance allows, and the pair you
+were aiming at comes back out of band having *moved*. ⇒ **Apply the contraction where
+the measurement is taken**: plan the keys, sample the planned curves, find the offending
+pairs, and contract *those samples* by forcing or moving the keys that produce them —
+then re-plan and re-sample. That is the closing loop below, and its subject is the curve
+series throughout.
+
+⚠️ **And aim *inside* the band, not at it.** `check`'s thresholds are exact and stated in
+[`src/check.ts`](../src/check.ts), so it is tempting to converge until every pair is
+just inside. But a run measuring its own change renders in **its own framing**, and the
+report renders in the one `check` chose — and a fraction of a percent of scale is worth
+a few percent of a pixel count. A pair you cleared by a hair in your loop can sit the
+wrong side of the same threshold in the report, on a difference that is entirely
+framing. ⇒ Converge to a **margin** — clear the band by enough that a percent of scale
+cannot cross it — and re-read the real report before believing the column.
+
+🚨 **There is a third direction, and on a busy shot it is the binding one: your candidate
+moving too *little*.** The two cases above are both *you moved when you should not have*
+— a hold that is not held, and excess change on a quiet pair. But `check`'s rule is
+**two-sided**: it faults a pair when **either** side moves several times the other by
+more than its pixel floor. So the mirror case is a reference that is genuinely busy and
+a candidate that reproduces a fraction of it, and nothing in the two paragraphs above
+names it.
+
+⭐ **The practical form is a floor rather than a ceiling: on every pair the reference
+moves, yours has to move at least about a quarter as much.** Read the exact multiple and
+the pixel floor out of [`src/check.ts`](../src/check.ts) rather than trusting the
+approximation — but plan against the floor, because it behaves quite differently from
+the ceiling:
+
+- **It is not fixed by keys.** Over-change is a planning artefact you can force or
+  contract away. Under-change means the *poses themselves* barely differ, so no key plan
+  recovers it — the fit has to find more motion before the planner sees any.
+- **It is where a whole-figure objective fails hardest**, which is why the item below
+  belongs beside it: a passage whose motion is a small part against a large still body
+  contributes almost nothing to a whole-shot score, so a fitter converges happily on a
+  near-static series and every pose looks fine on its own.
+- ⚠️ **And the band will accept a shot that is visibly underplayed.** Clearing the floor
+  at a quarter is not reproducing the motion; it is not *failing* it. A run whose busy
+  passage sits near the floor should say so in the log as a known-weak passage rather than
+  quote the column as if it were a fidelity result — the column is a **band**, and a band
+  is the widest thing that passes, not the thing you were aiming at.
+
+⭐ **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 +2512,87 @@ 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.
+
+⚖️ **Read that last sentence with the rule two paragraphs up, because taken literally
+the two pull apart — and the resolution is that the basin is a *per-channel floor*,
+not a second global declaration.** The tension is real: *declare one tolerance* asks
+for a single figure in one unit so the density trade reads as one curve, while
+*declare at or above the widest basin* points at the worst-identified knob in the rig.
+Those can differ by **an order of magnitude** — a well-levered channel the objective
+pins to a fraction of a pixel sitting in the same rig as a part the objective barely
+sees at all, whose basin is several pixels wide. Take the widest and every good channel
+is keyed to the worst one's ignorance; take the declared figure alone and the bad
+channel ships the fitter's wander as data.
+
+⭐ **What decides it: a basin belongs to the estimator that wrote the channel, and a
+run that fits poses has more than one.** The two rules are answering different
+questions. *One tolerance* is about the **unit and comparability** of the figure you
+declare — that survives untouched. *The basin* is about the **noise under a particular
+series**, and noise is a property of the estimator on that channel, not of the rig. So:
+
+> **Declare one tolerance, in pixels at the end of what each bone swings. Then floor it
+> per channel at that channel's own basin, capped.** Effective tolerance for a channel
+> = `max(declared, min(that channel's basin, cap))`.
+
+- **Why per channel** — the thing the floor protects against is encoding wander, and
+  wander is per channel. A global maximum spends keys nowhere they were needed and
+  removes them nowhere they were wrong.
+- **Why a cap, and this is the part worth understanding.** The basin bounds **what you
+  know**; the tolerance also bounds **what you render**, and the rendered series is read
+  by `check`'s change column at *zero* slack (§9.2). So an uncapped floor lets a
+  badly-identified channel buy a reduction error large enough to show up as motion the
+  reference does not have — trading a measure nothing reads for one read at zero
+  tolerance, which is the wrong direction. A cap of a pixel or two, declared and
+  recorded, bounds the reduction error whatever the identifiability.
+- ⇒ **And a channel whose basin exceeds the cap is telling you it is not identified,
+  which is a different problem with a different fix.** The answer there is a **prior** —
+  regularise the channel toward a smooth trend and say in the log that you did — not a
+  tolerance wide enough to key it three times and call the result a measurement. ⚠️ Such
+  a channel is *partly a prior rather than a measurement*, and a run that does this
+  records which channels and over which passages, exactly as it records a contraction
+  trade below.
+
+📌 **Record all three numbers**: the declared tolerance, each floored channel's basin,
+and the cap. `diff`'s `key_counts` is the finish line and a run gets one shot at it, so
+the arithmetic that produced the density is the only thing that makes the figure
+readable afterwards.
+
 **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