perf(webapp): keep the snapshot store inert until a Redis host is configured

With no snapshot-store Redis host set, the feature must add zero standing
cost. Two paths did not honour that:

- The org census started its periodic organization.findMany poll at import,
  gated only on NODE_ENV, so a production process with no host still polled
  the replica every reload interval. Gate the poll on a host check that is
  independent of NODE_ENV.
- The run store wired the redis-only Postgres-suppression predicate into
  every PostgresRunStore unconditionally, so every snapshot write ran a mode
  resolution (and a background per-org replica read on a cold cache). Thread
  the predicate through buildRunStore and wire it only when configured; unset
  leaves the store a plain passthrough that writes every snapshot row.

Both now route through a single isSnapshotStoreConfigured gate.

Author: d-cs

apps/webapp/app/v3/runStore.server.ts

@@ -20,6 +20,7 @@ import {
 } from "~/db.server";
 import { env } from "~/env.server";
 import { singleton } from "~/utils/singleton";
+import { isSnapshotStoreConfigured } from "./snapshotStoreConfigured.server";
 import { decorateWithSnapshotStore } from "./snapshotStoreInstance.server";
 import { snapshotStoreModeResolver } from "./snapshotStoreMode.server";
 import {
@@ -55,15 +56,20 @@ type BuildRunStoreDeps = {
   singleResilience?: TransactionResilienceConfig;
   newResilience?: TransactionResilienceConfig;
   legacyResilience?: TransactionResilienceConfig;
+  /** The redis-only PG-suppression predicate, or undefined for a plain passthrough. Passed in (never
+   * read from env here) so this builder stays pure; the caller wires it only when the store is
+   * configured, so an unconfigured deploy writes every snapshot row with no per-write resolution. */
+  snapshotWrites?: (organizationId?: string) => boolean;
 };
 
 /**
  * Pure run-store builder (no env / no boot side effects — webapp testability rule).
  *
  * Split OFF (default / self-host): returns the exact passthrough PostgresRunStore we
  * have always returned, built from the single control-plane handles. No second store
- * is constructed and no marker predicate is consulted, so behavior is byte-identical
- * to single-DB today.
+ * is constructed, and the redis-only marker predicate is consulted only when the caller
+ * wired one (i.e. the snapshot store is configured); with it unset behavior is
+ * byte-identical to single-DB today.
  *
  * Split ON: returns a RoutingRunStore that selects between a NEW store (where new runs
  * are born) and a LEGACY store (draining) by run-id residency (id shape). There is no cuid
@@ -74,14 +80,18 @@ type BuildRunStoreDeps = {
 const suppressPgAtRedisOnly = (organizationId?: string) =>
   snapshotStoreModeResolver.resolve(organizationId) !== "redis-only";
 
+// Wired into the store only when the snapshot store is configured. Unconfigured, this stays undefined
+// and PostgresRunStore writes every snapshot row with no per-write mode resolution (the inert state).
+const snapshotWritesPredicate = isSnapshotStoreConfigured() ? suppressPgAtRedisOnly : undefined;
+
 export function buildRunStore(deps: BuildRunStoreDeps): RunStore {
   if (!deps.splitEnabled) {
     return new PostgresRunStore({
       prisma: deps.singleWriter,
       readOnlyPrisma: deps.singleReplica,
       maxWait: deps.singleResilience?.maxWait,
       transactionStartRetry: deps.singleResilience?.startRetry,
-      snapshotWrites: suppressPgAtRedisOnly,
+      snapshotWrites: deps.snapshotWrites,
     });
   }
 
@@ -97,14 +107,14 @@ export function buildRunStore(deps: BuildRunStoreDeps): RunStore {
     schemaVariant: "dedicated",
     maxWait: deps.newResilience?.maxWait,
     transactionStartRetry: deps.newResilience?.startRetry,
-    snapshotWrites: suppressPgAtRedisOnly,
+    snapshotWrites: deps.snapshotWrites,
   });
   const legacyStore = new PostgresRunStore({
     prisma: deps.legacyWriter,
     readOnlyPrisma: deps.legacyReplica,
     maxWait: deps.legacyResilience?.maxWait,
     transactionStartRetry: deps.legacyResilience?.startRetry,
-    snapshotWrites: suppressPgAtRedisOnly,
+    snapshotWrites: deps.snapshotWrites,
   });
 
   // Gen-2 shards: one dedicated store per descriptor, handed to the N-way router. An aliased shard
@@ -118,7 +128,7 @@ export function buildRunStore(deps: BuildRunStoreDeps): RunStore {
       schemaVariant: "dedicated" as const,
       maxWait: shard.resilience?.maxWait,
       transactionStartRetry: shard.resilience?.startRetry,
-      snapshotWrites: suppressPgAtRedisOnly,
+      snapshotWrites: deps.snapshotWrites,
     }),
     aliasOf: shard.aliasOf,
   }));
@@ -198,6 +208,7 @@ export const runStoreWithoutSnapshotDecorator: RunStore = singleton("RunStore.un
       singleWriter: prisma,
       singleReplica: $replica,
       singleResilience: resilienceForClient(prisma),
+      snapshotWrites: snapshotWritesPredicate,
     });
   }
   const { shardHandles, ...storeHandles } = handles;
@@ -216,6 +227,7 @@ export const runStoreWithoutSnapshotDecorator: RunStore = singleton("RunStore.un
     singleResilience: resilienceForClient(prisma),
     newResilience: resilienceForClient(handles.newWriter),
     legacyResilience: resilienceForClient(handles.legacyWriter),
+    snapshotWrites: snapshotWritesPredicate,
   });
 });
 

apps/webapp/app/v3/snapshotStoreConfigured.server.ts

@@ -0,0 +1,13 @@
+import { env } from "~/env.server";
+
+/**
+ * The single bootstrap switch for the snapshot store. With no Redis host configured the feature is
+ * inert: the org census does not poll, the run store is a plain Postgres passthrough with no per-write
+ * mode resolution, and no decorator is attached. Every optional piece gates on this one predicate so
+ * that merging the feature with the host unset adds zero standing cost.
+ */
+export function isSnapshotStoreConfigured(
+  host: string | undefined = env.RUN_ENGINE_SNAPSHOT_STORE_REDIS_HOST ?? undefined
+): boolean {
+  return !!host;
+}

apps/webapp/app/v3/snapshotStoreInstance.server.ts

@@ -13,6 +13,7 @@ import { env } from "~/env.server";
 import { logger } from "~/services/logger.server";
 import { singleton } from "~/utils/singleton";
 import { getSnapshotRepairEnqueuer } from "./snapshotStoreBindings.server";
+import { isSnapshotStoreConfigured } from "./snapshotStoreConfigured.server";
 import { snapshotStoreHalted, snapshotStoreModeResolver } from "./snapshotStoreMode.server";
 import { createSnapshotStoreMetrics } from "./snapshotStoreMetrics.server";
 import { snapshotStoreOrgCensus } from "./snapshotStoreOrgCensus.server";
@@ -21,7 +22,7 @@ import { meter } from "./tracer.server";
 const KEY_PREFIX = "engine:";
 
 function isConfigured(): boolean {
-  return !!env.RUN_ENGINE_SNAPSHOT_STORE_REDIS_HOST;
+  return isSnapshotStoreConfigured();
 }
 
 function redisOptions(): RedisOptions {

apps/webapp/app/v3/snapshotStoreOrgCensus.server.ts

@@ -4,6 +4,7 @@ import { env } from "~/env.server";
 import { createReloadingRegistry } from "~/utils/reloadingRegistry.server";
 import { singleton } from "~/utils/singleton";
 import { FEATURE_FLAG } from "~/v3/featureFlags";
+import { isSnapshotStoreConfigured } from "~/v3/snapshotStoreConfigured.server";
 import { cachedOrgModeFor, NO_OVERRIDE } from "~/v3/snapshotStoreMode.server";
 
 /** The narrow slice of Prisma the census reads, so a test injects a fake without a mocking library. */
@@ -58,6 +59,18 @@ function classify(rows: Array<{ id: string; featureFlags: unknown }>): OrgCensus
   return { readEnabled, redisOnly, cohort, everEnabled };
 }
 
+/**
+ * The census poll runs only when the store is configured AND we are outside test. The host gate is
+ * independent of NODE_ENV so a production process with no Redis host never starts the poll: the
+ * merged-but-off deploy pays no standing organization.findMany.
+ */
+export function defaultCensusAutoStart(
+  host: string | undefined = env.RUN_ENGINE_SNAPSHOT_STORE_REDIS_HOST ?? undefined,
+  nodeEnv: string | undefined = process.env.NODE_ENV
+): boolean {
+  return isSnapshotStoreConfigured(host) && nodeEnv !== "test";
+}
+
 export function createSnapshotStoreOrgCensus(
   clients?: { replica: SnapshotStoreOrgCensusClient },
   opts?: { intervalMs?: number; autoStart?: boolean }
@@ -66,7 +79,7 @@ export function createSnapshotStoreOrgCensus(
   const registry = createReloadingRegistry<OrgCensusSnapshot>({
     name: "snapshot-store-org-census",
     intervalMs: opts?.intervalMs ?? env.GLOBAL_FLAGS_RELOAD_INTERVAL_MS,
-    autoStart: opts?.autoStart ?? process.env.NODE_ENV !== "test",
+    autoStart: opts?.autoStart ?? defaultCensusAutoStart(),
     load: async () =>
       // WHERE returns orgs with EITHER key, so an ever-enabled org that is now off (or holds only
       // the latch after a clear) still returns. Classification stays in code, identical to the resolver.
@@ -116,7 +129,10 @@ export function createSnapshotStoreOrgCensus(
   };
 }
 
-/** Built at import, like globalFlagsRegistry: reads the DB-backed census on GLOBAL_FLAGS_RELOAD_INTERVAL_MS. */
+/**
+ * Built at import, like globalFlagsRegistry, but the poll starts only when a Redis host is configured
+ * (see defaultCensusAutoStart). Unconfigured, the object is inert: constructed, never polling.
+ */
 export const snapshotStoreOrgCensus = singleton("snapshotStoreOrgCensus", () =>
   createSnapshotStoreOrgCensus()
 );

apps/webapp/test/snapshotStoreConfigured.server.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { isSnapshotStoreConfigured } from "~/v3/snapshotStoreConfigured.server";
+
+describe("isSnapshotStoreConfigured", () => {
+  it("is false when no Redis host is set (feature merged but inert)", () => {
+    expect(isSnapshotStoreConfigured(undefined)).toBe(false);
+    expect(isSnapshotStoreConfigured("")).toBe(false);
+  });
+
+  it("is true once a Redis host is set", () => {
+    expect(isSnapshotStoreConfigured("snap-redis.internal")).toBe(true);
+  });
+});

apps/webapp/test/snapshotStoreOrgCensus.server.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   createSnapshotStoreOrgCensus,
+  defaultCensusAutoStart,
   type SnapshotStoreOrgCensusClient,
 } from "~/v3/snapshotStoreOrgCensus.server";
 
@@ -126,6 +127,31 @@ describe("snapshot store org census", () => {
   });
 });
 
+describe("snapshot store org census — autoStart host gate", () => {
+  it("never polls when no Redis host is configured, even in production", () => {
+    expect(defaultCensusAutoStart(undefined, "production")).toBe(false);
+    expect(defaultCensusAutoStart("", "production")).toBe(false);
+  });
+
+  it("polls only when configured and outside test", () => {
+    expect(defaultCensusAutoStart("snap-redis", "production")).toBe(true);
+    expect(defaultCensusAutoStart("snap-redis", "test")).toBe(false);
+  });
+
+  it("does not issue a query when built with a disabled autoStart", async () => {
+    const calls: FindManyArgs[] = [];
+    const census = createSnapshotStoreOrgCensus(
+      { replica: fakeClient([{ id: "org_a", featureFlags: null }], calls) },
+      { autoStart: defaultCensusAutoStart(undefined, "production"), intervalMs: 5 }
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(calls).toHaveLength(0);
+    census.stop();
+  });
+});
+
 describe("snapshot store org census — definite ever-enabled set", () => {
   // A: latched but dialled back to off. B: at redis-read and latched. C: has the mode key but off,
   // never latched. D: not returned by the query at all.