cozyclay 3.1.0 → 3.1.2

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);

package/src/motion3/refs.js

@@ -5,9 +5,13 @@
 //   anchor:<name>                       a spec anchor, resolved as the compiler resolves it
 //   landmark:mouth                      the measured face landmark
 //   person:<id>.<Bone>                  another character's joint where its installed take has it (people.js)
-//   object:<id>[.center|.top|.base]     a body or a group (object-pose.js objectBoxesAt): the centre,
-//                                       top-face centre or bottom-face centre of the AABB of its
-//                                       part boxes' corners (default center)
+//   object:<id>[.center|.top|.base|.rim] a body or a group (object-pose.js objectBoxesAt): the centre,
+//                                       top-face centre or bottom-face centre of the world AABB of its
+//                                       part boxes' corners (default center); .rim is its opening (a cup's,
+//                                       a can's): the top face of its highest part in the part's own axes,
+//                                       so it tilts with it, and measured against another point the edge of
+//                                       that face nearest the point (where a lip meets a cup). A tilted cup's
+//                                       .top is the box's highest corner height over its middle, not its rim
 // Frames are absolute; a frame outside the compiled window (out.f0 ..) answers null.
 import { REF_KINDS } from "./schema/fields.js";
 import { resolveBone } from "./bones.js";
@@ -20,14 +24,14 @@ import { add, apply, sub, len } from "./compiler/math.js";
 import { sdBox } from "./qa/geometry.js";
 import { personJoint, peopleList } from "./people.js";
 
-const SYNTAX = { joint: "joint:<Bone>", bone: "bone:<Bone>", prop: "prop:<prop>.<point>", anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base]", person: "person:<id>.<Bone>" };
+const SYNTAX = { joint: "joint:<Bone>", bone: "bone:<Bone>", prop: "prop:<prop>.<point>", anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base|.rim]", person: "person:<id>.<Bone>" };
 
 function parse(ref) {
 	const m = /^([a-z]+):(.+)$/s.exec(String(ref));
 	if (!m) return null;
 	const [, kind, rest] = m;
 	if (kind === "prop") { const [name, point] = rest.split("."); return { kind, name, point: point ?? "" }; }
-	if (kind === "object") { const o = /^(.+)\.(center|top|base)$/s.exec(rest); return { kind, name: o ? o[1] : rest, point: o ? o[2] : null }; }
+	if (kind === "object") { const o = /^(.+)\.(center|top|base|rim)$/s.exec(rest); return { kind, name: o ? o[1] : rest, point: o ? o[2] : null }; }
 	if (kind === "person") { const dot = rest.lastIndexOf("."); return { kind, name: dot > 0 ? rest.slice(0, dot) : rest, point: dot > 0 ? rest.slice(dot + 1) : "" }; }
 	return { kind, name: rest, point: null };
 }
@@ -42,6 +46,18 @@ function boxesPoint(boxes, which) {
 	return which === "top" ? [c[0], hi[1], c[2]] : which === "base" ? [c[0], lo[1], c[2]] : c;
 }
 
+/** The opening of a body or group's boxes: { o, n, r }, the top face of the highest part in its own axes (centre, axis, the smaller half width). */
+export function openingOf(boxes) {
+	const tops = (boxes ?? []).map(b => ({ o: add(b.pos, apply(b.R, [0, 2 * b.half[1], 0])), n: [b.R[0][1], b.R[1][1], b.R[2][1]], r: Math.min(b.half[0], b.half[2]) }));
+	return tops.length ? tops.reduce((p, q) => (q.o[1] > p.o[1] ? q : p)) : null;
+}
+
+/** The point of an opening's edge nearest p (its centre when p is on the axis). */
+function rimNear(op, p) {
+	const v = sub(p, op.o), along = v[0] * op.n[0] + v[1] * op.n[1] + v[2] * op.n[2], across = sub(v, op.n.map(x => x * along)), d = len(across);
+	return d > 1e-6 ? add(op.o, across.map(x => (x * op.r) / d)) : op.o;
+}
+
 /** World point [x, y, z] of `ref` at absolute frame f of compile result out, or null. */
 export function refPoint(out, f, ref) {
 	const fr = out.frames?.[f - (out.f0 ?? 0)], r = parse(ref);
@@ -52,7 +68,7 @@ export function refPoint(out, f, ref) {
 		case "prop": { const p = diag.props?.[r.name]?.[r.point]; return Array.isArray(p) ? p.slice() : null; }
 		case "anchor": return out.ctx.spec.anchors?.[r.name] ? resolveAnchor(out.ctx, r.name, s, { ...diag, frame: f }, c) : null;
 		case "landmark": return sk.landmarks?.[r.name] ? bonePoint(s, sk.index.Head, sk.landmarks[r.name]) : null;
-		case "object": { const boxes = objectBoxesAt(out, r.name, f); return boxes ? boxesPoint(boxes, r.point) : null; }
+		case "object": { const boxes = objectBoxesAt(out, r.name, f); return boxes ? (r.point === "rim" ? openingOf(boxes).o.slice() : boxesPoint(boxes, r.point)) : null; }
 		case "person": return personJoint(out.ctx.scene, r.name, r.point, f);
 		default: return null;
 	}
@@ -71,25 +87,33 @@ export function refDistance(out, f, a, b) {
 		const p = refPoint(out, f, surf[0]), boxes = objectBoxesAt(out, surf[1].name, f);
 		return p && boxes ? Math.max(0, Math.min(...boxes.map(box => sdBox(p, box)))) : null;
 	}
+	// an opening against another point: the edge of it nearest that point
+	const rim = [a, b].map(ref => { const r = parse(ref); return r?.kind === "object" && r.point === "rim" ? r : null; });
+	if (rim[0] || rim[1]) {
+		const [own, other] = rim[0] ? [rim[0], b] : [rim[1], a], p = refPoint(out, f, other), op = openingOf(objectBoxesAt(out, own.name, f));
+		return p && op ? len(sub(p, rimNear(op, p))) : null;
+	}
 	const p = refPoint(out, f, a), q = refPoint(out, f, b);
 	return p && q ? len(sub(p, q)) : null;
 }
 
-/**
- * The prefixed refs a bare name could mean in this spec, rig and scene (`; did you mean
- * "object:empty-2"?`), or "". A field that takes more than one ref kind stays strict.
- */
-function bareHint(spec, { sk, scene }, ref, kinds) {
-	if (typeof ref !== "string" || !ref) return "";
-	const id = ref.replace(/\.(center|top|base)$/, ""), [prop, point] = ref.split(".");
+/** The prefixed refs a bare name could mean in this spec, rig and scene (lenient.js takes the one when there is one). */
+export function bareRefs(spec, { sk, scene }, ref, kinds = REF_KINDS) {
+	if (typeof ref !== "string" || !ref) return [];
+	const id = ref.replace(/\.(center|top|base|rim)$/, ""), [prop, point] = ref.split(".");
 	const bone = sk && (kinds.includes("joint") || kinds.includes("bone")) ? resolveBone(sk, ref).bone : null;
-	const known = [
+	return [
 		kinds.includes("object") && (scene?.objects?.[id] || partsOf(scene, id).length) && `object:${ref}`,
 		bone && `${kinds.includes("joint") ? "joint" : "bone"}:${bone}`,
 		kinds.includes("anchor") && spec.anchors?.[ref] && `anchor:${ref}`,
 		kinds.includes("prop") && spec.props?.[prop] && (point === "origin" || spec.props[prop].points?.[point]) && `prop:${ref}`,
 		kinds.includes("landmark") && ref === "mouth" && "landmark:mouth",
 	].filter(Boolean);
+}
+
+/** `; did you mean "object:empty-2"?` for a bare name (bareRefs), or "". A field that takes more than one ref kind stays strict. */
+function bareHint(spec, ctx, ref, kinds) {
+	const known = bareRefs(spec, ctx, ref, kinds);
 	return known.length ? `; did you mean ${known.map(k => `"${k}"`).join(" or ")}?` : "";
 }
 

package/src/motion3/repair-watch.js

@@ -0,0 +1,132 @@
+// The stop rule of the compile-repair loop (motion.compile): a short note in the answer when more
+// compiles stopped paying. It never refuses a compile; the agent reads output.stuck and the prompt
+// tells it to obey. The agent's own logs set the numbers: a compile is ~0.3 s but a repair step is
+// ~1,250 output tokens of model time, a turn compiles median 8 / p90 17 times, a failure that survives
+// two retries unchanged survives a third about a third of the time, and about a fifth of the
+// compiles after a take first passes QA failed QA again (re-tweaking what already passed).
+//   polish  an earlier compile of this character in this turn passed QA: say so, stop unless asked
+//   cap     REPAIR_CAP compiles after the first: report what still fails on the best take
+//   stuck   the same failing groups (or more) for STUCK_AFTER compiles in a row, neither fewer nor
+//           DELTA_STEP less severe: stop patching them (or re-applying their hints), start over,
+//           take another approach, or report what the best take still fails
+// History is per character and agent turn (context.turnId); without a turn (MCP, tests) per character,
+// with the cap counted along the base chain (a whole spec starts it again). In a turn the cap counts agent
+// steps: the compiles of one tool call (context.callId; a script's nested ones share the script's) are one
+// repair step, as a script that compares variants is one try; a compile with no call id is a step of its own.
+// The 60 bench sessions: compiles counted one by one read 10-23 at the agent's 6-12th compiling call. The stuck streak
+// counts the same steps: of the runs of 3 script compiles whose problems and issues did not drop (the SSE frames), 21 of
+// 37 merged (48 of 71 base) lay inside one script, which compared variants; each step's last compile carries it on. A whole spec sent after a
+// stuck note is the fresh start the note asked for, so the streak starts again too.
+// A note never leaves the take empty: the agent obeys it by reporting, and a turn whose compiles all ran
+// install: "ifClean" (or false) unclean ended with no take (5 of 30 bench runs). So the line keeps its best
+// compile per placement (`at`, the last PLACES of them: a take plays in the character's placement frame,
+// take.js, so it only meets the scene where it was baked) with its take, and a note on a compile that did
+// not install itself answers `install`: the best take here, when the character carries no take or one the
+// watch put on that this one beats. The caller installs it (no compile: the take is the one baked then).
+// A take the agent installed (install: true, or an ifClean that installed) is never replaced for the rest
+// of the line, nor one the character had before it (replay of merged r3 S8: the agent's own take was
+// swapped for an earlier draft, so its report no longer named the character's take).
+import { groupKey } from "./qa/severity.js";
+
+const STUCK_AFTER = 3;
+const REPAIR_CAP = 10;
+const DELTA_STEP = 0.05;
+const KEPT = 32;
+// lines whose best takes are kept (the newest): a take is ~0.25 MB a 240-frame Y Bot take (rotations, 65 bones), so
+// with PLACES each at most about 3 MB here; an older line keeps its notes but no take (its turn is over)
+const TAKES = 4;
+// placements per line whose best take is kept (S8 r1 moved the body 0.78 -> 0.88 -> 0.94 -> 0.88 m)
+const PLACES = 3;
+const SAY_CODES = 2;
+
+const severity = groups => groups.reduce((s, g) => s + (Number.isFinite(g.severity) ? g.severity : 0), 0);
+const superset = (a, b) => [...b].every(k => a.has(k));
+const better = (a, b) => (a.ok !== b.ok ? a.ok : a.n !== b.n ? a.n < b.n : a.sev < b.sev);
+const problems = n => `${n} problem${n === 1 ? "" : "s"}`;
+const cut = s => (s.length > 40 ? `${s.slice(0, 39)}~` : s);
+const named = c => `${c.specId} (${c.ok ? "QA passes" : problems(c.n)})`;
+// a take plays in the character's placement frame: one the watch put on says so (a move misaligns it)
+const POS = "bound to this position (recompile after a move)";
+
+export function createRepairWatch() {
+	const lines = new Map();
+	const lineOf = key => {
+		let line = lines.get(key);
+		if (line) { lines.delete(key); lines.set(key, line); return line; }
+		// picks: the best compile per placement; held: the take the watch put on; mine: the agent's own last install
+		line = { compiles: 0, steps: 0, call: null, last: null, before: null, passed: null, best: null, picks: new Map(), held: null, mine: null, noted: false, depth: new Map() };
+		lines.set(key, line);
+		if (lines.size > KEPT) lines.delete(lines.keys().next().value);
+		return line;
+	};
+	/**
+	 * One compile's note. qa is the full QA (every group); base the specId it patched, absent for a whole
+	 * spec; at the placement key of the compile (character pose and scene), take its baked take (kept while
+	 * it is the best at `at`), installed whether this compile put its own take on the character, current the
+	 * specId of the take the character carries now (after this compile).
+	 * -> { say?, install?: { specId, take } } : install is the best take the caller puts on the character.
+	 * callId the agent's tool call the compile ran in, or null.
+	 * @param {{ characterId: string, turnId?: string | null, callId?: string | null, specId: string, base?: string, qa: { ok: boolean, groups: object[] },
+	 *   at?: string, take?: unknown, installed?: boolean, current?: string | null }} c
+	 */
+	function note({ characterId, turnId = null, callId = null, specId, base, qa, at = "", take, installed = false, current = null }) {
+		const line = lineOf(`${characterId}\u0000${turnId ?? ""}`), groups = qa.groups ?? [];
+		const now = { specId, at, ok: Boolean(qa.ok), fails: new Set(groups.map(groupKey)), n: groups.length, sev: severity(groups), streak: 1 };
+		// core: the failures the whole streak shares (its first compile's; the later ones hold them all)
+		now.core = now.fails;
+		// a step: one agent call (its compiles share callId) or one compile; the streak compares with the last compile of the
+		// step before, so the variants one script compares are one try, not three
+		const step = !callId || callId !== line.call;
+		if (step) line.before = line.last;
+		const prev = line.before, fresh = base === undefined && line.noted;
+		if (prev && !fresh && now.fails.size && prev.fails.size && superset(now.fails, prev.fails) && now.n >= prev.n && now.sev > prev.sev * (1 - DELTA_STEP))
+			Object.assign(now, { streak: prev.streak + 1, core: prev.core });
+		line.compiles += 1;
+		if (step) line.steps += 1;
+		line.call = callId;
+		const depth = base === undefined ? 0 : (line.depth.get(base) ?? 0) + 1;
+		line.depth.set(specId, depth);
+		const repairs = turnId ? line.steps - 1 : depth, passed = line.passed, best = line.best;
+		line.last = now;
+		if (now.ok && !line.passed) line.passed = specId;
+		if (!best || better(now, best)) line.best = now;
+		// the best take at this placement (each of the last PLACES keeps its own), and the agent's own install
+		let pick = line.picks.get(at);
+		if (!pick || better(now, pick)) {
+			pick = { ...now, take };
+			let older = lines.size - TAKES;
+			for (const other of lines.values()) if (older-- > 0) for (const p of other.picks.values()) p.take = undefined;
+		}
+		line.picks.delete(at);
+		line.picks.set(at, pick);
+		if (line.picks.size > PLACES) line.picks.delete(line.picks.keys().next().value);
+		if (installed) line.mine = now;
+		const past = c => (best && best.specId !== c.specId && better(best, c) ? `; best so far ${named(best)}` : "");
+		const kind = passed && passed !== specId ? "polish" : repairs >= REPAIR_CAP && !now.ok ? "cap" : now.streak >= STUCK_AFTER ? "stuck" : null;
+		line.noted = Boolean(kind) && !passed;
+		if (!kind) return {};
+		// the take to leave on the character: this compile's, or the agent's own, when it carries it; else fill an empty
+		// take, or upgrade the one the watch put on, with the best here; a take from before this line stays
+		const held = line.held, mine = line.mine && line.mine.specId === current, watched = held && held.specId === current;
+		const keeps = !installed && !mine && watched && held.at === at && !better(pick, held);
+		const fills = !installed && !mine && !keeps && (current === null || watched) && pick.take !== undefined;
+		const install = fills ? { specId: pick.specId, take: pick.take } : undefined;
+		if (install) line.held = pick;
+		// what the character carries after the note, in one sentence; then what to do (a cap note at most ~180 characters)
+		const status = installed ? `This take is installed${past(now)}.` : install ? `Installed the best take here, ${named(pick)}, ${POS}.`
+			: mine ? `Your installed take ${named(line.mine)} stays${past(line.mine)}.` : keeps ? `${named(held)} stays installed, ${POS}.`
+				: current !== null && pick.take !== undefined ? `The earlier take stays; to replace it, install the best take here, ${named(pick)}.`
+					: `Install the best take here, ${named(pick)}.`;
+		const asked = "stop unless the user asked for a specific change";
+		let say;
+		if (kind === "polish") say = !install ? `${passed} already passed QA: ${asked}.` : install.specId === passed ? `${passed} passed QA and is now installed, ${POS}: ${asked}.`
+			: `${passed} passed QA at another position; the best take here, ${named(pick)}, is installed, ${POS}. Report its problems; ${asked}.`;
+		else if (kind === "cap") say = `${repairs} repair ${turnId && callId ? "calls" : "compiles"}. ${status} Report its problems; stop unless asked for more.`;
+		else {
+			const codes = [...now.core], names = codes.slice(0, SAY_CODES).map(cut).join(", ") + (codes.length > SAY_CODES ? ` +${codes.length - SAY_CODES}` : "");
+			say = `${names} unchanged over ${now.streak} ${turnId && callId ? "calls" : "compiles"}. Stop patching it or re-applying its hint: start afresh or try another approach. ${status} If neither helps, report its problems.`;
+		}
+		return { say, ...(install ? { install } : {}) };
+	}
+	return { note };
+}