Merge branch 'w1-inf-05-electric-removal-realtime-client-backend-collapse' into integration-batch-01

Author: d-cs

.server-changes/realtime-native-only.md

@@ -0,0 +1,10 @@
+---
+area: webapp
+type: improvement
+---
+
+Collapse the realtime run feed to the native backend only and remove the Electric-SQL HTTP proxy path. `resolveRealtimeStreamClient` now returns the native realtime client unconditionally, so the per-org `realtimeBackend` flag, the `REALTIME_BACKEND_NATIVE_ENABLED` master switch, and the shadow-compare scaffolding are no longer consulted for serving runs. The Electric proxy `RealtimeClient` class, its singleton, the shadow client/comparator, and the orphaned Electric-proxy integration test are removed. The run-feed path no longer constructs Electric shape URLs or reads `ELECTRIC_ORIGIN`, so native realtime is not pinned to the soon-abandoned RDS DB via Electric shapes. Applies to self-host too: with the Electric proxy gone, self-host now serves runs over native realtime unconditionally.
+
+The native wire serializer (`electricStreamProtocol.server.ts`) is retained — it emits the wire format the SDK realtime client speaks and is still used by the native client. The dashboard trace-sync routes (`sync.traces.*`) still use `ELECTRIC_ORIGIN` and are out of scope for this change, so the Electric container cannot be fully decommissioned by this change alone.
+
+Note: the production shadow-compare divergence sign-off ("shadowCompare diff clean before deletion") is an operational gate handled separately from this code change.

apps/webapp/CLAUDE.md

@@ -75,8 +75,8 @@ const signal = getRequestAbortSignal();
 Access via `env` export from `app/env.server.ts`. **Never use `process.env` directly.**
 
 For testable code, **never import env.server.ts** in test files. Pass configuration as options instead:
-- `realtimeClient.server.ts` (testable service, takes config as constructor arg)
-- `realtimeClientGlobal.server.ts` (creates singleton with env config)
+- `realtime/nativeRealtimeClient.server.ts` (testable service, takes config as constructor arg)
+- `realtime/nativeRealtimeClientInstance.server.ts` (creates singleton with env config)
 
 ## Run Engine 2.0
 

apps/webapp/app/routes/realtime.v1.batches.$batchId.ts

@@ -29,7 +29,7 @@ export const loader = createLoaderApiRoute(
     },
   },
   async ({ authentication, request, resource: batchRun, apiVersion }) => {
-    // Pick the Electric proxy or the native backend per org (defaults to Electric); both implement streamBatch.
+    // Resolve the native realtime client; it implements streamBatch.
     const client = await resolveRealtimeStreamClient(authentication.environment);
 
     return client.streamBatch(

apps/webapp/app/routes/realtime.v1.runs.$runId.ts

@@ -49,7 +49,7 @@ export const loader = createLoaderApiRoute(
     },
   },
   async ({ authentication, request, resource: run, apiVersion }) => {
-    // Pick the Electric proxy or the native backend per org (defaults to Electric); both implement streamRun.
+    // Resolve the native realtime client; it implements streamRun.
     const client = await resolveRealtimeStreamClient(authentication.environment);
 
     return client.streamRun(

apps/webapp/app/routes/realtime.v1.runs.ts

@@ -31,7 +31,7 @@ export const loader = createLoaderApiRoute(
     },
   },
   async ({ searchParams, authentication, request, apiVersion }) => {
-    // Pick the Electric proxy or the native backend per org (defaults to Electric); both implement streamRuns.
+    // Resolve the native realtime client; it implements streamRuns.
     const client = await resolveRealtimeStreamClient(authentication.environment);
 
     return client.streamRuns(

apps/webapp/app/services/realtime/electricStreamProtocol.server.ts

@@ -1,6 +1,7 @@
 /**
- * Pure (no DB/Redis/env) Electric HTTP shape-stream wire serializer, byte-faithful to what the
- * deployed `@electric-sql/client` (1.0.14 + 0.4.0) and the SDK's `SubscribeRunRawShape` expect.
+ * Pure (no DB/Redis/env) native realtime wire serializer. It emits the shape-stream wire format the
+ * SDK's realtime client speaks, byte-faithful to what the deployed `@electric-sql/client` (1.0.14 + 0.4.0)
+ * and the SDK's `SubscribeRunRawShape` expect.
  * Each column value is wire-encoded as a string (or null) decoded via the `electric-schema` header;
  * `up-to-date` is the only control message that makes the client emit, and re-sending a full row is idempotent.
  */

apps/webapp/app/services/realtime/resolveRealtimeStreamClient.server.ts

@@ -1,93 +1,12 @@
-import { $replica } from "~/db.server";
-import { env } from "~/env.server";
-import { singleton } from "~/utils/singleton";
-import { FEATURE_FLAG } from "~/v3/featureFlags";
-import { makeFlag } from "~/v3/featureFlags.server";
-import { logger } from "../logger.server";
 import { type RealtimeEnvironment } from "../realtimeClient.server";
-import { realtimeClient } from "../realtimeClientGlobal.server";
-import { BoundedTtlCache } from "./boundedTtlCache";
 import { type RealtimeStreamClient } from "./nativeRealtimeClient.server";
 import { getNativeRealtimeClient } from "./nativeRealtimeClientInstance.server";
-import { getShadowRealtimeClient } from "./shadowRealtimeClientInstance.server";
-
-type RealtimeBackend = "electric" | "native" | "shadow";
-
-// Two gates, both defaulting to the Electric path: the env master switch, then the
-// per-org `realtimeBackend` feature flag (cached so long-polls don't hit the DB per request).
-const nativeBackendEnabled = env.REALTIME_BACKEND_NATIVE_ENABLED === "1";
-
-const flag = singleton("realtimeBackendFlag", () => makeFlag($replica));
-const backendCache = singleton(
-  "realtimeBackendCache",
-  () =>
-    new BoundedTtlCache<RealtimeBackend>(
-      env.REALTIME_BACKEND_FLAG_CACHE_TTL_MS,
-      env.REALTIME_BACKEND_FLAG_CACHE_MAX_ENTRIES
-    )
-);
 
+// The realtime run feed is served exclusively by the native backend; there is no longer
+// an Electric proxy path or per-org backend selection. The signature is kept async (and
+// still accepts the authenticated environment) so the run routes don't have to change.
 export async function resolveRealtimeStreamClient(
   environment: RealtimeEnvironment & { organization?: { featureFlags?: unknown } }
 ): Promise<RealtimeStreamClient> {
-  if (!nativeBackendEnabled) {
-    return realtimeClient;
-  }
-
-  // The authenticated environment already carries the org's feature flags; pass them
-  // through so a cache miss doesn't need an extra organization read.
-  const orgFeatureFlags = environment.organization
-    ? (environment.organization.featureFlags ?? {})
-    : undefined;
-
-  switch (await getRealtimeBackend(environment.organizationId, orgFeatureFlags)) {
-    case "native":
-      return getNativeRealtimeClient();
-    case "shadow":
-      // The client is still served Electric; the native path is diffed in the background.
-      return getShadowRealtimeClient();
-    case "electric":
-    default:
-      return realtimeClient;
-  }
-}
-
-async function getRealtimeBackend(
-  organizationId: string,
-  orgFeatureFlags: unknown | undefined
-): Promise<RealtimeBackend> {
-  const cached = backendCache.get(organizationId);
-  if (cached !== undefined) {
-    return cached;
-  }
-
-  let backend: RealtimeBackend = "electric";
-
-  try {
-    const overrides =
-      orgFeatureFlags !== undefined
-        ? orgFeatureFlags
-        : (
-            await $replica.organization.findFirst({
-              where: { id: organizationId },
-              select: { featureFlags: true },
-            })
-          )?.featureFlags;
-
-    backend = await flag({
-      key: FEATURE_FLAG.realtimeBackend,
-      defaultValue: "electric",
-      overrides: (overrides as Record<string, unknown>) ?? {},
-    });
-  } catch (error) {
-    // Never let a flag lookup failure break the realtime feed.
-    logger.error("[resolveRealtimeStreamClient] failed to resolve realtimeBackend flag", {
-      organizationId,
-      error,
-    });
-    backend = "electric";
-  }
-
-  backendCache.set(organizationId, backend);
-  return backend;
+  return getNativeRealtimeClient();
 }