fix(run-ops split): interlock split mode against native realtime backend

Enabling RUN_OPS_SPLIT_ENABLED without REALTIME_BACKEND_NATIVE_ENABLED
silently breaks realtime: Electric replicates only from the control-plane
DB, so NEW-resident (ksuid) runs on the dedicated run-ops DB are invisible
and every realtime subscription hangs.

Add a boot-time interlock that refuses split mode in that misconfiguration,
mirroring the existing distinct-DB data-loss sentinel. The check is a pure
predicate (assertSplitRealtimeInterlock) run synchronously inside
assertRunOpsSplitSentinel on the same eager-boot path, failing fast before
the async DB probe and before any run-ops routing is wired.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: d-cs

.server-changes/run-ops-split-realtime-interlock.md

@@ -0,0 +1,12 @@
+---
+area: webapp
+type: fix
+---
+
+Add a boot-time interlock that refuses to enable the run-ops DB split
+(`RUN_OPS_SPLIT_ENABLED`) unless the native realtime backend
+(`REALTIME_BACKEND_NATIVE_ENABLED`) is also on. Electric replicates only from the
+control-plane database, so enabling the split without the native backend would
+leave NEW-resident (ksuid) runs invisible to realtime and hang every
+subscription. The check runs synchronously on the same eager-boot path as the
+existing distinct-DB sentinel and fails fast before any run-ops routing is wired.

apps/webapp/app/db.server.ts

@@ -19,7 +19,10 @@ import {
   logTransactionInfrastructureError,
 } from "./utils/prismaErrors";
 import { singleton } from "./utils/singleton";
-import { isSplitEnabled } from "./v3/runOpsMigration/splitMode.server";
+import {
+  isSplitEnabled,
+  assertSplitRealtimeInterlock,
+} from "./v3/runOpsMigration/splitMode.server";
 import { computeRunOpsSplitReadEnabled } from "./v3/runOpsMigration/runOpsSplitReadGate";
 import { DATASOURCE_CONTEXT_KEY, startActiveSpan } from "./v3/tracer.server";
 import { context, Span, trace } from "@opentelemetry/api";
@@ -283,6 +286,13 @@ export const runOpsSplitReadEnabled: boolean = computeRunOpsSplitReadEnabled({
 // call it from the eager-boot path before any run-ops routing is wired.
 export async function assertRunOpsSplitSentinel(): Promise<void> {
   if (!env.RUN_OPS_SPLIT_ENABLED) return;
+  // Realtime interlock (synchronous): Electric replicates only from the control-plane
+  // DB, so split-on without the native realtime backend leaves NEW-resident runs
+  // invisible and hangs every subscription. Fail fast before the async DB probe.
+  assertSplitRealtimeInterlock({
+    splitEnabled: env.RUN_OPS_SPLIT_ENABLED,
+    nativeRealtimeEnabled: env.REALTIME_BACKEND_NATIVE_ENABLED === "1",
+  });
   const ok = await isSplitEnabled();
   if (!ok) {
     throw new Error(

apps/webapp/app/v3/runOpsMigration/splitMode.server.ts

@@ -40,6 +40,29 @@ export async function computeSplitEnabled(
   return result.distinct === true;
 }
 
+export type SplitRealtimeInterlockConfig = {
+  splitEnabled: boolean;
+  nativeRealtimeEnabled: boolean;
+};
+
+/**
+ * Boot-time realtime interlock (pure predicate). Split mode puts NEW-resident
+ * (ksuid) runs on the dedicated run-ops DB, but Electric replicates only from the
+ * control-plane DB — with the native realtime backend OFF those runs are invisible
+ * and every realtime subscription hangs. Refuse split unless native is on; split-off
+ * is always allowed regardless of the realtime backend.
+ */
+export function assertSplitRealtimeInterlock(config: SplitRealtimeInterlockConfig): void {
+  if (!config.splitEnabled) {
+    return;
+  }
+  if (!config.nativeRealtimeEnabled) {
+    throw new Error(
+      "RUN_OPS_SPLIT_ENABLED is on but the native realtime backend (REALTIME_BACKEND_NATIVE_ENABLED) is not enabled — Electric cannot serve NEW-resident runs; refusing to enable split."
+    );
+  }
+}
+
 let cached: Promise<boolean> | undefined;
 
 export function isSplitEnabled(): Promise<boolean> {

apps/webapp/test/runOpsSplitMode.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, it, vi } from "vitest";
 // @testcontainers/postgresql resolves because it is declared in apps/webapp/package.json.
 import { PostgreSqlContainer } from "@testcontainers/postgresql";
-import { computeSplitEnabled } from "~/v3/runOpsMigration/splitMode.server";
+import {
+  computeSplitEnabled,
+  assertSplitRealtimeInterlock,
+} from "~/v3/runOpsMigration/splitMode.server";
 import { probeDistinctDatabases } from "~/v3/runOpsMigration/distinctDbSentinel.server";
 
 describe("computeSplitEnabled (pure)", () => {
@@ -58,6 +61,29 @@ describe("computeSplitEnabled (pure)", () => {
   });
 });
 
+describe("assertSplitRealtimeInterlock (pure)", () => {
+  it("throws when split is on but the native realtime backend is off", () => {
+    expect(() =>
+      assertSplitRealtimeInterlock({ splitEnabled: true, nativeRealtimeEnabled: false })
+    ).toThrowError(/native realtime backend|REALTIME_BACKEND_NATIVE_ENABLED/i);
+  });
+
+  it("does not throw when split is on and the native realtime backend is on", () => {
+    expect(() =>
+      assertSplitRealtimeInterlock({ splitEnabled: true, nativeRealtimeEnabled: true })
+    ).not.toThrow();
+  });
+
+  it("does not throw when split is off, regardless of the native realtime backend", () => {
+    expect(() =>
+      assertSplitRealtimeInterlock({ splitEnabled: false, nativeRealtimeEnabled: false })
+    ).not.toThrow();
+    expect(() =>
+      assertSplitRealtimeInterlock({ splitEnabled: false, nativeRealtimeEnabled: true })
+    ).not.toThrow();
+  });
+});
+
 describe("distinct-DB sentinel (real Postgres)", () => {
   it("reports NOT distinct when both URLs hit the same physical cluster", async () => {
     const pg = await new PostgreSqlContainer("docker.io/postgres:14").start();