rig-c 0.0.0-stage → 2.20.4

package/src/assertions/emitted/index.ts

@@ -0,0 +1,148 @@
+/**
+ * The round trip's rules, restated over the text rigc emitted (issue #1060,
+ * step 4e of #380) — the half of the gate the entry that links none of
+ * spine-core runs beside the model side (`../model/index.ts`).
+ *
+ * ⭐ **Every one of the 50 is accounted for, by name.** The model side runs
+ * the moved assertions (`MOVED_ASSERTIONS`) over the document. What is left —
+ * the complement, read off `ASSERTION_KIND` rather than listed — is the
+ * round trip's own: A00, A01, A02, A05, A07, A16, A18, A31, A35 at the time of
+ * writing. Each of those but one reads the raw text, not what spine-core
+ * loaded: the atlas's line layout (A07), the skeleton JSON's draw-order
+ * offsets, deform runs, version label, legacy arrays, legacy bone key and
+ * curve arrays (A31, A35, A16, A01, A02, A05), and A18's second compile. So
+ * each is restated here over the same text, by a body under `../bodies/` that
+ * is the round trip's clause word for word, and prints the round trip's line
+ * (`RC28` holds the two on every recipe and on each assertion's mutants).
+ * The one that cannot be is **A00**: it is spine-core's parser loading the
+ * pair, and there is no second reader of the format to stand in for it. It
+ * SKIPs, naming spine-core and where the round trip does run — never a PASS
+ * on nothing. A code the complement grows by that this file does not know is
+ * an internal error, so a new round-trip rule cannot go unrun here in silence.
+ *
+ * Links nothing from the runtime.
+ */
+import { ASSERTION_KIND, type AssertionProfile } from '../kinds.ts';
+import { verdictHarness, type VerdictLists } from '../harness.ts';
+import { MOVED_ASSERTIONS } from '../model/index.ts';
+import type { Verdicts } from '../harness.ts';
+import { isObj, type Json } from '../values.ts';
+import { a01NoLegacyToplevelConstraintArrays } from '../bodies/a01.ts';
+import { a02NoBoneTransformKey } from '../bodies/a02.ts';
+import { a05CurveArrayLength } from '../bodies/a05.ts';
+import { a07AtlasTextShape } from '../bodies/a07.ts';
+import { a16SkeletonVersion43 } from '../bodies/a16.ts';
+import { a18DeterministicEmit } from '../bodies/a18.ts';
+import { a31DrawOrderOffsetsResolve } from '../bodies/a31.ts';
+import { a35DeformKeysFitTheAttachment } from '../bodies/a35.ts';
+import { parseAtlasText } from '../../atlas.ts';
+
+/** What the restated rules read: the emitted texts, the document written beside them, and a second compile's three. */
+export interface EmittedTextInput {
+  skeletonText: string;
+  atlasText: string;
+  /** The document `build` writes — A18 compares it with the second compile's. */
+  modelText: string;
+  /** A second, independent compile's texts; absent, A18 SKIPs as the round trip's does on a re-gate. */
+  reEmit?: { skeletonText: string; atlasText: string; modelText: string };
+  profile: AssertionProfile;
+}
+
+/** The emitted texts as the bodies read them: the skeleton JSON parsed, or `null` where it does not parse. */
+interface EmittedTexts {
+  raw: Json | null;
+  input: EmittedTextInput;
+}
+
+/** A00's SKIP here: what did not run, and where it does. */
+export const SKIP_NO_ROUND_TRIP =
+  "spine-core's parser is the subject of this rule and this entry links none of it — the entry that links it runs the round trip on build and validate " +
+  '(installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts`), ' +
+  'and the selftest and CI run it on every corpus build';
+
+/** The code this file SKIPs rather than restates. */
+const A00 = 'A00_ROUNDTRIP_PARSE';
+
+/**
+ * The restated rules, in `validate()`'s report order — A00's place among them
+ * (after A35, before A16) is the round trip's, so the report reads in the order
+ * the round trip's does.
+ */
+export const EMITTED_TEXT_RULES: ReadonlyArray<{ code: string; run: (v: Verdicts, texts: EmittedTexts) => void }> = [
+  { code: 'A07_ATLAS_TEXT_SHAPE', run: (v, t) => a07AtlasTextShape(v, t.input.atlasText) },
+  { code: 'A31_DRAW_ORDER_OFFSETS_RESOLVE', run: (v, t) => a31DrawOrderOffsetsResolve(v, t.raw) },
+  { code: 'A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', run: (v, t) => a35DeformKeysFitTheAttachment(v, t.raw) },
+  { code: A00, run: (v) => v.skip(A00, SKIP_NO_ROUND_TRIP) },
+  { code: 'A16_SKELETON_VERSION_4_3', run: (v, t) => a16SkeletonVersion43(v, t.raw) },
+  { code: 'A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS', run: (v, t) => a01NoLegacyToplevelConstraintArrays(v, t.raw) },
+  { code: 'A02_NO_BONE_TRANSFORM_KEY', run: (v, t) => a02NoBoneTransformKey(v, t.raw) },
+  { code: 'A05_CURVE_ARRAY_LENGTH', run: (v, t) => a05CurveArrayLength(v, t.raw) },
+  {
+    code: 'A18_DETERMINISTIC_EMIT',
+    run: (v, { input }) => {
+      const again = input.reEmit;
+      const encoding =
+        again === undefined
+          ? []
+          : [
+              ...(again.skeletonText !== input.skeletonText ? ['recompiling produced a different skeleton.json'] : []),
+              ...(again.atlasText !== input.atlasText ? ['recompiling produced a different skeleton.atlas'] : []),
+            ];
+      a18DeterministicEmit(v, { again: again !== undefined, encoding, first: input.modelText, second: again?.modelText ?? '' });
+    },
+  },
+];
+
+/**
+ * The figures `validate()` reads off the pair it loaded, read off the same two
+ * texts here (issue #1114), into `stats` first — the order the round trip's
+ * report holds them in: `pages` and `regions` from the atlas text by rigc's own
+ * reader (`parseAtlasText`, whose pages and regions are the runtime atlas's in
+ * file order), then `bones`, `slots`, `animations` and `version` from the
+ * skeleton JSON — the arrays and the animation map the runtime loads them
+ * from, and `skeleton.spine` as it states it, `(none)` where it states none.
+ * The skeleton's four are left out where its JSON does not parse, as the round
+ * trip leaves them out where it loaded nothing; nothing here is a value the
+ * texts do not state.
+ */
+function pairFigures(stats: Record<string, number | string>, raw: Json | null, atlasText: string): void {
+  const atlas = parseAtlasText(atlasText);
+  stats.pages = atlas.pages.length;
+  stats.regions = atlas.regions.length;
+  if (!isObj(raw)) return;
+  const listed = (v: unknown): number => (Array.isArray(v) ? v.length : 0);
+  stats.bones = listed(raw.bones);
+  stats.slots = listed(raw.slots);
+  stats.animations = isObj(raw.animations) ? Object.keys(raw.animations).length : 0;
+  const declared = isObj(raw.skeleton) ? raw.skeleton.spine : undefined;
+  stats.version = declared === undefined || declared === null ? '(none)' : typeof declared === 'string' ? declared : JSON.stringify(declared);
+}
+
+/** Every code the model side does not run, read off the registry — what this file must account for. */
+export function roundTripOnlyCodes(): string[] {
+  const moved = new Set(MOVED_ASSERTIONS.map((m) => m.code));
+  return Object.keys(ASSERTION_KIND).filter((code) => !moved.has(code));
+}
+
+/** The restated rules over one build's emitted texts, in `validate()`'s report shape. */
+export function validateEmittedText(input: EmittedTextInput): VerdictLists & { profile: AssertionProfile } {
+  const known = new Set(EMITTED_TEXT_RULES.map((r) => r.code));
+  const unrun = roundTripOnlyCodes().filter((code) => !known.has(code));
+  if (unrun.length > 0) {
+    throw new Error(`internal: ${unrun.join(', ')} runs on neither side here — the model side does not run it and src/assertions/emitted/index.ts neither restates nor SKIPs it`);
+  }
+  const h = verdictHarness(input.profile, ASSERTION_KIND, 'the emitted text');
+  let raw: Json | null = null;
+  try {
+    raw = JSON.parse(input.skeletonText) as Json;
+  } catch (err) {
+    h.fail(A00, `skeleton JSON is not parseable: ${(err as Error).message}`);
+  }
+  pairFigures(h.stats, raw, input.atlasText);
+  for (const rule of EMITTED_TEXT_RULES) {
+    if (rule.code === A00 && raw === null) continue;
+    h.check(rule.code, () => rule.run(h.verdicts, { raw, input }));
+  }
+  const { failures, passed, skipped, profileSkipped, stats } = h;
+  return { failures, passed, skipped, profileSkipped, stats, profile: input.profile };
+}

package/src/assertions/facts/animated_bones.ts

@@ -0,0 +1,30 @@
+/**
+ * Which bones an animation keys (issue #1025, step 4c of #380) — the roster
+ * half of the census's F18 that A15 reads: whether the skeleton holds an
+ * animation of a name, whether it keys any bone, and which bones, in the
+ * order the file keys them.
+ *
+ * ⭐ **Three states, because A15 says three different things.** No such
+ * animation, an animation that keys no bone, and the bones it keys are each a
+ * sentence of their own in A15 — one is a missing subject, the next a subject
+ * with nothing in it, the last the subject — so the fact keeps them apart
+ * rather than folding the first two into an empty list.
+ *
+ * The order is the file's: A15 prints one line per keyed bone in it. The file
+ * keys an animation's bones in an object filled in the order the emitter
+ * writes the model's (`emitAnimation`), which is the document's own list — so
+ * an array-index bone name (`5`, `10`) is listed first whatever its place in
+ * that list (issue #1039), and the model side reads it through `keyedOrder`.
+ *
+ * Links nothing from the runtime: `validate()` reads it off the skeleton JSON
+ * as A15 always did, and the model side off the document
+ * (`../model/animated_bones.ts`).
+ */
+export interface AnimatedBoneFacts {
+  /**
+   * The bones `animation` keys, in the file's order — `undefined` when the
+   * skeleton holds no animation of that name, `null` when it holds one that
+   * carries no bone timeline at all.
+   */
+  bonesKeyedBy(animation: string): readonly string[] | null | undefined;
+}

package/src/assertions/facts/animation_durations.ts

@@ -0,0 +1,37 @@
+/**
+ * The animations and how long each one runs (issue #1025, cut 4c-3 of step
+ * 4c of #380) — the census's F18 and F19 as A09 reads them: the animation
+ * roster in the file's order, each animation's duration as the runtime holds
+ * it, and each of its timelines' own duration.
+ *
+ * ⭐ **The runtime's durations, not the stated ones.** An animation's duration
+ * is the last key of every timeline it carries, as float32 — the number
+ * `SkeletonJson` computes and stores, which is what A09 holds against the
+ * declared duration — and a timeline's own duration is its last key, as
+ * float32 (`Timeline.getDuration`). A09 counts the timelines keyed past the
+ * declared duration in its message, so the list holds one entry per timeline
+ * the runtime builds, in no order a body may read: A09 counts them and
+ * nothing else.
+ *
+ * The order of the roster is the file's: A09's last clause prints one line per
+ * animation the spec does not declare, in it.
+ *
+ * Links nothing from the runtime: `validate()` reads it off the loaded
+ * skeleton (`spineAnimationDurations`), the model side off the document and
+ * the core (`../model/animation_durations.ts`).
+ */
+
+/** One animation, as A09 reads it. */
+export interface AnimationDuration {
+  readonly name: string;
+  /** The runtime's duration: the last key of every timeline, float32. */
+  readonly duration: number;
+  /** Each timeline's own duration — its last key, float32 — one per timeline the runtime builds. */
+  readonly timelineDurations: readonly number[];
+}
+
+/** What A09 reads. */
+export interface AnimationDurationFacts {
+  /** Every animation the skeleton holds, in the file's order. */
+  readonly animations: readonly AnimationDuration[];
+}

package/src/assertions/facts/atlas_pages.ts

@@ -0,0 +1,19 @@
+/**
+ * The atlas's pages, as the bodies that read them see them (issue #1025, step
+ * 4c of #380) — the census's F20, without `pma`, which the model document does
+ * not hold and a later cut supplies from the caller.
+ *
+ * Links nothing from the runtime: a spine-core `TextureAtlas` satisfies the
+ * shape structurally, which is how `validate()` supplies it, and the model
+ * side supplies the document's `pages` section (`../model/atlas_pages.ts`).
+ */
+
+/** One page: its name, a path relative to the directory the atlas sits in. */
+export interface AtlasPage {
+  readonly name: string;
+}
+
+/** The atlas, or `null` when there is none to read — the round trip refused it, or the model side read no document. */
+export interface AtlasPageFacts {
+  readonly atlas: { readonly pages: readonly AtlasPage[] } | null;
+}

package/src/assertions/facts/atlas_regions.ts

@@ -0,0 +1,52 @@
+/**
+ * The atlas as the page rules read it (issue #1025, step 4c of #380) — the
+ * census's F20 and F21 whole: every page's name, declared size and `pma`, every
+ * region's rectangle and the page it sits on, and the region a name resolves
+ * to. A06, A19 and A27 read it; A17, which reads only the page names, keeps the
+ * narrower `./atlas_pages.ts`.
+ *
+ * ⭐ **The order is a fact, and it is the file's.** A06 and A27 print one line
+ * per offending page or region, and A06's overlap clause prints a pair in the
+ * order it meets them, so `pages` and `regions` hold the atlas's own order —
+ * pages as the file lists them, regions page by page in the file's order — and
+ * `findRegion` answers with the FIRST region of exactly that name, the one the
+ * runtime's lookup returns.
+ *
+ * Links nothing from the runtime: spine-core's `TextureAtlas` satisfies the
+ * shape structurally, which is how `validate()` supplies it. The model side
+ * supplies the document's `pages` section, with each page's `pma` given by its
+ * caller until the document states it (issue #1026) — `../model/atlas_regions.ts`.
+ */
+
+/** One page: its name (a path relative to the directory the atlas sits in), the size it declares, and whether it claims premultiplied alpha. */
+export interface AtlasRegionPage {
+  readonly name: string;
+  readonly width: number;
+  readonly height: number;
+  readonly pma: boolean;
+}
+
+/** One region: its name exactly as the atlas spells it, the rectangle in the page's texels, and the page it sits on. */
+export interface AtlasRegionEntry {
+  readonly name: string;
+  readonly page: AtlasRegionPage;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly degrees: number;
+  readonly offsetX: number;
+  readonly offsetY: number;
+  readonly originalWidth: number;
+  readonly originalHeight: number;
+}
+
+/** The atlas, or `null` when there is none to read — the round trip refused it, or the model side read no document. */
+export interface AtlasRegionFacts {
+  readonly atlas: {
+    readonly pages: readonly AtlasRegionPage[];
+    readonly regions: readonly AtlasRegionEntry[];
+    /** The first region of exactly this name, pages in order — or `null`. */
+    findRegion(name: string): AtlasRegionEntry | null;
+  } | null;
+}

package/src/assertions/facts/bone_timelines.ts

@@ -0,0 +1,37 @@
+/**
+ * Every animation's bone timelines, in the file's order and spelling (issue
+ * #1025, cut 4c-4 of #380) — the half of the census's F18/F19 that the stroke
+ * rules read: which bones each animation keys, with which timelines, and each
+ * key as the file states it.
+ *
+ * ⭐ **The file's order, and the file's spelling**, for the reason A45's slot
+ * timelines carry both (`./slot_colour.ts`): A24 and A30 print one line per
+ * bone and per timeline in the order the file keys them, and A24, A29 and A30
+ * print a key's `x`, `y` and `time` as the file states them. So the list holds,
+ * for every animation in the order the file keys them and every bone in the
+ * order the animation keys them, that bone's timelines — name to keys — as
+ * the file spells them. `validate()` reads it off the skeleton JSON
+ * (`rawBoneTimelines`); the model side produces it from the document by calling
+ * the emitter's own order and its parser-default and key-order passes
+ * (`../model/bone_timelines.ts`), so a key field the emitter would leave out at
+ * the parser's default is left out here too.
+ *
+ * ⚠️ `timelines` is `unknown` rather than an object because the raw JSON can
+ * hold anything there and A24 counts a keyed bone before it asks what the
+ * bone's timelines are; the document always holds an object.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** One animation's timelines on one bone: timeline name -> keys, as the file states them. */
+export interface BoneTimelines {
+  readonly animation: string;
+  readonly bone: string;
+  readonly timelines: unknown;
+}
+
+/** What A24, A29 and A30 read. */
+export interface BoneTimelineFacts {
+  /** Every (animation, bone) pair the file keys, in the header's order. */
+  readonly boneTimelines: readonly BoneTimelines[];
+}

package/src/assertions/facts/constraint_targets.ts

@@ -0,0 +1,56 @@
+/**
+ * The constraint timelines of every animation, as A34 walks them (issue
+ * #1025, cut 4c-5 of step 4c of #380): the constraints the skeleton declares,
+ * and each animation's `ik`, `transform`, `path`, `physics` and `slider`
+ * groups as the Spine file states them — the constraint each entry names and
+ * the key arrays under it.
+ *
+ * ⭐ **The order is the file's.** The animations in the order the file keys
+ * them, in each the five groups in that fixed order, each group's entries in
+ * the order the file keys them, each entry's timelines likewise: A34 prints
+ * one line per finding, so the walk is a fact both suppliers state.
+ *
+ * 🔸 **Which constraints a physics timeline naming none reaches is a
+ * question, not a value** — the runtime answers it by building the timeline
+ * its parser builds for the name and asking each constraint's data whether it
+ * takes the key (`unnamedPhysicsReach`), the model side by the core's own
+ * reading (`posedPhysics`, through `unnamedReach`). A body asks for it
+ * (`reach`), and the selftest puts every question to both (`VF14`).
+ *
+ * Links nothing from the runtime.
+ */
+
+/** One key array under an entry: the timeline's name (`''` for the `ik`/`transform` shape) and what it holds — how many keys, or the spelling of a value that is not a list. */
+export interface TargetKeyArray {
+  readonly timeline: string;
+  readonly keys: { readonly count: number } | { readonly spelled: string };
+}
+
+/** One entry of a group: the constraint name the file keys it by, and either the spelling of a value that is not an object where named timelines go (`bare`) or its key arrays. */
+export interface TargetEntry {
+  readonly name: string;
+  readonly bare: string | null;
+  readonly keyArrays: readonly TargetKeyArray[];
+}
+
+/** One animation: its name and the groups it states, in the walk's order. */
+export interface TargetAnimation {
+  readonly name: string;
+  readonly groups: ReadonlyArray<{ readonly group: 'ik' | 'transform' | 'path' | 'physics' | 'slider'; readonly entries: readonly TargetEntry[] }>;
+}
+
+/** What a physics timeline naming no constraint reaches: whether it is a `reset`, and the constraints that take its key. */
+export interface UnnamedReach {
+  readonly resets: boolean;
+  readonly reached: readonly string[];
+}
+
+/** What A34 reads. */
+export interface ConstraintTargetFacts {
+  /** Every entry of the skeleton's `constraints` array that is an object: its name (null when it states none as a string), its type as spelled, and its name as the sentence spells it. */
+  readonly constraints: ReadonlyArray<{ readonly name: string | null; readonly type: string; readonly spelled: string }>;
+  /** Every animation, or `null` when the skeleton declares none (its `animations` is not an object). */
+  readonly groupsByAnimation: readonly TargetAnimation[] | null;
+  /** What a physics timeline named `timeline` that names no constraint reaches — or `null` for a name the parser builds no timeline for. */
+  reach(timeline: string): UnnamedReach | null;
+}

package/src/assertions/facts/constraints.ts

@@ -0,0 +1,155 @@
+/**
+ * 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,
+ * 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;
+    /**
+     * The bone's `length`, as the runtime holds it after its parse (0 where the
+     * file leaves it out) — the lever a `rotate`, `shearX` or `scaleX` drive is
+     * stepped with (issue #1195): the tip `length·(a, c)` the rotation chases,
+     * and the radius the along-bone motion is divided by for `scaleX`.
+     */
+    readonly boneLength: number;
+    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;
+    /**
+     * For an ik over exactly two bones, the second bone's ancestors, its
+     * parent first and the root last; empty for any other count (issue
+     * #1205). The two-bone solve places the second bone through the first's
+     * matrix from the second's own local offset, so it is the solve of the
+     * chain drawn only when the first entry here is the first bone.
+     */
+    readonly secondAncestors: readonly string[];
+  };
+  /**
+   * 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, 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/deform_survey.ts

@@ -0,0 +1,27 @@
+/**
+ * The deform survey (issue #1025, cut 4c-3 of step 4c of #380) — the
+ * census's R6 and the structure under it, as A39 reads them: every deform key
+ * of every animation measured in the frame its animation is reached in, every
+ * span between two keys scanned, and what was passed over.
+ *
+ * ⭐ **One fact, because it is one measurement.** The survey is what
+ * `explain`'s `DEFORM` block prints whole and A39 gates on, and the reason
+ * both read one survey rather than each posing for itself is that the
+ * report's reversal count and A39's are the same count
+ * (`src/deformmeasure.ts`'s header). So A39 is handed the survey, not the
+ * poses under it: `validate()` hands it spine-core's — the Spine skeleton read
+ * and posed by the runtime (`surveyDeformKeys`) — and the model side the core's
+ * — the model document's structure posed by rigc's core (`surveyOfModel`,
+ * `src/deformsurvey.ts`). `tools/survey_hashes.ts` holds the two to one survey
+ * on every corpus row, and the selftest on every call with a model in hand
+ * (`VF12`).
+ *
+ * Links nothing from the runtime.
+ */
+import type { DeformSurvey } from '../../deformsurvey.ts';
+
+/** What A39 reads. */
+export interface DeformSurveyFacts {
+  /** The survey, with the slots in `exempt` passed over unmeasured (the rig's `deformMayFold`). */
+  survey(exempt: ReadonlySet<string>): DeformSurvey;
+}

package/src/assertions/facts/event_keys.ts

@@ -0,0 +1,55 @@
+/**
+ * Every event key, in the file's order, with the declaration it fires (issue
+ * #1025, cut 4c-4 of #380) — what A32 reads.
+ *
+ * ⭐ **Split per clause, and the split is in this interface.** A32 has five
+ * clauses. Four of them — a key with no string `name`, a key firing an event
+ * the skeleton does not declare, a key whose time is not a finite number, and
+ * a key earlier than the one before it — are states `readModel` refuses by
+ * name (`readEventKeys` in `src/core/events.ts`, measured on forged documents:
+ * each one is refused at the key's address), so no readable document reaches
+ * them and they stay with the round trip: `validate()` runs them over the
+ * skeleton JSON and hands their findings in as `kept`, in the order they
+ * print, with `stopped` where the clause ended the key's reading. The fifth —
+ * `volume` or `balance` on a key whose event declares no audio — is the rig's:
+ * the document holds the key's fields and the declaration's `audio`, and a
+ * readable document can carry it. That clause is the body's
+ * (`../bodies/a32.ts`), and the model side supplies `kept` empty.
+ *
+ * The order is the file's: animations in the order the file keys them (the
+ * emitter's `editorAnimationOrder`), and an animation's keys in the order the
+ * document lists them, which is the order the emitter writes them
+ * (`emitAnimation`'s `events`). `timelines` counts the animations carrying an
+ * event timeline at all, which is what A32 SKIPs on when it is zero.
+ *
+ * Links nothing from the runtime.
+ */
+
+/** One event key: where it is, what the kept clauses found, and what the moved clause reads. */
+export interface EventKeyEntry {
+  readonly animation: string;
+  /** The key's index in its animation's event timeline. */
+  readonly index: number;
+  /** The findings of the clauses that stay with the round trip, in the order they print — always empty on the model side. */
+  readonly kept: readonly string[];
+  /** Whether a kept clause ended the key's reading, so the moved clause does not run on it. */
+  readonly stopped: boolean;
+  /** The event the key fires. */
+  readonly name: string;
+  /** Which of the two audio fields the key states. */
+  readonly sets: { readonly volume: boolean; readonly balance: boolean };
+  /** Whether the event the key fires declares an audio path (a string). */
+  readonly audio: boolean;
+}
+
+/** What A32 reads. */
+export interface EventKeyFacts {
+  /** Whether the skeleton JSON parsed — always true on the model side, whose parse is the reader's. */
+  readonly parsed: boolean;
+  /** Whether the skeleton declares an `animations` object at all. */
+  readonly animations: boolean;
+  /** How many animations carry an event timeline. */
+  readonly timelines: number;
+  /** Every event key, in the file's order. */
+  readonly keys: readonly EventKeyEntry[];
+}

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