docs: ADR 0002 — data-placement rubric (D1 / per-user DO / Analytics Engine)

[kentcdodds]

What

Records the data-placement rubric decided during the July 2026 scalability review as decision record docs/contributing/decisions/0002-data-placement.md:

• Context: the shared D1 (APP_DB) is the scaling bottleneck (global single writer, shared 10 GB cap); the audit found awaited per-call D1 writes on hot paths (entitlement counter upserts, withAccountWriteLease fencing, activation upserts, workflow_runs projections, uncached plan read in assertWithinEntitlement); precedent existed in the RunLog DO move (migrations 0099/0112).
• Decision: the rubric — D1 when data is found by something other than the owner's userId, spans entities/tables, is cached low-write config, needs fleet-wide queries, or is a cross-user enumeration/deletion index; a per-user Durable Object when data is high-write, userId-addressed, owner-local, read on the owner's own path; Analytics Engine for append-only reporting-grade telemetry within AE's retention window; R2/KV/Vectorize homes unchanged. Plus the five forces (lookup direction, transactional boundaries, read topology, serialization, operations) and the standing rules (budget justification for new awaited hot-path D1 writes, deletion/export coverage in the same move, admin cross-user SELECT redesign in the same change, per-user isolation held in every storage home).
• Consequences: the concrete placements (per-user meter DO, RunLog DO consolidation, AE reporting, separate audit D1, Vectorize per-user namespaces, mailbox DO second wave) and what deliberately stays in D1.

Notes for review

• The task brief assumed no ADR directory existed and proposed docs/contributing/architecture/decisions/0001-.... The repo already has an ADR system at docs/contributing/decisions/ (template, index, numbering, temporal-check exemption in tools/check-docs-temporal-language.ts), so this record lands there as 0002 instead of creating a parallel directory. The existing index already documents the naming convention.
• Linked from docs/contributing/architecture/index.md (Data Storage bullet) and the decisions index.
• npm run primitives:check needs no change: it validates that paths listed in primitives.yaml resolve; new docs don't require registration and this PR reshapes no primitive.
• Docs only; no code changes. Sibling tracks implement the placements concurrently.
• Review feedback addressed: added the per-user isolation standing rule (CodeRabbit's one actionable comment).

System recap — composes existing primitives (low risk, docs only)

Mode: recap · Base: main @ 915db38 · Head: 5050df9

Classification: composes — documentation-only change; the classifier matches no primitive code roots and no primitive is added or reshaped. The ADR documents placement rules for existing storage primitives.

Primitives touched

Primitive	Group	Impact
(none)	—	docs only — ADR 0002 + two index links

System map

The ADR records which storage primitive each kind of data belongs to; all nodes are unchanged context.

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
	adr["ADR 0002<br/>Data placement record"]:::touched
	d1AppDb["d1-app-db<br/>D1 app database"]:::untouched
	durableStorage["durable-storage<br/>Durable storage buckets"]:::untouched
	usageMetering["usage-metering<br/>Usage metering"]:::untouched
	vectorizeSearch["vectorize-search<br/>Vectorize search"]:::untouched
	adr -->|"stays: identity/config/indexes; rule: budget-justified hot-path writes"| d1AppDb
	adr -->|"moves: counters, fencing, run history, milestones to per-user DOs"| durableStorage
	adr -->|"moves: reporting aggregates to Analytics Engine"| usageMetering
	adr -->|"confirms: per-user namespaces + userId metadata"| vectorizeSearch
	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

Conductor report

• STATUS: done
• What shipped: ADR 0002 (docs/contributing/decisions/0002-data-placement.md) capturing the data-placement rubric (D1 vs per-user Durable Objects vs Analytics Engine, with R2/KV/Vectorize homes), the five forces, standing rules (including per-user isolation from review feedback), and the concrete placements; linked from the decisions index and the architecture index.
• Deviation from brief: the repo already had an ADR directory at docs/contributing/decisions/ (template, index, ADR 0001), so this landed there as 0002 instead of creating docs/contributing/architecture/decisions/0001-.... That directory is also the one exempted from docs:check-temporal, which point-in-time ADRs require. npm run primitives:check needed no change.
• Risk: low — docs-only, no code or primitive changes.
• Merged/deployed: yes — squash-merged as 96b41d9; production deploy succeeded (deploy run). npm run validate green locally; all CI checks green.
• Scope spill: none — no sibling-owned files touched; data-storage.md untouched (only the architecture index gained a link).

  

Summary by CodeRabbit

• Documentation
  • Added an architecture decision record documenting data-storage placement across supported storage services.
  • Documented criteria, scalability considerations, operational guidance, data assignments, and conditions for revisiting the decision.
  • Linked the new decision record from the architecture documentation and decision index.

[coderabbitai]

Warning

Review limit reached

@cursor[bot], you've reached your PR review limit, so we couldn't start this review.

Next review available in: 52 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 71cb6ff6-a71d-4486-8f94-f2d59772f7c4

📥 Commits

Reviewing files that changed from the base of the PR and between 12abfe8 and 5050df9.

📒 Files selected for processing (1)

• docs/contributing/decisions/0002-data-placement.md

📝 Walkthrough

Walkthrough

This change adds ADR 0002 for data placement across storage systems. It documents placement criteria, concrete assignments, operational guardrails, and revisit conditions. The architecture and ADR indexes now link to the new decision record.

Changes

Data placement documentation

Layer / File(s)	Summary
Define data placement rules docs/contributing/decisions/0002-data-placement.md	Adds ADR 0002 with storage criteria, placement assignments, operational rules, retained D1 responsibilities, accepted costs, and revisit conditions.
Index the decision docs/contributing/architecture/index.md, docs/contributing/decisions/index.md	Links the data-placement ADR from the Data Storage architecture entry and the decision-record index.

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

Possibly related PRs

• kentcdodds/kody#1108: Adds and indexes architecture decision records that this ADR system extends.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies ADR 0002 and its data-placement rubric, which matches the primary documentation change.
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/adr-data-placement-1f96

---

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

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

Mocks:

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

[cursor]

@coderabbitai review

[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/decisions/0002-data-placement.md`:
- Around line 34-44: Update the data-placement ADR to add a standing per-user
isolation rule covering packages, jobs, secrets, values, memories, remote
connectors, email inboxes, and durable storage: all reads and writes must be
scoped by userId and reject cross-user access. State that only documented
operator/admin indexes and reporting aggregates may be cross-user, and link to
the existing data-storage.md contract for the full isolation model.

🪄 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: cf55ee52-ab8f-4e45-b89c-8ce64fb188f1

📥 Commits

Reviewing files that changed from the base of the PR and between 915db38 and 12abfe8.

📒 Files selected for processing (3)

• docs/contributing/architecture/index.md
• docs/contributing/decisions/0002-data-placement.md
• docs/contributing/decisions/index.md