test: pin batch region-error retry contract (#330)

[s2x]

Description

Implements #330 ([TEST-10]): pins the retry behaviour for region errors returned inside batch responses (RawBatchGetResponse/RawBatchPutResponse top-level region_error).

batchGetWithRetry() runs only the dispatch inside RetryExecutor::execute(); the region-error check happens in BatchAsyncExecutor's wait phase (CheckedGrpcFuture::waitForExecutor() → RegionErrorHandler::check()), outside the retry executor entirely. The pinned contract: a region error inside a batch response is not retried, does not switch the cached leader, and does not invalidate the region cache — it surfaces as a BatchPartialFailureException.

Changes

• testBatchGetNotLeaderInsideResponseIsNotRetriedSurfacesAsPartialFailure — NotLeader hint (store 2) inside the response drives exactly one RPC (no reissue), no cache invalidation, and a BatchPartialFailureException carrying a RegionException with the NotLeader hint, keyed by regionId
• testEpochNotMatchInsideBatchResponseIsNotInvalidatedEither — pins the multi-region fromCallable() waiter path: non-NotLeader region errors also surface without invalidation
• testBatchPutPartialFailureReportsWhichRegionsFailedAndDispatched — 3 regions, region 2 fails: getRegionErrors() keys identify region 2, all 3 regions dispatched before the wait-phase short-circuit, getTotalRegions() == 3
• testBatchGetSplitsIntoSubBatchesAtMaxBatchLimit — 600 keys in one region → exactly 2 RawBatchGet RPCs (512-key limit)
• testBatchPutSplitsOnByteSizeNotOnlyCount — 10 × ~2 KB pairs → exactly 2 RawBatchPut RPCs (16384-byte limit)
• testBatchGetWithDuplicateKeysDoesNotDuplicateRegionDispatch — 3 keys (2 duplicates) → exactly 1 RPC
• Because RawKvBatch hardcodes new Call(...), the region-error tests drive the exact wait-boundary composition RawKvBatch builds (CheckedGrpcFuture::fromGrpcFuture/fromCallable over a mocked \Grpc\Call) through BatchAsyncExecutor::executeParallel(); the split tests count dispatches via the getChannel mock against a dead channel
• RawKvBatch.php statement coverage: 15/352 (4.3%) → 220/348 (63%)
• CHANGELOG [Unreleased] Tests entry; learnings added to docs/helpers/faq.md

Closes #330

Changelog

• [TEST-10]: pinned with tests that region errors inside batch responses are not retried and do not invalidate the region cache — they surface as BatchPartialFailureException with per-region keys; auto-split limits (512 keys / 16384 bytes) pinned by dispatch counts; RawKvBatch.php coverage 4.3% → 63%. ([TEST-10] Pin the retry behaviour for region errors returned inside batch responses #330)

Code Review

• Pending subagent code review