fix(idempotency): complete and delete the record acquired at operation start

[vishwakt]

Summary

Changes

IdempotencyHandler keeps a reference to the payload it hashes, and BasePersistenceLayer recomputed the idempotency key and validation hash from that payload on every call. If the wrapped function mutates its input (normalising a field, adding a processed flag), saveInProgress() hashes the original payload while saveSuccess() and deleteRecord() hash the mutated one, so they target a different key. The in-progress record stays INPROGRESS, an identical retry throws IdempotencyAlreadyInProgressError until it expires and can then re-run the side effect, failure cleanup deletes the wrong key, and with payload validation enabled an identical retry can fail validation. This applies to makeIdempotent, the decorator, and the Middy middleware, since all three pass the event by reference.

This binds record identity to the operation rather than the payload, the first approach suggested in the issue:

• BasePersistenceLayer.getRecordIdentity() resolves the idempotency key and payload hash for a payload. IdempotencyHandler calls it before attempting acquisition, so the identity is available both when a record is acquired and when the function runs without acquiring one (durable replay on an existing INPROGRESS record).
• saveInProgress(), saveSuccess(), and deleteRecord() accept an optional trailing options object, { identity }, and use the identity instead of hashing data again. The options shape leaves room for future settings without more positional arguments. Without it they behave exactly as before, so direct callers and custom persistence layers keep working. Public signatures are otherwise unchanged: saveInProgress() still returns Promise<void>, and existing overrides of all three methods still compile. An override of saveInProgress() that forwards only the original arguments still lands on the right record, because the payload has not been mutated at that point. An override of saveSuccess(data, result) or deleteRecord(data) that forwards only the original arguments discards the identity and can still hash a mutated payload, so the docs now recommend accepting and forwarding the whole options object unchanged in public-method overrides, and using the protected _putRecord / _updateRecord / _deleteRecord hooks for custom storage, which need no changes. BasePersistenceLayerInterface is updated to match, and the IdempotencyRecordIdentity and PersistenceOperationOptions types are exported.

Only the post-acquisition calls need the identity: getRecord() and processExistingRecord() run in the replay branch before the wrapped function executes, so the payload cannot have mutated yet.

Regression tests assert that completion (_updateRecord) and cleanup (_deleteRecord) carry the same idempotencyKey as acquisition (_putRecord) when the wrapped function mutates its input, that the stored payloadHash matches when a validated field is mutated, that the same holds during a durable replay where _putRecord rejects with IdempotencyItemAlreadyExistsError, and that a subclass overriding saveInProgress() as Promise<void> compiles and completes the right record. The mutation and replay tests fail on main with a different key or hash, and the override test fails to compile against the first revision of this PR. Unit tests for getRecordIdentity() and for the identity argument on each of the three methods are included. The idempotency unit suite passes (151 tests) with the 100% coverage gate.

Note on #5708

This is the direction the issue describes as replacing the prefix re-application in #5708: with the fully resolved key captured before acquisition, saveSuccess() and deleteRecord() no longer depend on idempotencyKeyPrefix being re-applied before each call. Both PRs touch IdempotencyHandler, so whichever lands second needs a small rebase. Happy to rebase either way, or to fold the configure() prefix reset from #5708 in here if that is preferred.

Issue number: closes #5715

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[svozza]

Great work @vishwakt, this turned out to be trickier than expect!