[P1] Enforce subscription-aware quotas and provider rate limits

[postigodev]

Context

Issue #96 moves rate limiting out of process memory, while #119 defines plans, entitlements, and durable usage. Preppie still needs one enforcement layer that combines abuse protection with commercial allowances.

A paid subscription must not simply multiply a static request limit. Different provider-backed operations have different costs, units, concurrency risks, and failure semantics.

Scope

Enforcement service

• Resolve the authenticated user’s effective entitlement before starting a metered operation.
• Atomically reserve quota or capacity before calling OpenAI, ElevenLabs, vision, or other paid providers.
• Commit actual usage after success and release or adjust reservations after failure.
• Use idempotency keys so retries do not consume allowance twice.
• Enforce limits consistently across replicas and deploys using the infrastructure selected in [P1] Replace in-memory rate limits with distributed usage enforcement #96.

Policy categories

Define separate policies for:

• Authentication abuse controls.
• AI recipe/meal generation.
• Recipe import, including image imports.
• Pantry structuring and alternatives.
• AI chat/adaptation.
• Voice session starts, concurrent sessions, connected duration, and provider-billed duration.
• Vision scans and external product/provider calls.

User and API behavior

• Return typed errors that distinguish authentication failure, plan restriction, exhausted quota, concurrent-session conflict, abuse rate limit, provider outage, and internal metering failure.
• Return retry/reset timing and safe remaining-usage metadata where appropriate.
• Do not report a user as having consumed usage when a request never reached the provider or failed before billable work.
• Define fail-open/fail-closed behavior per category when the entitlement or limiter store is unavailable.
• Prevent browser-only checks from being the authorization boundary.

Voice-specific controls

• Prevent more than one billable voice session per user unless explicitly allowed.
• Set a server-enforced maximum session duration.
• End or refuse sessions once allowance is exhausted.
• Meter duration using trustworthy server/provider events rather than only a client timer.
• Coordinate transport/gating work with [P0] Enforce real hands-free audio gating and accurate microphone states #111.

Administration and support

• Support time-bounded promotional grants and manual adjustments through audited operations.
• Provide support-visible reason codes for denied operations without exposing sensitive provider or payment data.
• Add cost-spike and quota-bypass alerts.

Acceptance criteria

• A free, founding, expired, grace-period, and admin-granted user receives the correct effective limits.
• Limits remain correct across concurrent requests, replicas, deploys, and retries.
• Provider failures do not incorrectly consume final quota.
• Voice concurrency and maximum-duration limits are enforced server-side.
• Exhausted quota produces a stable typed response with reset/upgrade guidance.
• Abuse limits remain separate from commercial usage allowances.
• The frontend cannot bypass a limit by calling a lower-level endpoint directly.
• Automated tests cover races, duplicate requests, provider timeout, cancellation, plan change, grace period, and quota reset.

Dependencies

• Subscription lifecycle: [P0] Build Stripe subscription billing and customer lifecycle #118.
• Entitlements and usage ledger: [P0] Define plan entitlements and durable usage accounting #119.
• Distributed limiter infrastructure: [P1] Replace in-memory rate limits with distributed usage enforcement #96.
• Hands-free audio lifecycle: [P0] Enforce real hands-free audio gating and accurate microphone states #111.
• Observability: [P1] Add cross-service, frontend, and database observability #95.

Out of scope

• Choosing final permanent quota numbers before beta data exists.
• Replacing provider-native safety or account-level spending controls.