rig-c 0.0.0-stage → 2.20.4

package/src/chainfit.ts

@@ -0,0 +1,2752 @@
+/**
+ * chainfit — where the parts `pose` cannot see sit, read through the candidate rig.
+ *
+ * ⭐ This is `pose`'s sibling, not its replacement, and the difference is one
+ * input. `pose` is handed a picture and a pile of loose PNGs and nothing else, so
+ * it searches each part's full rigid family — two translations, a rotation and a
+ * scale — and it is honest about what that costs on a dense figure: a part drawn
+ * behind another has the occluder's pixels where its own should be, so its
+ * residual rises **at the correct placement**. On a biped in a stance that is the
+ * far arm, both thighs, the feet, the fists and whatever the hands hold.
+ *
+ * chainfit is handed the **candidate rig as well**. That buys two things `pose`
+ * structurally cannot have:
+ *
+ * 1. **Draw order**, so occlusion becomes measurable rather than a caveat. The
+ *    parts drawn after a part are exactly what covers it, and the pixels they
+ *    cover are EXCLUDED from that part's objective instead of charged to it. A
+ *    residual here is over the part's VISIBLE pixels, and `visibleShare` says how
+ *    much of the part that was — so a 12%-visible answer carries its uncertainty
+ *    in the report rather than in the reader's head.
+ * 2. **Hierarchy and attachment geometry**, so the search collapses. A child bone
+ *    whose parent is already placed does not have four degrees of freedom: its
+ *    pivot is fixed by the rig's own joint offset, so all that is left is the
+ *    hinge — one rotation about that pivot — plus a stretch, and only where the
+ *    candidate's own timelines say the rig leaves scale free. One degree of
+ *    freedom instead of four also kills the duplication `pose` has to report as
+ *    ambiguous: two identical limbs are no longer two equal answers when each of
+ *    them hangs off a different placed shoulder.
+ *
+ * 🚫 **Usage phase, so nothing here is a score and no pass bar attaches.** Same
+ * framing as `pose`, and for the same reason: this reads a **given condition** —
+ * the pose the user handed over — into spec coordinates an agent then states by
+ * construction. The residual and `visibleShare` exist so a caller knows how far
+ * to trust a placement and where two answers are equally good. The only
+ * thresholds in this file are the ones that decide whether to print an answer at
+ * all, and every one of them is reported and movable.
+ *
+ * 🔍 The objective is `src/pose.ts`'s, borrowed rather than rewritten — see the
+ * ⭐ note at the head of that file. What this adds is the mask, and the one place
+ * a mask can go wrong is worth stating before the code: **the visible set is
+ * frozen in the part's own space before the search runs**, at the placement the
+ * rig itself predicts. A mask recomputed per candidate placement makes the
+ * denominator a free variable, and the cheapest move is then to slide the part
+ * until the occluder covers nearly all of it and a handful of agreeing pixels are
+ * all that is scored. Frozen, the denominator is a constant and a move can only
+ * be paid for by agreeing with the frame.
+ *
+ * ⬇️ **The walk goes outward from an anchor, which means downward only.** An
+ * anchored part fixes its own bone completely — four numbers read off the picture
+ * for the four a similarity has — and every descendant then follows from the rig.
+ * A bone ABOVE an anchor does not: recovering it would need to know what the link
+ * between them did, which is precisely the unknown the anchor does not carry. So a
+ * limb with no trusted part on it or above it is refused rather than guessed at
+ * from a cousin.
+ *
+ * ⬆️ **The one exception is the INWARD step, and it is exactly one shape: a bone
+ * with two or more anchored descendants.** One anchored descendant carries no
+ * information about the link above it, which is the sentence above. TWO of them on
+ * different sub-chains carry something else entirely — not the links, but the
+ * bone's own placement. A bone's world transform has four numbers; a descendant's
+ * PIVOT depends on that bone and on the rig's own offsets and NOT on the
+ * descendant's own hinge, so each anchored descendant contributes two equations.
+ * Two of them make four, and four equations fix four numbers. That is the whole
+ * geometry, and `solveFromDescendants` is the whole solver.
+ *
+ * ⚠️ Which means the inward step reaches exactly one kind of bone: **one that
+ * branches.** A bone with a single child sub-chain can never be determined however
+ * good the anchor below it is — that is `no-bracket`, refused by name. Measured on
+ * the 2026-09-03 spineboy candidate, `torso` is the only bone in the rig that
+ * branches, and it is the bone the run recorded 30 `no-anchor` frames for.
+ *
+ * 🚫 And a determination is NOT a measurement of the bone it places. Its evidence
+ * lives on the anchors, so the numbers that price it are `disagreementPx`,
+ * `redundancy` and `leverPx` — not the bone's own `residual`. The visibility floor
+ * still refuses an inward placement nothing in the frame can confirm, for the same
+ * reason it refuses an anchor: the floor is about what the picture can check, not
+ * about how the number was arrived at.
+ *
+ * Coordinates are the frame's own — **frame pixels, y down, origin top-left** —
+ * exactly as in a `pose` report, so the two are readable side by side. The one
+ * addition is `hingeDeg` and `localRotationDeg`, which are **Spine** degrees
+ * (CCW, y up) because they are timeline values: what a `rotate` key would carry.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { Plate, readPlate } from '../tools/plate.ts';
+import {
+  AMBIGUITY_ABSOLUTE,
+  AMBIGUITY_RELATIVE,
+  DEFAULT_MAX_RESIDUAL,
+  POSE_SPEC,
+  UNEXPLAINED_TOLERANCE,
+  buildSamples,
+  errBilinear,
+  errNearest,
+  estimatePose,
+  halvePlate,
+  levelOf,
+  materialPlate,
+  normaliseDegrees,
+  readBackground,
+  roundTo,
+  type Level,
+  type PoseBackground,
+  type PoseReport,
+  type Samples,
+} from './pose.ts';
+import type { SpineBone, SpineRegionAttachment, SpineSkeletonJson } from './types.ts';
+
+export class ChainFitError extends Error {}
+
+/**
+ * The `spec` field every report carries, so a consumer can refuse a future shape.
+ *
+ * ⚠️ Bumped from `rigc-chainfit/1` by the inward step, and the bump is the point:
+ * a consumer that switched exhaustively on `role` or on `refusal.reason` now has
+ * two values it has never seen — `inward` and `no-bracket` — and a bone whose
+ * refusal used to read `no-anchor` can now read `no-bracket` instead. Everything
+ * `/1` carried is still there and still means the same thing; what changed is the
+ * range of two enums, which is exactly what a version exists to announce.
+ */
+export const CHAINFIT_SPEC = 'rigc-chainfit/2';
+
+// ---------------------------------------------------------------------------
+// the constants the search is made of — every one of them is reported
+// ---------------------------------------------------------------------------
+
+/**
+ * Share of a part's own alpha weight that has to survive the occluders before an
+ * answer about it is printed rather than refused.
+ *
+ * ⚠️ Not a pass bar; it is where "this measurement is of that part" stops being
+ * true. Below it the residual is a statement about a sliver, and the refusal names
+ * the measured share beside this number so a caller who wants the sliver can read
+ * past it — the placement is still filled in.
+ */
+export const DEFAULT_MIN_VISIBLE = 0.25;
+
+/**
+ * Alpha, 0..255, at which a pixel of a later-drawn part counts as covering.
+ *
+ * The same threshold the 2026-09-03 measurement run's occluder masks used, and it
+ * is a threshold rather than a blend because the question is binary: either this
+ * pixel of the frame is evidence about this part, or it is evidence about the
+ * thing in front of it.
+ */
+export const OCCLUDER_ALPHA = 96;
+
+/** Default hinge window, in Spine degrees about the bone's setup rotation. */
+export const DEFAULT_HINGE_MIN = -180;
+export const DEFAULT_HINGE_MAX = 180;
+
+/**
+ * The CEILING on the hinge sweep's step, in degrees — not the step itself.
+ *
+ * `hingeLadder` divides the window into whole steps no coarser than this, so a
+ * window whose span this does not divide is walked at an even, finer step, and
+ * the step the report states is read off that ladder. The full turn divides it
+ * exactly, which is why the default report carries this number.
+ *
+ * A full turn at this step is 120 evaluations of one bone, which is what a single
+ * degree of freedom buys: `pose` cannot afford an exhaustive rotation ladder at
+ * every position and every scale, and this has no positions or scales to cross.
+ * So the default window is the whole turn. A window that does not contain the
+ * truth is the failure `pose`'s §11.4 warns about — it does not reliably refuse,
+ * it reports the best thing inside the window — and one degree of freedom is cheap
+ * enough not to have to run that risk by default.
+ */
+export const HINGE_STEP = 3;
+
+/**
+ * Ratio window the stretch degree of freedom is searched over, when it is free.
+ *
+ * Free means the candidate's own animations key a `scale` timeline on that bone,
+ * or the caller named `--stretch`. A rig that never scales a bone is a rig saying
+ * that bone does not stretch, and inventing the freedom would hand back a length
+ * the spec does not have.
+ */
+export const DEFAULT_STRETCH_RATIO = 1.25;
+
+/** Rungs the stretch ladder gets across its window. */
+export const STRETCH_STEPS = 4;
+
+/**
+ * How many times the masks are rebuilt from the answers and the fit rerun.
+ *
+ * The first pass freezes each part's visible set at the placement the RIG
+ * predicts, which is the only seed available before anything is fitted. Where the
+ * fit then moves a limb a long way, that frozen set was measured somewhere the
+ * part no longer is — `visibleShareAtFit` is the field that says so. A second pass
+ * re-freezes on the first pass's own answers, which is why two is the default and
+ * one is a legitimate, faster, less converged choice.
+ */
+export const DEFAULT_PASSES = 2;
+
+/**
+ * What makes a `pose` answer good enough to anchor a chain on.
+ *
+ * ⭐ These two numbers are the 2026-09-03 measurement run's own "clean frame"
+ * criterion, taken rather than invented: that run folded 147 `pose` reports and
+ * counted a part as read when its residual was within 0.16, its `unexplained`
+ * within 0.45, and it came back unambiguous. Anchoring asks the same question —
+ * *is this placement trustworthy enough to hang other placements off?* — so it
+ * gets the same line, and a caller who moves it moves a reported field.
+ */
+export const ANCHOR_MAX_RESIDUAL = 0.16;
+export const ANCHOR_MAX_UNEXPLAINED = 0.45;
+
+/** Two hinge answers this close are one answer under two names. */
+export const AMBIGUITY_HINGE_DEG = 5;
+
+/**
+ * How far apart, in frame pixels, two anchored descendants have to sit before the
+ * rotation they determine is worth printing.
+ *
+ * ⭐ Derived rather than picked. An inward determination reads the bone's rotation
+ * off the DIRECTION between two anchored pivots, so a pivot error of ε px across a
+ * lever of L px is an angle error of about ε / L radians. The anchor pass's own
+ * placements are good to roughly half a pixel at best, and the chain-fit suite's
+ * hinge tolerance is 3° = 0.052 rad, so a lever that keeps a half-pixel error
+ * inside that tolerance has to be at least 0.5 / 0.052 ≈ 9.5 px. Eight is that
+ * arithmetic rounded down to a number a reader can hold, and it is a **reported,
+ * movable field** (`--inward-lever`) like every other threshold in this file.
+ *
+ * ⚠️ It is not a pass bar. Below it the bone is refused `no-bracket` naming the
+ * measured lever beside this number, and — unlike `occluded` — nothing is printed,
+ * because an angle read across two coincident points is not a placement that got
+ * worse, it is not a placement.
+ */
+export const DEFAULT_MIN_LEVER_PX = 8;
+
+/** Anchored descendants an inward determination needs. Four unknowns, two each. */
+export const INWARD_MIN_DETERMINANTS = 2;
+
+/** Sample budget per part per evaluation. The reported numbers use every pixel regardless. */
+const SEARCH_SAMPLES = 512;
+
+/** Basins each stretch rung sends to the polish, and how many survive to it in all. */
+const MINIMA_PER_RUNG = 6;
+const POLISH_CANDIDATES = 12;
+
+/** Alternates beyond this many are not printed; the count is still stated. */
+const MAX_ALTERNATES = 3;
+
+/**
+ * How far the visible share may move between the seed and the fit before the
+ * report says the measurement and the answer are not in the same place.
+ */
+const VISIBILITY_DRIFT_TOLERANCE = 0.15;
+
+const DEG = Math.PI / 180;
+
+// ---------------------------------------------------------------------------
+// the report
+// ---------------------------------------------------------------------------
+
+/** One placement of one part, in frame pixels, y down, origin top-left. */
+export interface ChainFitPlacement {
+  /** Where the part image's own centre — `(width/2, height/2)` — lands. */
+  x: number;
+  y: number;
+  /** Screen degrees: positive turns clockwise on screen. `screenToSpineDegrees` converts. */
+  rotationDeg: number;
+  /** Uniform, as frame pixels per part pixel. */
+  scale: number;
+  /**
+   * The searched degree of freedom, in **Spine** degrees relative to the bone's
+   * setup rotation — the delta a `rotate` key would carry.
+   *
+   * `null` where the quantity does not exist: an anchored bone whose own parent is
+   * unplaced has a placement read straight off the picture and no link above it to
+   * measure a local rotation against.
+   */
+  hingeDeg: number | null;
+  /** The bone's local rotation this placement implies, Spine degrees. `null` with `hingeDeg`. */
+  localRotationDeg: number | null;
+  /** The stretch factor on the bone. `1` where the DOF was not free, `null` with `hingeDeg`. */
+  stretch: number | null;
+  /**
+   * Alpha-weighted mean absolute colour error over the part's **visible** pixels,
+   * 0..1 — the objective of `src/pose.ts`, with the covered pixels dropped from
+   * both sums rather than charged. Lower is better explained; that is all it means.
+   */
+  residual: number;
+  /**
+   * The share of the part's own alpha weight the residual was computed on: what
+   * nothing drawn after it covered, at the placement the set was frozen at.
+   *
+   * ⚠️ Read every residual next to this. Both halves of a low residual on a 0.08
+   * visible share are true, and neither is worth much on its own.
+   */
+  visibleShare: number;
+  /** Part pixels behind that share — the count the number actually rests on. */
+  scoredPixels: number;
+  /**
+   * The same share recomputed where the answer LANDED, rather than where the set
+   * was frozen. Far from `visibleShare` means the fit moved out of its own
+   * measurement; another pass is the repair, and `search.passes` says how many ran.
+   */
+  visibleShareAtFit: number;
+  /** Share of the VISIBLE weight whose per-pixel error clears `UNEXPLAINED_TOLERANCE`. */
+  unexplained: number;
+  /** Share of the part's WHOLE alpha weight that lands outside the frame canvas. */
+  offCanvas: number;
+  /** Frame pixels of material this placement accounts for, over its visible set. */
+  footprint: number;
+  /** Axis-aligned box the placed part occupies, frame pixels. */
+  bbox: { x: number; y: number; width: number; height: number };
+}
+
+export type ChainFitRefusalReason =
+  | 'no-anchor'
+  /**
+   * The bone has anchored descendants but they do not bracket it: one where two
+   * are needed, or two that sit on top of each other, or every path to them
+   * crossing a bone whose own hinge or scale is unknown.
+   *
+   * ⚠️ Distinct from `no-anchor` on purpose. `no-anchor` says *nothing on this
+   * limb or below it was trusted*, and the repair is upstream at the anchor pass.
+   * `no-bracket` says *something below it was trusted and it was not enough*, and
+   * the repair is the rig's own topology or one more anchor on a different
+   * sub-chain — a different sentence to a caller who has to act on it.
+   */
+  | 'no-bracket'
+  | 'occluded'
+  | 'no-match'
+  | 'empty-part'
+  | 'no-part-image'
+  | 'unsupported-geometry';
+
+export interface ChainFitRefusal {
+  reason: ChainFitRefusalReason;
+  detail: string;
+}
+
+/** One anchored descendant an inward determination was read from. */
+export interface ChainFitInwardDeterminant {
+  /** The anchored bone whose pivot supplied two of the four equations. */
+  bone: string;
+  /** The part its anchor was read from — how the anchor pass names it. */
+  part: string;
+  /** Frame pixels from the determined bone's own pivot to this one's. */
+  leverPx: number;
+  /**
+   * Frame pixels between where the adopted answer predicts this pivot and where
+   * this anchor actually put it.
+   *
+   * ⭐ Zero by construction at `redundancy` 0 — two determinants and four unknowns
+   * leave nothing to disagree — and a real measurement above it. Same philosophy
+   * as `pivotDisagreementPx`: the number is not an error to be minimised, it is
+   * the rig and the picture disagreeing by that much, in the one place the
+   * disagreement is visible.
+   */
+  offsetPx: number;
+  /**
+   * Bones strictly between the determined bone and this one. They carry no art, so
+   * their hinge could not be fitted and their SETUP rotation was composed through —
+   * every number in this determination inherits that assumption.
+   */
+  carried: string[];
+}
+
+/** How an `inward` bone was determined, and what prices the determination. */
+export interface ChainFitInwardView {
+  /**
+   * Only one form exists, and naming it is how a future one stays readable beside
+   * it: `descendants` = two or more anchored descendants fixed all four numbers.
+   */
+  form: 'descendants';
+  determinants: ChainFitInwardDeterminant[];
+  /** Anchored descendants that could NOT be used, named with the reason rather than dropped. */
+  rejected: { bone: string; why: string }[];
+  /**
+   * Equations the solve had beyond the four a similarity needs — `2 × determinants − 4`.
+   *
+   * 🚨 Read `disagreementPx` next to this and never without it. At `redundancy` 0
+   * the disagreement is `null`, because a determination with nothing left over
+   * cannot be checked against itself: it fits its own two points exactly whether
+   * or not the rig is right. Redundancy is where the diagnostic value lives.
+   */
+  redundancy: number;
+  /** The widest frame-pixel span between two determinant pivots — what the rotation was read across. */
+  leverPx: number;
+  /** The floor `leverPx` had to clear, so an answer at its edge is visible as one. */
+  minLeverPx: number;
+  /**
+   * The worst `offsetPx` over the determinants: the over-determination residual,
+   * in frame pixels. `null` at `redundancy` 0.
+   *
+   * 🚨 **It says the determination disagrees with itself. It does NOT say which
+   * determinant is wrong.** The solve is least squares, so a displacement on one
+   * anchor is spread across every determinant near it — measured on the chain-fit
+   * fixture, a deliberate 4 px error on `buried` came back as 1.95 px on `arm`
+   * and 1.74 px on `buried`, because those two sit 5 bone units apart while the
+   * third is 24 away and nothing in the arithmetic can tell a tight pair apart.
+   * Read the per-determinant `offsetPx` list as a pattern, and attribute with a
+   * second frame or with `pivotDisagreementPx` on the anchors themselves.
+   */
+  disagreementPx: number | null;
+}
+
+/** What the rig says about the bone this part hangs off, and what was searched on it. */
+export interface ChainFitBoneView {
+  name: string;
+  parent: string | null;
+  /** The bone's own setup rotation, Spine degrees — what `hingeDeg` is measured from. */
+  setupRotationDeg: number;
+  /**
+   * Chain links from the trunk. `0` means this part's own bone IS the trunk — it
+   * was anchored, or it was determined inward — and `-1` means unplaced.
+   */
+  depth: number;
+  /** The bone this part's placement is ultimately hung from, or `null`. */
+  anchoredTo: string | null;
+  /**
+   * What that trunk bone is: an `anchor` read off the picture, or an `inward`
+   * determination read off two anchors below it.
+   *
+   * ⚠️ The field to check before quoting anything hung off it. An `inward` trunk
+   * was never seen by the anchor pass, so every placement below it inherits the
+   * determination's own uncertainty — `bone.inward.disagreementPx` on that trunk
+   * bone is where that uncertainty is priced.
+   */
+  anchoredToRole: 'anchor' | 'inward' | null;
+  /**
+   * Non-`null` only on a bone this run determined INWARD, and then it is the whole
+   * account of that determination. See `ChainFitInwardView`.
+   */
+  inward: ChainFitInwardView | null;
+  dof: {
+    /**
+     * Always searched on a chain bone: the hinge is the premise of the instrument.
+     * `false` on an anchor and on an inward bone — neither had anything searched.
+     */
+    rotation: boolean;
+    /** Searched only where the candidate leaves scale free — see `DEFAULT_STRETCH_RATIO`. */
+    stretch: boolean;
+    /**
+     * The candidate keys a `translate` timeline on this bone, so the pivot the
+     * hinge turned about is itself something the rig moves. The placement is still
+     * read off pixels; it is `localRotationDeg` that stops being keyable alone.
+     */
+    pivotFree: boolean;
+  };
+  /** The window taken, so an answer at its edge is visible as one. */
+  window: { hingeMinDeg: number; hingeMaxDeg: number; hingeStepDeg: number; stretchMin: number; stretchMax: number };
+  /** Other parts scored together with this one, because they hang off the same bone. */
+  sharedWith: string[];
+  /**
+   * Bones between the anchor and this one that carry no art. Nothing could fit
+   * their hinge, so their setup rotation was carried through and every placement
+   * below them inherits that assumption.
+   */
+  carriedBones: string[];
+  /**
+   * Anchored bones only: how far the chain's own prediction of this bone's pivot
+   * is from where the anchor put it, in frame pixels. It is a measure of the RIG
+   * against the picture — a large value says the joint offset the candidate
+   * declares is not the joint the frame shows. `null` when the chain had no
+   * prediction, which is every anchor whose parent is unplaced.
+   */
+  pivotDisagreementPx: number | null;
+}
+
+/** What the anchor pass said about this part, whether or not it became an anchor. */
+export interface ChainFitAnchorVerdict {
+  residual: number;
+  unexplained: number;
+  ambiguous: boolean;
+  /** Did it clear `ANCHOR_MAX_RESIDUAL` / `ANCHOR_MAX_UNEXPLAINED` and come back unique? */
+  eligible: boolean;
+}
+
+export interface ChainFitPart {
+  /** The part PNG's file name — how the report names the part everywhere. */
+  part: string;
+  path: string;
+  slot: string;
+  attachment: string;
+  width: number;
+  height: number;
+  /**
+   * `anchor` = taken from the anchor pass; `chain` = fitted through the rig;
+   * `inward` = DETERMINED from two or more anchored descendants, with nothing
+   * searched; `unplaced` = none of the three.
+   */
+  role: 'anchor' | 'chain' | 'inward' | 'unplaced';
+  bone: ChainFitBoneView;
+  /**
+   * Why this answer should not be taken at face value, or `null`.
+   *
+   * ⚠️ `placement` is still filled in under `occluded` and `no-match`, on purpose:
+   * a refusal names why not to trust a number, it does not hide it. The reasons
+   * that leave it `null` — `no-anchor`, `no-bracket`, `empty-part`,
+   * `no-part-image`, `unsupported-geometry` — are the ones where nothing was
+   * placed at all.
+   */
+  refusal: ChainFitRefusal | null;
+  placement: ChainFitPlacement | null;
+  /** Other hinge answers inside the ambiguity margin, best first. */
+  alternates: ChainFitPlacement[];
+  ambiguous: boolean;
+  /**
+   * What the anchor pass made of this same part on this same frame, or `null` when
+   * it had nothing for it.
+   *
+   * ⭐ The field that makes the two instruments readable together: `eligible` false
+   * with a `chain` placement beside it is a part the chain bought.
+   */
+  anchorVerdict: ChainFitAnchorVerdict | null;
+  /** Plain-language versions of everything above, in the order they were found. */
+  notes: string[];
+}
+
+export interface ChainFitReport {
+  spec: string;
+  /** The coordinate contract, spelled out in the file rather than assumed. */
+  space: string;
+  candidate: {
+    skeleton: string;
+    /** The skins searched for each slot's setup attachment, in the order tried. */
+    skins: string[];
+    bones: number;
+    slots: number;
+    /** Slots with a setup attachment this run could resolve to a region. */
+    drawn: number;
+    /** Setup draw order, back to front — the order the masks were built in. */
+    drawOrder: string[];
+  };
+  images: string;
+  frame: { path: string; width: number; height: number; background: PoseBackground };
+  anchor: {
+    source: 'pose' | 'file';
+    path: string | null;
+    criterion: { maxResidual: number; maxUnexplained: number; requireUnambiguous: boolean };
+    /** The parts whose answer was trusted, and whose bones the walk started from. */
+    anchored: string[];
+  };
+  /**
+   * The inward step's own account, beside `anchor` because it is the other way a
+   * trunk gets into this report.
+   */
+  inward: {
+    /** Bones this run determined from two or more anchored descendants, in bone order. */
+    determined: string[];
+    criterion: { minDeterminants: number; minLeverPx: number; determinantsMustBeAnchored: boolean };
+  };
+  search: {
+    hinge: { minDeg: number; maxDeg: number; stepDeg: number; steps: number };
+    stretch: { ratio: number; steps: number; freeFrom: string };
+    minVisible: number;
+    maxResidual: number;
+    ambiguity: { absolute: number; relative: number; hingeDeg: number };
+    passes: number;
+    occluderAlpha: number;
+  };
+  /** What the numbers above cannot see. Read before consuming them. */
+  caveats: string[];
+  parts: ChainFitPart[];
+}
+
+export interface ChainFitOptions {
+  /** A compiled candidate: a directory holding `skeleton.json`, or the path to one. */
+  candidatePath: string;
+  /** Where the candidate's attachment image names resolve to loose PNGs. */
+  imagesDir: string;
+  /** One pose frame. */
+  framePath: string;
+  /** A `rigc pose` report for this frame. Without it, one is computed internally. */
+  anchorPath?: string;
+  hinge?: { minDeg: number; maxDeg: number };
+  /** Ratio window for the stretch DOF, and an explicit request to search it everywhere. */
+  stretch?: number;
+  minVisible?: number;
+  maxResidual?: number;
+  passes?: number;
+  /** The inward step's lever floor, in frame pixels — see `DEFAULT_MIN_LEVER_PX`. */
+  minLeverPx?: number;
+  /** Sizes the internal anchor pass only; refused together with `anchorPath`. */
+  scale?: { min: number; max: number };
+  rotation?: { minDeg: number; maxDeg: number };
+  anchorMaxResidual?: number;
+  anchorMaxUnexplained?: number;
+}
+
+// ---------------------------------------------------------------------------
+// the candidate, as much of it as a chain fit needs
+// ---------------------------------------------------------------------------
+
+/** A region attachment's own geometry, defaulted, in the bone's local space. */
+interface AttachmentGeometry {
+  x: number;
+  y: number;
+  /** Spine degrees, CCW — the attachment's own rotation inside the bone. */
+  rotation: number;
+  scaleX: number;
+  scaleY: number;
+  width: number;
+  height: number;
+}
+
+/** One drawable this run will place. */
+interface DrawnSlot {
+  slot: string;
+  bone: string;
+  attachment: string;
+  /** The image name the attachment resolves against `--images`. */
+  image: string;
+  geometry: AttachmentGeometry;
+}
+
+/** A bone's placement in the frame's own pixels. */
+interface BonePlace {
+  x: number;
+  y: number;
+  /** Screen degrees, positive clockwise — the bone's world rotation, y-flipped. */
+  rotDeg: number;
+  /** Frame pixels per bone unit. */
+  unit: number;
+}
+
+/** A part's placement in the frame's own pixels, before it is measured. */
+interface PartPlace {
+  cx: number;
+  cy: number;
+  rotDeg: number;
+  /** Frame pixels per part pixel. */
+  scale: number;
+}
+
+/**
+ * A bone-local point (Spine's y-up local space) into frame pixels.
+ *
+ * ⭐ The whole y flip, in one place. Spine composes in a y-up world with CCW
+ * rotations; a frame is y-down with clockwise ones. Negating the local `y` and the
+ * rotation together turns the composition into a plain screen-space similarity,
+ * which is what lets every step below be one multiply — and it is verified rather
+ * than argued: this reproduces `src/render.ts`'s own posed quads to 1e-5 px across
+ * a 17-bone candidate, which is the check the selftest keeps.
+ */
+function applyBoneLocal(p: BonePlace, u: number, v: number): [number, number] {
+  const cos = Math.cos(p.rotDeg * DEG);
+  const sin = Math.sin(p.rotDeg * DEG);
+  const sv = -v;
+  return [p.x + p.unit * (cos * u - sin * sv), p.y + p.unit * (sin * u + cos * sv)];
+}
+
+/** The child's placement, given the parent's and the two residual degrees of freedom. */
+function childPlace(parent: BonePlace, bone: SpineBone, hingeDeg: number, stretch: number): BonePlace {
+  const [x, y] = applyBoneLocal(parent, bone.x ?? 0, bone.y ?? 0);
+  return {
+    x,
+    y,
+    rotDeg: parent.rotDeg - ((bone.rotation ?? 0) + hingeDeg),
+    unit: parent.unit * (bone.scaleX ?? 1) * stretch,
+  };
+}
+
+/** Where the part image lands, given its bone's placement. */
+function partPlaceOf(bp: BonePlace, geometry: AttachmentGeometry, pngWidth: number): PartPlace {
+  const [cx, cy] = applyBoneLocal(bp, geometry.x, geometry.y);
+  return {
+    cx,
+    cy,
+    rotDeg: bp.rotDeg - geometry.rotation,
+    scale: (bp.unit * geometry.scaleX * geometry.width) / pngWidth,
+  };
+}
+
+/** The inverse: one known part placement fixes its bone's, all four numbers of it. */
+function bonePlaceFromPart(pl: PartPlace, geometry: AttachmentGeometry, pngWidth: number): BonePlace {
+  const unit = (pl.scale * pngWidth) / (geometry.width * geometry.scaleX);
+  const rotDeg = pl.rotDeg + geometry.rotation;
+  const cos = Math.cos(rotDeg * DEG);
+  const sin = Math.sin(rotDeg * DEG);
+  const sv = -geometry.y;
+  return {
+    x: pl.cx - unit * (cos * geometry.x - sin * sv),
+    y: pl.cy - unit * (sin * geometry.x + cos * sv),
+    rotDeg,
+    unit,
+  };
+}
+
+/** The link an already-placed pair of bones implies — the inverse of `childPlace`. */
+function linkOf(parent: BonePlace, child: BonePlace, bone: SpineBone): { hingeDeg: number; stretch: number } {
+  return {
+    hingeDeg: normaliseDegrees(parent.rotDeg - child.rotDeg - (bone.rotation ?? 0)),
+    stretch: child.unit / Math.max(1e-9, parent.unit * (bone.scaleX ?? 1)),
+  };
+}
+
+/**
+ * A point in a bone's own local space, y already negated — the `(a, b)` of the
+ * inward solve, and the coordinates `applyBoneLocal(place, a, -b)` maps to frame
+ * pixels.
+ *
+ * ⭐ Why the negation is carried in the type rather than done at each call. In
+ * these coordinates a bone's placement acts LINEARLY:
+ *
+ *     X = x + p·a − q·b        p = unit · cos(rotDeg)
+ *     Y = y + q·a + p·b        q = unit · sin(rotDeg)
+ *
+ * Four unknowns — `x`, `y`, `p`, `q` — appearing linearly, which is the whole
+ * reason the inward step has a closed form instead of a search. `unit` and
+ * `rotDeg` come back out as `hypot(p, q)` and `atan2(q, p)`.
+ */
+interface BoneLocal {
+  a: number;
+  b: number;
+}
+
+/**
+ * A descendant's pivot expressed in an ancestor's own local space, or the reason
+ * that cannot be done.
+ *
+ * 🚨 The refusal is the load-bearing half. A descendant's pivot is a function of
+ * the ancestor's placement and of the SETUP offsets in between — and of the
+ * in-between bones' own hinges and scales, which is where it can stop being
+ * known. So a path is walked and every bone strictly between the two is
+ * interrogated: art on it means its hinge is a searched unknown, a free scale
+ * means the DISTANCE across it is unknown, and unsupported geometry means the
+ * composition is not a similarity at all. Any of the three and the descendant is
+ * not usable — named, not silently dropped, because "I had an anchor down there
+ * and could not use it" is the sentence a caller needs.
+ */
+type RigidPath = { local: BoneLocal; carried: string[] } | { blocked: string };
+
+/**
+ * Compose from `from`'s local space down to `to`'s pivot, refusing by name.
+ *
+ * `hasArt` and `stretchFree` are passed in rather than recomputed so this stays a
+ * pure function of the rig plus two predicates the caller already owns.
+ */
+function rigidPathTo(
+  bones: Map<string, SpineBone>,
+  unsupported: Map<string, string>,
+  hasArt: (bone: string) => boolean,
+  stretchFree: (bone: string) => boolean,
+  from: string,
+  to: string,
+): RigidPath {
+  // Up from `to` to `from`, so the path comes out parent-first when reversed. A
+  // guard on the walk length rather than a visited set: a cycle in a skeleton's
+  // parent links would otherwise spin here, and Spine data can be forged.
+  const up: string[] = [];
+  let cursor: string | undefined = to;
+  for (let guard = 0; guard <= bones.size; guard++) {
+    if (cursor === undefined) return { blocked: `"${to}" is not a descendant of "${from}"` };
+    if (cursor === from) break;
+    up.push(cursor);
+    cursor = bones.get(cursor)?.parent;
+  }
+  if (cursor !== from) return { blocked: `"${to}" is not a descendant of "${from}"` };
+  const path = up.reverse();
+  if (path.length === 0) return { blocked: `"${to}" is "${from}" itself` };
+
+  const carried: string[] = [];
+  // Everything strictly between the two — `path` without its last entry, which is
+  // `to` and whose OWN hinge and scale are irrelevant: a bone's pivot sits above
+  // its own local transform.
+  for (const mid of path.slice(0, -1)) {
+    const bad = unsupported.get(mid);
+    if (bad !== undefined) return { blocked: `bone "${mid}" lies between them and ${bad}` };
+    if (hasArt(mid)) {
+      return {
+        blocked:
+          `bone "${mid}" lies between them and carries art, so its hinge is one of the quantities this ` +
+          'instrument searches rather than one it knows — the distance and direction across it are not fixed',
+      };
+    }
+    if (stretchFree(mid)) {
+      return {
+        blocked:
+          `bone "${mid}" lies between them and the candidate leaves its scale free, so the DISTANCE across it ` +
+          'is unknown and the bone above it stays underdetermined',
+      };
+    }
+    carried.push(mid);
+  }
+
+  // Identity in `from`'s local space, then one `childPlace` per link with the
+  // hinge and the stretch at their setup values — which is exactly what `carried`
+  // above has just certified is the only thing they can be.
+  let acc: BonePlace = { x: 0, y: 0, rotDeg: 0, unit: 1 };
+  for (const name of path) {
+    const bone = bones.get(name);
+    if (bone === undefined) return { blocked: `the skeleton does not declare "${name}"` };
+    acc = childPlace(acc, bone, 0, 1);
+  }
+  // `applyBoneLocal` negated each local y on the way through, so `acc` is already
+  // in (a, b) and no second negation belongs here.
+  return { local: { a: acc.x, b: acc.y }, carried };
+}
+
+/** One equation pair for the inward solve: a local point and where it landed. */
+interface InwardPoint {
+  local: BoneLocal;
+  X: number;
+  Y: number;
+}
+
+/**
+ * The four numbers a bone's placement is, from two or more anchored descendants.
+ *
+ * ⭐ Least squares in closed form, because the model is linear in the unknowns
+ * (see `BoneLocal`) — so there is no window to search, no basin to miss and no
+ * tolerance to state. With exactly two points it fits them EXACTLY; with more it
+ * is the similarity that minimises the summed squared pivot error, and what it
+ * leaves over is `disagreementPx`.
+ *
+ * `null` where the points cannot fix a similarity at all: every local point at the
+ * same place, so no direction exists to read a rotation from.
+ */
+function solveFromDescendants(points: InwardPoint[]): BonePlace | null {
+  const n = points.length;
+  if (n < INWARD_MIN_DETERMINANTS) return null;
+  let ma = 0;
+  let mb = 0;
+  let mX = 0;
+  let mY = 0;
+  for (const pt of points) {
+    ma += pt.local.a;
+    mb += pt.local.b;
+    mX += pt.X;
+    mY += pt.Y;
+  }
+  ma /= n;
+  mb /= n;
+  mX /= n;
+  mY /= n;
+  let spread = 0;
+  let dotp = 0;
+  let dotq = 0;
+  for (const pt of points) {
+    const a = pt.local.a - ma;
+    const b = pt.local.b - mb;
+    const X = pt.X - mX;
+    const Y = pt.Y - mY;
+    spread += a * a + b * b;
+    dotp += a * X + b * Y;
+    dotq += a * Y - b * X;
+  }
+  if (!(spread > 1e-12)) return null;
+  const p = dotp / spread;
+  const q = dotq / spread;
+  const unit = Math.hypot(p, q);
+  if (!(unit > 1e-9)) return null;
+  return {
+    x: mX - p * ma + q * mb,
+    y: mY - q * ma - p * mb,
+    rotDeg: Math.atan2(q, p) / DEG,
+    unit,
+  };
+}
+
+function num(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+/** Read the skeleton file, or refuse by name. */
+function readSkeleton(path: string): SpineSkeletonJson {
+  if (!existsSync(path)) throw new ChainFitError(`no skeleton at ${path}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new ChainFitError(`cannot parse ${path} as JSON: ${(err as Error).message}`);
+  }
+  const skel = parsed as SpineSkeletonJson;
+  if (!Array.isArray(skel?.bones) || !Array.isArray(skel?.slots) || !Array.isArray(skel?.skins)) {
+    throw new ChainFitError(
+      `${path} is not Spine skeleton data — a chain fit needs its bones, its slots in draw order and its skins`,
+    );
+  }
+  return skel;
+}
+
+/**
+ * The bones a chain fit cannot compose through, by name and reason.
+ *
+ * ⚠️ Refused rather than approximated, and propagated down the tree: shear, a
+ * non-uniform scale and every `inherit` mode but `normal` all make the world
+ * transform something other than the similarity every placement in this file is.
+ * Approximating one would put a plausible number on a part whose geometry this
+ * instrument does not model — the same failure as searching a window that does not
+ * contain the truth, which does not refuse either, it just answers wrongly.
+ */
+function unsupportedBones(bones: SpineBone[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const bone of bones) {
+    const inherited = bone.parent === undefined ? undefined : out.get(bone.parent);
+    if (inherited !== undefined) {
+      out.set(bone.name, `its parent "${bone.parent}" is unsupported (${inherited})`);
+      continue;
+    }
+    const sx = num(bone.scaleX, 1);
+    const sy = num(bone.scaleY, 1);
+    const shearX = num(bone.shearX, 0);
+    const shearY = num(bone.shearY, 0);
+    if (shearX !== 0 || shearY !== 0) {
+      out.set(bone.name, `it shears (shearX ${shearX}, shearY ${shearY}), which is not a similarity`);
+    } else if (sx !== sy) {
+      out.set(bone.name, `its setup scale is non-uniform (scaleX ${sx}, scaleY ${sy}), which is not a similarity`);
+    } else if (sx <= 0) {
+      out.set(bone.name, `its setup scale is ${sx}; a mirrored or zero-scale bone has no rigid placement`);
+    } else if (bone.inherit !== undefined && bone.inherit !== 'normal') {
+      out.set(bone.name, `it inherits "${bone.inherit}" rather than "normal", so its world transform is not the chain's`);
+    }
+  }
+  return out;
+}
+
+/** The region attachment for one slot's setup attachment, and the image it names. */
+function resolveAttachment(
+  skel: SpineSkeletonJson,
+  slot: string,
+  attachment: string,
+): { geometry: AttachmentGeometry; image: string } | { unsupported: string } | null {
+  for (const skin of skel.skins) {
+    const raw = skin.attachments?.[slot]?.[attachment];
+    if (raw === undefined) continue;
+    // A region attachment is the one member of the union with no `type`, which is
+    // also how the parser reads it, so this is the format's own discriminator
+    // rather than a convention chosen here.
+    const kind: string = 'type' in raw ? raw.type : 'region';
+    if (kind !== 'region') {
+      return {
+        unsupported: `attachment "${attachment}" is a ${kind}, and only a region attachment has a rigid placement`,
+      };
+    }
+    const region = raw as SpineRegionAttachment;
+    const scaleX = num(region.scaleX, 1);
+    const scaleY = num(region.scaleY, 1);
+    if (scaleX !== scaleY) {
+      return { unsupported: `attachment "${attachment}" scales non-uniformly (scaleX ${scaleX}, scaleY ${scaleY})` };
+    }
+    if (scaleX <= 0) {
+      return { unsupported: `attachment "${attachment}" has scaleX ${scaleX}; a mirrored region has no rigid placement` };
+    }
+    const width = num(region.width, 0);
+    const height = num(region.height, 0);
+    if (width <= 0 || height <= 0) {
+      return { unsupported: `attachment "${attachment}" declares width ${width} and height ${height}` };
+    }
+    return {
+      geometry: {
+        x: num(region.x, 0),
+        y: num(region.y, 0),
+        rotation: num(region.rotation, 0),
+        scaleX,
+        scaleY,
+        width,
+        height,
+      },
+      image: typeof region.path === 'string' && region.path.length > 0 ? region.path : attachment,
+    };
+  }
+  return null;
+}
+
+/** Which local properties the candidate's own animations key, per bone. */
+function keyedProperties(skel: SpineSkeletonJson): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  for (const animation of Object.values(skel.animations ?? {})) {
+    for (const [bone, timelines] of Object.entries(animation.bones ?? {})) {
+      const set = out.get(bone) ?? new Set<string>();
+      for (const name of Object.keys(timelines)) set.add(name);
+      out.set(bone, set);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// the mask
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp one placed part's own coverage into a frame-sized mask.
+ *
+ * ⚠️ Walked over the DESTINATION pixels and inverse-mapped, not forward from the
+ * part's pixels. Forward stamping leaves holes wherever the placement magnifies —
+ * one part pixel then covers several frame pixels and only one of them is written
+ * — and a mask with holes lets an occluder's pixels back into a child's objective
+ * in a lattice, which is worse than not masking at all because it looks masked.
+ */
+function stampCover(into: Uint8Array, width: number, height: number, part: Plate, pl: PartPlace): void {
+  if (!(pl.scale > 0)) return;
+  const cos = Math.cos(pl.rotDeg * DEG);
+  const sin = Math.sin(pl.rotDeg * DEG);
+  const halfW = part.width / 2;
+  const halfH = part.height / 2;
+  const reach = Math.hypot(halfW, halfH) * pl.scale + 1;
+  const x0 = Math.max(0, Math.floor(pl.cx - reach));
+  const x1 = Math.min(width - 1, Math.ceil(pl.cx + reach));
+  const y0 = Math.max(0, Math.floor(pl.cy - reach));
+  const y1 = Math.min(height - 1, Math.ceil(pl.cy + reach));
+  for (let fy = y0; fy <= y1; fy++) {
+    for (let fx = x0; fx <= x1; fx++) {
+      const dx = fx + 0.5 - pl.cx;
+      const dy = fy + 0.5 - pl.cy;
+      const u = (dx * cos + dy * sin) / pl.scale + halfW;
+      const v = (-dx * sin + dy * cos) / pl.scale + halfH;
+      if (u < 0 || v < 0 || u >= part.width || v >= part.height) continue;
+      if (part.data[(Math.floor(v) * part.width + Math.floor(u)) * 4 + 3] < OCCLUDER_ALPHA) continue;
+      into[fy * width + fx] = 1;
+    }
+  }
+}
+
+/** A part's own visible pixels under a cover mask, in the part's own space. */
+interface VisibleSet {
+  keep: Uint8Array;
+  /** Alpha weight the cover leaves, and the part's whole alpha weight. */
+  weight: number;
+  total: number;
+  /** Part pixels the residual will rest on. */
+  pixels: number;
+}
+
+function visibleMask(part: Plate, pl: PartPlace, cover: Uint8Array, width: number, height: number): VisibleSet {
+  const keep = new Uint8Array(part.width * part.height);
+  const cos = Math.cos(pl.rotDeg * DEG) * pl.scale;
+  const sin = Math.sin(pl.rotDeg * DEG) * pl.scale;
+  let weight = 0;
+  let total = 0;
+  let pixels = 0;
+  for (let y = 0; y < part.height; y++) {
+    for (let x = 0; x < part.width; x++) {
+      const a = part.data[(y * part.width + x) * 4 + 3];
+      if (a === 0) continue;
+      const w = a / 255;
+      total += w;
+      const u = x + 0.5 - part.width / 2;
+      const v = y + 0.5 - part.height / 2;
+      const fx = pl.cx + u * cos - v * sin;
+      const fy = pl.cy + u * sin + v * cos;
+      const ix = Math.floor(fx);
+      const iy = Math.floor(fy);
+      // ⭐ Off the canvas is NOT covered: nothing is drawn over it, it simply is
+      // not in the picture. It stays in the visible set and the objective charges
+      // it the full 1, which is how a placement that hangs the part off the frame
+      // pays for it instead of being excused by the mask.
+      if (ix >= 0 && iy >= 0 && ix < width && iy < height && cover[iy * width + ix] === 1) continue;
+      keep[y * part.width + x] = 1;
+      weight += w;
+      pixels++;
+    }
+  }
+  return { keep, weight, total, pixels };
+}
+
+/** Which SAMPLES of a part survive its visible mask, and their weight. */
+function keptSamples(samples: Samples, keep: Uint8Array, part: Plate): { flags: Uint8Array; weight: number } {
+  const flags = new Uint8Array(samples.count);
+  let weight = 0;
+  for (let i = 0; i < samples.count; i++) {
+    // `u + width/2` is exactly the centre of the mip cell this sample averages,
+    // in full-resolution part pixels, so this reads the mask where the sample is.
+    const px = Math.floor(samples.u[i] + part.width / 2);
+    const py = Math.floor(samples.v[i] + part.height / 2);
+    if (px < 0 || py < 0 || px >= part.width || py >= part.height) continue;
+    if (keep[py * part.width + px] === 0) continue;
+    flags[i] = 1;
+    weight += samples.w[i];
+  }
+  return { flags, weight };
+}
+
+// ---------------------------------------------------------------------------
+// the objective
+// ---------------------------------------------------------------------------
+
+/** One part, ready to be scored: its art, its samples and the frozen visible set. */
+interface Target {
+  geometry: AttachmentGeometry;
+  plate: Plate;
+  samples: Samples;
+  flags: Uint8Array;
+  /** Sampled visible weight — the denominator, and a constant by construction. */
+  weight: number;
+}
+
+/**
+ * The objective for one bone, over every part that hangs off it.
+ *
+ * ⭐ The degree of freedom belongs to the BONE, not to the part, so a bone
+ * carrying four slots — a head with its eye, its mouth and its goggles — is fitted
+ * once against all four rather than four times against one each. The parts are
+ * pooled by their visible weight, which is the honest weighting: a bone whose head
+ * is most of the way visible and whose eye is a sliver is mostly told by the head.
+ */
+function boneResidual(bp: BonePlace, targets: Target[], level: Level, plate: Plate, smooth: boolean): number {
+  let acc = 0;
+  let denom = 0;
+  for (const target of targets) {
+    if (target.weight <= 0) continue;
+    const s = target.samples;
+    const pl = partPlaceOf(bp, target.geometry, target.plate.width);
+    const cos = Math.cos(pl.rotDeg * DEG) * pl.scale;
+    const sin = Math.sin(pl.rotDeg * DEG) * pl.scale;
+    for (let i = 0; i < s.count; i++) {
+      if (target.flags[i] === 0) continue;
+      const fx = pl.cx + s.u[i] * cos - s.v[i] * sin;
+      const fy = pl.cy + s.u[i] * sin + s.v[i] * cos;
+      acc +=
+        s.w[i] *
+        (smooth
+          ? errBilinear(level, plate, fx, fy, s.r[i], s.g[i], s.b[i])
+          : errNearest(level, fx, fy, s.r[i], s.g[i], s.b[i]));
+    }
+    denom += target.weight;
+  }
+  return denom > 0 ? acc / denom : 1;
+}
+
+/** One answer mid-search: the two residual degrees of freedom and what they scored. */
+interface HingeCandidate {
+  hingeDeg: number;
+  stretch: number;
+  residual: number;
+}
+
+/**
+ * Pattern search on the residual degrees of freedom: probe, take the best
+ * improvement, halve the steps when none of them improves.
+ *
+ * The sweep has already done the part a local method cannot — with one degree of
+ * freedom, "find the right basin" is an exhaustive scan of a line, which is why
+ * this file can afford the whole turn as its default window.
+ */
+function polishHinge(
+  start: HingeCandidate,
+  targets: Target[],
+  level: Level,
+  plate: Plate,
+  parent: BonePlace,
+  bone: SpineBone,
+  stretchBounds: { min: number; max: number },
+  /**
+   * The hinge window the report declares.
+   *
+   * ⚠️ Clamped here for the same reason `pose`'s polish clamps its scale: a
+   * refinement free to walk outside the window would report an answer nobody
+   * searched, and the window is a reported field a caller is entitled to read as
+   * a promise. A full turn contains every angle, so it is left unclamped and the
+   * hinge may wrap.
+   */
+  hingeBounds: { min: number; max: number; wraps: boolean },
+): HingeCandidate {
+  const at = (hingeDeg: number, stretch: number): number =>
+    boneResidual(childPlace(parent, bone, hingeDeg, stretch), targets, level, plate, true);
+  const clamp = (v: number): number => Math.min(stretchBounds.max, Math.max(stretchBounds.min, v));
+  const hold = (v: number): number =>
+    hingeBounds.wraps ? v : Math.min(hingeBounds.max, Math.max(hingeBounds.min, v));
+  let cur: HingeCandidate = { ...start, residual: at(start.hingeDeg, start.stretch) };
+  let dh = HINGE_STEP;
+  let ds = stretchBounds.max > stretchBounds.min ? 0.04 : 0;
+  for (let guard = 0; guard < 200; guard++) {
+    if (dh <= 0.02 && ds <= 0.002) break;
+    let best = cur;
+    const probe = (hingeDeg: number, stretch: number): void => {
+      const residual = at(hingeDeg, stretch);
+      if (residual < best.residual) best = { hingeDeg, stretch, residual };
+    };
+    if (dh > 0.02) {
+      probe(hold(cur.hingeDeg + dh), cur.stretch);
+      probe(hold(cur.hingeDeg - dh), cur.stretch);
+    }
+    if (ds > 0.002) {
+      probe(cur.hingeDeg, clamp(cur.stretch * (1 + ds)));
+      probe(cur.hingeDeg, clamp(cur.stretch * (1 - ds)));
+    }
+    if (best === cur) {
+      dh /= 2;
+      ds /= 2;
+      continue;
+    }
+    cur = best;
+  }
+  return cur;
+}
+
+/**
+ * The hinge ladder, with a full turn's duplicate endpoint dropped.
+ *
+ * ⭐ `pose`'s `rotationLadder` is the shape this follows, and for the same reason
+ * (issue #738). This one used to march `HINGE_STEP` off the floor and then append
+ * the ceiling, so any window whose span is not a whole number of steps got a
+ * short final gap — `--hinge -20,20` walked thirteen gaps of 3° and one of 1° —
+ * while the report printed `step 3°` and every part's note said `in 3° steps`.
+ * Now the window is divided into `Math.ceil(span / HINGE_STEP)` equal steps,
+ * endpoints included, and the step reported is `hingeLadderStep` of what this returns.
+ *
+ * ⚠️ The count is a CEILING rather than a rounding: rounding down would give a
+ * window like 4° one step of 4°, and the constant would stop bounding the step.
+ * With the ceiling the rung count is the march's own — `ceil(span / step) + 1`
+ * either way — so the repair moves where the rungs sit and never how many there
+ * are, and a span the constant divides gets the same rungs it always had.
+ *
+ * Exported because `CF19` and `CUR82` read the printed step back against it: the
+ * run walks exactly this, so it is the ladder a report line is a promise about.
+ */
+export function hingeLadder(minDeg: number, maxDeg: number): number[] {
+  const span = maxDeg - minDeg;
+  if (span <= 0) return [minDeg];
+  if (span >= 360 - 1e-9) {
+    const count = Math.round(360 / HINGE_STEP);
+    const out: number[] = [];
+    for (let i = 0; i < count; i++) out.push(minDeg + (i * 360) / count);
+    return out;
+  }
+  const steps = Math.ceil(span / HINGE_STEP - 1e-9);
+  const out: number[] = [];
+  for (let i = 0; i <= steps; i++) out.push(minDeg + (span * i) / steps);
+  return out;
+}
+
+/** The step a hinge ladder walks, read off the ladder rather than off the constant it was capped at. */
+export function hingeLadderStep(degrees: readonly number[]): number {
+  return degrees.length > 1 ? degrees[1] - degrees[0] : 0;
+}
+
+/** How a chain part's note says the hinge was walked — the same step the `search` line states. */
+export function hingeWalkPhrase(stepDeg: number): string {
+  // A shut window walks one rung and has no step, so the old `in 3° steps` on a
+  // `--hinge 12,12` note was a claim about a ladder that did not exist.
+  return stepDeg > 0 ? `in ${roundTo(stepDeg, 3)}° steps` : 'at its one rung';
+}
+
+/**
+ * The `search` line's hinge clause.
+ *
+ * ⭐ Exported for the reason `pose`'s `searchRotationClause` is: `docs/AUTHORING.md`
+ * quotes this clause, and `CUR82` builds it here over the window the page names
+ * and looks for it in the page, so the two go stale together or not at all.
+ * Rounded for the console alone — `search.hinge.stepDeg` in the JSON is the
+ * ladder's own step, unrounded.
+ */
+export function searchHingeClause(hinge: ChainFitReport['search']['hinge']): string {
+  return `hinge ${hinge.minDeg}°–${hinge.maxDeg}° step ${roundTo(hinge.stepDeg, 3)}° (${hinge.steps} rungs)`;
+}
+
+function stretchLadder(bounds: { min: number; max: number }): number[] {
+  if (bounds.max <= bounds.min) return [1];
+  const out: number[] = [];
+  for (let i = 0; i <= STRETCH_STEPS; i++) out.push(bounds.min * (bounds.max / bounds.min) ** (i / STRETCH_STEPS));
+  return out;
+}
+
+/**
+ * Every basin on the hinge line, best first.
+ *
+ * 🚨 Local minima rather than the global best alone, and per stretch rung rather
+ * than pooled — the same reason `pose` keeps its coarse scale fields apart. A limb
+ * that explains the picture pointing forwards and again pointing back is two
+ * answers, and an instrument that reports one of them has picked without saying so.
+ */
+function hingeMinima(sweep: HingeCandidate[], wraps: boolean): HingeCandidate[] {
+  const out: HingeCandidate[] = [];
+  const n = sweep.length;
+  for (let i = 0; i < n; i++) {
+    const prev = i === 0 ? (wraps ? sweep[n - 1] : null) : sweep[i - 1];
+    const next = i === n - 1 ? (wraps ? sweep[0] : null) : sweep[i + 1];
+    if (prev !== null && prev.residual < sweep[i].residual) continue;
+    if (next !== null && next.residual < sweep[i].residual) continue;
+    out.push(sweep[i]);
+  }
+  if (out.length === 0 && n > 0) out.push(sweep.reduce((a, b) => (b.residual < a.residual ? b : a)));
+  return out.sort((a, b) => a.residual - b.residual);
+}
+
+// ---------------------------------------------------------------------------
+// measuring the answer
+// ---------------------------------------------------------------------------
+
+interface Measured {
+  residual: number;
+  visibleShare: number;
+  scoredPixels: number;
+  unexplained: number;
+  offCanvas: number;
+  footprint: number;
+  bbox: { x: number; y: number; width: number; height: number };
+}
+
+/**
+ * The reported numbers, over EVERY visible pixel of the part rather than a sample
+ * of them — and over the frozen set, which is the set the search minimised.
+ */
+function measure(part: Plate, pl: PartPlace, frozen: VisibleSet, level: Level, plate: Plate): Measured {
+  const cos = Math.cos(pl.rotDeg * DEG) * pl.scale;
+  const sin = Math.sin(pl.rotDeg * DEG) * pl.scale;
+  let acc = 0;
+  let unexplained = 0;
+  let onMaterial = 0;
+  let off = 0;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (let y = 0; y < part.height; y++) {
+    for (let x = 0; x < part.width; x++) {
+      const i = (y * part.width + x) * 4;
+      const a = part.data[i + 3];
+      if (a === 0) continue;
+      const w = a / 255;
+      const u = x + 0.5 - part.width / 2;
+      const v = y + 0.5 - part.height / 2;
+      const fx = pl.cx + u * cos - v * sin;
+      const fy = pl.cy + u * sin + v * cos;
+      if (fx < minX) minX = fx;
+      if (fx > maxX) maxX = fx;
+      if (fy < minY) minY = fy;
+      if (fy > maxY) maxY = fy;
+      const inside = fx >= 0 && fy >= 0 && fx < level.width && fy < level.height;
+      if (!inside) off += w;
+      if (frozen.keep[y * part.width + x] === 0) continue;
+      const err = errBilinear(level, plate, fx, fy, part.data[i], part.data[i + 1], part.data[i + 2]);
+      acc += w * err;
+      if (err > UNEXPLAINED_TOLERANCE) unexplained += w;
+      if (inside) {
+        const ix = Math.min(level.width - 1, Math.floor(fx));
+        const iy = Math.min(level.height - 1, Math.floor(fy));
+        onMaterial += w * (plate.data[(iy * level.width + ix) * 4 + 3] / 255);
+      }
+    }
+  }
+  const denom = frozen.weight > 0 ? frozen.weight : 1;
+  const total = frozen.total > 0 ? frozen.total : 1;
+  return {
+    residual: frozen.weight > 0 ? acc / denom : 1,
+    visibleShare: frozen.weight / total,
+    scoredPixels: frozen.pixels,
+    unexplained: frozen.weight > 0 ? unexplained / denom : 1,
+    offCanvas: off / total,
+    // One part pixel covers `scale²` frame pixels, so this is the frame area the
+    // placement accounts for over the pixels it was allowed to claim.
+    footprint: onMaterial * pl.scale * pl.scale,
+    bbox: { x: minX, y: minY, width: maxX - minX, height: maxY - minY },
+  };
+}
+
+function toPlacement(
+  pl: PartPlace,
+  link: { hingeDeg: number; stretch: number } | null,
+  setupRotation: number,
+  stats: Measured,
+  visibleShareAtFit: number,
+): ChainFitPlacement {
+  return {
+    x: roundTo(pl.cx, 3),
+    y: roundTo(pl.cy, 3),
+    rotationDeg: roundTo(normaliseDegrees(pl.rotDeg), 3),
+    scale: roundTo(pl.scale, 5),
+    hingeDeg: link === null ? null : roundTo(normaliseDegrees(link.hingeDeg), 3),
+    localRotationDeg: link === null ? null : roundTo(normaliseDegrees(setupRotation + link.hingeDeg), 3),
+    stretch: link === null ? null : roundTo(link.stretch, 5),
+    residual: roundTo(stats.residual, 5),
+    visibleShare: roundTo(stats.visibleShare, 4),
+    scoredPixels: stats.scoredPixels,
+    visibleShareAtFit: roundTo(visibleShareAtFit, 4),
+    unexplained: roundTo(stats.unexplained, 4),
+    offCanvas: roundTo(stats.offCanvas, 4),
+    footprint: roundTo(stats.footprint, 1),
+    bbox: {
+      x: roundTo(stats.bbox.x, 2),
+      y: roundTo(stats.bbox.y, 2),
+      width: roundTo(stats.bbox.width, 2),
+      height: roundTo(stats.bbox.height, 2),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the anchor
+// ---------------------------------------------------------------------------
+
+/** One part's anchor-pass answer, in the shape the walk needs it. */
+interface AnchorEntry {
+  place: PartPlace;
+  verdict: ChainFitAnchorVerdict;
+}
+
+function readAnchorFile(path: string): PoseReport {
+  if (!existsSync(path)) throw new ChainFitError(`no anchor report at ${path}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new ChainFitError(`cannot parse the anchor report ${path} as JSON: ${(err as Error).message}`);
+  }
+  const report = parsed as PoseReport;
+  if (report?.spec !== POSE_SPEC) {
+    throw new ChainFitError(
+      `${path} declares spec ${JSON.stringify(report?.spec ?? null)}; --anchor takes a ${POSE_SPEC} report, ` +
+        'which is what `rigc pose --out` writes',
+    );
+  }
+  if (!Array.isArray(report.parts)) throw new ChainFitError(`${path} carries no parts array`);
+  return report;
+}
+
+/** An anchor report folded into per-part entries, keyed by PNG file name. */
+function anchorEntries(
+  report: PoseReport,
+  criterion: { maxResidual: number; maxUnexplained: number },
+): Map<string, AnchorEntry> {
+  const out = new Map<string, AnchorEntry>();
+  for (const part of report.parts) {
+    if (part.placement === null) continue;
+    const p = part.placement;
+    const eligible =
+      part.refusal === null &&
+      !part.ambiguous &&
+      p.residual <= criterion.maxResidual &&
+      p.unexplained <= criterion.maxUnexplained;
+    out.set(basename(part.part), {
+      place: { cx: p.x, cy: p.y, rotDeg: p.rotationDeg, scale: p.scale },
+      verdict: { residual: p.residual, unexplained: p.unexplained, ambiguous: part.ambiguous, eligible },
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// the instrument
+// ---------------------------------------------------------------------------
+
+/** The mutable state of one part across the passes. */
+interface PartState {
+  drawn: DrawnSlot;
+  path: string;
+  plate: Plate | null;
+  /** Why nothing was searched, when nothing was. */
+  blocked: ChainFitRefusal | null;
+  place: PartPlace | null;
+  /** The visible set the search was scored on, frozen before it ran. */
+  frozen: VisibleSet | null;
+  /** The link its bone ended up on, or `null` where the quantity does not exist. */
+  link: { hingeDeg: number; stretch: number } | null;
+  /** Its bone's visible set had to be relocated by an unmasked look before it froze. */
+  relocated: boolean;
+  /**
+   * This part IS the one its bone's anchor was read from.
+   *
+   * ⭐ The distinction the refusals turn on. Three kinds of placement live in one
+   * report: the anchor's own, which came from the anchor pass and was not searched
+   * here; the other parts on an anchored bone, whose placement is the RIG's and is
+   * therefore a real measurement of it; and the chain's, which was searched. This
+   * instrument refuses the last two and does not second-guess the first — an
+   * `occluded` refusal says "a search over a sliver is not a measurement", and no
+   * search happened. Its trust signal is `anchorVerdict`, which is the pass's own.
+   */
+  isAnchorSource: boolean;
+  alternates: { place: PartPlace; link: { hingeDeg: number; stretch: number } }[];
+  role: 'anchor' | 'chain' | 'inward' | 'unplaced';
+}
+
+export function estimateChainFit(options: ChainFitOptions): ChainFitReport {
+  const skeletonPath = resolveSkeletonPath(options.candidatePath);
+  const framePath = resolve(options.framePath);
+  const imagesDir = resolve(options.imagesDir);
+  if (!existsSync(framePath)) throw new ChainFitError(`no pose frame at ${framePath}`);
+  if (!existsSync(imagesDir) || !statSync(imagesDir).isDirectory()) {
+    throw new ChainFitError(`${imagesDir} is not a directory — --images takes the directory the part PNGs are in`);
+  }
+  if (options.anchorPath !== undefined && (options.scale !== undefined || options.rotation !== undefined)) {
+    throw new ChainFitError(
+      '--scale and --rotation size the internal anchor pass, and --anchor means there is no internal pass; ' +
+        'give those two to `rigc pose` when you make the report instead',
+    );
+  }
+  let frame: Plate;
+  try {
+    frame = readPlate(framePath);
+  } catch (err) {
+    throw new ChainFitError(`cannot read the pose frame ${framePath}: ${(err as Error).message}`);
+  }
+
+  const skel = readSkeleton(skeletonPath);
+  const bones = new Map<string, SpineBone>(skel.bones.map((b) => [b.name, b]));
+  const boneOrder = skel.bones.map((b) => b.name);
+  const unsupported = unsupportedBones(skel.bones);
+  const keyed = keyedProperties(skel);
+
+  const hingeMin = options.hinge?.minDeg ?? DEFAULT_HINGE_MIN;
+  const hingeMax = options.hinge?.maxDeg ?? DEFAULT_HINGE_MAX;
+  const hinges = hingeLadder(hingeMin, hingeMax);
+  // One derivation of the step, read off the ladder the run walks: the report's
+  // `search.hinge`, every part's `window` and every part's note all take it
+  // from here, and none of them from `HINGE_STEP`, which only caps it.
+  const hingeStep = hingeLadderStep(hinges);
+  const wraps = hingeMax - hingeMin >= 360 - 1e-9;
+  const stretchRatio = options.stretch ?? DEFAULT_STRETCH_RATIO;
+  const stretchEverywhere = options.stretch !== undefined;
+  const minVisible = options.minVisible ?? DEFAULT_MIN_VISIBLE;
+  const maxResidual = options.maxResidual ?? DEFAULT_MAX_RESIDUAL;
+  const passes = Math.max(1, Math.round(options.passes ?? DEFAULT_PASSES));
+  const minLeverPx = options.minLeverPx ?? DEFAULT_MIN_LEVER_PX;
+  const criterion = {
+    maxResidual: options.anchorMaxResidual ?? ANCHOR_MAX_RESIDUAL,
+    maxUnexplained: options.anchorMaxUnexplained ?? ANCHOR_MAX_UNEXPLAINED,
+  };
+
+  // --- what the candidate draws, in its own order --------------------------
+  const drawn: DrawnSlot[] = [];
+  const undrawn: string[] = [];
+  const blockedSlots: { slot: string; why: string }[] = [];
+  for (const slot of skel.slots) {
+    if (slot.attachment === undefined) {
+      undrawn.push(slot.name);
+      continue;
+    }
+    const resolved = resolveAttachment(skel, slot.name, slot.attachment);
+    if (resolved === null) {
+      undrawn.push(slot.name);
+      continue;
+    }
+    if ('unsupported' in resolved) {
+      blockedSlots.push({ slot: slot.name, why: resolved.unsupported });
+      continue;
+    }
+    drawn.push({
+      slot: slot.name,
+      bone: slot.bone,
+      attachment: slot.attachment,
+      image: resolved.image,
+      geometry: resolved.geometry,
+    });
+  }
+  if (drawn.length === 0) {
+    throw new ChainFitError(
+      `${skeletonPath} poses no region attachment in its setup pose — a chain fit places region attachments, and ` +
+        'this candidate has none to place',
+    );
+  }
+
+  // --- the parts, and the states that carry them ---------------------------
+  const states: PartState[] = [];
+  const plateCache = new Map<string, Plate | null>();
+  for (const slot of drawn) {
+    const path = join(imagesDir, `${slot.image}.png`);
+    const state: PartState = {
+      drawn: slot,
+      path,
+      plate: null,
+      blocked: null,
+      place: null,
+      frozen: null,
+      link: null,
+      relocated: false,
+      isAnchorSource: false,
+      alternates: [],
+      role: 'unplaced',
+    };
+    const boneBlock = unsupported.get(slot.bone);
+    if (!bones.has(slot.bone)) {
+      state.blocked = {
+        reason: 'unsupported-geometry',
+        detail: `slot "${slot.slot}" hangs off bone "${slot.bone}", which the skeleton does not declare`,
+      };
+    } else if (boneBlock !== undefined) {
+      state.blocked = { reason: 'unsupported-geometry', detail: `bone "${slot.bone}": ${boneBlock}` };
+    } else {
+      const plate = loadPart(path, plateCache);
+      if (typeof plate === 'string') {
+        state.blocked = { reason: 'no-part-image', detail: plate };
+      } else if (!hasMaterial(plate)) {
+        state.blocked = {
+          reason: 'empty-part',
+          detail: `${basename(path)} is ${plate.width}x${plate.height} and every pixel of it is transparent`,
+        };
+      } else {
+        state.plate = plate;
+      }
+    }
+    states.push(state);
+  }
+
+  // --- the frame, as the objective reads it --------------------------------
+  const background = readBackground(frame);
+  const material = materialPlate(frame, background);
+  background.materialShare = roundTo(material.share, 4);
+  const level = levelOf(material.plate, 1);
+
+  // --- the anchor ----------------------------------------------------------
+  const anchorSource: 'pose' | 'file' = options.anchorPath === undefined ? 'pose' : 'file';
+  const partPaths = [...new Set(states.filter((s) => s.plate !== null).map((s) => s.path))].sort();
+  const anchorReport =
+    options.anchorPath === undefined
+      ? // ⭐ The internal anchor pass IS `pose`, over exactly the parts this
+        // candidate draws — not a second estimator with the same job. `--anchor`
+        // is the same call made earlier and saved.
+        estimatePose({ imagesDir, framePath, parts: partPaths, scale: options.scale, rotation: options.rotation })
+      : readAnchorFile(options.anchorPath);
+  const anchors = anchorEntries(anchorReport, criterion);
+
+  const anchorForBone = new Map<string, { state: PartState; entry: AnchorEntry }>();
+  for (const state of states) {
+    if (state.plate === null) continue;
+    const entry = anchors.get(basename(state.path));
+    if (entry === undefined || !entry.verdict.eligible) continue;
+    const held = anchorForBone.get(state.drawn.bone);
+    // A bone carrying several drawn parts is anchored by the one the pass trusts
+    // most, because they cannot all be right and the residual is the tie-break.
+    if (held === undefined || entry.verdict.residual < held.entry.verdict.residual) {
+      anchorForBone.set(state.drawn.bone, { state, entry });
+    }
+  }
+
+  // --- the walk ------------------------------------------------------------
+  const placedBones = new Map<string, BonePlace>();
+  const depthOf = new Map<string, number>();
+  const anchoredTo = new Map<string, string>();
+  const carried = new Map<string, string[]>();
+  const pivotDisagreement = new Map<string, number>();
+  const targetsOfBone = new Map<string, PartState[]>();
+  for (const state of states) {
+    if (state.plate === null) continue;
+    const list = targetsOfBone.get(state.drawn.bone) ?? [];
+    list.push(state);
+    targetsOfBone.set(state.drawn.bone, list);
+  }
+  /** Bones the inward step determined, and the account of each determination. */
+  const inwardBones = new Map<string, ChainFitInwardView>();
+  /** Why a bone the inward step LOOKED at could not be determined, for its refusal. */
+  const inwardAttempt = new Map<string, string>();
+  const hasArt = (bone: string): boolean => (targetsOfBone.get(bone) ?? []).length > 0;
+  const boneStretchFree = (bone: string): boolean => stretchEverywhere || (keyed.get(bone)?.has('scale') ?? false);
+
+  /** Where the rig currently puts a part, given the placed bones. */
+  const placeOf = (state: PartState): PartPlace | null => {
+    const bp = placedBones.get(state.drawn.bone);
+    if (bp === undefined || state.plate === null) return null;
+    return partPlaceOf(bp, state.drawn.geometry, state.plate.width);
+  };
+
+  /**
+   * Seed every bone: trunk bones from their own answer, the rest from the rig.
+   *
+   * ⭐ Two kinds of trunk now, and they are seeded identically on purpose. An
+   * ANCHORED bone's four numbers were read off the picture; an INWARD bone's were
+   * determined from two anchored descendants. Either way the bone is fixed, its
+   * `depth` is 0 and everything under it follows from the rig — so the only thing
+   * that distinguishes them downstream is `anchoredToRole`, which is exactly the
+   * field a caller reads to decide how much to trust a subtree.
+   *
+   * Idempotent, and run more than once: the inward step needs the anchored bones
+   * placed before it can determine anything, and its determinations then need
+   * propagating to everything below them.
+   */
+  const seedBones = (): void => {
+    for (const name of boneOrder) {
+      const bone = bones.get(name);
+      if (bone === undefined || unsupported.has(name)) continue;
+      const anchor = anchorForBone.get(name);
+      const parentPlace = bone.parent === undefined ? undefined : placedBones.get(bone.parent);
+      const chainPlace = parentPlace === undefined ? null : childPlace(parentPlace, bone, 0, 1);
+      if (anchor !== undefined && anchor.state.plate !== null) {
+        const place = bonePlaceFromPart(anchor.entry.place, anchor.state.drawn.geometry, anchor.state.plate.width);
+        placedBones.set(name, place);
+        depthOf.set(name, 0);
+        anchoredTo.set(name, name);
+        carried.set(name, []);
+        if (chainPlace !== null) {
+          pivotDisagreement.set(name, Math.hypot(chainPlace.x - place.x, chainPlace.y - place.y));
+        }
+        continue;
+      }
+      if (inwardBones.has(name)) {
+        // Already in `placedBones` — put there by `inwardStep`, which is the only
+        // writer of it. Its own bookkeeping is set here so the two trunk kinds go
+        // through one code path.
+        depthOf.set(name, 0);
+        anchoredTo.set(name, name);
+        carried.set(name, []);
+        continue;
+      }
+      if (chainPlace === null || bone.parent === undefined) continue;
+      placedBones.set(name, chainPlace);
+      depthOf.set(name, (depthOf.get(bone.parent) ?? 0) + 1);
+      const root = anchoredTo.get(bone.parent);
+      if (root !== undefined) anchoredTo.set(name, root);
+      const inherited = carried.get(bone.parent) ?? [];
+      const fittable = (targetsOfBone.get(name) ?? []).length > 0;
+      carried.set(name, fittable ? inherited : [...inherited, name]);
+    }
+  };
+
+  /**
+   * The inward step: bones with two or more ANCHORED descendants, determined.
+   *
+   * ⬆️ Run after `seedBones` and before anything is fitted, so what it sees is
+   * exactly the anchored bones and the rig's own prediction below them. A bone it
+   * reaches is a bone the outward walk left unplaced, which — because seeding
+   * propagates through every placed parent — means a bone with **no placed
+   * ancestor at all**. So there is no parent side to bracket against, and the
+   * whole determination comes from below.
+   *
+   * 🚨 The determinants are ANCHORED bones and nothing else. A bone the outward
+   * walk placed is sitting at whatever hinge the rig's setup happens to declare
+   * until it is fitted, and a bone this step determined is itself derived —
+   * reading either as evidence would compound a guess into a placement and there
+   * would be no field that said so. `criterion.determinantsMustBeAnchored` states
+   * it in the report.
+   */
+  const inwardStep = (): void => {
+    for (const name of boneOrder) {
+      if (placedBones.has(name) || unsupported.has(name)) continue;
+      const bone = bones.get(name);
+      if (bone === undefined) continue;
+
+      const usable: { bone: string; part: string; local: BoneLocal; carried: string[]; place: BonePlace }[] = [];
+      const rejected: { bone: string; why: string }[] = [];
+      for (const [anchoredBone, held] of anchorForBone) {
+        const place = placedBones.get(anchoredBone);
+        if (place === undefined) continue;
+        const path = rigidPathTo(bones, unsupported, hasArt, boneStretchFree, name, anchoredBone);
+        if ('blocked' in path) {
+          // Only worth reporting for an anchor that IS below this bone: "not a
+          // descendant" is true of most of the skeleton and says nothing.
+          if (!path.blocked.includes('is not a descendant of')) rejected.push({ bone: anchoredBone, why: path.blocked });
+          continue;
+        }
+        usable.push({
+          bone: anchoredBone,
+          part: basename(held.state.path),
+          local: path.local,
+          carried: path.carried,
+          place,
+        });
+      }
+
+      const listed = (): string =>
+        rejected.length === 0
+          ? ''
+          : `; ${rejected.length} anchored descendant(s) could not be used — ${rejected
+              .map((r) => `"${r.bone}" (${r.why})`)
+              .join('; ')}`;
+
+      if (usable.length + rejected.length === 0) continue; // nothing below it: `no-anchor`, unchanged
+      if (usable.length < INWARD_MIN_DETERMINANTS) {
+        inwardAttempt.set(
+          name,
+          `bone "${name}" has ${usable.length} usable anchored descendant(s) ` +
+            `(${usable.length === 0 ? 'none' : usable.map((u) => `"${u.bone}"`).join(', ')}) and an inward ` +
+            `determination needs ${INWARD_MIN_DETERMINANTS}: four numbers fix a placement and each anchored ` +
+            'descendant supplies two. One anchor below a bone says nothing about the link above it' +
+            listed(),
+        );
+        continue;
+      }
+
+      const solved = solveFromDescendants(usable.map((u) => ({ local: u.local, X: u.place.x, Y: u.place.y })));
+      let lever = 0;
+      for (let i = 0; i < usable.length; i++) {
+        for (let j = i + 1; j < usable.length; j++) {
+          lever = Math.max(lever, Math.hypot(usable[i].place.x - usable[j].place.x, usable[i].place.y - usable[j].place.y));
+        }
+      }
+      if (solved === null) {
+        inwardAttempt.set(
+          name,
+          `bone "${name}" has ${usable.length} usable anchored descendant(s) (${usable
+            .map((u) => `"${u.bone}"`)
+            .join(', ')}) and they do not fix a rotation: the rig places their pivots at the same point in ` +
+            `"${name}"'s own local space, so there is no direction to read one from` + listed(),
+        );
+        continue;
+      }
+      if (lever < minLeverPx) {
+        inwardAttempt.set(
+          name,
+          `bone "${name}"'s anchored descendants (${usable.map((u) => `"${u.bone}"`).join(', ')}) sit ` +
+            `${roundTo(lever, 3)} px apart in the frame, below the lever floor ${minLeverPx}: a rotation read ` +
+            'across that span turns a half-pixel anchor error into several degrees, so nothing is printed rather ' +
+            'than printed and disowned' +
+            listed(),
+        );
+        continue;
+      }
+
+      // What the adopted answer PREDICTS for each determinant's own pivot, against
+      // where that anchor actually put it. At two determinants this is zero by
+      // construction; above two it is the diagnostic.
+      const determinants: ChainFitInwardDeterminant[] = usable.map((u) => {
+        const [px, py] = applyBoneLocal(solved, u.local.a, -u.local.b);
+        return {
+          bone: u.bone,
+          part: u.part,
+          leverPx: roundTo(Math.hypot(u.place.x - solved.x, u.place.y - solved.y), 3),
+          offsetPx: roundTo(Math.hypot(px - u.place.x, py - u.place.y), 4),
+          carried: u.carried,
+        };
+      });
+      const redundancy = 2 * usable.length - 4;
+      placedBones.set(name, solved);
+      inwardBones.set(name, {
+        form: 'descendants',
+        determinants,
+        rejected,
+        redundancy,
+        leverPx: roundTo(lever, 3),
+        minLeverPx,
+        disagreementPx: redundancy > 0 ? roundTo(Math.max(...determinants.map((d) => d.offsetPx)), 4) : null,
+      });
+      inwardAttempt.delete(name);
+    }
+  };
+
+  /**
+   * The union of everything drawn AFTER each of the named parts, at wherever those
+   * later parts currently sit.
+   *
+   * 🚨 Rebuilt for each bone the moment before that bone is fitted, and NOT once
+   * per pass — this is the difference between the instrument working on a stance
+   * and not. Building every mask from the rig's setup prediction seems equivalent
+   * and is not: a setup pose has the arms hanging down the body, so the first pass
+   * masks a thigh with an arm that is not there. Measured on `ess/idle/f0000`,
+   * `front-thigh` came back 4.5% visible, was searched over 202 pixels and landed
+   * 78° out; with the mask refreshed from the arm's own fitted placement — the arm
+   * bones are declared before the thighs, so they are already fitted by then — the
+   * same part reads 71% visible and lands on the leg. What remains order-dependent
+   * is what `passes` is for.
+   *
+   * Walked in reverse draw order with one running union, so the union holds
+   * exactly the later-drawn parts at each snapshot, and one frame-sized array is
+   * all it costs however many parts there are.
+   */
+  const coversFor = (indices: number[]): Map<number, Uint8Array> => {
+    const out = new Map<number, Uint8Array>();
+    if (indices.length === 0) return out;
+    const wanted = new Set(indices);
+    const lowest = Math.min(...indices);
+    const cover = new Uint8Array(frame.width * frame.height);
+    for (let i = states.length - 1; i >= lowest; i--) {
+      if (wanted.has(i)) out.set(i, cover.slice());
+      const state = states[i];
+      if (state.plate === null || state.place === null) continue;
+      stampCover(cover, frame.width, frame.height, state.plate, state.place);
+    }
+    return out;
+  };
+  const indexOfState = new Map<PartState, number>();
+  states.forEach((state, i) => indexOfState.set(state, i));
+
+  const samplesCache = new Map<string, Samples>();
+  const samplesFor = (state: PartState, plate: Plate, scale: number): Samples => {
+    // The part is reduced to about the frame's own resolution before it is
+    // sampled — comparing full-resolution art against a frame drawn at a fifth of
+    // it charges the frame's own downsampling on every edge pixel.
+    const mip = Math.max(0, Math.min(8, Math.round(Math.log2(1 / Math.max(1e-6, scale)))));
+    const key = `${state.path}:${mip}`;
+    const hit = samplesCache.get(key);
+    if (hit !== undefined) return hit;
+    let reduced = plate;
+    for (let i = 0; i < mip; i++) reduced = halvePlate(reduced);
+    const built = buildSamples(reduced, 2 ** mip, plate.width / 2, plate.height / 2, SEARCH_SAMPLES);
+    samplesCache.set(key, built);
+    return built;
+  };
+
+  for (let pass = 0; pass < passes; pass++) {
+    if (pass === 0) {
+      seedBones();
+      // ⬆️ Then inward, then seed again to carry each determination down its own
+      // subtree — and around, because determining one bone can put a NEW anchored
+      // descendant within a rigid path of the next one up. The loop settles in one
+      // extra round on every rig measured so far; the guard is there because a
+      // forged skeleton is allowed to be strange, not because this is expected to
+      // iterate.
+      for (let round = 0; round < 4; round++) {
+        const before = inwardBones.size;
+        inwardStep();
+        if (inwardBones.size === before) break;
+        seedBones();
+      }
+      // An attempt recorded for a bone that a LATER round then placed — through a
+      // determination above it — would refuse a part that is in the report with a
+      // placement. The refusal is only for what is still unplaced.
+      for (const name of [...inwardAttempt.keys()]) if (placedBones.has(name)) inwardAttempt.delete(name);
+      for (const state of states) state.place = placeOf(state);
+    }
+    // Pass 0 seeds every chain bone on the rig's own prediction from the anchors;
+    // every later pass seeds on the previous pass's answers, which is what makes
+    // the frozen visible set and the answer converge on the same place.
+    //
+    // The inward step is NOT repeated: its determinants are the anchored bones,
+    // which no pass moves, so the second pass would compute the same four numbers.
+
+    for (const name of boneOrder) {
+      const bone = bones.get(name);
+      if (bone === undefined || unsupported.has(name) || anchorForBone.has(name) || inwardBones.has(name)) continue;
+      const parentPlace = bone.parent === undefined ? undefined : placedBones.get(bone.parent);
+      if (parentPlace === undefined) continue;
+      const boneTargets = targetsOfBone.get(name) ?? [];
+      const stretchFree = stretchEverywhere || (keyed.get(name)?.has('scale') ?? false);
+      const stretchBounds = stretchFree ? { min: 1 / stretchRatio, max: stretchRatio } : { min: 1, max: 1 };
+
+      // The occluders do not move while this bone is fitted, so one snapshot per
+      // bone serves both the seed below and the freeze after it.
+      const covers = coversFor(boneTargets.map((s) => indexOfState.get(s) ?? 0));
+
+      /**
+       * Freeze the bone's parts where they currently sit, and report how much of
+       * the bone that leaves scoreable.
+       *
+       * ⭐ Frozen HERE: the visible set is decided once, before the search, and
+       * the search cannot change it. A denominator the search can shrink turns
+       * "explain these pixels" into "cover yourself up", and the cheapest move is
+       * then to slide behind the occluder until a handful of agreeing pixels are
+       * all that is scored — measured, that produced parts reporting an 8–20%
+       * visible share with a confident residual at rotations 100–140° out on an
+       * upright stance.
+       */
+      const freezeHere = (): { targets: Target[]; visible: number; whole: number } => {
+        const targets: Target[] = [];
+        let visible = 0;
+        let whole = 0;
+        for (const state of boneTargets) {
+          const cover = covers.get(indexOfState.get(state) ?? -1);
+          if (state.plate === null || cover === undefined || state.place === null) continue;
+          const set = visibleMask(state.plate, state.place, cover, frame.width, frame.height);
+          state.frozen = set;
+          visible += set.weight;
+          whole += set.total;
+          const samples = samplesFor(state, state.plate, state.place.scale);
+          const kept = keptSamples(samples, set.keep, state.plate);
+          targets.push({
+            geometry: state.drawn.geometry,
+            plate: state.plate,
+            samples,
+            flags: kept.flags,
+            weight: kept.weight,
+          });
+        }
+        return { targets, visible, whole };
+      };
+
+      /** The same parts with nothing masked out — every pixel of them scoreable. */
+      const bareTargets = (): Target[] => {
+        const out: Target[] = [];
+        for (const state of boneTargets) {
+          if (state.plate === null || state.place === null) continue;
+          const samples = samplesFor(state, state.plate, state.place.scale);
+          out.push({
+            geometry: state.drawn.geometry,
+            plate: state.plate,
+            samples,
+            flags: new Uint8Array(samples.count).fill(1),
+            weight: samples.weight,
+          });
+        }
+        return out;
+      };
+
+      /** The best hinge on one set of targets, found by sweeping and refining. */
+      const searchOver = (targets: Target[]): HingeCandidate[] => {
+        const seeds: HingeCandidate[] = [];
+        for (const stretch of stretchLadder(stretchBounds)) {
+          const rung: HingeCandidate[] = hinges.map((hingeDeg) => ({
+            hingeDeg,
+            stretch,
+            residual: boneResidual(
+              childPlace(parentPlace, bone, hingeDeg, stretch),
+              targets,
+              level,
+              material.plate,
+              false,
+            ),
+          }));
+          seeds.push(...hingeMinima(rung, wraps).slice(0, MINIMA_PER_RUNG));
+        }
+        seeds.sort((a, b) => a.residual - b.residual);
+        return seeds
+          .slice(0, POLISH_CANDIDATES)
+          .map((seed) =>
+            polishHinge(seed, targets, level, material.plate, parentPlace, bone, stretchBounds, {
+              min: hingeMin,
+              max: hingeMax,
+              wraps,
+            }),
+          )
+          .sort((a, b) => a.residual - b.residual);
+      };
+
+      /** Move the bone, and its parts with it. */
+      const put = (cand: HingeCandidate): void => {
+        placedBones.set(name, childPlace(parentPlace, bone, cand.hingeDeg, cand.stretch));
+        for (const state of boneTargets) state.place = placeOf(state);
+      };
+
+      // What to fall back to, saved before anything moves. On pass 0 this is the
+      // rig's own prediction from the anchor; on every later pass it is the
+      // previous pass's answer, and either is a better fallback than resetting the
+      // hinge to zero — which would throw away a relocation the first pass found.
+      const seedBone = placedBones.get(name);
+      const seedPlaces = boneTargets.map((st) => st.place);
+      const restoreSeed = (): void => {
+        if (seedBone !== undefined) placedBones.set(name, seedBone);
+        boneTargets.forEach((st, i) => {
+          st.place = seedPlaces[i];
+        });
+      };
+
+      let frozenHere = freezeHere();
+      let relocated = false;
+      // 🚨 A part the RIG predicts is invisible would otherwise never be looked
+      // for. The seed of the first pass is the candidate's own setup, and a setup
+      // pose routinely hides a limb the frame shows — a spineboy setup has both
+      // arms hanging down the body, so the thigh's visible set freezes at 4% and a
+      // search over 202 pixels lands 78° out. So a bone whose frozen share is
+      // under the floor gets ONE unmasked look first — `pose`'s own question,
+      // restricted to this arc — purely to decide WHERE to freeze. The answer is
+      // then re-searched with the mask in place, so nothing is ever ranked on a
+      // denominator the search could shrink.
+      if (frozenHere.visible < minVisible * frozenHere.whole) {
+        const bare = bareTargets();
+        if (bare.some((t) => t.weight > 0)) {
+          const wasVisible = frozenHere.visible;
+          const relocation = searchOver(bare);
+          if (relocation.length > 0) {
+            put(relocation[0]);
+            const after = freezeHere();
+            // ⚠️ Kept only if it actually helped. An unmasked look at a part that
+            // is genuinely behind something reads the occluder and can land
+            // somewhere even more covered than the rig's guess; taking that would
+            // trade a useful fallback — "the chain put it here" — for a wandered
+            // number, and the refusal below would then name a placement nobody
+            // has a reason to believe.
+            if (after.visible > wasVisible) {
+              frozenHere = after;
+              relocated = true;
+              for (const state of boneTargets) {
+                state.link = { hingeDeg: relocation[0].hingeDeg, stretch: relocation[0].stretch };
+              }
+            } else {
+              restoreSeed();
+              frozenHere = freezeHere();
+            }
+          }
+        }
+      }
+
+      // ⚠️ Still under the floor after that look: nothing more is searched, and
+      // what gets reported is where the chain put it. The honest answer there is
+      // "the chain put it here and the pixels could not confirm it", which is what
+      // the `occluded` refusal says — and the placement is printed anyway.
+      if (frozenHere.targets.every((t) => t.weight <= 0) || frozenHere.visible < minVisible * frozenHere.whole) {
+        for (const state of boneTargets) {
+          state.role = 'chain';
+          state.alternates = [];
+          state.relocated = relocated;
+          // The seed is already what is placed — the relocation either stuck or
+          // was undone — so all this settles is how it gets described.
+          state.link = state.link ?? { hingeDeg: 0, stretch: 1 };
+        }
+        continue;
+      }
+
+      const polished = searchOver(frozenHere.targets);
+      const distinct: HingeCandidate[] = [];
+      for (const cand of polished) {
+        const same = distinct.some(
+          (d) =>
+            Math.abs(normaliseDegrees(d.hingeDeg - cand.hingeDeg)) <= AMBIGUITY_HINGE_DEG &&
+            Math.abs(Math.log(d.stretch / cand.stretch)) <= Math.log(1.03),
+        );
+        if (!same) distinct.push(cand);
+      }
+
+      put(distinct[0]);
+      for (const state of boneTargets) {
+        state.role = 'chain';
+        state.link = { hingeDeg: distinct[0].hingeDeg, stretch: distinct[0].stretch };
+        state.relocated = relocated;
+        state.alternates =
+          state.plate === null
+            ? []
+            : distinct.slice(1, 1 + MAX_ALTERNATES).map((cand) => ({
+                place: partPlaceOf(
+                  childPlace(parentPlace, bone, cand.hingeDeg, cand.stretch),
+                  state.drawn.geometry,
+                  (state.plate as Plate).width,
+                ),
+                link: { hingeDeg: cand.hingeDeg, stretch: cand.stretch },
+              }));
+      }
+    }
+
+    // Anchored parts keep the anchor's own placement — nothing here re-fits it.
+    // The LINK is still derived where the parent is placed, because "what local
+    // rotation does this anchor imply" is a number the caller wants and the chain
+    // above it can answer.
+    //
+    // ⬆️ An INWARD part goes through the same block for the same reason: nothing
+    // fitted it either, its placement is wherever the determination put its bone,
+    // and its `hingeDeg` exists only if the bone above it happens to be placed —
+    // which, for a bone the inward step reached, it is not. So the link comes back
+    // `null` and the report says the quantity does not exist rather than printing
+    // a zero.
+    for (const state of states) {
+      if (state.plate === null) continue;
+      const anchor = anchorForBone.get(state.drawn.bone);
+      const determined = inwardBones.has(state.drawn.bone);
+      if (anchor === undefined && !determined) continue;
+      const bonePlace = placedBones.get(state.drawn.bone);
+      const bone = bones.get(state.drawn.bone);
+      state.role = anchor === undefined ? 'inward' : 'anchor';
+      state.isAnchorSource = anchor !== undefined && anchor.state === state;
+      state.place = state.isAnchorSource && anchor !== undefined ? anchor.entry.place : placeOf(state);
+      const parentPlace =
+        bone === undefined || bone.parent === undefined ? undefined : placedBones.get(bone.parent);
+      state.link =
+        bone !== undefined && bonePlace !== undefined && parentPlace !== undefined
+          ? linkOf(parentPlace, bonePlace, bone)
+          : null;
+    }
+  }
+
+  // What each part shows WHERE IT LANDED, as opposed to where its visible set was
+  // frozen. One reverse-draw-order sweep over the fitted placements, and it does
+  // double duty: it is `visibleShareAtFit` for a fitted part, and it IS the frozen
+  // set for a part nothing searched — an anchor's placement is its own seed, so
+  // "frozen at the seed" and "measured where it landed" are the same set there.
+  const shareAtFit = new Map<string, number>();
+  {
+    const cover = new Uint8Array(frame.width * frame.height);
+    for (let i = states.length - 1; i >= 0; i--) {
+      const state = states[i];
+      if (state.plate === null || state.place === null) continue;
+      const set = visibleMask(state.plate, state.place, cover, frame.width, frame.height);
+      shareAtFit.set(state.drawn.slot, set.total > 0 ? set.weight / set.total : 0);
+      if (state.frozen === null) state.frozen = set;
+      stampCover(cover, frame.width, frame.height, state.plate, state.place);
+    }
+  }
+
+  // --- the report ----------------------------------------------------------
+  const report: ChainFitReport = {
+    spec: CHAINFIT_SPEC,
+    space:
+      'frame pixels, y down, origin top-left. (x, y) is where the part image\'s own centre lands; rotationDeg is ' +
+      'screen degrees, positive clockwise; scale is frame pixels per part pixel. Reconstruct a part pixel p as ' +
+      'centre + scale * R(rotationDeg) * (p - (width/2, height/2)) — the same contract a rigc-pose report ' +
+      'carries. hingeDeg and localRotationDeg are SPINE degrees (CCW, y up) instead, because they are timeline ' +
+      'values: what a rotate key would carry. src/transform.ts converts between the two (screenToSpineDegrees, ' +
+      'cropToSpineY).',
+    candidate: {
+      skeleton: skeletonPath,
+      skins: skel.skins.map((s) => s.name),
+      bones: skel.bones.length,
+      slots: skel.slots.length,
+      drawn: drawn.length,
+      drawOrder: drawn.map((d) => d.slot),
+    },
+    images: imagesDir,
+    frame: { path: framePath, width: frame.width, height: frame.height, background },
+    anchor: {
+      source: anchorSource,
+      path: options.anchorPath === undefined ? null : resolve(options.anchorPath),
+      criterion: { ...criterion, requireUnambiguous: true },
+      anchored: [...anchorForBone.values()].map((a) => basename(a.state.path)).sort(),
+    },
+    inward: {
+      determined: boneOrder.filter((name) => inwardBones.has(name)),
+      criterion: {
+        minDeterminants: INWARD_MIN_DETERMINANTS,
+        minLeverPx,
+        determinantsMustBeAnchored: true,
+      },
+    },
+    search: {
+      hinge: { minDeg: hingeMin, maxDeg: hingeMax, stepDeg: hingeStep, steps: hinges.length },
+      stretch: {
+        ratio: stretchRatio,
+        steps: STRETCH_STEPS,
+        freeFrom: stretchEverywhere
+          ? 'every bone, because --stretch was named'
+          : "the candidate's own bone `scale` timelines",
+      },
+      minVisible,
+      maxResidual,
+      ambiguity: { absolute: AMBIGUITY_ABSOLUTE, relative: AMBIGUITY_RELATIVE, hingeDeg: AMBIGUITY_HINGE_DEG },
+      passes,
+      occluderAlpha: OCCLUDER_ALPHA,
+    },
+    caveats: [
+      'No number here is a score and none of them has a pass bar. This reads a given condition — the pose you ' +
+        'were handed — into spec coordinates an agent then states by construction. The residual and ' +
+        '`visibleShare` say how far to trust a placement and where two answers are equally good.',
+      'Every residual is over the part\'s VISIBLE pixels: what nothing drawn after it in the candidate\'s own ' +
+        'setup draw order covered. That is the whole difference from `rigc pose`, whose residuals are charged for ' +
+        'the occluder — so the two are NOT the same number on an occluded part, and this one always has to be read ' +
+        'next to `visibleShare`. A low residual on a 0.08 share is a confident statement about a sliver.',
+      'The occlusion is the CANDIDATE\'s, not the picture\'s, and so is the geometry. A wrong draw order masks the ' +
+        'wrong pixels, and a joint offset the rig gets wrong moves the pivot every hinge below it turns about — an ' +
+        'answer here is only as good as the structure it was read through. `pivotDisagreementPx` on an anchored ' +
+        'bone is the one direct measurement of that: how far the rig\'s own prediction of the joint sits from ' +
+        'where the anchor found it.',
+      'Setup draw order, on one frame. A `drawOrder` timeline reorders the slots at runtime and this cannot know ' +
+        'the time, so a candidate that has one is masked in the order its setup pose declares.',
+      'The hinge is searched; the pivot is NOT. A bone the candidate keys a `translate` timeline on carries ' +
+        '`dof.pivotFree`, which means the arc this answer sits on has a centre the rig itself moves — the ' +
+        'placement is still read off pixels, but `localRotationDeg` alone will not reproduce it.',
+      'The walk goes OUTWARD from a trunk, so a limb with no trusted part on it or above it is refused rather ' +
+        'than guessed at. An anchor fixes its own bone completely; it says nothing about what the link above it ' +
+        'did, so nothing above a SINGLE anchor is recoverable from it — that is `no-anchor` and `no-bracket`.',
+      'The INWARD step is the one exception and it is one shape: a bone with two or more ANCHORED descendants on ' +
+        "different sub-chains. A descendant's pivot depends on this bone and on the rig's own offsets and NOT on " +
+        'the descendant\'s own hinge, so each one supplies two of the four numbers a placement is. Which means it ' +
+        'reaches exactly the bones that BRANCH: a bone with one child sub-chain is `no-bracket` however good the ' +
+        'anchor below it is. `inward.determined` names what it reached.',
+      'An `inward` placement is NOT a measurement of the bone it places. Its evidence is the anchors below it, so ' +
+        'what prices it is `bone.inward.disagreementPx` read next to `bone.inward.redundancy` — and at redundancy ' +
+        '0 the disagreement is `null`, because two determinants and four unknowns fit each other exactly whether ' +
+        'or not the rig is right. The bone\'s own `residual` and `visibleShare` say how much of the answer the ' +
+        'frame can independently confirm, which on a bone drawn behind its own limbs can be very little.',
+      'An `ambiguous` part has two or more hinge answers this instrument cannot separate — a limb that explains ' +
+        'the picture forwards and again backwards. All of them are reported and none was picked.',
+      'A part refused `occluded` is refused because too little of it survives the parts in front of it, and the ' +
+        'best placement found is still in `placement`: the chain put it there and the pixels did not confirm it. ' +
+        'A refusal names why not to trust a number; it does not hide it.',
+      'An ANCHOR can be refused too, and it is not a contradiction: the anchor pass judged the placement over ' +
+        "the part's WHOLE footprint — all `pose` can see, and blind to what covers it — while this instrument has " +
+        'measured how much of the part is visible at all. A refused anchor means the placement may well be right ' +
+        'and the CONFIRMATION is missing, and every part whose `anchoredTo` names that bone rests on it. ' +
+        '`anchorVerdict` carries the pass\'s own numbers so the two readings can be compared rather than merged.',
+    ],
+    parts: [],
+  };
+
+  if (undrawn.length > 0) {
+    report.caveats.push(
+      `${undrawn.length} slot(s) hold no region this run could resolve in the setup pose, so they were neither ` +
+        `placed nor treated as occluders: ${undrawn.join(', ')}.`,
+    );
+  }
+  for (const { slot, why } of blockedSlots) {
+    report.caveats.push(`slot "${slot}" was neither placed nor treated as an occluder: ${why}.`);
+  }
+  const unplacedOccluders = states.filter((s) => s.plate === null || s.place === null).map((s) => s.drawn.slot);
+  if (unplacedOccluders.length > 0) {
+    report.caveats.push(
+      `${unplacedOccluders.length} drawn slot(s) could not be placed, so they masked nothing and every part ` +
+        `behind them is reported MORE visible than the picture shows: ${unplacedOccluders.join(', ')}.`,
+    );
+  }
+  if (Object.values(skel.animations ?? {}).some((a) => Array.isArray(a.drawOrder) && a.drawOrder.length > 0)) {
+    report.caveats.push(
+      'the candidate carries a `drawOrder` timeline, so the order the masks were built in is its setup order and ' +
+        'not necessarily the order this frame was drawn in.',
+    );
+  }
+  if (skel.constraints !== undefined && skel.constraints.length > 0) {
+    report.caveats.push(
+      `the candidate declares ${skel.constraints.length} constraint(s) (${skel.constraints
+        .map((c) => `${c.name}:${c.type}`)
+        .join(', ')}). A constraint moves bones after their local transforms are composed, so a fitted ` +
+        '`localRotationDeg` here is a placement, not necessarily a value you can key and reproduce.',
+    );
+  }
+
+  if (report.inward.determined.length > 0) {
+    report.caveats.push(
+      `${report.inward.determined.length} bone(s) were determined INWARD rather than read or fitted ` +
+        `(${report.inward.determined.join(', ')}), and every placement whose \`anchoredToRole\` is "inward" hangs ` +
+        'off one of them. The determinants are anchor-pass-eligible bones, so the caveat about a refused anchor ' +
+        'applies to them too — a determinant this instrument can barely see is still a determinant.',
+    );
+  }
+
+  const ctx: FinishContext = {
+    bones,
+    keyed,
+    placedBones,
+    depthOf,
+    anchoredTo,
+    carried,
+    pivotDisagreement,
+    targetsOfBone,
+    anchorForBone,
+    anchors,
+    inwardBones,
+    inwardAttempt,
+    shareAtFit,
+    level,
+    material: material.plate,
+    hinge: { minDeg: hingeMin, maxDeg: hingeMax, stepDeg: hingeStep },
+    stretchRatio,
+    stretchEverywhere,
+    minVisible,
+    maxResidual,
+  };
+  for (const state of states) report.parts.push(finishPart(state, ctx));
+  return report;
+}
+
+interface FinishContext {
+  bones: Map<string, SpineBone>;
+  keyed: Map<string, Set<string>>;
+  placedBones: Map<string, BonePlace>;
+  depthOf: Map<string, number>;
+  anchoredTo: Map<string, string>;
+  carried: Map<string, string[]>;
+  pivotDisagreement: Map<string, number>;
+  targetsOfBone: Map<string, PartState[]>;
+  anchorForBone: Map<string, { state: PartState; entry: AnchorEntry }>;
+  anchors: Map<string, AnchorEntry>;
+  inwardBones: Map<string, ChainFitInwardView>;
+  inwardAttempt: Map<string, string>;
+  shareAtFit: Map<string, number>;
+  level: Level;
+  material: Plate;
+  hinge: { minDeg: number; maxDeg: number; stepDeg: number };
+  stretchRatio: number;
+  stretchEverywhere: boolean;
+  minVisible: number;
+  maxResidual: number;
+}
+
+function finishPart(state: PartState, ctx: FinishContext): ChainFitPart {
+  const name = basename(state.path);
+  const bone = ctx.bones.get(state.drawn.bone);
+  const anchored = ctx.anchorForBone.has(state.drawn.bone);
+  const determined = ctx.inwardBones.get(state.drawn.bone) ?? null;
+  const stretchFree = ctx.stretchEverywhere || (ctx.keyed.get(state.drawn.bone)?.has('scale') ?? false);
+  const trunk = ctx.anchoredTo.get(state.drawn.bone) ?? null;
+  const view: ChainFitBoneView = {
+    name: state.drawn.bone,
+    parent: bone?.parent ?? null,
+    setupRotationDeg: num(bone?.rotation, 0),
+    depth: ctx.depthOf.get(state.drawn.bone) ?? -1,
+    anchoredTo: trunk,
+    anchoredToRole: trunk === null ? null : ctx.inwardBones.has(trunk) ? 'inward' : 'anchor',
+    inward: determined,
+    dof: {
+      // Neither an anchor nor a determination searched anything, so neither
+      // reports a searched degree of freedom. `dof` is what was SEARCHED, not
+      // what the rig leaves free.
+      rotation: !anchored && determined === null,
+      stretch: stretchFree && !anchored && determined === null,
+      pivotFree: ctx.keyed.get(state.drawn.bone)?.has('translate') ?? false,
+    },
+    window: {
+      hingeMinDeg: ctx.hinge.minDeg,
+      hingeMaxDeg: ctx.hinge.maxDeg,
+      hingeStepDeg: ctx.hinge.stepDeg,
+      stretchMin: stretchFree ? roundTo(1 / ctx.stretchRatio, 5) : 1,
+      stretchMax: stretchFree ? ctx.stretchRatio : 1,
+    },
+    sharedWith: (ctx.targetsOfBone.get(state.drawn.bone) ?? [])
+      .filter((s) => s !== state)
+      .map((s) => basename(s.path))
+      .sort(),
+    carriedBones: ctx.carried.get(state.drawn.bone) ?? [],
+    pivotDisagreementPx: ctx.pivotDisagreement.has(state.drawn.bone)
+      ? roundTo(ctx.pivotDisagreement.get(state.drawn.bone) as number, 3)
+      : null,
+  };
+  const out: ChainFitPart = {
+    part: name,
+    path: state.path,
+    slot: state.drawn.slot,
+    attachment: state.drawn.attachment,
+    width: state.plate?.width ?? 0,
+    height: state.plate?.height ?? 0,
+    role: state.role,
+    bone: view,
+    refusal: state.blocked,
+    placement: null,
+    alternates: [],
+    ambiguous: false,
+    anchorVerdict: ctx.anchors.get(name)?.verdict ?? null,
+    notes: [],
+  };
+  if (state.blocked !== null) {
+    out.notes.push(`${name} was not searched: ${state.blocked.detail}.`);
+    return out;
+  }
+  const plate = state.plate as Plate;
+  const frozen = state.frozen;
+  if (state.place === null || frozen === null || !ctx.placedBones.has(state.drawn.bone)) {
+    out.role = 'unplaced';
+    // ⭐ Two refusals, and which one it is says where the repair lives. The inward
+    // step recorded an attempt exactly when it found something anchored below this
+    // bone and could not use it — so an attempt present means "there WAS evidence
+    // down there", and a caller reads a different sentence and takes a different
+    // action than the one who has nothing anywhere on the limb.
+    const attempt = ctx.inwardAttempt.get(state.drawn.bone);
+    if (attempt !== undefined) {
+      out.refusal = { reason: 'no-bracket', detail: `${name}: ${attempt}` };
+      out.notes.push(
+        `${name} was not placed, and not for want of an anchor: something below it WAS trusted. Two anchored ` +
+          'descendants on different sub-chains would determine this bone outright — so the repair is either one ' +
+          'more anchor on a sub-chain that has none, or a rig whose topology branches here at all. A single ' +
+          'anchored descendant, however good, carries nothing about the link above it.',
+      );
+      return out;
+    }
+    out.refusal = {
+      reason: 'no-anchor',
+      detail:
+        `${name} hangs off bone "${state.drawn.bone}", which has no placed ancestor and no anchored descendant: ` +
+        'no part on it, above it or below it came back from the anchor pass inside the anchor criterion, so there ' +
+        'was nothing to walk a chain from and nothing to determine it inward from either',
+    };
+    out.notes.push(
+      `${name} was not placed. A chain needs a trunk — supply --anchor with a report that reads at least one part ` +
+        'of this limb or above it, or loosen --anchor-residual. Nothing above a single anchor is recoverable from ' +
+        'it, so one trusted part further out does not help this one; TWO of them on different sub-chains below ' +
+        'this bone would, and that is the inward step.',
+    );
+    return out;
+  }
+
+  const stats = measure(plate, state.place, frozen, ctx.level, ctx.material);
+  const atFit = ctx.shareAtFit.get(state.drawn.slot) ?? stats.visibleShare;
+  const placement = toPlacement(state.place, state.link, view.setupRotationDeg, stats, atFit);
+  out.placement = placement;
+
+  const margin = Math.max(AMBIGUITY_ABSOLUTE, placement.residual * AMBIGUITY_RELATIVE);
+  out.alternates = state.alternates
+    .map((alt) =>
+      toPlacement(alt.place, alt.link, view.setupRotationDeg, measure(plate, alt.place, frozen, ctx.level, ctx.material), atFit),
+    )
+    .filter((alt) => alt.residual - placement.residual <= margin)
+    .slice(0, MAX_ALTERNATES);
+  out.ambiguous = out.alternates.length > 0;
+  if (out.ambiguous) {
+    out.notes.push(
+      `${name} has ${out.alternates.length + 1} hinge answers within ${roundTo(margin, 4)} residual of each other ` +
+        '— all of them are reported and none was picked. A limb that explains the picture forwards and again ' +
+        'backwards looks exactly like this.',
+    );
+  }
+
+  if (out.role === 'anchor') {
+    out.notes.push(
+      `${name} is an ANCHOR: this placement is the anchor pass's own answer, taken because it cleared the anchor ` +
+        'criterion, and nothing here re-fitted it. Its residual and visible share are this instrument\'s, measured ' +
+        'over the masked pixels.',
+    );
+    if (view.pivotDisagreementPx !== null && view.pivotDisagreementPx > 2) {
+      out.notes.push(
+        `the chain above it predicts this bone's pivot ${view.pivotDisagreementPx} px from where the anchor put ` +
+          "it — the candidate's own joint offset and the picture disagree by that much.",
+      );
+    }
+  } else if (out.role === 'inward' && view.inward !== null) {
+    const inward = view.inward;
+    out.notes.push(
+      `${name} is on a bone this run determined INWARD: nothing searched it and the anchor pass never saw it. ` +
+        `Its four numbers come from ${inward.determinants.length} anchored descendant(s) — ` +
+        `${inward.determinants.map((d) => `${d.bone} (${d.part})`).join(', ')} — read across a ` +
+        `${inward.leverPx} px lever, with ${inward.redundancy} surplus equation(s).`,
+    );
+    out.notes.push(
+      inward.disagreementPx === null
+        ? `redundancy 0, so \`disagreementPx\` is null rather than zero: ${inward.determinants.length} determinants ` +
+          'supply exactly the four numbers a placement is, and a solve with nothing left over fits its own points ' +
+          'exactly whether or not the rig is right. One more anchored descendant on a third sub-chain is what ' +
+          'would make this checkable.'
+        : `the determination disagrees with itself by ${inward.disagreementPx} px at worst ` +
+          `(${inward.determinants.map((d) => `${d.bone} ${d.offsetPx}`).join(', ')} px): over ` +
+          `${inward.redundancy} surplus equation(s), that is the rig's own joint offsets and the anchors below ` +
+          'this bone disagreeing by that much. It is a rig diagnostic in the same sense as ' +
+          '`pivotDisagreementPx`, not an error bar on the placement.',
+    );
+    for (const d of inward.determinants) {
+      if (d.carried.length === 0) continue;
+      out.notes.push(
+        `the path to determinant "${d.bone}" runs through ${d.carried.join(', ')}, which carry nothing scoreable — ` +
+          'their setup rotation was composed through, and this determination inherits that assumption.',
+      );
+    }
+    for (const r of inward.rejected) {
+      out.notes.push(`anchored descendant "${r.bone}" was not usable as a determinant: ${r.why}.`);
+    }
+    if (placement.hingeDeg === null) {
+      out.notes.push(
+        `"${view.name}" has no placed parent — that is why the inward step had to determine it — so \`hingeDeg\` ` +
+          'and `localRotationDeg` are null: there is no link above it to measure a local rotation against. The ' +
+          'placement is a world one, and `src/transform.ts` converts it.',
+      );
+    }
+  } else {
+    const dof = view.dof.stretch ? 'a hinge and a stretch' : 'one hinge';
+    out.notes.push(
+      `${name} was read by walking ${view.depth} link(s) out from ${view.anchoredTo ?? 'an anchor'} and searching ` +
+        `${dof} over ${ctx.hinge.minDeg}°…${ctx.hinge.maxDeg}° ${hingeWalkPhrase(ctx.hinge.stepDeg)} — not the four degrees of ` +
+        'freedom `pose` has to search.',
+    );
+  }
+  if (view.anchoredToRole === 'inward' && out.role !== 'inward') {
+    const trunk = view.anchoredTo === null ? null : ctx.inwardBones.get(view.anchoredTo);
+    out.notes.push(
+      `⚠️ the trunk this hangs off — "${view.anchoredTo}" — was DETERMINED inward from ` +
+        `${trunk?.determinants.length ?? 0} anchored descendant(s), not read off the picture` +
+        (trunk?.disagreementPx === null
+          ? ' with no surplus equation to check it against'
+          : ` (worst self-disagreement ${trunk?.disagreementPx} px)`) +
+        '. Every number here rests on that determination.',
+    );
+  }
+  if (state.relocated) {
+    out.notes.push(
+      `the rig predicted ${name} almost entirely covered, so its visible set was frozen at an UNMASKED look ` +
+        "instead — `pose`'s own question restricted to this arc — and the masked search ran from there. The share " +
+        'below is what that relocation left scoreable.',
+    );
+  }
+  if (view.carriedBones.length > 0) {
+    out.notes.push(
+      `${view.carriedBones.join(', ')} carry nothing scoreable, so their hinge could not be fitted and their setup ` +
+        'rotation was carried through. Every number here inherits that assumption.',
+    );
+  }
+  if (view.dof.pivotFree) {
+    out.notes.push(
+      `the candidate keys a \`translate\` timeline on "${view.name}", so the pivot this hinge turned about is ` +
+        'itself something the rig moves; `localRotationDeg` alone will not reproduce this placement.',
+    );
+  }
+
+  if (placement.visibleShare < ctx.minVisible) {
+    // ⚠️ An ANCHOR gets this refusal too, and the wording carries why rather than
+    // leaving a reader to reconcile two rows. The two criteria disagree on
+    // purpose: the anchor pass judged this placement over the part's WHOLE
+    // footprint, which is all `pose` can see and which does not know what covers
+    // it, and this instrument has just measured that almost nothing of the part is
+    // visible. Both are true. Suppressing the refusal because "no search happened
+    // here" was tried and is worse — measured on the 2026-09-03 corpus it printed
+    // `rear-bracer` as READ on 82 of 147 frames at a median visible share of 0.1%,
+    // which is the number this floor exists to stop anybody quoting.
+    out.refusal = {
+      reason: 'occluded',
+      detail:
+        `${name}: only ${(placement.visibleShare * 100).toFixed(1)}% of it survives the parts drawn over it, ` +
+        `below the visibility floor ${ctx.minVisible}; the residual ${placement.residual.toFixed(4)} is a ` +
+        `statement about ${placement.scoredPixels} part pixel(s)` +
+        (state.isAnchorSource
+          ? ` — and it is an ANCHOR, accepted by the anchor pass on its own criterion (residual ` +
+            `${(out.anchorVerdict?.residual ?? 0).toFixed(4)}, unexplained ` +
+            `${((out.anchorVerdict?.unexplained ?? 0) * 100).toFixed(0)}% over the part's WHOLE footprint, which ` +
+            'cannot know what covers it), so every placement hung off it inherits this doubt'
+          : out.role === 'inward'
+            ? ` — and it is an INWARD determination, so the residual is not what the placement rests on ` +
+              `(that is ${view.inward?.determinants.length ?? 0} anchored descendant(s) across a ` +
+              `${view.inward?.leverPx ?? 0} px lever). What this floor refuses is the CONFIRMATION: the frame ` +
+              'cannot check the answer either way'
+            : ''),
+    };
+    out.notes.push(
+      state.isAnchorSource
+        ? `${name} anchors this chain and this instrument can barely see it. The placement is the anchor pass's ` +
+          'and may well be right; what is refused is the confirmation, and everything with ' +
+          `\`anchoredTo\` = "${view.name}" rests on it.`
+        : out.role === 'inward'
+          ? // ⚠️ The floor is kept here deliberately, and this is the second time
+            // that call has been made in this file: exempting a placement nothing
+            // searched was tried for anchors in `2ff80af` and reverted in
+            // `0ff25ea` because it prints a part nobody can see as READ. An inward
+            // determination has a better provenance than an anchor's sliver and
+            // the floor still applies, because the floor is about what the PICTURE
+            // can confirm, not about how the number was obtained — and a count of
+            // "readable" that includes bones the frame cannot check is exactly the
+            // figure this floor exists to keep out of a table.
+            `${name} sits on a bone that was determined inward, and this frame cannot confirm it: the geometry ` +
+            'says where it goes and the pixels are not there to agree or disagree. The determination is in ' +
+            '`bone.inward` and the placement is still in `placement`; what is refused is the confirmation.'
+          : `${name} is too far behind other parts to measure on this frame. The best placement found is still in ` +
+            '`placement`.',
+    );
+  } else if (placement.residual > ctx.maxResidual) {
+    out.refusal = {
+      reason: 'no-match',
+      detail:
+        `${name}: the best placement found has residual ${placement.residual.toFixed(4)} over its visible pixels, ` +
+        `above --max-residual ${ctx.maxResidual}`,
+    };
+    out.notes.push(
+      out.role === 'inward'
+        ? // No window was searched here, so the usual advice about it would be
+          // wrong: this is the determination and the picture disagreeing, and the
+          // determination is the thing to look at.
+          `${name} was DETERMINED inward and its visible pixels do not agree with the frame where the ` +
+          'determination put it. That is a real disagreement between the anchors below this bone and the ' +
+          "candidate's own joint offsets — read `bone.inward.disagreementPx` and the determinants' own " +
+          '`anchorVerdict`s before believing either side.'
+        : `${name}'s visible pixels do not agree with the frame at any hinge in the window. Check the window, the ` +
+          "candidate's joint offset for this limb, and its draw order.",
+    );
+  }
+  if (Math.abs(placement.visibleShareAtFit - placement.visibleShare) > VISIBILITY_DRIFT_TOLERANCE) {
+    out.notes.push(
+      `the visible set was frozen where ${(placement.visibleShare * 100).toFixed(1)}% of ${name} showed and the ` +
+        `answer landed where ${(placement.visibleShareAtFit * 100).toFixed(1)}% does — the measurement and the ` +
+        'answer are not quite in the same place. Another --passes is the repair.',
+    );
+  }
+  if (placement.offCanvas > 0.01) {
+    out.notes.push(
+      `${roundTo(placement.offCanvas * 100, 1)}% of ${name}'s material falls outside the frame canvas at this placement.`,
+    );
+  }
+  return out;
+}
+
+/** A part PNG, or the reason it is not one. */
+function loadPart(path: string, cache: Map<string, Plate | null>): Plate | string {
+  if (cache.has(path)) {
+    const held = cache.get(path) ?? null;
+    return held === null ? `cannot read ${path}` : held;
+  }
+  if (!existsSync(path)) {
+    cache.set(path, null);
+    return `${path} is not there — --images must hold one PNG per attachment image name the candidate uses`;
+  }
+  try {
+    const plate = readPlate(path);
+    cache.set(path, plate);
+    return plate;
+  } catch (err) {
+    cache.set(path, null);
+    return `cannot decode ${path}: ${(err as Error).message}`;
+  }
+}
+
+function hasMaterial(plate: Plate): boolean {
+  for (let i = 3; i < plate.data.length; i += 4) if (plate.data[i] !== 0) return true;
+  return false;
+}
+
+/** A directory or a `skeleton.json` path, the way every other command takes a candidate. */
+function resolveSkeletonPath(target: string): string {
+  const abs = resolve(target);
+  if (!existsSync(abs)) throw new ChainFitError(`nothing at ${abs}`);
+  if (statSync(abs).isDirectory()) return join(abs, 'skeleton.json');
+  if (!abs.endsWith('.json')) throw new ChainFitError(`${abs} is neither a directory nor a .json skeleton`);
+  return abs;
+}
+
+// ---------------------------------------------------------------------------
+// the console report
+// ---------------------------------------------------------------------------
+
+function placementLine(p: ChainFitPlacement): string {
+  return (
+    `x=${p.x.toFixed(1).padStart(7)}  y=${p.y.toFixed(1).padStart(7)}  rot=${p.rotationDeg.toFixed(1).padStart(7)}°  ` +
+    `scale=${p.scale.toFixed(3)}  residual=${p.residual.toFixed(4)}  visible=${(p.visibleShare * 100).toFixed(0).padStart(3)}%`
+  );
+}
+
+export function chainFitLines(report: ChainFitReport): string[] {
+  const bg = report.frame.background;
+  const bgText =
+    bg.kind === 'colour' && bg.colour !== null
+      ? `rgb(${bg.colour.join(', ')}) over ${(bg.borderShare * 100).toFixed(0)}% of the border ring`
+      : bg.kind === 'transparent'
+        ? `transparency over ${(bg.borderShare * 100).toFixed(0)}% of the border ring`
+        : 'UNKNOWN — the border ring has no dominant colour, so every pixel counts as material and the silhouette ' +
+          'signal is gone; residuals here are colour agreement only';
+  const lines = [
+    `  ..    frame     ${report.frame.path}  (${report.frame.width}x${report.frame.height})`,
+    `  ..    ground    ${bgText}`,
+    `  ..    candidate ${report.candidate.skeleton}  (${report.candidate.bones} bones, ` +
+      `${report.candidate.drawn} of ${report.candidate.slots} slots drawn)`,
+    `  ..    parts     ${report.images}`,
+    `  ..    anchor    ${report.anchor.source === 'pose' ? 'an internal `rigc pose` pass' : (report.anchor.path ?? '')} · ` +
+      `${report.anchor.anchored.length} trusted (residual ≤ ${report.anchor.criterion.maxResidual}, ` +
+      `unexplained ≤ ${report.anchor.criterion.maxUnexplained}, unambiguous)`,
+    `  ..    inward    ${
+      report.inward.determined.length === 0
+        ? `nothing determined (needs ${report.inward.criterion.minDeterminants} anchored descendants on ` +
+          `different sub-chains, ≥ ${report.inward.criterion.minLeverPx} px apart)`
+        : `${report.inward.determined.length} bone(s) determined from anchored descendants: ` +
+          report.inward.determined.join(', ')
+    }`,
+    `  ..    search    ${searchHingeClause(report.search.hinge)} · stretch free from ` +
+      `${report.search.stretch.freeFrom} · refuse below visible ${report.search.minVisible} or above residual ` +
+      `${report.search.maxResidual} · ${report.search.passes} pass(es)`,
+  ];
+  const width = Math.max(8, ...report.parts.map((p) => p.part.length));
+  for (const part of report.parts) {
+    const label = part.part.padEnd(width);
+    const pad = ' '.repeat(width);
+    if (part.placement === null) {
+      lines.push(`  REFUSE ${label}  ${part.refusal?.reason ?? 'unplaced'}: ${part.refusal?.detail ?? ''}`);
+      continue;
+    }
+    const tag =
+      part.refusal !== null
+        ? 'REFUSE'
+        : part.ambiguous
+          ? 'AMBIG '
+          : part.role === 'anchor'
+            ? 'ANCHOR'
+            : part.role === 'inward'
+              ? 'INWARD'
+              : 'CHAIN ';
+    lines.push(`  ${tag} ${label}  ${placementLine(part.placement)}`);
+    if (part.bone.inward !== null) {
+      const inward = part.bone.inward;
+      lines.push(
+        `         ${pad}  bone ${part.bone.name} · DETERMINED from ${inward.determinants
+          .map((d) => `${d.bone}@${d.leverPx}px`)
+          .join(' + ')} · lever ${inward.leverPx} px · redundancy ${inward.redundancy} · disagreement ` +
+          `${inward.disagreementPx === null ? 'n/a at redundancy 0' : `${inward.disagreementPx} px`}`,
+      );
+      for (const r of inward.rejected) lines.push(`         ${pad}  unusable determinant ${r.bone}: ${r.why}`);
+    } else if (part.bone.anchoredToRole === 'inward') {
+      lines.push(`         ${pad}  hangs off "${part.bone.anchoredTo}", which was determined inward`);
+    }
+    if (part.role === 'chain') {
+      const hinge = part.placement.hingeDeg === null ? '—' : `${part.placement.hingeDeg.toFixed(2)}°`;
+      const local = part.placement.localRotationDeg === null ? '—' : `${part.placement.localRotationDeg.toFixed(2)}°`;
+      lines.push(
+        `         ${pad}  bone ${part.bone.name} · depth ${part.bone.depth} from ${part.bone.anchoredTo ?? '?'} · ` +
+          `hinge ${hinge} (local ${local} Spine)` +
+          (part.bone.dof.stretch && part.placement.stretch !== null ? ` · stretch ${part.placement.stretch.toFixed(3)}` : '') +
+          ` · ${part.placement.scoredPixels} px scored`,
+      );
+    }
+    if (part.bone.carriedBones.length > 0) {
+      lines.push(`         ${pad}  carried through un-fitted: ${part.bone.carriedBones.join(', ')}`);
+    }
+    part.alternates.forEach((alt, i) => {
+      const hinge = alt.hingeDeg === null ? '—' : `${alt.hingeDeg.toFixed(2)}°`;
+      lines.push(`         ${pad}  alt ${i + 2}: ${placementLine(alt)}  hinge ${hinge}`);
+    });
+    if (part.refusal !== null) lines.push(`         ${pad}  ${part.refusal.reason}: ${part.refusal.detail}`);
+  }
+  const read = report.parts.filter((p) => p.refusal === null).length;
+  const bought = report.parts.filter(
+    (p) => p.refusal === null && p.role === 'chain' && p.anchorVerdict?.eligible === false,
+  ).length;
+  const onInward = report.parts.filter(
+    (p) => p.refusal === null && (p.role === 'inward' || p.bone.anchoredToRole === 'inward'),
+  ).length;
+  lines.push('');
+  lines.push(
+    `  ..    ${read} of ${report.parts.length} part(s) read; ${bought} of them the anchor pass refused and the chain bought` +
+      (report.inward.determined.length === 0 ? '.' : `; ${onInward} of them rest on an inward determination.`),
+  );
+  lines.push('  ..    residuals are over VISIBLE pixels and are a trust signal, not a score — nothing here has a');
+  lines.push('  ..    pass bar. Read every one next to its `visible` share, and remember the occlusion is the');
+  lines.push("  ..    candidate's own: a wrong draw order masks the wrong pixels.");
+  return lines;
+}