[P1][Review] Stop automatic replay of non-idempotent writes and honor explicit retry configuration

[karlwaldman]

Review-only / approval gate

No implementation, PR merge, package publication or production mutation until the owner approves the full sprint plan.

Evidence

Reviewed main 31b8d80686495c5d6dcac0846d6e5a2c8d4bce8b.

Both client.py and async_client.py retry timeout/transport/5xx failures without considering HTTP method or an idempotency contract. Subscription/webhook creates use these helpers. Server completion followed by a lost response can cause repeated writes. Separately, mocked constructor max_retries=0,retry_on=[] becomes 3 attempts and default statuses due to or defaults. Current main DOES already pass quota headers into RetryStrategy; do not re-file that fixed bug.

Preferred smallest change

Default ambiguous non-idempotent writes to one attempt unless a supported server idempotency contract is present. Use explicit None defaults; define/document whether max_retries counts attempts or retries without silently changing existing callers. Preserve caller intent for retry_on=[]. Keep the current durable-quota suppression.

Acceptance / negative-path tests

Simulate commit-then-timeout for POST creates: one send and clear ambiguous-outcome error; GET transient recovery still works. Sync/async/header-return paths agree; empty retry_on preserved; invalid counts fail clearly; explicit zero behavior documented/tested.

Risk and PR gate

High-risk write replay semantics; Saturday.
One focused issue PR; independent adversarial review must challenge deletion safety, public compatibility, failure recovery and whether a smaller deletion suffices. Include red/green test evidence and packed/installable artifact proof for any published SDK/MCP change. Merge only in the approved priority order after reviewer objections are resolved. Do not publish a breaking change as a patch. If already fixed at execution time, record evidence and skip without a cosmetic PR.

[karlwaldman]

Adversarial sprint admission — rank 15/70

Scheduled Saturday, 2026-09-05 (America/New_York) in the approval-gated seven-night plan. Planning only; no implementation or merge yet.

Narrow outcome: Stop ambiguous write replays; honor retry configuration.

Required issue → PR → independent review → ordered merge evidence

• Reproduce on the execution-day main and confirm exact files/callers; the review baseline was the current-main SHA recorded in this issue. If already fixed or unnecessary, record proof and close without a cosmetic PR.
• Record why deletion alone does or does not solve this; delete redundant code before adding a helper/guard/automation.
• A focused failing regression/fixture first where practical; test the relevant malformed, absent, stale, rejected or timeout path as well as success. No production customer mutations or raw-secret evidence.
• One independently revertible PR, containing the narrow correction and targeted tests; no unrelated cleanup. Explain public/API compatibility and rollback.
• Independent adversarial reviewer tests the failure case, challenges the assumptions and simpler alternatives, and resolves every blocking finding.
• Refresh against the actual merge base and rerun checks before merging in this plan's numbered order. Preserve all existing required checks; no bypass to hit ten.
• Link merge SHA plus approved deployed/published artifact and post-release proof where relevant; otherwise mark release pending rather than claiming shipped.

Risk window: High-risk window, including prerequisites to the related high-risk correction.

[karlwaldman]

Coverage-audit revision — current sprint admission

Plan v2: oilpriceapi-api#8015 supersedes earlier scheduling comments. Rank 17/70; Saturday, 2026-09-05, America/New_York. Friday/Saturday high-risk window.

Intended outcome: Stop ambiguous write replays; honor retry configuration.

Coverage ledger: #8056. Inventory/pattern screening is complete; exhaustive semantic/runtime sign-off is not. Before implementation, review the complete affected file set and callers, revalidate against current main, supply the missing negative-path proof, and retain prior scope corrections. Prefer deletion, then simplification; correct behavior needs no PR.

No implementation is approved yet. After Karl approves: focused reversible PR → independent adversarial review → passing affected checks → merge in plan order → separately approved release/publish and artifact/customer-path verification. Maximum ten planned slots per night, not ten forced merges. If the dated window elapses before approval, re-anchor the calendar rather than backdate execution.