spine-rigc 0.26.0 → 0.28.0

package/README.md

@@ -533,9 +533,9 @@ first three work on any reference you have, and `bench` is a repository workflow
 and `bun run fetch-examples`. The reasoning behind them is in
 [the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 
-`build` and `validate` both default to `--profile spine` — the 29 validity rules, which
+`build` and `validate` both default to `--profile spine` — the 30 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
-adds all 44: the other 15 are one renderer's policy and one canvas budget's, and they
+adds all 45: the other 15 are one renderer's policy and one canvas budget's, and they
 fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
 ⇒ **That reason is about foreign data and does not carry to a rig you are authoring
 yourself: author under `--profile spine-html` and read the extra 15 as findings, and
@@ -681,7 +681,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | Spine 4.3's full export surface against what rigc emits and what the official examples measurably use, with the ordered gap list |
-| 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 44 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
+| 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 45 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
 | 🗺️ [ROADMAP.md](https://github.com/firejune/rigc/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 has to mean before the number is claimed — conditions rather than a feature list, because direction here comes from what users hit |
 | 📐 [CLAUDE.md](https://github.com/firejune/rigc/blob/main/CLAUDE.md) | **the doctrine** — why the validator's messages are the product, why nothing reaches disk before green, why no number is ever invented, and what a change has to keep. [CONTRIBUTING.md](https://github.com/firejune/rigc/blob/main/CONTRIBUTING.md) calls it worth ten minutes before a first patch. Repository material |
@@ -738,7 +738,7 @@ quality."* All six, with their verdicts, are in
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 44 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 45 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).

package/cli.ts

@@ -66,10 +66,24 @@ import {
   type DeformKeyMeasure,
   type DeformSpan,
 } from './src/deformmeasure.ts';
-import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
+import {
+  diffLines,
+  diffSkeletons,
+  reportedFigures,
+  sectionFigures,
+  type DiffAnimationPair,
+  type DiffReport,
+} from './src/diff.ts';
 import { ingest, IngestError, IngestSpecRefused, INGEST_GUTTERS, type IngestFinding, type IngestStage } from './src/ingest.ts';
 import { copyAtlasPages } from './src/emit.ts';
-import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas, parseAtlasText } from './src/atlas.ts';
+import {
+  DEFAULT_PADDING,
+  DEFAULT_PAGE_SIZE,
+  packAtlas,
+  pageFootprint,
+  parseAtlasText,
+  type AtlasRegion,
+} from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { KEY_TIME_EPSILON } from './src/timelines.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
@@ -218,13 +232,16 @@ const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images',
 /**
  * The flags a command is allowed to spell more than once.
  *
- * Only `vote --candidate` is, because a ballot is *by definition* several
- * candidates. Everywhere else a repeat is a mistake and is refused: `check
+ * `vote --candidate` is, because a ballot is *by definition* several
+ * candidates, and `diff --as` is, because a skeleton has as many shots as it
+ * has and one pairing per flag is the only spelling that keeps each pair a pair
+ * (issue #720). Everywhere else a repeat is a mistake and is refused: `check
  * --candidate a --candidate b` used to take `b` silently, which is a report
  * about a rig the caller did not think they were asking about.
  */
 const REPEATABLE_FLAGS: Record<string, ReadonlySet<string>> = {
   vote: new Set(['candidate']),
+  diff: new Set(['as']),
 };
 
 /**
@@ -1155,6 +1172,45 @@ function dropLine(dropped: DroppedState): string {
   return `  DROP  ${dropped.slot}/${dropped.state}: ${droppedStateReason(dropped)} (state not emitted)`;
 }
 
+/**
+ * The rectangle a region occupies **on its page**, for a line that has already
+ * said where the region is — and the empty string where the page rectangle is
+ * the one `bounds:` already states.
+ *
+ * ## The fact no surface an author reads carried (issue #718)
+ *
+ * The atlas line beside this clause prints the DRAWING's size, because that is
+ * what an attachment's width and height mean. A packer that turned the drawing a
+ * quarter to fit it wrote `bounds:` in the drawing's orientation too. So an
+ * author holding the pack and the build report had neither end of the rectangle
+ * they have to cut out of the page to measure a part against a rendered frame —
+ * and the one place rigc printed it was `A06`'s overlap text, reachable only
+ * under `--profile spine-html`. The knowledge was in the tree the whole time:
+ * `pageFootprint` has derived this rectangle for every reader of it since issue
+ * #579, and nothing an author reads said it.
+ *
+ * ⚠️ **The condition is `pageFootprint`'s own answer, not a second reading of
+ * `degrees`.** Re-spelling that predicate here is the exact duplication #579 was
+ * filed on — four readers derived this rectangle and two derived it wrongly — so
+ * the clause asks the function whether its answer differs from the `bounds:`
+ * line, and prints only then.
+ *
+ * 🔸 A consequence worth stating rather than leaving to be discovered: a region
+ * whose KEPT rectangle is square is silent here, because a quarter turn leaves
+ * its footprint the same two numbers and there is nothing the pack does not
+ * already say. The general rule — `bounds` is the unturned size, the footprint
+ * is its transpose at `rotate: 90` and `rotate: 270`, and which way to turn the
+ * rectangle to recover the drawing — belongs to an author's own reading and is
+ * stated in `docs/AUTHORING.md` §0.2, which holds for every region including
+ * that one.
+ */
+function pageRectangle(region: AtlasRegion): string {
+  const foot = pageFootprint(region);
+  return foot.width === region.width && foot.height === region.height
+    ? ''
+    : `, occupies ${foot.width}x${foot.height}`;
+}
+
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
@@ -1208,13 +1264,23 @@ function cmdBuild(flags: Record<string, string>): void {
     // that declares a `scale:` also says so and shows the texels it was read
     // from: the size on the left is the DRAWING's and the rectangle is the
     // pack's, and issue #267 is the report that printed the second as the first.
+    //
+    // `pageRectangle` closes the line's last silence (issue #718), and it is
+    // placed LAST rather than beside the turn it follows from, which is where
+    // the card put it. The two clauses collide nowhere else, and the collision
+    // is real: `scale 0.5 (373x106 texels)` is itself a size, so
+    // `rotate 90, occupies 106x373 scale 0.5 (…)` reads as though the footprint
+    // were the scaled quantity. As a trailing clause of the whole location
+    // phrase it is unambiguous with a `scale:` line and identical to the card's
+    // wording without one, which is every pack that has no `scale:` to state.
     const where =
       img.atlas === undefined
         ? img.page
         : `${img.page} @ ${img.atlas.x},${img.atlas.y}${img.atlas.degrees ? ` rotate ${img.atlas.degrees}` : ''}` +
           (img.atlasScale === undefined
             ? ''
-            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`);
+            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`) +
+          pageRectangle(img.atlas);
     console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
   }
   for (const d of result.droppedStates) console.log(dropLine(d));
@@ -1403,7 +1469,69 @@ function cmdValidate(flags: Record<string, string>, positional: string[]): void
   console.log('rigc: green');
 }
 
-function cmdDiff(flags: Record<string, string>, positional: string[]): void {
+/**
+ * `--as <candidate>=<reference>`, one pair per occurrence.
+ *
+ * ⚠️ Spelled with a pair where `check --as <name>` takes one name, and the
+ * difference is in what the two commands have on the other side. `check`
+ * measures against a rendered frame SET, which already carries the reference
+ * animation's name in its own directory, so one name closes the gap. `diff` has
+ * two skeletons and either may have its own vocabulary, so one name says which
+ * shot on which side and leaves the other unanswered. The direction — candidate
+ * first — is the one `bonedist`'s correspondence file already writes its
+ * `animations` map in.
+ *
+ * Every refusal here is a UsageError because every one of them is about the
+ * flag's own value, and each names what it read: a value with no `=`, an empty
+ * side, a name repeated on either side, and a name no animation on that side
+ * answers to. ⛔ The last of those is a refusal rather than a dropped pair for
+ * the reason a miss is refused by name everywhere else in this tool — a typo
+ * that quietly measured less would be a report about a pairing the caller did
+ * not ask for.
+ */
+function readAnimationPairs(values: string[], candidate: unknown, reference: unknown): DiffAnimationPair[] {
+  const animationsOf = (root: unknown): string[] => {
+    const anims = (root as { animations?: unknown } | null)?.animations;
+    return typeof anims === 'object' && anims !== null && !Array.isArray(anims) ? Object.keys(anims) : [];
+  };
+  const have = { candidate: animationsOf(candidate), reference: animationsOf(reference) };
+  const pairs: DiffAnimationPair[] = [];
+  for (const value of values) {
+    const at = value.indexOf('=');
+    if (at < 0) {
+      throw new UsageError(
+        `--as ${JSON.stringify(value)} is not a pair. It takes <candidate>=<reference> — two animation names joined ` +
+          'by `=`, because diff compares two skeletons and either may have its own name for the shot. The candidate ' +
+          `has [${have.candidate.join(', ') || 'none'}] and the reference has [${have.reference.join(', ') || 'none'}].`,
+      );
+    }
+    const pair = { candidate: value.slice(0, at), reference: value.slice(at + 1) };
+    if (pair.candidate === '' || pair.reference === '') {
+      throw new UsageError(
+        `--as ${JSON.stringify(value)} leaves the ${pair.candidate === '' ? 'candidate' : 'reference'} side empty; ` +
+          'it takes <candidate>=<reference>, a name on each side',
+      );
+    }
+    for (const side of ['candidate', 'reference'] as const) {
+      if (!have[side].includes(pair[side])) {
+        throw new UsageError(
+          `--as ${JSON.stringify(value)} names no ${side} animation: the ${side} has ` +
+            `[${have[side].join(', ') || 'none'}] and not ${JSON.stringify(pair[side])}`,
+        );
+      }
+      if (pairs.some((p) => p[side] === pair[side])) {
+        throw new UsageError(
+          `--as pairs the ${side} animation ${JSON.stringify(pair[side])} twice; each animation may be in one pair, ` +
+            'or the block would compare one shot against two',
+        );
+      }
+    }
+    pairs.push(pair);
+  }
+  return pairs;
+}
+
+function cmdDiff(flags: Record<string, string>, lists: Record<string, string[]>, positional: string[]): void {
   const [candidate, reference] = positional;
   if (!candidate || !reference) throw new UsageError('diff takes two paths: <candidate.json> <reference.json>');
   const candidatePath = resolve(candidate);
@@ -1411,7 +1539,10 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
   for (const path of [candidatePath, referencePath]) {
     if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
   }
-  const report = diffSkeletons(readJsonFile(candidatePath), readJsonFile(referencePath));
+  const candidateJson = readJsonFile(candidatePath);
+  const referenceJson = readJsonFile(referencePath);
+  const animationPairs = readAnimationPairs(lists.as ?? [], candidateJson, referenceJson);
+  const report = diffSkeletons(candidateJson, referenceJson, { animationPairs });
   console.log('rigc diff');
   for (const line of diffLines(report, { candidate: candidatePath, reference: referencePath })) console.log(line);
   if (flags.json !== undefined) {
@@ -3266,8 +3397,26 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'diff',
-    usage: ['rigc diff <candidate.json> <reference.json> [--json <out>]'],
-    flags: ['json'],
+    usage: ['rigc diff <candidate.json> <reference.json> [--as <candidate>=<reference>]… [--json <out>]'],
+    flags: ['as', 'json'],
+    overrides: {
+      as: {
+        value: '<candidate>=<reference>',
+        meaning:
+          'pair a candidate animation with a reference one, so the name-agnostic `animations` block can be ' +
+          'measured over shots the two files call different things. Repeatable, one pair each. An INPUT and never ' +
+          'derived: two skeletons cannot say which of their shots are the same shot. Without it the block appears ' +
+          'only when each side has exactly one animation, which pairs by position, and is otherwise absent rather ' +
+          'than guessed',
+      },
+    },
+    notes: [
+      'the `animations` block reads two figures once something has paired the shots, exactly as',
+      '`bones` and `slots` do: name-matched, where `names` lives, and name-agnostic over the pair.',
+      'A candidate that followed a brief withholding the animation name reads `count` 1/1 and 0.000',
+      'on every other name-matched measure — including `duration` and `key_counts` it may have got',
+      'exactly right — so read the pair and not the section mean.',
+    ],
   },
   {
     name: 'check',
@@ -3562,7 +3711,7 @@ try {
   else if (command === 'ingest') cmdIngest(flags, positional);
   else if (command === 'validate') cmdValidate(flags, positional);
   else if (command === 'explain') cmdExplain(flags);
-  else if (command === 'diff') cmdDiff(flags, positional);
+  else if (command === 'diff') cmdDiff(flags, lists, positional);
   else if (command === 'check') cmdCheck(flags);
   else if (command === 'bench') cmdBench(flags, positional);
   else if (command === 'bonedist') cmdBoneDist(flags);

package/docs/AUTHORING.md

@@ -169,7 +169,7 @@ What the flags mean:
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
-| `--profile` | `spine` = the 29 validity rules (**the default**) · `spine-html` = all 44, opt-in |
+| `--profile` | `spine` = the 30 validity rules (**the default**) · `spine-html` = all 45, opt-in |
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
@@ -178,7 +178,7 @@ What the flags mean:
 | `--again` | `vote --record` only: record a second vote on a ballot the ledger already has. Without it a repeat is refused by name rather than doubled |
 | `--frame` | `pose` and `chainfit`: one pose frame — the picture to read part placements out of. One frame per call; several key poses are several calls, and correlating them is yours (§11) |
 | `--scale` | the scale window to search, as **frame pixels per part pixel**, `<min>,<max>` (default `0.5,2`). The report states what it searched, and a window that does not contain the truth does not reliably refuse — §11. For `chainfit` it sizes the **internal anchor pass** and is refused beside `--anchor` — §12.4 |
-| `--rotation` | the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright. For `chainfit`, again the internal anchor pass — the chains' own window is `--hinge` |
+| `--rotation` | the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright — a window narrower than the coarse step is divided rather than refused, and `search` states the step that division produced (§11.3). For `chainfit`, again the internal anchor pass — the chains' own window is `--hinge` |
 | `--max-residual` | `pose` and `chainfit`: above this residual a placement is **refused by name** instead of reported flat (default `0.25`). A reporting threshold, not a pass bar — the placement is still in the JSON |
 | `--anchor` | `chainfit` only: a `rigc pose` report for **this** frame, whose confident placements become the anchors the chains hang off. Without it that pass runs internally — §12.2 |
 | `--hinge` | `chainfit` only: the window each child bone's local rotation is searched over, in **Spine** degrees about its setup value, `<min>,<max>` (default `-180,180`) — §12.4 |
@@ -389,6 +389,37 @@ silhouette and an authored mesh's fit figure is the same number. The one thing
 that does not change is what rigc **writes**: its own packer never turns a
 region.
 
+🔑 **That is a claim about rigc's instruments, and you may be holding only the
+pack.** An author who has to cut a part out of the page by hand — to measure it
+against a rendered frame, or to look at it at all — needs what the `rotate:` line
+means for the numbers beside it, and the pack states none of this:
+
+- `bounds: x, y, w, h` gives `w x h` in the **drawing's** orientation, so it is
+  the part's size **unturned**: the same two numbers the same drawing carries at
+  `rotate: 0`;
+- the rectangle on the **page** is therefore `h x w` at `x, y` — the transpose —
+  at `rotate: 90` and at `rotate: 270` alike, while `w x h` is what a region
+  occupies at `rotate: 0` and at `rotate: 180`;
+- cut that rectangle out of the page and turn it **clockwise** to recover the
+  drawing at `rotate: 90`, and **counter-clockwise** at `rotate: 270`; a half
+  turn has no direction to name.
+
+Each direction there is **measured** rather than reasoned about: it comes off
+`MeshAttachment.computeUVs` in the linked runtime, the one routine there that
+says where a region's texels are for all four values, and the selftest derives
+the words in that list from the same routine instead of reading them. ⚠️ Do not
+take the turn from `TextureAtlas`'s own `u2`/`v2` — those transpose at a quarter
+turn one way and not at the other, so one of the two pairs describes a rectangle
+the page does not have ([#579](https://github.com/firejune/rigc/issues/579)).
+
+`build` now prints the page rectangle on the line for a turned region, so the
+report carries the rectangle to cut instead of leaving it to be derived
+([#718](https://github.com/firejune/rigc/issues/718)):
+
+```bash
+#   ..      pendulum   105x139  <- ../export/atlas.png @ 710,16 rotate 90, occupies 139x105
+```
+
 ⚠️ Two limits here are real and neither is about rotation:
 
 - `--atlas-in` cannot recover what a `scale:` quantised away (above), turned or not;
@@ -500,6 +531,23 @@ the first:
 | `JUDGE` | the skeleton cannot answer and somebody has to: the stage, and each animation's duration |
 | `LOSS` | the skeleton's spelling and rigc's differ, on purpose, and the line says how. A path attachment's `lengths` is the one that matters — it is `PathConstraint`'s own four-sample measurement rather than an arc length (#560), so a transcribed one would freeze whatever produced the source. The header ones are cheaper: `HEADER_BOOKKEEPING` for a field the spec has no home for, `HEADER_REDERIVED` for the version string, `HEADER_ORIGIN` for an origin the source left to the format and the rebuild writes out (#622) |
 
+⛔ **It reads one generation of the format, and a file from another one ends loud.**
+Spine data is locked to the generation that exported it and a mismatch does not
+throw: 4.3 takes constraints from the top-level `constraints` array alone, so a
+4.0–4.2 file's `ik`/`transform`/`path`/`physics` arrays load as nothing at all — 1,302
+shipped skeletons parsed on a 4.3 runtime and loaded 0 of 8,672 constraints
+([#706](https://github.com/firejune/rigc/issues/706) row 1). So `ingest` reads
+`skeleton.spine` before it reads a field of the file. A file from another generation is
+a `BLOCK GENERATION_UNSUPPORTED` naming the generation, the string it was read from,
+and what a 4.3 reader loses **on that file**: the constraints parked in those arrays
+counted by kind, the bones carrying 4.2's `transform` where 4.3 spells `inherit`, and
+the physics constraints omitting `inertia`/`damping`, whose default is not the same
+number in the two. A label naming no generation rigc knows — or a header stating none —
+is a `BLOCK GENERATION_UNKNOWN`, never rounded to the nearest: a catalog that rounded
+handed 19 skeletons labelled `3.8.99` a 4.2 runtime and every one of them posed as NaN
+(row 7). Reading a file with *that generation's own* defaults is #706's item 2 and is
+not in this tool — re-export as 4.3, or transcribe by hand ([INGEST.md](INGEST.md) §2).
+
 📝 **Do not delete the `note`.** Both written specs carry one saying the file is
 decompiled and naming the skeleton it came from. A decompiled spec is
 indistinguishable from an authored one by inspection, every gate here calls it green —
@@ -516,7 +564,7 @@ The other commands:
 ```bash
 bun cli.ts explain  --rig … --motion … --out …   # the compiled rig as a table
 bun cli.ts validate path/to/spine                # re-gate artifacts already on disk
-bun cli.ts diff     candidate.json reference.json
+bun cli.ts diff     candidate.json reference.json [--as <candidate>=<reference>]…
 bun cli.ts check    --candidate path/to/spine --frames path/to/frames [--skin …]
 bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
 bun cli.ts render   --candidate path/to/spine [--animation …] [--skin …] [--fps 12] [--max 256]
@@ -550,6 +598,19 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
   deliberately does not combine them into a score: a rig with the right skeleton
   and the wrong timing and a rig with the right timing and the wrong skeleton call
   for opposite fixes. A measure with nothing to compare says `0/0` and says so.
+
+  ⭐ **If your animation is not called what the reference's is, say so with
+  `--as <candidate>=<reference>`** (repeatable, one pair each) — or let it pair by
+  position, which happens with no flag when each side carries exactly one
+  animation. Without a pairing every animation measure but `count` is keyed on the
+  name, so a rig whose shot is right down to the key counts reads **0.000** across
+  the section. The pairing gets `animations` the same two figures `bones` and
+  `slots` carry, and reading them as a pair — name-agnostic 1.000 beside `names`
+  0.000 — is what says the shot is right and the name is yours. The measures, the
+  refusals and what makes the block absent instead of guessed:
+  [INGEST.md](INGEST.md) §1.3.1, and *The measure inventory* in
+  [BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md),
+  which is repository material rather than part of this package.
 - **`check`** renders your candidate into the reference frames' own pixel grid and
   compares pixels — the only thing here that can see a wrong animation. **§9.**
   🚨 What it certifies is the **default skin** unless you pass `--skin <name>`:
@@ -1064,6 +1125,22 @@ loader's sentence and all the report had. Since
 `A08_REGION_NAMES_MATCH_ATTACHMENTS`, with the skin, the slot, the placeholder
 and the attachment's own name beside the path.
 
+Where each vertex sits on the **art**:
+
+| Field | Meaning |
+| --- | --- |
+| `uvs` | one `u, v` per vertex, in the order the geometry below uses. Both are fractions of the region rather than pixels, and the array's length is what fixes the vertex count — a mesh states no `vertexCount`. **`(0, 0)` is the region's top-left pixel and `(1, 1)` its bottom-right**, so `u` grows toward the right edge and `v` grows *downward* toward the bottom edge: the crop-pixel convention §11.2 states for a manifest, and not Spine's y-up world. What a **turned** region (`rotate: 90`, in a pack somebody else made) does to that is §0.2's subject |
+
+⭐ **Measured, because an assumption about a corner is invisible in a build that
+went green.** On a 64×48 plate whose four quadrants are four flat colours,
+`rigc render` drew a quad given `uvs` running `0 → 0.5` on both axes as 3,120 px
+of the **top-left** quadrant's colour and not one pixel of any other, and the same
+quad given `0.5 → 1` as 3,120 px of the **bottom-right**. Beside it, the runtime's own
+`MeshAttachment.computeUVs`, handed the emitted atlas region, put `(0, 0)` at page
+pixel `(0.00, 0.00)` and `(1, 1)` at `(64.00, 48.00)` — the region's own two
+corners, in the page's y-down pixels. `CUR44` in the selftest holds the sentence
+above against that second measurement.
+
 Geometry comes in one of two fields:
 
 | Field | Meaning |
@@ -1220,7 +1297,12 @@ the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`). Measured
 a forged skeleton — a link declaring 5 uvs, 3 triangles, `hull: 5` and
 `edges: [0, 2]` beside a 4-vertex source loaded with the **source's** 8-long
 `worldVerticesLength`, 6 triangles, `hullLength` 8 and 10 edges. Nothing the author
-wrote reached anything and nothing said so.
+wrote reached anything and nothing said so. ⇒ The same fact is held against a
+skeleton rigc did **not** write, where the compiler never sees the spec:
+`A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` (§5.2) names the attachment, the
+keys and whose geometry is drawn instead, and `ingest` reports one as
+`ATTACHMENT_LINK_GEOMETRY` before dropping it
+([INGEST §2.0](INGEST.md)) — [#710](https://github.com/firejune/rigc/issues/710).
 
 🚫 **A chain is refused, and so is a link to itself.** A `source` that names
 another linked mesh resolves in the order the file was read: measured through
@@ -1245,6 +1327,105 @@ and uvs. `A13_MESH_BUDGET` counts it as a mesh of its own: the runtime draws it
 one, so a link in a second slot is a second mesh slot against
 `invariants.meshSlots`.
 
+**The three types that carry geometry and no art** — a bounding box, a clipping
+polygon and a path. None of them resolves an atlas region, so none of them has an
+`image`, a `path` key, a `width`/`height` or uvs, and a skin holding only these
+builds an atlas with **no pages** (above). What they do share is one geometry
+shape, and it is the mesh's with one field added:
+
+- 🚨 **`vertexCount` is required and has no parser default.** A mesh takes its
+  count from `uvs.length`; these have no uvs, so the parser reads
+  `map.vertexCount << 1` as the length to expect — and with the field absent that
+  is `undefined << 1` = **0**, which sends `readVertices` down the WEIGHTED branch,
+  decodes the coordinate list as a weight run, and hands back an attachment with no
+  vertices at all. Nothing throws, and none of the three draws a pixel, so nothing
+  downstream notices. rigc refuses it by name: `vertexCount is undefined; a polygon
+  needs at least 3 vertices, stated outright`.
+- **The two encodings are the mesh's own**, traps included: `weights` binds bones
+  by NAME and is the form to use; `vertices` is an unweighted `x, y` run when
+  `vertices.length === vertexCount * 2` and Spine's index-encoded weighted run
+  otherwise, and the second of those needs `"boneIndexing": "raw"` said out loud.
+  `A33_VERTEX_ATTACHMENT_GEOMETRY` (§5.2) gates all three types and accepts either
+  encoding on each — measured by building both on each of the three.
+- 📐 **Which space the numbers are in.** An unweighted `x, y` is in the **slot's
+  bone's** local space; a `weights` binding's `x`/`y` is in **that binding's own
+  bone's** local space, and the slot's bone plays no part in it. Measured through
+  spine-core on a rig where the two are different bones: `(0, 0)`, `(30, 0)`,
+  `(30, 20)` written unweighted on a slot whose bone sits at `(-60, 25)` turned
+  −21° posed at `(-60.0000, 25.0000)`, `(-31.9926, 14.2490)` and
+  `(-24.8252, 32.9206)`, which is that bone's own transform of them; the same three
+  points bound by name to a bone at `(110, 70)` turned 37° and scaled `1.3, 0.8`,
+  in the very same slot, posed at `(110.0000, 70.0000)`, `(141.1468, 93.4708)` and
+  `(131.5177, 106.2490)` — the BOUND bone's transform, to four decimals.
+- **A `deform` timeline reaches all three** (§4.11); none of them is drawn, so a
+  render can show you nothing about any of them.
+
+**Bounding box** ([Spine: bounding boxes](http://esotericsoftware.com/spine-bounding-boxes)) —
+`"type": "boundingbox"`. A polygon the game hit-tests against — a hurt box, a pick
+region, a trigger volume — that moves with the skeleton and draws nothing.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | `"boundingbox"`. **Required**: an omitted `type` is `"region"`, and a region has nowhere to put these keys — measured, the refusal reads `attachment "mask" (region) has 2 keys this compiler does not read: "vertexCount", "vertices"` |
+| `vertexCount` | **required**, 3 or more. No default — the paragraph above is why |
+| `vertices` | the unweighted `x, y` run, in the slot bone's local space; or the index-encoded weighted run, behind `boneIndexing` |
+| `weights` | the by-name form: one entry per vertex, each a list of `{ "bone": …, "x": …, "y": …, "weight": … }`, each pair in that bone's local space. Never beside `vertices` |
+| `boneIndexing` | `"name"` (the default) or `"raw"`, which opts a weighted `vertices` run into Spine's index encoding. `"raw"` beside `weights` is refused: `weights` always binds by name |
+| `color` | `rrggbbaa`. **No default in the file** — omitted, the parser never calls `setFromString` and the attachment keeps the runtime's own colour. It is an editor affordance, the colour the polygon is drawn in there; rigc emits it verbatim when stated and leaves the key out when not |
+
+**Clipping polygon** ([Spine: clipping](http://esotericsoftware.com/spine-clipping)) —
+`"type": "clipping"`. A mask: the polygon clips every slot drawn from the one
+carrying it up to and including `end`, so a window, a portal or a wipe is one
+attachment rather than a second set of art.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | `"clipping"`. **Required** |
+| `vertexCount`, `vertices`, `weights`, `boneIndexing`, `color` | exactly as on a bounding box |
+| `end` | the last slot the clip applies to, **by name**. Absent is the parser's own encoding for *clip everything after this one*, which is why a typo cannot be told from an omission once the file is loaded: `findSlot` returns null on a miss and the parser assigns that null without a word, so the clip runs to the bottom of the draw order and takes every slot below it with it. rigc refuses a name the rig does not declare — `end names slot "X", which this rig does not declare` — and `A33` refuses it again on a skeleton rigc did not write |
+| `convex` | default **false**. True tells the runtime the polygon is convex so it can clip without triangulating it, and a polygon that deforms concave is clipped by its convex hull instead (`ClippingAttachment.convex`). Nothing here checks that the polygon is in fact convex |
+| `inverse` | default **false**. True makes everything **outside** the polygon visible instead of everything inside, and inverse clipping is always treated as convex (`ClippingAttachment.inverse`) |
+
+⚠️ **A clipping attachment is refused by the renderer profile and by nothing
+else.** `A11_NO_CLIPPING_ATTACHMENTS` (§5.2) fires under `--profile spine-html`
+because that renderer skips clipping silently; it is one renderer's policy rather
+than anything about the data, and the default `spine` profile builds one.
+
+**Path** ([Spine: paths](http://esotericsoftware.com/spine-paths)) —
+`"type": "path"`. The composite cubic Bezier a path **constraint** (§3.5.1) slides
+bones along. No runtime draws it, and it deforms with the slot's bone like any
+other vertex attachment.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | `"path"`. **Required** |
+| `vertexCount`, `vertices`, `weights`, `boneIndexing`, `color` | as on a bounding box — except that these vertices are knots **and** their handles, which the count rule below is about |
+| `closed` | default **false**. True joins the last knot back to the first |
+| `constantSpeed` | default **true** — note the direction. Leaving it out asks for the expensive-and-correct traversal, in which the runtime re-measures the path every frame and `lengths` is never read. `false` makes the runtime trust the emitted `lengths` instead: cheaper, exact only while the path holds its setup shape, and the reason a deformed path wants the default |
+| `lengths` | 🚫 **refused by name.** rigc measures the setup length of each curve off the geometry and emits it, the way it measures a region's size off its PNG: `"lengths" is not authored — rigc measures the setup arc length of each curve…`. The field is declared only so the refusal can say that rather than report a misspelt key. What the numbers are — and why *arc length* is the wrong name for them — is §10.6 |
+
+🚨 **`vertexCount` counts knots AND handles, and it has to be a multiple of 3.**
+The parser hands `vertexCount << 1` to `readVertices` and then walks the result in
+groups of six: the first and last points are the outer control handles of the end
+knots and are dropped, leaving a `3K + 1` chain. So an OPEN path of K curves states
+`vertexCount = 3(K + 1)`, minimum **6**, and a CLOSED one states `3K`, minimum
+**3**. A count that is not a multiple of 3 does not throw —
+`Utils.newArray(vertexCount / 3, 0)` accepts a fractional size, the groups of six
+then straddle the knots, and the constraint slides bones along a curve nobody drew
+— so rigc refuses both shapes: `vertexCount is N, which is not a multiple of 3`
+and `vertexCount is N and an open path needs at least 6`.
+
+```json
+"track": { "track": { "type": "path", "vertexCount": 9,
+  "vertices": [-30, 0, 0, 0, 30, 0, 60, 0, 90, 0, 120, 0, 150, 0, 180, 0, 210, 0] } }
+```
+
+Nine points are two curves. The outer handles at `x = -30` and `x = 210` are
+dropped, so the chain runs from `x = 0` to `x = 180` and rigc emits
+`"lengths": [90, 180]` beside it — measured, not stated. That is the path
+§3.5.1's constraint example rides: with `position: 0.25` its `cart` bone poses at
+`worldX = 45.000000`.
+
 The generators are `ring`, `ribbon`, `contour` and `grid` (see
 [`src/mesh.ts`](../src/mesh.ts)); the first two encode a deformation model rather
 than a table of numbers, which is why they are code invoked by data. The last two
@@ -4769,7 +4950,7 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A16_SKELETON_VERSION_4_3` | both | the `skeleton.spine` label is not on the 4.3 line (`4.3`, `4.3.N`, `4.3.N-suffix`) |
 | `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) — as it is for `A06`, `A19` and `A27`; see `A07` ([#608](https://github.com/firejune/rigc/issues/608)) |
 | `A18_DETERMINISTIC_EMIT` | both | a second compile of the same inputs differed. That is a compiler bug, not a spec bug — report it |
-| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art ([#266](https://github.com/firejune/rigc/issues/266)) **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art ([#266](https://github.com/firejune/rigc/issues/266)). ⚠️ **That scan states its verdict over the texels it READ, and never over texels that are not on the page** ([#705](https://github.com/firejune/rigc/issues/705)): a rectangle partly on its page is judged over the part that is on it, and the message carries both counts — `opaque in every one of the 77 texels of its 12x8 rectangle at -1,-1 … the other 19 of the 96 it declares are not on the page and are not measured here`. A rectangle with **no** texel on the page is reported **not measured** by name — the region, its rectangle, the page image's size, and the pointer to `A06`, which is the rule that judges a region's rectangle — and no verdict about opacity is printed at all. It stays a failure rather than becoming a SKIP because a SKIP is per ASSERTION: it would delete the verdicts on every other part of the same page, and an assertion cannot be skipped and failed at once without the report counting it twice. Before #705 the walk was silent about its own reach, so a part nobody could read printed *opaque in every one of its 12x8 texels* over zero of them, which is a refusal pointing at the wrong file: the art it names may be transparent, and the repair is the rectangle in `A06`'s row above **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not ([#684](https://github.com/firejune/rigc/issues/684)). Fix the rig spec's `controls`/`chain`, or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, a ribbon's entry row, or a contour's outline (which is all of it) is not pinned to its anchor bone at weight 1 |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
@@ -4794,6 +4975,7 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP` | both | a physics constraint driving a component the **Spine editor** cannot hold, on a rig that declared `invariants.editorRoundTrip` (§3.7). The editor's physics model holds `x` and `y` only, with no cap on how many at once, so a constraint driving `rotate`, `scaleX` or `shearX` is imported, exported and handed back driving **nothing** — measured over three rigs and twelve constraints with the predictions written first ([#540](https://github.com/firejune/rigc/issues/540)). The detail names the constraint and each component. ⚠️ rigc's own output is correct — every runtime plays a rotation jiggle — so this is opt-in and the default is *not* silence: on a rig that declares nothing it **SKIPs**, and the SKIP names the constraint and the component anyway, so an author learns without having asked. Fix by driving the constraint in `x`/`y`, or by dropping the declaration if the rig never goes near the editor. Disjoint from `A23_PHYSICS_CONSTRAINT_EFFECTIVE` by construction: A23 refuses an **empty** driven set, which is what comes back from the editor, and this refuses a non-empty one that will not survive going in. **SKIP** also when the rig declares the editor and carries no physics constraint at all |
 | `A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER` | both | a slider whose animation keys a property of a constraint **at or before it** in `constraints` (§3.5.2) — a slider's `mix` or `time`, an ik or transform mix, a path `position`, `spacing` or `mix`, any physics value. That array is the update order for every kind, and each constraint reads its own applied pose when its turn comes — `Slider.update` takes `mix` as the alpha it applies with and `time` as the time it applies at, `PhysicsConstraint.update` returns on `mix` 0 before reading the rest — so the key lands after the only read of it and `Posed.resetConstrained` discards it before the next frame: what the driven constraint drives is dead at every position of the driving dial, although its pose still holds the number ([#658](https://github.com/firejune/rigc/issues/658), [#665](https://github.com/firejune/rigc/issues/665)). The detail names the slider, the driven constraint with its kind, both array indices, the property, the runtime class whose `update` reads it, and the animation the key sits in. Fix by moving the driver earlier, or by keying that property from a slider that already is. **The two indices equal is the same failure**: a slider cannot key its own `mix` or `time`, and one muted at setup that keys its own `mix` up never applies anything at all — `A37` is silent there, because it asks whether *an* animation keys the mix and not which one. **Two shapes it deliberately leaves out**, both measured: a `physics` `reset` key, which fires on a crossed frame time and so never fires from a slider at all, in either order — the reorder would repair nothing; and a physics timeline naming no constraint, which is every physics constraint declaring that property global and IS refused for the ones already run. Disjoint from `A40` by construction: `A40` asks who writes a shared property last and excludes every slider whose `mix` is keyed, this asks whether anything reads what was written. **SKIP** when the skeleton declares no slider, and when no slider's animation keys a constraint property — that SKIP names any `reset` keys it found — a pass means a driver and a driven were compared |
 | `A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN` | both | a slot's `dark` (§3.3) or an `rgba2` timeline (§4.4) that the runtime does not hold as the file states it. Three shapes, all of which parse in silence: a `dark` the slot reader **drops** — it takes the field through a truthiness test, so `""` is discarded without a word and the slot renders with one colour; a `dark` that is **not six hex digits** — `Color.setFromString` slices fixed offsets and stores whatever `parseInt` gives back, so `"4020"` loads a channel of `NaN`; and an `rgba2` timeline on a slot with **no `dark` at all**, where the runtime allocates no dark colour and the first `state.apply` throws in the consumer's process. The keyed half is read by posing: the animation is stepped to each key's own time and the posed `color` and `darkColor` are compared against the hex the key states, to half a quantisation step (`1/510`). The detail names the slot, the value found and the value required. ⚠️ The required value is parsed **here** and not through `Color.fromString`, because a check that read it out of the parser it is checking would agree with that parser whatever it did. `compile.ts` refuses the third shape outright in a rig rigc builds; this is the same fact held against a skeleton it did not write. **SKIP** when no slot declares a `dark` and no animation keys an `rgba2` — there is then no two-colour tint to read back |
+| `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` | both | a **linked mesh** (§3.4) — `type: "linkedmesh"`, or a `type: "mesh"` carrying `source` — that also states `uvs`, `triangles`, `vertices`, `hull` or `edges`. The parser returns from the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`), so those keys are read by **nothing at all** and `setSourceMesh` fills the attachment with the source's arrays instead: the file says one mesh and every runtime draws another, in silence. The detail names the attachment by skin, slot and placeholder, every key it states, the `source` and where the parser looks for it — the two defaults spelled out, because an omitted `skin` is the **default** skin rather than the one the link is written in — and the shape the keys describe beside the shape the attachment loaded. ⚠️ **`width`/`height` are not part of this.** `setSourceMesh` overwrites both with the source's, so they are as dead at runtime — but the parser reads them (`:569-570`), the format carries them on a link and rigc emits them, so refusing them would refuse every link rigc writes (§3.4). `compile.ts` refuses the same shape outright in a rig rigc builds (§5.1); this is that fact held against a skeleton it did not write, and `ingest` reports it as `ATTACHMENT_LINK_GEOMETRY` ([INGEST §2.0](INGEST.md)). **SKIP** when no attachment in the skeleton takes its geometry from another — which is almost every skeleton, so a pass here means a link was read ([#710](https://github.com/firejune/rigc/issues/710)) |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.
@@ -7308,7 +7490,7 @@ Per part:
 | `ambiguous` | at least one alternate is inside the ambiguity margin. **Choose with something this instrument cannot see** — anatomy, the other frame, or `rigc vote` |
 | `rotationFree` | the part is self-similar under rotation, so `rotationDeg` is a placeholder and the value is yours |
 | `rotationSelfSimilarity` | the number `rotationFree` is a threshold on. A part just over the line is worth a look |
-| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part` |
+| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part`. A `no-match` whose best placement stopped **on a wall of the search window** names the wall in its detail — see §11.4 |
 | `coarse` | the grid this part was actually searched on. A handful of cells means the part is small relative to the frame and the first pass had little to go on |
 | `notes` | the same facts in prose, in the order they were found |
 
@@ -7326,6 +7508,16 @@ The report also carries `frame.background` (how the picture's empty space was
 identified — a flat colour, transparency, or `unknown`), `search` (every window
 and threshold that was applied), and `caveats`.
 
+🔒 **`search` states what ran, not what was asked for.** `search.rotation` carries
+`degrees`, the ladder the coarse pass actually walked, and its `stepDeg` is read
+off that ladder rather than off the constant the ladder was capped at. The coarse
+step `15°` is a **ceiling** on the step, not the step: a narrower window is
+divided into whole steps no coarser than it, so
+`--rotation -5,5` prints `rotation -5°–5° in 2 step(s) of 10°` and walks those two
+angles and no others. Nothing reported leaves the window either — the refinement
+and the quarter-turn probes are held inside it, and a window spanning a full turn
+holds nothing because it already contains every angle.
+
 ### 11.4 What it cannot see — read this before using the numbers
 
 - ⚠️ **Residuals degrade under occlusion, and there is no depth solver here.** A
@@ -7341,6 +7533,16 @@ and threshold that was applied), and `caveats`.
   answer is the best placement available *inside* `--scale` / `--rotation` and its
   residual can look reasonable. This is why the window is a reported field: if the
   numbers surprise you, check `search` before you trust them.
+- 🔒 **A refusal that stopped on a wall of the window says which wall.** When a
+  `no-match`'s best placement sits on the floor or the ceiling of `--scale`, or on
+  an edge of a `--rotation` window narrower than a full turn, the detail names it:
+  `best placement at scale 0.500, the floor of --scale 0.5,2 — the truth may lie below the window`.
+  That is the case where the window is the first thing to move rather than the
+  frame or the threshold — eleven parts of one frame came back refused at
+  `scale=0.500` against art rendered at `0.311` per part pixel, and the message
+  said only that the residual was above `--max-residual`. It is printed on a
+  **refusal and nowhere else**: an accepted placement sitting on a wall is a window
+  chosen to bracket the answer, which is the flag working.
 - ⚠️ **A frame whose border has no dominant colour reports `background.unknown`.**
   Every pixel then counts as material, the silhouette signal is gone, and the
   residual is colour agreement alone. The report says so rather than being quietly