cozyclay 3.1.0 → 3.1.2

package/src/motion3/pipeline.js

@@ -5,11 +5,14 @@
 // a cause and a hint per issue group against the agent's own spec, the style quantities are
 // measured (qa/style.js observeMotion; keyed objects: every key as drawn, qa/key-checks.js
 // heldReadings; each hand and foot against the nearest object, qa/near.js observeNear; each holding
-// wrist's bend, qa/wrist-obs.js observeWrist; a skill
+// wrist's bend, qa/wrist-obs.js observeWrist; how mechanical it reads against the agent's own
+// keys, qa/motion-life.js observeLife; a skill
 // paced to fit a short span: observations.paced; a skill whose release or
-// settle the last frame cut: observations.cut), and the timeline and the
+// settle the last frame cut: observations.cut; what the spec asked against what it got, per skill,
+// contact and goal: qa/asked.js observeAsked), and the timeline and the
 // requested probes read the result.
-// liftRequest first takes what the agent obviously meant: spec.probes are request probes, and a
+// prepareSpec (correct.js) first corrects slips with one reading and fits walkTo strides, both kept in the
+// stored spec; liftRequest takes what the agent obviously meant: spec.probes are request probes, and a
 // bare goals[].moved id is object:<id>; relaxSpec (lenient.js) fixes mechanical slips in the expanded
 // spec before validation and the answer lists each fix in notes.
 import { compileMotion } from "./compiler/compile.js";
@@ -28,8 +31,12 @@ import { heldReadings, HELD_UNITS } from "./qa/key-checks.js";
 import { observeNear, NEAR_UNITS } from "./qa/near.js";
 import { observeWrist, WRIST_UNITS } from "./qa/wrist-obs.js";
 import { observeLoad, LOAD_UNITS } from "./load.js";
+import { observeLife, LIFE_UNITS } from "./qa/motion-life.js";
 import { planWalks, applyWalkPlans } from "./walk-plan.js";
 import { relaxSpec } from "./lenient.js";
+import { observeAsked } from "./qa/asked.js";
+import { prepareSpec } from "./correct.js";
+import { compareQa, noWorse } from "./qa/verdict.js";
 
 const ms = t => Math.round(performance.now() - t);
 
@@ -41,6 +48,21 @@ function warpChecks(spec, map) {
 	return { ...spec, checks: c };
 }
 
+/**
+ * fix.retime is kept only when QA is no worse with it (qa/verdict.js noWorse: no more problems, at as many no higher
+ * summed severity, no goal lost); else the take compiles without it and fixed.retime says what it did (a session went from 30
+ * problems to 1015 after a retime). -> { out, measured, qa }
+ */
+function keptRetime(out, expanded, compile, qaOf) {
+	const qa = qaOf(out), measured = out.timeMap ? warpChecks(expanded, out.timeMap) : expanded;
+	if (!out.fixed?.retime) return { out, measured, qa };
+	const plain = compile({ ...expanded, fix: { ...expanded.fix, retime: false } }), base = qaOf(plain);
+	if (noWorse(qa, base)) return { out, measured, qa };
+	const v = compareQa(qa, base);
+	plain.fixed = { ...plain.fixed, retime: { ...out.fixed.retime, kept: false, how: `${out.fixed.retime.how}; not kept: QA was worse with it (summed severity ${v.sev[0]} -> ${v.sev[1]}, problems ${v.problems[0]} -> ${v.problems[1]}), so the take is compiled without it` } };
+	return { out: plain, measured: expanded, qa: base };
+}
+
 /**
  * liftRequest(spec, probes) -> { spec, probes }. spec.probes (sent inside the spec, or added by
  * a patch) join the request's probes after them and leave the spec, so they are never stored and
@@ -63,14 +85,27 @@ export function liftRequest(spec, probes) {
  * (with spec.probes, liftRequest).
  */
 export function compileSpec(sent, { sk, scene }, opts = {}) {
-	const { spec, probes: asked } = liftRequest(sent, opts.probes);
-	const t0 = performance.now(), ctx = { sk, scene, lenient: opts.lenient === true }, notes = [];
+	const notes = [], refusals = [];
+	try {
+		return compilePrepared(opts.lenient ? sent : prepareSpec(sent, { sk, scene }, notes, refusals), { sk, scene }, opts, notes, refusals);
+	} catch (error) {
+		// a walk prepareSpec refused is listed with whatever refused the spec first (validateSpec lists it with its own)
+		if (refusals.length && /^MOTION_SPEC_INVALID/.test(error.message) && !error.message.includes(refusals[0])) error.message = error.message.replace(/^MOTION_SPEC_INVALID: /, `MOTION_SPEC_INVALID: ${refusals.join("\n")}\n`);
+		// a refusal says what was corrected first, so the paths it names (a moved generator: use[i]) read right
+		if (notes.length && /^MOTION_SPEC_INVALID/.test(error.message)) error.message += `\n(adjusted before these checks: ${notes.join("; ")})`;
+		throw error;
+	}
+}
+
+function compilePrepared(prepared, { sk, scene }, opts, notes, refusals) {
+	const { spec, probes: asked } = liftRequest(prepared, opts.probes);
+	const t0 = performance.now(), ctx = { sk, scene, lenient: opts.lenient === true, problems: refusals };
 	const checks = opts.checks && nameChecks({ checks: opts.checks }).checks;
 	let plans = [];
 	const expand = s => {
 		const { spec: exp, used } = expandUse(nameChecks(applyWalkPlans(s, plans)), ctx);
 		// plain JSON objects compile about twice as fast as structuredClone'd ones (V8 shapes)
-		const full = relaxSpec(JSON.parse(JSON.stringify(checks ? { ...exp, checks } : exp)), scene, notes);
+		const full = relaxSpec(JSON.parse(JSON.stringify(checks ? { ...exp, checks } : exp)), scene, notes, sk);
 		validateSpec(full, ctx);
 		return { full, used };
 	};
@@ -83,16 +118,16 @@ export function compileSpec(sent, { sk, scene }, opts = {}) {
 	if (spec?.frames === "auto") markFramesAuto(resolved);
 	const t1 = performance.now();
 	const { full: expanded, used } = expand(resolved);
-	const out = compileMotion({ fps: 24, ...expanded }, ctx);
+	const { out, measured, qa } = keptRetime(compileMotion({ fps: 24, ...expanded }, ctx), expanded, s => compileMotion({ fps: 24, ...s }, ctx), o => runMotionQa(sk, o, o.timeMap ? warpChecks(expanded, o.timeMap) : expanded, { userSpec: resolved }));
 	const compileMs = ms(t1), t2 = performance.now();
-	const measured = out.timeMap ? warpChecks(expanded, out.timeMap) : expanded;
-	const qa = runMotionQa(sk, out, measured, { userSpec: resolved }), observations = observeMotion(sk, out, measured.checks), held = heldReadings(out);
+	const observations = observeMotion(sk, out, measured.checks), held = heldReadings(out);
 	if (held) Object.assign(observations, { units: `${observations.units}; ${HELD_UNITS}`, held });
 	const near = observeNear(sk, out), wrist = observeWrist(sk, out);
 	if (near) Object.assign(observations, { units: `${observations.units}; ${NEAR_UNITS}`, near });
 	if (wrist) Object.assign(observations, { units: `${observations.units}; ${WRIST_UNITS}`, wrist });
 	const load = observeLoad(sk, out);
 	if (load) Object.assign(observations, { units: `${observations.units}; ${LOAD_UNITS}`, load });
+	Object.assign(observations, { units: `${observations.units}; ${LIFE_UNITS}`, life: observeLife(sk, out, resolved?.keys) });
 	// a skill that paced its beats to fit a short span says so where every answer keeps it (C7 tier 1)
 	const paced = used.filter(u => u.paced).map(u => `${u.skill} paced ${u.paced.toFixed(2)} to fit f${u.f0}..f${u.end}`);
 	if (paced.length) observations.paced = paced;
@@ -101,6 +136,8 @@ export function compileSpec(sent, { sk, scene }, opts = {}) {
 	const placed = used.filter(u => u.placed).map(u => `${u.skill} f${u.f0}: ${u.placed.why}: at [${u.placed.at.join(", ")}], heading ${u.placed.heading}`);
 	if (placed.length) observations.placed = placed;
 	if (plans.length) observations.planned = plans.map(p => p.note);
+	const got = observeAsked(out, { used, use: resolved?.use, checks: measured.checks, goals: measured.goals, results: qa.goals });
+	if (got) observations.asked = got;
 	const timeline = timelineOf(out, { used, spec: expanded }), probes = asked && runProbes(out, asked, { spec: expanded, sk, scene, notes });
 	return { out, qa, observations, spec: resolved, expanded, used, fixed: out.fixed, search, timeline, ...(probes ? { probes } : {}), ...(notes.length ? { notes } : {}),
 		ms: { compile: compileMs, qa: ms(t2), total: ms(t0) } };

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

@@ -0,0 +1,96 @@
+// QA ARM warnings (lane arm): an elbow that reads awkward while the hand works, though nothing collides or breaks.
+// The agent saw these only in renders and re-keyed them after QA had passed (17% of the compiles in the hundred
+// costliest motion turns: elbows too high, wrapped over the head, out to the side). A working arm (on its IK, or a
+// hand a keyed carry leads, compiler/hold.js) is read on each frame in the chest's frame, the hand not overhead (the
+// wrist below the top of the head plus OVERHEAD: a lift over the head needs the elbow up; a hand that tips a cup at the
+// lips from above sits by the top of the head and is read):
+//   over the head  the elbow above the head's centre: the upper arm wraps over the head
+//   high           the upper arm more than HIGH deg from hanging (90 level): the elbow over the shoulder
+//   wing           the upper arm more than WING deg out to the side in the chest's frontal plane with the hand
+//                  within NEAR m of the trunk's axis: the elbow flared out while the hand works by the body
+// Runs of at least MIN frames on a side (gaps of GAP at most) make one line, worst first, at most LINES of them in
+// qa.warnings. They are warnings, not QA groups: they never fail a take (qa.ok), repair does not chase them, and the
+// output budget keeps them after every group (report.js). Each says the frames, the side and the spec change that
+// fixes it: on a keyed carry the object's keys there (lean FACE_LEAN, what a key at the lips takes by default,
+// ../face-lean.js; with that, the pos lower and nearer the chest), on an IK arm the elbow pole (elbow_<side>, body
+// frame: x out to the character's left, -y down, z forward).
+import { sub, scale, dot, len, clamp } from "../compiler/math.js";
+import { carried } from "../compiler/limbs.js";
+import { bonePoint } from "../compiler/skeleton.js";
+import { keyedEntries } from "../object-keys.js";
+import { FACE_LEAN } from "../face-lean.js";
+
+const HIGH = 105, WING = 75, NEAR = 0.3, OVERHEAD = 0.1, MIN = 4, GAP = 6, LINES = 2, WORKS = 0.5, DEG = 180 / Math.PI;
+const SIDES = { l: "Left", r: "Right" }, ORDER = { "over the head": 0, high: 1, wing: 2 };
+
+/** What the arm of side k reads like on solved frame { s, diag, c }: { kind, deg, held } or null (not working, or natural). */
+export function armPose(sk, { s, diag, c }, k) {
+	const held = (diag[`hold_${k}`]?.w ?? 0) > WORKS && !diag[`hold_${k}`].second;
+	if (!held && !((c[`armw_${k}`] ?? 0) > WORKS)) return null;
+	const I = sk.index, S = s.P[I[`${SIDES[k]}Arm`]], E = s.P[I[`${SIDES[k]}ForeArm`]], W = s.P[I[`${SIDES[k]}Hand`]], chest = I.Spine2 ?? I.Hips;
+	const up = carried(sk, s, chest, [0, 1, 0]), out = scale(carried(sk, s, chest, [1, 0, 0]), k === "l" ? 1 : -1);
+	const head = bonePoint(s, I.Head, sk.landmarks.headCentre);
+	if (dot(sub(W, head), up) > sk.landmarks.headRadii[1] + OVERHEAD) return null;
+	const v = sub(E, S), el = Math.acos(clamp(-dot(v, up) / len(v), -1, 1)) * DEG, flare = Math.atan2(dot(v, out), -dot(v, up)) * DEG;
+	if (dot(sub(E, head), up) > 0) return { kind: "over the head", deg: el, held };
+	if (el > HIGH) return { kind: "high", deg: el, held };
+	const axis = sub(W, s.P[I.Spine]), across = len(sub(axis, scale(up, dot(axis, up))));
+	if (flare > WING && across < NEAR) return { kind: "wing", deg: flare, held };
+	return null;
+}
+
+/** The keyed carry hand k holds and its keys within timeline frames f0..f1, else the one nearest f: { id, picks: [[index, key]] } or null. */
+function carryAt(out, k, f0, f1, f) {
+	const spec = out.ctx.spec, map = t => (out.timeMap ? out.timeMap(t) : t);
+	for (const [id, o] of keyedEntries(spec)) {
+		if (spec.props?.[o.prop]?.hand !== k) continue;
+		const keys = (out.ctx.hold?.entry?.(id) ?? o).keys, within = keys.map((key, i) => [i, key]).filter(([, key]) => map(key.f) >= f0 && map(key.f) <= f1);
+		const near = keys.reduce((b, key, j) => (Math.abs(map(key.f) - f) < Math.abs(map(keys[b].f) - f) ? j : b), 0);
+		return { id, picks: within.length ? within : [[near, keys[near]]] };
+	}
+	return null;
+}
+
+const r2 = v => Math.round(v * 100) / 100;
+const listed = (id, picks) => picks.map(([i, key]) => `objects.${id}.keys[${i}] (f${key.f})`).join(", ");
+/** The spec change that fixes run g (see the header). */
+function fixFor(sk, out, g) {
+	const k = g.k, sx = k === "l" ? 1 : -1, c = g.held && carryAt(out, k, g.first, g.last, g.worst);
+	if (c) {
+		const lean = c.picks.filter(([, key]) => key.aim && !(key.lean >= FACE_LEAN));
+		if (lean.length) return `give ${listed(c.id, lean)} lean ${FACE_LEAN} (tips the aim to the hand's side, the elbow stays down)`;
+		// lower, and nearer the chest across the ground, read on the frame of the run's worst key
+		const fr = out.frames[Math.max(0, Math.min(out.frames.length - 1, Math.round(g.worst - (out.f0 ?? 0))))], P = c.picks[0][1].pos;
+		const to = sub(fr.s.P[sk.index.Spine2 ?? sk.index.Hips], P), h = Math.hypot(to[0], to[2]) || 1;
+		return `move ${listed(c.id, c.picks)} pos by [${r2((0.05 * to[0]) / h)}, -0.08, ${r2((0.05 * to[2]) / h)}] (lower, nearer the chest)`;
+	}
+	// the pole in the body frame: down, a little out, and for a hand by the face in front of the chest
+	const pole = g.kind === "wing" ? [r2(0.1 * sx), -1, 0.2] : [r2(0.3 * sx), -1, g.mouth ? 0.35 : -0.2];
+	return `key elbow_${k} [${pole.join(", ")}] from f${g.first} to f${g.last} (down${g.kind === "wing" ? " and in" : " and a little out"}${g.mouth ? ", in front of the chest" : ""})`;
+}
+
+const WORDS = { "over the head": "upper arm wraps over the head", high: "elbow over the shoulder", wing: "elbow flared out to the side" };
+/**
+ * ARM warning lines of a compile (out.frames solved; frames absolute with out.f0): the worst LINES runs, worst
+ * first. A run is a side's awkward frames with gaps of at most GAP, all held or all on the IK, named by its worst
+ * kind (ORDER) and that kind's worst frame. [] when every working arm reads natural.
+ */
+export function armWarnings(sk, out) {
+	const runs = [], f0 = out.f0 ?? 0, mouthAt = s => bonePoint(s, sk.index.Head, sk.landmarks.mouth);
+	for (const k of ["l", "r"]) {
+		let run = null;
+		const close = () => { if (run && run.n >= MIN) runs.push(run); run = null; };
+		out.frames.forEach((fr, i) => {
+			const a = armPose(sk, fr, k), f = i + f0;
+			if (run && (f - run.last > GAP || (a && a.held !== run.held))) close();
+			if (!a) return;
+			const mouth = len(sub(fr.s.P[sk.index[`${SIDES[k]}Hand`]], mouthAt(fr.s))) < 0.25;
+			run ??= { k, kind: a.kind, held: a.held, first: f, worst: f, deg: a.deg, n: 0, mouth: false };
+			run.last = f; run.n++; run.mouth ||= mouth;
+			if (ORDER[a.kind] < ORDER[run.kind] || (a.kind === run.kind && a.deg > run.deg)) Object.assign(run, { kind: a.kind, deg: a.deg, worst: f });
+		});
+		close();
+	}
+	runs.sort((a, b) => ORDER[a.kind] - ORDER[b.kind] || b.n - a.n);
+	return runs.slice(0, LINES).map(g => `ARM arm_${g.k} ${WORDS[g.kind]} f${g.first}-f${g.last} (worst f${g.worst}, upper arm ${Math.round(g.deg)}deg ${g.kind === "wing" ? "out" : "up"}): ${fixFor(sk, out, g)}`);
+}

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 } : {}) };
 		})];
 	}));
 }