fix(run-store): guard findRuns skip and skip the non-candidate table on id-list reads

findRuns now throws when given skip: offset pagination cannot span the two run tables, where each would independently skip N rows from its own result rather than N from the merged result. For an id-list predicate (id in [...]), it now queries only the table whose id format can contain those ids, avoiding a wasted query against an empty task_run_v2 while it is unpopulated during rollout.

Author: d-cs

internal-packages/run-store/src/PostgresRunStore.test.ts

@@ -1,7 +1,7 @@
 import { postgresTest } from "@internal/testcontainers";
 import { isKsuidId, RunId } from "@trigger.dev/core/v3/isomorphic";
 import type { PrismaClient } from "@trigger.dev/database";
-import { describe, expect } from "vitest";
+import { describe, expect, vi } from "vitest";
 import { PostgresRunStore } from "./PostgresRunStore.js";
 import type { CreateCancelledRunInput, CreateFailedRunInput, CreateRunInput } from "./types.js";
 
@@ -2378,6 +2378,68 @@ describe("PostgresRunStore — table routing by id format", () => {
       ).rejects.toThrow(/cursor/i);
     }
   );
+
+  postgresTest(
+    "findRuns rejects `skip` (offset pagination cannot span the two tables)",
+    async ({ prisma }) => {
+      const { environment } = await seedEnvironment(prisma);
+      const store = new PostgresRunStore({ prisma, readOnlyPrisma: prisma });
+
+      await expect(
+        store.findRuns({
+          where: { runtimeEnvironmentId: environment.id },
+          select: { id: true },
+          skip: 10,
+          take: 5,
+        })
+      ).rejects.toThrow(/skip/i);
+    }
+  );
+
+  postgresTest(
+    "findRuns with an id-list partitions by id format and skips the table with no candidate ids",
+    async ({ prisma }) => {
+      const { organization, project, environment } = await seedEnvironment(prisma);
+      const store = new PostgresRunStore({ prisma, readOnlyPrisma: prisma });
+
+      const cuid = RunId.generate();
+      const ksuid = RunId.generateKsuid();
+      for (const r of [cuid, ksuid]) {
+        await seedRoutedRun(prisma, {
+          id: r.id,
+          friendlyId: r.friendlyId,
+          organizationId: organization.id,
+          projectId: project.id,
+          runtimeEnvironmentId: environment.id,
+        });
+      }
+
+      const ids = (rows: unknown) =>
+        (rows as Array<{ id: string }>).map((r) => r.id).sort();
+
+      // Mixed list: both tables queried, both runs returned.
+      expect(
+        ids(await store.findRuns({ where: { id: { in: [cuid.id, ksuid.id] } }, select: { id: true } }))
+      ).toEqual([cuid.id, ksuid.id].sort());
+
+      // cuid-only list: the task_run_v2 query is skipped, legacy run still returned.
+      const v2Spy = vi.spyOn(prisma.taskRunV2, "findMany");
+      const legacyOnly = await store.findRuns({ where: { id: { in: [cuid.id] } }, select: { id: true } });
+      expect(ids(legacyOnly)).toEqual([cuid.id]);
+      expect(v2Spy).not.toHaveBeenCalled();
+      v2Spy.mockRestore();
+
+      // ksuid-only list: the TaskRun query is skipped, v2 run still returned.
+      const legacySpy = vi.spyOn(prisma.taskRun, "findMany");
+      const v2Only = await store.findRuns({ where: { id: { in: [ksuid.id] } }, select: { id: true } });
+      expect(ids(v2Only)).toEqual([ksuid.id]);
+      expect(legacySpy).not.toHaveBeenCalled();
+      legacySpy.mockRestore();
+
+      // Empty list matches nothing.
+      expect(ids(await store.findRuns({ where: { id: { in: [] } }, select: { id: true } }))).toEqual([]);
+    }
+  );
 });
 
 describe("PostgresRunStore — v2 nested writes (run + related rows via nested Prisma create)", () => {

internal-packages/run-store/src/PostgresRunStore.ts

@@ -844,14 +844,31 @@ export class PostgresRunStore implements RunStore {
   ): Promise<unknown> {
     const prisma = client ?? this.readOnlyPrisma;
 
+    // Offset pagination can't be expressed across two tables: applying `skip`
+    // to each table independently skips N rows from each, not N from the merged
+    // result. Reject it rather than silently double-skip. No caller uses it;
+    // cross-table reads keyset-paginate on a where + (createdAt, id) orderBy.
+    if (args.skip !== undefined) {
+      throw new Error(
+        "RunStore.findRuns: `skip` (offset pagination) is not supported across the legacy TaskRun " +
+          "and task_run_v2 tables. Use a where-based keyset (createdAt + id) instead."
+      );
+    }
+
     // A run lives in exactly one physical table, chosen by its id format, so a
-    // multi-row read must hit BOTH `TaskRun` (legacy cuid) and `task_run_v2`
-    // (new ksuid) and combine. `task_run_v2` is an identical clone of `TaskRun`
-    // (same relation surface), so the SAME `args` — crucially the SAME `where`,
-    // which is the security scope — run unchanged against either delegate.
+    // multi-row read generally hits BOTH `TaskRun` (legacy cuid) and
+    // `task_run_v2` (new ksuid) and combines. `task_run_v2` is an identical
+    // clone of `TaskRun` (same relation surface), so the SAME `args` (crucially
+    // the SAME `where`, which is the security scope) run unchanged against
+    // either delegate. When the predicate is an `id: { in: [...] }` list, the
+    // table with no candidate ids is skipped (a cuid can't live in task_run_v2,
+    // nor a ksuid in TaskRun), avoiding an empty query while task_run_v2 is
+    // unpopulated during rollout.
     const legacyModel = prisma.taskRun;
     const v2Model = prisma.taskRunV2 as unknown as typeof prisma.taskRun;
 
+    const { queryLegacy, queryV2 } = this.#tablesForWhere(args.where);
+
     const ordered = this.#normalizeOrderBy(args.orderBy);
 
     // ORDERED + LIMITED → bounded 2-way merge.
@@ -881,8 +898,8 @@ export class PostgresRunStore implements RunStore {
       const perTableArgs = { ...queryArgs, take: args.take };
 
       const [legacyRows, v2Rows] = (await Promise.all([
-        legacyModel.findMany(perTableArgs),
-        v2Model.findMany(perTableArgs),
+        queryLegacy ? legacyModel.findMany(perTableArgs) : Promise.resolve([]),
+        queryV2 ? v2Model.findMany(perTableArgs) : Promise.resolve([]),
       ])) as [Array<Record<string, unknown>>, Array<Record<string, unknown>>];
 
       const merged = this.#mergeOrdered(legacyRows, v2Rows, comparator, args.take);
@@ -901,8 +918,8 @@ export class PostgresRunStore implements RunStore {
         : { args, addedKeys: [] as string[] };
 
     const [legacyRows, v2Rows] = (await Promise.all([
-      legacyModel.findMany(queryArgs),
-      v2Model.findMany(queryArgs),
+      queryLegacy ? legacyModel.findMany(queryArgs) : Promise.resolve([]),
+      queryV2 ? v2Model.findMany(queryArgs) : Promise.resolve([]),
     ])) as [Array<Record<string, unknown>>, Array<Record<string, unknown>>];
 
     let combined = legacyRows.concat(v2Rows);
@@ -924,6 +941,38 @@ export class PostgresRunStore implements RunStore {
     return this.#stripAddedKeys(combined, addedKeys);
   }
 
+  /**
+   * Which physical tables a `findRuns` predicate can match. A run id encodes
+   * its table, so an `id: { in: [...] }` list containing only cuids cannot match
+   * `task_run_v2` (and a ksuid-only list cannot match `TaskRun`): the table with
+   * no candidate ids is skipped, avoiding a wasted query against an empty
+   * `task_run_v2` during rollout. An empty `in` list matches nothing, so both
+   * are skipped. Any other predicate must consult both tables.
+   */
+  #tablesForWhere(where: Prisma.TaskRunWhereInput): { queryLegacy: boolean; queryV2: boolean } {
+    const idFilter = where.id;
+    const idIn =
+      idFilter !== null && typeof idFilter === "object" && "in" in idFilter
+        ? (idFilter as { in?: unknown }).in
+        : undefined;
+
+    if (Array.isArray(idIn)) {
+      let queryLegacy = false;
+      let queryV2 = false;
+      for (const id of idIn) {
+        if (typeof id === "string" && isKsuidId(id)) {
+          queryV2 = true;
+        } else {
+          queryLegacy = true;
+        }
+        if (queryLegacy && queryV2) break;
+      }
+      return { queryLegacy, queryV2 };
+    }
+
+    return { queryLegacy: true, queryV2: true };
+  }
+
   /**
    * The cross-table merge/sort compares order-key VALUES read off each returned
    * row, so every scalar order key must be present in the projection. When the