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

package/skills/prisma-8/references/upgrade-app.md

@@ -0,0 +1,101 @@
+# Upgrade Prisma 8 (user app)
+
+This reference upgrades a project that **consumes** Prisma 8 via the public package API (`@internal/postgres`, `@internal/mongo`, the contract files in `prisma/`, etc.). If the project is itself a Prisma 8 *extension*, use [`upgrade-extension.md`](upgrade-extension.md) instead — or both, if the repo contains both an app and an extension package.
+
+The per-transition instructions this reference reads live under [`../upgrading/app/upgrades/`](../upgrading/app/upgrades/).
+
+## Step 0 — Upgrade to the newest instructions, then re-read
+
+The upgrade instructions ship inside the installed Prisma packages, so the copy on disk describes the version currently installed — not the version being upgraded *to*. Bug fixes to *old* per-transition instructions ship with each release as part of the cumulative set, so the newest copy is the one to run.
+
+Do the version bump first (step 1 of the per-step flow below), re-sync the skills from the newly installed packages (`prisma skills sync`), and re-read this reference and the per-transition instructions before applying any code translation. If the agent runtime supports an in-session refresh, perform it after the sync; otherwise finish the session's reasoning against the re-read files.
+
+## Pre-flight — extension compatibility
+
+Before changing any code, refuse to upgrade past any installed extension's pinned Prisma Next version. Extensions in Prisma Next pin every `@internal/*` dependency to a single exact version (no carets, no ranges); that pin is the highest version the extension has been validated against. Upgrading the user app past that pin would silently desynchronise the extension's type identity from the app's.
+
+Steps:
+
+1. **Read `prisma.config.ts`** (or its TS-discoverable equivalent at the project root) and enumerate the list of extension packages it imports. Each `extensions: [...]` entry corresponds to an installed npm package.
+2. **For each extension**, read its installed `package.json` from `node_modules/<extension-package-name>/package.json` and find any `@internal/*` entry under `dependencies`, `peerDependencies`, or `optionalDependencies`. By construction those entries are exact-version pins (e.g. `"0.7.0"`), set when the extension author last ran their own upgrade.
+3. **Compute the lowest pinned version across all extensions.** That is the highest Prisma Next version reachable by this app on its current extension set.
+4. **Compare to the user's target.** If the target exceeds the lowest pin, halt with a structured message naming each lagging extension and its pinned version, and offer two paths:
+   - (a) Wait for the lagging extension to publish a compatible release, then re-run.
+   - (b) Re-run with `--to=<highest-reachable>` (or whatever flag/option the user is using to set the target).
+
+Do not auto-downgrade the target; do not skip the lagging extension; do not bump past it. If the user explicitly overrides the halt, surface the risk clearly first.
+
+If `prisma.config.ts` is absent or names no extensions, skip the pre-flight.
+
+## Role detection
+
+This flow applies when the project **consumes** Prisma Next:
+
+- `package.json` declares one or more `@internal/*` packages under `dependencies` / `devDependencies`, and
+- the package is *not* itself an extension (no `@internal/contract` (or other SPI) under `dependencies`/`peerDependencies`; name does not match `^@.*/extension-`; not referenced from a sibling app's `prisma.config.ts`).
+
+If the project also matches the extension-author role, run **this** flow first and then [`upgrade-extension.md`](upgrade-extension.md) in the same session. If detection is ambiguous, ask the user.
+
+## Version detection
+
+- **From-version.** Read the currently-installed Prisma Next version from `pnpm-lock.yaml` (or `package-lock.json` / `yarn.lock`) by inspecting the resolved version of any `@internal/*` package. If the lockfile shows multiple `@internal/*` packages at different minors (already broken), the **lowest** minor is the from-version.
+- **To-version.** Either the version the user specified, or whatever `npm view @internal/postgres dist-tags.latest` reports. Do not assume that is a stable version: while Prisma 8 is a release candidate, `latest` tracks the newest release, `8.0.0-rc.N` included. If the user wants a stable version specifically, they must name it.
+
+Report both back to the user before continuing.
+
+## Transition chain
+
+If the from-to delta spans more than one release (e.g. `0.6 → 0.8`), build the chain of steps between them:
+
+```text
+0.6 → 0.7 → 0.8
+```
+
+The [`../upgrading/app/upgrades/`](../upgrading/app/upgrades/) directories name the steps — read the chain off the directory names rather than deriving it arithmetically. Each directory is `<from>-to-<to>`. A step is one minor while the version line is stable (`0.7-to-0.8`); on the v8 release-candidate line a step is one release candidate (`8.0.0-rc.1-to-8.0.0-rc.2`), because an RC may carry breaking changes and each one needs its own translation. Moving onto the RC line from the last stable minor is a single step of its own (`0.17-to-8.0.0-rc.1`).
+
+Apply each step in order, fully: bump, install, run instructions, validate, commit — before moving to the next. Halt the chain on the first failed step; do not skip ahead.
+
+The chain order does not depend on which extensions are installed; the pre-flight has already established the target is reachable.
+
+## Per-step flow
+
+For each `(from, to)` step in the chain:
+
+1. **Bump `@internal/*` deps.** Rewrite every `@internal/*` entry in the project's `package.json` to the exact `<to>` version (no caret, no tilde). All entries advance to the same version. Cover `dependencies` and `devDependencies`. The skill itself ships inside the Prisma packages, so bumping them is what updates it; there is no separate skill package to bump.
+
+2. **Install.** Run `pnpm install` (or the project's lockfile-managing command). The project's code is now broken against the new types — the upgrade instructions for `<from> → <to>` exist to fix it.
+
+3. **Read the upgrade instructions.** Re-sync the skills (`prisma skills sync`) so the tree matches the version just installed, then load `../upgrading/app/upgrades/<from>-to-<to>/instructions.md`. Parse the YAML frontmatter and pay particular attention to its `changes[]` array.
+
+4. **Apply each change.** For each entry in `changes[]`:
+   - If the entry has a `detection` block (glob + content predicate), run it; skip the change if no files match. No `detection` → apply unconditionally.
+   - If the entry names a `script:` (a relative path next to `instructions.md`), invoke it from the project root:
+     - `*.ts` → `pnpm exec tsx <skill>/upgrading/app/upgrades/<from>-to-<to>/<script>`
+     - `*.sh` → `bash <skill>/upgrading/app/upgrades/<from>-to-<to>/<script>`
+     - codemods → invoke per the script's own prose.
+
+     No `script` → follow the prose body directly.
+
+   Empty `changes[]` (placeholder shape for transitions with no user-side breaking changes) is a no-op — proceed to validation.
+
+5. **Validate.** Run `pnpm typecheck && pnpm test` (or the project's equivalent — the `scripts` field of the project's `package.json` is the discovery surface). If anything is red, halt the chain. Do **not** auto-roll-back; surface the failure to the user with the failing change's `id` (from the frontmatter), the file paths the change operated on, and the inferred remediation.
+
+6. **Commit.** One commit per step containing the `package.json` bump, lockfile churn, and any source rewrites:
+
+   ```text
+   chore: upgrade @internal/* to <to-version>
+   ```
+
+   (Or the project's own commit-message convention.) Never squash steps. The user may squash on merge; the in-flight history must be per-step so a failed step is bisectable.
+
+Then move on to the next step.
+
+## When the chain is done
+
+Report back to the user: the number of steps applied, the SHAs of the commits you made, and any open follow-ups (e.g. tests that were already red before the upgrade and still are).
+
+## Failure surfaces
+
+When a step fails: surface a structured error with code `PN-UPGRADE-NNNN`, the failing change's `id`, the file paths touched (or the lockfile, or the validation command), and the inferred remediation. Do not retry automatically; do not auto-roll-back. The user can revert if they want a clean slate.
+
+If a pre-flight halt fires, do not bump anything; the project is left unchanged.

package/skills/prisma-8/references/upgrade-extension.md

@@ -0,0 +1,105 @@
+# Upgrade Prisma 8 (extension)
+
+This reference upgrades a project that **is** a Prisma 8 extension — a package that consumes the framework SPI (`@internal/contract`, `@internal/framework-components`, `@internal/migration-tools`, etc.) and exposes contract / middleware / codec / migration surfaces that downstream apps install via `prisma.config.ts`.
+
+If the project you are upgrading is a consumer **app** (it imports `@internal/postgres` or `@internal/mongo` from its application code), use [`upgrade-app.md`](upgrade-app.md) instead — or both, if the repo contains both a consumer app and an extension package, in which case run the app flow first then this one in the same session.
+
+The per-transition instructions this reference reads live under [`../upgrading/extension/upgrades/`](../upgrading/extension/upgrades/).
+
+## Step 0 — Upgrade to the newest instructions, then re-read
+
+The upgrade instructions ship inside the installed Prisma packages, so the copy on disk describes the version currently installed — not the version being upgraded *to*. Bug fixes to *old* per-transition instructions ship with each release as part of the cumulative set, so the newest copy is the one to run.
+
+Do the version bump first (step 1 of the per-step flow below), re-sync the skills from the newly installed packages (`prisma skills sync`), and re-read this reference and the per-transition instructions before applying any code translation.
+
+## Role detection
+
+This flow applies when the project **is** a Prisma Next extension. Heuristics:
+
+- `package.json` declares `@internal/contract` (or another SPI package) under `dependencies` or `peerDependencies`, and
+- the package's `name` matches `^@.*/extension-` (the in-tree convention used by `@internal/extension-pgvector`, etc.), or
+- the package is referenced as an `extensions` entry from a sibling app's `prisma.config.ts` in the same monorepo.
+
+If the project additionally consumes Prisma Next from its own app code, run [`upgrade-app.md`](upgrade-app.md) first, then this flow in the same session.
+
+If detection is ambiguous, ask the user which role to operate under.
+
+## Version detection
+
+- **From-version.** Read the currently-installed Prisma Next version from `pnpm-lock.yaml` (or `package-lock.json` / `yarn.lock`) by inspecting the resolved version of any `@internal/*` entry. If the lockfile shows multiple `@internal/*` packages at different minors, the lowest minor is the from-version.
+- **To-version.** Either the version the user specified, or whatever `npm view @internal/contract dist-tags.latest` reports. Do not assume that is a stable version: while Prisma 8 is a release candidate, `latest` tracks the newest release, `8.0.0-rc.N` included. If the user wants a stable version specifically, they must name it.
+
+Report both back to the user before continuing.
+
+## Transition chain
+
+If the from-to delta spans more than one release (e.g. `0.6 → 0.8`), build the chain of steps between them:
+
+```text
+0.6 → 0.7 → 0.8
+```
+
+The [`../upgrading/extension/upgrades/`](../upgrading/extension/upgrades/) directories name the steps — read the chain off the directory names rather than deriving it arithmetically. Each directory is `<from>-to-<to>`. A step is one minor while the version line is stable (`0.7-to-0.8`); on the v8 release-candidate line a step is one release candidate (`8.0.0-rc.1-to-8.0.0-rc.2`), because an RC may carry breaking changes and each one needs its own translation. Moving onto the RC line from the last stable minor is a single step of its own (`0.17-to-8.0.0-rc.1`).
+
+Apply each step in order, fully: bump, install, run instructions, check pins, validate, commit — before moving to the next. Halt the chain on the first failed step.
+
+## Per-step flow
+
+This flow assumes you are an **external extension author** — your extension lives in its own repo and consumes `@internal/*` from npm. (Extensions inside the `prisma/prisma` monorepo itself are bumped via `pnpm bump-version` / `scripts/set-version.ts`, which rewrites every `workspace:<X.Y.Z>` spec in lockstep with the root version; they do not run this skill.)
+
+For each `(from, to)` step in the chain:
+
+1. **Bump `@internal/*` deps.** Rewrite every `@internal/*` entry in the extension's `package.json` to the exact `<to>` version (e.g. `"0.8.0"` — no caret, no tilde, no range, no `workspace:` specifier; the exact-pin rule below details why). All entries advance to the same version. Cover whichever dep field(s) the extension uses today — `dependencies` and/or `peerDependencies` — and any `optionalDependencies`. The skill itself ships inside the Prisma packages, so bumping them is what updates it; there is no separate skill package to bump. The companion CLI tool is `@internal/extension-author-tools` — leave its pin at the version the extension's CI is currently using; bumping it is independent of the framework upgrade and is normally a no-op.
+
+2. **Install.** Run `pnpm install` (or the project's lockfile-managing command). The extension's source is now broken against the new SPI — the upgrade instructions for `<from> → <to>` exist to fix it.
+
+3. **Check pins.** Run `pnpm exec prisma-8-check-pins` (shipped by `@internal/extension-author-tools`). This sanity check asserts that every `@internal/*` entry across `dependencies`, `peerDependencies`, and `optionalDependencies` is a single exact-version string and that all entries share the same version. If the check fails, the bump step did not rewrite every spec — fix the offending entries and re-run before proceeding.
+
+4. **Read the upgrade instructions.** Re-sync the skills (`prisma skills sync`) so the tree matches the version just installed, then load `../upgrading/extension/upgrades/<from>-to-<to>/instructions.md`. Parse the YAML frontmatter and pay particular attention to its `changes[]` array.
+
+5. **Apply each change.** For each entry in `changes[]`:
+   - If the entry has a `detection` block (a glob + content predicate), run it. If no files match, skip this change.
+   - If the entry has no `detection`, apply unconditionally.
+   - If the entry names a `script:` (a relative path next to `instructions.md`), invoke it from the project root:
+     - `*.ts` → `pnpm exec tsx <skill>/upgrading/extension/upgrades/<from>-to-<to>/<script>`
+     - `*.sh` → `bash <skill>/upgrading/extension/upgrades/<from>-to-<to>/<script>`
+     - codemods → invoke per the script's own `instructions.md` prose.
+   - If the entry has no `script`, follow the prose body in `instructions.md` directly.
+
+   If `changes[]` is empty (the placeholder shape for transitions with no extension-side breaking changes), this sub-step is a no-op — proceed to validation.
+
+6. **Validate.** Run `pnpm build && pnpm test` (or the project's equivalent — the `scripts` field of the extension's `package.json` is the discovery surface). If anything is red, halt the chain. Do **not** auto-roll-back; surface the failure to the user with the failing change's `id` (from the frontmatter), the file paths the change operated on, and the inferred remediation.
+
+7. **Commit.** Create one commit containing this step's changes: the `package.json` bump, the lockfile churn from `pnpm install`, and any source-file rewrites from the applied changes. Use the message:
+
+   ```text
+   chore: upgrade @internal/* to <to-version>
+   ```
+
+   (Or the extension's own commit-message convention, if it has one.) One commit per step — never squash steps.
+
+Move on to the next step. Repeat.
+
+## Exact-pin rule
+
+Prisma Next extensions pin every `@internal/*` dependency to a single **exact** version (no `^`, no `~`, no range, no wildcard, no `workspace:` specifier in the published `package.json`). All `@internal/*` entries share the same version. The pin advances only after a successful upgrade run against the new minor.
+
+`prisma-8-check-pins` (shipped by `@internal/extension-author-tools` — install with `pnpm add -D @internal/extension-author-tools`) enforces the rule. Run it locally with:
+
+```bash
+pnpm exec prisma-8-check-pins
+```
+
+Wire it into the extension's CI alongside the build/test step so an accidental range pin fails the PR before it lands.
+
+## When the chain is done
+
+Report back to the user: the number of steps applied, the SHAs of the commits you made, and any open follow-ups.
+
+## Failure surfaces
+
+When a step fails:
+
+- Surface a structured error with code `PN-UPGRADE-NNNN`, the failing change's `id`, the file paths the change touched (or the lockfile, or the pin check, or the validation command), and the inferred remediation.
+- Do not retry automatically.
+- Do not auto-roll-back the commit. The user can revert if they want a clean slate.

package/skills/prisma-8/upgrading/app/upgrades/0.10-to-0.11/instructions.md

@@ -0,0 +1,56 @@
+---
+from: "0.10"
+to: "0.11"
+changes:
+  - id: insert-single-row-wrap-in-array
+    summary: Wrap single-row `.insert({...})` call sites in an array — `.insert([{...}])`. The single-object overload is removed; `.insert()` now exclusively accepts an array of row objects.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - ".insert("
+      anyMatch: true
+---
+
+# 0.10 → 0.11 — User upgrade instructions
+
+## `insert-single-row-wrap-in-array`
+
+Starting at the 0.11 release, the `.insert()` method on the SQL builder accepts **only** an array of row objects. The single-object overload that previously allowed `.insert({ field: value })` is removed.
+
+Before 0.11:
+
+```ts
+await runtime.execute(db.sql.user.insert({ email: 'alice@example.com' }).build());
+```
+
+Starting at 0.11:
+
+```ts
+await runtime.execute(db.sql.user.insert([{ email: 'alice@example.com' }]).build());
+```
+
+Walk every `.ts` / `.tsx` file matched by the `detection.glob` above. For each call site that passes a plain object directly to `.insert(...)`, wrap the argument in an array:
+
+- `.insert(row)` → `.insert([row])`
+- `.insert({ field: value })` → `.insert([{ field: value }])`
+
+Variable references to a row object are safe to wrap directly:
+
+```ts
+// Before
+for (const item of items) {
+  await runtime.execute(db.sql.table.insert(item).build());
+}
+// After
+for (const item of items) {
+  await runtime.execute(db.sql.table.insert([item]).build());
+}
+```
+
+If a call site already passes an array (`.insert([row1, row2])`), it is already correct — leave it unchanged.
+
+TypeScript will flag bare-object call sites as type errors after the bump, providing a reliable compile-time signal for every affected site.
+
+### Validation
+
+After applying the rule above, run `pnpm typecheck && pnpm test` (or your application's equivalent). The change is mechanical — every affected call site is flagged at compile time.

package/skills/prisma-8/upgrading/app/upgrades/0.11-to-0.12/instructions.md

@@ -0,0 +1,381 @@
+---
+from: "0.11"
+to: "0.12"
+changes:
+  - id: replace-verify-with-verify-marker
+    summary: |
+      The SQL runtime's `verify: { mode; requireMarker }` option is removed; replaced by `verifyMarker?: 'onFirstUse' | false` (default `'onFirstUse'`). The runtime no longer throws on contract-marker drift — instead it emits a structured `warn`-level log line once per runtime instance and proceeds with the query. Callers that previously caught `CONTRACT.MARKER_MISMATCH` to detect deploy-skew migrate to log scraping (filter on `code: 'CONTRACT.MARKER_MISMATCH'` / `code: 'CONTRACT.MARKER_MISSING'` from the runtime's `Log.warn` sink) or invoke the explicit `db-verify` CLI for fail-fast verification.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "verify:"
+        - "requireMarker"
+      anyMatch: false
+  - id: remove-capabilities-from-define-contract
+    summary: |
+      The `capabilities` field on the first argument of `defineContract({...}, ...)` is removed. Capabilities are now contributed automatically by extension packs and target components; declaring them by hand is no longer accepted and the contract builder will refuse the literal. Delete the `capabilities: { ... }` block from every `defineContract` call site, then re-emit your contract artefacts (`pnpm emit`, which runs `prisma-next contract emit`) to refresh `contract.json` / `contract.d.ts`. The regenerated artefacts pick up the contributor-declared capabilities — including two new ones in the 0.12 line, `postgres.distinctOn` and `sql.lateral`, which extensions contribute on your behalf when their pack is in `extensionPacks`.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "defineContract"
+        - "capabilities:"
+      anyMatch: false
+  - id: strip-migration-labels-hints
+    summary: |
+      The 0.12 migration manifest schema is closed (`'+': 'reject'`) and the metadata model no longer carries `labels` or `hints`; any on-disk `migration.json` still holding either key fails to load with `INVALID_MANIFEST` naming the offending key. Both fields are also dropped from the content-addressed migration identity, so `migrationHash` is now computed over `{ from, to, providedInvariants, createdAt }` plus the sibling `ops.json`. Run the colocated codemod to strip both keys from every `migration.json` and recompute its `migrationHash` over the slimmed envelope.
+    detection:
+      glob: "**/migration.json"
+      contains:
+        - '"labels"'
+        - '"hints"'
+      anyMatch: true
+    script: ./strip-migration-labels-hints.ts
+  - id: re-emit-closed-mongo-contracts
+    summary: |
+      Re-emit Mongo contract artefacts so emitted `$jsonSchema` validators are closed (`additionalProperties: false` at every level, including polymorphic `oneOf` branches). Each non-variant Mongo model must resolve to an `objectId` `_id` before emit succeeds — otherwise interpret fails with `PSL_MONGO_ID_REQUIRED`. After re-emitting, apply the open→closed validator migration with `prisma-next db update -y`; the planner classifies the tightening as `destructive` and refuses without confirmation.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"kind": "mongo-database"'
+      anyMatch: true
+    script: ./re-emit-closed-mongo-contracts.ts
+  - id: public-default-namespace
+    summary: |
+      Un-namespaced Postgres models now emit under the `public` namespace instead of the `__unbound__` sentinel; explicit `namespace unbound { … }` in PSL still round-trips to `__unbound__`. Re-emit contract artefacts (`pnpm emit`, i.e. `prisma-next contract emit`) so `contract.json` / `contract.d.ts` pick up the new storage/domain namespace key (`__unbound__`/`postgres-unbound-schema` → `public`/`postgres-schema`). No hand-editing of emitted JSON is required when the PSL/TS contract source is unchanged.
+    detection:
+      glob: "**/contract.json"
+      contains:
+        - '"kind": "postgres-unbound-schema"'
+      anyMatch: true
+    script: ./re-emit-postgres-public-default.ts
+  - id: domain-plane-namespaced-contract
+    summary: |
+      `contract.models` / `contract.valueObjects` moved under `contract.domain.namespaces.<ns>` (symmetric domain plane). Re-emit contract artefacts (`pnpm emit`) so emitted JSON and `contract.d.ts` carry the namespaced domain envelope; generated types switch from `Contract['models']` to `ContractModelsMap<Contract>`.
+    detection:
+      glob: "**/contract.d.ts"
+      contains:
+        - "Contract['models']"
+      anyMatch: true
+    script: ./re-emit-domain-namespaced-contracts.ts
+  - id: runtime-qualified-sql-default-namespace
+    summary: |
+      Postgres runtime SQL now emits namespace-qualified table identifiers (e.g. `"public"."user"`). Flat `db.sql.*` / `db.*` call sites are unchanged. Update integration or snapshot tests that assert raw SQL strings. Re-emit contract artefacts only if you are still catching up an earlier 0.12 namespacing transition.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - 'FROM "user"'
+      anyMatch: true
+---
+
+# 0.11 → 0.12 — User upgrade instructions
+
+## `replace-verify-with-verify-marker`
+
+Starting at the 0.12 release, the SQL runtime's marker-verification API is simplified. The previous `verify: { mode; requireMarker }` option carried two concerns — *when* to verify and *whether to throw on absent markers* — both of which leaked internal implementation detail into the public API. The new option is a single discriminated union: `verifyMarker?: 'onFirstUse' | false`, with `'onFirstUse'` as the default.
+
+The runtime's response to contract-marker drift also changes. Previously the runtime threw `CONTRACT.MARKER_MISMATCH` (or `CONTRACT.MARKER_MISSING`) on every query when the database's contract hash didn't match the runtime's. From 0.12 onward, the runtime emits a structured `warn`-level log line **once per runtime instance** and proceeds with the query. The intent is to make rolling deploys safe by default: a drifted-but-running app surfaces the warning loudly without crashing every query for the duration of the deploy window.
+
+### Migration
+
+Walk every call site that constructs a SQL runtime via `createRuntime(...)` or the convenience wrappers (`sqlite(...)`, `postgres(...)`, `postgresServerless(...)`).
+
+For each call site that passes `verify: {...}`:
+
+- `verify: { mode: 'onFirstUse', requireMarker: false }` → `verifyMarker: 'onFirstUse'` (or simply omit the option — `'onFirstUse'` is the default).
+- `verify: { mode: 'onFirstUse', requireMarker: true }` → `verifyMarker: 'onFirstUse'`. The `requireMarker: true` semantics (throw on absent marker) is removed; if you need fail-fast verification, use the `db-verify` CLI command at deploy time instead of relying on the runtime to crash.
+- `verify: { mode: 'always', requireMarker: ... }` → `verifyMarker: 'onFirstUse'`. The `'always'` mode (re-verify on every query) is dropped; verification is now once-per-runtime regardless of mode. The CLI `db-verify` command remains the explicit-verification surface.
+- `verify: { mode: 'startup', requireMarker: ... }` → `verifyMarker: 'onFirstUse'`. The `'startup'` mode is dropped for the same reason — without the throw-on-mismatch semantic, the `'startup'` vs `'onFirstUse'` distinction collapsed to "same behaviour, different timing." Verification fires lazily on the first `execute()` call.
+- If you explicitly want to skip marker verification entirely (e.g. during a known-skewed deploy window where contract drift is expected and tolerated): `verifyMarker: false`.
+
+### Before 0.12
+
+```ts
+const runtime = createRuntime({
+  stackInstance,
+  context,
+  driver,
+  verify: { mode: 'onFirstUse', requireMarker: false },
+});
+
+try {
+  for await (const row of runtime.execute(plan)) {
+    // ...
+  }
+} catch (err) {
+  if (err.code === 'CONTRACT.MARKER_MISMATCH') {
+    // deploy-skew detected — crash and let the orchestrator restart us
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+### Starting at 0.12
+
+```ts
+const runtime = createRuntime({
+  stackInstance,
+  context,
+  driver,
+  log: {
+    info: console.info,
+    warn: (payload) => {
+      console.warn(payload);
+      if (
+        payload.code === 'CONTRACT.MARKER_MISMATCH' ||
+        payload.code === 'CONTRACT.MARKER_MISSING'
+      ) {
+        // optional: forward to your observability surface
+        sendToTelemetry(payload);
+      }
+    },
+    error: console.error,
+  },
+  // verifyMarker omitted — 'onFirstUse' is the default
+});
+
+for await (const row of runtime.execute(plan)) {
+  // ...
+}
+```
+
+The runtime now does not crash on drift — it emits one structured log line per runtime instance, then proceeds. Operators who want fail-fast verification at deploy time (rather than as a per-runtime diagnostic) should invoke the `db-verify` CLI as part of their deployment pipeline.
+
+### Type-level change
+
+The `RuntimeVerifyOptions` type is removed from `@internal/sql-runtime` exports; replaced by `VerifyMarkerOption = 'onFirstUse' | false`. Any consumer code that imports `RuntimeVerifyOptions` will fail to compile after the bump.
+
+```diff
+-import type { RuntimeVerifyOptions } from '@internal/sql-runtime';
++import type { VerifyMarkerOption } from '@internal/sql-runtime';
+```
+
+### Validation
+
+After applying the rule above, run `pnpm typecheck && pnpm test` (or your application's equivalent). The change is mechanical: TypeScript flags every `verify: {...}` call site as a type error after the bump, and every `RuntimeVerifyOptions` import similarly. Once those errors are resolved, the behaviour change (warn-log instead of throw on drift) shows up only at runtime when a marker mismatch actually occurs.
+
+## `remove-capabilities-from-define-contract`
+
+Starting at the 0.12 release, the `capabilities` field on the first argument of `defineContract({...}, ...)` is removed. Capabilities are now contributed automatically by the target's components and the extension packs you load via `extensionPacks: { ... }`; the contract builder will refuse a literal `capabilities` key. Hand-declaring capabilities was redundant with — and frequently drifted from — the contributor-declared set, so the authoring surface drops the field outright.
+
+Two consumer-visible consequences:
+
+- **Source change**: delete the `capabilities: { ... }` block from every `defineContract` call site.
+- **Emitted artefacts**: the regenerated `contract.json` / `contract.d.ts` will pick up the contributor-declared capabilities. In the 0.12 line, two new capability keys land automatically — `postgres.distinctOn` and `sql.lateral` — when the matching adapter / target component is in the contract's component graph.
+
+### Before 0.12
+
+```ts
+import { defineContract } from '@internal/postgres/contract-builder';
+import { pgvector } from '@internal/pgvector';
+
+export const contract = defineContract(
+  {
+    extensionPacks: { pgvector },
+    capabilities: {
+      postgres: {
+        lateral: true,
+        jsonAgg: true,
+        returning: true,
+        'pgvector.cosine': true,
+      },
+    },
+  },
+  ({ field, model }) => {
+    // … model definitions …
+  },
+);
+```
+
+### Starting at 0.12
+
+```ts
+import { defineContract } from '@internal/postgres/contract-builder';
+import { pgvector } from '@internal/pgvector';
+
+export const contract = defineContract(
+  {
+    extensionPacks: { pgvector },
+  },
+  ({ field, model }) => {
+    // … model definitions …
+  },
+);
+```
+
+If your first argument becomes `{}` after the deletion (the only field it carried was `capabilities`), simplify to `defineContract({}, ({ field, model }) => { … })`. TypeScript flags any remaining `capabilities:` key on a `defineContract` call as an excess-property error after the bump, so every affected site is pinpointed at compile time.
+
+### Re-emit your contract
+
+After updating the source, regenerate the emitted artefacts so the new contributor-declared capabilities land in `contract.json` and `contract.d.ts`:
+
+```bash
+pnpm emit
+# (runs `prisma-next contract emit` under the hood)
+```
+
+You should see capability keys appear in the regenerated `contract.json` — for SQL targets, expect `postgres.distinctOn: true` and `sql.lateral: true` to show up if your contract uses the matching adapter / extensions.
+
+### Validation
+
+After applying the rule above, run `pnpm typecheck && pnpm test` (or your application's equivalent). The change is mechanical and TypeScript pinpoints every affected call site; the regenerated `contract.json` diff confirms the capabilities flowed through unchanged.
+
+## `strip-migration-labels-hints`
+
+Starting at the 0.12 release, the migration manifest schema is closed (`'+': 'reject'`) and the metadata model no longer carries `labels` or `hints`. Any on-disk `migration.json` that still holds either key fails to load: the loader rejects the manifest with `INVALID_MANIFEST`, naming the first offending key (`labels` or `hints`). The two fields are also removed from the content-addressed migration identity — `migrationHash` is now computed over `{ from, to, providedInvariants, createdAt }` plus the sibling `ops.json` — so every migrated manifest additionally needs its hash recomputed over the slimmed envelope, or it fails hash verification on the next load.
+
+Run the colocated codemod from your project root:
+
+```bash
+pnpm exec tsx ./strip-migration-labels-hints.ts
+```
+
+It walks every `migration.json` that has a sibling `ops.json` (a complete on-disk migration package), removes the `labels` and `hints` keys, and recomputes `migrationHash` over the slimmed metadata plus the operations. The edit is format-preserving — only the two key lines are removed and the hash value is swapped in place, so the rest of each manifest (key order, indentation, inline-vs-expanded arrays) is left untouched and the diff stays minimal. The codemod is idempotent: re-running it over already-migrated manifests makes no further changes.
+
+### Confirm every manifest is migrated
+
+Run the codemod in dry-run mode to confirm no manifest still carries the removed keys or a stale hash:
+
+```bash
+pnpm exec tsx ./strip-migration-labels-hints.ts --check
+```
+
+`--check` lists every manifest that still needs fixing and exits non-zero if any remain, so wire it into a pre-commit hook or CI step to keep stale manifests out of the tree. A fully migrated tree reports `0 needing fix` and exits `0`.
+
+### Validation
+
+After running the codemod, exercise any command that loads your migrations (your deploy or migration-status step). The loader recomputes and verifies each manifest's `migrationHash` on read: a manifest that still carried `labels`/`hints` would have thrown `INVALID_MANIFEST`, and a manifest with a stale hash would fail verification. Once the codemod has run, every manifest loads cleanly and its recomputed hash verifies against the slimmed envelope.
+
+## `re-emit-closed-mongo-contracts`
+
+Starting at the 0.12 release, MongoDB emits **closed** `$jsonSchema` validators by default. Every object schema in the emitted contract — collection validators, nested objects, and each branch of a polymorphic `oneOf` — carries `additionalProperties: false`. The contract canonicalizer also preserves `additionalProperties` through emission, so the on-disk migration for consumers is to re-emit their Mongo contracts and apply the resulting validator change to the database.
+
+Two authoring constraints apply before emit succeeds:
+
+- **Closed validators** land automatically on re-emit; no hand-editing of `contract.json` is required.
+- **Non-variant models need an `objectId` `_id`**. The new interpret-time rule `PSL_MONGO_ID_REQUIRED` rejects any non-variant Mongo model whose `_id` field does not resolve to `objectId`. Fix the PSL or TS contract source first — for example, ensure `@id` is present and typed as MongoDB's default `ObjectId` — then re-emit.
+
+### Re-emit your Mongo contracts
+
+Run the colocated script from your project root:
+
+```bash
+pnpm exec tsx ./re-emit-closed-mongo-contracts.ts
+```
+
+It finds every directory with a `prisma.config.ts` and a committed Mongo `contract.json`, then runs `pnpm emit` (or `prisma-next contract emit` when no emit script exists) in each. The regenerated `contract.json` / `contract.d.ts` pick up closed validators and an updated `storageHash`.
+
+Use `--check` to list contracts that still need re-emitting without writing files:
+
+```bash
+pnpm exec tsx ./re-emit-closed-mongo-contracts.ts --check
+```
+
+### Apply the validator migration
+
+Re-emitting changes the contract's `$jsonSchema` shape. The planner classifies the open→closed validator tightening as **`destructive`** — MongoDB replaces collection validators, and documents with fields outside the closed schema will fail validation after apply.
+
+Plan first to review the ops:
+
+```bash
+pnpm prisma-next db update --plan-only
+# or: prisma-next migration plan
+```
+
+Then apply with explicit confirmation:
+
+```bash
+pnpm prisma-next db update -y
+```
+
+Wire `-y` into your deploy pipeline only after you have reviewed the plan in a lower environment. Without `-y`, apply refuses when destructive ops are present.
+
+### Validation
+
+After re-emitting and applying, run `pnpm typecheck && pnpm test` (or your application's equivalent). Contract hash/type drift shows up immediately in TypeScript imports of `StorageHash`. At runtime, confirm `db verify` passes against the updated validators.
+
+## `public-default-namespace`
+
+Starting at the 0.12 release, un-namespaced Postgres models resolve to the `public` namespace id instead of falling back to the `__unbound__` sentinel. The emitted contract's default storage namespace key changes from `__unbound__` with `"kind": "postgres-unbound-schema"` to `public` with `"kind": "postgres-schema"`. Domain roots, FK `namespaceId` fields, and `contract.d.ts` namespace literals follow the same rename.
+
+Explicit opt-in to the sentinel remains available: `namespace unbound { … }` in PSL still round-trips to `__unbound__` on Postgres. Only contracts whose *default* namespace is still the old sentinel shape need this migration.
+
+### Re-emit Postgres contracts
+
+Run the colocated script from your project root:
+
+```bash
+pnpm exec tsx ./re-emit-postgres-public-default.ts
+```
+
+It finds every committed `contract.json` whose storage tree still carries `"kind": "postgres-unbound-schema"`, then runs `pnpm emit` (or `prisma-next contract emit`) in the matching contract space. Use `--check` to list spaces that still need re-emitting without writing files:
+
+```bash
+pnpm exec tsx ./re-emit-postgres-public-default.ts --check
+```
+
+### After re-emit
+
+If your database marker or migration head still references the old contract hash, plan and apply the resulting migration (`prisma-next db update --plan-only`, then `prisma-next db update -y` once reviewed). The schema ops are typically hash/metadata drift only when your PSL source did not change.
+
+### Validation
+
+After re-emitting, run `pnpm typecheck && pnpm test`. Inspect the `contract.json` diff: default models should sit under `storage.namespaces.public` and `domain.namespaces.public`, not `__unbound__`.
+
+## `domain-plane-namespaced-contract`
+
+Starting at the 0.12 release, the application plane is symmetric with storage: models and value objects live under `contract.domain.namespaces.<ns>` instead of flat `contract.models` / `contract.valueObjects` at the contract root (ADR 221). Emitted `contract.d.ts` exports `Models` via `ContractModelsMap<Contract>` rather than `Contract['models']`.
+
+### Re-emit your contracts
+
+Run the colocated script from your project root:
+
+```bash
+pnpm exec tsx ./re-emit-domain-namespaced-contracts.ts
+```
+
+It finds contract spaces whose on-disk artefacts still use the flat domain shape (JSON missing `domain.namespaces`, or `contract.d.ts` still referencing `Contract['models']`), then re-emits each space. Use `--check` for a dry-run:
+
+```bash
+pnpm exec tsx ./re-emit-domain-namespaced-contracts.ts --check
+```
+
+If you already re-emitted for `public-default-namespace` on 0.12, a single emit pass covers both transitions — run whichever entry's detection matches your tree.
+
+### Validation
+
+After re-emitting, run `pnpm typecheck && pnpm test`. The regenerated `contract.json` should carry a `domain.namespaces` envelope; `contract.d.ts` should export a `Models` alias derived from the contract type (on current 0.12 builds this is typically `Contract extends ContractType<StorageBase, infer TModels> ? TModels : never`, not `ContractModelsMap`, which was removed with runtime default-namespace qualification — see `runtime-qualified-sql-default-namespace` below).
+
+## `runtime-qualified-sql-default-namespace`
+
+Starting at the 0.12 release, runtime SQL on Postgres qualifies table identifiers with the storage namespace the flat DSL/ORM surface resolved ([ADR 223](../../../../docs/architecture%20docs/adrs/ADR%20223%20-%20Target-owned%20default%20namespace.md)). Un-namespaced Postgres models continue to resolve through the `public` default; explicit `namespace unbound { … }` in PSL still maps to `__unbound__`.
+
+### Application code
+
+No change is required for normal query code:
+
+```ts
+await db.sql.user.findMany();
+await db.User.findMany();
+```
+
+Bare names still resolve default-namespace-first; only the emitted SQL changes.
+
+### Tests and observability
+
+If you assert raw SQL strings (integration tests, query logs, migration snapshots), expect qualified Postgres identifiers:
+
+```diff
+-FROM "user"
++FROM "public"."user"
+```
+
+SQLite and Mongo behaviour for bare names is unchanged at the SQL/collection string level (SQLite `qualifyTable` is a no-op; Mongo has no SQL-style qualification).
+
+### Contract artefacts
+
+Re-emit (`pnpm emit` / `prisma-next contract emit`) is **not** required solely for this change when your PSL/contract source is already on the 0.12 namespaced shape. If you have not yet run the `domain-plane-namespaced-contract` or `public-default-namespace` transitions, complete those first — a single emit pass covers all on-disk contract updates.
+
+### Emitted types note
+
+If you maintain hand-written code against generated `contract.d.ts`, replace any use of removed `ContractModelsMap<Contract>` with the emitted `Models` export or `ContractModelDefinitions<YourContract>` from `@internal/contract/types`. That removal affects extension authors directly; application projects that only import the generated `Models` alias pick up the new shape on re-emit.