docs(tokenomics): align proposal with current quota work

[nerdalert]

Summary

Updates the token-rate-limiting proposal to reflect the current implementation, active experiments, and remaining architecture work across
Praxis and Praxis AI.

What changed

• Documents the current experimental token_rate_limit implementation:

  • ordered matching rules;
  • sliding-window and token-bucket algorithms;
  • reservation-based admission and settlement;
  • hard 429 enforcement;
  • memory and shared Valkey backends.

• Clarifies standalone and multi-instance deployment:

  • memory-backed quotas are process-local;
  • Valkey or a compatible single-endpoint Redis service can provide shared quota state across replicas;
  • quota enforcement remains independent of routing and orchestration.

• Defines trusted authenticated-subject keying and explicitly rejects caller-controlled identity headers as a security boundary.

• Documents the current reservation invariant and distinguishes reservation over-admission from settlement exceeding an estimate.

• Corrects abandoned-reservation behavior: ambiguous failures remain conservatively charged rather than being automatically refunded.

• Records current work on configurable estimation, soft enforcement, observability, metering, token extraction, and subject-keyed quotas.

• Distinguishes the currently implemented configuration from the richer target API.

• Adds production considerations for Redis/Valkey authentication, TLS, HA, sharding, failover, and script handling.

• Cross-references related tokenomics enhancement proposals and implementation work.

Motivation

The original proposal predates much of the experimental implementation. It did not clearly distinguish shipped behavior, open work, and
future API design, and some lifecycle language no longer matched the actual conservative reservation semantics.

This update gives architecture reviewers one standalone description of the quota system without coupling it to a particular control plane,
routing implementation, or Kubernetes deployment.

Validation

• Markdown lint passed.
• YAML frontmatter parsed successfully.
• git diff --check passed.
• The updated proposal is ASCII-clean.
• No Grid-specific dependency or terminology remains.
• The current Praxis AI implementation was inspected to verify backend, reservation, reconciliation, and Redis compatibility claims.

Related to praxis-proxy/ai#121.

[praxis-bot]

PR Review

Updates the token-rate-limiting proposal to align with current experimental implementation, adding an implementation inventory, reservation semantics, backend/deployment documentation, and cross-references.

Assessment

Strong update. The implementation inventory table is well-structured and clearly separates merged, open, and proposed work. The reservation contract, ownership boundaries, and fail-closed semantics are precisely stated. The soft-enforcement experiment is appropriately scoped as a candidate API with explicit qualification requirements.

Severity	Count
Critical	0
Large	0
Medium	2

No non-inline findings.

[praxis-bot]

[Medium] The related frontmatter is missing proposals that the new "Related Tokenomics Proposals" prose section explicitly cross-references: 00191, 00664, 00784, and 00794. Add them here so the structured metadata stays consistent with the body text.

related:
  - 00099
  - 00119
  - 00191
  - 00210
  - 00211
  - 00212
  - 00214
  - 00216
  - 00220
  - 00664
  - 00784
  - 00794

[praxis-bot]

[Medium] The compound adjective "authentication-neutral" is split across a line break. In rendered markdown the newline becomes a space, producing the visible text "authentication- neutral". Rewrap so the hyphenated word stays on one line, e.g.:

  producer; JWT, OIDC, OAuth, API-key, mTLS, and
  external authentication can publish the same
  authentication-neutral identity contract.

[praxis-bot-app]

Closing this PR due to 10 days of inactivity.
Feel free to re-open when you're ready to continue.