fix(webapp): read the primary when a waitpoint token misses both read replicas

A token completed immediately after it was minted could miss on the read
replicas and return a spurious 404, so the authoritative completion never ran.
Fall back to the owning-store primary before giving up.

Author: d-cs

apps/webapp/app/runEngine/concerns/resolveWaitpointThroughReadThrough.server.ts

@@ -1,6 +1,8 @@
 import type { PrismaReplicaClient } from "~/db.server";
 import {
   $replica as defaultLegacyReplica,
+  runOpsLegacyPrisma as defaultLegacyPrimary,
+  runOpsNewPrisma as defaultNewPrimary,
   runOpsNewReplica as defaultNewClient,
   runOpsSplitReadEnabled as defaultSplitReadEnabled,
 } from "~/db.server";
@@ -9,6 +11,8 @@ import { readThroughRun } from "~/v3/runOpsMigration/readThrough.server";
 type ResolveWaitpointDeps = {
   newClient?: PrismaReplicaClient;
   legacyReplica?: PrismaReplicaClient;
+  newPrimary?: PrismaReplicaClient;
+  legacyPrimary?: PrismaReplicaClient;
   splitEnabled?: boolean;
   isPastRetention?: (id: string) => boolean;
 };
@@ -18,12 +22,16 @@ type ResolveWaitpointDeps = {
 export type ResolveWaitpointReadThroughDefaults = {
   newClient: PrismaReplicaClient;
   legacyReplica: PrismaReplicaClient;
+  newPrimary: PrismaReplicaClient;
+  legacyPrimary: PrismaReplicaClient;
   splitEnabled: boolean;
 };
 
 const productionDefaults: ResolveWaitpointReadThroughDefaults = {
   newClient: defaultNewClient,
   legacyReplica: defaultLegacyReplica,
+  newPrimary: defaultNewPrimary as unknown as PrismaReplicaClient,
+  legacyPrimary: defaultLegacyPrimary as unknown as PrismaReplicaClient,
   splitEnabled: defaultSplitReadEnabled,
 };
 
@@ -36,18 +44,42 @@ export async function resolveWaitpointThroughReadThrough<T>(opts: {
 }): Promise<T | null> {
   const defaults = opts.defaults ?? productionDefaults;
 
+  const splitEnabled = opts.deps?.splitEnabled ?? defaults.splitEnabled;
+
   const result = await readThroughRun({
     runId: opts.waitpointId,
     environmentId: opts.environmentId,
     readNew: (client) => opts.read(client),
     readLegacy: (replica) => opts.read(replica),
     deps: {
-      splitEnabled: opts.deps?.splitEnabled ?? defaults.splitEnabled,
+      splitEnabled,
       newClient: opts.deps?.newClient ?? defaults.newClient,
       legacyReplica: opts.deps?.legacyReplica ?? defaults.legacyReplica,
       isPastRetention: opts.deps?.isPastRetention,
     },
   });
 
-  return result.source === "new" || result.source === "legacy-replica" ? result.value : null;
+  if (result.source === "new" || result.source === "legacy-replica") {
+    return result.value;
+  }
+  // past-retention is an intentional not-found: the token is gone, don't hit the primary.
+  if (result.source === "past-retention") {
+    return null;
+  }
+
+  // Read-your-writes fallback: readThroughRun is replica-only, so a token completed immediately after
+  // it was minted can miss on the replicas (not yet applied) and 404 a valid token - and the
+  // authoritative completeWaitpoint never runs. Re-read from the owning-store PRIMARY (new then legacy)
+  // before giving up. Bounded to this replica-miss; a genuinely-absent token still returns null.
+  const fromNewPrimary = await opts.read(opts.deps?.newPrimary ?? defaults.newPrimary);
+  if (fromNewPrimary != null) {
+    return fromNewPrimary;
+  }
+  if (splitEnabled) {
+    const fromLegacyPrimary = await opts.read(opts.deps?.legacyPrimary ?? defaults.legacyPrimary);
+    if (fromLegacyPrimary != null) {
+      return fromLegacyPrimary;
+    }
+  }
+  return null;
 }

apps/webapp/test/resolveWaitpointThroughReadThrough.readthrough.test.ts

@@ -151,6 +151,48 @@ describe("resolveWaitpointThroughReadThrough (hetero PG14 legacy + dedicated run
     }
   );
 
+  // Read-your-writes: a token completed immediately after mint may not be on the replicas yet. The
+  // replica-only read-through misses, and without a primary fallback we 404 a valid token (the
+  // authoritative completeWaitpoint never runs). The primary fallback must find it.
+  heteroRunOpsPostgresTest(
+    "a token missing on both replicas is found on the primary (no spurious 404)",
+    async ({ prisma17, prisma14 }) => {
+      const id = generateLegacyCuid();
+      const { project, environment } = await seedOrgProjectEnv(prisma14, "primary_fallback");
+      const seeded = await seedWaitpoint(prisma14, id, {
+        id: environment.id,
+        projectId: project.id,
+      });
+
+      // Both replicas miss (not yet replicated): point them at the dedicated DB, which lacks this
+      // legacy cuid waitpoint. The LEGACY primary (control-plane writer, prisma14) has it.
+      const newClient = recording(prisma17);
+      const legacyReplica = recording(prisma17);
+      const newPrimary = recording(prisma17);
+      const legacyPrimary = recording(prisma14);
+
+      const result = await resolveWaitpointThroughReadThrough({
+        waitpointId: id,
+        environmentId: environment.id,
+        read: read(id, environment.id),
+        deps: {
+          splitEnabled: true,
+          newClient: newClient.handle,
+          legacyReplica: legacyReplica.handle,
+          newPrimary: newPrimary.handle,
+          legacyPrimary: legacyPrimary.handle,
+        },
+      });
+
+      expect(result).not.toBeNull();
+      expect(result!.id).toBe(seeded.id);
+      // Replicas probed and missed; the fallback read the primary.
+      expect(newClient.calls.length).toBe(1);
+      expect(legacyReplica.calls.length).toBe(1);
+      expect(legacyPrimary.calls.length).toBe(1);
+    }
+  );
+
   heteroRunOpsPostgresTest(
     "bare caller (no deps) resolves a NEW-resident waitpoint via the safe run-ops defaults",
     async ({ prisma17, prisma14 }) => {
@@ -170,6 +212,9 @@ describe("resolveWaitpointThroughReadThrough (hetero PG14 legacy + dedicated run
         defaults: {
           newClient: prisma14 as unknown as PrismaReplicaClient,
           legacyReplica: prisma14 as unknown as PrismaReplicaClient,
+          // Primaries also miss the NEW-resident waitpoint, so the miss stays a miss.
+          newPrimary: prisma14 as unknown as PrismaReplicaClient,
+          legacyPrimary: prisma14 as unknown as PrismaReplicaClient,
           splitEnabled: true,
         },
       });
@@ -183,6 +228,8 @@ describe("resolveWaitpointThroughReadThrough (hetero PG14 legacy + dedicated run
         defaults: {
           newClient: prisma17 as unknown as PrismaReplicaClient,
           legacyReplica: prisma14 as unknown as PrismaReplicaClient,
+          newPrimary: prisma17 as unknown as PrismaReplicaClient,
+          legacyPrimary: prisma14 as unknown as PrismaReplicaClient,
           splitEnabled: true,
         },
       });