feat(entitlements): reap remaining authority narrows

[kentcdodds]

Intent

Close the remaining pre-launch UserMeter entitlement narrows from #1069 so no runtime or documentation presents D1 as a package-service liveness or account-write-lease authority.

Summary

• remove D1 package-service liveness counting and D1↔UserMeter liveness parity
• add migration 0141 to drop the retired D1 lease table and delete two stale feature flags while retaining the repair audit log
• upgrade UserMeter to schema v8 and rebuild warm lease tables without the unreferenced authority column
• rename account-export state fields from transitional *Shadow names to authoritative names
• rewrite entitlement contract docs around the final authority model

Testing

• npm run validate — passed
• 555 Node/Workers test files, 1,868 tests — passed
• 7 Playwright tests and 3 MCP tests — passed
• Focused reviewer-fix suites: 25 tests — passed
• Typecheck, format, lint, builds, migration ledger, temporal docs, and primitive map checks — passed
• Main validation — passed
• Production deploy — passed; migration 0141 applied

System changes

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ 6a77bf08 · Head: 989b9370

Classification: extends — this PR narrows persisted schemas and exported/admin contracts without adding a primitive.

Primitives touched

Primitive	Group	Impact
user-meter	storage	extends — schema v8 removes the physical lease authority column
d1-app-db	storage	extends — migration 0141 drops the retired lease table and stale flags
entitlements	auth	extends — UserMeter becomes the only package-service liveness read
account-export	assistant	extends — authoritative state fields replace *Shadow names
rbac	auth	extends — admin verification no longer exposes D1 liveness parity

System map

Entitlement enforcement and account export read authoritative UserMeter state; D1 retains payload recomputation, enumeration inventories, deletion tombstones, and repair audit data only.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	entitlements["entitlements<br/>Plans & entitlements"]:::extended
	userMeter["user-meter<br/>User meter"]:::extended
	accountExport["account-export<br/>Account data export"]:::extended
	rbac["rbac<br/>Role-based access control"]:::extended
	d1AppDb["d1-app-db<br/>D1 app database"]:::extended
	entitlements -->|"sole package-service running-count RPC"| userMeter
	accountExport -->|"storageBytesState, packageServiceStates, deletionState"| userMeter
	rbac -->|"admin storage/deletion verification only"| userMeter
	userMeter -->|"physical recompute, tombstone, repair audit; no liveness or lease mirror"| d1AppDb
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Before / after

Boundary	Before	After
Package-service liveness	UserMeter authority plus D1 parity/rollback apparatus	UserMeter-only reads; D1 enumeration only
D1 write leases	Quiescent table retained	Table dropped; repair audit retained
UserMeter lease schema	Warm v7 objects may retain authority	v8 rebuild preserves leases without authority
Account export	storageBytesShadow, packageServiceStatesShadow, deletionShadow	storageBytesState, packageServiceStates, deletionState

Invariants

Per-user Durable Object isolation remains unchanged: each stable user id maps to one UserMeter object, and the v8 rebuild runs inside that object's serialized initialization.

Conductor report

STATUS done — PR #1217 squash-merged as b9f83a33; local validate, AI review, and main CI are green; production deploy applied migration 0141 and deployed Worker version 223c78c5-0618-4050-af66-5b070a4e2234; production admin_feature_flag_list returns only demo-indicator, with no stale flags or overrides. Remains: none for this track.

  

Summary by CodeRabbit

• New Features

  • UserMeter is now the authoritative source for storage, deletion, package-service status, daily counters, and account write leases.
  • Account exports now present authoritative state using updated field names.
  • Added migration support to remove obsolete lease storage and retired feature flags.

• Bug Fixes

  • Improved schema migration behavior while preserving active leases and repair audit records.

• Documentation

  • Updated architecture, contribution, export, and administration documentation to reflect the updated authority model.

[coderabbitai]

📝 Walkthrough

Walkthrough

UserMeter is now authoritative for account-write leases, package-service liveness, storage bytes, and deletion state. Migration 0141 removes obsolete D1 lease storage and flags. Exports, parity reports, tests, and architecture documentation now use the authoritative model.

Changes

UserMeter authority migration

Layer / File(s)	Summary
Schema and lease cleanup packages/worker/migrations/..., packages/worker/src/entitlements/user-meter-do.ts, packages/worker/src/entitlements/*test.ts, tools/migration-ledger.json	Migration 0141 removes D1 lease storage and retired flags. UserMeter schema v8 removes the legacy authority column and preserves active leases.
Authoritative export contract packages/worker/src/entitlements/user-meter-do.ts, packages/worker/src/account/*, packages/worker/src/test-support/user-meter.ts, packages/worker/src/users-test-schema.ts	Exports use storageBytesState, packageServiceStates, and deletionState. D1 lease export targets and test-schema creation are removed.
Liveness and parity authority packages/worker/src/entitlements/service.ts, packages/worker/src/admin/*, packages/worker/src/mcp/capabilities/admin/*	D1 package-service counting and package-service parity reporting are removed. UserMeter remains the liveness authority.
Architecture contracts docs/contributing/architecture/*, docs/contributing/account-write-lease-repair.md	Documentation describes UserMeter authority, D1 enumeration roles, schema v8, sanitized deletion state, and updated parity rules.

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

Possibly related PRs

• kentcdodds/kody#1115: Earlier UserMeter authority work across entitlement and export paths.
• kentcdodds/kody#1128: Introduced the admin UserMeter parity functionality changed here.
• kentcdodds/kody#1201: Initiated the write-lease schema and authorization cutover completed here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.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
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.
Title check	✅ Passed	The title directly describes the main change: reaping remaining authority narrows from a prior issue, which aligns with closing D1 authority gaps in the UserMeter entitlements system.
Description check	✅ Passed	The description follows the template with complete Intent, Summary, and Testing sections. It includes all required information plus detailed System changes with visual diagrams and invariant documentation.

✨ 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/reap-entitlements-8567

---

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

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

Mocks:

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/worker/src/entitlements/account-write-lease-cleanup-migration.node.test.ts (1)

67-74: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Assert repair-audit row retention.

Lines 67-74 only prove that account_write_lease_repairs exists. Insert a valid repair row before migration 0141 and assert that it remains afterward. This verifies retained audit history and detects foreign-key action or cascade behavior caused by dropping account_write_leases.

🤖 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/entitlements/account-write-lease-cleanup-migration.node.test.ts`
around lines 67 - 74, Extend the migration test around the existing
account_write_lease_repairs table assertion by inserting a valid repair-audit
row before migration 0141 runs, then query the table afterward and assert that
the row is still present. Use the schema’s required fields and valid references,
and retain the existing table-existence assertion to verify both table creation
and audit-row preservation.

🤖 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/account/export.ts`:
- Around line 310-313: Update the documentation for the storageBytesState field
in the user-meter export result to state that the first page provides the
authoritative state and later pages include the property with a null value,
rather than omitting it. Keep the existing type and paging semantics unchanged.

---

Nitpick comments:
In
`@packages/worker/src/entitlements/account-write-lease-cleanup-migration.node.test.ts`:
- Around line 67-74: Extend the migration test around the existing
account_write_lease_repairs table assertion by inserting a valid repair-audit
row before migration 0141 runs, then query the table afterward and assert that
the row is still present. Use the schema’s required fields and valid references,
and retain the existing table-existence assertion to verify both table creation
and audit-row preservation.

🪄 Autofix

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: ef3b655f-a8b9-41ee-87bb-1848968f7cb2

📥 Commits

Reviewing files that changed from the base of the PR and between 6a77bf0 and d949fa3.

📒 Files selected for processing (23)

• docs/contributing/account-write-lease-repair.md
• docs/contributing/architecture/data-storage.md
• docs/contributing/architecture/entitlements.md
• docs/contributing/architecture/primitives.yaml
• docs/contributing/architecture/run-records.md
• packages/worker/migrations/0141-drop-account-write-leases-and-stale-flags.sql
• packages/worker/src/account/data-targets.ts
• packages/worker/src/account/deletion-state.node.test.ts
• packages/worker/src/account/export.node.test.ts
• packages/worker/src/account/export.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/entitlements/account-write-lease-cleanup-migration.node.test.ts
• packages/worker/src/entitlements/package-service-states.workers.test.ts
• packages/worker/src/entitlements/service.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-user-meter-parity.node.test.ts
• packages/worker/src/mcp/capabilities/admin/admin-user-meter-parity.ts
• packages/worker/src/test-support/user-meter.ts
• packages/worker/src/users-test-schema.ts
• tools/migration-ledger.json

💤 Files with no reviewable changes (2)

• packages/worker/src/account/data-targets.ts
• packages/worker/src/entitlements/package-service-states.workers.test.ts