🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(v4-migration): show the migration UI by default on dual write mode (#16316)
Steffen Schmitz4277d90a2fd8
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsxindex 43b9816880..51068191c3 100644--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx@@ -144,7 +144,7 @@ describe("useOrganizationSettingsPages", () => {);});- it("gates the v4 migration link on the v4UpgradeUi flag", () => {+ it("gates the v4 migration link on deployment availability", () => {const { result } = renderHook(() => useOrganizationSettingsPages());expect(diff --git a/web/src/__tests__/server/userAccount.servertest.ts b/web/src/__tests__/server/userAccount.servertest.tsindex 40b14f3b84..02f1f387dc 100644--- a/web/src/__tests__/server/userAccount.servertest.ts+++ b/web/src/__tests__/server/userAccount.servertest.ts@@ -45,29 +45,6 @@ describe("userAccountRouter.setFeaturePreviewEnabled", () => {expect(user.featureFlags).toEqual(["templateFlag", "modernSession"]);});- it("enables the V4 migration UI preview, leaving other flags intact", async () => {- const { caller, userId } = await createCaller({- featureFlags: ["templateFlag"],- });-- const result = await caller.userAccount.setFeaturePreviewEnabled({- flag: "v4UpgradeUi",- enabled: true,- });-- expect(result).toEqual({- success: true,- flag: "v4UpgradeUi",- enabled: true,- });-- const user = await prisma.user.findUniqueOrThrow({- where: { id: userId },- select: { featureFlags: true },- });- expect(user.featureFlags).toEqual(["templateFlag", "v4UpgradeUi"]);- });-it("disables a preview flag without touching the others", async () => {const { caller, userId } = await createCaller({featureFlags: ["templateFlag", "modernSession"],@@ -91,11 +68,11 @@ describe("userAccountRouter.setFeaturePreviewEnabled", () => {expect(user.featureFlags).toEqual(["templateFlag"]);});- it.each(["[email protected]", "[email protected]"])(- "persists an opt-out when %s disables a preview",- async (email) => {+ it.each(["langfuse.com", "clickhouse.com"])(+ "persists an opt-out when a team member on %s disables a preview",+ async (emailDomain) => {const { caller, userId } = await createCaller({- email,+ emailDomain,featureFlags: ["templateFlag"],});@@ -139,13 +116,15 @@ async function createCaller({aiFeaturesEnabled = true,featureFlags = ["templateFlag"],includeProjectInSession = true,- email,+ emailDomain = "example.com",}: {plan?: Plan;aiFeaturesEnabled?: boolean;featureFlags?: string[];includeProjectInSession?: boolean;- email?: string;+ // Domain only — the local part is always unique so reruns against the same+ // database do not trip the users.email unique constraint.+ emailDomain?: string;} = {}) {const id = randomUUID();const orgId = `org-${id}`;@@ -169,7 +148,7 @@ async function createCaller({const user = await prisma.user.create({data: {id: userId,- email: email ?? `${userId}@example.com`,+ email: `${userId}@${emailDomain}`,name: "User Account Test User",featureFlags,},@@ -212,7 +191,6 @@ async function createCaller({modernSession: featureFlags.includes("modernSession"),searchBar: featureFlags.includes("searchBar"),templateFlag: featureFlags.includes("templateFlag"),- v4UpgradeUi: featureFlags.includes("v4UpgradeUi"),excludeClickhouseRead: false,observationEvals: false,v4BetaToggleVisible: false,diff --git a/web/src/components/layouts/app-layout/utils/navigationFilters.ts b/web/src/components/layouts/app-layout/utils/navigationFilters.tsindex 432cbb5414..e40449cfcc 100644--- a/web/src/components/layouts/app-layout/utils/navigationFilters.ts+++ b/web/src/components/layouts/app-layout/utils/navigationFilters.ts@@ -83,12 +83,6 @@ export const filters = {return ctx.session?.user?.canToggleV4 === true ? route : null;}- if (route.featureFlag === "v4UpgradeUi") {- return ctx.session?.user?.featureFlags.v4UpgradeUi === true- ? route- : null;- }-const hasFlag =ctx.enableExperimentalFeatures ||ctx.cloudAdmin ||@@ -177,6 +171,7 @@ export const filters = {projectId: ctx.routerProjectId,isLangfuseCloud: ctx.isLangfuseCloud,v4WriteMode: ctx.session?.environment?.v4WriteMode,+ v4UpgradeUiAvailable: ctx.session?.user?.v4UpgradeUiAvailable === true,})? route: null;diff --git a/web/src/components/layouts/routes.tsx b/web/src/components/layouts/routes.tsxindex 5667437fad..3c0ee3ad42 100644--- a/web/src/components/layouts/routes.tsx+++ b/web/src/components/layouts/routes.tsx@@ -68,6 +68,7 @@ export type Route = {projectId: string | undefined;isLangfuseCloud: boolean;v4WriteMode: undefined | "legacy" | "dual" | "events_only"; // undefined until the session has loaded+ v4UpgradeUiAvailable: boolean; // deployment shows the v4 migration UI (see isV4UpgradeUiAvailable)}) => boolean;group?: RouteGroup; // group this route belongs to (within a section)};@@ -225,8 +226,8 @@ export const ROUTES: Route[] = [title: "Update",pathname: "",section: RouteSection.Secondary,- featureFlag: "v4UpgradeUi",- show: ({ projectId }) => projectId !== undefined,+ show: ({ projectId, v4UpgradeUiAvailable }) =>+ v4UpgradeUiAvailable && projectId !== undefined,menuNode: <V4MigrationNavItem />,},{diff --git a/web/src/features/events/lib/v4Rollout.clienttest.ts b/web/src/features/events/lib/v4Rollout.clienttest.tsindex 81cda4bc38..c4b8caba7f 100644--- a/web/src/features/events/lib/v4Rollout.clienttest.ts+++ b/web/src/features/events/lib/v4Rollout.clienttest.ts@@ -2,7 +2,7 @@import { afterEach, beforeEach, describe, expect, it } from "vitest";-import { canToggleV4 } from "./v4Rollout";+import { canToggleV4, isV4UpgradeUiAvailable } from "./v4Rollout";describe("canToggleV4", () => {const originalRegion = process.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION;@@ -40,3 +40,45 @@ describe("canToggleV4", () => {).toBe(false);});});++describe("isV4UpgradeUiAvailable", () => {+ // dualPreviewAvailable mirrors auth.ts: Cloud always has it, self-hosted only+ // with LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true.+ const availability = (+ isLangfuseCloud: boolean,+ v4WriteMode: "legacy" | "dual" | "events_only",+ allowPreviewOptIn = false,+ ) =>+ isV4UpgradeUiAvailable({+ isLangfuseCloud,+ v4WriteMode,+ dualPreviewAvailable: isLangfuseCloud || allowPreviewOptIn,+ });++ it("is on for Langfuse Cloud on dual and events_only", () => {+ expect(availability(true, "dual")).toBe(true);+ expect(availability(true, "events_only")).toBe(true);+ });++ it("is on for a self-hosted dual deployment that allows the preview opt-in", () => {+ expect(availability(false, "dual", true)).toBe(true);+ });++ it("is off for a self-hosted dual deployment without the preview opt-in", () => {+ // Nobody on the deployment can move onto the v4 read path, so every call to+ // action in the migration UI would be a dead end.+ expect(availability(false, "dual", false)).toBe(false);+ });++ it("is off for a self-hosted events_only deployment", () => {+ // The migration is already over: legacy API routes 404, legacy evaluators+ // are hidden and the legacy analytics integrations are no-ops.+ expect(availability(false, "events_only", true)).toBe(false);+ });++ it("is off on legacy regardless of deployment or opt-in", () => {+ // The events tables the migration surfaces read are not written.+ expect(availability(true, "legacy")).toBe(false);+ expect(availability(false, "legacy", true)).toBe(false);+ });+});diff --git a/web/src/features/events/lib/v4Rollout.ts b/web/src/features/events/lib/v4Rollout.tsindex 82281753e0..1e85b79796 100644--- a/web/src/features/events/lib/v4Rollout.ts+++ b/web/src/features/events/lib/v4Rollout.ts@@ -59,3 +59,50 @@ export function canToggleV4(return !shouldAutoEnableV4(context);}++type V4UpgradeUiAvailabilityContext = {+ isLangfuseCloud: boolean;+ v4WriteMode: "legacy" | "dual" | "events_only";+ // Whether a dual-mode deployment lets anyone read through the v4 events+ // tables: Cloud always does, self-hosted only with+ // LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN=true.+ dualPreviewAvailable: boolean;+};++/**+ * Whether this deployment shows the v4 migration/upgrade UI (sidebar "Action+ * required" pill, the per-project chips and banner on the organization+ * overview, the migration panel and status page) by default.+ *+ * This is a different question from `v4BetaEnabled`: the migration UI guides+ * users through work that is still pending, so it deliberately does not+ * require the user to have opted into v4 reads first — the panel is where that+ * opt-in is offered.+ *+ * - `legacy`: off. The events tables the migration surfaces read are not+ * written, so every readiness check would come back unknown.+ * - `dual`: on, but self-hosted only once the operator set ALLOW_PREVIEW_OPT_IN.+ * Both table sets are written, so there is a real migration to guide — but+ * without the opt-in nobody on the deployment can move onto the v4 read path,+ * which makes every call to action a dead end.+ * - `events_only`: Cloud only. Self-hosted the migration is already over — the+ * legacy public API routes 404, legacy evaluators are hidden and the legacy+ * analytics integrations are no-ops, so nothing is left to act on. On Cloud we+ * keep it so users still get an explanation once the region flips.+ *+ * Per-project exceptions are handled downstream by LANGFUSE_FORCE_V3_EXPERIENCE.+ */+export function isV4UpgradeUiAvailable({+ isLangfuseCloud,+ v4WriteMode,+ dualPreviewAvailable,+}: V4UpgradeUiAvailabilityContext): boolean {+ switch (v4WriteMode) {+ case "legacy":+ return false;+ case "dual":+ return dualPreviewAvailable;+ case "events_only":+ return isLangfuseCloud;+ }+}diff --git a/web/src/features/feature-flags/available-flags.ts b/web/src/features/feature-flags/available-flags.tsindex 6f278c716c..8741544b05 100644--- a/web/src/features/feature-flags/available-flags.ts+++ b/web/src/features/feature-flags/available-flags.ts@@ -7,7 +7,6 @@ export const featurePreviewFlags = [// no longer a per-user Feature Preview opt-in. Kept as dead plumbing for a// safe rollback; drop once the GA rollout is confirmed stable."searchBar",- "v4UpgradeUi","compactTimeline",] as const;@@ -29,10 +28,6 @@ export const isFeaturePreviewAvailable = (return true;}- if (flag === "v4UpgradeUi") {- return true;- }-if (flag === "compactTimeline") {return true;}diff --git a/web/src/features/feature-flags/types.ts b/web/src/features/feature-flags/types.tsindex 567557680a..32c0ab9fa1 100644--- a/web/src/features/feature-flags/types.ts+++ b/web/src/features/feature-flags/types.ts@@ -2,13 +2,9 @@ import { type availableFlags } from "./available-flags";export type Flag = (typeof availableFlags)[number];export type Flags = {- [key in Exclude<- Flag,- "modernSession" | "v4UpgradeUi" | "compactTimeline"- >]: boolean;+ [key in Exclude<Flag, "modernSession" | "compactTimeline">]: boolean;} & {// Optional while older sessions and test fixtures roll across new flags.modernSession?: boolean;- v4UpgradeUi?: boolean;compactTimeline?: boolean;};diff --git a/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx b/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsxindex 7421a144de..9e49d499ca 100644--- a/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx+++ b/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx@@ -20,7 +20,6 @@ type ControlledFeaturePreviewModalProps = {const PREVIEW_LABEL: Record<PreviewFlag, string> = {modernSession: "Compact Session View",searchBar: "Filter Search Bar",- v4UpgradeUi: "V4 Migration",compactTimeline: "Compact Timeline",};@@ -70,11 +69,6 @@ export function ControlledFeaturePreviewModal({onToggle: onToggle("modernSession"),isToggling: setFeaturePreviewEnabled.isPending,},- v4UpgradeUi: {- enabled: authSession.data?.user?.featureFlags.v4UpgradeUi === true,- onToggle: onToggle("v4UpgradeUi"),- isToggling: setFeaturePreviewEnabled.isPending,- },compactTimeline: {enabled:authSession.data?.user?.featureFlags.compactTimeline === true ||diff --git a/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx b/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsxindex 4eb59288e7..fbf43e9ad2 100644--- a/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx+++ b/web/src/features/feature-previews/components/FeaturePreviewModal.stories.tsx@@ -57,7 +57,6 @@ const meta = preview.meta({onOpenChange: fn(),state: {modernSession: { enabled: false, onToggle: fn(), isToggling: false },- v4UpgradeUi: { enabled: false, onToggle: fn(), isToggling: false },},},render: StatefulFeaturePreviewModal,diff --git a/web/src/features/feature-previews/components/FeaturePreviewModal.tsx b/web/src/features/feature-previews/components/FeaturePreviewModal.tsxindex f7f453e872..848360dd42 100644--- a/web/src/features/feature-previews/components/FeaturePreviewModal.tsx+++ b/web/src/features/feature-previews/components/FeaturePreviewModal.tsx@@ -89,23 +89,6 @@ const PREVIEW_REGISTRY: PreviewRegistryItem[] = [alt: "A whole trace as dense coloured lines, one per observation, cascading across a time axis.",},},- {- flag: "v4UpgradeUi",- title: "V4 Migration",- sidebarLabel: "V4 Migration",- description:- "Review each project's readiness for Langfuse v4 and get guided steps for anything that still needs an update.",- details:- "The V4 Migration experience adds a migration status page, project-level readiness indicators, and contextual upgrade guidance for SDKs, evaluators, deprecated APIs, and integrations.",- feedbackUrl: "https://github.com/orgs/langfuse/discussions",- illustration: {- light: "/assets/v4-beta-intro.jpg",- dark: "/assets/v4-beta-intro.jpg",- alt: "Langfuse v4 performance improvements across common observability workflows.",- width: 1024,- height: 598,- },- },// TODO(remove ~2026-06-19): dead registry entry — "searchBar" is GA on the v4// events tables and no longer surfaced in the dialog (no state entry in// ControlledFeaturePreviewModal), so this is filtered out and never renders.diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsxindex 70890ab88e..000c1757fe 100644--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx@@ -1222,6 +1222,22 @@ describe("V4MigrationHeaderContent", () => {).toHaveAttribute("href", "https://langfuse.com/docs/v4#timeline");});+ it("drops the dated deadline for self-hosted deployments", () => {+ // The date is a Cloud commitment: a self-hosted deployment keeps its legacy+ // surfaces until its own operator moves the write mode off dual.+ mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;++ render(<V4MigrationHeaderContent readiness="action-needed" />);++ expect(screen.getByText(/features may stop working/)).toHaveTextContent(+ "Some features may stop working without an upgrade once your administrator disables the legacy mode.",+ );+ expect(screen.queryByText(/November 16, 2026/)).not.toBeInTheDocument();+ expect(+ screen.queryByRole("link", { name: "November 16, 2026" }),+ ).not.toBeInTheDocument();+ });+it("reserves a close-button gutter on the title row when the host asks", () => {// The modal host floats the dialog's fallback close button over the// body's top-right corner; without the gutter it overlaps the title.diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsxindex 572967d785..3a4193de89 100644--- a/web/src/features/v4-migration/V4MigrationContent.tsx+++ b/web/src/features/v4-migration/V4MigrationContent.tsx@@ -11,6 +11,7 @@ import {} from "lucide-react";import { env } from "@/src/env.mjs";import { useIsInAppAgentLauncherVisible } from "@/src/features/in-app-agent/components/InAppAiAgentProvider";+import { useLangfuseCloudRegion } from "@/src/features/organizations/hooks";import { useSupportDrawer } from "@/src/features/support-chat/SupportDrawerProvider";import { Button } from "@/src/components/ui/button";import {@@ -1039,6 +1040,19 @@ export function V4MigrationIntegrationsSection({);}+/**+ * Whether this deployment is bound by the dated v3 sunset.+ *+ * `V4_MIGRATION_DEADLINE` is a Langfuse Cloud commitment. On a self-hosted+ * deployment nothing happens on that date — the legacy surfaces keep working+ * until the operator moves the write mode off `dual`, so quoting a date would+ * be plainly wrong. The Fern deprecation messages scope the same date to Cloud+ * for the same reason (see `deprecations.ts`).+ */+export function useHasV4MigrationDeadline(): boolean {+ return useLangfuseCloudRegion().isLangfuseCloud;+}+// Docs link and deadline note are shared by the panel/modal header and the// account-level status page so both surfaces read the same.export function V4MigrationDocsLink() {@@ -1053,6 +1067,17 @@ export function V4MigrationDocsLink() {}export function V4MigrationDeadlineNote() {+ const hasDeadline = useHasV4MigrationDeadline();++ if (!hasDeadline) {+ return (+ <p>+ Some features may stop working without an upgrade once your+ administrator disables the legacy mode.+ </p>+ );+ }+return (<p>After{" "}diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsxindex e911d68ab4..f0fc01e4c8 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx@@ -25,6 +25,8 @@ const mocks = vi.hoisted(() => ({lastTracePending: false,canToggleV4: true,isBetaEnabled: false,+ // Cloud is bound by the dated v3 sunset; self-hosted is not.+ hasDeadline: true,}));vi.mock("next/router", () => ({@@ -76,6 +78,7 @@ vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({vi.mock("@/src/features/v4-migration/V4MigrationContent", () => ({V4_MIGRATION_DEADLINE: "November 16, 2026",useCopyMigrationPrompt: () => vi.fn(),+ useHasV4MigrationDeadline: () => mocks.hasDeadline,// Stand-ins for the shared sidebar copy: the real components are covered in// V4MigrationContent.clienttest.tsx, here we only assert they are rendered.V4MigrationDocsLink: () => (@@ -161,6 +164,7 @@ describe("V4MigrationStatusPage", () => {mocks.evalCount = 1;mocks.lastTracePending = false;mocks.canToggleV4 = true;+ mocks.hasDeadline = true;mocks.isBetaEnabled = false;});@@ -300,6 +304,36 @@ describe("V4MigrationStatusPage", () => {expect(screen.queryByText(/Oct 9/)).not.toBeInTheDocument();});+ it("replaces the FAQ deadline with the operator cutoff when self-hosted", () => {+ // Nothing happens to a self-hosted deployment on the Cloud sunset date, so+ // the FAQ has to point at the operator's own write-mode switch instead.+ mocks.hasDeadline = false;++ render(<V4MigrationStatusPage />);++ expect(+ screen.getByText("once your administrator disables the legacy mode"),+ ).toBeInTheDocument();+ expect(+ screen.getByText("Once your administrator disables the legacy mode"),+ ).toBeInTheDocument();+ expect(screen.queryByText(/on November 16, 2026/)).not.toBeInTheDocument();+ expect(screen.queryByText(/On November 16, 2026/)).not.toBeInTheDocument();+ });++ it("drops the dated sunset from the switch-back warning when self-hosted", () => {+ mocks.isBetaEnabled = true;+ mocks.hasDeadline = false;++ render(<V4MigrationStatusPage />);++ expect(+ screen.getByText(+ /The features powering the legacy v3 UI will be sunset once your administrator disables the legacy mode\./,+ ),+ ).toBeInTheDocument();+ });+it("only shows the status pill when action is required", () => {mocks.evalCount = 0;mocks.sdk = {diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsxindex 39b0deb0d8..259440d935 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx@@ -15,6 +15,7 @@ import {} from "@/src/components/ui/table";import {useCopyMigrationPrompt,+ useHasV4MigrationDeadline,V4MigrationDeadlineNote,V4MigrationDocsLink,V4_MIGRATION_DEADLINE,@@ -474,6 +475,7 @@ export default function V4MigrationStatusPage() {function V4MigrationStatusPageContent() {const session = useSession();const handleCopyPrompt = useCopyMigrationPrompt();+ const hasDeadline = useHasV4MigrationDeadline();const orgs: V4MigrationOrganization[] =session.data?.user?.organizations?.map((org) => ({@@ -532,8 +534,13 @@ function V4MigrationStatusPageContent() {Yes, eventually. The{" "}<FaqLink href={SDK_UPGRADE_URL}>old SDKs</FaqLink>, trace-level evals,and APIs are frozen and stop working{" "}- <span className="underline">on {V4_MIGRATION_DEADLINE}</span>. They- keep running until then, but we're no longer fixing bugs in them.+ <span className="underline">+ {hasDeadline+ ? `on ${V4_MIGRATION_DEADLINE}`+ : "once your administrator disables the legacy mode"}+ </span>+ . They keep running until then, but we're no longer fixing bugs+ in them.</>),},@@ -558,8 +565,12 @@ function V4MigrationStatusPageContent() {q: "What if I do nothing?",a: (<>- <span className="underline">On {V4_MIGRATION_DEADLINE}</span>, old- SDKs stop sending data, and the{" "}+ <span className="underline">+ {hasDeadline+ ? `On ${V4_MIGRATION_DEADLINE}`+ : "Once your administrator disables the legacy mode"}+ </span>+ , old SDKs stop sending data, and the{" "}<FaqLink href={API_REFERENCE_URL}>deprecated evals and endpoints</FaqLink>{" "}@@ -690,6 +701,7 @@ function V4MigrationStatusPageContent() {// mode, post-rollout auto-enrollment).function SwitchBackSection() {const { canToggleV4, isBetaEnabled } = useV4Beta();+ const hasDeadline = useHasV4MigrationDeadline();if (!canToggleV4) {return null;@@ -705,9 +717,11 @@ function SwitchBackSection() {<div className="flex flex-col gap-4 pt-4">{isBetaEnabled && (<p className="text-muted-foreground text-sm leading-relaxed">- The features powering the legacy v3 UI will be sunset on{" "}- {V4_MIGRATION_DEADLINE}. We strongly recommend switching to the- latest UI (v4) before then.+ The features powering the legacy v3 UI will be sunset{" "}+ {hasDeadline+ ? `on ${V4_MIGRATION_DEADLINE}`+ : "once your administrator disables the legacy mode"}+ . We strongly recommend switching to the latest UI (v4) before then.</p>)}<V4PreviewToggleRow />diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.tsindex 9919e0b0a0..4a2ea8a4cf 100644--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts@@ -4,7 +4,6 @@ import { vi } from "vitest";import { useV4UpgradeUiEnabled } from "./useV4UpgradeUiEnabled";import { useForceV3Experience } from "./useForceV3Experience";-import { parseFlags } from "@/src/features/feature-flags/utils";vi.mock("next-auth/react", () => ({useSession: vi.fn(),@@ -17,13 +16,10 @@ vi.mock("./useForceV3Experience", () => ({const mockUseSession = vi.mocked(useSession);const mockUseForceV3Experience = vi.mocked(useForceV3Experience);-const mockSessionFlag = (v4UpgradeUi: boolean) => {+const mockSessionAvailability = (v4UpgradeUiAvailable: boolean) => {mockUseSession.mockReturnValue({data: {- user: {- admin: false,- featureFlags: { v4UpgradeUi },- },+ user: { admin: false, featureFlags: {}, v4UpgradeUiAvailable },environment: { enableExperimentalFeatures: false },},} as never);@@ -34,19 +30,26 @@ describe("useV4UpgradeUiEnabled", () => {mockUseForceV3Experience.mockReturnValue(false);});- it("maps the database flag into the session flag shape", () => {- const context = { email: undefined, v4BetaEnabled: false };- expect(parseFlags(["v4UpgradeUi"], context).v4UpgradeUi).toBe(true);- expect(parseFlags([], context).v4UpgradeUi).toBe(false);+ it("enables the UI when the deployment can act on the migration", () => {+ mockSessionAvailability(true);++ const { result } = renderHook(() => useV4UpgradeUiEnabled());++ expect(result.current).toBe(true);+ });++ it("stays disabled when the deployment cannot act on the migration", () => {+ mockSessionAvailability(false);++ const { result } = renderHook(() => useV4UpgradeUiEnabled());++ expect(result.current).toBe(false);});it("does not enable the UI for admins or experimental deployments", () => {mockUseSession.mockReturnValue({data: {- user: {- admin: true,- featureFlags: { v4UpgradeUi: false },- },+ user: { admin: true, featureFlags: {}, v4UpgradeUiAvailable: false },environment: { enableExperimentalFeatures: true },},} as never);@@ -56,29 +59,27 @@ describe("useV4UpgradeUiEnabled", () => {expect(result.current).toBe(false);});- it("enables the UI only when the user flag is set", () => {- mockSessionFlag(true);+ it("treats a session without the field as unavailable", () => {+ // Older sessions and test fixtures predate the field; default to off rather+ // than showing migration surfaces a deployment may not support.+ mockUseSession.mockReturnValue({+ data: {+ user: { admin: false, featureFlags: {} },+ environment: { enableExperimentalFeatures: false },+ },+ } as never);const { result } = renderHook(() => useV4UpgradeUiEnabled());- expect(result.current).toBe(true);+ expect(result.current).toBe(false);});it("suppresses the UI for projects forced onto the v3 experience", () => {- mockSessionFlag(true);+ mockSessionAvailability(true);mockUseForceV3Experience.mockReturnValue(true);const { result } = renderHook(() => useV4UpgradeUiEnabled());expect(result.current).toBe(false);});-- it("stays disabled when the flag is off regardless of force-v3", () => {- mockSessionFlag(false);- mockUseForceV3Experience.mockReturnValue(false);-- const { result } = renderHook(() => useV4UpgradeUiEnabled());-- expect(result.current).toBe(false);- });});diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.tsindex db114a64e3..ec0c07f419 100644--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts@@ -3,12 +3,14 @@ import { useSession } from "next-auth/react";import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";/**- * Raw `v4UpgradeUi` feature-preview flag, without the force-v3 suppression.+ * Whether this deployment shows the v4 migration UI at all, before the+ * per-project force-v3 suppression. Derived from the write mode once in the+ * auth session callback — see isV4UpgradeUiAvailable.*/export function useV4UpgradeUiFlag(): boolean {const { data: session } = useSession();- return session?.user?.featureFlags.v4UpgradeUi === true;+ return session?.user?.v4UpgradeUiAvailable === true;}/**@@ -19,7 +21,7 @@ export function useV4UpgradeUiFlag(): boolean {* when the migration UI is off.*/export function useV4UpgradeUiEnabled(projectId?: string): boolean {- const flag = useV4UpgradeUiFlag();+ const available = useV4UpgradeUiFlag();const forceV3 = useForceV3Experience(projectId);- return flag && !forceV3;+ return available && !forceV3;}diff --git a/web/src/server/auth.ts b/web/src/server/auth.tsindex a12e5cd5ab..93c3e2cdd2 100644--- a/web/src/server/auth.ts+++ b/web/src/server/auth.ts@@ -71,7 +71,10 @@ import {} from "@/src/features/entitlements/server/getPlan";import { getSSOBlockedDomains } from "@/src/features/auth-credentials/server/signupApiHandler";import { createSupportEmailHash } from "@/src/features/support-chat/createSupportEmailHash";-import { canToggleV4 } from "@/src/features/events/lib/v4Rollout";+import {+ canToggleV4,+ isV4UpgradeUiAvailable,+} from "@/src/features/events/lib/v4Rollout";import { canCreateOrganizations } from "@/src/features/organizations/server/canCreateOrganizations";const staticProviders: Provider[] = [@@ -875,6 +878,15 @@ export async function getAuthOptions(signupAttribution?: {(v4WriteMode === "dual" &&dualPreviewAvailable &&dbUser?.v4BetaEnabled === true);+ // The migration/upgrade UI is a separate question from the preview+ // read path above: it guides users through work that is still+ // pending, so it does not require the user to have opted into v4+ // reads first — the migration panel is where that opt-in is offered.+ const v4UpgradeUiAvailable = isV4UpgradeUiAvailable({+ isLangfuseCloud,+ v4WriteMode,+ dualPreviewAvailable,+ });return {...session,@@ -900,6 +912,7 @@ export async function getAuthOptions(signupAttribution?: {image: dbUser.image,admin: dbUser.admin,v4BetaEnabled,+ v4UpgradeUiAvailable,canToggleV4:v4WriteMode === "dual" && dualPreviewAvailable? isLangfuseClouddiff --git a/web/types/next-auth.d.ts b/web/types/next-auth.d.tsindex fca450e8ab..bdb0310791 100644--- a/web/types/next-auth.d.ts+++ b/web/types/next-auth.d.ts@@ -26,6 +26,12 @@ declare module "next-auth" {admin?: PrismaUser["admin"];v4BetaEnabled?: boolean;canToggleV4?: boolean;+ // Whether this deployment shows the v4 migration UI (sidebar pill,+ // organization-overview chips and banner, panel, status page). Derived+ // from the write mode in the session callback — see+ // isV4UpgradeUiAvailable. This is the gate every migration surface+ // reads, via useV4UpgradeUiEnabled; there is no per-user opt-in.+ v4UpgradeUiAvailable?: boolean;emailVerified?: string | null; // iso datetime string, need to stringify as JWT & useSession do not support Date objectscanCreateOrganizations: boolean; // default true, allowlist can be set via LANGFUSE_ALLOWED_ORGANIZATION_CREATORSorganizations: {