cozyclay 3.1.1 → 3.1.2

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

package/src/motion3/repair.js

@@ -3,22 +3,37 @@
 // the patch the latest compile gives that group. When none is kept, the top 2 groups just past
 // their limit with no patch, or a missed goal, get a small local search (repair-tune.js: the
 // responsible skill's args, the key pair of a speed spike, or for a goal where the body stands
-// and how it leans); the best candidate is the round's change. A change
-// is kept only when the summed severity (qa/severity.js) drops and no goal that held fails, else
-// it is undone. A round that keeps nothing ends the repair. The compiler is deterministic and
-// the candidates come in a fixed order, so the repair is too; no new compile starts after 20 s.
+// and how it leans); the best candidate is the round's change. A change is kept only when
+// qa/verdict.js compareQa calls it better (the summed severity drops, no goal that held fails, no
+// more problems, and what got worse costs at most half of what got better), else it is undone, so
+// the result is never worse than the spec as sent. A failure local to an arm (its reach, wrist,
+// elbow, a hand or forearm into something) is tried without moving the body first: a patch or a
+// candidate that moves the root (a stance, a walk's length, the root keys) comes only when nothing
+// else is kept, and the applied entry says so (movedBody). A patch tried and not kept is not tried
+// again, so the groups after it get their turn. A round that keeps nothing ends the repair. The
+// compiler is deterministic and the candidates come in a fixed order, so the repair is too; no new
+// compile starts after 20 s.
 import { applyPatch } from "./json-patch.js";
 import { groupKey } from "./qa/severity.js";
 import { tuneCandidates } from "./repair-tune.js";
+import { compareQa } from "./qa/verdict.js";
 
 const TRIES = 3, TUNE_GROUPS = 2, LIMIT_MS = 20000;
 const groupsOf = r => r?.qa?.groups ?? [];
 const totalOf = r => groupsOf(r).reduce((sum, g) => sum + (g.severity ?? 0), 0);
 const failedOf = r => (r?.qa?.goals ?? []).filter(g => !g.ok).length;
 const groupIn = (r, key) => groupsOf(r).find(g => groupKey(g) === key);
-const heldOf = r => (r?.qa?.goals ?? []).filter(g => g.ok).map(g => g.name);
-/** Lower summed severity, no more failed goals, and every goal that held still holds. */
-const better = (r, than) => totalOf(r) < totalOf(than) - 1e-9 && failedOf(r) <= failedOf(than) && heldOf(than).every(n => heldOf(r).includes(n));
+/** qa/verdict.js: lower summed severity, no goal lost, no more problems, no trade of one failure for worse ones. */
+const better = (r, than) => compareQa(r?.qa, than?.qa).better;
+
+const ARM_PART = /^(hand|farm|uarm)_[lr]\b|^(Left|Right)(Arm|ForeArm|Hand)/;
+/** A failure of one arm: its reach, wrist or elbow, or a hand, forearm or upper arm into something. */
+const armLocal = g => (g.kind === "REACH" && /^arm_miss_[lr]$/.test(g.subject)) || ["WRIST", "ELBOW"].includes(g.kind)
+	|| (["BODY", "FACE", "COLLIDE", "POP", "ACC", "SPEED", "FLIP"].includes(g.kind) && ARM_PART.test(g.subject));
+/** A patch that moves where the body stands: a stance, a walk's length or end, a root key. */
+const movesBody = patch => patch.some(o => /^\/use\/\d+\/args(\/(at|step|firstStep|to))?$/.test(o.path) && (o.path.endsWith("/args") ? ["at", "step", "firstStep", "to"].some(k => o.value?.[k] !== undefined) : true)
+	|| /^\/keys\/\d+\/set\/root$/.test(o.path) || (o.path === "/keys/-" && o.value?.set?.root !== undefined));
+const MOVED = "the body moved: no change that keeps it in place fixed this arm's failure";
 
 /**
  * repairSpec(spec, { rounds }, compile) -> { spec, result, repair }
@@ -26,12 +41,13 @@ const better = (r, than) => totalOf(r) < totalOf(than) - 1e-9 && failedOf(r) <=
  * @param {{ rounds?: number }} opts  1..8 (default 4)
  * @param {(spec: object) => object} compile  spec -> pipeline.js compileSpec result (qa.groups[i].patch)
  * @returns {{ spec: object, result: object, repair: { rounds: number, compiles: number,
- *   applied: { kind: string, subject: string, patch: object[], severity: number[] }[], rejected: number } }}
+ *   applied: { kind: string, subject: string, patch: object[], severity: number[], movedBody?: string }[], rejected: number } }}
  */
 export function repairSpec(spec, opts, compile) {
 	const want = Math.min(8, Math.max(1, Math.round(Number(opts?.rounds ?? 4)) || 4)), t0 = performance.now();
 	const late = () => performance.now() - t0 >= LIMIT_MS;
 	let current = spec, result = compile(spec), compiles = 1, rejected = 0, rounds = 0;
+	const refused = new Set();
 	const applied = [];
 	/** Compiles current + patch; null (counted as rejected) when the patch or the spec fails. */
 	const attempt = patch => {
@@ -45,38 +61,55 @@ export function repairSpec(spec, opts, compile) {
 		}
 	};
 	const keep = (g, key, patch, { next, r }) => {
-		applied.push({ kind: g.kind, subject: g.subject, patch, severity: [g.severity, groupIn(r, key)?.severity ?? 0] });
+		const moved = armLocal(g) && movesBody(patch);
+		applied.push({ kind: g.kind, subject: g.subject, patch, severity: [g.severity, groupIn(r, key)?.severity ?? 0], ...(moved ? { movedBody: MOVED } : {}) });
 		current = next; result = r;
 	};
-	/** The best tune candidate for group g (repair-tune.js); true when it is kept. */
-	const tune = g => {
-		let best = null;
-		for (const patch of tuneCandidates(g, current)) {
+	/** The best of the patches for group g; true when one is kept. */
+	const best = (g, patches) => {
+		let top = null;
+		for (const patch of patches) {
 			if (late()) break;
 			const t = attempt(patch);
 			if (!t) continue;
-			if (better(t.r, best?.r ?? result)) { if (best) rejected += 1; best = { ...t, patch }; } else rejected += 1;
-			if (best && totalOf(best.r) === 0 && !failedOf(best.r)) break;
+			if (better(t.r, top?.r ?? result)) { if (top) rejected += 1; top = { ...t, patch }; } else rejected += 1;
+			if (top && totalOf(top.r) === 0 && !failedOf(top.r)) break;
 		}
-		if (best) keep(g, groupKey(g), best.patch, best);
-		return Boolean(best);
+		if (top) keep(g, groupKey(g), top.patch, top);
+		return Boolean(top);
+	};
+	/** The tune candidates for group g (repair-tune.js); an arm's failure tries those that keep the body in place first. */
+	const tune = g => {
+		const all = tuneCandidates(g, current);
+		if (!armLocal(g)) return best(g, all);
+		return best(g, all.filter(p => !movesBody(p))) || best(g, all.filter(movesBody));
 	};
 	while (rounds < want && !late()) {
-		const keys = groupsOf(result).filter(g => g.patch).slice(0, TRIES).map(groupKey);
+		// a patch already tried and not kept is not tried again: the groups after it get their turn
+		const keys = groupsOf(result).filter(g => g.patch && !refused.has(JSON.stringify(g.patch))).slice(0, TRIES).map(groupKey);
 		const near = groupsOf(result).filter(g => tuneCandidates(g, current).length).slice(0, TUNE_GROUPS).map(groupKey);
 		if (!keys.length && !near.length) break;
 		rounds += 1;
 		let kept = 0;
+		const deferred = [];
 		for (const key of keys) {
 			const g = groupIn(result, key);
 			if (!g?.patch || late()) continue;
+			// an arm's failure whose patch moves the body waits until nothing else is kept this round
+			if (armLocal(g) && movesBody(g.patch)) { deferred.push(key); continue; }
 			const t = attempt(g.patch);
-			if (t && better(t.r, result)) { keep(g, key, g.patch, t); kept += 1; } else if (t) rejected += 1;
+			if (t && better(t.r, result)) { keep(g, key, g.patch, t); kept += 1; } else { refused.add(JSON.stringify(g.patch)); if (t) rejected += 1; }
 		}
 		for (const key of kept ? [] : near) {
 			const g = groupIn(result, key);
 			if (g && !late() && tune(g)) { kept += 1; break; }
 		}
+		for (const key of kept ? [] : deferred) {
+			const g = groupIn(result, key);
+			if (!g?.patch || late()) continue;
+			const t = attempt(g.patch);
+			if (t && better(t.r, result)) { keep(g, key, g.patch, t); kept += 1; break; } else { refused.add(JSON.stringify(g.patch)); if (t) rejected += 1; }
+		}
 		if (!kept) break;
 	}
 	return { spec: current, result, repair: { rounds, compiles, applied, rejected } };

package/src/motion3/report.js

@@ -2,30 +2,55 @@
 // head and readback take about 1.5 KB), so fitOutput keeps the most useful parts within
 // MOTION_OUTPUT_BUDGET bytes of JSON and says what it cut in `more`; the cut parts stay in the
 // spec store (spec-store.js) and motion.report pages through them. Keep order (first = last cut):
-//   1. frames, fps, installed, specId, qa.ok/total/goals, observations, delta, repair  (always;
+//   1. brief, frames, fps, installed, specId, qa.ok/total/goals, observations, delta, repair  (always;
 //      observations are bounded: a fixed set of joints and limbs, about 1 KB)
 //   2. the first MIN_FULL qa.groups in full
 //   3. probes
 //   4. timeline (the planted spans go first, then entries from the end)
 //   5. the other groups as one-liners { kind, subject, count, severity, first, last }
-//   6. fixed, search, skills, ms
-// Room left after that turns one-liners back into full groups, from the top.
+//   6. qa.warnings (qa/arm-checks.js: never failing, so after every group), as many lines as fit
+//   7. fixed, search, skills, ms
+// An answer that does not fit and has a delta (base + patch) says observations.units only by reference: the
+// base's answer gave them. Last resort: observations.asked and the brief lose lines, then full groups become one-liners.
+// Room left after that turns one-liners back into full groups, from the top. A head still too big (a
+// repair that applied many patches) keeps the newest repair.applied entries; more.repair counts the rest.
+// brief (briefOf) is the answer in a few fixed-shape lines, so a script comparing variants returns it as
+// it is instead of mapping qa itself:
+//   "<specId> qa ok|<problems> problems (<total> issues)[, installed|not installed]"
+//   "goals <n ok>/<n>[; MISS <name> <value> f<at> (<= or >= need)]...[; <n> more]"  (when the spec has goals; 3 misses)
+//   "<KIND> <subject> x<count> f<first>-<last>"  (the first 2 groups past the GOAL ones, which MISS names; subject cut to 48)
 
 export const MOTION_OUTPUT_BUDGET = 6000;
-const MIN_FULL = 4;
+const MIN_FULL = 4, BRIEF_GROUPS = 2, BRIEF_MISSES = 3, BRIEF_SUBJECT = 48;
+const AT_MOST = new Set(["near", "still"]), UNITS_SEEN = "as in the base's answer";
 const size = v => new TextEncoder().encode(JSON.stringify(v)).length;
 const oneLine = g => ({ kind: g.kind, subject: g.subject, count: g.count, severity: g.severity, first: g.first, last: g.last });
 
+/** The fixed-shape summary lines of an answer with qa (see the head comment), or null without qa. */
+export function briefOf({ specId, installed, qa }) {
+	if (!qa) return null;
+	const head = `${specId ?? "spec"} qa ${qa.ok ? "ok" : `${qa.problems ?? qa.groups?.length ?? 0} problems (${qa.total} issues)`}${installed === undefined ? "" : installed ? ", installed" : ", not installed"}`;
+	const goals = qa.goals ?? [], failed = goals.filter(g => !g.ok), miss = failed.slice(0, BRIEF_MISSES)
+		.map(g => `; MISS ${g.name} ${g.value ?? "never"}${g.at === null ? "" : ` f${g.at}`} (${AT_MOST.has(g.kind) ? "<=" : ">="} ${g.need})`).join("");
+	const more = failed.length > BRIEF_MISSES ? `; ${failed.length - BRIEF_MISSES} more` : "";
+	const groups = (qa.groups ?? []).filter(g => g.kind !== "GOAL").slice(0, BRIEF_GROUPS).map(g => `${g.kind} ${g.subject.slice(0, BRIEF_SUBJECT)} x${g.count} f${g.first}-${g.last}`);
+	return [head, ...(goals.length ? [`goals ${goals.length - failed.length}/${goals.length}${miss}${more}`] : []), ...groups];
+}
+
 /**
- * full output -> output within `budget` bytes of JSON. When something was cut it carries
+ * full output -> output within `budget` bytes of JSON, with brief (briefOf) first. When something was cut it carries
  * more: { specId, groups, timeline, probes }, how many items of each part are missing or
  * shortened; motion.report { specId, part, from } pages the whole part.
  */
-export function fitOutput(full, budget = MOTION_OUTPUT_BUDGET) {
+export function fitOutput(answer, budget = MOTION_OUTPUT_BUDGET) {
+	const brief = briefOf(answer), full = brief ? { brief, ...answer } : answer;
 	if (size(full) <= budget) return full;
-	const { qa, observations, probes, timeline, fixed, search, skills, ms, ...head } = full;
+	const { qa, observations: all, probes, timeline, fixed, search, skills, ms, ...head } = full;
+	// an answer to base + patch leaves out the units the base's answer gave
+	const observations = all?.units && full.delta ? { ...all, units: UNITS_SEEN } : all;
 	const groups = qa?.groups ?? [], more = { specId: full.specId, groups: 0, timeline: 0, probes: 0 };
-	const out = { ...head, ...(qa ? { qa: { ...qa, groups: [] } } : {}), ...(observations ? { observations } : {}) };
+	const { warnings, ...qaHead } = qa ?? {};
+	const out = { ...head, ...(qa ? { qa: { ...qaHead, groups: [] } } : {}), ...(observations ? { observations } : {}) };
 	// the counts in `more` may still grow by a digit or two after a check
 	const fits = extra => size({ ...out, ...extra, more }) <= budget - 32;
 	const nFull = Math.min(MIN_FULL, groups.length);
@@ -43,10 +68,26 @@ export function fitOutput(full, budget = MOTION_OUTPUT_BUDGET) {
 		more.timeline = list === lean ? timeline.length : timeline.length - n;
 	}
 	for (let i = nFull; i < groups.length && fits({ qa: { ...out.qa, groups: [...out.qa.groups, oneLine(groups[i])] } }); i++) out.qa.groups.push(oneLine(groups[i]));
+	for (let n = warnings?.length ?? 0; n > 0; n--) if (fits({ qa: { ...out.qa, warnings: warnings.slice(0, n) } })) { out.qa.warnings = warnings.slice(0, n); break; }
 	for (const [k, v] of [["fixed", fixed], ["search", search], ["skills", skills], ["ms", ms]]) if (v !== undefined && fits({ [k]: v })) out[k] = v;
 	for (let i = nFull; i < out.qa?.groups.length && fits({ qa: { ...out.qa, groups: out.qa.groups.map((g, j) => (j === i ? groups[i] : g)) } }); i++) out.qa.groups[i] = groups[i];
-	// last resort (huge hints): full groups become one-liners from the end
+	// last resort (huge hints): observations.asked loses its goal and contact lines from the end, the brief its group
+	// lines, then full groups become one-liners from the end, then asked loses its skill lines
+	const asked = out.observations?.asked, cut = keep => { while (out.observations.asked.length > keep && !fits({})) out.observations.asked.pop(); };
+	if (asked) { out.observations = { ...out.observations, asked: [...asked] }; cut(asked.filter(l => l.startsWith("use[")).length); }
+	// the brief's group lines repeat qa.groups
+	while (out.brief?.length > 1 && !out.brief[out.brief.length - 1].startsWith("goals ") && !fits({})) out.brief = out.brief.slice(0, -1);
 	for (let i = nFull - 1; i >= 0 && !fits({}); i--) out.qa.groups[i] = oneLine(groups[i]);
+	// a long repair (each applied patch in full) keeps its newest changes; the stored spec holds them all
+	const applied = out.repair?.applied;
+	if (Array.isArray(applied) && !fits({})) {
+		let n = applied.length;
+		while (n > 0 && !fits({ repair: { ...out.repair, applied: applied.slice(applied.length - n) } })) n--;
+		out.repair = { ...out.repair, applied: applied.slice(applied.length - n) };
+		more.repair = applied.length - n;
+	}
+	if (asked) cut(0);
+	if (asked && !out.observations.asked.length) delete out.observations.asked;
 	more.groups = groups.length - (out.qa?.groups ?? []).filter(g => "worst" in g).length;
 	return { ...out, more };
 }

package/src/motion3/schema/topics.js

@@ -42,7 +42,7 @@ export const EXAMPLES = {
 		{ f: 30, set: { lid: 1 }, step: ["lid"] }] },
 	refs: { props: { cupGrip: GRIP }, anchors: { spot: SPOT }, goals: [
 		{ name: "fingers at the spot", near: ["prop:cupGrip.fingers", "anchor:spot"], at: 30 },
-		{ name: "cup at the mouth", near: ["object:cup.top", "landmark:mouth"], tol: 0.06, at: [40, 50] },
+		{ name: "cup at the mouth", near: ["object:cup.rim", "landmark:mouth"], tol: 0.06, at: [40, 50] },
 		{ name: "hand above the hips", above: ["joint:RightHand", "bone:Hips"], at: 30 }] },
 	fix: { fix: { reach: true, slide: true, penetration: 0.02, self: true, retime: false } },
 };
@@ -99,17 +99,19 @@ export const NOTES = {
 		"at is an absolute frame or [f0, f1]; mode all (every frame; the default) or any (one frame; speed's default). A failed goal is a GOAL group first in qa.groups and makes qa.ok false.",
 		"after / before: another goal's name; at is cut to the frames after (before) the first frame that goal holds, so cause and effect keep their order wherever the event lands (the can moves after the kick). If that goal never holds, this one fails with value null.",
 		"Intent lines as goals: a contact is near between the touching point (joint:RightHandIndex4, joint:RightToeBase) and the object, tol 0.02-0.03; a negative is still on the object before: \"<contact goal>\"; an effect is moved on the object after: \"<contact goal>\" (mode any); a strike is speed of the joint, by m/s, before: \"<contact goal>\"; an effect on something nobody holds (a can that drops, a machine that rocks) moves it by spec.objects keys or fall (topic: \"objects\"), not a hinge or a swapped copy.",
-		"A cup or can brought to the mouth: give its aim keys lean 20-30 so the elbow stays low (observations.wrist raised counts the frames with the elbow over the shoulder)."],
+		"A cup or can brought to the mouth: an aim key with its top at the lips leans 45 by default so the elbow stays low (lean 0 holds aim exactly; observations.wrist raised counts the frames with the elbow over the shoulder). qa.warnings (ARM, never failing) name an elbow over the shoulder, over the head or flared out, its frames and the key or elbow_<side> pole that fixes it."],
 	probes: ["motion.compile { probes } (at most 16); spec.probes are measured too, not stored; answered whether or not it installs.",
 		"distance [a, b] -> { min, minAt, max, maxAt, mean, first, last } in m; a bare object:<id> measures to its surface. position -> { at: [{ f, p }] }, at most 16 rows."],
 	channels: ["key.set names channels; values ease between keys and hold after the last key. step: [channel] jumps at f instead.",
-		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. flow: false turns it off; { smooth: false } or { lag: false } one part.",
+		"Flow (spec.flow, on by default): the spine, head, arm swing/bend and wrist carry their speed through a key (a small overshoot) and trail the body (spine 1, head 2, arms 3 frames; lag: { spine, head, arms } or a number); and each change breaks along the body (overlap: the lower spine, chest, head, upper arm, forearm and wrist start and settle a few frames apart, one side trailing the other, the arm's swing settling past its stop; less for a short move, none on an arm's IK or a walk); feet, root, hand targets, weights, poles, fingers and objects land on their keys on time. flow: false turns it off; { smooth: false }, { lag: false } or { overlap: false } one part (overlap: a number 0..2 scales it).",
 		"w_<anchor>_<side> (0..1) weights a hand onto an anchor; the weights of one hand add up to at most 1.",
 		"Any other numeric channel must come from spec.channels, a hinge (objects.<id>.channel), a check's when or a visible switch; names ending _vis are visibility switches (shown above 0.5)."],
-	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base], person:<character id>.<Bone> (another character's joint in its installed take).",
+	refs: ["A ref names a point: joint:/bone:<Bone>, prop:<prop>.<point>, anchor:<name>, landmark:mouth, object:<id>[.center|.top|.base|.rim], person:<character id>.<Bone> (another character's joint in its installed take).",
+		"object .center/.top/.base are points of its world bounding box (a tilted cup's .top is not its rim); .rim is its opening (the top face in its own axes, tilting with it), against another point the nearest edge: drink goals take .rim.",
 		"object:<id> takes a body or a group (the box around its parts); in a distance a bare object:<id> means its surface.",
 		"Goals and probes take every kind; spec.checks keep joint:, prop: and anchor:."],
 	fix: [`spec.fix keys: ${FIX_KEYS.join(", ")}; false turns all off. output.fixed reports what each one changed.`,
 		"reach, slide, self and stance are on by default; penetration and retime are opt-in.",
+		"reach also brings the body to a hand on a world or scene-object anchor the straight arm misses: a lean, a hip shift, lower hips, the feet kept (fixed.reachBody lists each move); farther, place the body. retime is kept only when QA is no worse with it.",
 		"self keeps the arms out of the body on its fitted skin (QA BODY measures the same skin): wrist targets inside it go onto it, elbows turn about the shoulder-wrist line, a hand a little inside is pushed out. A fit's target (the mouth) is never moved; what is left is BODY, with checks.allow { part, object: <body part>, depth } for a contact meant to touch (a hand on a knee)."],
 };

package/src/motion3/schema/types.js

@@ -148,6 +148,6 @@ export const FIX_TYPES = {
 
 export const REF_DOCS = {
 	joint: "joint:<Bone>", bone: "bone:<Bone> (= joint:)", prop: "prop:<prop>.<point> (origin exists)",
-	anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base], a body or group; bare = its surface (distance)",
+	anchor: "anchor:<name>", landmark: "landmark:mouth", object: "object:<id>[.center|.top|.base|.rim], a body or group; bare = its surface (distance)",
 	person: "person:<id>.<Bone>",
 };

package/src/motion3/skills/basic.js

@@ -4,6 +4,7 @@ import { add, apply, ry } from "../compiler/math.js";
 import { walk } from "../compiler/walk.js";
 import { keyBook, skillError } from "./book.js";
 import { walkEnd } from "./info.js";
+import { fitTo, walkEndAt, r2, xzText, REACH_TOL } from "./walk-fit.js";
 import { GRASP_FINGERS, GRASP_POINTS } from "../compiler/vocab.js";
 import { clearStance, reachStance } from "./stance.js";
 import { CLOSE, GAZE, gazeAt, headKeyed, earlyTransport, holdsOpen, transportKeys } from "./reach-human.js";
@@ -40,30 +41,36 @@ export function standIdle(ctx) {
 /**
  * walkTo({ to: [x, z] } | { heading: h | [h0, h1] }, steps, step = 0.5, turnDistance, ...): the
  * walk generator from the pose at f0. With `to` the heading turns toward the point and the step
- * count covers the distance. Ends 16 + steps * period + 18 frames after f0, feet together; a
- * take that ends after the last step holds that pose to its end. The steps keep a natural rhythm
- * (compiler/gait-rhythm.js); vary: 0 makes every step the same.
+ * count covers the distance; with steps as well the stride is fitted so they end there (fitTo). Ends
+ * 16 + steps * period + 18 frames after f0, feet together; a take that ends after the last step holds
+ * that pose to its end. A walk with `to` that ends more than 0.1 m from it says where in `placed`. The
+ * steps keep a natural rhythm (compiler/gait-rhythm.js); vary: 0 makes every step the same.
  */
 export function walkTo(ctx) {
 	const { args, state } = ctx;
 	if (!state.foot_l || !state.foot_r || !state.root) skillError(ctx.tag, "needs a standing pose keyed before f0 (use standIdle or another skill first)");
-	const gen = { type: "walk", f0: ctx.f0, ...args };
+	let gen = { type: "walk", f0: ctx.f0, ...args }, adjust, c0, h1;
 	delete gen.to; delete gen.arrive;
 	const h0 = state.yaw ?? 0, step = args.step ?? 0.5, first = args.firstStep ?? 0.4;
 	if (args.to) {
-		const c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2];
+		c0 = [(state.foot_l[0] + state.foot_r[0]) / 2, (state.foot_l[2] + state.foot_r[2]) / 2];
 		const dx = args.to[0] - c0[0], dz = args.to[args.to.length - 1] - c0[1], d = Math.hypot(dx, dz);
-		let h1 = Math.atan2(dx, dz) * 180 / Math.PI;
+		h1 = Math.atan2(dx, dz) * 180 / Math.PI;
 		while (h1 - h0 > 180) h1 -= 360;
 		while (h1 - h0 < -180) h1 += 360;
 		gen.heading = args.heading ?? [h0, h1];
 		gen.steps = args.steps ?? Math.max(2, 2 + Math.round((d - first) / step));
+		if (typeof gen.heading === "number") gen.heading = [h0, gen.heading];
+		if (ctx.fit && d > REACH_TOL) ({ gen, adjust } = fitTo(ctx, gen, c0, d, h1));
 	}
 	if (typeof gen.heading === "number") gen.heading = [h0, gen.heading];
 	const keys = walk(gen, ctx.keys, ctx.sk, ctx.tag), end = walkEnd(gen), last = ctx.frames - 1;
+	const at = args.to && walkEndAt(keys), miss = at ? Math.hypot(at[0] - args.to[0], at[1] - args.to[args.to.length - 1]) : 0;
+	const placed = miss > REACH_TOL ? { placed: { at: at.map(r2), heading: Math.round(gen.heading?.[1] ?? h0), why: `ends ${r2(miss)} m from to ${xzText(args.to)}` } } : {};
+	const more = { ...placed, ...(adjust ? { adjust } : {}) };
 	// the settle after the last step only holds the pose: a take that ends in it ends the walk there
-	if (end > last && Math.max(...keys.filter(k => k.f < end).map(k => k.f)) <= last) return { keys: keys.filter(k => k.f <= last), end: last, cut: `settle cut at f${last} (hold to the end)` };
-	return { keys, end };
+	if (end > last && Math.max(...keys.filter(k => k.f < end).map(k => k.f)) <= last) return { keys: keys.filter(k => k.f <= last), end: last, cut: `settle cut at f${last} (hold to the end)`, ...more };
+	return { keys, end, ...more };
 }
 
 /** base when `props` has no other prop of that name (the same one again is fine), else base_<side>, base_<side>2, ... */