[v1.0] Bound and classify Windows atomic-replace retries #315

Goal

Retry genuinely transient Windows sharing/lock failures without imposing multi-second latency on permanent permission errors.

Background

Current _replace_with_retry() catches every PermissionError on Windows, retries up to 50 times, and sleeps with linear backoff:

The worst-case sleep before the final failure is:

0.005 * (1 + 2 + ... + 49) = 6.125 seconds

The code does not distinguish a transient sharing/lock violation from permanent access denied, a read-only destination, or another non-retryable permission condition. Managed metadata is written in the invocation lifecycle, so a permanent filesystem policy error can turn a fast actionable failure into an unexplained six-second stall. The only regression test covers one transient failure followed by success; it does not assert error classification or a maximum elapsed budget:

Scope

• Classify retryable Windows sharing/lock errors from winerror/documented platform signals.
• Fail immediately on permanent permission and path-policy errors.
• Replace attempt-count-only behavior with an explicit maximum elapsed budget.
• Make delay/clock behavior deterministic in tests and observable in debug diagnostics.
• Preserve atomic replacement and the old destination on failure.

Acceptance criteria

• Sharing/lock violations retry within a documented total deadline.
• Access denied and other non-retryable permission errors fail without sleeping.
• Worst-case retry latency is asserted in tests.
• Successful transient recovery, deadline exhaustion, and permanent failure retain correct temporary-file cleanup.
• Native Windows and mounted/network-filesystem cases are covered or explicitly documented.

Validation

Run focused fault-injection tests plus native Windows lifecycle and metadata persistence jobs.

Project fields

• Status: Backlog
• Priority: P2
• Area: Runtime
• Initiative: Adoption Polish
• Size: S

Ownership

• Assignee: @codeforester