cozyclay 3.1.1 → 3.1.2

package/src/motion3/correct.js

@@ -0,0 +1,236 @@
+// C21. Corrections: slips in a sent spec that have one reading, fixed before the spec is stored, each named
+// in output.adjusted ("corrected: ...") so the compile goes on instead of being refused. A name is corrected
+// only when exactly one known name matches it once case, "_", "-" and spaces are ignored (spinePitch ->
+// spine_pitch, walk_to -> walkTo), when it is a plural or a singular of one (goal -> goals), or by the short
+// alias lists below (arm_swing_l -> aswing_l, pos -> p on a world anchor), and the right name is not there
+// already. Anything with two readings stays for the validator to refuse with every problem listed.
+//   spec fields, use[i] skill names and fields, use[i].args names (an arg of the skill written beside args
+//   moves into it, args.f0 moves out), key channels and finger presets, object key and fall fields, goal,
+//   fit and check entry fields, anchor fields
+//   generators[i] with to, arrive, a single heading or type "walkTo" -> a walkTo use entry (the walk that
+//   heads for a point), placed in f0 order among the use entries
+//   objects.<id> written as { free: {...} } (or carry, hinge, follow) -> the record itself
+//   fitWalks: a walkTo with to and steps gets the stride, or the step count and cadence, that ends the steps at
+//   to in a natural gait (skills/basic.js fitTo), stored with the spec; one it cannot fit is refused with what the
+//   walk would do and needs
+import { SPEC_FIELDS, USE_FIELDS, OBJECT_KEY_FIELDS, FALL_FIELDS, GOAL_FIELDS, FIT_FIELDS, ANCHOR_FIELDS, CHECK_ENTRY_FIELDS, OBJECT_FIELDS } from "./schema/fields.js";
+import { VEC_CHANNELS, NUM_CHANNELS, MAP_CHANNELS, FINGER_PRESETS } from "./compiler/vocab.js";
+import { SKILL_INFO } from "./skills/info.js";
+import { SKILL_NAMES, expandUse } from "./skills/index.js";
+import { customChannels } from "./compiler/validate.js";
+
+const plain = v => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const squash = s => String(s).toLowerCase().replace(/[\s_-]/g, "");
+/** Sided names: left / right / L / R at the end read as _l / _r. */
+const sided = s => String(s).replace(/[_-]?(left|Left|LEFT)$/, "_l").replace(/[_-]?(right|Right|RIGHT)$/, "_r").replace(/[_-]?L$/, "_l").replace(/[_-]?R$/, "_r");
+const CHANNEL_ALIASES = { arm_swing: "aswing", armswing: "aswing", elbow_bend: "abend", arm_bend: "abend", wrist_twist: "wtwist", wrist_flex: "wflex",
+	foot_yaw: "fyaw", foot_pitch: "fpitch", arm_weight: "armw", ik_weight: "armw", hips: "root", pelvis: "root", finger: "fingers", hand_pole: "elbow", knee_pole: "knee" };
+const FIELD_ALIASES = {
+	objectKey: { position: "pos", rotation: "rot", quat: "rot", quaternion: "rot", frame: "f" },
+	anchor: { pos: "p", position: "p", point: "p", id: "object", joint: "bone" },
+	use: { frame: "f0", f: "f0" },
+};
+
+/** The one name of `names` that `name` stands for, or null: alias, case and separators, plural or singular. */
+function nameFor(name, names, aliases = {}) {
+	if (names.includes(name)) return name;
+	const alias = aliases[name] ?? aliases[squash(name)];
+	if (alias && names.includes(alias)) return alias;
+	const hits = new Set(names.filter(n => squash(n) === squash(name) || n === `${name}s` || `${n}s` === name));
+	return hits.size === 1 ? [...hits][0] : null;
+}
+
+/** obj with each unknown field that stands for exactly one free known field renamed; one note per rename. */
+function renameFields(obj, fields, at, notes, aliases) {
+	if (!plain(obj)) return obj;
+	let out = obj;
+	for (const f of Object.keys(obj)) {
+		const to = fields.includes(f) ? null : nameFor(f, fields, aliases);
+		if (!to || to in out) continue;
+		out = Object.fromEntries(Object.entries(out).map(([k, v]) => (k === f ? [to, v] : [k, v])));
+		notes.push(`corrected: ${at}.${f} -> ${at}.${to}`);
+	}
+	return out;
+}
+
+const mapList = (list, fn) => (Array.isArray(list) ? list.map(fn) : list);
+
+/** A generator that is a walkTo: it heads for a point, plans to arrive, turns to one heading, or says so. */
+const isWalkTo = g => plain(g) && (g.to !== undefined || g.arrive !== undefined || typeof g.heading === "number" || nameFor(String(g.type), ["walkTo"]) === "walkTo");
+
+function moveGenerators(spec, notes) {
+	if (!Array.isArray(spec.generators) || !spec.generators.some(isWalkTo)) return spec;
+	const use = Array.isArray(spec.use) ? [...spec.use] : [], kept = [];
+	spec.generators.forEach((g, i) => {
+		if (!isWalkTo(g)) return kept.push(g);
+		const { type, f0, ...args } = g, at = use.findIndex(u => plain(u) && Number.isFinite(u.f0) && u.f0 > f0);
+		const j = at < 0 ? use.length : at;
+		use.splice(j, 0, { skill: "walkTo", f0, args });
+		const why = g.to !== undefined ? "to" : g.arrive !== undefined ? "arrive" : typeof g.heading === "number" ? "a single heading" : `type "${type}"`;
+		notes.push(`corrected: generators[${i}] (a walk with ${why}) -> use[${j}] walkTo { ${Object.keys(args).join(", ")} }: a generator walks by steps and [h0, h1]; walkTo is the walk that heads for a point`);
+	});
+	const { generators, ...rest } = spec;
+	return { ...rest, ...(kept.length ? { generators: kept } : {}), use };
+}
+
+function fixUse(u, i, notes) {
+	if (!plain(u)) return u;
+	let out = u;
+	const skill = SKILL_NAMES.includes(u.skill) ? u.skill : nameFor(String(u.skill), SKILL_NAMES);
+	if (skill && skill !== u.skill) { out = { ...out, skill }; notes.push(`corrected: use[${i}].skill "${u.skill}" -> "${skill}"`); }
+	const info = SKILL_INFO[out.skill];
+	if (!info) return out;
+	const known = Object.keys(info.args);
+	if (plain(out.args) || out.args === undefined) {
+		const given = out.args ?? {};
+		let args = renameFields(given, known, `use[${i}].args`, notes);
+		// an enum arg written another way: "left" -> "l", "Back" -> "back"
+		for (const [a, v] of Object.entries(args)) {
+			const choices = info.args[a]?.enum, to = choices && typeof v === "string" && !choices.includes(v) ? nameFor(v, choices, { left: "l", right: "r" }) : null;
+			if (to) { args = { ...args, [a]: to }; notes.push(`corrected: use[${i}].args.${a} "${v}" -> "${to}"`); }
+		}
+		if (args.f0 !== undefined && !known.includes("f0") && out.f0 === undefined) {
+			const { f0, ...rest } = args;
+			args = rest; out = { ...out, f0 };
+			notes.push(`corrected: use[${i}].args.f0 -> use[${i}].f0`);
+		}
+		// an arg of the skill written beside args goes into args
+		for (const f of Object.keys(out)) {
+			const a = USE_FIELDS.includes(f) ? null : nameFor(f, known);
+			if (!a || a in args) continue;
+			args = { ...args, [a]: out[f] };
+			out = Object.fromEntries(Object.entries(out).filter(([k]) => k !== f));
+			notes.push(`corrected: use[${i}].${f} -> use[${i}].args.${a}`);
+		}
+		// an anchor a skill defines (reachGrip define) is an anchor like any other
+		if (plain(args.define) && ANCHOR_FIELDS[args.define.kind]) {
+			const define = renameFields(args.define, ["kind", ...ANCHOR_FIELDS[args.define.kind]], `use[${i}].args.define`, notes, FIELD_ALIASES.anchor);
+			if (define !== args.define) args = { ...args, define };
+		}
+		if (args !== given) out = { ...out, args };
+	}
+	return renameFields(out, USE_FIELDS, `use[${i}]`, notes, FIELD_ALIASES.use);
+}
+
+/** The body's channels and the spec's own (spec.channels, object and check channels, validate.js). */
+const knownChannels = spec => [...VEC_CHANNELS, ...NUM_CHANNELS, ...MAP_CHANNELS, ...customChannels(spec)];
+
+function channelFor(ch, known) {
+	const s = sided(ch), side = /_[lr]$/.exec(s)?.[0] ?? "", family = side ? s.slice(0, -2) : s;
+	const alias = CHANNEL_ALIASES[family] ?? CHANNEL_ALIASES[squash(family)];
+	if (alias && known.includes(alias + side)) return alias + side;
+	return nameFor(s, known);
+}
+
+function fixKey(key, i, known, notes) {
+	if (!plain(key) || !plain(key.set)) return key;
+	let set = key.set, step = key.step;
+	for (const ch of Object.keys(key.set)) {
+		if (known.includes(ch) || ch.endsWith("_vis") || ch.startsWith("w_")) continue;
+		const to = channelFor(ch, known);
+		if (!to || to in set) continue;
+		set = Object.fromEntries(Object.entries(set).map(([k, v]) => (k === ch ? [to, v] : [k, v])));
+		if (Array.isArray(step)) step = step.map(s => (s === ch ? to : s));
+		notes.push(`corrected: keys[${i}] (f${key.f}) channel "${ch}" -> "${to}"`);
+	}
+	for (const side of ["l", "r"]) {
+		const map = set[`fingers_${side}`];
+		if (!plain(map)) continue;
+		const fixed = renameFields(map, FINGER_PRESETS, `keys[${i}] (f${key.f}) fingers_${side}`, notes);
+		if (fixed !== map) set = { ...set, [`fingers_${side}`]: fixed };
+	}
+	return set === key.set ? key : { ...key, set, ...(step ? { step } : {}) };
+}
+
+/** objects.<id>: { free: { keys } } -> { keys }: a kind name used as a wrapper around the record's own fields. */
+function unwrapObject(id, o, notes) {
+	if (!plain(o)) return o;
+	const wrap = Object.keys(o).filter(k => ["free", "carry", "hinge", "follow", "switch"].includes(k) && plain(o[k]));
+	if (wrap.length !== 1) return o;
+	const { [wrap[0]]: inner, ...rest } = o;
+	if (Object.keys(inner).some(k => k in rest)) return o;
+	notes.push(`corrected: objects.${id}.${wrap[0]} { ${Object.keys(inner).join(", ")} } -> objects.${id} { ${Object.keys(inner).join(", ")} }: an entry's kind is read from its fields, not named`);
+	return { ...rest, ...inner };
+}
+
+function fixObject(id, o, notes) {
+	const at = `objects.${id}`, rec = unwrapObject(id, o, notes);
+	if (!plain(rec)) return rec;
+	const all = [...new Set(Object.values(OBJECT_FIELDS).flat())];
+	let out = renameFields(rec, all, at, notes);
+	if (Array.isArray(out.keys)) out = { ...out, keys: out.keys.map((k, j) => renameFields(k, OBJECT_KEY_FIELDS, `${at}.keys[${j}]`, notes, FIELD_ALIASES.objectKey)) };
+	if (plain(out.fall)) out = { ...out, fall: renameFields(out.fall, FALL_FIELDS, `${at}.fall`, notes) };
+	else if (Array.isArray(out.fall)) out = { ...out, fall: out.fall.map((fl, j) => renameFields(fl, FALL_FIELDS, `${at}.fall[${j}]`, notes)) };
+	return out;
+}
+
+const fixGoal = (g, i, notes) => renameFields(g, GOAL_FIELDS, `goals[${i}]`, notes);
+
+function fixAnchors(anchors, notes) {
+	if (!plain(anchors)) return anchors;
+	return Object.fromEntries(Object.entries(anchors).map(([name, a]) => [name, plain(a) && ANCHOR_FIELDS[a.kind]
+		? renameFields(a, ["kind", ...ANCHOR_FIELDS[a.kind]], `anchors.${name}`, notes, FIELD_ALIASES.anchor) : a]));
+}
+
+function fixChecks(checks, notes) {
+	if (!plain(checks)) return checks;
+	return Object.fromEntries(Object.entries(checks).map(([name, list]) => [name, CHECK_ENTRY_FIELDS[name] ? mapList(list, (k, j) => renameFields(k, CHECK_ENTRY_FIELDS[name], `checks.${name}[${j}]`, notes)) : list]));
+}
+
+/**
+ * correctSpec(spec, notes) -> the spec with every correction above (a new object when one applied,
+ * else spec itself); notes gets one "corrected: ..." line per correction. Run before the spec is stored (pipeline.js).
+ */
+function correctSpec(spec, notes = []) {
+	if (!plain(spec)) return spec;
+	const before = notes.length;
+	let s = renameFields(spec, [...SPEC_FIELDS, "probes"], "spec", notes);
+	s = moveGenerators(s, notes);
+	if (Array.isArray(s.use)) s = { ...s, use: s.use.map((u, i) => fixUse(u, i, notes)) };
+	if (s.anchors) s = { ...s, anchors: fixAnchors(s.anchors, notes) };
+	if (Array.isArray(s.keys)) { const known = knownChannels(s); s = { ...s, keys: s.keys.map((k, i) => fixKey(k, i, known, notes)) }; }
+	if (plain(s.objects)) s = { ...s, objects: Object.fromEntries(Object.entries(s.objects).map(([id, o]) => [id, fixObject(id, o, notes)])) };
+	if (Array.isArray(s.goals)) s = { ...s, goals: s.goals.map((g, i) => fixGoal(g, i, notes)) };
+	if (Array.isArray(s.fits)) s = { ...s, fits: s.fits.map((f, i) => renameFields(f, FIT_FIELDS, `fits[${i}]`, notes)) };
+	if (s.checks) s = { ...s, checks: fixChecks(s.checks, notes) };
+	return notes.length > before ? s : spec;
+}
+
+/**
+ * fitWalks(spec, { sk, scene }, notes, refusals) -> spec with each walkTo's fitted args (skills/basic.js fitTo) written
+ * into its use entry, so the stored spec walks where it says and compiles the same again; refusals gets one line per
+ * walk it cannot fit (the validator lists them with its own, pipeline.js). A spec that does not expand is left as it is.
+ */
+function fitWalks(spec, { sk, scene } = {}, notes = [], refusals = []) {
+	if (!plain(spec) || !Array.isArray(spec.use) || !spec.use.some(u => u?.skill === "walkTo" && plain(u.args) && u.args.to !== undefined)) return spec;
+	// a walk may end later freely only in a frames "auto" spec with nothing after it, else into frames nothing uses
+	// (skills/basic.js fitTo, roomAfter): busy lists the frames of the object keys, grabs and releases, last the take's last frame
+	const busy = Object.values(plain(spec.objects) ? spec.objects : {}).flatMap(o => (plain(o) ? [o.grab, o.release, ...(Array.isArray(o.keys) ? o.keys.map(k => k?.f) : [])] : [])).filter(Number.isFinite);
+	const expand = noStop => {
+		const fit = { refusals: [], stretch: spec.frames === "auto", busy, last: Number.isFinite(spec.frames) ? spec.frames - 1 : Infinity, noStop, stopped: new Set() };
+		try { return { used: expandUse({ ...spec, frames: 20000 }, { sk, scene, fit, auto: true }).used, fit }; } catch { return null; }
+	};
+	// a walk stopped before a body (walk-fit.js) moves where the next one starts: a stop is kept only while the spec has no
+	// more refusals than with every walk on its to (bench replay: 3 of 692 specs refused a later walk), the earliest first
+	let run = expand(new Set());
+	if (!run) return spec;
+	if (run.fit.stopped.size) {
+		const off = new Set(run.fit.stopped), onTo = expand(off);
+		if (onTo && onTo.fit.refusals.length < run.fit.refusals.length) {
+			for (const i of [...run.fit.stopped].sort((a, b) => a - b)) {
+				off.delete(i);
+				const t = expand(off);
+				if (!t || t.fit.refusals.length > onTo.fit.refusals.length) off.add(i);
+			}
+			run = expand(off) ?? onTo;
+		}
+	}
+	const { used, fit } = run;
+	refusals.push(...fit.refusals);
+	if (!used.some(u => u.adjust)) return spec;
+	for (const u of used) if (u.adjust) notes.push(`corrected: ${u.adjust.note}`);
+	return { ...spec, use: spec.use.map((u, i) => (used[i]?.adjust ? { ...u, args: { ...u.args, ...used[i].adjust.args } } : u)) };
+}
+
+/** prepareSpec(spec, { sk, scene }, notes, refusals): correctSpec, then fitWalks: the spec as it is stored and compiled. */
+export const prepareSpec = (spec, ctx, notes, refusals) => fitWalks(correctSpec(spec, notes), ctx, notes, refusals);

package/src/motion3/docs.js

@@ -2,14 +2,16 @@
 // Lane P owns the wording; the code only reads these constants. The procedure lives in the Studio
 // system prompt and the field tables in motion.describe, so these strings say only what each action takes and answers.
 export const MOTION_ACTION_HELP = {
-	compile: "Bake a spec on the character's rig and run QA. install: true installs (default), false or \"never\" changes nothing, \"ifClean\" only if the final qa.ok; output.installed tells. "
+	compile: "Bake a spec on the character's rig and run QA. install: true installs (default), false or \"never\" changes nothing, \"ifClean\" only if the final qa.ok. "
 		+ "Send spec, or base (an answered specId) + optional patch (JSON Patch); base alone or patch: [] re-measures (new probes). "
-		+ "spec = { schema: \"cozyclay.motion-spec.v1\", fps: 24, frames (number or \"auto\"), ... } (parts: motion.describe); any number may be { range: [lo, hi] } (searched). "
-		+ "probes (at most 16, request level; spec.probes: measured, not stored): { name, distance: [ref, ref] | position: ref, frames, every? }. "
-		+ "Refs need a prefix (joint: prop: anchor: landmark: object: person:; goals[].moved: a bare id too) and take loose bone names (any case); spec.checks need exact ones. "
+		+ "Address array items by field, not index: /keys/@f=120/set/hand_l (add creates the key at f120), remove /keys/@f=120, { op: \"move\", from: \"/keys/@f=120\", path: \"/keys/@f=132\" }, "
+		+ "/use/@skill=reach&f0=40, /goals/@name=<name>, /objects/<id>/keys/@f=40. "
+		+ "spec = { schema: \"cozyclay.motion-spec.v1\", fps: 24, frames (number or \"auto\"), ... }; any number may be { range: [lo, hi] } (searched). "
+		+ "probes (at most 16; spec.probes too, never stored): { name, distance: [ref, ref] | position: ref, frames, every? }. "
+		+ "Refs need a prefix (joint: prop: anchor: landmark: object: person:; goals[].moved: a bare id too) and take loose bone names; spec.checks need exact ones. "
 		+ "repair: { rounds } (1-8, default 4) applies group patches while severity drops. "
-		+ "qa judges only what is broken; speed, acceleration, balance, knee bend are observations unless checks.limits names them. "
-		+ "Answers frames, installed, specId, qa { ok, total, goals, groups (GOAL first, then severity; cause, hint, patch?) }, observations, delta (with base), repair, probes, timeline, fixed, search, skills. output.more: motion.report pages the rest.",
+		+ "qa judges only what is broken; speed, balance and bends are observations unless checks.limits names them. "
+		+ "Answers brief (qa, misses, top groups: a script returns it as is), frames, installed, stuck (when to stop), specId, qa { ok, total, goals, groups (GOAL first, then severity; cause, hint, repair patch?) }, observations (asked: skill ends, contacts, goal points), delta (with base), repair, probes, timeline, fixed, search, skills. more: motion.report pages the rest.",
 	qa: "Measure the character's installed take again against the scene as it is now (objects may have moved). Optional checks replace the spec's checks and its skills' checks. "
 		+ "Answers specId and qa as motion.compile does (goals, ranked groups with cause, hint and patch); output.more pages with motion.report. Changes nothing.",
 	sample: "World positions (metres) of named bones of the installed take at up to 64 frames. Bone names may be loose (any case, a mixamorig: prefix, aliases such as hips or hand_l); an unknown one answers a did-you-mean. "

package/src/motion3/face-lean.js

@@ -0,0 +1,31 @@
+// A held object brought to the face leans by default (lane arm). An aim key at the lips without lean or roll (a cup
+// tipped to the mouth) is held as the aim asks only with the elbow out to the side and over the shoulder: the grip the
+// reach took on the table turns the hand with the cup, and the wrist cannot take the rest (the agents' first compiles of
+// bench S6 and S8: the upper arm past 110 deg from hanging on 31 of 56, the elbow over the head on 17). Leaning the aim
+// toward the hand's side lets the elbow stay down (key-aim.js lean); the agent wrote lean on few of those keys and
+// re-keyed the elbows after QA had passed. So such a key leans FACE_LEAN deg (the most lean takes) unless it gives lean
+// or roll: its top (the rim) within FACE_NEAR m of the mouth at its frame, on the pose without the keys, on a body at
+// most SIP m tall (a cup, a can, a bottle: a bat's knob at the shoulder in a batting stance is not a sip, and a group's
+// height is unknown here); the rim stays where aim put it (leanPos). On the 84 first compiles of bench S6, S8 and S10 the agents wrote, the frames of BODY went
+// from 7231 to 5526, of FACE from 1102 to 839 and of WRIST from 1212 to 1007, and the takes with an elbow over the
+// shoulder (qa/arm-checks.js) from 39 to 31; the mouth goals missed on 694 frames instead of 623 (lean 35 within 0.2 m
+// saved fewer BODY and FACE frames and lost 46 mouth frames).
+import { add, scale, norm, dist } from "./compiler/math.js";
+
+export const FACE_LEAN = 45;
+const FACE_NEAR = 0.25, SIP = 0.3;
+/**
+ * Entry o of a body `top` m tall (0: a group) with FACE_LEAN on its aim keys (no lean, no roll) whose top (`top` m up
+ * the aim from pos) is within FACE_NEAR of the mouth at their frame; mouthAt(f) the mouth on the pose without the
+ * keys. o itself when none is, or the body is no sip (SIP).
+ */
+export function faceLeaned(o, top, mouthAt) {
+	if (!(top > 0 && top <= SIP)) return o;
+	let any = false;
+	const keys = o.keys.map(k => {
+		if (!k.aim || k.lean !== undefined || k.roll !== undefined || !(dist(add(k.pos, scale(norm(k.aim), top)), mouthAt(k.f)) < FACE_NEAR)) return k;
+		any = true;
+		return { ...k, lean: FACE_LEAN, leaned: true };
+	});
+	return any ? { ...o, keys } : o;
+}

package/src/motion3/fix/index.js

@@ -4,7 +4,9 @@
 //
 // spec.fix = { reach: true, slide: true, penetration: 0.02, self: true, retime: false } (false = all off)
 //   reach        wrist targets past the arm's reach go onto it through a soft knee (no snap);
-//                ankle targets past the leg's reach lower the hips just enough, eased in and out
+//                ankle targets past the leg's reach lower the hips just enough, eased in and out; a hand
+//                on a pinned target (a world or a scene object's anchor) that the straight arm misses brings
+//                the body to it: lean, hip shift, lower hips, the feet kept (reach-body.js, fixed.reachBody)
 //   slide        a sole under the floor lifts its ankle onto it (ground.js); a planted heel or ball
 //                that drifts less than 1 cm stays put, and a foot turning on its planted ball (heel
 //                up) or heel pivots about it whatever the drift; a flat planted foot (heel and ball
@@ -19,6 +21,7 @@
 //   grasp        a holding hand's fingers close on what it holds and the object rests in the hand (#816);
 //                false keeps the preset grip and the grab-frame offset
 import { lowerHips, armReach } from "./reach.js";
+import { reachBody } from "./reach-body.js";
 import { lockFeet } from "./slide.js";
 import { holdTurns } from "./turn.js";
 import { liftSoles } from "./ground.js";
@@ -46,6 +49,7 @@ export function applyFixes(out, fix, engine, { whole = true } = {}) {
 	if (fix.retime && whole) put("retime", retime(out, engine));
 	if (fix.slide) put("ground", liftSoles(out, engine));
 	if (fix.reach) put("reachLegs", lowerHips(out, engine));
+	if (fix.reach) put("reachBody", reachBody(out, engine));
 	if (fix.slide) put("slide", withTurns(holdTurns(out, engine), lockFeet(out, engine)));
 	// a pivot can hold a foot past the leg's reach: the hips go down for those frames too
 	if (fix.reach && fixed.slide?.pivots) put("reachLegs", mergeReach(fixed.reachLegs, lowerHips(out, engine)));

package/src/motion3/fix/reach-body.js

@@ -0,0 +1,172 @@
+// Reach by the body (spec.fix.reach): a hand on a pinned target (a world anchor, or an anchor on a scene object no
+// hand carries, at half weight or more) that the straight arm misses by more than QA's reach limit brings the body to
+// it instead of leaving REACH to the agent. Over each run of such frames the body leans toward the target (spine_pitch
+// forward, only for a target ahead and not above the shoulder), the hips shift toward it and, for a low target, go
+// down: one amount t in (0, 1] of LEAN deg, SHIFT m and DROP m, the least that brings the hand within GOOD m at the
+// run's worst frame (one the hand is fully on) with the elbow still bent (the target within BENT of the arm's reach),
+// eased in and out over EASE frames and following the weights that take the hand there (armw and the anchor's). The feet stay on their keyed targets (the
+// legs' IK takes the hips; fix.slide holds them after), so a contact keyed elsewhere does not move: a t is refused
+// when it puts a leg past its reach, takes the other hand, on its own target, further off it, or puts the body deeper
+// into the scene's bodies (QA's capsules against the boxes there: a lean into the machine the hand reaches into). The
+// whole move is undone when it adds a one-frame pop (QA's own detector) where it eases in or out, or when the misses
+// over the run do not drop. A run goes on for up to EASE frames while the hand stays short (it takes the object from
+// there). One pass, each run once, a run's amount scaled down by what an earlier run already added at its worst frame
+// (both hands on one box), so it cannot cascade. Reported as fixed.reachBody: per run the side, frames, lean (deg),
+// shift [x, z] (m), drop (m) and the worst miss where the hand is fully on, before -> after (the larger of a fit's
+// effector to the target and the wrist's). Sessions: REACH arm_miss_l 66 times, the agent moving the root by hand.
+import { sub, len, norm, dot } from "../compiler/math.js";
+import { SIDES } from "../compiler/pose.js";
+import { resolveAnchor, armReach } from "../compiler/anchors.js";
+import { round4 } from "./ease.js";
+import { CAPSULES, segPoints, sdBox } from "../qa/geometry.js";
+import { QA_LIMITS } from "../qa/checks.js";
+import { popChecks } from "../qa/style.js";
+
+const GOOD = 0.01, BENT = 0.97, LEAN = 25, SHIFT = 0.08, DROP = 0.15, EASE = 10, GAP = 2, SLACK = 0.002, TRIES = [0.25, 0.5, 0.75, 1];
+const smooth = x => x * x * (3 - 2 * x);
+
+/** The anchor that leads hand k at frame f when it is pinned (world, or a scene object no hand carries), else null. */
+function pinned(ctx, c, k, f) {
+	if (!(c[`armw_${k}`] >= 0.5)) return null;
+	let best = null;
+	for (const [ch, w] of Object.entries(c)) {
+		const m = /^w_(.+)_([lr])$/.exec(ch);
+		if (m && m[2] === k && w >= 0.5 && (!best || w > best.w)) best = { w, name: m[1] };
+	}
+	const a = best && ctx.spec.anchors?.[best.name];
+	return a && (a.kind === "world" || (a.kind === "object" && !ctx.objectHand?.(a.object, f))) ? best.name : null;
+}
+
+/** How deep the body is in the scene at frame f (the sum over QA's capsules), m; the reaching hand against the object it reaches for is left out. */
+function depthIn(out, f, k, object) {
+	const { s } = out.frames[f - out.f0], I = out.ctx.sk.index, scene = out.ctx.scene?.objects ?? {};
+	const boxes = Object.entries(out.objectsAt(f - out.f0) ?? {}).filter(([, b]) => b.half && !b.ignore);
+	const target = id => object !== undefined && (id === object || scene[id]?.ancestors?.includes(object));
+	let sum = 0;
+	for (const [part, a, b, r] of CAPSULES) {
+		if (I[a] === undefined || I[b] === undefined) continue;
+		const pts = segPoints(s.P[I[a]], s.P[I[b]], 5);
+		for (const [id, box] of boxes) if (!(part === `hand_${k}` && target(id))) sum += Math.max(0, r - Math.min(...pts.map(p => sdBox(p, box))));
+	}
+	return sum;
+}
+
+/** QA's one-frame pops (qa/style.js popChecks) over a run of frames: their summed excess past the floor. */
+function popsIn(sk, frames, L) {
+	let sum = 0;
+	popChecks(sk, { frames }, L, (kind, msg, f, value, limit) => { sum += value - limit; });
+	return sum;
+}
+
+/** The point a fit's effector names: a prop point, or the joints' middle. */
+function effector(sk, s, diag, eff) {
+	if (eff?.prop) return diag.props?.[eff.prop]?.[eff.point] ?? null;
+	const js = eff?.joints ?? ["RightHandIndex2", "RightHandMiddle2"], ps = js.map(j => s.P[sk.index[j]]).filter(Boolean);
+	return ps.length ? ps.reduce((m, p) => m.map((x, i) => x + p[i] / ps.length), [0, 0, 0]) : null;
+}
+
+/** Runs [a, b] (absolute frames) where hand k misses a pinned target by more than limit (gaps of GAP frames merge). */
+function runsOf(out, k, limit) {
+	const runs = [];
+	out.frames.forEach((fr, i) => {
+		const f = out.f0 + i;
+		if (!(fr.diag[`arm_miss_${k}`] > limit) || fr.diag[`arm_fold_${k}`] || !pinned(out.ctx, fr.c, k, f)) return;
+		const last = runs.at(-1);
+		if (last && f - last[1] <= GAP + 1) last[1] = f; else runs.push([f, f]);
+	});
+	// the hand is still short right after (it takes the object from there): the run goes on, up to EASE frames more
+	const short = f => f >= out.f0 && f < out.f0 + out.frames.length && out.frames[f - out.f0].diag[`arm_miss_${k}`] > limit && !out.frames[f - out.f0].diag[`arm_fold_${k}`];
+	for (const r of runs) for (let i = 0; i < EASE && short(r[1] + 1); i++) r[1] += 1;
+	return runs;
+}
+
+export function reachBody(out, engine) {
+	const { ctx } = out, { sk } = ctx, I = sk.index, n = out.frameCount, baked = out.baked;
+	const limit = ctx.spec.checks?.limits?.reach ?? 0.01, at = f => out.frames[f - out.f0];
+	const lo = out.f0, hi = out.f0 + out.frames.length - 1, report = [];
+	// what this fix added per frame, so overlapping runs (both hands) stay within one full amount
+	const added = { pitch: new Float64Array(n), move: new Float64Array(n) }, made = [];
+	for (const k of ["r", "l"]) for (const [a, b] of runsOf(out, k, limit)) {
+		// the target is the anchor's point (a fit winds the wrist target past it, so the miss does not say where it is);
+		// the run's worst frame is where it is farthest from the shoulder
+		const sh = f => at(f).s.P[I[`${SIDES[k]}Arm`]], target = f => { const { s, diag, c } = at(f), name = pinned(ctx, c, k, f); return name ? resolveAnchor(ctx, name, s, { ...diag, frame: f }, c) : null; };
+		// measured where the hand is fully on it (armw and the anchor's weight at 1) when the run has such frames: before, it is still on its way
+		const full = f => at(f).c[`armw_${k}`] >= 0.99 && at(f).c[`w_${pinned(ctx, at(f).c, k, f)}_${k}`] >= 0.99;
+		const span = Array.from({ length: b - a + 1 }, (_, i) => a + i), pick = span.some(full) ? span.filter(full) : span;
+		let fw = -1, T = null;
+		for (const f of pick) { const q = target(f); if (q && (!T || len(sub(q, sh(f))) > len(sub(T, sh(fw))))) { fw = f; T = q; } }
+		if (!T) continue;
+		const { s, diag, c } = at(fw), other = k === "l" ? "r" : "l";
+		const fit = (ctx.spec.fits ?? []).find(ft => ft.side === k && ft.anchor === pinned(ctx, c, k, fw)), eff = fit && effector(sk, s, diag, fit.effector);
+		const miss0 = Math.max(eff ? len(sub(eff, T)) : 0, diag[`arm_miss_${k}`] ?? 0);
+		// what the arm reaches with: the straight arm, and the effector's offset from the wrist when a fit names one
+		const reach = armReach(sk, k) + (eff ? len(sub(eff, s.P[I[`${SIDES[k]}Hand`]])) : 0);
+		const S = sh(fw), yaw = (c.yaw ?? 0) * Math.PI / 180, fwd = [Math.sin(yaw), 0, Math.cos(yaw)];
+		const flat = [T[0] - S[0], 0, T[2] - S[2]], hd = len(flat) > 1e-3 ? norm(flat) : fwd;
+		const lean = dot(hd, fwd) > 0.3 && T[1] < S[1] + 0.1 ? LEAN : 0, drop = DROP * Math.min(1, Math.max(0, (S[1] - T[1] - 0.2) / 0.4));
+		const free = Math.max(0, 1 - Math.max(added.pitch[fw] / LEAN, added.move[fw] / SHIFT));
+		if (!free) continue;
+		if (!baked.root) { baked.root = Array.from({ length: n }, () => sk.restWorldPos[I.Hips].slice()); made.push("root"); }
+		if (!baked.spine_pitch) { baked.spine_pitch = new Array(n).fill(0); made.push("spine_pitch"); }
+		const root0 = baked.root.map(r => r.slice()), pitch0 = baked.spine_pitch.slice();
+		const set = (f, t) => {
+			baked.root[f] = [root0[f][0] + hd[0] * SHIFT * t, root0[f][1] - drop * t, root0[f][2] + hd[2] * SHIFT * t];
+			baked.spine_pitch[f] = pitch0[f] + lean * t;
+		};
+		const legOk = (d, d0) => ["l", "r"].every(q => !((d[`leg_miss_${q}`] ?? 0) > Math.max(d0[`leg_miss_${q}`] ?? 0, 5e-4) + SLACK));
+		const otherOk = (d, d0) => !(at(fw).c[`armw_${other}`] > 0.5) || (d[`arm_miss_${other}`] ?? 0) <= (d0[`arm_miss_${other}`] ?? 0) + SLACK;
+		const object = ctx.spec.anchors[pinned(ctx, c, k, fw)]?.object, saved = at(fw), depth0 = depthIn(out, fw, k, object);
+		const trial = t => {
+			set(fw, t);
+			engine.solve([fw]);
+			// enough: the target within BENT of the arm's reach, so the elbow stays a little bent (a straight arm pops as it locks)
+			// the miss: a fit's effector to the target (the wrist reaches a soft-clamped target, fix.reach), else the wrist's
+			// (and the wrist's own miss too: a fit's target wound past a straight arm is what QA reads as REACH)
+			const { s: s1, diag: d } = at(fw), e1 = fit && effector(sk, s1, d, fit.effector), miss = Math.max(e1 ? len(sub(e1, T)) : 0, d[`arm_miss_${k}`] ?? 0);
+			const r = { t, miss, ok: legOk(d, diag) && otherOk(d, diag) && depthIn(out, fw, k, object) <= depth0 + SLACK, bent: len(sub(T, sh(fw))) <= BENT * reach };
+			baked.root[fw] = root0[fw]; baked.spine_pitch[fw] = pitch0[fw];
+			out.frames[fw - out.f0] = saved;
+			return r;
+		};
+		let best = null, prev = 0;
+		for (const t of TRIES.map(x => x * free)) {
+			const r = trial(t);
+			if (!r.ok) break;
+			if (!best || r.miss < best.miss) best = r;
+			if (r.miss <= GOOD && r.bent) {
+				// the least amount that is enough
+				let x = prev, y = t;
+				for (let it = 0; it < 4; it++) { const m = trial((x + y) / 2); if (m.ok && m.miss <= GOOD && m.bent) { y = m.t; best = m; } else x = m.t; }
+				break;
+			}
+			prev = t;
+		}
+		if (!best || !(best.miss < miss0 - GOOD)) continue;
+		// the body comes as the hand does, by the weights that take it to the target (the reach's own timing: a torso leaning
+		// over an arm still hanging swings it into the hips, and one leaning early changes the reach's speed profile)
+		const w01 = (ch, f) => Math.min(1, Math.max(0, baked[ch]?.[f] ?? 1)), name = pinned(ctx, c, k, fw);
+		const touched = [], weightAt = f => w01(`armw_${k}`, f) * w01(`w_${name}_${k}`, f) * (f >= a && f <= b ? 1 : smooth(1 - (f < a ? a - f : f - b) / (EASE + 1)));
+		for (let f = Math.max(lo, a - EASE); f <= Math.min(hi, b + EASE); f++) { set(f, best.t * weightAt(f)); touched.push(f); }
+		const before = touched.map(f => at(f)), depthBefore = touched.map(f => depthIn(out, f, k, object));
+		engine.solve(touched);
+		// kept when QA's reach (the wrist's misses over the run) and the worst miss where the hand is fully on drop, and no leg or other hand lost its target
+		const was = f => before[f - touched[0]], gapAt = (fr, f) => { const q = target(f), e = fit && q && effector(sk, fr.s, fr.diag, fit.effector); return Math.max(e ? len(sub(e, q)) : 0, fr.diag[`arm_miss_${k}`] ?? 0); };
+		const sumOf = get => span.reduce((m, f) => m + (get(f).diag[`arm_miss_${k}`] ?? 0), 0), worstOf = get => Math.max(...pick.map(f => gapAt(get(f), f)));
+		const depths = touched.map(f => depthIn(out, f, k, object)), L = { ...QA_LIMITS, ...ctx.spec.checks?.limits };
+		// the frames around the move, as they were and as they are: the move may not add a pop where it eases in or out
+		const near = Array.from({ length: Math.min(hi, touched.at(-1) + 3) - Math.max(lo, touched[0] - 3) + 1 }, (_, i) => Math.max(lo, touched[0] - 3) + i);
+		const popped = popsIn(sk, near.map(f => at(f)), L) > popsIn(sk, near.map(f => (f >= touched[0] && f <= touched.at(-1) ? before[f - touched[0]] : at(f))), L) + 1e-4;
+		const legsHeld = touched.every((f, i) => legOk(at(f).diag, before[i].diag) && otherOk(at(f).diag, before[i].diag) && depths[i] <= depthBefore[i] + SLACK);
+		const worst0 = worstOf(was), worst1 = worstOf(at);
+		if (!legsHeld || popped || !(sumOf(at) < sumOf(was) - 1e-6) || !(worst1 < worst0 - GOOD / 2)) {
+			for (const f of touched) { baked.root[f] = root0[f]; baked.spine_pitch[f] = pitch0[f]; }
+			touched.forEach((f, i) => { out.frames[f - out.f0] = before[i]; });
+			continue;
+		}
+		for (const f of touched) { added.pitch[f] += lean * best.t * weightAt(f); added.move[f] += SHIFT * best.t * weightAt(f); }
+		report.push({ side: k, frames: [a, b], lean: round4(lean * best.t), shift: [round4(hd[0] * SHIFT * best.t), round4(hd[2] * SHIFT * best.t)], drop: round4(drop * best.t), miss: [round4(worst0), round4(worst1)] });
+	}
+	// a channel this fix made for a move it undid goes again
+	if (!report.length) for (const ch of made) delete baked[ch];
+	return report.length ? { runs: report, how: "an out-of-reach hand on a pinned target: the body leaned (spine_pitch deg), shifted its hips (x, z m) and lowered them (m) toward it, eased in and out; the feet kept their targets" } : null;
+}

package/src/motion3/hint-check.js

@@ -0,0 +1,44 @@
+// C6. A hint's patch is offered only when it was compiled and helped. The logs: a patch applied as sent made the take
+// worse 49% of the time (better 40%), and the agent spent compiles finding that out. So the first CHECKED groups that
+// carry a patch (qa.groups order) each get one compile of the spec with their patch, and the patch stays on the group
+// only when its own group gets lower and qa/verdict.js compareQa calls the whole result better (no goal lost, no more
+// problems, nothing that got worse costs more than half of what got better); the group then says what it measured
+// (patchChecked). Otherwise the patch is taken off and patchTried says what it did; the hint's words stay. A patch past
+// the first CHECKED is not compiled and not offered. A spec repair or an earlier check already
+// compiled is not compiled again (`compile` may answer from its cache).
+import { applyPatch } from "./json-patch.js";
+import { groupKey } from "./qa/severity.js";
+import { compareQa, severityIn } from "./qa/verdict.js";
+
+const CHECKED = 2;
+const r2 = x => Math.round(x * 100) / 100;
+
+/**
+ * checkHints(spec, qa, compile) -> qa (its groups changed in place)
+ * @param {object} spec  the spec the patches address (qa's own)
+ * @param {object} qa  runMotionQa's answer for spec
+ * @param {(spec: object) => object} compile  spec -> its qa
+ */
+export function checkHints(spec, qa, compile) {
+	let n = 0;
+	for (const g of qa?.groups ?? []) {
+		if (!g.patch) continue;
+		if (n >= CHECKED) { delete g.patch; continue; }
+		n += 1;
+		const key = groupKey(g);
+		let next;
+		try { next = compile(applyPatch(spec, g.patch)); } catch (error) { next = { error: String(error?.message ?? error).slice(0, 160) }; }
+		const tried = g.patch.map(o => `${o.op} ${o.path}`).join(", "), patch = g.patch;
+		delete g.patch;
+		if (next?.error || !next?.groups) { g.patchTried = `${tried}: does not compile (${next?.error ?? "no QA"})`; continue; }
+		const own = [r2(severityIn(qa, key)), r2(severityIn(next, key))], v = compareQa(next, qa);
+		if (own[1] < own[0] && v.better) {
+			g.patch = patch;
+			g.patchChecked = { severity: own, total: v.sev, problems: v.problems };
+			continue;
+		}
+		const why = !(own[1] < own[0]) ? `this group ${own[0]} -> ${own[1]}` : v.why;
+		g.patchTried = `${tried}: compiled, did not help (${why}${why.startsWith("problems") ? "" : `; problems ${v.problems[0]} -> ${v.problems[1]}`})`;
+	}
+	return qa;
+}