feat: add native IK, retarget, and contact authoring

[alexkenley]

Stack

Depends on #896 at its final head, cb9d5a9ea4476510528f43218faf3ba44c7ecf25.

This branch contains the complete #896 stack plus the native IK/retarget/contact tranche (8d630a07) and its final FK contact-correctness fix (27a4fc38). Merge #896 first, then #897. Until #896 merges, GitHub's comparison for this PR includes the inherited #896 commits.

What changed

• Add UE 5.8 native configure_ik_rig authoring for retarget roots, root-motion bones, validated chains, goals, Full Body IK effectors/settings, and solver exclusions.
• Add UE 5.8 native configure_ik_retargeter authoring for the default op stack, per-op rig assignment, preview meshes, exact/fuzzy/manual mappings, named retarget poses, auto-alignment, offsets, and processor validation.
• Add generic contact_lock operations to the Control Rig transaction, including component-space targets, smooth boundary blends, optional driven bone/socket verification, and stabilizer controls.
• Expand typed IK Rig and Retargeter readers so agents can verify goals, solvers/effectors, exclusions, poses, ops, and per-op mappings without Python or reflection probes.
• Harden legacy retarget setup and batch retargeting with checked saves, no overwrite, strict input/skeleton/processor preflight, explicit partial mapping, and truthful rollback residuals.
• Document the reusable animation workflow and ship an agent skill for rig discovery, constraint authoring, immutable bake, and numeric V&V.
• Make a verified per-character Control Rig an explicit prerequisite before animation editing, with the same baseline gate in the live and editor-down tool surfaces, bundled skill, and guide.

Final-head contact correctness fix

UE skeletons can mark FK bones with TranslationRetargeting=Skeleton, which discards authored local translation offsets during evaluation. A translation-only contact edit could therefore appear to apply successfully while the evaluated bone never reached the target.

The final head detects that case and solves the contact through per-frame FK chain rotations derived with FABRIK, writes normalized local quaternion keys, and verifies the evaluated driven-bone residual after the solve. This prevents false-success contact reports on skeleton-retargeted FK chains.

The rotation-chain path deliberately requires a driven bone, Replace mode, and no stabilizer controls; unsupported combinations are rejected before mutation. Position-only contact targets preserve the source orientation.

Why

The previous surface could create shallow IK assets but could not round-trip solver goals, author the UE 5.8 retarget op stack/poses, or express and verify a generic contact constraint. Agents therefore had to guess from viewport output or use custom probes. This tranche makes those decisions native, typed, transactional, and numerically verifiable.

Transferability

The process is skeleton- and body-part-independent: discover the hierarchy/control types and reference transforms, express the desired motion as component-space anatomical/contact constraints, author normalized quaternion/scalar keys, bake to a new asset, and validate every affected and preserved bone numerically.

Rig mappings do not transfer blindly. Each skeleton still requires discovery of control/bone names, axes/signs, mirrored scale, joint limits, solver goals, translation-retargeting modes, and retarget chain mappings. The workflow and acceptance gates transfer; fixture-specific values do not.

Compatibility

• configure_ik_rig, configure_ik_retargeter, and contact_lock use UE 5.8 editor APIs and return errorCode=unsupported_engine_version on older engines. There is no silent raw-track or reflection fallback.
• Legacy IK Rig/Retargeter reads and existing actions retain their prior older-engine paths; richer typed state is emitted where the compiled engine exposes it.
• The new batch-retarget processor/skeleton validation is UE 5.8-gated.
• The plugin remains registered across the supported engine range so callers receive a structured compatibility response instead of an unknown action.

Live V&V (UE 5.8)

• Authored and persisted a structured IK Rig with retarget chains, goals, a connected FBIK solver, and solver exclusions.
• Authored and persisted the default retarget operation stack, per-op rig assignment, intentional partial mappings, and a named target pose.
• Retargeted motion between distinct humanoid skeleton fixtures while preserving frame rate, duration, numeric integrity, and loop continuity.
• Applied a fixed foot-contact constraint alongside an independent upper-body edit; measured contact drift remained below the configured tolerance while preserved chains remained at source.
• Confirmed required-solver-bone exclusions, export-text protected paths, and incompatible batch source skeletons are rejected before mutation with zero output assets.
• Reopened the fixture project and confirmed final IK, retarget, animation, and contact assets through native readback.

Checks

Final head: 27a4fc385b1b9399fc9bc4047f6f77fccecd63a8

• npm run test:unit: passed at the final head
• npx tsc --noEmit
• npm run audit:docs, audit:em-dash, and audit:unity
• editor-down and connected golden baselines
• UE 5.8 editor-module build
• UE 5.8 BuildPlugin package build
• clean consumer-project UE 5.8 build and persisted live readback
• GitHub build check is green at the final head

No Computer Use or execute_python is used by the implementation or workflow.