External Client Ingress

External client ingress extends AGN’s workload-routing model to a stable public endpoint. A global traffic manager selects an edge. AGN and Praxis then select and reach an eligible provider.

This document defines the production architecture contract. The Repository Implementation section identifies the capabilities implemented by the current AGN/Praxis integration. Deployment-specific development topologies and proof commands are documented with their environment rather than embedded in this contract.

The Praxis demos repository provides a generic managed-DNS validation contract with an OpenShift reference implementation. It keeps public edge selection separate from AGN provider selection and documents the health and regional-policy limits of DNS steering.

The architecture has two independent routing stages:

external client
  -> managed DNS / Anycast / global traffic manager
  -> Praxis AI edge gateway
  -> AGN-selected Praxis provider gateway
  -> provider-local inference backend

The first stage is network and edge selection. The second stage is model/provider selection. Combining them would put model, tenant, and provider capacity policy into DNS, which does not have the authenticated request context or parsed request body.

Ingress Patterns

AGN uses the same provider-routing contract for two entry patterns.

Workload Ingress

in-cluster workload
  -> cluster-local Praxis consumer gateway
  -> AGN-selected provider gateway
  -> inference backend

External Client Ingress

external client
  -> stable public service name
  -> healthy active edge selected by GTM
  -> AGN-selected provider gateway
  -> inference backend

The edge fleet is replicated. One public name does not imply one gateway process or a single AGN controller.

Component Ownership

AGN is a routing control plane. It does not proxy inference traffic. Praxis AI does not join SWIM or query Kubernetes, AGN Operators, DNS control APIs, or the filesystem while processing a request.

Request Path

The external edge pipeline is ordered so hard security and policy decisions run before provider preference:

request ID and trusted forwarding metadata
  -> external caller authentication
  -> tenant/model/region authorization
  -> rate, concurrency, and body limits
  -> model or capability extraction
  -> optional logical-model classification
  -> AGN candidate matching
  -> established-session binding or new-session selection
  -> provider cluster selection
  -> gateway-to-gateway mTLS

The provider gateway authenticates the edge again and applies its own local authorization. Discovery at the edge does not authorize access at the destination.

The selected overlay cluster names a pre-authorized Praxis load-balancer cluster. Overlay updates can change candidate eligibility and ordering. They do not create arbitrary endpoints, CA roots, client keys, or SNI values on the request path.

Control-Plane Path

local provider CRDs and observed metrics
  + remote authenticated SWIM/CRDT state
  + GridSite lifecycle and access policy
  -> per-edge eligibility, admission, locality, and scoring
  -> versioned routing overlay ConfigMap
  -> projected Kubernetes volume
  -> strict validation and atomic in-memory swap in Praxis AI
  -> loaded revision exposed by gateway status

The edge serves an accepted last-known-good snapshot during a bounded control-plane interruption. A rejected update never replaces the accepted snapshot. Overlay age and public route coverage feed edge readiness.

Routing Order

Hard gates precede preferences:

1. authenticated tenant and model authorization;
2. capability availability and destination trust;
3. residency, external-egress, and sovereignty policy;
4. provider/site lifecycle, health freshness, and admission;
5. logical route class for configured aliases;
6. established-session binding;
7. new-session locality tier;
8. AGN selection tier and rank;
9. deterministic selection among candidates AGN marks equivalent.

Location is a property of the edge’s trusted deployment identity. Client headers such as X-Region, X-Country, or internal route-class headers do not control AGN locality.

AGN computes site distance from the edge GridSite and provider GridSite:

same_site -> same_zone -> same_region -> cross_region -> unknown

A closer provider is preferred only while it remains eligible for the request class. Hard failure, policy loss, stale state, or closed admission overrides locality.

Provider Admission

The overlay carries a bounded admission result rather than raw metric series:

The provider site owns normalized, timestamped capacity signals. AGN owns the policy that turns those signals into admission state, including hysteresis, hold-down, expiry, and explicit drain overrides. Praxis consumes the result and does not reproduce AGN’s metric formula.

Unknown, pending, stale, or expired provider state is closed to new work in the external edge profile.

Session Affinity

Affinity is keyed from authenticated tenant identity, a validated session ID, the normalized capability, and any bound route class. Source IP and client-supplied tenant metadata are not affinity inputs.

For a new session, Praxis selects within the closest usable AGN selection tier. For an established session, the binding remains authoritative while the candidate is eligible for existing work. A none candidate, provider loss, policy loss, or capability loss breaks the binding. Recovery does not automatically pull a rebound session back.

An in-memory binding store scopes affinity to one edge process. Active-active production uses an explicitly supported shared-store or signed-token contract with bounded TTL, entry count, creation rate, concurrency behavior, and failure semantics.

Authentication Boundaries

External ingress has three separate credential domains.

Customer Identity

The edge authenticates the external bearer token, JWT, or API key and derives a bounded tenant/principal context. The external client’s Authorization header is removed before gateway-to-gateway or provider traffic.

AGN Peer Identity

The edge presents its AGN client certificate to a provider Praxis gateway. The provider validates the CA chain, SNI/server identity, client certificate, and configured peer_identity_trust policy. Public server certificates and AGN site certificates remain separate trust domains with separate rotation.

Provider Credential

The component making the final provider API call owns the provider credential. AGN carries a Secret reference, never credential bytes.

Praxis AI credential_inject maps an authorized selected candidate to a mounted Secret file at the final hop.

Edge Health and GTM

GTM probes edge liveness and readiness separately:

An individual provider failure does not make an otherwise useful edge unready. AGN removes that provider from eligible routes. Loss of all required route coverage, a hard-expired snapshot, or a failed security dependency makes the edge unready and causes GTM withdrawal.

GTM steering moves new connections. It does not migrate an in-flight SSE stream.

Route-aware readiness belongs with the accepted AGN routing snapshot because generic process or cluster health cannot prove that the edge has fresh, usable public route coverage. The traffic manager consumes readiness but never reads the AGN overlay or selects a provider.

Retry and Streaming Rules

Inference calls are commonly non-idempotent POST requests. Praxis may fail over before sending request bytes upstream. It does not automatically replay a request after bytes may have reached a provider unless that API and provider have an explicit idempotency contract.

During shutdown:

1. readiness is withdrawn;
2. new requests stop;
3. active streams receive the configured drain interval;
4. remaining connections close at the documented hard deadline.

Provider or edge failover applies to later requests, not an active stream.

Overlay Contract

The production acceptance contract uses a versioned, bounded envelope. The current repository emits the subset listed under Repository Implementation; revision, digest, expiry, and serving-status fields remain release gates until their implementation is present across AGN generation, distribution, and Praxis acceptance.

{
  "api_version": "grid.praxis.fast/v1alpha2",
  "grid_id": "grid-identity",
  "network": "production",
  "consumer": {
    "gateway": "public-edge",
    "site": "edge-us-east"
  },
  "revision": 42,
  "content_digest": "sha256:...",
  "generated_at": "2026-07-25T12:00:00Z",
  "valid_until": "2026-07-25T12:05:00Z",
  "candidates": [
    {
      "kind": "inference_model",
      "name": "shared-model",
      "site": "provider-us-east",
      "cluster": "gateway-provider-us-east",
      "stable_id": "sha256:...",
      "admission_state": "new_and_existing",
      "selection_tier": "same_region",
      "rank": 0
    }
  ]
}

The accepted schema defines maximum document size, candidate count, identifier length, duplicate behavior, supported versions, and unknown-field behavior. Praxis reports the loaded revision/digest, acceptance time, snapshot age, and last rejection reason.

Observability

Every request decision records bounded internal fields:

• edge site and region;
• authenticated tenant class, without raw identity;
• requested logical/concrete model;
• selected provider site, cluster, admission state, tier, and rank;
• overlay revision, digest, and age;
• decision reason and binding outcome;
• caller-auth, authorization, quota, and rate-limit result; and
• upstream connection phase, without request replay.

Prompts, session IDs, raw tenant identifiers, external-client credentials, provider credentials, private keys, and affinity secrets are never log or metric labels.

Control-plane status distinguishes:

desired -> rendered -> distributed -> accepted -> serving

This makes ConfigMap apply success distinguishable from the gateway actually using that revision.

Repository Implementation

The AGN and Praxis integration provides:

• per-GatewayRef routing overlay generation;
• candidate model/site/cluster identity;
• provider access-policy filtering;
• operator-side scoring;
• geography-derived locality tiers;
• threshold-derived admission metadata;
• stable_id, rank, and generated_at metadata;
• explicit mutual_tls or plaintext endpoint transport in generated consumer config;
• SWIM membership and CRDT provider propagation;
• provider Service address discovery and remote GridSite materialization;
• Kubernetes-native provider gateway address discovery;
• edge-local overlay ConfigMaps projected directly into Praxis pods; and
• independently rendered overlays for each edge GatewayRef.

Praxis core implements the generic primitives used by the completed path: upstream mTLS, downstream mTLS identity, peer_identity_trust, listeners, load balancing, health checks, configuration reload, and connection handling.

Praxis AI owns intelligent_route, provider credential injection, AI request parsing, provider_route, and the generic request-time routing contract. A compatible Praxis AI build provides overlay-file reload and the configured session-affinity behavior.

The deployment contract treats a ConfigMap write and process liveness as control-plane observations, not serving proof. Operators use gateway status, snapshot age, route coverage, and request evidence to determine whether an edge is ready for global traffic.

Provider Boundary

The provider-gateway Service selects only Praxis AI provider pods. Provider listeners require an edge certificate, validate the authorized edge identity with peer_identity_trust as the first unconditional filter, parse the inference model, and use an exact provider-local candidate/model/path map before forwarding to a private backend. That map selects a provider-local Secret reference; credential_inject reads the mounted Secret and replaces the external-client credential only on the final backend hop. The edge presents its client identity and verifies the provider CA and site-specific SNI.

intelligent_route.provider_hop_clusters defines the AI-owned serialization boundary. The filter always removes client-supplied X-AI-Routing-* fields and reconstructs the selected stable candidate and hop request ID only when the selected cluster is explicitly allowlisted as a provider hop. Direct backend and API clusters remain absent from that allowlist. Praxis does not interpret these fields. The provider consumes them only after mTLS and peer_identity_trust; provider_route then removes them, performs an exact local lookup, and writes provider-owned backend attribution. X-Praxis-* is not used for this wire contract because Praxis strips its reserved namespace before upstream requests.

Gateway addresses and provider state use independent SWIM broadcast lanes. A gateway-only update is accepted independently of the last provider-state revision, so a Service port or address change cannot remain hidden behind a higher, unrelated CRDT revision. The receiving operator reconciles the updated address into the auto-discovered GridSite.spec.gatewayEndpoint.address.

Provider backends are private Services. Network policy admits inference traffic from provider-gateway workloads and explicitly authorized health observers; other workloads are denied. Health observers do not possess the provider credential.