[johnnyeric]

Summary

With USAGE_SHADOW_PUBLISH_ENABLED=true, the gateway sends its finalized usage event to the queue-backed ingestion endpoint in both Frankfurt and SFO. It reuses the existing event and ID while current billing remains authoritative and independent of enqueue acceptance. The switch defaults off.

Enqueue runs in its own tracked after promise, including when earlier request-cleanup callbacks have finished. Publishing starts only after lifetime registration succeeds; missing request scope or lifetime support performs no network work. Acceptance and failure logs contain safe identifiers and categories. Staging enables the ingestion Worker's workers.dev URL for testing after deployment; production public URLs and preview URLs remain disabled.

Verification

• Exercised synthetic gateway usage through the actual publisher, HTTP, configured Worker entry and local queue in both regions. Verified matching usage IDs, disabled zero network calls, real unauthorized response, and bounded HTTP timeout with billing unaffected.
• Exercised a real HTTP stall after earlier request cleanup had drained: billing completed in milliseconds while the tracked background lifetime waited approximately two seconds for timeout. Fixture ports were released.

Visual Changes

N/A

Reviewer Notes

Depends on #7295 (usage enqueue helper); this PR contains only gateway integration, its configuration/tests, and staging endpoint configuration/docs.

Validation: 214 focused tests and 43 selected processUsage tests pass; 22 DB-backed cases excluded. Both typechecks, scoped lint, formatting and diff checks pass. The real Next lifecycle regression fails on the previous callback implementation in both regions and passes with independent promise registration. Staging and production deployment dry runs passed.

Database writes, authoritative writer transport and provider behavior are mocked/synthetic, and request lifecycle hooks are synthetic. Worker/HTTP/local queue components run in the actual local runtime with a temporary receipt consumer. No hosted gateway verification or real billing/inference was performed.

The existing Worker schema strips redundant runtime metadata.requested_model; core.requested_model is retained. The gateway sends the unchanged event, and queue receipts match its validated contract fields. HTTP 202 means enqueued, not processed or billed.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (6 files)

• ENVIRONMENT.md
• packages/web-shared/src/lib/ai-gateway/processUsage.ts
• packages/web-shared/src/lib/ai-gateway/usage-shadow-integration.test.ts
• packages/web-shared/src/lib/config.server.ts
• services/usage-ingest/README.md
• services/usage-ingest/wrangler.jsonc

---

_{Reviewed by deepseek-v4.1-flash · Input: 80.5K · Output: 21.4K · Cached: 1.1M}

_{Review guidance: REVIEW.md from base branch johnnyeric/usage-shadow-publisher}