feat(webapp): give the read gate the shard handles and the replication builder the descriptors

The read gate receives one handle per shard, with the declared aliasOf, so a
shard whose client is not distinct warns. The verdict it returns is unchanged.

The replication instance passes the shard descriptors to the source builder and
to the coverage check. The distinctness sentinel and the co-residency advisory
read the descriptors themselves, so the boot order is unchanged: the probe still
runs where it ran, with a wider target list.

Author: d-cs

apps/webapp/app/db.server.ts

@@ -594,6 +594,15 @@ export const runOpsSplitReadEnabled: boolean = computeRunOpsSplitReadEnabled({
   controlPlaneReplica: $replica,
   hasNewUrl: !!env.RUN_OPS_DATABASE_URL,
   hasLegacyUrl: !!env.RUN_OPS_LEGACY_DATABASE_URL,
+  // Observability only: a non-distinct shard handle warns and never changes the gen-1 verdict.
+  // Empty unless RUN_OPS_SHARDS is configured.
+  shardHandles: runOpsShardHandles.map((handle) => ({
+    key: handle.key,
+    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.
+    aliasOf: env.RUN_OPS_SHARDS.find((d) => d.key === handle.key)?.aliasOf,
+  })),
   logger,
 });
 

apps/webapp/app/services/runsReplicationInstance.server.ts

@@ -81,7 +81,7 @@ export function buildReplicationSources(args: {
 
 // The replication source id for a shard. It derives the client name and the leader-lock key, so it
 // must be stable and unique across sources.
-export function shardSourceId(key: string): string {
+function shardSourceId(key: string): string {
   return `shard-${key}`;
 }
 
@@ -111,7 +111,7 @@ export class SplitReplicationMisconfiguredError extends Error {
  * the boot catch site tests `instanceof SplitReplicationMisconfiguredError` to reach
  * process.exit(1), and a shard whose runs never reach ClickHouse must take that same exit.
  */
-export class ShardReplicationMisconfiguredError extends SplitReplicationMisconfiguredError {
+class ShardReplicationMisconfiguredError extends SplitReplicationMisconfiguredError {
   constructor(shardKey: string) {
     super(
       `run-ops shard ${shardKey} is configured but the runs-replication sources[] has no ` +

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

@@ -47,8 +47,7 @@ export function resolveCoresidencyEnforcement(args: {
     const store = args.shardKey === undefined ? "legacy run-ops DB" : `shard ${args.shardKey}`;
     return {
       throw: true,
-      message:
-        `RUN_OPS_EXPECT_CONTROL_PLANE_SPLIT is on but the ${store} is still co-resident with the control-plane DB; refusing to start.`,
+      message: `RUN_OPS_EXPECT_CONTROL_PLANE_SPLIT is on but the ${store} is still co-resident with the control-plane DB; refusing to start.`,
     };
   }
   return { throw: false };