refactor(entitlements): stop D1 daily counter mirror

[kentcdodds]

Summary

• stop all production hot-path reads/writes/bootstrap/mirror for entitlement_daily_counters
• initialize cold UserMeter keys at zero
• keep production reporting in Analytics Engine
• retain physical table plus export/deletion guards for staged removal

Validation

• PR validation — passed
• post-merge validation — passed
• production deployment — passed

System recap — contracts daily mirror code paths (medium risk)

Mode: recap · Base: main @ 5a4ce59a · Head: 436c2723

Classification: extends — removes hot-path D1 mirror/fallback behavior while retaining physical-schema guards.

Invariants

• no production hot daily D1 prepare/run
• cold keys initialize zero with INSERT OR IGNORE
• inbound claims remain retry-idempotent
• export/deletion guards remain while table exists
• no migration ran before the Worker deploy

Conductor report

• STATUS: done
• What shipped: all daily D1 mirror/bootstrap hot paths and scheduled retention stopped; physical table plus export/deletion guards remain for safe staged removal.
• Risk: medium — code-first contract stage after verified parity.
• Merged/deployed: yes / yes; PR #1133, post-merge validation, and production deploy succeeded.
• Production quiescence: snapshots at 16:29:02 and 16:32:23 UTC were identical (rows=104, total_count=48,884, max_updated_at=r/…1472), confirming mirror writes stopped after activation.
• Next stages: code-only removal of account export/deletion inventory target, deploy/verify, then migration-only 0126 drop and daily.mirrorRetired === true verification.

  

Summary by CodeRabbit

• Changes
  • Daily entitlement and email usage counts now use a single authoritative metering source.
  • New or previously unused daily resources start at zero, with UTC-day resets preserved.
  • Local email insights warn when quota data is unavailable while continuing to show delivery metrics.
  • Meter parity reports identify retired comparisons and validate meter-only results.
  • Daily-counter retention handling has been streamlined.

[coderabbitai]

📝 Walkthrough

Walkthrough

Daily entitlement counters now use UserMeter as the sole authority. D1 bootstrap, mirror writes, and retention pruning were removed. Parity reports support retired mirrors, local analytics return empty quota aggregates with warnings, and tests use UserMeter fixtures.

Changes

Daily counter migration

Layer / File(s)	Summary
UserMeter authority and entitlement flows packages/worker/src/entitlements/*, docs/contributing/architecture/entitlements.md, packages/worker/src/email/outbound.ts	Daily reads, consumes, refunds, and tests use UserMeter. Cold keys initialize at zero. D1 mirror operations and bootstrap reads were removed.
Inbound and email metering integration packages/worker/src/email/*, packages/worker/src/app/handlers/account-email.node.test.ts, packages/worker/src/mcp/capabilities/email/*, packages/worker/src/mcp/fetch-gateway.node.test.ts	Inbound quota handling and email tests use UserMeter reads and initialization. Retained waitUntil parameters no longer schedule mirror work.
Parity and degraded analytics reporting packages/worker/src/admin/user-meter-parity.*, packages/worker/src/app/admin-insights-data.*, packages/worker/src/mcp/capabilities/admin/*, packages/worker/src/admin/user-usage-data.node.test.ts, docs/contributing/architecture/entitlements.md, docs/contributing/architecture/data-storage.md	Parity detects missing daily-counter tables and reports meter-only results. Local analytics warns and returns empty quota aggregates while delivery aggregates continue using D1.
Legacy table retirement and retention cleanup packages/worker/src/app/retention*, packages/worker/src/app/account-retention-dispositions.ts, docs/contributing/architecture/data-storage.md, docs/contributing/architecture/entitlements.md	Daily-counter retention pruning was removed. The legacy table remains quiescent for pending deletion cleanup and later schema removal.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant EntitlementService
  participant UserMeter
  Caller->>EntitlementService: Request daily entitlement operation
  EntitlementService->>UserMeter: Initialize missing daily key at zero
  EntitlementService->>UserMeter: Read or update daily usage
  UserMeter-->>EntitlementService: Return usage state
  EntitlementService-->>Caller: Return entitlement result

Loading

Possibly related PRs

• kentcdodds/kody#1115: Completes the migration from the D1 daily-counter mirror.
• kentcdodds/kody#1128: Extends parity reporting for retired daily mirrors.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the primary change: stopping the D1 daily counter mirror for entitlements.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/meter-do-38c8

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

@coderabbitai review

[github-actions]

🔎 Preview deployed: https://kody-pr-1133.kody-a99.workers.dev

Worker: kody-pr-1133
D1: kody-pr-1133-db
KV: kody-pr-1133-oauth-kv

Mocks:

• cloudflare: https://kody-pr-1133-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-1133-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/contributing/architecture/data-storage.md`:
- Around line 642-646: Update the D1 daily mirror documentation near the “D1
daily mirror writes stopped” statement to limit the no-read/no-write claim to
enforcement and point-read paths. Explicitly document that
loadAdminUserMeterParityReport temporarily reads entitlement_daily_counters for
admin parity comparison while the table remains, until the follow-up migration
drops it.

In `@packages/worker/src/app/admin-insights-data.ts`:
- Around line 288-291: Split the fallback in admin-insights-data.ts so local
development emits the existing local-mode reason, while a missing EMAIL_EVENTS
binding emits a distinct binding-specific reason. Update
packages/worker/src/app/admin-insights-data.node.test.ts at lines 321-325 to set
WRANGLER_IS_LOCAL_DEV for the local assertion and add coverage asserting the
missing-binding reason.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5500cf07-4fcd-43c1-a2ba-8f800ec505b9

📥 Commits

Reviewing files that changed from the base of the PR and between 3a01d0a and 164b275.

📒 Files selected for processing (28)

• docs/contributing/architecture/data-storage.md
• docs/contributing/architecture/entitlements.md
• packages/worker/src/admin/user-meter-parity.node.test.ts
• packages/worker/src/admin/user-meter-parity.ts
• packages/worker/src/admin/user-usage-data.node.test.ts
• packages/worker/src/app/account-deletion.node.test.ts
• packages/worker/src/app/account-retention-dispositions.ts
• packages/worker/src/app/account-usage-data.node.test.ts
• packages/worker/src/app/admin-insights-data.node.test.ts
• packages/worker/src/app/admin-insights-data.ts
• packages/worker/src/app/handlers/account-email.node.test.ts
• packages/worker/src/app/retention.node.test.ts
• packages/worker/src/app/retention.ts
• packages/worker/src/email/inbound-delivery.ts
• packages/worker/src/email/inbound-entitlements.workers.test.ts
• packages/worker/src/email/inbound-spam-controls.workers.test.ts
• packages/worker/src/email/inbound.workers.test.ts
• packages/worker/src/email/outbound.ts
• packages/worker/src/entitlements/entitlements.node.test.ts
• packages/worker/src/entitlements/service.ts
• packages/worker/src/entitlements/test-schema.ts
• packages/worker/src/entitlements/user-meter-do.ts
• packages/worker/src/entitlements/user-meter.workers.test.ts
• packages/worker/src/mcp/capabilities/admin/admin-capabilities.node.test.ts
• packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.node.test.ts
• packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.ts
• packages/worker/src/mcp/capabilities/email/email-usage-get.workers.test.ts
• packages/worker/src/mcp/fetch-gateway.node.test.ts

💤 Files with no reviewable changes (4)

• packages/worker/src/email/inbound-entitlements.workers.test.ts
• packages/worker/src/app/account-deletion.node.test.ts
• packages/worker/src/mcp/capabilities/admin/admin-capabilities.node.test.ts
• packages/worker/src/app/retention.ts