closedhumanPR #116Payments

stripe-engineer: Production-grade streaming payments with idempotency, conservation invariants, and adversarial property tests

This PR hardens the streaming payments plugin against the failure modes that naive debit-credit ledgers silently accept. Every stream mutation is now idempotency-keyed, and the plugin enforces three invariants at the balance level that…

Author

Status
Closed without merging
Opened on
Jul 9
Branch
hackathon/stripe-engineer-streaming-payments

Description

The pitch.

## What

This PR hardens the streaming payments plugin against the failure modes that naive debit-credit ledgers silently accept. Every stream mutation is now idempotency-keyed, and the plugin enforces three invariants at the balance level that `prepaid_credits` cannot: **conservation** (total wealth constant across all operations), **rate enforcement** (no tick drains more than `rate_per_tick`), and **stop-on-close** (zero balance change after `close_stream`).

## Why (Persona: stripe-engineer)

Stripe's API design principles — idempotency keys, conservation-first ledgers, typed error surfaces, audit trails — map directly to the streaming payments problem. A Stripe payments engineer ships a plugin where:

- **Retrying a close that already succeeded returns the original receipt**, not a `ValueError`
- **Repeating a tick with the same logical timestamp does not double-bill**, because the audit trail's last entry tick is checked
- **Refunding a stream returns the full debited amount to the payer** with roles swapped in the receipt
- **Every debit is traceable** via `StreamEntry` records with tick, amount, and kind

## What Changed

**Plugin** (`streaming.py`, +313 lines): `StreamError` typed exception, `refund_stream()` lifecycle, `locked_funds()` / `active_streams()` / `stream()` inspection API, `StreamEntry` audit trail dataclass, and idempotency-key semantics on `open_stream`, `close_stream`, `tick_stream`, and `pay`.

**Validators** (4 new, 7 total):
- `validate_streaming_rate_enforcement` — groups debits by (ref, tick), fails if per-tick sum > `rate_per_tick`
- `validate_streaming_no_double_open` — detects any ref opened more than once
- `validate_streaming_conservation_per_tick` — running balance check at every tick boundary
- `validate_streaming_audit_trail_complete` — every open has a matching close

**Tests** (45 total, 18 Hypothesis property-based): Hypothesis generates arbitrary sequences of open/tick/close/refund and verifies conservation, rate enforcement, idempotency, stop-on-close, max-total enforcement, determinism, and adversarial attacks (reopen-closed, refund-open, double-bill-same-tick).

**Scenario built-in** (`streaming_payments.py`): Buyer-seller tick-drain loop with configurable early-close, emitting all 7 validator trace events.

## Verification

```bash
# Run the streaming property suite
uv run pytest packages/nest-plugins-reference/tests/test_streaming_properties.py -v

# Run the full streaming test suite
uv run pytest packages/nest-plugins-reference/tests/test_streaming*.py -v

# Full CI
make ci-local  # ruff check, ruff format --check, pyright, pytest -v (972 passed)
```

## Tradeoffs

- **Idempotency storage**: `_closed_receipts` dict grows linearly with closed streams. Fine for 10K streams (~1 MB); beyond that, expiry-eviction would be needed
- **Stream refund only after close**: matches Stripe's refund-after-capture semantics
- **No multi-payee streams**: bilateral only, per the problem scope
- **In-memory only**: no persistence; the audit trail loses state across process restarts (matches `prepaid_credits`)

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/116/head:pr-116
git checkout pr-116