feat: schedule preview and off-cycle payouts

Two things an operator needs that the scheduler alone does not give them.

Preview draws a contract's calendar from loose terms — start date,
frequency, period count — with no employee or wallet required, because the
schedule is what an operator wants to sanity-check first and a mistyped
start date is cheapest to fix before anything is saved. The same shape is
available for a live contract, from its current position. Both return
`ends_on`: "12 monthly payments from 15 Jan" is far easier to verify
against "ends 15 Dec" than against a list of twelve dates.

pay-now settles the next period immediately and consumes it. Deliberately
one endpoint rather than two: "run it now, don't wait for the tick" and
"pay it early" are the same operation and differ only in whether today
happens to be the payday. It bypasses the back-dated skip — that guard
exists to stop a new contract firing surprise back-pay, and an operator
explicitly asking to pay is not a surprise — and it takes the same
per-contract lock as the scheduler, which is what that lock was added for.
The ledger row is returned even on failure, since a manual payout that did
not land is exactly when you want the reason.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018jy52j9GRZ6XKa1Zt21LLj

tests/test_payout.py

@@ -13,7 +13,13 @@ from datetime import date
 import pytest
 
 from ..models import ContractStatus, PayoutStatus
-from ..services import MAX_PERIOD_ATTEMPTS, PeriodOutcome, run_due_periods
+from ..services import (
+    MAX_PERIOD_ATTEMPTS,
+    LifecycleError,
+    PeriodOutcome,
+    pay_now,
+    run_due_periods,
+)
 from .conftest import make_contract
 
 
@@ -210,3 +216,44 @@ def test_a_failure_under_the_cap_leaves_the_contract_active(payroll_stub):
 
     assert payroll_stub.contract.status == ContractStatus.active
     assert payroll_stub.ledger[-1].attempt == MAX_PERIOD_ATTEMPTS - 1
+
+
+# --- off-cycle payout ------------------------------------------------------
+
+
+def test_pay_now_settles_the_next_period_before_its_payday(payroll_stub):
+    payroll_stub.contract = make_contract(
+        start_date="2026-12-01", created_at="2026-01-01"
+    )
+
+    payout = asyncio.run(pay_now(payroll_stub.contract))
+
+    assert payout.status == PayoutStatus.paid
+    assert payout.period_index == 0
+    assert payroll_stub.contract.periods_done == 1
+
+
+def test_pay_now_ignores_the_back_dated_skip(payroll_stub):
+    """`_settle` skips back-dated periods to stop a new contract firing
+    surprise back-pay. An operator explicitly asking to pay is not a
+    surprise, so pay_now goes straight to the transfer."""
+    payroll_stub.contract = make_contract(
+        start_date="2026-01-15", created_at="2026-05-01", backfill=False
+    )
+
+    payout = asyncio.run(pay_now(payroll_stub.contract))
+
+    assert payout.status == PayoutStatus.paid
+    assert payroll_stub.attempted == [0]
+
+
+def test_pay_now_refuses_a_paused_contract(payroll_stub):
+    payroll_stub.contract = make_contract(status=ContractStatus.paused)
+    with pytest.raises(LifecycleError):
+        asyncio.run(pay_now(payroll_stub.contract))
+
+
+def test_pay_now_refuses_an_exhausted_contract(payroll_stub):
+    payroll_stub.contract = make_contract(total_periods=2, periods_done=2)
+    with pytest.raises(LifecycleError):
+        asyncio.run(pay_now(payroll_stub.contract))