fix(NODE-7430): throw timeout error when withTransaction retries exceed deadline

[tadjik1]

Description

Summary of Changes

Align withTransaction timeout behavior with the spec change from DRIVERS-3391: when retry attempts exhaust the timeout, enforce a deadline-based check. With CSOT (timeoutMS), throw a MongoOperationTimeoutError wrapping the last transient error as cause; without CSOT (legacy 120s), propagate the last error directly.
Please keep in mind, all the recent changes from https://jira.mongodb.org/browse/DRIVERS-3436 are incorporated in this PR as well.

Spec: https://github.com/mongodb/specifications/blob/master/source/transactions-convenient-api/transactions-convenient-api.md#sequence-of-actions

Notes for Reviewers

The makeTimeoutError helper mirrors the spec's makeTimeoutError pseudocode function. It also copies error labels from the cause, so callers can check hasErrorLabel('TransientTransactionError') on the timeout error itself.

What is the motivation for this change?

NODE-7430 / DRIVERS-3391

Release Highlight

Release notes highlight

Double check the following

• Lint is passing (npm run check:lint)
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[Copilot]

Pull request overview

This PR updates the driver’s withTransaction retry-timeout behavior to align with the transactions convenient API spec changes (DRIVERS-3391), ensuring that when the retry deadline is exceeded under CSOT (timeoutMS), the driver surfaces a timeout error rather than the last transient error directly.

Changes:

• Update ClientSession.withTransaction retry loop to enforce a computed retry deadline and throw a MongoOperationTimeoutError (CSOT) that wraps the last retry-triggering error as cause.
• Add/extend CSOT unified spec coverage for withTransaction timeout behavior, including retry scenarios with transient transaction errors.
• Add integration prose tests to validate legacy (non-CSOT) retry-timeout enforcement via mocked time progression.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
test/spec/client-side-operations-timeout/convenient-transactions.yml	Adds CSOT unified spec coverage for withTransaction timeout and introduces additional event assertions.
test/spec/client-side-operations-timeout/convenient-transactions.json	JSON equivalent of the above spec updates.
test/integration/transactions-convenient-api/transactions-convenient-api.prose.test.ts	Adds prose tests to validate the legacy 120s retry timeout behavior using a stubbed clock.
src/sessions.ts	Implements deadline-based retry timeout checks and introduces makeTimeoutError helper for CSOT wrapping behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[PavelSafronov]

Overall changes look good, just have some nit comments, but nothing blocking.

[dariakp]

@PavelSafronov @tadjik1 Can we address copilot's comments? They are on spec tests, but if we think they are valid, it's always an option to submit an improvement to the spec.

[nbbeeken]

LGTM, no functional concerns about that processTimeMS comment, it still satisfies monotonicity

outdated