@prisma/orm-postgres 8.0.0-rc.17-dev.42 → 8.0.0-rc.18

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

@@ -0,0 +1,1008 @@
+---
+from: "8.0.0-rc.17"
+to: "8.0.0-rc.18"
+changes:
+  - id: build-symbol-table-takes-default-namespace-id
+    summary: |
+      `buildSymbolTable` from `@internal/psl-parser` requires `defaultNamespaceId`. `ContractSourceContext` (`@internal/config/config-types`) and `ControlTargetDescriptor` (`@internal/framework-components/control`) each have a required `defaultNamespaceId`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bbuildSymbolTable\s*\('
+        - '\bContractSourceContext\b'
+        - '\bControlTargetDescriptor\b'
+  - id: symbol-table-has-no-top-level
+    summary: |
+      `SymbolTable` is `{ defaultNamespace, namespaces, namedTypes }` with no `topLevel`; `TopLevelScope` is removed. Top-level models, composite types, blocks and mixins are members of `symbolTable.defaultNamespace`. `NamespaceSymbol` has a contract `id` and a PSL `name`, `namespaces` is keyed by `id`, and `declarations` can be empty.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\.topLevel\b'
+        - '\bTopLevelScope\b'
+        - '\bNamespaceSymbol\b'
+        - '\.declarations\[0\]'
+        - '\bResolvedEntityReference\b'
+  - id: repeated-extension-block-is-a-duplicate-declaration
+    summary: |
+      A test that expects `PSL_DUPLICATE_EXTENSION_ENTITY` for an extension block repeated at the top level and in `namespace public { … }`, or under both `namespace unbound { … }` and `namespace __unbound__ { … }`, now gets `PSL_DUPLICATE_DECLARATION` with the message `Duplicate declaration of "<name>"`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bPSL_DUPLICATE_EXTENSION_ENTITY\b'
+  - id: psl-default-namespace-schema-rules
+    summary: |
+      PSL shipped with or generated by an extension: the top level and `namespace public { … }` (Postgres) share one set of names, and a top-level declaration cannot be named like the target's default namespace. Rename or remove the clashing declaration.
+    detection:
+      glob: "**/*.{prisma,psl}"
+      matches:
+        - '(^|\n)\s*namespace\s+(public|unbound|__unbound__)\s*\{'
+        - '(^|\n)[ \t]*(?!namespace[ \t])[A-Za-z_]\w*[ \t]+(public|unbound|__unbound__)[ \t]*\{'
+        - '(^|\n)\s*(public|unbound|__unbound__)\s*=\s*\S'
+  - id: block-spec-context-carries-data-types
+    summary: |
+      `BlockSpecContext` gains `dataTypes`, and `interpretExtensionBlocks`, `interpretExtensionBlock` and `interpretExtensionBlockAttributes` take a required `dataTypes`. `ControlDefaultRegistries` is deleted: an attribute spec context, `createBinder` and the Mongo PSL interpreter take `defaultFunctionRegistry` directly. Every factory in `sqlAttributeSpecs` takes the spec context.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '\b(BlockSpecContext|ControlDefaultRegistries|interpretExtensionBlocks|interpretExtensionBlock|interpretExtensionBlockAttributes)\b'
+        - 'controlMutationDefaults:\s*\{\s*defaultFunctionRegistry'
+        - 'sqlAttributeSpecs\.(model|field)\.\w+\(\)'
+  - id: tagged-literal-text-helpers
+    summary: |
+      `canonicalizeTaggedLiteralBody` and `TaggedLiteralCanonicalization` are exported from `@internal/framework-components/authoring` only, beside the new `printedTaggedLiteralReadsBack`. `printSqlExpressionLiteral` throws for a text that would read back as different text; check with `sqlTextsReadBack` first.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '\bcanonicalizeTaggedLiteralBody\b'
+        - '\bTaggedLiteralCanonicalization\b'
+        - '\bprintSqlExpressionLiteral\b'
+  - id: builder-raw-sql-is-a-sql-value
+    summary: |
+      In a TypeScript contract, `index({ where, expression })`, `check({ expression })`, `fullTextIndex({ where })` and the `using` and `withCheck` of `policySelect`, `policyInsert`, `policyUpdate`, `policyDelete` and `policyAll` take a `sql` value. A string there does not compile. Migration files keep strings.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '(?<!readonly |''function'', )\b(where|expression|using|withCheck)\s*:\s*[''"\x60]'
+  - id: sql-tag-interpolates-sql-values
+    summary: |
+      The `sql` tag interpolates other `sql` values: `` sql`${owner} AND deleted_at IS NULL` ``. Compose predicates this way instead of joining strings.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '(?<!\bsql)\x60\$\{[\w.]+\}\s+(AND|OR)\b'
+  - id: sql-tag-error-codes-renamed
+    summary: |
+      `CONTRACT.DEFAULT_SQL_INTERPOLATION` is renamed `CONTRACT.SQL_EXPRESSION_INTERPOLATION`. A NUL character or an oversize text in a `sql` value is `CONTRACT.SQL_EXPRESSION_INVALID`, not `CONTRACT.DEFAULT_INVALID`. `.default()` raises `CONTRACT.DEFAULT_INVALID` for `` sql`now()` ``, `` sql`autoincrement()` `` and unsafe SQL.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '\bDEFAULT_SQL_INTERPOLATION\b'
+        - '\bCONTRACT\.DEFAULT_INVALID\b'
+  - id: ts-storage-hash-may-change-once
+    summary: |
+      A raw SQL string with indentation shared by every line, blank lines at the start or end, a whitespace-only line or CRLF line breaks is stored as its canonical text once it is written as a `sql` value, which changes the contract's storage hash once.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '(?<!readonly )\b(where|expression|using|withCheck)\s*:\s*(\x60[ \t]*$|[''"\x60][ \t\r\n])'
+  - id: policy-handles-hold-sql-values
+    summary: |
+      `RlsPolicyHandle`, `RlsUsingPolicyDescriptor`, `RlsWithCheckPolicyDescriptor` and `RlsUsingWithCheckPolicyDescriptor` hold `using` and `withCheck` as `SqlExpression`; `fullTextIndex`'s `where` option, `IndexConstraint.where`, `IndexExpressionInput` and `AuthoredCheckConstraint.expression` are `SqlExpression` too. Read the text with `.text`.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '\b(RlsPolicyHandle|RlsUsingPolicyDescriptor|RlsWithCheckPolicyDescriptor|RlsUsingWithCheckPolicyDescriptor|IndexConstraint|IndexExpressionInput|AuthoredCheckConstraint)\b'
+  - id: sql-tag-lives-in-sql-contract
+    summary: |
+      The `sql` tag and the `SqlExpression` type live in `@internal/sql-contract/sql-expression`; `@internal/sql-contract-ts/contract-builder` re-exports both. The tag returns a `SqlExpression`, not a `ColumnDefault`. `sql-default-literal.ts` is deleted.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - 'sql-default-literal'
+        - '\bsql\x60[^\x60]*\x60\s*\.(kind|expression)\b'
+        - ':\s*ColumnDefault\s*=\s*sql\x60'
+        - 'import\s*(type\s*)?\{[^}]*\bsql\b[^}]*\}\s*from\s*[''"]@internal/sql-contract-ts/contract-builder[''"]'
+  - id: render-full-text-index-document-takes-a-definition
+    summary: |
+      `renderFullTextIndexExpression` from `@internal/target-postgres/sql-utils` is now `renderFullTextIndexDocument`, and it takes the index definition `{ weightGroups, language }` instead of a language and one column name.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '\brenderFullTextIndexExpression\b'
+  - id: full-text-indexable-codec-check-replaced
+    summary: |
+      `isFullTextIndexableCodec` is no longer exported from `@internal/target-postgres/sql-utils`. Check a full-text index with `fullTextIndexProblems`, or read a codec's traits with `postgresCodecTraitsOf`, both from `@internal/target-postgres/full-text-index-authoring`.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '\bisFullTextIndexableCodec\b'
+  - id: structured-index-option-values-hash-as-json
+    summary: |
+      An index option whose value is an array or an object now enters the index name's hash as JSON rather than through `String()`. A wire-named index with such an option gets a new name; re-emit contracts that declare one.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - 'constraints\.index\([\s\S]*options:\s*\{[^}]*[\[{]'
+  - id: collection-state-carries-tables
+    summary: |
+      A SQL ORM `CollectionState` has a required `tables` property holding the table scope and the aliased root table and variant tables of the collection, and `emptyState()` takes it as its argument. Build it with `createCollectionTables(contract, namespaceId, modelName)`. This applies to every hand-built state, including `IncludeExpr.nested`, a `combine()` branch state and the state of an include scalar selector.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bemptyState\('
+        - '\bCollectionState\b'
+  - id: state-filters-planned-as-written
+    summary: |
+      The SQL ORM planners no longer turn a literal in `CollectionState.filters` into a parameter. A filter put into a hand-built state must carry a `ParamRef` with the column's codec for each value compared with a column; a `LiteralExpr` left there is not encoded by the column's codec. Filters added through `collection.where(...)` are unaffected.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bfilters\s*:'
+  - id: create-model-accessor-takes-tables
+    summary: |
+      `createModelAccessor` takes the collection's tables as its fourth argument, before the optional variant's discriminator value: `createModelAccessor(context, namespaceId, modelName, tables, variantValue?)`.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bcreateModelAccessor\('
+  - id: include-expr-junction-table
+    summary: |
+      A hand-built `IncludeExpr` for a many-to-many relation needs a `junction` aliased table next to `through`; compiling a `through` include without one throws. `IncludeExpr.localTableName` is replaced by the optional `localVariantValue`, the discriminator value of the multi-table-inheritance variant whose table holds the relation's local columns.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bIncludeExpr\b'
+  - id: read-variants-by-discriminator-value
+    summary: |
+      A polymorphic base model's `variants` in a contract is keyed by discriminator value, and each entry is a reference `{ namespace, model }` to the variant model. Code that reads it finds the variant model at `variants[<value>].model`, where it used to find the value at `variants[<Model>].value`. `ContractVariantEntry` is removed; the entry type is `CrossReference`. A variant may be in a different namespace from its base.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts,js,mjs,cjs}"
+      matches:
+        - '(?<![\w$])variants(?![\w$])'
+        - '\bContractVariantEntry\b'
+  - id: sql-orm-state-names-a-variant-by-value
+    summary: |
+      SQL ORM collection state names a variant by its discriminator value, not its model name. `CollectionState.variantName` is `variantValue`, the type-state field `variantName` is `variantValue`, and `CollectionTables.variants` is keyed by discriminator value. `IncludeExpr.localTableName` is replaced by `localVariantValue`, as `include-expr-junction-table` describes.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bvariantName\b'
+        - '\bCollectionTables\b'
+  - id: orm-variant-types-take-a-value
+    summary: |
+      The Mongo ORM variant type helpers take a discriminator value where they took a variant model name: `VariantModelRow`, `VariantCreateInput`, and the fourth type parameter of `MongoCollection`. `DiscriminatorValues` is the keys of `variants`. `VariantNames` and `VariantNameForValue` are removed.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bVariantNames\b'
+        - '\bVariantNameForValue\b'
+        - '\bVariantModelRow\b'
+        - '\bVariantCreateInput\b'
+        - '\bMongoCollection\s*<'
+  - id: orm-refuses-names-that-are-not-fields
+    summary: |
+      The SQL ORM client refuses any name a caller passes that is not a field of the model, or of the variant the collection is narrowed to, with `ORM.FIELD_UNKNOWN`. That covers `where` shorthand and callbacks, `orderBy`, `select`, `distinct`, `distinctOn`, `groupBy`, `cursor`, aggregates, `having`, create, update and upsert data, `conflictOn`, include nested selects and relation filters. A column name that differs from its field name is no longer accepted, and rows no longer carry a column no field maps. `conflictOn` with a name that is not a field raised `ORM.ARGUMENT_INVALID` and now raises `ORM.FIELD_UNKNOWN`. The detection matches a file that names both `conflictOn` and `ORM.ARGUMENT_INVALID`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '(?<![\s\S])(?=[\s\S]*\bconflictOn\b)[\s\S]*\bORM\.ARGUMENT_INVALID\b'
+  - id: fragment-is-made-from-the-root-collection
+    summary: "The SQL ORM client's collection.fragment(body) refuses a collection with chained calls, such as db.Post.where(...).fragment(body), which used to ignore those calls; chain on the collection directly instead, or define a shared fragment on the model's root collection. A receiver typed by a type parameter, such as this in a custom collection class method, is refused at compile time. The detection matches .fragment( right after a closing parenthesis, as in a chained call, and this.fragment(."
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\)\s*\.fragment\('
+        - '\bthis\s*\.fragment\('
+  - id: fragment-types-are-renamed
+    summary: |
+      The SQL ORM client's types `Fragment` and `FieldFragment`, which 8.0.0-rc.17 exports, are renamed to `QueryFragment` and `DeclaredFieldsFragment`. Code still on the 8.0.0-rc.16 names renames `Scope` to `QueryFragment`, `FieldScope` to `DeclaredFieldsFragment` and `ScopeFacts` to `FragmentFacts` directly. `FragmentFacts`, `DeclaredField`, `db.orm.fragment` and `collection.fragment` keep their names. The detection matches `Fragment` and `Scope` only in an import or re-export from the ORM client (an `orm-client` entry or `@internal/sql-orm-client`), after a namespace import of it, or in an inline `import(...)` type of it, so React's `Fragment` and the SQL builder's `Scope` do not match.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\b(?:FieldFragment|FieldScope|ScopeFacts)\b'
+        - '(?:import|export)\s+(?:type\s+)?\{[^}]*\b(?:Fragment|Scope)\b[^}]*\}\s*from\s*[''"]@(?:prisma/[\w-]+/orm-client|internal/sql-orm-client)[''"]'
+        - 'import\s+(?:type\s+)?\*\s+as\s+([\w$]+)\s+from\s*[''"]@(?:prisma/[\w-]+/orm-client|internal/sql-orm-client)[''"][\s\S]*\b\1\.(?:Fragment|Scope)\b'
+        - 'import\(\s*[''"]@(?:prisma/[\w-]+/orm-client|internal/sql-orm-client)[''"]\s*\)\.(?:Fragment|FieldFragment|Scope|FieldScope)\b'
+  - id: unique-criterion-rejects-null
+    summary: |
+      `UniqueConstraintCriterion` in the SQL ORM client (`@prisma/orm-postgres/orm-client`, the other facades' `orm-client` entries and `@internal/sql-orm-client`) no longer accepts `null` for a nullable unique column, so the `conflictOn` of `upsert` and the criteria of a relation `connect` or `disconnect` stop compiling when a value is `null` or may be `null`. Pass a non-null value, or handle the null case before the call. The detection matches every `conflictOn`, `.connect(` and `.disconnect(`; leave as they are the calls on other objects, such as `postgres.connect(...)`, and the `conflictOn` of `createAll` and `createAndCount`, which is an array of field names.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\bconflictOn\b|\.(?:connect|disconnect)\s*\(|\bUniqueConstraintCriterion\b'
+  - id: prepared-all-and-aggregate-need-their-receiver
+    summary: |
+      On every collection of the SQL ORM client, `prepared.all` and `prepared.aggregate` no longer compile when called without the `prepared` object as their receiver, such as after `const { all } = collection.prepared`. Call them on the `prepared` object. `prepared.first` and `prepared.firstOrThrow` are not affected, and nothing changes at run time.
+    detection:
+      glob: "**/*.{ts,tsx,mts,cts}"
+      matches:
+        - '\{[^}]*\b(?:all|aggregate)\b[^}]*\}\s*=\s*[^;\n]*\.prepared\b'
+  - id: build-native-enums-takes-the-domain
+    summary: |
+      `buildNamespacedNativeEnums` from `@prisma/orm-postgres/runtime` takes the contract's domain as a second argument, `buildNamespacedNativeEnums(contract.storage, contract.domain)`, and leaves out each value set that a domain enum of the same namespace produced. The accessors it builds hold native enum types only; read a domain enum through the accessor `db.enums` uses.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bbuildNamespacedNativeEnums\s*\('
+  - id: middleware-hooks-are-activity-hooks
+    summary: |
+      The per-statement middleware hooks are replaced. `beforeQuery` and `beforeExecute` become `beforeEncode`; `interceptQuery` and `interceptExecute` become `intercept.onQuery` and `intercept.onExecute`; `afterQuery` and `afterExecute` become `activityEnded` on a statement; `afterTransaction` becomes `activityFinalized` on a statement. `onRow` and `beforeCompile` are unchanged.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\b(beforeQuery|beforeExecute|interceptQuery|interceptExecute|afterQuery|afterExecute|afterTransaction)\b'
+  - id: middleware-context-is-activity-context
+    summary: |
+      `RuntimeMiddlewareContext` is renamed `ActivityContext`. It gains `parent`, `state(key)` and `inTransaction()`, and loses `planExecutionId`; use `activity.id` instead.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bRuntimeMiddlewareContext\b'
+        - '\bplanExecutionId\b'
+  - id: after-result-types-removed
+    summary: |
+      `AfterQueryResult`, `AfterExecuteResult` and `AfterTransactionResult` are removed. Use `ActivityEndedResult` (narrow it with `result.kind === 'statement'` and `result.returns`) and `ActivityFinalizedResult`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bAfter(Query|Execute|Transaction)Result\b'
+  - id: aborted-phase-before-encode
+    summary: |
+      A `RUNTIME.ABORTED` error raised during the middleware stage before encoding reports `details.phase: 'beforeEncode'`, not `'beforeQuery'` or `'beforeExecute'`. The phases `'afterQuery'` and `'afterExecute'` no longer occur. Mongo's `RUNTIME.CONTENT_HASH_REQUIRES_RESOLVED_COMMAND` also reports `details.phase: 'beforeEncode'`, not `'beforeExecute'`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '[''"`](beforeQuery|beforeExecute|afterQuery|afterExecute)[''"`]'
+  - id: every-started-statement-is-ended-and-finalized
+    summary: |
+      Every statement the runtime accepts now starts an activity, and every started statement ends and is finalized exactly once. A call with an already-aborted signal fires `activityStarted` before it fails. A statement that fails before it runs, in `beforeCompile`, `beforeEncode` or parameter encoding, now ends `failed` and is finalized, where it got no `afterTransaction` before. `activityEnded` also fires for a statement the caller stopped reading (outcome `'stopped'`) and for a statement that failed before it ran (outcome `'failed'`, `latencyMs: 0`, `source: 'driver'`); `afterQuery` and `afterExecute` fired for neither, so a metrics or slow-query middleware now counts them unless it checks `result.outcome`. When a middleware's `activityStarted` throws, the middleware after it receive no `activityEnded` or `activityFinalized` for that activity. A statement still running when its transaction ends, such as a row stream still being read, is finalized when it ends, with the transaction's outcome, and keeps its `ctx.state` until then.
+  - id: observed-row-budget-runs
+    summary: |
+      The `budgets()` middleware now counts the rows a query returns and enforces `maxRows` on them. Before, the observed-row check never ran. With the default row severity `'error'`, or in `strict` mode, a query that returns more than `maxRows` rows fails with `BUDGET.ROWS_EXCEEDED`; with `'warn'` in `permissive` mode it logs one warning for the statement and keeps streaming.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bbudgets\('
+  - id: statement-runners-replace-middleware-runners
+    summary: |
+      `runBeforeQueryChain`, `runBeforeExecuteChain`, `runQueryWithMiddleware`, `runExecuteWithMiddleware`, `runAfterTransaction`, `reportQueryEnding`, `reportExecuteEnding`, `onQueryEndOutsideTransaction` and `QueryEnding` are removed from `@prisma/orm-framework`. A runtime runs a statement with `streamStatement` or `executeStatement`, whose body calls `beforeEncode`, `runQuery` and `runExecute`, and opens a transaction with `startTransactionActivity`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\b(runBeforeQueryChain|runBeforeExecuteChain|runQueryWithMiddleware|runExecuteWithMiddleware|runAfterTransaction|reportQueryEnding|reportExecuteEnding|onQueryEndOutsideTransaction|QueryEnding|afterTransactionStageFor|anyMiddlewareDeclaresAfterTransaction)\b'
+  - id: runtime-core-context-fields
+    summary: |
+      `RuntimeCoreOptions.ctx` is an `ActivityContextFields`: the context fields without `parent`, `state` and `inTransaction`, and without `planExecutionId`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bplanExecutionId\s*:'
+  - id: begin-transaction-on
+    summary: |
+      `SqlRuntimeBase.wrapTransaction(driverTx, connection)` is replaced by `beginTransactionOn(connection, owner)`, which starts the transaction activity, runs `BEGIN` on the connection and returns the wrapped transaction. `owner` is the `RuntimeConnection` the subclass hands to its callers for that connection; when the transaction's `activityStarted` hooks refuse the start before `BEGIN`, `withTransaction` releases `owner`, and after any other start failure it destroys it.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - '\bwrapTransaction\s*\('
+  - id: middleware-debug-events-renamed
+    summary: |
+      The runtime's debug events `middleware.interceptQuery` and `middleware.interceptExecute` are now `middleware.intercept.onQuery` and `middleware.intercept.onExecute`, and the logged error event `middleware.afterTransaction.error` is now `middleware.activityFinalized.error`.
+    detection:
+      glob: "**/*.{ts,mts,cts,tsx}"
+      matches:
+        - 'middleware\.(interceptQuery|interceptExecute|afterTransaction\.error)'
+  - id: rename-statements-capability-removed
+    summary: |
+      `TargetMigrationsCapability.renameStatements` (with `refused` and `keepDataByHand`), added in 8.0.0-rc.17, is removed: every target's planner carries out rename statements. The CLI no longer appends a target's text to a data-loss question.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '(?<![\w$])(?:renameStatements|keepDataByHand)\s*:'
+  - id: mongo-ddl-rename-collection
+    summary: |
+      `MongoDdlCommandVisitor` gains `renameCollection(command: RenameCollectionCommand)`, and `AnyMongoDdlCommand` and `AnyMongoDdlWireCommand` gain `RenameCollectionCommand` and `RenameCollectionWireCommand` (source in `collection`, new name in `to`). A visitor implementation, or a driver's `run`, handles the new kind.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '(?<![\w$])(?:MongoDdlCommandVisitor|AnyMongoDdlCommand|AnyMongoDdlWireCommand)(?![\w$])'
+  - id: mongo-dml-operations
+    summary: |
+      `MongoDataTransformOperation` is renamed `MongoDmlOperation`, and `MongoDataTransformCheck` `MongoDmlCheck`. Its `operationClass` is any `MigrationOperationClass`, not only `'data'`: the planner's document rewrites (`renameField`, `unsetField`) are DML operations with class `widening` or `destructive`. Tell a DML operation from a DDL operation with `isMongoDmlOperation(operation)` (it has `run`), not with `operationClass === 'data'`.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - 'operationClass\s*===?\s*["'']data["'']'
+        - '(?<![\w$])MongoDataTransform(?:Operation|Check)(?![\w$])'
+  - id: mongo-update-many-bypass-validation
+    summary: |
+      `RawUpdateManyCommand` takes an optional fourth argument `{ bypassDocumentValidation }`; `UpdateManyWireCommand` takes it as an optional fifth constructor argument and carries `bypassDocumentValidation: boolean`; the lowered `rawUpdateMany` draft (`MongoLoweredDraft`) requires `bypassDocumentValidation: boolean`.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - 'kind:\s*["'']rawUpdateMany["'']'
+  - id: mongo-op-factory-call-to-op
+    summary: |
+      A Mongo `OpFactoryCall`'s `toOp()`, and `renderOps(calls)`, return `AnyMongoMigrationOperation`, since `RenameFieldCall` and `UnsetFieldCall` produce DML operations.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      matches:
+        - '["'']@(?:prisma/orm-target-mongo|internal/target-mongo)(?:/[^"'']*)?["''][\s\S]*(?:\.toOp\(\)|(?<![\w$])renderOps\s*\()'
+---
+
+# 8.0.0-rc.17 → 8.0.0-rc.18 — Extension author upgrade instructions
+
+## The PSL symbol table places top-level declarations in the default namespace
+
+`@prisma/orm-framework` publishes these modules as `@prisma/orm-framework/psl-parser`, `/config/config-types` and `/components/control`.
+
+### `build-symbol-table-takes-default-namespace-id`
+
+Pass the target's default namespace id: `context.defaultNamespaceId` in a contract source, `stack.target.defaultNamespaceId` from a control stack. A `ContractSourceContext` or `ControlTargetDescriptor` built by hand adds the same field (`'public'` for Postgres, `'__unbound__'` for SQLite and MongoDB).
+
+```ts
+const { symbolTable } = buildSymbolTable({
+  documents,
+  sources,
+  defaultNamespaceId: context.defaultNamespaceId,
+});
+```
+
+### `symbol-table-has-no-top-level`
+
+Before:
+
+```ts
+for (const model of Object.values(symbolTable.topLevel.models)) visit(model, undefined);
+for (const namespace of Object.values(symbolTable.topLevel.namespaces)) {
+  for (const model of Object.values(namespace.models)) visit(model, namespace.name);
+}
+```
+
+After:
+
+```ts
+for (const namespace of Object.values(symbolTable.namespaces)) {
+  for (const model of Object.values(namespace.models)) visit(model, namespace.id);
+}
+```
+
+`symbolTable.namespaces` includes the default namespace, which is also `symbolTable.defaultNamespace` and holds the top-level declarations together with the members of a `namespace public { … }` block. `topLevel.namedTypes` is `symbolTable.namedTypes`. Use `namespace.id` for a contract id; `namespace.name` is the PSL spelling, which differs only for the late-bound namespace (id `__unbound__`, name `unbound`, one symbol for both spellings). `namespace.declarations` lists the written blocks and is empty for a default namespace with none. A model, composite type or block resolution always has `namespace`, so `resolution.namespace?.name ?? fallback` becomes `resolution.namespace.id`.
+
+### `repeated-extension-block-is-a-duplicate-declaration`
+
+The symbol table reports the repeated block before any entity factory runs. Change the expected code for those inputs only; `PSL_DUPLICATE_EXTENSION_ENTITY` is still reported when two different blocks place an entity under one key in one namespace.
+
+### `psl-default-namespace-schema-rules`
+
+A name declared both at the top level and inside `namespace public { … }` (the default namespace on Postgres), or a `types { }` binding or namespace with the same name as a member of that block, is `PSL_DUPLICATE_DECLARATION`: remove or rename one. A top-level declaration named like the target's default namespace (`public` on Postgres; `unbound` or `__unbound__` on SQLite and MongoDB) is rejected with the same code: rename it, and on a model keep the stored name with `@@map`.
+
+## Raw SQL in PSL is a `sql` literal
+
+### Spec contexts carry the stack's data types
+
+A block spec can now read the stack's data types, so a block parameter can receive a data type through `dataTypeValue`:
+
+```ts
+function policyUsingParam(ctx: BlockSpecContext) {
+  return {
+    type: optional(dataTypeValue(SQL_EXPRESSION_DATA_TYPE_ID, ctx.dataTypes)),
+    documentation: 'A SQL predicate controlling which rows this policy permits.',
+  };
+}
+```
+
+- `BlockSpecContext` is `{ symbols, dataTypes }`. It carries no block: a block attribute reads the block it belongs to from `BlockAttributeCtx.selfBlock` (ADR 262). Code that builds one passes the stack's `DataTypeSupport`, or `EMPTY_DATA_TYPES` from `@internal/psl-parser` when the stack registers none.
+- `interpretExtensionBlocks`, `interpretExtensionBlock` and `interpretExtensionBlockAttributes` take a required `dataTypes`. Pass the stack's data types, the same value the attribute spec context carries.
+- `ControlDefaultRegistries` is deleted. `AttributeSpecContext`, `CreateBinderOptions` and `InterpretPslDocumentToMongoContractInput` take `defaultFunctionRegistry: ControlMutationDefaultRegistry` in place of `controlMutationDefaults`:
+
+```diff
+- controlMutationDefaults: { defaultFunctionRegistry },
++ defaultFunctionRegistry,
+```
+
+A spec factory that read `ctx.controlMutationDefaults.defaultFunctionRegistry` reads `ctx.defaultFunctionRegistry`.
+
+`blockSpecContext({ symbols, dataTypes })` from `@internal/psl-parser` builds a `BlockSpecContext`. Every factory in `sqlAttributeSpecs` (from `@internal/sql-contract-psl/attribute-specs`) takes the spec context, including those whose spec does not read it: call `sqlAttributeSpecs.model.map(ctx)`, not `sqlAttributeSpecs.model.map()`.
+
+A spec that takes raw SQL can do what the SQL family and Postgres now do: declare `dataTypeValue(SQL_EXPRESSION_DATA_TYPE_ID, ctx.dataTypes)`, with `SQL_EXPRESSION_DATA_TYPE_ID` from `@internal/sql-contract/sql-expression`. The value it returns holds the canonical text; `sqlTextFromCanonical(value.value)` reads it.
+
+### Tagged literal text helpers
+
+`canonicalizeTaggedLiteralBody` and its result type `TaggedLiteralCanonicalization` are no longer exported from `@internal/framework-components/control`. Import them from `@internal/framework-components/authoring`:
+
+```diff
+- import { canonicalizeTaggedLiteralBody } from '@internal/framework-components/control';
+- import type { TaggedLiteralCanonicalization } from '@internal/framework-components/control';
++ import { canonicalizeTaggedLiteralBody } from '@internal/framework-components/authoring';
++ import type { TaggedLiteralCanonicalization } from '@internal/framework-components/authoring';
+```
+
+`canonicalizeTaggedLiteralBody` now drops every blank line at the start and end of the body, not only the first and the last, so its result is always its own canonical text.
+
+The same entry exports `printedTaggedLiteralReadsBack(text)`, which says whether a tagged literal printed with `text` reads back as the same text. `printSqlExpressionLiteral` from `@internal/sql-contract/sql-expression` now throws an internal error for a text that would read back as different text. Check the texts first with `sqlTextsReadBack(texts)` from the same module. When it returns `false`, `contract infer` skips an object named with `map:`, prints a wire-named index with `canonicalSqlText(text)` (whose result always reads back), and `contract print` refuses the object. Default expressions are not checked: they print with `printTaggedLiteral`, because defaults are compared with case and whitespace ignored.
+
+## Raw SQL in a TypeScript contract is a `sql` value
+
+### `builder-raw-sql-is-a-sql-value`
+
+Every field of the TypeScript contract builder that holds raw SQL takes a `sql` value, as `.default()` already did. Wrap each string in the `sql` tag, imported from the same contract-builder module as the other helpers:
+
+| Place | Before | After |
+| --- | --- | --- |
+| `index` `where` | `constraints.index([cols.email], { where: '(archived_at IS NULL)', name: 'users_email_active' })` | ``constraints.index([cols.email], { where: sql`(archived_at IS NULL)`, name: 'users_email_active' })`` |
+| `index` `expression` | `constraints.index({ expression: 'lower(email)', name: 'users_email_lower' })` | ``constraints.index({ expression: sql`lower(email)`, name: 'users_email_lower' })`` |
+| `fullTextIndex` `where` | `fullTextIndex(cols.text, { where: 'archived_at IS NULL', name: 'message_text_search_live' })` | ``fullTextIndex(cols.text, { where: sql`archived_at IS NULL`, name: 'message_text_search_live' })`` |
+| `check` `expression` | `check({ expression: 'total > 0', name: 'order_total_positive' })` | ``check({ expression: sql`total > 0`, name: 'order_total_positive' })`` |
+| a policy's `using` and `withCheck` | `policySelect(Profile, { name: 'profile_owner_read', roles: [authenticated], using: '"userId"::uuid = auth.uid()' })` | ``policySelect(Profile, { name: 'profile_owner_read', roles: [authenticated], using: sql`"userId"::uuid = auth.uid()` })`` |
+
+```ts
+import { check, policySelect, sql } from '@internal/postgres/contract-builder';
+```
+
+Copy the string's value, not its source: undo the TypeScript string's own escaping first, so `'"userId"'` and `"\"userId\""` both become `` sql`"userId"` ``. Inside the template, write each backtick as `` \` ``, each `${` as `\${`, and a backslash that precedes a backtick, a dollar sign or another backslash as `\\`; every other backslash is kept as written, so `E'\n'` stays `E'\n'`. An index or check object written by hand in `.sql({ indexes, checks })` takes a `sql` value in the same fields. A shared predicate held in a `const` becomes a `sql` value too: `` const owner = sql`"userId"::uuid = auth.uid()`; ``.
+
+Skip files under a `migrations/` folder and leave them as they are: migration functions take a string or a `sql` value, and a string keeps its exact text, while wrapping it in `sql` canonicalizes it, which can change the SQL that migration runs.
+
+The string form is a type error. JavaScript that is not type-checked and passes a string fails when the contract is built, with `CONTRACT.ARGUMENT_INVALID`, for example ``Index "users_email_active" where must be a sql`...` value.`` The message names the index, check or policy; an index or check with no `name` or `map` is named by its model, as in `Index on "User" where`. `.default('draft')` is not raw SQL: a string there is still a literal default. The `{ fields, render }` form of an index expression still returns a string from `render`, because that text is generated by code.
+
+This supersedes the TypeScript `fullTextIndex(cols.text, { where: 'archived_at IS NULL', … })` example of the `postgres-full-text-search` app instructions in the upgrade from 8.0.0-rc.11 to 8.0.0-rc.12: write it as ``fullTextIndex(cols.text, { where: sql`archived_at IS NULL`, … })``.
+
+### `sql-tag-interpolates-sql-values`
+
+The `sql` tag accepts other `sql` values inside `${…}`. It joins their text into the template and canonicalizes the whole text once. A predicate that was built by joining strings is written as one `sql` template:
+
+```ts
+const owner = sql`owner_id = current_setting('app.uid')::int`;
+const ownerAlive = sql`${owner} AND deleted_at IS NULL`;
+```
+
+Anything else inside `${…}`, such as a string or a number, is a type error, and throws `CONTRACT.SQL_EXPRESSION_INTERPOLATION` from JavaScript that is not type-checked. Prisma never quotes a value into SQL, so write any other text inside the template. Each line of an interpolated value after its first takes the indentation of the template line the `${…}` sits on, so a multi-line value inside an indented template stores the same text as the same SQL written out in one template.
+
+### `sql-tag-error-codes-renamed`
+
+- `CONTRACT.DEFAULT_SQL_INTERPOLATION` is now `CONTRACT.SQL_EXPRESSION_INTERPOLATION`, and its message is ``sql`...` only interpolates other sql`...` values; write any other text inside the template.``
+- A `sql` value whose text holds a NUL character or is larger than 65536 bytes throws `CONTRACT.SQL_EXPRESSION_INVALID` when it is made. It was `CONTRACT.DEFAULT_INVALID`.
+- `` sql`now()` ``, `` sql`autoincrement()` `` and unsafe SQL (`;`, a comment token, `$$` or `SELECT`) are no longer refused by the tag. `.default()` refuses them with `CONTRACT.DEFAULT_INVALID` and the same messages, so `` const current = sql`now()` `` compiles and runs, and `.default(current)` throws. In every other place such text is passed to the database unchanged.
+
+Update code that matches on these codes. Code that catches `CONTRACT.DEFAULT_INVALID` around a `sql` template that is not passed to `.default()` no longer sees it.
+
+### `ts-storage-hash-may-change-once`
+
+A `sql` value stores its canonical text, as a PSL `sql` literal does: indentation shared by every line, blank lines at the start and end, whitespace-only lines and carriage returns are removed. A raw SQL string whose text had any of these, for example a multi-line template string, is stored differently once it is written as a `sql` value, so the contract's storage hash changes once. Prisma-generated index, check and policy names do not change. Skip files under a `migrations/` folder and leave them as they are: migration functions take a string or a `sql` value, and a string keeps its exact text, while wrapping it in `sql` canonicalizes it, which can change the SQL that migration runs. Emit the contract again, and for a pack with migrations run `prisma migration plan` once and commit the migration it writes. For an index or check named with `map:` whose text changed, `migration plan` stops with a conflict and asks for a migration written with `migration new`, which needs no operations. The TypeScript policy helpers take no exact name, so a policy never needs this. A `{ fields, render }` index expression whose `render` returns text that is not canonical, such as indented multi-line text, also stores different text once, with the same steps; `fullTextIndex` stores its fields and language as data, renders no SQL, and is not affected.
+
+A contract built before this release can hold a column default whose text is not canonical. `contract infer` writes such a default with a note and `contract print` refuses it, for the reason ADR 268 gives ("Column defaults that do not read back"); the app instructions of this release say what to do.
+
+### `policy-handles-hold-sql-values`
+
+The types behind the builder fields changed with them. In code that builds, reads or re-exports them:
+
+- `RlsPolicyHandle.using` and `.withCheck` are `SqlExpression | undefined`. Every `using` and `withCheck` of `RlsUsingPolicyDescriptor`, `RlsWithCheckPolicyDescriptor` and both arms of `RlsUsingWithCheckPolicyDescriptor` is `SqlExpression`, required or optional as before. A function that takes a descriptor and passes its predicates on types them as `SqlExpression` too.
+- `fullTextIndex`'s option `where` is `SqlExpression` and is passed to `IndexConstraint.where` unchanged.
+- `IndexConstraint.where` is `SqlExpression`, `IndexExpressionInput` is `SqlExpression | DeferredIndexExpression`, and `AuthoredCheckConstraint.expression` is `SqlExpression`. `DeferredIndexExpression.render` still returns a string; lowering canonicalizes the text it returns, so a `render` that returns text that is not canonical stores different text once, as `ts-storage-hash-may-change-once` describes.
+- Import the type with `import type { SqlExpression } from '@internal/sql-contract/sql-expression';`, or from `@internal/sql-contract-ts/contract-builder`, which re-exports it.
+- Read the text of a value with `.text`. Code that lowers such a value from JavaScript that is not type-checked reads it with `requireSqlExpression(value, 'Policy "p" using').text` from `@internal/sql-contract/sql-expression`, which throws `CONTRACT.ARGUMENT_INVALID` for anything else. The Postgres target lowers a policy handle's predicates this way.
+
+The definition tree (`IndexNode`, `CheckNode`), `buildSqlContractFromDefinition`, `PostgresRlsPolicy` and the emitted contract keep strings.
+
+### `sql-tag-lives-in-sql-contract`
+
+`sql` is defined in `@internal/sql-contract/sql-expression`, with `SqlExpression`, `isSqlExpression`, `readSqlExpression` and `requireSqlExpression`. Read a value through `readSqlExpression` or `requireSqlExpression`, not by checking `isSqlExpression` and reading `.text`: a value made by another installed copy of the package passes `isSqlExpression`, and only those two functions canonicalize its text. `@internal/sql-contract-ts/contract-builder` re-exports `sql` and `type SqlExpression`; `packages/2-sql/2-authoring/contract-ts/src/sql-default-literal.ts` is deleted, so import from one of those modules. A contract-builder facade that re-exports `sql` also re-exports `type SqlExpression` beside it, and never the class as a value.
+
+The tag returns a `SqlExpression`, whose `text` is the canonical text. Code that read `` sql`...`.expression `` or typed the result as `ColumnDefault` reads `.text`, or passes the value to `.default()`, which stores `{ kind: 'function', expression: value.text }`. `describeTaggedLiteralFailure` and `resolveTemplateTagEscapes` are also exported from `@internal/framework-components/authoring`.
+
+This supersedes the sentence of the `sql-default-literal` extension instructions in the upgrade from 8.0.0-rc.11 to 8.0.0-rc.12 that says `` sql`now()` `` and `` sql`autoincrement()` `` are refused by the TypeScript `sql` tag: `.default()` refuses them now.
+
+## A full-text index is stored as data
+
+### `render-full-text-index-document-takes-a-definition`
+
+The renderer now draws the whole search document of a full-text index, which may cover several columns in weight groups, and is named for it. Import `renderFullTextIndexDocument` instead and pass the definition the contract stores in the index's `options`:
+
+```diff
+-import { renderFullTextIndexExpression } from '@internal/target-postgres/sql-utils';
++import { renderFullTextIndexDocument } from '@internal/target-postgres/sql-utils';
+
+-renderFullTextIndexExpression('english', 'body')
++renderFullTextIndexDocument({ weightGroups: [['body']], language: 'english' })
+```
+
+One field renders exactly what it rendered before, `to_tsvector('english', "body")`. A document of several columns wraps every column in `coalesce(column, '')`. A definition that breaks a rule of a full-text index (no group, more than four groups, an empty group, or a column named twice) is refused with `CONTRACT.INDEX_INVALID`.
+
+A Postgres full-text index in a contract is now an index of type `fullText`, registered in the Postgres index type registry, with `columns` and `options: { weightGroups, language }`, not an expression. `columns` is exactly `weightGroups.flat()`; a contract where they differ is refused with `CONTRACT.INDEX_INVALID` when it is loaded, as is a full-text index over a column whose codec Postgres does not know to be `textual`. Code that reads indexes from a contract recognises a full-text index by `type === 'fullText'` (exported as `FULL_TEXT_INDEX_TYPE` from `@internal/target-postgres/full-text-index-authoring`), and must not treat its `columns` as a plain index over those columns. In the database it is a `gin` index over the rendered document: the `fullText` entry of the Postgres index type registry declares `accessMethod: 'gin'`.
+
+### `full-text-indexable-codec-check-replaced`
+
+The rules of a full-text index, including that it covers text columns only, are now one function. Call it instead of testing each codec:
+
+```diff
+-import { isFullTextIndexableCodec } from '@internal/target-postgres/sql-utils';
++import {
++  fullTextIndexProblems,
++  postgresCodecTraitsOf,
++} from '@internal/target-postgres/full-text-index-authoring';
+
+-if (!isFullTextIndexableCodec(codecId)) refuse();
++const problems = fullTextIndexProblems({
++  weightGroups: [[columnName]],
++  codecs: { codecIdOf: () => codecId, traitsOf: postgresCodecTraitsOf },
++});
++if (problems.length > 0) refuse();
+```
+
+To test one codec alone, `postgresCodecTraitsOf(codecId)?.includes('textual') === true` is what `isFullTextIndexableCodec(codecId)` returned.
+
+### `structured-index-option-values-hash-as-json`
+
+`normalizeIndexOptionValue` from `@internal/sql-schema-ir/naming` writes an array or object value as JSON, with object keys sorted at every depth, so `[['a', 'b']]` and `[['a'], ['b']]` no longer hash to the same index name and the order in which an object's keys were written does not change it. Scalar values hash as before. If an extension's contract declares a wire-named index whose options hold an array or an object, rebuild its contract space so the emitted index name and storage hash move together.
+
+## SQL ORM collection state carries its tables
+
+These changes concern code that imports from `@prisma/orm-family-sql/orm-client` and builds SQL ORM collection state or model accessors by hand.
+
+### `collection-state-carries-tables`
+
+`CollectionState.tables` is a `CollectionTables` value: the table scope plus the aliased root table and each aliased multi-table-inheritance variant table. `emptyState` takes it as a required argument. Build it from the contract with `createCollectionTables`:
+
+```ts
+// before
+import { emptyState } from '@prisma/orm-family-sql/orm-client';
+
+const state = { ...emptyState(), limit: 10 };
+
+// after
+import { createCollectionTables, emptyState } from '@prisma/orm-family-sql/orm-client';
+
+const tables = createCollectionTables(contract, 'public', 'User');
+const state = { ...emptyState(tables), limit: 10 };
+```
+
+`createCollectionTables(contract, namespaceId, modelName)` takes the model the state is for. For a polymorphic model pass the base model name; its variant tables are aliased in the same scope.
+
+Every object typed `CollectionState` needs the property, not only top-level states:
+
+- `IncludeExpr.nested`;
+- the `state` of a `combine()` rows branch;
+- the `state` of an include scalar selector.
+
+A state passed to `new Collection(ctx, modelName, { state })` needs it too. A `Collection` constructed without `state` builds its own tables, so that call needs no change.
+
+Do not build a `CollectionTables` or a table scope by hand.
+
+A state built by hand for an include child must not reuse the parent's table aliases. Prefer building includes through `collection.include(...)` and reading `collection.state`, which aliases the child's tables from the parent's scope. Where a child state is built by hand for a relation whose target table already appears in the parent chain (a self-relation, or an include that returns to an ancestor's table), build it through `include()` instead; `createCollectionTables` starts a fresh scope and would give the child the same alias as its parent.
+
+### `state-filters-planned-as-written`
+
+This affects only code that writes expressions into `CollectionState.filters` itself (a hand-built state, an `IncludeExpr.nested` state, a `combine()` branch state). Such a filter used to have each literal compared with a column replaced by a parameter carrying the column's codec when the statement was planned. The planners now use stored filters unchanged.
+
+Build the filter through the collection, which binds it when `where()` is called, and read the state from the result:
+
+```ts
+// before
+const state = {
+  ...emptyState(),
+  filters: [BinaryExpr.eq(ColumnRef.of('users', 'email'), LiteralExpr.of(email))],
+};
+
+// after
+const state = users.where(BinaryExpr.eq(ColumnRef.of('users', 'email'), LiteralExpr.of(email))).state;
+```
+
+A filter that must be written by hand needs a `ParamRef` with the column's codec in place of the literal. A literal left in place is not encoded by the column's codec.
+
+### `create-model-accessor-takes-tables`
+
+Pass the tables as the fourth argument. A variant moves to the fifth, named by its discriminator value:
+
+```ts
+// before
+createModelAccessor(context, 'public', 'User');
+createModelAccessor(context, 'public', 'Task', 'Feature');
+
+// after
+createModelAccessor(context, 'public', 'User', createCollectionTables(context.contract, 'public', 'User'));
+createModelAccessor(
+  context,
+  'public',
+  'Task',
+  createCollectionTables(context.contract, 'public', 'Task'),
+  'feature',
+);
+```
+
+The accessor takes the aliases for its relation filters and relation orders from `tables.scope` and records them there. Two relation filters over the same table built from one accessor therefore get different aliases. Pass each accessor its own `createCollectionTables(...)` result unless the expressions it builds are meant for one statement.
+
+### `include-expr-junction-table`
+
+This affects only an `IncludeExpr` object written out by hand with a `through` descriptor. An include built with `collection.include('<relation>')` carries the aliased junction table already.
+
+There is no public function that aliases a junction table on its own. Replace the hand-built object with the include the collection builds:
+
+```ts
+// before
+const include: IncludeExpr = { relationName: 'tags', through: { table: 'user_tags', /* … */ }, /* … */ };
+
+// after
+const [include] = users.include('tags').state.includes;
+```
+
+`IncludeExpr` no longer has `localTableName`. Remove the property where the relation's local columns are on the parent model's own table, which is every relation of a non-polymorphic model, a base model or a single-table-inheritance variant. Where they are on a multi-table-inheritance variant's table, set `localVariantValue` to that variant's discriminator value:
+
+```ts
+// before
+const include: IncludeExpr = { relationName: 'assignee', localTableName: 'features', /* … */ };
+
+// after
+const include: IncludeExpr = { relationName: 'assignee', localVariantValue: 'feature', /* … */ };
+```
+
+## A variant is named by its discriminator value
+
+These changes concern code that reads `variants` from a contract, or that imports from `@prisma/orm-family-sql/orm-client` or `@prisma/orm-family-mongo/orm`. A contract an extension ships must be re-emitted: see the app instructions' `re-emit-contracts-with-polymorphic-models`.
+
+### `read-variants-by-discriminator-value`
+
+```ts
+// before
+for (const [variantName, { value }] of Object.entries(model.variants ?? {})) {
+  const variant = models[variantName];
+}
+
+// after
+for (const [value, variantRef] of Object.entries(model.variants ?? {})) {
+  const variant = contract.domain.namespaces[variantRef.namespace]?.models[variantRef.model];
+}
+```
+
+Look the variant model up in the namespace its reference names, not in the base's namespace. A discriminator value is unique in a hierarchy; a variant model name is not, because two namespaces may each have a variant model of the same name.
+
+Replace the type `ContractVariantEntry` with `CrossReference`, exported from the same module.
+
+### `sql-orm-state-names-a-variant-by-value`
+
+Rename the properties, and where a value is written or compared, use the discriminator value the variant declares in place of its model name:
+
+```ts
+// before
+const narrowed = { ...state, variantName: 'Feature' };
+
+// after, for @@base(Task, "feature")
+const narrowed = { ...state, variantValue: 'feature' };
+const featureTable = state.tables.variants.get('feature');
+```
+
+A type that reads the selected variant from a collection's type state reads `variantValue`, for example `CollectionTypeStateOf<C>['variantValue']`.
+
+### `orm-variant-types-take-a-value`
+
+These types are exported from `@prisma/orm-family-mongo/orm`. Pass the discriminator value where a variant model name was passed:
+
+```ts
+// before
+type BugRow = VariantModelRow<Contract, 'Task', 'Bug'>;
+type BugInput = VariantCreateInput<Contract, 'Task', 'Bug'>;
+type Bugs = MongoCollection<Contract, 'Task', NoIncludes, 'Bug'>;
+
+// after, for a Bug variant declaring "bug"
+type BugRow = VariantModelRow<Contract, 'Task', 'bug'>;
+type BugInput = VariantCreateInput<Contract, 'Task', 'bug'>;
+type Bugs = MongoCollection<Contract, 'Task', NoIncludes, 'bug'>;
+```
+
+`VariantNameForValue<C, M, V>` mapped a value to a model name for these helpers; pass the value itself. Replace `VariantNames<C, M>` with `DiscriminatorValues<C, M>` where the code lists what `variant()` accepts.
+
+## The SQL ORM client accepts only field names
+
+Every name passed to the SQL ORM client must be the name of a field of the model, or of the variant the collection is narrowed to. A name that is not a field throws `ORM.FIELD_UNKNOWN` with the message `Model "<model>" has no field "<name>"`. A column name is not a field name: pass the field instead.
+
+```diff
+- await db.orm.Post.where({ user_id: 1 }).all();
++ await db.orm.Post.where({ userId: 1 }).all();
+```
+
+Code that catches the error a `conflictOn` name that is not a field raises (in a create with `onConflict: 'skip'`) matched `ORM.ARGUMENT_INVALID`. Match `ORM.FIELD_UNKNOWN` instead.
+
+```diff
+- if (error.code === 'ORM.ARGUMENT_INVALID') {
++ if (error.code === 'ORM.FIELD_UNKNOWN') {
+```
+
+Leave other checks of `ORM.ARGUMENT_INVALID` alone; only the `conflictOn` refusal changed code.
+
+## `fragment` is called on the model's root collection
+
+A fragment for one model, made with `collection.fragment(body)`, is built from the model alone. Calls chained before `.fragment(...)`, such as `where`, `orderBy`, `include`, `limit` or `forUpdate`, were ignored without a word. Now `fragment` throws `ORM.ARGUMENT_INVALID` on such a collection, and a `where`, an `orderBy` or an `include` before it is also a compile error. A receiver typed by a type parameter, such as `this` in a custom collection class method or `C` in a generic function, is a compile error too, because it may be a chained collection.
+
+In the extension's code, chain on the collection directly instead of defining a fragment from it. Inside a class method, chain on `this`:
+
+```diff
+  titles() {
+-   return this.with(this.fragment((posts) => posts.select('id', 'title')));
++   return this.select('id', 'title');
+  }
+```
+
+If the fragment is shared between places, define it once as a module-level constant on the model's root collection, and move the chained calls that were meant to be part of it into its body:
+
+```diff
+- const recentSummary = db.orm.public.Post.orderBy((p) => p.id.desc()).fragment((posts) =>
+-   posts.select('id', 'title'),
+- );
++ const recentSummary = db.orm.public.Post.fragment((posts) =>
++   posts.orderBy((p) => p.id.desc()).select('id', 'title'),
++ );
+```
+
+The detection does not find a `.fragment(` call whose receiver is a variable or a parameter holding a chained collection, such as `const published = db.orm.public.Post.where(...)` followed by `published.fragment(...)`, or a generic receiver. Check those `.fragment(` calls by hand.
+
+Skip a match on the fragment for any model, `fragment(fields, body)`, called on a client returned by a call, such as `orm(...).fragment(fields, body)`, which did not change, and a match in code that uses the MongoDB ORM client, which did not change either.
+
+## `Fragment` is now `QueryFragment`, and `FieldFragment` is now `DeclaredFieldsFragment`
+
+A function from a collection to a collection, run with `collection.with(fn)`, is a query fragment, and its type is now named `QueryFragment<In, Out>`. "Fragment" alone also covers a row fragment, a function of the model accessor that `where` and `orderBy` take, and it is the name of React's `Fragment`. What `db.orm.fragment(fields, body)` returns, a fragment declared over the fields it needs, is now typed `DeclaredFieldsFragment`. The types work as before.
+
+These changes apply to the SQL ORM client only. The MongoDB ORM client did not change; skip matches in code that uses it.
+
+Rename `Fragment` to `QueryFragment` and `FieldFragment` to `DeclaredFieldsFragment`. These are the names 8.0.0-rc.17 exports.
+
+```diff
+- import type { FieldFragment, Fragment } from '@prisma/orm-postgres/orm-client';
++ import type { DeclaredFieldsFragment, QueryFragment } from '@prisma/orm-postgres/orm-client';
+
+- const newest: Fragment<PostCollection, Ordered<PostCollection>> = (posts) => posts.newestFirst();
++ const newest: QueryFragment<PostCollection, Ordered<PostCollection>> = (posts) => posts.newestFirst();
+```
+
+Code that still uses the 8.0.0-rc.16 names renames them to the new names directly: `Scope` to `QueryFragment`, `FieldScope` to `DeclaredFieldsFragment` and `ScopeFacts` to `FragmentFacts`.
+
+Rename every use of these types in the extension's code and in the declarations it exports, including a re-export such as `export type { Fragment } from '@prisma/orm-postgres/orm-client'`, a qualified name such as `Orm.Fragment` after `import * as Orm from '@prisma/orm-postgres/orm-client'`, and an inline type such as `import('@prisma/orm-postgres/orm-client').Fragment`. After renaming, sort the named imports again, since `QueryFragment` sorts in a different place than `Fragment` or `Scope`, and wrap any line the longer names make too long for the formatter.
+
+Do not rename React's `Fragment`, the SQL builder's `Scope` and `ScopeField` (imported from a `builder` entry or `@internal/sql-builder`), or any `Fragment` or `Scope` that is not imported from the ORM client. Do not rename `FragmentFacts` or `DeclaredField`, which keep their names.
+
+## `unique-criterion-rejects-null`
+
+`UniqueConstraintCriterion<TContract, ModelName>`, exported by the SQL ORM client (`@prisma/orm-postgres/orm-client`, the other facades' `orm-client` entries and `@internal/sql-orm-client`), is the object that names one row by its primary key or by one of its unique constraints. Each of its values is now the field's type without `null`. A `null` value cannot identify one row: a unique constraint allows any number of rows whose column is `NULL`.
+
+The type is the argument of three calls, and each of them now refuses `null` and a value whose type includes `null`:
+
+- `conflictOn` in `collection.upsert({ create, update, conflictOn })`
+- `mutator.connect(criterion)` and `mutator.connect([criterion, ...])` in a relation callback of `create` or `update`
+- `mutator.disconnect([criterion, ...])` in a relation callback of `update`
+
+Only a model with a nullable unique column is affected. Given `Account.handle`, a nullable column with a unique constraint, these no longer compile:
+
+```ts
+await db.orm.Account.upsert({ create, update, conflictOn: { handle: null } });
+await db.orm.Account.upsert({ create, update, conflictOn: { handle: maybeHandle } }); // maybeHandle: string | null
+
+await db.orm.Owner.where({ id }).update({
+  accounts: (accounts) => accounts.connect({ handle: maybeHandle }),
+});
+```
+
+The compiler reports `Type 'null' is not assignable to type 'string'` on the field.
+
+The detection also matches code this change does not affect. Leave as they are: a `.connect(` or `.disconnect(` call on another object, such as `postgres.connect({ url })`; and the `conflictOn` of `createAll` and `createAndCount`, which is an array of field names, such as `conflictOn: ['handle']`.
+
+What to write instead:
+
+- Where the value is known to be present, narrow it before the call, so that its type has no `null`:
+
+  ```ts
+  if (maybeHandle === null) {
+    throw new Error('an account needs a handle to be connected');
+  }
+  await db.orm.Owner.where({ id }).update({
+    accounts: (accounts) => accounts.connect({ handle: maybeHandle }),
+  });
+  ```
+
+- Where the value can be absent, decide what that case means and write it as its own branch. For `upsert`, create the row with `create(...)` in that branch, or use a constraint whose columns all have values, such as the primary key: `conflictOn: { id }`. For `connect` and `disconnect`, leave the criterion out of the list in that branch, or name the row by another key.
+
+- To read or write the rows whose column is `NULL`, use `where({ handle: null })`. It can match more than one row.
+
+- Where your own code declares a variable, a parameter or a return value as `UniqueConstraintCriterion<...>`, the same rule applies to the values assigned to it.
+
+## `prepared-all-and-aggregate-need-their-receiver`
+
+`all` and `aggregate` on a collection's `prepared` object now declare the object they are called on. This applies to every collection, not only one filtered with `whereUnique`. A call without that receiver no longer compiles:
+
+```ts
+const { all, aggregate } = db.orm.Post.prepared;
+all(); // error: The 'this' context of type 'void' is not assignable to method's 'this'
+aggregate((a) => ({ posts: a.count() })); // the same error
+```
+
+Call the method on the `prepared` object instead:
+
+```ts
+const prepared = db.orm.Post.prepared;
+prepared.all();
+prepared.aggregate((a) => ({ posts: a.count() }));
+```
+
+These still compile and need no change: a destructured `first` or `firstOrThrow`, as in `const { first, firstOrThrow } = db.orm.Post.prepared; first(); firstOrThrow()`, and `prepared.all` passed as a callback without being called. What the methods do at run time is unchanged.
+
+## `build-native-enums-takes-the-domain`
+
+Pass the contract's domain beside its storage:
+
+```ts
+// before
+buildNamespacedNativeEnums(contract.storage);
+// after
+buildNamespacedNativeEnums(contract.storage, contract.domain);
+```
+
+The result no longer has an accessor for a domain enum (an `enum` block or `enumType()`), only for native enum types. The type `NamespacedNativeEnums<Contract>` leaves out the same names. Code that read a domain enum from the result reads it from the accessor `db.enums` uses instead.
+
+## Middleware hooks are activity hooks
+
+The runtime now runs every statement and every transaction as an **activity**. A middleware observes an activity through three lifecycle events, `activityStarted`, `activityEnded` and `activityFinalized`, and changes or stops a statement through interceptors: `beforeEncode`, `intercept.onQuery`, `intercept.onExecute` and `onRow`. The per-statement hooks are gone.
+
+### Rename the hooks
+
+| Before | After |
+|---|---|
+| `beforeQuery`, `beforeExecute` | `beforeEncode` |
+| `interceptQuery`, `interceptExecute` | `intercept.onQuery`, `intercept.onExecute` |
+| `onRow` | `onRow` |
+| `afterQuery`, `afterExecute` | `activityEnded` on a statement |
+| `afterTransaction` | `activityFinalized` on a statement |
+| `beforeCompile` | `beforeCompile` |
+
+`beforeEncode` keeps the arguments of `beforeQuery` and `beforeExecute`: the lowered plan, the context and the parameter mutator. It runs for both `query()` and `execute()`. A middleware that defined both `beforeQuery` and `beforeExecute` with the same body defines `beforeEncode` once. A middleware that must tell them apart reads `activity.returns` (`'rows'` or `'stats'`) in `activityStarted` and keeps it in `ctx.state`.
+
+The interceptors move under one `intercept` object:
+
+```diff
+- async interceptQuery(plan, ctx) {
+-   return { rows: cached };
+- },
++ intercept: {
++   async onQuery(plan, ctx) {
++     return { rows: cached };
++   },
++ },
+```
+
+### Read the result from `activityEnded`
+
+`afterQuery(plan, result, ctx)` and `afterExecute(plan, result, ctx)` become one hook, `activityEnded(activity, result, ctx)`. It fires for transactions too, so check the kind first. `result.completed` is replaced by `result.outcome`, which is `'succeeded'`, `'failed'` or `'stopped'` (the caller stopped reading the rows). `latencyMs` and `source` are unchanged; `rowCount` or `stats` is there according to `result.returns`. The plan the caller sent is `activity.plan`; the lowered SQL is not on the activity, so a middleware that logs it keeps it from `beforeEncode` in `ctx.state`:
+
+```diff
+- async afterQuery(plan, result, ctx) {
+-   if (result.latencyMs > 250) ctx.log.warn({ sql: plan.sql, rowCount: result.rowCount });
+- },
++ async beforeEncode(plan, ctx) {
++   ctx.state(statementSql)['sql'] = plan.sql;
++ },
++ async activityEnded(activity, result, ctx) {
++   if (result.kind !== 'statement' || result.latencyMs <= 250) return;
++   ctx.log.warn({
++     sql: ctx.state(statementSql)['sql'],
++     ...(result.returns === 'rows' ? { rowCount: result.rowCount } : {}),
++   });
++ },
+```
+
+`statementSql` is a module-level `Symbol('…')`, for example `const statementSql = Symbol('slow-query-warning.sql')`. An error thrown from `activityEnded` after a successful statement still fails it and reaches the caller, as an error from `afterQuery` did; every other middleware still receives `activityEnded`, and the caller receives the first error. A transaction also ends: `succeeded` when its `commit()` or `rollback()` resolved, `failed` when it rejected. So a rolled-back transaction ends `succeeded` and is finalized `rolled-back`. `activityEnded` also fires where `afterQuery` and `afterExecute` did not: for a statement the caller stopped reading, with `result.outcome` `'stopped'`, and for a statement that failed before it ran, in `beforeCompile`, `beforeEncode` or parameter encoding, with `result.outcome` `'failed'`, `latencyMs: 0` and `source: 'driver'`. A middleware that counts statements or latencies checks `result.outcome` if it should skip them.
+
+### Replace `afterTransaction` with `activityFinalized`
+
+`afterTransaction(plan, result, ctx)` becomes `activityFinalized(activity, result, ctx)`. A statement still running when its transaction ends is finalized when it ends, after its `activityEnded`, where `afterTransaction` fired at the transaction's end, before the statement's after-hook. `result.outcome` keeps its three values, `'committed'`, `'rolled-back'` and `'unknown'`, and the same rules decide it. An error thrown from it is still logged and swallowed. It also fires for transactions, after their statements, so a middleware that acts on statements checks `activity.kind === 'statement'`. A statement that fails before it runs, in `beforeCompile`, `beforeEncode` or parameter encoding, is now finalized too: `unknown` outside a transaction, and with the transaction's outcome inside one.
+
+### Rename the context type and the execution id
+
+`RuntimeMiddlewareContext` is now `ActivityContext`, and `SqlMiddlewareContext` and `MongoMiddlewareContext` extend it. A SQL middleware imports `SqlMiddleware` and `SqlMiddlewareContext` from `@prisma/orm-postgres/family-runtime` (or `@prisma/orm-sqlite/family-runtime`), a Mongo middleware imports `MongoMiddleware` and `MongoMiddlewareContext` from `@prisma/orm-mongo/family-runtime`, and a cross-family middleware imports `CrossFamilyMiddleware` and `ActivityContext` from `@prisma/orm-framework/components/runtime`. `ctx.planExecutionId` is removed; use `activity.id`, a fresh id for each activity that every hook of the activity sees. A log detail or field that carried `planExecutionId: ctx.planExecutionId` becomes `activityId: activity.id`. Keep per-statement state in `ctx.state(key)` instead of a `WeakMap` keyed by the plan: each activity has its own state, and middleware that use the same key share the object. `AfterQueryResult`, `AfterExecuteResult` and `AfterTransactionResult` are removed; use `ActivityEndedResult` and `ActivityFinalizedResult`.
+
+### Abort phases and already-aborted calls
+
+A `RUNTIME.ABORTED` error raised during the middleware stage before encoding has `details.phase` `'beforeEncode'`. Code that matches `'beforeQuery'` or `'beforeExecute'` matches `'beforeEncode'` instead. The same holds for the Mongo error `RUNTIME.CONTENT_HASH_REQUIRES_RESOLVED_COMMAND`, raised when a Mongo `beforeEncode` hook calls `ctx.contentHash`: its `details.phase` is `'beforeEncode'`. A call whose signal was aborted before it was made now fires `activityStarted`, then ends `failed`, before it rejects with `RUNTIME.ABORTED`.
+
+### The observed-row budget now runs
+
+`budgets()` now counts the rows each query returns. Before, this check never ran, so a query that returned more than `maxRows` rows succeeded. Now, with the default row severity `'error'` or in `strict` mode, such a query fails with `BUDGET.ROWS_EXCEEDED` once the count passes `maxRows`; with `severities: { rowCount: 'warn' }` in `permissive` mode it logs one warning for the statement and keeps streaming. The `postgres()` client runs its runtime in `strict` mode, where every `budgets()` violation throws whatever its severity, so the warn path does not apply there until the client exposes `mode`. Raise `maxRows` for reads that are expected to return more rows. `tableRows` and `defaultTableRows` only change the estimate checked before a read runs; they do not change the limit on rows a read actually returns.
+
+### Move per-statement state from a `WeakMap` to `ctx.state`
+
+A middleware that kept per-statement state in a `WeakMap` keyed by the plan keeps it in `ctx.state` instead. The state object's values are `unknown`, so read them back through a type guard, and delete the entry in `activityEnded` once it is used:
+
+```diff
+- const pending = new WeakMap<object, PendingMiss>();
++ const pendingMiss = Symbol('cache.pendingMiss');
++
++ function pendingOf(ctx: ActivityContext): PendingMiss | undefined {
++   const miss = ctx.state(pendingMiss)['miss'];
++   return isPendingMiss(miss) ? miss : undefined;
++ }
+
+  // in intercept.onQuery, on a miss
+- pending.set(exec, { entry, buffer: [] });
++ ctx.state(pendingMiss)['miss'] = { entry, buffer: [] };
+
+  // in onRow
+- pending.get(exec)?.buffer.push(row);
++ pendingOf(ctx)?.buffer.push(row);
+
+  // in activityEnded, which replaces afterQuery
+- const miss = pending.get(exec);
+- if (miss === undefined) return;
+- pending.delete(exec);
+- if (!result.completed || result.source !== 'driver') return;
++ const miss = pendingOf(ctx);
++ if (miss === undefined) return;
++ delete ctx.state(pendingMiss)['miss'];
++ if (result.kind !== 'statement' || result.outcome !== 'succeeded' || result.source !== 'driver') return;
+```
+
+`pendingMiss` and `pendingOf` are module-level; `isPendingMiss` is a type guard for the state's shape. The middleware object then lists `intercept: { onQuery }`, `onRow` and `activityEnded` in place of `interceptQuery`, `onRow` and `afterQuery`.
+
+### Run statements through the statement runners
+
+A family runtime no longer composes the middleware runners itself. It runs each statement through one call that starts the activity, runs a body, and ends and finalizes the activity:
+
+```diff
+- await runBeforeQueryChain(exec, this.middleware, ctx, mutator);
+- yield* reportQueryEnding(onQueryEnd, () =>
+-   runQueryWithMiddleware(exec, this.middleware, ctx, () => this.runDriver(exec)),
+- );
++ yield* streamStatement(
++   { middleware: this.middleware, plan, context: contextFields, parent: undefined },
++   async function* (run) {
++     const exec = await prepare(run); // calls run.beforeEncode(draft, mutator) before encoding
++     yield* run.runQuery(exec, () => self.runDriver(exec));
++   },
++ );
+```
+
+`executeStatement` is the same for `execute()`, with `run.runExecute(exec, runDriver)`. `context` is an `ActivityContextFields`: the runtime-wide fields (`contract`, `mode`, `now`, `log`, `contentHash`, `scope`, and `signal` when the caller passed one); the runner adds `parent`, `state` and `inTransaction`. `parent` is the open transaction a statement was sent on, or `undefined`. `RuntimeCoreOptions.ctx` takes the same fields, so remove `planExecutionId` from it.
+
+A runtime that opens transactions calls `startTransactionActivity({ middleware, context, holdFinishedChildren })` before `BEGIN`, where `holdFinishedChildren` is decided once, when the runtime is created: `true` only when some middleware implements `activityFinalized`. It passes the result as the `parent` of every statement sent on the transaction or its connection while it is open, and calls `end({ by: 'commit' | 'rollback', outcome, ... })` when `commit()` or `rollback()` settles. A SQL runtime subclass that wrapped a driver transaction with `wrapTransaction(driverTx, connection)` calls `beginTransactionOn(connection, owner)` instead, which does all of this.
+
+### Renamed log events
+
+A test or log filter that matches the runtime's debug event `middleware.interceptQuery` or `middleware.interceptExecute` matches `middleware.intercept.onQuery` or `middleware.intercept.onExecute`. The error event `middleware.afterTransaction.error` is now `middleware.activityFinalized.error`.
+
+## MongoDB carries out `--rename` and `--delete`
+
+### `rename-statements-capability-removed`
+
+Delete `renameStatements` from a target's `migrations` capability, and any `keepDataByHand` function it pointed at. A test double of the capability that set it drops the member. A data-loss question now offers `rename` for a model or field the destination no longer has on every target; write a planner that carries out the resolved statements it is given, or refuses each with a `statementRefused` conflict that carries it in `refusedStatement`.
+
+### `mongo-ddl-rename-collection`
+
+The DDL command alphabet gains a collection rename:
+
+```ts
+import { RenameCollectionCommand } from '@prisma/orm-family-mongo/query-ast/control';
+
+new RenameCollectionCommand('profiles', 'users');
+```
+
+A `MongoDdlCommandVisitor<R>` implementation adds `renameCollection(command)`. A Mongo driver's `run(wireCommand)` handles `kind: 'renameCollection'`, as the shipped driver does with `db.renameCollection(collection, to)`, without `dropTarget`. An adapter's DDL lowering maps the command to `new RenameCollectionWireCommand(command.collection, command.to)`.
+
+### `mongo-dml-operations`
+
+Rename the types where code names them:
+
+```diff
+- import type { MongoDataTransformCheck, MongoDataTransformOperation } from '@prisma/orm-family-mongo/query-ast/control';
++ import type { MongoDmlCheck, MongoDmlOperation } from '@prisma/orm-family-mongo/query-ast/control';
+```
+
+Where code narrows `AnyMongoMigrationOperation` by `operation.operationClass === 'data'`, use the guard instead:
+
+```diff
+- if (operation.operationClass === 'data') {
++ if (isMongoDmlOperation(operation)) {
+```
+
+`isMongoDmlOperation` comes from `@prisma/orm-family-mongo/query-ast/control`. An operation without `run` is a DDL operation. The `dataTransform` factory keeps its name: it builds a DML operation with class `data`. A hand-written `dataTransform` still has class `data`, so a policy that leaves out `data` (as `db update`'s does) still refuses it, and runs `renameField` and `unsetField`.
+
+### `mongo-update-many-bypass-validation`
+
+A hand-built lowered draft of kind `rawUpdateMany` adds `bypassDocumentValidation: false`. A driver's `updateMany` passes `bypassDocumentValidation: true` to MongoDB when the wire command carries it.
+
+### `mongo-op-factory-call-to-op`
+
+Code typed against the result of `toOp()` or `renderOps(...)` as `MongoMigrationPlanOperation` widens it to `AnyMongoMigrationOperation`, and narrows with `isMongoDmlOperation` where it needs `execute` or `run`.