[kentcdodds]

Intent

Close the remaining storage-document residue identified after #1218 and #1219 for the pre-launch legacy elimination program tracked by #1069.

Summary

• describe USER email export as Mailbox-only without obsolete D1 compatibility rows
• state cursor-version compatibility as a current contract without rollout chronology
• remove completed-migration negative framing from Mailbox retention and the users schema
• document the provider reverse index by its final operational shape, without migration provenance

Testing

• npm run validate — passed (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, preview deployment, and CodeRabbit
• main validation — passed
• production deploy — passed, including healthcheck, execute smoke, and Vectorize reindex

System changes

System recap — composes existing primitives (low risk)

Mode: recap · Base: main @ 616573c4 · Head: 51f1c412

Classification: composes — one architecture document now states existing Mailbox, R2 cursor, export, and provider-index contracts without migration chronology; no primitive behavior changes.

Primitives touched

Primitive	Group	Impact
mailbox	storage	composes — final USER email authority wording
email-blobs-r2	storage	composes — current cursor compatibility contract
d1-app-db	storage	composes — final provider-index shape

System map

USER email export flows through Mailbox, with R2 object cursors for bytes and D1 limited to the operational provider reverse index.

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
	mailbox["mailbox<br/>Mailbox"]:::touched -->|"authoritative USER email export"| emailBlobs["email-blobs-r2<br/>Email blobs R2"]:::touched
	d1["d1-app-db<br/>D1 app database"]:::touched -->|"provider-message reverse lookup only"| mailbox
	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

• Mailbox/R2 remains the sole USER email graph authority.
• Runtime behavior, schemas, migrations, and cursor behavior are unchanged.

Conductor report

STATUS done — PR #1220 squash-merged as bbece08f; local validation, PR CI, main validation, and production deploy are green. Remaining work: only the separately deferred migration-history squash.

  

Summary by CodeRabbit

• Documentation
  • Updated data storage guidance to identify Mailbox as the authoritative source for user email data and exports.
  • Clarified export behavior, cursor version requirements, retention reporting, and operator mail handling.
  • Expanded provider-message reverse-lookup documentation and tightened architecture guidance around production data references.

[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: 6470c12d-1068-4d3c-8e73-9d276f54be6a

📥 Commits

Reviewing files that changed from the base of the PR and between 616573c and 51f1c41.

📒 Files selected for processing (1)

• docs/contributing/architecture/data-storage.md

---

📝 Walkthrough

Walkthrough

The storage architecture documentation now defines Mailbox as the authoritative USER email graph and export source. It also updates R2 traversal, production D1 restrictions, retention output, operator mail placement, and provider-message reverse-lookup details.

Changes

Mailbox authority and storage contracts

Layer / File(s)	Summary
Mailbox authority and export rules docs/contributing/architecture/data-storage.md	The documentation identifies Mailbox as the sole USER email graph export source, requires R2 version-1 cursor restarts, prohibits production D1 references to USER graph tables, and removes the users-table parity statement.
Retention and provider index contracts docs/contributing/architecture/data-storage.md	USER retention now returns Mailbox counts and email-content-free results. Operator mail remains outside per-user Mailbox objects. The provider-message reverse-lookup schema now includes ownership fields, indexes, and its opaque message identifier.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• kentcdodds/kody#1139: Documents the Mailbox authority and retention model.
• kentcdodds/kody#1153: Introduces the documented outbound provider-message reverse index.
• kentcdodds/kody#1194: Removes Mailbox parity columns and retired D1-to-Mailbox bootstrap behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the removal of remaining storage cutover residue, which matches the documentation-only changes.
Description check	✅ Passed	The description includes intent, summary, testing, and system changes, and it accurately matches the documentation-only scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

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

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

Mocks:

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