---
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.
-->
