[sumedh-aerram]

Issue number:

closes #8724

Summary

Changes

Read DataRecord.idempotency_key from the sort key when DynamoDB uses a composite primary key. The partition key remains shared across operations; the sort key identifies the operation. This restores local-cache lookup of stored responses and gives response hooks and in-progress diagnostics the correct key.

Add public-decorator tests across simple and composite schemas, including a custom sort-key name, both conditional-write returned items and get-item fallback, both local-cache settings for hooks, cache replay without extra DynamoDB requests, and in-progress diagnostics. Update response-hook docs and its example. Existing tests and event fixtures remain unchanged. No storage schema, public signature or dependency changes are introduced.

User experience

Previously, replaying a record created elsewhere cached it under the static partition key and never found it by operation key. Hooks also reported the shared partition key. Replays now cache and report the operation's own key. Simple primary-key tables keep their existing behavior.

Verification

AI assistants (Claude and Codex) helped investigate and implement this change. Local commands were executed and output inspected during development.

• New tests on unchanged upstream implementation: 16 failed, 8 passed (simple-key controls). With the one-line fix: all 24 passed.
• All 24 new cases passed on Python 3.10.22, 3.11.17, 3.13.17 and 3.14.9; Python 3.12 full idempotency suite: 226 passed.
• Python 3.12 full gate make -k pr ty: exit 0, 4026 passed, 73 skipped, 10 deselected; all 10 performance tests passed. Ruff, mypy (949 source files), ty, docs lint, security and complexity checks passed. Pre-commit hooks were also run explicitly on every changed file, including the new tests, and passed.
• Tests use the existing API Gateway v2 event fixture, the public decorator and botocore Stubber. The issue explicitly requests these public API tests with no AWS resources needed. No live DynamoDB service was called. No cache-performance benchmark or latency claim is made.
• Full repository gates on runtimes other than 3.12 and end-to-end AWS tests have not been run. Final committed, clean-tree make -k pr ty repeated successfully (exit 0); make test-dependencies passed all 15 Nox sessions on Python 3.12.14 with newly recreated environments. Independent review found no blocking defects and separately reran the 24 focused public-API cases successfully. The worktree remained clean. Optional broader cache/key-schema coverage was suggested; no defect was reproduced and existing tests were preserved.

---

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

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[leandrodamascena]

Thanks for the PR and for filling in the verification section, that helps. Heads up that the review may take a few days: this goes into 3.41.0 and I review every PR against a real service before approving, one at a time. No need to rebase or ping in the meantime, I'll come back here.