rig-c 0.0.0-stage → 2.20.4

package/src/ingest.ts

@@ -0,0 +1,2293 @@
+/**
+ * ingest — Spine 4.3 skeleton JSON back into a rig spec and a motion spec.
+ *
+ * ## What this is, and what makes it checkable
+ *
+ * `build` turns two spec files into a skeleton. This turns a skeleton back into
+ * two spec files, so that the contract is an **equality against the file it was
+ * read from**: `build(ingest(A)) === A`, byte for byte on `skeleton.json`. Every
+ * other gate in this repository compares rigc to rigc — the compiler against the
+ * validator, one compile against a second (`A18`), the emitter against its own
+ * assertions. This one compares rigc's output against an input rigc did not
+ * write, which is the only reference of that kind the tree has.
+ *
+ * ⇒ So every function below is an **inversion of one named function in
+ * [`compile.ts`](compile.ts)**, and each says which. That citation is what makes
+ * the module reviewable: a reader checks the pair, not the prose.
+ *
+ * ## The rule it is held to
+ *
+ * 🔒 **A decompiler never invents a value the skeleton does not carry.** It is
+ * CLAUDE.md's *"the compiler never invents a value that is not in the spec"*,
+ * mirrored — and the mirror is where a decompiler's defects live, because a
+ * plausible guess here produces a spec that compiles, gates green and says
+ * something nobody wrote. Where the skeleton cannot answer, this records a
+ * **finding** with a code and writes nothing: `findings` is the product, not a
+ * log. Exactly two values are not in a skeleton at all (the stage and an
+ * animation's duration), and a value somebody supplies for either is a
+ * `judgement` finding — a stage the file does not declare is carried as the
+ * absence it is, and only a caller's `--stage` is somebody deciding (issue
+ * #714); every construct the spec format cannot hold is a `blocker`; everything
+ * rigc re-derives rather than carries is `lossy`. The one thing it refuses outright rather than recording is
+ * an OPTION that contradicts the file — see `IngestError`.
+ *
+ * ## What it does not read
+ *
+ * Skeleton JSON, and nothing else. Not the atlas, not a `.spine` project, not a
+ * binary `.skel`, not the art. A rig spec's texture side is therefore the
+ * caller's (`IngestOptions.art`) and is stated as such.
+ *
+ * ## Purity
+ *
+ * No clock, no randomness, no filesystem, no network, and no `spine-core` — the
+ * three files allowed to link the runtime are named in CLAUDE.md and this is not
+ * one of them (`CUR07` refuses a fourth). The provenance `note` therefore carries
+ * a version the caller passes in and **no timestamp**, because a timestamp would
+ * break `A18_DETERMINISTIC_EMIT` the first time anybody rebuilt from an ingested
+ * spec.
+ */
+import {
+  PHYSICS_COMPONENTS,
+  SLOT_TRACKS as EMITTED_SLOT_TRACKS,
+  SPINE_VERSION,
+} from './compile.ts';
+import { CompileError } from './errors.ts';
+import { physicsDrives } from './core/constraints_physics.ts';
+import { CHANNELS_BY_KIND } from './timelines.ts';
+import {
+  LEGACY_BONE_INHERIT_KEY,
+  PHYSICS_FIELDS_WHOSE_DEFAULT_MOVED,
+  SPINE_GENERATIONS,
+  spineGeneration,
+  TOPLEVEL_CONSTRAINT_ARRAYS,
+} from './generation.ts';
+import { EVERY_GLOBAL_PHYSICS, MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
+import { PARSER_DEFAULTS, parserOmits } from './keyorder.ts';
+import { constraintAt, parseRigSpec, resolveBoneInherit, RIG_KEYS, RIG_SPEC_VERSION, type RigSpec } from './rig.ts';
+import type { MotionSpec } from './types.ts';
+
+/**
+ * The invocation this module refuses outright, rather than recording.
+ *
+ * ⚠️ **A finding is about the FILE; this is about the call.** Everything below
+ * that a skeleton cannot answer is a `finding` and the specs are still written,
+ * because a spec plus a list of what is missing from it beats no spec. An
+ * `IngestError` is the other thing: an option that contradicts the file it was
+ * given, where writing anything at all would be writing something the caller did
+ * not ask for. It is one re-run away from everything, which is what makes
+ * refusing cheaper than recording here (issue #626).
+ */
+export class IngestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'IngestError';
+  }
+}
+
+/**
+ * The specs this module wrote, and the tree's own parser refusing one of them.
+ *
+ * 🚨 **A parser refusal mid-`ingest` used to be the run's last word** (issue
+ * #692). `parseRigSpec` throws a `CompileError`, it went straight out through
+ * `ingest()`, and the run exited 1 with **no `BLOCK` line, no code and no
+ * `findings.json` on disk** — so a census that counts finding codes read those
+ * files as refused for no stated reason. A shape the spec format cannot hold is
+ * exactly what a coded `blocker` is for, and the code rides in `findings` here
+ * with everything else the run found.
+ *
+ * It carries the two spec objects because they are what the parser was given:
+ * writing them is what lets the sentence be read against a file rather than
+ * against the console. They are the same objects a successful run returns —
+ * `parseRigSpec` hands its input back typed — so the bytes on disk do not depend
+ * on which way the parse went.
+ */
+export class IngestSpecRefused extends Error {
+  constructor(
+    message: string,
+    readonly findings: IngestFinding[],
+    readonly rig: JsonObject,
+    readonly motion: JsonObject,
+  ) {
+    super(message);
+    this.name = 'IngestSpecRefused';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// findings
+// ---------------------------------------------------------------------------
+
+/**
+ * What a finding is about, which is also what the caller's exit code turns on.
+ *
+ * - `blocker` — the spec format cannot say this, so the rebuilt skeleton will
+ *   NOT be the one that was read. Non-zero exit.
+ * - `judgement` — the skeleton does not carry it and somebody decided. There
+ *   are exactly two: a stage the caller supplied, and an animation's duration.
+ * - `lossy` — the skeleton's spelling and rigc's differ, on purpose, and the
+ *   difference is named: a value rigc re-derives rather than takes (the
+ *   `spine` version), a field the spec has no home for (`hash`), or
+ *   a default the source left to the format and the rebuild writes out
+ *   (`HEADER_ORIGIN`, issue #622). The rebuilt file is a different file in that
+ *   field; it is not a different rig.
+ */
+export type IngestFindingKind = 'blocker' | 'judgement' | 'lossy';
+
+/**
+ * The gutter each kind prints under — the token a reader meets before the code,
+ * and the column `docs/INGEST.md` §2.0's finding-code table is keyed on.
+ *
+ * ⭐ Exported for the reason `SLOT_TRACKS` below is read off `compile.ts`
+ * (issue #650): it was a local table inside `cmdIngest`, so the CLI that prints
+ * a gutter, the page that documents one and the gate that compares the two
+ * would have held three copies of the same three pairs. The CLI pads it to one
+ * width for the column; the width is a printing decision and stays there.
+ */
+export const INGEST_GUTTERS: Record<IngestFindingKind, string> = {
+  blocker: 'BLOCK',
+  judgement: 'JUDGE',
+  lossy: 'LOSS',
+};
+
+export interface IngestFinding {
+  /** Stable code, so a table can count them and a doc can name one. */
+  code: string;
+  /** The object this is about, named the way a validator failure names one. */
+  where: string;
+  /** One sentence: what was found, and what it means for the rebuild. */
+  detail: string;
+  kind: IngestFindingKind;
+}
+
+/** The stage a skeleton does not carry. See `NO_STAGE` below. */
+export interface IngestStage {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface IngestOptions {
+  /** The rig spec's `name`, which the motion spec's `archetype` must equal. */
+  name: string;
+  /**
+   * How the rebuilt spec gets at the art.
+   *
+   * `loose` names an `image` per attachment, so `build --images <dir>` measures
+   * the PNGs; `none` states `width`/`height` only, for a rebuild that resolves
+   * through `build --atlas-in <pack>`. The skeleton encodes neither, which is
+   * why this is a flag rather than a derivation.
+   */
+  art: 'loose' | 'none';
+  /**
+   * The rig spec's own `images` — the directory every `image` written below
+   * resolves against — ALREADY spelled relative to the directory the spec will
+   * be written into (issue #595).
+   *
+   * Absent leaves the field out, and an absent `images` resolves against the
+   * spec's own directory: a caller who extracted the parts anywhere else then
+   * carries `build --images <dir>` on every rebuild forever, and a spec that
+   * needs a flag to build is a spec whose `note` would have to say so.
+   *
+   * ⚠️ Spelled by the CALLER, not here. Turning a directory somebody typed into
+   * an absolute path reads a working directory, and this module reads nothing;
+   * `cli.ts` resolves it and spells it with `relativeImagesPath`, which is the
+   * same function `build` spells `skeleton.images` with, so the two cannot
+   * drift. Meaningless under `art: 'none'`, which writes no `image` at all —
+   * `cli.ts` refuses that pair rather than writing a field nothing reads.
+   */
+  images?: string;
+  /**
+   * Supplied stage, for a skeleton that declares none.
+   *
+   * ⛔ **Beside a skeleton that declares one this is an `IngestError`, not an
+   * override** (issue #626). It used to be read only after the early return in
+   * `ingestHeader`, so a caller who passed it alongside a declared box got the
+   * file's box, no finding and exit 0 — and the sharper case is the caller who
+   * meant to correct a wrong box and believed they had. The file is the record
+   * of what was measured; two sources for one value is a question, and rigc
+   * refuses it rather than answering it quietly.
+   */
+  stage?: IngestStage;
+  /**
+   * The stage a rigc build's model document states (issue #907): its `stage`,
+   * or `null` for a rig that declared none. Given, it is read IN PLACE OF the
+   * header's `x`, `y`, `width`, `height` — which on a rigc build since #907 are
+   * the setup-pose bounding box, not the stage — and everything below reads it
+   * as it would read a header stating it (`--stage` beside it is the same
+   * refusal). Absent, the header is read, as for an export: an export carries
+   * no other box. The caller reads it — `src/` reads no files —
+   * (`documentStageBeside` in `src/cli/shared.ts`: the `rigc-compiled/3`
+   * document beside the skeleton, only when its digest is that skeleton's).
+   */
+  documentStage?: IngestStage | null;
+  /**
+   * The slot whose bounding box carries the stage (issue #1168, `--stage-box
+   * <slot>`): a rig built with `skeleton.stageBox` carries its stage there,
+   * in the files a consumer ships, while the header carries the setup-pose
+   * bounding box. Named, that box is read as the stage — in place of the
+   * header's box, as `documentStage` is — and the rebuilt rig spec asks for
+   * the same box (`skeleton.stageBox`) instead of transcribing it as an
+   * attachment. Every shape `build` could not write back is refused by name
+   * (`readStageBox`). Absent, nothing is read from a slot: no box is the stage
+   * because of its name.
+   */
+  stageBox?: string;
+  /** The source file's basename, for the provenance note. No path: no leak. */
+  source: string;
+  /** rigc's own version, for the provenance note. Passed in — `src/` reads no files. */
+  version: string;
+}
+
+export interface IngestResult {
+  rig: RigSpec;
+  motion: MotionSpec;
+  findings: IngestFinding[];
+}
+
+// ---------------------------------------------------------------------------
+// JSON narrowing — the input is a file somebody else wrote
+// ---------------------------------------------------------------------------
+
+type JsonObject = Record<string, unknown>;
+
+function isObj(v: unknown): v is JsonObject {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The array at `v`, or an empty one. An absent collection is not a fault here. */
+function arr(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : [];
+}
+
+/** The object at `v`, or an empty one. */
+function obj(v: unknown): JsonObject {
+  return isObj(v) ? v : {};
+}
+
+/** `Object.entries` over the OBJECT-valued entries of `v`, in file order. */
+function objEntries(v: unknown): Array<[string, JsonObject]> {
+  return Object.entries(obj(v)).filter((entry): entry is [string, JsonObject] => isObj(entry[1]));
+}
+
+/** `Object.entries` over the ARRAY-valued entries of `v`, in file order. */
+function arrEntries(v: unknown): Array<[string, unknown[]]> {
+  return Object.entries(obj(v)).filter((entry): entry is [string, unknown[]] => Array.isArray(entry[1]));
+}
+
+/** The numbers at `v`, or undefined. A mixed array is not a number array. */
+function numbers(v: unknown): number[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  return v.every((n) => typeof n === 'number') ? (v as number[]) : undefined;
+}
+
+function nameOf(v: unknown): string {
+  return isObj(v) && typeof v.name === 'string' ? v.name : '';
+}
+
+// ---------------------------------------------------------------------------
+// field tables — DERIVED from the rig spec's own key sets, never retyped
+// ---------------------------------------------------------------------------
+//
+// ⭐ `RIG_KEYS` is already the statement of which fields a rig spec holds, and
+// `checkRigSpecKeys` refuses everything outside it. Reading the carry list off
+// that table rather than copying it means a field added to the spec becomes
+// carryable here with no edit, and — the half that matters — a skeleton field
+// that has no rig-spec home is refused BY NAME instead of being dropped in
+// silence. A second list would be two lists that have to agree, which is the
+// defect `RIG_KEYS`'s own comment is about.
+
+/** Everything `RIG_KEYS` names for a shape, minus the keys this file handles itself. */
+function carried(shape: keyof typeof RIG_KEYS, ...handled: string[]): string[] {
+  return (RIG_KEYS[shape] as readonly string[]).filter((key) => !handled.includes(key));
+}
+
+/**
+ * Bone fields carried verbatim. Inverts `buildBone` in `compile.ts`.
+ *
+ * `from` is excluded because it is rigc's own: a bone position taken from a
+ * manifest anchor, resolved to `x`/`y` at compile time (`cropPointOf`). A
+ * skeleton holds the resolved numbers and nothing else, so carrying them as
+ * `x`/`y` is the inversion and a `from` here would be an invention.
+ */
+const BONE_FIELDS = carried('RigBone', 'name', 'from');
+
+/** Slot fields carried verbatim. Inverts the slot loop in `compile()` step 4. */
+const SLOT_FIELDS = carried('RigSlot', 'name');
+
+/** Per constraint type, the fields carried verbatim. Inverts `buildRigConstraint`. */
+const CONSTRAINT_FIELDS: Record<string, string[]> = {
+  ik: carried('RigIkConstraint', 'name', 'type'),
+  transform: carried('RigTransformConstraint', 'name', 'type'),
+  path: carried('RigPathConstraint', 'name', 'type'),
+  physics: carried('RigPhysicsConstraint', 'name', 'type'),
+  slider: carried('RigSliderConstraint', 'name', 'type'),
+};
+
+/**
+ * The physics constraints that drive nothing, by name, each with the component
+ * fields it DOES state — every one of them at most 0 (issue #731).
+ *
+ * 🔑 The question is the core's `physicsDrives` (`src/core/constraints_physics.ts`,
+ * issue #1015): a component above 0 drives its part of the step and nothing
+ * else does, so a constraint with none of `PHYSICS_COMPONENTS` above 0 moves no
+ * bone — `PhysicsConstraint.update` applies a part only on that test
+ * (`PhysicsConstraint.js:112`). An unstated component is the parser's 0. `build`
+ * refuses exactly that shape by name — `A23_PHYSICS_CONSTRAINT_EFFECTIVE` at the
+ * gate — so carrying one through made the decompiled spec of a file an editor
+ * exports unbuildable as a whole, over a constraint that did nothing in it.
+ *
+ * ⚠️ A component that is present and NOT a number is not inert: the parser takes
+ * it as written and `"0.5" > 0` is true in the runtime's comparison, so such a
+ * constraint is carried and rigc's own parser says what is wrong with it.
+ */
+function inertPhysics(root: JsonObject): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const raw of arr(root.constraints)) {
+    const constraint = obj(raw);
+    if (constraint.type !== 'physics' || typeof constraint.name !== 'string') continue;
+    const stated = PHYSICS_COMPONENTS.filter((field) => constraint[field] !== undefined);
+    if (!stated.every((field) => typeof constraint[field] === 'number')) continue;
+    const value = (field: (typeof PHYSICS_COMPONENTS)[number]): number => (constraint[field] === undefined ? 0 : (constraint[field] as number));
+    const drives = physicsDrives({ x: value('x'), y: value('y'), rotate: value('rotate'), shearX: value('shearX'), scaleX: value('scaleX') });
+    if (drives.x || drives.y || drives.rotateOrShearX || drives.scaleX) continue;
+    out.set(
+      constraint.name,
+      stated.map((field) => `${field} ${String(constraint[field])}`),
+    );
+  }
+  return out;
+}
+
+/**
+ * The two kinds `A47` / `A48` ask the muted-at-rest question of. An alias rather
+ * than the union written at each use, because `IG25`'s scan resolves a composed
+ * finding code against the nearest `<name>: '…' | '…'` above it, and `type:` is
+ * the identifier `ATTACHMENT_<TYPE>` composes from further down.
+ */
+type MixedConstraintKind = 'ik' | 'transform';
+
+/**
+ * The ik and transform constraints this file rests muted and never switches on
+ * — the shape `A47` / `A48` refuse — with the mixes each one reads (issue #784).
+ *
+ * 🔑 **Read the way the gate reads it, from the raw JSON.** This module does not
+ * link the runtime, so the defaults are the parser's own, spelled here: an ik
+ * `mix` is 1 when absent, on the constraint and on every key; a transform mix
+ * is 1 when absent except `mixY`, which is the same object's `mixX`, and
+ * `mixScaleY`, which is its `mixScaleX` (`SkeletonJson.js`, every
+ * `getValue(…, 1)`). A transform reads only the mixes of the `to` properties it
+ * declares, and one that declares none is `A48`'s other sentence, which no
+ * declaration answers — so it is not a candidate. Live is `!== 0`, the
+ * runtime's test. A key lifts a mix when the value it states is live, or when
+ * its Bezier handles for that channel are — the curve the runtime interpolates
+ * through (`curveChannelValues` in `validate.ts`), which is how a 0 → 0 pair
+ * with raised handles moves the bones.
+ *
+ * ⚠️ A disagreement with the gate is loud either way, never silent: an entry on
+ * a constraint the gate reads as live is refused by name (declared but already
+ * switched on), and a muted one this misses is `A47` / `A48` refusing it.
+ */
+function consumerDrivenCandidates(root: JsonObject): Array<{ type: MixedConstraintKind; name: string; reads: string[] }> {
+  const TO_MIX: Record<string, string> = {
+    rotate: 'mixRotate',
+    x: 'mixX',
+    y: 'mixY',
+    scaleX: 'mixScaleX',
+    scaleY: 'mixScaleY',
+    shearY: 'mixShearY',
+  };
+  /** Frame order of a transform timeline's six curve channels. */
+  const TRANSFORM_ORDER = ['mixRotate', 'mixX', 'mixY', 'mixScaleX', 'mixScaleY', 'mixShearY'];
+  const num = (value: unknown, fallback: number): number => (typeof value === 'number' ? value : fallback);
+  const transformMixes = (m: JsonObject): Record<string, number> => {
+    const mixX = num(m.mixX, 1);
+    const mixScaleX = num(m.mixScaleX, 1);
+    return {
+      mixRotate: num(m.mixRotate, 1),
+      mixX,
+      mixY: num(m.mixY, mixX),
+      mixScaleX,
+      mixScaleY: num(m.mixScaleY, mixScaleX),
+      mixShearY: num(m.mixShearY, 1),
+    };
+  };
+  /** The Bezier handle values of channel `c` on a key's `curve`; none when it is linear or stepped. */
+  const handles = (key: JsonObject, c: number): number[] =>
+    Array.isArray(key.curve) ? [key.curve[4 * c + 1], key.curve[4 * c + 3]].filter((v): v is number => typeof v === 'number') : [];
+  const keysOf = (kind: MixedConstraintKind, name: string): JsonObject[] =>
+    Object.values(obj(root.animations)).flatMap((animation) => arr(obj(obj(animation)[kind])[name]).map(obj));
+  const out: Array<{ type: MixedConstraintKind; name: string; reads: string[] }> = [];
+  for (const raw of arr(root.constraints)) {
+    const constraint = obj(raw);
+    if (typeof constraint.name !== 'string') continue;
+    if (constraint.type === 'ik') {
+      if (num(constraint.mix, 1) !== 0) continue;
+      const lifted = keysOf('ik', constraint.name).some((key) => num(key.mix, 1) !== 0 || handles(key, 0).some((v) => v !== 0));
+      if (!lifted) out.push({ type: 'ik', name: constraint.name, reads: ['mix'] });
+    } else if (constraint.type === 'transform') {
+      const reads = [
+        ...new Set(
+          Object.values(obj(constraint.properties)).flatMap((from) => Object.keys(obj(obj(from).to)).map((to) => TO_MIX[to])),
+        ),
+      ]
+        .filter((mix): mix is string => mix !== undefined)
+        .sort((a, b) => TRANSFORM_ORDER.indexOf(a) - TRANSFORM_ORDER.indexOf(b));
+      if (reads.length === 0) continue;
+      const setup = transformMixes(constraint);
+      if (reads.some((mix) => setup[mix] !== 0)) continue;
+      const lifted = keysOf('transform', constraint.name).some((key) => {
+        const values = transformMixes(key);
+        return reads.some((mix) => values[mix] !== 0 || handles(key, TRANSFORM_ORDER.indexOf(mix)).some((v) => v !== 0));
+      });
+      if (!lifted) out.push({ type: 'transform', name: constraint.name, reads });
+    }
+  }
+  return out;
+}
+
+/** What omitting one inert physics constraint took with it, for its finding. */
+interface PhysicsOmission {
+  /** `animation "<a>" <timeline>`, in file order. */
+  timelines: string[];
+  /** The skins whose `physics` member list named it. */
+  skins: string[];
+  /** Per animation, the latest key time on an omitted timeline of this constraint. */
+  lastKeys: Map<string, number>;
+}
+
+/**
+ * The per-skin member lists (`SkeletonJson` reads them before `attachments`).
+ *
+ * `RIG_KEYS.RigSkinEntry` is `attachments` plus the five constraint lists plus
+ * `bones`; the long form of a skin is exactly those, so the list is that set
+ * minus the table itself.
+ */
+const SKIN_LISTS = carried('RigSkinEntry', 'attachments');
+
+/**
+ * One value-track channel: the JSON field, and what the PARSER reads where a key
+ * omits it.
+ *
+ * ⚠️ A number is a constant default; a STRING is another field of the same key,
+ * which is how `mixY` works (`SkeletonJson:988` — it defaults to that key's own
+ * `mixX`, not to 1). The same two-shaped table as `CONSTRAINT_TIMELINES`'s
+ * `inheritsFrom`, and for the same reason.
+ */
+type TrackShape = Array<[field: string, dflt: number | string]>;
+
+/**
+ * Bone timeline shapes. Inverts `BONE_TRACKS` + `compileValueTrack`.
+ *
+ * 🚨 The defaults matter more than they look, and they are not all the same:
+ * Spine omits a field that equals the SETUP value, `translate` reads 0 there and
+ * `scale` reads 1. A decompiler that filled every omission with 0 would collapse
+ * every scale key it read, silently.
+ */
+const BONE_TRACKS: Record<string, TrackShape> = {
+  translate: [['x', 0], ['y', 0]],
+  translatex: [['value', 0]],
+  translatey: [['value', 0]],
+  scale: [['x', 1], ['y', 1]],
+  scalex: [['value', 1]],
+  scaley: [['value', 1]],
+  shear: [['x', 0], ['y', 0]],
+  shearx: [['value', 0]],
+  sheary: [['value', 0]],
+  rotate: [['value', 0]],
+};
+
+/**
+ * The bone timeline whose key holds a NAME rather than numbers — `inherit`,
+ * `{ time, inherit }`, stepped by the format (its reader builds no curve). The
+ * field and the default `SkeletonJson`'s `inherit` branch reads where a key
+ * omits it: `getValue(aFrame, "inherit", "Normal")`, which the table spells
+ * `normal`. Inverts `compileValueTrack`'s named branch (issue #733).
+ */
+const INHERIT_TRACK = { property: 'inherit', field: 'inherit', dflt: 'normal' } as const;
+
+/** Every bone timeline the motion spec has a track for, in the order the refusal prints them. */
+const BONE_TRACK_NAMES = [...Object.keys(BONE_TRACKS), INHERIT_TRACK.property];
+
+/**
+ * The eight physics timelines — `PHYSICS_TRACKS` in `compile.ts`, same order.
+ * `reset` carries no value at all — `compileValueTrack`'s zero-field branch.
+ *
+ * 🚨 The defaults are the parser's per-key ones and they are **0 on six of the
+ * eight**, which is not where a reader looks for them: the constraint's own
+ * defaults (`inertia` 0.5, `strength` 100, `damping` 0.85, `mass` 1) sit in the
+ * same file at `:306-312` and belong to the constraint, not to a key. A
+ * decompiler that filled an omitted `damping` key with 0.85 would write a spec
+ * that plays a different animation from the one it read, and every gate would
+ * call it green. Copied off `SkeletonJson.js:1062` and `:1090`, not assumed.
+ */
+const PHYSICS_TRACKS: Record<string, TrackShape> = {
+  inertia: [['value', 0]],
+  strength: [['value', 0]],
+  damping: [['value', 0]],
+  mass: [['value', 0]],
+  wind: [['value', 0]],
+  gravity: [['value', 0]],
+  mix: [['value', 1]],
+  reset: [],
+};
+
+/** `mix` is three values in ONE key — `PATH_TRACKS` in `compile.ts`. */
+const PATH_TRACKS: Record<string, TrackShape> = {
+  position: [['value', 0]],
+  spacing: [['value', 0]],
+  mix: [['mixRotate', 1], ['mixX', 1], ['mixY', 'mixX']],
+};
+
+/** ⚠️ `time`'s per-key default is **1**, not 0 (`:1121`). Copied, not assumed. */
+const SLIDER_TRACKS: Record<string, TrackShape> = { time: [['value', 1]], mix: [['value', 1]] };
+
+/**
+ * The `ik` and `transform` key fields and the value the PARSER reads where a key
+ * omits one — `CONSTRAINT_TIMELINES` in `compile.ts`, channels then flags.
+ *
+ * ⚠️ `mixY` is the one field whose default is not a constant: it is the same
+ * key's own `mixX` (`SkeletonJson:988`), which is why it is spelled here as a
+ * field name rather than a number.
+ */
+const IK_KEY_DEFAULTS: Record<string, number | boolean> = {
+  mix: 1,
+  softness: 0,
+  bendPositive: true,
+  compress: false,
+  stretch: false,
+};
+const TRANSFORM_KEY_DEFAULTS: Record<string, number | boolean | string> = {
+  mixRotate: 1,
+  mixX: 1,
+  mixY: 'mixX',
+  mixScaleX: 1,
+  mixScaleY: 1,
+  mixShearY: 1,
+};
+/** The three ik booleans, which `compileConstraintTrack` stamps from the rig. */
+const IK_FLAGS = ['bendPositive', 'compress', 'stretch'];
+
+/**
+ * The animation groups the motion spec carries. Anything else is a blocker.
+ *
+ * ⚠️ This said *"the groups `readAnimation` reads"* until issue #675, and the
+ * `ANIMATION_GROUP` detail below said it to the reader. It is not the same set:
+ * `SkeletonJson.readAnimation` reads `drawOrderFolder` too and builds a
+ * `DrawOrderFolderTimeline` from it, so on that one name the sentence told an
+ * author the parser ignores something it plays. What is true either way is the
+ * half that decides the rebuild — the motion spec has no home for it — so that
+ * is what both the list and the finding now say.
+ */
+const ANIMATION_GROUPS = ['bones', 'slots', 'ik', 'transform', 'path', 'physics', 'slider', 'attachments', 'drawOrder', 'events'];
+
+/** The header fields rigc writes that no rig spec field holds. */
+const HEADER_REDERIVED = ['spine'];
+
+/** The attachment types this module inverts. Everything else is refused by name. */
+const ATTACHMENT_TYPES = ['region', 'mesh', 'linkedmesh', 'boundingbox', 'clipping', 'path'];
+
+/**
+ * The geometry keys a LINKED mesh may state and the parser never reads
+ * (issue #710).
+ *
+ * `readAttachment` returns from the `source` branch at `SkeletonJson.js:586`,
+ * before `map.uvs` is touched, so a link carrying any of these is a file that
+ * says one mesh while every runtime draws its source's. The rig spec cannot hold
+ * them either — `buildRigLinkedMesh` refuses geometry on a link by name — so a
+ * rebuild that carried one would be a spec `build` refuses, and a rebuild that
+ * dropped it in silence would be this module normalising somebody's file without
+ * saying so.
+ *
+ * ⚠️ A second list beside `src/validate.ts`'s, deliberately: that module links
+ * spine-core and this one must not, so importing it would pull the runtime into
+ * every `ingest`. What holds the two equal is a RUN rather than a shared
+ * constant — one forged skeleton through both, with the keys `A44` names and the
+ * keys this finding names compared as sets.
+ */
+const LINKED_MESH_UNREAD_KEYS = ['uvs', 'triangles', 'vertices', 'hull', 'edges'];
+
+/**
+ * The slot timelines the motion spec carries — `compileTrack`'s own table,
+ * rather than a second list of the same two names.
+ *
+ * ⚠️ It was that second list until issue #650, spelled `['rgba', 'attachment']`
+ * with a comment saying where it had been copied from. The copy was true, which
+ * is the point: the emitter had no list at all — one `if` and a fall-through —
+ * so this module's blocker was the only place in `src/` that said what a slot
+ * track may be, and it said it about a compiler that accepted anything. Now
+ * there is one list and both sides read it.
+ */
+const SLOT_TRACKS = Object.keys(EMITTED_SLOT_TRACKS);
+
+/**
+ * The slot timelines the FORMAT has and the motion spec has no track for —
+ * **none** since issue #730 spelled `rgb`, `alpha` and `rgb2`, which were the
+ * last three. It stays derived rather than deleted, because an empty
+ * difference of two tables is a measurement and a deleted one is a claim: the
+ * day the format grows a seventh slot timeline, this is where it appears, and
+ * the blocker's sentence names it without an edit.
+ *
+ * ⭐ Both sides are derived, and that is the whole reason it exists rather than
+ * being spelled into the blocker's sentence. `docs/INGEST.md`'s row for this
+ * code named `rgba2` among the timelines nobody carries for as long as that was
+ * true, and went on saying it after issue #690 made it false — a hand-kept list
+ * beside a derived one, which is the shape this repository refuses everywhere
+ * else. The format's own list is `CHANNELS_BY_KIND.slot`, the emitter's is
+ * `SLOT_TRACKS`, and the difference is the answer.
+ */
+export const UNSPELT_SLOT_TRACKS = Object.keys(CHANNELS_BY_KIND.slot).filter((name) => !(name in EMITTED_SLOT_TRACKS));
+
+/**
+ * Everything this module has a branch for, as the branches themselves state it.
+ *
+ * ⭐ It exists so that a gate can ask the question a suite cannot answer from a
+ * list somebody typed: **is every construct `ingest` claims to carry actually
+ * exercised by a rig somebody builds?** A decompiler branch no rig reaches is a
+ * branch nobody has seen work, which is this repository's own definition of not
+ * a gate — and the vocabulary has to come from here, because a second copy in
+ * `selftest.ts` would go stale in exactly the direction that hides the hole.
+ */
+export const INGEST_VOCABULARY = {
+  attachments: ATTACHMENT_TYPES,
+  constraints: Object.keys(CONSTRAINT_FIELDS),
+  boneTracks: BONE_TRACK_NAMES,
+  slotTracks: SLOT_TRACKS,
+  path: Object.keys(PATH_TRACKS),
+  physics: Object.keys(PHYSICS_TRACKS),
+  slider: Object.keys(SLIDER_TRACKS),
+  animationGroups: ANIMATION_GROUPS,
+} as const satisfies Record<string, readonly string[]>;
+
+// ---------------------------------------------------------------------------
+// the inversions
+// ---------------------------------------------------------------------------
+
+/**
+ * Spine's flat weight run back into one `{bone, x, y, weight}` list per vertex.
+ *
+ * 🔒 Inverts `encodeNamedWeights`, and the inversion is **by name** for exactly
+ * the reason that function encodes by name: the run holds positions in the
+ * EMITTED bone array, a list no spec writes, so a decompiled `vertices` run
+ * would rebind every vertex the moment a bone moved in the array (issue #45).
+ * The names are the join key on both sides.
+ */
+function decodeWeights(vertices: readonly number[], boneNames: readonly string[]): Array<Array<Record<string, unknown>>> {
+  const out: Array<Array<Record<string, unknown>>> = [];
+  let i = 0;
+  while (i < vertices.length) {
+    const count = vertices[i++];
+    const vertex: Array<Record<string, unknown>> = [];
+    for (let k = 0; k < count; k++) {
+      vertex.push({ bone: boneNames[vertices[i]], x: vertices[i + 1], y: vertices[i + 2], weight: vertices[i + 3] });
+      i += 4;
+    }
+    out.push(vertex);
+  }
+  return out;
+}
+
+/**
+ * `"rrggbbaa"` back to `[r, g, b, a]` in 0..1. Inverts `rgbaHex`.
+ *
+ * ⚠️ One byte per channel is all the file holds, so this is exact in the only
+ * direction that matters: the rebuild quantises the same floats to the same
+ * bytes. It is not a recovery of whatever the original author typed.
+ */
+function hexToRgba(hex: string): number[] {
+  return [0, 2, 4, 6].map((i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255);
+}
+
+/**
+ * The three-channel form, which is what a two-colour key's `dark` is written as
+ * — `rrggbb` and no alpha, because `RGBA2Timeline` stores three dark channels
+ * and the fourth a shader reads there is the premultiply flag rather than a
+ * colour (`compile.ts`'s `rgba2Hex` states the same fact from the emit side).
+ */
+function hexToRgb(hex: string): number[] {
+  return [0, 2, 4].map((i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255);
+}
+
+/**
+ * Read a skeleton, write the two specs that rebuild it.
+ *
+ * Pure: the same skeleton and the same options give the same specs, every time.
+ * The two returned specs have been through `parseRigSpec` and `parseMotionSpec`
+ * before they leave — a decompiler that hands back something the compiler's own
+ * parser would refuse has produced a file nobody can use, and saying so here
+ * names the decompiler instead of leaving `build` to name the file.
+ */
+export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
+  const findings: IngestFinding[] = [];
+  const note = (kind: IngestFindingKind, code: string, where: string, detail: string): void => {
+    findings.push({ code, where, detail, kind });
+  };
+
+  const root = obj(skeleton);
+  const boneNames: string[] = arr(root.bones).map(nameOf);
+
+  // -- the generation -------------------------------------------------------
+  // 🚨 First, because every walk below reads the file as 4.3 and a file from
+  // another generation is one this module cannot honestly claim to have read
+  // (issue #706 item 3). It records; it does not refuse — see `readGeneration`.
+  readGeneration(root, note);
+
+  // -- header ---------------------------------------------------------------
+  // 🚨 THE SEAM. One function decides the rig spec's `skeleton` block, and the
+  // stage is the only value in this whole module that a skeleton cannot answer
+  // for. Since #578 a rig spec can SAY that a skeleton declares no stage, and
+  // since #714 this is where a file that declares none is carried as saying so.
+  const stageBox = opts.stageBox === undefined ? null : readStageBox(root, opts.stageBox, note);
+  const rigHeader = ingestHeader(obj(root.skeleton), opts, note, stageBox);
+
+  // -- physics constraints that drive nothing (issue #731) ------------------
+  // Read before the skins, because a skin's `physics` member list is one of the
+  // three places such a constraint is named and each has to let go of it.
+  const inert = inertPhysics(root);
+  const omissions = new Map<string, PhysicsOmission>();
+  const omission = (name: string): PhysicsOmission => {
+    const found = omissions.get(name);
+    if (found !== undefined) return found;
+    const made: PhysicsOmission = { timelines: [], skins: [], lastKeys: new Map() };
+    omissions.set(name, made);
+    return made;
+  };
+
+  // -- bones ----------------------------------------------------------------
+  // Inverts `buildBone`, which copies every declared field and omits the rest.
+  const bones = arr(root.bones).map((raw) => {
+    const bone = obj(raw);
+    const out: JsonObject = { name: bone.name };
+    for (const field of BONE_FIELDS) if (bone[field] !== undefined) out[field] = bone[field];
+    for (const key of Object.keys(bone)) {
+      if (key === 'name' || BONE_FIELDS.includes(key)) continue;
+      note('blocker', 'BONE_FIELD', `bone "${nameOf(bone)}"`, `field "${key}" has no rig-spec field, so it is dropped`);
+    }
+    return out;
+  });
+
+  // -- slots ----------------------------------------------------------------
+  // A slot some skin fills but that shows nothing in the setup pose carries NO
+  // `attachment` field, and `build` refuses a filled slot with no setup pose
+  // ("the compiler will not guess one"). The skeleton does state it: an absent
+  // `attachment` on a filled slot means "show nothing", which the rig spec
+  // spells `null`. Transcribing an absence is not inventing a value.
+  const filled = new Set<string>();
+  for (const skin of arr(root.skins)) {
+    for (const [slot, placeholders] of objEntries(obj(skin).attachments)) {
+      if (Object.keys(placeholders).length) filled.add(slot);
+    }
+  }
+  const slots = arr(root.slots).map((raw) => {
+    const slot = obj(raw);
+    const out: JsonObject = { name: slot.name };
+    for (const field of SLOT_FIELDS) if (slot[field] !== undefined) out[field] = slot[field];
+    if (out.attachment === undefined && filled.has(nameOf(slot))) out.attachment = null;
+    for (const key of Object.keys(slot)) {
+      if (key === 'name' || SLOT_FIELDS.includes(key)) continue;
+      note('blocker', 'SLOT_FIELD', `slot "${nameOf(slot)}"`, `field "${key}" has no rig-spec field, so it is dropped`);
+    }
+    return out;
+  });
+
+  // -- skins and attachments ------------------------------------------------
+  const skins: JsonObject = {};
+  for (const skin of arr(root.skins)) {
+    const entry = obj(skin);
+    const table: JsonObject = {};
+    for (const [slot, placeholders] of objEntries(entry.attachments)) {
+      const perSlot: JsonObject = {};
+      for (const [placeholder, att] of Object.entries(placeholders)) {
+        // The stage box is the rebuilt spec's `skeleton.stageBox`, which `build` writes from the stage — not an attachment to transcribe (issue #1168).
+        if (stageBox !== null && nameOf(entry) === 'default' && slot === stageBox.slot && placeholder === stageBox.attachment) continue;
+        perSlot[placeholder] = ingestAttachment(obj(att), placeholder, boneNames, opts, note, {
+          where: `skin "${nameOf(entry)}" slot "${slot}" attachment "${placeholder}"`,
+        });
+      }
+      if (stageBox !== null && nameOf(entry) === 'default' && slot === stageBox.slot) continue;
+      table[slot] = perSlot;
+    }
+    const lists: JsonObject = {};
+    let anyList = false;
+    for (const list of SKIN_LISTS) {
+      if (entry[list] !== undefined) {
+        let members = entry[list];
+        if (list === 'physics' && Array.isArray(members)) {
+          const named = members.filter((member): member is string => typeof member === 'string' && inert.has(member));
+          for (const member of named) omission(member).skins.push(nameOf(entry));
+          members = members.filter((member) => !(typeof member === 'string' && inert.has(member)));
+          // A list that named nothing BUT omitted constraints goes with them: an
+          // empty list and an absent one read the same, and only one of them is
+          // what the rebuild writes for a skin with no physics member.
+          if (named.length > 0 && (members as unknown[]).length === 0) continue;
+        }
+        lists[list] = members;
+        anyList = true;
+      }
+    }
+    // The long form only where the skin activates something; otherwise the short
+    // form, which is what every rig in this tree writes and what `splitRigSkin`
+    // reads back as the bare attachment table.
+    skins[nameOf(entry)] = anyList ? { ...lists, attachments: table } : table;
+  }
+
+  // -- constraints ----------------------------------------------------------
+  // Inverts `buildRigConstraint`. 4.3 puts every type in ONE array and branches
+  // on `type`, so an unknown `type` is refused here for the same reason the
+  // parser's silence about it is assertion A01: it would simply vanish.
+  const constraints: JsonObject[] = [];
+  for (const raw of arr(root.constraints)) {
+    const constraint = obj(raw);
+    const type = typeof constraint.type === 'string' ? constraint.type : '';
+    const fields = CONSTRAINT_FIELDS[type];
+    const who = `constraint "${nameOf(constraint)}"`;
+    if (fields === undefined) {
+      note('blocker', 'CONSTRAINT_TYPE', who, `type ${JSON.stringify(constraint.type)} is not one of ${Object.keys(CONSTRAINT_FIELDS).join(', ')}`);
+      continue;
+    }
+    // Omitted rather than carried, and said below once the timelines it takes
+    // with it are known (`PHYSICS_DRIVES_NOTHING`).
+    if (type === 'physics' && typeof constraint.name === 'string' && inert.has(constraint.name)) continue;
+    const out: JsonObject = { name: constraint.name, type };
+    for (const field of fields) if (constraint[field] !== undefined) out[field] = constraint[field];
+    for (const key of Object.keys(constraint)) {
+      if (key === 'name' || key === 'type' || fields.includes(key)) continue;
+      note('blocker', 'CONSTRAINT_FIELD', `${who} (${type})`, `field "${key}" has no rig-spec field, so it is dropped`);
+    }
+    constraints.push(out);
+  }
+
+  // -- animations -----------------------------------------------------------
+  const animations: JsonObject = {};
+  for (const [animName, raw] of objEntries(root.animations)) {
+    animations[animName] = ingestAnimation(animName, raw, root, note, inert, (name, property, lastKey) => {
+      const one = omission(name);
+      one.timelines.push(`animation "${animName}" ${property}`);
+      one.lastKeys.set(animName, Math.max(one.lastKeys.get(animName) ?? 0, lastKey));
+    });
+  }
+
+  // One finding per inert constraint, in the file's own order, naming what went
+  // with it. ⚠️ An animation's duration is the largest key time it has LEFT, so
+  // an omitted timeline that held the last key shortens the rebuilt animation —
+  // the one place this omission is not a no-op, and the detail says so there.
+  for (const [name, stated] of inert) {
+    const gone = omission(name);
+    const shortened = [...gone.lastKeys]
+      .map(([animName, lastKey]) => [animName, lastKey, Number(obj(animations[animName]).duration)] as const)
+      .filter(([, lastKey, duration]) => lastKey > duration)
+      .map(
+        ([animName, lastKey, duration]) =>
+          `animation "${animName}" had its last key at ${lastKey}s on one of them, so the rebuilt animation ends at ${duration}s`,
+      );
+    note(
+      'lossy',
+      'PHYSICS_DRIVES_NOTHING',
+      `constraint "${name}" (physics)`,
+      `drives no component: ${PHYSICS_COMPONENTS.join(', ')} are ` +
+        (stated.length ? `absent or at most 0 (it states ${stated.join(', ')})` : 'all absent') +
+        ', and `PhysicsConstraint.update` applies one only above 0, so it moves no bone and `build` would refuse it ' +
+        'by name (A23_PHYSICS_CONSTRAINT_EFFECTIVE). The rig spec omits it' +
+        (gone.timelines.length
+          ? `, and with it the ${gone.timelines.length} timeline(s) keyed to it, which would name a constraint the ` +
+            `rebuild does not have: ${gone.timelines.join('; ')}`
+          : '; no timeline keys it') +
+        (gone.skins.length ? `; it is taken off the physics list of skin(s) ${gone.skins.map((skin) => `"${skin}"`).join(', ')}` : '') +
+        (shortened.length
+          ? `. One thing does move, because a duration is the last key an animation has left: ${shortened.join('; ')}`
+          : '. The rebuild differs from the source by exactly these no-ops'),
+    );
+  }
+
+  // -- constraints the consumer drives (issue #784) --------------------------
+  // A constraint resting muted that no animation switches on is exactly what
+  // `A47` / `A48` refuse, and the export cannot say whether it is a leftover or
+  // a dial a game turns from code: the two are the same bytes. The rebuild
+  // reads it as the consumer's — the reading under which the file is correct —
+  // and says so twice: in the rig spec, as the declaration the gate reads, and
+  // as a finding naming the constraint, so the author sees what the rebuild is
+  // claiming. It is a `judgement` for `DURATION`'s reason: a statement the
+  // skeleton does not carry, made and printed rather than hidden, with nothing
+  // lost — the rebuilt skeleton is the same bytes either way.
+  const carried = new Set(constraints.map((c) => constraintAt(String(c.type), String(c.name))));
+  const consumerDrivenMix: JsonObject[] = [];
+  const animationCount = Object.keys(obj(root.animations)).length;
+  for (const { type, name, reads } of consumerDrivenCandidates(root)) {
+    if (!carried.has(constraintAt(type, name))) continue;
+    const assertion = type === 'ik' ? 'A47_IK_CONSTRAINT_NOT_MUTED_THROUGHOUT' : 'A48_TRANSFORM_CONSTRAINT_NOT_MUTED_THROUGHOUT';
+    consumerDrivenMix.push({
+      constraint: name,
+      type,
+      why:
+        'the source skeleton rests it muted and no animation keys its mix above 0; `rigc ingest` reads it as a mix ' +
+        'the consumer sets, which an export cannot state. Delete this entry if it is a leftover',
+    });
+    note(
+      'judgement',
+      'CONSUMER_DRIVEN_MIX',
+      `constraint "${name}" (${type})`,
+      `rests at ${reads.map((mix) => `${mix} 0`).join(', ')} and none of the ${animationCount} ` +
+        `animation${animationCount === 1 ? '' : 's'} keys its mix above 0, so nothing in this file ever switches it ` +
+        'on — and the file cannot say whether that is a leftover or a mix a game sets from code. `build` refuses the ' +
+        `shape by name (${assertion}) unless the rig spec says which, so the rig spec now says the consumer drives ` +
+        'it, in invariants.consumerDrivenMix, and the gate SKIPs it by name rather than measuring it. If it is a ' +
+        `leftover, delete the entry and rest ${type === 'ik' ? 'its mix' : 'a mix it reads'} above 0 or remove the ` +
+        'constraint, and the gate measures it again',
+    );
+  }
+
+  // -- assemble -------------------------------------------------------------
+  const rig: JsonObject = {
+    spec: RIG_SPEC_VERSION,
+    name: opts.name,
+    note: provenanceNote(opts, 'rig', consumerDrivenMix.length > 0),
+  };
+  if (Object.keys(rigHeader).length) rig.skeleton = rigHeader;
+  // Between `skeleton` and `bones`, which is where `RIG_KEYS.RigSpec` puts it —
+  // this file's key order is the spec's declared order and nothing sorts it.
+  if (opts.images !== undefined) rig.images = opts.images;
+  rig.bones = bones;
+  rig.slots = slots;
+  if (Object.keys(skins).length) rig.skins = skins;
+  if (constraints.length) rig.constraints = constraints;
+  if (isObj(root.events)) rig.events = { ...root.events };
+  // `invariants` is absent but for one field. A skeleton states no invariant,
+  // and INGEST §2.1 already says what to do about that: leave the block out,
+  // because an assertion with nothing to measure reports SKIP and never a pass.
+  // Writing an invariant that turns a check ON here would be certifying a rig
+  // nobody measured. `consumerDrivenMix` is the other direction — it turns two
+  // checks OFF for the constraints named above, which certifies nothing: what it
+  // buys is a SKIP by name, and a finding says each one out loud (issue #784).
+  if (consumerDrivenMix.length) rig.invariants = { consumerDrivenMix };
+
+  const motion: JsonObject = {
+    spec: MOTION_SPEC_VERSION,
+    archetype: opts.name,
+    cut: opts.name,
+    note: provenanceNote(opts, 'motion'),
+    // Empty on purpose: every curve below is written as a RAW `curve` array.
+    // A named easing says "this shape, wherever it is used" and an export carries
+    // a different bezier per key per channel, so there is no named easing to
+    // recognise — only a shape to copy. `easingCurve`'s output is what a raw
+    // curve holds, which is why the rebuild is byte-identical either way.
+    easings: {},
+    animations,
+  };
+
+  // 🔒 Through the tree's own parsers before they leave. `parseRigSpec` and
+  // `parseMotionSpec` are what `build` reads these files with, so a spec this
+  // module could produce and `build` would refuse is named here, at the
+  // decompiler, rather than three commands later at the file.
+  //
+  // ⚠️ And the refusal is a FINDING (issue #692). It is the one place in this
+  // module where a reader's exit code could come from something other than the
+  // findings list, which made it the one shape the census behind the finding
+  // codes could not count.
+  try {
+    return {
+      rig: parseRigSpec(rig, `ingest(${opts.source}): rig spec`),
+      motion: parseMotionSpec(motion, `ingest(${opts.source}): motion spec`),
+      findings,
+    };
+  } catch (err) {
+    if (!(err instanceof CompileError)) throw err;
+    note(
+      'blocker',
+      'SPEC_REFUSED',
+      `the specs written from "${opts.source}"`,
+      `${err.message} — rigc's own parser refuses what this run wrote, so \`build\` will refuse it too. Both files ` +
+        'are on disk so the sentence can be read against the skeleton it came from; nothing rebuilds this ' +
+        'skeleton until the shape it names has a spelling in the spec',
+    );
+    throw new IngestSpecRefused(err.message, findings, rig, motion);
+  }
+}
+
+type Note = (kind: IngestFindingKind, code: string, where: string, detail: string) => void;
+
+/**
+ * The generation of the data this module inverts, read off the version the
+ * emitter writes rather than typed beside it.
+ *
+ * ⚠️ `null` here would be a compiler emitting a version string this repository's
+ * own detector cannot read, and the comparison below is written so that it
+ * blocks every file rather than none — a reader that cannot say what it reads
+ * cannot certify anything. `runGenerationSuite`'s positive control is what says
+ * out loud that it is not null.
+ */
+const READER_GENERATION = spineGeneration(SPINE_VERSION);
+
+/** Up to six names, so one finding cannot print a hundred. */
+function spellSome(names: readonly string[]): string {
+  const shown = names.slice(0, 6).map((name) => `"${name}"`).join(', ');
+  return names.length > 6 ? `${shown} +${names.length - 6} more` : shown;
+}
+
+/**
+ * What a 4.3 reader loses on THIS file, counted on this file.
+ *
+ * 🚨 Three shapes, and they are the three #706 measured rather than three this
+ * module thought of: constraints parked in the top-level arrays 4.3 folded away
+ * (row 1 — 1,302 shipped skeletons parsed and loaded 0 of 8,672 constraints),
+ * bones carrying the key 4.3 renamed (row 6), and physics constraints omitting a
+ * field whose default is not the same number in 4.2 as in 4.3 (row 4).
+ *
+ * ⚠️ It is a MEASUREMENT and not an inventory: a construct none of the three
+ * describes is lost without being counted here, which is why the empty case says
+ * so rather than saying nothing was lost.
+ */
+function generationLosses(root: JsonObject): string[] {
+  const out: string[] = [];
+
+  const parked = TOPLEVEL_CONSTRAINT_ARRAYS.map((kind) => [kind, arr(root[kind]).length] as const).filter(
+    ([, count]) => count > 0,
+  );
+  const parkedTotal = parked.reduce((total, [, count]) => total + count, 0);
+  if (parkedTotal > 0) {
+    out.push(
+      `${parkedTotal} constraint(s) sit in top-level arrays (${parked.map(([kind, count]) => `${kind} ${count}`).join(', ')}) ` +
+        'and this reader takes constraints from "constraints" alone, so it reads none of them and the rebuilt rig has none',
+    );
+  }
+
+  const renamed = arr(root.bones)
+    .filter((bone) => isObj(bone) && LEGACY_BONE_INHERIT_KEY in bone)
+    .map((bone) => nameOf(bone));
+  if (renamed.length > 0) {
+    out.push(
+      `${renamed.length} bone(s) carry "${LEGACY_BONE_INHERIT_KEY}" where 4.3 spells "inherit" (${spellSome(renamed)}), ` +
+        'each dropped as a field the rig spec has no home for — the BONE_FIELD line beside this one — so the ' +
+        'rebuilt bone inherits Normally',
+    );
+  }
+
+  const physics = [...arr(root.physics), ...arr(root.constraints).filter((one) => isObj(one) && one.type === 'physics')].filter(
+    isObj,
+  );
+  const omitting = PHYSICS_FIELDS_WHOSE_DEFAULT_MOVED.map(
+    (field) => [field, physics.filter((one) => one[field] === undefined).length] as const,
+  ).filter(([, count]) => count > 0);
+  if (omitting.length > 0) {
+    out.push(
+      `${physics.length} physics constraint(s), of which ${omitting.map(([field, count]) => `${count} omit "${field}"`).join(' and ')} — ` +
+        "JSON omits a field equal to the parser's default and that default is NOT the same number in 4.2 as in 4.3 " +
+        '(#706 row 4), so the omission means one rig there and a different one here',
+    );
+  }
+  return out;
+}
+
+/**
+ * The generation, read before a field of the file is.
+ *
+ * 🚨 **The silence this converts into a name was measured on the branch point.**
+ * A 4.3 emit with its constraints moved into the top-level arrays 4.2 kept them
+ * in came back through `ingest` as a rig spec with **zero** constraints and
+ * **no finding about them at all**; the only blocker was `BONE_FIELD`, about the
+ * bone key. A 3.8 label produced one `LOSS HEADER_REDERIVED` line and exit 0.
+ * That is the shape this whole module exists to refuse — a decompiler that is
+ * quiet about what it dropped.
+ *
+ * ⭐ **One code with the generation in the sentence, rather than one code per
+ * generation.** `IG25` derives `docs/INGEST.md` §2.0's finding table by reading
+ * every `note` call in this file for a code matching `[A-Z_]+`, and compares it
+ * against rows matched with `[A-Z_<>]+`. A composed `GENERATION_${generation}`
+ * would read `GENERATION_3.8` at runtime — digits and a dot — so the call would
+ * be one the scan cannot resolve and the code would be missing from BOTH sides
+ * of that comparison, which is the one failure comparing two sets cannot report.
+ *
+ * ⚠️ The same scan counts its own population with a second, dumber pattern over
+ * the raw text, comments included — so a prose mention of that call spelled with
+ * its opening bracket raises the count without raising the sites, and `IG25`
+ * goes red on a file with nothing wrong in it. It did, on the first green run of
+ * this change: **25 of 26 read**, the 26th being this very paragraph.
+ *
+ * ⚠️ It does NOT refuse the file. Everything here is a finding and both specs
+ * are still written, for the reason `IngestFinding` states: a spec plus a list
+ * of what is missing from it beats no spec. The exit code is the caller's and it
+ * is 1, because this is a `blocker`.
+ */
+function readGeneration(root: JsonObject, note: Note): void {
+  const declared = obj(root.skeleton).spine;
+  const generation = typeof declared === 'string' ? spineGeneration(declared) : null;
+  if (generation !== null && generation === READER_GENERATION) return;
+  const stated = typeof declared === 'string' ? `${JSON.stringify(declared)}` : 'no `skeleton.spine` at all';
+  const reads = READER_GENERATION ?? '(none — this build\'s own version string is unreadable)';
+  const losses = generationLosses(root);
+  const measured =
+    losses.length > 0
+      ? `Measured on this file: ${losses.join('; ')}.`
+      : 'Measured on this file: no constraint in a top-level array, no bone carrying ' +
+        `"${LEGACY_BONE_INHERIT_KEY}", and no physics constraint omitting a default that moved — which is three ` +
+        'shapes counted and not a guarantee that nothing else differs.';
+  if (generation === null) {
+    note(
+      'blocker',
+      'GENERATION_UNKNOWN',
+      'skeleton.spine',
+      `the file states ${stated} and no Spine generation matches it. A version is read as its LEADING major.minor ` +
+        'token — a down-export states "4.0-from-4.1.24", which is 4.0 data from a 4.1 editor — and the generations ' +
+        `rigc knows are ${SPINE_GENERATIONS.join(', ')}; this reader reads ${reads}. It is NOT read as the nearest ` +
+        'one: a catalogue that handed 19 skeletons labelled "3.8.99" the nearest runtime it had loaded every one of ' +
+        `them and posed 238 of 248 bones as NaN (issue #706 row 7). ${measured}`,
+    );
+    return;
+  }
+  note(
+    'blocker',
+    'GENERATION_UNSUPPORTED',
+    'skeleton.spine',
+    `the file states ${stated}, which is Spine ${generation} data, and this reader reads Spine ${reads} only — it ` +
+      `inverts a ${SPINE_VERSION} emitter. A generation mismatch does not throw; it drops what the newer format ` +
+      `moved. ${measured} Reading the file with ${generation}'s OWN defaults is issue #706 item 2 — a ` +
+      'per-generation table extracted by machine from each runtime\'s `SkeletonJson` — and is not in this tool. ' +
+      `Re-export from a ${reads} editor, or transcribe the file by hand (docs/INGEST.md §2).`,
+  );
+}
+
+/** The four fields a stage is, in the order the editor and `compile` write them. */
+const STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
+
+/**
+ * Does this header declare a stage?
+ *
+ * 🔒 One reading, three callers below — the refusal, the origin default and the
+ * early return — because they are three statements about the same header and two
+ * spellings of "declares a stage" would be two things that have to agree. The
+ * EXTENT is what declares one: an origin for a box that is not there is a shape
+ * no export carries, which is how `diff`'s `stageFacts` and `compile`'s stage
+ * guard already read it.
+ */
+function declaresStage(head: JsonObject): boolean {
+  return head.width !== undefined && head.height !== undefined;
+}
+
+/**
+ * A stage as one string, for a message that has to put two of them side by side.
+ *
+ * The origin is spelled `0` where it is absent, for the reason `HEADER_ORIGIN`
+ * writes it: inside a declared extent that is what the omission means, so a
+ * refusal that printed the file's box as `undefined,undefined,…` would be
+ * quoting the file against the reading every other part of this tree holds.
+ */
+function spellStage(x: unknown, y: unknown, width: unknown, height: unknown): string {
+  return [x ?? 0, y ?? 0, width, height].map((value) => String(value)).join(',');
+}
+
+/**
+ * The rig spec's header fields a skeleton's own header can state — every one
+ * but `stageBox`, which is the caller's reading of a slot (`--stage-box`,
+ * issue #1168) and never a key of the Spine header: a header that carried a
+ * key of that name would otherwise be copied into the rebuilt spec as a
+ * request for a box nobody named.
+ */
+const HEADER_FIELDS_FROM_FILE: readonly string[] = RIG_KEYS.RigSkeletonHeader.filter((field) => field !== 'stageBox');
+
+/** The stage box `--stage-box` read (`readStageBox`): its slot, its attachment and the stage its four corners are. */
+interface StageBoxRead {
+  slot: string;
+  attachment: string;
+  stage: IngestStage;
+}
+
+/**
+ * Read the stage from the bounding box in `slotName` (issue #1168,
+ * `--stage-box`): the box `build` writes for a rig that asks for one
+ * (`skeleton.stageBox`), read back as the rebuild's stage.
+ *
+ * 🔒 **Only a box `build` could write back is read, and everything else is
+ * refused by name** — the slot is named by the caller, so a shape that is not
+ * the stage is a mistake to report, not a guess to make. Refused: a slot the
+ * skeleton does not have; a slot on a bone other than the root, or on a root
+ * that states a setup transform (the box would not be the stage in world
+ * space, and `build` refuses the same); a slot with no attachment in the
+ * `default` skin, more than one, or one in another skin; an attachment that
+ * is not a bounding box, states a `name` other than its placeholder, or is not
+ * four unweighted vertices; four vertices that are not the corners of one
+ * axis-aligned rectangle of positive size.
+ *
+ * The stage is the rectangle's least corner and its extent. What the rebuild
+ * writes differently is one lossy finding, `STAGE_BOX_REWRITTEN`: `build`
+ * writes the corners bottom-left first and counter-clockwise and states no
+ * `color`, so a box in another order or with the editor's colour comes back as
+ * the same rectangle, spelled `build`'s way.
+ */
+function readStageBox(root: JsonObject, slotName: string, note: Note): StageBoxRead {
+  const flag = `--stage-box ${slotName}`;
+  const slot = arr(root.slots).map(obj).find((s) => s.name === slotName);
+  if (slot === undefined) {
+    throw new IngestError(`${flag}: the skeleton has no slot "${slotName}"; it declares [${arr(root.slots).map(nameOf).join(', ')}]`);
+  }
+  const bones = arr(root.bones).map(obj);
+  const bone = bones.find((b) => b.name === slot.bone);
+  if (bone === undefined || bone.parent !== undefined) {
+    throw new IngestError(
+      `${flag}: slot "${slotName}" hangs on bone "${String(slot.bone)}", which is not the root. A stage box is the stage's ` +
+        "corners in world space, and build writes one only on the root — on any other bone the box's numbers are not the stage",
+    );
+  }
+  const moved: string[] = [
+    ...['x', 'y', 'rotation', 'shearX', 'shearY'].filter((key) => bone[key] !== undefined && bone[key] !== 0),
+    ...['scaleX', 'scaleY'].filter((key) => bone[key] !== undefined && bone[key] !== 1),
+  ];
+  if (moved.length > 0) {
+    throw new IngestError(
+      `${flag}: slot "${slotName}" hangs on the root "${nameOf(bone)}", which states ${moved.map((key) => `${key} ${JSON.stringify(bone[key])}`).join(', ')}. ` +
+        "A box on a root that moves at setup is not the stage in world space, and build refuses to write one there",
+    );
+  }
+  const elsewhere = arr(root.skins).map(obj).filter((skin) => skin.name !== 'default' && Object.keys(obj(obj(skin.attachments)[slotName])).length > 0);
+  if (elsewhere.length > 0) {
+    throw new IngestError(
+      `${flag}: slot "${slotName}" is also filled by skin(s) ${elsewhere.map((skin) => `"${nameOf(skin)}"`).join(', ')}. A stage box is its ` +
+        "slot's one attachment, in the default skin, so a reader of that slot finds the stage and nothing else",
+    );
+  }
+  const table = obj(obj(arr(root.skins).map(obj).find((skin) => skin.name === 'default')?.attachments)[slotName]);
+  const placeholders = Object.keys(table);
+  if (placeholders.length !== 1) {
+    throw new IngestError(
+      `${flag}: the default skin holds ${placeholders.length === 0 ? 'no attachment' : `${placeholders.length} attachments [${placeholders.join(', ')}]`} on slot "${slotName}"; ` +
+        "a stage box is its slot's one attachment",
+    );
+  }
+  const attachment = placeholders[0];
+  const att = obj(table[attachment]);
+  const where = `${flag}: attachment "${attachment}" on slot "${slotName}"`;
+  if (att.type !== 'boundingbox') throw new IngestError(`${where} is a ${JSON.stringify(att.type ?? 'region')}, not a bounding box`);
+  if (att.name !== undefined && att.name !== attachment) {
+    throw new IngestError(`${where} states the name ${JSON.stringify(att.name)}; a stage box is named by its placeholder, which is what build writes`);
+  }
+  const vertices = Array.isArray(att.vertices) ? att.vertices : [];
+  if (att.vertexCount !== 4 || vertices.length !== 8 || !vertices.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+    throw new IngestError(
+      `${where} states vertexCount ${JSON.stringify(att.vertexCount)} and ${vertices.length} vertex number(s); the stage is four unweighted ` +
+        'corners — vertexCount 4 and eight finite numbers',
+    );
+  }
+  const xy = vertices as number[];
+  const xs = [...new Set([xy[0], xy[2], xy[4], xy[6]])].sort((a, b) => a - b);
+  const ys = [...new Set([xy[1], xy[3], xy[5], xy[7]])].sort((a, b) => a - b);
+  const corners = new Set([0, 2, 4, 6].map((i) => `${xy[i]},${xy[i + 1]}`));
+  if (xs.length !== 2 || ys.length !== 2 || corners.size !== 4) {
+    throw new IngestError(`${where} holds [${xy.join(', ')}], which is not the four corners of one axis-aligned rectangle of positive size`);
+  }
+  const stage: IngestStage = { x: xs[0], y: ys[0], width: xs[1] - xs[0], height: ys[1] - ys[0] };
+  const rewritten: string[] = [];
+  const order = [xs[0], ys[0], xs[1], ys[0], xs[1], ys[1], xs[0], ys[1]];
+  if (order.some((v, i) => v !== xy[i])) rewritten.push(`its corners [${xy.join(', ')}] in build's order [${order.join(', ')}], bottom-left first and counter-clockwise`);
+  if (att.color !== undefined) rewritten.push(`no color (the source states ${JSON.stringify(att.color)}, an editor affordance build does not write on a stage box)`);
+  if (rewritten.length > 0) {
+    note('lossy', 'STAGE_BOX_REWRITTEN', `skin "default" slot "${slotName}" attachment "${attachment}"`, `the rebuild writes the same rectangle with ${rewritten.join(', and ')}`);
+  }
+  return { slot: slotName, attachment, stage };
+}
+
+/**
+ * The rig spec's `skeleton` block — and the one judgement in this module.
+ *
+ * 🚨 **A skeleton JSON need not carry a box, and a stage cannot be derived.**
+ * The stage is the working area the art was painted in; no pose of the rig
+ * states it. So a file that declares none is written as declaring none
+ * — `"width": null, "height": null`, the rig spec's spelling for that claim since
+ * issue #578 — and `compile` then emits a header with none of the four fields,
+ * which is the file that was read, byte for byte. No finding: nothing was lost,
+ * nothing re-derived and nobody decided anything, and a line saying so would be
+ * a finding about a file that rebuilds exactly (issue #714).
+ *
+ * ⚠️ **That is the shape of a whole production corpus, not a corner.** Until
+ * #714 this branch was a `NO_STAGE` blocker and the only road through it was a
+ * caller's `--stage` — a number the source never stated. Issue #714 counts 48 of
+ * 48 production exports at 4.3.26 carrying no box; all twelve exports under
+ * `examples/` carry all four fields, and take the declared branch below.
+ *
+ * 🔸 **Half a stage is still a blocker, and keeps the code.** A header that
+ * states an origin with no extent, or one extent without the other, declares no
+ * stage — the extent is what declares one — but it is not the absence either:
+ * the rig spec holds a stage as four fields or none (`parseRigSpec` refuses the
+ * pair `null` beside an `x`, and one extent alone is `compile`'s `no stage size`),
+ * so the rebuild cannot carry what the file states. No export measured here has
+ * that shape; the blocker names the fields it does state.
+ *
+ * ⭐ It is still the judgement that costs least to get wrong. `diff` does report
+ * the header's box — `bounds_present` and `bounds_box` (issue #578, renamed by
+ * #907) — but they sit in the `(reported)` block that no rung consults.
+ *
+ * 🔁 **What the box becomes (issue #907).** A header's box is its setup-pose
+ * bounding box — what the format says the four are, and what every editor
+ * export carries there. It is the only box a file has, so it becomes the
+ * rebuild's stage (`A14` and `A19` measure against it, as they did against the
+ * export's header). The rebuild's own header is not carried from it: `build`
+ * computes the setup-pose bounding box of what it draws (`headerBoundsOf` in
+ * `src/compile.ts`), which for a rebuild drawing the source's vertices is
+ * spine-core's `getBounds` over the source on the header's 1e-6 grid at float32 — not the editor's
+ * arithmetic, which on the twelve examples sits up to 0.0071 units away. A
+ * rigc build's own header is likewise its bounding box, not its stage: the
+ * stage is in `skeleton.model.json`, which the caller reads and hands in as
+ * `documentStage` when that document digests this skeleton — and then it is
+ * read in place of the header's box.
+ *
+ * 🔇 **Both of its silences were here, and both were around the DECLARED branch
+ * rather than the missing one.** That branch used to be a bare early return, so
+ * an origin the source omitted left no trace at all (issue #622) and a `--stage`
+ * given beside a declared box was read after it and therefore never (issue #626).
+ * Neither was wrong — the rebuild carried the right numbers both times — which is
+ * exactly the shape this whole module exists to convert into something named:
+ * a decompiler that is right for a reason it never states is a decompiler nobody
+ * can check.
+ */
+function ingestHeader(source: JsonObject, opts: IngestOptions, note: Note, box: StageBoxRead | null = null): JsonObject {
+  // The stage box the caller named (issue #1168) is the file's own statement of its stage, so a second source beside it is refused, as `--stage` beside a declared box is.
+  if (box !== null) {
+    const spelled = spellStage(box.stage.x, box.stage.y, box.stage.width, box.stage.height);
+    if (opts.stage !== undefined) {
+      throw new IngestError(
+        `--stage-box ${box.slot} reads a stage of ${spelled} from the skeleton's bounding box "${box.attachment}" and --stage supplied ` +
+          `${spellStage(opts.stage.x, opts.stage.y, opts.stage.width, opts.stage.height)}: two sources for one value. Drop one of the two flags`,
+      );
+    }
+    const doc = opts.documentStage;
+    if (doc !== undefined && (doc === null || spellStage(doc.x, doc.y, doc.width, doc.height) !== spelled)) {
+      throw new IngestError(
+        `--stage-box ${box.slot} reads a stage of ${spelled} from the skeleton's bounding box "${box.attachment}", and the model document ` +
+          `beside it states ${doc === null ? 'no stage' : spellStage(doc.x, doc.y, doc.width, doc.height)}: two statements of one stage that ` +
+          "disagree, about one build. rigc will not choose between them — A50_STAGE_BOX_IS_THE_STAGE refuses such a build, so one of the files was edited after it",
+      );
+    }
+  }
+  // A rigc build's stage is its model document's (issue #907, `IngestOptions.documentStage`) or its stage box's (issue #1168): read in place of the header's box.
+  const replaced = box !== null ? box.stage : opts.documentStage;
+  const head: JsonObject = replaced === undefined ? source : Object.fromEntries(Object.entries(source).filter(([key]) => !(STAGE_FIELDS as readonly string[]).includes(key)));
+  if (replaced) Object.assign(head, replaced);
+  // 🚨 Before a line of transcription, because a header the caller contradicted
+  // is not a header to start writing a spec from (issue #626).
+  if (declaresStage(head) && opts.stage !== undefined) {
+    throw new IngestError(
+      `the skeleton declares a stage of ${spellStage(head.x, head.y, head.width, head.height)} and --stage supplied ` +
+        `${spellStage(opts.stage.x, opts.stage.y, opts.stage.width, opts.stage.height)}: two sources for one value. ` +
+        'rigc will not overwrite a box the file states — the file is the record of what was measured, and the flag ' +
+        'is for a skeleton that declares none. Drop --stage, or correct `skeleton` in the source if its box is wrong',
+    );
+  }
+  const out: JsonObject = {};
+  for (const field of HEADER_FIELDS_FROM_FILE) if (head[field] !== undefined) out[field] = head[field];
+  // The stage box is the caller's reading of a slot, never a header key: a Spine header has no such field (issue #1168).
+  if (box !== null) out.stageBox = { slot: box.slot, attachment: box.attachment };
+  for (const key of Object.keys(head)) {
+    if (HEADER_FIELDS_FROM_FILE.includes(key)) continue;
+    if (HEADER_REDERIVED.includes(key)) {
+      // Two-sided on purpose: the same fact reads as bookkeeping when the two
+      // agree and as a warning when they do not, and a reader needs to be told
+      // which — a rebuild of a 4.2 export states 4.3, in one field, silently.
+      const same = head[key] === SPINE_VERSION;
+      note(
+        'lossy',
+        'HEADER_REDERIVED',
+        `skeleton.${key}`,
+        `the source states ${JSON.stringify(head[key])} and the rig spec has no field for it: a rebuild writes the ` +
+          `version of the runtime rigc links, ${SPINE_VERSION}` +
+          (same ? ', which is the same string, so nothing moves' : ' — so this field WILL change on the rebuild'),
+      );
+      continue;
+    }
+    note(
+      'lossy',
+      'HEADER_BOOKKEEPING',
+      `skeleton.${key}`,
+      `the editor writes "${key}" and the rig spec has no field for it; it is dropped and nothing reads it back`,
+    );
+  }
+  if (declaresStage(head)) {
+    // ⭐ **Inside a declared extent, an omitted origin IS `0`** (issue #620),
+    // which is a reading of the format rather than a value invented for a gap:
+    // `compile` assembles `header.x = rig.skeleton?.x ?? 0` under this same
+    // guard, `diff`'s `stageFacts` reads the omission the same way, and
+    // `stageFacts`'s own comment carries the four measurements behind it. So the
+    // spec states what the file meant instead of leaving the rebuild to a
+    // default in another module — and the half that has to be said out loud is
+    // the other one: the rebuilt header SPELLS a field the source omitted
+    // (issue #622).
+    const omitted = ['x', 'y'].filter((field) => head[field] === undefined);
+    if (omitted.length > 0) {
+      out.x = head.x ?? 0;
+      out.y = head.y ?? 0;
+      note(
+        'lossy',
+        'HEADER_ORIGIN',
+        `skeleton.${omitted.join('/')}`,
+        `the source declares a ${String(head.width)}x${String(head.height)} stage and omits ` +
+          `${omitted.map((field) => `"${field}"`).join(' and ')}; inside a declared extent an omitted origin is 0, ` +
+          'which is how `compile` and `diff` read it (#620), so the rig spec states x=' +
+          `${String(out.x)}, y=${String(out.y)} rather than leaving the rebuild to a default in another module. ` +
+          `⚠️ The rebuilt header WILL spell ${omitted.length > 1 ? 'those fields' : 'that field'}: it carries the ` +
+          'setup-pose bounding box `build` computes (#907), whose origin is wherever the art sits',
+      );
+    }
+    return out;
+  }
+  if (opts.stage === undefined) {
+    const stated = STAGE_FIELDS.filter((field) => head[field] !== undefined);
+    if (stated.length === 0) {
+      // The absence, carried: the pair goes where `RIG_KEYS` orders it, so the
+      // spec reads like one a transcriber would have written by hand.
+      const carried: JsonObject = {};
+      for (const field of HEADER_FIELDS_FROM_FILE) {
+        if (field === 'width' || field === 'height') carried[field] = null;
+        else if (out[field] !== undefined) carried[field] = out[field];
+      }
+      return carried;
+    }
+    const unstated = STAGE_FIELDS.filter((field) => head[field] === undefined);
+    note(
+      'blocker',
+      'NO_STAGE',
+      'skeleton.width/height',
+      `the skeleton states ${stated.map((field) => `"${field}"`).join(', ')} and no ` +
+        `${unstated.map((field) => `"${field}"`).join(', ')}, so it declares no stage — a width and a height are ` +
+        'what declare one — and it is not the absence either. A rig spec holds a stage as four fields or none, so ' +
+        'the rebuild cannot carry what this header states. Give --stage x,y,w,h if the box is known — the value is ' +
+        'the caller\'s, not derived: posing the rig would give the ANIMATED extent, which is a different number from ' +
+        'the setup box — or take the stray field(s) out of the source, and the absence is then carried as it stands',
+    );
+    return out;
+  }
+  Object.assign(out, opts.stage);
+  note(
+    'judgement',
+    'NO_STAGE',
+    'skeleton.width/height',
+    `the skeleton declares no stage and the caller supplied ${opts.stage.x},${opts.stage.y},${opts.stage.width},` +
+      `${opts.stage.height}. Nothing measured it against the art: \`A14\` and \`A19\` measure the art against it ` +
+      'and `diff` reports it, so a wrong box is green everywhere. Without --stage the absence is carried instead, ' +
+      'and the rebuild declares no stage either',
+  );
+  return out;
+}
+
+/**
+ * One attachment, by type. Inverts `buildRigAttachment`'s five branches.
+ *
+ * The types rigc does not emit are refused BY NAME rather than dropped, which is
+ * the same reason `buildRigAttachment` refuses them: the parser's own behaviour
+ * on a type it does not know is to return null and carry on, so a decompiler
+ * that skipped one would hand back a spec that is quietly missing an attachment.
+ */
+function ingestAttachment(
+  att: JsonObject,
+  placeholder: string,
+  boneNames: readonly string[],
+  opts: IngestOptions,
+  note: Note,
+  at: { where: string },
+): JsonObject {
+  // `readAttachment` reads no `type` as `region` (`SkeletonJson:539`), and so
+  // does `checkRigSpecKeys`. Both defaults are the parser's, not a guess.
+  const type = att.type === undefined ? 'region' : String(att.type);
+  const out: JsonObject = {};
+
+  // A LINKED mesh, in either of the format's two spellings. The format decides
+  // it — one branch of the reader for `mesh` and `linkedmesh`, and a truthy
+  // `source` decides (`SkeletonJson.js:568-569`, `:582`) — so `type: "mesh"` carrying
+  // `source` inverts to a link, and a `linkedmesh` with none does NOT: that map
+  // is read as an ordinary mesh, whose `uvs` it does not have, and the parser
+  // throws on it. Reading the second as a link would be this module inventing a
+  // construct the file does not contain (issue #691).
+  const linked = (type === 'mesh' || type === 'linkedmesh') && typeof att.source === 'string' && att.source.length > 0;
+
+  // The three types the parser gives a texture `path` to — and reads a
+  // `sequence` on. `readAttachment` reaches `getValue(map, "path", name)` in the
+  // `region` branch (`SkeletonJson.js:529`) and in the shared `mesh`/`linkedmesh`
+  // branch (`:560`); `boundingbox`, `path`, `point` and `clipping` are
+  // constructed from the name alone and resolve no region at all.
+  const resolvesRegion = linked || type === 'region' || type === 'mesh';
+
+  /** The texture side, which the skeleton does not encode. Inverts `buildRigRegion`'s tail. */
+  const carryArt = (): void => {
+    if (att.path !== undefined) out.path = att.path;
+    // `buildRigRegion` writes `path` when the image basename differs from the
+    // name the attachment carries — its stated `name`, else the placeholder —
+    // so naming the image after the region this attachment RESOLVES
+    // (`path ?? name ?? placeholder`, the defaults the format's reader applies
+    // at `SkeletonJson.js:526`, `:529`, `:560`) reproduces the same `path`
+    // decision AND the same atlas region name.
+    if (opts.art === 'loose') {
+      const region = att.path ?? (typeof att.name === 'string' ? att.name : placeholder);
+      out.image = `${String(region)}.png`;
+    }
+    if (att.width !== undefined) out.width = att.width;
+    if (att.height !== undefined) out.height = att.height;
+  };
+
+  /**
+   * The vertex array, as one of the two encodings `readVertices` decides between.
+   *
+   * Inverts `buildVertexGeometry` / `encodeNamedWeights`: the run is unweighted
+   * when it is exactly as long as the coordinate count the attachment declares,
+   * and a weight run otherwise. That length comparison is the parser's own.
+   */
+  const geometry = (declaredPairs: number | undefined): void => {
+    const vertices = numbers(att.vertices);
+    if (vertices === undefined) return;
+    if (declaredPairs !== undefined && vertices.length === declaredPairs * 2) out.vertices = vertices;
+    else out.weights = decodeWeights(vertices, boneNames);
+  };
+
+  const vertexCount = typeof att.vertexCount === 'number' ? att.vertexCount : undefined;
+
+  if (linked) {
+    out.type = 'linkedmesh';
+    carryArt();
+    out.source = att.source;
+    // Only what the file states. `slot`, `skin` and `timelines` each have a
+    // parser default (this attachment's slot, the default skin, true), and
+    // writing one the source omitted would be a rebuild that says more than the
+    // file did — and `buildRigLinkedMesh` drops it again on the way back out.
+    for (const field of ['slot', 'skin', 'timelines', 'color']) if (att[field] !== undefined) out[field] = att[field];
+    const dropped = LINKED_MESH_UNREAD_KEYS.filter((field) => att[field] !== undefined);
+    if (dropped.length > 0) {
+      note(
+        'lossy',
+        'ATTACHMENT_LINK_GEOMETRY',
+        at.where,
+        `the attachment is a LINKED mesh and states ${dropped.map((field) => `\`${field}\``).join(', ')}, which the ` +
+          'parser reads with nothing at all: it returns from the `source` branch before `readVertices` ' +
+          `(\`SkeletonJson.ts:582-586\`), so what this attachment draws is the geometry of ${JSON.stringify(att.source)}. ` +
+          `The rebuild drops ${dropped.length === 1 ? 'it' : 'them'} — the rig spec refuses geometry on a link by name, ` +
+          'and carrying it would write a spec `build` will not take. `A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN` ' +
+          'is the same fact held against the source file',
+      );
+    }
+  } else if (type === 'region') {
+    carryArt();
+    for (const field of ['x', 'y', 'rotation', 'scaleX', 'scaleY', 'color']) {
+      if (att[field] !== undefined) out[field] = att[field];
+    }
+  } else if (type === 'mesh') {
+    out.type = 'mesh';
+    carryArt();
+    out.uvs = att.uvs;
+    out.triangles = att.triangles;
+    geometry(Array.isArray(att.uvs) ? att.uvs.length / 2 : undefined);
+    // Carried rather than re-derived: `authoredHullAndEdges` takes an authored
+    // pair as written and cross-checks `hull` against the triangles, so stating
+    // both keeps the emitted arrays identical instead of equal-by-derivation.
+    if (att.hull !== undefined) out.hull = att.hull;
+    if (att.edges !== undefined) out.edges = att.edges;
+    if (att.color !== undefined) out.color = att.color;
+  } else if (type === 'boundingbox' || type === 'clipping') {
+    out.type = type;
+    out.vertexCount = att.vertexCount;
+    geometry(vertexCount);
+    if (att.color !== undefined) out.color = att.color;
+    if (type === 'clipping') {
+      for (const field of ['end', 'convex', 'inverse']) if (att[field] !== undefined) out[field] = att[field];
+    }
+  } else if (type === 'path') {
+    out.type = 'path';
+    out.vertexCount = att.vertexCount;
+    geometry(vertexCount);
+    for (const field of ['closed', 'constantSpeed', 'color']) if (att[field] !== undefined) out[field] = att[field];
+    // Carried verbatim (issue #804), where until then it was dropped as `LOSS
+    // PATH_LENGTHS` and re-measured. The editor measures it on the pose the
+    // first update gives the path constraint — constraints applied — and rigc
+    // does not pose, so the re-measure was a different number on every path a
+    // constraint moves at rest, and on every weighted path over a scaled bone.
+    if (att.lengths !== undefined) out.lengths = att.lengths;
+  } else {
+    note(
+      'blocker',
+      `ATTACHMENT_${type.toUpperCase()}`,
+      at.where,
+      `attachment type ${JSON.stringify(type)} is in the Spine 4.3 format and rigc does not emit it (it emits ` +
+        `${ATTACHMENT_TYPES.join(', ')}; point is the one deferred type left — docs/SPEC_COVERAGE.md part 1-6 says ` +
+        'what it would carry). The rebuild will not have this attachment',
+    );
+    return out;
+  }
+
+  // A numbered image series (issue #729). Carried as the file states it —
+  // the four fields `readSequence` reads — wherever the rig spec can say it;
+  // what is left for the blocker is a block the parser reads into a series
+  // that is not the one written, or one on a kind the parser never reads it on.
+  // `null` is the parser's own absent (`getValue(map, "sequence", null)`), so it
+  // is read as no series rather than as a malformed one.
+  if (att.sequence !== undefined && att.sequence !== null) {
+    const refusal = resolvesRegion
+      ? sequenceBlockRefusal(att.sequence)
+      : `the attachment is a ${type}, and \`readAttachment\` reads a \`sequence\` only on a region or a mesh ` +
+        '(`SkeletonJson.js:530`, `:561`) — the parser never read this one, and the rig spec refuses it there by name';
+    if (refusal === null) {
+      const seq = att.sequence as JsonObject;
+      const carried: JsonObject = {};
+      for (const field of ['count', 'start', 'digits', 'setup']) if (seq[field] !== undefined) carried[field] = seq[field];
+      out.sequence = carried;
+      // The frames ARE the art: `<path><number>` regions, which on the loose
+      // route are PNGs of those names. A single `image` would name one region
+      // the series does not have, and the rig spec refuses the pair.
+      delete out.image;
+    } else {
+      note(
+        'blocker',
+        'ATTACHMENT_SEQUENCE',
+        at.where,
+        `the attachment's \`sequence\` block is ${JSON.stringify(att.sequence)}: ${refusal}. The rebuild draws the ` +
+          'single region this attachment names instead of a series',
+      );
+    }
+  }
+  // 🔑 The attachment's own `name`, carried VERBATIM wherever the source states
+  // one — and nowhere else (issue #796). It is the runtime's `Attachment.name`
+  // (`getValue(map, "name", placeholder)`, `SkeletonJson.js:526`) and, with no
+  // `path`, the region the attachment draws; the rig spec has a field for it
+  // and `compile` writes exactly what that field states, so nothing about it is
+  // lost and nothing is re-derived. A name equal to its placeholder is carried
+  // too: the source spelled it, and the rebuild is held to the source's text.
+  // Put right after `type`, the order `RIG_KEYS` gives the field.
+  if (att.name === undefined) return out;
+  const { type: carriedType, ...rest } = out;
+  return carriedType === undefined ? { name: att.name, ...rest } : { type: carriedType, name: att.name, ...rest };
+}
+
+/**
+ * Why a `sequence` block cannot be carried as written, or `null` when it can —
+ * the rig spec's own refusals (`checkRigSequence`), stated about a file.
+ *
+ * Every one of them is a series the parser loads into something other than
+ * what the file says (issue #729): no `count` is 0 regions, a `setup` past the
+ * end is clamped, a fraction names a region like `stem1.5`.
+ */
+function sequenceBlockRefusal(seq: unknown): string | null {
+  if (typeof seq !== 'object' || seq === null || Array.isArray(seq)) {
+    return 'a sequence is an object of `count`, `start`, `digits` and `setup`';
+  }
+  const block = seq as JsonObject;
+  if (block.count === undefined) {
+    return 'it states no `count`, and `readSequence` reads 0 — the attachment loads holding no region and draws nothing';
+  }
+  for (const [field, min] of [['count', 1], ['start', 0], ['digits', 0], ['setup', 0]] as const) {
+    const value = block[field];
+    if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < min)) {
+      return `\`${field}\` is ${JSON.stringify(value)}, and the rig spec takes a whole number of at least ${min} there`;
+    }
+  }
+  if (typeof block.setup === 'number' && block.setup >= (block.count as number)) {
+    return `\`setup\` ${block.setup} is past the end of a ${String(block.count)}-frame series, and \`Sequence.resolveIndex\` clamps it to the last frame`;
+  }
+  return null;
+}
+
+/** One animation. Inverts step 5 of `compile()` — the whole timeline half. */
+function ingestAnimation(
+  animName: string,
+  anim: JsonObject,
+  root: JsonObject,
+  note: Note,
+  inert: ReadonlyMap<string, unknown>,
+  omitted: (constraint: string, property: string, lastKey: number) => void,
+): JsonObject {
+  const tracks: JsonObject[] = [];
+  let maxT = 0;
+  const seeT = (t: number): void => {
+    if (t > maxT) maxT = t;
+  };
+  const timeOf = (key: JsonObject): number => {
+    const t = typeof key.time === 'number' ? key.time : 0;
+    seeT(t);
+    return t;
+  };
+
+  /**
+   * A key's easing, as the motion spec spells it.
+   *
+   * Inverts `rawCurve`: `"stepped"` is a named easing the compiler passes
+   * through, and an array is the absolute (time, value) control points, four per
+   * channel, which `curve` takes verbatim. A key with neither is linear.
+   */
+  const easing = (key: JsonObject, out: JsonObject): void => {
+    if (key.curve === 'stepped') out.ease = 'stepped';
+    else if (key.curve !== undefined) out.curve = key.curve;
+  };
+
+  /**
+   * A value track of any of the four families. Inverts `compileValueTrack`.
+   *
+   * ⚠️ An EDITOR omits a channel that equals the parser's default, and the
+   * spec's `v` is positional — so an omission is filled at that channel's
+   * default, which is the value the runtime reads there. The emitter leaves
+   * the same channel out again wherever `PARSER_DEFAULTS` has a row for the
+   * key's kind (issue #716), so the rebuild is the source's own text there and
+   * nothing is said. What is reported, once per track, is a filled channel the
+   * emitter WILL write — a kind with no measured row — because that one is a
+   * restatement rather than a copy and a reader should know which.
+   */
+  const valueTrack = (target: JsonObject, property: string, keys: readonly unknown[], shape: TrackShape, where: string): void => {
+    const fields = shape.map(([field]) => field);
+    const out: JsonObject[] = [];
+    let restated = 0;
+    const family = Object.keys(target)[0];
+    const row = PARSER_DEFAULTS[`${family} ${property} key`];
+    for (const raw of keys) {
+      const key = obj(raw);
+      const entry: JsonObject = { t: timeOf(key) };
+      const filled: string[] = [];
+      // The zero-field branch: `reset` IS the event, so the key carries no value
+      // and the spec spells that `null`.
+      entry.v =
+        shape.length === 0
+          ? null
+          : shape.map(([field, dflt]) => {
+              if (key[field] !== undefined) return key[field];
+              filled.push(field);
+              // A string default names another field of THIS key (`mixY` ->
+              // `mixX`); when that one is absent too the chain ends at 1, which
+              // is what `ConstraintChannel.dflt` holds for both.
+              if (typeof dflt !== 'string') return dflt;
+              return key[dflt] === undefined ? 1 : key[dflt];
+            });
+      if (filled.length > 0) {
+        // The key as the emitter will hold it — every channel stated — asked
+        // the one question the emitter asks of it.
+        const emitted: JsonObject = { ...key };
+        shape.forEach(([field], i) => (emitted[field] = (entry.v as JsonObject[string][])[i]));
+        const site = { object: emitted, previous: () => null };
+        restated += filled.filter((field) => row === undefined || !parserOmits(row, site, field)).length;
+      }
+      easing(key, entry);
+      for (const field of Object.keys(key)) {
+        if (field === 'time' || field === 'curve' || fields.includes(field)) continue;
+        note('blocker', 'TIMELINE_FIELD', where, `key field "${field}" is not part of this timeline's shape`);
+      }
+      out.push(entry);
+    }
+    if (restated > 0) {
+      note(
+        'lossy',
+        'TIMELINE_KEY_RESTATED',
+        where,
+        `${restated} channel value(s) the source omits are written out at the parser's default (${shape
+          .map(([field, dflt]) => `${field}=${String(dflt)}`)
+          .join(', ')}), because the motion spec's \`v\` is positional and the emitter has no measured row ` +
+          `for "${family} ${property}" keys to leave them out by — the same values the runtime reads`,
+      );
+    }
+    tracks.push({ ...target, property, keys: out });
+  };
+
+  /**
+   * One family of constraint timelines: `<family>.<constraint>.<timeline>`.
+   *
+   * ⭐ All three tables are now COMPLETE against `SkeletonJson`'s switch for
+   * their group, so the blocker below no longer fires on anything the runtime
+   * plays — it is reachable only for a timeline name the parser itself falls
+   * through (`:1094` for physics, and neither the path nor the slider switch
+   * has a default either). It is kept rather than deleted because `ingest`'s
+   * contract is byte identity and not equivalence: a name nothing reads is
+   * still a name the rebuild does not write. The alternative — demoting it to
+   * `lossy`, on the argument that the rebuilt skeleton plays identically — is
+   * a decision about all three families and is not made here.
+   */
+  /**
+   * The physics constraints the rebuild carries — every one the file declares
+   * but those `ingest` omits as inert — which is what an unnamed physics
+   * timeline can reach in it.
+   */
+  const carriedPhysics = arr(root.constraints)
+    .map(obj)
+    .filter((one) => one.type === 'physics' && !(typeof one.name === 'string' && inert.has(one.name)));
+  /** Unnamed physics timelines that reach nothing in the rebuild, said once the duration is known. */
+  const unreached: Array<{ property: string; lastKey: number }> = [];
+  const family = (group: 'path' | 'physics' | 'slider', shapes: Record<string, TrackShape>): void => {
+    for (const [name, timelines] of objEntries(anim[group])) {
+      for (const [property, keys] of arrEntries(timelines)) {
+        // A timeline keyed to a physics constraint `ingest` omitted (issue #731)
+        // goes with it: carried, it names a constraint the rebuilt rig has not
+        // got, and `build` refuses the whole motion spec over it. Its keys are
+        // not seen by `seeT` — they are not in the rebuild — and their latest
+        // time is handed back so the finding can say when that shortened one.
+        if (group === 'physics' && inert.has(name)) {
+          let lastKey = 0;
+          for (const raw of keys) {
+            const t = obj(raw).time;
+            if (typeof t === 'number' && t > lastKey) lastKey = t;
+          }
+          omitted(name, property, lastKey);
+          continue;
+        }
+        const shape = shapes[property];
+        const where = `animation "${animName}" ${group} "${name}" ${property}`;
+        if (shape === undefined) {
+          note('blocker', `${group.toUpperCase()}_TIMELINE`, where, `timeline "${property}" is not in the motion spec`);
+          continue;
+        }
+        // The empty name is the physics group's timeline that names no
+        // constraint (issue #726), which the motion spec spells `"*"`. It
+        // writes every carried constraint declaring the property global —
+        // `reset` every one — and one that reaches none is a no-op the rebuild
+        // would be refused over by name, so it goes, and is said, instead.
+        if (group === 'physics' && name === '') {
+          const reaches =
+            property === 'reset' ? carriedPhysics.length > 0 : carriedPhysics.some((one) => Boolean(one[`${property}Global`]));
+          if (!reaches) {
+            let lastKey = 0;
+            for (const raw of keys) {
+              const t = obj(raw).time;
+              if (typeof t === 'number' && t > lastKey) lastKey = t;
+            }
+            unreached.push({ property, lastKey });
+            continue;
+          }
+          valueTrack({ physics: EVERY_GLOBAL_PHYSICS }, property, keys, shape, where);
+          continue;
+        }
+        valueTrack({ [group]: name }, property, keys, shape, where);
+      }
+    }
+  };
+
+  for (const [bone, timelines] of objEntries(anim.bones)) {
+    for (const [property, keys] of arrEntries(timelines)) {
+      const shape = BONE_TRACKS[property];
+      const where = `animation "${animName}" bone "${bone}" ${property}`;
+      if (property === INHERIT_TRACK.property) {
+        // `{ time, inherit }` -> `{ t, v: mode }`. The mode is carried in the
+        // table's spelling, which is what `build` writes back; a key that omits
+        // it, or spells it with a capital the runtime also folds, is a key the
+        // rebuild states differently and is counted as such. A spelling the
+        // runtime cannot resolve at all is carried as written — the file plays
+        // no mode there, and `build` refuses it by name rather than guessing one.
+        let restated = 0;
+        const out = keys.map((raw) => {
+          const key = obj(raw);
+          const entry: JsonObject = { t: timeOf(key) };
+          const written = key[INHERIT_TRACK.field];
+          const mode = written === undefined ? INHERIT_TRACK.dflt : resolveBoneInherit(written);
+          if (mode !== written && mode !== undefined) restated++;
+          entry.v = mode ?? (written as JsonObject[string]);
+          for (const field of Object.keys(key)) {
+            if (field === 'time' || field === INHERIT_TRACK.field) continue;
+            note('blocker', 'TIMELINE_FIELD', where, `key field "${field}" is not part of this timeline's shape`);
+          }
+          return entry;
+        });
+        if (restated > 0) {
+          note(
+            'lossy',
+            'TIMELINE_KEY_RESTATED',
+            where,
+            `${restated} key(s) omit the mode or spell it with a capital first letter, and are written out as the ` +
+              `mode the runtime reads there (an omitted one is ${INHERIT_TRACK.dflt}) — the same mode, in the ` +
+              'spelling the editor writes',
+          );
+        }
+        tracks.push({ bone, property, keys: out });
+        continue;
+      }
+      if (shape === undefined) {
+        note(
+          'blocker',
+          'BONE_TIMELINE',
+          where,
+          `timeline "${property}" has no track in the motion spec — a bone track is ${BONE_TRACK_NAMES.join(', ')} ` +
+            'and nothing else, so the rebuild plays nothing here',
+        );
+        continue;
+      }
+      valueTrack({ bone }, property, keys, shape, where);
+    }
+  }
+
+  for (const [slot, timelines] of objEntries(anim.slots)) {
+    for (const [property, keys] of arrEntries(timelines)) {
+      const where = `animation "${animName}" slot "${slot}" ${property}`;
+      if (property === 'attachment') {
+        // Inverts `compileTrack`'s attachment branch: `{time, name}`, where a
+        // null name is "show nothing". Attachment keys are stepped by nature and
+        // carry no curve at all.
+        tracks.push({
+          slot,
+          property: 'attachment',
+          keys: keys.map((raw) => {
+            const key = obj(raw);
+            return { t: timeOf(key), v: key.name === undefined ? null : key.name };
+          }),
+        });
+      } else if (property === 'rgba') {
+        // Inverts `compileTrack`'s rgba branch, whose key is `{time, color}`.
+        tracks.push({
+          slot,
+          property: 'rgba',
+          keys: keys.map((raw) => {
+            const key = obj(raw);
+            const entry: JsonObject = { t: timeOf(key), v: hexToRgba(String(key.color)) };
+            easing(key, entry);
+            return entry;
+          }),
+        });
+      } else if (property === 'rgba2') {
+        // Inverts `compileTrack`'s rgba2 branch, whose key is `{time, light,
+        // dark}`. The spec's `v` concatenates the two in the format's own
+        // channel order — light r g b a, then dark r g b — which is the order
+        // `readCurve` indexes a curve array by, so a key and its curve stay
+        // parallel through the round trip.
+        tracks.push({
+          slot,
+          property: 'rgba2',
+          keys: keys.map((raw) => {
+            const key = obj(raw);
+            const entry: JsonObject = {
+              t: timeOf(key),
+              v: [...hexToRgba(String(key.light)), ...hexToRgb(String(key.dark))],
+            };
+            easing(key, entry);
+            return entry;
+          }),
+        });
+      } else if (property === 'alpha') {
+        // Inverts `compileTrack`'s alpha branch, whose key is `{time, value}` —
+        // the one colour shape the format stores as a number, read by
+        // `readTimeline1` with a per-key default of **0**. That is a value
+        // track's shape exactly, so it goes through the same inversion and
+        // inherits its two findings: an omitted `value` is written out at 0 and
+        // reported as `TIMELINE_KEY_RESTATED`, and a field the shape has no
+        // place for is a `TIMELINE_FIELD` blocker (issue #730).
+        valueTrack({ slot }, property, keys, [['value', 0]], where);
+      } else if (property === 'rgb' || property === 'rgb2') {
+        // Inverts `compileTrack`'s other two separable shapes (issue #730):
+        // `rgb` is `{time, color: "rrggbb"}` and `rgb2` is `{time, light:
+        // "rrggbb", dark: "rrggbb"}`, and the spec's `v` is their channels in
+        // `readCurve`'s order. Each keeps its own name and its own key times:
+        // folding an `rgb` and an `alpha` into one `rgba` would state each
+        // channel at the other's key times, a value nobody keyed.
+        tracks.push({
+          slot,
+          property,
+          keys: keys.map((raw) => {
+            const key = obj(raw);
+            const v =
+              property === 'rgb'
+                ? hexToRgb(String(key.color))
+                : [...hexToRgb(String(key.light)), ...hexToRgb(String(key.dark))];
+            const entry: JsonObject = { t: timeOf(key), v };
+            easing(key, entry);
+            return entry;
+          }),
+        });
+      } else {
+        // 🔒 Composed from both tables, so it says the true thing whichever of
+        // two states it is reached in. A name the FORMAT has and the spec does
+        // not is the first; since issue #730 carried the last three there is no
+        // such name (`UNSPELT_SLOT_TRACKS` is empty), and what still reaches
+        // here is a name the format does not have at all — which
+        // `SkeletonJson.readAnimation` throws on (`Invalid timeline type for a
+        // slot`), so the sentence says so instead of printing an empty
+        // "remaining" list about a file no runtime loads.
+        const inFormat = property in CHANNELS_BY_KIND.slot;
+        note(
+          'blocker',
+          'SLOT_TIMELINE',
+          where,
+          (inFormat
+            ? `timeline "${property}" is in the format and the motion spec has no track for it`
+            : `timeline "${property}" is not a slot timeline the format has — the runtime's reader throws ` +
+              '"Invalid timeline type for a slot" on it, so no player loads this file') +
+            ` — a slot track is ${SLOT_TRACKS.join(' or ')} and nothing else, so the rebuild plays nothing here` +
+            (UNSPELT_SLOT_TRACKS.length > 0
+              ? `. The format's remaining slot timelines are ${UNSPELT_SLOT_TRACKS.join(', ')}`
+              : ''),
+        );
+      }
+    }
+  }
+
+  family('path', PATH_TRACKS);
+  family('physics', PHYSICS_TRACKS);
+  family('slider', SLIDER_TRACKS);
+
+  const ik = constraintGroup('ik', animName, anim, root, IK_KEY_DEFAULTS, seeT, note);
+  const transform = constraintGroup('transform', animName, anim, root, TRANSFORM_KEY_DEFAULTS, seeT, note);
+
+  // deform — `attachments.<skin>.<slot>.<attachment>.<timeline>`.
+  // Inverts `compileDeformTrack`, whose emitted key is `{time, offset?, vertices?}`
+  // and whose `offset` is omitted at 0 (the parser's default).
+  const deform: JsonObject[] = [];
+  // sequence — the other attachment timeline, inverting `compileSequenceTrack`:
+  // `{time, mode?, index?, delay?}` with each field written only where the file
+  // wrote it, because each has a parser default (`"hold"`, 0, the previous
+  // key's delay) and restating one would be a rebuild saying more than the file.
+  const sequence: JsonObject[] = [];
+  for (const [skinName, perSkin] of objEntries(anim.attachments)) {
+    for (const [slot, perSlot] of objEntries(perSkin)) {
+      for (const [attachment, timelines] of objEntries(perSlot)) {
+        for (const [property, keys] of arrEntries(timelines)) {
+          const where = `animation "${animName}" ${skinName}/${slot}/${attachment}`;
+          if (property === 'sequence') {
+            const entry: JsonObject = {
+              slot,
+              attachment,
+              keys: keys.map((raw) => {
+                const key = obj(raw);
+                const out: JsonObject = { t: timeOf(key) };
+                for (const field of ['mode', 'index', 'delay']) if (key[field] !== undefined) out[field] = key[field];
+                return out;
+              }),
+            };
+            if (skinName !== 'default') entry.skin = skinName;
+            sequence.push(entry);
+            continue;
+          }
+          if (property !== 'deform') {
+            // Reached only by a name OUTSIDE the format: `readAnimation` tests
+            // an attachment timeline for "deform" and "sequence" and reads
+            // nothing else (`SkeletonJson.js:1147-1201`), so no player plays it.
+            note(
+              'blocker',
+              'ATTACHMENT_TIMELINE',
+              where,
+              `timeline "${property}" is not an attachment timeline the format has — the runtime's reader tests for ` +
+                '"deform" and "sequence" and ignores anything else, and those two are what the motion spec carries',
+            );
+            continue;
+          }
+          const entry: JsonObject = {
+            slot,
+            attachment,
+            keys: keys.map((raw) => {
+              const key = obj(raw);
+              const out: JsonObject = { t: timeOf(key) };
+              if (key.offset !== undefined) out.offset = key.offset;
+              if (key.vertices !== undefined) out.vertices = key.vertices;
+              easing(key, out);
+              return out;
+            }),
+          };
+          // `skin` is absent for the default skin, which is the spec's own
+          // spelling (`MotionDeformTrack.skin`: absent = "default").
+          if (skinName !== 'default') entry.skin = skinName;
+          deform.push(entry);
+        }
+      }
+    }
+  }
+
+  // drawOrder — inverts `compileDrawOrder`. A key with no `offsets` restores the
+  // setup order; that is the parser's own encoding and the spec spells it the
+  // same way, so an absent array stays absent.
+  let drawOrder: JsonObject[] | undefined;
+  if (Array.isArray(anim.drawOrder)) {
+    drawOrder = anim.drawOrder.map((raw) => {
+      const key = obj(raw);
+      const out: JsonObject = { t: timeOf(key) };
+      if (Array.isArray(key.offsets)) {
+        out.offsets = key.offsets.map((o) => ({ slot: obj(o).slot, offset: obj(o).offset }));
+      }
+      return out;
+    });
+  }
+
+  // events — inverts `compileEvents`. The payload fields are written only where
+  // the firing overrides the declared event's own, which is what the file holds.
+  let events: JsonObject[] | undefined;
+  if (Array.isArray(anim.events)) {
+    events = anim.events.map((raw) => {
+      const key = obj(raw);
+      const out: JsonObject = { t: timeOf(key), name: key.name };
+      for (const field of ['int', 'float', 'string', 'volume', 'balance']) {
+        if (key[field] !== undefined) out[field] = key[field];
+      }
+      return out;
+    });
+  }
+
+  for (const { property, lastKey } of unreached) {
+    const flag = `${property}Global`;
+    note(
+      'lossy',
+      'PHYSICS_GLOBAL_REACHES_NOTHING',
+      `animation "${animName}" physics "" ${property}`,
+      'names no constraint, so the runtime writes it into every physics constraint ' +
+        (property === 'reset' ? 'the skeleton has' : `declaring "${flag}"`) +
+        ', and the rebuild carries ' +
+        (carriedPhysics.length === 0
+          ? 'no physics constraint'
+          : `none that does (${carriedPhysics.map((one) => `"${String(one.name)}"`).join(', ')})`) +
+        ` — it moves nothing, and \`build\` would refuse its \`"physics": "${EVERY_GLOBAL_PHYSICS}"\` track by name. ` +
+        'The motion spec omits it' +
+        (lastKey > maxT
+          ? `, and an animation's duration is the last key it has left, so the rebuilt animation ends at ${maxT}s rather than ${lastKey}s`
+          : '; the rebuild differs from the source by exactly this no-op'),
+    );
+  }
+
+  for (const group of Object.keys(anim)) {
+    if (ANIMATION_GROUPS.includes(group)) continue;
+    note(
+      'blocker',
+      'ANIMATION_GROUP',
+      `animation "${animName}"`,
+      `group "${group}" has no home in the motion spec — an animation group is ${ANIMATION_GROUPS.join(', ')} and ` +
+        'nothing else, so the rebuild carries nothing from it',
+    );
+  }
+
+  // 🚨 There is no duration in skeleton JSON. The largest key time is the only
+  // derivable answer and it is what a runtime plays to; it is WRONG for an
+  // animation that holds its last pose past its last key, and nothing in the
+  // file distinguishes the two. Recorded per animation rather than hidden.
+  note(
+    'judgement',
+    'DURATION',
+    `animation "${animName}"`,
+    `skeleton JSON carries no duration; the largest key time (${maxT}) is used, which is what a runtime plays to. ` +
+      'An animation meant to hold past its last key needs the real number stated by hand',
+  );
+
+  const out: JsonObject = { duration: maxT, tracks };
+  if (ik.length) out.ik = ik;
+  if (transform.length) out.transform = transform;
+  if (deform.length) out.deform = deform;
+  if (sequence.length) out.sequence = sequence;
+  if (drawOrder !== undefined) out.drawOrder = drawOrder;
+  if (events !== undefined) out.events = events;
+  return out;
+}
+
+/**
+ * `ik` / `transform` — one unnamed timeline per constraint.
+ *
+ * Inverts `compileConstraintTrack`, and this is the one inversion that has to
+ * RESTATE rather than copy. Two reasons, and neither invents a value:
+ *
+ * 1. **The uniform field set.** Every field of these keys is optional with a
+ *    per-key default, so `compileConstraintTrack` refuses a track whose keys do
+ *    not all name the same fields — *"state it on every key or on none"*. An
+ *    export does not obey that: it omits a field wherever it equals the default.
+ *    So a field ANY key states is written on EVERY key, at the value the parser
+ *    would have read there. Identical semantics — and, since issue #716, the
+ *    same file wherever `PARSER_DEFAULTS` has the key's row, because the
+ *    emitter leaves each such value out again. What is still reported is a
+ *    value the emitter writes back.
+ * 2. 🚨 **`rigFlags`.** `compileConstraintTrack` stamps the rig constraint's
+ *    non-default `bendPositive`/`compress`/`stretch` onto a key that omits one
+ *    (issue #273). On rigc's own output that is self-consistent — rigc already
+ *    wrote the flag on every key, so it is read back as stated. On a FOREIGN
+ *    export it would change what plays: the export's omission means the per-key
+ *    default, and the stamp would substitute the constraint's setup value. So a
+ *    flag the constraint declares non-default is written on every key at the
+ *    PARSER default, which is what the export actually plays.
+ */
+function constraintGroup(
+  group: 'ik' | 'transform',
+  animName: string,
+  anim: JsonObject,
+  root: JsonObject,
+  defaults: Record<string, number | boolean | string>,
+  seeT: (t: number) => void,
+  note: Note,
+): JsonObject[] {
+  const fields = Object.keys(defaults);
+  const out: JsonObject[] = [];
+  for (const [name, keys] of arrEntries(anim[group])) {
+    const where = `animation "${animName}" ${group} "${name}"`;
+    const stated = new Set<string>();
+    for (const raw of keys) {
+      const key = obj(raw);
+      for (const field of fields) if (key[field] !== undefined) stated.add(field);
+    }
+    if (group === 'ik') {
+      const constraint = arr(root.constraints)
+        .map(obj)
+        .find((c) => nameOf(c) === name && c.type === 'ik');
+      for (const flag of IK_FLAGS) {
+        if (constraint !== undefined && constraint[flag] !== undefined && constraint[flag] !== IK_KEY_DEFAULTS[flag]) {
+          stated.add(flag);
+        }
+      }
+    }
+    // A field filled on a key the source left it off is said only where the
+    // emitter will write it: where `PARSER_DEFAULTS`' row for the key would
+    // leave it out again, the rebuild is the source's own text (issue #716).
+    const row = PARSER_DEFAULTS[`${group} key`];
+    let restated = 0;
+    const ks = keys.map((raw) => {
+      const key = obj(raw);
+      const entry: JsonObject = { t: typeof key.time === 'number' ? key.time : 0 };
+      seeT(entry.t as number);
+      const filled: string[] = [];
+      for (const field of fields) {
+        if (!stated.has(field)) continue;
+        if (key[field] !== undefined) entry[field] = key[field];
+        else {
+          const dflt = defaults[field];
+          // `mixY`'s default is the same key's own `mixX`, spelled as that field
+          // name in the table above.
+          entry[field] = typeof dflt === 'string' ? (key[dflt] !== undefined ? key[dflt] : defaults[dflt]) : dflt;
+          filled.push(field);
+        }
+      }
+      if (filled.length > 0) {
+        const emitted: JsonObject = { ...key };
+        for (const field of fields) if (entry[field] !== undefined) emitted[field] = entry[field];
+        const site = { object: emitted, previous: () => null };
+        restated += filled.filter((field) => row === undefined || !parserOmits(row, site, field)).length;
+      }
+      if (key.curve === 'stepped') entry.ease = 'stepped';
+      else if (key.curve !== undefined) entry.curve = key.curve;
+      for (const field of Object.keys(key)) {
+        if (field === 'time' || field === 'curve' || fields.includes(field)) continue;
+        note('blocker', `${group.toUpperCase()}_KEY_FIELD`, where, `key field "${field}" is not part of this timeline's shape`);
+      }
+      return entry;
+    });
+    if (restated > 0) {
+      note(
+        'lossy',
+        'CONSTRAINT_KEY_RESTATED',
+        where,
+        `${restated} value(s) the source omits are restated at the parser's default, because the motion spec ` +
+          'requires one field set per track and the emitter writes them back — the same values the runtime reads, ' +
+          'spelled out',
+      );
+    }
+    out.push({ constraint: name, keys: ks });
+  }
+  return out;
+}
+
+/**
+ * The provenance sentence both specs carry (INGEST §2.4's rule).
+ *
+ * ⚠️ A decompiled spec is indistinguishable from an authored one by inspection,
+ * and every gate in this tree will call it green — because it IS green. No gate
+ * catches a missing note, which is exactly why `ingest` writes one itself rather
+ * than leaving it to the caller.
+ *
+ * 🔒 No timestamp, and that is a contract rather than a style: `A18` compares two
+ * independent compiles byte for byte, and a dated note in a spec would break the
+ * first rebuild from it.
+ */
+function provenanceNote(opts: IngestOptions, which: 'rig' | 'motion', consumerDriven = false): string {
+  const head =
+    `DECOMPILED from ${opts.source} by \`rigc ingest\` ${opts.version}. Every number here was read out of that ` +
+    'skeleton; nothing was authored, so this file says what the object IS and nothing about why.';
+  if (which === 'rig') {
+    // Only where the declaration was written, so every other decompiled rig spec
+    // keeps its note byte for byte.
+    if (consumerDriven) {
+      return (
+        `${head} \`invariants\` holds only \`consumerDrivenMix\`, the constraints this run read as mixes the ` +
+        'consumer sets (each is a CONSUMER_DRIVEN_MIX finding); it turns a refusal into a SKIP and certifies ' +
+        'nothing. A skeleton declares no other invariant, and an assertion with nothing to measure must SKIP ' +
+        'rather than pass.'
+      );
+    }
+    return (
+      `${head} \`invariants\` is deliberately absent — a skeleton declares none, and an assertion with nothing to ` +
+      'measure must SKIP rather than pass.'
+    );
+  }
+  return (
+    `${head} Every curve is a raw \`curve\` array — the absolute (time, value) control points verbatim — because an ` +
+    'export carries a different bezier per key per channel and no named easing can say that. Each `duration` is the ' +
+    'largest key time in its animation, which is the only figure skeleton JSON supports.'
+  );
+}