rig-parts 2.2.0 → 2.4.0

package/src/editreceipt.ts

@@ -0,0 +1,194 @@
+/**
+ * Editor receipts (issue #946): the author's record that an image this build
+ * reads was edited in an image editor, held to the bytes on disk.
+ *
+ * What the package can know was edited is what the input itself says was made
+ * outside See-through, never a guess from pixels: an author-made layer
+ * (`author:<label>`, issue #256), a hidden-art layer (`<layer>:hidden`, issue
+ * #359), a cut's `under` image (issue #170) and a limb segment's `cap` image
+ * (issue #349). Each of those images IS an edited image by the input's own
+ * declaration. A See-through layer or the painting overwritten in place by a
+ * script carries no such mark, so nothing here can find it; an author may
+ * still receipt it, and the receipt is then verified like any other.
+ *
+ * A receipt is `{file, sha256, from_sha256, editor}`:
+ *
+ * - `file` and `sha256` are VERIFIED: the file, relative to the config's
+ *   directory, must exist and its bytes must hash to `sha256`
+ *   (`ASSEMBLE_EDITOR_RECEIPT_FILE`, `ASSEMBLE_EDITOR_RECEIPT_SHA256`).
+ * - `from_sha256` (the bytes the edit started from) and `editor` (the editor
+ *   the author names) are DECLARATIONS. The loader holds them to presence and
+ *   form, and `from_sha256` to differ from `sha256` (an edit that left the
+ *   bytes unchanged is not an edit, `CONFIG_EDITOR_RECEIPT`). That a person
+ *   used that editor is not something a file can show, and nothing here
+ *   claims to check it.
+ *
+ * With `required: true` every edited image the build reads — of the base
+ * runs, of each alternate set's runs, every cut `under` and limb `cap` — must
+ * carry a receipt whose `sha256` is that image's file
+ * (`ASSEMBLE_EDITOR_RECEIPT_MISSING`). An image is matched to its receipt by
+ * content, not by path, so the two layouts a wrapper run may hold a layer in
+ * (`<filename>` and `parts/<name>.png`, byte-identical by `LAYERS_PNG_UNAMBIGUOUS`)
+ * resolve to one receipt. A PSD layer's file is the PSD. Absent `required`,
+ * receipts that are declared are verified and nothing is demanded; absent the
+ * block, no file is read and no byte of any output moves.
+ *
+ * Pure: reads files, hashes with `node:crypto`; no clock, no network.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import type { Problem } from './errors.ts';
+import type { LayerSet } from './layers.ts';
+
+/** One receipt, as `config.assemble.editor_receipts.receipts[i]` holds it. */
+export interface EditorReceipt {
+  /** The edited image, relative to the config's directory. */
+  file: string;
+  /** sha256 of the edited file's bytes, 64 lowercase hex digits; verified. */
+  sha256: string;
+  /** sha256 of the bytes the edit started from; declared, held to form and to differ from `sha256`. */
+  from_sha256: string;
+  /** The editor the author names; declared. */
+  editor: string;
+}
+
+/** `config.assemble.editor_receipts`. */
+export interface EditorReceipts {
+  /** `true`: every edited image the build reads needs a receipt. Absent or `false`: receipts are verified, none is demanded. */
+  required?: boolean;
+  /**
+   * Issue #947, `true`: every part's pixels trace to a layer of the split or to
+   * an image a receipt covers — every edited image needs a receipt, as under
+   * `required`, and a shape drawn in the config through a part's pixels is
+   * refused (`src/partsource.ts`). Absent or `false`: nothing more is demanded.
+   */
+  trace_parts?: boolean;
+  receipts: EditorReceipt[];
+}
+
+/** What a sha256 field must be, as a refusal quotes it. */
+export const SHA256_RULE = '64 lowercase hex digits (a sha256 of the file\'s bytes)';
+export const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+
+const AT = 'config.assemble.editor_receipts';
+
+/** sha256 of a file's bytes, lowercase hex. */
+export function fileSha256(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+/** A receipt that verified against its file, with where it was declared. */
+export interface VerifiedReceipt extends EditorReceipt {
+  /** `config.assemble.editor_receipts.receipts[i]`. */
+  at: string;
+  /** The file, resolved against the config's directory. */
+  path: string;
+}
+
+/** The receipts read for one build: those that verified, keyed by sha256, and the refusals of those that did not. */
+export interface ReceiptLedger {
+  required: boolean;
+  /** The field that made receipts required, as a refusal names it: `required`, else `trace_parts` (issue #947). */
+  by: 'required' | 'trace_parts';
+  bySha: ReadonlyMap<string, VerifiedReceipt>;
+  problems: Problem[];
+}
+
+/**
+ * Verify every declared receipt against its file. `spec` has passed the
+ * config loader (shape, hex form, `from_sha256` unlike `sha256`, unique
+ * `file`). A missing file is `ASSEMBLE_EDITOR_RECEIPT_FILE`; bytes that hash
+ * to another value are `ASSEMBLE_EDITOR_RECEIPT_SHA256`, naming both values.
+ */
+export function readEditorReceipts(spec: EditorReceipts | undefined, configPath: string): ReceiptLedger {
+  const problems: Problem[] = [];
+  const bySha = new Map<string, VerifiedReceipt>();
+  if (spec === undefined) return { required: false, by: 'required', bySha, problems };
+  const base = dirname(resolve(configPath));
+  spec.receipts.forEach((r, i) => {
+    const at = `${AT}.receipts[${i}]`;
+    const path = resolve(base, r.file);
+    const object = `${at} (file "${r.file}")`;
+    if (!existsSync(path) || !statSync(path).isFile()) {
+      problems.push({ code: 'ASSEMBLE_EDITOR_RECEIPT_FILE', object, detail: `names ${path}, which is no such file; the edited image, its path relative to the config's directory, is required` });
+      return;
+    }
+    const found = fileSha256(path);
+    if (found !== r.sha256) {
+      problems.push({ code: 'ASSEMBLE_EDITOR_RECEIPT_SHA256', object, detail: `the file's bytes hash to sha256 ${found}; the receipt's sha256 ${r.sha256} is required — the file changed after its receipt was written, or the receipt names another file` });
+      return;
+    }
+    if (!bySha.has(found)) bySha.set(found, { ...r, at, path });
+  });
+  const by = spec.required === true || spec.trace_parts !== true ? 'required' : 'trace_parts';
+  return { required: spec.required === true || spec.trace_parts === true, by, bySha, problems };
+}
+
+/** An image the input itself says was made or edited outside See-through. */
+export interface EditedImage {
+  /** How the input names it: `full:author:hand`, `config.assemble.cuts[0].under (part "x")`. */
+  object: string;
+  /** The file its pixels are read from. */
+  path: string;
+}
+
+/**
+ * The edited images of a pair of runs: every author-made layer and every
+ * hidden-art layer, named `<run>:<layer>` as `parts.json`'s `from` names a
+ * layer, after `label`. With one run (`single`) the head run is the full run
+ * and is listed once. A PSD layer has no file of its own; its file is the PSD.
+ */
+export function editedRunImages(runs: { full: LayerSet; head: LayerSet; single: boolean }, label = ''): EditedImage[] {
+  const out: EditedImage[] = [];
+  for (const run of runs.single ? (['full'] as const) : (['full', 'head'] as const)) {
+    const set = runs[run];
+    for (const l of set.layers) if (l.tag.group === 'author') out.push({ object: `${label}${run}:${l.name}`, path: resolve(l.file ?? set.source) });
+    for (const h of set.hidden) out.push({ object: `${label}${run}:${h.name}`, path: resolve(h.file ?? set.source) });
+  }
+  return out;
+}
+
+/** The images a config names by path that the author painted: every cut's `under` and every limb segment's `cap`. */
+export function editedConfigImages(configPath: string, cuts: ReadonlyArray<{ into: string; under?: string }>, limbs: Readonly<Record<string, { segments: ReadonlyArray<{ part: string; cap?: string }> }>> | undefined, cutsAt = 'config.assemble.cuts'): EditedImage[] {
+  const base = dirname(resolve(configPath));
+  const out: EditedImage[] = [];
+  cuts.forEach((q, i) => {
+    if (q.under !== undefined) out.push({ object: `${cutsAt}[${i}].under (part "${q.into}")`, path: resolve(base, q.under) });
+  });
+  for (const [l, limb] of Object.entries(limbs ?? {})) {
+    limb.segments.forEach((sg, k) => {
+      if (sg.cap !== undefined) out.push({ object: `config.limbs.${l}.segments[${k}].cap (part "${sg.part}")`, path: resolve(base, sg.cap) });
+    });
+  }
+  return out;
+}
+
+/**
+ * Under `required: true` (or `trace_parts: true`, issue #947), every edited image must have a receipt whose
+ * `sha256` is its file's bytes: `ASSEMBLE_EDITOR_RECEIPT_MISSING` names the
+ * image, its file and the sha256 found. A file that is not on disk is left to
+ * the reader that names it (`ASSEMBLE_UNDER_PRESENT`, `ASSEMBLE_LIMB_CAP_PRESENT`).
+ * Absent `required`, nothing is demanded and this returns no problem.
+ */
+export function missingReceipts(ledger: ReceiptLedger, images: readonly EditedImage[]): Problem[] {
+  if (!ledger.required) return [];
+  const problems: Problem[] = [];
+  for (const image of images) {
+    if (!existsSync(image.path) || !statSync(image.path).isFile()) continue;
+    const found = fileSha256(image.path);
+    if (ledger.bySha.has(found)) continue;
+    problems.push({
+      code: 'ASSEMBLE_EDITOR_RECEIPT_MISSING',
+      object: image.object,
+      detail: `${image.path} (sha256 ${found}) carries no editor receipt; ${AT}.${ledger.by} is true, so a receipt {file, sha256, from_sha256, editor} whose sha256 is this file's is required — edit the image in an image editor and record it, never generate or patch it in code`,
+    });
+  }
+  return problems;
+}
+
+/** The verified receipt for a file's current bytes, or null: the lookup a later gate (issue #947) traces a part's pixels through. */
+export function receiptFor(ledger: ReceiptLedger, path: string): VerifiedReceipt | null {
+  if (!existsSync(path) || !statSync(path).isFile()) return null;
+  return ledger.bySha.get(fileSha256(path)) ?? null;
+}

package/src/motionseampose.ts

@@ -1,8 +1,10 @@
 /** Posed-axis evidence from one stock seam render, never sampled source keys. */
-import type { GeometryFile, GeometryFrame } from '@rig-c/core/render';
+import type { GeometryFile } from '@rig-c/core/render-shared';
 import type { FrameSet } from './check.ts';
 import { PartsError } from './errors.ts';
 
+type GeometryFrame = GeometryFile['frames'][number];
+
 // Stock rig-c 2.69 geometry header, also exported by rig-c/render. render-shared
 // does not expose its constants; avoid loading the optional Spine side for a header read.
 export const SEAM_GEOMETRY_COORDINATES = 'spine world, y up, world units';

package/src/partsource.ts

@@ -0,0 +1,91 @@
+/**
+ * Part sources (issue #947): with `config.assemble.editor_receipts.trace_parts`
+ * true, every part's pixels trace to a layer of the See-through split or to an
+ * image an editor receipt covers (issue #946), and nothing else.
+ *
+ * Two kinds of input put pixels in a part that trace to neither, and both are
+ * read off the config, never guessed from pixels:
+ *
+ * - **An edited image with no receipt** — an author-made or hidden-art layer,
+ *   a cut's `under`, a limb segment's `cap`. `trace_parts` demands a receipt
+ *   for each exactly as `editor_receipts.required` does
+ *   (`ASSEMBLE_EDITOR_RECEIPT_MISSING`, `src/editreceipt.ts`).
+ * - **A shape the author drew in the config** that decides which pixels a part
+ *   holds: a cut's `polygon` (`assemble.cuts`, and each alternate set's own
+ *   `cuts`), `seethrough.arm_split`'s column or line, a limb's `split.line`, a
+ *   patch's `box` of the painting (`assemble.patches`) and a painting
+ *   extension's `band` (`assemble.extend_painting`). A drawn edge through a
+ *   layer's art is not an edge of the split, and it tears where the piece moves.
+ *   `parts.json` cannot show all of these afterwards — an arm split's parts are
+ *   recorded `full:handwear-r` and `full:handwear-l`, as See-through layers are
+ *   — so the refusal is made on the config, before anything is assembled
+ *   (`ASSEMBLE_PART_SOURCE`).
+ *
+ * What is NOT refused, and why: a limb's segments are cut at the joint the
+ * rig's bones place (`config.limbs`, `jointLine` in `src/limbs.ts`), not along
+ * a line the author drew, and a limb `split` with `edge: "painting"` follows the
+ * painting's stroke; a `take` entry's layer is another See-through run's,
+ * verified by its identity receipt (`taken_layers`); `extend_below_crop`
+ * continues a part from a layer of the full run; the automatic stages
+ * (projection, the seam override, the fringe push-back, the arm-run split by
+ * colour) write within a layer's own footprint or derive their line from the
+ * layers.
+ *
+ * Pure: reads the parsed config only.
+ */
+import type { AssembleConfig } from './config.ts';
+import type { Problem } from './errors.ts';
+
+const FLAG = 'config.assemble.editor_receipts.trace_parts';
+const REQUIRED = `${FLAG} is true, so every part's pixels must trace to a layer of the See-through split or to an image with an editor receipt`;
+const REMEDY = 'paint the piece as an author layer (author:<label>) in an image editor and record its receipt in config.assemble.editor_receipts, or take it whole from a layer of the split — never carve it by a shape drawn in the config';
+
+const box = (b: readonly number[]): string => `[${b.join(', ')}]`;
+
+/** Whether the config declares the gate. */
+export function tracePartsDeclared(cfg: Pick<AssembleConfig, 'assemble'>): boolean {
+  return cfg.assemble.editor_receipts?.trace_parts === true;
+}
+
+/**
+ * Under `trace_parts`, one `ASSEMBLE_PART_SOURCE` per shape the config draws
+ * through a part's pixels, naming the part (as `parts.json` names it), where
+ * the config declares the shape, and the shape found. Absent the flag, none.
+ * Order is the config's: cuts, each alternate set's cuts, patches, painting
+ * extensions, the arm split, limb splits in key order.
+ */
+export function untracedPartSources(cfg: Pick<AssembleConfig, 'assemble' | 'seethrough' | 'limbs'>): Problem[] {
+  if (!tracePartsDeclared(cfg)) return [];
+  const out: Problem[] = [];
+  const refuse = (object: string, found: string): void => {
+    out.push({ code: 'ASSEMBLE_PART_SOURCE', object, detail: `${found}; ${REQUIRED} — ${REMEDY}` });
+  };
+  const a = cfg.assemble;
+  (a.cuts ?? []).forEach((q, i) => {
+    refuse(`part "${q.into}" (config.assemble.cuts[${i}])`, `its pixels are carved out of part "${q.from}" by a hand-drawn ${q.polygon.length}-point polygon`);
+  });
+  (a.alternates ?? []).forEach((set, j) => {
+    (set.cuts ?? []).forEach((q, i) => {
+      refuse(`part "${q.into}" (config.assemble.alternates[${j}].cuts[${i}], alternate set "${set.name}")`, `its pixels are carved out of part "${q.from}" by a hand-drawn ${q.polygon.length}-point polygon`);
+    });
+  });
+  (a.patches ?? []).forEach((p, i) => {
+    refuse(`part "${p.name}" (config.assemble.patches[${i}])`, `its pixels are the painting's inside a hand-drawn box ${box(p.box)} (alpha "${p.alpha}"), which no layer of the split holds`);
+  });
+  (a.extend_painting ?? []).forEach((e, i) => {
+    refuse(`part "${e.part}" (config.assemble.extend_painting[${i}])`, `it gains the painting's pixels inside a hand-drawn band ${box(e.band)}, which no layer of the split holds there`);
+  });
+  const arm = cfg.seethrough.arm_split;
+  if (arm !== undefined) {
+    const shape = arm.x !== undefined ? `a hand-drawn column x = ${arm.x}` : `a hand-drawn ${(arm.line ?? []).length}-point line`;
+    refuse('parts full:handwear-r and full:handwear-l (config.seethrough.arm_split)', `their pixels are split out of the full run's handwear layer along ${shape}`);
+  }
+  for (const name of Object.keys(cfg.limbs ?? {}).sort()) {
+    const limb = (cfg.limbs ?? {})[name];
+    const line = limb.split?.line;
+    if (line === undefined) continue;
+    const parts = limb.segments.map((s) => `"${s.part}"`).join(', ');
+    refuse(`limb "${name}" parts ${parts} (config.limbs.${name}.split.line)`, `their pixels are split from the crossing limb's along a hand-drawn ${line.length}-point line; split.edge "painting" follows the painting's stroke instead`);
+  }
+  return out;
+}

package/src/requirements.ts

@@ -1,6 +1,7 @@
 import { setupPaintingProblems, type SetupPainting } from './setuppainting.ts';
 import { jointMaterialProblems, type JointMaterial } from './cutmaterial.ts';
 import { fixedSkeletonProblems, type FixedSkeleton } from './artjoints.ts';
+import { boundaryColourProblems, type BoundaryColour } from './boundarycolour.ts';
 /**
  * What a scene requires of a rig's motion, declared in a file `check` is given
  * (`--requirements`, issue #93, increment 2 of #87) and measured from the
@@ -199,6 +200,64 @@ export interface RequirementsFile {
   setup_painting?: SetupPainting;
   /** Explicit source-support declarations (#888), absent otherwise. */
   cut_material?: JointMaterial[];
+  /** Issue #944: `assemble`'s pinhole bar, measured only under `required: true`; absent when the file does not declare it. */
+  pinholes?: PinholesDeclaration;
+  /** Issue #941: `check`'s background bar over every declared seam pair and every frame, only under `required: true`; absent when the file does not declare it. */
+  seam_over_motion?: SeamOverMotionDeclaration;
+  /** Issue #942: the boundary colour-step bar against the rig's own pieces, measured by `check` only when declared. */
+  boundary_colour?: BoundaryColour;
+}
+
+/**
+ * Issue #944: the author's declaration that the flat parts stack may hold no
+ * pinhole at rest (`measurePinholes` in `src/assemble.ts`). `assemble` (and
+ * `build`'s assemble) measures it only when `required` is `true`, and refuses
+ * every pinhole by name (`ASSEMBLE_PINHOLES`); absent or `false`, the bar
+ * reports SKIP. The bar is 0 and is not a field: nothing is the author's to set
+ * but whether it holds.
+ */
+export interface PinholesDeclaration {
+  required: boolean;
+}
+
+/** Issue #944: the shape problems of a `pinholes` block — an object holding exactly the boolean `required` (and notes). */
+export function pinholesProblems(value: unknown, at: string): Problem[] {
+  const problems: Problem[] = [];
+  if (!isRecord(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: `is ${JSON.stringify(value)?.slice(0, 40)}; requires {"required": true} (assemble refuses every pinhole of the flat parts stack) or {"required": false} (the same as omitting it: the bar reports SKIP)` }];
+  for (const k of Object.keys(value)) if (k !== 'required' && !freeKey(k, value[k])) problems.push({ code: 'REQUIREMENTS_FIELD', object: `${at}.${k}`, detail: 'is not a field this block reads (required; note or *_note as a string; x-<name> as a record) — the bar is 0 and takes no value' });
+  if (typeof value.required !== 'boolean') problems.push({ code: 'REQUIREMENTS_FIELD', object: `${at}.required`, detail: `is ${JSON.stringify(value.required)}; requires true (assemble refuses every pinhole of the flat parts stack) or false (the same as omitting the block: the bar reports SKIP)` });
+  return problems;
+}
+
+/**
+ * Issue #941: the author's declaration that every declared seam pair —
+ * body-root, internal-joint and explicit — holds 0 background cells on every
+ * frame `SEAM_OVER_MOTION` reads (`motionSeamRequired` in `src/check.ts`).
+ * `check` (and `build`'s check) applies it only when `required` is `true`;
+ * absent or `false`, `SEAM_OVER_MOTION` reads, prints and writes as before.
+ * The bar is 0 and is not a field.
+ */
+export interface SeamOverMotionDeclaration {
+  required: boolean;
+}
+
+/** Issue #941: the shape problems of a `seam_over_motion` block — an object holding exactly the boolean `required` (and notes). */
+export function seamOverMotionProblems(value: unknown, at: string): Problem[] {
+  const problems: Problem[] = [];
+  if (!isRecord(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: `is ${JSON.stringify(value)?.slice(0, 40)}; requires {"required": true} (check refuses background on any frame of any declared seam pair) or {"required": false} (the same as omitting it: SEAM_OVER_MOTION reads as before)` }];
+  for (const k of Object.keys(value)) if (k !== 'required' && !freeKey(k, value[k])) problems.push({ code: 'REQUIREMENTS_FIELD', object: `${at}.${k}`, detail: 'is not a field this block reads (required; note or *_note as a string; x-<name> as a record) — the bar is 0 and takes no value' });
+  if (typeof value.required !== 'boolean') problems.push({ code: 'REQUIREMENTS_FIELD', object: `${at}.required`, detail: `is ${JSON.stringify(value.required)}; requires true (check refuses background on any frame of any declared seam pair) or false (the same as omitting the block: SEAM_OVER_MOTION reads as before)` });
+  return problems;
+}
+
+/** Issue #941: whether the file declares the seam background bar required. */
+export function seamOverMotionRequired(file: Pick<RequirementsFile, 'seam_over_motion'> | null): boolean {
+  return file?.seam_over_motion?.required === true;
+}
+
+/** Issue #944: whether the file declares the pinhole bar required. */
+export function pinholesRequired(file: Pick<RequirementsFile, 'pinholes'>): boolean {
+  return file.pinholes?.required === true;
 }
 
 /** One declared fold (issue #320): a slot, a named animation, and why the fold is the art's. */
@@ -289,7 +348,10 @@ export function readRequirements(path: string): RequirementsFile {
     problems.push({ code: 'REQUIREMENTS_SELF_TARGET', object: `${label} field "target"`, detail });
   };
   if (raw.spec !== REQUIREMENTS_SPEC) field(`${at} field "spec"`, `is ${JSON.stringify(raw.spec)}; ${JSON.stringify(REQUIREMENTS_SPEC)} is required`);
-  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold', 'fixed_skeleton', 'cut_material', 'setup_painting'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold, fixed_skeleton, cut_material, setup_painting; note or *_note as a string; x-<name> as a record)');
+  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold', 'fixed_skeleton', 'cut_material', 'setup_painting', 'pinholes', 'seam_over_motion', 'boundary_colour'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold, fixed_skeleton, cut_material, setup_painting, pinholes, seam_over_motion, boundary_colour; note or *_note as a string; x-<name> as a record)');
+  if ('pinholes' in raw) problems.push(...pinholesProblems(raw.pinholes, `${at} pinholes`));
+  if ('seam_over_motion' in raw) problems.push(...seamOverMotionProblems(raw.seam_over_motion, `${at} seam_over_motion`));
+  if ('boundary_colour' in raw) problems.push(...boundaryColourProblems(raw.boundary_colour, `${at} boundary_colour`));
   if ('setup_painting' in raw) problems.push(...setupPaintingProblems(raw.setup_painting, `${at} setup_painting`));
   if ('cut_material' in raw) problems.push(...jointMaterialProblems(raw.cut_material, `${at} cut_material`));
   if ('fixed_skeleton' in raw) problems.push(...fixedSkeletonProblems(raw.fixed_skeleton, `${at} fixed_skeleton`));
@@ -476,7 +538,7 @@ export function readRequirements(path: string): RequirementsFile {
     }
   }
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold, ...(raw.fixed_skeleton === undefined ? {} : { fixed_skeleton: raw.fixed_skeleton as FixedSkeleton }), ...(raw.cut_material === undefined ? {} : { cut_material: raw.cut_material as JointMaterial[] }), ...(raw.setup_painting === undefined ? {} : { setup_painting: raw.setup_painting as SetupPainting }) };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold, ...(raw.fixed_skeleton === undefined ? {} : { fixed_skeleton: raw.fixed_skeleton as FixedSkeleton }), ...(raw.cut_material === undefined ? {} : { cut_material: raw.cut_material as JointMaterial[] }), ...(raw.setup_painting === undefined ? {} : { setup_painting: raw.setup_painting as SetupPainting }), ...(raw.pinholes === undefined ? {} : { pinholes: { required: (raw.pinholes as PinholesDeclaration).required } }), ...(raw.seam_over_motion === undefined ? {} : { seam_over_motion: { required: (raw.seam_over_motion as SeamOverMotionDeclaration).required } }), ...(raw.boundary_colour === undefined ? {} : { boundary_colour: { max_step_excess: (raw.boundary_colour as BoundaryColour).max_step_excess } }) };
 }
 
 // ---------------------------------------------------------------------------

package/src/rig.ts

@@ -1336,7 +1336,7 @@ export function buildWaistPairSource(
   const CX = W / 2;
   const byPart = new Map(parts.parts.map((p) => [p.name, p]));
 
-  const configuredAlts = cfg.assemble.alternates ?? cfg.alternates ?? [];
+  const configuredAlts = cfg.assemble.alternates ?? [];
   const anchorRegions = new Set(Object.keys(cfg.regions).filter(n => !(n in cfg.meshes)));
   for (const a of configuredAlts) {
     if (a.base_anchor === undefined) continue;
@@ -1354,14 +1354,38 @@ export function buildWaistPairSource(
     if (JSON.stringify(configured === undefined ? null : orderedBaseAnchor(configured)) !== JSON.stringify(a.base_anchor === undefined ? null : orderedBaseAnchor(a.base_anchor))) fail('RIG_ALT_BASE_ANCHOR_MATCH_CONFIG', `alternate set "${a.name}" base_anchor`, 'config and parts.json declare different base anchors; re-run assemble before rig');
     problems.push(...recordedFocusProblems(a, `parts.json alternate set "${a.name}".focus`, parts.rig_size, parts.scale_rig_per_source));
   }
-  for (const a of cfg.assemble.alternates ?? cfg.alternates ?? []) {
+  for (const a of cfg.assemble.alternates ?? []) {
     const record = parts.alternates?.find((p) => p.name === a.name);
-    if (a.base_anchor !== undefined && record === undefined) fail('RIG_ALT_BASE_ANCHOR_MATCH_CONFIG', `alternate set "${a.name}" base_anchor`, 'has no assembled set; re-run assemble before rig');
+    // Issue #962: assemble writes a record for every declared set or refuses, so a declared set with no record was
+    // added or renamed since assemble, and the alternate map below would build without it and say nothing.
+    if (record === undefined) fail('RIG_ALT_SET_ASSEMBLED', `config.assemble alternate set "${a.name}"`, `has no record in parts.json (recorded sets: ${JSON.stringify((parts.alternates ?? []).map((p) => p.name))}); re-run assemble before rig`);
     if ((a.focus !== undefined || record?.focus !== undefined)
       && JSON.stringify(a.focus) !== JSON.stringify(record?.focus)) {
       fail('CONFIG_SET_FOCUS', `config.assemble alternate set "${a.name}".focus`, 'does not match the assembled painting point; re-run assemble after changing or removing focus');
     }
   }
+  // Issue #950: the alternate map below reads `drawn` and `parts` from the record only, so a config edit since
+  // assemble is refused by name rather than built from the stale record. assemble copies `drawn` verbatim and
+  // appends the generated hybrid band names to `parts`; only those appended names may stand beyond the config's.
+  const hybridBands = new Set(Object.values(cfg.limbs ?? {}).flatMap((limb) => limb.segments.flatMap((sg) => sg.hybrid === undefined ? [] : [sg.hybrid.part])));
+  const showDrawn = (d: Record<string, number> | undefined): string => d === undefined ? 'absent' : JSON.stringify(Object.fromEntries(Object.keys(d).sort().map((k) => [k, d[k]])));
+  const showParts = (p: readonly string[] | undefined): string => p === undefined ? 'absent' : JSON.stringify(p);
+  type AltFields = { drawn?: Record<string, number>; parts?: string[] };
+  // A set on one side only is not this rule's: a direct caller may pass records with no config set, and a config
+  // set with no record contributes no alternate map at all.
+  for (const record of parts.alternates ?? []) {
+    const configured: AltFields | undefined = configuredAlts.find((c) => c.name === record.name);
+    if (configured === undefined) continue;
+    if (showDrawn(configured.drawn) !== showDrawn(record.drawn)) {
+      fail('RIG_ALT_DRAWN_MATCH_CONFIG', `alternate set "${record.name}" drawn`, `config declares ${showDrawn(configured.drawn)}; parts.json records ${showDrawn(record.drawn)}; re-run assemble before rig`);
+    }
+    const declared = configured.parts;
+    const stripped = record.parts?.filter((n) => !(hybridBands.has(n) && !(declared ?? []).includes(n)));
+    if (showParts(declared) !== showParts(stripped)) {
+      const bands = record.parts !== undefined && stripped !== undefined && stripped.length !== record.parts.length ? `, ${showParts(stripped)} without its generated hybrid bands` : '';
+      fail('RIG_ALT_PARTS_MATCH_CONFIG', `alternate set "${record.name}" parts`, `config declares ${showParts(declared)}; parts.json records ${showParts(record.parts)}${bands}; re-run assemble before rig`);
+    }
+  }
   refuseIfAny(problems);
 
   // Standalone rig checks source-bound normalization, never reconstructing
@@ -1375,7 +1399,7 @@ export function buildWaistPairSource(
     }
   }
   refuseIfAny(problems);
-  for (const a of cfg.assemble.alternates ?? cfg.alternates ?? []) {
+  for (const a of cfg.assemble.alternates ?? []) {
     const record = parts.alternates?.find((p) => p.name === a.name);
     if (a.tips === undefined) {
       if (record?.tips !== undefined) {
@@ -2738,7 +2762,6 @@ export function buildWaistPairSource(
   if (parts.alternates !== undefined && parts.alternates.length > 0) {
     const setEntries: Record<string, AlternateSetMap> = {};
     for (const [altIdx, alt] of parts.alternates.entries()) {
-      const cfgAlt = cfg.alternates?.find((a) => a.name === alt.name);
       for (const [bone, tip] of Object.entries(alt.tips ?? {})) {
         if (bone === ROOT_BONE || !B.has(bone)) fail('RIG_NAME_RESOLVES', `parts.json alternates[${altIdx}].tips.${bone}`, `names "${bone}", which config.bones does not declare; re-run assemble with declared bone names`);
         if (!Array.isArray(tip) || tip.length !== 2 || !tip.every((n) => typeof n === 'number' && Number.isFinite(n))) {
@@ -2753,8 +2776,8 @@ export function buildWaistPairSource(
       }
       const altFront = new Set(alt.front ?? []);
       refuseIfAny(problems);
-      const explicitDrawn = alt.drawn ?? cfgAlt?.drawn;
-      const isSubsetSet = alt.parts !== undefined || cfgAlt?.parts !== undefined;
+      const explicitDrawn = alt.drawn;
+      const isSubsetSet = alt.parts !== undefined;
       let coveredBones: Set<string> | null = null;
       if (isSubsetSet) {
         coveredBones = new Set<string>();
@@ -2776,7 +2799,7 @@ export function buildWaistPairSource(
       if (explicitDrawn !== undefined) {
         for (const boneName of Object.keys(explicitDrawn)) {
           if (!B.has(boneName)) {
-            fail('RIG_NAME_RESOLVES', `config.alternates[${altIdx}].drawn.${boneName}`, `names the bone "${boneName}", which config.bones does not declare`);
+            fail('RIG_NAME_RESOLVES', `parts.json alternates[${altIdx}].drawn.${boneName}`, `names the bone "${boneName}", which config.bones does not declare`);
           } else if (coveredBones !== null && !coveredBones.has(boneName)) {
             const coveredList = [...coveredBones].map((b) => `"${b}"`).join(', ') || 'none';
             fail(

package/src/setuppainting.ts

@@ -11,10 +11,16 @@ export interface SetupPaintingRegion {
   max_pixels?: number;
 }
 export interface SetupPainting {
+  /** Issue #943: the author's declaration that this check may not SKIP. When
+   * true, a missing rgb_tolerance, regions or any region's max_pixels is
+   * refused by name (SETUP_PAINTING_REQUIRED_LIMIT) instead of reported as
+   * SKIP. Absent or false: the pre-#943 reading, unchanged. */
+  required?: boolean;
   /** A pixel counts when its maximum RGB difference is strictly greater. */
   rgb_tolerance: number;
   regions: SetupPaintingRegion[];
 }
+export const SETUP_PAINTING_REQUIRED_CODE = 'SETUP_PAINTING_REQUIRED_LIMIT';
 const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const integer = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v);
 const free = (k: string, v: unknown): boolean => (k.startsWith('x-') && k.length > 2) || ((k === 'note' || k.endsWith('_note')) && typeof v === 'string');
@@ -27,9 +33,17 @@ export function setupPaintingProblems(value: unknown, at: string): Problem[] {
     for (const k of Object.keys(v)) if (!allowed.includes(k) && !free(k, v[k])) fail(`${where}.${k}`, `is unknown; fields are ${allowed.join(', ')}`);
   };
   if (!object(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: 'requires {rgb_tolerance, regions: [{name, box, max_pixels?}]}' }];
-  keys(value, ['rgb_tolerance', 'regions'], at);
-  if (!integer(value.rgb_tolerance) || value.rgb_tolerance < 0 || value.rgb_tolerance > 255) fail(`${at}.rgb_tolerance`, 'requires an authored integer from 0 through 255; difference strictly above it counts');
-  if (!Array.isArray(value.regions) || value.regions.length === 0) fail(`${at}.regions`, 'requires a nonempty list of named source-grid regions');
+  keys(value, ['required', 'rgb_tolerance', 'regions'], at);
+  if ('required' in value && typeof value.required !== 'boolean') fail(`${at}.required`, `is ${JSON.stringify(value.required)}; requires true (the check may not SKIP: every limit must be declared) or false (the same as omitting it)`);
+  // Issue #943: under required: true an absent limit is not a SKIP to report but a refusal naming the field.
+  const required = value.required === true;
+  const missing = (where: string, needed: string): void => {
+    problems.push({ code: SETUP_PAINTING_REQUIRED_CODE, object: where, detail: `is absent; setup_painting.required is true, so SETUP_MATCHES_PAINTING may not SKIP — declare ${needed}. No limit is derived from the art` });
+  };
+  if (required && !('rgb_tolerance' in value)) missing(`${at}.rgb_tolerance`, 'an authored integer from 0 through 255');
+  else if (!integer(value.rgb_tolerance) || value.rgb_tolerance < 0 || value.rgb_tolerance > 255) fail(`${at}.rgb_tolerance`, 'requires an authored integer from 0 through 255; difference strictly above it counts');
+  if (required && !('regions' in value)) missing(`${at}.regions`, 'a nonempty list of named source-grid regions, each with box and an authored max_pixels');
+  else if (!Array.isArray(value.regions) || value.regions.length === 0) fail(`${at}.regions`, 'requires a nonempty list of named source-grid regions');
   else {
     const names = new Set<string>();
     value.regions.forEach((r, i) => {
@@ -40,6 +54,7 @@ export function setupPaintingProblems(value: unknown, at: string): Problem[] {
       else { if (names.has(r.name)) fail(`${where}.name`, `declares region "${r.name}" twice`); names.add(r.name); }
       if (!Array.isArray(r.box) || r.box.length !== 4 || !r.box.every(integer) || r.box[0] < 0 || r.box[1] < 0 || r.box[2] <= 0 || r.box[3] <= 0 || !Number.isSafeInteger(r.box[0] + r.box[2]) || !Number.isSafeInteger(r.box[1] + r.box[3])) fail(`${where}.box`, 'requires nonnegative integer x/y and positive integer width/height in stage pixels, with finite integer far edges');
       if ('max_pixels' in r && (!integer(r.max_pixels) || r.max_pixels < 0)) fail(`${where}.max_pixels`, 'requires a nonnegative authored integer pixel count, or omission for SKIP');
+      else if (required && !('max_pixels' in r)) missing(`${where}.max_pixels${typeof r.name === 'string' ? ` (region "${r.name}")` : ''}`, 'an authored nonnegative integer pixel count for this region; without it the region would report SKIP');
     });
   }
   return problems;