feat: bound subscription lifetime with max_executions/expiry_time

[prodbycorne]

Summary

Closes #23. stellar_send subscriptions had no cap at all — no max_executions, no expiry_time — so a subscription created once and then forgotten (or one whose keeper went offline for a long stretch) runs indefinitely, and the module's own deliberate "advance by exactly one interval per call" anti-drift design means a keeper resuming after a long gap can rapid-fire catch up every missed interval in one burst.

This is an open-ended/investigation issue (labeled "spike"), so the PR states its resolution explicitly:

• max_executions: Option<u32> — a hard ceiling on total lifetime executions. Reaching it auto-deactivates the subscription (active = false), the same terminal state cancel_subscription already produces, so a capped-out subscription surfaces the familiar SubscriptionInactive on any further call. Some(0) is rejected at creation (InvalidMaxExecutions) since it could never run.
• expiry_time: Option<u64> — a ledger timestamp past which execute_subscription refuses to run, independent of max_executions. Unlike the cap, this does not auto-deactivate — matching PaymentRequest.expiry's existing behavior in this same codebase, every attempt past expiry gets the specific SubscriptionExpired rather than a generic "inactive" once discovered. Must be strictly after start_time at creation (InvalidExpiry).
• Catch-up burst semantics are deliberately left unchanged. The issue frames disallowing catch-up (skip-ahead instead) as a genuine, undecided tradeoff — it trades a burst-of-payments surprise for a skipped-payment surprise, and the module's existing anti-drift design already reflects a considered choice. Per the issue's own reasoning ("a bounded subscription makes an unbounded catch-up burst less concerning... than an unbounded one"), max_executions/expiry_time is the resolution: they bound the burst's damage without touching the cadence logic itself. Documented at length in the module doc comment in subscription.rs.

Both Subscription fields are Option-typed and both are None by default — an unbounded subscription (e.g. an indefinite payroll payment) is still a fully valid, intentional choice; the payer opts into a bound rather than having one imposed.

Test plan

• InvalidMaxExecutions on max_executions = Some(0).
• InvalidExpiry on expiry_time == start_time (would be created already-expired).
• SubscriptionExpired on a due-but-expired execution — isolated specifically from SubscriptionNotDue (the due-time gate alone would allow the call). Confirmed the subscription stays active afterward (doesn't auto-deactivate on expiry, matching PaymentRequest).
• max_executions auto-deactivation end-to-end: still active after execution 1 of 2, auto-deactivates exactly on execution 2, and a 3rd attempt the schedule alone would permit correctly fails with SubscriptionInactive.
• test_execute_subscription_rapid_catch_up_multiple_calls (named per the issue's own testing-strategy ask): pins down the exact count for a known backlog — a 5-interval gap yields 6 successful rapid catch-up calls (the original due execution plus 5 more that individually came due), not 5, then a 7th is correctly refused.
• test_execute_subscription_max_executions_bounds_catch_up_burst: the same 5-interval/six-due-time backlog, but capped at 3 — auto-deactivates after exactly 3 executions (SubscriptionInactive, not SubscriptionNotDue) even though the backlog still has unclaimed due-times, proving the cap is what stopped it rather than the schedule running out on its own.
• All 3 pre-existing subscription tests updated for the new create_subscription signature and still passing.
• cargo build --workspace, cargo test --workspace (58 tests across all 4 contracts, 29 in stellar_send — up from 23), cargo clippy -p stellar_send --all-targets (zero new warnings — the 4 pre-existing ones are in send_path_payment/emit_path_payment_sent, untouched by this PR), and cargo fmt -p stellar_send --check (clean on every file this PR touches) all pass locally.
• This repository has no CI workflow configured (gh api .../actions/workflows reports 0), so there's nothing to gate on beyond the above local verification.

🤖 Generated with Claude Code