spine-rigc 1.9.4 → 2.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spine-rigc",
-  "version": "1.9.4",
-  "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, round-trips it through spine-core and named assertions, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
+  "version": "2.0.1",
+  "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {
     "rigc": "./bin/rigc.cjs"
@@ -55,6 +55,7 @@
   "files": [
     "bin/rigc.cjs",
     "cli.ts",
+    "cli_core.ts",
     "src",
     "tools/plate.ts",
     "tools/font5x7.ts",
@@ -90,10 +91,8 @@
     "viewer": "vite --config viewer/vite.config.ts",
     "prepublishOnly": "bun run typecheck && bun run lint && bun run selftest"
   },
-  "dependencies": {
-    "@esotericsoftware/spine-core": "4.3.13"
-  },
   "devDependencies": {
+    "@esotericsoftware/spine-core": "4.3.13",
     "@types/bun": "^1.4.0",
     "eslint": "^10.9.0",
     "spine-html": "^0.4.1",

package/skills/rigc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rigc
-description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output through a spine-core round-trip before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
+description: Author, build and validate Spine 4.3 skeleton data (skeleton.json plus its .atlas) from loose part PNGs with rigc, the rig compiler that verifies its own output with named assertions before writing it. Use for any request to make a Spine rig or Spine animation from PNG parts, or where the source is a Live2D, Unity or video model whose pictures you can render, to run or read rigc build, validate, render, preview, check or vote, or to write or fix a *.rig.json or *.motion.json spec; it says which shipped guide to open for the need at hand. Not for Live2D conversion, cutting an illustration into parts, or real-time face tracking.
 license: MIT
 compatibility: Requires Bun 1.2 or later. The tool is the npm package spine-rigc (bunx spine-rigc, or bun add -d spine-rigc); the command it installs is rigc.
 ---
@@ -8,8 +8,9 @@ compatibility: Requires Bun 1.2 or later. The tool is the npm package spine-rigc
 # rigc — a rig compiler for agents
 
 rigc compiles a rig spec and a motion spec into Spine 4.3 skeleton data and an
-atlas, round-trips the result through `@esotericsoftware/spine-core`, runs its
-named assertions, and writes **only if every one is green**. You cannot see the
+atlas, runs its named assertions — rigc's own validator in the published package,
+held to a `@esotericsoftware/spine-core` round trip's verdicts in its CI, all but
+the parse itself — and writes **only if every one is green**. You cannot see the
 rig you are authoring. The validator's messages and the shipped guides are the
 whole interface, and this skill only says which of them to open.
 
@@ -17,8 +18,10 @@ whole interface, and this skill only says which of them to open.
 
 - **Validation is never bypassed.** `build` writes nothing on a red gate; there is
   no `--no-validate`, and none may be added — AUTHORING §0 says so in as many
-  words. Correctness is the whole of the reason: the round trip through the
-  official parser is the only thing that makes the output trustworthy.
+  words. Correctness is the whole of the reason: the assertions are what make the
+  output trustworthy, and they are held to the official parser's verdicts in the
+  repository's CI — all but the parse itself, which runs only where the runtime is
+  installed and is reported as a SKIP elsewhere.
 - **The compiler never invents a value.** A field the spec leaves out is a
   `CompileError` naming that field. Fill the spec; do not expect a default read off
   the art — AUTHORING §2 and §5.
@@ -41,6 +44,13 @@ Codex, Gemini CLI and Antigravity read skills from `.agents/skills/` in the
 workspace and none of them reads `node_modules`; `rigc skills install` puts every
 skill the package ships there, and `rigc skills --help` says what it refuses.
 
+The package links no Spine runtime. `validate`, `preview` and `vote` below run
+through `@esotericsoftware/spine-core`: install it beside the package
+(`bun add -d @esotericsoftware/spine-core`) and the same `rigc` runs them, and
+`build` runs the round trip as well. Without it they are refused by name, and
+`build` writes the same files gated without the parse — `rigc --version` names the
+entry that ran.
+
 ## The loop
 
 1. `rigc build --rig <spec> --motion <spec> --images <dir> --out <dir>` compiles,

package/src/assertions/bodies/a01.ts

@@ -0,0 +1,23 @@
+/**
+ * A01, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the skeleton JSON — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { TOPLEVEL_CONSTRAINT_ARRAYS } from '../../generation.ts';
+import type { Json } from '../values.ts';
+
+export function a01NoLegacyToplevelConstraintArrays({ fail }: Verdicts, raw: Json | null): void {
+  for (const key of TOPLEVEL_CONSTRAINT_ARRAYS) {
+    if (raw && key in raw) {
+      fail(
+        'A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS',
+        `top-level "${key}" array present; 4.3 wants it inside "constraints" with type:"${key}"`,
+      );
+    }
+  }
+}

package/src/assertions/bodies/a02.ts

@@ -0,0 +1,21 @@
+/**
+ * A02, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the skeleton JSON — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { LEGACY_BONE_INHERIT_KEY } from '../../generation.ts';
+import { isObj, type Json } from '../values.ts';
+
+export function a02NoBoneTransformKey({ fail }: Verdicts, raw: Json | null): void {
+  const bones = Array.isArray(raw?.bones) ? (raw.bones as unknown[]) : [];
+  for (const bone of bones) {
+    if (isObj(bone) && LEGACY_BONE_INHERIT_KEY in bone) {
+      fail('A02_NO_BONE_TRANSFORM_KEY', `bone "${String(bone.name)}" uses "transform", the key 4.0 and 4.1 spelled; 4.2 and 4.3 spell it "inherit"`);
+    }
+  }
+}

package/src/assertions/bodies/a05.ts

@@ -0,0 +1,56 @@
+/**
+ * A05, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the skeleton JSON — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { SKIP_NO_TIMELINE } from '../reasons.ts';
+import { CHANNELS_BY_KIND, walkTimelines } from '../../timelines.ts';
+import { isObj, type Json } from '../values.ts';
+
+export function a05CurveArrayLength({ fail, skip }: Verdicts, raw: Json | null): void {
+  // Two clauses, so the SKIP needs both to be empty (#580). The vocabulary
+  // clause below measures every timeline it is handed — an unchecked name is a
+  // finding whether or not any key on it carries a curve — so a skeleton with
+  // timelines and no curve at all has still been measured. What measures
+  // nothing is a skeleton `walkTimelines` never calls back on.
+  let timelines = 0;
+  walkTimelines(raw, (path, kind, name, keys) => {
+    timelines++;
+    const table = CHANNELS_BY_KIND[kind];
+    if (!(name in table)) {
+      fail('A05_CURVE_ARRAY_LENGTH', `${path}: unchecked ${kind} timeline "${name}" — extend the validator`);
+      return;
+    }
+    const channels = table[name];
+    for (const key of keys) {
+      if (!isObj(key) || !('curve' in key)) continue;
+      const curve = key.curve;
+      if (channels === null) {
+        fail('A05_CURVE_ARRAY_LENGTH', `${path}: timeline "${name}" cannot carry a curve`);
+        continue;
+      }
+      if (curve === 'stepped') continue;
+      if (!Array.isArray(curve)) {
+        fail('A05_CURVE_ARRAY_LENGTH', `${path}: curve is ${JSON.stringify(curve)}, expected "stepped" or an array`);
+        continue;
+      }
+      if (curve.length !== channels * 4) {
+        fail(
+          'A05_CURVE_ARRAY_LENGTH',
+          `${path} (t=${String(key.time ?? 0)}): curve has ${curve.length} numbers, "${name}" needs ${channels} channels x 4 = ${channels * 4}`,
+        );
+      }
+      for (const n of curve) {
+        if (typeof n !== 'number' || !Number.isFinite(n)) {
+          fail('A05_CURVE_ARRAY_LENGTH', `${path}: curve holds a non-finite value ${JSON.stringify(n)}`);
+        }
+      }
+    }
+  });
+  if (timelines === 0) return skip('A05_CURVE_ARRAY_LENGTH', SKIP_NO_TIMELINE);
+}

package/src/assertions/bodies/a06.ts

@@ -81,6 +81,14 @@ export function a06AtlasPageSizeMatchesPng({ fail: failed, skip }: Verdicts, { a
     // of a page states; this rule prefixes the size the atlas declares, the
     // value the file would have had to carry.
     //
+    // 🔒 **And this is the one line that names it** (issue #1064). A file's
+    // readability is this rule's subject — it runs under both profiles and
+    // asks `pngProblem` first, so on every input where `A19` would find the
+    // same page unreadable, this FAIL is already printed. `A19` therefore
+    // SKIPs naming the page and pointing here when it failed nothing else,
+    // and says nothing about the page when it did: one unreadable file, one
+    // line, the way #1055 made one missing file A17's alone.
+    //
     // ⚠️ No size is read off a file rigc cannot decode, deliberately. A WebP
     // header carries its dimensions in a fixed field, and reading them would
     // print a number no oracle in this tree has checked (rigc links no WebP

package/src/assertions/bodies/a07.ts

@@ -0,0 +1,68 @@
+/**
+ * A07, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the atlas text — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+
+export function a07AtlasTextShape({ fail, skip }: Verdicts, atlasText: string): void {
+  const atlasLines = atlasText.replace(/\n$/, '').split('\n');
+  const atlasPageLines = atlasLines.filter((line) => line.trim().length > 0).length;
+  if (atlasPageLines === 0) {
+    // One of the exported reason constants, not a sentence of its own: the
+    // static-rig suite's arithmetic (S50, #580) counts a rule as skipped
+    // for want of a SUBJECT only when its reason is one of those constants.
+    return skip('A07_ATLAS_TEXT_SHAPE', SKIP_NO_ATLAS_PAGE);
+  }
+  // A blank line at either END of the file is named as that end (issues #803,
+  // #810), and a run of them is one finding stating its length. They are taken
+  // off both ends before the walk below, so the walk sees the page blocks and
+  // the blank lines between them and nothing else: a blank line after the last
+  // region is not a page block, and "consecutive blank lines" and "the last
+  // page block declares no region" are about blocks. `TextureAtlas` reads a
+  // blank at either end as nothing (`TextureAtlas.js:98-100` skips the leading
+  // run, `:116-118` ends a page block on each blank line), and rigc writes
+  // neither (`writeAtlasText`, and `--atlas-in` through `canonicalAtlasShape`),
+  // so a file that has one was written by something else and is refused.
+  let leading = 0;
+  while (leading < atlasLines.length && atlasLines[leading].trim().length === 0) leading++;
+  if (leading > 0) {
+    fail('A07_ATLAS_TEXT_SHAPE', `line 1: the file begins with ${leading === 1 ? 'a blank line' : `${leading} blank lines`}`);
+  }
+  let trailing = 0;
+  while (trailing < atlasLines.length - leading && atlasLines[atlasLines.length - 1 - trailing].trim().length === 0) trailing++;
+  const blockEnd = atlasLines.length - trailing;
+  let expectPage = true;
+  let sawRegionForPage = false;
+  for (let i = leading; i < blockEnd; i++) {
+    const line = atlasLines[i];
+    if (line.trim().length === 0) {
+      if (expectPage) fail('A07_ATLAS_TEXT_SHAPE', `line ${i + 1}: consecutive blank lines`);
+      else if (!sawRegionForPage) {
+        fail('A07_ATLAS_TEXT_SHAPE', `line ${i + 1}: blank line before this page had any region`);
+      }
+      expectPage = true;
+      sawRegionForPage = false;
+      continue;
+    }
+    if (expectPage) {
+      expectPage = false;
+      continue; // page name line
+    }
+    if (line.includes(':')) continue; // key: value line
+    // A bare non-key line is a region name, and it is used untrimmed.
+    if (line !== line.trim()) {
+      fail('A07_ATLAS_TEXT_SHAPE', `line ${i + 1}: region name has stray whitespace: ${JSON.stringify(line)}`);
+    }
+    sawRegionForPage = true;
+  }
+  if (!sawRegionForPage) fail('A07_ATLAS_TEXT_SHAPE', 'the last page block declares no region');
+  if (trailing > 0) {
+    fail('A07_ATLAS_TEXT_SHAPE', `line ${blockEnd + 1}: the file ends with ${trailing === 1 ? 'a blank line' : `${trailing} blank lines`}`);
+  }
+}

package/src/assertions/bodies/a16.ts

@@ -0,0 +1,24 @@
+/**
+ * A16, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the skeleton JSON — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { spineGeneration, type SpineGeneration } from '../../generation.ts';
+import { isObj, type Json } from '../values.ts';
+
+const SPINE_4_3: SpineGeneration = '4.3';
+
+export function a16SkeletonVersion43({ fail }: Verdicts, raw: Json | null): void {
+  const declared = isObj(raw?.skeleton) ? (raw.skeleton as Json).spine : undefined;
+  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>`,
+    );
+  }
+}

package/src/assertions/bodies/a18.ts

@@ -0,0 +1,62 @@
+/**
+ * A18, the body (issue #1060, step 4e of #380): a second, independent compile
+ * writes the same model document, byte for byte.
+ *
+ * One body, two suppliers, as every moved assertion is — but split. The
+ * runtime's side (`validate()` in `src/validate.ts`) compares the second
+ * compile's Spine pair as well, `skeleton.json` and `skeleton.atlas`, and
+ * hands those findings over as `encoding`, in the order it always printed
+ * them; the model side (`../model/index.ts`) compares the document alone,
+ * which is all a build with no Spine pair writes (`cli_core.ts build`). So
+ * the model's clause is written once, here, and the two sides cannot spell it
+ * apart. When neither side was handed a second compile — a re-gate of files on
+ * disk — there is nothing determinate about a comparison that never ran, and
+ * it SKIPs with the reason the round trip always gave (the vacuous-pass trap
+ * `A09` is guarded against too).
+ *
+ * Moved out of `src/validate.ts` unchanged but for the seam; `firstDifferingLine`
+ * moved with it, the one reader of it.
+ */
+import type { Verdicts } from '../harness.ts';
+
+const A18 = 'A18_DETERMINISTIC_EMIT';
+
+/** What A18 reads: whether a second compile was handed over, the encoding's findings, and the two documents. */
+export interface DeterminismFacts {
+  /** Whether a second, independent compile was handed over — without one the assertion has nothing to compare. */
+  again: boolean;
+  /** The findings of the clauses only one side compares (the Spine pair, on the runtime's), each a detail, in the order they print. */
+  encoding: readonly string[];
+  /** The first compile's model document — `undefined` where the caller handed a second compile and no first document. */
+  first: string | undefined;
+  /** The second compile's model document; read only where `again`. */
+  second: string;
+}
+
+/**
+ * Where two texts first differ, as A18 names it: the 1-based line and each
+ * side's line, trimmed and cut to 120 characters.
+ */
+export function firstDifferingLine(first: string, second: string): string {
+  const a = first.split('\n');
+  const b = second.split('\n');
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+  const cut = (line: string | undefined): string => (line === undefined ? '(end of text)' : JSON.stringify(line.trim().slice(0, 120)));
+  return `${i + 1}: ${cut(a[i])} first, ${cut(b[i])} second`;
+}
+
+export function a18DeterministicEmit({ fail, skip }: Verdicts, facts: DeterminismFacts): void {
+  if (!facts.again) return skip(A18, 'no second compile to compare against (re-gating artifacts on disk)');
+  for (const detail of facts.encoding) fail(A18, detail);
+  // The model document is compared like the Spine pair (issue #922): it is
+  // written beside them, and a map iterated in an order nothing fixed would
+  // reach it before it reached either of them — the document writes every
+  // `Map` of the model as an array in the map's order. On a build with no
+  // Spine pair it is the only artifact there is to compare.
+  if (facts.first === undefined) {
+    fail(A18, 'a second compile was handed over with no first model document to compare its skeleton.model.json against');
+  } else if (facts.second !== facts.first) {
+    fail(A18, `recompiling produced a different skeleton.model.json (first differing line ${firstDifferingLine(facts.first, facts.second)})`);
+  }
+}

package/src/assertions/bodies/a19.ts

@@ -122,6 +122,7 @@ export function a19OverlayPngsHaveAlpha({ fail: failed, skip }: Verdicts, { atla
   // moves nothing here (the size it was not measured at is `A06`'s to say).
   let pagesWithParts = 0;
   const unread: string[] = [];
+  const unreadable: string[] = [];
   for (const page of atlas.pages) {
     const abs = resolve(input.atlasDir, page.name);
     const on = sharedPages.get(page.name) ?? [];
@@ -131,28 +132,42 @@ export function a19OverlayPngsHaveAlpha({ fail: failed, skip }: Verdicts, { atla
       if (carriesPart) unread.push(page.name); // A17 names the file; this body says only that it did not read it
       continue;
     }
-    // 🔒 **A page that is not a PNG is a non-measurement for every part on
-    // it** (issue #732), stated the way #705's and #715's are: a FAIL naming
-    // what was not read, because `skip()` is per assertion and would delete
-    // 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.
+    // 🔒 **A page that is on disk and cannot be read as a PNG is named once,
+    // by `A06`, and this body only says it did not read it** (issue #1064,
+    // the other half of #1055's rule). Until this it FAILed here with a
+    // second sentence about the same file (#732's `not measured … belongs to
+    // A06`), so one unreadable page was two red lines: measured on the tree's
+    // 19 recipes with the first page replaced by text bytes, by a PNG cut
+    // inside its IDAT and by one with a wrong signature byte, A06 FAILed
+    // naming the file on 19 of 19 under both profiles and this rule added its
+    // FAIL on the 12 whose first page carries a part (`spine-html`).
+    //
+    // ⭐ Who names it is read off the two bodies, not chosen. Both ask
+    // `readPngHeader` (`pngProblem`, the one reader of a page's identity) the
+    // same question about the same file, A06 runs under both profiles and this
+    // rule under `spine-html` alone, and A06 FAILs on every page for which it
+    // answers with a problem — so on every input that reaches this branch, A06
+    // has already named the file and the report is red. A FAIL here would be
+    // the second naming and a PASS a certificate over alpha nobody read, so
+    // the page joins `#1055`'s unread list, with its own owner beside it.
+    //
+    // ⚠️ #732 chose a FAIL because `skip()` is per assertion and would delete
+    // the verdicts on every other page. Under #1055's rule that argument no
+    // longer forces it: the SKIP below is printed only when this body failed
+    // nothing else, so the verdicts it would replace are all passes, and its
+    // reason says how many pages they covered. With another failure standing,
+    // the failures stand and the unreadable page is A06's alone. A page
+    // holding nothing but the base plate had nothing for this rule to read
+    // either way and moves nothing, exactly as a missing one does.
+    //
+    // ⚠️ Only what `pngProblem` refuses comes here. A page whose header it
+    // accepts and whose texels the decoder then refuses (a broken zlib stream
+    // in an intact chunk walk) reaches `readPlate` below, which A06 never
+    // calls — this rule is the one reader that finds that file unreadable,
+    // and its line is unchanged by this.
     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.',
-      );
+      if (carriesPart) unreadable.push(page.name); // A06 names the file; this body says only that it did not read it
       continue;
     }
     if (on.length > 1) {
@@ -323,15 +338,49 @@ export function a19OverlayPngsHaveAlpha({ fail: failed, skip }: Verdicts, { atla
         'spine does not run this check.',
     );
   }
-  if (failures > 0 || unread.length === 0) return;
-  skip(
-    'A19_OVERLAY_PNGS_HAVE_ALPHA',
-    unread.length === pagesWithParts
-      ? `no part's alpha was read: none of the ${pagesWithParts} page file(s) carrying a part is on disk, which ` +
-          'A17_ATLAS_PAGE_FILES_EXIST names file by file, and that is not a pass while every part is unread'
-      : `${unread.length} of the ${pagesWithParts} page(s) carrying a part were not read — ` +
-          `${unread.map((name) => JSON.stringify(name)).join(', ')} — because the file is not on disk, which ` +
-          `A17_ATLAS_PAGE_FILES_EXIST names. Every part on the ${pagesWithParts - unread.length} page(s) that were ` +
-          "read can draw a transparent pixel, and that is not a pass while a part's alpha is unread",
+  if (failures > 0 || unread.length + unreadable.length === 0) return;
+  skip('A19_OVERLAY_PNGS_HAVE_ALPHA', unreadAlpha(pagesWithParts, unread, unreadable));
+}
+
+/**
+ * The SKIP's reason over the pages carrying a part that this rule did not
+ * read: `missing` (not on disk, which A17 names — issue #1055) and
+ * `unreadable` (on disk and not a PNG rigc can read, which A06 names — issue
+ * #1064). With only missing pages it is #1055's sentence to the byte; each
+ * group names its own owner, so one file is pointed at the one rule that
+ * names it.
+ */
+function unreadAlpha(pagesWithParts: number, missing: readonly string[], unreadable: readonly string[]): string {
+  const A17 = 'A17_ATLAS_PAGE_FILES_EXIST';
+  const A06 = 'A06_ATLAS_PAGE_SIZE_MATCHES_PNG';
+  const names = (pages: readonly string[]): string => pages.map((name) => JSON.stringify(name)).join(', ');
+  const total = missing.length + unreadable.length;
+  if (total === pagesWithParts) {
+    if (unreadable.length === 0) {
+      return (
+        `no part's alpha was read: none of the ${pagesWithParts} page file(s) carrying a part is on disk, which ` +
+        `${A17} names file by file, and that is not a pass while every part is unread`
+      );
+    }
+    if (missing.length === 0) {
+      return (
+        `no part's alpha was read: none of the ${pagesWithParts} page file(s) carrying a part can be read as PNG, ` +
+        `which ${A06} names file by file, and that is not a pass while every part is unread`
+      );
+    }
+    return (
+      `no part's alpha was read: of the ${pagesWithParts} page file(s) carrying a part, ${missing.length} are not ` +
+      `on disk, which ${A17} names file by file, and ${unreadable.length} cannot be read as PNG, which ${A06} ` +
+      'names file by file, and that is not a pass while every part is unread'
+    );
+  }
+  const because = [
+    ...(missing.length > 0 ? [`${names(missing)} — because the file is not on disk, which ${A17} names`] : []),
+    ...(unreadable.length > 0 ? [`${names(unreadable)} — because the file cannot be read as PNG, which ${A06} names`] : []),
+  ].join(', and — ');
+  return (
+    `${total} of the ${pagesWithParts} page(s) carrying a part were not read — ${because}. Every part on the ` +
+    `${pagesWithParts - total} page(s) that were read can draw a transparent pixel, and that is not a pass while ` +
+    "a part's alpha is unread"
   );
 }

package/src/assertions/bodies/a31.ts

@@ -0,0 +1,61 @@
+/**
+ * A31, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the skeleton JSON — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { isObj, type Json } from '../values.ts';
+
+export function a31DrawOrderOffsetsResolve({ fail, skip }: Verdicts, raw: Json | null): void {
+  if (!raw) return skip('A31_DRAW_ORDER_OFFSETS_RESOLVE', 'the skeleton JSON did not parse (A00 owns that failure)');
+  if (!Array.isArray(raw.slots) || !isObj(raw.animations)) {
+    return skip('A31_DRAW_ORDER_OFFSETS_RESOLVE', 'the skeleton declares no slots or no animations');
+  }
+  const slotIndex = new Map<string, number>();
+  (raw.slots as unknown[]).forEach((slot, i) => {
+    if (isObj(slot) && typeof slot.name === 'string') slotIndex.set(slot.name, i);
+  });
+  const slotCount = (raw.slots as unknown[]).length;
+  let sawATimeline = false;
+  for (const [animName, anim] of Object.entries(raw.animations as Json)) {
+    if (!isObj(anim) || !Array.isArray(anim.drawOrder)) continue;
+    sawATimeline = true;
+    (anim.drawOrder as unknown[]).forEach((key, k) => {
+      const at = `animation "${animName}" drawOrder key ${k}`;
+      if (!isObj(key) || !Array.isArray(key.offsets)) return; // no offsets = setup order
+      let previous = -1;
+      for (const entry of key.offsets as unknown[]) {
+        if (!isObj(entry) || typeof entry.slot !== 'string' || typeof entry.offset !== 'number') {
+          fail('A31_DRAW_ORDER_OFFSETS_RESOLVE', `${at}: an offset is not { slot: string, offset: number }`);
+          continue;
+        }
+        const index = slotIndex.get(entry.slot);
+        if (index === undefined) {
+          fail('A31_DRAW_ORDER_OFFSETS_RESOLVE', `${at}: slot "${entry.slot}" is not in the skeleton`);
+          continue;
+        }
+        if (index <= previous) {
+          const detail =
+            `${at}: slot "${entry.slot}" is at index ${index}, after an entry at index ${previous} — ` +
+            'offsets must be in ascending slot order or the loader never finishes reading them';
+          fail('A31_DRAW_ORDER_OFFSETS_RESOLVE', detail);
+          continue;
+        }
+        previous = index;
+        const landing = index + entry.offset;
+        if (!Number.isInteger(entry.offset) || landing < 0 || landing >= slotCount) {
+          fail(
+            'A31_DRAW_ORDER_OFFSETS_RESOLVE',
+            `${at}: slot "${entry.slot}" is at index ${index} and offset ${entry.offset} puts it at ${landing}, ` +
+              `outside the ${slotCount} slots`,
+          );
+        }
+      }
+    });
+  }
+  if (!sawATimeline) return skip('A31_DRAW_ORDER_OFFSETS_RESOLVE', 'no animation carries a drawOrder timeline');
+}