fix(webapp): exempt aliased shards from the shard boot interlock

An aliased shard owns no database: it shares its target's client by reference,
so its rows are still read with the split off and nothing is dropped. Feeding
every configured key to the interlock refused an alias-only config for no
reason.

The exemption now lives inside the interlock rather than at its call site, so
it takes the raw descriptors and no caller can forget to apply it. This matches
where the distinctness sentinel, the coresidency loop and replication already
draw the line.

Author: d-cs

apps/webapp/app/db.server.ts

@@ -622,7 +622,7 @@ export async function assertRunOpsSplitSentinel(): Promise<void> {
   // checked BEFORE the split-off early return below, which would otherwise skip it in silence.
   assertShardsRequireSplit({
     splitFlagEnabled: env.RUN_OPS_SPLIT_ENABLED,
-    shardKeys: env.RUN_OPS_SHARDS.map((shard) => shard.key),
+    shards: env.RUN_OPS_SHARDS,
   });
   if (!env.RUN_OPS_SPLIT_ENABLED) return;
   // Realtime interlock (synchronous): Electric replicates only from the control-plane

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

@@ -7,7 +7,11 @@
 import { env } from "~/env.server";
 import { logger } from "~/services/logger.server";
 import { probeDistinctStores as defaultProbe } from "./distinctDbSentinel.server";
-import { nonAliasedShards, type ShardTarget } from "~/v3/runOpsShards.server";
+import {
+  nonAliasedShards,
+  type RunOpsShardDescriptor,
+  type ShardTarget,
+} from "~/v3/runOpsShards.server";
 
 export type SplitModeConfig = {
   flagEnabled: boolean;
@@ -75,7 +79,8 @@ export function assertSplitRealtimeInterlock(config: SplitRealtimeInterlockConfi
 
 export type ShardsRequireSplitConfig = {
   splitFlagEnabled: boolean;
-  shardKeys: string[];
+  /** Raw descriptors. The alias exemption is applied here so no call site can forget it. */
+  shards: RunOpsShardDescriptor[];
 };
 
 /**
@@ -86,11 +91,18 @@ export type ShardsRequireSplitConfig = {
  * distinct) already refuse to boot; this closes the one that does not.
  */
 export function assertShardsRequireSplit(config: ShardsRequireSplitConfig): void {
-  if (config.splitFlagEnabled || config.shardKeys.length === 0) {
+  if (config.splitFlagEnabled) {
+    return;
+  }
+  // An aliased shard owns no database: it shares its target's client by reference, so its rows are
+  // still read with the split off and nothing is dropped. Exempt here exactly as it is exempt from
+  // the distinctness sentinel, the coresidency loop and replication.
+  const owning = nonAliasedShards(config.shards).map((shard) => shard.key);
+  if (owning.length === 0) {
     return;
   }
   throw new Error(
-    `RUN_OPS_SHARDS configures shard(s) ${config.shardKeys.join(", ")} but RUN_OPS_SPLIT_ENABLED is off, so no shard client is built and rows on those databases would be silently missing; refusing to start.`
+    `RUN_OPS_SHARDS configures shard(s) ${owning.join(", ")} but RUN_OPS_SPLIT_ENABLED is off, so no shard client is built and rows on those databases would be silently missing; refusing to start.`
   );
 }
 

apps/webapp/test/runOpsSplitMode.test.ts

@@ -157,32 +157,55 @@ describe("assertSplitRealtimeInterlock (pure)", () => {
 });
 
 describe("assertShardsRequireSplit (pure)", () => {
+  const owning = (key: string) => ({
+    key,
+    region: "local",
+    url: `postgres://${key}`,
+    replication: { slotName: `s_${key}`, publicationName: `p_${key}`, originGeneration: 2 },
+  });
+  const aliased = (key: string) => ({ key, region: "local", aliasOf: "new" as const });
+
   it("allows shards when the split flag is on", () => {
     expect(() =>
-      assertShardsRequireSplit({ splitFlagEnabled: true, shardKeys: ["a"] })
+      assertShardsRequireSplit({ splitFlagEnabled: true, shards: [owning("a")] })
     ).not.toThrow();
   });
 
   it("allows the split flag off when no shard is configured", () => {
-    expect(() =>
-      assertShardsRequireSplit({ splitFlagEnabled: false, shardKeys: [] })
-    ).not.toThrow();
+    expect(() => assertShardsRequireSplit({ splitFlagEnabled: false, shards: [] })).not.toThrow();
   });
 
-  // Shards are only ever built on the split-on arm of selectRunOpsTopology, so configuring one
-  // while the split flag is off silently drops it: no shard client, no shard leg, and any row
-  // already resident on that database disappears from every list with no error.
-  it("refuses to boot when a shard is configured but the split flag is off", () => {
+  // Shards are only built on the split-on arm of selectRunOpsTopology, so configuring one while
+  // the split flag is off silently drops it: no client, no leg, and any row already resident on
+  // that database disappears from every list with no error.
+  it("refuses to boot when a shard that owns a database is configured but the split flag is off", () => {
     expect(() =>
-      assertShardsRequireSplit({ splitFlagEnabled: false, shardKeys: ["a", "b"] })
+      assertShardsRequireSplit({ splitFlagEnabled: false, shards: [owning("a"), owning("b")] })
     ).toThrow(/RUN_OPS_SHARDS/);
   });
 
-  it("names the configured shards so the operator can see which were dropped", () => {
+  it("names the dropped shards so the operator can see which ones they are", () => {
     expect(() =>
-      assertShardsRequireSplit({ splitFlagEnabled: false, shardKeys: ["a", "b"] })
+      assertShardsRequireSplit({ splitFlagEnabled: false, shards: [owning("a"), owning("b")] })
     ).toThrow(/a, b/);
   });
+
+  // An aliased shard owns no database: it shares its target's client by reference, so its rows are
+  // still read with the split off. Refusing to boot for one is a false positive.
+  it("allows an alias-only config with the split flag off", () => {
+    expect(() =>
+      assertShardsRequireSplit({ splitFlagEnabled: false, shards: [aliased("a")] })
+    ).not.toThrow();
+  });
+
+  it("refuses only for the owning shards when the config mixes both", () => {
+    expect(() =>
+      assertShardsRequireSplit({
+        splitFlagEnabled: false,
+        shards: [aliased("a"), owning("b")],
+      })
+    ).toThrow(/shard\(s\) b /);
+  });
 });
 
 describe("distinct-DB sentinel (real Postgres)", () => {