cozyclay 2.1.0 → 3.0.0

package/src/motion3/qa/near.js

@@ -0,0 +1,96 @@
+// Measured, not judged (output.observations.near): how close each hand and foot comes to the scene
+// objects. A hand is its palm and its five fingertips, a foot its sole (geometry.js solePoints);
+// every scene body is a box at its pose that frame (object-pose.js: carried, hinged or still).
+// Per frame the nearest body within FAR m names its top group (the object) and the body (the
+// part); consecutive frames near the same object make a run, and the RUNS closest runs are kept,
+// in frame order. gap is the signed distance to the box (sdBox), < 0 inside. No run: nothing
+// within FAR m. A hand is not measured against what it carries (it is on it), and a follow
+// record (it rides the body) is none of these objects.
+// Why: a hand meant to strum floated 20 cm in front of a guitar with QA clean (session df388a9b),
+// and a toe went 4 cm into a stair's edge during a swing (session e7edb718); no other answer said so.
+import { sdBox, solePoints } from "./geometry.js";
+import { objectPoseAt, handOf } from "../object-pose.js";
+import { isFollow } from "../carried.js";
+import { add, apply, dist, len, scale } from "../compiler/math.js";
+
+const FAR = 0.3, RUNS = 2, TIPS = ["Thumb4", "Index4", "Middle4", "Ring4", "Pinky4"];
+const r3 = v => Math.round(v * 1000) / 1000;
+
+export const NEAR_UNITS = "near: hand (palm, fingertips), foot (sole) to the nearest object within 0.3 m (top group; part: the body at the closest frame), 2 closest runs; gap [min, f, max, f] m, < 0 inside"
+
+/** The effector points of a solved pose s: { hand_l, hand_r, foot_l, foot_r } -> [point, ...]. */
+function effectorPoints(sk, s) {
+	const I = sk.index, out = {};
+	for (const [S, k] of [["Left", "l"], ["Right", "r"]]) {
+		const palm = scale(add(s.P[I[`${S}Hand`]], s.P[I[`${S}HandMiddle1`]]), 0.5);
+		out[`hand_${k}`] = [palm, ...TIPS.map(t => s.P[I[`${S}Hand${t}`]]).filter(Boolean)];
+		out[`foot_${k}`] = Object.values(solePoints(sk, s, S));
+	}
+	return out;
+}
+
+/** True while a spec.objects entry over body `id` (its own or a group's) hides it at absolute frame f. */
+const hiddenAt = (out, id, f) => [id, ...(out.ctx.scene.objects[id].ancestors ?? [])]
+	.some(k => { const o = out.ctx.spec.objects?.[k]; return o?.visible && !((out.baked?.[o.visible]?.[f] ?? 0) > 0.5); });
+
+/** The scene bodies at absolute frame f as boxes with their top group, the hand carrying them and a bounding sphere; follow records left out. */
+function boxesAt(out, f) {
+	const { scene, spec } = out.ctx, boxes = [];
+	for (const [id, o] of Object.entries(scene?.objects ?? {})) {
+		const up = o.ancestors ?? [];
+		if ([id, ...up].some(k => isFollow(spec.objects?.[k])) || hiddenAt(out, id, f)) continue;
+		const pose = objectPoseAt(out, id, f);
+		if (!pose) continue;
+		const box = { pos: pose.pos, R: pose.R, half: o.half };
+		boxes.push({ id, root: up[up.length - 1] ?? id, hand: handOf(out, id, f), box, c: add(box.pos, apply(box.R, [0, o.half[1], 0])), r: len(o.half) });
+	}
+	return boxes;
+}
+
+/** Nearest box to a point set: [root, part, gap] within FAR, else null; the boxes hand `side` carries are left out. */
+function nearest(points, boxes, side) {
+	const c = scale(points.reduce((a, p) => add(a, p), [0, 0, 0]), 1 / points.length), spread = Math.max(...points.map(p => dist(p, c)));
+	let best = null;
+	for (const b of boxes) {
+		if (side && b.hand === side) continue;
+		if (dist(c, b.c) - b.r - spread > (best ? best[2] : FAR)) continue;
+		const gap = Math.min(...points.map(p => sdBox(p, b.box)));
+		if (gap <= FAR && (!best || gap < best[2])) best = [b.root, b.id, gap];
+	}
+	return best;
+}
+
+/** Runs of frames with the same nearest object -> the RUNS closest, in frame order. */
+function runsOf(rows, f0) {
+	const runs = [];
+	rows.forEach((row, i) => {
+		const last = runs[runs.length - 1];
+		if (!row) return;
+		const [root, part, gap] = row, f = i + f0;
+		if (last && last.object === root && last.frames[1] === f - 1) {
+			last.frames[1] = f;
+			if (gap < last.gap[0]) { last.gap[0] = gap; last.gap[1] = f; last.part = part; }
+			if (gap > last.gap[2]) { last.gap[2] = gap; last.gap[3] = f; }
+		} else runs.push({ object: root, part, frames: [f, f], gap: [gap, f, gap, f] });
+	});
+	return runs.sort((a, b) => a.gap[0] - b.gap[0]).slice(0, RUNS).sort((a, b) => a.frames[0] - b.frames[0])
+		.map(({ object, part, frames, gap }) => ({ object, ...(part !== object ? { part } : {}), frames, gap: [r3(gap[0]), gap[1], r3(gap[2]), gap[3]] }));
+}
+
+/**
+ * observeNear(sk, out) -> { hand_l?, hand_r?, foot_l?, foot_r? } (null when nothing is within FAR m
+ * of any of them, or the scene has no bodies). Frames are absolute (out.f0 added).
+ */
+export function observeNear(sk, out) {
+	if (!Object.keys(out.ctx.scene?.objects ?? {}).length) return null;
+	const f0 = out.f0 ?? 0, rows = { hand_l: [], hand_r: [], foot_l: [], foot_r: [] };
+	out.frames.forEach(({ s }, i) => {
+		const f = i + f0, boxes = boxesAt(out, f), pts = effectorPoints(sk, s);
+		for (const k of Object.keys(rows)) {
+			// a hand is on what it carries: measure it against everything else
+			rows[k].push(nearest(pts[k], boxes, k.startsWith("hand_") ? k.slice(-1) : null));
+		}
+	});
+	const near = Object.fromEntries(Object.entries(rows).map(([k, r]) => [k, runsOf(r, f0)]).filter(([, r]) => r.length));
+	return Object.keys(near).length ? near : null;
+}

package/src/motion3/qa/object-checks.js

@@ -0,0 +1,135 @@
+// QA of scene objects the spec carries (C3 and 7.1), as plain issues { kind, msg, frame, value,
+// limit } (frame indexes out.frames):
+//   GRAB     "<id>: hand 12.0 cm from it at grab", frame = grab, limit = checks.limits.grab
+//            (default 0.03 m); the distance runs from the prop origin to the part boxes' surface
+//            at their scene pose (where the hand finds them). An object its visible channel shows
+//            only from grab on appears in the hand (a cigarette out of a pocket), and one grabbed
+//            at frame 0 is in hand from the take's first frame (C3, as with no grab): nothing to
+//            pick up (session d5c110a7: a bat kit left on the floor, grab 0, "63.6 cm").
+//   COLLIDE  "<part> x <id>": a body capsule in a carried object (every part box of a group) at
+//            any frame it is shown, the holding hand and forearm excused (the fingers ride on the
+//            hand), and a second hand on the frames it grips the object (../second-hand.js): at
+//            weight 0.5 or more, or with its palm inside the object (a grip the arm turns only
+//            partly still holds the handle: session 6262a69c, f37-40, the agent allowed it);
+//            "<id> x <other>": a carried object in another scene box from grab on, the
+//            support it stood on at grab excused for +-3 frames around grab and release. The
+//            depths and checks.allow work as for the body (checks.js); <id> is the spec.objects
+//            key, so a group reads as one object.
+//   REACH    "<id>: 6.2 cm off its keys": a keyed object the hand could not hold where its keys ask (key-checks.js)
+import { QA_LIMITS, allowance } from "./checks.js";
+import { keyIssues } from "./key-checks.js";
+import { CAPSULES, segPoints, sdBox } from "./geometry.js";
+import { isCarried, propOrigin } from "../carried.js";
+import { objectBoxesAt, partsOf, spanOf, restingAt } from "../object-pose.js";
+import { add, sub, apply, dot, cross, len, dist, scale, norm } from "../compiler/math.js";
+
+const NEAR_SUPPORT = 3;
+
+const centre = b => add(b.pos, apply(b.R, [0, b.half[1], 0]));
+const col = (R, i) => [R[0][i], R[1][i], R[2][i]];
+
+/**
+ * Overlap of two boxes (separating axes): { depth, axis } with depth > 0 when they overlap and
+ * axis the unit direction that moves `a` out of `b` by depth; depth <= 0 when apart. With
+ * `side` (a direction from b toward where a came from) the exit is taken on that side.
+ */
+export function boxOverlap(a, b, side = null) {
+	const ca = centre(a), cb = centre(b), d = sub(ca, cb), A = [0, 1, 2].map(i => col(a.R, i)), B = [0, 1, 2].map(i => col(b.R, i));
+	const axes = [...A, ...B, ...A.flatMap(u => B.map(v => cross(u, v)))];
+	let best = { depth: Infinity, axis: [0, 1, 0] };
+	for (const raw of axes) {
+		if (len(raw) < 1e-6) continue;
+		const L = norm(raw), r = (box, U) => U.reduce((s, u, i) => s + Math.abs(dot(u, L)) * box.half[i], 0), reach = r(a, A) + r(b, B);
+		if (reach - Math.abs(dot(d, L)) <= 0) return { depth: reach - Math.abs(dot(d, L)), axis: L };
+		const out = dot(side ?? d, L) < 0 ? scale(L, -1) : L, depth = reach - dot(d, out);
+		if (depth < best.depth) best = { depth, axis: out };
+	}
+	return best;
+}
+
+/** True when the palm of hand k (between its index and middle finger, where a grip holds) is inside one of `boxes`: the hand holds the object there. */
+const palmIn = (sk, s, k, boxes) => {
+	const S = k === "l" ? "Left" : "Right", p = scale(add(s.P[sk.index[`${S}HandIndex2`]], s.P[sk.index[`${S}HandMiddle2`]]), 0.5);
+	return boxes.some(b => sdBox(p, b) <= 0);
+};
+
+/** True while entry o's record is shown (its `visible` channel above 0.5, or no channel) at absolute f. */
+const shownAt = (out, o, f) => !o.visible || (out.baked?.[o.visible]?.[f] ?? 0) > 0.5;
+
+/** The part boxes of `id` where the hand finds it (any frame f, the hint asks later ones too): its scene pose, or where a fall before its grab left it (C17). */
+const restingBoxes = (out, id, f) => partsOf(out.ctx.scene, id).map(part => ({ ...out.ctx.scene.objects[part], ...restingAt(out, part, f) }));
+
+/** Prop origin to the nearest part box surface of `id` where it rests before grab, at absolute frame f (0 inside). */
+export function grabGap(out, id, f) {
+	const { sk, spec } = out.ctx, fr = out.frames[f - (out.f0 ?? 0)];
+	if (!fr) return null;
+	const p = propOrigin(sk, spec, fr.s, spec.objects[id]);
+	return Math.max(0, Math.min(...restingBoxes(out, id, f).map(box => sdBox(p, box))));
+}
+
+/** The scene box right below `id` at grab (absolute frame), the support it may touch near grab and release. */
+function supportOf(out, id, grab) {
+	const parts = restingBoxes(out, id, grab);
+	if (!parts.length) return null;
+	const low = Math.min(...parts.map(b => b.pos[1] - Math.abs(b.R[1][0]) * b.half[0] - Math.abs(b.R[1][2]) * b.half[2]));
+	const c = scale(parts.map(centre).reduce((s, p) => add(s, p), [0, 0, 0]), 1 / parts.length), probe = [c[0], low - 0.01, c[2]];
+	let best = null;
+	for (const [oid, box] of Object.entries(out.ctx.objectsAt(grab))) {
+		if (box.carried || !box.half) continue;
+		const d = sdBox(probe, box);
+		if (d <= 0.02 && (!best || d < best[1])) best = [oid, d];
+	}
+	return best?.[0] ?? null;
+}
+
+/**
+ * objectChecks(sk, out, spec) -> issues
+ * @param {object} sk  the rig
+ * @param {object} out  compileMotion result (out.ctx.spec, out.ctx.scene; object-pose.js)
+ * @param {object} spec  the expanded spec QA measures (checks, objects)
+ * @returns {{ kind: string, msg: string, frame: number, value: number, limit: number }[]}
+ */
+export function objectChecks(sk, out, spec) {
+	const carried = Object.entries(out.ctx.spec.objects ?? {}).filter(([, o]) => isCarried(o));
+	if (!carried.length) return [];
+	const checks = spec.checks ?? {}, L = { ...QA_LIMITS, ...checks.limits }, allow = checks.allow, issues = [], f0 = out.f0 ?? 0, I = sk.index;
+	const push = (kind, msg, f, value, limit) => issues.push({ kind, msg, frame: f, value: +value.toFixed(4), limit });
+	// checks.allow names the carried id or one of its parts, on either side
+	const lim = (parts, objs) => parts.reduce((v, p) => objs.reduce((w, x) => w ?? allowance(allow, p, x), v), null) ?? L.allow;
+	for (const [id, o] of carried) {
+		const [grab, release] = spanOf(out, o), k = spec.props?.[o.prop]?.hand, excused = new Set([`hand_${k}`, `farm_${k}`]);
+		if (o.grab !== undefined && grab > 0 && out.frames[grab - f0] && shownAt(out, o, grab - 1)) {
+			const gap = grabGap(out, id, grab);
+			if (gap > L.grab) push("GRAB", `${id}: hand ${(gap * 100).toFixed(1)} cm from it at grab`, grab - f0, gap, L.grab);
+		}
+		const support = o.grab !== undefined ? supportOf(out, id, grab) : null;
+		const nearSupport = f => Math.abs(f - grab) <= NEAR_SUPPORT || (o.release !== undefined && Math.abs(f - release) <= NEAR_SUPPORT);
+		for (let i = 0; i < out.frames.length; i++) {
+			const f = i + f0, boxes = objectBoxesAt(out, id, f);
+			if (!boxes || !shownAt(out, o, f)) continue;
+			const ids = boxes.map(b => b.id), spheres = boxes.map(b => [b, centre(b), len(b.half)]), { s } = out.frames[i];
+			const grips = Object.entries(out.frames[i].diag).filter(([k, v]) => /^hold_[lr]$/.test(k) && v?.second === id && (v.w >= 0.5 || palmIn(sk, s, k.slice(-1), boxes))).map(([k]) => `hand_${k.slice(-1)}`);
+			for (const [part, a, b, r] of CAPSULES) {
+				if (excused.has(part) || grips.includes(part)) continue;
+				const A = s.P[I[a]], B = s.P[I[b]], mid = scale(add(A, B), 0.5), reach = r + dist(A, B) / 2, l = lim([part], [id, ...ids]);
+				let pts = null, pen = -Infinity;
+				for (const [box, c, rb] of spheres) {
+					if (reach - (dist(mid, c) - rb) <= l) continue;
+					pts ??= segPoints(A, B);
+					pen = Math.max(pen, r - Math.min(...pts.map(p => sdBox(p, box))));
+				}
+				if (pen > l) push("COLLIDE", `${part} x ${id}`, i, pen, l);
+			}
+			if (f < grab) continue;
+			for (const [oid, ob] of Object.entries(out.objectsAt(i))) {
+				if (!ob.half || ob.ignore || (oid === support && nearSupport(f))) continue;
+				const l = lim([id, ...ids], [oid]), oc = centre(ob), orad = len(ob.half);
+				let depth = -Infinity;
+				for (const [box, c, rb] of spheres) if (dist(c, oc) < rb + orad + l) depth = Math.max(depth, boxOverlap(box, ob).depth);
+				if (depth > l) push("COLLIDE", `${id} x ${oid}`, i, depth, l);
+			}
+		}
+	}
+	keyIssues(out, L, push);
+	return issues;
+}

package/src/motion3/qa/patch.js

@@ -0,0 +1,161 @@
+// C6. Hint fixes -> JSON Patch (RFC 6902, json-patch.js) on the agent's own spec.
+//
+// A hint function may return fix (non-enumerable on the group, never in the output):
+//   { channel: "hand_l", f: 106, delta: [dx, dy, dz] | n }   move a keyed channel by delta at f
+//   { channel: "elbow_r", f: 120, value: [x, y, z] | n }      set a channel at f
+//   { path: "/fix/retime", value: true }                      set a spec path
+//   { path: "/anchors/cupHandle/p", delta: [dx, dy, dz] }     move a spec value by delta
+//   { channel: "root", f, delta, hold: true }                  move the body that stands at f
+// Each becomes g.patch = [{ op, path, value }] against opts.userSpec (the spec as the agent sent
+// it, use[] not expanded): a user key that sets the channel within f +-2 -> replace
+// /keys/<i>/set/<ch>; a standIdle stance moved sideways -> /use/<i>/args/at; otherwise add
+// /keys/- with the frame's value moved. A path fix replaces the value, or adds it when only the
+// last step is missing (or the top-level /fix object). A hold fix moves what placed the body
+// at f by the delta's x and z: a standIdle args.at, a walkTo's length (firstStep with 2 steps,
+// else step; its to when steps follow from it), or the run of the agent's root keys around f.
+// g.patch is set only when the patch applies to userSpec and changes it.
+import { applyPatch } from "../json-patch.js";
+
+const NEAR = 2;
+const round4 = v => (Array.isArray(v) ? v.map(round4) : typeof v === "number" ? Math.round(v * 1e4) / 1e4 : v);
+const tokens = path => path.split("/").slice(1).map(t => t.replaceAll("~1", "/").replaceAll("~0", "~"));
+const pointer = parts => parts.map(t => `/${String(t).replaceAll("~", "~0").replaceAll("/", "~1")}`).join("");
+const isNum = x => typeof x === "number" && Number.isFinite(x);
+
+/** The value at a JSON pointer, or undefined. */
+function valueAt(doc, parts) {
+	let node = doc;
+	for (const t of parts) {
+		if (node === null || typeof node !== "object" || !Object.hasOwn(node, t)) return undefined;
+		node = node[t];
+	}
+	return node;
+}
+
+/** v moved by d (same shape: a number, or a vector of numbers), else undefined. */
+function moved(v, d) {
+	if (isNum(v) && isNum(d)) return v + d;
+	if (Array.isArray(v) && Array.isArray(d) && v.length === d.length && v.every(isNum) && d.every(isNum)) return v.map((x, i) => x + d[i]);
+	return undefined;
+}
+
+/** The user key nearest f (within NEAR frames) that sets channel ch, as its index; -1 if none. */
+function userKey(userSpec, ch, f) {
+	let best = -1;
+	(userSpec.keys ?? []).forEach((k, i) => {
+		if (!k?.set || !Object.hasOwn(k.set, ch) || !isNum(k.f) || Math.abs(k.f - f) > NEAR) return;
+		if (best < 0 || Math.abs(k.f - f) < Math.abs(userSpec.keys[best].f - f)) best = i;
+	});
+	return best;
+}
+
+/** A standIdle stance moved by the root's sideways delta: /use/<i>/args/at. */
+function standPatch(X, userSpec, fix, near) {
+	const m = /^use\[(\d+)\] standIdle$/.exec(near?.src ?? ""), d = fix.delta;
+	if (!m || fix.channel !== "root" || !Array.isArray(d) || Math.hypot(d[0], d[2]) < Math.abs(d[1])) return null;
+	const i = Number(m[1]), u = userSpec.use?.[i], root = X.fr(near.f).c.root;
+	if (u?.skill !== "standIdle") return null;
+	const at = Array.isArray(u.args?.at) ? u.args.at : root && [root[0], root[2]];
+	if (!at) return null;
+	const value = round4(at.map((v, j) => v + (j === 0 ? d[0] : j === at.length - 1 ? d[2] : 0)));
+	if (!u.args) return [{ op: "add", path: `/use/${i}/args`, value: { at: value } }];
+	return [{ op: Object.hasOwn(u.args, "at") ? "replace" : "add", path: `/use/${i}/args/at`, value }];
+}
+
+/** A walkTo made longer or shorter by the delta along the body's heading at f (null when it is mostly sideways). */
+function walkPatch(X, userSpec, i, fix) {
+	const u = userSpec.use?.[i], a = u?.args ?? {}, d = fix.delta, h = (X.fr(fix.f).c.yaw ?? 0) * Math.PI / 180;
+	const along = d[0] * Math.sin(h) + d[2] * Math.cos(h);
+	if (u?.skill !== "walkTo" || Math.abs(d[0] * Math.cos(h) - d[2] * Math.sin(h)) > Math.abs(along)) return null;
+	const set = (arg, value) => [u.args ? { op: Object.hasOwn(a, arg) ? "replace" : "add", path: `/use/${i}/args/${arg}`, value: round4(value) } : { op: "add", path: `/use/${i}/args`, value: { [arg]: round4(value) } }];
+	if (a.steps === undefined && Array.isArray(a.to)) return set("to", a.to.map((v, j) => v + (j === 0 ? d[0] : j === a.to.length - 1 ? d[2] : 0)));
+	const steps = a.steps ?? 8, arg = steps <= 2 ? "firstStep" : "step", now = a[arg] ?? (arg === "step" ? 0.5 : 0.4), value = now + along / Math.max(1, steps - 2);
+	return steps >= 2 && value > 0.05 ? set(arg, value) : null;
+}
+
+/** The agent's root keys around f (no skill root key between them) moved by the delta's x and z. */
+function rootRunPatch(X, userSpec, fix) {
+	const list = X.keys("root"), mine = k => /^keys\[\d+\]$/.test(k.src);
+	const at = list.findLastIndex(k => k.f <= fix.f);
+	if (at < 0 || !mine(list[at])) return null;
+	let a = at, b = at;
+	while (a > 0 && mine(list[a - 1])) a -= 1;
+	while (b < list.length - 1 && mine(list[b + 1])) b += 1;
+	return list.slice(a, b + 1).map(k => {
+		const j = Number(/\d+/.exec(k.src)[0]), r = userSpec.keys?.[j]?.set?.root;
+		return Array.isArray(r) && r.length === 3 ? { op: "replace", path: `/keys/${j}/set/root`, value: round4([r[0] + fix.delta[0], r[1], r[2] + fix.delta[2]]) } : null;
+	}).filter(Boolean);
+}
+
+/** fix.hold: what placed the body at f (the root key at or before it) moves. */
+function bodyPatch(X, userSpec, fix) {
+	if (!Array.isArray(fix.delta) || !X?.fr) return null;
+	const prev = X.bracket("root", fix.f).prev, m = /^use\[(\d+)\] (standIdle|walkTo)\b/.exec(prev?.src ?? "");
+	if (m?.[2] === "standIdle") return standPatch(X, userSpec, fix, prev);
+	if (m?.[2] === "walkTo") return walkPatch(X, userSpec, Number(m[1]), fix);
+	const run = prev && rootRunPatch(X, userSpec, fix);
+	return run?.length ? run : null;
+}
+
+function channelPatch(X, userSpec, fix) {
+	const { channel: ch, f } = fix;
+	if (typeof ch !== "string" || !isNum(f)) return null;
+	if (fix.hold) return bodyPatch(X, userSpec, fix);
+	const to = v => (fix.value !== undefined ? fix.value : moved(v, fix.delta));
+	const i = userKey(userSpec, ch, f);
+	if (i >= 0) {
+		const value = to(userSpec.keys[i].set[ch]);
+		return value === undefined ? null : [{ op: "replace", path: pointer(["keys", i, "set", ch]), value: round4(value) }];
+	}
+	if (!X?.fr) return null;
+	const { prev, next } = X.bracket(ch, f);
+	const near = prev && f - prev.f <= NEAR ? prev : next && next.f - f <= NEAR ? next : null;
+	const stand = fix.delta !== undefined && standPatch(X, userSpec, fix, near);
+	if (stand) return stand;
+	const value = to(X.fr(f).c[ch]);
+	return value === undefined ? null : [{ op: "add", path: "/keys/-", value: { f: Math.round(f), set: { [ch]: round4(value) } } }];
+}
+
+function pathPatch(userSpec, fix) {
+	if (typeof fix.path !== "string" || !fix.path.startsWith("/")) return null;
+	const parts = tokens(fix.path), now = valueAt(userSpec, parts);
+	const value = fix.delta === undefined ? fix.value : now === undefined && fix.path.endsWith("/offset") ? fix.delta : moved(now, fix.delta);
+	if (value === undefined) return null;
+	if (now !== undefined) return [{ op: "replace", path: fix.path, value: round4(value) }];
+	const parent = valueAt(userSpec, parts.slice(0, -1));
+	if (parent !== undefined) return [{ op: "add", path: fix.path, value: round4(value) }];
+	// a missing top-level object (spec.fix): add it with the one member
+	if (parts.length === 2 && parts[0] === "fix") return [{ op: "add", path: pointer([parts[0]]), value: { [parts[1]]: round4(value) } }];
+	return null;
+}
+
+/** The patch for one fix, or null when it does not apply mechanically or changes nothing. */
+function patchOf(fix, X, userSpec) {
+	const patch = fix.channel !== undefined ? channelPatch(X, userSpec, fix) : fix.path !== undefined ? pathPatch(userSpec, fix) : null;
+	if (!patch) return null;
+	try {
+		return JSON.stringify(applyPatch(userSpec, patch)) === JSON.stringify(userSpec) ? null : patch;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * attachPatches(groups, { X, userSpec }) -> groups (the same array)
+ * @param {object[]} groups  ranked QA groups, each maybe with a non-enumerable g.fix
+ * @param {{ X: object, userSpec?: object }} ctx  X = the explain context (qa/explain.js: X.out,
+ *   X.spec the expanded spec, X.keys(ch), X.bracket(ch, f)); userSpec undefined = no patches
+ */
+export function attachPatches(groups, { X, userSpec } = {}) {
+	if (!userSpec || typeof userSpec !== "object") return groups;
+	for (const g of groups) {
+		if (!g.fix) continue;
+		try {
+			const patch = patchOf(g.fix, X, userSpec);
+			if (patch) g.patch = patch;
+		} catch {
+			// a fix the context cannot place (no frame, no key table) gets no patch
+		}
+	}
+	return groups;
+}

package/src/motion3/qa/severity.js

@@ -0,0 +1,38 @@
+// C6. How bad a QA issue group is, one formula for the agent (qa.groups order and severity),
+// the open-parameter search (search.js cost) and repair (repair.js): the issue count weighted by
+// how far the worst issue is past its limit, at most 4x. See docs/motion-api-v3.1.md.
+
+/** Kinds whose value must stay ABOVE the limit (a cosine, a drop, a clearance). */
+export const LOW_IS_BAD = new Set(["ORIENT", "BELOW", "CLEARANCE"]);
+
+/** How far the worst issue of group g is past its limit (>= 0, in the kind's unit). */
+export const excessOf = g => Math.max(0, LOW_IS_BAD.has(g.kind) ? g.limit - g.worst : g.worst - g.limit);
+
+/** Unrounded severity; search.js sums these as its cost. */
+export const weightOf = g => g.count * (1 + Math.min(3, excessOf(g) / Math.max(Math.abs(g.limit), 0.01)));
+
+/** Severity of group g, rounded to 2 decimals. */
+export const severityOf = g => Math.round(weightOf(g) * 100) / 100;
+
+/** A measurement in a subject: a free-standing number ("12.0 cm", "120deg", "-0.30") or a frame ("f150"). */
+const MEASURE = /(?<![\w\-.[])[-+]?\d+(\.\d+)?|\bf\d+\b/g;
+
+/**
+ * The grouping key of an issue (kind + subject): every measurement in the subject becomes "#",
+ * so one problem at many frames and depths is one group. Digits that are part of a name stay:
+ * an id ("cube-6", "empty-2"), a bone ("LeftHandIndex3"), a bracketed index ("contacts[1]", a
+ * default check name, qa/check-names.js) and the whole "<name>: " prefix of a named check or goal.
+ */
+export const groupKey = g => {
+	const cut = g.subject.indexOf(": "), head = cut >= 0 ? g.subject.slice(0, cut + 2) : "";
+	return `${g.kind} ${head}${g.subject.slice(head.length).replace(MEASURE, m => (m[0] === "f" ? "f#" : "#"))}`;
+};
+
+/**
+ * Adds excess (4 decimals) and severity to every group and returns them ordered: GOAL groups
+ * first, then severity, then count, both descending (ties keep their order).
+ */
+export function rankGroups(groups) {
+	for (const g of groups) { g.excess = Math.round(excessOf(g) * 1e4) / 1e4; g.severity = severityOf(g); }
+	return groups.sort((a, b) => (b.kind === "GOAL") - (a.kind === "GOAL") || b.severity - a.severity || b.count - a.count);
+}

package/src/motion3/qa/spec-checks.js

@@ -0,0 +1,65 @@
+// Task checks the agent declares in spec.checks (balance is style: style.js).
+//   contacts:  [{ name, point, target, tol, when }]       point on target (e.g. filter on lips)
+//   orient:    [{ name, from, to, along, minCos, when }]  direction from->to against "face" | "up" | [x,y,z]
+//   below:     [{ name, joint, ref, min, when }]          joint at least `min` m below ref (no chicken wing)
+//   clearance: [{ name, part, object, min, frames }]      body part keeps `min` m from an object
+//   appear:    [{ name, channel, joint, anchor, tol }]    a visibility switch happens with joint at anchor
+//   supports:  [{ object, part, tol }]                     frames where `part` rests on `object` skip balance (style.js)
+// point/from/to: "joint:Name" | "prop:name.point" | "anchor:name"; when: weight channel (> 0.99) or [f0, f1].
+// f below indexes out.frames (frame out.f0 + f when the compile was windowed).
+import { sub, dot, norm, len } from "../compiler/math.js";
+import { carried } from "../compiler/limbs.js";
+import { resolveAnchor } from "../compiler/anchors.js";
+import { CAPSULES, segPoints, sdBox } from "./geometry.js";
+
+export function pointOf(out, f, ref) {
+	const { s, diag, c } = out.frames[f], [kind, rest] = ref.split(/:(.*)/s);
+	if (kind === "joint") return s.P[out.ctx.sk.index[rest]];
+	if (kind === "prop") { const [p, pt] = rest.split("."); return diag.props?.[p]?.[pt] ?? null; }
+	if (kind === "anchor") return resolveAnchor(out.ctx, rest, s, diag, c);
+	throw new Error(`MOTION_SPEC_INVALID: check point "${ref}"`);
+}
+
+const active = (out, f, when) => (Array.isArray(when) ? f + (out.f0 ?? 0) >= when[0] && f + (out.f0 ?? 0) <= when[1] : when ? (out.frames[f].c[when] ?? 0) > 0.99 : true);
+
+function alongDir(out, f, along) {
+	if (along === "up") return [0, 1, 0];
+	if (along === "face") return carried(out.ctx.sk, out.frames[f].s, out.ctx.sk.index.Head, [0, 0, 1]);
+	return norm(along);
+}
+
+export function specChecks(out, checks = {}) {
+	const issues = [], n = out.frames.length, sk = out.ctx.sk, I = sk.index;
+	const push = (kind, msg, f, value, limit) => issues.push({ kind, msg, frame: f, value: +value.toFixed(4), limit });
+	for (let f = 0; f < n; f++) {
+		for (const k of checks.contacts ?? []) if (active(out, f, k.when)) {
+			const a = pointOf(out, f, k.point), b = pointOf(out, f, k.target);
+			if (!a || !b) continue;
+			const e = len(sub(a, b));
+			if (e > (k.tol ?? 0.01)) push("CONTACT", `${k.name}: ${(e * 100).toFixed(1)} cm apart`, f, e, k.tol ?? 0.01);
+		}
+		for (const k of checks.orient ?? []) if (active(out, f, k.when)) {
+			const a = pointOf(out, f, k.from), b = pointOf(out, f, k.to);
+			if (!a || !b) continue;
+			const cosv = dot(norm(sub(b, a)), alongDir(out, f, k.along));
+			if (cosv < (k.minCos ?? 0.64)) push("ORIENT", `${k.name}: cos ${cosv.toFixed(2)}`, f, cosv, k.minCos ?? 0.64);
+		}
+		for (const k of checks.below ?? []) if (active(out, f, k.when)) {
+			const { P } = out.frames[f].s, drop = P[I[k.ref]][1] - P[I[k.joint]][1];
+			if (drop < (k.min ?? 0.08)) push("BELOW", `${k.name}: ${k.joint} only ${(drop * 100).toFixed(1)} cm below ${k.ref}`, f, drop, k.min ?? 0.08);
+		}
+		for (const k of checks.clearance ?? []) if (active(out, f, k.frames)) {
+			const box = out.objectsAt(f)[k.object], cap = CAPSULES.find(c => c[0] === k.part);
+			if (!box || !cap) continue;
+			const { P } = out.frames[f].s, d = Math.min(...segPoints(P[I[cap[1]]], P[I[cap[2]]]).map(p => sdBox(p, box))) - cap[3];
+			if (d < k.min) push("CLEARANCE", `${k.name}: ${(d * 100).toFixed(1)} cm`, f, d, k.min);
+		}
+	}
+	for (const k of checks.appear ?? []) for (let f = 1; f < n; f++) {
+		const was = (out.frames[f - 1].c[k.channel] ?? 0) > 0.5, is = (out.frames[f].c[k.channel] ?? 0) > 0.5;
+		if (was === is) continue;
+		const e = len(sub(pointOf(out, f, `joint:${k.joint}`), pointOf(out, f, `anchor:${k.anchor}`)));
+		if (e > (k.tol ?? 0.035)) push("APPEAR", `${k.name}: switches with the hand ${(e * 100).toFixed(1)} cm from ${k.anchor}`, f, e, k.tol ?? 0.035);
+	}
+	return issues;
+}