[Reliability] transact/readTransact retry unbounded with no default ceiling

[s2x]

Context / Problem

The transaction retry loops spin while (true) and rely entirely on FoundationDB's on_error backoff to eventually throw on non-retryable errors:

src/Database.php:62-89,199-267

There is no library-level retry/time ceiling and no convenient way to set a default RETRY_LIMIT/TIMEOUT. A persistently conflicting workload can spin indefinitely.

Affected files / locations

• src/Database.php:62-89,199-267

Proposed approach

Document the unbounded retry behavior and provide an optional, configurable default retry limit and/or timeout applied to transactions created via the convenience helpers, without changing the default FDB semantics for users who do not opt in.

Acceptance Criteria

• Documentation updated/added (retry/timeout behavior and configuration)
• Unit test(s) added covering the configurable ceiling logic
• Functional test(s) added: a transaction that exceeds the configured limit fails deterministically
• Changelog entry added
• Post-implementation comment posted on this issue describing what was changed

Severity

Low

[s2x]

Implemented explicit bounds + throw fix for the unbounded retry loop. Summary:

New files:

• src/TransactionRetryLimitExceededException.php — library-level exception carrying the actual retry attempt count and elapsed wall-clock seconds. Inherits \RuntimeException (not FDBException, because the native FDB transaction never reported an error).
• tests/Unit/TransactionRetryLimitTest.php — 28 unit cases covering the configuration validation (positive, zero, negative ⇒ InvalidArgumentException), the pure Database::checkRetryLimit() predicate across the boundary matrix (attempts-only, time-only, both, neither, equality edges, precedence), and the exception's fields + default message pluralization.
• tests/Integration/TransactionRetryLimitTest.php — 6 integration cases that run against a live FDB cluster and confirm the loop in Database::runWithRetry() is wired up correctly: transact/readTransact/watch honour the attempt ceiling, the unrelated unconfigured-default preserves the historical unbounded semantics, the wall-clock ceiling terminates the loop, and FoundationDB::reset() clears both ceilings.

API additions on FoundationDB:

• defaultTransactionRetryLimit(int) / getDefaultTransactionRetryLimit() — attempt ceiling. 0 = unbounded (default), negative ⇒ \InvalidArgumentException.
• defaultTransactionTimeoutSeconds(float) / getDefaultTransactionTimeoutSeconds() — wall-clock ceiling in seconds. 0.0 = unbounded (default), negative ⇒ \InvalidArgumentException.
• Both ceilings are process-wide defaults; reset via FoundationDB::reset().

Database:

• New Database::checkRetryLimit() public static predicate (no FFI; tested in isolation).
• New private Database::runWithRetry() shared by transact(), readTransact(), and the four watch helpers. Replaces the previous while(true){try{…commit;return}catch(FDBException){onError}} pattern with the bounded loop. When neither ceiling is configured (default), the loop falls back to the historical while(true) behaviour so users who do not opt in get exactly the same semantics as before.

Docs: docs/transactions.md adds a 'Bounded retry' section explaining the configuration surface, why / how it differs from FDB's own per-transaction MAX_RETRY_DELAY / RETRY_LIMIT options (PHP-side budget is the outer guarantee), and an example exception handler. CHANGELOG entry at the top of [Unreleased] describes the contract end-to-end.

Default behaviour unchanged — 0 / 0.0 for both ceilings preserves the historical FDB semantics for users who do not opt in. Lim is green (composer lint), all 486 unit tests pass. Integration tests require a live FDB cluster (libfdb_c.so installed) and run in the project's Docker environment.