orm/projects/facade-import-surface-completion · pr/orm

GGitHubTML-3483: Give each ADR merged since late September its own number (#30619)

文件	最后提交记录	最后更新时间
dispatches	feat: an application depends on one Prisma package (ADR 242) (#29864) ## What changes for someone using Prisma Today, an application that talks to Postgres installs a long list of our packages: ```jsonc { "dependencies": { "@prisma-next/postgres": "...", "@prisma-next/sql-runtime": "...", "@prisma-next/sql-orm-client": "...", "@prisma-next/target-postgres": "...", "@prisma-next/adapter-postgres": "...", "@prisma-next/sql-contract": "..." // ...a dozen more } } ``` After this PR, it installs one: ```jsonc { "dependencies": { "@prisma/orm-postgres": "0.16.0" } } ``` Everything else arrives as that package's own dependencies. Three of our example apps are converted in this PR to prove it — one per database — and each has exactly one Prisma package in its `dependencies`. This implements [ADR 242](https://github.com/prisma/prisma/pull/29852), which is already merged. ## What gets published 17 packages, all under the `@prisma` scope: - 3 database packages — `@prisma/orm-postgres`, `orm-sqlite`, `orm-mongo`. An application installs exactly one. We call these facades: each is a small package that wires its database together and re-exports everything an application needs. - 6 extension packs — PostGIS, pgvector, ParadeDB, Supabase, arktype-json, middleware-cache. Optional, installed alongside a database package. - 7 platform packages — the framework, the toolchain, one per database family, one per database target. Applications never install these directly; they arrive as dependencies. Extension authors do install them. - the `prisma` command, as a bin-only package. Every other workspace package — around 50 of them — stops being published. They still exist in the repo as the unit we organise code in; they just stop having a life on the registry. This PR does not make that switch yet. It builds and proves the new surface while leaving today's publish list exactly as it is. Flipping it is a separate change. ## The problem this design has to avoid A published package can't depend on packages that won't exist on the registry. So each published package contains a compiled copy of the internal packages it covers. That creates a trap. If one application ends up with the same code twice — once inside a published package, once as its own package — then classes, registries, and anything compared by reference exist twice too. An `instanceof` check quietly returns false. Nothing crashes, nothing fails to compile, and both copies behave identically in isolation. You find out much later, somewhere unrelated. So the rule the whole design follows is: every piece of internal code is published from exactly one package. Concretely, that means: - Each published package is built in one pass, so code shared between its own entry points exists once. Verified from the build's source maps: no module appears in more than one chunk, in any published package. - When one published package needs code from another, it imports it as a real dependency rather than compiling in a second copy. - A facade re-exports from the platform packages; it never carries its own copy. `@prisma/orm-postgres/orm-client` and `@prisma/orm-family-sql/orm-client` are two names for the same object, and there's a test that asserts exactly that from installed tarballs. - One table in `packages/0-shared/publish-surface` maps every internal package to where it's published. The build, the code generator, and the lint checks all read it, so there's one answer to "where does this live" rather than three that can drift. ## Generated code follows the application Prisma writes imports into your project — contract types and migration files. Those imports have to name packages your project actually depends on, or they won't resolve. So the generator now reads the `package.json` next to the config it's generating for. A project that depends on `@prisma/orm-postgres` gets imports from that package. A project on today's names keeps today's names. Nothing to configure, because the manifest already says which it is. Contract hashes are unaffected, and that isn't an assumption — hashes are computed from a structure that import text never enters, and there's a test asserting the hash is identical across naming schemes while the emitted imports demonstrably differ. ## What stops the trap coming back Two checks, because the failure is silent and won't show up in a test suite: - Every example app and test project must use one naming scheme, not a mix. `lint-single-import-root` scans them and fails the build if any project imports from both, since that's the situation that loads code twice. - `lint-consumer-internal-imports` counts how many internal-package imports remain in those projects and compares against a committed number. It fails if the number goes up (someone added one) and also if it goes down without the number being updated (so improvements get locked in). Target is zero. The build itself also refuses to proceed if the published-package map would put one module in two places, or if a published package's `package.json` no longer matches what its code actually needs. ## Reading this PR It's large — 257 files — because it's a migration. The commits are grouped and meant to be read in order: 1. Platform packages — the build mechanism, and the seven platform packages it produces. 2. Database packages, extension packs, the `prisma` command — completes the set of 17. 3. Generated imports become configurable — one place decides which names get written, with today's names still the default. 4. Database-family symmetry, publishing the map, the identity checks. 5. One package per application — the three converted examples, the re-exports they proved necessary, and the counting check. 6. Migration files follow the project too. One thing worth knowing while reading: re-exporting a package republishes all of its sub-paths, not just the one that was needed. This PR adds 115 published sub-paths across the three database packages. Two candidates were dropped for exactly that reason — see below. ## Alternatives considered Let an application install platform packages alongside its facade. Nothing would need re-exporting and the facades would stay thinner. Rejected: an application would again juggle several Prisma dependencies whose correct combination it maintains by hand, and getting it wrong — upgrading one and not the other — produces the silent two-copies failure above. Re-exporting costs a generated line and nothing at runtime. Re-export everything an application might plausibly want. Rejected in review: because re-exporting brings a package's entire sub-path surface, generosity is expensive and hard to undo. Migration tooling (54 sub-paths) was dropped because its only users are extension packs, which install platform packages anyway; the SQL driver re-export was dropped because nothing imported it at all. What remains is what a converted example actually needed. Flip the publish list in this same PR. Rejected: it would mix "does the new surface work" with "is it safe to stop publishing 50 packages" in one review. The switch is mechanical once this lands, and gets its own change. ## Verification `build`, `typecheck` (156 tasks), `test:packages` (1077 files / 14087 tests), `test:e2e`, `lint`, `lint:deps`, `lint:docs`, `lint:manifests`, `check:publish-deps`, `check:clean-tree`, `lint:casts` and `lint:throws` (no new instances), `test:scripts`, coverage, the tarball-install suites, and regenerating every committed artifact leaves the tree unchanged. Known-unstable and unrelated to this change: the `relation-mode-gh-` port suites (TML-3140), and several test timeouts that are too tight under load. ## Follow-ups TML-3124 switch the publish list · TML-3127 build cache can validate a stale published package on CI · TML-3140 unstable port suites · TML-3141 a test-helper sub-path reaches a package that is never published. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - New Features* - Added consolidated public ORM packages for PostgreSQL, MongoDB, SQLite, framework tooling, database targets, and extensions. - Generated contracts, migrations, and scaffolds now adapt imports to the consuming project’s package surface. - Added facade-provided `prisma-next` CLI access and consolidated migration entrypoints. - Documentation - Updated installation, package naming, public entrypoint, and migration scaffolding guidance. - Tests - Added coverage for package installation, exports, CLI behavior, module identity, and import compatibility. - Chores - Added checks preventing incompatible internal and public package imports. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	3 个月前
manual-qa-reports	feat: an application depends on one Prisma package (ADR 242) (#29864) ## What changes for someone using Prisma Today, an application that talks to Postgres installs a long list of our packages: ```jsonc { "dependencies": { "@prisma-next/postgres": "...", "@prisma-next/sql-runtime": "...", "@prisma-next/sql-orm-client": "...", "@prisma-next/target-postgres": "...", "@prisma-next/adapter-postgres": "...", "@prisma-next/sql-contract": "..." // ...a dozen more } } ``` After this PR, it installs one: ```jsonc { "dependencies": { "@prisma/orm-postgres": "0.16.0" } } ``` Everything else arrives as that package's own dependencies. Three of our example apps are converted in this PR to prove it — one per database — and each has exactly one Prisma package in its `dependencies`. This implements [ADR 242](https://github.com/prisma/prisma/pull/29852), which is already merged. ## What gets published 17 packages, all under the `@prisma` scope: - 3 database packages — `@prisma/orm-postgres`, `orm-sqlite`, `orm-mongo`. An application installs exactly one. We call these facades: each is a small package that wires its database together and re-exports everything an application needs. - 6 extension packs — PostGIS, pgvector, ParadeDB, Supabase, arktype-json, middleware-cache. Optional, installed alongside a database package. - 7 platform packages — the framework, the toolchain, one per database family, one per database target. Applications never install these directly; they arrive as dependencies. Extension authors do install them. - the `prisma` command, as a bin-only package. Every other workspace package — around 50 of them — stops being published. They still exist in the repo as the unit we organise code in; they just stop having a life on the registry. This PR does not make that switch yet. It builds and proves the new surface while leaving today's publish list exactly as it is. Flipping it is a separate change. ## The problem this design has to avoid A published package can't depend on packages that won't exist on the registry. So each published package contains a compiled copy of the internal packages it covers. That creates a trap. If one application ends up with the same code twice — once inside a published package, once as its own package — then classes, registries, and anything compared by reference exist twice too. An `instanceof` check quietly returns false. Nothing crashes, nothing fails to compile, and both copies behave identically in isolation. You find out much later, somewhere unrelated. So the rule the whole design follows is: every piece of internal code is published from exactly one package. Concretely, that means: - Each published package is built in one pass, so code shared between its own entry points exists once. Verified from the build's source maps: no module appears in more than one chunk, in any published package. - When one published package needs code from another, it imports it as a real dependency rather than compiling in a second copy. - A facade re-exports from the platform packages; it never carries its own copy. `@prisma/orm-postgres/orm-client` and `@prisma/orm-family-sql/orm-client` are two names for the same object, and there's a test that asserts exactly that from installed tarballs. - One table in `packages/0-shared/publish-surface` maps every internal package to where it's published. The build, the code generator, and the lint checks all read it, so there's one answer to "where does this live" rather than three that can drift. ## Generated code follows the application Prisma writes imports into your project — contract types and migration files. Those imports have to name packages your project actually depends on, or they won't resolve. So the generator now reads the `package.json` next to the config it's generating for. A project that depends on `@prisma/orm-postgres` gets imports from that package. A project on today's names keeps today's names. Nothing to configure, because the manifest already says which it is. Contract hashes are unaffected, and that isn't an assumption — hashes are computed from a structure that import text never enters, and there's a test asserting the hash is identical across naming schemes while the emitted imports demonstrably differ. ## What stops the trap coming back Two checks, because the failure is silent and won't show up in a test suite: - Every example app and test project must use one naming scheme, not a mix. `lint-single-import-root` scans them and fails the build if any project imports from both, since that's the situation that loads code twice. - `lint-consumer-internal-imports` counts how many internal-package imports remain in those projects and compares against a committed number. It fails if the number goes up (someone added one) and also if it goes down without the number being updated (so improvements get locked in). Target is zero. The build itself also refuses to proceed if the published-package map would put one module in two places, or if a published package's `package.json` no longer matches what its code actually needs. ## Reading this PR It's large — 257 files — because it's a migration. The commits are grouped and meant to be read in order: 1. Platform packages — the build mechanism, and the seven platform packages it produces. 2. Database packages, extension packs, the `prisma` command — completes the set of 17. 3. Generated imports become configurable — one place decides which names get written, with today's names still the default. 4. Database-family symmetry, publishing the map, the identity checks. 5. One package per application — the three converted examples, the re-exports they proved necessary, and the counting check. 6. Migration files follow the project too. One thing worth knowing while reading: re-exporting a package republishes all of its sub-paths, not just the one that was needed. This PR adds 115 published sub-paths across the three database packages. Two candidates were dropped for exactly that reason — see below. ## Alternatives considered Let an application install platform packages alongside its facade. Nothing would need re-exporting and the facades would stay thinner. Rejected: an application would again juggle several Prisma dependencies whose correct combination it maintains by hand, and getting it wrong — upgrading one and not the other — produces the silent two-copies failure above. Re-exporting costs a generated line and nothing at runtime. Re-export everything an application might plausibly want. Rejected in review: because re-exporting brings a package's entire sub-path surface, generosity is expensive and hard to undo. Migration tooling (54 sub-paths) was dropped because its only users are extension packs, which install platform packages anyway; the SQL driver re-export was dropped because nothing imported it at all. What remains is what a converted example actually needed. Flip the publish list in this same PR. Rejected: it would mix "does the new surface work" with "is it safe to stop publishing 50 packages" in one review. The switch is mechanical once this lands, and gets its own change. ## Verification `build`, `typecheck` (156 tasks), `test:packages` (1077 files / 14087 tests), `test:e2e`, `lint`, `lint:deps`, `lint:docs`, `lint:manifests`, `check:publish-deps`, `check:clean-tree`, `lint:casts` and `lint:throws` (no new instances), `test:scripts`, coverage, the tarball-install suites, and regenerating every committed artifact leaves the tree unchanged. Known-unstable and unrelated to this change: the `relation-mode-gh-` port suites (TML-3140), and several test timeouts that are too tight under load. ## Follow-ups TML-3124 switch the publish list · TML-3127 build cache can validate a stale published package on CI · TML-3140 unstable port suites · TML-3141 a test-helper sub-path reaches a package that is never published. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - New Features* - Added consolidated public ORM packages for PostgreSQL, MongoDB, SQLite, framework tooling, database targets, and extensions. - Generated contracts, migrations, and scaffolds now adapt imports to the consuming project’s package surface. - Added facade-provided `prisma-next` CLI access and consolidated migration entrypoints. - Documentation - Updated installation, package naming, public entrypoint, and migration scaffolding guidance. - Tests - Added coverage for package installation, exports, CLI behavior, module identity, and import compatibility. - Chores - Added checks preventing incompatible internal and public package imports. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	3 个月前
slices	feat: an application depends on one Prisma package (ADR 242) (#29864) ## What changes for someone using Prisma Today, an application that talks to Postgres installs a long list of our packages: ```jsonc { "dependencies": { "@prisma-next/postgres": "...", "@prisma-next/sql-runtime": "...", "@prisma-next/sql-orm-client": "...", "@prisma-next/target-postgres": "...", "@prisma-next/adapter-postgres": "...", "@prisma-next/sql-contract": "..." // ...a dozen more } } ``` After this PR, it installs one: ```jsonc { "dependencies": { "@prisma/orm-postgres": "0.16.0" } } ``` Everything else arrives as that package's own dependencies. Three of our example apps are converted in this PR to prove it — one per database — and each has exactly one Prisma package in its `dependencies`. This implements [ADR 242](https://github.com/prisma/prisma/pull/29852), which is already merged. ## What gets published 17 packages, all under the `@prisma` scope: - 3 database packages — `@prisma/orm-postgres`, `orm-sqlite`, `orm-mongo`. An application installs exactly one. We call these facades: each is a small package that wires its database together and re-exports everything an application needs. - 6 extension packs — PostGIS, pgvector, ParadeDB, Supabase, arktype-json, middleware-cache. Optional, installed alongside a database package. - 7 platform packages — the framework, the toolchain, one per database family, one per database target. Applications never install these directly; they arrive as dependencies. Extension authors do install them. - the `prisma` command, as a bin-only package. Every other workspace package — around 50 of them — stops being published. They still exist in the repo as the unit we organise code in; they just stop having a life on the registry. This PR does not make that switch yet. It builds and proves the new surface while leaving today's publish list exactly as it is. Flipping it is a separate change. ## The problem this design has to avoid A published package can't depend on packages that won't exist on the registry. So each published package contains a compiled copy of the internal packages it covers. That creates a trap. If one application ends up with the same code twice — once inside a published package, once as its own package — then classes, registries, and anything compared by reference exist twice too. An `instanceof` check quietly returns false. Nothing crashes, nothing fails to compile, and both copies behave identically in isolation. You find out much later, somewhere unrelated. So the rule the whole design follows is: every piece of internal code is published from exactly one package. Concretely, that means: - Each published package is built in one pass, so code shared between its own entry points exists once. Verified from the build's source maps: no module appears in more than one chunk, in any published package. - When one published package needs code from another, it imports it as a real dependency rather than compiling in a second copy. - A facade re-exports from the platform packages; it never carries its own copy. `@prisma/orm-postgres/orm-client` and `@prisma/orm-family-sql/orm-client` are two names for the same object, and there's a test that asserts exactly that from installed tarballs. - One table in `packages/0-shared/publish-surface` maps every internal package to where it's published. The build, the code generator, and the lint checks all read it, so there's one answer to "where does this live" rather than three that can drift. ## Generated code follows the application Prisma writes imports into your project — contract types and migration files. Those imports have to name packages your project actually depends on, or they won't resolve. So the generator now reads the `package.json` next to the config it's generating for. A project that depends on `@prisma/orm-postgres` gets imports from that package. A project on today's names keeps today's names. Nothing to configure, because the manifest already says which it is. Contract hashes are unaffected, and that isn't an assumption — hashes are computed from a structure that import text never enters, and there's a test asserting the hash is identical across naming schemes while the emitted imports demonstrably differ. ## What stops the trap coming back Two checks, because the failure is silent and won't show up in a test suite: - Every example app and test project must use one naming scheme, not a mix. `lint-single-import-root` scans them and fails the build if any project imports from both, since that's the situation that loads code twice. - `lint-consumer-internal-imports` counts how many internal-package imports remain in those projects and compares against a committed number. It fails if the number goes up (someone added one) and also if it goes down without the number being updated (so improvements get locked in). Target is zero. The build itself also refuses to proceed if the published-package map would put one module in two places, or if a published package's `package.json` no longer matches what its code actually needs. ## Reading this PR It's large — 257 files — because it's a migration. The commits are grouped and meant to be read in order: 1. Platform packages — the build mechanism, and the seven platform packages it produces. 2. Database packages, extension packs, the `prisma` command — completes the set of 17. 3. Generated imports become configurable — one place decides which names get written, with today's names still the default. 4. Database-family symmetry, publishing the map, the identity checks. 5. One package per application — the three converted examples, the re-exports they proved necessary, and the counting check. 6. Migration files follow the project too. One thing worth knowing while reading: re-exporting a package republishes all of its sub-paths, not just the one that was needed. This PR adds 115 published sub-paths across the three database packages. Two candidates were dropped for exactly that reason — see below. ## Alternatives considered Let an application install platform packages alongside its facade. Nothing would need re-exporting and the facades would stay thinner. Rejected: an application would again juggle several Prisma dependencies whose correct combination it maintains by hand, and getting it wrong — upgrading one and not the other — produces the silent two-copies failure above. Re-exporting costs a generated line and nothing at runtime. Re-export everything an application might plausibly want. Rejected in review: because re-exporting brings a package's entire sub-path surface, generosity is expensive and hard to undo. Migration tooling (54 sub-paths) was dropped because its only users are extension packs, which install platform packages anyway; the SQL driver re-export was dropped because nothing imported it at all. What remains is what a converted example actually needed. Flip the publish list in this same PR. Rejected: it would mix "does the new surface work" with "is it safe to stop publishing 50 packages" in one review. The switch is mechanical once this lands, and gets its own change. ## Verification `build`, `typecheck` (156 tasks), `test:packages` (1077 files / 14087 tests), `test:e2e`, `lint`, `lint:deps`, `lint:docs`, `lint:manifests`, `check:publish-deps`, `check:clean-tree`, `lint:casts` and `lint:throws` (no new instances), `test:scripts`, coverage, the tarball-install suites, and regenerating every committed artifact leaves the tree unchanged. Known-unstable and unrelated to this change: the `relation-mode-gh-` port suites (TML-3140), and several test timeouts that are too tight under load. ## Follow-ups TML-3124 switch the publish list · TML-3127 build cache can validate a stale published package on CI · TML-3140 unstable port suites · TML-3141 a test-helper sub-path reaches a package that is never published. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - New Features* - Added consolidated public ORM packages for PostgreSQL, MongoDB, SQLite, framework tooling, database targets, and extensions. - Generated contracts, migrations, and scaffolds now adapt imports to the consuming project’s package surface. - Added facade-provided `prisma-next` CLI access and consolidated migration entrypoints. - Documentation - Updated installation, package naming, public entrypoint, and migration scaffolding guidance. - Tests - Added coverage for package installation, exports, CLI behavior, module identity, and import compatibility. - Chores - Added checks preventing incompatible internal and public package imports. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	3 个月前
manual-qa.md	feat: an application depends on one Prisma package (ADR 242) (#29864) ## What changes for someone using Prisma Today, an application that talks to Postgres installs a long list of our packages: ```jsonc { "dependencies": { "@prisma-next/postgres": "...", "@prisma-next/sql-runtime": "...", "@prisma-next/sql-orm-client": "...", "@prisma-next/target-postgres": "...", "@prisma-next/adapter-postgres": "...", "@prisma-next/sql-contract": "..." // ...a dozen more } } ``` After this PR, it installs one: ```jsonc { "dependencies": { "@prisma/orm-postgres": "0.16.0" } } ``` Everything else arrives as that package's own dependencies. Three of our example apps are converted in this PR to prove it — one per database — and each has exactly one Prisma package in its `dependencies`. This implements [ADR 242](https://github.com/prisma/prisma/pull/29852), which is already merged. ## What gets published 17 packages, all under the `@prisma` scope: - 3 database packages — `@prisma/orm-postgres`, `orm-sqlite`, `orm-mongo`. An application installs exactly one. We call these facades: each is a small package that wires its database together and re-exports everything an application needs. - 6 extension packs — PostGIS, pgvector, ParadeDB, Supabase, arktype-json, middleware-cache. Optional, installed alongside a database package. - 7 platform packages — the framework, the toolchain, one per database family, one per database target. Applications never install these directly; they arrive as dependencies. Extension authors do install them. - the `prisma` command, as a bin-only package. Every other workspace package — around 50 of them — stops being published. They still exist in the repo as the unit we organise code in; they just stop having a life on the registry. This PR does not make that switch yet. It builds and proves the new surface while leaving today's publish list exactly as it is. Flipping it is a separate change. ## The problem this design has to avoid A published package can't depend on packages that won't exist on the registry. So each published package contains a compiled copy of the internal packages it covers. That creates a trap. If one application ends up with the same code twice — once inside a published package, once as its own package — then classes, registries, and anything compared by reference exist twice too. An `instanceof` check quietly returns false. Nothing crashes, nothing fails to compile, and both copies behave identically in isolation. You find out much later, somewhere unrelated. So the rule the whole design follows is: every piece of internal code is published from exactly one package. Concretely, that means: - Each published package is built in one pass, so code shared between its own entry points exists once. Verified from the build's source maps: no module appears in more than one chunk, in any published package. - When one published package needs code from another, it imports it as a real dependency rather than compiling in a second copy. - A facade re-exports from the platform packages; it never carries its own copy. `@prisma/orm-postgres/orm-client` and `@prisma/orm-family-sql/orm-client` are two names for the same object, and there's a test that asserts exactly that from installed tarballs. - One table in `packages/0-shared/publish-surface` maps every internal package to where it's published. The build, the code generator, and the lint checks all read it, so there's one answer to "where does this live" rather than three that can drift. ## Generated code follows the application Prisma writes imports into your project — contract types and migration files. Those imports have to name packages your project actually depends on, or they won't resolve. So the generator now reads the `package.json` next to the config it's generating for. A project that depends on `@prisma/orm-postgres` gets imports from that package. A project on today's names keeps today's names. Nothing to configure, because the manifest already says which it is. Contract hashes are unaffected, and that isn't an assumption — hashes are computed from a structure that import text never enters, and there's a test asserting the hash is identical across naming schemes while the emitted imports demonstrably differ. ## What stops the trap coming back Two checks, because the failure is silent and won't show up in a test suite: - Every example app and test project must use one naming scheme, not a mix. `lint-single-import-root` scans them and fails the build if any project imports from both, since that's the situation that loads code twice. - `lint-consumer-internal-imports` counts how many internal-package imports remain in those projects and compares against a committed number. It fails if the number goes up (someone added one) and also if it goes down without the number being updated (so improvements get locked in). Target is zero. The build itself also refuses to proceed if the published-package map would put one module in two places, or if a published package's `package.json` no longer matches what its code actually needs. ## Reading this PR It's large — 257 files — because it's a migration. The commits are grouped and meant to be read in order: 1. Platform packages — the build mechanism, and the seven platform packages it produces. 2. Database packages, extension packs, the `prisma` command — completes the set of 17. 3. Generated imports become configurable — one place decides which names get written, with today's names still the default. 4. Database-family symmetry, publishing the map, the identity checks. 5. One package per application — the three converted examples, the re-exports they proved necessary, and the counting check. 6. Migration files follow the project too. One thing worth knowing while reading: re-exporting a package republishes all of its sub-paths, not just the one that was needed. This PR adds 115 published sub-paths across the three database packages. Two candidates were dropped for exactly that reason — see below. ## Alternatives considered Let an application install platform packages alongside its facade. Nothing would need re-exporting and the facades would stay thinner. Rejected: an application would again juggle several Prisma dependencies whose correct combination it maintains by hand, and getting it wrong — upgrading one and not the other — produces the silent two-copies failure above. Re-exporting costs a generated line and nothing at runtime. Re-export everything an application might plausibly want. Rejected in review: because re-exporting brings a package's entire sub-path surface, generosity is expensive and hard to undo. Migration tooling (54 sub-paths) was dropped because its only users are extension packs, which install platform packages anyway; the SQL driver re-export was dropped because nothing imported it at all. What remains is what a converted example actually needed. Flip the publish list in this same PR. Rejected: it would mix "does the new surface work" with "is it safe to stop publishing 50 packages" in one review. The switch is mechanical once this lands, and gets its own change. ## Verification `build`, `typecheck` (156 tasks), `test:packages` (1077 files / 14087 tests), `test:e2e`, `lint`, `lint:deps`, `lint:docs`, `lint:manifests`, `check:publish-deps`, `check:clean-tree`, `lint:casts` and `lint:throws` (no new instances), `test:scripts`, coverage, the tarball-install suites, and regenerating every committed artifact leaves the tree unchanged. Known-unstable and unrelated to this change: the `relation-mode-gh-` port suites (TML-3140), and several test timeouts that are too tight under load. ## Follow-ups TML-3124 switch the publish list · TML-3127 build cache can validate a stale published package on CI · TML-3140 unstable port suites · TML-3141 a test-helper sub-path reaches a package that is never published. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - New Features* - Added consolidated public ORM packages for PostgreSQL, MongoDB, SQLite, framework tooling, database targets, and extensions. - Generated contracts, migrations, and scaffolds now adapt imports to the consuming project’s package surface. - Added facade-provided `prisma-next` CLI access and consolidated migration entrypoints. - Documentation - Updated installation, package naming, public entrypoint, and migration scaffolding guidance. - Tests - Added coverage for package installation, exports, CLI behavior, module identity, and import compatibility. - Chores - Added checks preventing incompatible internal and public package imports. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	3 个月前
plan.md	TML-3483: Give each ADR merged since late September its own number (#30619) ## Linked issue [TML-3483](https://linear.app/prisma-company/issue/TML-3483). Related: [TML-3020](https://linear.app/prisma-company/issue/TML-3020) (the eleven older duplicated numbers, not touched here). ## Summary `main` had three files named `ADR 258 - …`, so "see ADR 258" did not say which decision it meant: ```text ADR 258 - List cardinality has independent container and element nullability.md ADR 258 - A model names its storage verbatim, and a rename is an operation.md ADR 258 - A collection keeps its class through the chain.md ``` The same happened to 207, 255 and 259 in the last two weeks. The ADR that merged first keeps the number. Each ADR that merged later moves to a new number: \| Was \| Now \| ADR \| \| --- \| --- \| --- \| \| 255 \| 262 \| Block specs bind top-level block values \| \| 207 \| 263 \| A serverless Postgres connection has the same query interface as a `postgres()` client \| \| 258 \| 264 \| A model names its storage verbatim, and a rename is an operation \| \| 258 \| 265 \| A collection keeps its class through the chain \| \| 259 \| 266 \| The cache middleware passes data to its store, and the store decides how to cache \| The new numbers start at 262 because `main` now has ADR 260 and open pull requests already use 256 and 261. The query fragments ADR (259) cited "ADR 260" for the collection-scopes ADR in prisma/orm#30428, which has not merged. ADR 260 on `main` is now the `afterTransaction` stage, so that citation is removed. prisma/orm#30428 can add it back with its final number. Every link and every mention of a moved ADR in docs, package READMEs and project files now uses the new number. Mentions in project research notes that describe the numbering at an earlier point in time are left as they were. `ADR-INDEX.md` gains rows for three ADRs it was missing: 259 (query fragments), 264 (storage names) and 265 (collection class). ## Open pull requests this affects These pull requests change a file that moves here. Git should carry their changes to the new file name, but links they add to the old name need updating: - prisma/orm#30550 and prisma/orm#30613 change ADR 255 (block specs), now ADR 262. - prisma/orm#30428 changes ADR 258 (collection class), now ADR 265. These open pull requests add an ADR whose number is already taken, so they clash again when they merge: - ADR 256: prisma/orm#30535 (language-server file watching). `main` already has ADR 256 (mutation-default generators). - ADR 260: prisma/orm#30428 (collection scopes) and prisma/orm#30550 / prisma/orm#30558 (raw SQL is a value of `sql-expression`). `main` already has ADR 260 (`afterTransaction` stage). ## Testing performed - Checked every Markdown link in the changed files that points to an ADR. All resolve. Two links that were already broken on `main` (ADR 009 and ADR 015) are unrelated and unchanged. - Searched the repository for the old file names and the old numbers. The only remaining matches are the earlier-point-in-time research notes described above. ## Skill update n/a — internal only. ## Upgrade instructions [`upgrade-instructions/pending/adr-numbers-unique/extension/`](upgrade-instructions/pending/adr-numbers-unique/extension/instructions.md) declares `changes: []`. The three package READMEs change only their ADR links, so extension authors have nothing to do. ## Checklist - [x] All commits are signed off (`git commit -s`) per the [DCO](../CONTRIBUTING.md#developer-certificate-of-origin-dco). - [x] I read [CONTRIBUTING.md](../CONTRIBUTING.md) and the change is scoped to one logical concern. - [x] Tests are updated (or `n/a` if the change is doc-only / refactor with no behavioural delta). n/a, docs only. - [x] The PR title is in `TML-NNNN: <sentence-case title>` form. - [x] The Skill update section above is filled in. ## Notes for the reviewer Alternatives considered: - Move whichever ADR has fewer references. For 255 that would move relation ordering instead of block specs, and no open pull request touches it. Rejected because a rule based on merge order is simple to apply the next time, and an earlier fix (ADR 255 to ADR 256 for mutation-default generators) already moved the later ADR. - Also renumber the eleven older duplicates (159 to 224). They have been cited by number for months, and deciding which ADR each bare mention means needs reading each citation. That stays with TML-3020. Agent: etain-65 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * Documentation * Updated ADR references across guides, architecture documentation, and package READMEs to reflect current numbering. * Added ADRs to the architecture index and corrected links covering serverless PostgreSQL connections, block specifications, storage naming, query collections, and cache middleware. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	29 天前
retros.md	retro(facade-import-surface-completion): orchestrator skipped drive-qa-* before PR #557 Records the procedural miss: orchestrator declared the slice "code-complete" after the reviewer returned READY FOR PR on reviews/code-review.md and opened PR #557 without ever invoking drive-qa-plan or drive-qa-run. The slice spec's SDoD4 explicitly required both. The miss was caught by the operator, not by the workflow. Root cause is a canonical gap in drive-build-workflow § Post-conditions: the post-conditions enumerate reviewer-driven gates but do not require an explicit walk of the slice-DoD checklist before declaring the branch PR-ready. The skill body lists drive-qa-plan / drive-qa-run as atomic skills the workflow calls, but nothing structurally fires them before handoff to the PR-opening skill. Lands the lesson in three project-context surfaces (canonical drive-build-workflow tightening is proposed separately, pending operator confirmation before touching canonical): - projects/facade-import-surface-completion/retros.md (new) -- the project-level retro record per drive-run-retro § Step 7. - drive/calibration/dod.md § Slice-DoD overlay -- explicit "slice-close ritual" note that the orchestrator must walk the SDoD checklist verbatim, not just trust reviewer SATISFIED. - drive/qa/findings.md + drive/retro/findings.md -- trial-period finding stanzas tagged gap and boundary respectively. Signed-off-by: Will Madden <madden@prisma.io>	5 个月前
spec.md	TML-3483: Give each ADR merged since late September its own number (#30619) ## Linked issue [TML-3483](https://linear.app/prisma-company/issue/TML-3483). Related: [TML-3020](https://linear.app/prisma-company/issue/TML-3020) (the eleven older duplicated numbers, not touched here). ## Summary `main` had three files named `ADR 258 - …`, so "see ADR 258" did not say which decision it meant: ```text ADR 258 - List cardinality has independent container and element nullability.md ADR 258 - A model names its storage verbatim, and a rename is an operation.md ADR 258 - A collection keeps its class through the chain.md ``` The same happened to 207, 255 and 259 in the last two weeks. The ADR that merged first keeps the number. Each ADR that merged later moves to a new number: \| Was \| Now \| ADR \| \| --- \| --- \| --- \| \| 255 \| 262 \| Block specs bind top-level block values \| \| 207 \| 263 \| A serverless Postgres connection has the same query interface as a `postgres()` client \| \| 258 \| 264 \| A model names its storage verbatim, and a rename is an operation \| \| 258 \| 265 \| A collection keeps its class through the chain \| \| 259 \| 266 \| The cache middleware passes data to its store, and the store decides how to cache \| The new numbers start at 262 because `main` now has ADR 260 and open pull requests already use 256 and 261. The query fragments ADR (259) cited "ADR 260" for the collection-scopes ADR in prisma/orm#30428, which has not merged. ADR 260 on `main` is now the `afterTransaction` stage, so that citation is removed. prisma/orm#30428 can add it back with its final number. Every link and every mention of a moved ADR in docs, package READMEs and project files now uses the new number. Mentions in project research notes that describe the numbering at an earlier point in time are left as they were. `ADR-INDEX.md` gains rows for three ADRs it was missing: 259 (query fragments), 264 (storage names) and 265 (collection class). ## Open pull requests this affects These pull requests change a file that moves here. Git should carry their changes to the new file name, but links they add to the old name need updating: - prisma/orm#30550 and prisma/orm#30613 change ADR 255 (block specs), now ADR 262. - prisma/orm#30428 changes ADR 258 (collection class), now ADR 265. These open pull requests add an ADR whose number is already taken, so they clash again when they merge: - ADR 256: prisma/orm#30535 (language-server file watching). `main` already has ADR 256 (mutation-default generators). - ADR 260: prisma/orm#30428 (collection scopes) and prisma/orm#30550 / prisma/orm#30558 (raw SQL is a value of `sql-expression`). `main` already has ADR 260 (`afterTransaction` stage). ## Testing performed - Checked every Markdown link in the changed files that points to an ADR. All resolve. Two links that were already broken on `main` (ADR 009 and ADR 015) are unrelated and unchanged. - Searched the repository for the old file names and the old numbers. The only remaining matches are the earlier-point-in-time research notes described above. ## Skill update n/a — internal only. ## Upgrade instructions [`upgrade-instructions/pending/adr-numbers-unique/extension/`](upgrade-instructions/pending/adr-numbers-unique/extension/instructions.md) declares `changes: []`. The three package READMEs change only their ADR links, so extension authors have nothing to do. ## Checklist - [x] All commits are signed off (`git commit -s`) per the [DCO](../CONTRIBUTING.md#developer-certificate-of-origin-dco). - [x] I read [CONTRIBUTING.md](../CONTRIBUTING.md) and the change is scoped to one logical concern. - [x] Tests are updated (or `n/a` if the change is doc-only / refactor with no behavioural delta). n/a, docs only. - [x] The PR title is in `TML-NNNN: <sentence-case title>` form. - [x] The Skill update section above is filled in. ## Notes for the reviewer Alternatives considered: - Move whichever ADR has fewer references. For 255 that would move relation ordering instead of block specs, and no open pull request touches it. Rejected because a rule based on merge order is simple to apply the next time, and an earlier fix (ADR 255 to ADR 256 for mutation-default generators) already moved the later ADR. - Also renumber the eleven older duplicates (159 to 224). They have been cited by number for months, and deciding which ADR each bare mention means needs reading each citation. That stays with TML-3020. Agent: etain-65 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * Documentation * Updated ADR references across guides, architecture documentation, and package READMEs to reflect current numbering. * Added ADRs to the architecture index and corrected links covering serverless PostgreSQL connections, block specifications, storage naming, query collections, and cache middleware. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: willbot <w.a.madden+machine@gmail.com> Signed-off-by: Will Madden <madden@prisma.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>	29 天前