[Bounty $5k] [Registry] Filter handlers by data locality — regional worker pools

[neuralmint]

Summary

Fixes #3933 — enforces data locality filtering during handler registration and resolution for regional worker pools.

Changes

• LocalityPolicy: defines valid regions, capacity limits, and type-to-region locking rules. Rejects invalid or policy-violating locality assignments with LocalityViolationError.
• LocalityResolver: maintains a locality→agent index and enforces invariant checks during lifecycle changes. On locality updates, the old cache entries are invalidated so stale entries are never served.
• AgentRegistry integration:
  • register() now accepts an optional locality parameter
  • list() supports locality filtering alongside existing status and group filters
  • delete() cleans up the locality index
  • update_agent_locality() enables re-assignment with full cache invalidation
• All decisions are logged via structured logging, and metric counters track registrations, updates, deletions, cache invalidations, and handler resolution counts.

Acceptance Criteria

• ✅ Deterministic regression test covers the regional worker pools trigger (see TestLocalityResolver, TestLocalityPolicy, TestAgentRegistryLocality)
• ✅ Registry locality resolver rejects invalid locality assignments and preserves correct lifecycle state
• ✅ Logs and metrics explain decisions without exposing private runtime data

Test Output

All 36 registry tests pass (8 original + 28 new locality tests):

tests/test_agent_registry.py (36 passed in 0.22s)

Also verified: test_config (5 passed), test_scheduler (5 passed).