feat(collision): shape-precise shielded-prism collision at the visible shell

[gradies]

What & why

#617 kept shielded prisms skimmable by keeping the primitive box trigger, but interaction happened at the bare prism size — the 3× visible shell was cosmetic. This delivers shape-precise interaction at the visible shell, without a mesh collider: the box trigger resizes to the shell AABB (no swap), and impact dispatch refines it to the true octahedron/stella via an analytic signed-margin gate. Reuses the on-branch ContainsPointLocal math, and fixes the two failure modes that sank the parallel tetrahedral-collider-cost branch — grazing skims rejected (a containment-only gate), and pop-then-destroy (a collider swap).

Per-system summary

• Shells (PrismOctahedronShield, PrismStellatedOctahedronShield) — implement the new IShieldContainmentGate: SignedMargin (octahedron L1 / stella 4-form, positive-inside) + SignedMarginSphere(centre, R) = SignedMargin(centre) + R·√((invA/sx)² + (invB/sy)² + (invC/sz)²) (sphere-vs-shell, conservative — never a dead zone). The shielded pose resizes the box to authoredSize × interactionShellScale (config knob, default = the 3× visual), publishes Prism.SetActiveShieldGate on settle, restores + clears on withdraw. Box is resize-only, never swapped/disabled (enabled stays owned by the spawn window / collider-LOD / destruction).
• IShieldContainmentGate (new) — SignedMargin / SignedMarginSphere / ContainsWorldPoint.
• Prism — ActiveShieldGate (server-private) + internal setter, cleared on reset / OnDisable.
• ImpactorBase — narrowphase at the OnTriggerEnter chokepoint: sphere touchers gate on SignedMarginSphere (world centre + world radius), others on a ClosestPoint point margin, both vs ShieldMarginThreshold (default 0 = "reaches the shell"). Contacts that enter the enlarged box outside the shell park and re-test on OnTriggerStay, and drop if their shell went null since parking — impactee-side (ActiveShieldGate == null) and self-side (HasOwnShieldGate) — closing the same-tick pop-then-destroy.
• SkimmerImpactor — dropped the _skimBand + threshold override; skim and pop unify at threshold 0 (the sphere radius supplies the grazing reach, so "pop in thin air" is gone). Stay/Exit call base first.
• Generators — SignedMarginLocal siblings to ContainsPointLocal.
• Docs — Docs/CollisionLOD/DESIGN.md (plan, exact contracts, the round-by-round findings, and the §6 editor checklist); CLAUDE.md shield row updated to the shipped mechanism.

Verification status

• Reviewed, not run. Three fable-5 adversarial rounds drove this — they caught and fixed: the impactee-side no-op probe, the pose force-enable fighting LOD, the pop-threshold conflation, the point-probe skim dead-zones, and the impactee-side same-tick race. The final round's verifiers hit the fable-5 usage limit, so the closing adversarial pass was manual (Opus) and caught one more — the self-side parked-drop. Compile verified by inspection.
• Not compiled in Unity and not play-tested here — collision feel/timing is not headless-verifiable. The editor pass is the gate (DESIGN.md §6):
  1. Rhino pops a shielded prism at the shell distance (~3×), not point-blank; a graze does not destroy the inner prism.
  2. Squirrel skims register while grazing the shell (not only center-punch); danger-skim energy still applies.
  3. Super-shielded (stella) — same two checks; watch the non-convex inter-spike gaps for skim dead-zones.
  4. LOD — fly away → shielded collider culls; fly back → restores.
  5. Profiler — Physics.SendEvents / *.AcceptImpactee at dense shielded mass.

Follow-ups

• One-swing pop+destroy left intentionally emergent (no bespoke post-pop grace): a swipe that reaches through a popped shell hits the prism; a graze pops only. If it should always take a second swing, add a small post-pop grace (noted in DESIGN.md §7.1).
• Base OnTriggerStay now delivers Stay callbacks to every impactor (previously only the skimmer). Cheap early-out when nothing is parked, but new per-frame callback volume on the prism hot path — profile Physics.SendEvents; if material, restrict Stay to impactors that actually park.
• Sphere margin is conservative across L1 octant / stella facet seams (fires slightly early — the safe direction); tune interactionShellScale per shell if reach feels off.
• The point / sphere LOD tiers are already realized (collider-LOD + PrismSpatialIndex for AOE); Phase 2 formalization is measure-first (DESIGN.md §4).

Collider / perf impact (ecology gate)

No new physics queries, no mesh colliders, one trigger per prism (unchanged), still collider-LOD-cullable. The shielded box grows to 3× (more broadphase over-cover → more candidate OnTrigger callbacks near a shielded prism), each resolved by a ~box-AABB analytic margin test. New per-frame cost: the base OnTriggerStay dispatch to all impactors (see Follow-ups).

🤖 Generated with Claude Code

---

Generated by Claude Code