docs(planning): add April milestone plan with workstream priorities

[wmadden]

Intent

Create a detailed plan for the April "Ready for external contributors" milestone which gives each workstream owner a clear mandate: what architectural assumptions to validate, how to know when they're done, and when to stop. The plan is structured around priority-ordered validation points (VPs) with user stories, concrete tasks, and explicit stop conditions — designed to prevent scope creep and help us fight the urge to polish or perfect our work.

The story

1. Establish the "architectural validation, not polish" framing. Five weeks, six independent workstreams, each with a single owner. The goal is to prove design decisions hold under real conditions, not to perfect the user experience.

2. Define validation points for each workstream. Each VP identifies an architectural assumption, describes a user story that would prove it, lists tasks, and defines a stop condition. Work proceeds top-down within each workstream.

3. Migration system (3 VPs). Data migrations with invariant-aware routing (highest risk — the graph model's route equivalence breaks when data matters), manual migration authoring with scaffold commands, and a large-contract scaling test.

4. Contract authoring (3 VPs). Symmetric PSL/TS surfaces from shared ADR 170 composition, TS DSL terseness parity with PSL, and invisible contract emission via build tool plugins.

5. Runtime pipeline (4 VPs + benchmarks side quest). Transactions with SQL DSL interop, extension-contributed operations through both query surfaces (with shared codec trait gating from PR feat: Introduce codec trait system #247), RSC concurrency safety, and middleware request rewriting.

6. MongoDB PoC (1 VP as vertical slice). Sequential discovery phases testing the entire stack against a document database — contract surface, authoring, emit, codecs, runtime, ORM with a shared interface. Framed as exploratory since the task breakdown will evolve.

7. SQLite (2 VPs). End-to-end vertical slice through all stack layers against a second SQL target, plus an optional D1 extensibility architectural check.

8. Contributor readiness (1 VP). Example extensions, API reference, getting-started guide, and dev relations handoff — validating that someone outside the team can actually build an extension using only published docs.

Documents added

• docs/planning/april-milestone.md — the milestone plan with six workstreams, validation points, and stop conditions
• docs/planning/0-references/framework-integration-analysis.md — analysis of hard integration problems for popular frameworks
• docs/planning/0-references/community-generator-migration-analysis.md — mapping of 33 Prisma ORM community generators to Prisma Next extension capabilities
• docs/planning/0-references/data-migrations.md — theoretical model for data migrations as guarded transitions
• docs/planning/0-references/data-migrations-solutions.md — potential solutions for data migration routing
• docs/planning/mongo-target/mongodb-primitives-reference.md — MongoDB primitives reference for the PoC

Compatibility / migration / risk

None — documentation only, no code changes.

Non-goals / intentionally out of scope

• Weekly timeline (replaced by priority-ordered task queues per workstream)
• Task estimation or time budgets
• Implementation — this PR is planning artifacts only

Summary by CodeRabbit

• Documentation
  • Added data migration model and implementation documentation
  • Added framework integration analysis for Prisma Next architecture
  • Added MongoDB primitives reference and PoC planning guide
  • Added April milestone planning with validation points and workstreams
  • Added community generator migration analysis and inventory reference

[coderabbitai]

📝 Walkthrough

Walkthrough

Seven new documentation files added covering strategic planning, design specifications, architectural analysis, and reference materials for data migrations, framework integration, community generators, MongoDB support, and April milestone objectives.

Changes

Cohort / File(s)	Summary
Planning & Milestones docs/planning/april-milestone.md	Defines April milestone goals with validation-first approach across six workstreams (migrations, contracts, runtime, MongoDB PoC, SQLite, contributor readiness), each with architectural validation points and ownership assignments.
Data Migrations docs/planning/0-references/data-migrations.md, docs/planning/0-references/data-migrations-solutions.md	Theory document defining data migrations as guarded transitions with invariants; solutions document specifying schema-compatibility checks, ownership models, integration patterns, routing behavior, and CLI semantics.
Architecture Analysis docs/planning/0-references/community-generator-migration-analysis.md, docs/planning/0-references/framework-integration-analysis.md	Generator inventory and migration analysis covering 37 community generators across 9 use-case families with categorization matrix; framework integration analysis covering connection management, RSC concurrency, streaming composition, build-tool contract emit, and integration patterns.
MongoDB Target docs/planning/mongo-target/mongo-poc-plan.md, docs/planning/mongo-target/mongodb-primitives-reference.md	MongoDB PoC plan defining scope, required components, and implementation sequence; primitives reference cataloging MongoDB data models, BSON types, indexes, CRUD operations, aggregation pipelines, and SQL/MongoDB concept mappings.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

📖 Seven scrolls unfurled with care and thought,
Planning threads in patterns tautly wrought,
Data flows and frameworks sketched ahead,
MongoDB whispers in the reference thread,
A rabbit hops through april's mapped-out way, 🐰
Where validation points illuminate the day.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the main change: adding an April milestone plan document with workstream priorities, which is the primary addition in this PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch planning

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@prisma-next/runtime-executor

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/runtime-executor@262

@prisma-next/sql-runtime

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-runtime@262

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-paradedb@262

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/extension-pgvector@262

@prisma-next/postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/postgres@262

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-orm-client@262

@prisma-next/contract-authoring

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract-authoring@262

@prisma-next/contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract-ts@262

@prisma-next/ids

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/ids@262

@prisma-next/psl-parser

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/psl-parser@262

@prisma-next/cli

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/cli@262

@prisma-next/emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/emitter@262

@prisma-next/eslint-plugin

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/eslint-plugin@262

@prisma-next/migration-tools

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/migration-tools@262

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/vite-plugin-contract-emit@262

@prisma-next/sql-contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract@262

@prisma-next/sql-errors

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-errors@262

@prisma-next/sql-operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-operations@262

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-schema-ir@262

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-psl@262

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-ts@262

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-contract-emitter@262

@prisma-next/family-sql

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/family-sql@262

@prisma-next/sql-kysely-lane

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-kysely-lane@262

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane-query-builder@262

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-relational-core@262

@prisma-next/sql-lane-sql-builder-new

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane-sql-builder-new@262

@prisma-next/sql-lane

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/sql-lane@262

@prisma-next/target-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/target-postgres@262

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/adapter-postgres@262

@prisma-next/driver-postgres

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/driver-postgres@262

@prisma-next/core-control-plane

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/core-control-plane@262

@prisma-next/core-execution-plane

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/core-execution-plane@262

@prisma-next/config

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/config@262

@prisma-next/contract

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/contract@262

@prisma-next/operations

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/operations@262

@prisma-next/plan

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/plan@262

@prisma-next/utils

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/utils@262

commit: 3342766

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/planning/april-milestone.md (1)

13-13: Reduce repeated sentence starts for readability.

Three consecutive “Each ...” starts make this paragraph feel repetitive; consider varying one or two sentence openings.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/planning/april-milestone.md` at line 13, The paragraph starts three
sentences with "Each" which reads repetitively; reword one or two sentences to
vary openings while preserving meaning: keep the first sentence as "Each
workstream is roughly independent..." but change the second to something like
"Workstreams have a priority-ordered queue of validation points (VP)," and the
third to "A VP identifies an architectural assumption to test, describes a user
story that would prove it, lists concrete tasks, and defines a stop condition."
Also consider combining the final instructions about work order and assisting
others into one sentence to improve flow; update references to "VP" and "stop
condition" exactly as currently named.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/planning/april-milestone.md`:
- Line 215: Update the comparison line "Comparative benchmark suite (Prisma Next
vs Prisma ORM vs raw driver)" to explicitly name the shared benchmark axis (for
example: "Prisma Next vs Prisma ORM vs raw driver — p95 latency", or "—
throughput (req/sec)", or "— memory usage (RSS)"), so the comparison is
unambiguous and follows the guideline that comparisons must state the shared
axis; modify the wording in the same line in docs/planning/april-milestone.md to
include the chosen axis and any units.

---

Nitpick comments:
In `@docs/planning/april-milestone.md`:
- Line 13: The paragraph starts three sentences with "Each" which reads
repetitively; reword one or two sentences to vary openings while preserving
meaning: keep the first sentence as "Each workstream is roughly independent..."
but change the second to something like "Workstreams have a priority-ordered
queue of validation points (VP)," and the third to "A VP identifies an
architectural assumption to test, describes a user story that would prove it,
lists concrete tasks, and defines a stop condition." Also consider combining the
final instructions about work order and assisting others into one sentence to
improve flow; update references to "VP" and "stop condition" exactly as
currently named.

🪄 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: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: c00f0b3e-a17a-40ac-9d5a-6b47a6965d8a

📥 Commits

Reviewing files that changed from the base of the PR and between d508653 and 3342766.

📒 Files selected for processing (1)

• docs/planning/april-milestone.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

State the benchmark axis explicitly in the comparison line.

“Prisma Next vs Prisma ORM vs raw driver” should name the shared axis (e.g., p50/p95 latency, throughput, memory, cold-start) so the comparison is unambiguous and consistent with docs standards.

As per coding guidelines, “Comparisons must state the shared axis (knob, invariant, or trade-off) when written”.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/planning/april-milestone.md` at line 215, Update the comparison line
"Comparative benchmark suite (Prisma Next vs Prisma ORM vs raw driver)" to
explicitly name the shared benchmark axis (for example: "Prisma Next vs Prisma
ORM vs raw driver — p95 latency", or "— throughput (req/sec)", or "— memory
usage (RSS)"), so the comparison is unambiguous and follows the guideline that
comparisons must state the shared axis; modify the wording in the same line in
docs/planning/april-milestone.md to include the chosen axis and any units.