rig-parts 1.85.0 → 1.87.0

package/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { applyTakenLayers } from './src/takelayers.ts';
+import { applyDepth, prepareDepth } from './src/depthworkflow.ts';
 /**
  * rig-parts — one painting and its See-through layers in, Spine-ready parts
  * and rig specs out, verified through rig-c.
@@ -67,6 +68,16 @@ const LATER: ReadonlyArray<[string, string]> = [];
 const HELP = `rig-parts ${version()} — Spine-ready parts from one painting and its See-through layers
 
 usage:
+  rig-parts depth-prepare --parts <assembled-dir> --config <depth-recipe.json> --out <empty-dir>
+      Write per-part inference PNGs on neutral gray, upscaled and padded as
+      declared, plus a source-hashed manifest. No model is bundled or called.
+
+  rig-parts depth-apply --parts <assembled-dir> --manifest <manifest.json> --config <depth-recipe.json> --rig-config <config.json> --out <empty-dir>
+      Register floating-point JSON depth or signed normals, normalize inside
+      alpha >=128, apply declared median/relief and group near/zScale/pivot,
+      extend past alpha, and write parts, relocated config and depth-report.json.
+      Normals require one closed convex island. See AUTHORING for the schemas.
+
   rig-parts layers <dir | layers.json | file.psd>
       Read a See-through decomposition — the ComfyUI wrapper form (a directory
       holding layers.json and one PNG per layer) or an upstream .psd — and print
@@ -1077,6 +1088,8 @@ function printLayerTable(set: LayerSet): void {
  * no row; `layers` takes one positional path beside its flags (issue #359).
  */
 const TAKES = {
+  'depth-prepare': { valued: ['--parts', '--config', '--out'], switches: [] },
+  'depth-apply': { valued: ['--parts', '--manifest', '--config', '--rig-config', '--out'], switches: [] },
   layers: { valued: ['--export', '--template', '--canvas', '--full', '--source', '--config'], switches: [] },
   sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: [] },
   rig: { valued: ['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
@@ -2181,6 +2194,27 @@ function cmdPainting(args: string[]): number {
   }
 }
 
+function cmdDepthPrepare(args: string[]): number {
+  const f = flags(args, 'depth-prepare', ['--parts', '--config', '--out']);
+  if (typeof f === 'string') return usage(f);
+  try {
+    const result = prepareDepth({ parts: f.get('--parts')!, config: f.get('--config')!, out: f.get('--out')! });
+    console.log(`depth-prepare: ${result.parts.length} part(s); manifest.json binds crop, padding and source/input hashes`);
+    return EXIT_OK;
+  } catch (error) { return printRefusal(error); }
+}
+
+function cmdDepthApply(args: string[]): number {
+  const f = flags(args, 'depth-apply', ['--parts', '--manifest', '--config', '--rig-config', '--out']);
+  if (typeof f === 'string') return usage(f);
+  try {
+    const result = applyDepth({ parts: f.get('--parts')!, manifest: f.get('--manifest')!, config: f.get('--config')!, rigConfig: f.get('--rig-config')!, out: f.get('--out')! });
+    for (const row of result.parts as Array<Record<string, unknown>>) console.log(`depth-apply: ${row.part} levels=${row.levels} clip=${row.clipFraction} reliefRigPixels=${row.reliefRigPixels} sign=${row.sign}`);
+    console.log('depth-apply: wrote registered parts, config.json and depth-report.json; run rig for the core gate');
+    return EXIT_OK;
+  } catch (error) { return printRefusal(error); }
+}
+
 function main(argv: string[]): number | Promise<number> {
   const [command, ...rest] = argv;
   if (command === undefined || command === '--help' || command === '-h' || command === 'help') {
@@ -2192,6 +2226,8 @@ function main(argv: string[]): number | Promise<number> {
     return EXIT_OK;
   }
   if (command === 'layers') return cmdLayers(rest);
+  if (command === 'depth-prepare') return cmdDepthPrepare(rest);
+  if (command === 'depth-apply') return cmdDepthApply(rest);
   if (command === 'sheet') return cmdSheet(rest);
   if (command === 'rig') return cmdRig(rest);
   if (command === 'propose') return cmdPropose(rest);

package/docs/AUTHORING.md

@@ -5120,6 +5120,28 @@ wind (1, 0), then (40, 0) from 0.5 s, reads `TEXTURE_STRETCH` 32.181 (FAIL, `hai
 triangle 258), two meshes folding under `ANIMATIONS_DO_NOT_FOLD` (FAIL; none without the
 flag) and 8 `CLOTH_SETTLES` warnings for 9 (selftest `CK515`).
 
+**Joint material contact** (issue #894). Each played `SEAM_OVER_MOTION.rows[]` adds
+`joint_contact`: `status` (`REPORTED` or `SKIP`), `joints` (declared limb joint
+labels or a proven body root's bone), and, when observed, the frame counts
+`joined`, `separated` and `unavailable`, plus `reasons` with each unavailable
+reason and its observed frame indices. `JOINT_CONTACT` prints one informational
+line per pair and animation; it is never a bar and changes no PASS, warning or
+exit status. It counts core 2.84.0's `jointContact.frames` from the same seam
+render. Core reads edge-connected half-opacity material: initially overlapping
+single-component pieces are joined when their posed union connects by an edge
+or overlap, separated when it does not. A diagonal contact is separated. Missing
+setup overlap, absent drawings, disconnected material or multiple fragments are
+unavailable with core's reason. A pair without a declared named joint is
+unavailable even if its arbitrary slot drawings connect. An absent core contact
+field is unavailable when the frame count is known; absent frame counts or zero
+samples are SKIP with a reason, never invented joined frames. Unavailable is
+never added to joined. No pair or animation is a named SKIP in the output.
+Contact reports material connectivity at core's texel grid, not anatomical
+intent, sub-cell contact or the absence of local holes. Raw gap, ghost, floor
+and body-root verdicts keep their existing producer readings. Core 2.83.0's
+visible-ghost and local-support gap definitions are inherited by the 2.84.0 pin;
+contact counts do not replace or reinterpret them.
+
 **Physics seam environments** (issue #591). Default: wind [1, 0], gravity [0, 1]. Still: wind [0, 0], gravity [0, 1]. In rig-play, environment(null) returns to Default; still air requires an explicit wind [0, 0]. For a physics rig with readable declared pairs and animations, SEAM_OVER_MOTION adds optional `worlds.default` and `worlds.still` readings. They are informational raw gap/ghost cell counts (including cells below the warning floor), never new bars or warnings; neither changes PASS, exit status or the bar count. Each world records its vectors, status and rows; each row names its pair, animation, drawn/banded frames and gap/ghost maximum and worst frame, cell size and world box. Per-frame hits are not embedded in check.json. A rendered world's `dir` is relative to check.json (`seam_motion/default` or `seam_motion/still`): it retains the complete rigc render, including frames.json, frame images and each animation's seam.json with all raw hits. The directories are published with check.json only after the readings are validated; scratch is removed, and an unrendered SKIP has no directory reference. The original reading and any custom `--environment` schedule keep their existing meaning; the two reference worlds are independent of that schedule. A rig with no wind response reports Still as SKIP with its reason; no band is SKIP, never a measured zero. With no readable declared pair or animation no worlds block is written. The same declared pair list is used for both reference worlds: neighbouring limb segments, explicit seam requirements and the proven body-root declarations described below. Thigh/hem pairs are not inferred. Adding reference worlds to a nonphysics reading stays byte-identical, with no extra key, line or render; issue #686 separately adds body-root declarations and their active-reading bar. Reference renders start physics at frame 0 at 12 fps; they do not certify a composed player scene or another sampling rate. Malformed sidecars or renderer failures remain named refusals.
 
 **Steady-wind seam band** (`--wind-band`, issue #590). `check --wind-band <spec.json>` (or `build --wind-band <spec.json>`, forwarded) sweeps steady horizontal wind across a caller-declared grid and reports the contiguous `[x_lo, x_hi]` band in which each declared seam pair holds `gap <= max_gap` and `ghost <= max_ghost` across every animation in `motion.json`. Every field in `{ "spec": "rig-parts-wind-band/1", "min", "max", "step", "fps", "max_gap", "max_ghost", "pairs" }` is required — nothing falls back to `SEAM_OVER_MOTION`'s pairs, one-cell floor, or fps. At each swept step `x = min + k * step`, `check` runs `rigc render --seam <pairs> --fps <fps> --max 16 --environment` with a single-step steady schedule `{ "spec": "rigc-environment/1", "steps": [{ "t": 0, "wind": [x, 0], "gravity": [0, 1] }] }` (`seam.json` cells are in each pair's coarser drawing texels, independent of `--max`). **What it does not measure:** the sweep is steady wind (`wind: [x, 0], gravity: [0, 1]` at `t = 0`), not a time-varying gust (`x ± a` at 0.2 Hz); transient overshoot from a changing wind is not read by a steady sweep, and the band is documented and reported as the steady-wind band (`mode: "steady"`, `gravity: [0, 1]`). It is a reported line (`status: "REPORTED"`), never a bar: it prints one `WIND_BAND:` summary line plus one `WIND_BAND:` line per pair that breaks inside `[min, max]`, and writes `WIND_BAND` in `check.json` before `PASS`.
@@ -6564,6 +6586,131 @@ and never assign a role, depth, binding or draw order. A part already bound to
 its actual intended role, then inspect setup, both turn endpoints and their diff;
 an explicit role alone does not establish that two drawings remain coincident.
 
+### Per-part provider maps (#897)
+
+`depth-prepare` and `depth-apply` are explicit stages after `assemble`, before
+`rig`. They carry no model, weights, provider service or downloads. Prepare
+writes one inference PNG per selected assembled part, composited onto gray 128,
+with integer LANCZOS upscaling and padding. A `rig-parts-depth-inputs/1` manifest
+binds the original parts.json hash, part PNG hash, rig crop `[x,y,w,h]`, native
+and upscaled sizes, padding, recipe hash and inference PNG hash. Map registration
+is declared, never inferred from a filename or guessed from art.
+
+```sh
+rig-parts depth-prepare --parts assembled --config depth.json --out inference
+# A provider reads inference/*.png and writes the declared floating-point maps.
+rig-parts depth-apply --parts assembled --manifest inference/manifest.json --config depth.json --rig-config config.json --out mapped
+rig-parts rig --parts mapped --config mapped/config.json --out compiled
+```
+
+The separate recipe is not a new field on character config:
+
+```json
+{
+  "spec": "rig-parts-depth/1",
+  "prepare": {"longSide": 1024, "paddingFraction": 0.08, "padding": 4},
+  "groups": {"head": {"near": "white", "zScale": 30, "pivot": 15}},
+  "parts": {
+    "face": {"map": "face.json", "source": "depth", "frame": "part", "group": "head", "median": 21, "relief": 13}
+  },
+  "clear": []
+}
+```
+
+All displayed numbers are authored example choices, not defaults. `longSide`
+and additive `padding` are integers; upscale is `max(1,ceil(longSide/max(w,h)))`
+and pad is `floor(max(upscaledSize)*paddingFraction)+padding`. Each part declares
+`median` and nonnegative `relief` in rig pixels. Each group (`head` or `body`)
+declares `near`, positive `zScale` and `pivot`; optional `unitDepths` explicitly
+replaces that group's rigid depths. `clear` explicitly lists part references to
+remove, including any small units intended to sample the surface. Unselected
+parts retain their artwork and depth references. The output config copies the
+original, sets the declared group pivots/unit depths, and relocates animation,
+requirements and control-skeleton file paths. Built-in skeleton names remain
+names. A selected part whose provenance records `depth.kind: "authored-unit"`
+is refused before output (`DEPTH_AUTHORED_UNIT_CONFLICT`); apply does not invent
+a transition to a transported scalar reference. Unselected authored units keep
+their original representation. Roles and draw order stay the author's.
+
+Maps are UTF-8 JSON `{"spec":"rig-parts-map/1","width":2,"height":2,
+"channels":1,"data":[0.125,0.25,0.5,0.875]}`: row-major finite numeric values,
+with channels interleaved for signed XYZ normals (`channels:3`). JSON is open,
+lossless for binary64 numbers, and requires no numeric-array dependency; an
+8-bit preview cannot preserve the raw map's normalization. Paths resolve beside
+the recipe. `frame:"part"` requires native part dimensions; `"upscaled"` requires
+the prepared art's enlarged dimensions without padding; `"input"` requires the
+whole prepared image and crops its declared padding before reduction. Scalar
+maps use float32 BOX reduction. Normal sources require signed image-axis XYZ
+(x right, y down), not an RGB normal preview.
+
+Apply computes `u=(raw-median(raw))/(p95-p5)` inside original alpha >=128,
+using linear percentiles, then `Z=median+relief*u`. A flat map requires explicit
+relief 0. Encode `Z/zScale` for near white, `1-Z/zScale` for near black, clip to
+[0,1], and round to the nearest 8-bit level with even ties. Extend every
+non-support pixel with the Euclidean nearest support value, with row-major ties.
+The resulting opaque gray sheet carries no background cliff. The report names
+levels, clip fraction (Z <=0 or >=zScale on support), declared relief in rig
+pixels, group pivot, sign, raw median/p5/p95 and source/input/map/sheet hashes.
+It reports measurements, not a depth-quality pass mark. `rig` still runs Core's
+gate; apply writes parts and configuration, never a skeleton or a gate verdict.
+Outputs must be absent or empty; all declared inputs validate before emitting.
+
+`source:"normals"` is optional and limited to one closed convex part. It refuses
+multiple four-connected alpha islands both before and after stride2 sampling.
+At half resolution it integrates adjacent gradients `-nx/max(abs(nz),0.15*norm)`
+and `-ny/max(abs(nz),0.15*norm)` with step2 trapezoids and matrix-free LSQR
+(maximum 3000 iterations, atol/btol 1e-6, condition limit 1e8). Cross erosion
+finds an interior core (max(3,floor(0.12*sqrt(area))) steps) and a three-step rim.
+The sign makes mean core depth greater than mean rim depth; no reference is
+read. An empty core or unresolved sign refuses. Before float32 BOX, unsupported
+integration-grid samples receive the Euclidean nearest supported float height,
+with row-major ties; supported integrated heights are unchanged. This fill uses
+the stride2 integration mask itself, not the native mask or encoded gray levels,
+so unsupported zeros cannot enter a supported native pixel through BOX. BOX
+then brings the field back to the native grid before the same normalization.
+Normalization still reads all native alpha>=128 support; a boundary repair can
+change its percentiles and therefore interior levels too. Iterations and
+residual are reported. One connected silhouette does not certify convexity or
+exclude internal occlusion edges; choose scalar depth for strands and collars.
+
+The [provider trial](https://github.com/rig-c/parts/issues/897) measured Depth
+Anything V2 Large and Small, DA3MONO-LARGE, DepthPro, Lotus depth/normal G,
+Marigold depth, and bundled MiDaS/Zoe/LeReS/Metric3D routes. DA3 and Small rows
+were added after the initial report. The stage2 reproduction uses V2 Large
+with the Lotus-normal face, not DA3. No model is required by these commands.
+The trial's role relief/width ratios (face 0.1264803, front hair 0.1018772,
+back hair 0.0857722, ornament 0.0375868, garment 0.0990473) came from one
+head-turn demo's p5..p95 depth and part widths. They are measured starting
+points for declared proportions, not anatomical laws or default calibration.
+The owner's preference for per-part volume is subjective provenance, not an
+automated quality conclusion. Model licence posture remains the owner's choice.
+
+`depth.full.layers` and `depth.head.layers` still accept authored source-grid
+sheets. They bind the See-through layer before assembly transports/scales/crops
+it; they do not bind an already assembled part's post-merge image. Use them
+when a sheet genuinely occupies that source grid. The commands above bind the
+final assembled grid and preserve the existing `parts.json` reference consumed
+by `rig`, so their output requires no alternate compiler or dependency pin.
+
+| rule | refused input | remedy |
+| --- | --- | --- |
+| <a id="DEPTH_RECIPE"></a>`DEPTH_RECIPE` | unknown, absent or wrongly typed recipe field, group, source or frame | use the documented explicit recipe schema; no guessed field |
+| <a id="DEPTH_RECIPE_NUMBER"></a>`DEPTH_RECIPE_NUMBER` | missing/nonfinite median, relief, near-scale pivot or prepare number; invalid range/integer | declare every numeric field in its documented units and range |
+| <a id="DEPTH_INPUT_PRESENT"></a>`DEPTH_INPUT_PRESENT` | declared JSON input missing or not a file | restore the named file |
+| <a id="DEPTH_INPUT_JSON"></a>`DEPTH_INPUT_JSON` | malformed numeric or configuration JSON | write valid finite JSON |
+| <a id="DEPTH_PART_RESOLVES"></a>`DEPTH_PART_RESOLVES` | selected or cleared name absent from parts.json | use the assembled part name |
+| <a id="DEPTH_OUTPUT_EMPTY"></a>`DEPTH_OUTPUT_EMPTY` | nonempty output or output containing an input | choose a separate absent or empty directory |
+| <a id="DEPTH_INPUT_BINDING"></a>`DEPTH_INPUT_BINDING` | changed recipe, art, part record, crop, padding or inference PNG | prepare again for these exact inputs |
+| <a id="DEPTH_MAP_FORMAT"></a>`DEPTH_MAP_FORMAT` | wrong numeric schema, channels, shape, count, unknown field or nonfinite element | provide the declared float JSON map, not a preview |
+| <a id="DEPTH_MAP_SIZE"></a>`DEPTH_MAP_SIZE` | map dimensions differ from its explicit frame | use the registered part, enlarged art or padded input grid |
+| <a id="DEPTH_MAP_SUPPORT"></a>`DEPTH_MAP_SUPPORT` | no alpha>=128 support | provide a supported part |
+| <a id="DEPTH_MAP_SPREAD"></a>`DEPTH_MAP_SPREAD` | p5=p95 with nonzero relief | supply a nonflat map or declare relief 0 |
+| <a id="DEPTH_NORMAL_ISLANDS"></a>`DEPTH_NORMAL_ISLANDS` | zero/multiple connected components at native or integration resolution | scalar source, or a larger registered normal input that preserves one island |
+| <a id="DEPTH_NORMAL_VECTOR"></a>`DEPTH_NORMAL_VECTOR` | a sampled support normal is zero | provide nonzero signed XYZ normals |
+| <a id="DEPTH_NORMAL_CONVEXITY"></a>`DEPTH_NORMAL_CONVEXITY` | core/rim or its convexity sign is unresolved | larger closed convex mask or scalar source |
+| <a id="DEPTH_GROUP_BINDING"></a>`DEPTH_GROUP_BINDING` | part outside declared turn roles, mixed retained near/zScale, or filename collision | register exact roles and one shared scale/polarity, replace/clear conflicting sheets, use distinct names |
+| <a id="DEPTH_AUTHORED_UNIT_CONFLICT"></a>`DEPTH_AUTHORED_UNIT_CONFLICT` | a selected part already records `provenance.depth.kind: "authored-unit"`; adding scalar depth would make its two representations conflict | retain the authored unit or supply an explicitly reassembled scalar-compatible input; apply never replaces the provenance automatically |
+
 ### Unit depth precedence
 
 For `"unit"` roles, a transported part's sheet is recorded and validated but is not

package/docs/STABILITY.md

@@ -49,6 +49,8 @@ defaults are the help's too, and none is guessed from the art.
 <!-- stable:commands -->
 | command | flags |
 | --- | --- |
+| `depth-prepare` | `--parts`, `--config`, `--out` (issue #897; separate numeric-depth recipe) |
+| `depth-apply` | `--parts`, `--manifest`, `--config`, `--rig-config`, `--out` (issue #897; original character config is read-only) |
 | `layers` | one positional path: a wrapper directory, a `layers.json` or a `.psd`; with it, optional `--export` (a directory to write the wrapper form into, issue #359); or `--template` with `--canvas` and no path; or a positional head run with `--full`, `--source`, `--config` together for `PLAN_HEAD_GARMENT_OVERLAP` (issue #826) |
 | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols` |
 | `inputs` | `--source`, `--config`, `--out` |
@@ -525,3 +527,16 @@ only for that explicit block; `check --requirements` refuses unavailable or
 stale evidence rather than reconstructing original art from emitted siblings.
 Without the block the API reading is SKIP; CLI stdout and emitted bytes remain unchanged.
 See [Source before scissors](AUTHORING.md#source-before-scissors).
+
+## Provider-map depth stages (#897)
+
+The opt-in `depth-prepare` and `depth-apply` commands accept the separate
+`rig-parts-depth/1` recipe and finite floating-point `rig-parts-map/1` JSON.
+Prepared provenance is `rig-parts-depth-inputs/1`; application writes
+`rig-parts-depth-report/1`, standard part depth references and a relocated
+character config. Their schemas, frames, alpha threshold, normalization,
+encoding, convexity sign and refusal remedies are in
+[AUTHORING](AUTHORING.md#per-part-provider-maps-897). No existing build path
+calls these stages; no-config builds retain their existing behavior and bytes.
+Group numbers and unit depths are explicit; no provider or absolute scale is
+inferred. A new depth stage never replaces Core's rig gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.85.0",
+  "version": "1.87.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "@rig-c/core": "2.82.0"
+    "@rig-c/core": "2.84.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/build.ts

@@ -81,7 +81,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, CLOTH_LINE, type ClothLine, clothWarnText, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, readCheckEnvironment, readWindBand, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR, WIND_BAND_LINE, windBandLines } from './check.ts';
+import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, CLOTH_LINE, type ClothLine, clothWarnText, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, motionJointContactLines, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, readCheckEnvironment, readWindBand, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR, WIND_BAND_LINE, windBandLines } from './check.ts';
 import { type Cut, type Extend, type Limb, loadConfigAndAnimations, loadConfigWithBytes, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
 import { coreCompileGuideLine, failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from '@rig-c/core/mesh';
@@ -1824,7 +1824,7 @@ export function sweepCheckLines(line: SweepLine, steps: ReadonlyMap<string, { le
 export function motionSeamLines(line: MotionSeamLine, plant: MotionSeamPlant = {}): string[] {
   const unmeasured = (line.roots?.unmeasured ?? []).map(root => `root pair for ${root.limb} (${root.part}, bone "${root.bone}", parent "${root.parent}", candidates ${root.candidates.join('/')}): SKIP — ${root.reason}`);
   const rootStatus = line.roots === undefined ? '' : '; body-root gap-open+under-ghost gate ' + line.roots.status + ' (' + line.roots.pairs.length + ' pair(s)); ghost ownership from resolved draw order' + (line.roots.reason === undefined ? '' : ' — ' + line.roots.reason);
-  if (line.worlds === undefined && line.status === 'SKIP' && line.rows.length === 0 && line.pairs.every((p) => p.unread === undefined)) return [`${MOTION_SEAM_LINE}: SKIP — ${String(line.reason)}${unmeasured.length === 0 ? '' : rootStatus}`, ...unmeasured];
+  if (line.worlds === undefined && line.status === 'SKIP' && line.rows.length === 0 && line.pairs.every((p) => p.unread === undefined)) return [`${MOTION_SEAM_LINE}: SKIP — ${String(line.reason)}${unmeasured.length === 0 ? '' : rootStatus}`, ...unmeasured, ...motionJointContactLines(line)];
   const read = `${line.pairs.length} declared pair(s) in ${line.animations.length} animation(s) (${line.animations.join(', ')}), read by rigc render --seam at ${line.fps} fps on the build as played`;
   const head =
     line.status === 'SKIP'
@@ -1832,6 +1832,7 @@ export function motionSeamLines(line: MotionSeamLine, plant: MotionSeamPlant = {
       : `${MOTION_SEAM_LINE}: ${line.status} — ${read}: ${line.warnings} warning(s), never a bar${rootStatus}; ${line.floor}`;
   return [
     head,
+    ...motionJointContactLines(line),
     ...unmeasured,
     ...line.pairs.filter((p) => p.unread !== undefined).map((p) => `seam "${p.pair}" (${p.declared.join('; ')}): not read — ${String(p.unread)}`),
     ...line.rows.filter((r) => r.status === 'skip').map((r) => `seam "${r.pair}" in "${r.animation}": SKIP — rigc read no band on any of the ${r.drawn} frame(s) both slots draw, so there is no seam to read`),

package/src/check.ts

@@ -83,6 +83,7 @@ import { baseAnchorMoves, type AnchorRegion } from './baseanchor.ts';
  * the last idle frame is refused unless it sits at t = duration (within
  * `TIME_SLACK`, issue #244).
  */
+import { jointContactReading, type JointContactReading } from './jointcontact.ts';
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import type { Viewport as RootCoverageViewport } from '@rig-c/core/render-shared';
@@ -4341,6 +4342,8 @@ export interface MotionSeamPair {
   a: string;
   b: string;
   declared: string[];
+  /** Explicit limb joint labels or a proven body root's bone; never inferred for arbitrary seams. */
+  joints?: string[];
   /** Why the pair is not read: a slot `rig.json` does not have. */
   unread?: string;
   /** Issue #686: segment-zero provenance and its immediate named body carrier. */
@@ -4374,6 +4377,8 @@ export interface MotionSeamSelection {
 export interface MotionSeamRow {
   pair: string;
   animation: string;
+  /** Report-only core connectivity, independent of raw counts and verdicts. */
+  joint_contact?: JointContactReading;
   /** rigc's: `skip` when no frame has a band to read — nothing measured, not a seam that held. */
   status: 'read' | 'skip';
   /** Frames both slots draw, and of those the frames read (rigc's `drawn`, `banded`). */
@@ -4426,10 +4431,12 @@ export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: s
 export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ name: string; part: string; neighbour: string }>, rig?: Record<string, unknown>, readSetup?: (candidates: readonly MotionSeamPair[]) => readonly MotionRootSetupRow[]): MotionSeamSelection {
   const out: MotionSeamPair[] = [];
   const unmeasuredRoots: MotionUnmeasuredRoot[] = [];
-  const add = (a: string, b: string, declared: string): void => {
+  const add = (a: string, b: string, declared: string, joint?: string): void => {
     const hit = out.find((p) => (p.a === a && p.b === b) || (p.a === b && p.b === a));
-    if (hit !== undefined) hit.declared.push(declared);
-    else out.push({ pair: `${a}|${b}`, a, b, declared: [declared] });
+    if (hit !== undefined) {
+      hit.declared.push(declared);
+      if (joint !== undefined && !hit.joints?.includes(joint)) (hit.joints ??= []).push(joint);
+    } else out.push({ pair: `${a}|${b}`, a, b, declared: [declared], ...(joint === undefined ? {} : { joints: [joint] }) });
   };
   const limbs: string[] = [];
   for (const p of parts.parts) if (p.limb !== undefined && !limbs.includes(p.limb.name)) limbs.push(p.limb.name);
@@ -4437,7 +4444,7 @@ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ nam
     const segs = parts.parts.filter((p) => p.limb?.name === limb).sort((x, y) => (x.limb as LimbRecord).segment - (y.limb as LimbRecord).segment);
     for (let i = 1; i < segs.length; i++) {
       const lower = segs[i].limb as LimbRecord;
-      add(segs[i - 1].name, segs[i].name, `config.limbs.${limb} segment ${lower.segment}${lower.joint === undefined ? '' : `, joint "${lower.joint}"`}`);
+      add(segs[i - 1].name, segs[i].name, `config.limbs.${limb} segment ${lower.segment}${lower.joint === undefined ? '' : `, joint "${lower.joint}"`}`, lower.joint);
     }
   }
   for (const r of seams) add(r.part, r.neighbour, `requirement "${r.name}" (seam)`);
@@ -4473,7 +4480,7 @@ export function motionSeamSelection(parts: PartsFile, seams: ReadonlyArray<{ nam
     }
   }
   for (const root of selected) {
-    add(root.a, root.b, root.declared[0]);
+    add(root.a, root.b, root.declared[0], root.root?.bone);
     const pair = out.find(p => (p.a === root.a && p.b === root.b) || (p.a === root.b && p.b === root.a));
     if (pair !== undefined) pair.root = root.root;
   }
@@ -4578,7 +4585,7 @@ function motionRootCandidates(parts: PartsFile, rig: Record<string, unknown>): M
     }
     for (const { part: body } of eligible) out.push({ pair: body.name + '|' + root.name, a: body.name, b: root.name,
       declared: ['config.limbs.' + limb + ' segment 0, body carrier "' + parent + '" from ' + body.from],
-      root: { limb, bone: l.bone, parent } });
+      joints: [l.bone], root: { limb, bone: l.bone, parent } });
   }
   refuseIfAny(problems);
   return out;
@@ -4923,11 +4930,14 @@ function readSeamRows(dir: string, animations: readonly string[], fps: number, p
           }
         }
       }
+      const contact = setup ? undefined : jointContactReading(p.jointContact, want.joints ?? [], set.written ?? set.sampled, at, problems);
+      if (contact === null) return;
       worldRows?.push({ pair: want.pair, animation, status: p.status, drawn: p.drawn, banded: p.banded, gap: kinds.gap, ghost: kinds.ghost });
       const opens = [...over.keys()].sort((x, y) => x - y);
       rows.push({
         pair: want.pair,
         animation,
+        ...(setup ? {} : { joint_contact: contact }),
         status: p.status,
         drawn: p.drawn,
         banded: p.banded,
@@ -5081,6 +5091,21 @@ export function enrichMotionSeamPoses(dir: string, rig: Record<string, unknown>,
   }
 }
 
+/** One informational line per observed pair/animation; missing readings are named SKIP. */
+export function motionJointContactLines(line: MotionSeamLine): string[] {
+  if (line.rows.length === 0) return ['JOINT_CONTACT: SKIP — ' + (line.reason ?? 'no sampled pair/animation reading')];
+  const lines = line.rows.map(row => {
+    const c = row.joint_contact;
+    const head = 'JOINT_CONTACT: "' + row.pair + '" in "' + row.animation + '"';
+    if (c === undefined || c.status === 'SKIP') return head + ': SKIP — ' + (c?.reason ?? 'no contact observation');
+    return head + ', joint ' + (c.joints.length === 0 ? 'unavailable' : c.joints.map(n => JSON.stringify(n)).join(', ')) +
+      ': joined ' + c.joined + ', separated ' + c.separated + ', unavailable ' + c.unavailable + ' frame(s)' +
+      (c.reasons.length === 0 ? '' : '; ' + c.reasons.map(r => r.reason + (r.frames === undefined ? '' : ' on frames ' + frameRuns(r.frames))).join('; ')) + '; report only';
+  });
+  for (const pair of line.pairs) if (!line.rows.some(row => row.pair === pair.pair)) lines.push('JOINT_CONTACT: "' + pair.pair + '": SKIP — ' + (pair.unread ?? line.reason ?? 'no sampled animation'));
+  return lines;
+}
+
 /** One warning as the console prints it (issue #493's form, the floor's clause after it). */
 export function motionSeamWarnText(r: MotionSeamRow): string {
   const pose = r.pose_at_worst;

package/src/depthmaps.ts

@@ -0,0 +1,170 @@
+/** Provider-independent floating-point maps. No model or reference depth is read here. */
+import { PartsError } from './errors.ts';
+import { connectedComponents } from './raster/components.ts';
+import { extendDepthSilhouette } from './depthsheets.ts';
+import { newRaster, type Raster } from './raster/types.ts';
+import { edgeLength } from './length.ts';
+
+export interface NumericMap { spec: 'rig-parts-map/1'; width: number; height: number; channels: 1 | 3; data: number[] }
+export function depthMapFail(code: string, object: string, detail: string): never {
+  throw new PartsError([{ code, object, detail }]);
+}
+export function readNumericMap(raw: unknown, at: string): NumericMap {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return depthMapFail('DEPTH_MAP_FORMAT', at, 'requires a rig-parts-map/1 JSON object');
+  const r = raw as Record<string, unknown>;
+  if (Object.keys(r).some(k => !['spec', 'width', 'height', 'channels', 'data'].includes(k)) || r.spec !== 'rig-parts-map/1' || !Number.isSafeInteger(r.width) || !Number.isSafeInteger(r.height) || Number(r.width) < 1 || Number(r.height) < 1 || (r.channels !== 1 && r.channels !== 3) || !Array.isArray(r.data) || r.data.length !== Number(r.width) * Number(r.height) * r.channels || !r.data.every(x => typeof x === 'number' && Number.isFinite(x))) {
+    return depthMapFail('DEPTH_MAP_FORMAT', at, 'requires positive integer width/height, channels 1 or 3 and exactly width*height*channels finite row-major numbers; previews and quantized PNGs are not numeric maps');
+  }
+  return r as unknown as NumericMap;
+}
+
+/** NumPy percentile's linear interpolation on sorted samples, including the even median. */
+export function mapQuantile(sorted: readonly number[], q: number): number {
+  const p = (sorted.length - 1) * q, i = Math.floor(p), f = p - i;
+  return sorted[i] * (1 - f) + sorted[Math.min(i + 1, sorted.length - 1)] * f;
+}
+export function alphaSupport(art: Raster): Uint8Array {
+  return Uint8Array.from({ length: art.width * art.height }, (_, i) => art.data[i * 4 + 3] >= 128 ? 1 : 0);
+}
+
+/** Pillow mode-F BOX: discrete box taps, horizontal then vertical float32 passes.
+ * Unlike area coverage, BOX gives equal weights to the included pixel centres.
+ * Verification compares this operation to an independent Pillow oracle.
+ */
+export function floatBox(data: ArrayLike<number>, w: number, h: number, width: number, height: number): Float64Array {
+  const pass = (src: ArrayLike<number>, sw: number, sh: number, dw: number): Float32Array => {
+    const out = new Float32Array(dw * sh), scale = sw / dw;
+    for (let x = 0; x < dw; x++) {
+      const center = (x + 0.5) * scale, support = Math.max(1, scale) * 0.5;
+      const lo = Math.max(0, Math.trunc(center - support + 0.5)), hi = Math.min(sw, Math.trunc(center + support + 0.5));
+      const indices: number[] = [];
+      for (let i = lo; i < hi; i++) { const d = (i - center + 0.5) / Math.max(1, scale); if (d > -0.5 && d <= 0.5) indices.push(i); }
+      if (indices.length === 0) indices.push(Math.min(sw - 1, Math.max(0, Math.floor(center))));
+      for (let y = 0; y < sh; y++) { let v = 0; for (const i of indices) v += src[y * sw + i] / indices.length; out[y * dw + x] = v; }
+    }
+    return out;
+  };
+  const horizontal = w === width ? Float32Array.from(data) : pass(data, w, h, width);
+  if (h === height) return Float64Array.from(horizontal);
+  const transpose = new Float32Array(width * h);
+  for (let y = 0; y < h; y++) for (let x = 0; x < width; x++) transpose[x * h + y] = horizontal[y * width + x];
+  const vertical = pass(transpose, h, width, height), out = new Float64Array(width * height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) out[y * width + x] = vertical[x * height + y];
+  return out;
+}
+
+function norm(v: Float64Array): number { let s = 0; for (const x of v) s += x * x; return Math.sqrt(s); }
+function eroded(mask: Uint8Array, w: number, h: number, count: number): Uint8Array {
+  let cur = mask;
+  for (let n = 0; n < count; n++) {
+    const next = new Uint8Array(cur.length);
+    for (let y = 1; y < h - 1; y++) for (let x = 1; x < w - 1; x++) { const i = y * w + x; next[i] = cur[i] && cur[i - 1] && cur[i + 1] && cur[i - w] && cur[i + w] ? 1 : 0; }
+    cur = next;
+  }
+  return cur;
+}
+
+/** Matrix-free LSQR over right/down adjacent mask pixels, row order right then down.
+ * Paige/Saunders bidiagonalization; atol=btol=1e-6, conlim=1e8, at most 3000
+ * iterations. These are algorithm settings, not fitted depth-quality bars.
+ */
+function solveEdges(a: Int32Array, b: Int32Array, rhs: Float64Array, size: number): { z: Float64Array; iterations: number; residual: number } {
+  const mul = (v: Float64Array, out: Float64Array): void => { for (let i = 0; i < a.length; i++) out[i] = v[b[i]] - v[a[i]]; };
+  const trans = (u: Float64Array, out: Float64Array): void => { out.fill(0); for (let i = 0; i < a.length; i++) { out[b[i]] += u[i]; out[a[i]] -= u[i]; } };
+  const z = new Float64Array(size), u = rhs.slice(), v = new Float64Array(size);
+  let beta = norm(u); const bnorm = beta;
+  if (beta === 0) return { z, iterations: 0, residual: 0 };
+  for (let i = 0; i < u.length; i++) u[i] /= beta;
+  trans(u, v); let alpha = norm(v);
+  if (alpha === 0) return { z, iterations: 0, residual: beta };
+  for (let i = 0; i < v.length; i++) v[i] /= alpha;
+  const w = v.slice(), av = new Float64Array(u.length), atu = new Float64Array(size);
+  let rhobar = alpha, phibar = beta, anorm = 0, ddnorm = 0, xnorm = 0, xxnorm = 0, zeta = 0, cs2 = -1, sn2 = 0, iterations = 0, residual = beta;
+  for (; iterations < 3000;) {
+    iterations++; mul(v, av);
+    for (let i = 0; i < u.length; i++) u[i] = av[i] - alpha * u[i];
+    beta = norm(u);
+    if (beta > 0) {
+      for (let i = 0; i < u.length; i++) u[i] /= beta;
+      anorm = Math.sqrt(anorm * anorm + alpha * alpha + beta * beta);
+      trans(u, atu);
+      for (let i = 0; i < v.length; i++) v[i] = atu[i] - beta * v[i];
+      alpha = norm(v);
+      if (alpha > 0) for (let i = 0; i < v.length; i++) v[i] /= alpha;
+    }
+    const rho = edgeLength(rhobar, beta), cs = rhobar / rho, sn = beta / rho;
+    const theta = sn * alpha; rhobar = -cs * alpha;
+    const phi = cs * phibar; phibar = sn * phibar;
+    const tau = sn * phi;
+    for (let i = 0; i < z.length; i++) { const d = w[i] / rho; z[i] += phi * d; ddnorm += d * d; w[i] = v[i] - theta / rho * w[i]; }
+    const delta = sn2 * rho, gambar = -cs2 * rho, right = phi - delta * zeta;
+    const zbar = right / gambar; xnorm = Math.sqrt(xxnorm + zbar * zbar);
+    const gamma = edgeLength(gambar, theta); cs2 = gambar / gamma; sn2 = theta / gamma; zeta = right / gamma; xxnorm += zeta * zeta;
+    residual = Math.abs(phibar);
+    const arnorm = alpha * Math.abs(tau), acond = anorm * Math.sqrt(ddnorm);
+    if (acond >= 1e8 || arnorm <= 1e-6 * anorm * residual || residual <= 1e-6 * bnorm + 1e-6 * anorm * xnorm) break;
+  }
+  return { z, iterations, residual };
+}
+
+export interface NormalHeight { data: Float64Array; sign: 1 | -1; coreMinusRim: number; iterations: number; residual: number }
+/** Normals are signed XYZ in image axes (x right/y down), not RGB previews.
+ * Half-resolution stride, step2 edge trapezoids, cross-erosion core/rim sign.
+ * Convexity selects between a height and its negation without an answer key.
+ */
+export function integrateNormals(map: NumericMap, art: Raster, at: string): NormalHeight {
+  const support = alphaSupport(art);
+  const islands = connectedComponents({ width: art.width, height: art.height, data: support }, 4).count - 1;
+  if (islands !== 1) return depthMapFail('DEPTH_NORMAL_ISLANDS', at, `has ${islands} four-connected alpha>=128 islands; exactly one closed convex part is required, use scalar depth for occlusion-separated parts`);
+  if (map.channels !== 3 || map.width !== art.width || map.height !== art.height) return depthMapFail('DEPTH_MAP_SIZE', at, `normal map is ${map.width}x${map.height}x${map.channels}; registered art ${art.width}x${art.height}x3 is required`);
+  const w = Math.ceil(map.width / 2), h = Math.ceil(map.height / 2), mask = new Uint8Array(w * h), px = new Float64Array(w * h), py = new Float64Array(w * h), ids = new Int32Array(w * h).fill(-1);
+  let count = 0;
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    const src = 2 * y * map.width + 2 * x, i = y * w + x;
+    mask[i] = support[src]; if (!mask[i]) continue;
+    ids[i] = count++;
+    const nx = map.data[src * 3], ny = map.data[src * 3 + 1], nz = map.data[src * 3 + 2], length = edgeLength(edgeLength(nx, ny), nz);
+    if (length < 1e-12 || !Number.isFinite(length)) return depthMapFail('DEPTH_NORMAL_VECTOR', `${at} (${x * 2},${y * 2})`, 'has zero or overflowing length; a finite nonzero representable signed XYZ vector is required');
+    const divisor = Math.max(Math.abs(nz), 0.15 * length);
+    px[i] = Math.fround(-nx / divisor); py[i] = Math.fround(-ny / divisor);
+  }
+  const sampledIslands = connectedComponents({ width: w, height: h, data: mask }, 4).count - 1;
+  if (sampledIslands !== 1) return depthMapFail('DEPTH_NORMAL_ISLANDS', at, `half-resolution mask has ${sampledIslands} islands; provide a larger registered input so stride2 keeps one island`);
+  const aa: number[] = [], bb: number[] = [], rr: number[] = [];
+  for (const [dx, dy, g] of [[1, 0, px], [0, 1, py]] as const) {
+    for (let y = 0; y < h - dy; y++) for (let x = 0; x < w - dx; x++) {
+      const i = y * w + x, j = (y + dy) * w + x + dx;
+      if (mask[i] && mask[j]) { aa.push(ids[i]); bb.push(ids[j]); rr.push(Math.fround(g[i] + g[j])); }
+    }
+  }
+  const solve = solveEdges(Int32Array.from(aa), Int32Array.from(bb), Float64Array.from(rr), count);
+  const core = eroded(mask, w, h, Math.max(3, Math.trunc(0.12 * Math.sqrt(count)))), inner = eroded(mask, w, h, 3);
+  let cv = 0, rv = 0, cn = 0, rn = 0;
+  for (let i = 0; i < mask.length; i++) { if (core[i]) { cv += solve.z[ids[i]]; cn++; } if (mask[i] && !inner[i]) { rv += solve.z[ids[i]]; rn++; } }
+  const d = cv / cn - rv / rn;
+  if (!cn || !rn || !Number.isFinite(d) || Math.abs(d) < 1e-12) return depthMapFail('DEPTH_NORMAL_CONVEXITY', at, `core ${cn}, rim ${rn}, core-minus-rim ${d}; a resolved convex interior is required, use a larger mask or scalar source`);
+  const sign = d >= 0 ? 1 : -1, data = new Float64Array(w * h);
+  for (let i = 0; i < mask.length; i++) if (mask[i]) data[i] = Math.fround(solve.z[ids[i]] * sign);
+  return { data, sign, coreMinusRim: d, iterations: solve.iterations, residual: solve.residual };
+}
+
+export interface MapSheetReading { levels: number; clipFraction: number; reliefRigPixels: number; rawMedian: number; rawP5: number; rawP95: number }
+export function mapToSheet(data: ArrayLike<number>, art: Raster, median: number, relief: number, near: 'black' | 'white', zScale: number, at: string): { sheet: Raster; reading: MapSheetReading } {
+  const support = alphaSupport(art), values: number[] = [];
+  for (let i = 0; i < support.length; i++) if (support[i]) values.push(data[i]);
+  if (!values.length) return depthMapFail('DEPTH_MAP_SUPPORT', at, 'has no alpha>=128 pixels; a part with declared support is required');
+  values.sort((a, b) => a - b);
+  const med = mapQuantile(values, 0.5), lo = mapQuantile(values, 0.05), hi = mapQuantile(values, 0.95), spread = hi - lo;
+  if (![med, lo, hi, spread].every(Number.isFinite)) return depthMapFail('DEPTH_MAP_FORMAT', at, 'normalization overflows finite arithmetic; provide finite representable median and percentile spread');
+  if (spread === 0 && relief !== 0) return depthMapFail('DEPTH_MAP_SPREAD', at, `p5=p95=${lo} but relief=${relief}; a nonflat map or explicit relief 0 is required`);
+  const sheet = newRaster(art.width, art.height), seeds = newRaster(art.width, art.height), levels = new Set<number>(); let clipped = 0;
+  for (let i = 0; i < support.length; i++) {
+    const z = median + relief * (spread === 0 ? 0 : (data[i] - med) / spread), unit = Math.max(0, Math.min(1, near === 'white' ? z / zScale : 1 - z / zScale));
+    if (!Number.isFinite(z) && support[i]) return depthMapFail('DEPTH_MAP_FORMAT', at, `world depth at support pixel ${i} overflows; declare representable median/relief and raw numbers`);
+    // Uint8ClampedArray implements ties-to-even, as numpy.round does.
+    sheet.data[i * 4] = unit * 255; sheet.data[i * 4 + 1] = sheet.data[i * 4 + 2] = sheet.data[i * 4]; sheet.data[i * 4 + 3] = 255;
+    seeds.data[i * 4 + 3] = support[i] ? 255 : 0;
+    if (support[i]) { levels.add(sheet.data[i * 4]); if (z <= 0 || z >= zScale) clipped++; }
+  }
+  return { sheet: extendDepthSilhouette(sheet, seeds), reading: { levels: levels.size, clipFraction: clipped / values.length, reliefRigPixels: relief, rawMedian: med, rawP5: lo, rawP95: hi } };
+}

package/src/depthworkflow.ts

@@ -0,0 +1,239 @@
+/** Explicit opt-in commands for provider maps on already assembled parts (#897).
+ * No existing assembly/build path calls these stages. All inputs validate before
+ * the first output is emitted; output directories must be absent or empty.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { loadConfigAndAnimations, parseConfig } from './config.ts';
+import { depthReading, readSourceDepth } from './depthsheets.ts';
+import { alphaSupport, depthMapFail as fail, floatBox, integrateNormals, mapToSheet, readNumericMap, type NumericMap } from './depthmaps.ts';
+import { readParts } from './parts.ts';
+import { readPartSet } from './propose.ts';
+import { decodePngBytes, encodePngBytes } from './raster/png.ts';
+import { resize } from './raster/resize.ts';
+import { connectedComponents } from './raster/components.ts';
+import { isSkeletonName } from './skeleton.ts';
+import { newRaster, type Raster } from './raster/types.ts';
+
+type Obj = Record<string, unknown>;
+interface PrepareOptions { longSide: number; paddingFraction: number; padding: number }
+interface Group { median?: never; near: 'black' | 'white'; zScale: number; pivot: number; unitDepths?: Record<string, number> }
+interface PartMap { map: string; source: 'depth' | 'normals'; frame: 'part' | 'upscaled' | 'input'; group: string; median: number; relief: number }
+export interface DepthRecipe { spec: 'rig-parts-depth/1'; prepare: PrepareOptions; groups: Record<string, Group>; parts: Record<string, PartMap>; clear: string[] }
+interface PreparedPart { part: string; crop: number[]; sourceSha256: string; input: string; inputSha256: string; size: number[]; upscaled: number[]; upscale: number; padding: number; inputSize: number[] }
+interface Prepared { spec: 'rig-parts-depth-inputs/1'; partsSha256: string; recipeSha256: string; background: number; alpha: number; parts: PreparedPart[] }
+const hash = (bytes: Uint8Array | string): string => createHash('sha256').update(bytes).digest('hex');
+const text = (raw: unknown): string => JSON.stringify(raw, null, 2) + '\n';
+function object(raw: unknown, at: string): Obj {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return fail('DEPTH_RECIPE', at, 'requires an object with the documented fields');
+  return raw as Obj;
+}
+function keys(o: Obj, allowed: readonly string[], at: string): void {
+  const unknown = Object.keys(o).filter(k => !allowed.includes(k));
+  if (unknown.length) fail('DEPTH_RECIPE', at, `unknown fields ${unknown.join(', ')}; allowed: ${allowed.join(', ')}`);
+}
+function number(raw: unknown, at: string, min: number, inclusive = true): number {
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || (inclusive ? raw < min : raw <= min)) return fail('DEPTH_RECIPE_NUMBER', at, `is ${String(raw)}; an explicit finite number ${inclusive ? '>=' : '>'} ${min} is required`);
+  return raw;
+}
+function readJson(file: string): unknown {
+  if (!existsSync(file) || !statSync(file).isFile()) return fail('DEPTH_INPUT_PRESENT', file, 'is missing or not a file; restore the declared input');
+  try { return JSON.parse(readFileSync(file, 'utf8')) as unknown; }
+  catch { return fail('DEPTH_INPUT_JSON', file, 'is not valid JSON; finite numeric JSON data is required'); }
+}
+function plain(name: string, at: string): void {
+  if (!name || name.startsWith('.') || /[\\/]/.test(name) || name.includes('\0')) fail('DEPTH_RECIPE', at, `name "${name}" is not a plain part filename`);
+}
+export function parseDepthRecipe(raw: unknown): DepthRecipe {
+  const o = object(raw, 'depth recipe'); keys(o, ['spec', 'prepare', 'groups', 'parts', 'clear'], 'depth recipe');
+  if (o.spec !== 'rig-parts-depth/1') fail('DEPTH_RECIPE', 'spec', 'requires rig-parts-depth/1');
+  const p = object(o.prepare, 'prepare'); keys(p, ['longSide', 'paddingFraction', 'padding'], 'prepare');
+  const prepare = { longSide: number(p.longSide, 'prepare.longSide', 1), paddingFraction: number(p.paddingFraction, 'prepare.paddingFraction', 0), padding: number(p.padding, 'prepare.padding', 0) };
+  if (!Number.isSafeInteger(prepare.longSide) || !Number.isSafeInteger(prepare.padding)) fail('DEPTH_RECIPE_NUMBER', 'prepare', 'longSide and padding must be explicit safe integers');
+  const groups: Record<string, Group> = {};
+  for (const [name, value] of Object.entries(object(o.groups, 'groups'))) {
+    if (!['head', 'body'].includes(name)) fail('DEPTH_RECIPE', `groups.${name}`, 'requires head or body, matching config.turn or config.turn.body');
+    const g = object(value, `groups.${name}`); keys(g, ['near', 'zScale', 'pivot', 'unitDepths'], `groups.${name}`);
+    if (g.near !== 'white' && g.near !== 'black') fail('DEPTH_RECIPE', `groups.${name}.near`, `is ${String(g.near)}; explicit white or black is required`);
+    const unitDepths: Record<string, number> = {};
+    if (g.unitDepths !== undefined) for (const [part, v] of Object.entries(object(g.unitDepths, `groups.${name}.unitDepths`))) unitDepths[part] = number(v, `groups.${name}.unitDepths.${part}`, -Infinity);
+    groups[name] = { near: g.near, zScale: number(g.zScale, `groups.${name}.zScale`, 0, false), pivot: number(g.pivot, `groups.${name}.pivot`, -Infinity), ...(g.unitDepths === undefined ? {} : { unitDepths }) };
+  }
+  const parts: Record<string, PartMap> = {};
+  for (const [name, value] of Object.entries(object(o.parts, 'parts'))) {
+    plain(name, `parts.${name}`); const p = object(value, `parts.${name}`); keys(p, ['map', 'source', 'frame', 'group', 'median', 'relief'], `parts.${name}`);
+    if (typeof p.map !== 'string' || !p.map) fail('DEPTH_RECIPE', `parts.${name}.map`, 'requires a declared numeric JSON map filename relative to the recipe');
+    if (p.source !== 'depth' && p.source !== 'normals') fail('DEPTH_RECIPE', `parts.${name}.source`, 'requires depth or normals');
+    if (p.frame !== 'part' && p.frame !== 'upscaled' && p.frame !== 'input') fail('DEPTH_RECIPE', `parts.${name}.frame`, 'requires part, upscaled or input; registration is never inferred from dimensions');
+    if (typeof p.group !== 'string' || !Object.hasOwn(groups, p.group)) fail('DEPTH_RECIPE', `parts.${name}.group`, 'must resolve to a declared group');
+    parts[name] = { map: p.map, source: p.source, frame: p.frame, group: p.group, median: number(p.median, `parts.${name}.median`, -Infinity), relief: number(p.relief, `parts.${name}.relief`, 0) };
+  }
+  if (!Object.keys(parts).length) fail('DEPTH_RECIPE', 'parts', 'requires at least one named part');
+  if (!Array.isArray(o.clear) || !o.clear.every(n => typeof n === 'string') || new Set(o.clear).size !== o.clear.length) fail('DEPTH_RECIPE', 'clear', 'requires an explicit array of unique part names, [] when none; no sheet is dropped implicitly');
+  for (const name of o.clear as string[]) { plain(name, 'clear'); if (Object.hasOwn(parts, name)) fail('DEPTH_RECIPE', `clear.${name}`, 'also has a new map; choose clear or apply'); }
+  return { spec: 'rig-parts-depth/1', prepare, groups, parts, clear: o.clear as string[] };
+}
+function emptyOutput(out: string, inputs: readonly string[]): void {
+  const canonical = (p: string): string => existsSync(p) ? realpathSync(p) : resolve(canonical(dirname(resolve(p))), basename(p));
+  const target = canonical(out);
+  for (const input of inputs) {
+    const path = canonical(input), r = relative(target, path), back = relative(path, target);
+    if (r === '' || (!r.startsWith(`..${sep}`) && r !== '..' && !r.startsWith(sep))) fail('DEPTH_OUTPUT_EMPTY', out, 'contains or is an input path; use a separate absent or empty output directory');
+    if (existsSync(input) && statSync(input).isDirectory() && back !== '..' && !back.startsWith(`..${sep}`) && !back.startsWith(sep)) fail('DEPTH_OUTPUT_EMPTY', out, 'is inside an input directory; choose a separate output so source inputs remain read-only');
+  }
+  if (existsSync(out) && (!statSync(out).isDirectory() || readdirSync(out).length !== 0)) fail('DEPTH_OUTPUT_EMPTY', out, 'is not an empty directory; choose an absent or empty output, never overwrite inputs or old evidence');
+}
+function preparedParts(partsDir: string, recipe: DepthRecipe): { manifest: Prepared; images: Map<string, Uint8Array> } {
+  const set = readPartSet(partsDir), images = new Map<string, Uint8Array>(), parts: PreparedPart[] = [];
+  for (const name of [...Object.keys(recipe.parts), ...recipe.clear]) if (!set.recs.some(p => p.name === name)) fail('DEPTH_PART_RESOLVES', name, 'names no assembled part; use exact parts.json names');
+  for (const part of set.recs.filter(p => Object.hasOwn(recipe.parts, p.name))) {
+    const art = set.images.get(part.name) as Raster, { longSide, paddingFraction, padding } = recipe.prepare;
+    const upscale = Math.max(1, Math.ceil(longSide / Math.max(art.width, art.height))), w = art.width * upscale, h = art.height * upscale;
+    const pad = Math.floor(Math.max(w, h) * paddingFraction) + padding, big = resize(art, w, h, 'lanczos3'), input = newRaster(w + pad * 2, h + pad * 2);
+    for (let i = 0; i < input.width * input.height; i++) input.data.set([128, 128, 128, 255], i * 4);
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4, j = ((y + pad) * input.width + x + pad) * 4, a = big.data[i + 3];
+      for (let c = 0; c < 3; c++) input.data[j + c] = Math.floor((big.data[i + c] * a + 128 * (255 - a) + 127) / 255);
+    }
+    if (!alphaSupport(art).some(Boolean)) fail('DEPTH_MAP_SUPPORT', part.name, 'has no alpha>=128 pixels; a supported part is required');
+    const bytes = encodePngBytes(input), file = `${part.name}.png`; images.set(file, bytes);
+    parts.push({ part: part.name, crop: [part.x, part.y, part.w, part.h], sourceSha256: hash(readFileSync(join(partsDir, 'parts', file))), input: file, inputSha256: hash(bytes), size: [art.width, art.height], upscaled: [w, h], upscale, padding: pad, inputSize: [input.width, input.height] });
+  }
+  return { manifest: { spec: 'rig-parts-depth-inputs/1', partsSha256: hash(readFileSync(join(partsDir, 'parts.json'))), recipeSha256: hash(text(recipe)), background: 128, alpha: 128, parts }, images };
+}
+export function prepareDepth(input: { parts: string; config: string; out: string }): Prepared {
+  const recipe = parseDepthRecipe(readJson(input.config));
+  emptyOutput(input.out, [input.parts, input.config]);
+  const { manifest, images } = preparedParts(input.parts, recipe);
+  mkdirSync(input.out, { recursive: true });
+  for (const [file, bytes] of images) writeFileSync(join(input.out, file), bytes);
+  writeFileSync(join(input.out, 'manifest.json'), text(manifest));
+  return manifest;
+}
+function registeredMap(map: NumericMap, p: PreparedPart, frame: PartMap['frame'], at: string): NumericMap {
+  const [w, h] = frame === 'part' ? p.size : frame === 'input' ? p.inputSize : p.upscaled;
+  if (map.width !== w || map.height !== h) return fail('DEPTH_MAP_SIZE', at, `is ${map.width}x${map.height}; declared ${frame} frame is ${w}x${h}`);
+  if (frame !== 'input') return map;
+  const data: number[] = [];
+  for (let y = 0; y < p.upscaled[1]; y++) for (let x = 0; x < p.upscaled[0]; x++) for (let c = 0; c < map.channels; c++) data.push(map.data[((y + p.padding) * map.width + x + p.padding) * map.channels + c]);
+  return { ...map, width: p.upscaled[0], height: p.upscaled[1], data };
+}
+
+/** Extend the float field from its OWN stride2 integration support before BOX.
+ * Keep every supported height unchanged; Euclidean nearest seeds use row-major
+ * ties. A nearest seed must be on the four-neighbour boundary: an interior
+ * seed always has a strictly closer axis neighbour toward an unsupported point.
+ * No gray encoding or native-art mask is used on this integration grid.
+ */
+function extendIntegratedHeight(data: Float64Array, art: Raster): Float64Array {
+  const w = Math.ceil(art.width / 2), h = Math.ceil(art.height / 2);
+  const support = Uint8Array.from({ length: w * h }, (_, i) => art.data[((2 * Math.floor(i / w)) * art.width + 2 * (i % w)) * 4 + 3] >= 128 ? 1 : 0);
+  const boundary: number[] = [];
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    const i = y * w + x;
+    if (support[i] && (x === 0 || y === 0 || x === w - 1 || y === h - 1 || !support[i - 1] || !support[i + 1] || !support[i - w] || !support[i + w])) boundary.push(i);
+  }
+  // integrateNormals already refused empty/disconnected support before this call.
+  const filled = data.slice();
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    const i = y * w + x; if (support[i]) continue;
+    let distance = Infinity, seed = -1;
+    for (const j of boundary) {
+      const dx = x - j % w, dy = y - Math.floor(j / w), d = dx * dx + dy * dy;
+      if (d < distance) { distance = d; seed = j; }
+    }
+    filled[i] = data[seed];
+  }
+  return filled;
+}
+export function applyDepth(input: { parts: string; manifest: string; config: string; rigConfig: string; out: string }): Obj {
+  const recipe = parseDepthRecipe(readJson(input.config)), expected = preparedParts(input.parts, recipe);
+  const supplied = readJson(input.manifest);
+  if (text(supplied) !== text(expected.manifest)) fail('DEPTH_INPUT_BINDING', input.manifest, 'does not match the recipe, parts.json, art hashes, crop or padding; run depth-prepare again for these exact inputs');
+  for (const p of expected.manifest.parts) {
+    const file = join(dirname(input.manifest), p.input);
+    if (!existsSync(file) || hash(readFileSync(file)) !== p.inputSha256) fail('DEPTH_INPUT_BINDING', p.part, 'prepared inference PNG is missing or changed; restore its exact bytes or prepare again');
+  }
+  emptyOutput(input.out, [input.parts, input.config, input.manifest, input.rigConfig, ...Object.values(recipe.parts).map(p => resolve(dirname(input.config), p.map))]);
+  const rawParts = object(readJson(join(input.parts, 'parts.json')), 'parts.json'), file = readParts(join(input.parts, 'parts.json'));
+  for (const p of file.parts) if (Object.hasOwn(recipe.parts, p.name) && p.provenance?.depth?.kind === 'authored-unit') fail('DEPTH_AUTHORED_UNIT_CONFLICT', `part "${p.name}"`, 'has provenance.depth.kind "authored-unit"; a transported scalar reference cannot coexist with authored unit depth — retain the unit declaration or supply an explicitly reassembled scalar-compatible input; no automatic transition is made');
+  loadConfigAndAnimations(input.rigConfig);
+  const raw = object(readJson(input.rigConfig), 'rig config'), turn = object(raw.turn, 'config.turn');
+  for (const [name, group] of Object.entries(recipe.groups)) {
+    const target = name === 'head' ? turn : object(turn.body, 'config.turn.body'); target.pivot = group.pivot;
+    if (group.unitDepths !== undefined) target.unitDepths = group.unitDepths;
+  }
+  // Keep relative paths portable when relocating the output directory with its inputs.
+  const motion = raw.motion as Obj | undefined;
+  if (typeof motion?.animations_from === 'string') motion.animations_from = relative(resolve(input.out), resolve(dirname(input.rigConfig), motion.animations_from));
+  const control = (raw.generation as Obj | undefined)?.control as Obj | undefined;
+  if (typeof control?.skeleton === 'string' && !isSkeletonName(control.skeleton)) control.skeleton = relative(resolve(input.out), resolve(dirname(input.rigConfig), control.skeleton));
+  if (typeof raw.requirements === 'string') raw.requirements = relative(resolve(input.out), resolve(dirname(input.rigConfig), raw.requirements));
+  parseConfig(raw);
+  const writes = new Map<string, Uint8Array>(), rows: Obj[] = [], recs = rawParts.parts as Obj[];
+  // Retain auxiliary art (including alternate sets) and diagnostics byte-for-byte.
+  // Symlink inputs would obscure ownership and can escape this assembled directory.
+  const retained = new Map<string, Uint8Array>();
+  const collect = (dir: string, prefix: string): void => {
+    for (const ent of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, ent.name), key = prefix + ent.name;
+      if (ent.isDirectory()) collect(path, key + '/');
+      else if (ent.isFile()) retained.set(key, readFileSync(path));
+      else fail('DEPTH_INPUT_PRESENT', path, 'is not a regular owned file/directory; supply a self-contained assembled directory without symlinks');
+    }
+  };
+  collect(input.parts, '');
+  for (const p of file.parts) {
+    const name = p.name, bytes = readFileSync(join(input.parts, 'parts', `${name}.png`)), art = decodePngBytes(bytes, name), rec = recs.find(r => r.name === name) as Obj;
+    writes.set(`${name}.png`, bytes);
+    const declaration = Object.hasOwn(recipe.parts, name) ? recipe.parts[name] : undefined;
+    if (declaration === undefined) {
+      if (recipe.clear.includes(name)) { if (p.depth !== undefined) retained.delete(`parts/${p.depth.image}`); delete rec.depth; }
+      else if (p.depth !== undefined) { readSourceDepth(join(input.parts, 'parts', p.depth.image), art, null); writes.set(p.depth.image, readFileSync(join(input.parts, 'parts', p.depth.image))); }
+      continue;
+    }
+    const g = recipe.groups[declaration.group], target = declaration.group === 'head' ? turn : object(turn.body, 'config.turn.body');
+    if (!Object.hasOwn(object(target.roles, `config.turn.${declaration.group}.roles`), name)) fail('DEPTH_GROUP_BINDING', name, `declared group ${declaration.group} does not name this part in its roles; register it explicitly`);
+    const prepared = expected.manifest.parts.find(row => row.part === name) as PreparedPart;
+    const mapPath = resolve(dirname(input.config), declaration.map), numeric = readNumericMap(readJson(mapPath), name), mapBytes = readFileSync(mapPath);
+    const map = registeredMap(numeric, prepared, declaration.frame, name);
+    let values: ArrayLike<number>, normal: ReturnType<typeof integrateNormals> | undefined;
+    if (declaration.source === 'normals') {
+      if (map.channels !== 3) fail('DEPTH_MAP_FORMAT', name, 'normals require three signed XYZ channels');
+      const islands = connectedComponents({ width: art.width, height: art.height, data: alphaSupport(art) }, 4).count - 1;
+      if (islands !== 1) fail('DEPTH_NORMAL_ISLANDS', name, `native part has ${islands} alpha>=128 islands; exactly one closed convex part is required`);
+      const maskArt = map.width === art.width && map.height === art.height ? art : resize(art, map.width, map.height, 'lanczos3');
+      normal = integrateNormals(map, maskArt, name);
+      values = floatBox(extendIntegratedHeight(normal.data, maskArt), Math.ceil(map.width / 2), Math.ceil(map.height / 2), art.width, art.height);
+    } else {
+      if (map.channels !== 1) fail('DEPTH_MAP_FORMAT', name, 'depth requires one floating-point channel');
+      values = floatBox(map.data, map.width, map.height, art.width, art.height);
+    }
+    const { sheet, reading } = mapToSheet(values, art, declaration.median, declaration.relief, g.near, g.zScale, name), image = `${name}_depth.png`, sheetBytes = encodePngBytes(sheet);
+    if (file.parts.some(p => `${p.name}.png` === image)) fail('DEPTH_GROUP_BINDING', name, `sheet filename ${image} collides with artwork; use noncolliding part names`);
+    writes.set(image, sheetBytes);
+    if (p.depth !== undefined) retained.delete(`parts/${p.depth.image}`);
+    rec.depth = { image, near: g.near, zScale: g.zScale, sources: [{ from: p.from, image: basename(declaration.map), sha256: hash(mapBytes), crop: [0, 0, art.width, art.height], reading: depthReading(sheet, art, null) }] };
+    rows.push({ part: name, group: declaration.group, source: declaration.source, frame: declaration.frame, sourceSha256: prepared.sourceSha256, mapSha256: hash(mapBytes), inputSha256: prepared.inputSha256, sheetSha256: hash(sheetBytes), median: declaration.median, relief: declaration.relief, near: g.near, zScale: g.zScale, pivot: g.pivot, ...reading, sign: normal?.sign ?? 1, ...(normal === undefined ? {} : { integration: { stride: 2, iterations: normal.iterations, residual: normal.residual, coreMinusRim: normal.coreMinusRim, maxIterations: 3000, atol: 1e-6, btol: 1e-6 } }) });
+  }
+  // A replacement must share near/zScale with every retained part in its actual group.
+  for (const [name, g] of Object.entries(recipe.groups)) {
+    const target = name === 'head' ? turn : object(turn.body, 'config.turn.body'), roles = object(target.roles, `config.turn.${name}.roles`);
+    for (const rec of recs) if (Object.hasOwn(roles, String(rec.name)) && rec.depth !== undefined) {
+      const d = rec.depth as Obj;
+      if (d.near !== g.near || d.zScale !== g.zScale) fail('DEPTH_GROUP_BINDING', String(rec.name), `retained ${name} sheet near=${String(d.near)}, zScale=${String(d.zScale)}; declared group requires ${g.near}, ${g.zScale}; replace or explicitly clear that sheet`);
+    }
+  }
+  const report = { spec: 'rig-parts-depth-report/1', partsSha256: expected.manifest.partsSha256, recipeSha256: expected.manifest.recipeSha256, manifestSha256: hash(readFileSync(input.manifest)), rigConfigSha256: hash(readFileSync(input.rigConfig)), alpha: 128, normalization: 'median, linear p5..p95', extension: 'nearest alpha>=128, row-major ties', cleared: recipe.clear, parts: rows };
+  mkdirSync(join(input.out, 'parts'), { recursive: true });
+  for (const [file, bytes] of retained) {
+    if (['parts.json', 'config.json', 'depth-report.json'].includes(file)) continue;
+    const target = join(input.out, file); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes);
+  }
+  for (const [file, bytes] of writes) writeFileSync(join(input.out, 'parts', file), bytes);
+  writeFileSync(join(input.out, 'parts.json'), text(rawParts));
+  writeFileSync(join(input.out, 'config.json'), text(raw));
+  writeFileSync(join(input.out, 'depth-report.json'), text(report));
+  return report;
+}

package/src/jointcontact.ts

@@ -0,0 +1,59 @@
+/** Report core's material connectivity; no count here participates in a bar. */
+import { PartsError, type Problem } from './errors.ts';
+
+export interface JointContactReading {
+  status: 'REPORTED' | 'SKIP';
+  joints: string[];
+  joined?: number;
+  separated?: number;
+  unavailable?: number;
+  reasons: Array<{ reason: string; frames?: number[] }>;
+  reason?: string;
+}
+const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** Count only producer observations; invalid input adds a problem and yields no reading when a collector is supplied. */
+export function jointContactReading(raw: unknown, joints: readonly string[], sampled: unknown, object: string, problems?: Problem[]): JointContactReading | null {
+  const names = [...new Set(joints)];
+  const fail = (detail: string): null => {
+    const problem = { code: 'FRAMES_SIDECAR', object, detail: 'jointContact: ' + detail };
+    if (problems === undefined) throw new PartsError([problem]);
+    problems.push(problem);
+    return null;
+  };
+  const knownCount = typeof sampled === 'number' && Number.isSafeInteger(sampled) && sampled >= 0 ? sampled : undefined;
+  if (raw === undefined) {
+    const reason = names.length === 0 ? 'pair has no declared named joint' : 'core seam reading has no jointContact.frames';
+    return knownCount === undefined || knownCount === 0
+      ? { status: 'SKIP', joints: names, reasons: [], reason: knownCount === 0 ? 'no sampled frames' : 'sample count unavailable: ' + reason }
+      : { status: 'REPORTED', joints: names, joined: 0, separated: 0, unavailable: knownCount, reasons: [{ reason }] };
+  }
+  if (!record(raw) || !Array.isArray(raw.frames)) return fail('requires { frames: [...] }');
+  if (knownCount !== undefined && raw.frames.length !== knownCount) return fail('has ' + raw.frames.length + ' frame(s); frames.json records ' + knownCount);
+  const frames: Array<{ index: number; time: number; status: 'joined' | 'separated' | 'unavailable'; reason: string | null }> = [];
+  for (const f of raw.frames) {
+    if (!record(f) || typeof f.index !== 'number' || !Number.isSafeInteger(f.index) || f.index < 0 ||
+        typeof f.time !== 'number' || !Number.isFinite(f.time) || f.time < 0 ||
+        (f.status !== 'joined' && f.status !== 'separated' && f.status !== 'unavailable') ||
+        (f.status === 'unavailable' ? typeof f.reason !== 'string' || f.reason.trim() === '' : f.reason !== null)) return fail('requires nonnegative index/time, joined/separated with null reason, or unavailable with a nonempty reason');
+    const previous = frames.at(-1);
+    if (previous !== undefined && (f.index <= previous.index || f.time <= previous.time)) return fail('frame indices and times must increase strictly');
+    frames.push({ index: f.index, time: f.time, status: f.status, reason: f.reason as string | null });
+  }
+  if (frames.length === 0) return { status: 'SKIP', joints: names, reasons: [], reason: 'no sampled frames' };
+  const out: JointContactReading = { status: 'REPORTED', joints: names, joined: 0, separated: 0, unavailable: 0, reasons: [] };
+  for (const f of frames) {
+    const status = names.length === 0 ? 'unavailable' : f.status;
+    const reason = names.length === 0 ? 'pair has no declared named joint' : f.reason;
+    if (status === 'joined') out.joined = (out.joined ?? 0) + 1;
+    else if (status === 'separated') out.separated = (out.separated ?? 0) + 1;
+    else {
+      out.unavailable = (out.unavailable ?? 0) + 1;
+      const why = reason as string;
+      let hit = out.reasons.find(r => r.reason === why);
+      if (hit === undefined) { hit = { reason: why, frames: [] }; out.reasons.push(hit); }
+      hit.frames?.push(f.index);
+    }
+  }
+  return out;
+}