[v3 RC4] Align Better Auth UI with the retained @btst/db cohort

[olliethedev]

Current decision — 2026-08-31

Stable v3 retains @btst/db@2.2.3, @btst/adapter-prisma@2.2.3, and @btst/adapter-drizzle@2.2.3 on their existing Better Auth 1.6.16 baseline. This issue no longer proposes updating the database fork or widening its peers to Better Auth 1.7.2.

The correction belongs to the Better Auth UI companion: publish a new candidate aligned to the retained 1.6.16 cohort, then prove the complete public package graph through packed npm and pnpm consumers.

Companion implementation: better-stack-ai/better-auth-ui#22.

Problem

The published RC3 artifacts select two incompatible exact Better Auth cohorts:

@btst/stack@3.0.0-rc.3
  -> @btst/db@2.2.3
     -> better-auth@1.6.16
     -> @better-auth/core@1.6.16
     -> @better-auth/utils@0.4.1

@btst/better-auth-ui@2.0.0-rc.3
  -> better-auth@1.7.2
  -> @better-auth/api-key@1.7.2
  -> @better-auth/passkey@1.7.2
  -> @better-fetch/fetch@1.3.1

A fresh strict pnpm resolution cannot satisfy both universes. A frozen force-resolved lockfile may materialize, but that does not meet the clean-install acceptance criterion and can mask incompatible package types.

Bio Mogging reproduced the same split with the Prisma adapter: validation evidence.

Target v3 cohort

Retain the database packages unchanged and align the companion to:

• @btst/db@2.2.3
• @btst/adapter-prisma@2.2.3
• @btst/adapter-drizzle@2.2.3
• better-auth@1.6.16
• @better-auth/core@1.6.16
• @better-auth/utils@0.4.1
• @better-auth/api-key@1.6.16
• @better-auth/passkey@1.6.16
• @better-fetch/fetch@1.2.2
• better-call@1.3.6

better-auth@1.6.16 already depends on the exact Core, Utils, Fetch, and Better Call versions above. This also satisfies the published Stack RC3 exact better-call@1.3.6 peer.

What to deliver

1. Complete better-auth-ui#22 and publish an immutable companion candidate, expected as @btst/better-auth-ui@2.0.0-rc.4 under next.
2. Exercise the candidate through the packed-consumer coverage in Add packed npm/pnpm compatibility smoke tests #174 with the retained database and adapter packages.
3. Record the exact source commits, tags, workflow runs, npm integrities/shasums, dist-tags, and resolved dependency graphs on [v3] Resolve RC3 findings and publish stable v3 #153.
4. Feed the verified cohort and explicit adapter transaction: true application guidance into [v3 stable docs] Publish the final production migration and verification playbook #175.

Acceptance criteria

• The Better Auth UI candidate uses the exact retained 1.6.16 cohort.
• @btst/db and all BTST adapters remain at 2.2.3 and receive no source or metadata changes for this v3 correction.
• A minimal BTST fixture without Better Auth UI installs cleanly.
• A Better Auth UI auth-plus-account fixture installs cleanly with both npm and strict pnpm.
• The resolved graph contains one compatible Better Auth/Core/Utils/Fetch/Call universe and requires no force flag, peer override, or undocumented direct pin.
• Packed Next.js, React Router, and TanStack fixtures type-check and production-build.
• Focused auth, account, avatar, session-refresh, and logout behavior passes against Better Auth 1.6.16.
• Optional organization, API-key, and passkey integrations remain opt-in and pass their declared type/runtime checks.
• Public tarballs match the artifacts exercised by the compatibility gate.
• latest remains on the existing stable package lines until stable v3 is separately approved.

Explicit non-goals

• Updating the better-stack-ai/better-auth fork to a newer upstream baseline.
• Changing BTST adapter transaction defaults or implementing new adapter semantics.
• Pulling newer upstream Drizzle adapter behavior into the v3 release.
• Claiming simultaneous Better Auth 1.6.x and 1.7.x support.

Adapter synchronization and future Better Auth upgrades must be tracked separately after v3. Applications using Form Builder, Media, or other atomic plugins continue to configure transaction: true explicitly; #175 owns that migration guidance.

Blocked by

• better-stack-ai/better-auth-ui#22
• Add packed npm/pnpm compatibility smoke tests #174 packed npm/pnpm verification

Parent

• [v3] Resolve RC3 findings and publish stable v3 #153

[olliethedev]

Additional RC3 runtime evidence: the published Drizzle adapter is not only peer-incompatible; it also fails RC3 media mutations.

With @btst/adapter-drizzle@2.2.3:

1. createDrizzleAdapter(..., { provider: \"pg\" }) exposes no transaction function, despite CreateDrizzleAdapterConfig.transaction documenting @default true. RC3 media creation fails with ATOMIC_TRANSACTION_REQUIRED until transaction: true is passed explicitly.
2. After enabling transactions and adding RC3's new mediaAsset.updatedAt / mediaFolder.updatedAt schema fields, upload + asset creation succeeds.
3. Deleting that asset fails with:

BetterAuthError: Adapter \"drizzle\" updateMany must return a finite number affected row count.
DELETE /api/data/media/assets/<id> 500

The 2.2.3 adapter's updateMany returns the raw Drizzle builder result rather than a numeric affected-row count. RC3's ownership/claim operations enforce the adapter contract and reject it.

A coordinated adapter/db release should therefore fix the runtime contract and the misleading transaction default in addition to widening the Better Auth peers.

[olliethedev]

Final validation nuance after committing the force-resolved lockfile: pnpm can materialize that frozen resolution, and a full --force --frozen-lockfile --strict-peer-dependencies reinstall completed. That does not make the cohort peer-valid: resolution is skipped from the lock, which binds @btst/db@2.2.3 and @btst/adapter-drizzle@2.2.3 to Better Auth/Core 1.7.2 despite their exact 1.6.16 declarations, and binds Stack's exact better-call@1.3.6 peer to 1.4.0.

The report will classify frozen lock materialization as passing with this caveat, but the “no undocumented peer pins / clean dependency graph” acceptance criterion remains failed. The adapter runtime findings are unchanged: explicit transaction: true is required and media delete still fails the finite updateMany row-count contract.

[olliethedev]

Bio Mogging RC3 adds matching Prisma evidence from the retained real-project validation.

Exact cohort:

• @btst/stack@3.0.0-rc.3
• @btst/adapter-prisma@2.2.3
• @btst/db@2.2.3
• better-auth@1.7.2
• pnpm 10.17.1

A fresh strict resolution without reading the lockfile fails with the same exact peer split:

@btst/stack -> better-call@1.3.6 (found 1.4.0)
@btst/db -> better-auth@1.6.16, core@1.6.16, utils@0.4.1
@btst/adapter-prisma -> better-auth@1.6.16, core@1.6.16, utils@0.4.1
(found Better Auth 1.7.2 / core 1.7.2 / utils 0.4.2)

As with the Drizzle report, --force --frozen-lockfile --strict-peer-dependencies can materialize the committed invalid resolution, so frozen install is reproducible but the public cohort is not peer-valid.

Prisma also reproduces the transaction-default migration trap. With the documented-looking default config:

createPrismaAdapter(prisma, db, { provider: "postgresql" })({})

Form creation succeeds, but update, public submission, and delete each return 500 ATOMIC_TRANSACTION_REQUIRED; Media owner-sensitive writes use the same requirement. Adding transaction: true makes Form update/submission/delete and the full Media upload/update/move/delete lifecycle pass. Prisma asset deletion correctly removed the database row and Vercel Blob, so I did not reproduce the Drizzle updateMany row-count defect.

The combination is particularly easy to miss in migration: initial reads and creates work, while later lifecycle steps fail. The RC3 migration guidance should explicitly require transaction: true for adapters/databases that support it, and the published adapter/db peers still need an aligned release.

[olliethedev]

The corrected RC4 cohort is complete and verified.

Release provenance:

• Better Auth UI implementation: fix: align Better Auth UI with retained 1.6 cohort better-auth-ui#23
• Published @btst/better-auth-ui@2.0.0-rc.4 from release run https://github.com/better-stack-ai/better-auth-ui/actions/runs/33446733887
• Integrity: sha512-nhePkXvn0pjlXKKS4FwGlslVV04VuO0SjmFO79BfHttRPCVBsOEH7BMrXbOcACgwRRyRq8gGY4ggI6IRtTTi+Q==
• Shasum: 980ad834d71a709f65c5179ba2eb75a554c37970
• latest remained on 1.2.5.

Compatibility evidence:

• Public packed npm/pnpm consumer gate: test: add packed npm and pnpm consumer gates #251
• Successful gate run: https://github.com/better-stack-ai/better-stack/actions/runs/33447678962
• The downloaded public tarball matched the locally tested artifact byte-for-byte.
• Generated Next.js, React Router, and TanStack strict-peer fixtures: feat(cli): restore Better Auth UI scaffold #252
• Packed fixture run: https://github.com/better-stack-ai/better-stack/actions/runs/33450708155
• Framework build/E2E run: https://github.com/better-stack-ai/better-stack/actions/runs/33450708157

The resolved package graph uses one Better Auth/Core/Utils/Fetch/Call universe: Better Auth/Core 1.6.16, Utils 0.4.1, Fetch 1.2.2, and Better Call 1.3.6. @btst/db, @btst/adapter-prisma, and @btst/adapter-drizzle remain unchanged at 2.2.3. Optional organization, API-key, and passkey behavior remains opt-in.

The production migration guide, including explicit transaction: true guidance and the separately tracked Drizzle affected-row risk, remains owned by #175/#137. Closing this cohort-alignment ticket as complete.