Add Grid distributed quota demo

[nerdalert]

Summary

Adds a runnable Grid demo for three independent, subject-keyed distributed token quotas through one shared endpoint.

application-a, application-b, and application-c authenticate with Basic Auth against the same listener on either consumer gateway. Their verified identities select independent Valkey-backed quota buckets, while admitted requests use one Grid overlay spanning west, central, and east providers.

What it demonstrates

• Three applications share one endpoint and one quota rule configuration.
• Each verified subject receives an independent token quota.
• A subject's quota is shared across two consumer gateway replicas.
• Scaling gateways does not multiply quota capacity.
• Exhausting one application does not consume another application's budget.
• Invalid credentials and quota denials stop before provider contact.
• Admitted requests are routed across three attributable Grid provider sites.
• Concurrent reservation bounds, natural expiry, restart persistence, Valkey fail-closed/recovery, NetworkPolicy boundaries, revision convergence, structured evidence, and automatic cleanup.

Architecture

The request path is:

Basic Auth -> authenticated request identity -> subject-keyed token quota -> Grid provider selection

Praxis publishes the verified username as private request-local AuthenticatedIdentity. Praxis AI consumes that trusted identity with key: authenticated_subject and hashes it into an opaque quota key. Grid remains responsible only for provider eligibility and selection after admission.

The identity contract is not tied to Basic Auth. JWT/OIDC/OAuth-backed authentication can publish the same identity type for reuse by the quota filter.

Contents

Adds demos/grid-distributed-quota/ with:

• architecture, security, image, execution, evidence, and cleanup documentation;
• a complete three-cluster Forge topology;
• two consumer gateway configurations using one shared endpoint;
• shared Valkey and restricted NetworkPolicy resources;
• provider gateway and VCR backend resources;
• Grid trust bootstrap resources;
• a run.sh entry point backed by Grid's first-class token-rate-limit qualification;
• generated-state and evidence exclusions.

The repository index and shared Grid demo launcher are also updated.

Quota contract

Admission reserves configured tokens before provider routing. The enforced invariant is:

active reserved tokens <= capacity

Actual token usage is settled after the response and retained as accounting evidence. A response may use more than its estimate without representing an admission error. The demo does not implement or claim a soft quota.

Security boundaries

• Identity comes only from successful authentication, never a client-controlled application header.
• Passwords and Authorization values are not placed in identity metadata or evidence.
• Subject values are hashed before use in quota backend keys and metrics.
• Provider credentials remain confined to provider gateways.
• Denied requests do not contact providers.
• Valkey and backend access are restricted by NetworkPolicy.
• Checked-in credentials are disposable Kind fixtures and must not be reused in production.

Cross-repository dependencies

Landing order is intentional:

1. feat(basic-auth): publish authenticated identity praxis#1108 publishes verified Basic Auth identity.
2. feat(token-rate-limit): key quotas by authenticated subject ai#980 adds authenticated-subject quota keying and consumes a Praxis release containing that producer.
3. test(quota): qualify three-application distributed quotas grid#127 provides the reference topology and qualification.
4. This demo consumes those released or merged prerequisites.

Related to praxis-proxy/ai#121 and praxis-proxy/grid#101.
Supersedes #19.

Validation

The underlying Grid qualification passed twice from fresh Kind environments, 9/9 scenarios each, with automatic teardown. Demo shell syntax, ShellCheck, Forge structure, documentation, and diff checks also passed.

This remains draft until the dependency chain lands, exact released versions/image provenance are documented, and the demo is rerun from clean upstream checkouts without local Cargo patches.