@rig-c/parts 2.49.1 → 2.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -333,6 +333,7 @@ Command details and config saving are in the [command reference](docs/AUTHORING.
333
333
  | `edited-part` | [Record an edited part receipt](docs/AUTHORING.md#edited-rig-space-parts-assembleedited_parts-issue-1278) |
334
334
  | `external-receipt` | [Record or verify an external mask](docs/AUTHORING.md#external-mask-receipt) |
335
335
  | `propose` | [Draft or inspect a character config](docs/AUTHORING.md#command-reference) |
336
+ | `bust-landmarks` | [Write the chest landmarks file from a review act](docs/AUTHORING.md#drafting-the-chest-carrier) |
336
337
  | `compare` | [Compare two skeletons by name](docs/AUTHORING.md#command-reference) |
337
338
  | `rig` | [Author gated rig and motion specs](docs/AUTHORING.md#command-reference) |
338
339
  | `check` | [Build, render and measure a rig](docs/AUTHORING.md#command-reference) |
package/cli.ts CHANGED
@@ -5,6 +5,7 @@ import { DIFF_DRAFTS_SPEC, diffDraftsCommand } from './src/diffdrafts.ts';
5
5
  import { applyTakenLayers } from './src/takelayers.ts';
6
6
  import { applyDepth, bindDepthMap, prepareDepth } from './src/depthworkflow.ts';
7
7
  import { externalReceipt } from './src/externalreceipt.ts';
8
+ import { BUST_LANDMARKS_ACT_SCHEMA, BUST_LANDMARKS_PROVENANCE_SPEC, BUST_LANDMARKS_PROVENANCE_SUFFIX, type BustSidecar, planBustLandmarks, readBustSidecar, stageBustLandmarks, stageReplacements, type StagedBustLandmarks } from './src/bustlandmarks.ts';
8
9
  import { writeEditedPart } from './tools/edited-part-cli.ts';
9
10
  /**
10
11
  * rig-parts — one painting and its See-through layers in, Spine-ready parts
@@ -31,8 +32,8 @@ import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK
31
32
  import { ComfyClient, resolveHost, runBackground, runMatte, runPainting, runSeeThrough } from './src/comfy/index.ts';
32
33
  import { coreCfg, DEFAULT_GROW_PX, runForeground } from './src/plate.ts';
33
34
  import { type CharacterConfig, loadClothConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
34
- import { configWriteLines, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
35
- import { failLine, guidePointer, PartsError } from './src/errors.ts';
35
+ import { configWriteLines, type ConfigWriteTarget, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
36
+ import { failLine, guidePointer, PartsError, type Problem } from './src/errors.ts';
36
37
  import { GUIDE_DOC, type GuideAnswer, guideRule, guideSection } from './src/guide.ts';
37
38
  import { proposeHeadBox, type Box } from './src/headbox.ts';
38
39
  import { headCropPreflight, headCropPreflightLines } from './src/headcroppreflight.ts';
@@ -211,6 +212,10 @@ usage:
211
212
  Draft the chest-holding topwear as contour. Landmark JSON declares apex_r,
212
213
  apex_l and optional cleavage in rig pixels. Without cleavage, intersect
213
214
  their segment with the neck-to-hip midline. --no-bust needs a stated reason.
215
+ A record <landmarks.json>${BUST_LANDMARKS_PROVENANCE_SUFFIX} beside the file (bust-landmarks
216
+ writes one) must name the drafted chest carrier and the file's own
217
+ sha256; a pending shape in it needs --write-config, which writes it with
218
+ the points and marks the record applied.
214
219
  rig-parts propose … [--keypoints <keypoints.json> [--person <id>] [--wrist-snap <px>]]
215
220
  Read the figure's pose from one explicit file (spec "${KEYPOINTS_SPEC}"):
216
221
  its space (painting-px, origin top-left, y down — another is refused),
@@ -374,6 +379,24 @@ usage:
374
379
  --no-back-hair leaves "back hair" out of the box. --write-config updates
375
380
  only seethrough.head_box in an existing config through the layers loader.
376
381
 
382
+ rig-parts bust-landmarks --from-act <act.json> --parts <dir> --config <config.json> --out <landmarks.json> [--write-config]
383
+ Write the file propose --bust-landmarks reads (apex_r, apex_l and
384
+ optional cleavage, rig px) from the one chest row of a Review
385
+ ${BUST_LANDMARKS_ACT_SCHEMA} act, and <out>${BUST_LANDMARKS_PROVENANCE_SUFFIX} beside it (spec
386
+ "${BUST_LANDMARKS_PROVENANCE_SPEC}": the act's schema, id and
387
+ file sha256, the row's sha256, verified against the row's edit, the
388
+ slot, the source hash and frame). The row's slot must be a part of
389
+ parts.json whose config mesh is a contour, its frame parts.json's
390
+ rig_size, and its alpha, clearance, spacing, bone_r and bone_l those of
391
+ the config's contour.bust. --write-config instead takes those five into
392
+ the config's existing contour.bust, a field the act omits removed,
393
+ through the config loader; the config is untouched when none differs.
394
+ With no contour.bust yet, fields that differ from the defaults are
395
+ recorded as a pending shape in the record, and propose --write-config
396
+ --bust-landmarks writes them with the points and marks them applied.
397
+ Writes nothing on a refusal; the outputs are renamed into place only
398
+ once both are staged.
399
+
377
400
  rig-parts head-crop-preflight --full <run> --canvas <W>x<H> --head-box '[left,top,right,bottom]'
378
401
  Report full-run drawn pixels beyond the crop: JSON stdout, advice stderr; no head run needed.
379
402
 
@@ -1214,6 +1237,7 @@ const TAKES = {
1214
1237
  'edited-part': { valued: ['--config', '--part', '--file', '--from', '--editor', '--producer', '--parts', '--rig-config'], switches: ['--help'] },
1215
1238
  'external-receipt': { valued: ['--kind', '--file', '--painting', '--producer', '--out', '--verify'], switches: ['--help'] },
1216
1239
  'check-parts': { valued: ['--parts', '--out'], switches: ['--json', '--help'] },
1240
+ 'bust-landmarks': { valued: ['--from-act', '--parts', '--config', '--out'], switches: ['--write-config', '--help'] },
1217
1241
  'diff-components': { valued: ['--stack', '--painting', '--parts', '--figure', '--floor', '--threshold', '--out', '--verify'], switches: ['--owners', '--help'] },
1218
1242
  'diff-drafts': { valued: ['--left', '--right', '--out'], switches: ['--help'] },
1219
1243
  'depth-bind': { valued: ['--map', '--input', '--part'], switches: ['--help'] },
@@ -1712,6 +1736,8 @@ function cmdPropose(args: string[]): number {
1712
1736
  if (!flags.has('--write-config')) return usage(`--only-missing belongs to ${mode}; give --write-config <config.json>, the existing config the entries are added to`);
1713
1737
  }
1714
1738
  let staged: StagedConfigWrite | null = null;
1739
+ // Issue #1382: the landmarks file's record, marked applied beside the config write that applies its pending shape.
1740
+ let sidecarStaged: StagedBustLandmarks | null = null;
1715
1741
  try {
1716
1742
  if (headBox) {
1717
1743
  const stray = [...flags.keys()].filter((f) => f !== '--full' && f !== '--canvas' && f !== '--write-config');
@@ -1839,9 +1865,12 @@ function cmdPropose(args: string[]): number {
1839
1865
  if (noBust !== undefined && (noBust.trim().length === 0 || bustPath !== undefined)) return usage('--no-bust requires a non-blank reason and cannot accompany --bust-landmarks');
1840
1866
  const bust: BustDraft = {};
1841
1867
  if (noBust !== undefined) bust.noBust = noBust;
1868
+ let sidecar: BustSidecar | null = null;
1842
1869
  if (bustPath !== undefined) {
1870
+ let bytes: Buffer;
1843
1871
  try {
1844
- bust.landmarks = readBustLandmarks(JSON.parse(readFileSync(bustPath, 'utf8')) as unknown);
1872
+ bytes = readFileSync(bustPath);
1873
+ bust.landmarks = readBustLandmarks(JSON.parse(bytes.toString('utf8')) as unknown);
1845
1874
  } catch (error) {
1846
1875
  if (error instanceof PartsError) throw error;
1847
1876
  throw new PartsError([{
@@ -1849,6 +1878,14 @@ function cmdPropose(args: string[]): number {
1849
1878
  detail: `cannot read the declared JSON file (${error instanceof Error ? error.message : String(error)}). Give an object with apex_r, apex_l and optional cleavage in rig pixels`,
1850
1879
  }]);
1851
1880
  }
1881
+ // Issue #1382: no record beside the file is the hand-written fallback, read as before.
1882
+ sidecar = readBustSidecar(bustPath, bytes);
1883
+ if (sidecar?.pending != null) {
1884
+ const what = `${sidecar.path} holds a pending shape (${pendingFields(sidecar.pending.fields)}) from act ${JSON.stringify(sidecar.provenance.act.act_id)}`;
1885
+ if (writeArg === undefined) throw new PartsError([{ code: 'PROPOSE_BUST_PENDING', object: '--bust-landmarks', detail: `${what}, which only a config write keeps; give --write-config <config.json> so propose writes it into contour.bust with the three points, or it is lost — nothing was written` }]);
1886
+ if (target === null || onlyMissing) throw new PartsError([{ code: 'PROPOSE_BUST_PENDING', object: onlyMissing ? '--only-missing' : '--cloth', detail: `${what}; propose writes it only through an ordinary --write-config update of an existing config, not with ${onlyMissing ? '--only-missing' : '--cloth'} — nothing was written` }]);
1887
+ separateConfigWriteTarget(target, [sidecar.path]);
1888
+ }
1852
1889
  }
1853
1890
  const { proposal: drafted, basis, draftLint } = proposeWithBasis(P, joints, wristSnap, gridRule, cloth, true, bust);
1854
1891
  const fullRun = flags.get('--full');
@@ -1859,6 +1896,13 @@ function cmdPropose(args: string[]): number {
1859
1896
  : withTurn(drafted, draftTurn(P, { ...(fullRun === undefined ? {} : { full: readLayers(fullRun) }), ...(headRun === undefined ? {} : { head: readLayers(headRun) }) }, drafted));
1860
1897
  // Emit only after green: a proposal the config loader would refuse is not written, nor a basis record that does not hold to it.
1861
1898
  checkProposal(P, prop);
1899
+ if (sidecar !== null) {
1900
+ // The record's part must be the chest carrier this draft makes: points placed on another part are not these.
1901
+ const carriers = Object.entries(prop.meshes).filter(([, mesh]) => 'contour' in mesh && mesh.contour.bust !== undefined).map(([part]) => part);
1902
+ if (!carriers.includes(sidecar.provenance.slot)) {
1903
+ throw new PartsError([{ code: 'PROPOSE_BUST_SIDECAR_PART', object: `${sidecar.path} slot`, detail: `is "${sidecar.provenance.slot}"; the chest carrier this draft makes (${carriers.length === 0 ? 'none' : carriers.map((c) => `"${c}"`).join(', ')}) is required: the record's points were placed on another part` }]);
1904
+ }
1905
+ }
1862
1906
  // The same parts drafted without the recipe: what --write-config measures its edits against, and what issue #572's chain reading compares with.
1863
1907
  const plain = cloth === null ? null : proposeWithBasis(P, joints, wristSnap, gridRule, null, true, bust).proposal;
1864
1908
  // Issue #537: the sections the recipe moves, measured against the same parts drafted without it, spliced before anything is written.
@@ -1894,16 +1938,33 @@ function cmdPropose(args: string[]): number {
1894
1938
  })();
1895
1939
  const bfile = basisFile(P, prop, basis, cfg === null || cmpPath === undefined ? null : { where: cmpPath, config: cfg });
1896
1940
  const img = drawLandmarks(P, painting, prop.bones, 'PROPOSAL - CORRECT ME');
1897
- if (target !== null) staged = stageConfigWrite(target, onlyMissing ? { kind: 'proposal-missing', proposal: prop, parts: P.recs } : { kind: 'proposal', proposal: prop, sections: PROPOSAL_CONFIG_SECTIONS });
1941
+ const pending = sidecar?.pending ?? null;
1942
+ if (target !== null) staged = stageConfigWrite(target, onlyMissing ? { kind: 'proposal-missing', proposal: prop, parts: P.recs } : { kind: 'proposal', proposal: prop, sections: PROPOSAL_CONFIG_SECTIONS, ...(pending === null ? {} : { bustShape: pending }) });
1898
1943
  else if (written !== null) staged = stageConfigWrite({ kind: 'fresh', path: written.at, text: written.text });
1944
+ // The record marked applied is staged after the config and renamed in before the config's commit; a failed
1945
+ // config commit puts the record back, so the two change together or not at all.
1946
+ if (sidecar !== null && sidecar.appliedText !== null && staged !== null) sidecarStaged = stageReplacements([[sidecar.path, sidecar.appliedText]]);
1899
1947
  mkdirSync(render, { recursive: true });
1900
1948
  writeFileSync(join(out, 'proposal.json'), serializeProposal(prop));
1901
1949
  writeFileSync(join(out, BASIS_FILE), serializeBasis(bfile));
1902
1950
  writePng(join(render, 'landmarks.png'), img.full);
1903
1951
  if (img.head !== null) writePng(join(render, 'landmarks_head.png'), img.head);
1904
1952
  if (staged !== null) {
1905
- staged.commit();
1953
+ const marked = sidecarStaged;
1954
+ if (marked !== null) { marked.commit(); sidecarStaged = null; }
1955
+ try { staged.commit(); }
1956
+ catch (error) {
1957
+ if (marked === null) throw error;
1958
+ const problems = error instanceof PartsError ? [...error.problems] : [];
1959
+ try { marked.undo(); } catch (cleanup) { if (cleanup instanceof PartsError) problems.push(...cleanup.problems); }
1960
+ staged = null;
1961
+ if (problems.length === 0) throw error;
1962
+ throw new PartsError(problems);
1963
+ }
1906
1964
  if (target !== null) for (const line of configWriteLines(target, staged.changes)) console.error(line);
1965
+ if (marked !== null && pending !== null && sidecar !== null) {
1966
+ console.log(`propose: wrote the pending shape of act ${JSON.stringify(sidecar.provenance.act.act_id)} into meshes.${pending.part}.contour.bust (${pendingFields(pending.fields)}) with the three points; marked it applied in ${sidecar.path}`);
1967
+ }
1907
1968
  const writtenPath = target?.path ?? written?.at;
1908
1969
  if (writtenPath !== undefined && P.manifest.assembly_config !== undefined) {
1909
1970
  try {
@@ -1935,6 +1996,9 @@ function cmdPropose(args: string[]): number {
1935
1996
  if (cfg !== null) for (const l of compareLines(compare(prop.bones, cfg.bones))) console.log(l);
1936
1997
  return EXIT_OK;
1937
1998
  } catch (err) {
1999
+ if (sidecarStaged !== null) {
2000
+ try { sidecarStaged.cancel(); } catch (cleanup) { if (!(cleanup instanceof PartsError)) throw cleanup; }
2001
+ }
1938
2002
  if (staged !== null) {
1939
2003
  try { staged.abort(err); } catch (combined) { return printRefusal(combined); }
1940
2004
  }
@@ -2662,6 +2726,64 @@ function cmdExternalReceipt(args: string[]): number {
2662
2726
  } catch (error) { return printRefusal(error); }
2663
2727
  }
2664
2728
 
2729
+ /** A pending shape's fields, as `alpha 0.3, bone_r "chest"`. */
2730
+ function pendingFields(fields: Readonly<Record<string, number | string | undefined>>): string {
2731
+ return Object.entries(fields).filter(([, v]) => v !== undefined).map(([k, v]) => `${k} ${JSON.stringify(v)}`).join(', ');
2732
+ }
2733
+
2734
+ function cmdBustLandmarks(args: string[]): number {
2735
+ // The one switch (issue #1382, round 2): taken out before the valued flags are read.
2736
+ const writes = args.filter((a) => a === '--write-config').length;
2737
+ if (writes > 1) return usage('--write-config is given twice');
2738
+ const f = flags(args.filter((a) => a !== '--write-config'), 'bust-landmarks', ['--from-act', '--parts', '--config', '--out']);
2739
+ if (typeof f === 'string') return usage(f);
2740
+ try {
2741
+ const input = { act: f.get('--from-act')!, parts: f.get('--parts')!, config: f.get('--config')!, out: f.get('--out')!, writeConfig: writes === 1 };
2742
+ // The config to write is read before it is checked, so its commit refuses a change made in between; a refusal
2743
+ // reading it joins the act's and the inputs' in one report.
2744
+ const prior: Problem[] = [];
2745
+ let target: ConfigWriteTarget | null = null;
2746
+ if (input.writeConfig) {
2747
+ try { target = readConfigWriteTarget(input.config); }
2748
+ catch (error) { if (error instanceof PartsError) prior.push(...error.problems); else throw error; }
2749
+ }
2750
+ const plan = planBustLandmarks(input, prior);
2751
+ if (target !== null) separateConfigWriteTarget(target, [plan.out, plan.provenancePath], 'BUST_LANDMARKS_OUT');
2752
+ // propose's order: the config staged (and checked through the loader) first, then the outputs written, then the
2753
+ // config committed; a failure before the config's commit leaves it as it was, and a failed config commit puts
2754
+ // the earlier outputs back.
2755
+ const staged: StagedConfigWrite | null = target !== null && plan.configPatch !== null ? stageConfigWrite(target, plan.configPatch) : null;
2756
+ let outputs: StagedBustLandmarks;
2757
+ try {
2758
+ outputs = stageBustLandmarks(plan);
2759
+ outputs.commit();
2760
+ } catch (error) {
2761
+ if (staged !== null) staged.abort(error);
2762
+ throw error;
2763
+ }
2764
+ if (staged !== null) {
2765
+ try { staged.commit(); }
2766
+ catch (error) {
2767
+ const problems = error instanceof PartsError ? [...error.problems] : [];
2768
+ try { outputs.undo(); } catch (cleanup) { if (cleanup instanceof PartsError) problems.push(...cleanup.problems); }
2769
+ if (problems.length === 0) throw error;
2770
+ throw new PartsError(problems);
2771
+ }
2772
+ }
2773
+ const { landmarks, provenance } = plan;
2774
+ if (target !== null) for (const line of configWriteLines(target, staged?.changes ?? [])) console.error(line);
2775
+ console.log(`bust-landmarks: slot "${provenance.slot}" apex_r ${JSON.stringify(landmarks.apex_r)} apex_l ${JSON.stringify(landmarks.apex_l)} cleavage ${landmarks.cleavage === undefined ? 'absent (propose derives it)' : JSON.stringify(landmarks.cleavage)}; act ${JSON.stringify(provenance.act.act_id)} sha256=${provenance.act.file_sha256} row sha256=${provenance.row_sha256} (verified against the row's edit)`);
2776
+ const shape = provenance.shape;
2777
+ if (shape === undefined) console.log(`wrote ${plan.out} and ${plan.provenancePath}; next: rig-parts propose … --bust-landmarks ${plan.out}`);
2778
+ else {
2779
+ // Issue #1382: the config declares no contour.bust, so the reviewed shape waits in the record for propose.
2780
+ console.log(`bust-landmarks: pending shape for "${provenance.slot}": ${pendingFields(shape.fields)}; the config declares no contour.bust yet, so ${plan.provenancePath} carries it until propose writes it with the three points`);
2781
+ console.log(`wrote ${plan.out} and ${plan.provenancePath}; next, to apply it: rig-parts propose … --write-config ${resolve(input.config)} --bust-landmarks ${plan.out}`);
2782
+ }
2783
+ return EXIT_OK;
2784
+ } catch (error) { return printRefusal(error); }
2785
+ }
2786
+
2665
2787
  function cmdDepthBind(args: string[]): number {
2666
2788
  const f = flags(args, 'depth-bind', ['--map', '--input', '--part']);
2667
2789
  if (typeof f === 'string') return usage(f);
@@ -2702,6 +2824,7 @@ function main(argv: string[]): number | Promise<number> {
2702
2824
  if (command === 'depth-prepare') return cmdDepthPrepare(rest);
2703
2825
  if (command === 'edited-part') return cmdEditedPart(rest);
2704
2826
  if (command === 'external-receipt') return cmdExternalReceipt(rest);
2827
+ if (command === 'bust-landmarks') return cmdBustLandmarks(rest);
2705
2828
  if (command === 'depth-bind') return cmdDepthBind(rest);
2706
2829
  if (command === 'depth-apply') return cmdDepthApply(rest);
2707
2830
  if (command === 'sheet') return cmdSheet(rest);
package/docs/AUTHORING.md CHANGED
@@ -236,7 +236,13 @@ neck-to-hip midline. A missing unique crossing inside the segment is refused by
236
236
  name, requiring an explicit cleavage point or apices on opposite sides of the midline.
237
237
  The derived point is rounded to the existing 1/256-pixel contour grid. Declared apex
238
238
  coordinates are preserved exactly in both the regions and their bones.
239
- The proposal writes `contour.bust` and `boob_r` / `boob_l` under `chest`.
239
+ The proposal writes `contour.bust` and `boob_r` / `boob_l` under `chest`. When
240
+ `propose --write-config` redrafts the chest carrier, it keeps the `contour.bust`
241
+ shape fields (`alpha`, `clearance`, `bone_r`, `bone_l`, `spacing`) that the config
242
+ being rewritten already declares for that same part, in the shorthand's key order
243
+ after the new `apex_r`, `apex_l` and `cleavage` (issue #1428). A pending shape in
244
+ the landmarks file's record (below, issue #1382) is written the same way, and takes
245
+ the place of any declared value for its fields.
240
246
 
241
247
  A chest-holding torso with neither landmarks nor an explicit omission reason is
242
248
  refused with `PROPOSE_BUST_INPUT` before any proposal is written. `--no-bust "rigid breastplate"` omits the bust and records the
@@ -248,6 +254,128 @@ covers the chest also takes this contour rule, keeping its recipe's segments. A
248
254
  recipe that explicitly declares `influence` for that torso conflicts with the contour
249
255
  mode and is refused, naming the field to remove or the cloth part to separate.
250
256
 
257
+ **Where the points come from (issue #1382).** The person places them in review,
258
+ on a drafted rig, and the act review emits carries them. The order is:
259
+
260
+ 1. Draft without the chest: `propose … --no-bust "<reason>"`, or with a
261
+ hand-written landmarks file as above. Either way the chest carrier is drafted
262
+ as a contour, which the review chest editor needs.
263
+ 2. Build the draft and let the person place or correct apex_r, apex_l and
264
+ cleavage in review's chest editor. Their Request changes is a
265
+ `rig-review/act@9` act with a `value.chestLandmarks` row.
266
+ 3. `rig-parts bust-landmarks --from-act <act.json> --parts <dir> --config <config.json> --out <landmarks.json>`
267
+ writes the landmarks file from that row. It writes
268
+ `<landmarks.json>.provenance.json` beside it. When the person changed a
269
+ shape field (`alpha`, `clearance`, `bone_r`, `bone_l`, `spacing`) and the
270
+ config already declares `contour.bust`, add `--write-config`: it takes the
271
+ act's five values into that `contour.bust` and then writes the landmarks
272
+ file. When the config declares no `contour.bust` yet (the first draft), the
273
+ changed fields are recorded as a **pending** shape in the record, and the
274
+ command prints the one that applies them.
275
+ 4. Redraft with `propose … --write-config <config.json> --bust-landmarks <landmarks.json>`.
276
+ It writes `contour.bust` with the three points, and with a pending shape it
277
+ writes those fields too, in the same staged write, and marks the record
278
+ applied. The redraft keeps the config's declared shape fields (#1428).
279
+ Without `--write-config`, `propose` drafts the points alone and refuses a
280
+ record with a pending shape, which only a config write keeps.
281
+
282
+ The hand-written file stays the fallback when no review act exists.
283
+ `bust-landmarks` reads the act's JSON itself. It reads `schema`, `actId` and the
284
+ rows of `value.chestLandmarks`. From each row it reads `edit.slot`, `edit.skin`,
285
+ `edit.attachment`, `edit.basis`, `edit.source.hash`, `edit.source.frame`,
286
+ `edit.bust` and `sha256`. It refuses by name:
287
+
288
+ - an act that is not readable JSON, has another `schema`, or has no chest row (`BUST_LANDMARKS_ACT`);
289
+ - a row that is malformed for what it reads (`BUST_LANDMARKS_ROW`). That covers a
290
+ point that is not two finite numbers, a missing apex, a `basis` other than
291
+ `"setup"`, a `sha256` or `source.hash` that is not 64 lowercase hex digits, a
292
+ `sha256` that is not the digest of the row's `edit`, a missing frame, and a
293
+ `bust` field `contour.bust` does not have;
294
+ - a slot that is not a part of `parts.json`, or whose `config.meshes` entry is
295
+ not a contour mesh, an attachment other than the slot (an explicit mesh's
296
+ island slot), or a skin other than `default` (`BUST_LANDMARKS_SLOT`);
297
+ - two rows for one part (`BUST_LANDMARKS_PART_ROWS`), or rows for more than one
298
+ part (`BUST_LANDMARKS_ROWS`). `propose` drafts one chest carrier, and the
299
+ landmarks file names no part;
300
+ - an `edit.source.frame` other than `parts.json`'s `rig_size`, the frame the
301
+ points are rig px in (`BUST_LANDMARKS_FRAME`);
302
+ - an `alpha`, `clearance`, `spacing`, `bone_r` or `bone_l` that differs from the
303
+ config's `meshes.<part>.contour.bust` after defaults (`BUST_LANDMARKS_SHAPE`).
304
+ The landmarks file carries none of the five, so a different value would be
305
+ dropped. A config with no `contour.bust` yet, the first draft made with
306
+ `--no-bust`, compares against the defaults (alpha 0.22, clearance 3.8,
307
+ spacing 14, bones `boob_r` and `boob_l`). Those are the values `propose`
308
+ drafts `contour.bust` with from the three points, so a first correction that
309
+ keeps the defaults passes. The redraft keeps the config's declared shape
310
+ fields (#1428). With `--write-config` and a declared `contour.bust`, a
311
+ difference is written rather than refused (below). With no `contour.bust`, a
312
+ difference is not refused either: it is left pending in the record (below),
313
+ because the five fields alone do not make a `contour.bust`, which needs
314
+ `apex_r`, `apex_l` and `cleavage`, and no point is made up to build one;
315
+ - an `--out`, or its provenance record, inside the parts directory, over the act,
316
+ the config or `parts.json` by path or as a hard link (the same device and inode,
317
+ compared when the output exists), over a directory, or over an existing file
318
+ that is not writable (`BUST_LANDMARKS_OUT`).
319
+
320
+ `--write-config` updates the `--config` file in place through the same staged
321
+ writer `propose --write-config` uses, and prints its change lines to stderr. After
322
+ the run the config's five effective values equal the act's: a field the act
323
+ spells out is written as the act gives it, and a field the act omits is removed
324
+ from `contour.bust`, so it reads as the default. Only fields whose effective
325
+ values differ are touched. When none differs, the config's bytes are not
326
+ touched and the change line reads `unchanged`. The candidate config passes the
327
+ full config loader before anything is written.
328
+
329
+ Every problem is collected and printed at once, and nothing is written on a
330
+ refusal. The two outputs are written to temporary siblings and renamed into
331
+ place only once both are staged. With `--write-config` the config is staged
332
+ first and committed last, the order `propose --write-config` uses. A failure
333
+ removes the temporaries and leaves the earlier files as they were.
334
+
335
+ The provenance record (spec `rig-parts-bust-landmarks-provenance/1`)
336
+ holds, in this order: `act` (`schema`, `act_id`, and `file_sha256`, the sha256
337
+ of the act file's bytes), `row_sha256`, `slot`, `source` (`hash`, and `frame` as
338
+ `width` and `height`), and `landmarks_sha256`, the sha256 of the landmarks file
339
+ written beside it. It has no clock, so the same act writes the same bytes. The
340
+ record sits beside the landmarks file because `propose --bust-landmarks` refuses
341
+ any key but the three points.
342
+
343
+ A **pending** shape is the record's last key, `shape`, present only when the
344
+ config declared no `contour.bust` and the act's shape differs from the defaults:
345
+ `{"status": "pending", "fields": {…}}`, the act's fields whose value differs from
346
+ the default, in the shorthand's key order (`alpha`, `clearance`, `bone_r`,
347
+ `bone_l`, `spacing`). An all-default act writes no `shape`, so its record is the
348
+ same bytes as before. `propose --bust-landmarks <file>` reads `<file>.provenance.json`
349
+ when it is there; with none it reads the landmarks file as before. A record there
350
+ must be well formed (`PROPOSE_BUST_SIDECAR`), its `landmarks_sha256` must be the
351
+ landmarks file's own digest (`PROPOSE_BUST_SIDECAR_DIGEST`), and its `slot` must
352
+ be the chest carrier the draft makes (`PROPOSE_BUST_SIDECAR_PART`). A pending
353
+ shape needs `--write-config` into an existing config, not `--cloth` or
354
+ `--only-missing` (`PROPOSE_BUST_PENDING`). With it, `propose` writes the fields
355
+ after the three points in the config write it stages, and rewrites the record with
356
+ `"status": "applied"`. The record is staged after the config, renamed in before
357
+ the config's commit, and put back if that commit fails, so both change or
358
+ neither. An applied record writes nothing more: a hand edit of the shape after
359
+ that is kept by every later redraft (#1428).
360
+
361
+ The row's `sha256` is recomputed and a mismatch is
362
+ refused as `BUST_LANDMARKS_ROW` on `value.chestLandmarks[i].sha256`: it must be
363
+ the sha256 (lowercase hex) of `JSON.stringify` of the row's `edit`, with object
364
+ keys sorted recursively and array order kept. That rule is a copy of review's
365
+ request digest, so the contract is held in two places. Parts does not check a
366
+ config hash: the act carries none.
367
+
368
+ | rule | means | change |
369
+ | --- | --- | --- |
370
+ | <a id="BUST_LANDMARKS_ACT"></a>`BUST_LANDMARKS_ACT` | the `--from-act` file is unreadable, is not JSON, is not a `rig-review/act@9` act, has no `actId`, or has no `value.chestLandmarks` row | pass the chest-landmarks act review emitted, unchanged |
371
+ | <a id="BUST_LANDMARKS_ROW"></a>`BUST_LANDMARKS_ROW` | a `value.chestLandmarks[i]` field the command reads is missing or malformed: a point, `basis`, `sha256` (or a `sha256` that is not the digest of the row's `edit`), `source.hash`, `source.frame`, a shape field, or an unknown `bust` field | re-emit the act from review, unedited; the named field is the one to fix |
372
+ | <a id="BUST_LANDMARKS_SLOT"></a>`BUST_LANDMARKS_SLOT` | the row's slot is not a part of `parts.json` or not a contour mesh in `config.meshes`, its attachment is not the slot, or its skin is not `default` | place the points on the chest carrier's own slot; pass the `--parts` and `--config` the reviewed rig was built from |
373
+ | <a id="BUST_LANDMARKS_PART_ROWS"></a>`BUST_LANDMARKS_PART_ROWS` | the act has more than one row for one part | keep one chest-landmarks row for the part in review |
374
+ | <a id="BUST_LANDMARKS_ROWS"></a>`BUST_LANDMARKS_ROWS` | the act has rows for more than one part; `propose` drafts one chest carrier | keep the row for the chest carrier only |
375
+ | <a id="BUST_LANDMARKS_FRAME"></a>`BUST_LANDMARKS_FRAME` | the row's `edit.source.frame` is not `parts.json`'s `rig_size` | pass the `--parts` directory of the rig the act was made on |
376
+ | <a id="BUST_LANDMARKS_SHAPE"></a>`BUST_LANDMARKS_SHAPE` | the row's `alpha`, `clearance`, `spacing`, `bone_r` or `bone_l` differs from the config's declared `meshes.<part>.contour.bust` after defaults (with no `contour.bust`, a difference is recorded pending instead) | run again with `--write-config` to take the act's value into the config, or put the config's value back in review and emit the act again |
377
+ | <a id="BUST_LANDMARKS_OUT"></a>`BUST_LANDMARKS_OUT` | `--out` or `<out>.provenance.json` lies inside `--parts`, is the act, the config or `parts.json` (by path or as a hard link), is a directory or a read-only file, or cannot be staged or replaced | choose a path outside the parts directory that is no input, in an existing writable directory; remove a leftover `.<name>.rig-parts.tmp` the detail names |
378
+
251
379
  Drafted torso bytes change from lattice (or a figure trunk's region) to contour.
252
380
  Non-torso meshes retain their modes. A contour torso whose segments name a chain
253
381
  also declares `{ "maxInfluences": null, "floor": "continuous" }`, avoiding the
@@ -3743,6 +3871,10 @@ world units. Other proposal modes (`--keypoints`, `--compare`, `--grid-rule`,
3743
3871
  | --- | --- | --- |
3744
3872
  | <a id="PROPOSE_TORSO_ISLAND_LEFT_OUT"></a>`PROPOSE_TORSO_ISLAND_LEFT_OUT` | WARN: a non-dust island smaller than one drafted sampling cell is omitted; names its art px and rig-pixel box | inspect the omitted art; separate it if it needs its own mesh; `contour.stray` records the largest omitted island |
3745
3873
  | <a id="PROPOSE_TORSO_ISLANDS"></a>`PROPOSE_TORSO_ISLANDS` | the chest carrier has no art, equal-largest island ties, or a non-dust extra island with an art-pixel count greater than or equal to the drafted `contour.spacing` squared; the detail includes the threshold | supply art with one uniquely largest island; separate non-dust extra pieces at or above the threshold; dust keeps its existing rule, and smaller non-dust islands are omitted with `PROPOSE_TORSO_ISLAND_LEFT_OUT` |
3874
+ | <a id="PROPOSE_BUST_SIDECAR"></a>`PROPOSE_BUST_SIDECAR` | the `<landmarks>.provenance.json` beside `--bust-landmarks` cannot be read, is not JSON, or is not a well-formed `rig-parts-bust-landmarks-provenance/1` record (an unknown key, or a malformed `act`, digest, `slot`, `source` or `shape`) | write the landmarks file and its record again with `bust-landmarks`, or remove the record to use a hand-written landmarks file |
3875
+ | <a id="PROPOSE_BUST_SIDECAR_DIGEST"></a>`PROPOSE_BUST_SIDECAR_DIGEST` | the record's `landmarks_sha256` is not the sha256 of the landmarks file beside it: the file was edited after `bust-landmarks` wrote it | write both again with `bust-landmarks` from the act; to use edited points, remove the record (a hand-written file has none) |
3876
+ | <a id="PROPOSE_BUST_SIDECAR_PART"></a>`PROPOSE_BUST_SIDECAR_PART` | the record's `slot` is not the chest carrier this draft makes | redraft the parts the act was made on, or place the points on the chest carrier in review |
3877
+ | <a id="PROPOSE_BUST_PENDING"></a>`PROPOSE_BUST_PENDING` | the record holds a pending shape and `propose` would not write it: no `--write-config`, or `--cloth` or `--only-missing` | run `propose … --write-config <config.json> --bust-landmarks <landmarks.json>` into the existing config |
3746
3878
  | <a id="PROPOSE_BUST_INPUT"></a>`PROPOSE_BUST_INPUT` | a chest torso has neither a bust declaration nor an omission reason, a bust landmark is missing, malformed or unknown, the omission reason is blank or conflicts with landmarks, the midline has no unique crossing inside the apex segment, or the chest carrier is absent or ambiguous, or its recipe declares an incompatible influence mode | give finite rig-pixel apex_r/apex_l and optional cleavage, or a non-blank omission reason; separate overlapping chest-holding topwear |
3747
3879
  | <a id="PROPOSE_NECK_BODY_TURN"></a>`PROPOSE_NECK_BODY_TURN` | no authored sampled body turn | follow this recipe and supply the named input; the refusal writes no config |
3748
3880
  | <a id="PROPOSE_NECK_PLAN"></a>`PROPOSE_NECK_PLAN` | no unique neck plan row | follow this recipe and supply the named input; the refusal writes no config |
@@ -4502,6 +4634,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
4502
4634
  | `propose … --keypoints <file> [--person <id>]` | read a posed figure's joints from one explicit file (space, image size, people, each joint observed, occluded or missing, its source): a joint with a position places the neck, hip, chest or a sleeve chain as given, a note says how every joint was used or which rule stood in, and LINT reads the torso and sleeves along the joints instead of by screen y ([AUTHORING §3](AUTHORING.md)) |
4503
4635
  | `propose … --full <run> --head <run> --write-config <config>` | [draft an independent neck](AUTHORING.md#a-neck-that-moves-on-its-own) in an existing sampled body turn and reassemble its full-run source under `<out>/rig` |
4504
4636
  | `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
4637
+ | `bust-landmarks --from-act <act.json> --parts <dir> --config <config.json> --out <landmarks.json> [--write-config]` | write the file `propose --bust-landmarks` reads from the one chest row of a review `rig-review/act@9` act, with `<out>.provenance.json` beside it; `--write-config` takes the act's shape fields into the config's `contour.bust` ([drafting the chest carrier](#drafting-the-chest-carrier)) |
4505
4638
  | `propose --parts --source --out --from-config <config> [--keypoints <file> [--person <id>]]` | draw and LINT the config's current bones (by the joints too, given `--keypoints`); proposes nothing, so takes only these flags (not `--full`, `--head`, `--cloth`, `--write-config`, `--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`) |
4506
4639
  | `compare --left <file> --right <file> [--map <bonemap.json>]` | compare two skeletons — a config, a proposal or a `rig.json` — bone by bone: origin, parent, tip, length and direction per pair, the bones neither side pairs, the required ones missing, and each side's roles read off the spec; no frame is guessed, and nothing pairs by resemblance (`propose --compare` reads origins only) |
4507
4640
  | `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json` (plus `mesh_report.json` and `run.json`, `spec` `rig-run/1`), written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
@@ -6411,8 +6544,8 @@ outside the consumed inputs pending [#1177](https://github.com/rig-c/parts/issue
6411
6544
  | <a id="CHECK_SETUP_PAINTING_MEASURED"></a>`CHECK_SETUP_PAINTING_MEASURED` | missing native setup/ownership or unsupported clipping | supply observable textured setup geometry; an unavailable instrument never passes |
6412
6545
  | <a id="CHECK_BOUNDARY_COLOUR_STEP"></a>`CHECK_BOUNDARY_COLOUR_STEP` | the requirements file declares `boundary_colour.max_step_excess` and a part boundary's colour step in the rig's render exceeds the same boundary's step in the rig's own pieces by more than it; the part pair, the frame (`setup` or `idle frame <n> (t <s> s)`), the stage pixel, the excess, the declared allowance and both steps are quoted. Unlike [`CHECK_SETUP_MATCHES_PAINTING`](#CHECK_SETUP_MATCHES_PAINTING), which compares the painting per declared region at the setup pose, this compares against the rig's own flat pieces (`parts.json` placement at setup, each piece's rest colour through its art UVs on every idle frame), so a part drawn over its neighbour's line art is not a failure | the pair's rig image or mesh: `rig/images/<part>.png` (a texture stretched into its padded UVs, or a notch cut out of it), or that part's mesh in `config.json` `meshes` when the mesh cuts a corner off the art; see [Boundary colour step](#boundary-colour-step-issue-942) |
6413
6546
  | <a id="CHECK_BOUNDARY_COLOUR_UNMEASURED"></a>`CHECK_BOUNDARY_COLOUR_UNMEASURED` | `boundary_colour` is declared and the step cannot be taken: no `parts.json`, no `idle`, or a default-skin region or mesh image without a sequence, with a parts record, whose rig image is not its parts PNG with one even pad on every side (refused before anything is built); otherwise a drawn slot has no `parts.json` piece, is clipped, or its rig image is not its parts PNG with one even pad on every side (the slot and frame are named). Never a pass | make every drawn slot a `parts.json` piece, or drop `boundary_colour` from the requirements file (the bar then reports SKIP) |
6414
- | <a id="CHECK_BEHIND_PART_SEAMS"></a>`CHECK_BEHIND_PART_SEAMS` | `behind_seams` is declared and a selected pair exceeds its allowance in the independent `motion_opened` reading on an idle frame, in the `standing` reading at setup (compared against the parts' flat recomposite at their painted positions), or in the `motion_opened` reading at an opted-in named turn pose (idle and turn `standing` are not measured); the pair, behind slots, reading, frame, counted seam cells and allowance are named | repair the declared seam in `parts/<part>.png` or `config.json` (`regions`, `meshes`, or `bones`), or author its allowance in `requirements.json` (`behind_seams.allowance` or `behind_seams.pairs[].allowance`); no WARN mode or rest-visible mask; see [Behind-part seams](#behind-part-seams-issue-1314) |
6415
- | <a id="CHECK_BEHIND_PART_SEAMS_UNMEASURED"></a>`CHECK_BEHIND_PART_SEAMS_UNMEASURED` | a pair with an authored effective threshold cannot read a mandatory population: selected pair, eligible behind slots, `--parts` manifest (`parts.json` and `parts/*.png`) for setup standing's flat recomposite, idle, readable setup, motion support, boundary population, or verified render/grid/material evidence; mandatory unread evidence makes the combined line FAIL. A missing threshold alone is a nonrequired SKIP and HOLE without this refusal code | for the detail `no --parts manifest was supplied; setup standing compares the setup render with the parts' flat recomposite`, supply `parts.json` and `parts/<part>.png` (or pass `--parts <dir>` on the `rig-parts check` command line). For the detail `standing endpoints include ambiguous half-alpha owners` (measured at setup only), the line names the case and, for each case, the first endpoint in scan order with both members' alpha: *neither* member reaches 128/255 there (both members' soft edges paint the same cell, each below 128/255) or *both* do (the members' overlap reaches the gap's edge). Edit `parts/<part>.png` of one member, or its source layer, so that exactly one member reaches 128/255 at that endpoint and the other is below it or does not paint it; the corridor is then read and may fail [`CHECK_BEHIND_PART_SEAMS`](#CHECK_BEHIND_PART_SEAMS) on a real gap. A threshold at or above the cell's distance to the recomposite removes the cell from the reading altogether; the threshold decides what could count; it does not clear a cell that could. `requirements.json` `behind_seams.allowance` never clears an unread cell; removing `behind_seams.threshold` (or `behind_seams.pairs[].threshold`), or the pair from `behind_seams.pairs[]` in `requirements.json`, only silences the reading (issues #1405, #1408). When a turn pose (or idle frame) reads the `motion_opened` `HOLE` (`stock transported setup-overlap support is unavailable on every named turn pose; motion-opened is not measured`, or `stock transported setup-overlap support is unavailable on every idle frame; motion-opened is not measured`, or `both named front slots must draw on this frame`, or `no eligible slot is drawn strictly behind both pair members (including every fragment)`), give the pair's two front members a setup overlap band in `parts/<part>.png` or `config.json` (`regions`, `meshes`, or `bones`) and ensure both members and at least one rear slot in `behind_slots` draw in consistent order at setup and on every turn pose (or idle frame) so `motion_opened` can transport setup-overlap cells, or — when the pair is not a turn-tracked overlap seam — omit `behind_seams.turn` (or the pair's threshold in `requirements.json` `behind_seams`; issue #1412). For any other detail, supply the named measurement evidence in `parts/<part>.png`, `config.json` or `requirements.json` `behind_seams`; an invalid selected-pair override in `requirements.json` `behind_seams.pairs[]` also refuses by name, and existing renderer or sidecar refusals remain refusals |
6547
+ | <a id="CHECK_BEHIND_PART_SEAMS"></a>`CHECK_BEHIND_PART_SEAMS` | `behind_seams` is declared and a selected pair exceeds its allowance in the independent `motion_opened` reading on an idle frame, in the `standing` reading at setup (compared against the parts' flat recomposite at their painted positions), or in the `motion_opened` reading at an opted-in named turn pose (idle and turn `standing` are not measured); a contact-only pair's `motion_opened` (`motion_support: "setup-contact"`, issue #1409) counts the same way and, where `lower_bound_cells` is present, the count is a lower bound; the pair, behind slots, reading, frame, counted seam cells and allowance are named | repair the declared seam in `parts/<part>.png` or `config.json` (`regions`, `meshes`, or `bones`), or author its allowance in `requirements.json` (`behind_seams.allowance` or `behind_seams.pairs[].allowance`); no WARN mode or rest-visible mask; see [Behind-part seams](#behind-part-seams-issue-1314) |
6548
+ | <a id="CHECK_BEHIND_PART_SEAMS_UNMEASURED"></a>`CHECK_BEHIND_PART_SEAMS_UNMEASURED` | a pair with an authored effective threshold cannot read a mandatory population: selected pair, eligible behind slots, `--parts` manifest (`parts.json` and `parts/*.png`) for setup standing's flat recomposite, idle, readable setup, motion support, boundary population, or verified render/grid/material evidence; mandatory unread evidence makes the combined line FAIL. A missing threshold alone is a nonrequired SKIP and HOLE without this refusal code | for the detail `no --parts manifest was supplied; setup standing compares the setup render with the parts' flat recomposite`, supply `parts.json` and `parts/<part>.png` (or pass `--parts <dir>` on the `rig-parts check` command line). For the detail `standing endpoints include ambiguous half-alpha owners` (measured at setup only), the line names the case and, for each case, the first endpoint in scan order with both members' alpha: *neither* member reaches 128/255 there (both members' soft edges paint the same cell, each below 128/255) or *both* do (the members' overlap reaches the gap's edge). Edit `parts/<part>.png` of one member, or its source layer, so that exactly one member reaches 128/255 at that endpoint and the other is below it or does not paint it; the corridor is then read and may fail [`CHECK_BEHIND_PART_SEAMS`](#CHECK_BEHIND_PART_SEAMS) on a real gap. A threshold at or above the cell's distance to the recomposite removes the cell from the reading altogether; the threshold decides what could count; it does not clear a cell that could. `requirements.json` `behind_seams.allowance` never clears an unread cell; removing `behind_seams.threshold` (or `behind_seams.pairs[].threshold`), or the pair from `behind_seams.pairs[]` in `requirements.json`, only silences the reading (issues #1405, #1408). When a turn pose (or idle frame) reads the `motion_opened` `HOLE` (`stock transported setup-overlap support is unavailable on every named turn pose; motion-opened is not measured`, or `stock transported setup-overlap support is unavailable on every idle frame; motion-opened is not measured`, or `both named front slots must draw on this frame`, or `no eligible slot is drawn strictly behind both pair members (including every fragment)`, or a contact-only pair's `has no overlap band and no setup contact edge` or `setup contact support requires one drawn fragment per pair member` or `setup contact support requires unclipped pair members` detail), give the pair's two front members a setup overlap band or a setup contact edge (issue #1409) in `parts/<part>.png` or `config.json` (`regions`, `meshes`, or `bones`) and ensure both members and at least one rear slot in `behind_slots` draw in consistent order at setup and on every turn pose (or idle frame) so `motion_opened` can transport setup-overlap cells, or — when the pair is not a turn-tracked overlap seam — omit `behind_seams.turn` (or the pair's threshold in `requirements.json` `behind_seams`; issue #1412). For any other detail, supply the named measurement evidence in `parts/<part>.png`, `config.json` or `requirements.json` `behind_seams`; an invalid selected-pair override in `requirements.json` `behind_seams.pairs[]` also refuses by name, and existing renderer or sidecar refusals remain refusals |
6416
6549
  | <a id="SETUP_PAINTING_REQUIRED_LIMIT"></a>`SETUP_PAINTING_REQUIRED_LIMIT` | `setup_painting.required` is `true` and a limit the check needs is absent: `rgb_tolerance`, `regions`, or a region's `max_pixels` (the object names the region). Refused when the requirements file is read, before anything is built (issue #943) | author the named limit; none is derived from the art. Without `required` the same region reports SKIP |
6417
6550
  | <a id="SETUP_PAINTING_MOSTLY_UNCOVERED"></a>`SETUP_PAINTING_MOSTLY_UNCOVERED` | WARN only, never a refusal and never a bar (issue #1421): with neither `setup_painting.figure_mask` nor `setup_painting.backdrop` declared, more than half of a region's counted pixels are uncovered (`2 × uncovered > counted`, read off the region's `(uncovered)` slot row and its `pixel_count`; exactly half, or a region that counts nothing, does not warn). The line names the region and both figures. Without either declaration the count cannot tell painted background from missing figure, so on a scene painting the region's limit mostly measures background the rig does not draw | declare `setup_painting.figure_mask` (a figure-only rig on a scene painting) or `setup_painting.backdrop` (a full-frame painting over an opaque plate) to make the limit bind the figure; the verdict, `problems` and `check.json` do not change, and the summary line names the warning |
6418
6551
  | <a id="CHECK_SOURCE_GRID"></a>`CHECK_SOURCE_GRID` | the setup-pose still and its black-tinted twin (the coverage `SETUP_POSE_VS_SOURCE` reads) did not come back on one grid over one opaque background | a rigc problem; report it |
@@ -7213,7 +7346,7 @@ Under `--source <painting.png>`, a second reported line, also never a FAIL
7213
7346
  | <a id="CHECK_SUPPORT_GRID"></a>`CHECK_SUPPORT_GRID` | a support sidecar, part PNG or painting cannot be registered to the declared native canvas | use the same parts.json dimensions and source scale, and regenerate assemble output; no resized or guessed domain is substituted |
7214
7347
  | <a id="SETUP_MATCHES_PAINTING"></a>`SETUP_MATCHES_PAINTING` | declared region count, native box, limit and actual top contributor rows; observations source-over white unless `setup_painting.backdrop` declares the opaque plate behind a full-frame painting | PASS/FAIL against authored limits; no limit is SKIP, or the refusal `SETUP_PAINTING_REQUIRED_LIMIT` under `setup_painting.required: true`; with `--source`, no declaration is SKIP with its reason and declaration remedy; undeclared regions are not judged |
7215
7348
  | <a id="BOUNDARY_COLOUR_STEP"></a>`BOUNDARY_COLOUR_STEP` | the worst colour-step excess over the rig's own pieces at any part boundary of the setup and every idle frame, its part pair, frame and stage pixel, and the declared `max_step_excess` | PASS/FAIL against the declared allowance (FAIL is [`CHECK_BOUNDARY_COLOUR_STEP`](#CHECK_BOUNDARY_COLOUR_STEP), an unreadable piece [`CHECK_BOUNDARY_COLOUR_UNMEASURED`](#CHECK_BOUNDARY_COLOUR_UNMEASURED)); no `boundary_colour` in the requirements file is SKIP with its reason and the declaration to add, never a pass |
7216
- | <a id="BEHIND_PART_SEAMS"></a>`BEHIND_PART_SEAMS` | selected front pair and declaration provenance, per-frame `behind_slots`, core seam grid, separate `setup`, `motion_opened` and `standing` readings, sampled/read/unmeasured counts, per-frame hits, worst frame, temporal spans and spatial runs | required for pairs with an authored effective threshold: PASS/FAIL against the effective allowance, default 0; missing T is a nonrequired SKIP and HOLE, while mandatory unread evidence causes `CHECK_BEHIND_PART_SEAMS_UNMEASURED` and combined FAIL; no declaration is SKIP, and curved or diagonal openings are not certified |
7349
+ | <a id="BEHIND_PART_SEAMS"></a>`BEHIND_PART_SEAMS` | selected front pair and declaration provenance, per-frame `behind_slots`, core seam grid, separate `setup`, `motion_opened` and `standing` readings, sampled/read/unmeasured counts, per-frame hits, worst frame, temporal spans and spatial runs | required for pairs with an authored effective threshold: PASS/FAIL against the effective allowance, default 0; a contact-only pair's motion line ends `; support setup-contact` (and the frame count with `lower_bound_cells`) when it is read from setup contact edges; missing T is a nonrequired SKIP and HOLE, while mandatory unread evidence causes `CHECK_BEHIND_PART_SEAMS_UNMEASURED` and combined FAIL; no declaration is SKIP, and curved or diagonal openings are not certified |
7217
7350
 
7218
7351
  `assemble` writes optional `part_support_domains.json` beside `parts.json`, with
7219
7352
  spec `rig-parts-support-domains/1`. It binds the exact parts.json and named PNG
@@ -8384,10 +8517,11 @@ pair on that pose, or
8384
8517
  when `motion_opened` cannot read that pose), while `motion_opened` is the turn
8385
8518
  reading. When a turn pose reads the `motion_opened` `HOLE`
8386
8519
  (`stock transported setup-overlap support is unavailable on every named turn pose; motion-opened is not measured`),
8387
- give the pair a setup overlap band in `parts/<part>.png` or `config.json`
8388
- (`regions`, `meshes`, or `bones`) and keep both members and at least one rear
8520
+ give the pair a setup overlap band or a setup contact edge (a cell drawn only
8521
+ by one member beside a cell drawn only by the other) in `parts/<part>.png` or
8522
+ `config.json` (`regions`, `meshes`, or `bones`) and keep both members and at least one rear
8389
8523
  slot drawn in front/behind order across the turn poses so `motion_opened` can
8390
- transport setup-overlap support, or omit `behind_seams.turn` (or the pair's
8524
+ transport setup-overlap or setup-contact support, or omit `behind_seams.turn` (or the pair's
8391
8525
  threshold in `requirements.json`). No sweep or temporal span is claimed. Its stock transported
8392
8526
  setup-overlap evidence is computed separately with the official seam reader;
8393
8527
  the idle's exact stock binding is unchanged. One throwaway rig-c build appends a
@@ -8430,8 +8564,24 @@ The two readings are independent:
8430
8564
  turn poses). Its ordinary all-behind-hidden counterfactual must be
8431
8565
  transparent at the exact seam-cell centre, and setup attribution must show A
8432
8566
  or B covering that material. It uses no one-cell floor. A rigidly translated
8433
- closed pair stays closed; no setup overlap band means this half is unmeasured
8434
- on idle and turn.
8567
+ closed pair stays closed. A contact-only pair (issue #1409) has no setup
8568
+ overlap band: no cell drawn at 128/255 or more by both members at setup.
8569
+ When its stock transported support is otherwise complete (every idle frame or
8570
+ turn pose drawn), `motion_opened` reads it from its setup contact edges
8571
+ instead: each edge between a cell drawn only by A and a cell drawn only by B
8572
+ at setup is carried to the frame by both members' meshes, and the cells that
8573
+ the carried edge sweeps, drawn by neither member there, are the frame's
8574
+ candidates; a candidate counts under the same hidden/full/rear tests as a
8575
+ band cell when either member's map carries it back onto that member's setup
8576
+ material. Such a frame, pose and pair carry `motion_support: "setup-contact"`.
8577
+ A swept cell that passes those tests but that neither map carries back onto
8578
+ setup material is not counted; the frame or pose then records the number in
8579
+ `lower_bound_cells` and its count is a lower bound (the pair's
8580
+ `lower_bound_frames` or `lower_bound_poses` counts such rows). Each member must
8581
+ draw one fragment at setup and on the frame, and no clip may cut either
8582
+ member there (a clipped drawing is not its attachment's, so it cannot be
8583
+ carried through the attachment map); otherwise the frame is a named `HOLE`. A pair with neither an overlap band nor a contact edge stays
8584
+ unmeasured on idle and turn.
8435
8585
  - `standing` is measured at `setup` against the parts' flat recomposite at their
8436
8586
  painted positions (issues #1408, #1412); it is not measured on idle frames or
8437
8587
  turn poses. At `setup`, it
@@ -8551,8 +8701,9 @@ evidence does not remove a measured hit.
8551
8701
  | `unread_corridors[].endpoints[][2]` | World-space x coordinate of the endpoint cell centre. |
8552
8702
  | `unread_corridors[].endpoints[][3]` | World-space y coordinate of the endpoint cell centre, y up. |
8553
8703
  | `unread_corridors[].endpoints[][4]` | Observed half-alpha owner code: 0 means neither A nor B reaches 128/255; 1 means only A does; 2 means only B does; 3 means both do. A and B are the selected pair's named members; 0 and 3 are not resolved by guessing. |
8554
- | `unread_corridors[].cells` | Interior native-cell centres as numeric `[world_x, world_y]` tuples, y up, left-to-right or top-to-bottom along the run, leaving out cells within T of the parts' recomposite at setup. A centre may occur in multiple corridors. |
8555
- | `unread_corridors[].cell_count` | The number of reported interior cells in this corridor (at setup, leaving out cells within T of the recomposite), exactly `cells.length`. |
8704
+ | `unread_corridors[].cells` | Interior native-cell centres as numeric `[world_x, world_y]` tuples, y up, left-to-right or top-to-bottom along the run, leaving out cells within T of the parts' recomposite at setup, capped at 64 evenly spaced entries (`floor(j · cell_count / 64)`, `j = 0 … 63`, when `cell_count > 64`; all `cell_count` entries when `cell_count <= 64`). A centre may occur in multiple corridors. |
8705
+ | `unread_corridors[].cell_count` | The corridor's full count of unread interior cells (at setup, leaving out cells within T of the recomposite), equal to `cells.length + (cells_omitted ?? 0)`. |
8706
+ | `unread_corridors[].cells_omitted` | Optional positive integer, present only when `cell_count > 64`: the unread interior cells left out of `cells` (`cell_count - cells.length`). |
8556
8707
  | `unread_corridors[].row_scope` | `pair`; the corridor observes the selected front pair, not an individual rear slot. |
8557
8708
  | `unread_corridors[].row_kind` | `evidence`, including when the required check fails. |
8558
8709
  | `unread_corridors[].row_subjects` | The two selected part names in producer A/B order. |
@@ -9662,18 +9813,18 @@ Internal `SeamSupport.drawings` never enters check JSON. Named requirement
9662
9813
  | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for e.slot; otherwise [] | [check.ts:3697](../src/check.ts#L3697) |
9663
9814
  | `ANIMATIONS_DO_NOT_FOLD.folding` | `ANIMATIONS_DO_NOT_FOLD.folding` | part when the supplied mapping resolves a piece; otherwise rig | finding when entry === undefined; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:3659](../src/check.ts#L3659) |
9664
9815
  | `ART_JOINT_DISTANCE.joints` | `ART_JOINT_DISTANCE.joints` | 'rig' | finding when status === 'FAIL'; otherwise evidence | [] | [artjoints.ts:86](../src/artjoints.ts#L86) |
9665
- | `BEHIND_PART_SEAMS.contributors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples[].contributors`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples[].contributors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:526](../src/behindseams.ts#L526) |
9666
- | `BEHIND_PART_SEAMS.hits` | `BEHIND_PART_SEAMS.pairs[].motion_opened.frames`; `BEHIND_PART_SEAMS.pairs[].standing.frames`; `BEHIND_PART_SEAMS.pairs[].motion_opened.worst`; `BEHIND_PART_SEAMS.pairs[].standing.worst` | 'pair' | finding when r.px > allowance; otherwise evidence | parts | [behindseams.ts:608](../src/behindseams.ts#L608) |
9667
- | `BEHIND_PART_SEAMS.pairs` | `BEHIND_PART_SEAMS.pairs` | 'pair' | finding when failed; otherwise evidence | parts | [behindseams.ts:693](../src/behindseams.ts#L693) |
9816
+ | `BEHIND_PART_SEAMS.contributors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples[].contributors`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples[].contributors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:664](../src/behindseams.ts#L664) |
9817
+ | `BEHIND_PART_SEAMS.hits` | `BEHIND_PART_SEAMS.pairs[].motion_opened.frames`; `BEHIND_PART_SEAMS.pairs[].standing.frames`; `BEHIND_PART_SEAMS.pairs[].motion_opened.worst`; `BEHIND_PART_SEAMS.pairs[].standing.worst` | 'pair' | finding when r.px > allowance; otherwise evidence | parts | [behindseams.ts:750](../src/behindseams.ts#L750) |
9818
+ | `BEHIND_PART_SEAMS.pairs` | `BEHIND_PART_SEAMS.pairs` | 'pair' | finding when failed; otherwise evidence | parts | [behindseams.ts:838](../src/behindseams.ts#L838) |
9668
9819
  | `BEHIND_PART_SEAMS.pairs[].frames` | `BEHIND_PART_SEAMS.pairs[].frames` | | | | |
9669
9820
  | `BEHIND_PART_SEAMS.pairs[].setup` | `BEHIND_PART_SEAMS.pairs[].setup` | | | | |
9670
- | `BEHIND_PART_SEAMS.samples` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:525](../src/behindseams.ts#L525) |
9671
- | `BEHIND_PART_SEAMS.spans` | `BEHIND_PART_SEAMS.pairs[].motion_opened.spans`; `BEHIND_PART_SEAMS.pairs[].standing.spans` | 'pair' | evidence | parts | [behindseams.ts:616](../src/behindseams.ts#L616) |
9672
- | `BEHIND_PART_SEAMS.turn.pairs` | `BEHIND_PART_SEAMS.turn.pairs` | 'pair' | finding when required; otherwise evidence; finding when motion.status === 'FAIL' &#124;&#124; standing.status === 'FAIL' &#124;&#124; threshold !== null && read !== turn.poses.length; otherwise evidence | [pair.a, pair.b]; parts | [behindseams.ts:723](../src/behindseams.ts#L723), [behindseams.ts:773](../src/behindseams.ts#L773) |
9821
+ | `BEHIND_PART_SEAMS.samples` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:663](../src/behindseams.ts#L663) |
9822
+ | `BEHIND_PART_SEAMS.spans` | `BEHIND_PART_SEAMS.pairs[].motion_opened.spans`; `BEHIND_PART_SEAMS.pairs[].standing.spans` | 'pair' | evidence | parts | [behindseams.ts:758](../src/behindseams.ts#L758) |
9823
+ | `BEHIND_PART_SEAMS.turn.pairs` | `BEHIND_PART_SEAMS.turn.pairs` | 'pair' | finding when required; otherwise evidence; finding when motion.status === 'FAIL' &#124;&#124; standing.status === 'FAIL' &#124;&#124; threshold !== null && read !== turn.poses.length; otherwise evidence | [pair.a, pair.b]; parts | [behindseams.ts:870](../src/behindseams.ts#L870), [behindseams.ts:923](../src/behindseams.ts#L923) |
9673
9824
  | `BEHIND_PART_SEAMS.turn.pairs[].frames` | `BEHIND_PART_SEAMS.turn.pairs[].frames` | | | | |
9674
- | `BEHIND_PART_SEAMS.turn.unmeasured` | `BEHIND_PART_SEAMS.turn.unmeasured` | pair === null ? 'rig' : 'pair' | finding when mandatory; otherwise evidence | pair === null ? [] : [pair.a, pair.b] | [behindseams.ts:715](../src/behindseams.ts#L715) |
9675
- | `BEHIND_PART_SEAMS.unmeasured` | `BEHIND_PART_SEAMS.unmeasured` | pair === null ? 'rig' : 'pair'; 'rig' | finding when required; otherwise evidence; finding | pair === null ? [] : [pair.a, pair.b]; [] | [behindseams.ts:629](../src/behindseams.ts#L629), [behindseams.ts:974](../src/behindseams.ts#L974), [behindseams.ts:1022](../src/behindseams.ts#L1022) |
9676
- | `BEHIND_PART_SEAMS.unread_corridors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.unread_corridors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:459](../src/behindseams.ts#L459) |
9825
+ | `BEHIND_PART_SEAMS.turn.unmeasured` | `BEHIND_PART_SEAMS.turn.unmeasured` | pair === null ? 'rig' : 'pair' | finding when mandatory; otherwise evidence | pair === null ? [] : [pair.a, pair.b] | [behindseams.ts:862](../src/behindseams.ts#L862) |
9826
+ | `BEHIND_PART_SEAMS.unmeasured` | `BEHIND_PART_SEAMS.unmeasured` | pair === null ? 'rig' : 'pair'; 'rig' | finding when required; otherwise evidence; finding | pair === null ? [] : [pair.a, pair.b]; [] | [behindseams.ts:771](../src/behindseams.ts#L771), [behindseams.ts:1125](../src/behindseams.ts#L1125), [behindseams.ts:1173](../src/behindseams.ts#L1173) |
9827
+ | `BEHIND_PART_SEAMS.unread_corridors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.unread_corridors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:585](../src/behindseams.ts#L585) |
9677
9828
  | `BOUNDARY_COLOUR_STEP.over` | `BOUNDARY_COLOUR_STEP.over` | 'pair' | finding | r.parts | [boundarycolour.ts:221](../src/boundarycolour.ts#L221) |
9678
9829
  | `BOUNDARY_COLOUR_STEP.unmeasured` | `BOUNDARY_COLOUR_STEP.unmeasured` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for r.slot; otherwise [] | [boundarycolour.ts:222](../src/boundarycolour.ts#L222) |
9679
9830
  | `CLOTH_SETTLES.rows` | `CLOTH_SETTLES.rows` | 'rig' | finding when speeds.length > 0 && s < speeds.length; otherwise evidence | [] | [check.ts:6144](../src/check.ts#L6144) |