docs: close out legacy migration narratives

[kentcdodds]

Intent

Finish the documentation/comment closeout for the pre-launch legacy elimination program tracked in #1069. Current-operations docs should describe only the final storage and package-authoring contracts.

Summary

• replace completed Mailbox, UserMeter, RunLog projection, and schema rollout diaries with present-tense authority and retention contracts
• delete the stale July 2026 capability/primitive audit and remove its temporal-check exemption
• document deprecated invocation detectors, teaching stubs, publish checks, and codemods as permanent author guardrails
• align UserMeter package-service comments with authoritative DO liveness and D1 enumeration inventory
• clarify that codemod/publish-lint lockstep covers parsed files, while parse failures remain codemod-only manual findings

Testing

• npm run validate — passed on the post-Remove legacy jobs and RunLog observability residue #1215 rebased head (553 test files / 1,855 tests; 7 Playwright E2E tests; docs temporal-language check passed)
• PR CI — passed, including Node, Workers, MCP, E2E, static checks, Cursor Bugbot, CodeRabbit, and the aggregate Validate gate
• main validation — passed after retrying one transient Workerd E2E server crash
• production deploy — passed, including healthcheck, execute smoke, and Vectorize reindex

System changes

System recap — composes existing primitives (low risk)

Mode: recap · Base: main @ 984b2fcc · Head: db4a0e71

Classification: composes — documentation, comments, and teaching copy are aligned with existing runtime contracts; no primitive behavior or schema changes.

Primitives touched

Primitive	Group	Impact
user-meter	storage	composes — documents authoritative counters, liveness, and leases
package-runtime	runtime	composes — labels existing teaching errors as permanent guardrails
package-codemods	assistant	composes — documents permanent repair paths
mcp-server	surfaces	composes — clarifies runtime helper teaching stubs
repo-sessions	runtime	composes — clarifies publish-time rejection
entitlements	auth	composes — removes completed authority-rollout narration

System map

Package source is checked at publish time and repaired through codemods; runtime teaching errors reinforce the same contract. UserMeter documentation reflects the existing split between authoritative DO state and D1 inventory.

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
	repoSessions["repo-sessions<br/>Repo sessions"]:::touched -->|"parsed source publish guard"| packageRuntime["package-runtime<br/>Package runtime"]:::touched
	packageCodemods["package-codemods<br/>Package codemods"]:::touched -->|"source repair plus parse-failure manual findings"| repoSessions
	mcpServer["mcp-server<br/>MCP endpoint (/mcp)"]:::touched -->|"runtime teaching stubs"| packageRuntime
	entitlements["entitlements<br/>Plans & entitlements"]:::touched -->|"authoritative counter and liveness reads"| userMeter["user-meter<br/>User meter"]:::touched
	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

Invariants

• Per-user UserMeter authority and D1 enumeration boundaries are unchanged.
• Unsupported package invocation forms remain rejected at publish time and fail with teaching errors at runtime.
• No migrations or runtime branch changes are included.

Conductor report

STATUS done — PR #1218 squash-merged as 116bfd3b; post-#1215 rebase and final-schema review complete; local npm run validate, PR CI, main validation, and production deploy are green. Remaining work: only the separately deferred migration-history squash.

  

Summary by CodeRabbit

• Documentation
  • Updated architecture and package documentation to reflect current storage, entitlement, liveness, retention, and migration authority.
  • Clarified that unsupported dynamic imports and invocation patterns are permanently rejected, with actionable runtime guidance.
  • Documented current package storage grants, vector search boundaries, mailbox behavior, and codemod repair paths.
  • Removed the historical capability and primitive migration-risk audit.
• Maintenance
  • Updated technical comments and test descriptions to match current behavior; no functional runtime changes were introduced.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request removes a historical audit and updates architecture documentation and code comments to describe finalized storage authorities, Mailbox behavior, UserMeter ownership, and permanent package import and invocation restrictions. Runtime behavior and public declarations remain unchanged.

Changes

Post-migration state alignment

Layer / File(s)	Summary
Storage and entitlement authority documentation docs/contributing/architecture/*.md, docs/contributing/architecture/primitives.yaml, tools/check-docs-temporal-language.ts, packages/worker/src/usage/aggregate-rollups.ts	Storage documentation now reflects UserMeter, Mailbox, RunLog, R2, and dedicated D1 authority. Historical migration, parity, and rollback details were removed.
UserMeter authority terminology packages/worker/src/entitlements/*, packages/worker/src/app/account-usage-data.node.test.ts	Comments and JSDoc now describe authoritative storage usage and liveness state, D1 enumeration inventory, and bootstrap repair behavior.
Static-first package guidance and guards docs/contributing/package-codemods.md, docs/contributing/packages-and-manifests.md, docs/use/packages.md, packages/worker/src/package-*/**, packages/worker/src/mcp/runtime-helper-manifest.ts, packages/worker/src/repo/checks.ts	Documentation and comments now describe permanent rejection of literal dynamic imports, unsupported invocation forms, fail-closed teaching stubs, and codemod repair paths.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• kentcdodds/kody#1217: Established the authority changes documented by this pull request.
• kentcdodds/kody#1045: Introduced related static-first package invocation guidance.
• kentcdodds/kody#1115: Introduced the UserMeter-based entitlement authority described here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% 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 clearly and concisely describes the documentation changes that close out legacy migration narratives.
Description check	✅ Passed	The description includes all required sections and clearly explains the intent, changes, testing, and low-risk system impact.

✨ 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-docs-closeout-62f6

---

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

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

Mocks:

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/package-codemods.md`:
- Around line 167-169: Qualify the lockstep statement in
docs/contributing/package-codemods.md:167-169 to apply only to parsed findings,
unless publish lint is also updated to include parse-failure findings. Update
the collector documentation in
packages/worker/src/package-runtime/deprecated-invocation-usage.ts:7-11 to state
that parsed findings remain aligned while unparseable files produce codemod-only
manual findings.

🪄 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: f3ff287c-b6a2-4511-a3a1-48959635dc93

📥 Commits

Reviewing files that changed from the base of the PR and between e090800 and 5bac5d9.

📒 Files selected for processing (24)

• docs/contributing/architecture/capability-and-primitive-audit-2026-07.md
• docs/contributing/architecture/data-storage.md
• docs/contributing/architecture/entitlements.md
• docs/contributing/architecture/feature-flags.md
• docs/contributing/architecture/primitives.yaml
• docs/contributing/package-codemods.md
• docs/contributing/packages-and-manifests.md
• docs/use/packages.md
• packages/worker/src/app/account-usage-data.node.test.ts
• packages/worker/src/entitlements/d1-storage-reconciliation.ts
• packages/worker/src/entitlements/service.ts
• packages/worker/src/entitlements/user-meter-do.ts
• packages/worker/src/mcp/fetch-gateway.node.test.ts
• packages/worker/src/mcp/runtime-helper-manifest.ts
• packages/worker/src/package-codemods/codemods/0001-ambient-storage-to-package-storage.ts
• packages/worker/src/package-codemods/codemods/0002-static-first-invocation.ts
• packages/worker/src/package-invocations/idempotent-module-invocation.ts
• packages/worker/src/package-runtime/deprecated-invocation-usage.ts
• packages/worker/src/package-runtime/module-graph-import-rewriting.ts
• packages/worker/src/package-runtime/package-app.ts
• packages/worker/src/package-runtime/runtime-source-modules.ts
• packages/worker/src/repo/checks.ts
• packages/worker/src/usage/aggregate-rollups.ts
• tools/check-docs-temporal-language.ts

💤 Files with no reviewable changes (2)

• docs/contributing/architecture/capability-and-primitive-audit-2026-07.md
• tools/check-docs-temporal-language.ts