@rig-c/core 2.64.3 → 2.65.1

package/README.md

@@ -26,7 +26,7 @@ published beside it with the same files at every version.
 
 <p align="center"><em>Fourteen part PNGs drawn from scratch for this repo, one rig spec, one motion spec — the assembly,
 the breathing and the wave are all rigc-compiled Spine animations, rendered with
-<code>rigc render</code>.</em></p>
+<code>rigc render</code>. A <a href="https://raw.githubusercontent.com/rig-c/core/main/assets/rigc-demo@2x.gif">2x version</a> (1200x810) sits beside it.</em></p>
 
 Loose part PNGs and two small JSON files in; **Spine 4.3 skeleton data out** — a
 `skeleton.json` and a `skeleton.atlas` that load in any Spine runtime and **import
@@ -526,7 +526,7 @@ a rig compiles green, because green says nothing at all about the picture.
 conditions, <code>rigc pose</code> reads where every part sits in each picture, two
 candidate in-betweenings are compiled from the same pair — and a real
 <code>rigc vote</code> ballot picks the winner, because the movement between the poses
-is the one thing no instrument here will grade.</em></p>
+is the one thing no instrument here will grade. A <a href="https://raw.githubusercontent.com/rig-c/core/main/assets/rigc-keypose@2x.gif">2x version</a> (1200x810) sits beside it.</em></p>
 
 Three properties of `vote` are worth stating, because they are what make its ledger
 usable by the next agent rather than by a reader: **a tie is a recorded outcome, not a
@@ -580,7 +580,7 @@ while <code>gaze</code> and <code>turn</code> return to rest, so the hand-offs m
 differing pixels — and the composing is the consumer's. Authorable on plain Spine 4.3, no
 plugin, no runtime patch; what the turn costs is authoring rather than runtime capability,
 and that cost is one stated expression per key. Compiled and rendered entirely by the
-published package.</em></p>
+published package. A <a href="https://raw.githubusercontent.com/rig-c/core/main/assets/rigc-scene@2x.gif">2x version</a> (1200x810) sits beside it.</em></p>
 
 🎞️ **How the three films on this page were made** is kept with them, one directory per
 film in [`films/`](https://github.com/rig-c/core/tree/main/films) — a `run.sh` that

package/docs/AUTHORING.md

@@ -4993,6 +4993,14 @@ consumer's, decided by dressing the skeleton rather than by the animation.
   Seconds, not frames: nothing requires a key to land on any frame grid, and a
   reference rendered at some rate says nothing about where its keys are. Put keys
   where the motion changes.
+  ⚠️ **A phrase generated cycle by cycle ends one key before its period.** Write
+  each cycle of a 1 s phrase as t = 0…1 and the closing key of one cycle lands on
+  the opening key of the next, so the track is refused at the first boundary; the
+  refusal names both keys and, when the keys after the pair repeat the spacing of
+  the keys before it, says so. Generate each cycle without its closing key and
+  keep that key on the last cycle only: a looping player takes `time % duration`
+  and nothing interpolates across the wrap, so a track that stops short of its
+  period holds its last key until it (issue #1506).
 - **Key times are emitted as float32s like every other number, and never stored
   LATER than you wrote them.** Every emitted number is the shortest decimal naming
   its float32 — the text the editor writes, and the precision the runtime keeps,
@@ -7213,7 +7221,7 @@ retain the minimal inputs and report that code rather than inventing author data
 | <a id="CE_COMPILE_CURVE_VALUE_NONFINITE"></a>`CE_COMPILE_CURVE_VALUE_NONFINITE` | “&lt;value&gt; (t=&lt;value&gt;): raw curve holds a non-finite value &lt;value&gt;” | Supply finite numbers in the raw curve array. |
 | <a id="CE_COMPILE_VALUE_TIMELINE_PROPERTY_UNKNOWN"></a>`CE_COMPILE_VALUE_TIMELINE_PROPERTY_UNKNOWN` | “animation "&lt;value&gt;": &lt;value&gt; "&lt;value&gt;" has no property "&lt;value&gt;"” | Use a property present on the named target's timeline family. |
 | <a id="CE_COMPILE_TIMELINE_KEYS_EMPTY"></a>`CE_COMPILE_TIMELINE_KEYS_EMPTY` | “&lt;value&gt;: no keys”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>“animation "&lt;value&gt;" events”<br>“animation "&lt;value&gt;" drawOrder”<br>“animation "&lt;value&gt;" slot "&lt;value&gt;" &lt;value&gt;”<br>“animation "&lt;value&gt;" &lt;value&gt; constraint "&lt;value&gt;"”<br>Here the values named in the message include: “default”. | Supply at least one key in the timeline. |
-| <a id="CE_COMPILE_KEY_TIMES_NOT_INCREASING"></a>`CE_COMPILE_KEY_TIMES_NOT_INCREASING` | “&lt;value&gt;: key times must strictly increase (at t=&lt;value&gt;)”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>“animation "&lt;value&gt;" drawOrder”<br>“animation "&lt;value&gt;" slot "&lt;value&gt;" &lt;value&gt;”<br>“animation "&lt;value&gt;" &lt;value&gt; constraint "&lt;value&gt;"”<br>Here the values named in the message include: “default”. | Order keys by strictly increasing time. |
+| <a id="CE_COMPILE_KEY_TIMES_NOT_INCREASING"></a>`CE_COMPILE_KEY_TIMES_NOT_INCREASING` | “&lt;value&gt;: key times must strictly increase — key &lt;value&gt; at t=&lt;value&gt; does not come after key &lt;value&gt; at t=&lt;value&gt; (keys counted from 0)”, and when the two keys share a time and the keys after them repeat the spacing of the keys before them: “. The keys from t=&lt;value&gt; repeat every &lt;value&gt;s, so key &lt;value&gt; closes one cycle and key &lt;value&gt; opens the next at the same time: a phrase that repeats every &lt;value&gt;s ends one key before its period. Generate each cycle without its closing key and keep that key on the last cycle only — a looping player wraps from it to t=0, and a track that stops short holds its last key until the wrap”<br>Also: “animation "&lt;value&gt;" deform &lt;value&gt;/&lt;value&gt;/&lt;value&gt;”<br>“animation "&lt;value&gt;" drawOrder”<br>“animation "&lt;value&gt;" slot "&lt;value&gt;" &lt;value&gt;”<br>“animation "&lt;value&gt;" &lt;value&gt; constraint "&lt;value&gt;"”<br>Here the values named in the message include: “default”. | Order keys by strictly increasing time; the message names both keys of the pair. A phrase generated cycle by cycle with each cycle written from its start to its end repeats every boundary key — drop each cycle's closing key and keep it on the last cycle only (§4.5). |
 | <a id="CE_COMPILE_STEPPED_TIMELINE_EASING"></a>`CE_COMPILE_STEPPED_TIMELINE_EASING` | “&lt;value&gt; key at t=&lt;value&gt; carries [an easing ("&lt;value&gt;") / a curve], and this timeline is stepped by the format — its reader builds no curve, so the mode changes AT the key and holds until the next one. Remove it”<br>Also: “animation "&lt;value&gt;" &lt;value&gt; "&lt;value&gt;" &lt;value&gt;” | Remove easing/curve from the stepped mode timeline. |
 | <a id="CE_COMPILE_TIMELINE_MODE_UNKNOWN"></a>`CE_COMPILE_TIMELINE_MODE_UNKNOWN` | “&lt;value&gt; key at t=&lt;value&gt; names mode &lt;value&gt;; &lt;value&gt;”<br>“known: &lt;value&gt; — the runtime folds the case of the first letter and of nothing else”<br>Also: “animation "&lt;value&gt;" &lt;value&gt; "&lt;value&gt;" &lt;value&gt;”<br>“, ”<br>Here the values named in the message include: “noScaleOrReflection”, “normal”, “onlyTranslation”, “noRotationOrReflection”. | Use a mode named in the timeline's allowed mode list. |
 | <a id="CE_COMPILE_VALUELESS_TIMELINE_VALUE"></a>`CE_COMPILE_VALUELESS_TIMELINE_VALUE` | “&lt;value&gt;: this timeline takes no value; use null”<br>Also: “animation "&lt;value&gt;" &lt;value&gt; "&lt;value&gt;" &lt;value&gt;” | Use null for a timeline that takes no value. |
@@ -11357,10 +11365,23 @@ ambiguous one ends with a sentence saying which reading its figures support:
 
   > loud.png: the best placement found has residual 0.5000, above --max-residual 0.25; part is 200x150 px (span 200 frame px, opaque 1) with texture 0.2473, detail 49.455; 2 candidate(s), best 0.5000, next 0.5000, spread 0.0000 — above the measured floor (AUTHORING §11.5: detail 0.5, measured from 24 px up), so size and texture do not explain this; the cut (or the search window) is the suspect
 
+- **above the floor, one size in two places** — two copies of an 18x34 checker 0.6 of its span and 6° apart, the shape a left/right pair cut from one drawing reads as:
+
+  > part is 18x34 px (span 36.2 frame px, opaque 1) with texture 0.0221, detail 0.752; 14 candidate(s), best 0.0160, next 0.0162, spread 0.0002 — above the measured floor (AUTHORING §11.5: detail 0.5, measured from 24 px up), so size and texture do not explain this; every placement in the margin is at the best's scale (within 0.30%, bar 2%) and in another place (the nearest 0.62 span(s) away, bar 0.45), which is the part — or a near-copy, such as a left/right pair cut from one drawing — drawn more than once: read the placements as an unordered set and order it across frames (MOTION.md §2.2 🔀); a --rotation window that excludes one place chooses the answer rather than measuring it
+
 Read the figures, not only the verdict. *Below* says plainness alone explains the
 failure: the cut may be right, and `pose` cannot tell. *Above* says it does not,
 so look at the cut, the `--scale`/`--rotation` window, or — for an ambiguity — at
-whether the frame really holds the part twice. ⚠️ Above the floor is **not** a
+whether the frame really holds the part twice. 🔀 When **every** placement inside
+the margin is at the best's scale and in another place — the two bars the sentence
+prints beside the figures it measured — the reading says the frame does hold it more than once and
+names MOTION.md §2.2's unordered set instead of a window: no `--scale` window
+separates two copies of one size, and a `--rotation` window that excludes one place
+*chooses* the answer — both files then place on the other copy, one of them off its
+truth and printed clean. Both bars sit at the geometric middle of the gap measured
+between such repeats and every other ambiguity on the floor's grid (the constants
+`REPEAT_SCALE_RATIO` and `REPEAT_DISTANCE_SPANS` in `src/pose.ts` carry the figures);
+any other ambiguity above the floor keeps the window sentence. ⚠️ Above the floor is **not** a
 promise that `pose` will place the part (see the rates below).
 
 **The texture figure.** `legibility.texture` is the mean colour step between
@@ -11505,7 +11526,10 @@ cutoff, and `PO26` holds every polish to strictly descending residuals, read thr
 the same trace. `PO31` places §6's post at the old placement from the page's own
 input bytes, and `PO32` holds it to taking the quarter-rung escape and reading the same twice.
 `PO33` holds the coarse row the tool reads rotations from to the field each seed was
-picked from.
+picked from. `PO34` holds two copies of one part 0.6 span apart to both coming back — and is
+seen red on the quarter-span grid releases before 1.4.0 searched on, which put them on
+one placement — and `PO35` holds the two readings of an ambiguity above the floor to
+their own shapes, each with a forged alternate that moves it to the other.
 
 ## 12. Reading the half of that picture `pose` refuses — `rigc chainfit`
 

package/docs/MOTION.md

@@ -234,7 +234,11 @@ frames is your job.** `alternates` non-empty means the answer was not unique;
 `ambiguous` means at least one alternate is inside the margin. Two identical limbs
 look exactly like that, and so does a shape whose silhouette fits itself at more than
 one angle. The instrument has run out — it sees one frame and has no notion of which
-limb is which. A method that works:
+limb is which. A left/right pair cut from one drawing is two files that each fit both
+places, so each comes back with both, and narrowing `--scale` or `--rotation` until one
+place is left picks the answer — it does not read it; the `ambiguous:` reading names
+this route instead of a window when every placement in the margin is one size in
+another place (AUTHORING §11.5). A method that works:
 
 1. **Enumerate the assignments, not the placements.** With k interchangeable
    placements of one part in frame A and k in frame B, there are k! ways to pair them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.64.3",
+  "version": "2.65.1",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/compile.ts

@@ -1148,6 +1148,51 @@ function checkKeyTime(where: string, time: number, authored: number, duration: n
   );
 }
 
+/**
+ * The one refusal for a key that does not come after the key before it, for
+ * every timeline kind (issue #1506) — six call sites used to spell it six times.
+ *
+ * It names both keys by index and authored time, because the time alone does
+ * not say which pair to look at: a generated phrase of four one-second cycles,
+ * each written t = 0…1, collides at every cycle boundary, and `(at t=1)` read
+ * the same as an ordinary slip. When the two keys share a time AND the keys
+ * after the pair repeat the spacing of the keys before it, the period is read
+ * off the keys themselves — the second key's time less the first key's — and
+ * the message says that the closing key of one cycle is the opening key of the
+ * next. Nothing else is inferred: a duplicate with no keys after it, or with
+ * keys that do not repeat, carries the pair alone, and the declared `loop` is
+ * not consulted because it is a player hint (§4.1) and the boundary is the same
+ * either way. The fix is phrased from the runtime rather than from taste:
+ * `Animation.apply` wraps a looping time as `time % duration` and the last
+ * frame of every curve timeline is stepped, so a track that stops short of its
+ * period holds its last key until the wrap rather than easing into t = 0.
+ *
+ * ⚠️ The repetition is compared in authored seconds within one float32 step of
+ * the later key (`float32Step`) — `lag`/`stagger` shift every key of a track by
+ * the same amount, so the spacing is the same before and after them.
+ */
+function refuseKeyOrder(where: string, keys: ReadonlyArray<{ t: number }>, i: number, duplicate: boolean): never {
+  const at = keys[i].t;
+  const before = keys[i - 1].t;
+  const period = at - keys[0].t;
+  const following = Math.min(i - 1, keys.length - 1 - i);
+  let repeats = duplicate && period > 0 && following >= 1;
+  for (let j = 1; repeats && j <= following; j++) {
+    if (Math.abs(keys[i + j].t - keys[j].t - period) > float32Step(keys[i + j].t)) repeats = false;
+  }
+  const boundary = repeats
+    ? `. The keys from t=${keys[0].t} repeat every ${period}s, so key ${i - 1} closes one cycle and key ${i} opens ` +
+      `the next at the same time: a phrase that repeats every ${period}s ends one key before its period. Generate ` +
+      'each cycle without its closing key and keep that key on the last cycle only — a looping player wraps from ' +
+      'it to t=0, and a track that stops short holds its last key until the wrap'
+    : '';
+  throw new CompileError(
+    `${where}: key times must strictly increase — key ${i} at t=${at} does not come after key ${i - 1} at ` +
+      `t=${before} (keys counted from 0)${boundary}`,
+    'CE_COMPILE_KEY_TIMES_NOT_INCREASING',
+  );
+}
+
 function channelHex(v: number): string {
   const clamped = Math.max(0, Math.min(1, v));
   return Math.round(clamped * 255)
@@ -8106,9 +8151,7 @@ function compileValueTrack(
     const key = track.keys[i];
     const next = track.keys[i + 1];
     const time = keyTime(key.t + shift);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, track.keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     // A named-value timeline (`inherit`): the key's `v` is one name, stepped by
     // the format. The name is resolved rather than copied, and what is WRITTEN
@@ -8237,9 +8280,7 @@ function compileDrawOrder(
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     // No offsets = "back to the setup draw order", which is the parser's own
     // encoding for it. An empty array means the same thing and is written the
@@ -8478,9 +8519,7 @@ function compileConstraintTrack(
     const key = keys[i];
     const next = keys[i + 1];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
 
     const entry: ModelKey = { time };
@@ -8906,9 +8945,7 @@ function compileSequenceTrack(
   for (let i = 0; i < track.keys.length; i++) {
     const key = track.keys[i];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, track.keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     if (key.index !== undefined && key.index >= series.count) {
       throw new CompileError(
@@ -8946,9 +8983,7 @@ function compileDeformTrack(
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
     const time = keyTime(key.t);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
     // -- a key that states a MODEL rather than a run (issue #294) ------------
     //
@@ -9660,9 +9695,7 @@ function compileTrack(
     const key = track.keys[i];
     const next = track.keys[i + 1];
     const time = keyTime(key.t + shift);
-    if (i > 0 && time <= (out[i - 1].time as number)) {
-      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`, 'CE_COMPILE_KEY_TIMES_NOT_INCREASING');
-    }
+    if (i > 0 && time <= (out[i - 1].time as number)) refuseKeyOrder(where, track.keys, i, time === out[i - 1].time);
     checkKeyTime(where, time, key.t, duration);
 
     if (shape === 'attachment') {

package/src/pose.ts

@@ -185,7 +185,7 @@ export const COARSE_STRIDE_FRACTION = 0.125;
  * trials found rather than 226, and 12 that placed on the old grid lost rather
  * than 9 (both at three minima per rung).
  */
-const COARSE_SUPPRESSION_CELLS = 4;
+export const COARSE_SUPPRESSION_CELLS = 4;
 
 /** How many scale rungs one octave gets in the coarse ladder. */
 export const SCALE_STEPS_PER_OCTAVE = 3;
@@ -254,7 +254,27 @@ export const BACKGROUND_BORDER_SHARE = 0.6;
  * carries it: 227 trials found against 226 at three, none lost, and a CPU cost
  * inside the grid's run-to-run noise.
  */
-const MINIMA_PER_SCALE = 5;
+export const MINIMA_PER_SCALE = 5;
+
+/**
+ * The three numbers that decide which basins the coarse pass sends down —
+ * `COARSE_STRIDE_FRACTION`, `COARSE_SUPPRESSION_CELLS`, `MINIMA_PER_SCALE` — as
+ * one value, so a control can run the search on the grid an earlier release
+ * used and show what the current one buys (issue #1519). See
+ * `PoseOptions.coarseGrid`.
+ */
+export interface PoseCoarseGrid {
+  strideFraction: number;
+  suppressionCells: number;
+  minimaPerScale: number;
+}
+
+/** The grid every caller gets — the three constants above, unchanged. */
+export const COARSE_GRID: PoseCoarseGrid = {
+  strideFraction: COARSE_STRIDE_FRACTION,
+  suppressionCells: COARSE_SUPPRESSION_CELLS,
+  minimaPerScale: MINIMA_PER_SCALE,
+};
 
 /**
  * How many candidates survive each refinement level.
@@ -387,6 +407,64 @@ export function floorClause(): string {
   return `detail ${POSE_FLOOR.detail}, measured from ${POSE_FLOOR.span} px up`;
 }
 
+/**
+ * When an ambiguity is ONE part fitting several places at one size — the
+ * reading a left/right pair cut from one drawing gives, which no window
+ * resolves (issue #1519).
+ *
+ * Both bars are read off the measured gap between the two populations, and
+ * each sits at that gap's geometric middle — the same rule for both, so neither
+ * is a number chosen to make one case come out:
+ *
+ * - **Scale**, as `|alternate / best − 1|` and over EVERY alternate inside the
+ *   margin. Same-size repeats measured 0.00001–0.00034 (a pair of legs and a pair
+ *   of ears in a picture rendered from a rig), 0.0030 (the selftest's twin
+ *   fixture, PO34) and 0.0055 (the pose fixture's mirrored arms, PO02). Every
+ *   other ambiguous part above the floor on `tools/pose_floor.ts`'s 420 trials
+ *   had an alternate at least 0.0719 off its best's scale — two scales at one
+ *   spot — and so did a pair of eyes read at 1.000 and 0.922. √(0.0055 × 0.0719)
+ *   ≈ 0.020.
+ * - **Distance**, from the best's centre to the nearest alternate's, over the
+ *   part's span at the best's scale. On that grid every other alternate above
+ *   the floor sat within 0.336 span of its best — two readings of one spot — or
+ *   2.26 spans or more away at a scale more than 20% off, which the scale bar
+ *   already separates; the closest repeat measured was the legs at 0.603.
+ *   √(0.336 × 0.603) ≈ 0.45.
+ *
+ * ⚠️ One grid trial above the floor takes this branch and is not a repeat: a
+ * blurred 48 px shin whose four placements all stopped on the scale FLOOR of the
+ * default window, at 0.5 against a truth at 1.0. Every placement on one wall has
+ * one scale by construction. Its console line marks the wall beside the value,
+ * which is the first thing to move; nothing in the alternates alone separates it
+ * from a repeat — a pair of ears in the same picture also sat on a scale floor.
+ */
+export const REPEAT_SCALE_RATIO = 0.02;
+export const REPEAT_DISTANCE_SPANS = 0.45;
+
+/** How an ambiguity's placements stand to the best one, when they are one part in several places at one size. */
+export interface PoseRepeat {
+  /** The largest `|alternate.scale / best.scale − 1|` inside the margin. */
+  scaleRatio: number;
+  /** The nearest alternate's centre distance from the best's, in spans at the best's scale. */
+  spans: number;
+}
+
+/**
+ * Whether every alternate inside the margin is a DIFFERENT place at the SAME
+ * scale as the best, against `REPEAT_SCALE_RATIO` and `REPEAT_DISTANCE_SPANS`
+ * — `null` when any one is not, or there is none. `span` is the part's longest
+ * material side in frame pixels at the best placement's scale.
+ *
+ * ⭐ Exported so the selftest can hand it a forged alternate and watch the
+ * reading change branch; the search calls it with exactly what it reported.
+ */
+export function repeatedPlaces(best: PosePlacement, alternates: readonly PosePlacement[], span: number): PoseRepeat | null {
+  if (alternates.length === 0 || !(span > 0)) return null;
+  const scaleRatio = Math.max(...alternates.map((a) => Math.abs(a.scale / best.scale - 1)));
+  const spans = Math.min(...alternates.map((a) => hypot2(a.x - best.x, a.y - best.y) / span));
+  return scaleRatio <= REPEAT_SCALE_RATIO && spans >= REPEAT_DISTANCE_SPANS ? { scaleRatio, spans } : null;
+}
+
 /**
  * The sentence that tells "the part is wrong" from "the part is too small or too
  * plain for `pose`", with every figure it rests on (issue #857).
@@ -394,7 +472,11 @@ export function floorClause(): string {
  * ⭐ Exported for the reason `windowEdgeNote` is: the guide quotes it, and a
  * message and the document teaching it must be built from one place.
  */
-export function legibilityReading(l: Omit<PoseLegibility, 'reading'>, verdict: 'refused' | 'ambiguous'): string {
+export function legibilityReading(
+  l: Omit<PoseLegibility, 'reading'>,
+  verdict: 'refused' | 'ambiguous',
+  repeat: PoseRepeat | null = null,
+): string {
   const figures =
     `part is ${l.width}x${l.height} px (span ${l.span} frame px, opaque ${l.opaqueShare}) with texture ${l.texture}, ` +
     `detail ${l.detail}; ` +
@@ -425,12 +507,27 @@ export function legibilityReading(l: Omit<PoseLegibility, 'reading'>, verdict: '
   // blurred goggles and gun from 128 px and rear shin at 48 px — five of them
   // 2.1–2.7 px off, the rear shin 19 px. So the sentence names that reading
   // too, with the one remedy that separates it: a window.
+  //
+  // 🔀 Except when the placements are one size in different places (issue
+  // #1519). Measured on a picture holding a left/right pair cut from one
+  // drawing: no --scale window separated them, narrower or wider, because they
+  // ARE one scale, and every --rotation window that "resolved" them did so by
+  // excluding one place — after which both files placed on the other, one of
+  // them 69 px off its truth and printed clean. There the window does not tell
+  // the two readings apart, it picks one, so the sentence names the route that
+  // does work instead.
+  const ambiguity =
+    repeat === null
+      ? 'either the frame holds more than one place this part fits, or every candidate missed the true one — ' +
+        'a narrower --scale or --rotation window around what you know of the part tells the two apart'
+      : `every placement in the margin is at the best's scale (within ${(repeat.scaleRatio * 100).toFixed(2)}%, ` +
+        `bar ${REPEAT_SCALE_RATIO * 100}%) and in another place (the nearest ${repeat.spans.toFixed(2)} span(s) away, ` +
+        `bar ${REPEAT_DISTANCE_SPANS}), which is the part — or a near-copy, such as a left/right pair cut from one ` +
+        'drawing — drawn more than once: read the placements as an unordered set and order it across frames ' +
+        '(MOTION.md §2.2 🔀); a --rotation window that excludes one place chooses the answer rather than measuring it';
   return (
     `${figures} — above the measured floor (AUTHORING §11.5: ${floorClause()}), so size and texture do not explain this; ` +
-    (verdict === 'refused'
-      ? 'the cut (or the search window) is the suspect'
-      : 'either the frame holds more than one place this part fits, or every candidate missed the true one — ' +
-        'a narrower --scale or --rotation window around what you know of the part tells the two apart')
+    (verdict === 'refused' ? 'the cut (or the search window) is the suspect' : ambiguity)
   );
 }
 
@@ -664,6 +761,19 @@ export interface PoseOptions {
    * level of every part's refinement is appended to it. See `PoseTrace`.
    */
   trace?: PoseTrace;
+  /**
+   * The coarse grid to search on — default `COARSE_GRID`, which is what the CLI
+   * always uses and has no flag to change.
+   *
+   * ⚠️ A plant, not a tuning knob. It exists so the selftest can run the search
+   * on the quarter-span grid releases before 1.4.0 used and watch a control go
+   * red there: two near-identical parts 0.6 of a span apart came back as ONE
+   * placement on that grid, printed `PLACE` with no alternate (issue #1519). A
+   * control nobody has seen fail holds nothing, and the only honest way to see
+   * this one fail is to search on the grid that failed. The report states the
+   * stride fraction in force in `search.coarse.strideFraction`.
+   */
+  coarseGrid?: PoseCoarseGrid;
 }
 
 /** A search candidate as the trace states it: where the part image's centre would land, frame pixels. */
@@ -1742,7 +1852,7 @@ export function estimatePose(options: PoseOptions): PoseReport {
       coarse: {
         frameLongSide: COARSE_LONG_SIDE,
         partSpan: COARSE_PART_SPAN,
-        strideFraction: COARSE_STRIDE_FRACTION,
+        strideFraction: (options.coarseGrid ?? COARSE_GRID).strideFraction,
         framePyramid: framePyramid.length,
       },
       maxResidual,
@@ -1787,6 +1897,7 @@ export function estimatePose(options: PoseOptions): PoseReport {
         maxResidual,
         { min: scaleMin, max: scaleMax },
         rotationBounds,
+        options.coarseGrid ?? COARSE_GRID,
         options.trace,
       ),
     );
@@ -1804,6 +1915,7 @@ function placePart(
   maxResidual: number,
   scaleBounds: { min: number; max: number },
   rotationBounds: { min: number; max: number; wraps: boolean },
+  coarseGrid: PoseCoarseGrid,
   trace?: PoseTrace,
 ): PosePart {
   const scaleMin = scaleBounds.min;
@@ -1938,14 +2050,14 @@ function placePart(
   }
   const coarse = levels[coarseIndex];
   const spanAtCoarse = (span * scaleReference) / coarse.reduction;
-  const stride = Math.max(1, Math.round(spanAtCoarse * COARSE_STRIDE_FRACTION));
+  const stride = Math.max(1, Math.round(spanAtCoarse * coarseGrid.strideFraction));
   const coarseSamples = samplesFor(coarse.reduction, COARSE_SAMPLES);
   let candidates: Candidate[] = [];
   let grid = { reduction: coarse.reduction, cols: 0, rows: 0, stride };
   for (const scale of scales) {
     const field = coarseScan(coarse, coarseSamples, scale, searchRotations, stride);
     grid = { reduction: coarse.reduction, cols: field.cols, rows: field.rows, stride };
-    candidates.push(...localMinima(field, COARSE_SUPPRESSION_CELLS, MINIMA_PER_SCALE));
+    candidates.push(...localMinima(field, coarseGrid.suppressionCells, coarseGrid.minimaPerScale));
   }
   base.coarse = grid;
   candidates.sort((a, b) => a.residual - b.residual);
@@ -1976,7 +2088,7 @@ function placePart(
     const plate = plates[li];
     const smooth = li !== coarseIndex;
     const branch = li === branchLevel;
-    const keep = li === coarseIndex ? scales.length * MINIMA_PER_SCALE : REFINE_CANDIDATES;
+    const keep = li === coarseIndex ? scales.length * coarseGrid.minimaPerScale : REFINE_CANDIDATES;
     const s = samplesFor(level.reduction, li === 0 ? POLISH_SAMPLES : REFINE_SAMPLES);
     // The coarse pass only sampled every `stride` pixels, so entering the
     // refinement the anchor can be half a stride out; the first polish gets a
@@ -2235,7 +2347,17 @@ function placePart(
   // move, and this sentence is about what moving it cannot change.
   if (base.refusal !== null || base.ambiguous) {
     const verdict = base.refusal !== null ? 'refused' : 'ambiguous';
-    const reading = legibilityReading(base.legibility, verdict);
+    // The whole margin rather than the alternates kept, so a repeat is not
+    // read off a list `MAX_ALTERNATES` truncated.
+    const repeat =
+      verdict === 'ambiguous'
+        ? repeatedPlaces(
+            best,
+            close.map((d) => d.placement),
+            span * best.scale,
+          )
+        : null;
+    const reading = legibilityReading(base.legibility, verdict, repeat);
     base.legibility.reading = reading;
     if (base.refusal !== null) base.refusal.detail += `; ${reading}`;
     base.notes.push(`${name}: ${reading}.`);