feat(WHE-20): implement deterministic monthly settlement engine

docs/specs/HOUSEBOT-011-monthly-settlement-engine.md

@@ -0,0 +1,80 @@
+# HOUSEBOT-011: Monthly Settlement Engine
+
+## Summary
+
+Implement a deterministic monthly settlement use-case that computes per-member dues from rent, utilities, and shared purchases.
+
+## Goals
+
+- Compute per-member net due amounts deterministically.
+- Support utility split modes: equal and weighted-by-days.
+- Model purchase offsets where payer reimbursement reduces their due.
+
+## Non-goals
+
+- Persistence adapters.
+- Telegram command handlers.
+
+## Scope
+
+- In: pure settlement use-case logic and tests.
+- Out: DB writes, HTTP/bot integration.
+
+## Interfaces and Contracts
+
+- Input: `SettlementInput` from `@household/domain`.
+- Output: `SettlementResult` with per-member line breakdown.
+- Entry point: `calculateMonthlySettlement(input)` in application package.
+
+## Domain Rules
+
+- Use integer minor units only via `Money` value object.
+- Rent is split evenly among active members.
+- Utility split:
+  - `equal`: evenly among active members.
+  - `weighted_by_days`: proportional to `utilityDays` for each active member.
+- Purchase offset per member:
+  - `purchaseSharedCost - purchasePaid`
+- Net due:
+  - `rentShare + utilityShare + purchaseOffset`
+
+## Data Model Changes
+
+- None.
+
+## Security and Privacy
+
+- No PII required in settlement computation.
+- Uses internal typed member IDs only.
+
+## Observability
+
+- Explanations list on each line provides deterministic calculation fragments.
+
+## Edge Cases and Failure Modes
+
+- No active members.
+- Weighted utility split with invalid or missing day values.
+- Purchase payer not in active members.
+- Negative monetary inputs.
+- Currency mismatch across input values.
+
+## Test Plan
+
+- Unit:
+  - 3-member equal split with purchase offset.
+  - 4-member weighted utility split.
+  - 5-member deterministic fixture with multiple purchases.
+  - Invalid weighted utility day input.
+  - Invalid purchase payer.
+
+## Acceptance Criteria
+
+- [ ] Equal utility split default implemented.
+- [ ] Day-based utility split implemented.
+- [ ] Deterministic fixtures for 3-5 roommate scenarios.
+- [ ] Explicit errors for invalid settlement inputs.
+
+## Rollout Plan
+
+- Merge as dependency for bot command handlers and statement generation flow.