feat(token-quota): add distributed quota topology

.dockerignore

@@ -0,0 +1,5 @@
+.git
+.forge
+target
+**/target
+evidence

charts/grid-operator/crds/gridnetwork.yaml

@@ -381,6 +381,24 @@ spec:
                   items:
                     type: string
                   type: array
+                selectionPolicy:
+                  description: |-
+                    Local request distribution policy for the active selection group.
+
+                    This is independent of scoring. When absent, the overlay carries no
+                    selection override and Praxis uses deterministic selection.
+                  nullable: true
+                  properties:
+                    mode:
+                      description: Local selection mode used by the data-plane gateway.
+                      enum:
+                        - deterministic
+                        - roundRobin
+                        - random
+                      type: string
+                  required:
+                    - mode
+                  type: object
                 staleCandidateTtlSeconds:
                   description: |-
                     Maximum age in seconds before a stale (`fresh=false`) remote routing

charts/grid-site/templates/gridnetwork.yaml

@@ -1,4 +1,15 @@
 {{- if .Values.gridNetwork.name }}
+{{- $existing := lookup "grid.praxis-proxy.io/v1alpha1" "GridNetwork" .Release.Namespace .Values.gridNetwork.name }}
+{{- $configuredSelectionPolicy := .Values.gridNetwork.selectionPolicy }}
+{{- $existingSelectionPolicy := dig "spec" "selectionPolicy" nil $existing }}
+{{- $selectionPolicy := $configuredSelectionPolicy }}
+{{- if not $selectionPolicy }}
+  {{- if $existingSelectionPolicy }}
+    {{- $selectionPolicy = $existingSelectionPolicy }}
+  {{- else if not $existing }}
+    {{- $selectionPolicy = dict "mode" "roundRobin" }}
+  {{- end }}
+{{- end }}
 apiVersion: grid.praxis-proxy.io/v1alpha1
 kind: GridNetwork
 metadata:
@@ -20,6 +31,10 @@ spec:
   {{- with .Values.gridNetwork.zone }}
   zone: {{ . | quote }}
   {{- end }}
+  {{- with .Values.gridNetwork.seeds }}
+  seeds:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
   {{- with .Values.gridNetwork.routingPolicy }}
   routingPolicy: {{ . | quote }}
   {{- end }}
@@ -33,6 +48,12 @@ spec:
   admissionPolicy:
     {{- toYaml . | nindent 4 }}
   {{- end }}
+  {{- with $selectionPolicy }}
+  {{- if .mode }}
+  selectionPolicy:
+    mode: {{ .mode | quote }}
+  {{- end }}
+  {{- end }}
   {{- with .Values.gridNetwork.metricsRefreshInterval }}
   {{- if . }}
   metricsRefreshInterval: {{ . | quote }}

charts/grid-site/templates/gridsite.yaml

@@ -16,4 +16,8 @@ spec:
   {{- with .Values.gridSite.zone }}
   zone: {{ . | quote }}
   {{- end }}
+  {{- with .Values.gridSite.egress }}
+  egress:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
 {{- end }}

charts/grid-site/tests/gridnetwork_test.yaml

@@ -32,6 +32,15 @@ tests:
           path: spec.gridId
           value: ""
 
+  - it: defaults a new GridNetwork to roundRobin selection
+    set:
+      gridNetwork.name: prod-grid
+      gridSite.name: prod-site
+    asserts:
+      - equal:
+          path: spec.selectionPolicy.mode
+          value: roundRobin
+
   - it: renders budgetPolicy.tenants verbatim when set
     set:
       gridNetwork.name: prod-grid

charts/grid-site/values.schema.json

@@ -21,6 +21,10 @@
         "zone": {
           "type": "string"
         },
+        "seeds": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
         "swim": {
           "type": "object",
           "additionalProperties": true,
@@ -71,6 +75,17 @@
             }
           }
         },
+        "selectionPolicy": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["deterministic", "roundRobin", "random"]
+            }
+          }
+        },
         "metricsRefreshInterval": {
           "type": "string",
           "pattern": "^([1-9][0-9]*s|[1-9][0-9]{3,}ms)$"
@@ -125,6 +140,14 @@
         },
         "providerSiteLabel": {
           "type": "string"
+        },
+        "egress": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "address": { "type": "string", "minLength": 1 },
+            "tls": { "type": "object", "additionalProperties": true }
+          }
         }
       }
     },

charts/grid-site/values.yaml

@@ -3,6 +3,7 @@ gridNetwork:
   gridId: ""
   region: ""
   zone: ""
+  seeds: []
   swim: {}
   tls: {}
   gatewayRefs: []
@@ -24,6 +25,7 @@ gridSite:
   region: ""
   zone: ""
   providerSiteLabel: ""
+  egress: {}
 
 inferenceProviders: []
 

charts/praxis-gateway/templates/deployment.yaml

@@ -147,6 +147,10 @@ spec:
           args:
             {{- toYaml . | nindent 12 }}
           {{- end }}
+          {{- with .Values.env }}
+          env:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
           securityContext:
             runAsNonRoot: true
             allowPrivilegeEscalation: false

charts/praxis-gateway/values.schema.json

@@ -100,6 +100,40 @@
       "items": { "type": "string" },
       "description": "Container arguments."
     },
+    "env": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "value": { "type": "string" },
+          "valueFrom": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["secretKeyRef"],
+            "properties": {
+              "secretKeyRef": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["name", "key"],
+                "properties": {
+                  "name": { "type": "string", "minLength": 1 },
+                  "key": { "type": "string", "minLength": 1 },
+                  "optional": { "type": "boolean" }
+                }
+              }
+            }
+          }
+        },
+        "oneOf": [
+          { "required": ["value"] },
+          { "required": ["valueFrom"] }
+        ]
+      },
+      "description": "Environment variables passed to the Praxis container."
+    },
     "config": {
       "type": "object",
       "additionalProperties": false,

charts/praxis-gateway/values.yaml

@@ -38,6 +38,10 @@ args:
   - "--config"
   - "/etc/praxis/praxis.yaml"
 
+# -- Environment variables passed to the Praxis container. Use valueFrom for
+# -- credentials and other deployment-managed secrets.
+env: []
+
 # -- Required Praxis configuration.
 config:
   # -- Name of an existing ConfigMap containing the Praxis configuration.

deploy/crds/gridnetwork.yaml

@@ -381,6 +381,24 @@ spec:
                   items:
                     type: string
                   type: array
+                selectionPolicy:
+                  description: |-
+                    Local request distribution policy for the active selection group.
+
+                    This is independent of scoring. When absent, the overlay carries no
+                    selection override and Praxis uses deterministic selection.
+                  nullable: true
+                  properties:
+                    mode:
+                      description: Local selection mode used by the data-plane gateway.
+                      enum:
+                        - deterministic
+                        - roundRobin
+                        - random
+                      type: string
+                  required:
+                    - mode
+                  type: object
                 staleCandidateTtlSeconds:
                   description: |-
                     Maximum age in seconds before a stale (`fresh=false`) remote routing

docs/README.md

@@ -9,6 +9,9 @@
 - [Routing](architecture/routing.md) — versioned overlay contract, revision
   lifecycle, candidate ordering, `intelligent_route`, `peer_identity_trust`, and
   provider-side request forwarding.
+- [Provider Selection and Load Balancing](architecture/provider-selection-and-load-balancing.md) —
+  eligibility, routing groups, scoring, selection modes, affinity, and
+  overlay lifecycle.
 - [Scoring](architecture/scoring.md) — operator-side candidate scoring,
   metrics input, and request-time scoring boundaries.
 - [Auth and Policy](architecture/auth.md) — provider authentication strategies,