cozyclay 3.1.1 → 3.1.2

package/src/motion3/qa/asked.js

@@ -0,0 +1,113 @@
+// Measured, not judged (output.observations.asked): what the spec asked against what the take did, the
+// quantities agents probed or re-compiled for right after a compile (session study: the root where a walk
+// ended, the mouth and the cup top on the drink frame, when the fingers met the cup), one line each:
+//   use[i] <skill>[ <side> <anchor>] f<a>-<b>: at [x, z] yaw <deg>[ (asked <deg>)][; to [x, z]: <m> m short|past[, <m> m aside][, ...]]
+//       at = the feet's midpoint at the skill's last frame (what walkTo.to and standIdle.at place), yaw = the
+//       body's heading there; a walkTo whose steps are given only aims at to (the steps set the distance)
+//   <contact name> f<a>-<b>: gap <cm> f<f> .. <cm> f<f> (tol <cm>)   checks.contacts (reachGrip adds "fingers
+//       on <anchor>"): the frames its when holds, the closest and the farthest gap; "never on" when it never holds
+//   goal <name> f<f>: <ref> [x, y, z], <ref> [x, y, z][; best <m> f<f>]   the goal's points on the frame its
+//       result names (near and above; moved and still when they fail); best: the closest frame of a near goal
+//       held on every frame
+// An object ref is a point of the AABB of its boxes (refs.js), so a line names which: (box top) is the top-face
+// centre, not a rim or an opening; (box base) the bottom-face centre; (box centre) the centre; a bare object in
+// a near goal is its surface. Frames are absolute and follow a retime (out.timeMap); metres to 3 decimals.
+import { refPoint, refDistance } from "../refs.js";
+import { active, contactGap } from "./spec-checks.js";
+import { goalKinds, goalName, movedRef } from "./goals.js";
+import { m3 } from "./fmt.js";
+
+const MAX_SKILLS = 8, MAX_CONTACTS = 6, MAX_GOALS = 8, OFF = 0.05, YAW_OFF = 5;
+
+const v3 = p => `[${p.map(m3).join(", ")}]`;
+const cm = v => `${Math.round(v * 1000) / 10}`;
+const wrap = d => ((d % 360) + 540) % 360 - 180;
+const meaning = { top: " (box top)", base: " (box base)", center: " (box centre)", rim: " (opening)" };
+
+/** A ref with what an object point is: "object:cup.top (box top)". */
+function named(ref, bare) {
+	const m = /^object:.+?(?:\.(center|top|base|rim))?$/s.exec(ref);
+	if (!m) return ref;
+	return `${ref}${m[1] ? meaning[m[1]] : bare ? " (surface)" : meaning.center}`;
+}
+
+/** The feet's midpoint [x, z] and the heading at absolute frame f, or null outside the compiled window. */
+function standAt(out, f) {
+	const fr = out.frames[f - (out.f0 ?? 0)];
+	if (!fr) return null;
+	const { P } = fr.s, I = out.ctx.sk.index, l = P[I.LeftFoot], r = P[I.RightFoot];
+	return { at: [(l[0] + r[0]) / 2, (l[2] + r[2]) / 2], yaw: fr.c?.yaw ?? 0 };
+}
+
+function skillLine(out, u, i, use, map) {
+	const last = out.frameCount - 1, clamp = f => Math.max(0, Math.min(last, Math.round(map(f))));
+	const a = clamp(u.f0), b = clamp(u.end ?? u.f0), end = standAt(out, b), args = use?.args ?? {};
+	if (!end) return null;
+	const side = args.side ? ` ${args.side}` : "", anchor = args.anchor ? ` ${args.anchor}` : "";
+	let line = `use[${i}] ${u.skill}${side}${anchor} f${a}-${b}: at ${v3(end.at)} yaw ${Math.round(wrap(end.yaw))}`;
+	const heading = Array.isArray(args.heading) ? args.heading[args.heading.length - 1] : args.heading;
+	if (typeof heading === "number" && Math.abs(wrap(end.yaw - heading)) > YAW_OFF) line += ` (asked ${heading})`;
+	const goal = Array.isArray(args.to) ? [args.to[0], args.to[args.to.length - 1]] : Array.isArray(args.at) && !u.placed ? args.at : null;
+	if (goal) {
+		const d = [end.at[0] - goal[0], end.at[1] - goal[1]], off = Math.hypot(...d);
+		if (off > OFF) {
+			const start = args.to && standAt(out, a), dir = start && Math.hypot(goal[0] - start.at[0], goal[1] - start.at[1]) > 1e-6
+				? [goal[0] - start.at[0], goal[1] - start.at[1]].map((x, _, v) => x / Math.hypot(...v)) : null;
+			const along = dir ? d[0] * dir[0] + d[1] * dir[1] : null, aside = dir ? Math.abs(d[0] * dir[1] - d[1] * dir[0]) : null;
+			const how = dir ? `${m3(Math.abs(along))} m ${along < 0 ? "short" : "past"}${aside > OFF ? `, ${m3(aside)} m aside` : ""}` : `${m3(off)} m off`;
+			line += `; ${args.to ? "to" : "at"} ${v3(goal)}: ${how}${args.to && args.steps !== undefined ? ", args.steps set the distance (to only aims)" : ""}`;
+		}
+	}
+	return line;
+}
+
+function contactLine(out, k) {
+	const f0 = out.f0 ?? 0;
+	let lo = null, hi = null, first = null, lastOn = null;
+	for (let f = 0; f < out.frames.length; f++) {
+		if (!active(out, f, k.when)) continue;
+		first ??= f + f0; lastOn = f + f0;
+		const e = contactGap(out, f, k);
+		if (e === null) continue;
+		if (!lo || e < lo[0]) lo = [e, f + f0];
+		if (!hi || e > hi[0]) hi = [e, f + f0];
+	}
+	if (first === null) return `${k.name}: never on${typeof k.when === "string" ? ` (${k.when} never > 0.99)` : ""}`;
+	return `${k.name} f${first}-${lastOn}: gap ${lo ? `${cm(lo[0])} cm f${lo[1]} .. ${cm(hi[0])} cm f${hi[1]}` : "unknown"} (tol ${cm(k.tol ?? 0.01)})`;
+}
+
+function goalLine(out, g, i, result) {
+	const kind = goalKinds(g)[0];
+	if (!result || result.at === null || !(kind === "near" || kind === "above" || (!result.ok && (kind === "moved" || kind === "still")))) return null;
+	const refs = kind === "near" || kind === "above" ? g[kind] : [movedRef(g[kind].includes(":") ? g[kind] : `object:${g[kind]}`)];
+	const pts = refs.map(r => [r, refPoint(out, result.at, r)]);
+	if (pts.some(([, p]) => !p)) return null;
+	let line = `goal ${goalName(g, i)} f${result.at}: ${pts.map(([r, p]) => `${named(r, kind === "near")} ${v3(p)}`).join(", ")}`;
+	if (kind === "near" && Array.isArray(g.at) && g.at[0] !== g.at[1] && (g.mode ?? "all") === "all") {
+		const f0 = out.f0 ?? 0;
+		let best = null;
+		for (let f = Math.max(g.at[0], f0); f <= Math.min(g.at[1], f0 + out.frames.length - 1); f++) {
+			const d = refDistance(out, f, g.near[0], g.near[1]);
+			if (d !== null && (!best || d < best[0])) best = [d, f];
+		}
+		if (best && best[1] !== result.at) line += `; best ${m3(best[0])} f${best[1]}`;
+	}
+	return line;
+}
+
+/**
+ * observeAsked(out, { used, use, checks, goals, results }) -> string[] | null
+ * @param {object} out  compileMotion result
+ * @param {{ used: object[], use?: object[], checks?: object, goals?: object[], results?: object[] }} ctx  used = the skills
+ *   expandUse ran, use = the spec's own use entries (their args are what was asked), checks = the measured checks,
+ *   goals = the expanded spec's goals and results = qa.goals (same order, by name)
+ */
+export function observeAsked(out, { used = [], use = [], checks = {}, goals = [], results = [] }) {
+	const map = out.timeMap ?? (f => f), byName = new Map(results.map(r => [r.name, r]));
+	const lines = [
+		...used.slice(0, MAX_SKILLS).map((u, i) => skillLine(out, u, i, use[i], map)),
+		...(checks.contacts ?? []).slice(0, MAX_CONTACTS).map(k => contactLine(out, k)),
+		...goals.map((g, i) => goalLine(out, g, i, byName.get(goalName(g, i)))).filter(Boolean).slice(0, MAX_GOALS),
+	].filter(Boolean);
+	return lines.length ? lines : null;
+}

package/src/motion3/qa/goals.js

@@ -1,6 +1,7 @@
 // Goals (C8): what the motion must achieve, measured on the compiled frames. A goal names one
 // predicate and the frames it must hold on (at: an absolute frame or [f0, f1]):
-//   near:  [a, b]  refDistance(a, b) <= tol (default 0.05 m)
+//   near:  [a, b]  refDistance(a, b) <= tol (default 0.05 m); a round body's .top and the mouth measure its rim
+//                  (nearRefs), and a failing near goal on a .top says which point it read
 //   above: [a, b]  a.y - b.y >= by (default 0 m)
 //   moved: ref     an object's point (default its base) is at least by (default 0.05 m) from
 //                  where the scene put it; any other point ref (prop:, joint:, landmark:, anchor:)
@@ -19,7 +20,7 @@
 // count and first..last show how much of at fails and the search (search.js) sees progress; "any"
 // one, at the best frame. Issue frames index out.frames (out.f0 + i); goals[].at and every frame in
 // a message are absolute.
-import { refPoint, refDistance } from "../refs.js";
+import { refPoint, refDistance, openingOf } from "../refs.js";
 import { partsOf } from "../object-pose.js";
 import { add, apply, len, sub } from "../compiler/math.js";
 import { m3 } from "./fmt.js";
@@ -42,13 +43,14 @@ export const goalNeed = (g, kind) => (AT_MOST.has(kind) ? g.tol : g.by) ?? DEFAU
 const goalMode = (g, kind) => g.mode ?? (kind === "speed" ? "any" : "all");
 
 /** moved and still measure the named point of an object ref (its base when none is named), any other ref as it is. */
-export const movedRef = ref => (!ref.startsWith("object:") || /\.(center|top|base)$/.test(ref) ? ref : `${ref}.base`);
+export const movedRef = ref => (!ref.startsWith("object:") || /\.(center|top|base|rim)$/.test(ref) ? ref : `${ref}.base`);
 
 /** Where the scene put the point of a moved object ref: the same AABB point refs.js answers, from the scene boxes. */
 function scenePoint(scene, ref) {
-	const [, id, which] = /^object:(.+)\.(center|top|base)$/s.exec(movedRef(ref)) ?? [];
+	const [, id, which] = /^object:(.+)\.(center|top|base|rim)$/s.exec(movedRef(ref)) ?? [];
 	const boxes = partsOf(scene, id).map(p => scene.objects[p]);
 	if (!boxes.length) return null;
+	if (which === "rim") return openingOf(boxes).o;
 	const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
 	for (const b of boxes) for (const x of [-1, 1]) for (const y of [0, 2]) for (const z of [-1, 1]) {
 		const p = add(b.pos, apply(b.R, [x * b.half[0], y * b.half[1], z * b.half[2]]));
@@ -74,9 +76,35 @@ function speedAt(out, ref, f) {
 	return q ? len(sub(p, q)) * fps : null;
 }
 
+const MOUTH = "landmark:mouth", TOP = /^object:(.+)\.top$/s;
+
+/**
+ * A near goal of an object's .top and the mouth, on a body whose highest part is round (a cylinder: a cup, a can, a
+ * bottle), measures its opening's rim nearest the mouth (refs.js .rim): .top is the top-face centre of its world
+ * bounding box, which a tilted cup lifts off the rim it is drunk from (a session read 8 failures in a row off it).
+ * -> the refs measured, as given when nothing changes.
+ */
+export function nearRefs(scene, g) {
+	const [a, b] = g.near, top = [a, b].map(r => TOP.exec(r)?.[1]), i = top[0] && b === MOUTH ? 0 : top[1] && a === MOUTH ? 1 : -1;
+	if (i < 0) return g.near;
+	const parts = partsOf(scene, top[i]).map(p => scene.objects[p]).filter(p => p?.half && p.pos && p.R);
+	const high = parts.length ? parts.reduce((p, q) => (q.pos[1] + 2 * q.half[1] > p.pos[1] + 2 * p.half[1] ? q : p)) : null;
+	if (high?.renderer !== "cylinder") return g.near;
+	return g.near.map((r, j) => (j === i ? `object:${top[i]}.rim` : r));
+}
+
+/** What a near goal's .top measured, said in its message (refs.js): the rim it was read at, or the bounding-box top it is. */
+function topNote(scene, g) {
+	const ref = g.near.find(r => TOP.test(r));
+	if (!ref) return "";
+	const id = TOP.exec(ref)[1];
+	return nearRefs(scene, g) !== g.near ? ` (measured at ${id}'s rim nearest the mouth, object:${id}.rim; its .top is its bounding box's top)`
+		: ` (${ref} is the top-face centre of its world bounding box; object:${id}.rim is its opening, which tilts with it)`;
+}
+
 /** The measured value of goal g at absolute frame f (metres, m/s for speed), or null when a ref is unknown there. */
 function measure(out, g, kind, f, home) {
-	if (kind === "near") return refDistance(out, f, g.near[0], g.near[1]);
+	if (kind === "near") { const [a, b] = nearRefs(out.ctx.scene, g); return refDistance(out, f, a, b); }
 	if (kind === "above") {
 		const a = refPoint(out, f, g.above[0]), b = refPoint(out, f, g.above[1]);
 		return a && b ? a[1] - b[1] : null;
@@ -139,9 +167,9 @@ function windowOf(X, i) {
 	return { a, b };
 }
 
-function message(name, kind, row, need, any, from) {
+function message(name, kind, row, need, any, from, note = "") {
 	const where = any ? `f${row.f}, the best of f${any[0]}-f${any[1]}` : `f${row.f}`;
-	if (kind === "near") return `${name}: ${m3(row.v)} m at ${where} (needs <= ${need})`;
+	if (kind === "near") return `${name}: ${m3(row.v)} m at ${where} (needs <= ${need})${note}`;
 	if (kind === "above") return `${name}: ${m3(row.v)} m above at ${where} (needs >= ${need})`;
 	if (kind === "speed") return `${name}: ${m3(row.v)} m/s at ${where} (needs >= ${need})`;
 	if (kind === "still") return `${name}: ${m3(row.v)} m from ${from === undefined ? "its scene pose" : `f${from}`} at ${where} (needs <= ${need})`;
@@ -183,8 +211,9 @@ export function goalChecks(out, goals) {
 		const ok = pick.short <= 0;
 		results.push({ name, kind, ok, value: m3(pick.v), at: pick.f, need });
 		if (ok) return;
+		const note = kind === "near" ? topNote(out.ctx.scene, g) : "";
 		for (const r of any ? [pick] : rows.filter(r => r.short > 0)) {
-			issues.push({ kind: "GOAL", msg: message(name, kind, r, need, any && cut ? [w.a, w.b] : null, from), frame: r.f - f0, value: round4(r.short), limit: 0 });
+			issues.push({ kind: "GOAL", msg: message(name, kind, r, need, any && cut ? [w.a, w.b] : null, from, kind === "near" ? note : ""), frame: r.f - f0, value: round4(r.short), limit: 0 });
 		}
 	});
 	return { issues, results };

package/src/motion3/qa/hints-goal.js

@@ -14,7 +14,7 @@ import { inHandAt } from "../object-pose.js";
 import { refPoint } from "../refs.js";
 import { scale, norm, sub, len } from "../compiler/math.js";
 import { moveHint } from "./hints-contact.js";
-import { goalKinds, goalName, goalNeed, goalWindow, movedHome, movedRef } from "./goals.js";
+import { goalKinds, goalName, goalNeed, goalWindow, movedHome, movedRef, nearRefs } from "./goals.js";
 import { m3, vec } from "./fmt.js";
 
 const MARGIN = 0.003, LEAK = 0.02, BODY_MAX = 0.2;
@@ -79,7 +79,7 @@ function partOf(X, ref, f) {
 	const [, kind, rest] = /^([a-z]+):(.+)$/s.exec(ref) ?? [];
 	if (kind === "prop") return X.spec.props?.[rest.split(".")[0]]?.hand ? `hand_${X.spec.props[rest.split(".")[0]].hand}` : null;
 	if (kind === "object") {
-		const o = carrierOf(X, rest.replace(/\.(center|top|base)$/, ""), f), k = o && X.spec.props?.[o.prop]?.hand;
+		const o = carrierOf(X, rest.replace(/\.(center|top|base|rim)$/, ""), f), k = o && X.spec.props?.[o.prop]?.hand;
 		return k ? `hand_${k}` : null;
 	}
 	if (kind === "landmark") return "root";
@@ -107,7 +107,8 @@ function plan(X, goal, kind, f, amount, from) {
 		const away = p && home && len(sub(p, home)) > 1e-3 ? norm(sub(p, home)) : [0, 1, 0];
 		return part ? [part, scale(away, kind === "still" ? -amount : amount)] : null;
 	}
-	const [a, b] = goal[kind], pa = partOf(X, a, f), pb = partOf(X, b, f);
+	// a near goal measures what goals.js nearRefs reads (a cup's rim at the mouth)
+	const [a, b] = kind === "near" ? nearRefs(X.out.ctx.scene, goal) : goal[kind], pa = partOf(X, a, f), pb = partOf(X, b, f);
 	const rank = p => (p?.startsWith("hand_") ? 2 : p ? 1 : 0), moveA = rank(pa) >= rank(pb);
 	const part = moveA ? pa : pb, sign = moveA ? 1 : -1;
 	if (!part) return null;
@@ -136,13 +137,13 @@ export const goalHints = {
 		const move = plan(X, goal, kind, f, amount, w.a);
 		if (!move) {
 			if (kind === "still" && goal.still.startsWith("object:")) {
-				const id = goal.still.slice(7).replace(/\.(center|top|base)$/, "");
+				const id = goal.still.slice(7).replace(/\.(center|top|base|rim)$/, "");
 				return { cause: `objects.${id}`, hint: `${id} moves at f${f}, where it should stay: hold its hinge channel or keys until then, or start them later${why}` };
 			}
 			if (kind === "still") return { cause: `goal ${name}`, hint: `${goal.still} moves at f${f} and nothing that follows the body moves it; name a joint, prop point or held object${why}` };
 			if (kind === "moved" && !goal.moved.startsWith("object:")) return { cause: `goal ${name}`, hint: `${goal.moved} does not move with the body at f${f}; name a joint, prop point or held object` };
 			if (kind === "moved") {
-				const id = goal.moved.slice(7).replace(/\.(center|top|base)$/, "");
+				const id = goal.moved.slice(7).replace(/\.(center|top|base|rim)$/, "");
 				return { cause: `objects.${id}`, hint: `${id} is not in a hand at f${f}, so nothing moves it: carry it (objects.${id} = { prop, grab }) or hinge it` };
 			}
 			return { cause: `goal ${name}`, hint: `neither ${goal[kind][0]} nor ${goal[kind][1]} moves with the body at f${f}; name a joint, prop point or held object` };

package/src/motion3/qa/index.js

@@ -2,7 +2,8 @@
 // moves (object-checks.js), the other people in the scene (people-checks.js, PERSON), its goals (goals.js) and the style checks it opted into by naming
 // their limit (style.js; otherwise style is measured, not judged: observeMotion). Groups are
 // ranked by severity.js. total counts frame-level issues (a goal held on "all" frames adds one per failing frame); problems
-// counts the groups, which is what a person reads (src/qa-label.js).
+// counts the groups, which is what a person reads (src/qa-label.js). qa.warnings (arm-checks.js) reads an awkward
+// working arm and never fails a take.
 import { generalChecks, QA_LIMITS } from "./checks.js";
 import { styleChecks, floatChecks } from "./style.js";
 import { specChecks } from "./spec-checks.js";
@@ -12,6 +13,7 @@ import { loadChecks } from "../load.js";
 import { goalChecks } from "./goals.js";
 import { wristIssues } from "./wrist-checks.js";
 import { peopleChecks } from "./people-checks.js";
+import { armWarnings } from "./arm-checks.js";
 import { explainGroups } from "./explain.js";
 import { LOW_IS_BAD, groupKey, rankGroups } from "./severity.js";
 
@@ -42,5 +44,6 @@ export function runMotionQa(sk, out, spec, opts = {}) {
 	if (out.f0) for (const i of issues) i.frame += out.f0;
 	const groups = summarizeIssues(issues);
 	if (opts.explain !== false) explainGroups(sk, out, spec, groups, { userSpec: opts.userSpec });
-	return { ok: issues.length === 0, total: issues.length, problems: groups.length, ...(spec.goals ? { goals: goals.results } : {}), groups };
+	const warnings = armWarnings(sk, out);
+	return { ok: issues.length === 0, total: issues.length, problems: groups.length, ...(spec.goals ? { goals: goals.results } : {}), groups, ...(warnings.length ? { warnings } : {}) };
 }

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

@@ -62,7 +62,7 @@ export function keyHint(X, g) {
 
 const r1 = v => Math.round(v * 10) / 10, r2 = v => Math.round(v * 100) / 100;
 /** observations.held units: what a row of a keyed object says. */
-export const HELD_UNITS = "held: per key, deg = the drawn +Y off the asked one (aim, or rot's +Y), cm = the drawn base off pos, got = the drawn +Y (when 1 deg off or more), rot = what an aim key used";
+export const HELD_UNITS = "held: per key, deg = the drawn +Y off the asked one (aim, or rot's +Y), cm = the drawn base off pos, got = the drawn +Y (when 1 deg off or more), rot = what an aim key used, lean = the lean a mouth key took by default (give lean 0 to hold aim exactly)";
 
 /**
  * Every key of every keyed carry as drawn: { <id>: [{ f, deg, cm, got?, rot? }] } in key order
@@ -72,11 +72,12 @@ export function heldReadings(out) {
 	const held = keyedEntries(out.ctx.spec);
 	if (!held.length) return null;
 	return Object.fromEntries(held.map(([id, o]) => {
-		const curve = curveIn(out, id), keys = [...o.keys].sort((a, b) => a.f - b.f);
+		// the keys as the compile holds them: a mouth key the compile leaned says so (object-keys.js faceLeaned)
+		const curve = curveIn(out, id), keys = [...(out.ctx.hold?.entry?.(id) ?? o).keys].sort((a, b) => a.f - b.f);
 		return [id, keys.map((k, i) => {
 			const got = rootPoseAt(out, id, Math.round(curve.t[i])), y = [got.R[0][1], got.R[1][1], got.R[2][1]];
 			const want = k.aim ? norm(k.aim) : apply(matFromQuat(curve.q[i]), [0, 1, 0]), deg = r1(angle(want, y));
-			return { f: k.f, deg, cm: r1(dist(k.pos, got.pos) * 100), ...(deg >= 1 ? { got: y.map(r2) } : {}), ...(k.aim ? { rot: curve.rots[i] } : {}) };
+			return { f: k.f, deg, cm: r1(dist(k.pos, got.pos) * 100), ...(deg >= 1 ? { got: y.map(r2) } : {}), ...(k.aim ? { rot: curve.rots[i] } : {}), ...(k.leaned ? { lean: k.lean } : {}) };
 		})];
 	}));
 }

package/src/motion3/qa/motion-life.js

@@ -0,0 +1,243 @@
+// Measured, not judged (output.observations.life): how mechanical a take reads. Five cheap readings
+// over the baked frames and the keys the agent wrote, one linear pass each, warnings only (never a
+// QA group, never qa.ok):
+//   sync   outside walks, the frame each body part (CHAINS) starts and stops moving (its activity,
+//          below, past START of its usual level after a hold); the starts (stops) of several parts
+//          close together are one transition, synchronous where most of them go within +-1 frame.
+//          A body does not do that: the pelvis or a hand leads and the trunk, head and arms follow
+//          a few frames later. score = the share of transitions that are synchronous.
+//   keys   the gaps between the agent's key frames (per channel and all channels as one): their
+//          coefficient of variation (cv, 0 = an even grid) and the share of keys on a half second.
+//          Keys on a beat move every pose at one tempo; keys on the extremes do not.
+//   jerk   the third difference of each CHAINS joint's position (m/s^3): its 95th percentile on
+//          the frames the body moves, and spike frames, where a joint goes past SPIKE times its level
+//          (and JERK_FLOOR): the acceleration snaps there, a seam between two keys' curves (a landing
+//          too); warned past twice that.
+//   twin   outside walks (the hips over WALK_SPEED) and jumps (no foot still), in WINDOW-frame windows: the correlation of
+//          the left and right limb's bend speeds (elbow and shoulder; knee and hip). Over TWIN both
+//          sides do the same thing on the same frames. score = the share of windows that twin.
+//   dead   runs of a second or more with no joint moving over DEAD m a frame outside a still goal:
+//          a statue (idle false, or a pose held where the idle layer stays off).
+// Activity is a part's own motion: the turn (deg/frame) of its local rotation, and for the hips
+// their world turn or travel (cm/frame), so a hand carried by its arm does not count as moving.
+// Why: compiled takes pass QA and still read mechanical (every part starts and stops on one frame,
+// keys every 12 frames, both arms twinned), and nothing in the answer said so.
+import { sub, len } from "../compiler/math.js";
+
+const CHAINS = ["Hips", "Spine", "Spine2", "Head", "LeftArm", "RightArm", "LeftForeArm", "RightForeArm", "LeftHand", "RightHand",
+	"LeftUpLeg", "RightUpLeg", "LeftLeg", "RightLeg", "LeftFoot", "RightFoot"];
+/** A part moves above MOVE deg (cm) a frame; holds are HOLD frames or more under it; START of a part's usual level starts it. */
+const MOVE = 0.25, HOLD = 3, START = 0.2;
+/** sync: events GAP frames or less apart are one transition; synchronous when SYNC_MIN parts and SYNC_SHARE of its parts go within +-1 frame. */
+const SYNC_MIN = 4, SYNC_SHARE = 0.6, GAP = 3;
+const GRID_CV = 0.15, GRID_KEYS = 4, HALF_SHARE = 0.7;
+const SPIKE = 4, JERK_FLOOR = 20;
+const WALK_SPEED = 0.25, FOOT_STILL = 0.005, WINDOW = 48, TWIN = 0.9, TWIN_SWEEP = 15;
+const DEAD = 1e-4;
+const r2 = x => Math.round(x * 100) / 100;
+
+export const LIFE_UNITS = "life (warnings, not QA): [share or s, worst f0, f1]; keys [gap cv, even channels, half-second share]; jerk [p95 m/s^3, joint, spikes]";
+
+const p95 = xs => { const s = [...xs].sort((a, b) => a - b); return s.length ? s[Math.min(s.length - 1, Math.floor(0.95 * s.length))] : 0; };
+const cvOf = gaps => { const m = gaps.reduce((a, b) => a + b, 0) / gaps.length, v = gaps.reduce((a, g) => a + (g - m) ** 2, 0) / gaps.length; return m > 0 ? Math.sqrt(v) / m : 0; };
+function pearson(a, b) {
+	const n = a.length, ma = a.reduce((s, x) => s + x, 0) / n, mb = b.reduce((s, x) => s + x, 0) / n;
+	let ab = 0, aa = 0, bb = 0;
+	for (let i = 0; i < n; i++) { ab += (a[i] - ma) * (b[i] - mb); aa += (a[i] - ma) ** 2; bb += (b[i] - mb) ** 2; }
+	return aa > 0 && bb > 0 ? ab / Math.sqrt(aa * bb) : 0;
+}
+
+/** Per CHAINS part, activity[f] (from f-1): its local turn in deg; the hips the larger of their world turn and travel in cm. */
+function activities(sk, F) {
+	const I = sk.index, n = F.length, DEG = 180 / Math.PI;
+	return CHAINS.map(j => {
+		const b = I[j], p = j === "Hips" ? -1 : sk.parent[b], act = new Float64Array(n);
+		let L = new Float64Array(9), prev = new Float64Array(9);
+		for (let f = 0; f < n; f++) {
+			const { R, P } = F[f].s, B = R[b], A = p < 0 ? null : R[p];
+			// L = A^T B (the local rotation), written out: a pass over every frame of every part must not allocate
+			for (let r = 0; r < 3; r++) for (let c = 0; c < 3; c++) L[r * 3 + c] = A ? A[0][r] * B[0][c] + A[1][r] * B[1][c] + A[2][r] * B[2][c] : B[r][c];
+			if (f) {
+				let tr = 0;
+				for (let i = 0; i < 9; i++) tr += L[i] * prev[i];
+				const turn = Math.acos(Math.max(-1, Math.min(1, (tr - 1) / 2))) * DEG, Q = F[f - 1].s.P[b];
+				act[f] = p < 0 ? Math.max(turn, Math.hypot(P[b][0] - Q[0], P[b][1] - Q[1], P[b][2] - Q[2]) * 100) : turn;
+			}
+			[L, prev] = [prev, L];
+		}
+		return act;
+	});
+}
+
+/** Moves between holds: [a, b] runs of frames where some part moves, gaps under HOLD frames joined. */
+function moves(acts, n) {
+	const runs = [];
+	let a = -1, quiet = 0;
+	for (let f = 1; f < n; f++) {
+		if (acts.some(act => act[f] > MOVE)) { if (a < 0) a = f; quiet = 0; }
+		else if (a >= 0 && ++quiet >= HOLD) { runs.push([a, f - quiet]); a = -1; quiet = 0; }
+	}
+	if (a >= 0) runs.push([a, n - 1 - quiet]);
+	return runs.filter(([x, y]) => y - x >= 3);
+}
+
+/**
+ * Starts and stops outside walks: a part starts where its activity rises past its threshold
+ * (MOVE, or START of its usual level: the 90th percentile of its moving frames) after HOLD frames
+ * under it, and stops where it falls under it for HOLD frames. Events of several parts that follow
+ * one another within GAP frames are one transition; it is synchronous when, of the m parts in it
+ * (SYNC_MIN or more), max(SYNC_MIN, SYNC_SHARE * m) go within one 3-frame window.
+ */
+function syncOf(acts, walking, n) {
+	const events = [[], []];
+	acts.forEach((act, j) => {
+		const level = [...act].filter(v => v > MOVE).sort((a, b) => a - b), thr = Math.max(MOVE, START * (level[Math.floor(0.9 * level.length)] ?? 0));
+		const on = f => act[f] > thr;
+		for (let f = 1; f < n; f++) {
+			if (walking[f]) continue;
+			if (on(f) && !on(f - 1)) { let q = 1; while (q <= HOLD && f - q >= 0 && !on(f - q)) q++; if (q > HOLD || f - q < 0) events[0].push([f, j]); }
+			if (!on(f) && on(f - 1)) { let q = 0; while (q < HOLD && f + q < n && !on(f + q)) q++; if (q >= HOLD && f + q < n) events[1].push([f - 1, j]); }
+		}
+	});
+	let total = 0, synced = 0, worst = null;
+	for (const list of events) {
+		list.sort((a, b) => a[0] - b[0]);
+		for (let i = 0; i < list.length;) {
+			let k = i + 1;
+			while (k < list.length && list[k][0] - list[k - 1][0] <= GAP) k++;
+			const group = list.slice(i, k), m = new Set(group.map(e => e[1])).size;
+			i = k;
+			if (m < SYNC_MIN) continue;
+			let best = 0, at = group[0][0];
+			for (let x = 0, y = 0; y < group.length; y++) {
+				while (group[y][0] - group[x][0] > 2) x++;
+				const c = new Set(group.slice(x, y + 1).map(e => e[1])).size;
+				if (c > best) { best = c; at = group[x][0]; }
+			}
+			total++;
+			if (best >= Math.max(SYNC_MIN, Math.ceil(SYNC_SHARE * m))) synced++;
+			if (!worst || best / m > worst.share || (best / m === worst.share && best > worst.k)) worst = { share: best / m, k: best, of: m, at: [at, at + 2] };
+		}
+	}
+	return { score: total ? r2(synced / total) : 0, total, worst };
+}
+
+/** The agent's keys: cv of all key gaps, the channels keyed on an even grid, the share on half seconds. */
+function keysOf(keys, fps) {
+	const per = new Map(), all = new Set();
+	for (const k of keys ?? []) {
+		if (!Number.isFinite(k?.f)) continue;
+		all.add(k.f);
+		for (const ch of Object.keys(k.set ?? {})) (per.get(ch) ?? per.set(ch, new Set()).get(ch)).add(k.f);
+	}
+	const gaps = fs => { const s = [...fs].sort((a, b) => a - b); return s.slice(1).map((f, i) => f - s[i]); };
+	const eligible = [...per].filter(([, fs]) => fs.size >= GRID_KEYS), grid = eligible.filter(([, fs]) => cvOf(gaps(fs)) < GRID_CV).map(([ch]) => ch);
+	const inner = [...all].filter(f => f > 0), half = Math.round(fps / 2);
+	return { cv: all.size >= GRID_KEYS ? r2(cvOf(gaps(all))) : null, grid, eligible: eligible.length,
+		halfSec: inner.length >= GRID_KEYS ? r2(inner.filter(f => f % half === 0).length / inner.length) : null };
+}
+
+function jerkOf(sk, F, moving, fps) {
+	const k3 = fps ** 3;
+	let top = [0, null], worst = null;
+	const spikes = new Set();
+	for (const j of CHAINS) {
+		const X = F.map(fr => fr.s.P[sk.index[j]]), J = new Float64Array(F.length), on = [];
+		for (let f = 3; f < F.length; f++) {
+			const d = i => X[f][i] - 3 * X[f - 1][i] + 3 * X[f - 2][i] - X[f - 3][i];
+			J[f] = Math.hypot(d(0), d(1), d(2)) * k3;
+			if (moving[f]) on.push(J[f]);
+		}
+		const level = p95(on);
+		if (level > top[0]) top = [r2(level), j];
+		for (let f = 3; f < F.length; f++) {
+			if (J[f] <= Math.max(JERK_FLOOR, SPIKE * level)) continue;
+			spikes.add(f);
+			const ratio = J[f] / Math.max(level, 1e-9);
+			if (!worst || ratio > worst.ratio) worst = { ratio, f, j };
+		}
+	}
+	return { p95: top, spikes: spikes.size, worst };
+}
+
+/** Bend angles (deg) per frame of one side's limb: [elbow, shoulder] or [knee, hip]. */
+function bends(sk, s, S, arm) {
+	const I = sk.index, P = s.P, up = sub(P[I.Spine2], P[I.Hips]);
+	const ang = (a, b) => Math.acos(Math.max(-1, Math.min(1, (a[0] * b[0] + a[1] * b[1] + a[2] * b[2]) / Math.max(1e-9, len(a) * len(b))))) * 180 / Math.PI;
+	const [r, m, e] = arm ? [`${S}Arm`, `${S}ForeArm`, `${S}Hand`] : [`${S}UpLeg`, `${S}Leg`, `${S}Foot`];
+	const u = sub(P[I[m]], P[I[r]]);
+	return [ang(u, sub(P[I[e]], P[I[m]])), ang(u, arm ? up : [-up[0], -up[1], -up[2]])];
+}
+
+function twinOf(sk, F, walking) {
+	const res = {};
+	for (const [name, arm] of [["arms", true], ["legs", false]]) {
+		const L = F.map(({ s }) => bends(sk, s, "Left", arm)), R = F.map(({ s }) => bends(sk, s, "Right", arm));
+		let windows = 0, twins = 0, worst = null;
+		for (let a = 1; a + WINDOW <= F.length; a += WINDOW / 4) {
+			if (walking.slice(a, a + WINDOW).some(Boolean)) continue;
+			const dl = [], dr = [];
+			for (let f = a; f < a + WINDOW; f++) for (let i = 0; i < 2; i++) { dl.push(L[f][i] - L[f - 1][i]); dr.push(R[f][i] - R[f - 1][i]); }
+			const sweep = d => d.reduce((x, v) => x + Math.abs(v), 0);
+			if (sweep(dl) < TWIN_SWEEP || sweep(dr) < TWIN_SWEEP) continue;
+			const c = pearson(dl, dr);
+			windows++;
+			if (c > TWIN) twins++;
+			if (!worst || c > worst.c) worst = { c, at: [a, a + WINDOW - 1] };
+		}
+		res[name] = { score: windows ? r2(twins / windows) : 0, windows, worst };
+	}
+	return res;
+}
+
+function deadOf(sk, F, spec, fps) {
+	const still = new Uint8Array(F.length);
+	for (const g of spec.goals ?? []) {
+		const at = Array.isArray(g?.at) ? g.at : null;
+		if (g?.still !== undefined && at?.length) for (let f = Math.max(0, Math.round(at[0])); f <= Math.min(F.length - 1, Math.round(at[at.length - 1])); f++) still[f] = 1;
+	}
+	let best = null, frames = 0;
+	for (let f = 1, a = -1; f <= F.length; f++) {
+		const dead = f < F.length && !still[f] && sk.names.every((_, j) => len(sub(F[f].s.P[j], F[f - 1].s.P[j])) < DEAD);
+		if (dead) { if (a < 0) a = f; continue; }
+		if (a >= 0 && f - a >= fps) { frames += f - a; if (!best || f - a > best[1] - best[0] + 1) best = [a, f - 1]; }
+		a = -1;
+	}
+	return { frames, best };
+}
+
+/**
+ * observeLife(sk, out, keys) -> observations.life; keys are the spec keys as the agent wrote them
+ * (a skill's keys are the compiler's). Frames are absolute (out.f0 added). flags names the metrics
+ * past their mark, worst first; warn is what to change for the worst (one line: the receipt budget, report.js).
+ */
+export function observeLife(sk, out, keys) {
+	const F = out.frames, n = F.length, fps = out.fps ?? 24, f0 = out.f0 ?? 0, spec = out.ctx.spec, I = sk.index, warnings = [];
+	const acts = activities(sk, F), runs = moves(acts, n), moving = new Uint8Array(n);
+	for (const [a, b] of runs) moving.fill(1, a, b + 1);
+	// a walk: the hips travel over WALK_SPEED, widened by half a window so its first and last steps count
+	const walking = new Uint8Array(n), pad = WINDOW / 2;
+	for (let f = 1; f < n; f++) {
+		const P = F[f].s.P[I.Hips], Q = F[f - 1].s.P[I.Hips];
+		if (Math.hypot(P[0] - Q[0], P[2] - Q[2]) * fps > WALK_SPEED) walking.fill(1, Math.max(0, f - pad), Math.min(n, f + pad));
+	}
+	// twins leave out walks and jumps too: no foot still (a flip, a hop takes both legs together)
+	const free = walking.slice();
+	for (let f = 1; f < n; f++) if (["LeftFoot", "RightFoot"].every(j => len(sub(F[f].s.P[I[j]], F[f - 1].s.P[I[j]])) > FOOT_STILL)) free.fill(1, Math.max(0, f - pad), Math.min(n, f + pad));
+	const sync = syncOf(acts, walking, n), k = keysOf(keys, fps), jerk = jerkOf(sk, F, moving, fps), twin = twinOf(sk, F, free), dead = deadOf(sk, F, spec, fps);
+	const span = ([a, b]) => `f${a + f0}-${b + f0}`;
+	// [weight, metric, advice]: the answer keeps the worst advice and names every metric it flags
+	if (sync.total >= 2 && sync.score >= 0.5) warnings.push([sync.score, "sync", `${sync.worst.k} of ${sync.worst.of} parts start or stop together ${span(sync.worst.at)}: lead with pelvis or a hand, spine/head/arms 2-4 frames later`]);
+	const gridKeys = (k.cv !== null && k.cv < GRID_CV) || (k.eligible && k.grid.length / k.eligible >= 0.5) || (k.halfSec ?? 0) >= HALF_SHARE;
+	if (gridKeys) warnings.push([0.9, "keys", `keys on a grid: key the extremes (contact, peak, turn), vary the gaps`]);
+	if (jerk.worst && jerk.worst.ratio > 2 * SPIKE) warnings.push([0.6, "jerk", `${jerk.worst.j} jerks ${Math.round(jerk.worst.ratio)}x at f${jerk.worst.f + f0}: a key snaps; ease or move it`]);
+	for (const [name, t] of Object.entries(twin)) if (t.windows >= 2 && t.score >= 0.4) warnings.push([t.score, name, `${name} mirror ${span(t.worst.at)}: ${name === "legs" ? "weight onto one foot, not straight down" : "offset one side 2-4 frames or pose it apart"}`]);
+	if (dead.best) warnings.push([0.7, "dead", `dead still ${span(dead.best)}${spec.idle === false ? " (idle false)" : ""}: let idle run or key a settle`]);
+	warnings.sort((a, b) => b[0] - a[0]);
+	const at = (score, w) => (w ? [score, w[0] + f0, w[1] + f0] : [score]);
+	return {
+		sync: at(sync.score, sync.worst?.at), keys: [k.cv, k.grid.length, k.halfSec], jerk: [...jerk.p95, jerk.spikes],
+		arms: at(twin.arms.score, twin.arms.worst?.at), legs: at(twin.legs.score, twin.legs.worst?.at), dead: at(r2(dead.frames / fps), dead.best),
+		...(warnings.length ? { flags: warnings.map(w => w[1]), warn: warnings[0][2] } : {}),
+	};
+}

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

@@ -36,7 +36,7 @@ function graspPart(out, ref) {
 	return out.ctx.sockets?.get(name)?.owner ?? a.object;
 }
 
-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);
+export 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];
@@ -44,19 +44,25 @@ function alongDir(out, f, along) {
 	return norm(along);
 }
 
+/** How far a checks.contacts entry k's point is from its target at frame f (indexes out.frames), m; null when a point is unknown there. */
+export function contactGap(out, f, k) {
+	const a = pointOf(out, f, k.point), b = pointOf(out, f, k.target);
+	if (!a || !b) return null;
+	// on a grasp's anchor the fingers close on the held part wherever the grasp turned them round it: they are on it
+	// when they are on its surface (as goals' near on an object), not on one point of it (session 7f15b4ae: 0.4 cm
+	// on the cup, read as 5.3 cm from the anchor)
+	// and a hand that holds a thing resting in its palm (seat.js) has its fingers on that thing's surface
+	const held = graspPart(out, k.target) ?? seatedIn(out, k.point, f + (out.f0 ?? 0));
+	return held ? refDistance(out, f, k.point, `object:${held}`) ?? len(sub(a, b)) : len(sub(a, b));
+}
+
 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;
-			// on a grasp's anchor the fingers close on the held part wherever the grasp turned them round it: they are on it
-			// when they are on its surface (as goals' near on an object), not on one point of it (session 7f15b4ae: 0.4 cm
-			// on the cup, read as 5.3 cm from the anchor)
-			// and a hand that holds a thing resting in its palm (seat.js) has its fingers on that thing's surface
-			const held = graspPart(out, k.target) ?? seatedIn(out, k.point, f + (out.f0 ?? 0)), e = held ? refDistance(out, f, k.point, `object:${held}`) ?? len(sub(a, b)) : 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);
+			const e = contactGap(out, f, k);
+			if (e !== null && 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);

package/src/motion3/qa/verdict.js

@@ -0,0 +1,50 @@
+// C6. Is one compile's QA better than another's: the one rule repair (repair.js) keeps a change by and the hint check
+// (hint-check.js) offers a patch by. Better means all of
+//   less       the summed severity (severity.js) drops
+//   goals      no more goals fail, and every goal that held still holds
+//   problems   no more issue groups than before
+//   trade      what got worse (a new group, or a group whose severity rose) costs at most half of what got better
+// Logs: a hint patch applied as sent made the take worse 49% of the time, and repair moved the root and broke the arms;
+// a lower sum alone let a change through that traded one failure for several new ones.
+import { groupKey } from "./severity.js";
+
+const groupsOf = qa => qa?.groups ?? [];
+const sevOf = qa => groupsOf(qa).reduce((sum, g) => sum + (g.severity ?? 0), 0);
+const heldOf = qa => (qa?.goals ?? []).filter(g => g.ok).map(g => g.name);
+const failedOf = qa => (qa?.goals ?? []).filter(g => !g.ok).length;
+const TRADE = 0.5;
+const r2 = x => Math.round(x * 100) / 100;
+
+/** The group severities by key (severity.js groupKey). */
+function byKey(qa) {
+	const m = new Map();
+	for (const g of groupsOf(qa)) m.set(groupKey(g), (m.get(groupKey(g)) ?? 0) + (g.severity ?? 0));
+	return m;
+}
+
+/**
+ * compareQa(next, base) -> { better, why, sev: [base, next], problems: [base, next], worse: [{ key, severity: [a, b] }] }
+ * why: the first rule that failed ("" when better); worse: the groups that got worse, worst first (at most 3).
+ */
+export function compareQa(next, base) {
+	const a = byKey(base), b = byKey(next);
+	let rise = 0, drop = 0;
+	const worse = [];
+	for (const [k, v] of b) { const was = a.get(k) ?? 0; if (v > was + 1e-9) { rise += v - was; worse.push({ key: k, severity: [r2(was), r2(v)] }); } else drop += was - v; }
+	for (const [k, v] of a) if (!b.has(k)) drop += v;
+	worse.sort((x, y) => y.severity[1] - y.severity[0] - (x.severity[1] - x.severity[0]));
+	const sev = [r2(sevOf(base)), r2(sevOf(next))], problems = [groupsOf(base).length, groupsOf(next).length];
+	const lost = heldOf(base).filter(n => !heldOf(next).includes(n));
+	const why = !(sevOf(next) < sevOf(base) - 1e-9) ? `summed severity ${sev[0]} -> ${sev[1]}`
+		: failedOf(next) > failedOf(base) || lost.length ? `goal ${lost.length ? `"${lost[0]}" no longer holds` : "failures rose"}`
+			: problems[1] > problems[0] ? `problems ${problems[0]} -> ${problems[1]}`
+				: rise > TRADE * drop + 1e-9 ? `${worse[0]?.key} got worse (${worse[0]?.severity.join(" -> ")})` : "";
+	return { better: !why, why, sev, problems, worse: worse.slice(0, 3) };
+}
+
+/** next is no worse than base: no more problems (at as many, the summed severity does not rise), no more goals fail, none that held is lost. */
+export const noWorse = (next, base) => (groupsOf(next).length < groupsOf(base).length || (groupsOf(next).length === groupsOf(base).length && sevOf(next) <= sevOf(base) + 1e-9))
+	&& failedOf(next) <= failedOf(base) && heldOf(base).every(n => heldOf(next).includes(n));
+
+/** Severity of the group with key `key` in qa (0 when it is gone). */
+export const severityIn = (qa, key) => groupsOf(qa).filter(g => groupKey(g) === key).reduce((s, g) => s + (g.severity ?? 0), 0);