fix(core): don't assume a 64-character idempotency key is pre-hashed on reset

[claude]

Requested by Matt Aitken · Slack thread

idempotencyKeys.reset() now honours an explicitly passed scope even when the key material happens to be 64 characters long.

Before: resetIdempotencyKey treated any 64-character string as an already-computed hash and sent it to the API verbatim. That short-circuit ran before the scope logic, so if your key material is itself a 64-character digest — a common pattern when you hash your own dedup identity — the scope you passed was silently discarded and the un-hashed material went on the wire. The server stores the hash, so the reset matched no run and returned 404 every single time. Key material of any other length worked fine, which made this look arbitrary.

After: a 64-character string is only passed through when there is evidence it is already a hash. Otherwise an explicit scope is honoured and the hash is derived, at any key length.

How

The pass-through now requires positive evidence rather than a length guess:

• the idempotency key catalog recognises the string, so it came from idempotencyKeys.create(), or
• no scope was passed, so there is nothing to derive a hash from and the length is the only available signal.

An explicit scope is an explicit request to derive the hash, so it is never short-circuited past.

Both existing behaviours are preserved:

1. A key from idempotencyKeys.create() is still forwarded unchanged (catalog hit), including when a scope is also passed — it is never hashed twice.
2. 64-character material passed straight to trigger() is stored un-hashed, and resetting it with no scope still sends it verbatim.

isIdempotencyKey is deliberately left alone: it applies the same length rule on the trigger path, but it is self-consistent there, and changing it would invalidate already-stored keys.

The attachedOptions?.key / attachedOptions?.scope fallbacks below the guard were unreachable — every catalog entry is a 64-character digest, so it always hit the short-circuit first — and re-deriving from them produces the identical hash anyway. They are removed rather than left as dead code.

---

✅ Checklist

• I have followed every step in the contributing guide
• The PR title follows the convention.
• I ran and tested the code works

---

Testing

New tests in packages/core/src/v3/idempotencyKeys.test.ts drive the real resetIdempotencyKey against a local HTTP server and assert on the exact value that reaches the wire — nothing is mocked. They cover:

• 64-character material + explicit { scope: "global" } resolves to the same value idempotencyKeys.create() produces (fails without this change)
• 64-character material + { scope: "run", parentRunId } derives the run-salted hash (fails without this change)
• a key from idempotencyKeys.create() is forwarded unchanged, with and without a scope
• a 64-character key with no scope is still forwarded unchanged
• ordinary short material is still hashed

pnpm run test ./src/v3/idempotencyKeys.test.ts --run   # 7 passed
pnpm run build --filter @trigger.dev/core              # clean
pnpm run format && pnpm run lint                       # clean

Reverting only the source change turns the two new scope tests red and leaves the three compatibility tests green.

---

Changelog

idempotencyKeys.reset() now works when your idempotency key is itself 64 characters long. Previously any 64-character key was assumed to be already hashed, so passing one along with a scope silently ignored the scope and the reset never found a matching run.

---

Follow-ups (not in this PR)

• docs/idempotency.mdx describes the idempotencyKey parameter of reset() as "the 64-character hash string" in one place while showing raw material plus { scope: "global" } a few lines later. Worth reconciling.
• No surface currently exposes the stored hash that the reset endpoint matches on — ctx.run.idempotencyKey, the run page and the idempotency_key query column all show the user-provided key. That is what leads people to send a value reset cannot match.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6016987

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 27 packages

Name	Type
@trigger.dev/core	Patch
@trigger.dev/build	Patch
trigger.dev	Patch
@trigger.dev/python	Patch
@trigger.dev/redis-worker	Patch
@trigger.dev/schema-to-json	Patch
@trigger.dev/sdk	Patch
@internal/cache	Patch
@internal/clickhouse	Patch
@internal/llm-model-catalog	Patch
@internal/metrics-pipeline	Patch
@trigger.dev/rbac	Patch
@internal/redis	Patch
@internal/replication	Patch
@internal/run-engine	Patch
@internal/run-store	Patch
@internal/schedule-engine	Patch
@trigger.dev/sso	Patch
@internal/tracing	Patch
@internal/tsql	Patch
@internal/dashboard-agent	Patch
@internal/sdk-compat-tests	Patch
@trigger.dev/react-hooks	Patch
@trigger.dev/rsc	Patch
@trigger.dev/database	Patch
@trigger.dev/otlp-importer	Patch
@internal/testcontainers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@6016987

trigger.dev

npm i https://pkg.pr.new/trigger.dev@6016987

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@6016987

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@6016987

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@6016987

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@6016987

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@6016987

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@6016987

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@6016987

commit: 6016987