feat: payout ledger with bounded retry

Closes the gap the scheduler commit left open: a failed payday was retried
indefinitely with nothing but a log line to show for it.

Every attempt — paid, skipped and failed — is now written to
payroll.payouts and exposed at GET /api/v1/payouts. Failures are in the
ledger, not only in the log, because "why did nobody get paid on the 1st"
is the question the ledger exists to answer.

Ledger rows are self-describing: each copies the terms in force at the time
(amount, currency, both wallets) instead of pointing at the contract, and
there is no foreign key to contracts. A payout has to still read correctly
after its contract is edited, and deleting a contract must not take its
history with it. This is the one place duplicating a contract field is
right — the contract holds what is true now, a payout holds what was true
then.

Retries are bounded at 5 attempts per period, after which the contract is
paused rather than the period abandoned. A payday that cannot be funded is
a fact somebody has to act on; dropping it silently is the one outcome
payroll must never produce. Pausing does not advance the position, so
resuming after topping up retries the same payday. The attempt count is
derived from the ledger rather than a column on the contract, so it
survives a restart and stays auditable.

Also restores the explanatory comments on the broad `except Exception`
handlers, which ruff's RUF100 stripped along with their now-unused noqa
directives.

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

migrations.py

@@ -47,3 +47,44 @@ async def m001_initial(db):
     await db.execute(
         "CREATE INDEX payroll.idx_contracts_employee ON contracts (employee_id);"
     )
+
+
+async def m002_payouts(db):
+    """The payout ledger — one row per attempt at one period.
+
+    Rows are self-describing (they carry the contract terms in force at the
+    time) so a payout still reads correctly after its contract is edited or
+    deleted. There is deliberately no foreign key to `contracts` for the
+    same reason: deleting a contract must not take its history with it.
+    """
+
+    await db.execute(f"""
+        CREATE TABLE payroll.payouts (
+            id TEXT PRIMARY KEY,
+            contract_id TEXT NOT NULL,
+            period_index INTEGER NOT NULL,
+            payday TEXT NOT NULL,
+            status TEXT NOT NULL,
+            attempt INTEGER NOT NULL DEFAULT 1,
+            amount_msat {db.big_int},
+            amount REAL NOT NULL DEFAULT 0,
+            currency TEXT NOT NULL DEFAULT 'sat',
+            employee_id TEXT NOT NULL DEFAULT '',
+            employee_wallet TEXT NOT NULL DEFAULT '',
+            source_wallet TEXT NOT NULL DEFAULT '',
+            payment_hash TEXT,
+            detail TEXT NOT NULL DEFAULT '',
+            created_at TIMESTAMP NOT NULL DEFAULT {db.timestamp_now}
+        );
+        """)
+
+    # Counting a period's prior failures runs on every failed attempt.
+    await db.execute(
+        "CREATE INDEX payroll.idx_payouts_period "
+        "ON payouts (contract_id, period_index);"
+    )
+    # The employee-facing payslip view filters on the destination wallet.
+    await db.execute(
+        "CREATE INDEX payroll.idx_payouts_employee_wallet "
+        "ON payouts (employee_wallet);"
+    )