spine-rigc 0.25.0 → 0.25.2

package/README.md

@@ -503,7 +503,7 @@ commands take it and what its default is.
 | `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
-| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. `--stage x,y,w,h` supplies the stage for a skeleton that declares none, and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
+| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. `--stage x,y,w,h` supplies the stage for a skeleton that declares none — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/` |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
@@ -539,7 +539,7 @@ rebuild it. It is the only command that runs against `build`'s direction, and th
 only one whose contract is an equality rather than a rulebook:
 
 ```bash
-rigc ingest hero.json --out specs/ --stage 0,0,1024,768 --images parts/
+rigc ingest hero.json --out specs/ --images parts/
 rigc build --rig specs/rig.json --motion specs/motion.json --out build/
 rigc diff build/skeleton.json hero.json
 ```
@@ -580,7 +580,10 @@ One thing it drops on purpose and says so: a path attachment's `lengths`, which
 - **The stage.** `skeleton.width`/`height`: rigc always writes one, and a skeleton that
   carries none is refused by name unless `--stage x,y,w,h` supplies it. It is not
   derivable — posing the rig gives the *animated* extent, which is a different number
-  from the setup box. ⚠️ This said *"an editor export carries none"* until #594 measured
+  from the setup box. ⛔ **And `--stage` beside a box the file already states is refused
+  too**, for the opposite reason: two sources for one value, where the file is the record
+  of what was measured. It used to be read after the box and therefore never
+  ([#626](https://github.com/firejune/rigc/issues/626)). ⚠️ This said *"an editor export carries none"* until #594 measured
   it: **all twelve exports in the example corpus carry a stage** and none of them needs
   the flag. It is still the value that costs least to get wrong, because `diff` reports
   the box and gates nothing on it.

package/cli.ts

@@ -67,7 +67,7 @@ import {
   type DeformSpan,
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
-import { ingest, type IngestFindingKind, type IngestStage } from './src/ingest.ts';
+import { ingest, IngestError, type IngestFindingKind, type IngestStage } from './src/ingest.ts';
 import { copyAtlasImages } from './src/emit.ts';
 import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
@@ -2965,7 +2965,9 @@ const FLAG_MEANINGS: Record<string, string> = {
     'derived: posing the rig gives the ANIMATED extent, which is a different number from the setup box, so this ' +
     "is the caller's value, and without it the missing stage is reported as a blocker. ⚠️ An editor export MAY " +
     'carry none; every editor export measured for this project carries one and ingest reads it straight through, ' +
-    'so the flag is for a file that really has none rather than for editor exports as a class',
+    'so the flag is for a file that really has none rather than for editor exports as a class. ⛔ Beside a ' +
+    'skeleton that already declares a box it is REFUSED rather than ignored: two sources for one value, and the ' +
+    'file is the record of what was measured',
   help: "show this command's flags and exit",
 };
 
@@ -3310,11 +3312,12 @@ const USAGE = [
   'ingest runs build backwards: it reads a Spine 4.3 skeleton.json and writes the rig',
   'spec and motion spec that rebuild it, so an existing skeleton becomes a starting',
   'point instead of something to retype:',
-  '  rigc ingest hero.json --out specs/ --stage 0,0,1024,768   rig.json + motion.json',
+  '  rigc ingest hero.json --out specs/ --images parts/         rig.json + motion.json',
   'The contract is an equality, not a rulebook: build(ingest(x)) is x, byte for byte.',
   'It reads the skeleton and nothing else — no .spine project, no binary .skel, no',
   'atlas — so two things are the caller\'s and are refused rather than guessed: the',
-  'setup stage (--stage, only when the skeleton itself declares none) and how the spec',
+  'setup stage (--stage, only when the skeleton itself declares none — beside a box the',
+  'file states, the flag is refused rather than ignored) and how the spec',
   'reaches the art (--art). --images <dir> is the third and the only optional one: it',
   'WRITES the rig spec\'s own images directory, relative to --out, so the rebuild needs',
   'no flag.',
@@ -3431,5 +3434,15 @@ try {
     console.error(`rigc chainfit: ${err.message}`);
     process.exit(2);
   }
+  // A usage error in kind — an option that contradicts the file it was given —
+  // and exit 2 for that reason rather than 1: nothing was compiled and nothing
+  // was written, so it is the invocation that has to change (issue #626). It is
+  // raised in `src/ingest.ts` rather than here because the library caller who
+  // passes the same contradiction deserves the same refusal, and one rule in one
+  // place is what stops the two from drifting apart.
+  if (err instanceof IngestError) {
+    console.error(`rigc ingest: ${err.message}`);
+    process.exit(2);
+  }
   throw err;
 }

package/docs/AUTHORING.md

@@ -362,7 +362,7 @@ Everything above starts from two spec files you wrote. `rigc ingest` starts from
 an existing rig is a starting point instead of 250 KB of arrays to retype.
 
 ```bash
-bun cli.ts ingest hero.json --out specs/ --stage 0,0,1024,768 --images parts/
+bun cli.ts ingest hero.json --out specs/ --images parts/
 #   ..    out  /abs/path/specs
 #   ..    art  loose
 #   ..    images ../parts/  (the rig spec's own, from /abs/path/specs)
@@ -397,7 +397,7 @@ repository builds on every run.
 | `--art loose` (default) | name an `image` per attachment — `<path or placeholder>.png` — so the rebuild resolves loose PNGs and rigc measures them |
 | `--art none` | state `width`/`height` only, so the rebuild is `build --atlas-in <pack.atlas>` and every part resolves out of the pack |
 | `--images <dir>` | **write** the rig spec's own `images` directory, spelled relative to `--out`, so the rebuild is a plain `build --rig … --motion … --out …`. Without it the field is left out and every `image` resolves against `--out` itself, which holds the specs and no art — so every rebuild has to repeat `build --images <dir>`. Refused together with `--art none`, which writes no `image` for it to be the base of |
-| `--stage x,y,w,h` | the setup bounding box, **for a skeleton that declares none**. An editor export *may* be one; every export under `examples/` carries a box and `ingest` reads it straight through |
+| `--stage x,y,w,h` | the setup bounding box, **for a skeleton that declares none**. An editor export *may* be one; every export under `examples/` carries a box and `ingest` reads it straight through — so passing the flag at one of them is **refused**, naming both boxes, rather than silently doing nothing ([#626](https://github.com/firejune/rigc/issues/626)) |
 | `--name <n>` | the rig spec's `name`, which the motion spec's `archetype` must equal (default: the file's basename) |
 
 ⚠️ **`ingest --images` and `build --images` point opposite ways.** `build --images`
@@ -414,6 +414,16 @@ editor's setup box. So a file that declares none is a **blocker**, named, unless
 `--stage x,y,w,h` supplies it; supply it from the project the file came from, or from
 the editor's own canvas.
 
+⛔ **The flag is refused beside a box the file states.** Two sources for one value, and
+the file is the one that was measured — so `ingest` names both boxes and stops rather
+than writing one of them and saying nothing. Drop the flag, or correct `skeleton` in the
+source if its box is wrong ([#626](https://github.com/firejune/rigc/issues/626)). What
+it does **not** do is refuse an *omitted origin*: inside a declared extent an omitted
+`x`/`y` is `0` — the reading `build` emits and `diff` compares
+([#620](https://github.com/firejune/rigc/issues/620)) — so the written spec states it
+and a `LOSS HEADER_ORIGIN` line says the source omitted it and that the rebuild will
+spell it ([#622](https://github.com/firejune/rigc/issues/622)).
+
 ⚠️ **This said an editor export "never" carries one until
 [#594](https://github.com/firejune/rigc/issues/594) measured the corpus.** All twelve
 exports under `examples/` declare `x`, `y`, `width` and `height`, `ingest` takes the
@@ -443,7 +453,7 @@ the first:
 | --- | --- |
 | `BLOCK` | the spec format cannot say it, so the rebuild will **not** be the file that was read — `linkedmesh`, `point`, an attachment `sequence`, an unknown field on a bone, slot or constraint, a timeline family the motion spec has no track for. The command exits non-zero **and still writes both specs**, because a spec plus a list of what is missing from it beats no spec |
 | `JUDGE` | the skeleton cannot answer and somebody has to: the stage, and each animation's duration |
-| `LOSS` | the skeleton says it and rigc re-derives it, on purpose. A path attachment's `lengths` is the one that matters — it is `PathConstraint`'s own four-sample measurement rather than an arc length (#560), so a transcribed one would freeze whatever produced the source |
+| `LOSS` | the skeleton's spelling and rigc's differ, on purpose, and the line says how. A path attachment's `lengths` is the one that matters — it is `PathConstraint`'s own four-sample measurement rather than an arc length (#560), so a transcribed one would freeze whatever produced the source. The header ones are cheaper: `HEADER_BOOKKEEPING` for a field the spec has no home for, `HEADER_REDERIVED` for the version string, `HEADER_ORIGIN` for an origin the source left to the format and the rebuild writes out (#622) |
 
 📝 **Do not delete the `note`.** Both written specs carry one saying the file is
 decompiled and naming the skeleton it came from. A decompiled spec is
@@ -1982,6 +1992,20 @@ one wins today. ⛔ rigc does **not** set the flag for you. The compiler never
 invents a value that is not in the spec, and a rig whose composition was chosen by
 the tool is one nobody can reason about.
 
+⚠️ **And below full authority it is a weighting rather than a quieter erasure**
+([#399](https://github.com/firejune/rigc/issues/399)). An additive slider scales
+its whole contribution by its own `mix`, so two of them at any pair of mixes are
+still the sum — which is why `A40` skipping below full authority is right: what
+happens there is a weighting, not the erasure it refuses. A **non-additive**
+slider at `mix` α applies `current + (value + setup − current) × α`, a lerp *from
+the pose it found*, so the earlier slider is not erased — it is attenuated by
+`1 − α`. `mix × contribution` is not the arithmetic there, so a later dial turned
+part of the way down takes that share of every earlier slider on the target with
+it, on every frame, with the gate green — the second reason to write
+`"additive": true` on **every** slider that shares a target and not only on the
+later one. `PS130` in `selftest.ts` poses both models rather than quoting the
+runtime, and [`docs/FACE.md`](FACE.md) §8 is the same rule on a face's two axes.
+
 ⚠️ **And `"additive": true` is not always available.** Only some timelines support
 additive application at all: bone, deform, transform-constraint, path `position`,
 physics `wind`/`gravity`, and a slider's own `mix`. A **slot colour, an attachment

package/docs/FACE.md

@@ -1180,6 +1180,31 @@ breaks the moment the two share a target — in the worked example both `turn` a
 `tilt` key `headroll`. §7's paragraph on sliders is the mechanism and
 `A40_SLIDERS_COMPOSE_ON_A_SHARED_TARGET` is the refusal.
 
+✅ **And the space between the two dials is measured rather than inferred**
+([#399](https://github.com/firejune/rigc/issues/399)). Two additive sliders posed
+at a grid of *both* values — and over a rotation and a translation, so the claim
+is not one property's — are the closed-form sum at every cell of it, to float64:
+each slider maps its own reading to a time by §3.5.2's rule, its animation is read
+there, and the two contributions add. ⭐ That is a property of the **interior**
+and not of the corners, which is the whole reason it needed a grid: `PS129` drives
+the same comparison with an `ease` on one of the two animations, and every corner
+of the space still reads as correct while most of the inside has moved. ⇒ **a
+lookup table wants linear keys for a second reason** — not only that the face
+would drift while the value sat still, but that a curve is invisible to any check
+that reads an axis at its ends.
+
+⚠️ **And `mix` below 1 is not what it looks like when the later slider is not
+additive.** An additive slider scales its whole contribution by its own `mix`, so
+two of them at any pair of mixes are still the sum — which is why `A40` skipping
+below full authority is right: what happens there is a weighting, not the erasure
+it refuses. A **non-additive** slider at `mix` α applies
+`current + (value + setup − current) × α`, a lerp *from the pose it found*, so the
+earlier slider is not erased — it is attenuated by `1 − α`. A pitch dial turned
+halfway down takes that share of the yaw with it, on every frame, with the gate
+green. ⇒ write `"additive": true` on **every** slider that shares a target and
+not only on the later one, which is what the paragraph above already asks for and
+this is the second reason for.
+
 ✅ **The editor half, measured.** This paragraph said *unknown* until the round
 trip was taken with `tools/editor_roundtrip.ts` on a licensed editor (data
 version 4.3.26) against a 4.3.13 build of
@@ -1403,6 +1428,15 @@ shift through the vertex's coordinate instead of its index, so the next
 renumbering cannot move it. A `vertices` run is positional by format — that is
 `fromVertex`'s whole job — and a *generator* of one has no reason to be.
 
+🔒 **And that repair is now measured rather than asserted.** `bun run selftest`
+runs this script again against a rig whose vertices have been renumbered every
+way the compiler accepts — the outline rotated along its own walk, the outline
+reflected, the interior reordered — and requires the run it writes to come back
+as the same geometry once the renumbering is undone, while the run's own
+positions have visibly moved. Nothing here declares that property: the subject
+is any script on any page whose product is a `vertices` run, read off the
+product.
+
 **What comes back from both:**
 
 | | good | (a) one band inverted | (b) mesh folded |

package/docs/INGEST.md

@@ -467,8 +467,10 @@ resolved rather than guessed, for §0.2's reason: `spineboy/export` holds two, a
 
 **What it will not do is invent.** Everything the spec format cannot hold is a
 finding with a code — `BLOCK` for a construct the rebuild will be missing, `JUDGE`
-for the two values a skeleton does not carry, `LOSS` for the one number rigc
-re-derives on purpose. A blocker exits non-zero and still writes both files.
+for the two values a skeleton does not carry, `LOSS` wherever the source's spelling and
+rigc's differ on purpose (a number rigc re-derives, a field the spec has no home for, or
+a default the source left to the format and the rebuild writes out). A blocker exits
+non-zero and still writes both files.
 
 **Two values are not in a skeleton**, so `ingest` asks rather than guesses:
 
@@ -483,7 +485,11 @@ re-derives on purpose. A blocker exits non-zero and still writes both files.
   reports it as two measures of its own (`stage_present`, `stage_box`, since
   [#578](https://github.com/firejune/rigc/issues/578)) and they are `(reported)`, so
   nothing on the ladder reads them and an absurd box is green nearly everywhere. The
-  corpus half of the selftest's `IG` suite is the one gate that does read them;
+  corpus half of the selftest's `IG` suite is the one gate that does read them. ⛔ **The
+  flag is refused beside a box the file states** — two sources for one value, both named,
+  and the file is the record of what was measured
+  ([#626](https://github.com/firejune/rigc/issues/626)). It used to be read only *after*
+  the file's box, so `--stage` at any of the twelve did nothing and said nothing;
 - **each animation's duration** — the format has no such field. The largest key time
   is used, stated in the motion spec's `note`, and recorded as a finding per
   animation. Edit it if you know the real number.
@@ -620,7 +626,7 @@ rebuild against its source produces differences of exactly three kinds, in every
 | Kind | Example, candidate vs reference | Why |
 | --- | --- | --- |
 | **header bookkeeping**, 3 per file | `skeleton.hash: undefined vs "VFWbaK2UoCM"`, `skeleton.audio: undefined vs null`, `skeleton.spine: "4.3.13" vs "4.3.75-beta"` | the rig spec has no field for `hash` or `audio`, and the version is the runtime rigc links. `ingest` reports all three as findings — `HEADER_BOOKKEEPING` and `HEADER_REDERIVED` |
-| **an omitted default written out** | `…rotate[0].time: 0 vs undefined` | the editor omits a zero `time`; rigc writes it. AUTHORING §10.5's *do not imitate the exporter's omissions*, from the other side |
+| **an omitted default written out** | `…rotate[0].time: 0 vs undefined` | the editor omits a zero `time`; rigc writes it. AUTHORING §10.5's *do not imitate the exporter's omissions*, from the other side. The header has one of these too and it is the one `ingest` now names: a stage at the origin is written `width`/`height` with no `x`/`y`, and the rebuild spells both — `LOSS HEADER_ORIGIN`, with the box unchanged ([#622](https://github.com/firejune/rigc/issues/622)). No file in this corpus takes that branch: all twelve declare an origin away from 0 |
 | **the emitted precision** | `…curve[0]: 0.066667 vs 0.06666667`, `uvs[0]: 0 vs 2.554152e-7` | rigc emits six decimals |
 
 ⇒ **So the corpus gate is `diff` at 1.000 rather than a byte comparison**, and it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "Rig compiler for Spine — declarative rig specs in, Spine 4.3 skeleton data out, verified by a spine-core round-trip. Built so AI agents can author rigs and check their own work; the output imports into the Spine editor.",
   "type": "module",
   "bin": {

package/skills/ingest/SKILL.md

@@ -29,14 +29,15 @@ not do for you.
 ## Start here: `rigc ingest`
 
 ```bash
-rigc ingest hero.json --out specs/ --stage 0,0,1024,768
+rigc ingest hero.json --out specs/
 rigc build --rig specs/rig.json --motion specs/motion.json --images parts/ --out build/
 ```
 
 It reads the skeleton — **only** the skeleton — and writes the rig spec and motion
 spec that rebuild it, byte for byte. Two values it refuses rather than guessing: the
 **stage** (`--stage`, for a skeleton that declares none — an editor export *may* be
-one, though every one in the example corpus carries a box) and each animation's
+one, though every one in the example corpus carries a box, and passing the flag at a
+file that declares a box is refused rather than ignored) and each animation's
 **duration** (the largest key time, recorded as a finding).
 Read `findings.json`: a `BLOCK` line means the rebuild will be missing something and
 the command exits non-zero. Keep the `note` both specs carry. INGEST §2.0.

package/src/ingest.ts

@@ -26,7 +26,8 @@
  * log. Exactly two values are not in a skeleton at all (the stage and an
  * animation's duration) and both are `judgement` findings; every construct the
  * spec format cannot hold is a `blocker`; everything rigc re-derives rather than
- * carries is `lossy`.
+ * 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
  *
@@ -48,6 +49,24 @@ import { MOTION_SPEC_VERSION, parseMotionSpec } from './motion.ts';
 import { parseRigSpec, 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';
+  }
+}
+
 // ---------------------------------------------------------------------------
 // findings
 // ---------------------------------------------------------------------------
@@ -59,8 +78,12 @@ import type { MotionSpec } from './types.ts';
  *   NOT be the one that was read. Non-zero exit.
  * - `judgement` — the skeleton does not carry it and somebody has to decide.
  *   There are exactly two: the stage, and an animation's duration.
- * - `lossy` — the skeleton carries it and rigc re-derives it rather than taking
- *   it, which is correct and is said out loud (`lengths`, the `spine` version).
+ * - `lossy` — the skeleton's spelling and rigc's differ, on purpose, and the
+ *   difference is named: a value rigc re-derives rather than takes (`lengths`,
+ *   the `spine` version), a field the spec has no home for (`hash`, `audio`), 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';
 
@@ -112,7 +135,17 @@ export interface IngestOptions {
    * `cli.ts` refuses that pair rather than writing a field nothing reads.
    */
   images?: string;
-  /** Supplied stage. Used ONLY when the skeleton carries no width/height. */
+  /**
+   * 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 source file's basename, for the provenance note. No path: no leak. */
   source: string;
@@ -573,6 +606,32 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
 
 type Note = (kind: IngestFindingKind, code: string, where: string, detail: string) => void;
 
+/**
+ * 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 `skeleton` block — and the one judgement in this module.
  *
@@ -585,16 +644,35 @@ type Note = (kind: IngestFindingKind, code: string, where: string, detail: strin
  *
  * ⚠️ This said an editor export's `skeleton` block is `hash`, `spine`, `images`,
  * `audio` **and no box at all** until issue #594 measured the corpus: all twelve
- * exports under `examples/` carry `x`/`y`/`width`/`height`, and the early return
- * below is the branch they take. The blocker is for a file that really has none,
- * and this module has no example of one.
+ * exports under `examples/` carry `x`/`y`/`width`/`height`, and the declared-stage
+ * branch below is the one they take. The blocker is for a file that really has
+ * none, and this module has no example of one.
  *
  * ⭐ It is still the judgement that costs least to get wrong. `diff` does report
  * the box — `stage_present` and `stage_box`, since issue #578 — but they sit in
  * the `(reported)` block that no rung consults, so a deliberately absurd unit box
  * is green everywhere a candidate is scored.
+ *
+ * 🔇 **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(head: JsonObject, opts: IngestOptions, note: Note): JsonObject {
+  // 🚨 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 RIG_KEYS.RigSkeletonHeader) if (head[field] !== undefined) out[field] = head[field];
   for (const key of Object.keys(head)) {
@@ -621,7 +699,33 @@ function ingestHeader(head: JsonObject, opts: IngestOptions, note: Note): JsonOb
       `the editor writes "${key}" and the rig spec has no field for it; it is dropped and nothing reads it back`,
     );
   }
-  if (out.width !== undefined && out.height !== undefined) return out;
+  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 what `compile` emits and what `diff` compares (#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 rebuild WILL spell ${omitted.length > 1 ? 'those fields' : 'that field'}: same box, different bytes`,
+      );
+    }
+    return out;
+  }
   if (opts.stage === undefined) {
     note(
       'blocker',