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

package/skills/prisma-8/upgrading/extension/upgrades/0.15-to-0.16/instructions.md

@@ -0,0 +1,219 @@
+---
+from: "0.15"
+to: "0.16"
+changes:
+  - id: extension-supabase-test-utils-export-removed
+    summary: |
+      `@internal/extension-supabase` no longer exports the `./test/utils` subpath
+      (`bootstrapSupabaseShim`), and it is no longer a pattern to copy for extension test
+      tooling. The import typechecked (types shipped in `dist`), but the subpath never worked
+      from npm — the shim reads fixture `.sql` files that were never published, so every call
+      failed with ENOENT before touching a database. Delete any import of
+      `@internal/extension-supabase/test/utils`; keep hermetic test helpers package-internal
+      (tests import them by source path) rather than publishing them as subpath exports whose
+      on-disk fixtures don't ship.
+    detection:
+      glob: "**/*.{ts,mts,cts,js,mjs}"
+      contains:
+        - "extension-supabase/test/utils"
+      anyMatch: true
+  - id: identity-columns-need-explicit-default-under-strict-verify
+    summary: |
+      `contract infer` now emits `@default(autoincrement())` for a Postgres `GENERATED ALWAYS AS IDENTITY` / `GENERATED BY DEFAULT AS IDENTITY` column (previously it emitted a bare column with no default, since Postgres reports no `column_default` for an identity column). Symmetrically, `db verify` introspecting a live identity column now resolves its default to `autoincrement()` too (previously it resolved to nothing). This only changes `db verify --strict` — without `--strict`, an undeclared live default is tolerated either way (and it is fully tolerated regardless of strictness under `control: 'external'`, the posture most extension packs declare). If your pack's own tests run `db verify --strict` against a table with an identity column whose contract does not declare `@default(autoincrement())`, verify now reports that default as an unexpected extra. Re-run `contract infer` for the affected table, or add `@default(autoincrement())` by hand.
+  - id: pluralize-back-relation-names-no-longer-double-pluralize
+    summary: |
+      `contract infer`'s back-relation field name generation used a hand-rolled pluralization rule that appended `es` to any table name already ending in `s`/`x`/`z`/`ch`/`sh`, doubling an already-plural table name (`sessions` -> `sessionses`). `contract infer` now uses real inflection (the `pluralize` library) and produces the correct name (`sessions` stays `sessions`; a genuinely singular `status` still becomes `statuses`). This only affects a future `contract infer` run — an already-generated `.prisma` file is untouched, so nothing breaks until you next re-run infer for your pack. If you do re-run `contract infer` against a schema with an already-plural table name, diff the regenerated `.prisma` file for any back-relation field whose name changed — that's a public field name your pack's consumers access via `.include()`/`.select()`/the generated TypeScript types, so a rename is a breaking change to your pack's own published surface, to be versioned and documented like any other.
+  - id: scalar-type-descriptors-channel-removed
+    summary: |
+      `ComponentMetadata.scalarTypeDescriptors` is retired — the unified authoring type namespace
+      is now the single channel for scalar types. If your extension/adapter descriptor declared
+      `scalarTypeDescriptors: new Map([['String', 'pg/text@1'], ...])`, move each entry to a
+      zero-arg type-constructor contribution in the descriptor's `authoring.type` namespace:
+      `String: { kind: 'typeConstructor', output: { codecId: 'pg/text@1', nativeType: 'text' } }`.
+      The `nativeType` is now explicit — it was previously derived from the codec's first target
+      type, so check the codec manifest for the value to inline. Code that read
+      `ControlStack.scalarTypeDescriptors` / `ContractSourceContext.scalarTypeDescriptors` should
+      read `stack.scalarTypes` (the scalar type names) or derive the name ->
+      `{ codecId, nativeType }` map via `collectScalarTypeConstructors(stack.authoringContributions.type)`
+      from `@internal/framework-components/authoring`. `assembleScalarTypeDescriptors` is
+      deleted, and `validateScalarTypeCodecIds` now takes the authoring type namespace instead of
+      a descriptor map.
+    detection:
+      glob: "**/*.{ts,mts,cts}"
+      contains:
+        - "scalarTypeDescriptors"
+        - "assembleScalarTypeDescriptors"
+      anyMatch: true
+  - id: postgres-json-rebound-to-native-json
+    summary: |
+      On the postgres target the PSL `Json` scalar re-binds from `pg/jsonb@1` / `jsonb` to
+      `pg/json@1` / `json`; a new bare `Jsonb` scalar carries `pg/jsonb@1` / `jsonb`
+      (`postgresScalarAuthoringTypes` in `@internal/adapter-postgres`). Extension test
+      schemas and fixtures that author postgres `Json` fields and mean jsonb storage must
+      switch those fields to `Jsonb`; assertions that pin the `Json` name's derived binding
+      (e.g. over `collectScalarTypeConstructors(stack.authoringContributions.type)` or
+      `stack.scalarTypes`) now expect `Json -> { codecId: 'pg/json@1', nativeType: 'json' }`
+      plus the new `Jsonb -> { codecId: 'pg/jsonb@1', nativeType: 'jsonb' }` entry. PSL
+      value-object storage columns still emit jsonb (the interpreter now prefers the target's
+      `Jsonb` scalar and falls back to `Json`). The legacy `@db.Json` attribute path
+      (`NATIVE_TYPE_SPECS`) is unchanged, as are sqlite/mongo `Json` bindings and the TS
+      builder surface (`field.json()`, `jsonbColumn`).
+    detection:
+      glob: "**/*.{prisma,ts,mts,cts}"
+      contains:
+        - "Json"
+      anyMatch: true
+  - id: default-generators-no-longer-set-storage
+    summary: |
+      `@default(<generator>)` never mutates a column's storage any more — the type position is
+      the only storage decider — and the whole generator-storage-override SPI is retired with
+      it. Removed surfaces: `MutationDefaultGeneratorDescriptor.resolveGeneratedColumnDescriptor`
+      (`@internal/framework-components/control`) — generator descriptors are now
+      `{ id, applicableCodecIds?, buildPhases? }` only, and `applicableCodecIds` remains the
+      validation channel (`PSL_INVALID_DEFAULT_APPLICABILITY` on mismatch); the transitional
+      `baseScalar` marker on `AuthoringTypeConstructorDescriptor` and
+      `ScalarTypeConstructorOutput` (`@internal/framework-components/authoring`) — scalar
+      type-constructor contributions and the derived scalar view are plain
+      `{ codecId, nativeType, typeParams? }` again; and the `@internal/ids` exports
+      `resolveBuiltinGeneratedColumnDescriptor` / `GeneratedColumnDescriptor` (the TS spec
+      helpers `uuidv4()`, `nanoid()`, … still return `GeneratedColumnSpec` bundling their
+      explicit `sql/char@1` column). Packs that registered a generator descriptor with a
+      storage-resolution hook must drop the hook; PSL schemas in extension fixtures relying on
+      `String @default(uuid()/cuid()/nanoid()/ulid())` producing `character(N)` columns must
+      either accept the target String storage (postgres: `pg/text@1` / `text`) or author the
+      char storage explicitly in the type position (`Char(36) @default(uuid())`, …), then
+      re-emit.
+    detection:
+      glob: "**/*.{ts,mts,cts,prisma}"
+      contains:
+        - "resolveGeneratedColumnDescriptor"
+        - "resolveBuiltinGeneratedColumnDescriptor"
+        - "baseScalar"
+        - "@default(uuid("
+        - "@default(cuid("
+        - "@default(nanoid("
+        - "@default(ulid("
+      anyMatch: true
+---
+
+<!--
+Release bump to 0.16.0 (PR #1019): the version bump itself. Every
+`packages/3-extensions/*/package.json` advances to 0.16.0 (version field +
+`workspace:` specifier lockstep). The bump commit touches only `package.json`
+files and `pnpm-lock.yaml` — no SPI, contract shape, or emitted artefact change
+beyond the pack version stamp. No extension-author action beyond the normal
+dependency upgrade this recipe covers. Incidental substrate diff only.
+-->
+
+<!--
+TML-3037 (contract infer output round-trips through contract emit): the
+`packages/3-extensions/supabase` diff is this repo's own pack regenerating
+under the three fixes recorded as `changes[]` entries above, plus two changes
+that need no entry because they are purely additive: the postgres target now
+registers `btree`/`hash`/`gin`/`gist`/`spgist`/`brin` as built-in index types,
+so `auth.one_time_tokens`' two `USING hash` indexes — previously impossible to
+emit at all (emit threw `unregistered index type "hash"`) — now come back
+declared as `@@index(..., type: "hash")`; and the `Decimal` scalar
+(`pg/numeric@1` with no `typeParams`) no longer crashes `ExecutionContext`
+construction, a base-scalar fix with no prior working case to break.
+
+The jsonb `dbgenerated` literal defaults on `custom_oauth_providers`
+(`attribute_mapping`, `authorization_params`), `webauthn_credentials`
+(`transports`), and `iceberg_namespaces` (`metadata`) are also declared again,
+each as `@default(dbgenerated("..."))` verbatim — but this is *not* an
+authoring-side fix and needs no `changes[]` entry of its own: emit still keeps
+the raw expression as `kind: 'function'` exactly as it always did (no
+`contract.json` shape change relative to a pack that already declared these
+defaults). What changed is `db verify`: the postgres target's `SchemaIR`
+construction now resolves the expected side's `kind: 'function'` default
+through the same literal-recognizing parser introspection already used, so a
+literal-shaped `dbgenerated(...)` default compares equal against the live
+column instead of reporting permanent drift. That fix is invisible to
+`contract.json` and the contract's `storageHash`, so nothing downstream needs
+to regenerate anything on account of it.
+
+`custom_oauth_providers`' `acceptable_client_ids`/`scopes` — also `text[]`
+with a `dbgenerated("'{}'::text[]")` default, but on *list* fields — stay
+omitted: `contract emit` rejects any function-kind default on a list field
+(`PSL_LIST_EXECUTION_DEFAULT_UNSUPPORTED`), and `dbgenerated(...)` always
+lowers to `kind: 'function'` at authoring time now (a target-owned handler
+classifying it as a literal there would need the column's native type,
+threaded through the shared `DefaultFunctionLoweringContext` framework type —
+exactly the family-vocabulary-in-framework violation this round removed).
+This is a known, undocumented-elsewhere limitation, not a regression: it was
+never fixed to begin with on the branch this round reviewed.
+
+`generate-contract.ts`'s `DOUBLE_PLURALIZED_FIELD_NAMES` and `INDEX_OMISSIONS`
+workaround tables are deleted entirely; `DEFAULT_OMISSIONS` shrinks from 7
+entries (across `auth.users`, `auth.custom_oauth_providers`,
+`auth.webauthn_credentials`, `storage.iceberg_namespaces`) to 3
+(`auth.users.phone`, a `DEFAULT NULL` that round-trips to `@default(null)`, a
+different still-open defect; and `auth.custom_oauth_providers`'
+`acceptable_client_ids`/`scopes`, the list-default limitation above). No
+extension-authoring SPI change — an extension pack's own contract regenerates
+automatically the same way this pack's did.
+-->
+
+<!--
+TML-3027 (foreign keys and indexes are discrete contract entities): emitted
+contract-shape change. `contract emit` now materializes the per-FK `constraint`/
+`index` authoring booleans into discrete entities — a `foreignKeys[]` entry is the
+referential constraint only (no `constraint`/`index` fields), and every backing
+index (including one backing a FK) is its own named `indexes[]` entry. The booleans
+remain as authoring input (`@relation(index:)`, TS `fk({ constraint, index })`,
+`foreignKeyDefaults`). An extension whose contract declares FKs re-emits to the new
+shape on the next `contract emit`, with no authoring change. Extension code that
+reads `.constraint` / `.index` off a contract's `foreignKeys[]` entry (e.g. custom
+migration/verify logic or a hand-built contract fixture) must drop those fields and
+read the discrete `indexes[]` entry instead. No SPI or DDL change: the schema-IR the
+planner and `db verify` derive is identical. (The `packages/3-extensions/` diff is
+pgvector test fixtures updated to the new FK literal shape.)
+-->
+
+<!--
+Supabase integration close-out (TML-2503): docs-only. The
+`packages/3-extensions/` touch is `packages/3-extensions/supabase/README.md` —
+links into the deleted `projects/supabase-integration/` workspace re-pointed at
+ADR 237 (the service_role secondary-root decision) or inlined as plain text.
+No SPI, contract shape, or emitted artefact change. Incidental substrate diff
+only.
+-->
+
+<!--
+TML-3028 (dependency-graph migration ordering; SchemaDiffIssue.reason removed):
+the migration-diff internal `SchemaDiffIssue` lost its `reason` field —
+discriminate a diff issue via the presence of `expected`/`actual`, or the
+exported `issueOutcome(issue): ExpectationFailureReason` helper from
+`@internal/framework-components/control`. `ExpectationFailureReason` keeps its
+`'not-found' | 'not-expected' | 'not-equal'` values and its export path; it is now
+the helper's return type rather than the removed field's type. This is a framework migration-control
+internal, not an extension-authoring SPI. The `packages/3-extensions/` diff is
+supabase-extension TEST assertions updated from `.reason` to presence — no runtime,
+contract, SPI, or DDL change. Incidental test-only diff.
+-->
+
+<!--
+TML-2783 (explicit MTI selections): `changes: []`. The `packages/3-extensions/sql-orm-client` diff is limited to internal polymorphic projection planning and regression tests; it changes no public API, contract/emitted artifact, extension-authoring surface, adapter API, or downstream source translation.
+-->
+
+<!--
+Dependabot dev-deps group bump (PR #961): `changes: []`. The
+`packages/3-extensions/` diff is biome.jsonc schema-version alignment for the
+biome 2.5.2 dev-dependency bump plus the code sites biome 2.5 newly flags
+(useOptionalChain in `sql-orm-client/src/collection.ts`); no SPI, contract
+shape, emitted artefact, or extension-authoring surface change. Incidental
+substrate diff only.
+-->
+
+<!--
+Dependabot dev-deps group bump (PR #1006): `changes: []`. The
+`packages/3-extensions/` diff is test-only — the `sql-orm-client` tests updated
+from `(x?.y as T).z` to `(x!.y as T).z` to satisfy biome 2.5.3's stricter
+noUnsafeOptionalChaining (biome 2.5.2 → 2.5.3 dev-dependency bump). No SPI,
+contract shape, emitted artefact, or extension-authoring surface change.
+Incidental substrate diff only.
+-->
+
+<!--
+TML-2979 (MTI variant predicates in count writes): `changes: []`. The `packages/3-extensions/sql-orm-client` diff fixes internal query planning and adds regression coverage; it changes no public API, contract shape, emitted artefact, extension-authoring surface, adapter API, or downstream source translation. Incidental substrate diff only.
+-->