@prisma/orm-mongo 8.0.0-rc.1-dev.45 → 8.0.0-rc.10

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.2-to-8.0.0-rc.3/instructions.md

@@ -0,0 +1,5 @@
+---
+from: "8.0.0-rc.2"
+to: "8.0.0-rc.3"
+changes: []
+---

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.3-to-8.0.0-rc.4/instructions.md

@@ -0,0 +1,137 @@
+---
+from: "8.0.0-rc.3"
+to: "8.0.0-rc.4"
+changes:
+  - id: prisma-config-hard-cut-and-top-level-commands
+    summary: |
+      The deprecated fallbacks are gone: the CLI no longer reads
+      `prisma-next.config.ts`, no longer accepts the flat (un-nested) config shape, and the
+      `prisma-next` command no longer exists. The unified CLI (`@prisma/cli`, installed from
+      the `next` dist-tag; its binary is currently `prisma-cli`) runs the ORM commands at the
+      top level — `contract emit`, `db init`, `migration plan`, `migrate` — with only `init`
+      under the `orm` group (`orm init`), and the only config it reads is `prisma.config.ts`
+      in the engine envelope shape.
+
+      1. Rename `prisma-next.config.ts` to `prisma.config.ts` if you have not already.
+      2. Rewrite the export to the envelope shape. Old flat shape:
+         `import { defineConfig } from '@prisma/orm-postgres/config';`
+         `export default defineConfig({ contract: '…', db: { connection: … } });`
+         New shape:
+         `import { definePrismaConfig } from '@prisma/cli-engine';`
+         `import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';`
+         `export default definePrismaConfig({ orm: ormConfig({ contract: '…', db: { connection: … } }) });`
+         The options object moves into the target helper unchanged. The same pattern applies
+         to `@prisma/orm-sqlite/config` and `@prisma/orm-mongo/config`.
+      3. If the config reads `process.env`, keep (or add) `import 'dotenv/config';` as the
+         first import — the loader does not read `.env` for you.
+      4. In `package.json`, replace the `prisma-next` devDependency with `prisma@latest`
+         plus `@prisma/cli-engine` at the exact version that `@prisma/cli` names in its own
+         dependencies, and update your extension's contract-space
+         build and emit scripts from `prisma-next contract emit` to `prisma-cli contract emit`.
+      5. Run `prisma-cli contract emit` to confirm the config loads and to regenerate the
+         artifacts (their generated-file headers change with this release).
+    detection:
+      glob: "**/prisma-next.config.ts"
+  - id: facades-compose-the-raw-lane
+    summary: |
+      A facade no longer gets the whole-query raw tag from the builder. `Db<C>` is a pure
+      namespace map now, so the `raw` key it used to answer is gone, and the tag is composed at
+      client build instead.
+
+      Build it with `createRawLane({ context, rawCodecInferer })` from
+      `@internal/sql-builder/runtime`, typed `RawLane<TContract>` from
+      `@internal/sql-builder/types`, and expose it as your client's `raw`. Callers then write
+      ``client.raw.sql`SELECT ...` ``. A client that binds per role or per scope builds one lane
+      per bound context, the way it already builds one `sql` per context. A static context —
+      the no-runtime shape that returns `context`, `contract` and `sql` — builds one too and
+      returns it as `raw`.
+
+      If your `raw` property was the contract-free expression tag (`createRawSql(inferer)`), it
+      changes shape from a callable to `{ sql }`. That breaks your own surface, so note it in
+      your release.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - 'createRawSql\('
+        - 'RawSqlTag'
+        # `fns.raw` is a fragment call site and is deliberately excluded:
+        # fragments are unchanged by this release.
+        - '(?<!(?<![\w$])fns)\.raw`'
+      anyMatch: true
+  - id: reserved-raw-namespace-check-removed
+    summary: |
+      `sql()` no longer refuses a contract whose storage declares a namespace named `raw`, and
+      `ORM.NAMESPACE_RESERVED` leaves the error catalogue. Nothing raises the code now, so drop
+      any branch that matched it: a test asserting the refusal, a doc listing the code, an
+      error mapping of your own.
+    detection:
+      glob: "**/*.{ts,mts,cts,md}"
+      contains:
+        - "ORM.NAMESPACE_RESERVED"
+      anyMatch: true
+  - id: contract-fixture-restamp
+    summary: |
+      Committed contract artifacts (`contract.json` / `contract.d.ts`, including test
+      fixtures) embed the toolchain version, which moves to 8.0.0-rc.4. Regenerate them
+      with your emit script (`build:contract-space` or equivalent) after upgrading, or
+      fixture comparisons fail on the version stamp alone.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"version": "8.0.0-rc.3"'
+---
+
+# 8.0.0-rc.3 → 8.0.0-rc.4 — Extension-author upgrade instructions
+
+## `facades-compose-the-raw-lane`
+
+`Db<C>` is a namespace map and nothing else, so a facade composes the whole-query raw tag itself
+and exposes it as the raw lane:
+
+```ts
+import { createRawLane, sql } from '@internal/sql-builder/runtime';
+import type { Db, RawLane } from '@internal/sql-builder/types';
+
+const sqlDb: Db<TContract> = sql<TContract>({ context, rawCodecInferer });
+const raw: RawLane<TContract> = createRawLane<TContract>({ context, rawCodecInferer });
+```
+
+Callers reach the tag at `client.raw.sql`. A client that binds per role or per scope builds one
+lane per bound context, exactly as it already builds one `sql` per context.
+
+A static context does the same. If your facade ships a no-runtime surface — the shape that
+returns `context`, `contract`, `sql` and friends without opening a connection — build the lane
+there too and return it as `raw`:
+
+```ts
+export interface YourStaticContext<TContract extends Contract<SqlStorage>> {
+  readonly sql: Db<TContract>;
+  readonly raw: RawLane<TContract>;
+  // …context, contract, enums
+}
+
+const raw: RawLane<TContract> = createRawLane<TContract>({ context, rawCodecInferer });
+```
+
+Its `raw` property changes type from the contract-free tag to `RawLane<TContract>`, the same
+change the connected client makes, so a consumer reads both surfaces the same way.
+
+Two shapes change for your consumers. Anyone who wrote ``client.sql.raw`...` `` writes
+``client.raw.sql`...` ``. Anyone who called `client.raw` as an expression tag calls
+`client.raw.sql`...`.returns(codecId)` instead, or `fns.raw` inside a builder callback. Both are
+breaking changes to your own surface, so note them in your release.
+
+The detector looks for `createRawSql(`, `RawSqlTag`, and `raw` used as a tag. It skips the
+receiver `fns` exactly, including `x.fns.raw`, because that is a fragment call site and needs no
+change. A receiver that merely ends in those letters, such as `myfns.raw`, still matches, as
+does a functions object aliased to another name.
+
+## `reserved-raw-namespace-check-removed`
+
+`sql()` used to refuse a contract whose storage declared a namespace named `raw`, raising
+`ORM.NAMESPACE_RESERVED` at client construction. The check is gone with the constraint it
+enforced: the lane is composed by the client, not answered by the namespace map, so no contract
+can shadow it.
+
+Drop any branch that matched the code — a test asserting the refusal, an error mapping, a doc
+that lists it. The code no longer exists in the catalogue, and nothing raises it.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.4-to-8.0.0-rc.5/instructions.md

@@ -0,0 +1,129 @@
+---
+from: "8.0.0-rc.4"
+to: "8.0.0-rc.5"
+changes:
+  - id: wrap-pg-constructions-with-suppress-idle-connection-errors
+    summary: |
+      Wrap every pg `Pool` or `Client` your extension constructs with `suppressIdleConnectionErrors`, newly exported from `@internal/driver-postgres/runtime` (canonical home `@internal/utils/suppress-idle-connection-errors`). node-postgres emits 'error' on the pool or client when an idle connection drops; with no listener Node kills the host process. The helper attaches a no-op listener, is idempotent per emitter, and returns the same instance. Bindings handed to the driver (`pgPool`/`pgClient`/`url`) are wrapped by the driver itself since rc.5, so this applies to pg handles your extension uses outside a driver binding.
+    detection:
+      glob: "**/*.ts"
+      contains:
+        - "new Pool("
+        - "new Client("
+        - "new pg.Pool("
+        - "new pg.Client("
+      anyMatch: true
+  - id: distinct-on-requires-postgres-capability
+    summary: |
+      `Collection#distinctOn(...)` now requires the contract to declare the `postgres.distinctOn`
+      capability, mirroring the sql-builder lane's existing gate. A contract without it (e.g.
+      SQLite-only) makes the call a compile error — the parameter type narrows to `never` — where
+      it used to compile and silently produce undeduped rows at runtime, since the target's
+      renderer never rendered `DISTINCT ON` for a target that cannot express it.
+
+      Every `.distinctOn(...)` call your code makes on a `Collection` was already wrong on any
+      target lacking `postgres.distinctOn`; the type error is the fix surfacing at compile time
+      instead of a silently wrong result set at runtime. Move the call to a contract that
+      declares `postgres.distinctOn`, or remove it — there is no runtime opt-out.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - '\.distinctOn\('
+      anyMatch: true
+  - id: groupby-pre-group-pagination-now-scopes-rows
+    summary: |
+      `take()`, `skip()`, `cursor()`, `distinct()`, `distinctOn()`, and `orderBy()` written before
+      `.groupBy(...)` on a `Collection` now scope the rows that get grouped, instead of being
+      silently dropped. `db.orm.<Model>.take(10).groupBy('x').aggregate(...)` used to group every
+      matching row; it now groups only the first 10 (by whatever `orderBy()` is active).
+
+      There is no reliable static pattern that separates a call site whose answer just became
+      correct from one whose answer is now different from before — both look identical in source.
+      Any test asserting values on a `.groupBy(...)` chain with a pre-group pagination clause
+      needs re-checking against the new (correct) numbers by hand.
+  - id: groupby-post-group-pagination-requires-order-by
+    summary: |
+      `GroupedCollection` gained its own `take()` / `skip()` / `orderBy()`, which page the grouped
+      rows themselves when written *after* `.groupBy(...)`. Post-group `take()` / `skip()` require
+      a prior post-group `orderBy()` — without one they are a compile error, the parameter type
+      narrows to `never`, because a database may return groups in any order and "the first n
+      groups" is undefined without one.
+
+      This is not a rote find-and-replace: `db.orm.<Model>.groupBy('x').take(10)` needs a caller
+      to pick what "first" means for their groups, which is a decision only they can make. Add an
+      `.orderBy(...)` naming one of the fields passed to `groupBy(...)` before the `take()` /
+      `skip()` call.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - '\.groupBy\('
+      anyMatch: true
+---
+
+# 8.0.0-rc.4 → 8.0.0-rc.5 — Extension author upgrade instructions
+
+## `wrap-pg-constructions-with-suppress-idle-connection-errors`
+
+Walk every file matched by `detection.glob`. For each pg `Pool` or `Client` the extension constructs, wrap the construction:
+
+```ts
+import { suppressIdleConnectionErrors } from '@internal/driver-postgres/runtime';
+
+const pool = suppressIdleConnectionErrors(
+  new Pool({ connectionString: options.url }),
+);
+```
+
+This is the same translation applied to the in-repo `@internal/postgres` and `@internal/extension-supabase` runtimes in this transition. The helper only attaches a no-op `'error'` listener (connect/query failures still reject their own promises), so behavior is otherwise unchanged; without it, a dropped idle connection crashes the process that hosts the extension.
+
+If your extension's test suite fakes the `pg` module, the fakes need an `on` method (`on = vi.fn().mockReturnThis()` on a class fake, or `on: vi.fn()` on an object literal) — the runtime now calls `.on('error', ...)` on every pool, client, and checked-out pool client.
+## `distinct-on-requires-postgres-capability`
+
+`Collection#distinctOn(...)` used to compile and run on any target, but only Postgres ever
+rendered its `DISTINCT ON` clause — a call on any other target (SQLite) compiled clean and
+silently returned undeduped rows at runtime. The method now carries the same capability gate the
+sql-builder lane already enforces: its parameter type narrows to `never` unless the contract
+declares `postgres.distinctOn`, so the same call is a compile error on a contract that lacks it,
+and a runtime error carrying `ORM.CAPABILITY_MISSING` if reached dynamically (e.g. through a
+hand-built `CollectionState`).
+
+Find every `.distinctOn(...)` call your code makes on a `Collection` and check whether the
+contract it runs against declares `postgres.distinctOn`. If it does, nothing changes — the call
+already worked correctly and keeps compiling. If it does not, the call was already producing the
+wrong result set; either move the collection onto a Postgres-capable contract, or remove the
+`.distinctOn(...)` call and accept the undeduped rows it was silently returning before.
+
+`Collection#distinct(...)` is unaffected — it lowers to a portable `ROW_NUMBER` dedup and needs
+no capability, on any target.
+
+## `groupby-pre-group-pagination-now-scopes-rows`
+
+Any `.take(...)`, `.skip(...)`, `.cursor(...)`, `.distinct(...)`, `.distinctOn(...)`, or
+`.orderBy(...)` your extension calls *before* `.groupBy(...)` on a `Collection` used to be
+silently dropped once `.groupBy(...)` joined the chain — the aggregate reduced over every
+matching row, ignoring the pagination clause entirely. It now scopes the rows that get grouped,
+the same way root `.aggregate()` scopes its rows (see the sibling entry for that fix, already
+shipped in `8.0.0-rc.4` → `8.0.0-rc.5`'s predecessor window).
+
+There is no detection regex for this one worth writing: the call sites that need re-checking
+look identical, in source, to the call sites that already worked correctly (a chain built with
+this scoping in mind, versus one that assumed the pagination clause was a no-op). Grep for
+`.groupBy(` and read every match with a pre-group pagination clause; if the test asserting its
+result seeds fewer distinct groups than pagination scope allows, or asserts totals computed over
+every row rather than the paginated window, the expected values need updating to match the now-
+correct behavior.
+
+## `groupby-post-group-pagination-requires-order-by`
+
+`GroupedCollection` (what `.groupBy(...)` returns) gained `take()`, `skip()`, and `orderBy()`,
+which page the *grouped* rows when written after `.groupBy(...)` — previously `.groupBy(...)` had
+no chain of its own past `.having(...)`. Calling post-group `take()` or `skip()` without a prior
+post-group `orderBy()` is a compile error: the parameter type narrows to `never`, because a
+database may return groups in any order and "the first n groups" has no defined meaning without
+one.
+
+If your extension's own code (or its test suite) calls `.groupBy(...).take(...)` or
+`.groupBy(...).skip(...)` with no `.orderBy(...)` between them, it will fail to compile after this
+upgrade. There is no default ordering to insert automatically — add an `.orderBy(...)` naming one
+of the fields you passed to `groupBy(...)` (ascending or descending is your call; whichever
+matches what "the first n groups" should mean for that query) before the `take()` / `skip()` call.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.5-to-8.0.0-rc.6/instructions.md

@@ -0,0 +1,102 @@
+---
+from: "8.0.0-rc.5"
+to: "8.0.0-rc.6"
+changes:
+  - id: postgres-temporal-codec-ids-retired
+    summary: |
+      Five PostgreSQL temporal codec ids were removed with no compatibility aliases. Each
+      native type now has two representation-explicit codecs — one whose application value is a
+      `Temporal.*`, one that passes PostgreSQL's own text through unchanged:
+
+      | Retired | Temporal replacement | Text replacement |
+      | --- | --- | --- |
+      | `pg/date@1` | `pg/date-temporal@1` (`Temporal.PlainDate`) | `pg/date-string@1` |
+      | `pg/timestamp@1` | `pg/timestamp-temporal@1` (`Temporal.PlainDateTime`) | `pg/timestamp-string@1` |
+      | `pg/timestamptz@1` | `pg/timestamptz-temporal@1` (`Temporal.Instant`) | `pg/timestamptz-string@1` |
+      | `pg/time@1` | `pg/time-temporal@1` (`Temporal.PlainTime`) | `pg/time-string@1` |
+      | `sql/timestamp@1` | `pg/timestamptz-temporal@1` | `pg/timestamptz-string@1` |
+
+      An extension names these ids in more places than a user does. Sweep all of them:
+
+      1. **Column descriptors in an extension contract.** A pack that declares its own tables
+         (`extensionModel(...)` with `{ codecId, nativeType }` column literals) picks the
+         representation on its consumers' behalf. Choose the Temporal id where application code
+         reads the column as a value, and the `*String` id where it should stay text — the
+         Supabase pack's `auth` tables took the Temporal id for exactly that reason.
+      2. **`descriptor-meta` registrations, control-plane hooks and aggregate matrices.** Any
+         table keyed by codec id gains two entries where it had one, or moves its single entry.
+         A parity or coverage table that enumerates ids needs the four new `*-string@1` ids as
+         well as the four `*-temporal@1` ones.
+      3. **Hand-built contracts and test doubles.** Deserializing a contract literal that names
+         a retired id now fails validation rather than resolving to something plausible.
+      4. **Introspection maps.** `date`, `timestamp`, `timestamptz` and `time` map to the bare
+         PSL names (`Date`, `Timestamp(p)`, `Timestamptz(p)`, `Time(p)`), which resolve to the
+         Temporal codecs. The `*String` names are authoring-only and must claim no
+         `targetTypes`, or they compete for introspection ownership.
+      5. **Re-emit any contract your package commits.** `build:contract-space` (or
+         `prisma contract emit`) rewrites `contract.json` and `contract.d.ts`; commit both.
+    detection:
+      glob: "**/*.{ts,mts,cts,json}"
+      regex:
+        - "pg/(date|timestamp|timestamptz|time)@1"
+        - "sql/timestamp@1"
+      anyMatch: true
+  - id: temporal-codecs-require-a-global-and-refuse-a-date
+    summary: |
+      A Temporal-backed codec reads the application's global `Temporal` implementation. Prisma
+      neither bundles nor imports a polyfill, and the check is lazy: registering a pack,
+      validating a contract, resolving a descriptor and constructing a codec instance all
+      succeed with no `Temporal` in scope. Only invoking one fails, with
+      `RUNTIME.TEMPORAL_UNAVAILABLE`.
+
+      Two consequences for an extension:
+
+      1. **Your test suites need the global.** If your package exercises a Temporal-backed
+         column, install a polyfill in a vitest `setupFiles` entry
+         (`import 'temporal-polyfill/full/global';`) and add `temporal-polyfill` as a
+         devDependency. For TypeScript to see the same global, add a `.d.ts` under your test
+         directory containing `/// <reference types="temporal-polyfill/types/global" />` — the
+         package's own `temporal-polyfill/global` types resolve to `export {}` and declare
+         nothing.
+      2. **Encode is nominally typed now.** These codecs check `Symbol.toStringTag` and refuse
+         anything that is not their own Temporal type, including a `Date`, with
+         `RUNTIME.ENCODE_FAILED` naming the codec. If your pack contributes a mutation-default
+         generator or any other value that lands in a Temporal-backed column, it must produce
+         the matching `Temporal.*` value — a `Date` no longer slips through to be serialized as
+         `Date.prototype.toString()`.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      regex:
+        - "pg/(date|timestamp|timestamptz|time)-temporal@1"
+      anyMatch: true
+  - id: contract-space-restamp
+    summary: |
+      The emitted contract artifacts embed the toolchain version, which moves to 8.0.0-rc.6.
+      Rebuild the extension's contract space (the package's `build:contract-space` script)
+      once after upgrading so the emitted artifacts match the installed toolchain. The
+      toolchain also re-released against `@prisma/cli-engine@0.2.2` (a CLI-side fix with no
+      extension-facing surface).
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"version": "8.0.0-rc.5"'
+---
+
+# 8.0.0-rc.5 → 8.0.0-rc.6 — Extension author upgrade instructions
+
+# PostgreSQL temporal representations, for extension authors
+
+There is no codemod: the retired ids map to *two* replacements each, and which one an extension
+should name is a judgement about what its consumers do with the column. Sweep by id, decide per
+site, then re-emit any committed contract artifact.
+
+Four behaviours bear on an extension's own codecs. Writes serialize at full precision and let
+PostgreSQL round to the column's declared precision, carries included. A Temporal codec rejects
+`infinity`, years beyond roughly ±271821, and non-ISO `DateStyle` output, naming the `*String` type
+that reads them losslessly. The driver hands temporal OIDs through as server text rather than
+building a `Date`. And temporal expressions are cast to `text` before PostgreSQL builds JSON, so a
+nested read returns the same text a flat one does.
+
+## `contract-space-restamp`
+
+For every `contract.json` matched by `detection`, run the extension package's `build:contract-space` script (or its emit command) once after upgrading. Beyond the temporal changes above, the only expected diff is the embedded `version` moving to `8.0.0-rc.6`. The toolchain also re-released against `@prisma/cli-engine@0.2.2`; that change has no extension-facing surface.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.6-to-8.0.0-rc.7/instructions.md

@@ -0,0 +1,33 @@
+---
+from: "8.0.0-rc.6"
+to: "8.0.0-rc.7"
+changes:
+  - id: rename-orm-pagination-methods
+    summary: |
+      Rename ORM collection pagination calls from `.take(n)` to `.limit(n)` and from `.skip(n)` to `.offset(n)`. This applies to SQL and Mongo ORM collections, including relation refinements and grouped SQL collections. Do not rename Mongo query-builder `.skip(n)` calls: that lower-level API continues to mirror the `$skip` pipeline stage.
+  - id: contract-space-restamp
+    summary: |
+      The emitted `contract.json` / `contract.d.ts` embed the toolchain version, which moves
+      to 8.0.0-rc.7. Rebuild the extension's contract space (the package's `build:contract-space`
+      script) once after upgrading so the emitted artifacts match the installed toolchain. The toolchain also re-released against
+      `@prisma/cli-engine@0.2.3` (a CLI-side change with no ORM-facing surface).
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"version": "8.0.0-rc.6"'
+---
+
+# 8.0.0-rc.6 → 8.0.0-rc.7 — Extension author upgrade instructions
+
+## `rename-orm-pagination-methods`
+
+Find calls on Prisma 8 ORM collections in extension source and tests, then apply these translations:
+
+- `.take(n)` → `.limit(n)`
+- `.skip(n)` → `.offset(n)`
+
+Apply the same translation inside `include(...)` refinement callbacks, `combine(...)` branches, and after SQL ORM `groupBy(...)`. Leave Mongo query-builder chains that start from `mongoQuery(...).from(...)` or an equivalent query-builder factory unchanged: their `.limit(...)` and `.skip(...)` methods name Mongo aggregation pipeline stages rather than the ORM collection API.
+
+## `contract-space-restamp`
+
+For every `contract.json` matched by `detection`, run the extension package's `build:contract-space` script (or its emit command) once after upgrading. The only expected diff beyond the pagination rename is the embedded `version` moving to `8.0.0-rc.7`.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.7-to-8.0.0-rc.8/instructions.md

@@ -0,0 +1,35 @@
+---
+from: "8.0.0-rc.7"
+to: "8.0.0-rc.8"
+changes:
+  - id: engine-pin-moves-to-0-3-0
+    summary: |
+      The toolchain now peers `@prisma/cli-engine@0.3.0` (up from 0.2.3). An extension that
+      pins `@prisma/cli-engine` in its own manifests must move the pin to `0.3.0`. The engine
+      now declares `@prisma/management-api-sdk` as a peer dependency (`^1.55.0`) instead of a
+      regular dependency; the `prisma` CLI shell supplies it at runtime, so only tooling that
+      runs the engine outside the CLI shell needs to install the SDK itself.
+    detection:
+      glob: "**/package.json"
+      contains:
+        - '"@prisma/cli-engine": "0.2.3"'
+  - id: contract-space-restamp
+    summary: |
+      The emitted `contract.json` / `contract.d.ts` embed the toolchain version, which moves
+      to 8.0.0-rc.8. Rebuild the extension's contract space (the package's `build:contract-space`
+      script) once after upgrading so the emitted artifacts match the installed toolchain.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"version": "8.0.0-rc.7"'
+---
+
+# 8.0.0-rc.7 → 8.0.0-rc.8 — Extension author upgrade instructions
+
+## `engine-pin-moves-to-0-3-0`
+
+For every `package.json` matched by `detection`, change the `@prisma/cli-engine` version from `0.2.3` to `0.3.0` and reinstall. If the extension's tooling runs the engine outside the unified `prisma` CLI shell (rare), also install `@prisma/management-api-sdk` at a version satisfying `^1.55.0` — the engine now declares it as a peer dependency and no longer bundles it.
+
+## `contract-space-restamp`
+
+For every `contract.json` matched by `detection`, run the extension package's `build:contract-space` script (or its emit command) once after upgrading. The only expected diff is the embedded `version` moving to `8.0.0-rc.8`.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.8-to-8.0.0-rc.9/instructions.md

@@ -0,0 +1,86 @@
+---
+from: "8.0.0-rc.8"
+to: "8.0.0-rc.9"
+changes:
+  - id: remove-nested-relations-from-sql-orm-upsert-and-batch-create
+    summary: |
+      SQL ORM `upsert({ create })`, `createAll()`, and `createAndCount()` payloads no longer accept nested relation mutation callbacks, which these operations cannot execute. Remove the callbacks and create related records separately, or use ordinary `create()` when the records must be created as one nested relation operation.
+  - id: namespace-qualify-sql-orm-filter-types
+    summary: |
+      SQL ORM reusable filter types now require the domain namespace before the model name: `<Contract, Namespace, Model>`.
+  - id: add-attributes-to-psl-extension-block-literals
+    summary: |
+      `PslExtensionBlock` gained a required `attributes` record (attribute name → `{ args, span }`, the kit-parsed values of the block's `@@` attributes). Every hand-built block node — synthesised blocks in scripts, inference builders, and test fixtures — must set `attributes` next to `blockAttributes` (`{}` when the block carries no attributes).
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "blockAttributes:"
+      anyMatch: true
+  - id: read-native-enum-map-failures-from-the-kit
+    summary: |
+      `PSL_NATIVE_ENUM_INVALID_MAP` no longer exists. A malformed `@@map` on a `native_enum` block — and every other malformed block attribute — is reported at symbol-table time as `PSL_INVALID_ATTRIBUTE_SYNTAX`; only the policy `@@map("")` empty-name rule keeps its own code (`PSL_POLICY_INVALID_MAP`). Replace references to the removed code and assert those diagnostics on the `buildSymbolTable` result rather than on the interpretation result.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "PSL_NATIVE_ENUM_INVALID_MAP"
+      anyMatch: true
+  - id: arg-type-parse-is-a-property
+    summary: |
+      `ArgType.parse` is now a property function type carrying a `Ctx` parameter, so the ctx an argument type needs is checked contravariantly. A class that implements `ArgType` with a `parse(...)` method, or an object typed against `ArgType<T>` and used inside `blockAttribute()`, must declare `parse` as a function-typed property over the ctx it actually reads.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "implements ArgType"
+        - "ArgType<"
+      anyMatch: true
+  - id: state-attribute-spec-contexts-explicitly
+    summary: |
+      The attribute-spec interpret contexts were reshaped. `BlockInterpretCtx` and `InterpretCtx` are gone, replaced by `AttributeCtx` (`sourceId` + `sourceFile`), `ModelAttributeCtx` (adds `selfModel`), and `FieldAttributeCtx` (adds a required `field` and `resolveReferencedModel()`). Contexts no longer carry `level`. `ArgType`, `OptionalArgType`, `Param`, `PositionalParam`, and `AttributeSpec` lost their default type arguments, so every use site must name its context. `fieldRef('self')` / `fieldRef('referenced')` became `fieldRef()` / `referencedFieldRef()`, and `FieldRefScope`, `FieldRefArgType`, and the `scope` property are removed. `oneOf` is one generic signature over a single context shared by every alternative, so a mixed alternation must be given that context by an annotation or a contextual type.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "InterpretCtx"
+        - "fieldRef("
+        - "FieldRefScope"
+        - "FieldRefArgType"
+        - "ArgType<"
+        - "AttributeSpec<"
+        - "PositionalParam"
+      anyMatch: true
+---
+
+# 8.0.0-rc.8 → 8.0.0-rc.9 — Extension author upgrade instructions
+
+## `remove-nested-relations-from-sql-orm-upsert-and-batch-create`
+
+Find SQL ORM calls to `upsert()`, `createAll()`, and `createAndCount()` whose create payloads contain relation fields assigned callback functions. Remove those callbacks and create the related records separately. When the operation requires nested relation creation, replace it with ordinary `create()`, which continues to accept and execute relation mutation callbacks.
+
+## `namespace-qualify-sql-orm-filter-types`
+
+Find TypeScript references to `ShorthandWhereFilter`, `RelationPredicate`, `RelationPredicateInput`, and `RelationFilterAccessor`. Add the model's domain namespace as the second generic argument and place the model name third. Rewrite `ShorthandWhereFilter<Contract, Model>` as `ShorthandWhereFilter<Contract, Namespace, Model>` and `ShorthandWhereFilter<Contract, Model, Namespace>` as `ShorthandWhereFilter<Contract, Namespace, Model>`. Rewrite the relation types from `<Contract, Model>` to `<Contract, Namespace, Model>`. For predicates targeting a relation, use the namespace declared by that relation's `to.namespace` coordinate.
+
+## `add-attributes-to-psl-extension-block-literals`
+
+Find every object literal typed as `PslExtensionBlock` (they carry `kind`, `keyword`, `name`, `parameters`, `blockAttributes`, `span`). Add `attributes` beside `blockAttributes`. A block with no `@@` attributes takes `attributes: {}`. A block synthesised with a `blockAttributes` entry takes the parsed shape of that entry, keyed by attribute name with the spec's positional keys as `args` — for example a synthesised `@@map("x")` on a `policy_*` or `native_enum` block becomes `attributes: { map: { args: { name: 'x' }, span } }`. Consumers that read a block attribute read `block.attributes[name]?.args`, never `block.blockAttributes`.
+
+## `read-native-enum-map-failures-from-the-kit`
+
+Delete every reference to `PSL_NATIVE_ENUM_INVALID_MAP`. Where a test asserted that code after interpreting a document, parse the document and assert `PSL_INVALID_ATTRIBUTE_SYNTAX` on the diagnostics `buildSymbolTable` returns instead; interpretation no longer sees a malformed block attribute. A `@@map(foo)` argument reports `Expected a string literal`; a missing argument reports `Attribute "map" is missing required argument "name"`.
+
+## `arg-type-parse-is-a-property`
+
+Find classes declaring `implements ArgType<…>` with a `parse(arg, ctx)` method and object literals typed against `ArgType<T>`. Declare `parse` as a property whose type is `(arg: ExpressionAst, ctx: Ctx) => Result<T, readonly PslDiagnostic[]>`. Pick the narrowest `Ctx` the implementation actually reads, as the next entry describes. Dispatch on the syntax node with `XAst.cast(arg.syntax)` rather than `arg instanceof XAst` so the argument type keeps working when the spec and the parser come from different module copies.
+
+## `state-attribute-spec-contexts-explicitly`
+
+**Rename the context types.** `BlockInterpretCtx` becomes `AttributeCtx`. `InterpretCtx` splits: use `ModelAttributeCtx` where the code reads `selfModel` and nothing else, and `FieldAttributeCtx` where it reads `field` or `resolveReferencedModel()`. Both are exported from `@internal/psl-parser`.
+
+**Drop `level` from every context value.** A hand-built ctx object that set `level: 'field' | 'model' | 'block'` must delete that property; contexts no longer declare it. `AttributeSpec.level` is a different field and is unchanged — keep setting and reading it.
+
+**Move `resolveReferencedModel` down to the field level.** A model-level ctx must no longer supply it. The `resolveReferencedModel: () => undefined` stub that model-level ctx builders carried is now a type error; delete it. A field-level ctx must supply both `field` (previously optional, now required) and `resolveReferencedModel()`.
+
+**Name a context at every use site.** `ArgType<T>`, `OptionalArgType<T>`, `Param<T>`, `PositionalParam<T>`, and `AttributeSpec<Out>` no longer default their second type argument. Rewrite each as `ArgType<T, AttributeCtx>` when the combinator reads only `sourceId` / `sourceFile`, `ArgType<T, ModelAttributeCtx>` when it reads `selfModel`, and `ArgType<T, FieldAttributeCtx>` when it reads `field` or `resolveReferencedModel()`; the same choice applies to the other four. `PositionalParam` also lost its `T = unknown` default, so a bare `PositionalParam` becomes `PositionalParam<unknown, Ctx>`. Prefer the widest context that still typechecks: a spec parameter over `AttributeCtx` is usable inside `blockAttribute()`, `modelAttribute()`, and `fieldAttribute()` alike.
+
+**Split the field reference combinator.** Replace `fieldRef('self')` with `fieldRef()` and `fieldRef('referenced')` with `referencedFieldRef()` (imported from `@internal/psl-parser`). `fieldRef()` is typed over `ModelAttributeCtx` and stays usable in model attributes such as `@@index`; `referencedFieldRef()` is typed over `FieldAttributeCtx` and is accepted only in field attributes. The `FieldRefScope` and `FieldRefArgType` types and the `scope` property on the returned combinator are removed — a test asserting `fieldRef('self').scope` has no replacement; assert on the parse behaviour or on `label` instead.
+
+**Give `oneOf` one context for all of its alternatives.** `oneOf` is now a single generic signature: the output is the union of the alternatives' outputs, and every alternative parses over the same context. An alternation whose alternatives all read only `sourceId` / `sourceFile` — `str()`, `num()`, `bool()`, `identifier()`, `json()`, `entityRef()`, `funcCall()` — needs nothing; its context is `AttributeCtx` and it stays usable at every level. An alternation that mixes those with a model-scoped or field-scoped alternative such as `fieldRef()` must be told which context it parses over, because `oneOf` no longer computes one from the alternatives. Supply it from the surrounding code: annotate the result (`const arm: ArgType<string, ModelAttributeCtx> = oneOf(str(), fieldRef())`), annotate the alternatives tuple before spreading it into `oneOf(...arms)`, or let the enclosing function's return type provide it. Such an alternation remains rejected inside `blockAttribute()`.

package/skills/prisma-8/upgrading/extension/upgrades/8.0.0-rc.9-to-8.0.0-rc.10/instructions.md

@@ -0,0 +1,63 @@
+---
+from: "8.0.0-rc.9"
+to: "8.0.0-rc.10"
+# sql-orm-client doc-comment sweep: reviewed, no entry required
+# postgres shell dependency ownership: reviewed, no extension-author action required; bundled packages now declare the catalog Node/pg type dependencies that public shell manifests mirror
+changes:
+  - id: schema-header-use-prisma-8
+    summary: |
+      The schema header that marks a Prisma 8 schema is now `// use prisma-8`. The language server
+      still serves the old header and its Format action rewrites it; new schemas and the
+      inferred-schema printer write the new form. Replace `// use prisma-next`
+      at the top of every `.prisma` file the extension ships or tests against.
+    detection:
+      glob: "**/*.prisma"
+      contains:
+        - "// use prisma-next"
+  - id: env-vars-drop-next-infix
+    summary: |
+      The CLI environment variables lost their `NEXT_` infix: `PRISMA_NEXT_DISABLE_TELEMETRY`,
+      `PRISMA_NEXT_TELEMETRY_ENDPOINT`, `PRISMA_NEXT_DEBUG`, and the rest are now
+      `PRISMA_DISABLE_TELEMETRY`, `PRISMA_TELEMETRY_ENDPOINT`, `PRISMA_DEBUG`, and so on. The old
+      `PRISMA_NEXT_DISABLE_TELEMETRY` opt-out is still honoured; the others are not. Rename them
+      in the extension's test setup and CI configuration.
+    detection:
+      glob: "**/*"
+      contains:
+        - "PRISMA_NEXT_"
+  - id: to-one-relations-record-nullable
+    summary: |
+      `ContractNonJunctionRelation`'s `'1:1'` and `'N:1'` members now require `nullable: boolean`,
+      and contract validation rejects a `contract.json` whose to-one relations lack it. Set
+      `nullable` on every to-one relation the extension constructs, and rebuild the extension's
+      contract space so its emitted `contract.json` / `contract.d.ts` carry the flag.
+    detection:
+      glob: "**/*.ts"
+      matches:
+        - '(?<!\bnullable\b(?:[^{}]|\{[^{}]*\})*)(?:(?<=\bon\s*:(?:[^{}]|\{[^{}]*\})*)|(?=(?:[^{}]|\{[^{}]*\})*\bon\s*:))\bcardinality:\s*[''"](?:N:1|1:1)[''"](?!(?:[^{}]|\{[^{}]*\})*\bnullable\b)'
+  - id: contract-space-re-emit-nullable
+    summary: |
+      The extension's emitted `contract.json` must carry `nullable` on every `1:1` and `N:1`
+      relation. Rebuild the contract space (the package's `build:contract-space` script) once
+      after upgrading.
+    detection:
+      glob: "**/contract.json"
+      matches:
+        - '"cardinality":\s*"(?:N:1|1:1)",\s*"on":'
+---
+
+## `to-one-relations-record-nullable`
+
+For every TypeScript file matched by `detection`, find each object literal that builds a to-one contract relation (`cardinality: 'N:1'` or `'1:1'` together with an `on` join) and add `nullable: <boolean>` to it: `true` when the relation field is optional (the local foreign-key columns are nullable), `false` when it is required. The side of a one-to-one relation that does not own the foreign key is always `nullable: true`. Contract builders and PSL authoring set the flag from the field's `?`, so only code that assembles `ContractRelation` values by hand needs the edit.
+
+## `contract-space-re-emit-nullable`
+
+For every `contract.json` matched by `detection`, run the extension package's `build:contract-space` script (or its emit command) once after upgrading. The expected diff is one `"nullable"` boolean per to-one relation in `contract.json`, plus the `Models` namespace, `models` constant, and `RelationKeys` import in `contract.d.ts`.
+
+## `schema-header-use-prisma-8`
+
+For every `.prisma` file matched by `detection`, replace the first-line header `// use prisma-next` with `// use prisma-8`. Nothing else in the file changes.
+
+## `env-vars-drop-next-infix`
+
+For every file matched by `detection`, replace the `PRISMA_NEXT_` prefix with `PRISMA_` on each environment variable name.

package/dist/bin__prisma-next.mjs

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import "@prisma/orm-toolchain/bin/prisma-next";
-export {};