feat: AsyncGuardedPayment (v0.2.0)

[amavashev]

Summary

Adds an async-context-manager variant of cycles_guard_payment for asyncio runtimes (FastAPI, anyio, OpenAI async SDK, etc.). The sync GuardedPayment remains unchanged and the entire v0.1.x contract is preserved.

Public API additions

• AsyncGuardedPayment class
• cycles_guard_payment_async(client, mandate, ...) factory

from runcycles import AsyncCyclesClient, CyclesConfig
from runcycles_ap2 import AP2Mandate, cycles_guard_payment_async

async def charge(mandate: AP2Mandate) -> None:
    async with AsyncCyclesClient(CyclesConfig.from_env()) as client:
        async with cycles_guard_payment_async(
            client, mandate=mandate, run_id="run_abc123", tenant="acme",
        ) as guard:
            psp_receipt = await psp.charge_async(mandate)
            guard.attach_receipt_fields(psp_ref=psp_receipt.id)

Implementation note

The async variant uses runcycles.AsyncCyclesClient for I/O; everything else (idempotency keying, mapping, validation, exceptions, receipt construction) is shared via the existing module-level helpers in mapping.py / _validation.py / receipt.py. So the two classes can't drift in subtle ways.

Behaviour parity with sync

Contract	Same path
AP2GuardDenied on DENY or failed reserve	✓
AP2DryRunResult on dry-run (body unreachable)	✓
AP2GuardCommitUncertain on post-PSP unknown outcomes (terminal codes / transport / 5xx / uncaught) — no auto-release	✓
AP2GuardCommitFailed on 4xx unrecognized commit rejection (release attempted, released + release_error populated)	✓
Auto-release on exception inside the body	✓
Idempotency-key derivation incl. open-mandate consume-once scope	✓
set_actual_micros type/range validation	✓
attach_receipt_fields / abort / RuntimeAuthorityReceipt	✓

Test plan

• 18 new async tests in tests/test_async_guard.py mirroring the sync surface — clean commit, dry-run, denial, release on exception, abort, all four commit-uncertain branches (5xx with/without body, transport error, exception during commit), 4xx commit-failed, set_actual_micros int64 validation, open-mandate scope routing
• All 110 sync tests still pass — no regressions
• ruff check . && ruff format --check . — clean
• mypy --strict runcycles_ap2 — 0 errors (8 files)
• pytest --cov=runcycles_ap2 --cov-fail-under=95 — 128 passed, 97.60% coverage
• python -m build — sdist + wheel build cleanly as runcycles_ap2-0.2.0
• CI green before merge

Out of v0.2 (still planned for v0.3)

• Multi-currency (still raises AP2CurrencyError on non-USD)
• payment.refund convenience helper
• Server-verifiable runtime-authority receipt (requires cycles-protocol signed-receipt field)

Release sequence after merge

1. Tag v0.2.0 and push → fires python-publish.yml workflow
2. Build job verifies pyproject.toml version (0.2.0) matches tag
3. Publish to PyPI (trusted-publisher OIDC, already configured for v0.1.0)
4. Create GitHub release from CHANGELOG body

[amavashev]

Audit follow-up pushed (3ae0b94)

Per the self-audit, the async test surface was thinner than sync — covered the major paths but missed several regression locks that the sync tests already enforce. Also found four small doc/comment drifts between the two classes. None functional; all parity.

11 new async regression tests

Test class	New tests
TestAsyncCleanCommit	set_actual_micros_negative_rejected, set_actual_micros_rejects_non_int_types (parametrized: bool/float/str/None/list)
TestAsyncReleaseOnException	value_error_uses_exception_type_in_key
TestAsyncDenial	missing_reservation_id_raises_guard_denied (protocol-violation path)
TestAsyncDryRun	dry_run_deny_raises_guard_denied_not_dry_run_result, dry_run_result_carries_caps_and_scopes, non_dry_run_does_not_set_flag
TestAsyncCommitUncertain	reservation_finalized_raises_uncertain (third terminal code), commit_5xx_without_body_uses_synthetic_code
TestAsyncCommitFailed	commit_failed_records_release_transport_failure, commit_failed_records_release_non_success
TestAsyncFromAp2EndToEnd (new)	from_ap2_shape_flows_through_async_guard

Doc drift fixes in guard.py

• Module docstring now covers both sync and async classes (was "Sync context manager wrapping...")
• AsyncGuardedPayment class docstring now enumerates the decision rules directly so help(AsyncGuardedPayment) shows the contract
• AsyncGuardedPayment.abort docstring picks up the "Use for late-discovered failures" tail
• AsyncGuardedPayment.__aexit__ picks up the NOTE comment about dry-run never reaching __aexit__

Gates after follow-up

• ruff check . && ruff format --check . — clean
• mypy --strict runcycles_ap2 — 0 errors (8 files)
• pytest --cov=runcycles_ap2 --cov-fail-under=95 — 146 passed, 99.20% coverage (up from 128/97.60%)
• python -m build — sdist + wheel build cleanly

No public API change. No wire-shape change. No exception or validation logic change.

PR #4 should now be ready for merge; CI re-run on the new commit.

[amavashev]

P1 + P3 fixes pushed (788d708)

Both findings addressed.

P1 — async commit cancellation now wrapped as commit-uncertain

asyncio.CancelledError is a BaseException on Python 3.8+, so the generic except Exception clause in async _handle_commit did NOT catch it. Reviewer reproduced this with an AsyncMock raising CancelledError: the raw exception escaped, no release was attempted, and the caller had no reservation_id / error_code despite the post-PSP unknown-outcome contract.

Fix: explicit except asyncio.CancelledError clause ahead of the generic Exception clause:

except asyncio.CancelledError as exc:
    raise AP2GuardCommitUncertain(
        f"AP2 commit cancelled mid-flight ... Commit may have reached Cycles before "
        f"cancellation; no release was attempted.",
        error_code="COMMIT_CANCELLED",
        reservation_id=self._reservation_id,
    ) from exc

Same post-PSP unknown semantics as the existing branches — no auto-release (commit may have settled), __cause__ chains the original CancelledError, caller's except AP2GuardCommitUncertain runs as a quick reconciliation step and the task still terminates after.

Sync path unaffected.

Public API addition (additive, on an existing exception): new error_code value "COMMIT_CANCELLED" on AP2GuardCommitUncertain. Documented in the class docstring + CHANGELOG entry.

New regression test: test_commit_cancellation_surfaces_as_uncertain — asserts the conversion, the chained __cause__, and that release is NOT attempted.

P3 — refreshed stale test counts

CHANGELOG.md and AUDIT.md v0.2.0 entries still cited the initial-commit numbers (18 new tests, 128 total). Updated to current: 147 total, 37 in test_async_guard.py, 99.20% coverage.

Gates

• ruff check . && ruff format --check . — clean
• mypy --strict runcycles_ap2 — 0 errors (8 files)
• pytest --cov=runcycles_ap2 --cov-fail-under=95 — 147 passed, 99.20% coverage
• python -m build — sdist + wheel build cleanly as runcycles_ap2-0.2.0

No wire-shape change. No validation change.

[amavashev]

Doc parity for COMMIT_CANCELLED pushed (3909133)

Three public-facing doc spots were still stale after the previous commit added COMMIT_CANCELLED. All fixed:

Spot	Fix
README async note (line 101)	"raises the same exceptions under the same conditions as sync" → now adds "plus one async-only condition: an asyncio.CancelledError landing while the commit POST is in flight is wrapped as AP2GuardCommitUncertain(error_code=\"COMMIT_CANCELLED\") with the original cancellation chained via __cause__"
README lifecycle table (line 123)	Scenario column includes asyncio.CancelledError (async only); error_code enumeration includes COMMIT_CANCELLED (async only)
README exception table (line 219)	AP2GuardCommitUncertain row covers COMMIT_CANCELLED (async only) with the chained __cause__ contract
CHANGELOG line 11	"Same exception contract" → "Same exception classes plus one async-only condition (cancellation mid-commit, see below)"
CHANGELOG line 17	"No exception or validation changes" was overbroad. Split into a new Changed (async-only) subsection recording the additive error_code value, plus a narrower Unchanged line scoped to wire shape, validation, and the sync API

No code change. Gates re-verified locally: ruff check clean, mypy --strict 0 errors, 147 tests pass.

[amavashev]

Docstring parity for COMMIT_CANCELLED pushed (07e93af)

Two internal docstrings still enumerated the post-PSP unknown-outcome list without the async cancellation path. Both fixed:

Spot	Fix
AsyncGuardedPayment.__doc__ (guard.py) — Decision rules bullet on post-PSP unknown outcomes	Now reads "terminal codes, transport, 5xx, uncaught exception, or an asyncio.CancelledError landing mid-flight" plus a sentence noting error_code="COMMIT_CANCELLED" and the chained __cause__
AP2GuardCommitFailed.__doc__ (exceptions.py) — the "this is NOT the right exception for unknown-outcome failures" paragraph pointing readers at AP2GuardCommitUncertain	List now includes "(async only) asyncio.CancelledError mid-flight"

Runtime behavior unchanged. AP2GuardCommitUncertain.__doc__ already documented COMMIT_CANCELLED from the original fix; these two were the last internal sources of truth missing the entry. Public README is current.

Gates: ruff check clean, mypy --strict 0 errors, 147 tests pass.