fix(webapp): warn about the read-gate case a shard can actually reach

A shard with no replicaUrl takes its own writer as its replica handle, so its
reads go to its primary. That is the per-shard analogue of the existing legacy
warning, and it is reachable today.

The control-plane identity check stays as a regression guard, now marked as
unreachable by construction: a non-aliased shard always gets a freshly built
client. It exists so a future control-plane fallback for shards cannot silently
route a shard's reads to another database.

Author: d-cs

apps/webapp/app/db.server.ts

@@ -598,6 +598,7 @@ export const runOpsSplitReadEnabled: boolean = computeRunOpsSplitReadEnabled({
   // Empty unless RUN_OPS_SHARDS is configured.
   shardHandles: runOpsShardHandles.map((handle) => ({
     key: handle.key,
+    writer: handle.writer,
     replica: handle.replica,
     // The DECLARED field, not client identity: an aliased shard shares its target's client by
     // reference, so identity comparison cannot tell the two apart.

apps/webapp/app/v3/runOpsMigration/runOpsSplitReadGate.ts

@@ -9,11 +9,11 @@ export function computeRunOpsSplitReadEnabled(args: {
   hasNewUrl: boolean;
   hasLegacyUrl: boolean;
   /**
-   * Gen-2 shard replica handles. Observability only: a non-distinct shard handle WARNS and never
-   * changes the returned verdict. The distinctness sentinel already fail-closes the boot on the
-   * same condition, and a gen-2 fault must not disable the proven gen-1 read fan-out as well.
+   * Gen-2 shard handles. Observability only: a non-distinct shard handle WARNS and never changes the
+   * returned verdict. A gen-2 fault must not disable the proven gen-1 read fan-out, and the
+   * distinctness sentinel already fail-closes the boot when two stores share a database.
    */
-  shardHandles?: Array<{ key: string; replica: unknown; aliasOf?: "new" }>;
+  shardHandles?: Array<{ key: string; writer?: unknown; replica: unknown; aliasOf?: "new" }>;
   logger?: { warn: (msg: string, meta?: Record<string, unknown>) => void };
 }): boolean {
   const newIsDistinctDedicatedClient =
@@ -34,6 +34,20 @@ export function computeRunOpsSplitReadEnabled(args: {
   // state and never a fault. Keyed on the declared field, not on object identity.
   for (const shard of args.shardHandles ?? []) {
     if (shard.aliasOf !== undefined) continue;
+
+    // A shard with no replica URL takes its own writer as its replica handle, so its reads go to
+    // its primary. This is the per-shard analogue of the existing legacy-primary warning.
+    if (shard.writer !== undefined && shard.replica === shard.writer) {
+      args.logger?.warn(
+        `run-ops shard ${shard.key} has no read replica handle; reads for that shard will hit the ` +
+          "shard primary. Set the shard's replicaUrl to keep replica reads off its primary."
+      );
+      continue;
+    }
+
+    // Unreachable by construction today: a non-aliased shard always gets a freshly built client.
+    // Kept as a regression guard, so a future control-plane fallback for shards cannot silently
+    // route a shard's reads to another database.
     if (
       shard.replica === args.controlPlaneWriter ||
       shard.replica === args.controlPlaneReplica ||

apps/webapp/test/runOpsSplitReadGate.test.ts

@@ -233,6 +233,52 @@ describe("computeRunOpsSplitReadEnabled shard handles", () => {
     ).toBe(true);
   });
 
+  // The reachable case. A shard with no replicaUrl gets its own WRITER as its replica handle, so its
+  // reads go to its primary. selectRunOpsTopology does exactly that (db.server.ts), which makes this
+  // the per-shard analogue of the existing legacy "reads will hit the legacy primary" warning.
+  it("warns when a shard has no distinct replica handle, so its reads hit its primary", () => {
+    const warn = vi.fn();
+    computeRunOpsSplitReadEnabled({
+      ...base,
+      shardHandles: [{ key: "a", writer: shardA, replica: shardA }],
+      logger: { warn },
+    });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toMatch(/shard a/i);
+    expect(warn.mock.calls[0][0]).toMatch(/primary/i);
+  });
+
+  it("does not warn when a shard has its own distinct replica handle", () => {
+    const warn = vi.fn();
+    computeRunOpsSplitReadEnabled({
+      ...base,
+      shardHandles: [{ key: "a", writer: shardA, replica: shardB }],
+      logger: { warn },
+    });
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("does NOT warn about primary reads for an aliased shard", () => {
+    const warn = vi.fn();
+    computeRunOpsSplitReadEnabled({
+      ...base,
+      shardHandles: [
+        { key: "z", writer: dedicatedNew, replica: dedicatedNew, aliasOf: "new" as const },
+      ],
+      logger: { warn },
+    });
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("keeps the gen-1 verdict when a shard reads from its primary", () => {
+    expect(
+      computeRunOpsSplitReadEnabled({
+        ...base,
+        shardHandles: [{ key: "a", writer: shardA, replica: shardA }],
+      })
+    ).toBe(true);
+  });
+
   it("warns once per offending shard", () => {
     const warn = vi.fn();
     computeRunOpsSplitReadEnabled({