[v3] Resolve RC3 findings and publish stable v3

[olliethedev]

Stable-v3 cohort correction — 2026-08-31

The RC3 package graph selected Better Auth 1.7.2 for Better Auth UI while @btst/db@2.2.3 and its adapters retain Better Auth 1.6.16. Stable v3 will resolve that mismatch by aligning the companion down to the retained database cohort, not by upgrading or synchronizing the database fork.

• Coordination and clean-install acceptance: [v3 RC4] Align Better Auth UI with the retained @btst/db cohort #244.
• Companion implementation and immutable RC4 publication: better-auth-ui#22.
• Packed npm/pnpm proof: Add packed npm/pnpm compatibility smoke tests #174.
• Stable migration guidance, including explicit transaction: true where atomic plugins require it: [v3 stable docs] Publish the final production migration and verification playbook #175.
• Any future Better Auth fork or adapter upgrade is separate post-v3 work.

This correction supersedes the preserved RC3 planning text below wherever it names Better Auth 1.7.2 as the stable-v3 target cohort.

---

This was generated by AI during triage.

Current status — 2026-08-31

RC3 has been published and its primary real-application validation is complete. This status section supersedes the pre-publication ordering and unchecked RC3 gates preserved below as historical release context.

Completed

• [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 and the complete canonical v3 runtime/DX sequence through [v3 DX] Contract legacy seams and verify the complete all-plugin matrix #225 are merged.
• better-auth-ui#20 is complete via better-auth-ui PR #21, and @btst/better-auth-ui@2.0.0-rc.3 is published on next.
• PR #243 published @btst/stack@3.0.0-rc.3 and @btst/codegen@0.2.0-rc.3 on next.
• better-stack-web#37 completed the retained RC3 validation and published its report/evidence.
• RC3 authenticated Next SSR refetches without request headers after hydration #245 was closed after confirming that its apparent SSR regression was an application route-group composition mistake.

Remaining stable-release work

• [v3 RC4] Align Better Auth UI with the retained @btst/db cohort #244 and better-auth-ui#22: align Better Auth UI with the retained @btst/db@2.2.3 Better Auth 1.6.16 cohort; do not upgrade the database fork for v3.
• RC3 codegen cannot load a real Next.js stack config #246: make codegen load a normal Next.js stack configuration using the application module-resolution environment.
• [v3 stable] Restore the Better Auth UI CLI scaffold and documentation #219: restore the optional Better Auth UI auth-plus-account CLI/catalog/docs path.
• [v3 stable] Verify exact Better Auth UI override contracts across repositories #170: finish cross-repository override-contract acceptance after the companion implementation.
• Add packed npm/pnpm compatibility smoke tests #174: add permanent packed npm/pnpm consumer smoke tests.
• [v3 stable docs] Publish the final production migration and verification playbook #175: publish the final stable-v3 production migration and verification playbook.
• bio-mogging#109 completed the retained Prisma validation and remains non-blocking.

The published-artifact defects in #244 and #246 justify a focused RC4 before stable v3. This tracker now owns that RC4/stable closeout: fix the defects, pass the packed consumer gates, complete the scaffold and documentation, record focused validation, complete the soak, publish stable packages, and then close parent #137.

---

Context

Sub-issue of #137. This is the operational tracker for completing, publishing, and handing off the coordinated v3 RC3 cohort. RC3 must use npm's next dist-tag so latest continues to resolve to stable releases throughout validation.

RC1 and RC2 publication/real-project records remain preserved in this issue's comments:

• RC1 Better Stack Web validation
• RC2 Better Stack Web validation
• RC2 Bio Mogging validation

RC3 is a new coordinated release gate. The substantial #202 runtime/plugin-interface redesign lands first; the maintained Better Auth UI companion then migrates once against that final API; the main repository restores the optional companion scaffold/docs; generated clean installations verify the packed artifacts; and only then are the RC3 packages published together.

Real-project validation is deliberately post-publication and user-owned. It does not block RC3.

Exact RC3 publication targets

• @btst/stack@3.0.0-rc.3
• @btst/codegen@0.2.0-rc.3
• @btst/better-auth-ui@2.0.0-rc.3
• Exact stable companion/adapter/YAR and Better Auth versions recorded by Add packed npm/pnpm compatibility smoke tests #174 from the release lockfiles and packed artifacts

Publish all prerelease packages with --tag next. Do not move any package's latest tag. The Stack tag is v3.0.0-rc.3; the companion repository publishes its own v2.0.0-rc.3 release/tag from the reviewed release commit.

Authoritative dependency chain

#202 final core runtime/plugin DX
  -> better-auth-ui#20 migration implementation and RC3 package shape
  -> #219 restore optional core CLI/catalog/docs integration
  -> #174 packed-artifact compatibility and clean-install gate
  -> #175 final production migration/verification playbook
  -> coordinated core/codegen/Better Auth UI RC3 publication
  -> user-owned Better Stack Web #37 and Bio Mogging #109 validation

The Better Auth UI migration issue includes its release work, but its implementation PR/package shape must be available to #219 and #174 before publication. Hold its npm publication step for this coordinated gate; do not publish the companion early simply to satisfy a textual dependency.

RC3 implementation gate

• [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 lands with the final createBackendStack/createClientStack interfaces, centralized client runtime, inferred overrides, normalized plugin IDs/factories/lifecycle names, and preserved [v3 auth] Ship one-rule full-stack authorization #180–[v3 auth] Remove RC authorization paths and publish the v3 contract #193 authorization semantics.
• better-stack-ai/better-auth-ui#20 migrates the wrapper/bridge against the landed [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 API while leaving upstream component/domain code substantially unchanged.
• Better Auth UI owns its own Better Auth session/native permissions and exports no Better Auth-to-BTST authorization or identity factories.
• The corrected companion candidate uses the retained Better Auth 1.6.16 database cohort, exact wrapper-facing peer contract, and optional adapter peers; the database fork remains unchanged for v3.
• [v3 stable] Restore the Better Auth UI CLI scaffold and documentation #219 restores the official optional CLI/catalog/docs path with the minimal auth-plus-account default and no generated Better Auth backend/database ownership.
• [v3 stable] Verify exact Better Auth UI override contracts across repositories #170 verifies the cross-repository exact override contract, including the original avatar reproduction and negative type cases.
• [v3 stable docs] Publish the final production migration and verification playbook #175 documents the final [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202 and [v3 auth] Ship one-rule full-stack authorization #180–[v3 auth] Remove RC authorization paths and publish the v3 contract #193 migration rather than stale RC2/legacy authorization/provider shapes.

Generated release gate

The release candidate is not publishable until CI validates what consumers will install, not merely workspace links:

• Pack the exact Stack, codegen, Better Auth UI, and maintained companion artifacts intended for publication.
• Generate fresh Next.js, React Router, and TanStack Router/Start applications through the maintained CLI/template path.
• Exercise the minimal no-Better-Auth fixture and the optional Better Auth UI auth-plus-account fixture.
• Install packed artifacts with both npm and pnpm across the coordinated matrix defined by Add packed npm/pnpm compatibility smoke tests #174.
• Assert peer-clean installation, one compatible Better Auth/Better Call type universe, no mandatory optional adapters, and no undocumented direct pins.
• Type-check and production-build every generated framework fixture.
• Run build, typecheck, lint, knip/unused-export checks, unit tests, docs build, registry generation/checks, init smoke, and three-framework codegen E2E.
• Confirm client bundles contain no server-only request headers, secrets, Better Auth server instances, or server authorization modules.

Live Better Auth/database authentication across three frameworks is not required for this gate. Package/fixture tests establish installability and build correctness; real-project behavior is tested after publication.

Publication and provenance

• Bump release commits to the exact RC3 versions and verify tags match package versions.
• Publish the core GitHub prerelease and Stack/codegen artifacts from the matching tag/ref with npm provenance.
• Publish the Better Auth UI GitHub prerelease and npm artifact from its matching tag/ref.
• Verify all three expected artifacts resolve through next at their exact versions.
• Verify latest remains on @btst/stack@2.12.2, @btst/codegen@0.1.3, and @btst/better-auth-ui@1.2.5 unless a separately approved stable release has occurred before RC3.
• Record exact versions, source commits, workflow runs, npm integrities/shasums, dist-tags, and the machine-readable compatibility cohort on this issue.
• Verify the public tarballs match the artifacts exercised by the generated release gate.

Post-publication real-project handoff

Publication unblocks, but does not wait for:

• better-stack-ai/better-stack-web#37 — incremental RC2-to-RC3 Next.js/Drizzle validation from retained branch validation/btst-v3-rc.2.
• olliethedev/bio-mogging#109 — incremental RC2-to-RC3 Next.js/Prisma validation from its retained RC2 branch.

The user owns both audits. They reuse retained RC2 manifests/evidence, pin the exact public versions, and report substantial findings upstream. A finding may motivate RC4; neither ticket is an RC3 publication prerequisite.

Stable release remains later

• Complete the agreed RC soak period with no unresolved release blockers.
• Bump packages from prerelease to final versions and run the complete release matrix on final commits.
• Merge v3 into main, publish final releases, verify latest, and retire obsolete next tags.
• Close Phase 3: remove legacy dual paths and release v3.0.0 #137 only after stable package installation is verified from the public registry.

Blocked by

• [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202
• better-stack-ai/better-auth-ui#20, specifically its migration/package-preparation work
• [v3 stable] Restore the Better Auth UI CLI scaffold and documentation #219
• [v3 stable] Verify exact Better Auth UI override contracts across repositories #170
• Add packed npm/pnpm compatibility smoke tests #174
• [v3 stable docs] Publish the final production migration and verification playbook #175

Parent

• Phase 3: remove legacy dual paths and release v3.0.0 #137

[olliethedev]

Existing-app / representative v2 upgrade validation complete

External validation project: better-stack-ai/better-stack-web branch validation/btst-v3-rc.1

Full report with the route manifest, raw results, environment record, migration notes, and all 42 stable/RC screenshot pairs: BTST v3 RC real-world validation report

Versions and setup

• Existing Next.js 16.2.1 / React 19.2.1 application at start commit ab843797f969cb4c198f97da595788406335ae8a
• Stable baseline: exact resolved @btst/stack@2.12.2 + @btst/yar@1.2.0
• Candidate: exact @btst/stack@3.0.0-rc.1 + @btst/yar@1.3.0
• Isolated dev containers with Node 22.18.0, pnpm 10.17.1, and an isolated PostgreSQL 16.14 fixture database
• Three separate browser identities: anonymous, regular user, and administrator
• Real Vercel Blob and OpenAI credentials were used; the database and Blob test asset were restored/removed afterward

Result

• All 42 declared application/plugin page targets reached the same final URL, title, and primary heading as stable when captured under each target's intended role.
• 34 screenshot pairs are pixel-identical; six differ only in dev-badge/animation timing; two contain the expected new v3 list-search UI (CMS and Forms).
• No blocking Next.js overlay was captured.
• RC typecheck and optimized production build pass, including 22 static outputs and the fixture blog SSG page. Lint has 0 errors and 10 pre-existing warnings.
• Production public SSG, protected redirects, authenticated CMS SSR, schema compatibility, Blog/CMS/Form writes, comment moderation, Vercel Blob upload/delete, and a real OpenAI streamed response passed.
• The docs-aware chat fails identically on stable and RC because the app injects a 496,278-character corpus into one tool result; this is an app-level context-size problem, not an RC regression.

DX verdict

The v3 better-DX goal is partially achieved. The steady state is materially cleaner: framework router/API/auth wiring is centralized on StackProvider, plugin overrides lose repeated plumbing, and Next API handlers collapse to toNextRouteHandlers(handler). The existing-app upgrade is not release-ready yet because the async request-aware Next page integration, dependency graph, and one comments-auth behavior still require work.

Substantial findings:

• [v3 RC] createNextPage cannot support async request-aware stack clients #162 — createNextPage cannot support async request-aware stack clients
• [v3 RC] Published packages require manual auth alignment and retain incompatible better-call peers #163 — published packages require manual auth alignment and retain incompatible better-call peers
• [v3 RC] CommentThread loses per-thread sign-in return URL #164 — CommentThread loses the per-thread sign-in return URL (confirmed in a production browser: v3 emits only /p/auth/sign-in instead of the post-specific redirectTo=...#comments link)

This supplies evidence for the external-project, exact-RC install, representative-v2 upgrade, production/SSR/routing/auth/comments/plugin-flow, and environment/results items in the Real-world validation checklist. It intentionally does not claim the three fresh generated-project checks; Next.js, React Router, and TanStack Router scaffolds remain separate checklist work. Fixes/PR review and an rc.2 validation round also remain open.

[olliethedev]

RC2 existing-app / representative-v2 validation complete

Retained validation branch: better-stack-ai/better-stack-web@validation/btst-v3-rc.2
Committed evidence: 653b39d
Full report with provenance, route matrix, functional results, DX assessment, and all 42 stable/RC2 screenshot pairs: BTST v3 RC2 real-world validation report

Raw evidence: route results · RC2 screenshots/errors

Candidate

• @btst/stack@3.0.0-rc.2 at tagged commit d5f79b3d927714df24255020170391b66d7c856f
• @btst/better-auth-ui@2.0.0-rc.1 at tagged commit 9cc5586691a7be8fbff50d32c164c282b4f0b088
• @btst/yar@1.3.2, @btst/adapter-drizzle@2.2.3
• Exact Better Auth/Better Call/TanStack/Zod cohort recorded in the report and lockfile
• Exact comparison baseline remains @btst/stack@2.12.2

Result

• All 42 declared app and installed-plugin pages match stable on normalized final URL, title, H1, and overlay state under their intended anonymous/user/admin identities.
• 29 screenshot pairs are decoded-pixel identical; 11 differ only in animation/Next dev indicator; 2 show the intentional CMS/Form list-search enhancement. No product visual regression found.
• Clean frozen install, typecheck, schema push, lint (0 errors / 10 pre-existing warnings), and optimized production build pass; the build generates 22 static outputs.
• Production public SSG, anonymous protected redirect, admin login, and authenticated CMS SSR pass.
• Blog/CMS/Form writes, comment post/reply/edit/like/moderation/read-back, real Vercel Blob upload/delete, simple OpenAI streaming, Better Auth UI profile/avatar/API-key flows, and sampled negative authorization pass.
• Database and remote Blob objects were restored/removed after testing.

RC1 findings

• [v3 RC] createNextPage cannot support async request-aware stack clients #162 fixed: the request-aware async createNextPage factory now replaces the 101-line manual page with a 28-line integration.
• [v3 RC] Published packages require manual auth alignment and retain incompatible better-call peers #163 fixed: the exact published cohort installs without peer conflicts and the app-local CLI is gone.
• [v3 RC] CommentThread loses per-thread sign-in return URL #164 fixed: the per-post sign-in URL again preserves redirectTo=/p/blog/...#comments.

New RC2 findings

• [v3 RC2] CommentThread ignores delete permission and surfaces failed owner action #169 — CommentThread renders owner Delete despite can(..., "delete") denying it; the 403 escapes as an unhandled mutation rejection.
• [v3 stable] Verify exact Better Auth UI override contracts across repositories #170 — official Better Auth UI v3 docs put avatar under account, but the released bridge only reads auth.avatar; the documented configuration type-checks and is silently ignored.

DX verdict

The better-DX purpose is substantially achieved in the migrated steady state. RC2 eliminates the largest RC1 integration workarounds and makes installation deterministic. #169 and #170 remain concrete permission/documentation polish gaps, so the experience is not yet fully frictionless.

This reruns the existing-app/v2-upgrade, production/SSR/routing/auth/comments/representative-plugin criteria against RC2. It still does not claim the separate fresh Next.js, React Router, or TanStack Router generator checks.

[olliethedev]

Additional project RC2 validation is complete: retained branch, full report, commit 545ae2d409e7ec242def2fe2570c21c5be618980.

Verdict: Go. Exact cohort: stack 3.0.0-rc.2, better-auth-ui 2.0.0-rc.1, adapter-prisma 2.2.3, YAR 1.3.2, with exact compatible Better Auth/query companions. Stable was exact stack 2.12.2 + YAR 1.2.0 and its dependency patch is retained.

Highlights: 48/48 normalized page outcomes match; screenshots classify 32 identical / 9 expected improvements / 7 dev-only noise / 0 regressions; browser errors improve from stable 29 to RC2 0. All 69 stable/candidate authorization route-role pairs match at HTTP level; real-browser account/org checks are 23/27 exact plus four expected disabled-org anonymous redirect-target normalizations, with all authenticated outcomes matching. Functional Blog/CMS/Forms/Comments/real Blob/Auth/Prisma/SSR/SSG/ISR/production flows pass. Frozen install, typecheck, lint (0 errors, 10 pre-existing warnings), and optimized build pass. DB/Blob/session cleanup is complete.

No new RC blocker was found. Existing #169 was reproduced (owner Delete UI offered, backend correctly denies 403); this app has production comments disabled and the behavior is not a security bypass. #162, #163, and #164 are verified fixed in this application.