fix(webapp): parse idempotencyKeyOptions in canonical { key, scope } shape on buffer read-fallback

`readFallback.server.ts` was checking `Array.isArray(idempotencyKeyOptionsRaw)` and
returning `undefined` otherwise. The SDK and Prisma both serialise this
field as `{ key, scope }` (per `IdempotencyKeyOptionsSchema`); the
array form never matches, so `SyntheticRun.idempotencyKeyOptions` was
always `undefined` for buffered runs.

Downstream effect: `getUserProvidedIdempotencyKey` falls back to
`run.idempotencyKey` when options are absent — which is the *hash*,
not the user-supplied key. PG-resident runs return the user's key
(options parse succeeds); buffered runs were returning the hash. The
API's `idempotencyKey` field silently flipped values at the drainer-
materialisation boundary.

Parse via `IdempotencyKeyOptionsSchema.safeParse` so the buffered
response matches PG-resident behaviour from the moment the run is
buffered.

Type change is local to `SyntheticRun` — `synthesiseFoundRunFromBuffer`
and `buildSyntheticSpanRun` both forward via `?? null` into Prisma
`JsonValue | null` destinations, which accept the new object shape.

Two regression tests on `mollifierReadFallback.test.ts`:
1. Canonical `{ key, scope }` object parses to the schema-shaped data.
2. Legacy array form (the previous bug) and other invalid shapes
   return undefined so downstream falls back to the hash, matching
   how PG-resident runs handle malformed/missing options.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: d-cs

apps/webapp/app/v3/mollifier/readFallback.server.ts

@@ -1,5 +1,7 @@
 import type { MollifierBuffer } from "@trigger.dev/redis-worker";
 import { RunId } from "@trigger.dev/core/v3/isomorphic";
+import { IdempotencyKeyOptionsSchema } from "@trigger.dev/core/v3/schemas";
+import type { z } from "zod";
 import { logger } from "~/services/logger.server";
 import { deserialiseMollifierSnapshot } from "./mollifierSnapshot.server";
 import { getMollifierBuffer } from "./mollifierBuffer.server";
@@ -50,7 +52,15 @@ export type SyntheticRun = {
   // expose it here so the cached-hit branch can apply the same check
   // rather than indefinitely returning the buffered run's id.
   idempotencyKeyExpiresAt: Date | undefined;
-  idempotencyKeyOptions: string[] | undefined;
+  // `{ key, scope }` object form, matching how the SDK serialises and PG
+  // stores it. Previously typed as `string[]` (legacy/incorrect — Prisma
+  // is `Json?` carrying the schema-shaped object). `getUserProvidedIdempotencyKey`
+  // and `extractIdempotencyKeyScope` both parse via the same Zod schema;
+  // they returned `undefined` for the array-shape, which silently
+  // demoted the response to surface the hash instead of the user-
+  // provided key for buffered runs — a contract divergence from
+  // PG-resident runs. See the regression test in `mollifierReadFallback.test.ts`.
+  idempotencyKeyOptions: z.infer<typeof IdempotencyKeyOptionsSchema> | undefined;
   isTest: boolean;
   depth: number;
   ttl: string | undefined;
@@ -145,9 +155,18 @@ export async function findRunByIdWithMollifierFallback(
     }
 
     const snapshot = deserialiseMollifierSnapshot(entry.payload);
-    const idempotencyKeyOptionsRaw = snapshot.idempotencyKeyOptions;
-    const idempotencyKeyOptions = Array.isArray(idempotencyKeyOptionsRaw)
-      ? asStringArray(idempotencyKeyOptionsRaw)
+    // Parse via the canonical schema (`{ key: string, scope: "run" |
+    // "attempt" | "global" }`) rather than the legacy Array.isArray
+    // check. The SDK and Prisma both store this as an object; the array
+    // form never matches, so a buffered run's response previously fell
+    // back to the server-side hash in `getUserProvidedIdempotencyKey`
+    // instead of the customer-supplied key — diverging from how
+    // materialised runs render the same field.
+    const idempotencyKeyOptionsParsed = IdempotencyKeyOptionsSchema.safeParse(
+      snapshot.idempotencyKeyOptions,
+    );
+    const idempotencyKeyOptions = idempotencyKeyOptionsParsed.success
+      ? idempotencyKeyOptionsParsed.data
       : undefined;
 
     const tags = asStringArray(snapshot.tags);

apps/webapp/test/mollifierReadFallback.test.ts

@@ -137,7 +137,7 @@ describe("findRunByIdWithMollifierFallback", () => {
         metadata: '{"customer":"acme"}',
         metadataType: "application/json",
         idempotencyKey: "client-abc",
-        idempotencyKeyOptions: ["payload"],
+        idempotencyKeyOptions: { key: "client-abc", scope: "run" },
         isTest: true,
         depth: 2,
         ttl: "1h",
@@ -161,7 +161,7 @@ describe("findRunByIdWithMollifierFallback", () => {
     expect(result!.metadata).toBe('{"customer":"acme"}');
     expect(result!.metadataType).toBe("application/json");
     expect(result!.idempotencyKey).toBe("client-abc");
-    expect(result!.idempotencyKeyOptions).toEqual(["payload"]);
+    expect(result!.idempotencyKeyOptions).toEqual({ key: "client-abc", scope: "run" });
     expect(result!.isTest).toBe(true);
     expect(result!.depth).toBe(2);
     expect(result!.ttl).toBe("1h");
@@ -195,6 +195,73 @@ describe("findRunByIdWithMollifierFallback", () => {
     expect(result!.parentSpanId).toBe("span_parent");
   });
 
+  it("parses idempotencyKeyOptions in the canonical { key, scope } object shape (regression for the buffered-vs-PG API contract divergence)", async () => {
+    // Regression for the bug where `readFallback` parsed
+    // `idempotencyKeyOptions` via Array.isArray and rejected the
+    // canonical object shape. The SDK and Prisma both serialise this
+    // as `{ key, scope }`; the legacy array check would reject it,
+    // returning `undefined` here, which downstream demoted the API's
+    // `idempotencyKey` field to surface the *hash* (server-side
+    // generated) instead of the user-supplied key — diverging from
+    // how materialised runs render the same field, and creating a
+    // silent contract flip at the drainer-materialisation boundary.
+    // Pin the schema-parse path so the buffered response matches
+    // PG-resident behaviour from the moment the run is buffered.
+    const entry: BufferEntry = {
+      runId: "run_1",
+      envId: "env_a",
+      orgId: "org_1",
+      payload: JSON.stringify({
+        taskIdentifier: "t",
+        idempotencyKey: "<hashed>",
+        idempotencyKeyOptions: { key: "user-supplied-key", scope: "global" },
+      }),
+      status: "QUEUED",
+      attempts: 0,
+      createdAt: NOW,
+    };
+    const result = await findRunByIdWithMollifierFallback(
+      { runId: "run_1", environmentId: "env_a", organizationId: "org_1" },
+      { getBuffer: () => fakeBuffer(entry) },
+    );
+    expect(result).not.toBeNull();
+    expect(result!.idempotencyKeyOptions).toEqual({
+      key: "user-supplied-key",
+      scope: "global",
+    });
+  });
+
+  it("returns undefined for idempotencyKeyOptions when the snapshot carries a legacy/invalid shape", async () => {
+    // The Zod schema parse rejects:
+    //   - array shape (the legacy bug we just fixed)
+    //   - object without required fields
+    //   - missing field entirely
+    // In all these cases the field is left `undefined`. Downstream
+    // `getUserProvidedIdempotencyKey` then falls back to the
+    // `idempotencyKey` field, matching how PG-resident runs handle
+    // malformed/missing options.
+    const entry: BufferEntry = {
+      runId: "run_1",
+      envId: "env_a",
+      orgId: "org_1",
+      payload: JSON.stringify({
+        taskIdentifier: "t",
+        idempotencyKey: "<hashed>",
+        // Legacy array shape — must NOT be accepted.
+        idempotencyKeyOptions: ["payload"],
+      }),
+      status: "QUEUED",
+      attempts: 0,
+      createdAt: NOW,
+    };
+    const result = await findRunByIdWithMollifierFallback(
+      { runId: "run_1", environmentId: "env_a", organizationId: "org_1" },
+      { getBuffer: () => fakeBuffer(entry) },
+    );
+    expect(result).not.toBeNull();
+    expect(result!.idempotencyKeyOptions).toBeUndefined();
+  });
+
   it("defaults snapshot-derived fields to safe values when absent", async () => {
     const entry: BufferEntry = {
       runId: "run_1",