spine-rigc 1.7.0 → 1.9.0

package/src/assertions/facts/constraints.ts

@@ -0,0 +1,131 @@
+/**
+ * The constraints and the timelines that key them, as the bodies that ask
+ * "does this constraint do anything" read them (issue #1025, step 4c of
+ * #380) — the census's F12 to F17 and F19 with R1 and R2, for A23, A36, A37,
+ * A41, A42, A47 and A48.
+ *
+ * ⭐ **The order is the runtime's update order**, which is the file's
+ * `constraints` array and the document's: a body that prints one line per
+ * constraint prints them in this order, and `A42` compares two positions in
+ * it. A timeline's `constraint` is a position in the same list.
+ *
+ * ⭐ **The timelines are in the order the runtime builds them**: the
+ * animations in the file's order, and within one the groups `ik`,
+ * `transform`, `path`, `physics`, `slider` — whatever order the file keys
+ * them in [measured: an animation keying `slider`, `physics`, `transform`,
+ * `ik` in that key order loads ik, transform, physics, slider] — each group's
+ * constraints and their timelines in the file's order. A body printing one
+ * line per key prints them in this order.
+ *
+ * 🔸 **Values are the ones the runtime holds after its parse, and each
+ * derivation is a function rigc already runs**, called by the model side: a
+ * field the record leaves out reads the parser's value through the core's
+ * record readers (`readModel`); `massInverse` and `step` are the core
+ * physics record's `1 / mass` and `1 / fps`; a key's time and value are the
+ * float32 the core's timeline reader stores; a Bézier segment's samples are
+ * `bezierPolyline` (`src/core/animation.ts`), the runtime's curve the core
+ * reproduces; the constraints a physics timeline naming none reaches are
+ * read off the core's own `posedPhysics`, asked rather than restated.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** The five constraint kinds, in the motion spec's words. */
+export type ConstraintKind = 'ik' | 'transform' | 'path' | 'physics' | 'slider';
+
+/** The five components a physics constraint drives, by name. */
+export interface PhysicsComponents {
+  readonly x: number;
+  readonly y: number;
+  readonly rotate: number;
+  readonly scaleX: number;
+  readonly shearX: number;
+}
+
+/** The four bounded values of a physics constraint's setup pose — the fields `PHYSICS_POSE_RULES` judges. */
+export interface PhysicsSetup {
+  readonly mix: number;
+  readonly massInverse: number;
+  readonly strength: number;
+  readonly damping: number;
+}
+
+/** One constraint, in update order. Exactly one of the kind fields is set, the one its `kind` names. */
+export interface ConstraintEntry {
+  readonly kind: ConstraintKind;
+  readonly name: string;
+  /** The runtime class the constraint updates as (`IkConstraint`, `Slider`, …) — the word A42's sentence names `update` on. */
+  readonly runtimeClass: string;
+  readonly physics?: { readonly bone: string; readonly components: PhysicsComponents; readonly setup: PhysicsSetup; readonly step: number };
+  readonly path?: { readonly bones: readonly string[]; readonly slot: string; readonly setup: { readonly mixRotate: number; readonly mixX: number; readonly mixY: number } };
+  readonly slider?: {
+    /** The animation it applies — its name, how many timelines it carries and its duration — or `null` when it applies none. */
+    readonly animation: { readonly name: string; readonly timelines: number; readonly duration: number } | null;
+    /** The dial bone's name, or `null` for the bone-less form. */
+    readonly bone: string | null;
+    readonly loop: boolean;
+    readonly scale: number;
+    readonly mix: number;
+  };
+  readonly ik?: { readonly bones: readonly string[]; readonly target: string; readonly mix: number };
+  /**
+   * A transform constraint's six mix channels in frame order — `mixRotate`,
+   * `mixX`, `mixY`, `mixScaleX`, `mixScaleY`, `mixShearY` — each the field's
+   * name and its setup value where the constraint declares that property as
+   * a `to`, and `null` where it does not: a mix the constraint never reads.
+   */
+  readonly transform?: { readonly bones: readonly string[]; readonly mixes: ReadonlyArray<{ readonly field: string; readonly setup: number } | null> };
+}
+
+/** One frame of a constraint timeline: its time and its first channel, as the runtime stores them (float32). */
+export interface ConstraintFrame {
+  readonly time: number;
+  readonly value: number;
+}
+
+/** One constraint timeline of one animation. */
+export interface ConstraintTimeline {
+  readonly animation: string;
+  readonly kind: ConstraintKind;
+  /**
+   * What it keys, in the motion spec's word: `ik` or `transform` for those
+   * two; `position`, `spacing`, `mix`; `inertia` … `mix` or `reset`; `time`
+   * or `mix`.
+   */
+  readonly word: string;
+  /** The constraint it names, as a position in `constraints` — or −1 for a physics timeline naming none. */
+  readonly constraint: number;
+  /** The constraints it writes into, as positions in `constraints`. */
+  readonly reach: readonly number[];
+  /** Its frames; empty for `reset`. */
+  readonly frames: readonly ConstraintFrame[];
+  /**
+   * Every value one channel poses while it plays: each key's own and every
+   * sample of each Bézier segment between two keys, in frame order. Channel
+   * 0 is the first value a frame holds (an ik frame's `mix`, a transform
+   * frame's `mixRotate`, a path `mix` frame's `mixRotate`, the one value of
+   * the others).
+   */
+  channelValues(channel: number): readonly number[];
+  /**
+   * On a physics timeline whose value `PHYSICS_POSE_RULES` bounds, the number
+   * a keyed `value` becomes in the pose field the integrator reads — a `mass`
+   * key lands as its reciprocal (`massInverse`), the rest as they are: the
+   * census's R1. `validate()` asks the runtime's own `set`; the model side the
+   * rule's `toPose`, the compiler's reading, which a selftest control holds to
+   * the runtime's. Absent on every other timeline.
+   */
+  readonly posed?: (value: number) => number;
+}
+
+/** What A23, A36, A37, A41, A42, A47 and A48 read. */
+export interface ConstraintFacts {
+  /** How many animations the skeleton declares. */
+  readonly animations: number;
+  /** Every constraint, in update order. */
+  readonly constraints: readonly ConstraintEntry[];
+  /** Every constraint timeline of every animation, in the order the runtime builds them. */
+  readonly timelines: readonly ConstraintTimeline[];
+  /** The slots some skin gives a path attachment, each once. */
+  readonly pathSlots: readonly string[];
+}

package/src/assertions/facts/linked_meshes.ts

@@ -0,0 +1,38 @@
+/**
+ * The linked meshes the file declares, as `A44` reads them (issue #1025, step
+ * 4c of #380): the census's F10, the subject half.
+ *
+ * ⭐ **The subject is the file's links, not the loaded ones** (A44's own ⚠️):
+ * a link whose region is missing loads as nothing and is in no skin, so the
+ * walk is over what the file declares — the skins in the file's order, each
+ * skin's slot keys as the file keys them, each slot's entries in table order.
+ * The model side walks the document's `linkedmesh` records in that order, by
+ * calling the emitter's own orders (`editorSkinOrder`, `editorSlotKeyOrder`).
+ *
+ * 🔒 **Everything A44 refuses is the encoding's.** A linked mesh's record
+ * holds no geometry field at all — `uvs`, `triangles`, `vertices`, `hull` and
+ * `edges` written on a link exist only in the Spine text, which is the
+ * card's census row for A44 ("a link record has no geometry field"). So the
+ * clause that refuses them stays in `src/validate.ts`, which hands its finding
+ * about each link here; the model side, which cannot spell such a link, hands
+ * none. What moved is the roster — which links there are, so a rig with none
+ * SKIPs on both sides and a rig with some is measured on both.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** One link the file declares. */
+export interface LinkEntry {
+  readonly skin: string;
+  readonly slot: string;
+  readonly placeholder: string;
+  /** The placeholder of the mesh it draws. */
+  readonly source: string;
+  /** The kept clause's finding about this link — the geometry keys it states — in order; never on the model side. */
+  readonly encoding: readonly string[];
+}
+
+/** What A44 reads. */
+export interface LinkFacts {
+  readonly links: readonly LinkEntry[];
+}

package/src/assertions/facts/mesh_attachments.ts

@@ -0,0 +1,71 @@
+/**
+ * The mesh attachments, as the bodies that read their geometry and their
+ * weights see them (issue #1025, step 4c of #380) — the census's F07 (vertex
+ * data), F08 (mesh geometry) and F10 (the linked-mesh join), for A04, A20,
+ * A21, A28 and the mesh half of A23.
+ *
+ * ⭐ **The order is the file's**, as `./skin_entries.ts` states it: every
+ * skin in the file's order, and within a skin the entries slot by slot in the
+ * skeleton's slot order — the walk spine-core's `getAttachments()` makes and
+ * the model side reproduces by calling the emitter's own order.
+ *
+ * 🔸 **What a vertex's binding names is the bone's INDEX in the roster**,
+ * because two bodies print it (`A20`'s weight-0 clause and `A28`'s row
+ * shapes) and the index is what the file holds. The model document names a
+ * binding's bone by name; its supplier turns the name into the index the
+ * emitter writes (`boneIndexOf` in `src/emit_spine.ts`), called, and a weight
+ * into the float32 the runtime stores it as (`Math.fround`).
+ *
+ * 🔒 **`encoding` is the round trip's, and only the round trip's.** A clause
+ * whose subject is the Spine encoding — the flat vertex run's own coherence,
+ * a binding's index into the bone array — has no model-side subject: the
+ * document names bones and states the weighted form outright, and the run is
+ * written by the emitter (the card's point 2). Those clauses stay in
+ * `src/validate.ts`, which hands their findings to the body here, at the
+ * place in the walk the body used to print them, so the moved body and the
+ * kept clause print the lines the one body printed, in the same order. The
+ * model side supplies none, because it has no encoding to be wrong.
+ *
+ * Links nothing from the runtime: the shapes are plain values.
+ */
+
+/** One influence of a weighted vertex: the bone's index in the roster and the weight the runtime holds. */
+export interface MeshBinding {
+  readonly bone: number;
+  readonly weight: number;
+  /** The kept clause's finding about this binding's index (`A20`'s range rule), where it has one; never on the model side. */
+  readonly encoding?: string;
+}
+
+/** One mesh attachment of one skin, a linked mesh included (it loads as a mesh drawing its source's geometry). */
+export interface MeshEntry {
+  /** The attachment's own name: the entry's `name`, else its placeholder. */
+  readonly name: string;
+  readonly skin: string;
+  /** The slot it is filed under, and that slot's bone. */
+  readonly slot: string;
+  readonly slotBone: string;
+  readonly placeholder: string;
+  /** The file's link, when this entry takes its geometry from another mesh, or `null`. */
+  readonly link: { readonly source: string } | null;
+  /** The triangles it draws, as indices into its vertices — a link's are its source's. */
+  readonly triangles: readonly number[];
+  /** `worldVerticesLength`: two numbers per vertex. */
+  readonly worldVerticesLength: number;
+  /** Its `uvs`, as the runtime reads them (doubles). */
+  readonly regionUVs: readonly number[];
+  /** `hullLength`: two numbers per hull vertex. */
+  readonly hullLength: number;
+  /** Per vertex its influences, in order — or `null` for an unweighted mesh. */
+  readonly weights: ReadonlyArray<readonly MeshBinding[]> | null;
+  /** The kept clauses' findings about this mesh's vertex run (`A04`'s encoding rules), in order; never on the model side. */
+  readonly encoding: readonly string[];
+}
+
+/** What A04, A20, A21, A28 and A23 read of the meshes. */
+export interface MeshFacts {
+  /** The bone roster's names, by index. */
+  readonly bones: readonly string[];
+  /** Every mesh attachment of every skin, in the file's walk order. */
+  readonly meshes: readonly MeshEntry[];
+}

package/src/assertions/facts/region_joins.ts

@@ -0,0 +1,34 @@
+/**
+ * The join from an attachment to an atlas region, before anything loads it
+ * (issue #1025, step 4c of #380) — the census's F21 names plus the skin
+ * entries' region paths, as A08 reads them: every region name the atlas
+ * declares, and every lookup a skin entry will make.
+ *
+ * 🚨 **Both halves are read before the round trip, on purpose** (issue #589):
+ * A08 exists to name a miss the loader would refuse without naming the
+ * placeholder or the skin, so it cannot read what the loader produced. On the
+ * model side the same holds one step over — A08 runs behind the reader alone,
+ * not behind the region rule that stands in A00's place, so a miss is named by
+ * A08's sentence on both sides and the parse beside it refuses the same file.
+ *
+ * ⭐ **The order is the file's.** A08 prints one line per lookup that misses,
+ * in the order the skins, a skin's slot keys and a slot's placeholders stand in
+ * the file — the emitter's `editorSkinOrder` and `editorSlotKeyOrder`, called
+ * on the model side — and then one per padded region name, in the atlas's
+ * order.
+ *
+ * Links nothing from the runtime: `validate()` reads the region names off a
+ * `TextureAtlas` it builds for this alone and the lookups off the skeleton
+ * JSON; the model side reads both off the document (`../model/region_joins.ts`).
+ */
+import type { AttachmentRegionJoin } from '../region_lookups.ts';
+
+export type { AttachmentRegionJoin };
+
+/** What A08 reads. Each half is `null` when its file did not parse, and the body says which. */
+export interface RegionJoinFacts {
+  /** Every region the atlas declares, by its name as spelled (untrimmed), in the atlas's order. */
+  readonly regionNames: readonly string[] | null;
+  /** Every skin entry that resolves through a region, with the names it will look up, in the file's order. */
+  readonly joins: readonly AttachmentRegionJoin[] | null;
+}

package/src/assertions/facts/skin_entries.ts

@@ -0,0 +1,37 @@
+/**
+ * The skin entries, as the bodies that walk them read them (issue #1025, step
+ * 4c of #380) — the census's F03, F05 and F06: every skin's attachments, of
+ * which kind each is, and a region's name and size.
+ *
+ * ⭐ **The order is a fact, and it is the file's.** A body that prints one
+ * line per offending entry prints them in the order this list holds them, so a
+ * supplier that walked another order would print the same findings in another
+ * order — a different report about the same rig. The order is the one
+ * spine-core's loaded skins list their entries in: the skins in the file's
+ * order (`default` first, the rest in the editor's order the emitter writes —
+ * `editorSkinOrder` in `src/compile.ts`), and within a skin the entries slot by
+ * slot in the skeleton's slot order, each slot's in the order its table states
+ * them. The model side produces it by calling the emitter's own order, never
+ * by restating it (`../model/skin_entries.ts`); the selftest measures the two
+ * walks equal on every multi-skin build it makes.
+ *
+ * Links nothing from the runtime: a spine-core `RegionAttachment` satisfies
+ * the entry shape structurally, which is how `validate()` supplies it.
+ */
+
+/** One region attachment: the name it loaded under (its `name`, else its placeholder), the region path it resolves through (its `path`, else that name) and its size. */
+export interface RegionEntry {
+  readonly name: string;
+  readonly width: number;
+  readonly height: number;
+  /** Read by A19 (issue #1025, cut 4c-1), which exempts a base plate by the region it draws; the runtime types it as possibly unset, and reads it with the name as fallback. */
+  readonly path?: string;
+}
+
+/** What the skins hold, for A03, A11 and A19. */
+export interface SkinEntryFacts {
+  /** Every region attachment of every skin, in the file's walk order (the header's ⭐). */
+  readonly regionAttachments: readonly RegionEntry[];
+  /** How many clipping attachments the skins hold, every skin counted. */
+  readonly clippingCount: number;
+}

package/src/assertions/facts/skin_members.ts

@@ -0,0 +1,53 @@
+/**
+ * What a skin activates, and what asks to be activated (issue #1025, step 4c
+ * of #380) — the census's F01, F04 and F12 as A38 reads them: every bone with
+ * its parent and its `skinRequired` flag, every constraint in update order with
+ * its flag, and each skin's own `bones` and constraint lists.
+ *
+ * 🔑 **A constraint is an object, not a name.** A skin lists constraint
+ * OBJECTS, and two constraints of one name under two kinds are two objects a
+ * skin may list separately (issue #692) — so a skin's `constraints` hold the
+ * very entries `constraints` holds, and a body asks whether one is listed by
+ * identity. A bone's `parent` is the bone entry itself, so the ancestor chain is
+ * walked by reference too.
+ *
+ * ⭐ **The order is the file's.** A38 prints one line per offending member:
+ * skins in the file's order (the emitter's, `editorSkinOrder`), a skin's bones
+ * as it lists them and its constraints kind by kind in the order the file keys
+ * them (`ik`, `transform`, `path`, `physics`, `slider` — `RIG_SKIN_CONSTRAINT_KEYS`,
+ * the emitter's), then the bones in the skeleton's order and the constraints in
+ * update order.
+ *
+ * Links nothing from the runtime: spine-core's loaded `SkeletonData` satisfies
+ * the shape structurally, which is how `validate()` supplies it, and the model
+ * side builds it from the document (`../model/skin_members.ts`).
+ */
+
+/** One bone: its name, whether it is skin-required, and its parent entry. */
+export interface MemberBone {
+  readonly name: string;
+  readonly skinRequired: boolean;
+  readonly parent: MemberBone | null;
+}
+
+/** One constraint: its name and whether it is skin-required. */
+export interface MemberConstraint {
+  readonly name: string;
+  readonly skinRequired: boolean;
+}
+
+/** One skin: its name and the bones and constraint entries it lists. */
+export interface MemberSkin {
+  readonly name: string;
+  readonly bones: readonly MemberBone[];
+  readonly constraints: readonly MemberConstraint[];
+}
+
+/** What A38 reads. */
+export interface SkinMemberFacts {
+  readonly skins: readonly MemberSkin[];
+  /** Every bone, in the skeleton's order. */
+  readonly bones: readonly MemberBone[];
+  /** Every constraint, in update order. */
+  readonly constraints: readonly MemberConstraint[];
+}

package/src/assertions/facts/skin_meshes.ts

@@ -0,0 +1,49 @@
+/**
+ * The skins' mesh entries, as the budget and canvas rules read them (issue
+ * #1025, step 4c of #380) — the census's F03, F05 and F08 for A13, A14, A15 and
+ * A22: every mesh a skin holds, linked meshes included, with where it sits
+ * (its slot and that slot's bone), how big it is (its size, its triangle list,
+ * its authored UVs and how many coordinates its vertices make) and which bones
+ * its weights name.
+ *
+ * ⭐ **A linked mesh is the geometry it draws.** The runtime loads a link as a
+ * mesh whose triangles, UVs, vertices, weights, width and height are its
+ * source's (`setSourceMesh` overwrites the link's own `width` and `height`),
+ * so an entry for a link carries its source's — the model side reads them
+ * through the core's own join, `sourceOfDoc`, never a copy of the rule.
+ *
+ * ⭐ **The order is the file's**, as `./skin_entries.ts` states it: skins in
+ * the emitter's order, a skin's entries slot by slot in the skeleton's slot
+ * order, each slot's in its table's order. A13 and A22 print one line per
+ * offending mesh in this order.
+ *
+ * Links nothing from the runtime: `validate()` reads each entry off
+ * spine-core's loaded `MeshAttachment`, and the model side off the document
+ * (`../model/skin_meshes.ts`).
+ */
+
+/** One mesh entry of one skin. */
+export interface MeshEntry {
+  /** The name it loaded under: its `name`, else its placeholder. */
+  readonly name: string;
+  /** The slot whose table holds it. */
+  readonly slot: string;
+  /** That slot's bone. */
+  readonly slotBone: string;
+  /** Its triangle list, three vertex indices per triangle. */
+  readonly triangles: readonly number[];
+  readonly width: number;
+  readonly height: number;
+  /** The UVs the file authored, two per vertex — the runtime's `regionUVs`, not the page-space `uvs` a renderer computes. */
+  readonly regionUVs: ArrayLike<number>;
+  /** Two per vertex, whatever the vertex encoding — the count the runtime recomputes. */
+  readonly worldVerticesLength: number;
+  /** Every bone its weights name, in the weight run's order (repeats kept); empty for an unweighted mesh. */
+  readonly weightBones: readonly string[];
+}
+
+/** What A13, A14, A15 and A22 read of the skins. */
+export interface SkinMeshFacts {
+  /** Every mesh entry of every skin, in the file's walk order. */
+  readonly meshes: readonly MeshEntry[];
+}

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/facts/stage.ts

@@ -0,0 +1,24 @@
+/**
+ * The stage the skeleton states (issue #1025, step 4c of #380) — the census's
+ * F11: the setup-pose box's width and height, which A14 measures a mesh against
+ * and A19 measures an attachment against.
+ *
+ * ⚠️ **`undefined` is a value here, and it is the runtime's.** A skeleton that
+ * declares no stage loads with `width` and `height` undefined (measured through
+ * spine-core 4.3.13: a header with neither key reads both as `undefined`, not
+ * 0), and the two rules read that absence differently on purpose — A14 skips,
+ * A19 names the base plate it cannot decide. So the fact carries the absence
+ * rather than a number standing in for it, and each body reads it as it always
+ * did.
+ *
+ * Not in the model document: the stage is the emitter's header
+ * (`SkeletonHeader.stage`), and it enters the document with issue #1026. Until
+ * then the model side is given it by its caller (`../model/stage.ts`).
+ * Links nothing from the runtime.
+ */
+
+/** The stage's two extents, each `undefined` where the skeleton states none. */
+export interface StageFacts {
+  readonly width: number | undefined;
+  readonly height: number | undefined;
+}

package/src/assertions/facts/vertex_polygons.ts

@@ -0,0 +1,53 @@
+/**
+ * The polygons — bounding boxes, clipping attachments and paths — and the
+ * slot a clip ends at, as `A33` reads them (issue #1025, step 4c of #380):
+ * the census's F07 and F09.
+ *
+ * ⭐ **Two orders, each the one its walk always had.** The polygons are in
+ * the loaded skins' order (`./skin_entries.ts`'s ⭐), which is the order A33
+ * walked spine-core's `getAttachments()`. The clip ends are in the order the
+ * FILE spells them — the skins in the file's order, each skin's slot keys as
+ * the file keys them, each slot's entries in table order — because A33 read
+ * them off the skeleton JSON: a `null` end and an `end` never written are the
+ * same loaded object. The model side produces both by calling the emitter's
+ * own orders (`editorSkinOrder`, `editorSlotKeyOrder`).
+ *
+ * 🔒 **`encoding` is the round trip's**, as in `./mesh_attachments.ts`: the
+ * weighted run's decode — a vertex claiming no bone, a binding indexing past
+ * the roster, a run decoding to another vertex count, a weight array of the
+ * wrong length — and an unweighted array of the wrong length have no subject
+ * in a document that states the weighted form outright and names bones.
+ * `src/validate.ts` keeps those clauses and hands their findings here, in the
+ * order the body printed them; the model side supplies none.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** One polygon: how A33 names it, the vertex count it loaded, and a path's own fields. */
+export interface PolygonEntry {
+  /** `bounding box "x"`, `clipping attachment "x"` or `path "x"` — the attachment's own name. */
+  readonly what: string;
+  /** `worldVerticesLength`: two numbers per vertex. */
+  readonly worldVerticesLength: number;
+  /** A path's `closed` and cumulative curve `lengths`, as the runtime holds them; `null` for the other two kinds. */
+  readonly path: { readonly closed: boolean; readonly lengths: readonly number[] } | null;
+  /** The kept clauses' findings about this polygon's vertex run, in order; never on the model side. */
+  readonly encoding: readonly string[];
+}
+
+/** One clipping attachment that states an `end`, as the file states it. */
+export interface ClipEnd {
+  readonly placeholder: string;
+  readonly slot: string;
+  readonly end: unknown;
+}
+
+/** What A33 reads. */
+export interface PolygonFacts {
+  /** Every bounding box, clipping attachment and path of every skin, in the loaded walk's order. */
+  readonly polygons: readonly PolygonEntry[];
+  /** Every clipping attachment that states an `end`, in the file's order. */
+  readonly clipEnds: readonly ClipEnd[];
+  /** The skeleton's slot names. */
+  readonly slots: readonly string[];
+}

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