[kentcdodds]

Summary

Admin-only read-only admin_user_meter_parity compares one stable user's D1 and UserMeter state for daily counters, storage bytes, package services, deletion tombstones, and lease mirrors. Output is sanitized and bounded; cold/stalled/truncated reports fail closed.

System recap — composes parity verification surfaces (low risk)

Mode: recap · Base: main @ f0b00c4a · Head: a6180fc3

No authority/state mutation; admin read model only.

Conductor report

• STATUS: done
• Merged/deployed: yes / yes; PR #1128, post-merge validation, and production deploy succeeded.
• Fleet evidence (2026-08-01 15:17–15:21 UTC, all 38 users): daily mismatches 0; storage mismatches/bootstraps 0; package-service running-count mismatches 0; deletion tombstone mismatches 0; lease mirror mismatches converged to 0 (doOnly=0, legacyWithoutD1=0).
• Daily contract: VERIFIED and completed through #1133, #1134, and #1135. Production verification at 17:47 UTC: D1 table/index absent and daily.mirrorRetired=true.
• Storage flip: NOT READY despite zero parity mismatch. Mailbox-owned inbound/outbound storage reservations still omit env.USER_METER; flipping would create split authority. Earliest safe time is after that handoff deploy plus one complete reconciliation rotation with zero parity mismatches.
• Package-service flip: NOT READY. feat(services): shadow liveness in UserMeter #1119 deployed at 2026-08-01 08:52 UTC, so the earliest 24h soak completion is 2026-08-02 08:52 UTC. Current running-count parity is zero mismatches, but one user has two stopped D1-only inventory rows; cold-bootstrap/inventory policy must be reviewed before flip.
• Deletion D1 mirror removal: NOT READY. Mirror coverage converged (doOnly=0), but production still had 166 D1-only rows: holder categories included unspecified, mcp, and web, not exclusively known email leases. Remove mirrors only after old-isolate drain plus zero unexplained non-email D1-only rows and successful mark/list/repair smoke tests.

  

Summary by CodeRabbit

• New Features

  • Added an administrator-only admin_user_meter_parity capability for read-only comparison of account entitlement data.
  • Reports parity for daily usage, storage, package services, deletion state, and lease status without exposing sensitive lease credentials.
  • Indicates missing, uninitialized, mismatched, or incomplete data for troubleshooting.

• Documentation

  • Added guidance covering parity checks, bootstrap handling, thresholds, and incomplete inventories.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

UserMeter–D1 parity capability

Layer / File(s)	Summary
Scalar parity report and validation packages/worker/src/admin/user-meter-parity.ts, packages/worker/src/admin/user-meter-parity.node.test.ts	Defines the parity report and compares daily counters and storage bytes. Tests cover full parity, mismatches, bootstrap-required state, immutability, and missing users.
Inventory and lease parity packages/worker/src/admin/user-meter-parity.ts, packages/worker/src/admin/user-meter-parity.node.test.ts	Adds capped pagination and compares package services, deletion timestamps, and lease mirrors. Tests cover D1-only, DO-only, legacy-only, and truncated inventory states.
Admin MCP capability and registration packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.ts, packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.node.test.ts, packages/worker/src/mcp/capabilities/admin/domain.ts, packages/worker/src/mcp/capabilities/registry.node.test.ts, docs/contributing/architecture/entitlements.md	Registers the admin-only capability with schemas, auditing, role filtering, secret redaction, and documentation.

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

Sequence Diagram(s)

sequenceDiagram
  participant Admin
  participant MCP
  participant ParityLoader
  participant D1
  participant UserMeter
  Admin->>MCP: submit stable_user_id
  MCP->>ParityLoader: loadUserMeterParityReport
  ParityLoader->>D1: read account and entitlement state
  ParityLoader->>UserMeter: read meter inventories
  D1-->>ParityLoader: D1 parity inputs
  UserMeter-->>ParityLoader: UserMeter parity inputs
  ParityLoader-->>MCP: validated parity report
  MCP-->>Admin: report and audit success

Loading

Possibly related PRs

• kentcdodds/kody#1115: Introduced the UserMeter and D1 state inspected by this parity reporter.
• kentcdodds/kody#1119: Introduced the package-service state and counts used for parity checks.
• kentcdodds/kody#1125: Introduced the write-lease mirror state compared by this reporter.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.26% 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 describes the new admin UserMeter parity verification capability.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 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-1128.kody-a99.workers.dev

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

Mocks:

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/worker/src/admin/user-meter-parity.ts (1)

367-376: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Bound the D1 inventory query with the same cap.

The meter walk stops at userMeterParityInventoryMaxRows, but this query returns all D1 rows. For an account above the cap, d1Only counts every unpaged meter row as a D1-only mismatch. The truncated flag keeps parity false, so no false pass occurs, but the reported categories mislead the operator.

Apply LIMIT userMeterParityInventoryMaxRows + 1 and mark the compare truncated when the extra row appears.

🤖 Prompt for 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.

In `@packages/worker/src/admin/user-meter-parity.ts` around lines 367 - 376, The
D1 inventory query in the user-meter parity flow must use the same row cap as
the meter walk. Update the query near d1RowsResult to request
userMeterParityInventoryMaxRows + 1 rows, then detect the extra row, set the
comparison’s truncated flag, and limit the rows used for d1Only classification
to the configured cap.

🤖 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 `@packages/worker/src/admin/user-meter-parity.ts`:
- Around line 250-270: Extract the duplicated paging logic from the user-meter
parity flow into a shared helper that accepts the page-fetch function, preserves
maxRows and truncation behavior, and stops when nextStartAfter is missing or
does not advance beyond the previous cursor. Update the loop at
packages/worker/src/admin/user-meter-parity.ts:250-270 to use the helper, and
replace the repeated listWriteLeases loop at
packages/worker/src/admin/user-meter-parity.ts:286-306 with the same helper;
both sites require direct changes.

---

Nitpick comments:
In `@packages/worker/src/admin/user-meter-parity.ts`:
- Around line 367-376: The D1 inventory query in the user-meter parity flow must
use the same row cap as the meter walk. Update the query near d1RowsResult to
request userMeterParityInventoryMaxRows + 1 rows, then detect the extra row, set
the comparison’s truncated flag, and limit the rows used for d1Only
classification to the configured cap.

🪄 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: e40289dc-e06c-49cd-a7f9-1a7173c5295b

📥 Commits

Reviewing files that changed from the base of the PR and between f0b00c4 and c44a518.

📒 Files selected for processing (7)

• 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/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/admin/domain.ts
• packages/worker/src/mcp/capabilities/registry.node.test.ts

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/worker/src/admin/user-meter-parity.node.test.ts (1)

265-379: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Add a cross-user isolation test.

Seed a second stableUserId with distinct daily counters, storage, package services, deletion state, and leases. Load the report for each user. Assert that each report contains only that user's state.

The current single-user tests cannot detect a user-scoping error in a D1 query or Durable Object lookup. As per coding guidelines, "**/*: Every signed-in user must have a fully isolated personal assistant, including separate packages, jobs, secrets, values, memories, remote connectors, email inboxes, and durable storage."

🤖 Prompt for 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.

In `@packages/worker/src/admin/user-meter-parity.node.test.ts` around lines 265 -
379, Extend the test around loadAdminUserMeterParityReport with a second
stableUserId and distinct daily, storage, package-service, deletion, and lease
data in both D1 and the meter environment. Load reports for both users and
assert each report’s daily, storage, packageServices, and deletion fields
contain only its own seeded state, including distinct counts, values, and lease
tokens, while preserving the existing secret-safety assertion.

Source: Coding guidelines

🤖 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.

Outside diff comments:
In `@packages/worker/src/admin/user-meter-parity.node.test.ts`:
- Around line 265-379: Extend the test around loadAdminUserMeterParityReport
with a second stableUserId and distinct daily, storage, package-service,
deletion, and lease data in both D1 and the meter environment. Load reports for
both users and assert each report’s daily, storage, packageServices, and
deletion fields contain only its own seeded state, including distinct counts,
values, and lease tokens, while preserving the existing secret-safety assertion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6ca8e38e-17f4-4da4-af9d-0e5ab9289c69

📥 Commits

Reviewing files that changed from the base of the PR and between c44a518 and a6180fc.

📒 Files selected for processing (2)

• packages/worker/src/admin/user-meter-parity.node.test.ts
• packages/worker/src/admin/user-meter-parity.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/worker/src/admin/user-meter-parity.ts