feat(filters): add grid_route

[nerdalert]

Summary

Adds grid_route to praxis-ai-filters and registers it from praxis-ai-proxy.

Architecturally, this is the AI/Grid-owned routing filter that consumes a static site/capability descriptor and selects the upstream cluster for the request. The Grid operator can render candidate overlays from provider state, and the AI proxy can consume those candidates without requiring Praxis core to understand models, tools, sites, freshness, or Grid-specific routing policy.

This keeps the split intentional:

• Praxis core provides generic proxy mechanics: filter runtime, request context, pipeline validation, and load_balancer.
• The AI repo owns AI/Grid semantics: model routing, MCP tool routing, freshness preference, locality preference, and Grid candidate shape.

In a gateway pipeline, grid_route sits after request classification and before load_balancer:

filters:
  - filter: json_body_field
    field: model
    header: X-Model

  - filter: grid_route
    local_site: site-a
    candidates:
      - kind: inference_model
        name: granite-3.3-8b
        site: site-a
        cluster: granite-local
        fresh: true

  - filter: load_balancer
    clusters:
      - name: granite-local
        endpoints:
          - "127.0.0.1:8001"

grid_route is the cluster-selecting filter for this path. It writes ctx.cluster, and load_balancer forwards to that selected cluster. No router filter is required between them.

What changed

• Adds grid_route inference and MCP tool routing
• Registers grid_route from the AI proxy
• Routes inference_model candidates by model header, defaulting to X-Model
• Routes mcp_tool candidates by mcp.method=tools/call and mcp.name
• Gives MCP metadata precedence over model-header routing
• Selects ctx.cluster directly for downstream load_balancer
• Prefers fresh candidates over stale candidates
• Prefers local-site candidates over remote candidates when freshness is equal
• Adds docs, examples, and schema coverage

Boundary

This PR keeps AI/Grid-specific semantics in the AI repo:

• model/provider candidate routing
• MCP tool candidate routing
• freshness/locality preference
• Grid route docs and examples

Praxis core remains responsible for generic proxy primitives:

• filter runtime
• pipeline validation
• request context
• load balancing
• generic routing/security filters

Additional reviewer context

This PR adds the Praxis AI grid_route filter, which is the request-time half of the Grid routing handoff.

Grid does not route live HTTP requests itself. Grid renders a routing overlay from GridNetwork, GridSite, InferenceProvider, metrics, SWIM/CRDT state, and access-policy decisions. Praxis AI then consumes that overlay through grid_route.

Grid side quests:

• Grid architecture overview:
  https://github.com/praxis-proxy/grid/blob/main/docs/architecture/overview.md

• Routing architecture and overlay handoff:
  https://github.com/praxis-proxy/grid/blob/main/docs/architecture/routing.md

• Consumer ConfigMap / grid-config.json handoff:
  https://github.com/praxis-proxy/grid/blob/main/docs/architecture/consumer-config.md

• Scoring model that determines overlay candidate order:
  https://github.com/praxis-proxy/grid/blob/main/docs/architecture/scoring.md

• Credential and auth boundary:
  https://github.com/praxis-proxy/grid/blob/main/docs/architecture/auth.md

• Kind/E2E validation docs:
  https://github.com/praxis-proxy/grid/blob/main/docs/architecture/ci-kind-e2e.md

• Grid README with current validation commands:
  https://github.com/praxis-proxy/grid/blob/main/README.md

Grid/Praxis AI responsibility split:

• Grid owns provider discovery, policy filtering, scoring, and overlay rendering.
• Praxis AI owns request parsing, grid_route candidate selection, and forwarding to a preconfigured load_balancer cluster.
• grid_route does not call Kubernetes, Grid, SWIM, or CRDT at request time.
• grid_route does not create upstream clusters dynamically. Any cluster named by a Grid candidate must already exist in the Praxis AI load_balancer config.
• Credential-bearing candidates carry only credential references. Secret/token resolution is handled by the separate grid_credential_inject path.

Validation

• cargo +nightly-2026-03-28 fmt --all -- --check
• cargo test -p praxis-ai-filters grid
• cargo test -p praxis-tests-schema grid_route
• cargo clippy -p praxis-ai-filters -- -D warnings
• cargo clippy -p praxis-ai-proxy -- -D warnings
• RUSTDOCFLAGS="-D warnings" cargo doc -p praxis-ai-filters -p praxis-ai-proxy --no-deps
• git diff --check

[praxis-bot]

Review: feat(filters): add grid_route

Clean, well-structured PR. The filter design is sound: static candidate scoring, deterministic selection, MCP precedence over model header, proper fail-closed behavior. Validation is thorough (bounds on all identifiers, reserved header prefix rejection, duplicate detection). Unit test coverage in route.rs and descriptor.rs is excellent.

Findings

Severity	Count
Critical	0
Large	0
Medium	1

One medium finding below regarding test coverage for the MCP example config.