cozyclay 3.1.0 → 3.1.2

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

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