Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

23.5 KB
Raw Blame
// @ts-check
// Automated quality gate for generated motion clips.
//
// The text-to-motion lane (workers/model-text2motion, reached through
// POST /api/forge-motion) samples a motion diffusion model, so its output is a
// distribution, not a guarantee: a prompt can come back frozen in bind pose,
// torn by a single-frame discontinuity, or "walking" with both feet skating
// across the floor. None of those may reach the public library, and none of
// them is visible from the clip's metadata. This module decides, from the clip
// JSON alone, whether a generated clip is good enough to publish beside the
// curated Mixamo catalog.
//
// It is deliberately deterministic and dependency-free: no GPU, no renderer,
// no model call. Every check is arithmetic over the keyframes, so the same
// verdict is reachable from the seeding cron, from the batch runner on a
// workstation, and from a unit test.
//
// The interesting check is FOOT SLIDE, and it is measured rather than guessed.
// src/animation-canonical-rest.js carries the reference rig completely: every
// canonical bone's world bind rotation, its world rest position, and its
// parent. That is enough to run forward kinematics on each frame of the clip
// and put the feet in world space, root translation included. A correct walk
// plants a foot and lets the world carry it backwards; a skating walk drags
// the planted foot. The gate measures the drift of each foot across the frames
// it is actually in contact with the ground and rejects on the worst span.
//
// Thresholds are calibrated against the curated library rather than invented:
// a generated clip is held to the standard the Mixamo clips already meet, so
// the gate can never reject motion that the platform itself ships. See
// scripts/gcp/calibrate-motion-gate.mjs, which replays this module over both
// catalogs and prints the distributions the bounds below are drawn from.

import {
	CANONICAL_PARENT,
	CANONICAL_REST_POSITION,
	CANONICAL_REST_WORLD,
} from '../../src/animation-canonical-rest.js';
import { worldMotionMetrics, footContactMetrics, loopSeamDistance } from './motion-seed.js';

export const MOTION_GATE_VERSION = 2;

/**
 * Every bound the gate enforces, in one frozen object so a caller (or a report)
 * can name the rule it tripped without reading the code.
 */
export const MOTION_BOUNDS = Object.freeze({
	// Structure.
	minDurationSeconds: 0.8,
	maxDurationSeconds: 12,
	minFrames: 12,
	maxFrames: 1800,
	minRotationTracks: 12,
	// How far the delivered clip may miss the requested length. The sampler
	// rounds to whole frames, so this is loose on purpose; it exists to catch a
	// lane that silently returned somebody else's clip.
	durationTolerance: 0.35,
	// A quaternion track whose keys are not unit length will be renormalised by
	// three.js and silently change the pose, so refuse it here instead.
	quatNormTolerance: 0.05,

	// Motion content.
	// Averaged angular speed across every rotation track. A clip below this is
	// standing in bind pose: technically valid, worthless in a library.
	minMeanAngularSpeedDeg: 5,
	// Largest single-frame WORLD step of a witness joint, over that joint's own
	// p95 step. Measured on local rotations instead, this test cannot work: the
	// sampler emits a 180 degree twist about a bone's own axis that the child
	// bone cancels, which is invisible on the mesh but maxes out any local
	// angular bound, and the authored library itself reaches 121 degrees in a
	// single frame. A local threshold therefore rejects real motion and genuine
	// tears alike (measured: 100% of generated clips and 66% of the authored
	// library). Judging joint POSITIONS separates them. Authored clips score a
	// median of 1.69 and a worst case of 5.79, so 6.5 leaves headroom.
	// See docs/animation-seeding.md.
	maxWorldStepRatio: 6.5,
	// Loop clips only: how far, in metres, a joint sits from where it started,
	// measured hips-relative in world space so a travelling loop still counts as
	// a loop. Measured on local rotations instead this reports a 178 degree seam
	// on a clip whose joints are 2.9 cm apart, because the twist flips the child
	// bone cancels land in that comparison too. Authored loops sit at 0.000 and a
	// generated clip run through closeLoopSeam() also lands at 0.000, while a raw
	// generated walk ends 0.25 m out.
	maxLoopSeamMetres: 0.08,

	// Space.
	// Planted-foot drift as a multiple of the stride the clip actually covers,
	// counting only frames where a foot is on this clip's own floor AND the hips
	// are upright over it. Without the upright test, floor work (a fall, a crawl,
	// a breakdance flair) reads as skating because the "lower" foot is merely the
	// one that happens to be less high.
	maxSlidePerStride: 0.85,
	// A foot below the ground plane by more than this (metres) is clipping
	// through the floor.
	maxGroundPenetration: 0.15,
	// Hips translation speed. The diffusion model occasionally launches the root.
	maxRootSpeedMetresPerSecond: 6,
});

/**
 * Bones a humanoid clip must drive to be worth publishing. Fingers are not
 * required: the text-to-motion lane emits a 22-joint SMPL body and the retarget
 * engine leaves unlisted bones at rest, which is correct.
 */
export const REQUIRED_BONES = Object.freeze([
	'Hips',
	'Spine',
	'Head',
	'LeftArm',
	'LeftForeArm',
	'RightArm',
	'RightForeArm',
	'LeftUpLeg',
	'LeftLeg',
	'LeftFoot',
	'RightUpLeg',
	'RightLeg',
	'RightFoot',
]);

// ── Quaternion / vector helpers ──────────────────────────────────────────────
// [x, y, z, w] throughout, matching three.js and the clip JSON.

function qMul(a, b) {
	const [ax, ay, az, aw] = a;
	const [bx, by, bz, bw] = b;
	return [
		aw * bx + ax * bw + ay * bz - az * by,
		aw * by - ax * bz + ay * bw + az * bx,
		aw * bz + ax * by - ay * bx + az * bw,
		aw * bw - ax * bx - ay * by - az * bz,
	];
}

function qConjugate(q) {
	return [-q[0], -q[1], -q[2], q[3]];
}

function qRotate(q, v) {
	// v' = q * (v, 0) * q⁻¹, expanded to avoid two full quaternion products.
	const [x, y, z, w] = q;
	const [vx, vy, vz] = v;
	const tx = 2 * (y * vz - z * vy);
	const ty = 2 * (z * vx - x * vz);
	const tz = 2 * (x * vy - y * vx);
	return [
		vx + w * tx + y * tz - z * ty,
		vy + w * ty + z * tx - x * tz,
		vz + w * tz + x * ty - y * tx,
	];
}

/** Shortest rotation angle between two unit quaternions, in degrees. */
function qAngleDeg(a, b) {
	const dot = Math.abs(a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]);
	return (2 * Math.acos(Math.min(1, dot)) * 180) / Math.PI;
}

function qNorm(q) {
	return Math.hypot(q[0], q[1], q[2], q[3]);
}

const IDENTITY_Q = [0, 0, 0, 1];

// ── Reference skeleton ───────────────────────────────────────────────────────

/**
 * Local rest offset of each bone in its parent's bind frame, derived once from
 * the reference rig. Forward kinematics needs the offset in the parent's local
 * space, while the generated table stores world rest positions, so each is
 * rotated back through the parent's world bind rotation.
 */
const LOCAL_REST_OFFSET = (() => {
	/** @type {Record<string, number[]>} */
	const out = {};
	for (const [bone, parent] of Object.entries(CANONICAL_PARENT)) {
		const here = CANONICAL_REST_POSITION[bone];
		if (!here) continue;
		if (!parent) {
			out[bone] = [...here];
			continue;
		}
		const up = CANONICAL_REST_POSITION[parent];
		if (!up) continue;
		const parentWorld = CANONICAL_REST_WORLD[parent] || IDENTITY_Q;
		out[bone] = qRotate(qConjugate(parentWorld), [
			here[0] - up[0],
			here[1] - up[1],
			here[2] - up[2],
		]);
	}
	return Object.freeze(out);
})();

/** Hip height of the reference rig, the scale every distance is reported in. */
export const REFERENCE_HIP_HEIGHT = CANONICAL_REST_POSITION.Hips?.[1] || 1;

/** Ground plane: the lowest rest point of the reference rig's feet. */
const REST_FLOOR_Y = Math.min(
	CANONICAL_REST_POSITION.LeftToeBase?.[1] ?? CANONICAL_REST_POSITION.LeftFoot?.[1] ?? 0,
	CANONICAL_REST_POSITION.RightToeBase?.[1] ?? CANONICAL_REST_POSITION.RightFoot?.[1] ?? 0,
);

// Walk the parents first so a single pass can compose world transforms.
const FK_ORDER = (() => {
	const seen = new Set();
	/** @type {string[]} */
	const order = [];
	const visit = (bone) => {
		if (seen.has(bone) || !(bone in CANONICAL_PARENT)) return;
		seen.add(bone);
		const parent = CANONICAL_PARENT[bone];
		if (parent) visit(parent);
		order.push(bone);
	};
	for (const bone of Object.keys(CANONICAL_PARENT)) visit(bone);
	return Object.freeze(order.filter((b) => LOCAL_REST_OFFSET[b]));
})();

// ── Clip parsing ─────────────────────────────────────────────────────────────

/**
 * A structural problem the gate could not look past: the clip is not a clip.
 * Thrown only by readClip; every quality verdict comes back as data.
 */
export class MotionClipShapeError extends Error {}

/**
 * Normalise a three.js AnimationClip JSON into the sampled form the checks
 * work on: one quaternion per bone per frame plus the root translation.
 *
 * The clip's tracks are keyframed independently, so the checks resample every
 * track onto the union of its own key times. The text-to-motion lane emits all
 * tracks on one uniform time base, and so does the Mixamo bake, so in practice
 * this is a straight read; the nearest-key lookup only matters for a clip
 * authored elsewhere.
 *
 * @param {unknown} raw
 * @returns {{ name: string, duration: number, frames: number, times: number[],
 *   rotations: Record<string, number[][]>, rootPositions: number[][] | null,
 *   trackNames: string[], rotationTrackCount: number }}
 */
export function readClip(raw) {
	if (!raw || typeof raw !== 'object') throw new MotionClipShapeError('clip is not an object');
	const clip = /** @type {any} */ (raw);
	const tracks = Array.isArray(clip.tracks) ? clip.tracks : null;
	if (!tracks || tracks.length === 0) throw new MotionClipShapeError('clip carries no tracks');

	/** @type {Record<string, number[][]>} */
	const rotations = {};
	/** @type {number[][] | null} */
	let rootPositions = null;
	/** @type {number[] | null} */
	let times = null;
	const trackNames = [];
	let rotationTrackCount = 0;

	for (const track of tracks) {
		const name = typeof track?.name === 'string' ? track.name : '';
		const keyTimes = Array.isArray(track?.times) ? track.times.map(Number) : null;
		const values = Array.isArray(track?.values) ? track.values.map(Number) : null;
		if (!name || !keyTimes || !values) {
			throw new MotionClipShapeError(`track ${name || '(unnamed)'} is missing times or values`);
		}
		trackNames.push(name);

		const [bone, property] = splitTrackName(name);
		const stride = property === 'quaternion' ? 4 : 3;
		if (values.length !== keyTimes.length * stride) {
			throw new MotionClipShapeError(
				`track ${name} has ${values.length} values for ${keyTimes.length} keys at stride ${stride}`,
			);
		}
		const framesHere = [];
		for (let i = 0; i < keyTimes.length; i++) {
			framesHere.push(values.slice(i * stride, i * stride + stride));
		}
		if (property === 'quaternion') {
			rotations[bone] = framesHere;
			rotationTrackCount++;
			if (!times || keyTimes.length > times.length) times = keyTimes;
		} else if (property === 'position' && bone === 'Hips') {
			rootPositions = framesHere;
			if (!times) times = keyTimes;
		}
	}

	if (!times || times.length === 0) throw new MotionClipShapeError('clip has no keyframe times');
	if (rotationTrackCount === 0) throw new MotionClipShapeError('clip drives no rotations');

	const duration = Number(clip.duration);
	return {
		name: typeof clip.name === 'string' ? clip.name : '',
		duration: Number.isFinite(duration) ? duration : times[times.length - 1],
		frames: times.length,
		times,
		rotations,
		rootPositions,
		trackNames,
		rotationTrackCount,
	};
}

function splitTrackName(name) {
	const dot = name.lastIndexOf('.');
	return dot < 0 ? [name, ''] : [name.slice(0, dot), name.slice(dot + 1)];
}

// ── Forward kinematics ───────────────────────────────────────────────────────

/**
 * Place every reference bone in world space for one frame of the clip.
 * Bones the clip does not drive keep their bind rotation, exactly as the
 * retarget engine leaves them.
 *
 * @param {ReturnType<typeof readClip>} clip
 * @param {number} frame
 * @returns {{ positions: Record<string, number[]>, rotations: Record<string, number[]> }}
 */
export function poseAtFrame(clip, frame) {
	/** @type {Record<string, number[]>} */
	const positions = {};
	/** @type {Record<string, number[]>} */
	const worldRotations = {};

	const root = clip.rootPositions?.[Math.min(frame, clip.rootPositions.length - 1)] || null;

	for (const bone of FK_ORDER) {
		const parent = CANONICAL_PARENT[bone];
		const track = clip.rotations[bone];
		const local = track ? track[Math.min(frame, track.length - 1)] : null;
		const localQ = local && local.length === 4 ? local : CANONICAL_REST_WORLD[bone] && !parent ? IDENTITY_Q : IDENTITY_Q;

		if (!parent) {
			worldRotations[bone] = localQ;
			// Hips.position is the clip's root track when present; otherwise the
			// character stands at its rest hip position.
			positions[bone] = root ? [...root] : [...CANONICAL_REST_POSITION[bone]];
			continue;
		}
		const parentQ = worldRotations[parent] || IDENTITY_Q;
		const parentP = positions[parent] || [0, 0, 0];
		const offset = qRotate(parentQ, LOCAL_REST_OFFSET[bone]);
		positions[bone] = [parentP[0] + offset[0], parentP[1] + offset[1], parentP[2] + offset[2]];
		worldRotations[bone] = qMul(parentQ, localQ);
	}
	return { positions, rotations: worldRotations };
}

/**
 * Foot trajectories in world space, one entry per frame.
 * @param {ReturnType<typeof readClip>} clip
 */
function footTrajectories(clip) {
	const left = [];
	const right = [];
	for (let f = 0; f < clip.frames; f++) {
		const { positions } = poseAtFrame(clip, f);
		left.push(positions.LeftToeBase || positions.LeftFoot || [0, 0, 0]);
		right.push(positions.RightToeBase || positions.RightFoot || [0, 0, 0]);
	}
	return { left, right };
}

/**
 * Worst horizontal drift of a foot while it is planted, in metres.
 *
 * "Planted" is the frames where the foot sits in the lowest band of its own
 * vertical range: a walk cycle's stance phase, an idle's whole timeline. Drift
 * is measured per contiguous span, so a foot that lifts, travels and lands
 * again is not charged for the step it legitimately took.
 *
 * @param {number[][]} trajectory
 * @param {number} contactBand  metres above the foot's own minimum that still counts as contact
 */
function worstPlantedDrift(trajectory, contactBand) {
	if (trajectory.length < 2) return 0;
	let minY = Infinity;
	for (const p of trajectory) minY = Math.min(minY, p[1]);
	const ceiling = minY + contactBand;

	let worst = 0;
	/** @type {number[] | null} */
	let spanStart = null;
	let spanDrift = 0;
	/** @type {number[] | null} */
	let previous = null;

	for (const p of trajectory) {
		if (p[1] <= ceiling) {
			if (!spanStart) {
				spanStart = p;
				spanDrift = 0;
			} else if (previous) {
				spanDrift += Math.hypot(p[0] - previous[0], p[2] - previous[2]);
			}
			previous = p;
		} else {
			if (spanStart) worst = Math.max(worst, spanDrift);
			spanStart = null;
			previous = null;
			spanDrift = 0;
		}
	}
	if (spanStart) worst = Math.max(worst, spanDrift);
	return worst;
}

// ── Measurement ──────────────────────────────────────────────────────────────

/**
 * Every number the gate decides on. Exported separately from the verdict so the
 * calibration script can print distributions across a whole catalog without
 * re-deriving them.
 *
 * @param {ReturnType<typeof readClip>} clip
 */
export function measureClip(clip) {
	const fps = clip.frames > 1 ? (clip.frames - 1) / Math.max(clip.duration, 1e-6) : 0;

	let nonFinite = 0;
	let worstQuatNormError = 0;
	let timeRegressions = 0;
	for (let i = 1; i < clip.times.length; i++) {
		if (!(clip.times[i] > clip.times[i - 1])) timeRegressions++;
	}
	for (const t of clip.times) if (!Number.isFinite(t)) nonFinite++;

	let angularStepSum = 0;
	let angularStepCount = 0;
	let maxFrameStepDeg = 0;
	for (const frames of Object.values(clip.rotations)) {
		for (const q of frames) {
			for (const c of q) if (!Number.isFinite(c)) nonFinite++;
			worstQuatNormError = Math.max(worstQuatNormError, Math.abs(qNorm(q) - 1));
		}
		for (let i = 1; i < frames.length; i++) {
			const step = qAngleDeg(frames[i - 1], frames[i]);
			if (!Number.isFinite(step)) {
				nonFinite++;
				continue;
			}
			angularStepSum += step;
			angularStepCount++;
			maxFrameStepDeg = Math.max(maxFrameStepDeg, step);
		}
	}
	const meanStepDeg = angularStepCount ? angularStepSum / angularStepCount : 0;
	const meanAngularSpeedDeg = meanStepDeg * (fps || 0);

	// Loop seam: how far the last frame's pose is from the first across all
	// driven bones. Reported for every clip; only enforced on loops.
	let seamDeg = 0;
	for (const frames of Object.values(clip.rotations)) {
		if (frames.length < 2) continue;
		seamDeg = Math.max(seamDeg, qAngleDeg(frames[0], frames[frames.length - 1]));
	}

	let rootSpeed = 0;
	let rootTravel = 0;
	if (clip.rootPositions && clip.rootPositions.length > 1) {
		for (let i = 1; i < clip.rootPositions.length; i++) {
			const a = clip.rootPositions[i - 1];
			const b = clip.rootPositions[i];
			for (const c of b) if (!Number.isFinite(c)) nonFinite++;
			const d = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
			rootTravel += d;
			rootSpeed = Math.max(rootSpeed, d * (fps || 0));
		}
	}

	const { left, right } = footTrajectories(clip);
	const contactBand = REFERENCE_HIP_HEIGHT * 0.06;
	const footSlide = Math.max(
		worstPlantedDrift(left, contactBand),
		worstPlantedDrift(right, contactBand),
	);
	let lowestFootY = Infinity;
	for (const p of left) lowestFootY = Math.min(lowestFootY, p[1]);
	for (const p of right) lowestFootY = Math.min(lowestFootY, p[1]);

	return {
		frames: clip.frames,
		duration: clip.duration,
		fps,
		rotationTracks: clip.rotationTrackCount,
		hasRootTrack: !!clip.rootPositions,
		nonFinite,
		timeRegressions,
		worstQuatNormError,
		meanAngularSpeedDeg,
		maxFrameStepDeg,
		loopSeamDeg: seamDeg,
		rootTravelMetres: rootTravel,
		maxRootSpeedMetresPerSecond: rootSpeed,
		footSlideMetres: footSlide,
		footSlideRatio: footSlide / REFERENCE_HIP_HEIGHT,
		groundPenetrationMetres: Math.max(0, REST_FLOOR_Y - lowestFootY),
		missingBones: REQUIRED_BONES.filter((b) => !clip.rotations[b]),
	};
}

// ── Verdict ──────────────────────────────────────────────────────────────────

/**
 * Turn measurements into an accept/reject decision. Pure and synchronous: the
 * cron, the batch runner and the tests all reach the same verdict for a clip.
 *
 * @param {ReturnType<typeof measureClip>} m
 * @param {{ loop?: boolean, requestedDuration?: number|null, bounds?: typeof MOTION_BOUNDS }} [opts]
 * @returns {{ pass: boolean, reasons: string[] }}
 */
export function decideMotionVerdict(m, opts = {}) {
	const b = opts.bounds || MOTION_BOUNDS;
	const reasons = [];

	if (m.nonFinite > 0) reasons.push('non_finite_keyframes');
	if (m.timeRegressions > 0) reasons.push('times_not_increasing');
	if (m.frames < b.minFrames) reasons.push('too_few_frames');
	if (m.frames > b.maxFrames) reasons.push('too_many_frames');
	if (!(m.duration >= b.minDurationSeconds)) reasons.push('duration_too_short');
	if (m.duration > b.maxDurationSeconds) reasons.push('duration_too_long');
	if (m.rotationTracks < b.minRotationTracks) reasons.push('too_few_rotation_tracks');
	if (m.worstQuatNormError > b.quatNormTolerance) reasons.push('quaternions_not_normalized');
	if (m.missingBones.length) reasons.push('missing_required_bones');
	if (m.meanAngularSpeedDeg < b.minMeanAngularSpeedDeg) reasons.push('motion_too_still');
	if (m.worldStepRatio > b.maxWorldStepRatio) reasons.push('frame_discontinuity');
	if (m.maxRootSpeedMetresPerSecond > b.maxRootSpeedMetresPerSecond) reasons.push('root_velocity_implausible');
	if (m.slidePerStride > b.maxSlidePerStride) reasons.push('foot_slide');
	if (m.groundPenetrationMetres > b.maxGroundPenetration) reasons.push('ground_penetration');
	if (opts.loop && m.loopSeamMetres > b.maxLoopSeamMetres) reasons.push('loop_seam_open');

	const requested = Number(opts.requestedDuration);
	if (Number.isFinite(requested) && requested > 0) {
		const drift = Math.abs(m.duration - requested) / requested;
		if (drift > b.durationTolerance) reasons.push('duration_off_request');
	}

	return { pass: reasons.length === 0, reasons };
}

/**
 * The whole gate: parse, measure, decide. A clip whose shape cannot be read is
 * a reject with the structural reason attached rather than a thrown error, so a
 * batch never dies on one malformed response.
 *
 * @param {unknown} raw  the clip JSON as served by the worker
 * @param {{ loop?: boolean, requestedDuration?: number|null, bounds?: typeof MOTION_BOUNDS }} [opts]
 */
export function gateMotionClip(raw, opts = {}) {
	let clip;
	try {
		clip = readClip(raw);
	} catch (err) {
		return {
			pass: false,
			reasons: ['unreadable_clip'],
			detail: err instanceof Error ? err.message : String(err),
			metrics: null,
			gateVersion: MOTION_GATE_VERSION,
		};
	}
	const metrics = measureClip(clip);
	// World-space smoothness, liveliness and foot contact, measured on the raw
	// clip by the shared forward-kinematics implementation in motion-seed.js.
	// These are what a viewer actually sees, so they carry the two rules that a
	// local-rotation measure gets wrong.
	const world = worldMotionMetrics(raw);
	const foot = footContactMetrics(raw);
	metrics.worldStepRatio = world.continuity;
	metrics.worldTravelMetres = world.travel;
	metrics.worstWitnessJoint = world.continuityJoint;
	metrics.slidePerStride = foot.slidePerStride;
	metrics.plantedFrames = foot.plantedFrames;
	metrics.loopSeamMetres = loopSeamDistance(raw);
	const { pass, reasons } = decideMotionVerdict(metrics, opts);
	return { pass, reasons, detail: '', metrics, gateVersion: MOTION_GATE_VERSION };
}

/** One human sentence per reason, for the reject sidecar and the batch report. */
export const MOTION_GATE_RULES = Object.freeze({
	unreadable_clip: 'the response was not a readable three.js AnimationClip',
	non_finite_keyframes: 'a keyframe carried NaN or Infinity',
	times_not_increasing: 'keyframe times did not advance monotonically',
	too_few_frames: 'too few keyframes to read as motion',
	too_many_frames: 'more keyframes than any library clip should carry',
	duration_too_short: 'shorter than the shortest useful library clip',
	duration_too_long: 'longer than the library ceiling',
	too_few_rotation_tracks: 'drives too few bones to animate a humanoid',
	quaternions_not_normalized: 'rotation keys are not unit quaternions',
	missing_required_bones: 'a required humanoid bone has no track',
	motion_too_still: 'the character barely moves; effectively a bind pose',
	frame_discontinuity: 'a single frame jumps further than a body can rotate',
	root_velocity_implausible: 'the root translates faster than a body can travel',
	foot_slide: 'a planted foot skates across the floor',
	ground_penetration: 'a foot sinks through the ground plane',
	loop_seam_open: 'the loop pops because the last frame does not meet the first',
	duration_off_request: 'the delivered length does not match what was requested',
});

/** @param {string[]} reasons */
export function explainMotionGate(reasons) {
	return reasons.map((r) => MOTION_GATE_RULES[r] || r);
}