fix(core,cli): retain idempotency key metadata beyond 1000 keys per run (#4094)

Fixes #4046

## Problem

When a single run creates more than 1000 idempotency keys (e.g. a large
batch trigger where each item calls `idempotencyKeys.create()`), the
original key and scope metadata is silently dropped for all but the most
recent 1000 keys.

`idempotencyKeys.create()` returns a plain 64-char hash and stores the
`{ key, scope }` mapping in an in-process catalog keyed by that hash.
That catalog was a fixed-size **LRU capped at 1000 entries**. Once a run
creates more than 1000 keys, the earliest mappings are evicted, so when
the SDK later looks them up to attach `idempotencyKeyOptions` to the
trigger call, it finds nothing and sends `undefined`. The affected runs
then:

- report `ctx.run.idempotencyKey` as the raw hash instead of the
user-provided key
- have no `idempotencyKeyScope`
- show empty `idempotency_key` / `idempotency_key_scope` in the
dashboard and analytics

Deduplication still works (the hash is intact); only the human-readable
metadata is lost, which makes the failure silent and hard to notice.

## Fix

- Replace the LRU catalog with an unbounded in-memory catalog, so every
key created within a run keeps its metadata regardless of how many are
created.
- Clear the catalog at each run boundary via
`resetExecutionEnvironment()` (both dev and managed workers), matching
how every other per-run manager is reset. Deployed workers reuse one
process across many runs (warm starts), so this bounds memory to a
single run's keys instead of accumulating across runs — which is the
reason the size cap existed in the first place.

## Tests

- New public-API test creates 3000 keys and asserts all of them
(including the first) retain their key/scope — this fails on `main` and
passes with the fix.
- New test for the in-memory catalog covers store/retrieve/overwrite,
large-N retention (no eviction), and `clear()`.
- New test asserts the catalog is emptied after a run-boundary reset.
- Replaces the previous LRU catalog + its eviction tests.

Verified: `@trigger.dev/core` and `trigger.dev` both build; all
idempotency tests pass. Changeset added (patch).

Author: matt-aitken

.changeset/idempotency-key-catalog-eviction.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Fix idempotency key metadata (original key + scope) being silently dropped when a single run creates more than 1000 idempotency keys. The in-process catalog that maps a key's hash back to its original key/scope is no longer bounded to 1000 entries, so `idempotencyKeys.create()` results retain their metadata regardless of how many are created in a run. The catalog is now cleared at each run boundary so it does not accumulate across warm-start runs.

packages/cli-v3/src/entryPoints/dev-run-worker.ts

@@ -35,6 +35,7 @@ import {
   realtimeStreams,
   inputStreams,
   sessionStreams,
+  resetIdempotencyKeyCatalog,
 } from "@trigger.dev/core/v3";
 import { TriggerTracer } from "@trigger.dev/core/v3/tracer";
 import {
@@ -378,6 +379,7 @@ function resetExecutionEnvironment() {
   taskContext.disable();
   standardTraceContextManager.reset();
   standardHeartbeatsManager.reset();
+  resetIdempotencyKeyCatalog();
 
   // Wait for all streams to finish before completing the run
   waitUntil.register({

packages/cli-v3/src/entryPoints/managed-run-worker.ts

@@ -34,6 +34,7 @@ import {
   realtimeStreams,
   inputStreams,
   sessionStreams,
+  resetIdempotencyKeyCatalog,
 } from "@trigger.dev/core/v3";
 import { TriggerTracer } from "@trigger.dev/core/v3/tracer";
 import {
@@ -350,6 +351,7 @@ function resetExecutionEnvironment() {
   taskContext.disable();
   standardTraceContextManager.reset();
   standardHeartbeatsManager.reset();
+  resetIdempotencyKeyCatalog();
 
   // Wait for all streams to finish before completing the run
   waitUntil.register({

packages/core/src/v3/idempotency-key-catalog/catalog.ts

@@ -8,4 +8,5 @@ export type IdempotencyKeyOptions = {
 export interface IdempotencyKeyCatalog {
   registerKeyOptions(hash: string, options: IdempotencyKeyOptions): void;
   getKeyOptions(hash: string): IdempotencyKeyOptions | undefined;
+  clear(): void;
 }

packages/core/src/v3/idempotency-key-catalog/inMemoryIdempotencyKeyCatalog.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { InMemoryIdempotencyKeyCatalog } from "./inMemoryIdempotencyKeyCatalog.js";
+
+describe("InMemoryIdempotencyKeyCatalog", () => {
+  it("stores and retrieves options", () => {
+    const catalog = new InMemoryIdempotencyKeyCatalog();
+    const options = { key: "my-key", scope: "global" as const };
+
+    catalog.registerKeyOptions("hash1", options);
+
+    expect(catalog.getKeyOptions("hash1")).toEqual(options);
+  });
+
+  it("returns undefined for non-existent keys", () => {
+    const catalog = new InMemoryIdempotencyKeyCatalog();
+
+    expect(catalog.getKeyOptions("non-existent")).toBeUndefined();
+  });
+
+  it("updates options when registering the same hash twice", () => {
+    const catalog = new InMemoryIdempotencyKeyCatalog();
+
+    catalog.registerKeyOptions("hash1", { key: "key1", scope: "global" });
+    catalog.registerKeyOptions("hash1", { key: "key1-updated", scope: "run" });
+
+    expect(catalog.getKeyOptions("hash1")).toEqual({ key: "key1-updated", scope: "run" });
+  });
+
+  it("retains every entry regardless of count (no eviction)", () => {
+    const catalog = new InMemoryIdempotencyKeyCatalog();
+    const count = 5000;
+
+    for (let i = 0; i < count; i++) {
+      catalog.registerKeyOptions(`hash${i}`, { key: `key${i}`, scope: "global" });
+    }
+
+    // The very first entry must still be present — nothing is silently evicted.
+    expect(catalog.getKeyOptions("hash0")).toEqual({ key: "key0", scope: "global" });
+    expect(catalog.getKeyOptions(`hash${count - 1}`)).toEqual({
+      key: `key${count - 1}`,
+      scope: "global",
+    });
+  });
+
+  it("clear() removes all entries", () => {
+    const catalog = new InMemoryIdempotencyKeyCatalog();
+
+    catalog.registerKeyOptions("hash1", { key: "key1", scope: "global" });
+    catalog.registerKeyOptions("hash2", { key: "key2", scope: "run" });
+
+    catalog.clear();
+
+    expect(catalog.getKeyOptions("hash1")).toBeUndefined();
+    expect(catalog.getKeyOptions("hash2")).toBeUndefined();
+  });
+});

packages/core/src/v3/idempotency-key-catalog/inMemoryIdempotencyKeyCatalog.ts

@@ -0,0 +1,25 @@
+import type { IdempotencyKeyCatalog, IdempotencyKeyOptions } from "./catalog.js";
+
+/**
+ * Maps an idempotency-key hash back to the original user-provided key and scope.
+ *
+ * The mapping is held for the lifetime of a single run: the worker clears it at
+ * each run boundary (warm starts reuse the process), so it never accumulates
+ * across runs. Within a run every registered key is retained regardless of how
+ * many are created, so the key/scope metadata is never silently dropped.
+ */
+export class InMemoryIdempotencyKeyCatalog implements IdempotencyKeyCatalog {
+  private cache = new Map<string, IdempotencyKeyOptions>();
+
+  registerKeyOptions(hash: string, options: IdempotencyKeyOptions): void {
+    this.cache.set(hash, options);
+  }
+
+  getKeyOptions(hash: string): IdempotencyKeyOptions | undefined {
+    return this.cache.get(hash);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+}

packages/core/src/v3/idempotency-key-catalog/index.ts

@@ -2,7 +2,7 @@ const API_NAME = "idempotency-key-catalog";
 
 import { getGlobal, registerGlobal } from "../utils/globals.js";
 import type { IdempotencyKeyCatalog, IdempotencyKeyOptions } from "./catalog.js";
-import { LRUIdempotencyKeyCatalog } from "./lruIdempotencyKeyCatalog.js";
+import { InMemoryIdempotencyKeyCatalog } from "./inMemoryIdempotencyKeyCatalog.js";
 
 export class IdempotencyKeyCatalogAPI {
   private static _instance?: IdempotencyKeyCatalogAPI;
@@ -24,11 +24,15 @@ export class IdempotencyKeyCatalogAPI {
     return this.#getCatalog().getKeyOptions(hash);
   }
 
+  public clear(): void {
+    this.#getCatalog().clear();
+  }
+
   #getCatalog(): IdempotencyKeyCatalog {
     let catalog = getGlobal(API_NAME);
     if (!catalog) {
-      // Auto-initialize with LRU catalog on first access
-      catalog = new LRUIdempotencyKeyCatalog();
+      // Auto-initialize on first access
+      catalog = new InMemoryIdempotencyKeyCatalog();
       registerGlobal(API_NAME, catalog, true);
     }
     return catalog;