cozyclay 3.1.1 → 3.1.2

package/src/motion3/json-patch.js

@@ -1,11 +1,22 @@
-// JSON Patch (RFC 6902) on a motion spec: add, remove, replace and test, with "-" to append to
+// JSON Patch (RFC 6902) on a motion spec: add, remove, replace, move and test, with "-" to append to
 // an array in add. Used for motion.compile { base, patch } (C7) and by repair (C6). Errors are
 // MOTION_SPEC_INVALID (INVALID_ARGUMENT to the agent) and name the op and what is there:
-//   patch[1] (replace /keys/12/f): /keys/12 does not exist (keys has 9 entries)
+//   patch[1] (replace /keys/12/f): /keys/12 does not exist (keys has 9 entries; by frame: /keys/@f=<f>, f 0, 24, 40, ...)
 // With a notes list (motion.compile, lenient.js), replace on a member an existing object lacks adds it
 // and says so; repair (no notes) stays strict.
+//
+// Stable addressing: an array step may be a selector "@field=value" ("&" joins more), the element whose
+// field reads value, instead of an index. An index edit goes wrong silently when an earlier entry is
+// added or removed, and the agent's own logs show index paths are most of what it patches, so:
+//   /keys/@f=120/set/hand_l          the key at frame 120 (several there: the last, the one that wins the bake)
+//   /objects/cup/keys/@f=40/pos      an object key by frame
+//   /use/@skill=reach&f0=40/args/at  a skill by name and first frame; /goals/@name=cup lifted; /fits/@anchor=cupHandle
+// add (and a lenient replace) through a selector that matches nothing creates the element ({ f: 120, set: {} }):
+// one op sets a channel on a key whether the key exists or not. remove /keys/@f=120 removes every key at 120;
+// a key moves with { op: "move", from: "/keys/@f=120", path: "/keys/@f=132" } (its f becomes 132; refused when
+// 132 is keyed). A selector that matches nothing lists the values there, nearest frames first, so a retry lands.
 
-const OPS = ["add", "remove", "replace", "test"];
+const OPS = ["add", "remove", "replace", "move", "test"];
 const bad = msg => { throw new Error(`MOTION_SPEC_INVALID: ${msg}`); };
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 
@@ -13,10 +24,68 @@ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const tokens = path => path.split("/").slice(1).map(t => t.replaceAll("~1", "/").replaceAll("~0", "~"));
 const pointer = parts => parts.map(t => `/${String(t).replaceAll("~", "~0").replaceAll("/", "~1")}`).join("");
 
-function what(container, name) {
-	if (Array.isArray(container)) return `${name} has ${container.length} entries`;
-	const keys = Object.keys(container);
-	return keys.length ? `${name} has ${keys.slice(0, 8).join(", ")}${keys.length > 8 ? ", ..." : ""}` : `${name} is empty`;
+const SELECTOR = /^@[A-Za-z_]\w*=[^&]*(&[A-Za-z_]\w*=[^&]*)*$/;
+/** "@skill=reach&f0=40" -> [["skill", "reach"], ["f0", "40"]], or null for any other step. */
+const conditions = t => (SELECTOR.test(t) ? t.slice(1).split("&").map(c => [c.slice(0, c.indexOf("=")), c.slice(c.indexOf("=") + 1)]) : null);
+const matches = (el, conds) => el !== null && typeof el === "object" && conds.every(([k, v]) => Object.hasOwn(el, k) && String(el[k]) === v);
+const isMap = v => v !== null && typeof v === "object" && !Array.isArray(v);
+const numeric = v => (/^-?\d+(\.\d+)?$/.test(v) ? Number(v) : v);
+// the fields that tell entries apart, in the order an error offers them
+const NAMES = ["name", "skill", "anchor", "f", "f0", "side", "type"];
+
+/** What an array holds, for an error: its length, and how to address it by a field its entries carry. */
+function what(container, name, want) {
+	if (!Array.isArray(container)) {
+		const keys = Object.keys(container);
+		return keys.length ? `${name} has ${keys.slice(0, 8).join(", ")}${keys.length > 8 ? ", ..." : ""}` : `${name} is empty`;
+	}
+	const field = want?.[0] ?? NAMES.find(k => container.some(el => el && typeof el === "object" && Object.hasOwn(el, k)));
+	if (!field) return `${name} has ${container.length} entries`;
+	const all = [...new Set(container.filter(el => el && Object.hasOwn(el, field)).map(el => el[field]))];
+	// frames: the nearest to the one asked for, shown in order
+	const target = Number(want?.[1]);
+	const values = all.every(v => typeof v === "number")
+		? (Number.isFinite(target) ? [...all].sort((a, b) => Math.abs(a - target) - Math.abs(b - target)) : all).slice(0, 8).sort((a, b) => a - b) : all.slice(0, 8);
+	return `${name} has ${container.length} entries; by ${field}: /${name}/@${field}=<${field}>, ${field} ${values.join(", ")}${all.length > values.length ? ", ..." : ""}`;
+}
+
+/** Index (as a string) of the element of arr that step t selects; creates it when `create`, else -1 when none. */
+function select(arr, t, rest, tag, name, create) {
+	const conds = conditions(t), hits = [];
+	arr.forEach((el, i) => matches(el, conds) && hits.push(i));
+	const frameOnly = conds.length === 1 && conds[0][0] === "f";
+	if (hits.length > 1 && !frameOnly) {
+		const field = NAMES.find(k => !conds.some(c => c[0] === k) && new Set(hits.map(i => arr[i]?.[k])).size === hits.length);
+		bad(`${tag}: ${hits.length} ${name} entries have ${t.slice(1)}${field ? ` (${field} ${hits.map(i => arr[i][field]).join(", ")}; add &${field}=<${field}>)` : ` (indices ${hits.join(", ")})`}`);
+	}
+	if (hits.length) {
+		// keys at one frame merge, the last winning: prefer the last that holds the rest of the path, then its parent
+		const has = (i, path) => { let n = arr[i]; for (const p of path) { if (n === null || typeof n !== "object" || !Object.hasOwn(n, p)) return false; n = n[p]; } return true; };
+		return String(hits.findLast(i => has(i, rest)) ?? hits.findLast(i => has(i, rest.slice(0, -1))) ?? hits.at(-1));
+	}
+	if (!create) return -1;
+	const el = Object.fromEntries(conds.map(([k, v]) => [k, numeric(v)]));
+	if (rest.length > 1) el[rest[0]] = {};
+	arr.push(el);
+	return String(arr.length - 1);
+}
+
+/** parts with every selector step but the last turned into an index; creates elements when `create`. */
+function resolve(doc, parts, tag, create, notes) {
+	let node = doc;
+	const out = [];
+	for (let i = 0; i < parts.length; i++) {
+		let t = parts[i];
+		if (Array.isArray(node) && conditions(t) && i < parts.length - 1) {
+			const name = i ? out[i - 1] : "the spec", k = select(node, t, parts.slice(i + 1), tag, name, false);
+			if (k === -1 && !create) bad(`${tag}: ${pointer([...out, t])} matches nothing (${what(node, name, conditions(t)[0])})`);
+			t = k === -1 ? select(node, t, parts.slice(i + 1), tag, name, true) : k;
+			if (k === -1) { out.created = true; notes?.push(`${tag}: created ${pointer(out)}/${t} (${parts[i].slice(1)})`); }
+		}
+		out.push(t);
+		if (i < parts.length - 1) node = node !== null && typeof node === "object" ? node[Array.isArray(node) ? Number(t) : t] : undefined;
+	}
+	return out;
 }
 
 /** The container holding the last token, walking every token before it. */
@@ -32,18 +101,57 @@ function parentOf(doc, parts, tag) {
 	return node;
 }
 
+/** The last step on an array, a selector: add appends (its fields set), remove drops every match, the rest take the one match. */
+function bySelector(node, last, op, value, tag, name) {
+	const conds = conditions(last), hits = node.flatMap((el, i) => (matches(el, conds) ? [i] : []));
+	if (op === "add") {
+		if (hits.length) bad(`${tag}: ${name} already has an entry with ${last.slice(1)}; replace its fields or remove it first`);
+		if (value === null || typeof value !== "object" || Array.isArray(value)) bad(`${tag}: add through a selector takes an object value`);
+		node.push({ ...structuredClone(value), ...Object.fromEntries(conds.map(([k, v]) => [k, numeric(v)])) });
+		return null;
+	}
+	if (!hits.length) bad(`${tag}: ${name} has no entry with ${last.slice(1)} (${what(node, name, conds[0])})`);
+	if (op === "remove") { for (const i of hits.reverse()) node.splice(i, 1); return null; }
+	return select(node, last, [], tag, name, false);
+}
+
 function applyOne(doc, op, i, notes) {
 	if (!op || typeof op !== "object" || !OPS.includes(op.op)) bad(`patch[${i}]: op must be ${OPS.join(", ")}, got ${JSON.stringify(op?.op)}`);
 	const tag = `patch[${i}] (${op.op} ${op.path})`;
-	if (typeof op.path !== "string" || (op.path !== "" && !op.path.startsWith("/"))) bad(`${tag}: path must be a JSON Pointer such as "/keys/0/f"`);
+	if (typeof op.path !== "string" || (op.path !== "" && !op.path.startsWith("/"))) bad(`${tag}: path must be a JSON Pointer such as "/keys/0/f" or "/keys/@f=24/set/hand_l"`);
+	if (op.op === "move") {
+		if (typeof op.from !== "string" || !op.from.startsWith("/")) bad(`${tag}: move needs from, a JSON Pointer such as "/keys/@f=120"`);
+		const parts = resolve(doc, tokens(op.from), tag, false), last = parts.at(-1), node = parentOf(doc, parts, tag), name = parts.at(-2) ?? "the spec";
+		let value;
+		if (Array.isArray(node) && conditions(last)) {
+			// every key at that frame moves, merged into one (later entries win, as in the bake)
+			const hits = node.flatMap((el, j) => (matches(el, conditions(last)) ? [j] : []));
+			if (!hits.length) bad(`${tag}: ${name} has no entry with ${last.slice(1)} (${what(node, name, conditions(last)[0])})`);
+			value = hits.map(j => node[j]).reduce((a, b) => Object.fromEntries([...new Set([...Object.keys(a), ...Object.keys(b)])].map(f => [f,
+				isMap(a[f]) && isMap(b[f]) ? { ...a[f], ...b[f] } : Array.isArray(a[f]) && Array.isArray(b[f]) && f === "step" ? [...new Set([...a[f], ...b[f]])] : Object.hasOwn(b, f) ? b[f] : a[f]])));
+			for (const j of hits.reverse()) node.splice(j, 1);
+		} else {
+			if (!Object.hasOwn(node, Array.isArray(node) ? Number(last) : last)) bad(`${tag}: ${op.from} does not exist (${what(node, name)})`);
+			value = node[Array.isArray(node) ? Number(last) : last];
+			if (Array.isArray(node)) node.splice(Number(last), 1); else delete node[last];
+		}
+		return applyOne(doc, { op: "add", path: op.path, value }, i, notes);
+	}
 	if (op.op !== "remove" && !Object.hasOwn(op, "value")) bad(`${tag}: needs a value`);
 	if (op.path === "") {
 		if (op.op === "replace") return structuredClone(op.value);
 		if (op.op === "test") { if (!same(doc, op.value)) bad(`${tag}: the spec differs from the test value`); return doc; }
 		bad(`${tag}: ${op.op} needs a path below the spec`);
 	}
-	const parts = tokens(op.path), last = parts[parts.length - 1], node = parentOf(doc, parts, tag);
+	const create = op.op === "add" || (op.op === "replace" && Boolean(notes));
+	const parts = resolve(doc, tokens(op.path), tag, create, notes), node = parentOf(doc, parts, tag);
+	let last = parts[parts.length - 1];
 	const name = parts.length > 1 ? parts[parts.length - 2] : "the spec";
+	if (Array.isArray(node) && conditions(last)) {
+		if (op.op === "replace" && notes && !node.some(el => matches(el, conditions(last)))) { notes.push(`${tag}: nothing had ${last.slice(1)}; added`); return applyOne(doc, { ...op, op: "add" }, i); }
+		last = bySelector(node, last, op.op, op.value, tag, name);
+		if (last === null) return doc;
+	}
 	if (Array.isArray(node)) {
 		if (last === "-") { if (op.op !== "add") bad(`${tag}: "-" (append) works with add only`); node.push(structuredClone(op.value)); return doc; }
 		const k = /^\d+$/.test(last) ? Number(last) : NaN;
@@ -55,7 +163,7 @@ function applyOne(doc, op, i, notes) {
 		else if (!same(node[k], op.value)) bad(`${tag}: value is ${JSON.stringify(node[k])?.slice(0, 60)}, not ${JSON.stringify(op.value)?.slice(0, 60)}`);
 		return doc;
 	}
-	if (op.op === "replace" && notes && !Object.hasOwn(node, last)) notes.push(`${tag}: ${op.path} did not exist (${what(node, name)}); added`);
+	if (op.op === "replace" && notes && !Object.hasOwn(node, last)) { if (!parts.created) notes.push(`${tag}: ${op.path} did not exist (${what(node, name)}); added`); }
 	else if (op.op !== "add" && !Object.hasOwn(node, last)) bad(`${tag}: ${op.path} does not exist (${what(node, name)})`);
 	if (op.op === "remove") delete node[last];
 	else if (op.op === "test") { if (!same(node[last], op.value)) bad(`${tag}: value is ${JSON.stringify(node[last])?.slice(0, 60)}, not ${JSON.stringify(op.value)?.slice(0, 60)}`); }
@@ -66,9 +174,9 @@ function applyOne(doc, op, i, notes) {
 /**
  * Applies ops in order to a copy of doc (doc is never changed) and returns the copy; the first
  * failing op throws MOTION_SPEC_INVALID and nothing is applied. notes (optional) turns a replace on a
- * missing object member into an add and collects a line for it.
+ * missing object member (or a selector that matches nothing) into an add and collects a line for it.
  * @param {object} doc
- * @param {{ op: "add" | "remove" | "replace" | "test", path: string, value?: any }[]} ops
+ * @param {{ op: "add" | "remove" | "replace" | "move" | "test", path: string, from?: string, value?: any }[]} ops
  * @param {string[]} [notes]
  */
 export function applyPatch(doc, ops, notes) {

package/src/motion3/lenient.js

@@ -4,16 +4,22 @@
 //   relaxSpec        on the expanded spec before validation (pipeline.js): a goal window partly past the
 //                    clip is cut to it; an object key with only pos takes the turn of the key before it
 //                    (else after it, else its scene pose: rot for a free entry, aim for a carry so the
-//                    arm picks the roll); a rot of length strictly between 0.5 and 2 is normalized
+//                    arm picks the roll); a rot of length strictly between 0.5 and 2 is normalized; a knee
+//                    pole that points backward in the body frame but forward read as a world direction at
+//                    the root yaw of its frame (a body turned 90 deg or more) is that world direction; a bare
+//                    name in goals near / above that is exactly one ref (refs.js bareRefs) is that ref
+//   (spelling and placement slips in the sent spec: correct.js, before it is stored)
 //   clampProbe       a probe window partly past the take is cut to it (probes.js)
 //   fitEvery         a position probe's every grows to fit its 16 rows (probes.js)
 //   clampFrames      contact-sheet frames past the range are pulled into it (studio-motion-visual.js)
 //   normalizeCompileArgs  install spellings ("always", "if_clean", ...) and repair: { rounds: 0 } / true
 //                    (the registry's normalizeArgs, before the schema check)
-import { quatFromMat } from "./compiler/math.js";
+import { quatFromMat, apply, ry } from "./compiler/math.js";
+import { stateAt } from "./compiler/walk.js";
 import { groupsOf } from "./scene.js";
 import { isCarried } from "./carried.js";
 import { isFree } from "./free-motion.js";
+import { bareRefs } from "./refs.js";
 
 const fmtRange = r => `[${r[0]},${r[1]}]`;
 /** Adds note to notes once (search trials expand the same spec again). */
@@ -72,13 +78,49 @@ function normalizeRots(id, o, notes) {
 	});
 }
 
+const r3 = v => v.map(x => Math.round(x * 1000) / 1000);
+/** A knee pole sent as a world direction (agents facing -Z write [0, 0, -1] for "forward"): its body-frame reading at the root yaw. */
+function worldPoles(spec, notes) {
+	if (!Array.isArray(spec.keys)) return;
+	spec.keys.forEach((key, i) => {
+		for (const ch of ["knee_l", "knee_r"]) {
+			const v = key?.set?.[ch];
+			if (!(Array.isArray(v) && v.length === 3 && v.every(Number.isFinite))) continue;
+			const l = Math.hypot(...v);
+			if (!(l > 1e-6 && v[2] < -0.7 * l)) continue;
+			const yaw = stateAt(spec.keys, key.f).yaw;
+			if (!(Number.isFinite(yaw) && Math.abs(((yaw % 360) + 540) % 360 - 180) >= 90)) continue;
+			const body = r3(apply(ry(-yaw), v));
+			if (body[2] < 0.7 * l) continue;
+			key.set[ch] = body;
+			note(notes, `corrected: ${key.src?.startsWith("keys[") ? key.src : `keys[${i}]`} (f${key.f}) ${ch} [${r3(v)}] is a world direction at root yaw ${Math.round(yaw)}: body frame [${body}] (a pole is +z forward)`);
+		}
+	});
+}
+
+/** goals[i].near / above: a bare name with one reading in the expanded spec, rig and scene takes it ("LeftHand" -> joint:LeftHand). */
+function bareGoalRefs(spec, ctx, notes) {
+	if (!Array.isArray(spec.goals)) return;
+	spec.goals.forEach((g, i) => {
+		for (const kind of ["near", "above"]) (Array.isArray(g?.[kind]) ? g[kind] : []).forEach((ref, j) => {
+			if (typeof ref !== "string" || /^[a-z]+:/.test(ref)) return;
+			const known = bareRefs(spec, ctx, ref);
+			if (known.length !== 1) return;
+			g[kind][j] = known[0];
+			note(notes, `corrected: goals[${i}].${kind}[${j}] "${ref}" -> "${known[0]}"`);
+		});
+	});
+}
+
 /**
- * relaxSpec(spec, scene, notes): the fixes above, in place on the expanded spec (a plain JSON copy the
+ * relaxSpec(spec, scene, notes, sk): the fixes above, in place on the expanded spec (a plain JSON copy the
  * compile measures; the stored spec stays as sent). notes collects one line per fix.
  */
-export function relaxSpec(spec, scene, notes) {
+export function relaxSpec(spec, scene, notes, sk) {
 	if (!spec || typeof spec !== "object") return spec;
 	relaxGoals(spec, notes);
+	bareGoalRefs(spec, { sk, scene }, notes);
+	worldPoles(spec, notes);
 	for (const [id, o] of Object.entries(spec.objects ?? {})) {
 		if (!o || typeof o !== "object" || !Array.isArray(o.keys) || !(isCarried(o) || isFree(o))) continue;
 		fillTurns(id, o, scene, notes);

package/src/motion3/object-keys.js

@@ -13,10 +13,11 @@
 import { isCarried, carriedPose, compose, relative } from "./carried.js";
 import { seatsInHand, seatOffset, settleAt, between as slide } from "./seat.js";
 import { groupsOf } from "./scene.js";
-import { restState } from "./compiler/skeleton.js";
+import { restState, bonePoint } from "./compiler/skeleton.js";
 import { add, scale, sub, apply, T, matFromQuat, quatFromMat } from "./compiler/math.js";
 import { qmul, qconj, qlog, qexp, qrot, qdot, qnorm } from "./compiler/quat.js";
 import { keyRots, leanPos } from "./key-aim.js";
+import { faceLeaned } from "./face-lean.js";
 import { holdCost } from "./compiler/hold.js";
 import { polePlan, smoothPath, smoothed } from "./hold-plan.js";
 import { secondGrip, secondHold, gripGate } from "./second-hand.js";
@@ -60,7 +61,7 @@ export function curveIn(out, id) {
 	if (!had || had.map !== map || had.baked !== baked) {
 		const hold = out.ctx.hold, solved = new Map(), at = t => { const f = Math.round(t); if (!solved.has(f)) solved.set(f, hold.plainFrame(f).s); return solved.get(f); };
 		const plain = t => quatFromMat(hold.carryOn(id, at(t)).R), strain = (t, pos, q, opts) => hold.strainOn(id, at(t), { pos, R: matFromQuat(q) }, opts);
-		cache.set(id, { map, baked, curve: curveOf(out.ctx.spec.objects[id], f => (map ? map(f) : f), plain, strain, 2 * (out.ctx.scene?.objects?.[id]?.half?.[1] ?? 0)) });
+		cache.set(id, { map, baked, curve: curveOf(hold.entry?.(id) ?? out.ctx.spec.objects[id], f => (map ? map(f) : f), plain, strain, 2 * (out.ctx.scene?.objects?.[id]?.half?.[1] ?? 0)) });
 	}
 	return cache.get(id).curve;
 }
@@ -112,6 +113,17 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	const { sk, spec, scene } = ctx, held = keyedEntries(spec);
 	if (!held.length) return null;
 	const seated = new Set(held.map(([id]) => id).filter(id => seatsInHand(spec, spec.objects[id], scene, id)).map(id => spec.objects[id]));
+	// the entry as the compile holds it: mouth keys leaned (faceLeaned), read once per compile on the frames without keys
+	const entries = new WeakMap(), mapped0 = f => (out.timeMap ? Math.round(out.timeMap(f)) : f);
+	const entry = id => {
+		if (!entries.has(out)) entries.set(out, new Map());
+		const cache = entries.get(out);
+		if (!cache.has(id)) {
+			const top = 2 * (scene?.objects?.[id]?.half?.[1] ?? 0);
+			cache.set(id, faceLeaned(spec.objects[id], top, f => bonePoint(solvePlain(mapped0(f)).s, sk.index.Head, sk.landmarks.mouth)));
+		}
+		return cache.get(id);
+	};
 	const palmOf = (o, s) => carriedPose(sk, spec, s, { prop: o.prop }, seated.has(o)), attached = new WeakMap(), attaching = new Set();
 	const restAt = (id, f) => ctx.restingAt?.(id, f) ?? scene?.objects?.[id] ?? groupsOf(scene)[id];
 	// a keyed carry of a thin body (a cup, a can, a bar) whose grip is free (no at/along, no orient: false, no grasp fit, no keyed
@@ -130,7 +142,7 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 			&& mapped(Math.min(...o.keys.map(key => key.f))) <= grab;
 		if (!free) return null;
 		attaching.add(id);
-		try { cache.set(id, chooseGrip({ sk, o, side: SIDES[k], grab, rest: restAt(id, grab), plain: f => solvePlain(f).s, palmOf: s => palmOf(o, s), map: mapped })); } finally { attaching.delete(id); }
+		try { cache.set(id, chooseGrip({ sk, o: entry(id), side: SIDES[k], grab, rest: restAt(id, grab), plain: f => solvePlain(f).s, palmOf: s => palmOf(o, s), map: mapped })); } finally { attaching.delete(id); }
 		return cache.get(id);
 	};
 	const attach = id => {
@@ -156,7 +168,7 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	const strainOn = (id, s, pose, opts) => { const o = spec.objects[id]; return holdCost(sk, s, SIDES[spec.props[o.prop].hand], compose(pose, invert(attach(id))), palmOf(o, s), opts); };
 	const heldAt = (id, o, f) => {
 		const curve = curveIn(out, id), w = leadWeight(curve, spanIn(out, o), f);
-		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attachAt(id, f))), measure: s => palmOf(o, s), comfort: o.keys.some(k => k.lean > 0) } : null;
+		return w > 0 ? { w, palm: compose(keyedPose(curve, f), invert(attachAt(id, f))), measure: s => palmOf(o, s), comfort: entry(id).keys.some(k => k.lean > 0) } : null;
 	};
 	// the elbow's planned path over the frames the keys lead (hold-plan.js), once per baked channels and time map
 	const plans = new WeakMap();
@@ -268,5 +280,5 @@ export function holdHook(ctx, out, solvePlain, solveLed) {
 	const firstKey = id => { const t = Math.min(...spec.objects[id].keys.map(k => k.f)); return out.timeMap ? Math.round(out.timeMap(t)) : t; };
 	// the grips chosen for keyed carries (observations.wrist reads them): [{ id, hand, name, cost, today }]
 	const grips = () => held.map(([id, o]) => { const p = chosen(id); return p && { id, hand: spec.props[o.prop].hand, name: p.name, cost: p.cost, today: p.today }; }).filter(Boolean);
-	return { lead, attach, attachAt, attaching: id => attaching.has(id), plainFrame: solvePlain, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
+	return { lead, attach, attachAt, attaching: id => attaching.has(id), plainFrame: solvePlain, entry, carryOn, strainOn, span: id => spanIn(out, spec.objects[id]), firstKey, grips };
 }

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)}`);
+}