spine-rigc 1.6.2 → 1.8.0

package/src/assertions/model/index.ts

@@ -0,0 +1,130 @@
+/**
+ * The model side of the validator (issue #1025, step 4c of #380): the
+ * assertions that moved out of `src/validate.ts`, run over the model document
+ * and rigc's core instead of over what spine-core loaded.
+ *
+ * ⭐ **One body, two suppliers.** Every moved assertion is one function under
+ * `../bodies/`, written against a fact interface under `../facts/`.
+ * `validate()` supplies the facts from spine-core's loaded objects and calls
+ * the body inside its own `check`; this entry supplies them from the document
+ * (`./parse.ts`, `./skin_entries.ts`, `./atlas_pages.ts`, `./slot_colour.ts`)
+ * and calls the same body inside the same harness (`../harness.ts`). The
+ * selftest holds the two to the same lines on every call it makes with a
+ * model in hand, and `tools/verdict_gate.ts` on every recipe.
+ *
+ * 🔸 **What the entry is given.** The document's text, the directory its
+ * pages resolve against, and the profile — and nothing read off a Spine file:
+ * a model-side verdict that read `skeleton.json` would be a second reading of
+ * the encoding, which is the round trip's subject and not the rig's. The stage
+ * and the atlas's `pma`, which the document does not hold, are the caller's to
+ * give once an assertion that reads them moves (a later cut, the census's §2).
+ *
+ * ⛔ **Not wired into any command.** `build` keeps the round trip and its
+ * forty-nine lines; this entry is what the selftest and the instrument call
+ * until every moved assertion is on it (the card's design, point 7).
+ *
+ * Links nothing from the runtime, directly or through what it imports — held
+ * by the selftest's `VF` controls.
+ */
+import { ASSERTION_KIND, type AssertionProfile } from '../kinds.ts';
+import { verdictHarness, type VerdictHarness, type Verdicts, type VerdictLists } from '../harness.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_MODEL } from '../reasons.ts';
+import { a03RegionWidthHeightFinite } from '../bodies/a03.ts';
+import { a11NoClippingAttachments } from '../bodies/a11.ts';
+import { a17AtlasPageFilesExist } from '../bodies/a17.ts';
+import { a45SeparableColorTimelinesOwnTheirChannelsAndPoseAsWritten } from '../bodies/a45.ts';
+import { A00_MODEL_READ, A00_MODEL_REGIONS_ON_PAGES, MODEL_PARSE_KIND, modelRead, modelRegionsOnPages, SKIP_NO_MODEL_DOCUMENT, type ReadDocument } from './parse.ts';
+import { modelSkinEntries } from './skin_entries.ts';
+import { modelAtlasPages } from './atlas_pages.ts';
+import { modelSlotColour } from './slot_colour.ts';
+import type { SkinEntryFacts } from '../facts/skin_entries.ts';
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import type { SlotColourFacts } from '../facts/slot_colour.ts';
+
+/** What the model side is given. */
+export interface ModelValidateInput {
+  /** The document `build` writes beside the Spine pair (`skeleton.model.json`). */
+  modelText: string;
+  /** The directory the document's page names resolve against — the build's `--out`. */
+  atlasDir: string;
+  profile: AssertionProfile;
+}
+
+/** The model side's report: `validate()`'s shape, over the moved assertions and the two parse rules. */
+export interface ModelReport extends VerdictLists {
+  profile: AssertionProfile;
+}
+
+/**
+ * The fact families, composed: one supplier per family under `./`, each a
+ * function of the read document. A body names the family it reads, so a later
+ * cut that moves an assertion over an existing family adds a body file and a
+ * row below, and one over a new family adds a facts file, a supplier file and
+ * a field here.
+ */
+export interface ModelSupply {
+  skinEntries: (read: ReadDocument) => SkinEntryFacts;
+  atlasPages: (read: ReadDocument) => AtlasPageFacts;
+  slotColour: (read: ReadDocument) => SlotColourFacts;
+}
+
+/** The suppliers the model side runs on. */
+export const MODEL_SUPPLY: ModelSupply = { skinEntries: modelSkinEntries, atlasPages: modelAtlasPages, slotColour: modelSlotColour };
+
+/**
+ * One moved assertion: its code, and how the model side runs its body once the
+ * document is read. The list is the registry of what has moved — each later
+ * cut appends its rows — and the selftest reads it for the codes it compares.
+ */
+export interface MovedAssertion {
+  code: string;
+  /** The body, over the document. Not called when the model side read no document. */
+  run: (verdicts: Verdicts, read: ReadDocument, input: ModelValidateInput, supply: ModelSupply) => void;
+  /** What the body SKIPs with when there is no document — the model side's counterpart of the reason `validate()` gives when the round trip produced nothing. */
+  unread: string;
+}
+
+/**
+ * The moved assertions, in `validate()`'s report order. `SKIP_NO_ATLAS` for
+ * A17 rather than `SKIP_NO_MODEL` because that is what A17 says over a missing
+ * atlas on either side: its body reads only the pages, and on this side no
+ * document means no pages.
+ */
+export const MOVED_ASSERTIONS: readonly MovedAssertion[] = [
+  { code: 'A03_REGION_WIDTH_HEIGHT_FINITE', run: (v, read, _input, supply) => a03RegionWidthHeightFinite(v, supply.skinEntries(read)), unread: SKIP_NO_MODEL },
+  { code: 'A11_NO_CLIPPING_ATTACHMENTS', run: (v, read, _input, supply) => a11NoClippingAttachments(v, supply.skinEntries(read)), unread: SKIP_NO_MODEL },
+  { code: 'A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN', run: (v, read, _input, supply) => a45SeparableColorTimelinesOwnTheirChannelsAndPoseAsWritten(v, supply.slotColour(read)), unread: SKIP_NO_MODEL },
+  { code: 'A17_ATLAS_PAGE_FILES_EXIST', run: (v, read, input, supply) => a17AtlasPageFilesExist(v, supply.atlasPages(read), input), unread: SKIP_NO_ATLAS },
+];
+
+/** The codes the model side prints: its two parse rules, then the moved assertions. */
+export const MODEL_SIDE_CODES: readonly string[] = [A00_MODEL_READ, A00_MODEL_REGIONS_ON_PAGES, ...MOVED_ASSERTIONS.map((m) => m.code)];
+
+/** The parse: the reader, then the region rule. Returns the document when both held. */
+function parse(h: VerdictHarness, modelText: string): ReadDocument | null {
+  const read = h.check(A00_MODEL_READ, () => modelRead(h.verdicts, modelText)) ?? null;
+  if (read === null) {
+    h.check(A00_MODEL_REGIONS_ON_PAGES, () => h.skip(A00_MODEL_REGIONS_ON_PAGES, SKIP_NO_MODEL_DOCUMENT));
+    return null;
+  }
+  return h.check(A00_MODEL_REGIONS_ON_PAGES, () => modelRegionsOnPages(h.verdicts, read)) === true ? read : null;
+}
+
+/**
+ * Run the model side: the parse, then every moved assertion — each over the
+ * document, or skipped naming the parse when there is none — and return the
+ * report in `validate()`'s shape, which `reportLines` in `src/validate.ts`
+ * prints. `plant` replaces a family's supplier; only the selftest's plants
+ * pass one.
+ */
+export function validateModel(input: ModelValidateInput, plant: Partial<ModelSupply> = {}): ModelReport {
+  const supply: ModelSupply = { ...MODEL_SUPPLY, ...plant };
+  const h = verdictHarness(input.profile, { ...ASSERTION_KIND, ...MODEL_PARSE_KIND }, 'the model side');
+  const read = parse(h, input.modelText);
+  for (const moved of MOVED_ASSERTIONS) {
+    h.check(moved.code, () => (read === null ? h.skip(moved.code, moved.unread) : moved.run(h.verdicts, read, input, supply)));
+  }
+  const { failures, passed, skipped, profileSkipped, stats } = h;
+  return { failures, passed, skipped, profileSkipped, stats, profile: input.profile };
+}
+

package/src/assertions/model/parse.ts

@@ -0,0 +1,136 @@
+/**
+ * The model side's parse (issue #1025, step 4c of #380): what stands where
+ * `A00_ROUNDTRIP_PARSE` stands when there is no spine-core object to load.
+ *
+ * Two rules, each a named line:
+ *
+ * - **`A00_MODEL_READ`** — `readModel` (`src/core/index.ts`) read the document.
+ *   Its refusals are the parse: every one names the path of what it refused,
+ *   and the line carries the reader's own sentence. A document it refuses is
+ *   one whose wrongness has no readable model to live in — a size that is
+ *   absent, a colour that is not hex, key times that do not increase (the
+ *   census found four of the slice's mutants there) — and that refusal is the
+ *   model side's verdict on it.
+ * - **`A00_MODEL_REGIONS_ON_PAGES`** — every region a record resolves through
+ *   is a region of the document's `pages`, and no region record states an
+ *   `atlas` of `null`. Measured by the census before this rule existed: 23
+ *   cases fail `A00_ROUNDTRIP_PARSE` in a selftest run, and 14 of them are
+ *   documents `readModel` accepts — a record's path naming no region (five
+ *   forged), and nine builds whose model holds `atlas: null` because the build
+ *   had no art or its pack lacked the region. spine-core refuses all fourteen
+ *   at load (`Region not found in atlas`), and the core refused them only when
+ *   it posed. This rule refuses them where the parse does, by the record's
+ *   address and the region's name.
+ *
+ * The region a record resolves through is the core's rule, called rather than
+ * restated: its name and path are `shownRow`'s (path, else name, else the
+ * placeholder), a series' frame names are `frameRegionName` over the series
+ * `readUvSequences` reads, and a name is looked up as `documentPageLookup`
+ * looks it up — the first region of that exact spelling, pages in order.
+ *
+ * ⛔ Rejected: the codes `M00_…` (`M` plus two digits names a mutant row in the
+ * selftest — `M03`, `M12` — and a reader of a report could not tell a rule
+ * from a plant), and a new assertion number (`A50`): the gate's registry would
+ * then demand the row of every `validate()` report, and these two rules have no
+ * meaning there. `A00_` because they stand in A00's place, and `_MODEL_`
+ * because they are the model side's.
+ *
+ * Links nothing from the runtime.
+ */
+import { CORE_REGION_KINDS, CoreInputError, readModel, shownRow, type CompiledDocument } from '../../core/index.ts';
+import { documentPageLookup, frameRegionName, readUvSequences } from '../../core/uvs.ts';
+import type { AssertionKind } from '../kinds.ts';
+import type { Verdicts } from '../harness.ts';
+
+/** The reader's refusal, as a line. */
+export const A00_MODEL_READ = 'A00_MODEL_READ';
+/** The region rule, as a line. */
+export const A00_MODEL_REGIONS_ON_PAGES = 'A00_MODEL_REGIONS_ON_PAGES';
+
+/** The two rules' kinds: both are validity — a document either is one a build could pose, or it is not. */
+export const MODEL_PARSE_KIND: Readonly<Record<string, AssertionKind>> = {
+  [A00_MODEL_READ]: 'validity',
+  [A00_MODEL_REGIONS_ON_PAGES]: 'validity',
+};
+
+/** What the region rule SKIPs with when the reader refused the document. */
+export const SKIP_NO_MODEL_DOCUMENT = `the reader refused the document, so there is no record to resolve (${A00_MODEL_READ} owns that failure)`;
+/** What the region rule SKIPs with when no record resolves through a region. */
+export const SKIP_NO_REGION_RECORD = 'no record of the document resolves through an atlas region';
+
+/** The document as both readings hold it: `readModel`'s, and the JSON the suppliers read spellings from. */
+export interface ReadDocument {
+  doc: CompiledDocument;
+  json: Record<string, unknown>;
+}
+
+/** `A00_MODEL_READ`'s body: the document read, or the reader's refusal as a FAIL. Returns the read document or null. */
+export function modelRead({ fail }: Verdicts, modelText: string): ReadDocument | null {
+  let doc: CompiledDocument;
+  try {
+    doc = readModel(modelText);
+  } catch (err) {
+    if (!(err instanceof CoreInputError)) throw err;
+    fail(A00_MODEL_READ, err.message);
+    return null;
+  }
+  return { doc, json: JSON.parse(modelText) as Record<string, unknown> };
+}
+
+/**
+ * Every region name each record resolves through, by the record's address —
+ * the census's rule R-region, read with the core's own lookups. A record of a
+ * kind that draws no region (clipping, path, bounding box) resolves through
+ * none.
+ */
+export function regionNamesOf(read: ReadDocument): Array<{ where: string; names: string[]; atlasNull: boolean }> {
+  const sequences = readUvSequences(read.json);
+  const out: Array<{ where: string; names: string[]; atlasNull: boolean }> = [];
+  for (const skin of read.doc.skins) {
+    for (const [slot, table] of Object.entries(skin.attachments)) {
+      for (const [placeholder, record] of Object.entries(table)) {
+        if (!CORE_REGION_KINDS.has(record.kind)) continue;
+        const path = shownRow({ skin: skin.name, placeholder, record }).path as string;
+        const series = sequences.get(`${skin.name}/${slot}/${placeholder}`);
+        const names = series === undefined ? [path] : Array.from({ length: series.count }, (_, i) => frameRegionName(path, series, i));
+        out.push({ where: `skin "${skin.name}" slot "${slot}" placeholder "${placeholder}"`, names, atlasNull: record.kind === 'region' && record.atlas === null });
+      }
+    }
+  }
+  return out;
+}
+
+/** `A00_MODEL_REGIONS_ON_PAGES`'s body. Returns whether the document passed it. */
+export function modelRegionsOnPages({ fail, skip }: Verdicts, read: ReadDocument): boolean {
+  let records: ReturnType<typeof regionNamesOf>;
+  try {
+    records = regionNamesOf(read);
+  } catch (err) {
+    // A series `readModel` keeps only the count of: `readUvSequences` refuses its `start` or `digits` by path.
+    if (!(err instanceof CoreInputError)) throw err;
+    fail(A00_MODEL_REGIONS_ON_PAGES, err.message);
+    return false;
+  }
+  if (records.length === 0) {
+    skip(A00_MODEL_REGIONS_ON_PAGES, SKIP_NO_REGION_RECORD);
+    return true;
+  }
+  if (read.doc.pages === null) {
+    fail(A00_MODEL_REGIONS_ON_PAGES, `the document is ${read.doc.spec}, which states no pages, so none of the ${records.length} record(s) that resolve through a region can be found on one`);
+    return false;
+  }
+  const lookup = documentPageLookup(read.doc.pages);
+  let held = true;
+  for (const { where, names, atlasNull } of records) {
+    if (atlasNull) {
+      fail(A00_MODEL_REGIONS_ON_PAGES, `${where}: the region record's atlas is null — the build had no rectangle for "${names[0]}", and a runtime loading it finds no region`);
+      held = false;
+    }
+    for (const name of names) {
+      if (lookup(name) !== null) continue;
+      fail(A00_MODEL_REGIONS_ON_PAGES, `${where}: resolves through the region ${JSON.stringify(name)}, which no page of the document holds`);
+      held = false;
+    }
+  }
+  return held;
+}

package/src/assertions/model/skin_entries.ts

@@ -0,0 +1,58 @@
+/**
+ * The model side's supply of `SkinEntryFacts` (issue #1025, step 4c of #380):
+ * the skins' region attachments and clipping count, read off the document.
+ *
+ * ⭐ **In the file's order, by the emitter's own rule.** The document holds the
+ * skins in the spec's order and the Spine file holds them in the editor's
+ * (`default` first, the rest by the editor's comparator), so a walk of the
+ * document in its own order lists the same entries in another order on a rig
+ * whose skins the comparator moves — the census measured that on 3 of 52
+ * multi-skin compiles. The skins are therefore put in the file's order by
+ * calling `editorSkinOrder` from `src/compile.ts`, the function the emitter is
+ * handed (`emitSkins`), not by a copy of its rule. Within a skin the entries go
+ * slot by slot in the skeleton's slot order — the document's `slots`, which is
+ * the emitted array's order — and a slot's entries in its table's order, which
+ * the emitter writes unchanged; the selftest measures this walk equal to
+ * spine-core's on every multi-skin build it makes.
+ *
+ * A region's name is the record's `name`, else its placeholder — `shownRow`'s
+ * rule in the core — and its size the record's `width` and `height`, the
+ * numbers the file states (`readModel` refuses a size that is not a finite
+ * number, so a size the runtime would load as NaN has no document to arrive in).
+ *
+ * Links nothing from the runtime.
+ */
+import { editorSkinOrder } from '../../compile.ts';
+import { shownRow } from '../../core/index.ts';
+import type { RegionEntry, SkinEntryFacts } from '../facts/skin_entries.ts';
+import type { ReadDocument } from './parse.ts';
+
+/** How the skins are put in the file's order: the emitter's rule. A parameter only so the selftest can show what the document's own order would print (`VF05`). */
+export type SkinOrder = <T extends { name: string }>(skins: readonly T[]) => T[];
+
+/** The skins' entries in the file's walk order, each with its skin, slot and placeholder. */
+export function fileOrderedEntries(read: ReadDocument, order: SkinOrder = editorSkinOrder): Array<{ skin: string; slot: string; placeholder: string; record: ReadDocument['doc']['skins'][number]['attachments'][string][string] }> {
+  const out: ReturnType<typeof fileOrderedEntries> = [];
+  for (const skin of order(read.doc.skins)) {
+    for (const { name: slot } of read.doc.slots) {
+      const table = skin.attachments[slot];
+      if (table === undefined) continue;
+      for (const [placeholder, record] of Object.entries(table)) out.push({ skin: skin.name, slot, placeholder, record });
+    }
+  }
+  return out;
+}
+
+export function modelSkinEntries(read: ReadDocument, order: SkinOrder = editorSkinOrder): SkinEntryFacts {
+  const regionAttachments: RegionEntry[] = [];
+  let clippingCount = 0;
+  for (const entry of fileOrderedEntries(read, order)) {
+    if (entry.record.kind === 'clipping') clippingCount++;
+    if (entry.record.kind !== 'region') continue;
+    const geometry = entry.record.geometry;
+    // `readModel` reads every region record's geometry or refuses the document, so a record without one is this module's defect.
+    if (geometry?.kind !== 'region') throw new Error(`internal: skin "${entry.skin}" slot "${entry.slot}" placeholder "${entry.placeholder}" is a region record the reader returned without its geometry`);
+    regionAttachments.push({ name: shownRow(entry).name, width: geometry.region.width, height: geometry.region.height });
+  }
+  return { regionAttachments, clippingCount };
+}

package/src/assertions/model/slot_colour.ts

@@ -0,0 +1,80 @@
+/**
+ * The model side's supply of `SlotColourFacts` (issue #1025, step 4c of #380).
+ *
+ * - **The slot timelines, in the file's order and spelling.** The document
+ *   holds each animation's slot timelines in the order they are applied, with
+ *   every key as the compiler built it; the Spine file keys the animations in
+ *   the editor's order and passes every key through two passes. So the
+ *   animations are put in order by `editorAnimationOrder` (`src/compile.ts`,
+ *   the function the emitter is handed), and the timelines are laid out as the
+ *   file lays them and handed to the emitter's own `withoutParserDefaults` and
+ *   `inEditorKeyOrder` (`src/keyorder.ts`) — so a key field the emitter would
+ *   leave out at the parser's default is left out here too, and a body
+ *   printing `JSON.stringify(key.value)` prints what it prints over the file.
+ *   Nothing here restates either rule.
+ * - **Whether an animation exists**: the document's own roster.
+ * - **A slot's posed colour**: the core's raw entry (`poseRawAnimation`,
+ *   `src/core/raw.ts`) taking one step of the time on a fresh non-looping
+ *   track, under the view the core poses with no skin set (`noSkinView`,
+ *   `src/render_core.ts`) — the reading of what `validate()` does through
+ *   spine-core (a fresh skeleton, no skin, setup pose, the track stepped to the
+ *   time and applied). Its slot rows are the ones `CR03` holds bit for bit to
+ *   spine-core on every frame of the nineteen recipes; that the two readings
+ *   print the same A45 line is the selftest's supplier check, on every call
+ *   that poses one (`VF02`). A channel the pose read as no number is NaN, as a
+ *   non-finite channel reads on the runtime's side.
+ *
+ * Links nothing from the runtime.
+ */
+import { editorAnimationOrder } from '../../compile.ts';
+import type { CompiledDocument } from '../../core/index.ts';
+import { poseRawAnimation } from '../../core/raw.ts';
+import { inEditorKeyOrder, withoutParserDefaults } from '../../keyorder.ts';
+import { noSkinView } from '../../render_core.ts';
+import type { SlotColourFacts, SlotTimelines } from '../facts/slot_colour.ts';
+import { isObj, type Json } from '../values.ts';
+import type { ReadDocument } from './parse.ts';
+
+const list = (v: unknown): Json[] => (Array.isArray(v) ? v.filter(isObj) : []);
+
+/** Every animation's slot timelines as the Spine file states them: `animations.<name>.slots.<slot>.<timeline> = keys`. */
+export function fileSlotTimelines(read: ReadDocument): SlotTimelines[] {
+  const byName = new Map<string, Json>();
+  for (const anim of list(read.json.animations)) if (typeof anim.name === 'string') byName.set(anim.name, anim);
+  const animations: Json = {};
+  for (const name of editorAnimationOrder([...byName.keys()])) {
+    const slots: Json = {};
+    for (const slot of list((byName.get(name) as Json).slots)) {
+      if (typeof slot.name !== 'string') continue;
+      const timelines: Json = {};
+      for (const timeline of list(slot.timelines)) {
+        if (typeof timeline.name === 'string') timelines[timeline.name] = list(timeline.keys).map((key) => ({ ...key }));
+      }
+      slots[slot.name] = timelines;
+    }
+    // An animation keying no slot writes no `slots` group — `emitAnimation`'s `if (animation.slots.size)`.
+    animations[name] = Object.keys(slots).length > 0 ? { slots } : {};
+  }
+  const file = inEditorKeyOrder(withoutParserDefaults({ animations }));
+  const out: SlotTimelines[] = [];
+  for (const [animation, anim] of Object.entries(file.animations)) {
+    if (!isObj(anim) || !isObj(anim.slots)) continue;
+    for (const [slot, timelines] of Object.entries(anim.slots)) if (isObj(timelines)) out.push({ animation, slot, timelines });
+  }
+  return out;
+}
+
+export function modelSlotColour(read: ReadDocument): SlotColourFacts {
+  let view: CompiledDocument | null = null;
+  return {
+    slotTimelines: fileSlotTimelines(read),
+    hasAnimation: (name) => read.doc.animations.some((a) => a.name === name),
+    posedSlot: (animation, slot, time) => {
+      view ??= noSkinView(read.doc);
+      const row = poseRawAnimation(view, animation, [time], {}, 'animation')[1].slots.find((r) => r[0] === slot);
+      if (row === undefined) return undefined;
+      const channel = (v: number | null): number => (v === null ? Number.NaN : v);
+      return { color: { r: channel(row[2]), g: channel(row[3]), b: channel(row[4]), a: channel(row[5]) } };
+    },
+  };
+}

package/src/assertions/reasons.ts

@@ -0,0 +1,127 @@
+/**
+ * What a SKIP says, by what the assertion was denied (issues #568, #580, #608).
+ *
+ * Moved here from `src/validate.ts` by issue #1025 (step 4c of #380), words
+ * unchanged: an assertion body now lives in a module that links nothing from
+ * the runtime (`./bodies/`), and the bodies print these sentences on both
+ * sides — over what spine-core loaded and over the model document. A sentence
+ * kept in the file that links spine-core could not be read by the second.
+ * `src/validate.ts` re-exports every one, so nothing that imported them from
+ * there moves.
+ */
+
+/**
+ * What a SKIP says when `A00_ROUNDTRIP_PARSE` handed an assertion nothing to
+ * look at.
+ *
+ * Two of them rather than one, because what an assertion was denied is the whole
+ * content of its SKIP: `A20` wanted the loaded skeleton and `A06` wanted the
+ * loaded atlas, and a reader who is told which can tell a rule that is waiting
+ * on the parse from one that is waiting on the art. Both point at A00 instead of
+ * restating its detail, which the FAIL row prints in full.
+ *
+ * Exported so a control compares against them rather than quoting them — the
+ * same reason `ASSERTION_NAMES` is exported.
+ */
+export const SKIP_NO_SKELETON = 'the round trip did not produce a skeleton to measure (A00 owns that failure)';
+export const SKIP_NO_ATLAS = 'the round trip did not produce an atlas to measure (A00 owns that failure)';
+/**
+ * The third of them, and it is NOT waiting on A00 (issue #608): the atlas parsed
+ * and it has no pages, which is what a compile that measured no art writes. The
+ * four rules whose only subject is a page — A06, A17, A19, A27 — have nothing to
+ * look at, and an empty loop walking out of `check()` is reported as a PASS.
+ */
+/*
+ * **An empty subject list: SKIP or PASS, and which one is derived (issue #580).**
+ *
+ * `check()` records a pass when a body runs to its end without a `fail()` or a
+ * `skip()`, so a body whose main construct is a loop over a list that is EMPTY
+ * passes having measured nothing — the vacuous green one ring out from the bare
+ * `return` guards issue #568 converted. Two different things can be true of such
+ * a loop, and the criterion decides between them by reading the rule's own name
+ * and its `fail()` sentences rather than by preference:
+ *
+ *   * A name of the form ⟨subject⟩_⟨property⟩ — `REGION_WIDTH_HEIGHT_FINITE`,
+ *     `MESH_TRIANGLES_AND_ENCODING`, `PHYSICS_CONSTRAINT_EFFECTIVE`,
+ *     `ATLAS_PAGE_SIZE_MATCHES_PNG` — quantifies over the subject it names, and
+ *     its `fail()` names a member of that subject, the value found and the value
+ *     required. With no member, nothing was measured: it **SKIPs**, and the
+ *     reason names the subject that was absent.
+ *   * A name of the form NO_⟨construct⟩ — `NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS`,
+ *     `NO_BONE_TRANSFORM_KEY`, `NO_CLIPPING_ATTACHMENTS`, `NO_DARK_COLOR`,
+ *     `NO_FULL_FRAME_MESH` — quantifies over occurrences of something a correct
+ *     artifact has NONE of, and its `fail()` reports that the construct is
+ *     present rather than measuring a value on it. Zero occurrences IS the
+ *     measurement, so it **PASSes**: the loop is a search of the artifact, and
+ *     the artifact is what it measured.
+ *   * A name carrying both halves takes each at its word.
+ *     `A15_IDLE_NO_MESH_BONE_KEYS` is the pattern and already reads this way: no
+ *     `idle` animation, or an `idle` with no bone timeline, is the named subject
+ *     absent and SKIPs; no mesh-driving bone among the bones `idle` does key is
+ *     the construct absent and passes. `A10_NO_NAN_AFTER_STEPPING` was the same
+ *     shape until issue #902, and is the next bullet's now: #882 gave it a
+ *     setup-pose clause whose subject is the bones, beside the stepping clause
+ *     whose subject is the animations.
+ *   * An assertion with more than one clause SKIPs only when EVERY clause had
+ *     nothing to measure, which is the shape `A09`, `A33` and `A38` already
+ *     carry (`polygons.length === 0 && endsChecked === 0`), and `A10` since #902.
+ *     `A13_MESH_BUDGET` is why the clause is stated: a declared slot budget is
+ *     measured against a count of mesh slots, and zero is a count, so that half
+ *     passes on a rig with no mesh — while a rig that declares only a TRIANGLE
+ *     budget has nothing left to measure and skips.
+ *
+ * ⚠️ What the criterion is not allowed to become is a table of assertions with
+ * their verdicts written beside them. Every row above is decided by reading the
+ * name and the sentences the assertion already prints, so a rule added tomorrow
+ * is decided by the same reading and nobody re-opens this question.
+ */
+
+/**
+ * What a SKIP says when the artifact carries no member of the subject a rule
+ * quantifies over (issue #580), by subject.
+ *
+ * One constant per SUBJECT rather than one per assertion, for the reason the two
+ * above are two: what the rule was denied is the whole content of its SKIP, and
+ * three rules denied the same thing should say so in the same words. Exported so
+ * a control compares against them rather than quoting them.
+ */
+export const SKIP_NO_REGION_ATTACHMENT = 'the skeleton carries no region attachment';
+export const SKIP_NO_MESH_ATTACHMENT = 'the skeleton carries no mesh attachment';
+export const SKIP_NO_ANIMATION = 'the skeleton carries no animation';
+/**
+ * A10's (issue #902): its setup clause reads the bones and its stepping clause
+ * the animations, so it skips only when the skeleton carries neither — and the
+ * sentence is `SKIP_NO_ANIMATION`'s with the second subject added, so the two
+ * cannot drift into different words for the same absence.
+ */
+export const SKIP_NO_POSE = `${SKIP_NO_ANIMATION} and no bone, so there is no setup pose to read and nothing to step`;
+export const SKIP_NO_TIMELINE = 'no animation here carries a timeline';
+export const SKIP_NO_PHYSICS_CONSTRAINT = 'the skeleton declares no physics constraint';
+export const SKIP_NO_ATLAS_PAGE = 'the atlas declares no page';
+export const SKIP_NO_ATLAS_REGION = 'the atlas declares no region';
+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" or "rgb2" timeline, so there is no two-colour tint to read back';
+export const SKIP_NO_SEPARABLE_COLOR =
+  'no animation keys an "rgb" or "alpha" timeline, so there is no separable slot colour to read back';
+export const SKIP_NO_LINKED_MESH = 'no attachment in this skeleton takes its geometry from another one';
+export const SKIP_NO_SEQUENCE =
+  'no attachment carries a "sequence" block and no animation keys a "sequence" timeline, so there is no numbered series to read back';
+/**
+ * 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
+ * eight constants and quotes the ninth is a control with a hand-kept exception
+ * in it.
+ */
+export const SKIP_NO_DECLARED_DURATION =
+  'the motion spec declares no animations and the skeleton has none — a static rig has no duration to compare';
+
+/**
+ * The model side's `SKIP_NO_SKELETON` (issue #1025): the reader refused the
+ * document, or the document names a region its pages lack, so a body that
+ * reads the model has nothing to read. It names the two model-side parse
+ * rules rather than A00, because on this side there is no round trip — the
+ * reader and the region rule are what stand in its place (`./model/parse.ts`).
+ */
+export const SKIP_NO_MODEL = 'the model side read no document to measure (A00_MODEL_READ or A00_MODEL_REGIONS_ON_PAGES owns that failure)';

package/src/assertions/values.ts

@@ -0,0 +1,39 @@
+/**
+ * How an assertion body reads a value — the helpers the bodies under
+ * `./bodies/` share with the ones still in `src/validate.ts` (issue #1025,
+ * step 4c of #380), moved here unchanged so both read a value one way. Links
+ * nothing from the runtime.
+ */
+
+/** A JSON object as `JSON.parse` returns it. */
+export type Json = Record<string, unknown>;
+
+/** A JSON object, and not an array or `null`. */
+export function isObj(v: unknown): v is Json {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The time to pose a key at so that the runtime is AT it: the later of the
+ * file's number and that number as spine-core stores it (issue #771).
+ *
+ * 🚨 Every timeline keeps its key times in a `Float32Array`
+ * (`Utils.newFloatArray`), and a key time the float cannot hold exactly is
+ * stored at the nearest one — for `0.2`, `0.20000000298…`, which is LATER than
+ * the double `0.2`. Stepped to the file's own number, a timeline is then just
+ * BEFORE its key: before a first key it writes the setup value (`time <
+ * frames[0]`), and past a stepped key it still holds the one before
+ * (`frames[i] > time`). That is a pose one float step from the key, not the
+ * key's — measured on the selftest's own `ingest_probe`, whose `alpha` key at
+ * 0.2 posed the setup 1.0 and was refused as `the key states value 0.4`.
+ *
+ * ⚠️ The later of the two rather than `Math.fround` alone: where the float
+ * rounds DOWN, the file's number is already past the stored key, and a runtime
+ * built without typed arrays stores the double itself — in both, the file's
+ * number is the one at or after the key. What a key time rounds to is the
+ * runtime's storage and not the file's statement, so a rule judging what a KEY
+ * states poses at the key; the rounding itself is nothing an author can repair.
+ */
+export function atStoredKey(time: number): number {
+  return Math.max(time, Math.fround(time));
+}

package/src/atlas.ts

@@ -80,18 +80,20 @@
  *
  * `src/compile.ts` must stay independent of the runtime — that is what keeps the
  * compiler and the gate from checking each other's assumptions — so the importer
- * cannot reach for `TextureAtlas`. The reader below is therefore written straight
- * off `TextureAtlas`'s own field table (`dist/TextureAtlas.js`, the
- * `pageFields` / `regionFields` maps and the loop under them), including the
- * parts that look like mistakes and are not: the page name is trimmed and a
- * region name is the RAW line, a blank line closes a page block, `readEntry`
- * stops at four values, and `originalWidth/Height` fall back to `width/height`
- * only when BOTH are zero.
+ * cannot reach for `TextureAtlas`. The reader below therefore states, for every
+ * field the format has, what the runtime reads it as — the page and region
+ * fields of `dist/TextureAtlas.js` — including the readings that look like
+ * mistakes and are not: the page name is trimmed and a region name is the RAW
+ * line, a blank line closes a page block, an entry holds at most four values,
+ * and `originalWidth/Height` fall back to `width/height` only when BOTH are
+ * zero.
  *
  * A second opinion about a format is a liability, so it is measured rather than
- * asserted: the selftest parses every `.atlas` in the example corpus with both
- * this reader and `spine-core`'s and compares every field of every region. If
- * they ever disagree, that control goes red and this file is wrong.
+ * asserted: `PKR01` parses every `.atlas` in the example corpus with both this
+ * reader and `spine-core`'s `TextureAtlas` and compares every page's name, size
+ * and `pma` and every region's eleven fields — 10 atlas files, 132 regions, 3
+ * of them rotated, 0 fields apart when this was written (issue #1015). If they
+ * ever disagree, that control goes red and this file is wrong.
  */
 import { CompileError } from './errors.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
@@ -272,8 +274,9 @@ function int(text: string | undefined): number {
 /**
  * Read an atlas file's text into pages and regions.
  *
- * A transcription of `TextureAtlas`'s constructor, and deliberately a dull one —
- * every branch below is there because the runtime has it. Two additions, both of
+ * The format as the runtime reads it, field for field, and deliberately a dull
+ * reader — every branch below states a reading `PKR01` holds against
+ * `TextureAtlas`'s parse of the corpus (see the header). Two additions, both of
  * them fields a PLAYER has no use for and an IMPORTER does: `nameLine`, which
  * `rewritePageNames` needs, and the page's `scale:`, which is what turns a
  * region's texels back into the drawing's own size (`AtlasPage.scale`).
@@ -1337,7 +1340,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  * a plate's rows run downwards, so the kept rectangle's top row is
  * `originalHeight - offsetY - height`.
  *
- * ## A rotated region is TRANSCRIBED, not guessed at (issue #570)
+ * ## A rotated region is MEASURED, not guessed at (issue #570)
  *
  * This refused a rotated region until 2026-09-17, on the argument that the
  * runtime holds "three opinions" about the mapping. Measurement refutes the
@@ -1348,7 +1351,13 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  *     `dist/attachments/MeshAttachment.js:126-162`) is the one routine that
  *     states where a region's texels are for **all four** `degrees`, and it is
  *     the routine `substituteTexture` in [`src/render.ts`](render.ts) already
- *     goes through. The loop below is its inverse, term for term;
+ *     goes through. The loop below inverts what it samples: `PKR02` asks it,
+ *     for every texel of every region of the corpus atlases, which page texel
+ *     the runtime samples and compares the lift — 132 regions, 2,848,402
+ *     texels, 0 apart, three of them turned (90 twice, 270 once) and each of
+ *     those lifting differently with the turn ignored; `PK29` lifts the
+ *     packer's fixture at each of 0, 90, 180 and 270 back to its PNG byte for
+ *     byte;
  *   * `TextureAtlas`'s `u2`/`v2` (`dist/TextureAtlas.js:164-171`) transpose the
  *     rectangle at 90 and not at 270, so at 270 they describe a rectangle the
  *     page does not have — but `MeshAttachment.computeUVs` never reads them for
@@ -1358,8 +1367,9 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  *     region-attachment rendering defect (issue #199) and not a statement about
  *     where the drawing sits.
  *
- * Inverting the runtime's own expression on texel centres puts kept-rectangle
- * pixel `(x, y)` — `x` from the drawing's left, `y` down from `top` — at page
+ * On texel centres — at 90 and 270 measured against the runtime's sampling
+ * (`PKR02`), at 180 against the packer fixture's turn (`PK29`) — the mapping
+ * puts kept-rectangle pixel `(x, y)` — `x` from the drawing's left, `y` down from `top` — at page
  * pixel `(X + x, Y + y)` unturned, `(X + y, Y + width - 1 - x)` at 90,
  * `(X + width - 1 - x, Y + height - 1 - y)` at 180 and
  * `(X + height - 1 - y, Y + x)` at 270, writing `X`/`Y` for the region's own