feat(affinity): add arcane-affinity crate — interaction-weighted IClusteringModel

[rebelmachina]

Summary

Implements AffinityEngine (IN-08) — a stateful IClusteringModel that groups entities by observed interaction probability rather than pure spatial proximity. This is the hand-crafted baseline that sits between the current spatial-only RulesEngine and the future ML/RL clustering model.

Solves three known RulesEngine failure modes:

• Boundary thrashing — entities no longer oscillate on cluster boundaries; migration hysteresis (threshold + cooldown) prevents it
• Interaction blindness — party/guild/proximity signals group interacting entities together even across spatial boundaries
• No temporal awareness — interaction graph retains history (exponential decay) so a moving raid group isn't split mid-crossing

New crate: arcane-affinity

Module	What it does
AffinityEngine	IClusteringModel impl — 7-phase evaluate() loop
InteractionGraph	Decaying pairwise weights between entities, with GC
MigrationState	Per-entity migration cooldowns
ClusterScorer	Interaction affinity + spatial tiebreaker scoring
AffinityConfig	All tunable parameters with sensible defaults

Algorithm (7 phases per evaluation tick):

1. Decay interaction weights + inject party/guild/proximity signals
2. Tick migration cooldowns
3. Build cluster membership and centroids from view
4. Score each entity, mark migrations above threshold and off cooldown
5. Spatial fallback for new entities
6. Clean up removed entities
7. Translate per-entity assignments into ClusterDecision (merge/split)

Integration changes in existing crates

• arcane-core — extend IClusteringModel with compute_entity_assignments() default method (zero breaking changes — RulesEngine requires no changes)
• arcane-spatial — add snapshot_entities() to expose entity-level data
• arcane-infra — ClusterManager::run_evaluation_cycle() now populates WorldStateView.players and ClusterInfo.player_ids (previously always empty; RulesEngine behavior unchanged)

Test plan

• cargo test -p arcane-affinity — 22 tests, all passing
• cargo build --workspace — full workspace green, no regressions
• Unit tests: InteractionGraph (7), MigrationState (5), ClusterScorer (4), AffinityEngine (5) — all modules covered
• Integration tests: valid assignments, validate_view, drop-in replacement

Closes

Closes #65, #66, #67, #68, #69, #70, #71, #72, #73
Part of epic #64

What's NOT in this PR (next steps)

• Add arcane-affinity as optional dependency in arcane-infra with model selection #74 — arcane-affinity optional dependency + model selection in arcane-infra (wire the feature flag so ClusterManager can be constructed with AffinityEngine)
• Unit tests for all arcane-affinity modules #75/Integration tests: raid group cohesion, oscillation prevention, spatial fallback #76 — extended integration tests (raid group cohesion, oscillation, boundary crossing)
• Decision execution — ClusterManager still discards decisions (_decisions); execution wiring is a separate epic

🤖 Generated with Claude Code

[martinjms]

🔴 Critical: fallback can bypass hysteresis checks

Why this matters

• A player can move clusters without passing threshold/cooldown logic.
• This lines up with the failing CI test for oscillation/hysteresis behavior.

Evidence

let mut new_assignments: HashMap<Uuid, Uuid> = assignments.clone();

if let std::collections::hash_map::Entry::Vacant(e) =
    new_assignments.entry(player.player_id)
{
    if let Some(cid) = nearest_cluster(player.position, &cluster_centroids) {
        e.insert(cid);
    }
}

Technical details

new_assignments is seeded from cache only.
If a player is missing in cache, Phase 5 fallback assigns nearest cluster directly, which can move an already-assigned player without going through Phase 4 migration gating (migration_threshold + cooldown).

Suggested shape:

• Seed from authoritative current assignment in view.players first.
• Only let Phase 4 change assignment when hysteresis checks pass.
• Keep Phase 5 only for truly unassigned/new entities.

[martinjms]

🟠 Required: make nearest_cluster tie-breaking deterministic

Why this matters

• Equal-distance cases can pick different clusters across runs.
• That makes behavior harder to reproduce and can create flaky tests.

Evidence

fn nearest_cluster(pos: Vec2, centroids: &HashMap<Uuid, Vec2>) -> Option<Uuid> {
    centroids
        .iter()
        .min_by(|(_, ca), (_, cb)| {
            let da = /* distance to ca */;
            let db = /* distance to cb */;
            da.partial_cmp(&db).unwrap_or(std::cmp::Ordering::Equal)
        })
        .map(|(&id, _)| id)
}

Technical details

When da == db, comparison returns Equal.
Since iteration is over a HashMap, tie resolution can depend on map iteration order.

Suggested shape:

• Add explicit tie-break (cluster_id ordering), or
• Evaluate centroids from a stable ordered collection before selecting min.

[rebelmachina]

Both review comments addressed in commit 0d1c7c1.

Comment 1 (critical — fallback bypasses hysteresis): Fixed. new_assignments is now seeded from view.players before Phase 4 runs:

let mut new_assignments: HashMap<Uuid, Uuid> = assignments.clone();
for player in players {
    new_assignments.entry(player.player_id).or_insert(player.cluster_id);
}

Entities that score below migration_threshold in Phase 4 are already in new_assignments with their current cluster, so Phase 5 never fires for them. Phase 5 is now a true last-resort for entities with no cluster assignment at all.

Comment 2 (required — non-deterministic tie-breaking): Fixed. nearest_cluster now uses .then_with(|| id_a.cmp(id_b)) as a stable UUID tie-break when distances are equal.

Test update: isolated_entity_uses_spatial_fallback updated to go through Phase 4 correctly — sets migration_threshold: 0.0 so any positive spatial improvement triggers migration, expressing the original intent without relying on the Phase 5 bypass.

hysteresis_prevents_boundary_oscillation (the CI failure) now passes. 25/25 tests green locally.