diff --git a/docs/adr/005-cash-out-dispense-outcome.md b/docs/adr/005-cash-out-dispense-outcome.md index 22bc03a..121616a 100644 --- a/docs/adr/005-cash-out-dispense-outcome.md +++ b/docs/adr/005-cash-out-dispense-outcome.md @@ -246,9 +246,13 @@ rather than pausing it. Server: `cash_owed` and `dispense_unreported` are two new buckets on `StuckSettlementsResponse`. They are the only buckets whose meaning is *a customer is owed -money*, and they render first. Arrival in either bucket triggers the operator notification -path (whatever `notifyOperator` equivalent spirekeeper grows; at minimum the dashboard banner -— but the push is the point, and it belongs in the same transaction that writes the row). +money*, and they render first. Arrival in `cash_owed` or `partial_pending` sends the operator +a **NIP-17 gift-wrapped DM** (kind 14 → 13 → 1059) to their own LNbits-account pubkey, or to +`super_config.alerts_pubkey` when set — a note to self any NIP-46 client renders. It is signed +through the operator's signer (no key at rest), is best-effort (a failed publish is logged and +the report is still acked — the worklist is the durable record), and sets +`operator_notified_at` so a report resend never re-alerts. Not email, not NIP-04. +*(Implemented: spirekeeper `notify.py`, slice 2.)* Resolution closes **both** ledgers: @@ -256,11 +260,13 @@ Resolution closes **both** ledgers: to `remediated` via `remediateTransaction`. The machine sends a `report_dispense` for the remediation with `remediates_txid`, and the server moves the settlement from `cash_owed` to `pending` and distributes. -- **Off-machine settlement.** The operator paid the customer by hand. A new `settle_cash_owed` - operator action records provenance (free text, author, time) on the settlement, moves it to - `pending`, and publishes a `settle_transaction { txid, note }` operator op; the machine - applies it by setting `remediated_by` to the note and `status = 'remediated'`. Today there is - no way to record this at all, and the machine's ledger asserts the debt forever. +- **Off-machine settlement.** The operator paid the customer by hand. + `POST /settlements/{id}/settle-cash-owed` records provenance (free text, author, time) on the + settlement, moves it to `pending` and distributes **at the full amount** (the customer is + whole), and publishes a machine-wide `settle_transaction { id, at, txid, note }` operator op; + the machine applies it through `remediateTransaction(txid, "settled-off-machine::")`, + which only touches rows still in an error state, so re-delivery is harmless. Before slice 2 + there was no way to record this at all, and the machine's ledger asserted the debt forever. `PartialDispenseData` is pre-filled from the report's `bills` so the operator confirms a number the hardware produced rather than typing one.