spine-rigc 1.7.0 → 1.8.0

package/src/assertions/facts/slot_colour.ts

@@ -0,0 +1,43 @@
+/**
+ * Slot colour timelines and the colour a slot poses at (issue #1025, step 4c
+ * of #380) — the census's F18 and R4: the animations and the slot timelines
+ * they key, and one slot's light colour posed by the runtime's rule.
+ *
+ * ⭐ **The file's order, and the file's spelling.** A45's first clause names
+ * the timeline "which the file states last" as the one that wins, so the order
+ * of a slot's timelines is a value and not a presentation; and its findings
+ * print a key's `time`, `color` and `value` as the file states them. So the
+ * list holds, for every animation in the order the file keys them and every
+ * slot in the order the animation keys them, that slot's timelines in the
+ * file's order, each key as the file spells it. `validate()` reads it off the
+ * skeleton JSON; the model side produces it from the document by calling the
+ * emitter's own order and its own parser-default and key-order passes
+ * (`../model/slot_colour.ts`), so a key the emitter would write without a field
+ * reads without it here too.
+ */
+
+/** One animation's timelines on one slot: timeline name -> keys, as the file states them. */
+export interface SlotTimelines {
+  readonly animation: string;
+  readonly slot: string;
+  readonly timelines: Readonly<Record<string, unknown>>;
+}
+
+/** A slot's light colour as posed: four channels, NaN where the pose read no number. */
+export interface PosedSlotColour {
+  readonly color: { readonly r: number; readonly g: number; readonly b: number; readonly a: number };
+}
+
+/** What A45 reads. */
+export interface SlotColourFacts {
+  /** Every (animation, slot) pair whose timelines the file keys, in the header's order. */
+  readonly slotTimelines: readonly SlotTimelines[];
+  /** Whether the skeleton holds an animation of this name. */
+  hasAnimation(name: string): boolean;
+  /**
+   * The slot's colour with the animation applied at `time` on a fresh,
+   * non-looping track from the setup pose, no skin set — or `undefined` for a
+   * slot the skeleton does not have.
+   */
+  posedSlot(animation: string, slot: string, time: number): PosedSlotColour | undefined;
+}

package/src/assertions/harness.ts

@@ -0,0 +1,109 @@
+/**
+ * The harness an assertion body runs in, and the report it fills (issue
+ * #1025, step 4c of #380).
+ *
+ * One harness for both sides. `validate()` runs a body over the facts it reads
+ * off what spine-core loaded; the model side (`./model/index.ts`) runs the same
+ * body over the facts it reads off the model document and the core. What makes
+ * a line the same line on both sides is that the body is one function and the
+ * harness deciding PASS, SKIP, FAIL and PROF around it is one function too — a
+ * second copy of `check` would be a second place a verdict could be decided
+ * differently.
+ *
+ * Moved here from `validate()`, the rule unchanged: an assertion is recorded
+ * as passed only when its body neither failed nor skipped, a body that throws
+ * is a FAIL whose detail is `threw: <message>`, and a rule the profile does not
+ * carry is not run at all and is recorded as out of profile.
+ *
+ * This module links nothing from the runtime, directly or through what it
+ * imports — the condition for the model side to use it, held by the selftest.
+ */
+import { kindRunsUnder, type AssertionKind, type AssertionProfile } from './kinds.ts';
+
+/** One failure: the assertion's code and the sentence naming the object, the value found and the value required. */
+export interface Failure {
+  assertion: string;
+  detail: string;
+}
+
+/** What a body is handed: how to fail, how to declare it had nothing to measure, and the stats line it may add to. */
+export interface Verdicts {
+  fail: (assertion: string, detail: string) => void;
+  skip: (assertion: string, reason: string) => void;
+  stats: Record<string, number | string>;
+}
+
+/** The four lists and the stats a run of bodies leaves — the shape `validate()` returns, less the profile. */
+export interface VerdictLists {
+  failures: Failure[];
+  /** Assertions that ran and passed, in order. */
+  passed: string[];
+  /** Assertions that had nothing to run against, with the reason. */
+  skipped: Array<{ assertion: string; reason: string }>;
+  /** Assertions the profile does not apply, with their kind. */
+  profileSkipped: Array<{ assertion: string; kind: 'renderer' | 'archetype' }>;
+  stats: Record<string, number | string>;
+}
+
+/** A harness: the lists it fills, the two calls a body makes, and `check`, which runs a body. */
+export interface VerdictHarness extends VerdictLists {
+  fail: Verdicts['fail'];
+  skip: Verdicts['skip'];
+  /**
+   * Run one assertion; record it as passed only if it neither failed nor skipped,
+   * and do not run it at all when the profile does not carry that kind of rule.
+   *
+   * The unknown-assertion throw is deliberate: an assertion with no entry in
+   * the kind table would otherwise pick a profile by accident, and picking
+   * wrong means either a rule that never runs or a rule that fires on
+   * everybody's data.
+   *
+   * The body's return value is handed back — `undefined` when the assertion did
+   * not run or threw. `validate()`'s A00 uses it so that the loaded atlas and
+   * skeleton can be `const`: assigning them from inside this callback leaves
+   * the type checker unable to see that they were ever set, and every later read
+   * of `atlas.pages` or `data.bones` becomes a property of `never`.
+   */
+  check: <T>(assertion: string, body: () => T) => T | undefined;
+  /** `fail`, `skip` and `stats`, as one value to hand a body. */
+  verdicts: Verdicts;
+}
+
+/**
+ * A fresh harness for one run under `profile`. `kinds` is the kind table the
+ * run's codes are looked up in, and `who` names the run in the throw for a code
+ * the table lacks — `validate` for the gate, so its message is the one it was.
+ */
+export function verdictHarness(profile: AssertionProfile, kinds: Readonly<Record<string, AssertionKind>>, who: string): VerdictHarness {
+  const failures: Failure[] = [];
+  const passed: string[] = [];
+  const skipped: VerdictLists['skipped'] = [];
+  const profileSkipped: VerdictLists['profileSkipped'] = [];
+  const stats: Record<string, number | string> = {};
+  const fail = (assertion: string, detail: string): void => {
+    failures.push({ assertion, detail });
+  };
+  /** Declare that an assertion had nothing to check, and why. */
+  const skip = (assertion: string, reason: string): void => {
+    skipped.push({ assertion, reason });
+  };
+  const check = <T>(assertion: string, body: () => T): T | undefined => {
+    const kind = kinds[assertion];
+    if (!kind) throw new Error(`${who}: assertion "${assertion}" has no ASSERTION_KIND entry`);
+    if (!kindRunsUnder(kind, profile)) {
+      profileSkipped.push({ assertion, kind: kind === 'renderer' ? 'renderer' : 'archetype' });
+      return undefined;
+    }
+    const before = failures.length;
+    const skippedBefore = skipped.length;
+    let result: T | undefined;
+    try {
+      result = body();
+    } catch (err) {
+      fail(assertion, `threw: ${(err as Error).message}`);
+    }
+    if (failures.length === before && skipped.length === skippedBefore) passed.push(assertion);
+    return result;
+  };
+  return { failures, passed, skipped, profileSkipped, stats, fail, skip, check, verdicts: { fail, skip, stats } };
+}

package/src/assertions/kinds.ts

@@ -0,0 +1,102 @@
+/**
+ * What kind of rule each assertion is, and which profile runs which kind
+ * (issue #1025, step 4c of #380).
+ *
+ * The table lives here rather than in `src/validate.ts` because two harnesses
+ * read it now: `validate()`'s `check`, which runs an assertion over what
+ * spine-core loaded, and the model side's (`./harness.ts`), which runs the
+ * same body over the model document and the core. A profile has to exclude
+ * the same rules on both sides, and two copies of the table is how one of
+ * them would come to exclude a rule the other runs. This module links nothing
+ * from the runtime, which is the condition for the model side to read it.
+ */
+
+/** The two rulebooks — `ValidateProfile` in `src/validate.ts`, where the choice between them is argued. */
+export type AssertionProfile = 'spine' | 'spine-html';
+
+/** The three kinds a rule can be; the table's own comment says what each means. */
+export type AssertionKind = 'validity' | 'renderer' | 'archetype';
+
+/**
+ * What kind of rule each assertion is. Every assertion has an entry, and
+ * `check()` throws on a name that has none — a new assertion must state its kind
+ * rather than defaulting into one, because the default would decide, silently,
+ * whether it runs on foreign data.
+ *
+ *   validity  — the file is wrong for any consumer. Runs under every profile.
+ *   renderer  — valid Spine that this project's renderer or frame budget refuses.
+ *   archetype — a structural rule about rigc's own formations, meaningless to a
+ *               skeleton rigc did not compile.
+ *
+ * Two assertions are MIXED and are marked `validity` here because their
+ * validity half must never stop running; their policy clauses are gated inside
+ * the assertion body against `profile`, and each such clause says so where it
+ * lives. They are A06 (size-vs-PNG and every region's rectangle inside the page
+ * it names are validity; pma / rotation / two regions over the same texels are
+ * policy — the rectangle moved across that line in issue #694, and the reason
+ * is stated where it now sits) and A20 (weight coherence is validity; requiring
+ * a mesh to be weighted at all is policy).
+ *
+ * A08 was the third until issue #574 retired its policy clause. It required a
+ * skin entry's placeholder to be spelled like the region it resolves to, under
+ * a renderer that resolves art by `path` and has never read a placeholder — so
+ * restating it as the renderer's own join made it a tautology over the validity
+ * half. The argument, with the renderer lines it is measured against, sits above
+ * `check('A08_…')`.
+ */
+export const ASSERTION_KIND: Readonly<Record<string, AssertionKind>> = {
+  A00_ROUNDTRIP_PARSE: 'validity',
+  A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS: 'validity',
+  A02_NO_BONE_TRANSFORM_KEY: 'validity',
+  A03_REGION_WIDTH_HEIGHT_FINITE: 'validity',
+  A04_MESH_TRIANGLES_AND_ENCODING: 'validity',
+  A05_CURVE_ARRAY_LENGTH: 'validity',
+  A06_ATLAS_PAGE_SIZE_MATCHES_PNG: 'validity', // mixed — see above
+  A07_ATLAS_TEXT_SHAPE: 'validity',
+  A08_REGION_NAMES_MATCH_ATTACHMENTS: 'validity', // no longer mixed — see above (#574)
+  A09_ANIMATION_DURATION_MATCHES_SPEC: 'validity',
+  A10_NO_NAN_AFTER_STEPPING: 'validity',
+  A11_NO_CLIPPING_ATTACHMENTS: 'renderer',
+  A12_NO_DARK_COLOR: 'renderer',
+  A13_MESH_BUDGET: 'renderer',
+  A14_NO_FULL_FRAME_MESH: 'renderer',
+  A15_IDLE_NO_MESH_BONE_KEYS: 'renderer',
+  A16_SKELETON_VERSION_4_3: 'validity',
+  A17_ATLAS_PAGE_FILES_EXIST: 'validity',
+  A18_DETERMINISTIC_EMIT: 'validity',
+  A19_OVERLAY_PNGS_HAVE_ALPHA: 'renderer',
+  A20_MESH_WEIGHTS_COHERENT: 'validity', // mixed — see above
+  A21_MESH_RIM_PINNED: 'archetype',
+  A22_MESH_UVS_IN_UNIT_RANGE: 'validity',
+  A23_PHYSICS_CONSTRAINT_EFFECTIVE: 'validity',
+  A24_AXIS_SPACE_STROKE: 'archetype',
+  A25_DETACHED_BONE_PARENTAGE: 'archetype',
+  A26_SLOT_DRAW_ORDER: 'archetype',
+  A27_REGION_NAME_MATCHES_PAGE_FILENAME: 'renderer',
+  A28_RIBBON_ROWS_SHARE_WEIGHTS: 'archetype',
+  A29_STROKE_WITHIN_CONTACT_DEPTH: 'archetype',
+  A30_STROKE_WITHIN_CAP_CONTAINMENT: 'archetype',
+  A31_DRAW_ORDER_OFFSETS_RESOLVE: 'validity',
+  A32_EVENT_KEYS_RESOLVE: 'validity',
+  A33_VERTEX_ATTACHMENT_GEOMETRY: 'validity',
+  A34_CONSTRAINT_TIMELINE_TARGETS: 'validity',
+  A35_DEFORM_KEYS_FIT_THE_ATTACHMENT: 'validity',
+  A36_PATH_CONSTRAINT_EFFECTIVE: 'validity',
+  A37_SLIDER_CONSTRAINT_EFFECTIVE: 'validity',
+  A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED: 'validity',
+  A39_DEFORM_KEEPS_TRIANGLE_WINDING: 'archetype',
+  A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET: 'validity',
+  A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP: 'validity',
+  A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER: 'validity',
+  A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN: 'validity',
+  A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN: 'validity',
+  A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN: 'validity',
+  A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES: 'validity',
+  A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+  A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT: 'validity',
+};
+
+/** Whether `profile` runs a rule of `kind`: `spine` runs validity alone, `spine-html` every kind. */
+export function kindRunsUnder(kind: AssertionKind, profile: AssertionProfile): boolean {
+  return kind === 'validity' || profile === 'spine-html';
+}

package/src/assertions/model/atlas_pages.ts

@@ -0,0 +1,15 @@
+/**
+ * The model side's supply of `AtlasPageFacts` (issue #1025, step 4c of #380):
+ * the document's `pages` section, which `build` spells from the atlas text it
+ * writes (`pagesOfAtlas` in `src/model.ts`), so the page names are the ones
+ * the written atlas names, in its order and trimmed as the parser trims them.
+ * A `rigc-compiled/1` document states no pages, and reads as no atlas.
+ *
+ * Links nothing from the runtime.
+ */
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import type { ReadDocument } from './parse.ts';
+
+export function modelAtlasPages(read: ReadDocument): AtlasPageFacts {
+  return { atlas: read.doc.pages === null ? null : { pages: read.doc.pages.map((page) => ({ name: page.name })) } };
+}

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 };
+}