refactor(account): retire D1 write lease mirror

[kentcdodds]

Summary

• stop writing same-token D1 lease mirrors for UserMeter-authoritative account writes
• retain D1 deleting_at point gate and exact legacy email D1 lease path
• retain admin list/repair support for historical stale D1 rows
• update parity so DO-only leases are expected after mirror retirement

Validation

• npm run validate — passed (1,893 tests)
• targeted deletion/parity suites, typecheck, lint — passed
• Cursor Bugbot + CodeRabbit — passed, no actionable comments

System recap

flowchart LR
  Write[Non-email account write] --> Gate[D1 deleting_at point gate]
  Gate --> Meter[(UserMeter lease authority)]
  Email[Legacy email transition] --> D1[(D1 lease path)]
  Delete[Deletion mark] --> D1
  Delete --> Meter
  Repair[Admin list / repair] --> D1
  Repair --> Meter

Loading

Primitive	Change	Risk
UserMeter lease	Sole lease record for env-supplied writes	Medium
D1 lease table	Legacy email + historical stale rows only	Medium
Deletion parity	DO-only expected; legacy-without-D1 remains a blocker	Low

No D1 table/column retirement in this PR.

Conductor report

• STATUS: merged, deployed, production cleanup complete
• Root cause: request paths intentionally acquired temporary D1 mirrors, then released DO first and ran D1 cleanup in waitUntil; failed/dropped cleanup left D1-only rows. At 20:47Z: 162 unspecified (all >10m), 20 MCP (19 >1h), 1 web from Jul 24. Growth after feat(account): move write-lease authority into UserMeter #1125 confirmed the leak.
• Old-isolate drain: feat(account): move write-lease authority into UserMeter #1125 authority deploy completed 2026-08-01 13:43Z; mirror retirement deployed in main 0d2896a8 at 2026-08-02 03:07Z. No MCP/web D1 rows were acquired after that deploy. One 03:08Z unspecified row remains because it still matches a live DO-authority lease; it was intentionally not repaired.
• Smoke evidence: admin list exposed the exact stale lease; audited repair f777653e-24c3-4808-8e3c-e3432c061360 returned repaired=true; follow-up list confirmed absent. Mark/list/repair behavior is covered by the authoritative test gate; no production deletion mark was run against a real account.
• Cleanup evidence: 190 pre-retirement rows repaired through admin_account_write_lease_repair; 190 succeeded, 0 failed, no raw deletes. Eight affected-user parity reports: d1Only=0, legacyWithoutD1=0, gate failures=0; doOnly=2 active and expected.
• Parity semantics: temporaryMirrorRetired=true; doOnly expected, legacyWithoutD1 remains a gate; d1Only is diagnostic.
• Fleet checkpoint: 39 users at 01:04Z–01:05Z; storage mismatches 0, package running mismatches 0. Two D1-only stopped service rows remain historical/non-authoritative by policy.
• Contract: D1 lease tables/count columns retained; no contraction until legacy email moves and remaining live/stale inventory is clean.
• Coordination: consolidated Discord ship summary posted to the daily GitHub summary channel (message 1533313823166173364).

  

Summary by CodeRabbit

• Changes
  • Retired temporary D1 mirroring for UserMeter-managed leases; Durable Objects are now authoritative.
  • Continued support for legacy email leases and historical D1 records, with audited repair handling.
  • Updated parity reporting and readiness checks to distinguish valid Durable Object-only leases from missing legacy records.
  • Improved account deletion and lease repair handling for missing or stale records, including retries and failure scenarios.
  • Updated architecture, contributor, and capability documentation to reflect the revised lease model.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9500824d-1815-41ad-be22-e33c1107ae0d

📥 Commits

Reviewing files that changed from the base of the PR and between d9bc9ea and 42e6e3b.

📒 Files selected for processing (3)

• docs/contributing/account-write-lease-repair.md
• docs/contributing/architecture/entitlements.md
• packages/worker/src/account/deletion-state.node.test.ts

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

• docs/contributing/account-write-lease-repair.md
• packages/worker/src/account/deletion-state.node.test.ts
• docs/contributing/architecture/entitlements.md

---

📝 Walkthrough

Walkthrough

The PR retires temporary D1 lease mirroring for UserMeter and Durable Object authority. It preserves legacy D1 leases and audited repairs, updates parity rules, and revises related tests and documentation.

Changes

Lease mirror retirement

Layer / File(s)	Summary
Remove DO lease mirroring packages/worker/src/account/deletion-state.ts, packages/worker/src/account/user-owned-surfaces.ts	UserMeter-authority leases no longer write or release temporary D1 mirror rows. Repair cleanup still occurs after confirmed Durable Object finalization.
Validate deletion and repair behavior packages/worker/src/account/deletion-state.node.test.ts	Tests cover absent mirrors, legacy-only D1 results, deferred release, and stale-row handling across successful, lost, and failed finalization.
Update parity reporting packages/worker/src/admin/user-meter-parity.ts, packages/worker/src/admin/user-meter-parity.node.test.ts, packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.ts	Parity reports mark the mirror as retired. DO-only leases pass parity, while legacy leases without D1 rows and truncated inventories fail readiness.
Align documentation and integration tests docs/contributing/account-write-lease-repair.md, docs/contributing/architecture/entitlements.md, packages/worker/src/community/community-icon.node.test.ts, packages/worker/src/mcp/memory/service.node.test.ts	Documentation describes split lease authority and repair rules. Race and acknowledgement tests remove obsolete mirror assumptions.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• kentcdodds/kody#1115: Introduced the UserMeter lease behavior that this PR updates.
• kentcdodds/kody#1123: Modified the same deletion-state and UserMeter lease-shadow paths.
• kentcdodds/kody#1128: Introduced parity logic updated for the retired D1 mirror.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Title check	✅ Passed	The title clearly and concisely describes the main change: retiring the D1 write-lease mirror.
Description check	✅ Passed	The description explains the intent, summarizes the changes, documents validation, and includes system impact and risk details.
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.

✨ 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.}

[github-actions]

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

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

Mocks:

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

[coderabbitai]

🧹 Nitpick comments (1)

packages/worker/src/account/deletion-state.node.test.ts (1)

1266-1283: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract a shared helper for seeding a stale pre-retirement D1 lease row. Three tests duplicate the same raw-SQL sequence (insert into account_write_leases, then increment active_write_count), differing only in the holder value. One shared helper removes this duplication and keeps the seeding logic in one place if the schema changes.

• packages/worker/src/account/deletion-state.node.test.ts#L1266-L1283: replace the manual INSERT INTO account_write_leases / UPDATE users SET active_write_count block with a call to a new helper, e.g. insertStaleD1LeaseRow(sqlite, { token: held.token, userId: 'user-a', holder: 'test:repair-finalize-stale', acquiredAt: held.acquiredAt }).
• packages/worker/src/account/deletion-state.node.test.ts#L1344-L1358: replace the equivalent block with the same helper, passing holder: 'test:stale-mirror-after-finalize'.
• packages/worker/src/account/deletion-state.node.test.ts#L1438-L1452: replace the equivalent block with the same helper, passing holder: 'test:finalize-fail-closed'.

🤖 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/account/deletion-state.node.test.ts` around lines 1266 -
1283, Extract an insertStaleD1LeaseRow helper in
packages/worker/src/account/deletion-state.node.test.ts that performs the
account_write_leases insert and active_write_count increment, then replace the
duplicated SQL at lines 1266-1283, 1344-1358, and 1438-1452 with helper calls
using each test’s existing token, userId, acquiredAt, and holder values:
test:repair-finalize-stale, test:stale-mirror-after-finalize, and
test:finalize-fail-closed.

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

Nitpick comments:
In `@packages/worker/src/account/deletion-state.node.test.ts`:
- Around line 1266-1283: Extract an insertStaleD1LeaseRow helper in
packages/worker/src/account/deletion-state.node.test.ts that performs the
account_write_leases insert and active_write_count increment, then replace the
duplicated SQL at lines 1266-1283, 1344-1358, and 1438-1452 with helper calls
using each test’s existing token, userId, acquiredAt, and holder values:
test:repair-finalize-stale, test:stale-mirror-after-finalize, and
test:finalize-fail-closed.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6f527296-c0df-4b49-ab9a-97b9916f3c51

📥 Commits

Reviewing files that changed from the base of the PR and between 1db61e5 and d9bc9ea.

📒 Files selected for processing (10)

• docs/contributing/account-write-lease-repair.md
• docs/contributing/architecture/entitlements.md
• packages/worker/src/account/deletion-state.node.test.ts
• packages/worker/src/account/deletion-state.ts
• packages/worker/src/account/user-owned-surfaces.ts
• packages/worker/src/admin/user-meter-parity.node.test.ts
• packages/worker/src/admin/user-meter-parity.ts
• packages/worker/src/community/community-icon.node.test.ts
• packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.ts
• packages/worker/src/mcp/memory/service.node.test.ts