spine-rigc 1.9.2 → 1.9.4

package/docs/AUTHORING.md

@@ -210,7 +210,7 @@ What the flags mean:
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
-| `--poser` | `render`, `check` and `explain`: `core` or `spine` — on `render` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core. Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `the "default" skin names` (no `--skin`, and the default skin names a skin-required bone or constraint, each named) · `and no "default" one` (no `--skin`, and skins with none named `default` — spine-core draws nothing there either, so the render stops at `there is nothing to draw`, exit 2, and only `--poser core` prints this refusal) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`). On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1) |
+| `--poser` | `render`, `check` and `explain`: `core` or `spine` — on `render` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`). On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1) |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
@@ -5847,7 +5847,7 @@ Fix A00 and run it again.
 | `A03_REGION_WIDTH_HEIGHT_FINITE` | both | a region loaded `NaN` or a non-positive size — the attachment has no `image` and no `width`/`height`. **SKIP** when the skeleton carries no region attachment |
 | `A04_MESH_TRIANGLES_AND_ENCODING` | both | authored mesh geometry: triangle count not a multiple of 3, an index out of range, or a `vertices` length that disagrees with `uvs` (the weighted/unweighted trap) **SKIP** when the skeleton carries no mesh attachment |
 | `A05_CURVE_ARRAY_LENGTH` | both | a raw `curve` with the wrong number of values, a non-finite number in one, or a curve on a timeline that cannot take one. Four numbers **per value channel**. **SKIP** when no animation carries a timeline at all. Timelines with no `curve` on any key still PASS: every timeline name is checked against the channel table whether or not a curve sits on one |
-| `A06_ATLAS_PAGE_SIZE_MATCHES_PNG` | both ◑ | the atlas `size:` disagrees with the PNG on disk — the message names the ratio it measured on **each** axis and the header that states the same art truthfully, and §0.2 has the whole of it: a runtime maps a region as a fraction of the DECLARED size and never reads the texture's own, so such a page draws, and what it breaks is every reader that addresses the page in texels. A uniform ratio is a `size:`/`scale:` pair away from honest and the message prints it; two ratios are not, because `scale:` carries one number, and the message says so rather than offering a header that would not work. **Or** a region's rectangle is not inside the page it names — rotation honoured, so a region at `rotate: 90` or `270` occupies `height x width` of the page and a region that fits only because it is turned is inside it. The message names the region, the rectangle it occupies, the page and the page's size. That clause is **validity** and runs under both profiles: a rectangle outside its page makes `u2 > 1` and samples whatever the wrap mode returns, and `--atlas-in` already refuses the same rectangle at compile time (§0.2). Under `spine-html` also: `pma`, rotation, and two regions on one page over the same texels — a packed page must be **one part covering it exactly** (the unpacked convention) or a **tiling**, and what that message names is the pair that shares texels. **Or** the page file is not a PNG at all, and then nothing about its size is measured: the message carries the page's path and the size the atlas declares, and names what the file is by its first bytes — one of WebP, JPEG, GIF, KTX, KTX2 by its signature, or no image format rigc recognises, the bytes in hex either way — or calls it **truncated** when it begins as a PNG and runs out before its `IEND` (§0.2). That clause is validity too: nothing in rigc can read such a page back. **SKIP** when the atlas declares no page |
+| `A06_ATLAS_PAGE_SIZE_MATCHES_PNG` | both ◑ | the atlas `size:` disagrees with the PNG on disk — the message names the ratio it measured on **each** axis and the header that states the same art truthfully, and §0.2 has the whole of it: a runtime maps a region as a fraction of the DECLARED size and never reads the texture's own, so such a page draws, and what it breaks is every reader that addresses the page in texels. A uniform ratio is a `size:`/`scale:` pair away from honest and the message prints it; two ratios are not, because `scale:` carries one number, and the message says so rather than offering a header that would not work. **Or** a region's rectangle is not inside the page it names — rotation honoured, so a region at `rotate: 90` or `270` occupies `height x width` of the page and a region that fits only because it is turned is inside it. The message names the region, the rectangle it occupies, the page and the page's size. That clause is **validity** and runs under both profiles: a rectangle outside its page makes `u2 > 1` and samples whatever the wrap mode returns, and `--atlas-in` already refuses the same rectangle at compile time (§0.2). Under `spine-html` also: `pma`, rotation, and two regions on one page over the same texels — a packed page must be **one part covering it exactly** (the unpacked convention) or a **tiling**, and what that message names is the pair that shares texels. **Or** the page file is not a PNG at all, and then nothing about its size is measured: the message carries the page's path and the size the atlas declares, and names what the file is by its first bytes — one of WebP, JPEG, GIF, KTX, KTX2 by its signature, or no image format rigc recognises, the bytes in hex either way — or calls it **truncated** when it begins as a PNG and runs out before its `IEND` (§0.2). That clause is validity too: nothing in rigc can read such a page back. **SKIP** when the atlas declares no page — and, rather than a PASS, when a page's file is **not on disk** and nothing else here failed: that page's size was not measured, so the reason names the pages not read (or says none was, when every file is missing) and points at `A17`, which fails naming each missing file — one missing file is named once, by the rule whose subject it is. With another `A06` failure standing, the missing page is `A17`'s alone |
 | `A07_ATLAS_TEXT_SHAPE` | both | atlas text: a region name with stray whitespace, or a blank line splitting a page block. rigc writes the atlas, so this means a hand-edited file. Three sentences are about blank lines and name three different repairs: `line 1: the file begins with a blank line` (or `with N blank lines` for a run, one finding) is a blank before the first page name — delete it; `line N: the file ends with a blank line` (or `with N blank lines`, one finding) is a blank after the last page block's final line — delete it, since rigc ends the file on one newline; `line N: consecutive blank lines` is two blank lines side by side between the first page and the last — delete one. None of the three is `the last page block declares no region`, which means a page name and its fields with no region after them. rigc writes none of the three: under `--atlas-in` the pack's blank lines are put in rigc's shape on re-emission (§0.2), so any of them means a file rigc did not write, handed to `validate`. ⚠️ An atlas with **no page block at all** — no non-blank line — is not one of those: its subject is absent, so this reports **SKIP** naming the byte count it read, and so do the four rules below whose subject is a page ([#608](https://github.com/firejune/rigc/issues/608)). A rig whose skins need no art writes exactly that file (§3.4), and before #608 this row refused it with two findings naming a page block that was not there. What an empty atlas does **not** excuse is an attachment that wants a region out of it — that is `A08` |
 | `A08_REGION_NAMES_MATCH_ATTACHMENTS` | both | three things, and the message says which: an attachment whose `path` names **no region** of this atlas; a `path` carrying **stray whitespace**, printed quoted so you can see it; an **atlas region name** carrying stray whitespace (`A07` names that same line with its line number). The first two are read off the raw file **before** the loader is asked, so the miss is named here with the skin, the slot, the placeholder and the attachment's own name — the four things `AtlasAttachmentLoader`'s own `Region not found in atlas: <path> (attachment: <name>)` does not carry. There is no `spine-html` clause here — a placeholder is free to differ from the region its `path` names **SKIP** when no attachment names a region *and* the atlas declares none — both of its subjects at once |
 | `A09_ANIMATION_DURATION_MATCHES_SPEC` | both | the loaded duration ≠ the declared one, or the two sides disagree about which animations exist (R7). Asymmetric by design: a frame of slack for an animation that ends early, and none worth the name for a key *past* the declared end, which is the same rule §4.5 states at compile time — held here against a skeleton the compiler never saw. **SKIP** when neither side has an animation at all — a static rig has no duration |
@@ -5858,9 +5858,9 @@ Fix A00 and run it again.
 | `A14_NO_FULL_FRAME_MESH` | renderer | a mesh spans the whole stage — a full-frame canvas that can never dirty-skip. **SKIP** when the skeleton declares no stage (§3.1): there is no full frame to span, and *unmeasured* must not print the same green as *measured and clear* |
 | `A15_IDLE_NO_MESH_BONE_KEYS` | renderer | the `idle` animation keys a bone that drives a mesh, directly or as a control bone. The rule assumes meshes are mostly static — the renderer skips redrawing a mesh nothing moved — so it has three states. **FAIL per bone** when the rig declares nothing: `idle keys bone "X", which drives a mesh — meshes never idle-skip`, and the **first** of those lines, once per run, names the case: `K bone(s) keyed by idle drive meshes; if this idle is meant to deform them (a painting rig), declare invariants.idleDrivesMeshes: { "why": … } in the rig spec — or, where the motion belongs to a pivot above the mesh, key that pivot one link up (FACE.md §3)`. It rides the first finding, so the count of FAIL lines is still the count of bones. **SKIP with the cost** when the rig declares `invariants.idleDrivesMeshes` (§3.7): `declared by the rig ("<why>"): idle keys N bone(s) that drive M mesh attachment(s) totalling V vertices — "a", "b" — and each of those meshes is recomputed on every frame it is shown`. **FAIL on a stale declaration** — declared, and the `idle` keys no mesh-driving bone, carries no bone timeline or does not exist: `the rig "X" declares invariants.idleDrivesMeshes ("…"), but "idle" keys no bone that drives a mesh, so the declaration switches off nothing — remove it`. Otherwise **SKIP** when there is no `idle` animation, or when the one there is carries no bone timeline — a rule whose subject does not exist is unmeasured and not satisfied |
 | `A16_SKELETON_VERSION_4_3` | both | the `skeleton.spine` label is not on the 4.3 line (`4.3`, `4.3.N`, `4.3.N-suffix`) |
-| `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. **SKIP** when the atlas declares no page — as it is for `A06`, `A19` and `A27`; see `A07` |
+| `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. This is the one rule that names a missing page file; `A06` and `A19` SKIP over the page they could not read and point here rather than naming it again. **SKIP** when the atlas declares no page — as it is for `A06`, `A19` and `A27`; see `A07` |
 | `A18_DETERMINISTIC_EMIT` | both | a second compile of the same inputs differed — in `skeleton.json`, `skeleton.atlas` or the model document `skeleton.model.json`, the one named (the document's first differing line with it). That is a compiler bug, not a spec bug — report it |
-| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part cannot draw a transparent pixel, so it would paint a solid rectangle over what is behind it. **The texels decide, on both routes**; the file header is only the fast negative. A file with no alpha channel (colour type 4 or 6) and no `tRNS` chunk has nowhere to keep a clear texel and is refused without being opened, by a sentence that names its colour type — so re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. A file whose header says it **could** be transparent is opened and read until its first texel below full alpha; one clear texel passes, and none is refused in the words the packed route uses for a region, naming the file and what it can hold — `is opaque in every one of its 200x80 texels` … `its file can hold transparency — colour type 6 (truecolour + alpha) carries an alpha channel — and no texel uses it`. Saving as RGBA is not the repair: the runtime draws the texels, not the declaration. On a loose page the file is the part, so the whole decoded image is the rectangle and no atlas coordinate is read. Only the base plate may be opaque, and which image that is is decided once for both routes: the plate the build names — on a cut manifest, the part whose window is the crop — and, only when it names none, an image at least the stage's size. The rig's statement comes first because the two can disagree: a stage stated small enough for an overlay to cover would otherwise exempt that overlay. A rig spec cannot name a base plate, so a stageless rig-spec build, and `validate <dir>` on a stageless skeleton, has nothing to decide it; an opaque part there is refused with *"nothing here decides which image that is: this skeleton declares no stage size to measure one against"* and the two ways to decide it — a `skeleton` stage the plate covers, or a cut manifest (for `validate`, the specs it was built from: `--rig`, `--motion` and the `--manifest`). Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art. ⚠️ **That scan states its verdict over the texels it READ, and never over texels that are not on the page**: a rectangle partly on its page is judged over the part that is on it, and the message carries both counts — `opaque in every one of the 77 texels of its 12x8 rectangle at -1,-1 … the other 19 of the 96 it declares are not on the page and are not measured here`. A rectangle with **no** texel on the page is reported **not measured** by name — the region, its rectangle, the page image's size, and the pointer to `A06`, which is the rule that judges a region's rectangle — and no verdict about opacity is printed at all. ⚠️ **A page whose IMAGE is not the size the atlas declares for it is the same non-measurement for every region on it**, and the clause above does not cover that case: a page rescaled after packing leaves most rectangles partly on it, at coordinates that address a different part of the picture, so a scan would come back with a confident verdict over texels nobody had located — on a two-region pack at a uniform 0.5 an opaque part's failure **disappears**, the scan finding a transparent texel 32 texels away from it. The row names the page's two sizes and points at `A06`, which judges the page grid and prints the header that repairs it (§0.2). It stays a failure rather than becoming a SKIP because a SKIP is per ASSERTION: it would delete the verdicts on every other part of the same page, and an assertion cannot be skipped and failed at once without the report counting it twice. ⚠️ **A page file that cannot be read as PNG at all is the same non-measurement for every part on it**: one row per page naming its parts and pointing at `A06`, which names what the file is. **SKIP** when the atlas declares no page |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part cannot draw a transparent pixel, so it would paint a solid rectangle over what is behind it. **The texels decide, on both routes**; the file header is only the fast negative. A file with no alpha channel (colour type 4 or 6) and no `tRNS` chunk has nowhere to keep a clear texel and is refused without being opened, by a sentence that names its colour type — so re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. A file whose header says it **could** be transparent is opened and read until its first texel below full alpha; one clear texel passes, and none is refused in the words the packed route uses for a region, naming the file and what it can hold — `is opaque in every one of its 200x80 texels` … `its file can hold transparency — colour type 6 (truecolour + alpha) carries an alpha channel — and no texel uses it`. Saving as RGBA is not the repair: the runtime draws the texels, not the declaration. On a loose page the file is the part, so the whole decoded image is the rectangle and no atlas coordinate is read. Only the base plate may be opaque, and which image that is is decided once for both routes: the plate the build names — on a cut manifest, the part whose window is the crop — and, only when it names none, an image at least the stage's size. The rig's statement comes first because the two can disagree: a stage stated small enough for an overlay to cover would otherwise exempt that overlay. A rig spec cannot name a base plate, so a stageless rig-spec build, and `validate <dir>` on a stageless skeleton, has nothing to decide it; an opaque part there is refused with *"nothing here decides which image that is: this skeleton declares no stage size to measure one against"* and the two ways to decide it — a `skeleton` stage the plate covers, or a cut manifest (for `validate`, the specs it was built from: `--rig`, `--motion` and the `--manifest`). Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art. ⚠️ **That scan states its verdict over the texels it READ, and never over texels that are not on the page**: a rectangle partly on its page is judged over the part that is on it, and the message carries both counts — `opaque in every one of the 77 texels of its 12x8 rectangle at -1,-1 … the other 19 of the 96 it declares are not on the page and are not measured here`. A rectangle with **no** texel on the page is reported **not measured** by name — the region, its rectangle, the page image's size, and the pointer to `A06`, which is the rule that judges a region's rectangle — and no verdict about opacity is printed at all. ⚠️ **A page whose IMAGE is not the size the atlas declares for it is the same non-measurement for every region on it**, and the clause above does not cover that case: a page rescaled after packing leaves most rectangles partly on it, at coordinates that address a different part of the picture, so a scan would come back with a confident verdict over texels nobody had located — on a two-region pack at a uniform 0.5 an opaque part's failure **disappears**, the scan finding a transparent texel 32 texels away from it. The row names the page's two sizes and points at `A06`, which judges the page grid and prints the header that repairs it (§0.2). It stays a failure rather than becoming a SKIP because a SKIP is per ASSERTION: it would delete the verdicts on every other part of the same page, and an assertion cannot be skipped and failed at once without the report counting it twice. ⚠️ **A page file that cannot be read as PNG at all is the same non-measurement for every part on it**: one row per page naming its parts and pointing at `A06`, which names what the file is. **SKIP** when the atlas declares no page — and, rather than a PASS, when a page carrying a part has no file on disk and nothing else here failed: that page's parts were not read, so the reason names the pages not read and how many of the pages carrying a part were (or says none was) and points at `A17`, which fails naming each missing file. A missing page holding only the base plate moves nothing here: this rule had no part on it to read |
 | `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. On a rig spec's `"boneIndexing": "raw"` mesh an index out of range or a run that does not decode is refused at compile first (§5.1, issue #917), so here it names a skeleton rigc did not compile. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not. Fix the rig spec's `controls`/`chain`, a `segments` generator's `bones` (its `influence` line names a bone no vertex binds), or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment |
 | `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, a ribbon's entry row, or a contour's outline (which is all of it) is not pinned to its anchor bone at weight 1. **SKIPs** by name on authored or linked geometry and on a `segments` mesh, whose outline is weighted by distance like the rest of it — none of them claims a pinned rim |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, round-trips it through spine-core and named assertions, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/assertions/bodies/a06.ts

@@ -18,12 +18,61 @@ import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
 import { pageFootprint, pageGridSentence } from '../../atlas.ts';
 import { readPngHeader } from '../../png.ts';
 
-export function a06AtlasPageSizeMatchesPng({ fail, skip }: Verdicts, { atlas }: AtlasRegionFacts, input: { atlasDir: string }, policy: boolean): void {
+export function a06AtlasPageSizeMatchesPng({ fail: failed, skip }: Verdicts, { atlas }: AtlasRegionFacts, input: { atlasDir: string }, policy: boolean): void {
   if (!atlas) return skip('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', SKIP_NO_ATLAS);
   if (atlas.pages.length === 0) return skip('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', SKIP_NO_ATLAS_PAGE);
+  // Every sentence this body prints goes through here, so the end of the body
+  // can tell "nothing failed" from "something failed" (issue #1055, below).
+  let failures = 0;
+  const fail = (assertion: string, detail: string): void => {
+    failures++;
+    failed(assertion, detail);
+  };
+  // 🔒 **A page whose file is not on disk is a page whose size was not
+  // measured, and the body says so rather than passing** (issue #1055). Until
+  // this the loop below walked past such a page and the assertion came out
+  // PASS — on a build with every page file deleted, a PASS over a size clause
+  // that had opened nothing, measured on 33 of the 38 recipe-and-profile
+  // pairs of the tree's 19 recipes (the other five failed clauses that read
+  // only the atlas's numbers: overlap and rotation, under `spine-html`). What the body does instead is decided by what `A17` prints on
+  // the same input, so that one missing file is named once, by the rule whose
+  // subject it is: A17 FAILs naming every such file and its path, which keeps
+  // the report red; this body adds no FAIL of its own about the file (a
+  // second naming), and it does not PASS (a certificate over a size nobody
+  // read). It SKIPs with a reason that names the pages it did not read and
+  // points at A17 — `unreadSizes` below, at both of the body's exits.
+  //
+  // ⚠️ Only when nothing else here failed. `skip()` is per assertion, and a
+  // skip beside failures puts A06 in two of the report's buckets (the #705
+  // argument in `a19.ts`); and a FAIL certifies nothing, so the unread page
+  // is A17's alone there. ⚠️ Not the tree's other multi-clause rule either
+  // (`../reasons.ts`, #580: a multi-clause assertion SKIPs only when EVERY
+  // clause had nothing to measure). That rule is about a clause whose subject
+  // list is EMPTY — zero is a count, and a count was measured. A page the
+  // atlas declares is a member of the size clause's subject that is present
+  // and was not read, and the PASS this replaces claimed it was.
+  const unread: string[] = [];
+  const unreadSizes = (): void => {
+    if (failures > 0 || unread.length === 0) return;
+    const total = atlas.pages.length;
+    skip(
+      'A06_ATLAS_PAGE_SIZE_MATCHES_PNG',
+      unread.length === total
+        ? `no page's size was measured: none of the ${total} page file(s) the atlas declares is on disk, which ` +
+            "A17_ATLAS_PAGE_FILES_EXIST names file by file. The clauses that read only the atlas's own numbers found " +
+            "nothing to fail, and that is not a pass while every page's size is unread"
+        : `the size of ${unread.length} of the ${total} page(s) the atlas declares was not measured — ` +
+            `${unread.map((name) => JSON.stringify(name)).join(', ')} — because the file is not on disk, which ` +
+            `A17_ATLAS_PAGE_FILES_EXIST names. The ${total - unread.length} page(s) that were read, and the clauses ` +
+            "that read only the atlas's own numbers, found nothing to fail, and that is not a pass while a page's size is unread",
+    );
+  };
   for (const page of atlas.pages) {
     const abs = resolve(input.atlasDir, page.name);
-    if (!existsSync(abs)) continue; // A17 owns this
+    if (!existsSync(abs)) {
+      unread.push(page.name); // A17 names the file; this body says only that it did not read it
+      continue;
+    }
     // 🔒 **A page that is not a PNG is a named failure, not a throw** (issue
     // #732). The reader's throw used to reach this rule's catch and print as
     // `threw: not a PNG (bad signature)`: the verdict right, the sentence a
@@ -118,7 +167,7 @@ export function a06AtlasPageSizeMatchesPng({ fail, skip }: Verdicts, { atlas }:
       );
     }
   }
-  if (!policy) return;
+  if (!policy) return unreadSizes();
   // ⭐ **One part per page OR a tiling page** (issue #266, follow-up 2). This
   // clause used to be the first alternative alone — every region's UVs
   // `(0,0)-(1,1)` — which is rigc's *unpacked* convention and exactly what
@@ -192,4 +241,5 @@ export function a06AtlasPageSizeMatchesPng({ fail, skip }: Verdicts, { atlas }:
       );
     }
   }
+  unreadSizes();
 }

package/src/assertions/bodies/a13.ts

@@ -3,17 +3,17 @@
  * triangles stay within the budget the rig declares.
  *
  * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
- * are a fact (`../facts/skin_meshes.ts`) rather than the lists `validate()`'s
+ * are a fact (`../facts/mesh_attachments.ts`) rather than the lists `validate()`'s
  * prelude filled from spine-core's loaded skins, and the rig info is the
  * caller's. Why the two budgets come from the rig and never from here stays
  * above the `check` call in `validate()`.
  */
 import type { Verdicts } from '../harness.ts';
-import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
 import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
 import type { RigInfo } from '../../types.ts';
 
-export function a13MeshBudget({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts, input: { rig?: RigInfo }): void {
+export function a13MeshBudget({ fail, skip }: Verdicts, { meshes }: Pick<MeshFacts, 'meshes'>, input: { rig?: RigInfo }): void {
   const meshAttachments = meshes;
   const meshSlots = new Set(meshes.map((mesh) => mesh.slot));
   const slotBudget = input.rig?.meshSlotBudget ?? null;

package/src/assertions/bodies/a14.ts

@@ -3,15 +3,15 @@
  * stage.
  *
  * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
- * and the stage are facts (`../facts/skin_meshes.ts`, `../facts/stage.ts`)
+ * and the stage are facts (`../facts/mesh_attachments.ts`, `../facts/stage.ts`)
  * rather than spine-core's loaded skins and skeleton header. The `check` call
  * stays in `validate()`.
  */
 import type { Verdicts } from '../harness.ts';
-import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
 import type { StageFacts } from '../facts/stage.ts';
 
-export function a14NoFullFrameMesh({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts, stage: StageFacts): void {
+export function a14NoFullFrameMesh({ fail, skip }: Verdicts, { meshes }: Pick<MeshFacts, 'meshes'>, stage: StageFacts): void {
   const meshAttachments = meshes;
   const stageW = stage.width || 0;
   const stageH = stage.height || 0;

package/src/assertions/bodies/a15.ts

@@ -3,7 +3,7 @@
  * drives a mesh, unless the rig declares that its idle deforms them.
  *
  * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
- * and the bones that drive them are a fact (`../facts/skin_meshes.ts`) rather
+ * and the bones that drive them are a fact (`../facts/mesh_attachments.ts`, the bones derived from the weights by `weightBonesOf`) rather
  * than spine-core's loaded skins and the weight run decoded here, the bones
  * `idle` keys are a fact (`../facts/animated_bones.ts`) rather than the raw
  * JSON, and the rig info is the caller's. Why the rule assumes meshes are
@@ -11,11 +11,11 @@
  * `check` call in `validate()`.
  */
 import type { Verdicts } from '../harness.ts';
-import type { MeshEntry, SkinMeshFacts } from '../facts/skin_meshes.ts';
+import { weightBonesOf, type MeshEntry, type MeshFacts } from '../facts/mesh_attachments.ts';
 import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
 import type { RigInfo } from '../../types.ts';
 
-export function a15IdleNoMeshBoneKeys({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts, animated: AnimatedBoneFacts, input: { rig?: RigInfo }): void {
+export function a15IdleNoMeshBoneKeys({ fail, skip }: Verdicts, facts: MeshFacts, animated: AnimatedBoneFacts, input: { rig?: RigInfo }): void {
   const A15 = 'A15_IDLE_NO_MESH_BONE_KEYS';
   /**
    * Every mesh attachment, loaded, with the bones that drive it — its slot's
@@ -25,9 +25,9 @@ export function a15IdleNoMeshBoneKeys({ fail, skip }: Verdicts, { meshes }: Skin
    * actually dirties the canvas every frame.
    */
   const meshDrivers: Array<{ mesh: MeshEntry; bones: Set<string> }> = [];
-  for (const mesh of meshes) {
+  for (const mesh of facts.meshes) {
     const bones = new Set<string>([mesh.slotBone]);
-    for (const bone of mesh.weightBones) bones.add(bone);
+    for (const bone of weightBonesOf(facts, mesh)) bones.add(bone);
     meshDrivers.push({ mesh, bones });
   }
   const meshBoneNames = new Set<string>();

package/src/assertions/bodies/a19.ts

@@ -21,13 +21,20 @@ import { colourTypeName, readPngHeader } from '../../png.ts';
 import { readPlate } from '../../../tools/plate.ts';
 import type { RigInfo } from '../../types.ts';
 
-export function a19OverlayPngsHaveAlpha({ fail, skip }: Verdicts, { atlas }: AtlasRegionFacts, stage: StageFacts, { regionAttachments }: Pick<SkinEntryFacts, 'regionAttachments'>, input: { atlasDir: string; rig?: RigInfo }): void {
+export function a19OverlayPngsHaveAlpha({ fail: failed, skip }: Verdicts, { atlas }: AtlasRegionFacts, stage: StageFacts, { regionAttachments }: Pick<SkinEntryFacts, 'regionAttachments'>, input: { atlasDir: string; rig?: RigInfo }): void {
   // A SKIP for the same reason A06's is (#568). This one is invisible under
   // `spine`, where the profile excludes the rule before its body runs — and
   // that is exactly why it was worth finding: `--profile spine-html` reported
   // it, and A27 below, green on an atlas nothing had read.
   if (!atlas) return skip('A19_OVERLAY_PNGS_HAVE_ALPHA', SKIP_NO_ATLAS);
   if (atlas.pages.length === 0) return skip('A19_OVERLAY_PNGS_HAVE_ALPHA', SKIP_NO_ATLAS_PAGE);
+  // Every sentence this body prints goes through here, so its end can tell
+  // "nothing failed" from "something failed" (issue #1055, at the page loop).
+  let failures = 0;
+  const fail = (assertion: string, detail: string): void => {
+    failures++;
+    failed(assertion, detail);
+  };
   const stageW = stage.width ?? 0;
   const stageH = stage.height ?? 0;
   // 🔒 **Which image is the base plate is decided ONCE, and the rig's own
@@ -96,10 +103,34 @@ export function a19OverlayPngsHaveAlpha({ fail, skip }: Verdicts, { atlas }: Atl
     if (on) on.push(region);
     else sharedPages.set(region.page.name, [region]);
   }
+  // 🔒 **A page whose file is not on disk is a page whose parts were not
+  // read, and the body says so rather than passing** (issue #1055). Until
+  // this the loop walked past such a page, and on a build with every page
+  // file deleted the assertion printed PASS on all 19 of the tree's recipes
+  // under `spine-html` having opened nothing. The rule for what it prints
+  // instead is `a06.ts`'s, read off what `A17` prints on the same input: A17
+  // FAILs naming each missing file, so the report is already red and the file
+  // already named; a FAIL here would be the second naming and a PASS a
+  // certificate over alpha nobody read. So the body SKIPs, naming the pages it
+  // did not read and pointing at A17 — only when it failed nothing else,
+  // because `skip()` is per assertion (#705's argument, below) and a FAIL
+  // certifies nothing.
+  //
+  // ⚠️ A page counts only when it carries a part this rule judges, by the
+  // predicate the non-PNG branch below uses: a missing page holding nothing
+  // but the base plate had nothing for this rule to read either way, so it
+  // moves nothing here (the size it was not measured at is `A06`'s to say).
+  let pagesWithParts = 0;
+  const unread: string[] = [];
   for (const page of atlas.pages) {
     const abs = resolve(input.atlasDir, page.name);
-    if (!existsSync(abs)) continue;
     const on = sharedPages.get(page.name) ?? [];
+    const carriesPart = on.length > 1 ? on.some((region) => !baseRegions.has(region.name)) : !basePages.has(page.name);
+    if (carriesPart) pagesWithParts++;
+    if (!existsSync(abs)) {
+      if (carriesPart) unread.push(page.name); // A17 names the file; this body says only that it did not read it
+      continue;
+    }
     // 🔒 **A page that is not a PNG is a non-measurement for every part on
     // it** (issue #732), stated the way #705's and #715's are: a FAIL naming
     // what was not read, because `skip()` is per assertion and would delete
@@ -292,4 +323,15 @@ export function a19OverlayPngsHaveAlpha({ fail, skip }: Verdicts, { atlas }: Atl
         'spine does not run this check.',
     );
   }
+  if (failures > 0 || unread.length === 0) return;
+  skip(
+    'A19_OVERLAY_PNGS_HAVE_ALPHA',
+    unread.length === pagesWithParts
+      ? `no part's alpha was read: none of the ${pagesWithParts} page file(s) carrying a part is on disk, which ` +
+          'A17_ATLAS_PAGE_FILES_EXIST names file by file, and that is not a pass while every part is unread'
+      : `${unread.length} of the ${pagesWithParts} page(s) carrying a part were not read — ` +
+          `${unread.map((name) => JSON.stringify(name)).join(', ')} — because the file is not on disk, which ` +
+          `A17_ATLAS_PAGE_FILES_EXIST names. Every part on the ${pagesWithParts - unread.length} page(s) that were ` +
+          "read can draw a transparent pixel, and that is not a pass while a part's alpha is unread",
+  );
 }

package/src/assertions/bodies/a22.ts

@@ -3,14 +3,14 @@
  * in the unit square, one pair per vertex.
  *
  * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
- * are a fact (`../facts/skin_meshes.ts`). The `check` call stays in
+ * are a fact (`../facts/mesh_attachments.ts`). The `check` call stays in
  * `validate()`.
  */
 import type { Verdicts } from '../harness.ts';
-import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
 import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
 
-export function a22MeshUvsInUnitRange({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts): void {
+export function a22MeshUvsInUnitRange({ fail, skip }: Verdicts, { meshes }: Pick<MeshFacts, 'meshes'>): void {
   const meshAttachments = meshes;
   if (meshAttachments.length === 0) return skip('A22_MESH_UVS_IN_UNIT_RANGE', SKIP_NO_MESH_ATTACHMENT);
   for (const mesh of meshAttachments) {

package/src/assertions/facts/animated_bones.ts

@@ -11,8 +11,10 @@
  * rather than folding the first two into an empty list.
  *
  * The order is the file's: A15 prints one line per keyed bone in it. The file
- * keys an animation's bones in the order the emitter writes the model's
- * (`emitAnimation`), which is the document's own list.
+ * keys an animation's bones in an object filled in the order the emitter
+ * writes the model's (`emitAnimation`), which is the document's own list — so
+ * an array-index bone name (`5`, `10`) is listed first whatever its place in
+ * that list (issue #1039), and the model side reads it through `keyedOrder`.
  *
  * Links nothing from the runtime: `validate()` reads it off the skeleton JSON
  * as A15 always did, and the model side off the document

package/src/assertions/facts/mesh_attachments.ts

@@ -1,8 +1,16 @@
 /**
- * The mesh attachments, as the bodies that read their geometry and their
- * weights see them (issue #1025, step 4c of #380) — the census's F07 (vertex
- * data), F08 (mesh geometry) and F10 (the linked-mesh join), for A04, A20,
- * A21, A28 and the mesh half of A23.
+ * The mesh attachments, as every body that reads a mesh sees them (issue
+ * #1025, step 4c of #380) — the census's F03, F05, F07 (vertex data), F08
+ * (mesh geometry) and F10 (the linked-mesh join), for A04, A13, A14, A15, A20,
+ * A21, A22, A28 and the mesh half of A23.
+ *
+ * ⭐ **One family** (issue #1054). Cut 4c-1 stated the meshes for A13, A14,
+ * A15 and A22 as a family of their own (`SkinMeshFacts`) and cut 4c-2 stated
+ * them again here; the two walked the same entries in the same order and
+ * agreed on every field they shared, and two families of one fact are two
+ * places for a supplier to disagree with itself. The size the budget and
+ * canvas rules read joined this one, and the bones a mesh's weights name are
+ * derived from `weights` (`weightBonesOf`) rather than stated beside them.
  *
  * ⭐ **The order is the file's**, as `./skin_entries.ts` states it: every
  * skin in the file's order, and within a skin the entries slot by slot in the
@@ -56,6 +64,9 @@ export interface MeshEntry {
   readonly regionUVs: readonly number[];
   /** `hullLength`: two numbers per hull vertex. */
   readonly hullLength: number;
+  /** Its `width` and `height` — a link's are its source's, which the runtime's `setSourceMesh` writes over the link's own. */
+  readonly width: number;
+  readonly height: number;
   /** Per vertex its influences, in order — or `null` for an unweighted mesh. */
   readonly weights: ReadonlyArray<readonly MeshBinding[]> | null;
   /** The kept clauses' findings about this mesh's vertex run (`A04`'s encoding rules), in order; never on the model side. */
@@ -69,3 +80,21 @@ export interface MeshFacts {
   /** Every mesh attachment of every skin, in the file's walk order. */
   readonly meshes: readonly MeshEntry[];
 }
+
+/**
+ * Every bone a mesh's weights name, in the weight run's order (repeats kept),
+ * by name — empty for an unweighted mesh. A binding whose index the roster
+ * does not hold names nothing here: that index is the encoding's fault, which
+ * `A20`'s kept clause names (`MeshBinding.encoding`), and no bone drives the
+ * mesh through it.
+ */
+export function weightBonesOf(facts: Pick<MeshFacts, 'bones'>, mesh: Pick<MeshEntry, 'weights'>): string[] {
+  const names: string[] = [];
+  for (const vertex of mesh.weights ?? []) {
+    for (const binding of vertex) {
+      const name = facts.bones[binding.bone];
+      if (name !== undefined) names.push(name);
+    }
+  }
+  return names;
+}

package/src/assertions/model/animated_bones.ts

@@ -5,13 +5,21 @@
  * The document writes each animation's `bones` as a list in the model's map
  * order, and the emitter writes the Spine file's `bones` group from that same
  * map, entry for entry, leaving the group out when it is empty
- * (`emitAnimation`'s `if (animation.bones.size)`) — so the list's order is the
- * file's, an empty list is a file with no `bones` group, and an animation the
- * document does not hold is one the file does not key. The first animation of
- * a name answers, as the file's object would hold only one.
+ * (`emitAnimation`'s `if (animation.bones.size)`) — so an empty list is a file
+ * with no `bones` group, and an animation the document does not hold is one the
+ * file does not key. The first animation of a name answers, as the file's
+ * object would hold only one.
+ *
+ * 🔢 **The order is `keyedOrder` over the list's, not the list's** (issue
+ * #1039). The group is an object keyed by bone name, so the file lists an
+ * array-index name (`5`, `10`) first whatever order the emitter filled it in —
+ * measured on a walk whose tracks key `-a, 5, 2b, 10, …`: the document lists
+ * that, the file and spine-core `5, 10, -a, 2b, …`, and A15 prints one line per
+ * keyed bone in the file's order.
  *
  * Links nothing from the runtime.
  */
+import { keyedOrder } from '../../compile.ts';
 import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
 import { isObj } from '../values.ts';
 import type { ReadDocument } from './parse.ts';
@@ -24,7 +32,7 @@ export function modelAnimatedBones(read: ReadDocument): AnimatedBoneFacts {
       if (animation === undefined) return undefined;
       const bones = Array.isArray(animation.bones) ? animation.bones.filter(isObj) : [];
       if (bones.length === 0) return null;
-      return bones.map((bone) => String(bone.name));
+      return keyedOrder(bones.map((bone) => String(bone.name)));
     },
   };
 }

package/src/assertions/model/bone_timelines.ts

@@ -6,9 +6,11 @@
  * `./slot_colour.ts`), over the `bones` group: the animations put in the
  * file's order by `editorAnimationOrder` (`src/compile.ts`, the function the
  * emitter is handed), each animation's bones and their timelines laid out as
- * the file lays them (`animations.<name>.bones.<bone>.<timeline> = keys`, in
- * the document's order, which is the order `emitAnimation` writes the model's
- * map in), and the whole handed to the emitter's own `withoutParserDefaults`
+ * the file lays them (`animations.<name>.bones.<bone>.<timeline> = keys`,
+ * filled in the document's order, which is the order `emitAnimation` writes
+ * the model's map in — and read back out of that object, so an array-index
+ * bone name comes first as it does in the file: issue #1039 measured this
+ * reader already walking the file's order), and the whole handed to the emitter's own `withoutParserDefaults`
  * and `inEditorKeyOrder` (`src/keyorder.ts`) — so a key field the emitter
  * leaves out at the parser's default (`time: 0`, a translate key's `y: 0`) is
  * left out here too, and a body printing a key's `time` prints what it prints

package/src/assertions/model/declared.ts

@@ -0,0 +1,127 @@
+/**
+ * What the build declared, read off the document (issue #1054): the rig info
+ * the archetype and declaration rules read, and each animation's declared
+ * duration, which A09 holds the keys against.
+ *
+ * ⭐ **The document is the one source, on every spec it is read at.** A
+ * `rigc-compiled/3`, `/2` and `/1` document all carry the `rig` section
+ * (`CompileResult.rig` as `modelDocument` writes it) and every animation's
+ * `duration` (the motion spec's, which `readModel` reads as
+ * `CoreAnimationTimelines.declared` and refuses when it is not a finite
+ * number). Until this module the model side took both from its caller, as
+ * `validate()` does, and its verdict moved with what the caller handed it:
+ * measured over the 19 recipes with the document's own values left out, A09
+ * read SKIP on 38 of 38 cells, ten rules read their bare-directory SKIP, and
+ * A20 read FAIL on 7 cells where it reads PASS — without the rig every mesh is
+ * judged a generated ring (`meshKindOf`), so an authored mesh fails the
+ * generator policy. A value the document states is read from the document,
+ * and the same value given beside it is refused by name
+ * (`refuseDeclaredBeside`), as issue #1026 made the stage and `pma`
+ * (`./given.ts`).
+ *
+ * 🔒 **The rig section is read field by field, never cast.** A body reads a
+ * declaration only through `modelRigInfo`, which refuses by its path a field
+ * that is missing, of the wrong type or not one the writer writes — the
+ * model side's parse runs it (`./parse.ts`, `A00_MODEL_READ`), so a document
+ * whose declarations are malformed is refused where the reader refuses, and
+ * never judged against a guess.
+ *
+ * Links nothing from the runtime.
+ */
+import type { MeshKind } from '../../mesh.ts';
+import type { RigInfo } from '../../types.ts';
+import { isObj } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+/** A rig section the model side cannot read as rig info: every problem, each by its path, in one sentence. */
+export class DeclaredInputError extends Error {}
+
+/** The mesh kinds a rig's `meshKinds` may name: the generators' and `authored`. */
+const MESH_KINDS = ['ring', 'ribbon', 'contour', 'grid', 'segments', 'authored'] as const satisfies ReadonlyArray<MeshKind | 'authored'>;
+// Every kind the type names is in the list, or this line does not type-check.
+const MESH_KINDS_COMPLETE: Exclude<MeshKind | 'authored', (typeof MESH_KINDS)[number]> extends never ? true : false = true;
+void MESH_KINDS_COMPLETE;
+
+type Check = (value: unknown, at: string, problems: string[]) => void;
+const say = (problems: string[], at: string, value: unknown, what: string): void => void problems.push(`${at} is ${JSON.stringify(value) ?? 'absent'}, not ${what}`);
+const str: Check = (v, at, p) => (typeof v === 'string' ? undefined : say(p, at, v, 'a string'));
+const bool: Check = (v, at, p) => (typeof v === 'boolean' ? undefined : say(p, at, v, 'true or false'));
+const num: Check = (v, at, p) => (typeof v === 'number' && Number.isFinite(v) ? undefined : say(p, at, v, 'a finite number'));
+const nullable = (inner: Check): Check => (v, at, p) => (v === null ? undefined : inner(v, at, p));
+const list = (inner: Check, length?: number): Check => (v, at, p) => {
+  if (!Array.isArray(v) || (length !== undefined && v.length !== length)) return say(p, at, v, length === undefined ? 'a list' : `a list of ${length}`);
+  v.forEach((x, i) => inner(x, `${at}[${i}]`, p));
+};
+const record = (inner: Check): Check => (v, at, p) => {
+  if (!isObj(v)) return say(p, at, v, 'an object');
+  for (const [k, x] of Object.entries(v)) inner(x, `${at}.${k}`, p);
+};
+const oneOf = (words: readonly string[]): Check => (v, at, p) => (typeof v === 'string' && words.includes(v) ? undefined : say(p, at, v, `one of ${words.join(', ')}`));
+const shape = (fields: Readonly<Record<string, Check>>): Check => (v, at, p) => {
+  if (!isObj(v)) return say(p, at, v, 'an object');
+  for (const [k, check] of Object.entries(fields)) check(v[k], `${at}.${k}`, p);
+  for (const k of Object.keys(v)) if (!(k in fields)) p.push(`${at}.${k} is not a field the rig section has`);
+};
+
+/** The rig section's fields, as `RigInfo` declares them and the writer writes every one — each required, none defaulted. */
+const RIG_FIELDS: Readonly<Record<keyof RigInfo, Check>> = {
+  archetype: str,
+  axisBone: nullable(str),
+  axisSubtree: list(str),
+  detached: list(list(str, 2)),
+  slotOrder: nullable(list(str)),
+  meshKinds: record(oneOf(MESH_KINDS)),
+  meshDeclaredBones: record(list(str)),
+  meshSoftBones: record(str),
+  deformMayFold: list(str),
+  editorRoundTrip: bool,
+  consumerDrivenMix: list(shape({ type: oneOf(['ik', 'transform']), constraint: str, why: str })),
+  idleDrivesMeshes: nullable(str),
+  basePlates: list(str),
+  meshSlotBudget: nullable(num),
+  meshTriangleBudget: nullable(num),
+  contactDepth: nullable(num),
+  capContainmentCeiling: nullable(num),
+  massBone: nullable(str),
+  inwardUnit: nullable(list(num, 2)),
+};
+
+/** Every problem with the document's `rig` section, each by its path — empty when it reads as rig info. */
+export function rigSectionProblems(json: Readonly<Record<string, unknown>>): string[] {
+  const problems: string[] = [];
+  shape(RIG_FIELDS)(json.rig, 'rig', problems);
+  return problems;
+}
+
+/** The rig info the document declares — its `rig` section, read field by field; a section that does not read is refused by its paths. */
+export function modelRigInfo(read: ReadDocument): RigInfo {
+  const problems = rigSectionProblems(read.json);
+  if (problems.length > 0) throw new DeclaredInputError(`the document's rig section does not read as rig info: ${problems.length} problem(s): ${problems.join('; ')}`);
+  return read.json.rig as RigInfo;
+}
+
+/**
+ * Each animation's declared duration, as the document states it and the core
+ * reads it (`CoreAnimationTimelines.declared`), keyed in the document's order —
+ * the motion spec's, the order `CompileResult.declaredDurations` is filled in.
+ */
+export function modelDeclaredDurations(read: ReadDocument): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const anim of read.doc.animations) out[anim.name] = anim.timelines.declared;
+  return out;
+}
+
+/** What a caller may not give beside a document, because every document states it. */
+export type DeclaredValue = 'rig' | 'declaredDurations';
+
+/** The sentence a value given beside the document is refused with. */
+export function declaredBesideRefusal(spec: string, what: DeclaredValue): string {
+  const given = what === 'rig' ? 'the rig info' : 'the declared durations';
+  const stated = what === 'rig' ? 'states it itself in its rig section' : "states each animation's duration itself";
+  return `the caller gave ${given} beside a ${spec} document, which ${stated} (issue #1054); a second source for one fact is refused rather than one of them silently read`;
+}
+
+/** A caller's value beside a document that states it, refused by name. */
+export function refuseDeclaredBeside(read: ReadDocument, input: { rig?: unknown; declaredDurations?: unknown }, what: DeclaredValue): void {
+  if (input[what] !== undefined) throw new Error(declaredBesideRefusal(read.doc.spec, what));
+}