feat(routing): enforce regional affinity and region-lock policies

[nerdalert]

Summary

Add explicit, enforceable regional-affinity and region-lock policy semantics to
Grid-produced routing state.

Grid already carries region and zone metadata on GridSite, derives locality
tiers (same_site, same_zone, same_region, cross_region, and unknown),
and can use those tiers when ordering provider candidates. That is routing
input, not an enforcement guarantee.

This issue adds the missing distinction between:

• regional affinity: prefer eligible providers in the selected or ingress
  region, with cross-region fallback only when policy permits it; and
• region locking: exclude every provider outside the allowed region and
  fail closed when no allowed provider remains.

Until this work is complete and runtime-proven, regional affinity and locking
remain not currently demonstrated capabilities.

Motivation

Candidate ordering alone cannot satisfy data-residency or sovereignty
requirements. A lower-ranked cross-region candidate is still selectable when
preferred capacity becomes unhealthy, stale, draining, or unavailable.

Operators need a policy contract that clearly answers:

• Which region is preferred or required?
• Is cross-region fallback allowed?
• What happens when region metadata is missing or contradictory?
• Does the restriction apply to new sessions, existing sessions, or both?
• Why was a candidate preferred, excluded, or retained?

A hard region lock must be an eligibility boundary, not a scoring weight.

Relationship to Existing Work

• Issue feat(ingress): publish bounded edge availability for global traffic managers #9 publishes bounded edge readiness for an external global traffic
  manager. It does not implement provider-region policy or DNS selection.
• Issue feat(routing): harden metric-driven provider admission and selection #10 hardens general provider admission and ranking. Regional locking
  must run as an authorization/eligibility gate before that ranking stage.
• intelligent_route consumes the ordered and eligible candidates produced by
  Grid. Praxis should remain producer-neutral; it should not acquire a
  Grid-specific regional policy engine.

Scope

Define and implement a bounded policy contract for:

• affinity mode versus locked mode;
• preferred and allowed regions;
• explicit cross-region fallback behavior;
• conservative handling of missing or unknown region metadata;
• interaction with health, freshness, admission state, drain, and session
  affinity;
• behavior when an existing session's provider becomes disallowed;
• deterministic candidate filtering and ordering;
• per-gateway or per-route policy attachment without trusting arbitrary caller
  headers;
• propagation through the versioned routing-overlay contract; and
• bounded status, Events, metrics, and structured decision evidence.

The implementation must preserve these ordering boundaries:

1. Authentication, authorization, and hard regional constraints determine
   eligibility.
2. Health, freshness, and admission determine whether eligible providers can
   accept new or existing work.
3. Regional affinity influences ordering only after eligibility is established.
4. Other bounded scoring signals rank candidates within the permitted set.

Behavioral Requirements

• Locked mode must never emit or select a candidate outside the allowed region.
• Locked mode with no eligible in-region provider must fail closed; it must not
  silently degrade to cross-region routing.
• Affinity mode may use a cross-region candidate only when fallback is
  explicitly allowed.
• Missing region metadata must not bypass a lock.
• A caller-supplied region header must not override trusted policy by itself.
• Policy changes must produce a new semantic overlay revision and retain the
  normal accepted/serving revision evidence chain.
• Invalid policy updates must retain the last-known-good serving revision.
• Session behavior during policy changes, drain, and provider failure must be
  deterministic and documented.
• Metrics must use bounded mode, outcome, and reason labels; region names,
  request identifiers, and arbitrary policy values must not become metric
  labels.

Acceptance Criteria

• The API clearly distinguishes affinity from locking and validates bounded
  region policy values.
• Policy ownership and attachment are documented, including the trusted
  source of the request or workload region.
• Grid filters disallowed candidates before scoring in locked mode.
• Affinity ordering prefers the configured region and falls back only when
  explicitly permitted.
• Missing, unknown, malformed, and conflicting region metadata fail
  according to documented conservative rules.
• New-session and existing-session behavior is tested for affinity, lock,
  drain, failure, recovery, and policy changes.
• Each edge-local overlay contains only candidates permitted for that
  gateway and policy context.
• Runtime evidence proves a locked request never crosses regions when all
  in-region providers are unavailable.
• Runtime evidence proves affinity fallback succeeds when policy permits
  cross-region use.
• Invalid updates retain the last-known-good routing revision.
• Status, Events, logs, and metrics explain preferred, excluded, fallback,
  and fail-closed decisions without unbounded cardinality.
• Compatibility behavior is defined for consumers that understand locality
  tiers but not the new policy fields.

Demonstration Requirements

Extend the Grid ingress environment with at least two labeled regions and
multiple eligible providers. Prove:

• same-region preference while local capacity is healthy;
• permitted cross-region fallback after local failure or drain;
• recovery back to the preferred region under documented stability rules;
• hard-lock failure when all allowed-region capacity is unavailable;
• no cross-region candidate in the locked overlay or served request path; and
• machine-readable policy, overlay-revision, edge, and provider evidence.

The environment may use local clusters with simulated region labels. It does
not claim production cross-region networking merely because the policy
semantics are demonstrated.

Non-Goals

• Provisioning cross-region network connectivity, firewalls, or private links.
• Implementing Route 53, authoritative DNS, anycast, or a global load balancer.
• Selecting the nearest public edge for an external client; that integration
  consumes the edge contract tracked in feat(ingress): publish bounded edge availability for global traffic managers #9.
• Treating region labels as proof of physical location without a trusted
  admission process.
• Adding Grid-specific policy semantics to generic Praxis request-path APIs.

Open-Source Requirements

Use portable Kubernetes APIs and producer-neutral routing contracts. The
feature must not require a proprietary DNS service, cloud load balancer,
hosted policy engine, commercial telemetry backend, or distribution-specific
controller.