Contact IK stage pipeline: unify frame ordering, hoist constraints, terminal limb IK

[arkavo-com]

Replaces the two competing animation frame orderings — AnimationLayerCompositor layer priorities and CrowdFrameStepper's hand-rolled phase list — with one named stage pipeline, hoists VRM node-constraint solving onto the final pose, and makes limb IK terminal so it re-solves against a finalised scene root.

Design: docs/superpowers/specs/2026-08-04-contact-ik-pipeline-design.md
Plan: docs/superpowers/plans/2026-08-04-contact-ik-pipeline.md

The pipeline

S0 sample     clip sampling, root motion
S2a place     scripted placement (absolute root write)
S1 compose    postural yield
S2b displace  stagger shove (additive) → exits with root/hips final, transforms refreshed
S3 limbSolve  limb IK → capture step → arm counterbalance
S4 constrain  ConstraintSolver on the final pose

CrowdFrameStepper becomes the scheduler; ordering truth lives in PoseStage. Single-avatar is the n=1 case.

S2 runs in two beats, deliberately. Placement must precede S1 because the postural lean measures its own trunk endpoints in world space; the shove must follow S1 because its penetration signal is the lean-relieved one. One writer, two beats — collapsing them changes the depth signal.

Behaviour changes

• C2 — constraints now resolve on the posed skeleton rather than the raw animation, so twist bones follow the IK-modified wrist. AnimationPlayer.solvesConstraints defaults true, preserving the contract for the ~10 direct callers (validators, benchmarks, isolation suites); the pipeline sets it false.
• C3 — limb IK is terminal. IKLayer leaves the compositor and runs in S3.
• C4 — one redundant propagation removed. This is a structural cleanup, not a perf win: idle crowd members pay one extra hierarchy walk per frame (table in the commit body). The design's "five calls down to two" target was unreachable; the honest floor is seven, each with a verified downstream reader.

Bugfix found along the way (1a05396)

IKLayer.solveIKForLeg assigned TwoBoneIKSolver.solve's world-frame rotation directly as a bone-local rotation. VRM legs rest at roughly −Y, so the aim hit aimAt's antiparallel branch and produced a ~174.5° misrotation even for a trivial identity target.

All 24 existing IKLayerTests stayed green through it, because none applied solve output to a rig — they test TwoBoneIKSolver on synthetic input and IKLayer's metadata. Now pinned by IKLayerRoundTripTests (four cases asserting ankle world position, including a beyond-reach clamp). TwoBoneIKSolver's documentation, which called its output "local rotation for root joint", was the proximate cause and is corrected.

This is a pre-existing defect independent of the refactor and may deserve its own release note.

How the crowd path is gated

Baseline pose sequences were captured from unmodified code and committed before any source change (b160e57 touches zero Sources/ files; 1068da2 touches only Sources/). Every later commit compares against that committed fixture. Serialization is String(Float.bitPattern); regeneration sits behind PIPELINE_BASELINE_GENERATE=1 + XCTSkip, so a normal run cannot overwrite its own oracle. The fixture was never regenerated — it is still last touched by b160e57.

Matrix: {stagger-off, stagger-on-pre-contact, stagger-on-post-contact} × {single, crowd}, 60-frame sequences.

Invariants

Enforced by signature or assertion: cross-avatar reads come only from a FrozenSnapshot of the partner's last-committed frame; root and hips are written only in S2 (debug guard); S0 asserts it never silently samples root motion.

Documented but unenforced: every direct-apply bone has a guaranteed every-frame upstream writer; nothing before S4 reads constraint output.

Known gaps

• The test fixture authors zero VRM node constraints, so the byte-identity gate is structurally incapable of detecting a C2 regression. C2 rests on the synthetic-constraint tests in ConstraintHoistTests. A rig with authored VRMC_node_constraint twist bones would give real end-to-end coverage.
• AnimationLayerCompositor.addIKLayer is deprecated: IKLayer now returns absolute bone-local rotations, which the compositor's basePose * delta composition would double-apply on rigs with non-identity leg bind rotations.
• CrowdFrameStepper permanently sets solvesConstraints = false on caller-owned players and avatarsForCamera hands them back. Documented ownership transfer, not detectable at runtime.

Test status

Full suite: 1944 tests, 185 skipped, 2 failures. Both failures are assertions in SpringBoneStressPosePenetrationTests.testLookUp_augmented_noForeheadPenetration, which fails on main independent of this branch (augmented head penetration 0.0209 m vs coarse 0.0065 m). Nothing here can reach the spring-bone augmentor. Worth investigating separately — it is the invariant the #309/#321 augmentation work exists to protect.

Also unrelated and worth its own look: BalanceModelTests.testEvaluate_isReadOnlyAndDeterministic flakes with ~1e-9 differences. "Float noise" does not explain it — a pure function on an unmutated model should be bit-identical, so something is mutating the rig between calls.

🤖 Generated with Claude Code

https://claude.ai/code/session_016mm7Pvu34Ks8qdUZKDBSUu

[arkavo-com]

Folded in: the two red tests

1. testLookUp_augmented_noForeheadPenetration — fixed (e96467d, a89b929)

Bisected to PR #378, then isolated to a single function by disabling each new collider group one at a time — only SpringBoneBreastCollider.computeShoulderColliders mattered.

Mechanism, and it is not what the test name says. The worst penetrator was J_Sec_Hair4_03_end at (0.020, 1.294, 0.052) — a front hair strand sunk 21 mm into the décolletage, not the forehead. The two mesh-fitted shoulder spheres sat at x = ±0.117 with radius 0.081, so their medial edges reached x = ±0.036, leaving a ~7 cm gap across the front midline. Front hair was funnelled medially into that gap, where no collider exists.

The proximity filter |wp - upperOrigin| < armLen * 0.5 is a radius filter with no directional component, so collarbone-side vertices were included and dragged the fit inboard. The fix excludes vertices medial of the socket along the shoulder→upperArm axis before fitting.

worst 0.020938784 m → 0.0 m. #377's own suites stay green (27/27), so the shoulder coverage it added is intact. Baseline deltas are confined to the J_Sec_Hair4_* chain — the exact strand that was penetrating — max 23–39 mm per tier, mean 3–4 mm, 8–10 of 46 joints over 5 mm. Comparable to #377's ~22 mm precedent.

An earlier attempt to add coverage instead was built and reverted (archived on tag neck-attempt-archive). The pocket sits 80.6 mm from the neck axis, so a neck-anchored collider needed a 108 mm radius to reach it — against an authored neck collider of 43.1 mm and a mesh-measured neck of p95 47.2 mm. Every test passed and it visibly splayed the avatar's side hair horizontally. Removing the funnel beats chasing it with coverage.

2. BalanceModelTests.testEvaluate_isReadOnlyAndDeterministic — not reproducible, no fix

8 runs, zero failures: 5 isolated, plus 3 full parallel suites in which it executed every time. Not fixing what I cannot reproduce. The observation that "float noise" cannot explain nondeterminism in a pure function over an unmutated model still stands as worth investigating if it recurs — a captured diff would settle it.

Also added: a sizing guard (38f615e)

The regression was an instance of a pattern, not an incident. SpringBoneBoneGeometry.limbCapsule computes max(authoredHint, length * radiusFraction) — the rig's authored radius is a floor and never a ceiling, so any fraction constant that overshoots wins silently on every rig. Measured against authored colliders on two fixtures:

collider	A	U
handSphere	3.80×	3.02×
mesh-fitted shoulder (before this fix)	1.88×	1.76×
mesh-fitted shoulder (after)	1.66×	1.34×
augmentor shoulder sphere	1.53×	1.20×
lowerArm capsule	1.50×	1.28×

The families that do track the rig derive their size from an authored radius — headSkullSphere (1.0 × rHead), headBrowCapsule (0.5 × rHead), breastTwinSphere (a copy) — landing at exactly 1.00× / 0.50× / 1.00× on both bodies. That is the grounded pattern the others should follow.

ColliderDimensionAudit asserts synthetic ≤ 1.25× authored on the anchor bone, with known offenders pinned in a documented table so the debt cannot grow. An entry that drops below the ceiling on every rig fails as stale, so fixes retire their own exemptions. Verified non-vacuous.

The hand sphere at 3.0–3.8× is untouched and shipping since #321 — worth its own issue.

Test status

Full suite: 1945 tests, 185 skipped, 0 failures.

[arkavo-com]

Addressed the inline review comment on CrowdFrameStepper.swift:105 in 830867a.

The stepper now records each caller-supplied player's prior solvesConstraints and restores it in deinit, so the flag is borrowed for the stepper's lifetime rather than taken permanently. Restore returns the value found, so a player that already had solving disabled stays disabled — it does not force true.

PlayerOwnershipTests covers both directions. Verified non-vacuous: disabling the restore fails the deinit test.

Worth recording that this exact issue was raised three times — twice during task review, then here — and each time I answered it with a doc comment instead of a restore. Documentation doesn't help a host that never reads it. Good catch.

CI is green (Static checks, Compile, Gitar, both Xcode Cloud test actions) and the full local suite is 1947 tests / 0 failures.

[arkavo-com]

Pushed: two further sub-projects (830867a → f1e9b7c, 34 commits)

This PR now also carries the #381 work built on the pipeline:

Skin-mesh coverage oracle (test-only)

Penetration measured against the actual skinned body mesh instead of hand-authored capsules: closest-point-on-triangle with angle-weighted pseudonormal classification (Bærentzen–Aanæs), spatial grid with exhaustive-fallback (no distance cutoff at any layer), SKIN-only body predicate with pinned per-fixture inventories. Fixtures AvatarSample_U and AvatarSample_M bundled — licence fields verified from the files (allowRedistribution=true).

Opt-in cloth-collision fidelity — VRMLoadingOptions.fitClothCollisionToMesh (default false)

Two halves, both required: (A) each spring joint's collision radius floored at the measured half-extent of the mesh skinned to it (VRoid authors hitRadius at median 3.7 mm for cards centimetres wide; M's hair median rises to 18.6 mm; authored values never mutated — effectiveHitRadius sits beside them), and (B) segment collision: three new Metal kernels collide the parent→child span, parent endpoint from a per-substep immutable snapshot, corrections single-writer to the child, t-scaled on interior spans and full-vector on anchor spans. The shipped collide kernels are textually untouched.

Flag-off is certified unchanged at three strengths: exact effective-value identity, a bit-exact 90-frame GPU baseline that survived the metallib recompile with zero divergence, and the per-tier regression CSVs (≤1 mm envelope).

Measured outcome on AvatarSample_M (skin-mesh oracle): worst Hair penetration 21.3 → 8.4 mm (armsCrossed), 26.6 → 8.4 mm (armsAtSides); each half alone is insufficient (11.1 / 16.0 mm), gated by an absolute <10 mm bound both halves are load-bearing for. Skirt was already clean and is guarded clean-stays-clean. GPU-timed spring-compute cost: 1.23–1.60× across M/U × ultra/extreme, against a ≤3× budget. Render evidence reviewed frame-by-frame (hair deflects around the raised forearm; hands rest on, not in, the skirt).

Final whole-branch review ran across both sub-projects; all findings fixed or batched into #383. Incidental discoveries filed: #382 (pre-existing phantom-velocity coast in applyVelocityCorrection, both copies noted).

Full suite on the pushed tree: 1990 tests, 190 skipped, 0 failures.

[gitar-bot]

Code Review ✅ Approved 3 resolved / 3 findings

Contact IK stage pipeline unifies frame ordering, hoists constraint solving onto final poses, and makes limb IK terminal. Addresses solvesConstraints configuration and inverseBindMatrices indexing safety, with no open findings.

✅ 3 resolved

✅ Edge Case: solvesConstraints permanently disabled on caller-owned players

📄 Sources/VRMMetalKit/Crowd/CrowdFrameStepper.swift:98-105 📄 Sources/VRMMetalKit/Crowd/CrowdFrameStepper.swift:157 📄 Sources/VRMMetalKit/Animation/Pipeline/PipelineAvatar.swift:59-73
Both CrowdFrameStepper.init (line 157) and PipelineAvatar.init (line 87) set player.solvesConstraints = false and never restore it. Because avatarsForCamera hands the same AnimationPlayer instances back to the host, any caller that later drives one of those players directly (outside the pipeline) will silently get a constraint-unsolved pose with no runtime signal. This is documented as an intentional ownership transfer, but it mutates externally-owned reference objects irreversibly; consider snapshotting/restoring the prior value on teardown or exposing an explicit re-enable path so reused players don't silently lose twist/aim constraint solving.

✅ Edge Case: Unguarded inverseBindMatrices indexing can crash on malformed skins

📄 Sources/VRMMetalKit/SpringBoneJointRadiusMeasure.swift:66
In SpringBoneJointRadiusMeasure.measure, skin.joints.indices.map { skin.joints[$0].worldMatrix * skin.inverseBindMatrices[$0] } indexes inverseBindMatrices by joint index. The loader fills identity matrices with count==joints.count when the glTF accessor is absent or errors, so normal files are safe, but a malformed accessor that decodes fewer matrices than joints would cause an out-of-bounds crash at load time (only when fitClothCollisionToMesh is on). RenderSafetyTests already guards this exact case defensively (jointIndex < skin.inverseBindMatrices.count); mirror that here. Note this matches an existing unguarded pattern in SpringBoneBreastCollider.swift.

✅ Edge Case: Mesh-to-node lookup ignores instanced meshes

📄 Sources/VRMMetalKit/SpringBoneJointRadiusMeasure.swift:62-69
model.nodes.first(where: { $0.mesh == mi }) resolves only the first node referencing a mesh, then uses that node's skin/palette for every vertex of the mesh. If the same mesh is instanced by multiple nodes with different skins, the measurement attributes all vertices to the first instance's skin, producing wrong world positions and radii. VRM rarely instances skinned meshes so impact is low, but the assumption is silent. Consider iterating nodes (not meshes) or asserting single-node ownership.

_{Was this helpful? React with 👍 / 👎 | Gitar}

[github-actions]

✅ Claude Code Review ran on 45a8d2e — result: success.

Findings (if any) are posted as inline comments; none means the review found nothing to flag. Run log.