rig-parts 1.66.0 → 1.67.0

package/README.md

@@ -287,7 +287,7 @@ rig-parts assemble --source painting.png --full layers/full --head layers/head -
 #    -> a large red hole neither run holds? add an assemble.patches entry (cut from the painting) and assemble again
 rig-parts propose --parts work/rig --source painting.png --out work
 #    -> proposal.json, basis.json (what each bone rests on) and render/landmarks.png; per-bone coverage lines;
-#       correct it, copy bones/meshes/regions/limbs/motion/constraints/turn/proposed_rig_scale into config.json, each it wrote
+#       correct it, copy bones/meshes/regions/limbs/motion/constraints/turn/motion_seams/proposed_rig_scale into config.json, each it wrote
 #       (limbs only with --keypoints, constraints only with --cloth, turn only with --full/--head;
 #       a limbs block left out is refused next)
 rig-parts propose --parts work/rig --source painting.png --out work --from-config config.json

package/docs/AUTHORING.md

@@ -140,6 +140,7 @@ read by no CPU stage).
 | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
 | `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `meshes.<part>` and `regions.<part>`, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — and every other byte as read; `--from <previous config>` (issue #571) takes an entry equal to the previous recipe's draft as the recipe's (*The config written*, under the recipe below) |
 | `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
+| `motion_seams` | propose, assemble, check | Optional `[{part, neighbour}]`, using output part names. Each unordered pair is declared once; self-pairs, unknown names, wrong shapes and unknown fields refuse (`CONFIG_MOTION_SEAM`, `PARTS_MOTION_SEAM`, `CHECK_MOTION_SEAM_DECLARATION`). Empty adds no pair. Assemble copies the declaration into `parts.json`; check merges it with existing pairs and never regenerates a removed declaration. It uses the existing non-root WARN floor and changes no bar or exit status. See *Explicit motion seam observations* below. |
 | `requirements` | build (read in place of `--requirements` when the flag is not given), and so its check | **authored**, optional, never proposed (issue #556): a path, relative to the config file's directory, to the `spine-parts-requirements/1` file the build's check reads (§7, *Declared requirements*) — so a rig that needs one (a `not_swinging` part, a `may_fold`) rebuilds from its config alone. `build` reads it before assemble, as it reads the flag's file, and `check.json`'s `requirements.file` records it with `path` as declared. Given beside `--requirements`, the two must name the same file once resolved, or a file of the same bytes, and the declaration is read and recorded (a build given both writes what the config alone writes); otherwise `BUILD_REQUIREMENTS_CONFLICT`, naming both. Not a non-empty string: `CONFIG_FIELD_TYPE`; no such file, where the config is read from a path: `CONFIG_FILE_PRESENT`. `check`, `compose`, `mesh-draft`, `remesh` and `retune` do not read it: their `--requirements` is the only door. Absent, nothing is read and no byte of any output moves |
 
 A skeleton alternate may declare `anchor: {neck: "head"}` (issue #543):
@@ -1280,7 +1281,7 @@ silhouette holds besides the art, each pixel counted once: `filledHolePixels` (t
 holes), `grownPixels` (added by the margin), `pinchFilledPixels` (added by the pinch fill) and
 `grownHolePixels` (transparent pixels the grown silhouette encloses — a notch whose mouth grew
 shut))
-and, per region, the vertices its bone reaches (`g > 0`) and holds alone (`g = 1`).
+and, per region (`regions: [{ name, bone, reached, whole }, ...]`, `src/rig.ts`), the vertices its bone reaches (`reached`, where the region owns a nonzero contribution, `g > 0`) and holds alone (`whole`, where `g >= 1`) — static setup-weight vertex counts, not a rendered frame-to-frame or `> 0.5 px` counterfactual-motion count.
 Across contour, automatic and influence reports, `regions[].bone` and `reach.nearest`
 name the authored template bones used to calculate the regions and reach. Stops and turn
 can rebind the emitted attachment after those calculations; these diagnostic names are
@@ -2108,8 +2109,8 @@ it runs in under a second; the build it saves runs the render and `check` as wel
 roughly as area / spacing², including the transition band: for a circle that area
 extends to `r + band`, not just `r`. The outline, background grid and sampled region
 rings also contribute, so multiplying the *whole* triangle count by that ratio
-incorrectly scales the fixed part. Read the part's `mesh_report.json` row first, and use
-`mesh-stats` for the candidate rather than waiting for a rendered build.
+incorrectly scales the fixed part. Read the part's `mesh_report.json` row first (`regions[].{name, bone, reached, whole}` and `contour` in `rig/mesh_report.json` or `out/rig/mesh_report.json` — see *A contour mesh*, *What it reports*, above, which `mesh-stats` does not print), and use
+`mesh-stats` for the candidate's `{part, mode, vertices, triangles}` dry count rather than waiting for a rendered build.
 
 A bounded calibration on the public [family office config](https://github.com/rig-c/examples/blob/d5a1768ce4a2d1e3f5726d1739cd0da4a63b0e13/family/roa/config.json)
 uses both `topwear` bust regions at spacing 14. Its pinned
@@ -2252,15 +2253,15 @@ the wind — is the consumer's, and the recipe drafts no key and no stimulus.
 ```
 
 (The selftest's fixture recipe, `fixtures/cloth.ts`: values chosen to exercise every
-rule, not advice. It leaves `length_ratio` and `strength` out, so the recipe's own
+rule, not advice — in particular, `"back hair": { "chains": 2, … }` exercises explicit multi-tree splitting and is not a recommendation to declare two trees on a one-mass side. It leaves `length_ratio` and `strength` out, so the recipe's own
 defaults are what is built and measured below.)
 
 What each rule drafts (`src/cloth.ts` holds them):
 
 | rule | drafts | from |
 | --- | --- | --- |
-| where | `bottomwear`: from `hip`, the root row 20 px below hip's y (the keyed chains' row), the tip row 4 px above the cloth's own bottom under each column (4 px above the part box's bottom when every column reaches the bottom band, or 4 px above where the cloth's alpha ends under that column on a floor-spread skirt whose middle hem ends above bare thighs; a column with no cloth below the root row gets no tree drafted there and emits a note saying so, issue #438). `back hair` that reaches below the shoulders: from `head`, per side of the eye axis (twin tails are a side each), the eye line to 4 px above its bottom. `front hair`: each strand that hangs below the chin (the lock rule's), from `head`, 0.22 face heights above the eye line to 5 px below the strand; the fringe's three columns keep their two links and their places | the keyed chains' own rows, which these replace |
-| trees | tree k of `chains` owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. On `back hair`, `chains` is optional (issues #390, #445, #461): when omitted, `propose --cloth` derives the tree count on each side from the side's **visible hair masses** — connected components of the `back hair` part's alpha below the eye-line root row (after skipping any undivided crown rows that bridge continuously across the eye axis), merged when they touch within one mesh grid cell — placing `max(1, floor(w / (4 * grid)) + 1)` trees inside each mass across its root-row opaque width `w` (one tree per `4 * grid` of horizontal reach, where a tree's segment weight `1 / (d + r)^2` with `r ≈ 0.42 * grid` drops to `MIN_WEIGHT = 0.03` at `2 * grid` on each side of the trunk), rooted at that mass's own top row and with every link inside that mass's column range; `propose`'s `LINT` names the masses it found and their columns when a side's tree count or link leaves them. An explicit `chains` that exceeds what the narrower side's opaque width at the eye-line root row holds (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`) or places a root off the 15 px dilated art is refused (`PROPOSE_CLOTH_BACK_HAIR_CHAINS`). With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt`. With `split.hold_tip: true` (issues #403, #392), sibling branches keep `strength.branch` across the fork, the mesh's `r` is raised to `grid`, and the rig stage blends each fork's sibling branch weight shares across four passes of 1-ring mesh-edge averaging (self weight 0.5, floor 0.005, cap 8 influences) — every share alike, trunk, branch and fixed bones, none held in place — holding the triangles where two branches' cells meet; when the recipe also declares `influence`, the drafted influence mesh carries `hold_tip: true` and `max` at least 8, and the rig stage smooths it by the same passes capped at that `max` (issue #615, the `meshes.<part>.influence` row) | `chains`, `links`, `split` |
+| where | `bottomwear`: from `hip`, the root row 20 px below hip's y (the keyed chains' row), the tip row 4 px above the cloth's own bottom under each column (4 px above the part box's bottom when every column reaches the bottom band, or 4 px above where the cloth's alpha ends under that column on a floor-spread skirt whose middle hem ends above bare thighs; a column with no cloth below the root row gets no tree drafted there and emits a note saying so, issue #438). `back hair` that reaches below the shoulders: from `head`, per side of the eye axis (twin tails are a side each), the eye line to 4 px above its bottom. `front hair`: each qualifying strand that hangs below the chin (the lock rule's: each connected component below `chin + 4` of height at least `0.3` face heights, `src/propose.ts`), from `head`, 0.22 face heights above the eye line to 5 px below the strand — the recipe's `chains`, `links` and `split` are applied separately to each qualifying hanging strand and do not replace the fringe's fixed three two-link columns (`bang_r`, `bang_c`, `bang_l` keep their two links and their places and take physics on both links) | the keyed chains' own rows, which these replace |
+| trees | tree k of `chains` (`N`) owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. **Count unit of `chains`:** on `back hair`, an explicit `chains: N` is passed to **each emitted side of the eye axis** (`N` trees on `r` and `N` on `l` when both sides emit, not a combined total across both sides; `src/cloth.ts`, `src/propose.ts`); on `front hair`, `chains: N` is applied **separately to each qualifying hanging strand** and does not replace the fringe's fixed two-link columns (`src/propose.ts`). On `back hair`, `chains` is optional (issues #390, #445, #461): when omitted, `propose --cloth` derives the tree count on each side from the side's **visible hair masses** and root-row reach — it is **not** a universal default of 1 or 2 trees for every painting (`RECIPE_BACK_HAIR_CHAINS = 2` in `src/cloth.ts` is only the fallback when `draftTrees` is called with neither `masses` nor `chains`) — connected components of the `back hair` part's alpha below the eye-line root row (after skipping any undivided crown rows that bridge continuously across the eye axis), merged when they touch within one mesh grid cell — placing `max(1, floor(w / (4 * grid)) + 1)` trees inside each mass across its root-row opaque width `w` (one tree per `4 * grid` of horizontal reach, where a tree's segment weight `1 / (d + r)^2` with `r ≈ 0.42 * grid` drops to `MIN_WEIGHT = 0.03` at `2 * grid` on each side of the trunk), rooted at that mass's own top row and with every link inside that mass's column range; `propose`'s `LINT` names the masses it found and their columns when a side's tree count or link leaves them. An explicit `chains` that exceeds what the narrower side's opaque width at the eye-line root row holds (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`) or places a root off the 15 px dilated art is refused (`PROPOSE_CLOTH_BACK_HAIR_CHAINS`). With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt`. With `split.hold_tip: true` (issues #403, #392), sibling branches keep `strength.branch` across the fork, the mesh's `r` is raised to `grid`, and the rig stage blends each fork's sibling branch weight shares across four passes of 1-ring mesh-edge averaging (self weight 0.5, floor 0.005, cap 8 influences) — every share alike, trunk, branch and fixed bones, none held in place — holding the triangles where two branches' cells meet; when the recipe also declares `influence`, the drafted influence mesh carries `hold_tip: true` and `max` at least 8, and the rig stage smooths it by the same passes capped at that `max` (issue #615, the `meshes.<part>.influence` row) | `chains`, `links`, `split` |
 | lengths | link j's length is the first's times q^j, q = `length_ratio`^(1/(links − 1)), the whole spanning root row to tip row: the links shorten toward the tip | `length_ratio` (default 0.5, below) |
 | stiffness | a trunk link takes `strength.trunk`, a branch link `strength.branch`, and the edge — the outermost branch on each outer side of the piece (both sides of a skirt or a strand; the outer side of each back-hair side; or, under `split.hold_tip: true` with `strength` left out, kept at `strength.branch` so a fork's sibling branches do not pull apart at the default 2:1 stiffness), or without `split` the outermost tree — `strength.edge`; a fringe column is a trunk, its outer two the edge. **Strength does not fall along a chain**: a tip reads soft because each link turns on top of every link above it, so the motion accumulates down the chain at one strength. Only the edge is declared softer | `strength` (default trunk 100, branch 100, edge 50, below) |
 | response | link j of an n-link path takes `wind` and `gravity` at j/(n − 1) of the way from the root value to the tip value; a single-link path takes the tip value. Each is a scalar **multiplier** of the environment the consumer sets (spine-core's skeleton `windX, windY`, `gravityX, gravityY`; rig-c 2.52.0's live track `setEnvironment`, rig-play 1.10.0's `environment()`): no direction is drafted | `wind`, `gravity` |
@@ -2891,7 +2892,7 @@ full loader before its assemble stage writes anything.
    no later stage can see — then
    `rig-parts propose --parts work/rig --source inputs/painting.png --out work --write-config config.json` →
    `work/proposal.json` and `work/render/landmarks.png` (+ `_head`). The flag saves
-   each of `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn` and `proposed_rig_scale` it
+   each of `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `motion_seams` and `proposed_rig_scale` it
    wrote into the config: `limbs` is written only with `--keypoints`, `constraints`
    only with `--cloth` and `turn` only with `--full`/`--head` (`PROPOSAL_CONFIG_SECTIONS` in `src/propose.ts` is the list,
    and the selftest's `TY18` holds this sentence to it). A `limbs` block left out
@@ -3048,7 +3049,7 @@ full loader before its assemble stage writes anything.
 The command-order selftest runs these stages on each fetched example from a
 config holding only `key`, `seethrough` and `assemble.rig_scale` (`RL01`). For
 the proposal step, copy `bones`, `meshes`, `regions`, `limbs`, `motion`,
-`constraints`, `turn` and `proposed_rig_scale` into the config, each section the
+`constraints`, `turn`, `motion_seams` and `proposed_rig_scale` into the config, each section the
 proposal wrote. `RL01` exercises that manual route and does not execute
 `--write-config`. The save forms above write the fields owned by their mode;
 a saved draft still needs validation.
@@ -3071,14 +3072,14 @@ mesh-stats: total 1816 triangles over 9 mesh(es)
 ```
 
 (`demo` as tracked, nine lattices.) The package holds no triangle budget: a budget is the
-consumer's, and the command prints no line against one. One line per mesh, in parts.json's
+consumer's, and the command prints no line against one. `mesh-stats` runs `buildRig` (`src/meshstats.ts`) and projects its `meshReport` via `meshStatsRows` to `{part, mode, vertices, triangles}` and the total (`meshStatsLines`) — one line per mesh, in parts.json's
 order, the row order of `mesh_report.json`; the mode is `lattice` for a `grid` entry,
-`contour`, `auto` or `influence`. An `auto` part's count is its reduction's result: when rigc's
+`contour`, `auto`, `influence` or `explicit`. It writes no `mesh_report.json` or skeleton data and runs no `rigc` or `check`. For per-region vertex counts on a contour mesh (`regions: [{ name, bone, reached, whole }, ...]`, where `reached` counts vertices with a nonzero region contribution, `g > 0`, and `whole` counts vertices where `g >= 1`; `src/rig.ts`), read the built rig's `mesh_report.json` (`rig/mesh_report.json` from `rig`, or `out/rig/mesh_report.json` from `build --out out` — see §3, *A contour mesh*, *What it reports*, and *Recipe: a soft region driven by physics*): those fields are written by `rig` / `build` and are not printed by `mesh-stats`. Neither `mesh-stats`'s dry totals nor `mesh_report.json`'s static `regions[].{reached, whole}` setup-weight counts are a rendered `> 0.5 px` counterfactual-motion count or a claim that the config passed the compiler, coverage, motion or visual `check` gates (§3, *Recipe: a soft region driven by physics*). An `auto` part's count is its reduction's result: when rigc's
 motion gate refuses that result, the rig stage replays an earlier accepted step, which needs
 rigc, and the line says so. A problem the rig stage would refuse — a part with no PNG, an
 outline that does not close, a name `bones` does not declare — is the rig stage's own refusal,
-by the same name, exit 1; it takes no `--requirements`, because the rig stage's meshes read
-none, and no `--idle-keys`, because where the idle's keys go moves no vertex.
+by the same name, exit 1; it takes `--config` and `--parts` alone (no `--candidate`, `--regions`, `--report`, `--requirements`, because the rig stage's meshes read
+none, and no `--idle-keys`, because where the idle's keys go moves no vertex).
 
 ### For artists: your own layered file (issue #359)
 
@@ -3217,7 +3218,7 @@ valued destination path with two destination rules — **in place on an existing
 | --- | --- | --- |
 | `propose --head-box` | existing regular config | `seethrough.head_box` |
 | `assemble --propose-plan` | existing regular config; must name `--config` itself | `assemble.plan`, `assemble.extend_below_crop` |
-| ordinary `propose --parts` without `--cloth` | existing regular config | each present `PROPOSAL_CONFIG_SECTIONS` value: `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `proposed_rig_scale` |
+| ordinary `propose --parts` without `--cloth` | existing regular config | each present `PROPOSAL_CONFIG_SECTIONS` value: `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `motion_seams`, `proposed_rig_scale` |
 | ordinary `propose --parts … --only-missing` (issues #671, #679) | existing regular config | only resolvable `meshes.<part>` or `regions.<part>` for an unattached part: attached covers existing `meshes` and `regions`, source parts consumed by the config's own `limbs.<name>.segments[].from`, and `assemble.patches` (always regions), with or without `--keypoints`. Entries are checked against the config's bones and chains, including mesh and `auto` bone/region references; an unresolved entry is never written. Each skipped part gets a note naming its attachment or the unresolved reference and why. An accepted split part from `full:drape-<s>` / `full:hand-<s>` also gains its missing `assemble.plan` row (drape before the full run's `handwear-<s>` row, hand after it); added row by row and entry by entry, every existing byte as read |
 | `propose --cloth <input.json>` | new file | the recipe's edits spliced into the cloth config; §3, *The config written*, gives entry ownership, hand-edit conflicts and `--from <previous.json>` |
 
@@ -3779,6 +3780,9 @@ See-through with another seed.
 | <a id="CONFIG_TAG_KNOWN"></a><a id="CONFIG_PART_NAME"></a><a id="CONFIG_PART_UNIQUE"></a>`CONFIG_TAG_KNOWN`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` | a plan or extend entry names neither a v3 tag nor `author:<label>` (an `author:` tag with a malformed label says what the label must be), a part name that is not a file name, or a part or layer twice — a patch named like a plan part or another patch, and a cut's `into` named like a plan part, a patch or another cut's, included | `assemble.plan`, `assemble.patches`, `assemble.cuts` |
 | <a id="CONFIG_SET_FOCUS"></a>`CONFIG_SET_FOCUS` | optional `assemble.alternates[i].focus` (issue #719) must be exactly two finite painting-pixel coordinates `[x, y]`, x right/y down, inside that alternate painting (edges included); the loader checks the tuple and `assemble` checks the actual canvas before writing. Only with focus, `parts.json` carries the original point and `focus_source_size`; `sets.json` carries the point in setup-world coordinates through the accepted rig-canvas resize and `src/coords.ts`. Absent means no focus field or inferred hand position | author a point inside the painting or omit `focus`; after changing or removing it, re-run `assemble` and `rig`. Scene placement belongs to the consumer |
 | <a id="CONFIG_SET_LAYERS"></a>`CONFIG_SET_LAYERS` | `assemble.alternates[i].layers` names an unknown, uncovered or hidden part, or a painting patch with no run-layer source | name a covered layer-backed output part (a limb segment name, not its consumed source); use `author:<label>` for author art |
+| <a id="CONFIG_MOTION_SEAM"></a>`CONFIG_MOTION_SEAM` | motion_seams has a malformed entry, an unknown output part, a self-pair, duplicate/reversed pair or unknown entry field | declare each unordered pair once with two resolved output part names |
+| <a id="PARTS_MOTION_SEAM"></a>`PARTS_MOTION_SEAM` | parts.json motion_seams violates the same declaration shape/name/uniqueness contract | reassemble with the declared output part names |
+| <a id="CHECK_MOTION_SEAM_DECLARATION"></a>`CHECK_MOTION_SEAM_DECLARATION` | a directly supplied parts record has an invalid explicit motion seam declaration | supply a valid parts.json declaration; check never infers a replacement |
 | <a id="CONFIG_NAME_RESOLVES"></a>`CONFIG_NAME_RESOLVES` | a parent, segment, region, track, blink member, blink still part or bone, extend part, patch or cut `draw.before`, or cut `from` names nothing declared above it (a cut's `from` must be a plan part); or a constraint's `bones`, `target`, `source` or `bone` names a bone `bones` does not declare (the detail names the constraint and lists the bones that exist); in `meshes.<part>.auto`, a bone or region name nothing declares; or `bones[i].link_inherit` names a link outside its own chain (the detail lists that chain's expanded links) | the named reference, or the declaration it needs |
 | <a id="CONFIG_BONE_UNIQUE"></a>`CONFIG_BONE_UNIQUE` | a bone or chain declared twice, or `root` declared | `bones` |
 | <a id="CONFIG_BONE_INHERIT"></a>`CONFIG_BONE_INHERIT` | a single bone's `inherit`, or a chain's `link_inherit.<link>`, is a string that is not one of rig-c's five mode names as its table spells them (issue #348); the line lists all five. `"NoScale"` is refused too: the runtime would fold the first letter, and this loader folds and maps nothing | `bones[i].inherit` or `bones[i].link_inherit.<link>` — `normal`, `onlyTranslation`, `noRotationOrReflection`, `noScale` or `noScaleOrReflection` (§3, `bones`) |
@@ -4287,6 +4291,14 @@ flag) and 8 `CLOTH_SETTLES` warnings for 9 (selftest `CK515`).
 **Steady-wind seam band** (`--wind-band`, issue #590). `check --wind-band <spec.json>` (or `build --wind-band <spec.json>`, forwarded) sweeps steady horizontal wind across a caller-declared grid and reports the contiguous `[x_lo, x_hi]` band in which each declared seam pair holds `gap <= max_gap` and `ghost <= max_ghost` across every animation in `motion.json`. Every field in `{ "spec": "rig-parts-wind-band/1", "min", "max", "step", "fps", "max_gap", "max_ghost", "pairs" }` is required — nothing falls back to `SEAM_OVER_MOTION`'s pairs, one-cell floor, or fps. At each swept step `x = min + k * step`, `check` runs `rigc render --seam <pairs> --fps <fps> --max 16 --environment` with a single-step steady schedule `{ "spec": "rigc-environment/1", "steps": [{ "t": 0, "wind": [x, 0], "gravity": [0, 1] }] }` (`seam.json` cells are in each pair's coarser drawing texels, independent of `--max`). **What it does not measure:** the sweep is steady wind (`wind: [x, 0], gravity: [0, 1]` at `t = 0`), not a time-varying gust (`x ± a` at 0.2 Hz); transient overshoot from a changing wind is not read by a steady sweep, and the band is documented and reported as the steady-wind band (`mode: "steady"`, `gravity: [0, 1]`). It is a reported line (`status: "REPORTED"`), never a bar: it prints one `WIND_BAND:` summary line plus one `WIND_BAND:` line per pair that breaks inside `[min, max]`, and writes `WIND_BAND` in `check.json` before `PASS`.
 
 
+**Explicit motion seam observations** (issue #750). `motion_seams` is optional in a proposal, config and `parts.json`. The pure `draftMotionSeams(config, parts)` generator reads source provenance and the final declared carrier hierarchy: a non-limb `topwear` mesh on exactly two single-bone carriers which are a named parent and child, and non-limb `handwear-r`/`handwear-l` whose carriers are strict descendants with the same nearest trunk carrier, either that parent or that child. A sleeve may branch from the parent as a sibling of the child; it binds neither trunk carrier itself, and carriers with different nearest trunks do not qualify. This establishes declared structure, not positive compiled vertex weights or setup alpha overlap; the stock seam reader observes the band. Other structures add nothing. No part spelling, motion keys, distance heuristic or ancestor in common supplies identity. Proposal copy/write-config and turn preserve this field. For an older authored config, retain its original and use the same generator on its frozen structure/source parts, adding only this declaration in a derived config with a provenance receipt; regenerating its other rig or motion sections changes the experiment. Check reads the declaration, never calls this generator, and never restores a removed pair. A duplicate with an existing limb/requirement/root pair retains each source; an independently proven body-root pair keeps its existing FAIL policy.
+
+Every played non-root WARN, including existing limb pairs, additionally records the actual above-floor `worst` hit (`kind`, `index`, `px`, `cell`, `box`; maximum count, earliest frame on a tie, gap before ghost on a remaining tie) and `pose_at_worst` (`index`, actual raw `time`, `joints`). Each joint records `bone`, `parent`, `world_x_axis_degrees`, `parent_relative_setup_axis_delta_degrees_mod360`, `static_range`, `comparison` and, when needed, `reason`. Carrier paths come from the drawings actually shown at that frame and their positive weights or rigid binding, followed through the declared hierarchy. The SAME seam render supplies `--geometry`; animation, viewport, frame index and raw hit time are bound before its actual `setup.bones` and posed matrices are read. Animation frame 0 can already be posed and is never substituted for setup. Missing/mismatched geometry or matrices is a named refusal, never a zero angle or an estimate from source keys or frame/fps.
+
+Parent-relative axes use the full inverse parent matrix; parent-only rotation cancels. Angles are CCW in world y-up, and the setup-relative delta is explicitly modulo 360 in [-180,180). A static range is copied unchanged from its limb record, or null when absent. `comparison: "axis-modulo-360"` describes normal, unsheared, nondegenerate axes and a range within that branch; it does not certify unwrapped winding or impose an angle bar. Special inheritance, shear/reflection, singular or degenerate axes, absent ranges and ambiguous winding report `comparison: "unavailable"` with a reason. These fields are observation evidence only. Existing `opens`, `px`, `max_px`, under-floor counts, root partitions and FAIL ownership keep their definitions.
+
+Absent declaration retains existing output bytes except optional new evidence on existing WARN rows. With a declared no-chest control, compare standalone checks at identical paths: exclude only the newly selected seam line's selection, rows, derived status and reason when the baseline already has that container. The historical absent-container bar required seven keys, CLEAR and zero warnings in every animation; its measured raw exit 1 remains red because the original idle keys the chest even though the added greeting keys only the head, and optional `worlds` is valid source data. [HQ's post-verdict restatement](https://github.com/rig-c/parts/issues/750#issuecomment-6398631279) instead requires the complete source-derived `MotionSeamLine` schema, including optional reference worlds, exact metadata and generated selection, and independent raw-row audits. All added greeting rows must be clean; any WARN must have an actual keyed pair-joint witness from the original motion, compiled tracks and carrier ancestry. STABILITY's *Explicit motion seam observations* section defines this audit and lossless removal of the new container: every outside byte stays identical. Keep the historical red beside the separate re-evaluation. No input, threshold, angle gate, exit behavior or animation selector is changed. Whether an open armhole should eventually fail is an open severity decision outside this WARN contract.
+
 **Body-root seam identity** (issue #686). A limb must have exactly one segment0 part. Its declared bone must have one named immediate parent; the root slot must bind that bone (or its declared turn child). Non-limb parts with `topwear` or `bottomwear` source provenance, a slot on that parent (directly or through its verified generated turn child) and a named default-skin drawing are candidates. The body-side child must match `applyTurn`'s exact generated name, unique identity bone and parent, control and per-part transform binding; a similarly named bone alone is not proof (issue #708). The original carrier and pair slot names do not change under turn; stock setup pose `render --seam` selects all matching drawings with `banded > 0` (its existing alpha-overlap band, without dilation), so one selects one pair and two select both pairs. When eligible candidates all return valid setup banded 0, that limb has no selected root pair: `unmeasuredRoots` retains its limb, bone, parent, segment0 part, candidates and named reason, reported as SKIP, not measured PASS. Part spelling, nearest geometry and shared mesh influences select nothing. On `wind` the pairs are `topwear|upperarm_r`, `topwear|upperarm_l`, `bottomwear|thigh_r` and `bottomwear|thigh_l`; “trunk” is not a part name. Existing pairs keep their order; a reversed explicit declaration deduplicates with the root pair and retains both declarations. An ambiguous/missing named binding, no eligible candidate, or unreadable/undrawn setup data is `CHECK_MOTION_SEAM_ROOT`, naming the part and candidates. Valid zero-band metadata is carried separately as optional `roots.unmeasured`, never as a fabricated measured pair. The all-zero root block remains present and its bar is skipped; measured FAIL takes precedence over SKIP, while measured PASS plus any unmeasured root stays SKIP. No body provenance leaves legacy pair selection unchanged and supplies no body-root coverage.
 
 Renderer metadata and exact raster reads use the promised `rig-c/render-shared` entry (rig-c >=2.69.0 <3.0.0). It registers no Spine runtime; where that runtime resolves from rig-c's own package root, the existing `rig-c/render` entry registers the official Spine side explicitly. An install without Spine keeps rig-c's own candidate chooser and gate; candidate or loader failures never select a guessed fallback.
@@ -5307,3 +5319,10 @@ missing a path, given twice, or combined with `--shard`):
   enter `holes`; check names or indented detail lines containing `HOLE` or `SKIP` (such as
   `RG82_BLINK_NO_HOLE_…` or `SO21_ZERO_SETUP_BANDS_REMAIN_NAMED_SKIPS_…`) are counted as `PASS` or
   `FAIL` controls and never as `skips` or `holes` (`RT16`, `RT17`).
+
+The WARN pose reader also requires the published stock coordinate header and
+the required source bone/parent roster. It binds the complete geometry frame
+cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
+including unselected frames, before reading the worst pose. Identical static
+ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
+never described as no declared range.

package/docs/MIGRATION.md

@@ -301,7 +301,7 @@ either (the examples' `expected/` and every existing control are unchanged).
 
 What to do: nothing. To draft a skirt or hair that the consumer's wind and gravity move,
 add a `cloth` block and propose with `--cloth`; copy each of `bones`, `meshes`, `regions`,
-`limbs`, `motion`, `constraints`, `turn` and `proposed_rig_scale` the proposal wrote into the config, as before
+`limbs`, `motion`, `constraints`, `turn`, `motion_seams` and `proposed_rig_scale` the proposal wrote into the config, as before
 (`constraints` is the one `--cloth` adds).
 
 ## After 1.20.0: the seam over a joint's range
@@ -443,3 +443,32 @@ bands* for the source, name, width and overlap refusals. Existing configs need
 no change. The parts reader gains `limb.hybrid` and `limb.band` records only
 for this mode, and the recorded lower range is measured once. The normal
 one-bone rule and existing range thresholds remain unchanged.
+
+## Explicit motion seam declarations and posed WARN evidence (issue #750)
+
+New proposals can include optional `motion_seams: [{part, neighbour}]` alongside
+the other proposed config sections. Carry it through assemble into parts.json.
+Each pair names two existing output parts, once regardless of direction; the
+strict readers name malformed, self, duplicate and unresolved declarations.
+Check observes declared pairs in every supplied animation with the existing
+non-root WARN floor; bars and exit status are unchanged. Existing body-root
+FAIL semantics remain in force for independently selected root pairs.
+
+Older authored configs acquire no declaration automatically. Keep the originals
+and use exported `draftMotionSeams(config, parts)` on the frozen authored
+structure and source-provenance parts, preserving every other config value in
+a derived input and recording the added declaration. Check does not run that
+generator; removing a declaration silences its independently declared pair.
+
+Existing played limb WARNs as well as newly declared WARNs gain same-render
+worst-frame pose evidence. Read relative angles as setup-axis deltas modulo
+360, alongside unchanged static ranges; unsupported comparisons carry an
+unavailable reason. The geometry setup, actual raw frame/time and parent
+matrices replace no source motion keys and introduce no angle threshold.
+
+The WARN pose reader also requires the published stock coordinate header and
+the required source bone/parent roster. It binds the complete geometry frame
+cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
+including unselected frames, before reading the worst pose. Identical static
+ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
+never described as no declared range.

package/docs/STABILITY.md

@@ -118,7 +118,7 @@ The fields, object by object (a bold path is where the object sits; `<part>` is
 part name, `[i]` an entry of a list):
 
 <!-- stable:config -->
-- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`, `requirements` (issue #556, additive: a path beside the config that build reads in place of its requirements flag, whose behaviour is unchanged)
+- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`, `requirements` (issue #556, additive: a path beside the config that build reads in place of its requirements flag, whose behaviour is unchanged), `motion_seams`
 - **generation** — required: `checkpoint`, `loras`, `trigger`, `identity`, `sampler`, `costume`, `negative_extra`, `style`, `negative_pose`, `latent`, `seed`; optional: `pose`, `control`
 - **generation.loras[i]** — required: `name`, `strength`; optional: `strength_clip`
 - **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
@@ -381,3 +381,52 @@ carrier and measured geometry must agree; the lower rigid piece alone carries
 existing `LIMB_ONE_BONE` line checks ordinary segments as before; the band
 requires exactly its two adjacent carriers. `SEAM_OVER_RANGE` uses the stored
 radius and existing rest-art comparison, without changing its bar.
+
+## Explicit motion seam observations (issue #750)
+
+`motion_seams: [{part, neighbour}]` is optional in proposal/config/parts.json.
+Absent leaves the existing declaration path unchanged. Readers refuse unknown
+parts, self-pairs, unordered duplicates, malformed entries and unknown entry
+fields by name. Empty declares no additional pair. Proposal turn/copy/write and
+assemble preserve it; check never infers a removed declaration. A declared pair
+uses the existing non-root WARN floor and unchanged exits, unless independently
+selected by the existing proven body-root FAIL contract.
+
+All played non-root WARN rows may add `worst` and `pose_at_worst`, including
+existing limb rows. Worst is the maximum above-floor raw hit, earliest frame
+on a tie, gap before ghost on a remaining tie. Pose evidence binds the same
+seam geometry's actual setup, frame index, animation, viewport and raw time.
+It records carrier-path world axes, parent-relative setup-axis deltas modulo
+360, unchanged static ranges and explicit unavailable comparison reasons;
+frame0 and source key endpoints are not setup or measured pose substitutes.
+No angle bar or new threshold is added. Missing/mismatched data refuses.
+Without a declaration only optional WARN evidence changes existing check bytes.
+For the declared no-chest control at identical paths, the exact byte projection
+of an existing seam container excludes only its selection, rows, derived status
+and reason. The historical optional-container bar required exactly seven keys,
+`CLEAR` and zero warnings across every animation. Its measured raw exit 1 stays
+red: the added greeting keys only the head, but the original idle also keys the
+chest and reports an above-floor opening at frames 8–12. The source type also
+permits informational `worlds`; neither finding changes the product contract.
+
+[HQ's post-verdict restatement](https://github.com/rig-c/parts/issues/750#issuecomment-6398631279)
+corrects that premise. When the baseline omits `SEAM_OVER_MOTION` entirely, audit
+the new container against the complete `MotionSeamLine` source type, including
+its required and optional fields and referenced types, rather than a hand-kept
+key list. Independently verify fps 12, the exact source floor, compiled animation
+roster, generated selection and every row against the raw readings. All added
+greeting rows must be readable and clean. Any WARN must name an animation that
+actually keys a joint on the pair's carrier ancestry, witnessed by the original
+authored motion, compiled tracks and actual drawing carriers. The original idle
+WARN remains reported with the unchanged floor and exit behavior. Only after
+those audits may lossless removal of the new container establish exact equality
+of every outside byte. An existing baseline container keeps the narrower field
+exclusions above. The original red and the separate post-verdict re-evaluation
+are retained together; no input, animation selector or threshold is changed.
+
+The WARN pose reader also requires the published stock coordinate header and
+the required source bone/parent roster. It binds the complete geometry frame
+cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
+including unselected frames, before reading the worst pose. Identical static
+ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
+never described as no declared range.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/skills/rig-parts/SKILL.md

@@ -85,7 +85,7 @@ under that.
    gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
    not in the rig. Then `rig-parts propose --parts work/rig
    --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `limbs`,
-   `motion`, `constraints`, `turn`, `proposed_rig_scale` from `proposal.json` into the config, each it
+   `motion`, `constraints`, `turn`, `motion_seams`, `proposed_rig_scale` from `proposal.json` into the config, each it
    wrote (`limbs` only with `--keypoints`, `constraints` only with `--cloth`, `turn`
    only with `--full`/`--head`; a `limbs` block left out is refused at the next step). `assemble` needs the plan and none of
    those sections; do not stub them to get past it (AUTHORING §4 says what each step

package/src/assemble.ts

@@ -104,6 +104,7 @@ import { type ArmSplit, type BoneEntry, type CharacterConfig, type ControlSkelet
 import { type Problem, refuseIfAny } from './errors.ts';
 import { CORE_ALPHA, figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
 import { padToSquare, squarePad } from './inputs.ts';
+import type { MotionSeamDeclaration } from './motionseams.ts';
 import { type CapRecord, type LimbRecord, PAINTING_RUN, type PartRecord, type PartsFile, type RecompositeRecord, type SceneRecord, type SingleRunPad } from './parts.ts';
 import { assignCrossedLimbs, assignOverlappingHands, type BonePlace, bonePlaces, capBox, coveredRadius, type CutPlacement, featherWeight, halfWidthAbout, inDisc, jointLine, type JointLine, jointOffsets, limbPolyline, limbRun, luma601, nearestLimb, nearestOnLine, offLineFigure, pastJoint, placeCut, polylineDist2, segmentOf } from './limbs.ts';
 import {
@@ -320,6 +321,7 @@ export interface AssembleInput {
   patches: Patch[];
   /** `assemble.cuts`: plan parts' pixels taken into new parts by polygon (`cutPart`), placed per their `draw`. */
   cuts: Cut[];
+  motion_seams?: MotionSeamDeclaration[];
   /** Internal alternate selection: piece layer by cut output; polygon subtraction and under stay on from. */
   cutLayers?: ReadonlyMap<string, string>;
   /**
@@ -5105,6 +5107,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     parts: {
       rig_size: [W, H],
       scale_rig_per_source: frame.S,
+      ...(input.motion_seams === undefined ? {} : { motion_seams: input.motion_seams.map(({ part, neighbour }) => ({ part, neighbour })) }),
       parts: placed.map((p) => p.record),
       ghost_px: ghost,
       recomposite: recompositeRecord(figures),
@@ -5875,7 +5878,7 @@ function unplannedNotes(
  * full-loader config, where it is optional.
  */
 export function stageFields(
-  cfg: Pick<CharacterConfig, 'seethrough' | 'assemble' | 'scene'> & { limbs?: Record<string, Limb>; bones?: BoneEntry[] },
+  cfg: Pick<CharacterConfig, 'seethrough' | 'assemble' | 'scene' | 'motion_seams'> & { limbs?: Record<string, Limb>; bones?: BoneEntry[] },
   single: { w: number; h: number } | null = null,
 ): {
   resolution: number;
@@ -5885,6 +5888,7 @@ export function stageFields(
   extend: Extend[];
   patches: Patch[];
   cuts: Cut[];
+  motion_seams?: MotionSeamDeclaration[];
   scene?: boolean;
   limbs?: Record<string, Limb>;
   bones?: BoneEntry[];
@@ -5915,6 +5919,7 @@ export function stageFields(
     extend: cfg.assemble.extend_below_crop ?? [],
     patches: cfg.assemble.patches ?? [],
     cuts: cfg.assemble.cuts ?? [],
+    ...(cfg.motion_seams === undefined ? {} : { motion_seams: cfg.motion_seams }),
     ...(cfg.scene === undefined ? {} : { scene: true }),
     ...(cfg.limbs === undefined ? {} : { limbs: cfg.limbs, bones: cfg.bones ?? [] }),
   };

package/src/check.ts

@@ -85,6 +85,8 @@ import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep
 import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
 import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal } from './coords.ts';
 import { capBox, inDisc } from './limbs.ts';
+import { motionSeamProblems } from './motionseams.ts';
+import { seamPoseFrame, seamStaticRange, type SeamPoseAtWorst } from './motionseampose.ts';
 import { coreCompileGuideLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import { framesInside, IDLE_FPS, TIME_SLACK } from './motion.ts';
 import {
@@ -4305,6 +4307,8 @@ export interface MotionSeamRow {
   worst?: MotionSeamHit & { kind: 'gap' | 'ghost' | 'gapOpen' | 'underGhost' | 'gapOpen+underGhost' };
   /** Exact stock partitions and the resolved UNDER owner, retained even below the floor. */
   cells?: MotionRootCells[];
+  /** Same-render posed evidence on every played non-root WARN. */
+  pose_at_worst?: SeamPoseAtWorst;
 }
 
 /** Existing pairs warn; new body roots alone can FAIL. Unavailable readings are named SKIP, never measured zero. */
@@ -4353,6 +4357,10 @@ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ nam
     }
   }
   for (const r of seams) add(r.part, r.neighbour, `requirement "${r.name}" (seam)`);
+  if (parts.motion_seams !== undefined) {
+    refuseIfAny(motionSeamProblems(parts.motion_seams, new Set(parts.parts.map(p => p.name)), 'parts.json motion_seams', 'CHECK_MOTION_SEAM_DECLARATION'));
+    parts.motion_seams.forEach((r, i) => add(r.part, r.neighbour, `motion_seams[${i}]`));
+  }
   const candidates = rig === undefined ? [] : motionRootCandidates(parts, rig);
   const selected: MotionSeamPair[] = [];
   if (candidates.length > 0) {
@@ -4750,6 +4758,7 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
       }
       const over = new Map<number, number>();
       let rootWorst: MotionSeamRow['worst'];
+      let warnWorst: MotionSeamRow['worst'];
       const rootFrames = new Set<number>();
       const cells: MotionRootCells[] = [];
       const kinds: Record<'gap' | 'ghost', MotionSeamWorldKind> = { gap: { max_px: 0, worst: null }, ghost: { max_px: 0, worst: null } };
@@ -4767,6 +4776,7 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
         // Existing internal pairs retain their original maximum-kind warning and floor.
         for (const h of hits) if (want.root === undefined && (plant.noFloor === true || openingOverFloor(h))) {
           over.set(h.index, Math.max(over.get(h.index) ?? 0, h.px));
+          if (warnWorst === undefined || h.px > warnWorst.px || (h.px === warnWorst.px && h.index < warnWorst.index)) warnWorst = { ...h, kind };
         }
       }
       if (want.root !== undefined && !setup) {
@@ -4842,6 +4852,7 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
         max_px: opens.reduce((m, f) => Math.max(m, over.get(f) ?? 0), 0),
         under_floor: (want.root === undefined ? p.opens : [...rootFrames].filter(f => cells.some(c => c.index === f && c.counted > 0))).filter((f) => !over.has(f)),
         ...(rootWorst === undefined ? {} : { worst: rootWorst }),
+        ...(warnWorst === undefined || setup ? {} : { worst: warnWorst }),
         ...(want.root === undefined ? {} : { cells }),
       });
     });
@@ -4898,9 +4909,99 @@ export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fp
   };
 }
 
+/** Enrich active non-root WARNs only, using the SAME seam render and raw hit time. */
+export function enrichMotionSeamPoses(dir: string, rig: Record<string, unknown>, parts: PartsFile | null, pairs: readonly MotionSeamPair[], rows: MotionSeamRow[]): void {
+  const wanted = rows.filter(row => row.opens.length > 0 && pairs.some(pair => pair.pair === row.pair && pair.root === undefined));
+  if (wanted.length === 0) return;
+  const problems: Problem[] = [];
+  const sidecar = readJson(join(dir, 'frames.json'), problems);
+  refuseIfAny(problems);
+  const sets = Array.isArray(sidecar?.sets) ? sidecar.sets.filter(isRecord) : [];
+  // Slots/weights already bind drawn stop links; resolve their ancestry in the same graph rig-c compiles.
+  const expanded = Array.isArray(rig.stops) ? (expandStops(rig as unknown as RigcRigSpec, 'rig.json') as unknown as Record<string, unknown>) : rig;
+  const bones = (Array.isArray(expanded.bones) ? expanded.bones : []).filter(isRecord);
+  const skin = isRecord(rig.skins) && isRecord(rig.skins.default) ? rig.skins.default : {};
+  const cache = new Map<string, { geometry: Record<string, unknown>; seam: Record<string, unknown>; cohort: FrameSet; parsed: IdleGeometry }>();
+  for (const row of wanted) {
+    const h = row.worst;
+    if (h === undefined) geometryProblem(row.pair, 'above-floor WARN has no worst raw hit');
+    const matches = sets.filter(set => set.animation === row.animation);
+    const set = matches[0];
+    if (matches.length !== 1 || typeof set.dir !== 'string' || isAbsolute(set.dir) || set.dir.split(/[\\/]/).includes('..')) geometryProblem(row.animation, 'one local same-animation frame set required for WARN pose');
+    let data = cache.get(row.animation);
+    if (data === undefined) {
+      const geometry = readJson(join(dir, String(set.dir), GEOMETRY_FILE), problems);
+      const seam = readJson(join(dir, String(set.dir), SEAM_READING_FILE), problems);
+      refuseIfAny(problems);
+      if (geometry === null || seam === null || !Array.isArray(geometry.frames) || geometry.frames.length !== set.written) geometryProblem(row.animation, 'stock seam geometry frame count differs from frames.json');
+      const cohort = readFrameSet(join(dir, String(set.dir)));
+      const parsed = readGeometry(join(dir, String(set.dir), GEOMETRY_FILE), cohort.written);
+      if (parsed === null) geometryProblem(row.animation, 'same-render geometry is missing');
+      data = { geometry, seam, cohort, parsed };
+      cache.set(row.animation, data);
+    }
+    const rawPairs = Array.isArray(data.seam.pairs) ? data.seam.pairs.filter(isRecord) : [];
+    const pair = pairs.find(p => p.pair === row.pair);
+    const raw = rawPairs.find(p => p.a === pair?.a && p.b === pair?.b);
+    const kind = raw?.[h.kind];
+    const hits = isRecord(kind) && Array.isArray(kind.frames) ? kind.frames.filter(isRecord) : [];
+    const hitsAt = hits.filter(hit => hit.index === h.index && hit.px === h.px && hit.cell === h.cell && JSON.stringify(hit.box) === JSON.stringify(h.box));
+    const time = hitsAt[0]?.time;
+    if (hitsAt.length !== 1 || typeof time !== 'number' || !Number.isFinite(time)) geometryProblem(row.pair, 'one matching worst raw hit with actual finite time required');
+    const rawFrames = (data.geometry.frames as unknown[]).filter(isRecord);
+    const frame = rawFrames.find(f => f.index === h.index);
+    const shown = Array.isArray(frame?.attachments) ? frame.attachments.filter(isRecord) : [];
+    const carriers = new Set<string>();
+    for (const name of [pair?.a, pair?.b]) {
+      const active = shown.filter(a => a.slot === name);
+      const onValue = typeof name === 'string' ? skin[name] : undefined;
+      const on = isRecord(onValue) ? onValue : {};
+      const attachment = active.length === 1 && typeof active[0].attachment === 'string' ? on[active[0].attachment] : undefined;
+      if (!isRecord(attachment)) geometryProblem(row.pair, `slot "${String(name)}": active default-skin drawing unavailable at worst frame`);
+      if (Array.isArray(attachment.weights)) {
+        const weights = attachment.weights.flatMap(v => Array.isArray(v) ? v.filter(isRecord) : []);
+        for (const w of weights) if (typeof w.bone === 'string' && typeof w.weight === 'number' && w.weight > 0) carriers.add(w.bone);
+      } else {
+        const slot = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find(sl => sl.name === name);
+        if (typeof slot?.bone !== 'string') geometryProblem(row.pair, `slot "${String(name)}": no declared bone`);
+        carriers.add(slot.bone);
+      }
+    }
+    if (carriers.size === 0) geometryProblem(row.pair, 'no positive-weight or rigid carrier at worst frame');
+    const ancestry = new Set<string>();
+    for (const carrier of carriers) {
+      const seen = new Set<string>();
+      let next: string | undefined = carrier;
+      while (next !== undefined) {
+        if (seen.has(next)) geometryProblem(row.pair, `cycle in carrier path at "${next}"`);
+        seen.add(next);
+        ancestry.add(next);
+        const named = bones.filter(b => b.name === next);
+        if (named.length !== 1) geometryProblem(row.pair, `carrier "${next}": one declared bone required`);
+        next = typeof named[0].parent === 'string' ? named[0].parent : undefined;
+      }
+    }
+    const joints = bones.filter(b => typeof b.name === 'string' && ancestry.has(b.name)).map(b => {
+      const ranges = parts?.parts.flatMap(p => {
+        const limb = p.limb;
+        return limb !== undefined && limb.bone === b.name && limb.range !== undefined ? [limb.range] : [];
+      }) ?? [];
+      return { bone: String(b.name), parent: typeof b.parent === 'string' ? b.parent : null,
+        inherit: typeof b.inherit === 'string' ? b.inherit : 'normal', ...seamStaticRange(ranges) };
+    });
+    for (const joint of joints) {
+      const track = boneTrackOf(data.parsed, join(dir, String(set.dir), GEOMETRY_FILE), data.cohort, joint.bone);
+      if (typeof track === 'string') geometryProblem(row.pair, track);
+    }
+    row.pose_at_worst = seamPoseFrame(data.geometry, row.animation, h.index, time, data.cohort, joints);
+  }
+}
+
 /** One warning as the console prints it (issue #493's form, the floor's clause after it). */
 export function motionSeamWarnText(r: MotionSeamRow): string {
-  return `WARN seam "${r.pair}" opens on ${r.opens.length} frame(s) ${frameRuns(r.opens)} max ${r.max_px} px in "${r.animation}" — over the one-cell floor${r.under_floor.length === 0 ? '' : `, ${r.under_floor.length} more frame(s) one cell thick not reported`}`;
+  const pose = r.pose_at_worst;
+  const evidence = pose === undefined ? '' : `; worst frame ${pose.index} (t = ${pose.time}s), ${pose.joints.map(j => `bone "${j.bone}" parent ${JSON.stringify(j.parent)} world ${j.world_x_axis_degrees === null ? 'unavailable' : round3(j.world_x_axis_degrees) + 'deg'}; relative setup axis ${j.parent_relative_setup_axis_delta_degrees_mod360 === null ? 'unavailable' : round3(j.parent_relative_setup_axis_delta_degrees_mod360) + 'deg modulo360'}, static range ${JSON.stringify(j.static_range)} (${j.comparison}${j.reason === undefined ? '' : ': ' + j.reason})`).join(' | ')}`;
+  return `WARN seam "${r.pair}" opens on ${r.opens.length} frame(s) ${frameRuns(r.opens)} max ${r.max_px} px in "${r.animation}" — over the one-cell floor${r.under_floor.length === 0 ? '' : `, ${r.under_floor.length} more frame(s) one cell thick not reported`}${evidence}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -6136,10 +6237,11 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         const activeDest = stripped === null ? seamMotionDir : join(seamMotionDir, env === null ? 'default' : 'active');
         const renderedWorlds = new Set<'default' | 'still'>();
         const hasRoots = read.some(p => p.root !== undefined);
-        const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), ...(hasRoots ? ['--geometry'] : []), '--out', activeDest]);
+        const r = measured(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--geometry', '--out', activeDest]);
         if (r.status !== 0) refuseIfAny(rigcFailed(`render --seam ${list} --fps ${fps}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
         const activeWorldRows: MotionSeamWorldRow[] = [];
         motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(activeDest, animationNames, fps, read, {}, stripped !== null && env === null ? activeWorldRows : undefined, hasRoots ? motionRootDrawOrderReader(activeDest) : undefined), undefined, motionRootProblems, unmeasuredRoots);
+        enrichMotionSeamPoses(activeDest, inp.rig, inp.parts, pairs, motionSeam.rows);
         if (stripped !== null) {
           const response = environmentResponse(readFileSync(join(buildDir, 'skeleton.json'), 'utf8'));
           motionSeam.worlds = motionSeamWorlds(true, response.wind.length > 0, world => {

package/src/config.ts

@@ -88,6 +88,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey, type RigStop } from 'rig-c/src/rig.ts';
 import { pyRound } from './round.ts';
+import { motionSeamProblems, type MotionSeamDeclaration } from './motionseams.ts';
 import { REQUIREMENTS_SPEC } from './requirements.ts';
 import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING, springStable } from './cloth.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
@@ -1069,6 +1070,8 @@ export interface CharacterConfig {
    * is read and no byte of any output moves.
    */
   requirements?: string;
+  /** Explicit motion observations, propagated to parts.json; absent means no added pair. */
+  motion_seams?: MotionSeamDeclaration[];
 }
 
 /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -1389,11 +1392,12 @@ export interface AssembleConfig {
   /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
   limbs?: Record<string, Limb>;
   bones?: BoneEntry[];
+  motion_seams?: MotionSeamDeclaration[];
   /** Issue #354: the `rig_scale` `propose` drafted the rig sections at, held equal to `assemble.rig_scale` when present. */
   proposed_rig_scale?: number;
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale', 'requirements'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale', 'requirements', 'motion_seams'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1464,6 +1468,10 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
     if (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
       checkAlternates(c, t.assemble.alternates, made, limbs, names?.bones ?? null, names?.chains ?? null, t.regions, t.meshes);
     }
+    if ('motion_seams' in t) {
+      const output = new Set([...made.parts.filter(n => !limbs?.consumed.has(n)), ...made.patches, ...made.cuts, ...(limbs?.parts.keys() ?? [])]);
+      c.problems.push(...motionSeamProblems(t.motion_seams, output, 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
+    }
   }
   if ('cloth' in t) checkCloth(c, t.cloth);
   const pose = base === null ? null : poseBeside(c, t.generation, base);
@@ -1660,6 +1668,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
   if ('stops' in t) checkStops(c, t.stops, names.bones, names.chains);
   const attached = attachedParts(t.meshes, t.regions);
+  if ('motion_seams' in t) c.problems.push(...motionSeamProblems(t.motion_seams, attached, 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
   const hasAltFace = hasAlternateFaceSet(t.assemble, [...parts, ...cuts]);
   if ('turn' in t) checkTurn(c, t.turn, attached, names.bones, hasAltFace);
   if ('scene' in t) checkScene(c, t.scene);
@@ -1890,9 +1899,9 @@ export interface SkeletonSections {
  * both before writing (`checkProposal`). A key the loader would not take is
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
  */
-export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number } {
+export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number; motion_seams?: MotionSeamDeclaration[] } {
   const c = new Check();
-  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale']);
+  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale', 'motion_seams']);
   if (top !== null) {
     const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
     if ('limbs' in top) {
@@ -1903,6 +1912,7 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
     }
     if ('meshes' in top) checkMeshes(c, top.meshes, names.bones, names.chains, top.stops);
     if ('regions' in top) checkRegions(c, top.regions, names.bones);
+    if ('motion_seams' in top) c.problems.push(...motionSeamProblems(top.motion_seams, attachedParts(top.meshes, top.regions), 'config.motion_seams', 'CONFIG_MOTION_SEAM'));
     if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
     if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
     if ('stops' in top) checkStops(c, top.stops, names.bones, names.chains);
@@ -1910,7 +1920,7 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
     if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
   }
   refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
-  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number };
+  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number; motion_seams?: MotionSeamDeclaration[] };
 }
 
 /**

package/src/motionseampose.ts

@@ -0,0 +1,117 @@
+/** Posed-axis evidence from one stock seam render, never sampled source keys. */
+import type { GeometryFile, GeometryFrame } from 'rig-c/render';
+import type { FrameSet } from './check.ts';
+import { PartsError } from './errors.ts';
+
+// Stock rig-c 2.69 geometry header, also exported by rig-c/render. render-shared
+// does not expose its constants; avoid loading the optional Spine side for a header read.
+export const SEAM_GEOMETRY_COORDINATES = 'spine world, y up, world units';
+const SEAM_GEOMETRY_SPEC: GeometryFile['spec'] = 'rigc-geometry/1';
+
+export interface SeamMatrix {
+  a: number; b: number; c: number; d: number;
+  worldX: number; worldY: number;
+}
+export interface SeamJointPose {
+  bone: string;
+  parent: string | null;
+  world_x_axis_degrees: number | null;
+  parent_relative_setup_axis_delta_degrees_mod360: number | null;
+  static_range: [number, number] | null;
+  comparison: 'axis-modulo-360' | 'unavailable';
+  reason?: string;
+}
+export interface SeamPoseAtWorst {
+  index: number;
+  time: number;
+  joints: SeamJointPose[];
+}
+const record = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const fail = (detail: string): never => { throw new PartsError([{ code: 'CHECK_GEOMETRY_FILE', object: 'motion seam pose', detail }]); };
+const wrap = (degrees: number): number => ((degrees + 180) % 360 + 360) % 360 - 180;
+const angle = (a: number, c: number): number => Math.atan2(c, a) * 180 / Math.PI;
+const inverseProduct = (p: SeamMatrix, c: SeamMatrix): SeamMatrix | null => {
+  const det = p.a * p.d - p.b * p.c;
+  if (det === 0 || !Number.isFinite(det)) return null;
+  const a = (p.d * c.a - p.b * c.c) / det, b = (p.d * c.b - p.b * c.d) / det;
+  const x = (-p.c * c.a + p.a * c.c) / det, d = (-p.c * c.b + p.a * c.d) / det;
+  return { a, b, c: x, d, worldX: 0, worldY: 0 };
+};
+const regular = (m: SeamMatrix): boolean => {
+  const x2 = m.a * m.a + m.c * m.c, y2 = m.b * m.b + m.d * m.d;
+  // Floating-point arithmetic slack only, relative to the two axis lengths.
+  return x2 > 0 && y2 > 0 && m.a * m.d - m.b * m.c > 0 &&
+    Math.abs(m.a * m.b + m.c * m.d) <= 64 * Number.EPSILON * Math.sqrt(x2 * y2);
+};
+
+/** World axes remain evidence even when local-range equivalence is unavailable. */
+export function seamJointPose(bone: string, parent: string | null, inherit: string, setup: SeamMatrix, posed: SeamMatrix,
+  parentSetup: SeamMatrix | null, parentPosed: SeamMatrix | null, range: [number, number] | null, rangeReason?: string): SeamJointPose {
+  const out: SeamJointPose = { bone, parent, world_x_axis_degrees: posed.a === 0 && posed.c === 0 ? null : angle(posed.a, posed.c),
+    parent_relative_setup_axis_delta_degrees_mod360: null, static_range: range, comparison: 'unavailable' };
+  if (inherit !== 'normal') return { ...out, reason: `inherit ${inherit}: parent-relative local-range comparison unavailable` };
+  if (parent === null || parentSetup === null || parentPosed === null) return { ...out, reason: 'no parent frame for a local-range comparison' };
+  const rest = inverseProduct(parentSetup, setup), frame = inverseProduct(parentPosed, posed);
+  if (rest === null || frame === null || !regular(rest) || !regular(frame) || !regular(parentSetup) || !regular(parentPosed)) return { ...out, reason: 'singular, reflected, sheared or degenerate axes: local-range comparison unavailable' };
+  const delta = wrap(angle(frame.a, frame.c) - angle(rest.a, rest.c));
+  out.parent_relative_setup_axis_delta_degrees_mod360 = delta;
+  if (range === null) return { ...out, reason: rangeReason ?? 'no declared static range; relative axis delta is modulo 360' };
+  if (range[0] <= -180 || range[1] >= 180 || Math.abs(delta) === 180) return { ...out, reason: 'ambiguous winding against static range; relative axis delta is modulo 360' };
+  // This is explicitly an axis comparison modulo 360, never an unwrapped local key or a new gate.
+  return { ...out, comparison: 'axis-modulo-360', reason: 'normal unsheared axes; modulo 360 only, winding not certified' };
+}
+
+/** Identical declarations share one range; conflicting declarations remain explicitly ambiguous. */
+export function seamStaticRange(ranges: readonly [number, number][]): { range: [number, number] | null; rangeReason?: string } {
+  const unique = [...new Map(ranges.map(range => [JSON.stringify(range), range])).values()];
+  return unique.length <= 1 ? { range: unique[0] ?? null }
+    : { range: null, rangeReason: `ambiguous declared static ranges ${unique.map(range => JSON.stringify(range)).join(', ')}; no local-range comparison` };
+}
+
+export type SeamFrameCohort = Pick<FrameSet, 'animation' | 'fps' | 'viewport'> & { frames: readonly Pick<GeometryFrame, 'index'>[] };
+export interface SeamPoseJoint {
+  bone: string;
+  parent: string | null;
+  inherit: string;
+  range: [number, number] | null;
+  rangeReason?: string;
+}
+
+/** Bind stock coordinates, source parent identities and the complete real PNG frame cohort. */
+export function seamPoseFrame(geometry: unknown, animation: string, index: number, time: number, cohort: SeamFrameCohort,
+  joints: readonly SeamPoseJoint[]): SeamPoseAtWorst {
+  if (!record(geometry) || geometry.spec !== SEAM_GEOMETRY_SPEC || geometry.animation !== animation || cohort.animation !== animation ||
+    geometry.fps !== cohort.fps || !record(geometry.viewport) || !Array.isArray(geometry.frames) || !record(geometry.setup)) return fail('same-animation stock geometry with matching fps, viewport, setup and frames required');
+  if (geometry.coordinates !== SEAM_GEOMETRY_COORDINATES) return fail(`coordinates must be ${JSON.stringify(SEAM_GEOMETRY_COORDINATES)}; found ${JSON.stringify(geometry.coordinates)}`);
+  const viewport = cohort.viewport;
+  for (const key of ['x', 'y', 'width', 'height', 'scale', 'pixelWidth', 'pixelHeight'] as const) {
+    if (typeof viewport[key] !== 'number' || !Number.isFinite(viewport[key]) || geometry.viewport[key] !== viewport[key]) return fail(`viewport ${key} differs from frames.json or is not finite`);
+  }
+  const roster = Array.isArray(geometry.bones) ? geometry.bones.filter(record) : [];
+  if (!Array.isArray(geometry.bones) || roster.length !== geometry.bones.length || roster.some(b => typeof b.name !== 'string' || (b.parent !== null && typeof b.parent !== 'string')) ||
+    new Set(roster.map(b => b.name)).size !== roster.length) return fail('bone/parent roster requires unique names and explicit string/null parents');
+  const declared = new Map<string, GeometryFile['bones'][number]>(roster.map(b => [String(b.name), { name: String(b.name), parent: b.parent as string | null }]));
+  for (const b of declared.values()) if (b.parent !== null && !declared.has(b.parent)) return fail(`bone/parent roster: parent "${b.parent}" of "${b.name}" is missing`);
+  for (const j of joints) {
+    if (!declared.has(j.bone) || declared.get(j.bone)?.parent !== j.parent || (j.parent !== null && !declared.has(j.parent))) return fail(`bone/parent roster for "${j.bone}" disagrees with source parent ${JSON.stringify(j.parent)}`);
+  }
+  const frames = geometry.frames.filter(record);
+  if (frames.length !== geometry.frames.length || frames.some(f => !Number.isSafeInteger(f.index) || Number(f.index) < 0 || typeof f.time !== 'number' || !Number.isFinite(f.time) || f.time < 0) || new Set(frames.map(f => f.index)).size !== frames.length) return fail('frame cohort requires unique integer indices and finite actual times');
+  if (frames.length !== cohort.frames.length || frames.some((f, i) => f.index !== cohort.frames[i].index)) return fail('frame cohort differs from the actual PNG frame set (including unselected frames)');
+  const frame = frames.find(f => f.index === index);
+  if (!Number.isSafeInteger(index) || !Number.isFinite(time) || frame === undefined || frame.time !== time) return fail(`frame ${index}: raw seam and geometry frame/time differ`);
+  const matrix = (rows: unknown, name: string): SeamMatrix => {
+    const matches = Array.isArray(rows) ? rows.filter(r => record(r) && r.name === name) : [];
+    const row = matches[0];
+    if (matches.length !== 1 || !record(row) || ['a','b','c','d','worldX','worldY'].some(k => typeof row[k] !== 'number' || !Number.isFinite(row[k]))) return fail(`bone "${name}": one matrix with six finite numbers required`);
+    return { a: Number(row.a), b: Number(row.b), c: Number(row.c), d: Number(row.d), worldX: Number(row.worldX), worldY: Number(row.worldY) };
+  };
+  const required = new Set(joints.flatMap(j => j.parent === null ? [j.bone] : [j.bone, j.parent]));
+  for (const name of required) {
+    matrix(geometry.setup.bones, name);
+    for (const f of frames) matrix(f.bones, name);
+  }
+  const setupBones = geometry.setup.bones;
+  return { index, time, joints: joints.map(j => seamJointPose(j.bone, j.parent, j.inherit, matrix(setupBones, j.bone), matrix(frame.bones, j.bone),
+    j.parent === null ? null : matrix(setupBones, j.parent), j.parent === null ? null : matrix(frame.bones, j.parent), j.range, j.rangeReason)) };
+}

package/src/motionseams.ts

@@ -0,0 +1,91 @@
+/** Explicit motion observations; no automatic declaration in check. */
+import type { BoneEntry, CharacterConfig, Segment } from './config.ts';
+import type { Problem } from './errors.ts';
+import { tagOf, type PartRecord } from './parts.ts';
+
+export interface MotionSeamDeclaration {
+  part: string;
+  neighbour: string;
+}
+
+/** Both readers share shape, name, self-pair and unordered uniqueness rules. */
+export function motionSeamProblems(value: unknown, names: ReadonlySet<string>, at: string, code: string): Problem[] {
+  const problems: Problem[] = [];
+  const bad = (object: string, detail: string): void => { problems.push({ code, object, detail }); };
+  if (!Array.isArray(value)) {
+    bad(at, 'requires an array of {part, neighbour} declarations');
+    return problems;
+  }
+  const seen = new Set<string>();
+  value.forEach((row: unknown, i) => {
+    const object = `${at}[${i}]`;
+    if (typeof row !== 'object' || row === null || Array.isArray(row)) { bad(object, 'requires {part, neighbour}'); return; }
+    const r = row as Record<string, unknown>;
+    for (const key of Object.keys(r)) if (key !== 'part' && key !== 'neighbour') bad(`${object}.${key}`, 'is unknown; only part and neighbour are read');
+    for (const key of ['part', 'neighbour']) {
+      if (typeof r[key] !== 'string' || r[key] === '') bad(`${object}.${key}`, 'requires a nonempty output part name');
+      else if (!names.has(r[key])) bad(`${object}.${key}`, `names "${r[key]}", which is no output part; known: ${[...names].join(', ')}`);
+    }
+    if (typeof r.part !== 'string' || typeof r.neighbour !== 'string') return;
+    if (r.part === r.neighbour) bad(object, `names "${r.part}" on both sides; two different parts are required`);
+    const key = JSON.stringify([r.part, r.neighbour].sort());
+    if (seen.has(key)) bad(object, 'duplicates an earlier pair, including reversed order; declare each unordered pair once');
+    seen.add(key);
+  });
+  return problems;
+}
+
+/** Expand only declared links; a miss has no inferred parent. */
+export function motionSeamParents(bones: readonly BoneEntry[]): Map<string, string> {
+  const parents = new Map<string, string>();
+  for (const bone of bones) {
+    if ('name' in bone) parents.set(bone.name, bone.parent);
+    else bone.points.forEach((_, i) => parents.set(`${bone.chain}${i}`, i === 0 ? bone.parent : `${bone.chain}${i - 1}`));
+  }
+  return parents;
+}
+
+/**
+ * Source-bound declaration generator, also callable on a frozen handed config.
+ * A non-limb topwear mesh has exactly two single-bone carriers, a named parent
+ * and child. Every handwear carrier is strictly below the same nearest member
+ * of that pair, either parent or child, and none is a trunk carrier itself.
+ * This proves the declared binding structure, not positive
+ * compiled vertex weights or alpha overlap (the stock seam reader observes that).
+ * No motion keys, thresholds, part spelling or nearest geometry select a pair.
+ */
+export function draftMotionSeams(config: Pick<CharacterConfig, 'bones' | 'meshes' | 'regions' | 'limbs'>, parts: readonly Pick<PartRecord, 'name' | 'from' | 'limb'>[]): MotionSeamDeclaration[] {
+  const parents = motionSeamParents(config.bones);
+  const singles = new Set(config.bones.flatMap(b => 'name' in b ? [b.name] : []));
+  const chains = new Map(config.bones.flatMap(b => 'chain' in b ? [[b.chain, b.points.map((_, i) => `${b.chain}${i}`)] as const] : []));
+  const bound = (part: string): string[] => {
+    const mesh = config.meshes[part];
+    if (mesh !== undefined && 'segments' in mesh) return [...new Set(mesh.segments.flatMap((s: Segment) => typeof s === 'string' ? chains.get(s) ?? [s] : [s[0]]))];
+    const region = config.regions[part];
+    return region === undefined ? [] : [typeof region === 'string' ? region : region.bone];
+  };
+  const consumed = new Set(Object.values(config.limbs ?? {}).flatMap(l => l.segments.map(s => s.from)));
+  const out: MotionSeamDeclaration[] = [];
+  for (const body of parts) {
+    if (body.limb !== undefined || consumed.has(body.name) || tagOf(body.from) !== 'topwear' || config.meshes[body.name] === undefined) continue;
+    const trunk = bound(body.name);
+    if (trunk.length !== 2 || !trunk.every(b => singles.has(b))) continue;
+    const child = trunk.find(b => parents.get(b) === trunk.find(other => other !== b));
+    if (child === undefined) continue;
+    for (const sleeve of parts) {
+      if (sleeve.limb !== undefined || consumed.has(sleeve.name) || !['handwear-r', 'handwear-l'].includes(tagOf(sleeve.from) ?? '')) continue;
+      const carriers = bound(sleeve.name);
+      const nearestTrunk = (bone: string): string | undefined => {
+        const seen = new Set<string>();
+        for (let b: string | undefined = parents.get(bone); b !== undefined && !seen.has(b); b = parents.get(b)) {
+          if (trunk.includes(b)) return b;
+          seen.add(b);
+        }
+        return undefined;
+      };
+      const carrierTrunk = carriers.length === 0 ? undefined : nearestTrunk(carriers[0]);
+      if (carrierTrunk !== undefined && carriers.every(b => parents.has(b) && !trunk.includes(b) && nearestTrunk(b) === carrierTrunk)) out.push({ part: body.name, neighbour: sleeve.name });
+    }
+  }
+  return out;
+}

package/src/parts.ts

@@ -85,6 +85,7 @@
  * a later stage. The writer's key order is fixed, so two runs over the same
  * inputs write the same bytes.
  */
+import { motionSeamProblems, type MotionSeamDeclaration } from './motionseams.ts';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { KEYPOINT_NAMES, type PosePoints } from './skeleton.ts';
@@ -355,6 +356,8 @@ export interface PartsFile {
   scale_rig_per_source: number;
   parts: PartRecord[];
   ghost_px: Record<string, number>;
+  /** Explicit observations only; check never regenerates a removed declaration. */
+  motion_seams?: MotionSeamDeclaration[];
   /** Absent in a `parts.json` the reference wrote; `assemble` always writes it. */
   recomposite?: RecompositeRecord;
   /** Written only under `config.scene` (issue #242): the recomposite was read inside this figure; absent otherwise. */
@@ -397,8 +400,8 @@ export interface SceneRecord {
   figure_mask: string;
 }
 
-const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad', 'alternates'] as const;
-const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad' && k !== 'alternates');
+const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad', 'alternates', 'motion_seams'] as const;
+const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad' && k !== 'alternates' && k !== 'motion_seams');
 export const SINGLE_RUN_PAD_KEYS = ['file_size', 'side', 'left', 'top'] as const;
 export const SCENE_KEYS = ['figure_alpha_above', 'figure_px', 'figure_mask'] as const;
 export const RECOMPOSITE_KEYS = ['mean_abs', 'within_limit', 'within_share', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed', 'holes'] as const;
@@ -475,6 +478,7 @@ export function serializeParts(file: PartsFile): string {
     rig_size: file.rig_size,
     scale_rig_per_source: file.scale_rig_per_source,
     parts: serializePartList(file.parts),
+    ...(file.motion_seams === undefined ? {} : { motion_seams: file.motion_seams.map(({ part, neighbour }) => ({ part, neighbour })) }),
     ghost_px: Object.fromEntries(Object.keys(file.ghost_px).sort().map((k) => [k, file.ghost_px[k]])),
     ...(file.recomposite === undefined ? {} : { recomposite: serializeRecomposite(file.recomposite) }),
     ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
@@ -663,6 +667,10 @@ function checkParts(raw: unknown, path: string): PartsFile {
     }
   }
   if (Array.isArray(o.parts)) checkLimbRecords(o.parts, '', fail);
+  if ('motion_seams' in o) {
+    const names = new Set((Array.isArray(o.parts) ? o.parts : []).flatMap(p => typeof p === 'object' && p !== null && typeof p.name === 'string' ? [p.name] : []));
+    problems.push(...motionSeamProblems(o.motion_seams, names, `${path} motion_seams`, 'PARTS_MOTION_SEAM'));
+  }
   if ('scene' in o) {
     const sc = o.scene;
     if (typeof sc !== 'object' || sc === null || Array.isArray(sc)) fail('PARTS_FIELD_TYPE', `${path} field "scene"`, `is ${show(sc)}; an object is required`);

package/src/propose.ts

@@ -147,6 +147,8 @@ import { type Mask, newMask, newRaster, type Raster } from './raster/types.ts';
 import { npMean, npMedian, npPercentile, pyFixed, pyInt, pyIntList, pyRepr, pyRound, pyStrList } from './pyfmt.ts';
 import type { JointState, RigJoint, RigJoints } from './keypoints.ts';
 import { IDLE_FPS } from './motion.ts';
+import { draftMotionSeams, type MotionSeamDeclaration } from './motionseams.ts';
+export { draftMotionSeams } from './motionseams.ts';
 import { FORK_SMOOTH_MAX_INFLUENCES, influenceFarthest } from './rig.ts';
 import { type Segment as WeightSegment } from './weights.ts';
 import { pyRound as roundTo } from './round.ts';
@@ -278,6 +280,8 @@ export interface Proposal {
   regions: Record<string, string>;
   /** Only under `--keypoints`, where an arm or a leg is drafted from its joints (issue #349): absent otherwise, so a proposal without one is the one written before it. */
   limbs?: Record<string, Limb>;
+  /** Source-bound torso/sleeve observations, written only when the structure resolves. */
+  motion_seams?: MotionSeamDeclaration[];
   motion: {
     duration: number;
     tracks: Array<ProposedSingleTrack | ProposedChainTrack>;
@@ -304,7 +308,7 @@ export interface Proposal {
  * {@link Proposal} key it does not hold, and the selftest's `TY18` holds every
  * paste sentence in the documents to it.
  */
-export const PROPOSAL_CONFIG_SECTIONS = ['bones', 'meshes', 'regions', 'limbs', 'motion', 'constraints', 'turn', 'proposed_rig_scale'] as const satisfies ReadonlyArray<Exclude<keyof Proposal, 'notes'>>;
+export const PROPOSAL_CONFIG_SECTIONS = ['bones', 'meshes', 'regions', 'limbs', 'motion', 'constraints', 'turn', 'motion_seams', 'proposed_rig_scale'] as const satisfies ReadonlyArray<Exclude<keyof Proposal, 'notes'>>;
 
 /** A {@link Proposal} key that is neither `notes` nor in {@link PROPOSAL_CONFIG_SECTIONS}; `never` while the list is whole. */
 type UnlistedProposalSection = Exclude<keyof Proposal, 'notes' | (typeof PROPOSAL_CONFIG_SECTIONS)[number]>;
@@ -661,7 +665,7 @@ export function withTurn(p: Proposal, draft: { turn: TurnSpec | null; notes: str
     }
     turn = { pivot: turn.pivot, depths };
   }
-  return { bones: p.bones, meshes: p.meshes, regions: p.regions, ...(p.limbs === undefined ? {} : { limbs: p.limbs }), motion: p.motion, ...(p.constraints === undefined ? {} : { constraints: p.constraints }), ...(turn === null ? {} : { turn }), proposed_rig_scale: p.proposed_rig_scale, notes: [...p.notes, ...draft.notes] };
+  return { bones: p.bones, meshes: p.meshes, regions: p.regions, ...(p.limbs === undefined ? {} : { limbs: p.limbs }), ...(p.motion_seams === undefined ? {} : { motion_seams: p.motion_seams }), motion: p.motion, ...(p.constraints === undefined ? {} : { constraints: p.constraints }), ...(turn === null ? {} : { turn }), proposed_rig_scale: p.proposed_rig_scale, notes: [...p.notes, ...draft.notes] };
 }
 
 // ---------------------------------------------------------------------------
@@ -3493,8 +3497,10 @@ export function proposeWithBasis(
     meshes[name] = { influence: { cell, radius, across: decl.across, max, shape: decl.shape, ...(held ? { hold_tip: true as const } : {}) }, segments };
   }
   const constrained = clothConstraints.length === 0 ? {} : { constraints: clothConstraints };
+  const motionSeams = draftMotionSeams({ bones, meshes, regions, ...drafted }, P.recs);
+  const observed = motionSeams.length === 0 ? {} : { motion_seams: motionSeams };
   return {
-    proposal: draftPassingChainSigns(P, { bones, meshes, regions, ...drafted, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, ...constrained, proposed_rig_scale: P.rigScale, notes }),
+    proposal: draftPassingChainSigns(P, { bones, meshes, regions, ...drafted, ...observed, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, ...constrained, proposed_rig_scale: P.rigScale, notes }),
     basis: { frame, bones: records },
     draftLint: [...jointsOffArt, ...radii],
   };