spine-rigc 1.8.0 → 1.9.0

package/src/assertions/bodies/a19.ts

@@ -0,0 +1,295 @@
+/**
+ * A19, the body (issue #1025, step 4c of #380): every overlay part can draw a
+ * transparent pixel — only the base plate may be opaque.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the pages and
+ * regions are a fact (`../facts/atlas_regions.ts`), the stage is a fact
+ * (`../facts/stage.ts`), the region attachments are the skins' fact
+ * (`../facts/skin_entries.ts`), and the directory and the rig info are the
+ * caller's. Why transparency is not the same thing as an alpha channel (#215)
+ * stays above the `check` call in `validate()`.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasRegionEntry, AtlasRegionFacts } from '../facts/atlas_regions.ts';
+import type { SkinEntryFacts } from '../facts/skin_entries.ts';
+import type { StageFacts } from '../facts/stage.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+import { pageFootprint } from '../../atlas.ts';
+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 {
+  // 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);
+  const stageW = stage.width ?? 0;
+  const stageH = stage.height ?? 0;
+  // 🔒 **Which image is the base plate is decided ONCE, and the rig's own
+  // statement decides it** (issue #770). A cut manifest names its base plate
+  // — the part whose window IS the crop — and that needs no stage box; the
+  // size of an attachment against the stage is read only when the build
+  // names none, because it is then the only statement there is (every build
+  // from a rig spec, and `validate <dir>`, which has no rig at all). Both
+  // routes below read the same two sets, so they cannot disagree about it.
+  //
+  // ⚠️ Before this, "at least the stage's size" was the only reading, and a
+  // stageless manifest rig came out with no base plate: the packed build was
+  // refused for its plate's opaque texels while the loose build of the same
+  // rig passed on the file's colour type. The order is a rule rather than a
+  // coincidence of the fixtures, where the two readings agree: a stage stated
+  // small enough for an overlay to "cover" is exactly where they part.
+  const named = input.rig?.basePlates ?? [];
+  const basePages = new Set<string>();
+  const baseRegions = new Set<string>();
+  const exempt = (name: string): void => {
+    const region = atlas.findRegion(name);
+    if (region) {
+      basePages.add(region.page.name);
+      baseRegions.add(region.name);
+    }
+  };
+  if (named.length > 0) {
+    for (const name of named) exempt(name);
+  } else {
+    for (const att of regionAttachments) {
+      if (stageW && stageH && att.width >= stageW && att.height >= stageH) exempt(att.path || att.name);
+    }
+  }
+  // The escape hatch is named the way it is reachable. With a base plate the
+  // rig names, that plate; with none but a stage, the size reading; and with
+  // neither, nothing here decides which image is the plate — so the sentence
+  // says what would, rather than pointing at a door that is not there.
+  const undecided =
+    'Only a base plate may be opaque, and nothing here decides which image that is: this skeleton declares no ' +
+    'stage size to measure one against, and ';
+  const exemption =
+    named.length > 0
+      ? `Only the base plate the rig names (${named.map((name) => JSON.stringify(name)).join(', ')}, the part ` +
+        "whose window is the cut manifest's crop) may be opaque."
+      : stageW && stageH
+        ? `Only the one image big enough to cover the whole stage (${stageW}x${stageH}) may be opaque.`
+        : input.rig
+          ? `${undecided}the build names no base plate. Either would decide it: give the rig spec a "skeleton" ` +
+            'stage the plate covers, or build from a cut manifest, whose base plate is the part whose window is ' +
+            'the crop.'
+          : `${undecided}no rig was given to name one. Either would decide it: state a "skeleton" stage the plate ` +
+            'covers, or validate with the specs it was built from (--rig, --motion and the --manifest, whose base ' +
+            'plate is the part whose window is the crop).';
+  // 🚨 Counted per page for the unpacked convention and per REGION on a shared
+  // page, and the split is not a convenience (issue #266, follow-up 2). A
+  // packed page's own file all but always declares transparency — the gutter
+  // and whatever is left over of the page are transparent — so the file-level
+  // question is answered "yes" by the packing itself, whatever the parts on it
+  // look like. Asking it that way once packs became gateable under this profile
+  // would have turned this assertion into a pass that measures nothing, which
+  // is the failure mode this file exists to prevent. So a shared page is opened
+  // and each region's own rectangle is measured instead.
+  const sharedPages = new Map<string, AtlasRegionEntry[]>();
+  for (const region of atlas.regions) {
+    const on = sharedPages.get(region.page.name);
+    if (on) on.push(region);
+    else sharedPages.set(region.page.name, [region]);
+  }
+  for (const page of atlas.pages) {
+    const abs = resolve(input.atlasDir, page.name);
+    if (!existsSync(abs)) continue;
+    const on = sharedPages.get(page.name) ?? [];
+    // 🔒 **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
+    // the verdicts on every other page of the same report. The file's
+    // identity is `A06`'s to judge, and this sentence points there. A page
+    // holding nothing but the full-stage base plate has no part to judge and
+    // says nothing, exactly as a readable one would.
+    const header = readPngHeader(abs);
+    if (header.problem !== null) {
+      const shared = on.length > 1;
+      const parts = shared ? on.filter((region) => !baseRegions.has(region.name)).map((region) => region.name) : [];
+      if (shared ? parts.length === 0 : basePages.has(page.name)) continue;
+      const subject = shared
+        ? `the ${parts.length} part(s) on shared page "${page.name}" (${parts.map((name) => JSON.stringify(name)).join(', ')}) are`
+        : `part image "${page.name}" is`;
+      fail(
+        'A19_OVERLAY_PNGS_HAVE_ALPHA',
+        `${subject} not measured: this rule reads a page's alpha out of its PNG, and the file cannot be read as ` +
+          'one, so it states nothing about whether any of them can draw a transparent pixel. What the file is ' +
+          "belongs to A06_ATLAS_PAGE_SIZE_MATCHES_PNG, which names it. This is renderer policy, and it belongs to " +
+          '--profile spine-html: the default --profile spine does not run this check.',
+      );
+      continue;
+    }
+    if (on.length > 1) {
+      // 🚨 A rotated region is refused by A06 under this profile, so this
+      // reading was assumed to be cosmetic — a rectangle printed beside a
+      // failure already standing. It is not: the loop below OPENS the
+      // rectangle and stops at the first transparent texel, so a rectangle
+      // wider than the drawing runs into the transparent gutter, finds its
+      // texel there and names nothing. With the transpose applied at 90 only,
+      // two fully opaque parts on one page were measured green at
+      // `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);
+      // 🚨 **The scan's coordinates are the atlas's, so a file that is not the
+      // declared grid is a non-measurement for every region on it** (issue
+      // #715), and #705's clause above does not cover it. That one fires when
+      // a rectangle has NO texel on the page; a page whose image is a rescale
+      // of the declared size leaves most rectangles partly on it, at
+      // coordinates that address a different part of the picture. Measured on
+      // a two-region pack at a uniform 0.5: the opaque part's failure
+      // DISAPPEARED — the scan found a transparent texel 32 texels away from
+      // it and returned — while the other printed #705's sentence over 0 of
+      // 256 texels. A verdict and a silence, both about texels nobody located.
+      //
+      // A FAIL for #705's reason, word for word: `skip()` is per assertion and
+      // would delete the verdicts on every other page in the same report.
+      if (plate.width !== page.width || plate.height !== page.height) {
+        for (const region of on) {
+          if (baseRegions.has(region.name)) continue;
+          const { width, height } = pageFootprint(region);
+          fail(
+            'A19_OVERLAY_PNGS_HAVE_ALPHA',
+            `part "${region.name}" is not measured: this rule opens the page at the coordinates the atlas ` +
+              `states, and page "${page.name}" declares ${page.width}x${page.height} over a ` +
+              `${plate.width}x${plate.height} image, so the ${width}x${height} rectangle at ${region.x},` +
+              `${region.y} is not where "${region.name}"'s texels are on this file and this rule states ` +
+              'nothing about whether it can draw a transparent pixel. The page grid is ' +
+              "A06_ATLAS_PAGE_SIZE_MATCHES_PNG's to judge, and it names the ratio and how to declare the page " +
+              'honestly. This is renderer policy, and it belongs to --profile spine-html: the default ' +
+              '--profile spine does not run this check.',
+          );
+        }
+        continue;
+      }
+      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;
+            }
+          }
+        }
+        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 ${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;
+    }
+    const info = header.info;
+    if (basePages.has(page.name)) continue; // the base plate: opaque is correct
+    // The header is the FAST NEGATIVE and only that (#215's rule, unchanged):
+    // a colour type 0, 2 or 3 file with no tRNS chunk has nowhere to keep a
+    // transparent texel, so it is refused without opening it.
+    if (!info.hasTransparency) {
+      fail(
+        'A19_OVERLAY_PNGS_HAVE_ALPHA',
+        `part image "${page.name}" cannot be transparent anywhere: it is colour type ${info.colourType} ` +
+          `(${colourTypeName(info.colourType)}) with no tRNS chunk, so it would paint a solid rectangle over ` +
+          'whatever is drawn behind it. Re-export it with transparency — as RGBA, or as an indexed or greyscale ' +
+          `PNG that keeps its tRNS chunk. ${exemption} This is renderer policy, and it belongs to --profile ` +
+          'spine-html: the default --profile spine does not run this check.',
+      );
+      continue;
+    }
+    // 🚨 **A header that says "could be transparent" is not an answer, and
+    // the texels decide it exactly as they do on a shared page** (issue
+    // #777). Until this the loose route stopped here, so a part saved as
+    // RGBA passed whether or not any texel used the channel: on the
+    // articulated fixture, stageless, an overlay rewritten as colour type 6
+    // with 0 of its 16,000 texels below full alpha PASSED loose and was
+    // refused by `--pack` of the same rig, over the same texels. The runtime
+    // draws those texels, not the file's declaration, so the loose verdict
+    // was the false green. The rectangle is the whole decoded image — on a
+    // loose page the file IS the part, so no atlas coordinate is read and
+    // #705's and #715's non-measurements cannot arise here — and the scan
+    // stops at the first clear texel, as the shared page's does.
+    const plate = readPlate(abs);
+    let transparent = false;
+    for (let y = 0; y < plate.height && !transparent; y++) {
+      for (let x = 0; x < plate.width; x++) {
+        if (plate.get(x, y)[3] < 255) {
+          transparent = true;
+          break;
+        }
+      }
+    }
+    if (transparent) continue;
+    const holds = info.hasAlpha
+      ? `colour type ${info.colourType} (${colourTypeName(info.colourType)}) carries an alpha channel`
+      : `colour type ${info.colourType} (${colourTypeName(info.colourType)}) carries a tRNS chunk`;
+    fail(
+      'A19_OVERLAY_PNGS_HAVE_ALPHA',
+      `part image "${page.name}" is opaque in every one of its ${plate.width}x${plate.height} texels, so it ` +
+        `would paint a solid rectangle over whatever is drawn behind it: its file can hold transparency — ${holds} ` +
+        '— and no texel uses it. Re-export the part with the transparency it is meant to have. ' +
+        `${exemption} This is renderer policy, and it belongs to --profile spine-html: the default --profile ` +
+        'spine does not run this check.',
+    );
+  }
+}

package/src/assertions/bodies/a20.ts

@@ -0,0 +1,122 @@
+/**
+ * A20, the body (issue #1025, step 4c of #380): a weighted mesh's weights
+ * cohere — every vertex bound, every weight finite and non-negative, every
+ * vertex's weights summing to 1 — and, under `spine-html`, a generated mesh is
+ * weighted, binds only bones that move it and binds every bone it declares.
+ *
+ * Moved out of `src/validate.ts` clause by clause, every clause about the
+ * weights themselves moving: a document's mesh names each vertex's bindings,
+ * so a vertex count that disagrees with the `uvs`, an empty binding list, a
+ * weight that is not finite, below 0 or 0 on a generated mesh, a sum off 1 and
+ * a declared bone no vertex binds each have a place to live there (the reader
+ * refuses the first three by the record's name). The one clause that does not
+ * — a binding's index past the bone array — is about the encoding: the
+ * document names a binding's bone, and the index is the emitter's to write.
+ * It stays with the round trip, which hands its finding in on the binding
+ * (`MeshBinding.encoding`), printed where the body always printed it.
+ *
+ * The weights are the ones the runtime holds — float32 — and a binding's bone
+ * its index in the roster, because the weight-0 clause prints it.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { meshKindOf } from '../mesh_kinds.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a20MeshWeightsCoherent({ fail, skip }: Verdicts, { meshes, bones }: MeshFacts, policy: boolean, rig: RigInfo | undefined): void {
+  if (meshes.length === 0) return skip('A20_MESH_WEIGHTS_COHERENT', SKIP_NO_MESH_ATTACHMENT);
+  for (const mesh of meshes) {
+    // 🚨 Authored geometry is not rigc's to have opinions about. The two
+    // policy branches in this assertion are both statements about what a
+    // rigc GENERATOR is supposed to produce — "a mesh here is weighted",
+    // "a generated mesh binds only bones that move it" — and neither is a
+    // fact about Spine or about somebody else's mesh. Applying them to
+    // authored geometry failed correct data (issue #44). The coherence
+    // rules below the branch are unconditional and still apply.
+    const generated = meshKindOf(mesh, rig) !== 'authored';
+    if (!mesh.weights) {
+      // 📐 PROFILE. An unweighted mesh is perfectly valid Spine — spineboy
+      // ships two — and the runtime poses it from the slot bone. What is
+      // NOT valid, in any profile, is a weighted mesh whose weights do not
+      // cohere, which is everything below this branch. So the requirement
+      // that a mesh be weighted at all is the policy half, and it is the
+      // only half gated here.
+      if (policy && generated) {
+        fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" is unweighted; the ring tier drives meshes by bones`);
+      }
+      continue;
+    }
+    const perVertex = mesh.weights;
+    const expected = mesh.worldVerticesLength / 2;
+    if (perVertex.length !== expected) {
+      fail(
+        'A20_MESH_WEIGHTS_COHERENT',
+        `mesh "${mesh.name}" has weights for ${perVertex.length} vertices but ${expected} uv pairs`,
+      );
+      continue;
+    }
+    perVertex.forEach((vertex, i) => {
+      if (!vertex.length) fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" vertex ${i} has no bones`);
+      let sum = 0;
+      for (const { bone, weight, encoding } of vertex) {
+        if (!Number.isFinite(weight) || weight < 0) {
+          fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" vertex ${i} has weight ${weight}`);
+        }
+        // 📐 PROFILE. A weight of exactly 0 is legal, harmless Spine: the
+        // runtime accumulates `(…) * weight` (Attachment.js:131), so the
+        // binding contributes nothing. The Spine editor writes them — the
+        // auto-weighted meshes in 6-arcs, 7-anticipation and 8-follow-through
+        // carry dozens, and their vertex weights still sum to 1. Treating one
+        // as corruption failed three rungs of the ladder on correct data.
+        // In a rigc-GENERATED ring or ribbon it is still a defect: the
+        // generator bound a bone that does nothing, which is a bug in the
+        // generator and dead work in the runtime's inner loop. So it stays a
+        // failure under spine-html and is not one under spine.
+        else if (policy && generated && weight === 0) {
+          fail(
+            'A20_MESH_WEIGHTS_COHERENT',
+            `mesh "${mesh.name}" vertex ${i} is bound to bone index ${bone} at weight 0; a generated mesh binds only bones that move it`,
+          );
+        }
+        // The index's range is the encoding's, kept with the round trip (the header).
+        if (encoding !== undefined) fail('A20_MESH_WEIGHTS_COHERENT', encoding);
+        sum += weight;
+      }
+      if (Math.abs(sum - 1) > 1e-3) {
+        fail('A20_MESH_WEIGHTS_COHERENT', `mesh "${mesh.name}" vertex ${i} weights sum to ${sum.toFixed(4)}`);
+      }
+    });
+    // 📐 PROFILE, and the converse of the weight-0 branch above: that one
+    // says a generated mesh binds only bones that MOVE it, and this one says
+    // every bone it declares moves it. They are halves of one sentence — the
+    // bone set the mesh declares is the bone set its weights reference — so
+    // they are one assertion rather than two, and neither is a fact about
+    // Spine: a declared bone nothing binds loads and renders perfectly.
+    //
+    // 🚨 It is the one mesh question a vertex cannot answer, which is why
+    // every per-vertex rule above was green on the ring that raised it: a
+    // rig-spec ring naming two grips bound one of them, and the absent bone
+    // appears in no vertex, in no sum and in no index (issue #684). The
+    // declaration comes from the compiler's own record of what it bound,
+    // which is what the `MESH` report line prints.
+    if (policy && generated && rig) {
+      const declared = rig.meshDeclaredBones[mesh.slot] || [];
+      const bound = new Set<string>();
+      for (const vertex of perVertex) {
+        for (const { bone } of vertex) {
+          const named = bones[bone];
+          if (named !== undefined) bound.add(named);
+        }
+      }
+      for (const name of declared) {
+        if (bound.has(name)) continue;
+        fail(
+          'A20_MESH_WEIGHTS_COHERENT',
+          `mesh "${mesh.name}" declares bone "${name}" and none of its ${perVertex.length} vertices binds it; ` +
+            `the weights reference ${[...bound].map((n) => `"${n}"`).join(', ')}`,
+        );
+      }
+    }
+  }
+}

package/src/assertions/bodies/a21.ts

@@ -0,0 +1,190 @@
+/**
+ * A21, the body (issue #1025, step 4c of #380): a generated mesh's rim — or
+ * a ribbon's entry row — is pinned to the slot's own bone, and a soft region
+ * moves only the vertices it declares. An `archetype` rule.
+ *
+ * Moved out of `src/validate.ts` whole: every clause is about the rig — which
+ * vertex sits on the region border or the hull, which bone carries it and at
+ * what weight — and a document's mesh states each of those (its `uvs`, its
+ * `hull`, its bindings by bone). Nothing it reads is the encoding's. The
+ * weights are the runtime's float32, a binding's bone its index in the roster
+ * (named back through the roster where the sentence names it), and a link's
+ * geometry its source's.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { authoredMeshNames, meshKindOf } from '../mesh_kinds.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a21MeshRimPinned({ fail, skip }: Verdicts, { meshes, bones }: MeshFacts, rig: RigInfo | undefined): void {
+  // Without the rig, ring and ribbon cannot be told apart — and the two kinds
+  // pin OPPOSITE edges, so guessing one would either check the wrong edge or
+  // check nothing while reporting a pass.
+  if (!rig) {
+    return skip('A21_MESH_RIM_PINNED', 'no rig info (validating a bare directory), so ring and ribbon cannot be told apart');
+  }
+  if (!meshes.some((m) => m.weights)) {
+    return skip('A21_MESH_RIM_PINNED', 'the skeleton has no weighted mesh attachment, so there is no rim to find unpinned');
+  }
+  // An authored mesh has no rim rigc drew and no entry row rigc placed, and
+  // a linked mesh has no rim of its OWN at all — the one it draws belongs to
+  // its source, and is measured there. Nothing to measure is a SKIP — never
+  // a pass, and never a failure on somebody else's correct geometry.
+  //
+  // 🔸 A `segments` mesh is rigc's own geometry and still has no rim to pin:
+  // its outline is traced off the art and weighted by distance like every
+  // other vertex, because a layer pulled by named bones is SUPPOSED to move
+  // at its edge. "Pinned to the slot bone" is not a claim that generator
+  // makes, so there is nothing here to hold it to — and `A20`'s coherence
+  // rules, which it does make, still apply to it in full.
+  const rimless = (m: (typeof meshes)[number]): boolean => meshKindOf(m, rig) === 'authored' || meshKindOf(m, rig) === 'segments';
+  const measurable = meshes.filter((m) => m.weights && !rimless(m));
+  if (measurable.length === 0) {
+    const authored = authoredMeshNames(meshes.filter((m) => m.weights), rig);
+    const segmented = meshes.filter((m) => m.weights && meshKindOf(m, rig) === 'segments').map((m) => `"${m.name}"`);
+    return skip(
+      'A21_MESH_RIM_PINNED',
+      segmented.length === 0
+        ? `every weighted mesh here is authored or linked geometry (${authored.join(', ')}), not a rigc ring or ` +
+            'ribbon — rigc did not place its rim, so it has no rim of its own to find unpinned'
+        : `every weighted mesh here is ${authored.length ? `authored or linked geometry (${authored.join(', ')}) or ` : ''}` +
+            `a "segments" lattice (${segmented.join(', ')}), not a rigc ring or ribbon — a segments mesh weights its ` +
+            'outline by distance to the bones it names, so it has no rim pinned to the slot bone to find unpinned',
+    );
+  }
+  for (const mesh of measurable) {
+    if (!mesh.weights) continue;
+    const perVertexAll = mesh.weights;
+    const slotBoneOf = mesh.slotBone;
+    // A ribbon's outer boundary is SUPPOSED to move — that is the whole point
+    // of a strip that changes length. So the rule splits by mesh kind rather
+    // than being relaxed: for a ribbon the invariant is that the ENTRY row
+    // cannot move, because that row is where the strip joins the part it
+    // comes out of. Both rules protect the same thing (the mesh's join to the
+    // plate underneath); they just live at different edges of the mesh.
+    //
+    // A `contour` takes the hull path below, and that is the check it wants
+    // rather than a third branch: a contour mesh's hull IS every vertex it
+    // has, and every one is pinned to the slot bone at weight 1, so "the rim
+    // is pinned" reads over the whole mesh. If a later contour tier ever
+    // moves interior vertices, this is the assertion that has to grow a
+    // branch — it will fail rather than pass quietly, which is the right way
+    // round.
+    if (meshKindOf(mesh, rig) === 'ribbon') {
+      const uvs = mesh.regionUVs ?? [];
+      let entryRow = 0;
+      for (let v = 0; v < perVertexAll.length; v++) {
+        if (Math.abs(uvs[v * 2 + 1]) > 1e-6) continue; // not on the entry edge
+        entryRow++;
+        const vertex = perVertexAll[v];
+        if (vertex.length !== 1 || Math.abs(vertex[0].weight - 1) > 1e-6) {
+          fail(
+            'A21_MESH_RIM_PINNED',
+            `ribbon "${mesh.name}" entry vertex ${v} is not pinned (${vertex.map((w) => w.weight.toFixed(3)).join('+')})`,
+          );
+          continue;
+        }
+        if (slotBoneOf && bones[vertex[0].bone] !== slotBoneOf) {
+          fail(
+            'A21_MESH_RIM_PINNED',
+            `ribbon "${mesh.name}" entry vertex ${v} is pinned to "${bones[vertex[0].bone]}", not the anchor bone "${slotBoneOf}"`,
+          );
+        }
+      }
+      if (entryRow < 2) {
+        fail('A21_MESH_RIM_PINNED', `ribbon "${mesh.name}" has ${entryRow} vertices on its entry edge; a strip needs two`);
+      }
+      continue;
+    }
+    // A rim a soft mask deliberately CARRIED (issue #382). The rule splits
+    // by declaration rather than being relaxed — the same move the ribbon
+    // branch above makes, and for the same reason: a wobbling silhouette is
+    // supposed to move, and the invariant is that nothing ELSE does. So on
+    // such a mesh a vertex is either pinned to the slot bone at 1 or shared
+    // between it and the ONE bone the rig declared, and a third bone, a
+    // wrong bone or a weight that does not close is still a failure.
+    const boundBone = rig.meshSoftBones[mesh.slot] ?? null;
+    if (boundBone !== null) {
+      const allowed = new Set([slotBoneOf, boundBone]);
+      let carried = 0;
+      for (let v = 0; v < perVertexAll.length; v++) {
+        const vertex = perVertexAll[v];
+        let sum = 0;
+        for (const { bone, weight } of vertex) {
+          const name = bones[bone];
+          if (!allowed.has(name)) {
+            fail(
+              'A21_MESH_RIM_PINNED',
+              `mesh "${mesh.name}" vertex ${v} is carried by "${name}", and this mesh declares only ` +
+                `"${slotBoneOf}" and the soft region's "${boundBone}"`,
+            );
+          }
+          if (name === boundBone && weight > 0) carried = carried + (weight >= 1 ? 1 : 0);
+          sum += weight;
+        }
+        if (Math.abs(sum - 1) > 1e-4) {
+          fail(
+            'A21_MESH_RIM_PINNED',
+            `mesh "${mesh.name}" vertex ${v} weights sum to ${sum.toFixed(4)}; a depth-bound mesh splits each ` +
+              'vertex between the slot bone and the bound bone, so it closes at 1',
+          );
+        }
+      }
+      // A mask that carried nothing reached here as a mesh pinned exactly
+      // as before, which is not the thing that was declared.
+      if (carried === 0) {
+        fail(
+          'A21_MESH_RIM_PINNED',
+          `mesh "${mesh.name}" declares a soft region on "${boundBone}" and no vertex is fully carried by it`,
+        );
+      }
+      continue;
+    }
+    const hullVertices = mesh.hullLength / 2;
+    if (!Number.isInteger(hullVertices) || hullVertices < 3) {
+      fail('A21_MESH_RIM_PINNED', `mesh "${mesh.name}" declares hull ${mesh.hullLength / 2}; the rim must be a real ring`);
+      continue;
+    }
+    const perVertex = mesh.weights;
+    if (hullVertices > perVertex.length) {
+      fail('A21_MESH_RIM_PINNED', `mesh "${mesh.name}" hull is ${hullVertices} of ${perVertex.length} vertices`);
+      continue;
+    }
+    // The rim is the alpha contour where generated pixels meet untouched
+    // base. One bone at weight 1, and that bone must be the slot's own —
+    // anything else and the seam can move.
+    const slotBone = mesh.slotBone;
+    for (let i = 0; i < hullVertices; i++) {
+      const vertex = perVertex[i];
+      if (vertex.length !== 1 || Math.abs(vertex[0].weight - 1) > 1e-6) {
+        fail(
+          'A21_MESH_RIM_PINNED',
+          `mesh "${mesh.name}" rim vertex ${i} is not pinned (${vertex.map((v) => v.weight.toFixed(3)).join('+')})`,
+        );
+        continue;
+      }
+      if (slotBone && bones[vertex[0].bone] !== slotBone) {
+        fail(
+          'A21_MESH_RIM_PINNED',
+          `mesh "${mesh.name}" rim vertex ${i} is pinned to "${bones[vertex[0].bone]}", not the slot bone "${slotBone}"`,
+        );
+      }
+    }
+    // Independent of the ring ORDER: whatever sits on the region border is
+    // the outline, and the outline moving means the part's own edge moving.
+    // Without this, reordering the rings would move the pinned prefix off
+    // the outline and A21 would still pass on the count alone.
+    const uvs = mesh.regionUVs ?? [];
+    for (let v = 0; v < perVertex.length; v++) {
+      const u = uvs[v * 2];
+      const t = uvs[v * 2 + 1];
+      const onBorder = [u, t].some((c) => Math.abs(c) < 1e-6 || Math.abs(c - 1) < 1e-6);
+      if (!onBorder) continue;
+      const vertex = perVertex[v];
+      if (vertex.length !== 1 || Math.abs(vertex[0].weight - 1) > 1e-6) {
+        fail('A21_MESH_RIM_PINNED', `mesh "${mesh.name}" vertex ${v} is on the region border but not pinned`);
+        break;
+      }
+    }
+  }
+}

package/src/assertions/bodies/a22.ts

@@ -0,0 +1,39 @@
+/**
+ * A22, the body (issue #1025, step 4c of #380): every mesh's authored UVs lie
+ * 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
+ * `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinMeshFacts } from '../facts/skin_meshes.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+
+export function a22MeshUvsInUnitRange({ fail, skip }: Verdicts, { meshes }: SkinMeshFacts): 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) {
+    // `regionUVs` is what the JSON authored; `uvs` is the page-space result
+    // and stays EMPTY until a renderer calls computeUVs, so asserting on it
+    // here would be asserting on the wrong array (measured: length 0 after
+    // a clean load). With one part per page the two are equal anyway —
+    // computeUVs reduces to `u + regionUV * width` with u=0, width=1
+    // (MeshAttachment.js:173-174), which is the claim this assertion rests
+    // on and this is where it is checked.
+    const uvs = mesh.regionUVs;
+    if (!uvs || uvs.length !== mesh.worldVerticesLength) {
+      fail(
+        'A22_MESH_UVS_IN_UNIT_RANGE',
+        `mesh "${mesh.name}" has ${uvs?.length ?? 0} authored uv values for ${mesh.worldVerticesLength}`,
+      );
+      continue;
+    }
+    for (let i = 0; i < uvs.length; i++) {
+      if (!Number.isFinite(uvs[i]) || uvs[i] < -1e-6 || uvs[i] > 1 + 1e-6) {
+        fail('A22_MESH_UVS_IN_UNIT_RANGE', `mesh "${mesh.name}" uv[${i}] is ${uvs[i]}`);
+        break;
+      }
+    }
+  }
+}