feat(grid-provider-traffic): add provider selection demo

[nerdalert]

Summary

This draft PR adds the focused grid-provider-traffic demonstration to the
public demos repository.

It shows Grid-programmed provider selection across three distinct provider
gateways, with one consumer gateway performing local intelligent_route
round-robin selection inside the active group.

                         Client traffic
                              |
                    Consumer / Edge Gateway
                              |
                       intelligent_route
                              |
          +-------------------+-------------------+
          |                   |                   |
   Provider Gateway A  Provider Gateway B  Provider Gateway C
          |                   |                   |
     Provider stack A    Provider stack B    Provider stack C
          |                   |                   |
       VCR backend A       VCR backend B       VCR backend C

The demo intentionally keeps one consumer entrypoint so the provider-level
selection behavior is easy to see. The architecture supports multiple
consumer/edge gateways for scale-out; each gateway maintains local selection
state rather than using a globally coordinated request-time counter.

Grid selects among provider gateways. Endpoint, replica, or backend selection
inside an individual provider gateway remains the responsibility of that
provider's independent serving stack.

Capabilities demonstrated

• Cross-site provider discovery and SWIM convergence.
• GridSite trust authorization and active remote sites.
• Versioned Grid overlay publication and Praxis overlay acceptance.
• Explicit routingPolicy: scoreFirst.
• Explicit scoringPolicy.strategy: noMetrics.
• Explicit selectionPolicy.mode: roundRobin.
• Three fresh NewAndExisting candidates in selection group 0.
• One consumer gateway routing to three separate provider gateways.
• Exact 20/20/20 distribution over 60 serial requests.
• Repeating three-provider selection sequence.
• VCR-backed provider attribution.
• Scoped teardown that removes only the demo clusters and network.

This PR does not claim weighted routing, metric-derived traffic ratios,
provider-local replica balancing, GLB, DNS/GTM routing, globally coordinated
round-robin, or automatic retry after an upstream request has started.

Pinned development images

The demo uses immutable project-owned development image tags and records their
expected registry digests in demos/grid-provider-traffic/configs/images.env.
It does not require local container builds.

• Gateway: ghcr.io/nerdalert/praxis-ai:grid-provider-selection-otel-20260814-536534aba5c1
• Operator: ghcr.io/nerdalert/grid-operator:provider-selection-20260814-d965540dad8d
• Overlay sync: ghcr.io/nerdalert/grid-overlay-sync:provider-selection-20260814-d965540dad8d
• VCR backend: ghcr.io/neuralmagic/vllm-vcr:vllm0.23

The tracing UI image is documented as an optional supporting component and is
not required for the core routing proof.

Running the demo

Until the provider-traffic xtask entrypoint is merged into Grid main, use the
public Grid feature branch that contains the command:

git clone --branch feat/provider-selection-groups \
  https://github.com/nerdalert/grid.git grid-provider-selection-grid
export GRID_REPO="$PWD/grid-provider-selection-grid"
git clone https://github.com/praxis-proxy/demos.git demos
cd demos
source demos/grid-provider-traffic/configs/images.env
./demos/grid-provider-traffic/run.sh --quick --teardown

The wrapper builds only Forge and xtask locally. It does not build the
gateway, operator, overlay-sync, or tracing UI images.

Validation

The clean validation used the pinned image tags, the Grid provider-selection
branch, and zero existing provider-traffic clusters.

• git diff --check
• bash -n demos/grid-provider-traffic/run.sh scripts/run-grid-demo.sh
• Ruby YAML parsing for the Forge and Kubernetes resource files
• Clean three-cluster install
• SWIM convergence and remote GridSite authorization
• Global overlay convergence
• Exact 60-request proof
• Exact provider distribution: 20/20/20
• Repeating provider sequence
• Scoped teardown

Runtime evidence showed:

• one consumer replica;
• three provider gateways;
• three VCR backends;
• all candidates in group 0;
• roundRobin selection mode;
• stable semantic and serving revisions during measurement;
• zero request failures.

The clean validation completed successfully in 380 seconds and removed only
the three provider-traffic Kind clusters and their network.

Related work

• Grid provider-selection research spike: Spike: request-time selection across equivalent Grid providers grid#31
• Grid provider-selection branch: https://github.com/nerdalert/grid/tree/feat/provider-selection-groups
• Praxis AI provider-selection branch: https://github.com/nerdalert/ai/tree/feat/provider-load-balancing
• Optional tracing UI: https://github.com/nerdalert/praxis-tracing

This is intentionally staying in draft until the Grid provider-selection
feature branch merges and the public demo can use the supported Grid main
entrypoint. It does not change Grid or Praxis AI implementation code.

Checklist

• Public demo README and topology documentation added.
• Pinned development image references documented.
• Provider-traffic xtask wrapper wiring added.
• Clean install and exact distribution proof completed.
• Teardown verified and unrelated Kind cluster preserved.
• Grid provider-selection branch merged into Grid main.
• Cross-repository image set promoted beyond research use.

[nerdalert]

Weighted Provider Demo

weighted-provider-distribution.mp4