spine-rigc 0.26.0 → 0.27.0

package/README.md

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

package/docs/AUTHORING.md

@@ -169,7 +169,7 @@ What the flags mean:
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
-| `--profile` | `spine` = the 29 validity rules (**the default**) · `spine-html` = all 44, opt-in |
+| `--profile` | `spine` = the 30 validity rules (**the default**) · `spine-html` = all 45, opt-in |
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview`, and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote`, so is a name that only *some* candidates have |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
@@ -500,6 +500,23 @@ the first:
 | `JUDGE` | the skeleton cannot answer and somebody has to: the stage, and each animation's duration |
 | `LOSS` | the skeleton's spelling and rigc's differ, on purpose, and the line says how. A path attachment's `lengths` is the one that matters — it is `PathConstraint`'s own four-sample measurement rather than an arc length (#560), so a transcribed one would freeze whatever produced the source. The header ones are cheaper: `HEADER_BOOKKEEPING` for a field the spec has no home for, `HEADER_REDERIVED` for the version string, `HEADER_ORIGIN` for an origin the source left to the format and the rebuild writes out (#622) |
 
+⛔ **It reads one generation of the format, and a file from another one ends loud.**
+Spine data is locked to the generation that exported it and a mismatch does not
+throw: 4.3 takes constraints from the top-level `constraints` array alone, so a
+4.0–4.2 file's `ik`/`transform`/`path`/`physics` arrays load as nothing at all — 1,302
+shipped skeletons parsed on a 4.3 runtime and loaded 0 of 8,672 constraints
+([#706](https://github.com/firejune/rigc/issues/706) row 1). So `ingest` reads
+`skeleton.spine` before it reads a field of the file. A file from another generation is
+a `BLOCK GENERATION_UNSUPPORTED` naming the generation, the string it was read from,
+and what a 4.3 reader loses **on that file**: the constraints parked in those arrays
+counted by kind, the bones carrying 4.2's `transform` where 4.3 spells `inherit`, and
+the physics constraints omitting `inertia`/`damping`, whose default is not the same
+number in the two. A label naming no generation rigc knows — or a header stating none —
+is a `BLOCK GENERATION_UNKNOWN`, never rounded to the nearest: a catalog that rounded
+handed 19 skeletons labelled `3.8.99` a 4.2 runtime and every one of them posed as NaN
+(row 7). Reading a file with *that generation's own* defaults is #706's item 2 and is
+not in this tool — re-export as 4.3, or transcribe by hand ([INGEST.md](INGEST.md) §2).
+
 📝 **Do not delete the `note`.** Both written specs carry one saying the file is
 decompiled and naming the skeleton it came from. A decompiled spec is
 indistinguishable from an authored one by inspection, every gate here calls it green —
@@ -1220,7 +1237,12 @@ the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`). Measured
 a forged skeleton — a link declaring 5 uvs, 3 triangles, `hull: 5` and
 `edges: [0, 2]` beside a 4-vertex source loaded with the **source's** 8-long
 `worldVerticesLength`, 6 triangles, `hullLength` 8 and 10 edges. Nothing the author
-wrote reached anything and nothing said so.
+wrote reached anything and nothing said so. ⇒ The same fact is held against a
+skeleton rigc did **not** write, where the compiler never sees the spec:
+`A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` (§5.2) names the attachment, the
+keys and whose geometry is drawn instead, and `ingest` reports one as
+`ATTACHMENT_LINK_GEOMETRY` before dropping it
+([INGEST §2.0](INGEST.md)) — [#710](https://github.com/firejune/rigc/issues/710).
 
 🚫 **A chain is refused, and so is a link to itself.** A `source` that names
 another linked mesh resolves in the order the file was read: measured through
@@ -4769,7 +4791,7 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A16_SKELETON_VERSION_4_3` | both | the `skeleton.spine` label is not on the 4.3 line (`4.3`, `4.3.N`, `4.3.N-suffix`) |
 | `A17_ATLAS_PAGE_FILES_EXIST` | both | a page the atlas declares is not a file. Check `--images` and `--out`. **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) — as it is for `A06`, `A19` and `A27`; see `A07` ([#608](https://github.com/firejune/rigc/issues/608)) |
 | `A18_DETERMINISTIC_EMIT` | both | a second compile of the same inputs differed. That is a compiler bug, not a spec bug — report it |
-| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art ([#266](https://github.com/firejune/rigc/issues/266)) **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) |
+| `A19_OVERLAY_PNGS_HAVE_ALPHA` | renderer | an overlay part image can never be transparent: no alpha channel (colour type 4 or 6) and no `tRNS` chunk either, so it would paint a solid rectangle over what is behind it. Re-export it as RGBA, or as an indexed / greyscale PNG that keeps its `tRNS`. Only the full-stage base plate may be opaque. Indexed-with-`tRNS` — the usual output of ImageMagick, "Export as PNG-8", GIMP's indexed mode, aseprite and pngquant — **passes**: it is transparent art. On a **shared** page the question is asked per REGION over the decoded page rather than per file, because a packed page's own file all but always declares transparency — its gutter is transparent — and the file-level question would then be answered by the packing rather than by the art ([#266](https://github.com/firejune/rigc/issues/266)). ⚠️ **That scan states its verdict over the texels it READ, and never over texels that are not on the page** ([#705](https://github.com/firejune/rigc/issues/705)): a rectangle partly on its page is judged over the part that is on it, and the message carries both counts — `opaque in every one of the 77 texels of its 12x8 rectangle at -1,-1 … the other 19 of the 96 it declares are not on the page and are not measured here`. A rectangle with **no** texel on the page is reported **not measured** by name — the region, its rectangle, the page image's size, and the pointer to `A06`, which is the rule that judges a region's rectangle — and no verdict about opacity is printed at all. It stays a failure rather than becoming a SKIP because a SKIP is per ASSERTION: it would delete the verdicts on every other part of the same page, and an assertion cannot be skipped and failed at once without the report counting it twice. Before #705 the walk was silent about its own reach, so a part nobody could read printed *opaque in every one of its 12x8 texels* over zero of them, which is a refusal pointing at the wrong file: the art it names may be transparent, and the repair is the rectangle in `A06`'s row above **SKIP** when the atlas declares no page ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A20_MESH_WEIGHTS_COHERENT` | both ◑ | a weighted vertex with no bone, a negative weight, a bone index out of range, or weights that do not sum to 1. Under `spine-html` also: an unweighted mesh, a binding at weight 0, or **a bone the mesh declares that no vertex binds** — `mesh "x" declares bone "grip_b" and none of its 25 vertices binds it; the weights reference "box", "grip_a"`. Those three are one sentence about rigc's own generators: the bone set a generated mesh declares is the bone set its weights reference, so a `controls` or `chain` name that moves nothing is a defect where a foreign mesh's is not ([#684](https://github.com/firejune/rigc/issues/684)). Fix the rig spec's `controls`/`chain`, or the manifest's `control_bones`. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
 | `A21_MESH_RIM_PINNED` | archetype | a generated ring's rim, a ribbon's entry row, or a contour's outline (which is all of it) is not pinned to its anchor bone at weight 1 |
 | `A22_MESH_UVS_IN_UNIT_RANGE` | both | a mesh UV outside its region, or a UV array that disagrees with the vertex count. **SKIP** when the skeleton carries no mesh attachment ([#580](https://github.com/firejune/rigc/issues/580)) |
@@ -4794,6 +4816,7 @@ Fix A00 and run it again ([#568](https://github.com/firejune/rigc/issues/568)).
 | `A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP` | both | a physics constraint driving a component the **Spine editor** cannot hold, on a rig that declared `invariants.editorRoundTrip` (§3.7). The editor's physics model holds `x` and `y` only, with no cap on how many at once, so a constraint driving `rotate`, `scaleX` or `shearX` is imported, exported and handed back driving **nothing** — measured over three rigs and twelve constraints with the predictions written first ([#540](https://github.com/firejune/rigc/issues/540)). The detail names the constraint and each component. ⚠️ rigc's own output is correct — every runtime plays a rotation jiggle — so this is opt-in and the default is *not* silence: on a rig that declares nothing it **SKIPs**, and the SKIP names the constraint and the component anyway, so an author learns without having asked. Fix by driving the constraint in `x`/`y`, or by dropping the declaration if the rig never goes near the editor. Disjoint from `A23_PHYSICS_CONSTRAINT_EFFECTIVE` by construction: A23 refuses an **empty** driven set, which is what comes back from the editor, and this refuses a non-empty one that will not survive going in. **SKIP** also when the rig declares the editor and carries no physics constraint at all |
 | `A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER` | both | a slider whose animation keys a property of a constraint **at or before it** in `constraints` (§3.5.2) — a slider's `mix` or `time`, an ik or transform mix, a path `position`, `spacing` or `mix`, any physics value. That array is the update order for every kind, and each constraint reads its own applied pose when its turn comes — `Slider.update` takes `mix` as the alpha it applies with and `time` as the time it applies at, `PhysicsConstraint.update` returns on `mix` 0 before reading the rest — so the key lands after the only read of it and `Posed.resetConstrained` discards it before the next frame: what the driven constraint drives is dead at every position of the driving dial, although its pose still holds the number ([#658](https://github.com/firejune/rigc/issues/658), [#665](https://github.com/firejune/rigc/issues/665)). The detail names the slider, the driven constraint with its kind, both array indices, the property, the runtime class whose `update` reads it, and the animation the key sits in. Fix by moving the driver earlier, or by keying that property from a slider that already is. **The two indices equal is the same failure**: a slider cannot key its own `mix` or `time`, and one muted at setup that keys its own `mix` up never applies anything at all — `A37` is silent there, because it asks whether *an* animation keys the mix and not which one. **Two shapes it deliberately leaves out**, both measured: a `physics` `reset` key, which fires on a crossed frame time and so never fires from a slider at all, in either order — the reorder would repair nothing; and a physics timeline naming no constraint, which is every physics constraint declaring that property global and IS refused for the ones already run. Disjoint from `A40` by construction: `A40` asks who writes a shared property last and excludes every slider whose `mix` is keyed, this asks whether anything reads what was written. **SKIP** when the skeleton declares no slider, and when no slider's animation keys a constraint property — that SKIP names any `reset` keys it found — a pass means a driver and a driven were compared |
 | `A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN` | both | a slot's `dark` (§3.3) or an `rgba2` timeline (§4.4) that the runtime does not hold as the file states it. Three shapes, all of which parse in silence: a `dark` the slot reader **drops** — it takes the field through a truthiness test, so `""` is discarded without a word and the slot renders with one colour; a `dark` that is **not six hex digits** — `Color.setFromString` slices fixed offsets and stores whatever `parseInt` gives back, so `"4020"` loads a channel of `NaN`; and an `rgba2` timeline on a slot with **no `dark` at all**, where the runtime allocates no dark colour and the first `state.apply` throws in the consumer's process. The keyed half is read by posing: the animation is stepped to each key's own time and the posed `color` and `darkColor` are compared against the hex the key states, to half a quantisation step (`1/510`). The detail names the slot, the value found and the value required. ⚠️ The required value is parsed **here** and not through `Color.fromString`, because a check that read it out of the parser it is checking would agree with that parser whatever it did. `compile.ts` refuses the third shape outright in a rig rigc builds; this is the same fact held against a skeleton it did not write. **SKIP** when no slot declares a `dark` and no animation keys an `rgba2` — there is then no two-colour tint to read back |
+| `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` | both | a **linked mesh** (§3.4) — `type: "linkedmesh"`, or a `type: "mesh"` carrying `source` — that also states `uvs`, `triangles`, `vertices`, `hull` or `edges`. The parser returns from the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`), so those keys are read by **nothing at all** and `setSourceMesh` fills the attachment with the source's arrays instead: the file says one mesh and every runtime draws another, in silence. The detail names the attachment by skin, slot and placeholder, every key it states, the `source` and where the parser looks for it — the two defaults spelled out, because an omitted `skin` is the **default** skin rather than the one the link is written in — and the shape the keys describe beside the shape the attachment loaded. ⚠️ **`width`/`height` are not part of this.** `setSourceMesh` overwrites both with the source's, so they are as dead at runtime — but the parser reads them (`:569-570`), the format carries them on a link and rigc emits them, so refusing them would refuse every link rigc writes (§3.4). `compile.ts` refuses the same shape outright in a rig rigc builds (§5.1); this is that fact held against a skeleton it did not write, and `ingest` reports it as `ATTACHMENT_LINK_GEOMETRY` ([INGEST §2.0](INGEST.md)). **SKIP** when no attachment in the skeleton takes its geometry from another — which is almost every skeleton, so a pass here means a link was read ([#710](https://github.com/firejune/rigc/issues/710)) |
 
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.

package/docs/INGEST.md

@@ -476,6 +476,19 @@ a default the source left to the format and the rebuild writes out). A blocker e
 non-zero and still writes both files. **Every code it can print has a row at the end
 of this section**, with its gutter, its effect on the exit code and what to do.
 
+⛔ **And it reads one generation.** Spine data is locked to the generation that
+exported it, and a mismatch is silent rather than loud: 4.3 takes constraints from the
+top-level `constraints` array alone, so a 4.0–4.2 file's `ik`/`transform`/`path`/
+`physics` arrays load as nothing at all — 1,302 shipped skeletons parsed on a 4.3
+runtime and loaded 0 of 8,672 constraints
+([#706](https://github.com/firejune/rigc/issues/706) row 1). So `ingest` reads
+`skeleton.spine` before it reads a field of the file, and a file from another
+generation is a blocker naming that generation and counting, **on that file**, what a
+4.3 reader loses by it. Reading such a file with *that generation's own* defaults is a
+different job — #706's item 2, a per-generation table extracted by machine from each
+runtime's `SkeletonJson` — and it is not in this tool, which is why the finding points
+at the policy rather than implying the file was read.
+
 **Two values are not in a skeleton**, so `ingest` asks rather than guesses:
 
 - **the stage** (`skeleton.width`/`height`) — `--stage x,y,w,h` is how you supply one
@@ -540,6 +553,7 @@ is the one failure a comparison of two sets cannot show you.
 | --- | --- | --- | --- | --- |
 | `ANIMATION_GROUP` | `BLOCK` | 1 | the animation carries a group the motion spec has no home for. The detail names the ten it does carry. `drawOrderFolder` is the group to know about: the runtime reads it and builds a timeline from it, and no export in this corpus carries one | transcribe that group by hand (§2), or accept that the rebuild does not carry it |
 | `ATTACHMENT_<TYPE>` | `BLOCK` | 1 | an attachment of a type rigc does not emit; the code is composed from the type, so on the one type left it reads `ATTACHMENT_POINT`. rigc emits region, mesh, linkedmesh, boundingbox, clipping and path — `linkedmesh` since [#691](https://github.com/firejune/rigc/issues/691), and `point` is the remaining deferred type | the rebuild will not have that attachment at all. `docs/SPEC_COVERAGE.md` part 1-6 says what a deferred type would carry |
+| `ATTACHMENT_LINK_GEOMETRY` | `LOSS` | 0 | a **linked mesh** that also states `uvs`, `triangles`, `vertices`, `hull` or `edges`. The parser returns from the `source` branch before `readVertices` (`SkeletonJson.ts:582-586`), so those keys are read by nothing at all and the attachment draws the geometry its `source` names; the rig spec has no home for them either, because `build` refuses geometry on a link by name. The detail lists the keys and the source. Until [#710](https://github.com/firejune/rigc/issues/710) the rebuild dropped them with no line at all, so an `ingest` that normalised somebody's file said nothing about it | nothing. The rebuild is the mesh the runtime was already drawing — and if those keys were the geometry you meant, take `source` off and author it as a mesh of its own. `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` is the same fact at the gate |
 | `ATTACHMENT_NAME` | `LOSS` | 0 | the attachment states a `name` and only **one** skin fills the placeholder, so rigc writes none — it composes `<skin>/<placeholder>` exactly where a placeholder is contested | nothing, unless something downstream looks that attachment up by the name the source gave it |
 | `ATTACHMENT_SEQUENCE` | `BLOCK` | 1 | the attachment carries a `sequence` block — a numbered image series — which the rig spec cannot say | the rebuild draws the single region the attachment names; the frames have to be driven some other way |
 | `ATTACHMENT_TIMELINE` | `BLOCK` | 1 | an attachment timeline other than `deform`, which is the only one the motion spec carries | transcribe it, or accept that the rebuild does not play it |
@@ -549,9 +563,11 @@ is the one failure a comparison of two sets cannot show you.
 | `CONSTRAINT_KEY_RESTATED` | `LOSS` | 0 | an `ik` or `transform` track whose keys do not all state the same fields. The motion spec takes one field set per track, so a field **any** key states is written on **every** key at the value the parser would have read there | nothing. Same values, larger file — the rebuild plays what the source plays |
 | `CONSTRAINT_TYPE` | `BLOCK` | 1 | a constraint whose `type` is none rigc knows, so the whole constraint is dropped rather than approximated | the rebuild has no such constraint; check the spelling before assuming the type is unsupported |
 | `DURATION` | `JUDGE` | 0 | skeleton JSON has no duration field at all. The largest key time is used, which is what a runtime plays to — and wrong for an animation that holds its last pose past its last key | if you know the real number, edit `duration` in the motion spec. It costs nothing: the declared duration is checked against the compiled keys |
+| `GENERATION_UNKNOWN` | `BLOCK` | 1 | `skeleton.spine` names no generation rigc knows, or the header states none at all. A version is read as its LEADING `major.minor` token — a down-export writes `4.0-from-4.1.24`, which is 4.0 data from a 4.1 editor — and it is never rounded to the nearest generation: a catalog that rounded handed 19 skeletons labelled `3.8.99` a 4.2 runtime and every one posed as NaN ([#706](https://github.com/firejune/rigc/issues/706) row 7) | check the string against the file you were handed. A real generation rigc does not list belongs on #706 item 1, with the string beside it |
+| `GENERATION_UNSUPPORTED` | `BLOCK` | 1 | the file is Spine data from another generation and this reader reads 4.3. The detail names the generation, the string it was read from, and what a 4.3 reader loses on **this** file: constraints parked in the top-level `ik` / `transform` / `path` / `physics` / `slider` arrays 4.3 folded into `constraints` and this reader never opens (row 1), bones carrying 4.2's `transform` where 4.3 spells `inherit` (row 6), and physics constraints omitting `inertia` / `damping`, whose default is not the same number in 4.2 as in 4.3 (row 4) | re-export the file as 4.3 from an editor of its own generation, or transcribe it by hand (§2). Reading it with **that generation's** defaults is #706 item 2 and is not in this tool |
 | `HEADER_BOOKKEEPING` | `LOSS` | 0 | a header field the editor writes and the rig spec has no home for — `hash`, `audio`. Dropped, and nothing reads it back | nothing. It is one of the three differences §2.3 measures on every editor export |
 | `HEADER_ORIGIN` | `LOSS` | 0 | the source declares an extent and omits `x`/`y`. Inside a declared extent an omitted origin **is** 0, so the spec states it — and the rebuild then spells two fields the source did not | nothing. Same box, different bytes — which is why byte identity is not the claim for an export that takes this branch |
-| `HEADER_REDERIVED` | `LOSS` | 0 | `skeleton.spine`: the rebuild writes the version of the runtime rigc links. The line says whether that is the same string the source states | nothing — but read the line: a 4.2 export rebuilds as 4.3 in that one field |
+| `HEADER_REDERIVED` | `LOSS` | 0 | `skeleton.spine`: the rebuild writes the version of the runtime rigc links. The line says whether that is the same string the source states | nothing — but read the line: a 4.2 export rebuilds as 4.3 in that one field, and a source from another generation raises `GENERATION_UNSUPPORTED` beside it, which is the blocker about the DATA rather than about the string |
 | `IK_KEY_FIELD` | `BLOCK` | 1 | a key field on an `ik` timeline that is not part of its shape | check the spelling; an unknown field is dropped from the rebuilt track |
 | `NO_STAGE` | `BLOCK` `JUDGE` | 1 | the skeleton declares no stage. It is a blocker with no `--stage`, and a **judgement** — exit 0 — when `--stage x,y,w,h` supplies one, because nothing measured the box you gave it | supply the box from the project the file came from. It cannot be derived: posing the rig gives the animated extent, which is a different number |
 | `PATH_LENGTHS` | `LOSS` | 0 | the source states a path attachment's `lengths` and rigc re-measures it as `PathConstraint` does | nothing. Dropping it is the correct reading: the field is the runtime's own four-sample forward difference, not an arc length |

package/docs/SPEC_COVERAGE.md

@@ -736,6 +736,7 @@ This is the split Part 4(c) needs. **Spine-validity** = the file is wrong for an
 | `A11_NO_CLIPPING_ATTACHMENTS` | **renderer-profile** | clipping attachments — "the renderer skips them silently" |
 | `A12_NO_DARK_COLOR` | **renderer-profile** | slot `dark`, `rgba2`/`rgb2` timelines — "parsed, then ignored". ⚠️ rigc **emits** the first two; a renderer that drops a construct is what a profile is for, not a reason not to emit it |
 | `A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN` | validity | a slot `dark` the parser drops or reads as NaN, an `rgba2` timeline on a slot with no dark colour to pose, or a key whose posed light/dark is not what it states |
+| `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` | validity | a linked mesh, in either spelling, that also states `uvs`, `triangles`, `vertices`, `hull` or `edges` — keys the `source` branch returns before reading, so the file says one mesh and every runtime draws its source's |
 | `A13_MESH_BUDGET` | **renderer-profile** | >4 mesh slots, >80 triangles per mesh |
 | `A14_NO_FULL_FRAME_MESH` | **renderer-profile** | a mesh spanning the whole stage |
 | `A19_OVERLAY_PNGS_HAVE_ALPHA` | **renderer-profile** | an overlay page that can never be transparent — no alpha channel and no `tRNS` chunk |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/src/generation.ts

@@ -0,0 +1,138 @@
+/**
+ * Which Spine data generation a skeleton's own version string names.
+ *
+ * ## Why this is one function and not a regex per caller
+ *
+ * Spine data is locked to the generation that exported it, and a mismatch fails
+ * **silently**: 4.3 takes constraints from the top-level `constraints` array
+ * alone, so a 4.0–4.2 file parses clean with none of them — measured across
+ * 1,302 shipped skeletons that loaded 0 of 8,672 constraints
+ * ([#706](https://github.com/firejune/rigc/issues/706) row 1). rigc is where
+ * that knowledge lives for the tools around it (#706 *Ownership*), and living
+ * in one place means one reader of `skeleton.spine`:
+ * `A16_SKELETON_VERSION_4_3` asks this function for its verdict, and `ingest`
+ * asks it before it reads a field of the file.
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * This is #706's item **1**, and nothing else. Item **2** — the per-generation
+ * table of key renames, array shapes and `getValue(map, key, default)` defaults,
+ * extracted by machine from each runtime branch's `SkeletonJson` — is not here,
+ * and neither is item **4**'s conversion utility. So this module reads a string
+ * and names a generation. It does not read a file, apply another generation's
+ * defaults, or convert anything, and a caller that meets data from another
+ * generation has to say so out loud rather than read it anyway.
+ *
+ * ## The grammar, and the two rules in it
+ *
+ * A version string is `MAJOR.MINOR`, an optional chain of `-from-MAJOR.MINOR`,
+ * then an optional `.PATCH` and an optional `-SUFFIX` after that. The shipped
+ * strings #706 lists are `3.8.99`, `4.0.33`, `4.0-from-4.1.24`,
+ * `4.0-from-4.1-from-4.2.29`, `4.1-from-4.2.33`, `4.2.09-beta`, `4.2.43`,
+ * `4.3.26` and `4.3.75-beta`.
+ *
+ * 1. **The leading token is the generation.** `4.0-from-4.1.24` is 4.0 data
+ *    written by a 4.1 editor — a *down-export* — and all 418 such-or-plain 4.0
+ *    files and 101 4.1 files in #706's corpus load and render on the 4.0 / 4.1
+ *    runtimes with 0 failures. Reading the trailing token would hand them the
+ *    wrong runtime, which is row 7's defect with extra steps.
+ * 2. **Every token has to be a generation this module knows, and the chain has
+ *    to ascend.** A down-export comes *from* a newer editor, so `4.0-from-4.1`
+ *    is a down-export and `4.3-from-4.2` is not a version string this reader
+ *    can account for. Both rules answer `null`, which is rule 3.
+ * 3. **Unknown is `null`, never the nearest.** A catalog builder gave 19
+ *    skeletons labelled `3.8.99` the nearest runtime it had; they loaded, and
+ *    posed 238 of 248 bones as NaN (#706 row 7). `null` is what a caller has to
+ *    act on, and it is why this returns a union rather than a number to compare.
+ *
+ * ⭐ Rules 2 and 3 together are also what keeps `A16`'s accepted set **exactly**
+ * what its own regex accepted before this module existed: 4.3 is the highest
+ * generation here, nothing can ascend above it, so no `-from-` string is ever
+ * read as 4.3 and `A16` still accepts `4.3`, `4.3.<patch>` and
+ * `4.3.<patch>-<suffix>` and those alone. The cost is stated rather than hidden:
+ * a future editor down-exporting as `4.3-from-4.4.1` reads as `null` here and is
+ * refused by name until that generation is added — which is #706 policy 1's own
+ * answer ("an unknown generation gets no runtime") rather than a gap in this one.
+ *
+ * ## Purity
+ *
+ * No clock, no randomness, no filesystem, no network, no `spine-core`. It reads
+ * strings and small plain objects and nothing else.
+ */
+
+/** A generation of Spine data — the `MAJOR.MINOR` pair a runtime is locked to. */
+export type SpineGeneration = '3.8' | '4.0' | '4.1' | '4.2' | '4.3';
+
+/**
+ * Every generation this module knows, oldest first.
+ *
+ * The order is load-bearing twice: a down-export chain has to ascend through it,
+ * and a caller listing "the generations rigc knows" reads it here rather than
+ * typing five strings next to a sixth.
+ */
+export const SPINE_GENERATIONS: readonly SpineGeneration[] = ['3.8', '4.0', '4.1', '4.2', '4.3'];
+
+/**
+ * `MAJOR.MINOR`, then the `-from-` chain, then the patch and its suffix.
+ *
+ * Anchored at both ends on purpose: `4.30` and `4.3.1.2` are not version strings
+ * and a partial match would read them as 4.3. The suffix shape is the one the
+ * editor writes for a pre-release (`4.3.75-beta`, which every one of the twelve
+ * official example exports declares) and is the same one `A16`'s own regex
+ * carried, character for character, before this module took it over.
+ */
+const VERSION_STRING = /^(\d+\.\d+)((?:-from-\d+\.\d+)*)(?:\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.+-]*)?)?$/;
+
+/**
+ * The generation a `skeleton.spine` string names, or `null` for one this module
+ * cannot account for.
+ *
+ * `null` is never the nearest generation and never a guess — see rule 3 above.
+ */
+export function spineGeneration(version: string): SpineGeneration | null {
+  const match = VERSION_STRING.exec(version);
+  if (match === null) return null;
+  const chain = match[2] === '' ? [] : match[2].split('-from-').slice(1);
+  const known = SPINE_GENERATIONS as readonly string[];
+  const steps = [match[1], ...chain].map((token) => known.indexOf(token));
+  if (steps.some((at) => at < 0)) return null;
+  for (let i = 1; i < steps.length; i++) if (steps[i] <= steps[i - 1]) return null;
+  return SPINE_GENERATIONS[steps[0]];
+}
+
+/**
+ * The constraint kinds a skeleton can carry as a **top-level array**, which 4.3
+ * folded into one `constraints` array with a `type` on each entry.
+ *
+ * 4.3 reads `constraints` and nothing else, so an array under any of these names
+ * loads without an error and the constraints in it are simply not there — #706
+ * row 1, and what `A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS` refuses in emitted
+ * data. `slider` never had a top-level form (sliders are 4.3's own), and it is
+ * on this list for the same reason as the other four: a constraint parked
+ * outside `constraints` vanishes whatever its kind, and a list with a hole in it
+ * is a rule with a hole in it.
+ */
+export const TOPLEVEL_CONSTRAINT_ARRAYS: readonly string[] = ['ik', 'transform', 'path', 'physics', 'slider'];
+
+/**
+ * The bone key 4.2 spelled `transform` and 4.3 spells `inherit`.
+ *
+ * The old key does not throw and does not warn — it is an unknown field, so the
+ * bone falls back to Normal inheritance (#706 row 6, and
+ * `A02_NO_BONE_TRANSFORM_KEY`).
+ */
+export const LEGACY_BONE_INHERIT_KEY = 'transform';
+
+/**
+ * The physics-constraint fields whose **omitted default** is not the same number
+ * in 4.2 as in 4.3.
+ *
+ * JSON omits a field equal to the parser's default, so the same file means two
+ * different constraints under two readers: `inertia` and `damping` both default
+ * to 1 in 4.2's `SkeletonJson` and to 0.5 and 0.85 in 4.3's (#706 row 4, which
+ * also counts 111 shipped constraints omitting `inertia`). The numbers are not
+ * repeated here deliberately — a hand-copied table is what #706 policy 3 exists
+ * to refuse, and item 2's generated table is where they belong. What a caller
+ * needs from this list is which fields to *count*, and that is what it is.
+ */
+export const PHYSICS_FIELDS_WHOSE_DEFAULT_MOVED: readonly string[] = ['inertia', 'damping'];

package/src/ingest.ts

@@ -47,6 +47,13 @@
 import { SLOT_TRACKS as EMITTED_SLOT_TRACKS, SPINE_VERSION } from './compile.ts';
 import { CompileError } from './errors.ts';
 import { CHANNELS_BY_KIND } from './timelines.ts';
+import {
+  LEGACY_BONE_INHERIT_KEY,
+  PHYSICS_FIELDS_WHOSE_DEFAULT_MOVED,
+  SPINE_GENERATIONS,
+  spineGeneration,
+  TOPLEVEL_CONSTRAINT_ARRAYS,
+} from './generation.ts';
 import { MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
 import { parseRigSpec, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
 import type { MotionSpec } from './types.ts';
@@ -404,6 +411,26 @@ const HEADER_REDERIVED = ['spine'];
 /** The attachment types this module inverts. Everything else is refused by name. */
 const ATTACHMENT_TYPES = ['region', 'mesh', 'linkedmesh', 'boundingbox', 'clipping', 'path'];
 
+/**
+ * The geometry keys a LINKED mesh may state and the parser never reads
+ * (issue #710).
+ *
+ * `readAttachment` returns from the `source` branch at `SkeletonJson.js:586`,
+ * before `map.uvs` is touched, so a link carrying any of these is a file that
+ * says one mesh while every runtime draws its source's. The rig spec cannot hold
+ * them either — `buildRigLinkedMesh` refuses geometry on a link by name — so a
+ * rebuild that carried one would be a spec `build` refuses, and a rebuild that
+ * dropped it in silence would be this module normalising somebody's file without
+ * saying so.
+ *
+ * ⚠️ A second list beside `src/validate.ts`'s, deliberately: that module links
+ * spine-core and this one must not, so importing it would pull the runtime into
+ * every `ingest`. What holds the two equal is a RUN rather than a shared
+ * constant — one forged skeleton through both, with the keys `A44` names and the
+ * keys this finding names compared as sets.
+ */
+const LINKED_MESH_UNREAD_KEYS = ['uvs', 'triangles', 'vertices', 'hull', 'edges'];
+
 /**
  * The slot timelines the motion spec carries — `compileTrack`'s own table,
  * rather than a second list of the same two names.
@@ -548,6 +575,12 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
   const root = obj(skeleton);
   const boneNames: string[] = arr(root.bones).map(nameOf);
 
+  // -- the generation -------------------------------------------------------
+  // 🚨 First, because every walk below reads the file as 4.3 and a file from
+  // another generation is one this module cannot honestly claim to have read
+  // (issue #706 item 3). It records; it does not refuse — see `readGeneration`.
+  readGeneration(root, note);
+
   // -- header ---------------------------------------------------------------
   // 🚨 THE SEAM. One function decides the rig spec's `skeleton` block, and the
   // stage is the only value in this whole module that a skeleton cannot answer
@@ -716,6 +749,146 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
 
 type Note = (kind: IngestFindingKind, code: string, where: string, detail: string) => void;
 
+/**
+ * The generation of the data this module inverts, read off the version the
+ * emitter writes rather than typed beside it.
+ *
+ * ⚠️ `null` here would be a compiler emitting a version string this repository's
+ * own detector cannot read, and the comparison below is written so that it
+ * blocks every file rather than none — a reader that cannot say what it reads
+ * cannot certify anything. `runGenerationSuite`'s positive control is what says
+ * out loud that it is not null.
+ */
+const READER_GENERATION = spineGeneration(SPINE_VERSION);
+
+/** Up to six names, so one finding cannot print a hundred. */
+function spellSome(names: readonly string[]): string {
+  const shown = names.slice(0, 6).map((name) => `"${name}"`).join(', ');
+  return names.length > 6 ? `${shown} +${names.length - 6} more` : shown;
+}
+
+/**
+ * What a 4.3 reader loses on THIS file, counted on this file.
+ *
+ * 🚨 Three shapes, and they are the three #706 measured rather than three this
+ * module thought of: constraints parked in the top-level arrays 4.3 folded away
+ * (row 1 — 1,302 shipped skeletons parsed and loaded 0 of 8,672 constraints),
+ * bones carrying the key 4.3 renamed (row 6), and physics constraints omitting a
+ * field whose default is not the same number in 4.2 as in 4.3 (row 4).
+ *
+ * ⚠️ It is a MEASUREMENT and not an inventory: a construct none of the three
+ * describes is lost without being counted here, which is why the empty case says
+ * so rather than saying nothing was lost.
+ */
+function generationLosses(root: JsonObject): string[] {
+  const out: string[] = [];
+
+  const parked = TOPLEVEL_CONSTRAINT_ARRAYS.map((kind) => [kind, arr(root[kind]).length] as const).filter(
+    ([, count]) => count > 0,
+  );
+  const parkedTotal = parked.reduce((total, [, count]) => total + count, 0);
+  if (parkedTotal > 0) {
+    out.push(
+      `${parkedTotal} constraint(s) sit in top-level arrays (${parked.map(([kind, count]) => `${kind} ${count}`).join(', ')}) ` +
+        'and this reader takes constraints from "constraints" alone, so it reads none of them and the rebuilt rig has none',
+    );
+  }
+
+  const renamed = arr(root.bones)
+    .filter((bone) => isObj(bone) && LEGACY_BONE_INHERIT_KEY in bone)
+    .map((bone) => nameOf(bone));
+  if (renamed.length > 0) {
+    out.push(
+      `${renamed.length} bone(s) carry "${LEGACY_BONE_INHERIT_KEY}" where 4.3 spells "inherit" (${spellSome(renamed)}), ` +
+        'each dropped as a field the rig spec has no home for — the BONE_FIELD line beside this one — so the ' +
+        'rebuilt bone inherits Normally',
+    );
+  }
+
+  const physics = [...arr(root.physics), ...arr(root.constraints).filter((one) => isObj(one) && one.type === 'physics')].filter(
+    isObj,
+  );
+  const omitting = PHYSICS_FIELDS_WHOSE_DEFAULT_MOVED.map(
+    (field) => [field, physics.filter((one) => one[field] === undefined).length] as const,
+  ).filter(([, count]) => count > 0);
+  if (omitting.length > 0) {
+    out.push(
+      `${physics.length} physics constraint(s), of which ${omitting.map(([field, count]) => `${count} omit "${field}"`).join(' and ')} — ` +
+        "JSON omits a field equal to the parser's default and that default is NOT the same number in 4.2 as in 4.3 " +
+        '(#706 row 4), so the omission means one rig there and a different one here',
+    );
+  }
+  return out;
+}
+
+/**
+ * The generation, read before a field of the file is.
+ *
+ * 🚨 **The silence this converts into a name was measured on the branch point.**
+ * A 4.3 emit with its constraints moved into the top-level arrays 4.2 kept them
+ * in came back through `ingest` as a rig spec with **zero** constraints and
+ * **no finding about them at all**; the only blocker was `BONE_FIELD`, about the
+ * bone key. A 3.8 label produced one `LOSS HEADER_REDERIVED` line and exit 0.
+ * That is the shape this whole module exists to refuse — a decompiler that is
+ * quiet about what it dropped.
+ *
+ * ⭐ **One code with the generation in the sentence, rather than one code per
+ * generation.** `IG25` derives `docs/INGEST.md` §2.0's finding table by reading
+ * every `note` call in this file for a code matching `[A-Z_]+`, and compares it
+ * against rows matched with `[A-Z_<>]+`. A composed `GENERATION_${generation}`
+ * would read `GENERATION_3.8` at runtime — digits and a dot — so the call would
+ * be one the scan cannot resolve and the code would be missing from BOTH sides
+ * of that comparison, which is the one failure comparing two sets cannot report.
+ *
+ * ⚠️ The same scan counts its own population with a second, dumber pattern over
+ * the raw text, comments included — so a prose mention of that call spelled with
+ * its opening bracket raises the count without raising the sites, and `IG25`
+ * goes red on a file with nothing wrong in it. It did, on the first green run of
+ * this change: **25 of 26 read**, the 26th being this very paragraph.
+ *
+ * ⚠️ It does NOT refuse the file. Everything here is a finding and both specs
+ * are still written, for the reason `IngestFinding` states: a spec plus a list
+ * of what is missing from it beats no spec. The exit code is the caller's and it
+ * is 1, because this is a `blocker`.
+ */
+function readGeneration(root: JsonObject, note: Note): void {
+  const declared = obj(root.skeleton).spine;
+  const generation = typeof declared === 'string' ? spineGeneration(declared) : null;
+  if (generation !== null && generation === READER_GENERATION) return;
+  const stated = typeof declared === 'string' ? `${JSON.stringify(declared)}` : 'no `skeleton.spine` at all';
+  const reads = READER_GENERATION ?? '(none — this build\'s own version string is unreadable)';
+  const losses = generationLosses(root);
+  const measured =
+    losses.length > 0
+      ? `Measured on this file: ${losses.join('; ')}.`
+      : 'Measured on this file: no constraint in a top-level array, no bone carrying ' +
+        `"${LEGACY_BONE_INHERIT_KEY}", and no physics constraint omitting a default that moved — which is three ` +
+        'shapes counted and not a guarantee that nothing else differs.';
+  if (generation === null) {
+    note(
+      'blocker',
+      'GENERATION_UNKNOWN',
+      'skeleton.spine',
+      `the file states ${stated} and no Spine generation matches it. A version is read as its LEADING major.minor ` +
+        'token — a down-export states "4.0-from-4.1.24", which is 4.0 data from a 4.1 editor — and the generations ' +
+        `rigc knows are ${SPINE_GENERATIONS.join(', ')}; this reader reads ${reads}. It is NOT read as the nearest ` +
+        'one: a catalogue that handed 19 skeletons labelled "3.8.99" the nearest runtime it had loaded every one of ' +
+        `them and posed 238 of 248 bones as NaN (issue #706 row 7). ${measured}`,
+    );
+    return;
+  }
+  note(
+    'blocker',
+    'GENERATION_UNSUPPORTED',
+    'skeleton.spine',
+    `the file states ${stated}, which is Spine ${generation} data, and this reader reads Spine ${reads} only — it ` +
+      `inverts a ${SPINE_VERSION} emitter. A generation mismatch does not throw; it drops what the newer format ` +
+      `moved. ${measured} Reading the file with ${generation}'s OWN defaults is issue #706 item 2 — a ` +
+      'per-generation table extracted by machine from each runtime\'s `SkeletonJson` — and is not in this tool. ' +
+      `Re-export from a ${reads} editor, or transcribe the file by hand (docs/INGEST.md §2).`,
+  );
+}
+
 /**
  * Does this header declare a stage?
  *
@@ -939,6 +1112,20 @@ function ingestAttachment(
     // writing one the source omitted would be a rebuild that says more than the
     // file did — and `buildRigLinkedMesh` drops it again on the way back out.
     for (const field of ['slot', 'skin', 'timelines', 'color']) if (att[field] !== undefined) out[field] = att[field];
+    const dropped = LINKED_MESH_UNREAD_KEYS.filter((field) => att[field] !== undefined);
+    if (dropped.length > 0) {
+      note(
+        'lossy',
+        'ATTACHMENT_LINK_GEOMETRY',
+        at.where,
+        `the attachment is a LINKED mesh and states ${dropped.map((field) => `\`${field}\``).join(', ')}, which the ` +
+          'parser reads with nothing at all: it returns from the `source` branch before `readVertices` ' +
+          `(\`SkeletonJson.ts:582-586\`), so what this attachment draws is the geometry of ${JSON.stringify(att.source)}. ` +
+          `The rebuild drops ${dropped.length === 1 ? 'it' : 'them'} — the rig spec refuses geometry on a link by name, ` +
+          'and carrying it would write a spec `build` will not take. `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` ' +
+          'is the same fact held against the source file',
+      );
+    }
   } else if (type === 'region') {
     carryArt();
     for (const field of ['x', 'y', 'rotation', 'scaleX', 'scaleY', 'color']) {

package/src/validate.ts

@@ -59,6 +59,12 @@ import {
   type DeformReach,
   type DialSpan,
 } from './deformmeasure.ts';
+import {
+  LEGACY_BONE_INHERIT_KEY,
+  spineGeneration,
+  TOPLEVEL_CONSTRAINT_ARRAYS,
+  type SpineGeneration,
+} from './generation.ts';
 import { colourTypeName, readPngInfo } from './png.ts';
 import {
   CHANNELS_BY_KIND,
@@ -188,6 +194,7 @@ const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP: 'validity',
   A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER: 'validity',
   A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN: 'validity',
+  A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN: 'validity',
 };
 
 /**
@@ -291,6 +298,7 @@ export const SKIP_NO_ATTACHMENT_REGION_JOIN =
   'no attachment names a region and the atlas declares none, so there is no attachment-to-region join to hold';
 export const SKIP_NO_TWO_COLOR_TINT =
   'no slot declares a "dark" colour and no animation keys an "rgba2" timeline, so there is no two-colour tint to read back';
+export const SKIP_NO_LINKED_MESH = 'no attachment in this skeleton takes its geometry from another one';
 /**
  * A09's, which predates this list and joins it rather than being rewritten: it
  * is the same fact about the same subject, and a control that compares against
@@ -512,11 +520,20 @@ function float32Step(t: number): number {
 }
 
 /**
- * `4.3`, `4.3.<patch>`, or `4.3.<patch>-<suffix>` — the last of which is what the
- * Spine editor writes for a pre-release (`"4.3.75-beta"` in all twelve official
- * example exports). The major/minor pair is the load-bearing part; see A16.
+ * The generation `A16` demands, which is the whole of what that assertion is
+ * about: the MAJOR.MINOR pair.
+ *
+ * ⭐ **The reading itself moved to [`generation.ts`](generation.ts)** with issue
+ * #706 — one reader of `skeleton.spine` for the whole repository, because
+ * `ingest` has to ask the same question of a file somebody else wrote and two
+ * regexes would answer it two ways. What did NOT move is the accepted set:
+ * `4.3`, `4.3.<patch>` and `4.3.<patch>-<suffix>`, the last of which is what the
+ * editor writes for a pre-release (`"4.3.75-beta"` in all twelve official
+ * example exports, and the string the original `/^4\.3(\.\d+)?$/` rejected —
+ * blocker B2). `GN05` holds that set against the old regex, which survives in
+ * `selftest.ts` and nowhere else, for exactly that comparison.
  */
-const SPINE_4_3_VERSION = /^4\.3(\.\d+(-[0-9A-Za-z][0-9A-Za-z.+-]*)?)?$/;
+const SPINE_4_3: SpineGeneration = '4.3';
 
 type Json = Record<string, unknown>;
 
@@ -616,9 +633,54 @@ export function attachmentRegionJoins(raw: unknown): AttachmentRegionJoin[] {
   return joins;
 }
 
+/**
+ * The mesh keys the `source` branch never reaches — the geometry a linked mesh
+ * may state and nothing reads (issue #710).
+ *
+ * Derived from the branch rather than chosen. `readAttachment` returns at
+ * `SkeletonJson.js:586` as soon as `source` is truthy, and everything below that
+ * return reads `map.uvs` (twice: as the length handed to `readVertices` and as
+ * `regionUVs`), `map.triangles`, `map.edges` and `map.hull`. `vertices` is on the
+ * list because `readVertices` reads `map.vertices` and nothing else (`:654`), so
+ * it goes unread with the call that would have read it.
+ *
+ * ⚠️ `width` and `height` are NOT on this list, although `setSourceMesh`
+ * overwrites both with the source's (`MeshAttachment.js:102-103`). The branch
+ * reads them at `:569-570`, the format carries them on a link and rigc emits
+ * them (#691). A key the parser reads is not a key the parser ignores, whatever
+ * a later pass does with the value.
+ */
+const LINKED_MESH_UNREAD_KEYS = ['uvs', 'triangles', 'vertices', 'hull', 'edges'] as const;
+
+/** One linked mesh as the FILE spells it, before the loader has resolved anything. */
+interface RawLinkedMesh {
+  /** The placeholder of the mesh whose geometry this attachment draws. */
+  source: string;
+  /**
+   * The `skin` the entry states, or `undefined` for the parser's default — which
+   * is the DEFAULT skin and never the skin the link is written in (`:429`).
+   */
+  skin?: string;
+  /** The `slot` the entry states, or `undefined` for the parser's default: this attachment's own slot (`:573-579`). */
+  slot?: string;
+  /** Which of `LINKED_MESH_UNREAD_KEYS` this entry states, in that order. */
+  geometry: string[];
+  /**
+   * How big a mesh those keys describe — `uvs.length / 2` and
+   * `triangles.length / 3` — when the entry states them as arrays.
+   *
+   * Read so that the failure can put the shape the author wrote beside the shape
+   * the runtime draws. `undefined` where the file states the key as something
+   * other than an array, which is a file this rule refuses for the key rather
+   * than for its length.
+   */
+  statedVertices?: number;
+  statedTriangles?: number;
+}
+
 /**
  * `"<skin>\0<slot>\0<placeholder>" -> source` for every linked mesh the raw
- * skeleton declares (issue #691).
+ * skeleton declares, with what the file says about each one (issues #691, #710).
  *
  * 🔑 The test is the parser's own and it is not `type`: `type: "mesh"` and
  * `type: "linkedmesh"` share one branch and a truthy `source` is what decides
@@ -626,8 +688,8 @@ export function attachmentRegionJoins(raw: unknown): AttachmentRegionJoin[] {
  * there, so it is not a link here either — that map is read as an ordinary mesh,
  * which is exactly what the runtime does with it.
  */
-function rawLinkedMeshSources(raw: unknown): Map<string, string> {
-  const links = new Map<string, string>();
+function rawLinkedMeshes(raw: unknown): Map<string, RawLinkedMesh> {
+  const links = new Map<string, RawLinkedMesh>();
   if (!isObj(raw) || !Array.isArray(raw.skins)) return links;
   for (const skin of raw.skins as unknown[]) {
     if (!isObj(skin) || !isObj(skin.attachments)) continue;
@@ -640,7 +702,14 @@ function rawLinkedMeshSources(raw: unknown): Map<string, string> {
         if (type !== 'mesh' && type !== 'linkedmesh') continue;
         const source = entry.source;
         if (typeof source !== 'string' || source.length === 0) continue;
-        links.set(`${skinName}\u0000${slot}\u0000${placeholder}`, source);
+        links.set(`${skinName}\u0000${slot}\u0000${placeholder}`, {
+          source,
+          skin: typeof entry.skin === 'string' ? entry.skin : undefined,
+          slot: typeof entry.slot === 'string' ? entry.slot : undefined,
+          geometry: LINKED_MESH_UNREAD_KEYS.filter((key) => entry[key] !== undefined),
+          statedVertices: Array.isArray(entry.uvs) ? entry.uvs.length / 2 : undefined,
+          statedTriangles: Array.isArray(entry.triangles) ? entry.triangles.length / 3 : undefined,
+        });
       }
     }
   }
@@ -1585,7 +1654,7 @@ export function validate(input: ValidateInput): ValidateReport {
   // stay rejected.
   check('A16_SKELETON_VERSION_4_3', () => {
     const declared = isObj(raw?.skeleton) ? (raw.skeleton as Json).spine : undefined;
-    if (typeof declared !== 'string' || !SPINE_4_3_VERSION.test(declared)) {
+    if (typeof declared !== 'string' || spineGeneration(declared) !== SPINE_4_3) {
       fail(
         'A16_SKELETON_VERSION_4_3',
         `skeleton.spine is ${JSON.stringify(declared)}, expected 4.3, 4.3.<patch> or 4.3.<patch>-<suffix>`,
@@ -1596,9 +1665,11 @@ export function validate(input: ValidateInput): ValidateReport {
   // --- A01: no legacy top-level constraint arrays ---------------------------
   // 4.3 folds every constraint into one `constraints` array with a `type`.
   // A 4.1/4.2-shaped `physics` array loads clean and the constraint just
-  // vanishes.
+  // vanishes. ⭐ The list is `generation.ts`'s since #706, because `ingest` has
+  // to count the same arrays in a file it did not emit, and two copies of five
+  // names is how one of them comes to be four.
   check('A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS', () => {
-    for (const key of ['ik', 'transform', 'path', 'physics', 'slider']) {
+    for (const key of TOPLEVEL_CONSTRAINT_ARRAYS) {
       if (raw && key in raw) {
         fail(
           'A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS',
@@ -1610,11 +1681,12 @@ export function validate(input: ValidateInput): ValidateReport {
 
   // --- A02: no bone.transform key ------------------------------------------
   // 4.3 renamed it to `inherit`; the old key loads and silently falls back to
-  // Normal inheritance (case 6b).
+  // Normal inheritance (case 6b). The key itself is `generation.ts`'s, for
+  // A01's reason.
   check('A02_NO_BONE_TRANSFORM_KEY', () => {
     const bones = Array.isArray(raw?.bones) ? (raw.bones as unknown[]) : [];
     for (const bone of bones) {
-      if (isObj(bone) && 'transform' in bone) {
+      if (isObj(bone) && LEGACY_BONE_INHERIT_KEY in bone) {
         fail('A02_NO_BONE_TRANSFORM_KEY', `bone "${String(bone.name)}" uses 4.2's "transform"; 4.3 wants "inherit"`);
       }
     }
@@ -1689,8 +1761,8 @@ export function validate(input: ValidateInput): ValidateReport {
   let clippingCount = 0;
   const meshSlots = new Set<number>();
   /**
-   * The loaded mesh of every attachment the FILE spells as a link, to the
-   * `source` it names (issue #691).
+   * The loaded mesh of every attachment the FILE spells as a link, to what the
+   * file says about it (issues #691, #710).
    *
    * 🔑 Read off the raw JSON and joined by (skin, slot, placeholder) rather than
    * asked of the loaded object, because `MeshAttachment.sourceMesh` is **private
@@ -1703,11 +1775,23 @@ export function validate(input: ValidateInput): ValidateReport {
    * placeholder is unique only within one skin's slot and several skins fill
    * one — and every assertion downstream holds the attachment, not its address.
    */
-  const linkedMeshes = new Map<MeshAttachment, string>();
+  const linkedMeshes = new Map<MeshAttachment, RawLinkedMesh>();
+  /**
+   * The same pairing the other way round — join key -> the attachment the loader
+   * produced for it — which is what `A44` needs and `kindOf` does not.
+   *
+   * 🔑 Two maps rather than one because the two questions are different. Every
+   * rule that asks "is THIS attachment a link" holds the object and wants the
+   * file's word about it; `A44` walks the FILE's links and asks what the runtime
+   * made of each, including the answer "nothing" — a link whose region is
+   * missing loads as `null` and is in no skin at all (`A08` names that), so its
+   * join key is absent here while the file still declares it.
+   */
+  const loadedLinks = new Map<string, MeshAttachment>();
 
   if (skeletonData) {
     const data = skeletonData as NonNullable<typeof skeletonData>;
-    const rawLinks = rawLinkedMeshSources(raw);
+    const rawLinks = rawLinkedMeshes(raw);
     for (const skin of data.skins) {
       for (const entry of skin.getAttachments()) {
         const att = entry.attachment;
@@ -1715,8 +1799,12 @@ export function validate(input: ValidateInput): ValidateReport {
         else if (att instanceof MeshAttachment) {
           meshAttachments.push(att);
           meshSlots.add(entry.slotIndex);
-          const source = rawLinks.get(`${skin.name}\u0000${data.slots[entry.slotIndex].name}\u0000${entry.placeholder}`);
-          if (source !== undefined) linkedMeshes.set(att, source);
+          const join = `${skin.name}\u0000${data.slots[entry.slotIndex].name}\u0000${entry.placeholder}`;
+          const link = rawLinks.get(join);
+          if (link !== undefined) {
+            linkedMeshes.set(att, link);
+            loadedLinks.set(join, att);
+          }
         } else if (att instanceof ClippingAttachment) clippingCount++;
       }
     }
@@ -2097,7 +2185,7 @@ export function validate(input: ValidateInput): ValidateReport {
       list
         .filter((m) => kindOf(m) === 'authored')
         .map((m) => {
-          const source = linkedMeshes.get(m);
+          const source = linkedMeshes.get(m)?.source;
           return source === undefined ? `"${m.name}"` : `"${m.name}" (linked to "${source}")`;
         });
 
@@ -3859,6 +3947,70 @@ export function validate(input: ValidateInput): ValidateReport {
         }
       }
     });
+
+    // --- A44: a linked mesh states no geometry of its own ------------------
+    //
+    // 🚨 The one shape the parser reads in SILENCE. `readAttachment` returns from
+    // the `source` branch at `SkeletonJson.js:586`, before `map.uvs` is touched
+    // at all, so `uvs`, `triangles`, `vertices`, `hull` and `edges` written on a
+    // link are read by nothing — and `setSourceMesh` then fills the attachment
+    // with the SOURCE's arrays. The file says one mesh and every runtime draws
+    // another, which is why this is `validity` and not one renderer's policy.
+    //
+    // ⭐ **It is a separate assertion rather than a clause on A04, and the reason
+    // is measurable both ways.** A04 reads the LOADED attachment —
+    // `mesh.triangles`, `mesh.worldVerticesLength`, `mesh.vertices` — which on a
+    // link are the source's after `setSourceMesh`: measured on a forged link
+    // declaring 5 uvs and 3 triangles beside a 4-vertex source, A04 PASSED
+    // having read 8 and 2, the source's own. The keys this rule is about are not
+    // in the data A04 holds, so the clause would have had to reach for the raw
+    // file, and a verdict line reading A04's name would then be naming a
+    // measurement of the loaded geometry while deciding about file keys nothing
+    // read. The SKIP is the sharper half: A04's subject is mesh attachments, so
+    // on a rig with meshes and no link its subject is PRESENT and it passes —
+    // there is no verdict left for "this rig has no link to measure", and a
+    // clause that cannot report SKIP reports a pass for an absent subject, which
+    // this repository already has a judgment about.
+    //
+    // ⚠️ The subject is the FILE's links and not the loaded ones. A link whose
+    // region is missing loads as `null` and is in no skin (`A08` names it), so
+    // walking the loaded attachments would let the whole rule vanish on exactly
+    // the file that is already wrong.
+    check('A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN', () => {
+      if (rawLinks.size === 0) return skip('A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN', SKIP_NO_LINKED_MESH);
+      for (const [join, link] of rawLinks) {
+        if (link.geometry.length === 0) continue;
+        const [skinName, slotName, placeholder] = join.split('\u0000');
+        const at = `skin ${JSON.stringify(skinName)} slot ${JSON.stringify(slotName)} placeholder ${JSON.stringify(placeholder)}`;
+        const keys = link.geometry.map((key) => JSON.stringify(key)).join(', ');
+        // Where the parser looks for `source`, with the two defaults spelled out:
+        // an omitted `skin` is the DEFAULT skin rather than this attachment's own
+        // (`:429`), and an omitted `slot` IS this attachment's own (`:573-579`).
+        const where =
+          `skin ${JSON.stringify(link.skin ?? 'default')}${link.skin === undefined ? ' (the default skin, because no "skin" was stated — never the skin this attachment is written in)' : ''} ` +
+          `slot ${JSON.stringify(link.slot ?? slotName)}${link.slot === undefined ? ' (this attachment\'s own, because no "slot" was stated)' : ''}`;
+        // What the author's own keys describe, printed only when both are
+        // readable — the shape the file states, beside the shape it draws.
+        const states =
+          link.statedVertices === undefined || link.statedTriangles === undefined
+            ? ''
+            : ` (${link.statedVertices} vertices and ${link.statedTriangles} triangles)`;
+        const drawn = loadedLinks.get(join);
+        const loaded =
+          drawn === undefined
+            ? 'what it loaded is not shown here because the round trip produced no attachment for it (A00 owns that)'
+            : `it loaded ${drawn.worldVerticesLength / 2} vertices and ${drawn.triangles.length / 3} triangles`;
+        fail(
+          'A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN',
+          `${at} links to ${JSON.stringify(link.source)} and states ${keys}${states}, and a linked mesh has no geometry of ` +
+            'its own. The parser returns from the `source` branch before `readVertices` ' +
+            `(\`SkeletonJson.ts:582-586\`), so ${link.geometry.length === 1 ? 'that key is' : 'those keys are'} read by ` +
+            `nothing at all: what this attachment draws is the geometry of ${JSON.stringify(link.source)} in ${where}, and ` +
+            `${loaded}. Remove ${link.geometry.length === 1 ? 'it' : 'them'}, or remove "source" and author this as a ` +
+            'mesh of its own.',
+        );
+      }
+    });
   }
 
   // --- A06 / A17 / A19: the atlas against the PNGs on disk ------------------
@@ -4114,14 +4266,39 @@ export function validate(input: ValidateInput): ValidateReport {
         // `rotate: 270` and red at 0, 90 and 180 — this assertion's own verdict,
         // flipped by the rotation it does not judge (issue #579). The footprint
         // is `pageFootprint`'s, which every other reader of it now calls.
+        // 🚨 **The scan counts what it READ, and zero texels read is not a
+        // verdict** (issue #705). The `continue` above walks past every
+        // coordinate that is not on the page, so a rectangle none of whose
+        // texels are on it came out of this loop with `transparent` still
+        // false — indistinguishable from a solid drawing — and the sentence
+        // below then stated opacity over texels nobody had opened. Measured on
+        // a pack shaped like #707's: `part "block" is opaque in every one of
+        // its 12x8 texels`, over **0 of 96**, on art carrying 36 clear texels
+        // where it was packed. That is the message-as-UI defect in one line —
+        // the reader is sent to re-export a part whose alpha was never the
+        // problem, and the rectangle that is the problem belongs to A06.
+        //
+        // ⚠️ It is a FAIL rather than a SKIP, and the report's own shape
+        // decides that rather than taste. `skip()` is per ASSERTION, so
+        // skipping here would delete the verdicts on every other part of the
+        // page — on that same pack the second part is genuinely opaque and is
+        // named — and adding a skip BESIDE those failures puts A19 in two of
+        // the four buckets `reportLines` adds up, which prints `45 assertions`
+        // where the registry holds 44. What is left is a failure that says
+        // what was not measured, which is also what "green means measured"
+        // requires: a part this rule could not read must not be certified by
+        // it.
         const plate = readPlate(abs);
         for (const region of on) {
           if (baseRegions.has(region.name)) continue;
           const { width, height } = pageFootprint(region);
+          const declared = width * height;
+          let read = 0;
           let transparent = false;
           for (let y = region.y; y < region.y + height && !transparent; y++) {
             for (let x = region.x; x < region.x + width; x++) {
               if (x < 0 || y < 0 || x >= plate.width || y >= plate.height) continue;
+              read++;
               if (plate.get(x, y)[3] < 255) {
                 transparent = true;
                 break;
@@ -4129,12 +4306,37 @@ export function validate(input: ValidateInput): ValidateReport {
             }
           }
           if (transparent) continue;
+          // The page's size here is the DECODED image's and not the `size:`
+          // line's, because it is the bound this scan actually clipped
+          // against; where the two disagree A06 says so in its own sentence.
+          if (read === 0) {
+            fail(
+              'A19_OVERLAY_PNGS_HAVE_ALPHA',
+              `part "${region.name}" is not measured: this rule read 0 of the ${declared} texels of its ` +
+                `${width}x${height} rectangle at ${region.x},${region.y} on page "${page.name}", whose image is ` +
+                `${plate.width}x${plate.height}, so it states nothing about whether "${region.name}" can draw a ` +
+                "transparent pixel. A region's rectangle is A06_ATLAS_PAGE_SIZE_MATCHES_PNG's to judge, and one " +
+                'that runs off its page is refused there by name. This is renderer policy, and it belongs to ' +
+                '--profile spine-html: the default --profile spine does not run this check.',
+            );
+            continue;
+          }
+          // A rectangle partly on the page states the verdict over the texels
+          // it read and says how many of the declared ones that was. A whole
+          // rectangle prints the sentence it has always printed, to the byte.
+          const over =
+            read === declared
+              ? `every one of its ${width}x${height} texels on shared page "${page.name}"`
+              : `every one of the ${read} texels of its ${width}x${height} rectangle at ${region.x},${region.y} ` +
+                `that are on shared page "${page.name}", whose image is ${plate.width}x${plate.height} — the ` +
+                `other ${declared - read} of the ${declared} it declares are not on the page and are not ` +
+                'measured here';
           fail(
             'A19_OVERLAY_PNGS_HAVE_ALPHA',
-            `part "${region.name}" is opaque in every one of its ${width}x${height} texels on shared page ` +
-              `"${page.name}", so it would paint a solid rectangle over whatever is drawn behind it. Re-export ` +
-              `the part with transparency and pack again. ${exemption} This is renderer policy, and it belongs ` +
-              'to --profile spine-html: the default --profile spine does not run this check.',
+            `part "${region.name}" is opaque in ${over}, so it would paint a solid rectangle over whatever is ` +
+              `drawn behind it. Re-export the part with transparency and pack again. ${exemption} This is ` +
+              'renderer policy, and it belongs to --profile spine-html: the default --profile spine does not run ' +
+              'this check.',
           );
         }
         continue;