# Kvitt: specification

Version **0.40** (2026-10-24). Schema version **4**. Sync protocol version **1**. Push payload version **1**.

This file is the single source of truth for Kvitt. It is written for implementation agents that have no other context. If code, a plan or `CLAUDE.md` disagrees with this file, this file is right. Words in `code` are literal identifiers, paths, enum values or error codes and must be used exactly as written. Anything not decided here is listed in §12 as `TODO(spec)`; do not invent a value for it.

Conventions used throughout:

* "Owner" is Jacob, the admin user. "Partner" is the other user. "User" is either of the two.
* "Öre" is 1/100 SEK. All money is an integer number of öre.
* "bp" is basis points. 10000 bp is 100 %.
* Timestamps are RFC 3339 UTC strings in exactly this form: `2026-10-17T06:00:00.000Z` (millisecond precision, literal `Z`). This form sorts correctly as a string.
* Dates without time are ISO 8601 `YYYY-MM-DD`. Months ("periods") are `YYYY-MM`. ISO weeks are `YYYY-Www` with the ISO week-numbering year (week starts Monday).
* Ids are UUIDv7, lowercase, hyphenated, 36 characters, stored and sent as strings.
* JSON keys are `snake_case`. Enum values are lowercase `snake_case` strings.
* "Must", "must not" and "may" are binding.

---

## 1. Overview & goals

Kvitt is a shared-expense app for one household of exactly two people living in Sweden: the owner and his spouse. It replaces Splitwise for them. It tracks who paid for what, who owes whom, and how the household spends money over time.

It consists of:

* A native Android app (Kotlin, Jetpack Compose) on two Samsung phones (Galaxy S26 and Galaxy S26+, Android 16). The app keeps a full copy of the household's data in a local Room database and works fully offline for expenses and settlements.
* A small Rust server (axum, SQLite) in Docker on a Raspberry Pi 3 at the owner's home, reachable at `https://<KVITT_PUBLIC_HOST>` (the default HTTPS port 443, D-124), where `KVITT_PUBLIC_HOST` is the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen, recorded in HANDOFF), through the owner's Nginx Proxy Manager on the Home Assistant Pi (D-120). The server stores the authoritative copy, syncs the phones, creates recurring expenses, sends push notifications, keeps an audit log and hosts the APK for in-app updates.
* A web client (D-129, §15): a React single-page app built into the server image and served by the server under `/app/`, for a browser on the owner's or the partner's computer. It has the app's features except the phone-only ones (pairing flow, push, offline use, in-app update), plus search, CSV export and keyboard shortcuts. It is online only.
* Card purchases (D-158, §9.12, FR-22): each user may connect their own payment card (at first the SJ Prio Mastercard) through the account-information service Enable Banking; the server reads that card's purchases and the card holder, and only the card holder, turns them into ordinary household expenses with a few taps. Read only: Kvitt never pays or moves money.

Goals for v1:

1. **G-1 Correct money.** Balances are exact to the öre and computed identically on phone and server, guaranteed by shared test vectors.
2. **G-2 Offline first.** Creating, editing and deleting expenses and settlements never waits for the network. Two weeks offline followed by a sync loses nothing.
3. **G-3 Flexible splitting.** Per-account default ratios (50/50 to start, configurable such as 60/40), custom ratios, exact amounts, or 100 % on one person.
4. **G-4 Clear settling.** One global balance, a per-account breakdown, and a settle-up flow that proposes how a payment is spread over accounts.
5. **G-5 Insight.** Monthly and weekly spending by category and by account, computed on the phone; averages, trends and a two-month forecast computed on the server (D-133).
6. **G-6 Trust.** Every change to an expense or settlement is visible as a timeline of who did what.
7. **G-7 Low-maintenance hosting.** One docker-compose stack on a 1 GB Raspberry Pi, nightly off-site backups, no cloud services except Firebase Cloud Messaging, Google Drive for backups and, for card purchases only, the account-information service Enable Banking (D-159).
8. **G-8 Bilingual.** Every user-visible string exists in Swedish and English. The phone's locale decides: Swedish when the device language is Swedish, English otherwise.
9. **G-9 History.** Six years of Splitwise history can be imported once, repeatably without duplicates.

---

## 2. Non-goals

Not in v1. Agents must not build any of these, even partially:

* Receipt photos or receipt scanning. Profile pictures are the only file upload.
* ~~Any card, bank, Spendwise or other financial-institution integration.~~ Revised by D-158: reading the purchases of the users' own payment cards through Enable Banking (account information only, §9.12, FR-22) is in scope. Still out: payments or transfers of any kind, bank accounts other than the connected cards, Spendwise, and any other provider than those in the card catalogue (E-36).
* Multiple currencies or exchange rates. All amounts are SEK. (The importer has a one-off conversion option, §4 FR-17.)
* Joint accounts, shared cards or "paid from the shared pot" as a payer. The payer is always one of the two users.
* More than two users, more than one household, user deletion.
* Passwords, password reset, email, SMS, OAuth sign-in.
* Play Store distribution.
* CSV or any other export, except the web client's CSV export of a filtered expense list (D-129, §15.7).
* ~~A web client. The only HTML the server serves is the invite landing page (§4 FR-2).~~ Revised by D-129: the web client of §15 is in scope; it is not a progressive web app and has no offline use. The server serves HTML for the invite landing page (§4 FR-2) and the web client under `/app/` (D-132).
* Server-side reporting beyond the advanced analytics of D-133 (§15.8): S-11 and S-12 stay computed on the phone.
* Debt simplification (meaningless with two users) and netting several accounts in opposite directions inside one settlement.
* Editing accounts, categories, recurring templates, profiles or invites while offline.
* Tablet, foldable or landscape-specific layouts of the Android app. Portrait phone only; landscape must not crash. (The web client is designed for the desktop, §15.1.)
* Widgets, Wear OS, iOS.
* In-app language picker in the Android app. The phone locale decides. (The web client has a language choice, §15.3.)
* Comments or chat on expenses.

---

## 3. Users & core user stories

### 3.1 Roles

| Role | Who | Count | Extra rights |
|---|---|---|---|
| `admin` | The owner | exactly 1 | Creates invites (partner and device), cancels invites, revokes any device |
| `member` | The partner | 0 or 1 | Revokes own devices other than the one in use |

Everything else (expenses, settlements, accounts, categories, recurring templates) is open to both users with identical rights. Either user may edit or delete anything the other created. Each user edits only their own display name and picture.

A user has one or more devices. v1 expects one phone each, but the model allows any number of devices per user without change.

### 3.2 User stories

* **US-1** As the owner I set up the server once from the command line and pair my phone with a one-time code.
* **US-2** As the owner I invite my partner with a link; my partner installs the app from the link, picks a name and a picture, and is paired.
* **US-3** As a user I add an expense in a few taps: amount, description, category, account; the split defaults to the account's ratio and the payer defaults to me.
* **US-4** As a user I record an expense my partner paid, so they do not have to.
* **US-5** As a user I split an expense differently: a custom ratio, exact amounts, or the whole amount on one of us.
* **US-6** As a user I see one number saying who owes whom overall, and the same per account.
* **US-7** As a user I settle up: I enter what I paid my partner, the app proposes which accounts it settles (oldest first), I adjust and confirm.
* **US-8** As a user I settle one account from that account's screen.
* **US-9** As a user I create expense accounts ("Vardag", "Huset", "Japan 2027"), give each a default ratio, and archive them when done.
* **US-10** As a user I set up a recurring expense (rent, streaming) that appears automatically each month.
* **US-11** As a user I see how much we spent per month or week, by category or by account, as a household total or as my share.
* **US-12** As a user I add and edit expenses on a plane or abroad without a connection, and everything syncs when I am back.
* **US-13** As a user I get a notification when my partner adds, changes or deletes something, and I can see in the expense who changed what.
* **US-14** As a user I am told when a new app version exists and install it from inside the app.
* **US-15** As the owner I import our Splitwise history once.
* **US-16** As the owner I can restore everything from a backup if the Pi dies.
* **US-17** As the owner I can remove a lost phone's access.
* **US-18** As a user I connect my own payment card with BankID once and then see my card purchases in Kvitt, updated by themselves, without typing them (D-158).
* **US-19** As a user I turn a card purchase into a household expense, or link it to the expense my partner already entered, in one or two taps, from the Kortköp tab or from an account (D-158).

---

## 4. Functional requirements (v1)

Each requirement has acceptance criteria (AC). An AC is satisfied only when a test (unit, integration, screenshot or instrumented) or a documented manual check in the milestone's gate demonstrates it. Limits and rules referenced as §9.x are stated only there.

### FR-1 Server bootstrap

The server starts with an empty database. The household is created from the command line on the Pi.

* AC-1.1 `kvitt-server bootstrap` on a database with no users creates an invite of kind `admin_setup`, prints its code (format §8.3), its landing link `https://<KVITT_PUBLIC_HOST>/i/<CODE>` (the base URL from `KVITT_PUBLIC_URL`), its expiry, and exits 0.
* AC-1.2 `kvitt-server bootstrap` on a database that has users prints `already initialized` to stderr and exits 2. It creates nothing.
* AC-1.3 Running `kvitt-server bootstrap` again before the first code is used cancels the previous `admin_setup` invite and prints a new one.
* AC-1.4 Accepting the `admin_setup` invite (FR-2) creates the `admin` user with the given display name and the first device, and returns a device token.
* AC-1.5 `GET /setup/status` returns `{"initialized": false}` before AC-1.4 and `{"initialized": true}` after.
* AC-1.6 `kvitt-server pair-device --user <user_id>` creates a `device` invite for an existing user and prints it like AC-1.1. This is the recovery path when the owner has lost every paired phone.

### FR-2 Invites and pairing

* AC-2.1 The admin creates a `partner` invite from Settings. It is refused with `household_full` when two users exist. Creating a new `partner` invite cancels any pending one.
* AC-2.2 The admin creates a `device` invite for either user from Settings (to pair a second phone).
* AC-2.3 An invite is single-use and expires 72 hours after creation. An expired, cancelled, used or unknown code is refused with `invite_invalid`; the response does not reveal which.
* AC-2.4 Accepting an invite takes the code, a device name and (for `admin_setup` and `partner`) a display name. It returns a bearer token, the kind of the accepted invite (`invite_kind`, D-086), the user, the device and the household's users. For a `partner` invite it creates the `member` user. On a first pairing the app asks for the display name on S-1 (§13.3); a partner confirms it on S-2 (AC-2.10) (D-050).
* AC-2.5 `GET /i/<CODE>` serves an HTML landing page in Swedish if the request's `Accept-Language` prefers `sv`, English otherwise. It shows: the app name, "Download Kvitt" linking to the latest APK (FR-16), an "Open in Kvitt" button linking to `kvitt://invite?server=<urlencoded KVITT_PUBLIC_URL>&code=<CODE>` (followed by `&from=<urlencoded name>` when the request carries a valid `from` query parameter, D-087), the code in groups of 4, and one sentence of instructions (copy in §13.3, "Invite landing page"). It does not reveal whether the code is valid and contains no personal data of its own: the `from` name is only passed on into the `kvitt://invite` link and never shown on the page; an invalid `from` (not UTF-8 after percent-decoding, a control character, or more than 40 code points after trimming) is dropped and the page still opens (D-087). While no APK is published (E-5 would answer `not_found`) the page omits the download button. The page is sent with `Referrer-Policy: no-referrer` and `Cache-Control: no-store`. The 404 page (E-4 with a code outside 1 to 32 characters) shows only "Kvitt" and "404". Since the app gate (§8.5, D-126) the page opens in a browser only on the home LAN; from outside, a browser gets a closed connection, while the app opens the link (AC-2.6, `autoVerify="false"`, so no App Links check depends on the page).
* AC-2.6 The app opens from `kvitt://invite?server=…&code=…[&from=…]` and from `https://<kvitt.publicHost>/i/<CODE>[?from=…]` (the manifest placeholder `publicHost`, D-121; unverified link, the user may get a chooser; the intent filter names no port, so it matches every port of the host and an older `:8443` link still opens S-1 with the server it names; invite-link parsing drops an explicit default port, `:443` for `https` and `:80` for `http`, D-124) directly into the pairing screen with both fields filled. When the link names the inviting admin (`from`, E-12, D-087), S-1's help line names them (`onboarding_code_help`); links without a name (older links) still open, with the generic help line. The `https` link is declared with `android:autoVerify="false"`. An invite link opened while the phone is paired is ignored: the app stays where it is and never re-pairs over live data (D-084). A link may name any server: as built, S-1 opens its server row expanded when the link's server is not the release default (`RELEASE_SERVER_URL` = `https://<kvitt.publicHost>`, D-121, D-124), so the address is visible and editable before pairing; v1 adds no confirmation step for an unusual server (security review L-6, D-116; a confirm step would need a design state, OQ-6).
* AC-2.7 The pairing screen also accepts manual entry: a server URL (prefilled with `RELEASE_SERVER_URL` in release builds, D-121) and the code. Codes are normalised per §8.3 before sending.
* AC-2.8 Release builds accept only `https://` server URLs. Debug builds also accept `http://` for `localhost`, `10.0.2.2` and private LAN addresses (`10.*`, `172.16.*`-`172.31.*`, `192.168.*`). The limit is enforced in code by `SessionRepositoryImpl.normaliseServerUrl`, not by the network security config, which cannot express IP ranges (§8.5, D-082). A release build therefore pairs with any `https://` server a link or the user names; what S-1 shows then is in AC-2.6 (D-116).
* AC-2.9 After pairing, the app runs a full sync (§14.4) and then asks for the notification permission (Android `POST_NOTIFICATIONS`). As built (M8), the request is made after the first successful sync after pairing.
* AC-2.10 A `partner` pairing (E-3 `invite_kind` = `partner`, D-086) continues to a profile step (display name prefilled from the accept call, optional picture) before the Home screen. Every other pairing goes to Home, including a member pairing a second phone with a `device` invite.
* AC-2.11 The admin sees pending invites (kind, created, expiry) in Settings and can cancel each.
* AC-2.12 More than 10 failed invite accepts from one client IP within 60 minutes yield `rate_limited` for the rest of that window. A failed accept is any 4xx answer of E-3 other than 429. After the tenth failure, further accepts from that IP are refused with `rate_limited` until 60 minutes after the first counted failure; the window is fixed from the first counted request, not sliding (D-031).

### FR-3 Devices and revocation

* AC-3.1 Settings lists devices: the admin sees all devices of both users; a member sees their own. Each row shows device name, owner, paired date, last seen date, app version (the version name, "Kvitt 1.1", once the device has reported one, else the version code; D-090), and "This device" for the current one.
* AC-3.2 The admin can revoke any device except the one in use (`cannot_revoke_current_device`). A member can revoke their own devices except the one in use. A member who names a device of the other user gets `not_found`, the same answer as for an unknown id, so the answer does not tell whose the device is (D-156, security review L-10; implemented in `07c36d2`).
* AC-3.3 A revoked device's next request gets HTTP 401 `device_revoked`. The app then deletes its token, its local database and its cached pictures, and shows the "Device removed" screen with a "Pair again" button.
* AC-3.4 A revoked device never receives pushes again.
* AC-3.5 Devices are never deleted from the database; revocation sets `revoked_at` and clears the device's `fcm_token` (D-034).

### FR-4 Profiles

* AC-4.1 Each user has a display name (limits §9.6) and an optional profile picture.
* AC-4.2 A user edits their own display name in Settings (online only). The change reaches the other phone through sync.
* AC-4.3 A user sets their own picture from the Android photo picker (no camera capture in v1) or removes it. Upload is online only.
* AC-4.4 The server accepts JPEG, PNG and WebP up to 5 MiB and at most 8000 × 8000 pixels, and also at most 16 000 000 pixels (width × height, for example 4000 × 4000) decoding to at most 64 MB (16 MP × 4 bytes, so a 16-bit image is refused above 8 MP), checked from the image header before decoding with the decoder's limits set as well, else `image_invalid` (D-114); it applies EXIF orientation, centre-crops to a square, re-encodes as JPEG quality 85 at 512 × 512 and 128 × 128, strips all metadata, and increments the user's `picture_version` (the first upload is version 1; after a removal the next version follows the highest one ever used, §10.4, D-030). PNG and WebP transparency is flattened onto white (D-034). Other input is refused with `image_invalid`, `unsupported_media_type` or `payload_too_large`.
* AC-4.5 Where no picture exists, the app shows the user's initials (first letter of the first two words of the display name, uppercase) on one of two colour tokens, `avatar-1` and `avatar-2` (values in U2's `docs/ux/design-spec.md`). A user's slot is a stable function of the user id, so the same user has the same colour on both phones (D-052).
* AC-4.6 The app caches pictures on disk (Coil) keyed by user id and `picture_version`, so they show offline.

### FR-5 Household gate

* AC-5.1 Until the partner has joined, the admin's Home screen shows "Waiting for your partner" with the "Invite partner" action, and creating accounts, expenses, settlements and recurring templates is not offered. In that state `SettlementRepository.start` and `recompute` return null and `save` returns `SaveResult.Invalid` with a `payer` `validation_failed` error; nothing throws (§14.2.4, D-111).
* AC-5.2 The server refuses account creation, recurring template creation and any expense or settlement mutation with `household_incomplete` while fewer than two users exist. (The rule exists because every split refers to both users.)

### FR-6 Expense accounts

* AC-6.1 Either user creates an account (online) with a name and a default split ratio. The editor starts at 50/50. Ratios are entered as percent with up to two decimals per user, the second user's value always being 100 minus the first; stored as bp (§9.1).
* AC-6.2 Account names are unique among non-deleted accounts, compared case-insensitively after trimming (Unicode lowercase). A duplicate is refused with `name_taken`.
* AC-6.3 Either user renames an account or changes its default ratio (online). A ratio change affects only expenses created afterwards; existing expenses keep the shares they were saved with.
* AC-6.4 Either user archives or unarchives an account (online), even with a non-zero balance. Archived accounts are hidden from the account pickers for new expenses and recurring templates, shown in a collapsed "Archived" section on Home, still count toward the global balance, still appear in analytics and can still be settled. Hiding is a picker rule only: the server accepts archived accounts and categories in E-28 and E-29 (as it does in sync pushes, §9.10).
* AC-6.5 Either user deletes an account (online) only when no non-deleted expense, no allocation of a non-deleted settlement and no non-deleted recurring template references it. Otherwise `account_not_empty`. Deletion is a soft delete (tombstone) so phones learn of it through sync.
* AC-6.6 Accounts are listed by `created_at` ascending, the order used by the settlement proposal (§9.4).
* AC-6.7 The account create and edit actions are disabled with a "Needs connection" hint when the phone is offline (§9.9).

### FR-7 Categories

* AC-7.1 One global, editable category list. A category has a name, an icon token (§9.7) and a colour token (§9.7).
* AC-7.2 The database is seeded with exactly these fourteen default categories (fixed ids, §14.1; the four with `sort_order` 25, 45, 85 and 95 were added by migration 0002, §14.1.1, D-054), each shown with its localised default name until a user renames it:

| `default_key` | English name | Swedish name | `icon` | `color` | `sort_order` |
|---|---|---|---|---|---|
| `groceries` | Groceries | Mat & hushåll | `shopping_cart` | `green` | 10 |
| `restaurants` | Dining (D-067) | Restaurang & café | `restaurant` | `orange` | 20 |
| `housing` | Housing | Boende | `key` | `indigo` | 25 |
| `home` | Home | Hem | `home` | `brown` | 30 |
| `utilities` | Utilities | Räkningar | `bolt` | `yellow` | 40 |
| `insurance` | Insurance | Försäkringar | `shield` | `slate` | 45 |
| `transport` | Transport | Transport | `directions_car` | `blue` | 50 |
| `travel` | Travel | Resor | `flight` | `teal` | 60 |
| `entertainment` | Entertainment | Nöje | `movie` | `purple` | 70 |
| `health` | Health | Hälsa | `medical_services` | `red` | 80 |
| `children` | Children | Barn | `child_care` | `lime` | 85 |
| `shopping` | Shopping | Shopping | `shopping_bag` | `pink` | 90 |
| `fees` | Fees & taxes | Avgifter & skatter | `account_balance` | `amber` | 95 |
| `other` | Other | Övrigt | `category` | `grey` | 100 |

  `home` keeps furniture, supplies, maintenance, electronics and services; rent and mortgage belong to `housing` (D-054).

* AC-7.3 Either user creates a category (online) with a name, icon and colour. New categories get `sort_order` = the maximum `sort_order` over non-deleted categories + 10 (D-034).
* AC-7.4 Either user renames, re-icons, recolours or reorders a category (online). Renaming a default category stores the custom name; "Reset name" (only for default categories) clears it so the localised name shows again.
* AC-7.5 Either user archives or unarchives a category. Archived categories are not offered for new expenses or templates but stay on existing ones and in analytics.
* AC-7.6 A category is deletable only if no non-deleted expense or non-deleted recurring template uses it (`category_in_use` otherwise). Default categories (with a `default_key`) cannot be deleted (`category_is_default`); they can be archived. Deletion is a soft delete.
* AC-7.7 Category names have no uniqueness rule.

### FR-8 Expenses

* AC-8.1 An expense has: account, amount (öre), description, category, date, payer, split, notes, created-by, last-modified-by, timestamps. Limits in §9.6.
* AC-8.2 Either user creates, edits or deletes any expense, online or offline. The id is a client-generated UUIDv7.
* AC-8.3 The payer is either user. The editor defaults the payer to the current user.
* AC-8.4 The date is any date within §9.6 limits, past or future. It defaults to today in the phone's time zone. This date is the only date used in analytics and lists.
* AC-8.5 Split modes (enum §9.1): `default` (the account's default ratio, copied into the expense when saved), `ratio` (a custom ratio), `exact` (exact öre per user), `full` (the whole amount borne by one chosen user, who may be the payer or not). Share computation per §9.1.
* AC-8.6 The editor defaults: account = the account last used on this phone if still active, else the oldest active account; category = the category suggestion of §9.11 for a new expense, whose last step is the category last used in that account on this phone if still active, else `other` (D-049); when `other` is archived too and no active last-used category exists, the editor shows no category until the user picks one (v0.9); editing an existing expense keeps its category; split mode `default`. On the web "this phone" means this browser (`localStorage`, D-147).
* AC-8.7 Exact mode: the user types one user's share; the other user's share is the amount minus it and is shown read-only. A typed share larger than the amount blocks saving with an inline error.
* AC-8.8 Changing the account of an expense in mode `default` re-copies the new account's ratio. In other modes the split is kept.
* AC-8.9 Deleting asks for confirmation and is a soft delete. Deleted expenses disappear from lists, balances and analytics on both phones after sync.
* AC-8.10 Expense lists show, per row: category icon and colour, description, date, amount, and a one-line effect from the viewer's side ("You lent 205,00 kr", "You borrowed 205,00 kr", "Not involved" for `full` on the payer, matching §13 copy; Swedish "Du lånade ut 205,00 kr", "Du lånade 205,00 kr", "Inte inblandad", D-052). Rows are ordered by date descending, then `created_at` descending.
* AC-8.11 An expense created from a recurring template is an ordinary expense in every way (editable, deletable) and shows "Recurring" with the template name in the detail view.

### FR-9 Recurring expenses

* AC-9.1 Either user creates, edits, pauses, resumes or deletes a recurring template (online). A template holds the expense fields (account, amount, description, category, payer, split mode and shares, notes) plus `day_of_month` (1-31), `start_period` and an optional `end_period`.
* AC-9.2 The server creates one expense per template per period at 06:00 Europe/Stockholm on the template's day. Days 29, 30 and 31 clamp to the last day of shorter months (day 31 in April creates on 30 April; day 29 in February 2027 creates on 28 February).
* AC-9.3 Generation rules (catch-up after downtime, idempotency, split resolution) are in §9.5.
* AC-9.4 Editing a template changes only expenses generated afterwards.
* AC-9.5 A generated expense that a user deletes is not recreated.
* AC-9.6 Each generated expense writes an audit entry with `source` = `recurring` and sends `recurring_expense_created` to every device of both users.
* AC-9.7 The template list shows each template's description, amount, account, day of month, paused state and next occurrence date (computed by the server, `next_occurrence_date`).
* AC-9.8 The editor's default `start_period` is the current month if `day_of_month` is today or later in the phone's time zone, else the next month. A new template's `day_of_month` defaults to today's day of the month, so the default `start_period` is the current month until the user picks an earlier day (D-072). The user may choose a `start_period` up to 12 months in the past (backfill) and any month in the future.

### FR-10 Balances

* AC-10.1 Home shows one global balance between the two users from the viewer's side: "<Partner> owes you X", "You owe <Partner> X" or "All settled up".
* AC-10.2 Home lists every active account with its balance in the same wording, and archived accounts in a collapsed section.
* AC-10.3 The account screen shows that account's balance and its expenses and settlements interleaved by date.
* AC-10.4 Balances are computed on the phone from the local database with the domain function of §14.5, include pending (unsynced) local changes, exclude deleted rows, and update immediately after a local write.
* AC-10.5 The global balance equals the sum of the per-account balances, archived accounts included.

### FR-11 Settlements

* AC-11.1 A settlement is a payment from one user to the other with an amount, a date, an optional note and one or more per-account allocations. Limits in §9.6.
* AC-11.2 The allocations' sum must equal the settlement amount. Each allocation is positive. An account appears at most once.
* AC-11.3 Global settle-up (from Home): the direction defaults to "the user who owes pays", the amount defaults to the absolute global balance (or empty when it is zero). The app computes the proposal with `propose_allocation` (§9.4, §14.5) and shows one editable row per proposed account plus "Add account" to add any other account (active or archived). The confirm button is enabled only when the allocations sum to the amount; the remaining difference is shown live.
* AC-11.4 Per-account settle-up (from the account screen) creates a settlement with exactly one allocation for that account; the amount defaults to the absolute account balance and the direction to "the user who owes in this account pays".
* AC-11.5 An allocation larger than the payer's current debt in that account is allowed (over-settling flips the account's sign) and is marked with a warning per row ("This settles more than is owed in <account>"). The confirm dialog repeats the warning.
* AC-11.6 Settlements can be created, edited and deleted (soft delete) offline, by either user, like expenses. When editing, the proposal and warnings are computed with the edited settlement excluded from the balances. An edited settlement opens with its saved allocation rows counted as edited by the user, so changing the amount keeps them; "Suggest again" (`settle_propose_again`, "Föreslå igen") re-proposes (D-074).
* AC-11.7 A settlement row in lists shows "<Payer> paid <Recipient> X" and the account count when more than one allocation exists. In an account's list (S-5) X is the settlement's allocation to that account, not the settlement total; everywhere else X is the total.
* AC-11.8 The server's `POST /settlements/proposal` returns exactly what the phone's `propose_allocation` returns for the same server state (verified by shared vectors). The phone always computes locally; the endpoint exists for parity tests and server-side tooling.

### FR-12 Audit log and timeline

* AC-12.1 The server appends an audit entry for every accepted create, update and delete of an expense or settlement, from the app, the scheduler or the importer. Entries are never updated or deleted.
* AC-12.2 An entry records entity type, entity id, action, source, actor user, actor device (null for scheduler and importer), client time of the change, server time, and a field diff (§14.4.7).
* AC-12.3 Audit entries reach both phones through sync pull.
* AC-12.4 The expense and settlement detail views show a timeline, newest last, one line per entry, such as "Anna created this · 3 Oct 14:02", "You changed the amount from 400,00 kr to 412,00 kr · 3 Oct 18:30", "Anna deleted this". Diffs show field names in the UI language; ids are resolved to names (accounts, categories, users).
* AC-12.5 A pending local change not yet synced shows as a last timeline line "Your change is waiting to sync".

### FR-13 Push notifications

* AC-13.1 When the server accepts a create, update or delete of an expense or settlement from a device of user U, it sends a push to every non-revoked device of the other user that has an FCM token. Types and payload in §14.6.
* AC-13.2 Recurring generation sends to every non-revoked device of both users.
* AC-13.3 The importer sends no pushes.
* AC-13.4 One `POST /sync` that produces more than 3 notifiable changes sends one `sync_batch` push instead of one per change.
* AC-13.5 The app shows the notification only after it has synced the change, built from local data in the phone's language (title and body copy in §13). If that sync fails within 20 seconds, it shows a generic text without amounts or descriptions.
* AC-13.6 Tapping a notification opens the detail view of the changed expense or settlement (S-8 or S-10). It opens Home for deletions, for `sync_batch` and for the generic notification (shown when the sync failed or the entity or its actor is missing locally) (D-085).
* AC-13.7 The app registers for push by Firebase Installation ID (D-083): it calls `register()` whenever it is paired and at each app start while paired, and every id Firebase hands to `onRegistered(fid)` is sent as `fcm_token` with `PUT /devices/current/push-token` (E-17). The server sends pushes to that id in the FCM HTTP v1 `message.fid` field (§14.6, D-096). When the device is revoked (AC-3.3) the app calls `unregister()`. A failed E-17 send (network error, 429, 5xx) is kept and sent again after each successful sync until the server accepts it; a newer id from `onRegistered` replaces the kept one (`PushTokenRetry` in `:app`, D-112).
* AC-13.8 No personal content (names, amounts, descriptions, notes) is placed in the FCM payload.
* AC-13.9 Notifications are posted with `VISIBILITY_PRIVATE` and a public version carrying the generic text "Kvitt" / "Open Kvitt to see it" (`notif_generic_title`, `notif_generic_body`), so a secure lock screen shows no description, amount, account or name (security review L-7, D-116).

### FR-14 Analytics

* AC-14.1 Analytics (S-11, S-12) are computed on the phone from Room with the pure function of §14.5.4. They work offline and include pending local changes. Revised by D-133: the advanced analytics (per-category averages and trends per month, the two-month forecast per account) come from the server's `/analytics/*` endpoints (E-34 trends, E-35 forecast, rules §14.5.7, D-138), online only (§9.9), shown on the web (W-11) and in the app's Insights section on S-11 (W6, as built D-141 to D-143) (§15.8); the web client computes S-11 and S-12's equivalents in the browser with the same functions (§15.5).
* AC-14.2 Range presets: `this_month`, `last_3_months`, `last_6_months`, `last_12_months`, `this_year`, `all_time`, `custom` (start and end date pickers). "Last N months" means the current month and the N-1 months before it, whole months. Default `last_6_months`.
* AC-14.3 Granularity: `month` or `week` (ISO, Monday start). Default `month`.
* AC-14.4 Measure: `household` (sum of full expense amounts, whoever paid) or `my_share` (sum of the viewer's shares). Default `household`.
* AC-14.5 Group by: `category` or `account`. Default `category`.
* AC-14.6 Charts: (1) spend over time, a stacked bar per bucket coloured by group; (2) category breakdown for the range, horizontal bars sorted by amount descending with amount and percent; (3) account breakdown for the range, same form. A total for the range is shown above the charts. Settlements are never counted as spend.
* AC-14.7 Every bucket in the range appears, empty ones as zero. Buckets at the edges of a custom range count only dates inside the range.
* AC-14.8 Tapping a bar or a breakdown row opens a list of the expenses behind that number.
* AC-14.9 Deleted expenses are excluded; archived accounts and categories are included.
* AC-14.10 Percentages are rounded half-up to one decimal and may not sum to exactly 100.
* AC-14.11 A drill-down for one category or account over the range shows its spend per bucket as a line chart (every bucket, empty ones as zero), the range average as a dashed reference line, a trailing moving average over 3 buckets, and a caption comparing the latest whole bucket with the average in whole percent; its range and granularity can be changed on the drill-down without changing S-11 (D-128).

### FR-15 Offline and sync

* AC-15.1 The phone holds a full local copy of: users, accounts, categories, recurring templates, expenses, settlements and audit entries (Room, §14.2).
* AC-15.2 Expenses and settlements can be created, edited and deleted offline. Accounts, categories, recurring templates, profile, pictures, invites and devices need the server; their actions are disabled offline with "Needs connection".
* AC-15.3 Sync runs on app start and every return to the foreground, 2 seconds after the last local write (debounced), every 15 minutes in the background through WorkManager (network constraint), and on every FCM data message (expedited one-off work, waited for up to 20 seconds, AC-13.5). A pull-to-refresh on Home (S-4) or account detail (S-5) also runs a sync, the same call as S-16 "Synka nu" (D-127). Only one sync runs at a time. WorkManager names in §14.4.1 (D-028).
* AC-15.4 The app shows a "Last synced" relative time and a pending-changes count on Home, and a sync status screen (§13).
* AC-15.5 Conflicts resolve by last-write-wins per row on the client `updated_at`, deletes are final, and rejected changes are shown to the user (§14.4).
* AC-15.6 A phone offline for 14 days with 200 local changes syncs all of them on reconnect (integration test with a scripted clock).

### FR-16 In-app update

* AC-16.1 The server hosts the latest signed release APK and its metadata (§10.6).
* AC-16.2 Release builds call `GET /apk/latest` on every cold start and at most once per 6 hours while resumed (the manual check of AC-16.6 skips this throttle, D-140). When `version_code` is greater than the installed one, Home shows an "Update available" banner with the version name.
* AC-16.3 "Update" downloads the APK to the app's cache, verifies the size and SHA-256 from the metadata, and installs through `PackageInstaller`. The first time, Android asks the user to allow "Install unknown apps" for Kvitt; the app explains this beforehand: `UpdateRepository` emits `UpdateState.NeedsInstallPermission` once (the explanation-shown flag in `prefs.preferences_pb`, §14.2.2), and the next `install()` proceeds to the system prompt. On Samsung phones Auto Blocker must be off for the install: with it on, the system installer refuses the APK (observed on both phones, 2026-10-24: turning it off let the update install; D-156). The owner turns it off for an update and back on afterwards; the D-155 blocked text (`update_install_blocked`) names Auto Blocker (AC-16.7).
* AC-16.4 A verification failure deletes the file and shows "Download failed, try again".
* AC-16.5 Debug builds never check for updates.
* AC-16.6 "Check for update" on S-22 calls `UpdateRepository.checkNow()` (D-140; `check()` before v0.30), which returns an `UpdateCheck` (D-092, revising D-073): `UpToDate` (nothing newer published; a 404 from E-5 counts as up to date) reports "You have the latest version" (`settings_about_up_to_date`, "Du har den senaste versionen"); `Failed` (no answer or another error) reports "Could not reach the server" (`common_could_not_reach_server`); `Available` shows the update banner. Debug builds report `UpToDate` without a request (AC-16.5). S-22 "Check for update" always calls `GET /apk/latest`, whatever the 6-hour throttle of AC-16.2 says, and restarts that window; the automatic checks on cold start and resume keep the throttle (D-140).
* AC-16.7 If the system installer refuses or fails the install, Home and S-22 show the Error banner "Kunde inte installera uppdateringen" (`update_install_failed`) with the reason (blocked by the phone's security settings, `update_install_blocked`, or the installer's own message) and "Försök igen", which downloads again; declining the system dialog shows "Uppdatera" again without an error (D-155). The cached APK is deleted once the installer answers.

### FR-17 Splitwise import

* AC-17.1 A one-off CLI `kvitt-import` (crate `kvitt-import`) imports Splitwise CSV exports, one file per Splitwise group, each into a Kvitt account named on the command line. Details §10.8.
* AC-17.2 Re-running the same import creates nothing new (stable import key, §10.8).
* AC-17.3 Splitwise categories map to Kvitt categories by the fixed table in §10.8; unknown names map to `other` and are listed in the summary.
* AC-17.4 Splitwise payments become settlements with one allocation.
* AC-17.5 `--dry-run` prints the summary (rows read, expenses, settlements, skipped duplicates, unknown categories, non-SEK rows, the reconciliation of §10.8) and writes nothing; it runs the whole import transaction and rolls it back, with the same exit status a real run would have (D-046).
* AC-17.6 Imported rows produce audit entries with `source` = `import` and no pushes.

### FR-18 Backups and restore

* AC-18.1 Every night at 03:30 Europe/Stockholm the backup sidecar writes a consistent SQLite snapshot and a pictures archive, gzips them and uploads them to the owner's Google Drive folder with rclone. Nothing on Drive is ever deleted or overwritten. Verified by the owner on 2026-10-24: the first backup on the Kvitt Pi ran and its snapshot pair is in the Drive folder (D-156, §11.4).
* AC-18.2 A restore drill following §10.9 restores a backup on the Pi and both phones then sync correctly, documented in `docs/validation/restore-drill.md`.

### FR-19 Localisation and formatting

* AC-19.1 Every user-visible string is a resource in `values/strings.xml` (English, the fallback) and `values-sv/strings.xml` (Swedish). No string literal appears in feature code. A lint or test in the Android gate fails on a key missing from either file. The APK carries only these two languages: `android/app/build.gradle.kts` sets `androidResources.localeFilters` to `en`, `sv` (G-8; `2bd6b58`), so libraries' translations into other languages are not packaged.
* AC-19.2 Money formatting per §9.8, dates per §9.8.
* AC-19.3 Category default names and every enum shown to users have strings in both languages.

### FR-20 Health

* AC-20.1 `GET /health` returns status, server version, schema version and a database check, unauthenticated, in under 100 ms on the Pi.
* AC-20.2 The docker healthcheck of the `server` service uses it.

### FR-21 Web client

The web client of §15 (D-129 to D-134). Its acceptance criteria:

* AC-21.1 `https://<KVITT_PUBLIC_HOST>/app/` serves the web client from the server image; every path under `/app/` that is not a file serves `index.html`, except a missing `assets/*` file, which is 404 `not_found` (D-135); without the web files (`KVITT_WEB_DIR` missing) `/app/*` is 404 `not_found` (§15.4).
* AC-21.2 A browser logs in with an invite code through E-3 like a phone pairs (any of the three kinds), as device `Web · <browser>`; the token is kept in `localStorage` and sent as a bearer token; the browser appears on Devices and can be revoked from another device (§15.2).
* AC-21.3 A 401 forgets the token and shows the login page; `device_revoked` adds the S-18 message. Log out forgets the token and says that the browser stays on Devices until revoked.
* AC-21.4 Every page of §15.6 shows the server's current data: the household snapshot is pulled from `GET /sync` on load, on window focus and after every write; nothing but the token, the language choice and per-viewer conveniences survives a reload (§15.5).
* AC-21.5 Writes go to the server at once (`POST /sync` for expenses and settlements, REST for the rest); a failed write changes nothing and keeps the form's values; nothing is queued.
* AC-21.6 The web's money functions pass the vector files of §14.5.2's functions; its analytics functions pass `resolve_range.json` and `spend_series.json`; its category suggestion passes `suggest_category.json` (§15.3).
* AC-21.7 Swedish when the browser prefers Swedish, English otherwise; a choice on W-13 overrides it in that browser; every string exists in both languages.
* AC-21.8 From 720 px wide the layout has a sidebar; under 720 px one column with a bottom bar, usable at 360 px; light and dark follow `prefers-color-scheme`.
* AC-21.9 `N` opens a new expense, `/` the search, `?` the shortcut help, `Esc` closes the open dialog or editor; `N`, `/` and `?` do nothing while typing in a field.
* AC-21.10 Search finds non-deleted expenses by text in the description or notes, filtered by amount range, date range, account, category and payer; the filtered list exports as a CSV file (§15.7).
* AC-21.11 Accessibility as §13.1, for the web: every action reachable by keyboard with a visible focus, a label for every icon-only control, text contrast at least 4.5:1, nothing conveyed by colour alone, semantic headings and landmarks.
* AC-21.12 No service worker and no web app manifest; nothing is loaded from another origin at run time (§15.2).

### FR-22 Card purchases

Each user may connect their own payment card; the server reads its purchases through Enable Banking and the card holder turns them into expenses (D-158 to D-176). Rules in §9.12 (CP-1 to CP-14); screens S-23 to S-27 (§13.3) and W-21 to W-23 (§15.6); endpoints E-36 to E-44 (§14.3.4). Its acceptance criteria:

* AC-22.1 Settings (S-13) has the row "Anslut kort" ("Connect card"), which opens S-24: the server's card catalogue (E-36), each card with its artwork. v0.35 has exactly one entry, `sj_prio_mastercard` (SJ Prio Mastercard, SEB Kort). A provider the server has no Enable Banking application for (CP-13) is listed as "Inte konfigurerat på servern" and cannot be tapped.
* AC-22.2 Tapping a card that is not connected opens S-25: the history choice (CP-3) and "Anslut med BankID". The app creates an authorisation attempt (E-37), opens the returned bank URL in a Custom Tab, and polls the attempt (E-38) while S-25 is open; the bank (BankID: app-to-app on the phone, QR on a computer) redirects to `/cards/callback` (E-39), whose page says the card is connected and links back to the app. Within 5 seconds of returning, S-25 shows "Kortet är anslutet" and opens S-23 (CP-2).
* AC-22.3 Only the card holder sees their connection and purchases. A device of the other user that names a connection or purchase id gets `not_found` (CP-11). Nothing about a card purchase is in `GET /sync`, the audit log, a push, S-11, S-12, E-34 or E-35 until it is turned into an expense, which is then an ordinary household expense in all of them.
* AC-22.4 The Kortköp tab (S-23, the second bottom destination, §13.2) lists the holder's purchases newest first, grouped by day, with the filters "Att hantera" (default), "Kopplade", "Ignorerade", "Alla"; pending purchases carry "Preliminär"; deposits and refunds (`credit`) appear only under "Alla" (CP-8). The list works offline from the phone's copy (§14.2.1).
* AC-22.5 The list updates by itself: the server fetches each active connection in the background at most 4 times per 24 hours (CP-4); "Uppdatera" and pull to refresh on S-23 ask the server for a fetch with the user present (CP-5); S-23 shows "Uppdaterad <relative time>" of the last successful fetch.
* AC-22.6 "Skapa utgift" on a purchase opens S-7 prefilled (CP-9): amount, description from the merchant text, the purchase date, the card holder as payer, the account, the category of §9.11 and the account's default split; "Spara" saves the expense and links the purchase to it. From the Kortköp list that is: tap the purchase, tap "Skapa utgift", tap "Spara".
* AC-22.7 The purchase sheet lists the household's existing expenses that match the purchase (CP-10, same amount, within ±3 days, not linked yet, entered by either user); one tap links. A row in "Att hantera" with exactly one match shows the chip "Koppla till <description>", which links in one tap.
* AC-22.8 "Ignorera" moves a purchase to "Ignorerade" (private, undoable with "Ångra" and "Sluta ignorera"); "Ta bort koppling" moves a linked purchase back to "Att hantera"; deleting a linked expense, by either user, moves its purchase back to "Att hantera" (CP-9).
* AC-22.9 Account detail (S-5) offers "Från kortköp" while the viewer has a connection: S-27 lists the viewer's purchases to handle, and one tap opens S-7 prefilled with that account.
* AC-22.10 The expense detail (S-8) shows the card holder, and only the card holder, the line "Från kortköp: <merchant>, <date>" with "Ta bort koppling".
* AC-22.11 From 14 days before the consent ends (`valid_until`, CP-6) S-23 shows "Kortanslutningen upphör <date>" with "Förnya med BankID"; after it ends, S-23 shows "Kortanslutningen har upphört", keeps the stored purchases, disables "Uppdatera" and offers "Förnya med BankID". Renewing keeps every purchase and its state.
* AC-22.12 "Koppla från" (S-26, with confirmation) revokes the session at Enable Banking, deletes the purchases neither linked nor ignored, and keeps the linked and ignored ones unless "Radera även kopplade och ignorerade köp" is ticked; expenses already created stay (CP-12).
* AC-22.13 Linking, unlinking, ignoring and "Skapa utgift" work offline on the phone; the link changes are kept on the phone and sent after the next successful sync push (CP-9). Connecting, renewing, "Uppdatera", the history setting and "Koppla från" need the server (§9.9).
* AC-22.14 No merchant text, amount, session id, authorisation code or `state` reaches a server log, an NPM log or a phone log (§8.7, D-163).
* AC-22.15 The web client (K3) has the same features: W-21 Kortköp, W-22 Anslut kort with BankID by QR in the browser, W-23 the connection's settings (§15.6).

---

## 5. Data model

This section explains the entities and their meaning. The exact server DDL is §14.1, the phone's Room entities §14.2, the wire JSON §14.3. Limits are in §9.6.

### 5.1 Entity overview

| Entity | Id origin | Synced to phones | Written by phones | Notes |
|---|---|---|---|---|
| User | server | yes (pull) | REST only, own profile | Exactly two in a complete household |
| Device | server | no | REST only | One per paired app install |
| Invite | server | no | REST only, admin | Single-use pairing code |
| Account | server | yes (pull) | REST only | Expense account, like a Splitwise group |
| Account default share | with account | yes (inside account) | REST only | One row per user, sums to 10000 bp |
| Category | server (defaults seeded with fixed ids) | yes (pull) | REST only | Global list |
| Recurring template | server | yes (pull) | REST only | Monthly generator |
| Recurring template split | with template | yes (inside template) | REST only | Shares for modes `ratio`, `exact`, `full` |
| Expense | client (UUIDv7) | yes (pull and push) | sync push | Soft delete |
| Expense split | with expense | yes (inside expense) | sync push | One row per user |
| Settlement | client (UUIDv7) | yes (pull and push) | sync push | Soft delete |
| Settlement allocation | with settlement | yes (inside settlement) | sync push | One row per account |
| Audit entry | server | yes (pull) | never | Append-only |
| Sync mutation record | server | no | never | Idempotency of pushes |
| Sync sequence, meta | server | no (epoch is sent in pull) | never | Global `server_version` counter, `sync_epoch` |
| Card connection (D-167) | server | the holder's phones only, through `GET /cards/sync` (E-40), never `GET /sync` | REST only, its own user | One per user and card provider; holds the Enable Banking session (server only) |
| Card purchase (D-167) | server (from the bank's transactions) | the holder's phones only, through E-40 | REST only (`PUT /cards/purchases/{id}`, E-44): link and ignore | Private to the card holder; `card_version` from `card_sequence` |
| Card auth attempt (D-162) | server | no | never (created by E-37) | Single-use `state` of one BankID connection attempt |
| Card sequence | server | no | never | `card_version` counter of card connections and purchases, separate from `server_version` |

Local-only phone tables: `sync_state` and `sync_rejections` (§14.2), and `card_sync_state` (§14.2.2, D-173).

### 5.2 Ownership of fields

* **`server_version`**: an integer from one global, strictly increasing sequence. Every insert or update of a synced row (users, accounts, categories, recurring templates, expenses, settlements, audit entries) takes the next value. Child rows (shares, splits, allocations) have none; a change to a child bumps its parent. Phones never set it.
* **`created_at`, `updated_at`** of expenses and settlements are set by the phone's clock at the time of the local write and are the last-write-wins key. For server-written rows (all others, and expenses created by the scheduler or importer) they are the server clock.
* **`created_by_user_id`** is set by the server from the authenticated device's user when it first stores the row, never taken from the client. `updated_by_user_id` and `updated_by_device_id` are set by the server on every accepted write.
* **`deleted_at`** marks a tombstone. Tombstones are kept forever on both server and phone and are synced like any other row.
* **`archived_at`** (accounts, categories) hides an item from pickers; it never affects money.

### 5.3 Money

* Amounts are integer öre in signed 64-bit integers (Kotlin `Long`, Rust `i64`, SQLite `INTEGER`).
* An expense's shares, one per user, always sum exactly to its amount.
* Ratios are integer bp per user summing to 10000.
* A user's **net position** in an account is: what they paid for expenses, minus their shares, plus settlement allocations they paid, minus settlement allocations they received. The two users' net positions always sum to zero. A positive net means the other user owes them that much. Formal definition §9.3.

### 5.4 Relationships

* An expense belongs to one account and one category, has one payer and exactly two splits (one per user), and optionally references the recurring template and period it was generated for.
* A settlement has a payer (`from_user_id`), a recipient (`to_user_id`) and one or more allocations, each to one account.
* An audit entry references one expense or settlement by type and id.
* A device belongs to one user. An invite of kind `device` targets one user.
* References from synced rows point only at rows that are never hard-deleted, so a reference always resolves on the server. On the phone a reference may be briefly unresolved during a pull (§14.2); the UI shows such a row only after its references resolve.

### 5.5 What is not stored

* No balances, totals or analytics are stored anywhere; they are always computed from rows.
* No exchange rates, no currencies (SEK is implicit).
* No passwords. Tokens and invite codes are stored only as SHA-256 hashes.

---

## 6. Architecture & stack

### 6.1 System view

```
 Samsung S26 (owner)            Samsung S26+ (partner)
 ┌──────────────────┐           ┌──────────────────┐
 │ Kvitt app        │           │ Kvitt app        │
 │ Compose UI       │           │                  │
 │ domain (pure)    │           │                  │
 │ Room (full copy) │           │                  │
 └───────┬──────────┘           └────────┬─────────┘
         │ HTTPS :443 (bearer token)     │
         ▼                               ▼
   router: external 443 ──► Home Assistant Pi :443   (already in place for Home Assistant, D-124; external 80 too, for Let's Encrypt)
 ┌──────────────── Home Assistant Pi ────────────────┐
 │ Nginx Proxy Manager (TLS, Let's Encrypt, D-120)   │
 └─────────────────────────┬─────────────────────────┘
                           │ plain HTTP over the LAN, :8080
                           ▼
 ┌──────────────────── Kvitt Pi: Raspberry Pi 3, docker compose ─────────────────────┐
 │ server (axum, :8080 published on the LAN) ──► /data/kvitt.sqlite (WAL)            │
 │ backup (sqlite .backup + gzip nightly ──► rclone ──► Google Drive)                │
 └───────────────────────────────────────────────────────────────────────────────────┘
         │ FCM HTTP v1 (service account)          ▲ Pi pulls images
         ▼                                        │
   Firebase Cloud Messaging ──► phones      owner's M4 Mac: build linux/arm64 images ──► Gitea registry
```

For card purchases (D-160) the server, and only the server, calls the Enable Banking API (`https://api.enablebanking.com`) over outbound HTTPS from the Kvitt Pi; the phones and the browser never talk to Enable Banking. The user's browser (a Custom Tab on the phone) visits Enable Banking's and the bank's pages for the BankID step and is redirected back to `https://<KVITT_PUBLIC_HOST>/cards/callback` (E-39, §10.5.2).

A browser running the web client (§15) reaches the same server the same way: HTTPS to NPM, which lets `/app/`, the invite accept and bearer-token requests through from outside the LAN (§8.5, D-130), and plain HTTP to the server, which serves the web client's files from its own image (D-132).

### 6.2 Android app

| Concern | Choice | Why |
|---|---|---|
| Language | Kotlin 2.x, latest stable | Owner's requirement |
| UI | Jetpack Compose, Material 3; Material 3 Expressive components where they are stable. The Material 3 artifact is pinned explicitly in the catalog (1.4.0 at M2b) alongside the Compose BOM. Against material3 1.4.0 only `ShortNavigationBar` of the Expressive set is public and used; every other Expressive API takes the fallback listed in D-064 (M6) | Native, modern, screenshot-testable |
| Min / target SDK | `minSdk` 36 (Android 16); `compileSdk` and `targetSdk` 37 (the latest stable API when M2b pinned them, in `libs.versions.toml`) | Both phones run Android 16; no legacy paths |
| Local DB | Room 3 (`androidx.room3`, 3.0.3 at M2b), KSP only, an `SQLiteDriver` with `androidx.sqlite:sqlite-bundled`, exported schema (D-012) | Full offline copy; migrations with tests |
| DI | Hilt. `:data`'s `DataModule` provides implementations only; the bindings of the `:core:model` interfaces to them live in `DataBindingsModule` (`@DisableInstallInCheck`), which `:app` includes in both variants through `di/AppDataModule.kt` in `src/main` (D-041, revised by D-081) | Standard, works with WorkManager and ViewModels |
| HTTP | Ktor client (OkHttp engine), kotlinx.serialization JSON | Kotlin-first, multiplatform-style DTOs |
| Background | WorkManager (periodic 15 min sync, expedited sync) | Survives process death, respects Doze |
| Dates | kotlinx-datetime | Allowed in pure modules (no `java.time`) |
| Images | Coil (Compose) with an auth header interceptor | Disk cache for offline avatars |
| Charts | Compose `Canvas` in `:core:design`, no chart library (D-063). Vico 3.3.1 cannot give the per-bar TalkBack nodes and tap targets, 2 dp segment gaps, corner radii on the whole bar (10/4 at M6; top 4, bottom 2 dp since D-097) and an axis gutter growing at 200 % that `docs/ux/design-spec.md` §3.10 requires. Vico was removed from the version catalog on 2026-10-18 (`a312758`); it was never used | The three charts are small; the design spec's accessibility rules need per-bar control |
| Push | Firebase Cloud Messaging (firebase-messaging 26.0.0 through the Firebase BoM 35.0.2, google-services plugin 4.5.0; registration by Firebase Installation ID, D-083), only inside `:adapter:fcm` | Free tier; vendor isolated per `CLAUDE.md` |
| Secrets | Android Keystore: an AES-256-GCM key (non-exportable) encrypts the device token; ciphertext in a private DataStore file | `EncryptedSharedPreferences` is deprecated |
| Build | Gradle with version catalog `android/gradle/libs.versions.toml`, Gradle daemon on JDK 25 (pinned), bytecode target Java 17. With AGP 9, `check` runs only the debug unit-test variant. `versionCode` and `versionName` come from the Gradle properties `kvitt.versionCode` and `kvitt.versionName`, defaulting to `1` and `dev` (§10.6) | Existing pin |
| Tests | JUnit, Compose screenshot tests with Roborazzi (1.76.0 at M2b) on Robolectric (4.17) with `@Config(sdk = [36])` (D-010), Room tests (DAOs and migrations) on Robolectric with the framework SQLite driver, migration tests built from the exported schema JSON rather than `room3-testing` (D-042), Ktor `MockEngine`, WorkManager's test `WorkManager` from `androidx.work:work-testing` (a `testImplementation` of `:data`, the same version as `work-runtime`, `c366fbd`). Unit tests run on JDK 25 with `--add-exports java.base/jdk.internal.access` and `--add-opens java.base/java.io` for Robolectric, set in `build-logic` for every Android module (D-013). `failOnNoDiscoveredTests` is off only for modules without `src/test` (the shells) and on everywhere else (D-014) | No mocking libraries (`CLAUDE.md`) |
| Typeface | The Material 3 default typeface; the app bundles no font file (D-020) | No licence step, no font resource |
| App icon | Adaptive launcher icon, vectors only (D-095): `android/app/src/main/res/mipmap-anydpi/ic_launcher.xml` with background colour `#9C5238` (the light theme's primary, `values/ic_launcher_colors.xml`) and foreground and monochrome layers (`drawable/ic_launcher_foreground.xml`, `drawable/ic_launcher_monochrome.xml`) drawing the `receipt_long` app mark at 48 dp, centred in the 108 dp canvas; the manifest's `android:icon` and `android:roundIcon` point at it, which clears lint `MissingApplicationIcon` | No raster assets; themed icons use the monochrome layer |

Module graph (directory `android/`):

| Module | Kind | Contents | May depend on |
|---|---|---|---|
| `:core:model` | pure Kotlin/JVM | Domain types (§14.5.1), analytics types (§14.5.4, package `se.hagstedt.kvitt.model.analytics`), `*State` classes, repository interfaces (§14.2.4) | kotlin, kotlinx |
| `:domain` | pure Kotlin/JVM | Split, balance, allocation, analytics functions (§14.5); test-vector tests | `:core:model` |
| `:core:design` | Android library | Built by M6 (`7730a31`) from `docs/ux/design-spec.md` §2 and §3: `KvittTheme`, tokens (`KvittColors`, `KvittShapes`, `KvittMotion`, which holds only the seesaw spring; navigation has no motion, D-108), typography, shared components (money text, avatar, category tile and pickers, balance header, sync pill, banners, charts drawn with `Canvas`, D-063; the ledger rows for expenses and settlements used by S-5, S-12 and S-16; the expense editor fields used by S-7 and S-19, D-019), `MoneyFormatter`, `DateFormatter`, the shared failure texts (`format/Failures.kt`: `FAILURE_NETWORK`, `commonFailureText`), the shared limits (`format/Limits.kt`: `BP_TOTAL`, `DISPLAY_NAME_MAX`, `DESCRIPTION_MAX`, `NOTES_MAX`, `FIRST_DATE`, `DAYS_AHEAD_MAX`, §9.6) and `savedSplitLabel` (S-8, S-16), shared strings (D-118). Its test fixtures (`src/testFixtures`, package `se.hagstedt.kvitt.design.testing`) are the shared test support of every Android module (D-118); they are not a module | `:core:model` |
| `:core:fakes` | Android library, used only by tests, screenshot tests and debug previews | Scenario-driven fakes of every repository interface (they call `:domain` for computed values so fakes never disagree with the real rules) | `:core:model`, `:domain` |
| `:data` | Android library | Room DB, DAOs, entities, Ktor API client and DTOs, sync engine, WorkManager workers, token store, repository implementations, APK updater | `:core:model`, `:domain` |
| `:adapter:fcm` | Android library | `FirebaseMessagingService`, registration by Firebase Installation ID (D-083), maps messages to `PushEvent` (`:core:model`, `model/Push.kt`, moved there by M12e, D-095) through `PushMapping`; `PushListener` stays in the adapter | `:core:model` |
| `:feature:onboarding` | Android library | Pairing, partner profile step, waiting for partner, device removed | `:core:model`, `:core:design` |
| `:feature:home` | Android library | Home (global balance, accounts), sync status, update banner | `:core:model`, `:core:design` |
| `:feature:account` | Android library | Account detail, account editor | `:core:model`, `:core:design` |
| `:feature:expense` | Android library | Expense editor, expense detail and timeline | `:core:model`, `:core:design` |
| `:feature:settle` | Android library | Settle up (global and per account), settlement detail and timeline | `:core:model`, `:core:design` |
| `:feature:analytics` | Android library | Analytics screen and drill-down list | `:core:model`, `:core:design` |
| `:feature:settings` | Android library | Settings hub, profile, categories, recurring templates, devices, invites, about | `:core:model`, `:core:design` |
| `:feature:cards` | Android library (D-173, K2) | Kortköp tab (S-23) with the purchase sheet, Anslut kort (S-24), connect (S-25), the connection's settings (S-26), "Från kortköp" (S-27), the card artwork (`CardArt`) | `:core:model`, `:core:design` |
| `:app` | Android application | `MainActivity`, navigation graph, Hilt wiring, deep links, notification channel and building, `Application` class | everything |

**Screenshot tests (D-010).** `roborazzi.test.verify=true` in `android/gradle.properties` makes every unit-test run, and so `check`, compare renders with the committed goldens. An intended change is re-recorded with `tools/gradle-serial.sh recordRoborazziDebug`, and every changed PNG is opened before committing. AGP's Compose Preview Screenshot Testing plugin was still alpha when M2b chose. Golden layout (D-098, M8c, revises D-066): three goldens per component sheet or screen state, `<name>_sv_light.png`, `<name>_sv_dark.png` and `<name>_en_light.png` (English covers string length, dark covers the theme; there is no `en_dark`), plus `<name>_sv_light_200.png` at 200 % font scale for the long states; `:app`'s `empty_screen_<light|dark>.png` are the only other names. The content is composed once and language, theme and font scale are switched through a configuration context, so Compose's non-linear font scaling still applies. Every capture renders at 1x density through the Robolectric qualifier `w411dp-h<height>dp-mdpi`, so a full screen of 411 × 891 dp is 411 × 891 px. Every committed PNG (goldens and the `docs/ux/` mock-ups) is compressed losslessly with `oxipng -o 4 --strip safe` before committing (`7c453d8`); Roborazzi verifies against the compressed files. Feature modules follow the same layout: each feature module has Roborazzi screenshot tests of its screen states with goldens in `src/test/screenshots/`, rendered full screen. A screen harness renders one more frame and idles the main looper before each capture; without that `:feature:home` and `:feature:account` captured the previous variant, so their committed `sv_dark` (and some `_sv_light_200` and dialog) goldens were one variant stale, fixed and re-recorded in `dc7a296` and `5b2ed37`. The reduction took the goldens from 1143 PNGs and 131 MB to 865 and 26 MB, the mock-ups from 36.8 to 26.0 MB, for a small repository on the home Gitea server. Since the Android overhaul (`c582363`, D-118) the harness is shared: `:core:design`'s test fixtures (`src/testFixtures`, package `se.hagstedt.kvitt.design.testing`) hold `Variant`, `TestClock`, `TestEnvironment`, `ScreenSnapshots` with the capture modes `Root`, `Screen` and `ScreenWhenIdle`, `MainDispatcherRule` and `withMain`, consumed as `testImplementation(testFixtures(project(":core:design")))`. Test fixtures are not a module, so the module graph below is unchanged; the architecture check rejects a module's test fixtures in any configuration other than a test configuration. The convention plugin `kvitt.android.screenshots` wires Roborazzi (plugin, `outputDir` `src/test/screenshots`) and the test libraries; feature build scripts carry no screenshot block.

**Hilt wiring (D-081, M8).** Both variants bind every `:core:model` interface to `:data`: `android/app/src/main/.../di/AppDataModule.kt` includes `DataBindingsModule` (D-041), and `AppBuildInfo` (defined in `:data`'s `di/DataModule.kt`, provided by `:app`'s `di/AppBuildInfoModule.kt`, §14.2.4) comes from `BuildConfig` in both variants and also carries `RELEASE_SERVER_URL` as `releaseServerUrl` (D-122). The debug fakes module (`a41f240`) and the release-only data module were deleted by M8; no Hilt module lives in `src/debug` or `src/release`. Fakes live only in test source sets and feature previews and never reach an installed build; `:app`'s unit tests run on a plain `Application`, not the Hilt application.

Features never call `:domain` directly: repositories return computed state (balances, previews, proposals), implemented in `:data` with `:domain`. The architecture check (Gradle task in `check`, owned by milestone M2b) fails the build on any other dependency edge and on `java.time`, `java.io` or `android.*` imports in `:core:model` and `:domain`.

**Feature convention (D-017).** Binding for every feature module (worked example and the stateless overload used by previews in `android/README.md`):

* Each feature exposes one composable entry point per screen. The entry point takes a ViewModel provided with `hiltViewModel()` and its navigation as plain lambdas (for example `onOpenExpense: (ExpenseId) -> Unit`, `onBack: () -> Unit`).
* Features never reference other features or the `NavHost`. `:app` owns the `NavHost` and connects the lambdas to routes.
* ViewModels receive repositories through the `:core:model` interfaces (§14.2.4). `:app` binds the interfaces through Hilt to `:data`; bindings to `:core:fakes` exist only in test and debug-preview source sets and never reach a release build.
* Shared UI that two features need is built in `:core:design` by M6 (D-019); a feature never copies another feature's component.
* Strings: `:app` holds only the app name; `:core:design` holds the shared strings (including the notification copy and channel name of §13.3 and §14.6, which `:app` uses); each feature module holds its own. Lint `MissingTranslation` is an error in every module. Keys of a feature module are prefixed by the feature name (`home_`, `account_`, `expense_`, ...); keys in `:core:design` never start with a feature name. This rule wins over any other key convention (§13.4, §14.7).

**Fakes.** Every fake in `:core:fakes` has at least the empty scenario (D-018): the household is complete (two named users, no pictures), there are no accounts, the categories are exactly the fourteen defaults of AC-7.2 (D-054), and there are no expenses, settlements, templates, rejections or pending changes. Feature agents add their own scenarios (§11.3).

### 6.3 Server

| Concern | Choice | Why |
|---|---|---|
| Language | Rust stable, edition 2024; the exact release pinned in `server/rust-toolchain.toml` (1.99.1 at M2a) and the same tag in the Dockerfile (§10.3) | Owner's requirement; small RSS on a 1 GB Pi |
| HTTP | axum on tokio (multi-thread runtime, 2 worker threads) | Mature, small |
| DB | SQLite via sqlx, WAL mode, migrations embedded with `sqlx::migrate!` | One file, easy backup, ample for two users |
| Serialization | serde, serde_json | Standard |
| OpenAPI | utoipa generates the document from code; `contracts/openapi.yaml` is the committed contract; a test asserts the generated document equals it (§14.3) | One contract, checked by the gate |
| Logging | tracing, tracing-subscriber, JSON lines to stdout | Docker log rotation; no personal content (§8.7) |
| Time | chrono with chrono-tz for Europe/Stockholm (M2a confirmed; no other time crate) | DST-correct scheduling |
| Ids | uuid crate, v7 | Same format as phones |
| Images | image crate (decode JPEG/PNG/WebP, encode JPEG) | Pure Rust, no system libs |
| HTTP client (FCM) | reqwest with rustls (crypto provider aws-lc-rs, certificates checked by the platform verifier); needs a C toolchain at build time and CA roots in the image (§10.3) | No OpenSSL on the image |
| FCM auth | Service-account JWT (RS256, jsonwebtoken crate, header `kid` = the key file's `private_key_id`) exchanged at `https://oauth2.googleapis.com/token` for an access token with scope `https://www.googleapis.com/auth/firebase.messaging`, cached until 5 minutes before expiry | HTTP v1 API needs OAuth2 |
| Scheduler | A tokio task inside `kvitt-server` (no extra crate) | One process, simple |
| Card purchases (D-160, K1) | `kvitt-server` module `src/cards/`: the provider registry (`providers.rs`), the `CardSource` trait and its one adapter `src/cards/enable_banking/` (the only code that names the vendor or reads its JSON; it maps it into Kvitt's own records), fetching and de-duplication (§9.12), the background poller (started from `src/tasks/`), the callback page; HTTP to Enable Banking through the existing reqwest client with rustls, JWTs signed RS256 with jsonwebtoken (both already in the stack) | Vendor isolated per `CLAUDE.md`; no new crate |

Cargo workspace (directory `server/`):

| Crate | Kind | Contents |
|---|---|---|
| `kvitt-domain` | library, no I/O | Money types, split, balance, allocation, settlement validation (§14.5), `next_occurrence_date` and the day clamping of §9.5 (D-015), test-vector tests. Depends only on `serde`; `serde_json` is a dev-dependency of the vector tests. Ids are plain strings (§14.5.1), so no `uuid` |
| `kvitt-server` | binary `kvitt-server` | Config, DB, migrations, HTTP API, auth, sync, audit, push, scheduler, pictures, APK, CLI subcommands (§10.4) |
| `kvitt-import` | binary `kvitt-import` | Splitwise CSV importer (§10.8). Depends on `kvitt-domain` and reuses `kvitt-server` as a library for DB access and audit writing (`kvitt-server` exposes a `lib.rs`) |

**Server seams (D-015).** So that M3, M4 and M9 work in parallel on M2a's skeleton:

* **Middleware in `router.rs` (M2a):** the `X-Kvitt-Protocol` check (426 `protocol_unsupported`), the `X-Kvitt-Server-Version` response header and the §8.6 body limits (1 MiB, 5 MiB for `PUT /me/picture`) are layers in `src/router.rs`. On authenticated routes the protocol check runs before the token check, so a request with a bad protocol header and a bad token gets 426, not 401. M3's rate limit (§8.6, AC-2.12) is a layer defined in `src/api/rate_limit.rs` and attached at one line in `router.rs` that M2a marks with a comment; that line is the only one M3 edits in `router.rs`.
* **Background tasks:** M2a creates `src/tasks/mod.rs` with a `start` function that `serve` calls once after migrations (initially doing nothing). M4 owns `src/tasks/**` and starts the scheduler, the push sender and the `sync_mutations` pruning from it. As M4 built it (D-039): `tasks::start` returns the `AppState` with the real push queue installed, and `serve` builds the router from that returned state. Since the server overhaul (`6c405e1`) it is a synchronous `fn start(AppState) -> AppState` (it never awaited or failed); D-039 holds.
* **Audit and push interfaces:** M2a defines the traits `AuditWriter` (in `src/audit/`) and `PushQueue` (in `src/push/`) with no-op implementations, and passes them through the application state (`AppState.audit`, `AppState.push`). M4 replaces the implementations (audit writer and diff of §14.4.7, FCM queue of §14.6); M3 and M9 only call the traits. Since M4 (D-039): `AppState::new` holds `SqlAuditWriter` by default and `NoopAuditWriter` no longer exists; `NoopPushQueue` stays as the queue when push is disabled (§14.6), and `tasks::start` installs the bounded `PushHub` otherwise. As M2a built them (exact signatures in `server/README.md`):
  * `AuditWriter::write` takes the caller's open connection inside its `BEGIN IMMEDIATE` transaction and one `AuditEvent` (entity type and id, action, source, actor user and device, `client_at`, `server_at`, and the wire object before the change, absent for a create, and after it, as JSON), and returns the new audit entry's id or an `AppError`. The writer derives `changes` (§14.4.7) and takes the entry's `server_version` from that same transaction.
  * `PushQueue::enqueue` takes one `PushMessage` (push type, one of the eight of §14.6; entity id or none; actor user id; count). It never blocks and never fails; callers call it after commit.
* **Recurring generation:** M2a implements `next_occurrence_date` and the day clamping in `kvitt-domain` (§14.5.2). M3 writes the one function that generates the due periods of one template (§9.5: candidate periods, one transaction per candidate, audit through `AuditWriter`, push through `PushQueue`) in `src/api/recurring.rs`, used by E-28 and E-29; M4's scheduler calls that function for every template. M4 therefore lands after M3 (it may start in parallel and rebases on M3 before its gate).

### 6.4 Why these choices

* **Phone computes balances and analytics.** Offline is a hard requirement and the data set is small (six years of two-person history is a few thousand rows). Computing on the phone keeps the server dumb and the Pi idle.
* **SQLite over Postgres.** Postgres alone would use a large share of the Pi's 1 GB. SQLite in WAL mode handles two users trivially and backs up as one file.
* **Global `server_version` sequence.** One integer cursor per phone is the simplest correct incremental sync. SQLite's single writer, with every write in a `BEGIN IMMEDIATE` transaction, makes versions commit in order, so a reader never sees a gap that later fills.
* **Last-write-wins on client time.** Two people rarely edit the same expense concurrently; LWW with an audit trail lets them see and fix the rare collision. Clock-skew protection is in §14.4.
* **Push carries ids only.** Personal data does not pass through Google; the phone syncs and builds the text locally.
* **No Play Store.** Two users; a self-hosted APK with `PackageInstaller` is enough.
* **Domain rules twice, one test suite.** Kotlin and Rust implement the same pure functions and must pass the same JSON vectors, so phone and server agree to the öre.

---

## 7. API outline

Base URL: `https://<KVITT_PUBLIC_HOST>` (the value of `KVITT_PUBLIC_URL`, port 443, D-124; `KVITT_PUBLIC_HOST` is the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen, recorded in HANDOFF), D-120). All paths below are relative to it. There is no path prefix and no API version in the path; the protocol version travels in a header (§14.3.1).

| # | Method | Path | Auth | Purpose |
|---|---|---|---|---|
| E-1 | GET | `/health` | none | Liveness and DB check; S-22 shows its `server_version` and `schema_version` (D-110) |
| E-2 | GET | `/setup/status` | none | Whether the household has been bootstrapped |
| E-3 | POST | `/invites/accept` | none | Pair a device with an invite code (all three invite kinds) |
| E-4 | GET | `/i/{code}` | none | Invite landing page (HTML) |
| E-5 | GET | `/apk/latest` | none | Latest APK metadata |
| E-6 | GET | `/apk/files/{file_name}` | none | APK download |
| E-7 | GET | `/me` | device | Current user, device and household users |
| E-8 | PATCH | `/me` | device | Change own display name |
| E-9 | PUT | `/me/picture` | device | Upload own picture |
| E-10 | DELETE | `/me/picture` | device | Remove own picture |
| E-11 | GET | `/users/{user_id}/picture` | device | Download a user's picture |
| E-12 | POST | `/invites` | admin | Create a `partner` or `device` invite |
| E-13 | GET | `/invites` | admin | List pending invites |
| E-14 | DELETE | `/invites/{invite_id}` | admin | Cancel an invite |
| E-15 | GET | `/devices` | device | List devices (admin: all; member: own) |
| E-16 | DELETE | `/devices/{device_id}` | device | Revoke a device |
| E-17 | PUT | `/devices/current/push-token` | device | Set or clear this device's FCM token |
| E-18 | POST | `/accounts` | device | Create account |
| E-19 | PATCH | `/accounts/{account_id}` | device | Rename, change default ratio |
| E-20 | POST | `/accounts/{account_id}/archive` | device | Archive |
| E-21 | POST | `/accounts/{account_id}/unarchive` | device | Unarchive |
| E-22 | DELETE | `/accounts/{account_id}` | device | Soft delete when empty |
| E-23 | POST | `/categories` | device | Create category |
| E-24 | PATCH | `/categories/{category_id}` | device | Rename, icon, colour, order, reset name |
| E-25 | POST | `/categories/{category_id}/archive` | device | Archive |
| E-26 | POST | `/categories/{category_id}/unarchive` | device | Unarchive |
| E-27 | DELETE | `/categories/{category_id}` | device | Soft delete when unused and not default |
| E-28 | POST | `/recurring-templates` | device | Create template |
| E-29 | PATCH | `/recurring-templates/{template_id}` | device | Edit, pause, resume |
| E-30 | DELETE | `/recurring-templates/{template_id}` | device | Soft delete |
| E-31 | GET | `/sync` | device | Pull changes since a cursor |
| E-32 | POST | `/sync` | device | Push local expense and settlement changes |
| E-33 | POST | `/settlements/proposal` | device | Server-side allocation proposal |
| E-34 | GET | `/analytics/trends` | device | Spending per month, averages and trends, household and per category (D-133, D-138) |
| E-35 | GET | `/analytics/forecast` | device | Forecast of the next two calendar months per account (D-133, D-138) |
| E-36 | GET | `/cards/providers` | device | The card catalogue: supported cards, artwork key, whether this server can connect them for the caller (D-160) |
| E-37 | POST | `/cards/auth` | device | Start connecting (or renewing) a card: an authorisation attempt and the bank URL (D-162) |
| E-38 | GET | `/cards/auth/{attempt_id}` | device | Status of the caller's authorisation attempt (D-162) |
| E-39 | GET | `/cards/callback` | none | The bank's redirect target: finishes the attempt, HTML page (D-162, D-163) |
| E-40 | GET | `/cards/sync` | device | The caller's card connections and purchases since a card cursor (D-167) |
| E-41 | PATCH | `/cards/connections/{connection_id}` | device | Shorten the history setting (D-164) |
| E-42 | POST | `/cards/connections/{connection_id}/refresh` | device | Fetch from the bank now, user present (D-165) |
| E-43 | DELETE | `/cards/connections/{connection_id}` | device | Disconnect (D-167) |
| E-44 | PUT | `/cards/purchases/{purchase_id}` | device | Link to an expense, unlink, ignore (D-169) |

Reads of accounts, categories, templates, expenses, settlements and audit entries happen only through `GET /sync`; E-34 and E-35 are computed read-only views over them (§14.5.7), not a second way to read rows. Card connections and purchases are not household rows: they are read only through E-40, by their holder (D-161). The web client's static files under `/app/` (§15.4, D-135) are not API endpoints: they have no E-number, no protocol check and no entry in `contracts/openapi.yaml`. Every REST write that changes a synced row returns that row in its wire form (§14.3.3), with its new `server_version`, so the phone can store it immediately.

Request and response shapes, error codes and status codes: §14.3. The OpenAPI 3.1 file `contracts/openapi.yaml` is written by milestone M1 from §14.3, which is binding.

---

## 8. Auth & security

### 8.1 Threat model

Two trusted users. The server is on the public internet on port 443, through NPM (D-120, D-124); outside the home LAN NPM passes only requests that carry the app key (§8.5, D-126). Threats in scope: random internet scanners, a stolen or lost phone, leaked invite links, a compromised backup location, accidental personal data in logs or push payloads. Out of scope: a malicious partner, an attacker with physical access to the Pi. Accepted risk (owner, 2026-10-19, security review M-1): the Drive backups stay unencrypted and the rclone token keeps the full `drive` scope, so a compromised Google account or `rclone.conf` exposes every backup (§8.7, §10.9).

Card purchases (D-161, D-163) add: the Enable Banking application's private key (in `secrets/cards/` on the Pi, never in the database or a backup) and the Enable Banking session ids (in the database) are credentials to read the connected cards' transactions; a session id alone is useless without the private key, so a leaked backup or database does not expose the cards, and a leaked key without the database names no session. Kvitt can never pay or move money: the access is PSD2 account information only. In scope also: a forged or replayed bank redirect (single-use `state` bound to user and device, short expiry, CP-2), the authorisation code in a URL reaching a log (`/cards/callback` is never logged, §10.5.2), and one user seeing the other's card purchases (holder-only authorization, §8.4). Card purchases are personal content: everything §8.7 says about descriptions and amounts applies to merchant texts and card amounts.

### 8.2 Device tokens

* On a successful invite accept the server generates 32 random bytes from the OS CSPRNG and returns the token `kvt_` + base64url without padding of those bytes (47 characters total).
* The server stores only `token_hash` = lowercase hex SHA-256 of the full token string.
* Tokens do not expire. They stop working only on revocation.
* Every authenticated request sends `Authorization: Bearer <token>`. The server hashes it, looks up a device with that hash and `revoked_at IS NULL`, and loads the user. Missing or unknown token: 401 `unauthorized`. Revoked: 401 `device_revoked`.
* The server updates `devices.last_seen_at`, `devices.app_version_code` and `devices.app_version_name` at most once per hour per device. That update sets `app_version_code` only when the request carries `X-Kvitt-App-Version` and its value parses as an integer, and `app_version_name` only when the request carries `X-Kvitt-App-Version-Name` with 1 to 32 characters after trimming (D-090); otherwise the stored value is kept. E-3 stores both from the accepting request.
* On the phone the token is encrypted with an Android Keystore AES-256-GCM key (alias `kvitt_token_key`, `setUserAuthenticationRequired(false)`, no export) and the ciphertext and IV are stored in DataStore file `auth.preferences_pb`. The server base URL, user id and device id are stored next to it in plain text, together with the pairing status (D-043).
* The token is never logged, never put in a URL, never included in a crash report or screenshot.

### 8.3 Invite codes

* 12 characters from the Crockford base32 alphabet `0123456789ABCDEFGHJKMNPQRSTVWXYZ` (60 bits), generated from the CSPRNG.
* Displayed as three groups of four separated by `-`, as `7K3M-QX9D-2HPA`. URLs carry the 12 characters without hyphens.
* Normalisation before hashing or sending: uppercase; remove `-` and spaces; replace `O` with `0` and `I` and `L` with `1`. A normalised code that is not exactly 12 alphabet characters is `invite_invalid`.
* Stored as `code_hash` = lowercase hex SHA-256 of the normalised code.
* Single-use, 72-hour expiry, cancellable. Rate limit in AC-2.12.

### 8.4 Authorization rules

| Action | admin | member |
|---|---|---|
| All expense, settlement, account, category, recurring template operations | yes | yes |
| Edit own display name and picture | yes | yes |
| Edit the other user's display name or picture | no | no |
| Create, list, cancel invites | yes | no (`forbidden`) |
| List devices | all | own only |
| Revoke a device | any except current | own except current (another user's device: `not_found`, D-156) |
| Card connections and purchases (E-37 to E-44) | own only; the other user's: `not_found` (D-161) | own only; the other user's: `not_found` (D-161) |

### 8.5 Transport

* TLS terminates in the owner's Nginx Proxy Manager (NPM) on the Home Assistant Pi, with NPM's Let's Encrypt certificate for the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen, recorded in HANDOFF), on the default HTTPS port 443 (D-124); the router forwards external TCP 443 to the Home Assistant Pi's 443 (NPM), already in place for Home Assistant; nothing is forwarded to the Kvitt Pi (§10.1, §10.5, D-120, D-124). TLS 1.2 minimum, NPM defaults otherwise. NPM forwards plain HTTP over the home LAN to the server's port 8080 on the Kvitt Pi (accepted by the owner, D-120).
* App gate (D-126, owner decision 2026-10-21): NPM closes the connection (`return 444`, nothing sent) of every request that neither carries the header `X-Kvitt-App: <key>` with the app key nor comes from the home LAN `192.168.1.0/24`. Every route is covered, `/health`, `/setup/status`, `/invites/accept`, `/i/{code}` and `/apk/*` included; only Let's Encrypt's `/.well-known/acme-challenge/`, which NPM serves from its own folder, passes (§10.5.2). D-130 later lets the web client's requests through (below). The LAN check reads nginx's `$realip_remote_addr`, the address that really connected, because NPM's `real_ip_header X-Real-IP` for private peers lets a client set `$remote_addr`. The release app sends `X-Kvitt-App` on every request when its build carries the key: the Gradle property `kvitt.appKey` (`-Pkvitt.appKey=…`, else the key `kvitt.appKey` in `android/local.properties`, else empty), 16 to 128 printable ASCII characters without white space or the build stops with a message giving the length, never the value; exposed as `BuildConfig.APP_KEY` and to `:data` as `AppBuildInfo.appKey` (whose `toString` hides it); added in `KvittApi`'s common headers (every API call: `/health`, `/apk/latest`, `/apk/files/{file_name}`, `/invites/accept` included) and in `PictureAuth` for profile pictures from the paired server; an empty key sends no header (debug builds against the development stack need none). The key is generated by the owner (`openssl rand -hex 32`) and lives only in `android/local.properties` and NPM's Custom Nginx Configuration: never in git, never in `.env`, never printed in docs or logs. The Rust server neither sees nor checks the header and `contracts/openapi.yaml` is unchanged (§14.3.1). The per-device bearer token stays the authentication (§8.2); the gate is a perimeter that keeps scanners and anyone without the app from the server. On the home LAN the "secret" is the Wi-Fi password, and the owner controls the APK's distribution (he installs it on both phones). Rotation: a second `if` line with the new key next to the old in NPM, the new APK through the update path (FR-16), then the old line removed. Accepted: the invite landing page works only on the LAN; `/health` from outside without the header gets a closed connection, so the outside check is the app's About screen (S-22) or `curl -H "X-Kvitt-App: $KEY"`; a leaked APK leaks the key until rotation; nothing at home protects against a bandwidth flood. **Web client (D-130, extends D-126):** from outside the LAN three more kinds of request pass without the key, because a browser cannot carry it: a path that is `/app` or starts with `/app/` (the web client's files), `POST /invites/accept` (the web login; AC-2.12's lockout bounds guessing), and a request with an `Authorization: Bearer` header whose path does not start with `/health`, `/setup/`, `/i/` or `/apk/` (the server checks the token; an unknown one gets 401 and counts against its address's unauthenticated limit, §8.6, the H-1 fix, D-115). `/health`, `/setup/status`, `/i/{code}` and `/apk/*` stay LAN-or-key only. Consequence, accepted: the server's authenticated routes are reachable from the internet with a wrong token (401, at most 60 per minute per address), which the security review's threat model already assumed before D-126 (§15.2).
* Release builds' network security config (`android/app/src/main/res/xml/network_security_config.xml`): cleartext disabled, system trust anchors only, unless the pinned-root switch is on, in which case a pinned root replaces the system anchors for one domain only (available but unprepared since D-120, §10.5.3). The pinned-root config is generated at build time (task `generatePinnedRootNetworkSecurityConfig`) from the template `android/app/src/releasePinnedRoot/network_security_config.xml` with the domain `kvitt.publicHost` (D-121), into the release resources only when the Gradle property `kvitt.tls.pinnedRoot` is `true` (D-082); the build stops with a message while `android/app/src/release/res/raw/kvitt_root_ca.crt` is not committed (`038c603`).
* Debug builds override the config in `android/app/src/debug` and allow cleartext to every host, because a network security config cannot express IP ranges; the AC-2.8 limit (`localhost`, `10.0.2.2`, private LAN addresses) is enforced by `SessionRepositoryImpl.normaliseServerUrl`. Lint's `InsecureBaseConfiguration` warning on the debug config is intended (D-082).
* The server trusts `X-Forwarded-For` only from NPM: `KVITT_TRUSTED_PROXY` is `HA_HOST`, NPM's LAN IPv4 address (an IP literal in the Pi's `.env`, D-125), and from that peer the server takes the last `X-Forwarded-For` entry as the client IP for rate limiting (D-120; the server is unchanged). A request from any other peer counts against the peer's own address.

### 8.6 Rate limiting and input limits

* Unauthenticated endpoints other than E-6, the web client's files (`/app`, `/app/` and `/app/*`, D-136) and unknown paths: at most 60 requests per minute per client IP, then 429 `rate_limited` with a `Retry-After` header in seconds. The `/app` paths count against the client IP even when the request carries a bearer token (D-136): a page load is `index.html` and a few hashed assets that the browser then caches for a year (§15.4), so 60 per minute leaves room for reloads.
* APK downloads (E-6, `GET /apk/files/{file_name}`): at most 10 requests per minute per client IP, then 429 `rate_limited` with `Retry-After`. Own fixed window, not counted against the 60; every request counts, a 404 included (D-119, security review L-3).
* Authenticated endpoints: at most 600 requests per minute per device.
* Keying (D-032, revised by D-115): the per-device limit is keyed by the hash of the bearer token, with no database lookup. A token is accepted only when a response to it is 2xx. A request with a token not yet accepted counts against its client IP's unauthenticated limit before it runs and is refused with `rate_limited` once the IP is over; a 2xx gives that count back (a newly paired device costs its IP nothing); a 401 for an accepted token counts against the IP and withdraws the acceptance; token entries, accepted or not, are pruned once their window expires; every 401 counts against the IP exactly once (security review H-1: before, a random token answered 426 without `X-Kvitt-Protocol` became accepted for good, bypassed the IP limit and was never pruned). All windows are fixed from the first counted request. The client IP is the peer address, or, when the peer is the trusted proxy (`KVITT_TRUSTED_PROXY`, re-resolved at most every 60 seconds), the last entry of `X-Forwarded-For`. Per-IP keying needs the peer address: `serve` runs the router with `into_make_service_with_connect_info::<SocketAddr>()` (added by M4 in `15056dc`, D-032 fulfilled).
* `GET /health` from the container healthcheck counts against the loopback IP's limit; at the compose healthcheck interval this stays far below 60 per minute and is accepted.
* Invite accept failures: AC-2.12.
* Card purchases (D-162, D-165): the bank's redirect `GET /cards/callback` (E-39) counts as an unauthenticated endpoint (60 per minute per client IP). E-37 keeps at most one pending attempt per user and provider (a new one expires the previous). E-42 contacts the bank at most once per connection per 60 seconds; a request within 60 seconds of the previous user-present fetch's start answers the current connection without contacting the bank (CP-5). Background fetches are capped at 4 per connection per 24 hours (CP-4).
* Request bodies: 1 MiB maximum, except `PUT /me/picture` at 5 MiB. Larger: 413 `payload_too_large`. Both limits are layers in `router.rs` (§6.3).
* JSON strings are validated for length after trimming leading and trailing whitespace, and are stored trimmed, `notes` included (D-034). Control characters other than newline are refused with `validation_failed` in `notes` only; this is intended. Names and descriptions accept newlines and are not checked for control characters.
* The rate limiter is in memory (resets on restart); no table.

### 8.7 Privacy and logging

* Server logs contain: timestamp, level, request method, route template (not the raw path with codes), status, latency, device id, error code. They never contain tokens, invite codes, display names, descriptions, notes, amounts or picture bytes.
* The phone never logs personal content, debug builds included (`CLAUDE.md`). Log tags use the prefix `Kvitt`.
* Nginx Proxy Manager's access log (`proxy-host-<id>_access.log` inside NPM) records the full `$request_uri`, query string included, on every path except `/i/`; the `location ^~ /i/` of the Custom Nginx Configuration has `access_log off` and `error_log /dev/null crit`, so neither the invite code nor the inviter's name (`?from=`) reaches a log, a 502 included. NPM logs no request headers, so the `Authorization` token is never logged. The API's other query parameters (`since`, `limit`, `size`, `v`) hold no personal content (§10.5.2, D-120, revises D-117).
* The push sender logs one info line `push sent` per message with aggregates only: `push_type`, `devices_sent`, `devices_targeted` and the last 8 characters of each device id that got it; the per-device line is at debug (D-113).
* FCM payloads carry ids and types only (§14.6).
* Card purchases (D-161, D-163): server logs carry no merchant text, amount, date of a purchase, Enable Banking session id, account uid, authorisation `code` or `state`, and no Enable Banking response body; the card adapter logs one info line per fetch with aggregates only (`card_fetch`: provider id, kind `background` or `user`, the counts of new, updated and removed purchases, the HTTP status class of the bank call, and the last 8 characters of the connection id; since v0.36 also the number of bank requests, of windows split and of windows truncated (CP-7), and of pending purchases booked under their own reference (`booked_by_ref`) and taken over by CP-8's secondary rule (`booked_by_match`), D-178). `/cards/callback` is logged by the server under its route template only, and NPM does not log it at all (§10.5.2). The phone never logs card content (`CLAUDE.md`). Card data is never in a push, the audit log or `GET /sync`. Backups (§10.9) include the card tables in the SQLite snapshot, like every table; the private key is not in `data/` and is never backed up.
* Backups on Google Drive are not encrypted in v1; they go to the owner's own Drive folder, reachable only by his Google account. The owner decided on 2026-10-19 not to encrypt them with an rclone `crypt` remote and to keep the token's `drive` scope (security review M-1 closed as an accepted risk, §8.1, `docs/validation/security-review.md`).

### 8.8 Phone hardening

* `android:allowBackup="false"` and `android:dataExtractionRules` excluding everything, so neither Google backup nor device transfer copies the token or database.
* Exported components: only `MainActivity` (launcher and deep-link intent filters) and library receivers guarded by a permission (Firebase's, as Firebase requires). The FCM service `KvittMessagingService` is not exported. Checked on the merged release manifest at M8.
* On `device_revoked` the app wipes local data as in AC-3.3.

### 8.9 Server hardening

* The server container runs as a non-root uid/gid: on the Kvitt Pi the owner's (`KVITT_UID`/`KVITT_GID` in `.env`, 1000:1000, D-125), on the development stack and as the image's default `10001`; with a read-only root filesystem and a 16 MB tmpfs `/tmp`, `/data` as the only writable volume, its secrets read-only (the FCM key file and, since D-175, the folder `secrets/cards/` with the Enable Banking private keys), no Linux capabilities, `no-new-privileges`.
* The TLS-terminating process is the owner's Nginx Proxy Manager on the Home Assistant Pi; its hardening is that install's, outside this repository (D-120).
* Only the server publishes a port (8080 on the Kvitt Pi's LAN; the router forwards only to NPM). The `backup` sidecar publishes no port and is reachable only on the compose default network. Anyone on the home LAN can reach `http://<kvitt-pi-address>:8080` directly; such requests count against their own address (§8.6, D-120).
* SQLite `PRAGMA foreign_keys = ON`, `journal_mode = WAL`, `synchronous = NORMAL`, `busy_timeout = 5000` on every connection.

---

## 9. Edge cases & business rules

### 9.1 Splits

Split modes:

| `split_mode` | Meaning | Stored `share_bp` per user | Stored `share_ore` per user |
|---|---|---|---|
| `default` | The account's default ratio at the time of saving | copied from the account | computed by the ratio rule |
| `ratio` | A custom ratio for this expense | as entered | computed by the ratio rule |
| `exact` | Exact amounts for this expense | `null` | as entered |
| `full` | One user bears the whole amount | bearer 10000, other 0 | bearer = amount, other 0 |

**Ratio rule** (modes `default`, `ratio`, `full`; exactly two users P = payer, N = non-payer):

```
share_ore(N) = floor(amount_ore * share_bp(N) / 10000)
share_ore(P) = amount_ore - share_ore(N)
```

The non-payer's exact share is rounded down, so the payer absorbs the remainder: the payer's share is 0 or 1 öre more than their exact share. Intermediate products are computed in 64-bit integers (the maximum, 1 000 000 000 × 10000, fits). Examples (also test vectors):

| amount_ore | payer | bp payer / non-payer | share payer | share non-payer |
|---|---|---|---|---|
| 1001 | A | 5000 / 5000 | 501 | 500 |
| 1 | A | 5000 / 5000 | 1 | 0 |
| 100 | B | 4000 / 6000 | 40 | 60 |
| 999 | A | 3333 / 6667 | 333 | 666 |
| 999 | B | 6667 / 3333 | 667 | 332 |
| 50000 | A | 0 / 10000 | 0 | 50000 |
| 50000 | A | 10000 / 0 | 50000 | 0 |

**Exact rule:** both shares are given, each 0 or more, and they must sum exactly to the amount, otherwise `exact_sum_mismatch`.

**Validity:** exactly two share entries, one for each household user, no other user ids; bp each 0 to 10000 and summing to 10000.

**Server check:** for every pushed expense the server recomputes the shares from `split_mode`, the amount, the payer and the given bp (or exact öre) with `kvitt-domain` and rejects the mutation with reason `validation_failed` if the pushed `share_ore` values differ. For mode `default` the server does not compare the bp with the account's current default (the phone may have copied an older default while offline); it only checks they sum to 10000.

### 9.2 Effect line from the viewer's side (lists)

For viewer V and an expense with payer P:

| Case | Line |
|---|---|
| V = P and the other's share > 0 | "You lent <other's share>" |
| V ≠ P and V's share > 0 | "You borrowed <V's share>" |
| the non-payer's share = 0 | "Not involved" when V ≠ P; "Paid for yourself" when V = P |

### 9.3 Balances

For an account and user u, over non-deleted expenses and non-deleted settlements:

```
net(u) =   Σ expenses where payer = u            : amount_ore
         − Σ expenses                             : share_ore(u)
         + Σ settlement allocations where from = u : allocation.amount_ore
         − Σ settlement allocations where to = u   : allocation.amount_ore
```

* `net(A) + net(B) = 0` always.
* The account balance shown to viewer V is `net(V)`: positive "<Other> owes you net(V)", negative "You owe <Other> −net(V)", zero "All settled up" (account screens say "Settled up").
* The global balance is the sum over all accounts, archived included, deleted excluded (a deleted account has no non-deleted rows by AC-6.5).
* Balances include pending local changes.

### 9.4 Settlement allocation proposal

Inputs: payer user id, amount (öre, > 0), and for every non-deleted account: id, `created_at`, archived flag, and the payer's current net in it (computed with §9.3, excluding the settlement being edited if any).

Algorithm (normative; §14.5 has the signature):

1. Owing accounts = accounts where payer's net < 0. Sort by `created_at` ascending, then by `id` ascending.
2. `remaining = amount`. For each owing account in order while `remaining > 0`: `a = min(remaining, −net)`, emit allocation `(account, a)`, `remaining −= a`.
3. If `remaining > 0` (the amount exceeds the total debt) and at least one owing account exists, add `remaining` to the **last** emitted allocation and report that account as over-settled.
4. If no owing account exists: the target is the oldest non-archived account (same sort); if every account is archived, the oldest account. Emit one allocation of the whole amount to it and report it as over-settled.
5. If there are no accounts: error `no_accounts`.

Output: ordered allocations, `excess_ore` (the amount added in steps 3 or 4, 0 otherwise), and `over_settled_account_ids`.

Consequences, stated so nobody "fixes" them:

* A global settle-up of exactly the global debt can leave individual accounts non-zero when the payer is owed in some account and owes in another (allocations are never negative). The global balance is then zero. Users settle individual accounts with per-account settle-ups in either direction.
* The proposal is only a suggestion; the user may edit any allocation, add accounts or remove rows.

**Over-settle warning** for a user-edited allocation list: allocation `(account, a)` is warned when `a > max(0, −net_payer(account))`.

**Settlement validity** (phone before saving, server on push): amount within §9.6; `from_user_id ≠ to_user_id`, both household users; 1 to 50 allocations; each `amount_ore ≥ 1`; account ids distinct and referencing existing non-deleted accounts; allocations sum to the amount. Error tokens in §14.5.3.

### 9.5 Recurring generation

* The scheduler runs once at server start and then daily at 06:00 Europe/Stockholm (DST-aware: always local 06:00). It reads the injected clock (`AppState.clock`) at least every 30 seconds rather than sleeping until the next run: after a forward clock jump past one or more runs it runs the missed job once; after a backward jump of more than a day it plans the next run again from the new time. The 04:00 pruning loop (§14.1) follows the same rules.
* For each template with `deleted_at IS NULL` and `paused = 0`, the candidate periods are every month `p` with `start_period ≤ p`, `p ≤ end_period` (if set), `p > last_generated_period` (if set), and whose occurrence instant (the clamped date at 06:00 Europe/Stockholm) is at or before now.
* For each candidate in ascending order the server, in one transaction: creates the expense (server-generated UUIDv7 id; `expense_date` = clamped date; fields copied from the template; `created_by_user_id` and `updated_by_user_id` = the template's `created_by_user_id`; `updated_by_device_id` null; `created_at` = `updated_at` = server now; `recurring_template_id` and `recurring_period` set), writes its splits (mode `default` resolves the account's current default ratio at generation time; other modes use the template's splits, with `ratio`/`full` recomputed by the ratio rule for the template amount), writes an audit entry (`create`, `source` = `recurring`), sets the template's `last_generated_period` and `updated_at` (server now), bumping its `server_version`, then enqueues the push (AC-9.6).
* The unique index on `(recurring_template_id, recurring_period)` makes generation idempotent; a conflict means the period was already generated and is skipped silently.
* Pausing stops generation. Resuming does not backfill periods whose occurrence passed while paused: on resume the server sets `last_generated_period` to the latest period whose occurrence instant is before now, if that is later than the current value and at or after `start_period`. Resuming a template that has not started yet therefore keeps its `start_period` (D-033).
* Changing `day_of_month` or `start_period` never regenerates past periods.
* `next_occurrence_date` (in the wire form, computed with `kvitt-domain::next_occurrence_date`, §14.5.2) is the clamped date of the first candidate period after `last_generated_period` that is ≥ `start_period` and ≤ `end_period`; `null` when paused, deleted or past `end_period`.
* A template's account may be archived (generation continues). Account deletion is blocked while a non-deleted template references it (AC-6.5).

### 9.6 Limits and validation

All string lengths are counted in Unicode code points after trimming. One table, used by phone validation and server validation alike:

| Field | Rule | Error (REST) / reason (sync) |
|---|---|---|
| `amount_ore` (expense, settlement, template) | integer 1 to 1 000 000 000 (10 000 000,00 kr) | `validation_failed` |
| allocation `amount_ore` | integer ≥ 1 | `validation_failed` |
| allocations per settlement | 1 to 50 | `validation_failed` |
| `share_bp` | integer 0 to 10000; the two sum to 10000 | `validation_failed` |
| `share_ore` | integer ≥ 0; the two sum to the amount | `validation_failed` |
| expense `description`, template `description` | 1 to 100 code points | `validation_failed` |
| expense `notes`, template `notes` | 0 to 1000 code points; newlines allowed | `validation_failed` |
| settlement `note` | 0 to 200 code points | `validation_failed` |
| `expense_date`, `settlement_date` | valid date, from `2000-01-01` to server today (Europe/Stockholm) + 365 days | `validation_failed` |
| account `name` | 1 to 60 code points; unique (AC-6.2) | `validation_failed`, `name_taken` |
| category `name` | 1 to 40 code points, or `null` for a default category | `validation_failed` |
| user `display_name` | 1 to 40 code points | `validation_failed` |
| device `name` | 1 to 60 code points | `validation_failed` |
| `fcm_token` (E-17) | 1 to 512 characters after trimming, or `null` to clear; a Firebase Installation ID has 22 (D-114) | `invalid_request` with field `fcm_token` |
| `day_of_month` | integer 1 to 31 | `validation_failed` |
| `start_period` | `YYYY-MM`, not earlier than 12 months before the current month | `validation_failed` |
| `end_period` | `null` or `YYYY-MM` ≥ `start_period` | `validation_failed` |
| `updated_at` in a push | ≤ server now + 10 minutes | `clock_skew` |
| mutations per `POST /sync` | 1 to 100; 0 is also `batch_too_large` (D-036) | `batch_too_large` |
| `GET /sync` `limit` | 1 to 1000, default 500 | `invalid_request` |
| `GET /sync` `since` | required, integer ≥ 0 | `invalid_request` |
| picture upload | ≤ 5 MiB, ≤ 8000 × 8000 px, JPEG/PNG/WebP | `payload_too_large`, `image_invalid`, `unsupported_media_type` |
| card `history_days` (E-37, E-41) | one of 7, 30, 90, 180 (CP-3; K0 reached at least 150 days right after BankID, so 180 stays, D-177); E-41 accepts only a value ≤ the current one | `validation_failed` |
| card purchase `merchant` (stored) | 0 to 140 code points, truncated by the server (CP-7) | none (never sent by clients) |
| E-44 body | `expense_id` a non-deleted expense id or `null`; `ignored` bool; `ignored` true needs `expense_id` null; a `credit` purchase accepts only `expense_id` null and `ignored` false (CP-8) | `validation_failed`; an unknown or deleted `expense_id` is `not_found` with field `expense_id`; `expense_already_linked` |
| `GET /cards/sync` `since`, `limit` | as `GET /sync`: `since` required, integer ≥ 0; `limit` 1 to 1000, default 500 | `invalid_request` |

Strings are stored as validated, that is trimmed (§8.6, D-034).

On the phone, a rule of this table that has no domain error token of §14.5.3 (the length limits, the date limits, `day_of_month`, the periods) is reported as `FieldError.error` = `validation_failed` (§14.2.4), the same token as the REST code; a missing required value is `required`.

The phone input field for amounts accepts digits, one decimal separator (`,` or `.`) and at most two decimals, without sign, and converts to öre exactly (string parsing, never floating point). A stored amount opens for editing with both decimals ("1 247,60", "12 400,00"); ratio percent fields keep the trimmed form ("60", "60,5") (D-078; `AmountInput.of` and `AmountInput.percent` in `:core:design`).

### 9.7 Icon and colour tokens

Category icon tokens are Material Symbols names. The allowed set (exhaustive, 33 tokens; `key`, `shield` and `account_balance` added by D-054):

`shopping_cart`, `restaurant`, `local_cafe`, `home`, `bolt`, `water_drop`, `wifi`, `directions_car`, `train`, `local_gas_station`, `flight`, `hotel`, `luggage`, `movie`, `music_note`, `sports_esports`, `fitness_center`, `medical_services`, `medication`, `shopping_bag`, `checkroom`, `pets`, `child_care`, `school`, `card_giftcard`, `celebration`, `build`, `chair`, `subscriptions`, `category`, `key`, `shield`, `account_balance`.

Colour tokens (exhaustive, 14 tokens; `slate` and `amber` added by D-054) with the muted Kalas values of `docs/ux/design-spec.md` §2.3 (D-047, D-051; recorded in v0.9). The table holds the base colour of each token; `design-spec.md` §2.3 also gives each token's container (the colour over `surface` at 18 % in light, 24 % in dark) and the contrast ratios, all at least 3:1 as graphics. Category colours are never used for text.

| Token | Light | Dark |
|---|---|---|
| `green` | `#4E7A55` | `#8FB896` |
| `orange` | `#B26A3E` | `#E8AA7E` |
| `brown` | `#6B5244` | `#B8A090` |
| `yellow` | `#9C7C2A` | `#E6C67A` |
| `blue` | `#4A78A8` | `#98C0E6` |
| `teal` | `#367F82` | `#8CCAC8` |
| `purple` | `#865891` | `#C59CDA` |
| `red` | `#A84B45` | `#DC8F86` |
| `pink` | `#AE5D7C` | `#EFB0BE` |
| `grey` | `#6C7177` | `#B0B2B3` |
| `indigo` | `#45508D` | `#969DD8` |
| `lime` | `#73822F` | `#B9CC86` |
| `slate` | `#5E2D4E` | `#B0719A` |
| `amber` | `#937D63` | `#DFCFC0` |

The server validates icon and colour against these lists (`validation_failed`).

### 9.8 Formatting

* Money, Swedish locale: `1 234,50 kr` (U+00A0 no-break space as the thousands separator and before `kr`; comma decimal; always two decimals).
* Money, any other locale: `SEK 1,234.50` (U+00A0 after `SEK`; comma thousands; point decimal; always two decimals).
* Money is never shown with a minus sign; direction is in words (§9.2, §9.3).
* Dates in lists: Swedish `3 okt.`, English `3 Oct`; with year when not the current year (`3 okt. 2025`, `3 Oct 2025`). Detail views: Swedish `lördag 3 oktober 2026`, English `Saturday, 3 October 2026`. Timeline times: 24-hour `14:02` in both languages.
* Relative "last synced": "just now" (< 1 minute), "N min ago" (< 60 minutes), "N h ago" (< 24 hours), otherwise the list date and time. Swedish: "nyss", "för N min sedan", "för N h sedan".
* Chart axis labels (months): Swedish three-letter forms without a dot (`maj`, `jun`, … `okt`), English `May`, `Jun`, … `Oct`; list dates keep the Swedish abbreviation dot (`3 okt.`, `25 sep.`; `mars`, `maj`, `juni`, `juli` are written out) (D-065).
* Day ranges in captions and summaries (S-11 total caption, S-12 summary) are written out with the year: Swedish `24 augusti–17 oktober 2026`, `1–30 november 2026`, `28 december 2025–3 januari 2026` (the year once when both ends share it, the month once when both ends share it); the period chip and the S-12 title keep the short form `24 aug.–17 okt.` (D-077, extends D-065; `DateFormatter.dayRangeLong`).
* File sizes (the update banner, S-17): SI megabytes (10^6 bytes) with one decimal rounded half up and U+00A0 before `MB`: Swedish `8,4 MB`, English `8.4 MB` (D-065).
* Month and weekday names in Swedish and English are tables inside `DateFormatter`, not platform locale data, so JVM tests and the phone give identical output (D-065).
* Formatting lives in `:core:design` (`MoneyFormatter`, `DateFormatter`), never in `:domain`.

### 9.9 Online-only actions

When the phone has no validated network (Android `NET_CAPABILITY_VALIDATED`) or the last request failed with a network error less than 30 seconds ago, these actions are disabled with "Needs connection" ("Kräver anslutning", `common_needs_connection`): create, edit, archive, unarchive, delete of accounts, categories and recurring templates; profile name and picture; invites; device revoke; in-app update; "Sync now" ("Synka nu") on S-8 and S-10 (their missing states) and on S-16 (D-080); and for card purchases (D-162, D-165): connecting and renewing (S-25, "Förnya med BankID"), "Uppdatera" on S-23, the history setting and "Koppla från" on S-26. Linking, unlinking, ignoring and "Skapa utgift" are not online-only (CP-9); pull to refresh on S-23 ends at once offline, as on S-4. A REST call that fails with a network error shows "Could not reach the server" and changes nothing locally. Pull-to-refresh on S-4 and S-5 is not disabled offline; it ends at once without a sync (D-127).

### 9.10 Other edge cases

| Situation | Rule |
|---|---|
| Both users edit the same expense offline | Last `updated_at` wins; the loser's phone receives `stale` with the winner's row, overwrites locally and lists it under "Changes not synced" (§14.4.6). Both edits are in the audit log only if both were accepted, so only the winning edit is logged. |
| One user deletes, the other edits the same expense offline | Delete wins regardless of arrival order and timestamps: a pushed delete is always applied, and any non-delete write to a tombstoned row is rejected `deleted` (§14.4.4). |
| An expense is created offline in an account that was deleted meanwhile | Rejected `reference_not_found`; the row is removed locally and listed under "Changes not synced". Cannot happen for archived accounts (writes to archived accounts are accepted). |
| An expense uses a category that was archived meanwhile | Accepted. |
| Phone clock far in the future | Pushes rejected `clock_skew`; the app shows "Your phone's clock is wrong" on the sync status screen and keeps the changes pending. |
| Phone clock behind | Its edits may lose LWW against older real edits. Accepted risk. |
| Server restored from an older backup | The server's `sync_epoch` changes (§10.9); phones detect it and re-push everything they hold (§14.4.8), so changes made after the backup are recovered from the phones. |
| Partner never joins | Admin stays in the waiting state (AC-5.1). |
| Admin loses phone | `kvitt-server pair-device --user <admin id>` on the Pi (AC-1.6); then revoke the lost device from the new phone. |
| Both users' devices revoked | Same recovery as above for each user. |
| An account is renamed to a name used by a deleted account | Allowed (uniqueness ignores deleted accounts). |
| Recurring template's category deleted | Cannot happen: category deletion is blocked while a template uses it. |
| Expense amount edited in mode `exact` | The editor keeps the typed user's share and recomputes the other; if the typed share now exceeds the amount, saving is blocked (AC-8.7). |
| Settlement edited so that an allocation's account was deleted meanwhile | Cannot happen: an account with allocations cannot be deleted. |
| Same user on two devices edits offline | Same as two users: LWW per row. |
| Time zones | Dates (`expense_date`, `settlement_date`) are calendar dates chosen by the user; analytics never convert them. Only "today" defaults use the phone's zone; server validation and scheduling use Europe/Stockholm. |
| A day with a DST change | Scheduling uses local 06:00, which exists on every day in Europe/Stockholm. |

### 9.11 Category suggestion

The expense editor (S-7) selects the category from the description while the user types (D-049, owner 2026-10-18). The rule is a pure function in `:domain` (§14.5.6, with platform Unicode services through `UnicodeText`), fed by `ExpenseRepository.suggestCategory` in `:data` (§14.2.4) from Room and the keyword table `contracts/category-keywords.csv` (§14.8).

**CS-1 Scope.** The suggestion runs only in the editor for a **new** expense. It never runs when an existing expense is edited and never changes the category of a saved expense. The recurring template editor (S-19) does not use it in v1.

**CS-2 Manual choice wins.** The editor keeps a flag "category picked by hand", false when the editor opens. Picking any category in the category grid sets it to true, also when the user picks the category already shown. While the flag is true the suggestion never changes the category, for the rest of this editor session (until the editor closes). Nothing resets the flag.

**CS-3 When it runs.** While the flag is false, the category is recomputed on every change of the description and on every change of the account. It is a local computation over Room data; no network.

**CS-4 Normalisation.** Descriptions (typed and stored) and keywords are compared after this normalisation:

1. Unicode NFC, then lowercase without locale rules (Kotlin `lowercase()`, which uses `Locale.ROOT`).
2. Delete every `'` (U+0027), `’` (U+2019) and `:` (so "Willy:s" becomes "willys" and "McDonald's" becomes "mcdonalds").
3. Replace every remaining code point that is not a Unicode letter (general category L), a decimal digit (general category Nd) or `&` with a space. Whitespace is therefore replaced too.
4. Collapse runs of spaces to one space and trim.

Diacritics are kept (å, ä, ö and é stay distinct; the keyword table lists both spellings where it matters). Digits are kept. The **tokens** are the normalised description split on spaces; the **first token** is the first of them. An empty normalised description matches no history and no keyword.

**CS-5 Order.** The suggested category is the first that applies of:

1. **History, exact:** among the non-deleted expenses on the phone (every account, either user, pending, imported and recurring ones included) whose normalised description equals the normalised typed description, the category used most often; on a tie, the one used most recently.
2. **History, first token:** among the non-deleted expenses whose first token equals the typed description's first token, the category used most often; on a tie, the one used most recently.
3. **Keywords:** the category of the winning entry of the keyword table (CS-6).
4. **Default:** the AC-8.6 fallback: the category last used in the selected account on this phone if still active, else `other`; when `other` is archived too, no category (AC-8.6).

"Used most often" counts the matching expenses per category. "Most recently" compares the latest matching expense of each tied category by (`expense_date`, then `created_at`), the expense-list order of AC-8.10; if that still ties, the lower category id (string order) wins. Archived and deleted categories are left out of the count; when no category is left, the next step applies (owner, 2026-10-18: most often, not most recent).

**CS-6 Keyword table.** Each entry has a `keyword` (already normalised per CS-4), a `match` and a `default_key`. An entry matches when:

* `token`: some token equals the keyword;
* `prefix`: some token starts with the keyword;
* `phrase`: the keyword's tokens occur consecutively in the tokens.

When several entries match, the longest keyword (in code points, spaces included, a surrogate pair counting as one) wins; on equal length, the entry earlier in the table wins (the table is sorted by `default_key`, then `keyword`, both in code-point order). The winning entry gives the active category with that `default_key` (a renamed default included, since the key stays). If that category is archived, the next matching entry in the same order is tried; when none is left, step 4 applies. The table is fixed data shipped with the app; users do not edit it. No entry maps to `other`.

**CS-7 What the user sees.** The suggestion simply replaces the category shown in the Kategori field: no caption, no marker, no confirmation (owner, 2026-10-18: a wrong guess is corrected with one tap). Clearing the description returns the field to the step-4 default.

Evidence (D-049): a chronological replay of the household's 1 775 Splitwise expenses with the fourteen categories of AC-7.2 and the §10.8 mapping put 79.7 % of rows in the right category, against 30.5 % for the step-4 default alone; with no history, the keywords cover 77 % of rows at 96 % accuracy. The replay is in `docs/ux/category-suggestion.md`.

### 9.12 Card purchases (D-158 to D-176)

The rules of FR-22. The card holder is the user who connected the card; "purchase" is one card transaction as the bank reports it. Facts about the provider (established 2026-10-24, D-159): the SJ Prio Mastercard is issued by SEB Kort Bank AB and, as a payment account, is reachable through PSD2 account information (AIS): read only, no payments. Kvitt reaches it through Enable Banking (enablebanking.com), whose changelog (August 2024) lists an "SJ Prio Mastercard (SE)" integration, in its restricted production mode: free, for evaluation and individual non-commercial use, fetching data only from accounts linked to the application in Enable Banking's control panel ("Activate by linking accounts", done with the bank's own authorisation, BankID). PSD2 RTS Art. 36(5)(b): without the user actively requesting it, a provider may access an account at most 4 times per 24 hours. Since the 2023 RTS amendment, access through a provider needs a renewed strong customer authentication (BankID) at most every 180 days; the bank's `maximum_consent_validity` may be lower. History older than about 90 days is usually available only right after authentication. The spike K0 measured the owner's card on 2026-10-24 (PLAN-K0, report `docs/spikes/K0-enable-banking.md`, D-177); its results are stated in the rules below as measured ("K0: …"). Three points were not measured and rest on the owner's decision of 2026-10-24 ("let's just assume it all works now given your test", D-177): the partner's card links to the owner's application (CP-13), a pending transaction keeps its `entry_reference` when it is booked (CP-8), and a session is reused on later days without BankID (CP-6). K1's owner steps verify all three on the real server (PLAN-K1 §8).

**CP-1 Catalogue (D-160).** Supported cards are entries of a provider registry in `kvitt-server` (`src/cards/providers.rs`), served by E-36. Each entry has an open-string id, a display name, the issuer, the Enable Banking ASPSP name and country, an image key and its source adapter (`enable_banking`); nothing outside the adapter names the vendor, and ids are never enums (`CLAUDE.md`). The registry has one entry: id `sj_prio_mastercard`, name "SJ Prio Mastercard", issuer "SEB Kort", ASPSP name `SJ Prio Mastercard`, country `SE`, image key `sj_prio_mastercard` (K0: listed exactly so in `GET /aspsps?country=SE`, one of 126 Swedish ASPSPs, `beta` false, `psu_types` [`personal`], auth method `REDIRECT`). The app and the web map the image key to their bundled artwork, committed in both (D-180); an unknown key draws the fallback card. A user has at most one connection per provider (D-167).

**CP-2 Connecting (D-162).** E-37 creates an authorisation attempt for the caller (user and device), the provider, the chosen history and the client (`android` or `web`): a random 32-byte `state` (base64url, stored only as its SHA-256 hash, like invite codes, §8.3), status `pending`, expiry 15 minutes after creation. It calls Enable Banking `POST /auth` with `access.valid_until` (CP-6), the ASPSP, the `state`, `redirect_url` = `<KVITT_PUBLIC_URL>/cards/callback` and `psu_type` `personal`, and returns the attempt id, the bank URL and the expiry. A new attempt for the same user and provider expires a pending older one. The client opens the URL (Android: a Custom Tab, D-173; web: the same tab, D-174); the user signs with BankID (app-to-app on the phone, QR in a desktop browser). The bank redirects the browser to E-39 with `code` and `state` (or `error`). E-39 looks the attempt up by the hash of `state` (D-184): an unknown or already used `state` changes nothing and shows the failure page; an expired one stores the attempt as `expired` and shows it too; otherwise the attempt is claimed atomically (only one callback gets past this point) before Enable Banking is asked for anything; then an `error` marks it `failed` with `cancelled`, a callback with neither `code` nor `error` `failed` with `bank_error`, and with a code it calls Enable Banking `POST /sessions` with the code, picks the card account (exactly one account in the session: that one; several: the first whose `cash_account_type` is `CARD`, else the first; none: `failed` with `no_account`, and that session is revoked at Enable Banking, best effort, D-184; K0: the SJ Prio session holds exactly one account, currency SEK, `cash_account_type` `CARD`), creates or updates the user's connection for that provider (status `active`, the new session id, account uid, `valid_until`, history), marks the attempt `connected`, starts the first fetch in the background (CP-4, user present with the callback request's address and user agent) and shows the success page. The attempt is single use: a second callback with the same `state` shows the failure page and changes nothing. The pages (bilingual by `Accept-Language`, copy in §13.3 "Card callback page") link back to the client: `kvitt://cards/connected?attempt=<attempt id>` for `android`, `/app/cards?attempt=<attempt id>` for `web`. The page never redirects by itself (a browser may block a scripted jump to `kvitt://`); the client learns the result by polling E-38 every 2 seconds while its connect screen is open (S-25, W-22) and when the return link opens it. Renewing an existing connection (CP-6) is the same flow; on success the connection keeps its id and every purchase, and the previous session is revoked at Enable Banking (best effort).

**CP-3 History (D-164).** The connect screen offers "Hämta köp från de senaste 7 / 30 / 90 / 180 dagar", default 30 days. The first fetch after an authorisation asks for transactions of that many days up to today (Europe/Stockholm), today counted as one of them (`date_from` = today − (`history_days` − 1), D-181), in windows (CP-7). K0: right after BankID the card gave at least 150 days (five consecutive 30-day windows back to 150 days, all answered with rows; the last 30 days to 180 were not asked by window), so 180 stays offered (D-177). The setting can be shortened later (E-41; it only affects later renewals, stored purchases stay); a longer value needs a fresh BankID, so S-26 offers it only through "Förnya med BankID" (E-37 with the new value), and says so ("En längre period kräver BankID igen").

**CP-4 Background fetch (D-165).** Enable Banking's FAQ: "many ASPSPs have the limit of 4 times a day for data fetches when PSU is not online". The server fetches every `active` connection in the background at 06:45, 11:45, 16:45 and 21:45 Europe/Stockholm (four slots spread over the day, away from the 04:00 pruning and the 06:00 recurring run), without the user's headers (not user present). A slot is skipped when the connection started 4 background fetches in the preceding 24 hours (`background_fetches`, the start times of the last four), when any fetch for it succeeded less than 2 hours before, or when one is running. The scheduler reads the clock as §9.5 does; after downtime it runs at most the slot that is due, never a backlog: at start-up the latest slot already passed runs once, subject to the 4-per-24-hours quota and the 2-hour rule (D-185). Every background start counts towards the quota, whatever its outcome (D-185). K0: a fetch without the user's headers was accepted for the SJ Prio card (HTTP 200); how many the bank accepts per 24 hours was not measured, so the 4-per-24-hours rule stands. A background fetch normally makes one bank request (its range starts 10 days before the latest stored booking date, one window of CP-7); the `card_fetch` line counts the requests (§8.7).

**CP-5 User-present fetch (D-165).** "Uppdatera" and pull to refresh on S-23 (and "Uppdatera" on W-21) call E-42, which fetches with the user present, so it does not count as background access. Enable Banking's PSU headers are `Psu-Ip-Address`, `Psu-User-Agent`, `Psu-Referer`, `Psu-Accept`, `Psu-Accept-Charset`, `Psu-Accept-Encoding`, `Psu-Accept-language` and `Psu-Geo-Location`, and a fetch sends "either all required PSU headers (in case of online data fetching) or none", the required set being the ASPSP's `required_psu_headers` in `GET /aspsps`. A user-present fetch therefore sends `Psu-Ip-Address` (the client IP of §8.6, which the rate limiter puts in a request extension for this, D-188) and `Psu-User-Agent` always, plus every other header the ASPSP requires, each taken from the app's own request (`User-Agent`, `Referer`, `Accept`, `Accept-Charset`, `Accept-Encoding`, `Accept-Language`); `Psu-Geo-Location` is never sent (Kvitt has no location). Each header is sent only when the app's request carries a value for it (D-186). The ASPSP's details from `GET /aspsps` are cached for 24 hours; when `/aspsps` fails, only `Psu-Ip-Address` and `Psu-User-Agent` are sent (D-186). K0: the SJ Prio ASPSP's `required_psu_headers` is exactly [`psu-ip-address`]; Enable Banking lists the names in lower case, so they are compared case-insensitively; a fetch with `Psu-Ip-Address` and `Psu-User-Agent` was accepted (HTTP 200) from the MacBook, and from the Pi it is checked by K1's owner steps. A background fetch sends none. E-42 contacts the bank at most once per connection per 60 seconds (§8.6) and waits up to 25 seconds for the fetch; if it takes longer it answers with `fetching` true and the fetch completes in the background. The app then pulls E-40. On the phone the regular sync triggers (AC-15.3) also pull E-40, so purchases fetched in the background reach the phone without a tap.

**CP-6 Consent (D-166).** `access.valid_until` asks for now plus the smaller of 180 days and the ASPSP's `maximum_consent_validity` (given in seconds in `GET /aspsps`), less 5 minutes (K0: the SJ Prio value is 15552000 seconds, 180 days, so the request is now plus 180 days less 5 minutes; the session made on 2026-10-24 returned `valid_until` 2027-04-22); the stored `valid_until` is the one Enable Banking's session returns. The session serves every fetch, user-present and background, until then without a new BankID (owner's assumption, D-177; K0 did not repeat a fetch on a later day, K1's owner steps check it). From 14 days before it, S-23 and S-26 show the expiry notice with "Förnya med BankID"; once it has passed, or Enable Banking reports the session expired or revoked, the connection's status becomes `expired`: no fetch runs, the stored purchases stay and keep working (link, ignore), and "Förnya med BankID" renews (CP-2).

**CP-7 Incremental fetch and mapping (D-168, D-178, D-179).** Each fetch covers the range from `date_from` = the later of (today − (`history_days` − 1), today being one of the `history_days` days, D-181, revising the earlier "today minus `history_days`", which made 181 days and 7 windows for 180) and (the latest stored booking date of the connection minus 10 days) up to today, so a purchase booked late and a pending purchase turning booked are seen again; the first fetch after an authorisation starts at today − (`history_days` − 1). K0: the SJ Prio card answers every transactions request with at most 100 transactions and never a `continuation_key`, so a longer range loses rows without an error (90 days gave 100 rows covering only the newest 60 days; 180 days with `strategy=longest` gave 100 rows that were neither the newest nor a contiguous range). The range is therefore fetched in windows (D-178):
* Windows: consecutive, non-overlapping, at most 30 days each, newest first, each asked with `date_from` and `date_to` (both inclusive); the oldest window takes what is left and may be shorter. A first fetch of 180 days makes 6 requests; an incremental fetch (10 to about 20 days) makes 1. A `continuation_key`, if one is ever returned, is followed within its window.
* Split: a window whose response holds 100 or more transactions (the cap, so the response may be cut) is split into two halves, the newer half taking the extra day of an odd length, and each half is asked again, newest first, down to windows of one day; the rows of the cut response are discarded and only the halves' rows are kept (D-185). A one-day window that still holds 100 is kept as returned and counts as truncated.
* `strategy` is never sent (Enable Banking's default strategy): `strategy=longest` neither lifts the cap nor returns the newest rows.
* `WRONG_TRANSACTIONS_PERIOD` for a window (not seen in K0) means the bank has no older history: that window and every older one are skipped and the fetch succeeds with the newer windows; the deletion of vanished pending purchases (CP-8) then covers only the windows that answered (D-185).
* A window may return transactions whose booking date lies one or two days outside it (K0: the bank filters on another date), so every transaction is kept as returned and the transactions of all windows are de-duplicated by `provider_ref` (below) before CP-8; the first occurrence, from the newer window, wins.
* Any other error ends the fetch with CP-14's error; the transactions of the windows already fetched are applied (CP-8).
* A fetch is complete when every window of its range answered and none was truncated; only a complete fetch deletes vanished pending purchases (CP-8).

Each transaction maps to a purchase:
* `provider_ref`: the transaction's `entry_reference`, which Enable Banking documents as "unique and immutable" but "in most cases … provided only for booked transactions" (`transaction_id` "may change" and is not used). K0: on the SJ Prio card it is on every transaction, the pending ones included, unique, and unchanged between two fetches. When absent, `h:` + lowercase hex SHA-256 of `<purchase_date>|<amount>|<indicator>|<merchant text>|<n>`, `<n>` the 0-based index of an identical earlier transaction in the same window's response.
* `direction`: `debit` for `DBIT`, `credit` for `CRDT`. `status`: `pending` for `PDNG`, `booked` for `BOOK`; other statuses are skipped. `bank_transaction_code` is not used: the direction alone decides (D-179). K0 saw `PURCHASE` 92, `PAYMENT` 5, `UNKNOWN` 2 and `FEE` 1 in 100 transactions; a debit `FEE` (a card fee) or `PAYMENT` is a debit like any purchase, so it is "Att hantera" and the holder turns it into an expense or ignores it.
* `purchase_date`: `booking_date`, else `value_date` (a pending transaction has no booking date), else `transaction_date`; a transaction with none of the three is skipped. `booking_date` is stored when the transaction is booked. K0: `value_date` on every transaction, `booking_date` on every booked one and on no pending one, `transaction_date` on none (D-179).
* Amount: `transaction_amount.amount` is a decimal string parsed to öre exactly (string parsing, never floating point, as §9.6's amount input); its sign is ignored, the direction carries it. K0: positive decimal strings with a point, and every transaction in `SEK`, purchases at German, Irish and Estonian merchants included (`exchange_rate` empty): the card account reports foreign purchases converted to SEK. A transaction whose currency is not `SEK` (not seen in K0; kept as a safeguard) is stored with `amount_ore` null, its amount as the decimal string `original_amount` and `original_currency` (ISO 4217); such a purchase shows "<amount> <currency>" with "Utländsk valuta", gets no matches (CP-10) and "Skapa utgift" opens S-7 with the amount empty. A transaction of 0,00 is skipped.
* `merchant`: the `remittance_information` lines joined with a space, else `creditor.name`, else "Kortköp" ("Card purchase"); whitespace collapsed, trimmed, at most 140 code points (truncated). K0: `remittance_information` holds exactly one line on every transaction and it is the merchant text; `creditor.name` is never present (D-179).
* Nothing else of a transaction is stored, logged or sent to a client (D-179): in particular not `debtor.name` (K0: the card holder's name), `debtor_account` (K0: a masked card number, scheme `CPAN`), `creditor.postal_address` (K0: the merchant's country and town), `transaction_id` or `bank_transaction_code`.

**CP-8 Matching a fetch to stored purchases (D-168, D-177).** Within one connection: a transaction whose `provider_ref` is stored updates that purchase's status, dates, amount and merchant (link and ignore state kept). On the SJ Prio card a pending transaction carries an `entry_reference` (K0), and a pending transaction is assumed to keep it when it is booked (owner's assumption, D-177; K1's owner steps check it through `booked_by_ref` and `booked_by_match`, §8.7), so the booked transaction updates the pending purchase by its reference. The secondary rule, for a booked transaction with no stored `provider_ref` (a bank that gives the booked transaction a new reference, or a pending one stored under the fallback hash), takes over a stored pending purchase of the connection (its id, link and ignore state kept; its `provider_ref` replaced) when the amounts and directions are equal, the dates are at most 3 days apart and the CS-4 first tokens (§9.11) of the merchant texts are equal (the server takes the first token with Rust's standard Unicode character classes and without NFC normalisation: it only compares two texts from the same bank, D-182); among several, the oldest pending one. Otherwise it is a new purchase. After a complete fetch (CP-7), a stored pending purchase dated inside the fetched range that the bank no longer reports, neither linked nor ignored, is deleted (a tombstone with its content erased, D-167); a linked or ignored one stays as it is. Credit purchases (`credit`: refunds, deposits, the card bill's payment; K0: 2 of 100 transactions, both payments of the card bill, no refund) are stored but never "Att hantera": they show only under "Alla", marked "Insättning", with no actions, because §9.6 has no negative expense; the sheet says to change the original expense by hand.

**CP-9 Turning a purchase into an expense (D-169).** "Skapa utgift" opens S-7 (W-5 on the web) as a new expense prefilled with: amount = `amount_ore`; description = the merchant text, trimmed to 100 code points (§9.6), case unchanged; date = `purchase_date`; payer = the card holder (the viewer); account = from S-27 the account it was opened from, otherwise the AC-8.6 default (the account last used on this phone, or browser, if still active, else the oldest active account); category = the §9.11 suggestion for that description and account (it is a new expense, CS-1; the user's own pick wins, CS-2); split mode `default`; notes empty. Saving creates an ordinary household expense (sync push, audited, the partner is notified as for any expense) and links the purchase to its id. A purchase links to at most one expense, and an expense is linked from at most one purchase of each user (`expense_already_linked`). "Ta bort koppling" (S-23 sheet, S-8) clears the link; the expense stays. When a linked expense is deleted, by either user, the server clears the link in the same transaction (§14.4.4 step 7), so the purchase is "Att hantera" again; the phone clears it locally at its own delete. On the phone, link, unlink and ignore are written to the local copy at once (offline too) and sent with E-44 after the household push of the next sync cycle, so the expense exists on the server first (§14.4.5, D-173); the web sends E-44 at once. The link is not audited and not pushed; editing the expense later leaves the link.

**CP-10 Suggested matches (D-170).** For a debit purchase in SEK that is neither linked nor ignored, the matches are the household's non-deleted expenses (either user's, imported and recurring included) with `amount_ore` equal to the purchase's, `expense_date` within 3 days before or after `purchase_date`, and not linked from another purchase of the viewer; ordered by the absolute day difference, then `created_at` descending, then id; at most 3 shown. Computed on the phone from Room and in the browser from the snapshot by the pure function `matchCardPurchase` (§14.5.8, vectors `match_card_purchase.json`). A row with exactly one match shows the chip "Koppla till <description>"; with two or three, "<n> möjliga utgifter", which opens the sheet. "Välj en annan utgift" in the sheet lists the non-deleted expenses not linked from another purchase of the viewer, dated within 14 days of the purchase, any amount, newest first.

**CP-11 Privacy (D-161).** Owner, 2026-10-24: only the card holder sees their card purchases. Card connections and purchases are read and written only by their holder's devices; every other caller, the other user's devices included, gets `not_found` for their ids, the same as an unknown id (cf. D-156). They are not in `GET /sync`, not audited, not pushed, not in S-11, S-12, E-34 or E-35, and the partner's phone stores none. An expense created from a purchase is an ordinary household expense; only the holder sees that it came from a card (S-8, AC-22.10).

**CP-12 Disconnecting (D-167).** E-43 revokes the session at Enable Banking (`DELETE /sessions/{id}`, best effort: a failure is logged without the id and the disconnect goes on), sets the connection's status to `disconnected` and erases its session id and account uid, and deletes the connection's purchases that are neither linked nor ignored (tombstones with their content erased). Linked and ignored purchases stay (the user's decisions, which keep a later reconnect of the same card from offering them again) unless `erase_handled` is true, when they are deleted too. Expenses created from purchases stay. Connecting the same card again reuses the connection (one per user and provider).

**CP-13 Server configuration (D-175).** Enable Banking's production control panel accepts only `https` redirect URLs (an `http://localhost` URL "uses unsupported scheme"); the application's registered redirect URL is `https://<KVITT_PUBLIC_HOST>/cards/callback`, the path of E-39, and no other is needed. The application id is not a secret but is kept out of the repository's text (it is the configuration's value, §10.4, and the key file's name in K0's git-ignored folder). Card features need an Enable Banking application: an application id and its private key file (§10.4). One application may serve both users (the owner links both cards to it in Enable Banking's control panel) or each user has their own. The owner's application exists (K0: restricted production, activated by linking the owner's card, its key file in K0's git-ignored folder until K1's owner steps copy it to the Pi). The partner's card is assumed to link to the owner's application (owner's assumption, D-177; K0 did not try it, K1's owner steps do); the fallback is the partner's own application, which `KVITT_EB_MEMBER_APP_ID` and its key file configure without code change. A user without a configured application sees the provider as not available (E-36 `available` false, AC-22.1); E-37 answers `cards_unavailable`. The owner accepts Enable Banking's Terms of Service before an application exists (the licence step of `CLAUDE.md`, PLAN-K0).

**CP-14 Errors (D-165).** A fetch that fails records `last_fetch_error` on the connection: `bank_unavailable` (Enable Banking or the bank did not answer, or answered 5xx), `rate_limited` (the bank refused for too many requests), `consent_expired` (CP-6) or `failed` (anything else); a later successful fetch clears it. Enable Banking's answers map as follows (D-183): `EXPIRED_SESSION`, `CLOSED_SESSION`, `REVOKED_SESSION` and `SESSION_DOES_NOT_EXIST` → `consent_expired`, and the connection's status becomes `expired` (CP-6); `ASPSP_RATE_LIMIT_EXCEEDED` or HTTP 429 → `rate_limited`; `ASPSP_ERROR`, `ASPSP_TIMEOUT`, HTTP 408, any 5xx or no answer → `bank_unavailable`; `WRONG_TRANSACTIONS_PERIOD` is no error but ends the walk back (CP-7); anything else → `failed`. S-23 shows "Kunde inte hämta köp. Senast uppdaterad <time>" while it is set, except for `consent_expired`, which shows the expired state.

---

## 10. Deployment & ops

All infrastructure files live in `infra/` (ownership §14.7). Secrets live in `infra/secrets/` on the Mac (git-ignored) and in `~/kvitt/secrets/` (`/home/jacobhagstedt/kvitt/secrets/`) on the Pi (D-125); neither is ever committed.

**Development first (D-001).** During development the server runs locally on the owner's M4 Mac (Docker compose from `infra/dev/compose.yaml`, or plain `cargo run` in `server/`), and debug builds pair against it over the home Wi-Fi (debug builds accept `http://` to private LAN addresses, AC-2.8). The development stack (built by M2c-dev, landed `c885aba`, D-022) has the `server` service and the `backup` job runnable on demand without the Drive upload; it has no proxy and no TLS (plain `http://`, which debug builds accept on private LAN addresses). Its data is a bind-mounted folder on the Mac (`infra/dev/data/`, git-ignored, and `infra/dev/backups/` for local snapshots); it mounts `infra/dev/secrets/` (git-ignored) read-only at `/secrets`, into which `infra/dev/up.sh` copies only `fcm-service-account.json` from `infra/secrets/`, so the server container sees no other secret (D-117; a folder rather than the file, so a missing key leaves the folder empty and push disabled, §10.4); its env file is `infra/dev/.env.example` (no `RCLONE_REMOTE` since `fc6126c`: the development backup never uploads); its `server` healthcheck is `kvitt-server healthcheck`; its `backup` runs as uid 10001 so that it can open the WAL files the server owns (on the Pi both run as the owner's uid, D-125). The Pi's env template is `infra/pi/.env.example` (D-103, D-125). The development stack's database was migrated to schema 2 (migration 0002, §14.1.1) on 2026-10-18 after a backup, and to schema 3 (migration 0003, §14.1.2) on 2026-10-18 when it was rebuilt from `b7b7483`, again after a backup. On the Mac's Podman setup `infra/dev/up.sh` alone does not swap in a rebuilt image: run `infra/dev/up.sh --down`, then `infra/dev/up.sh`. Firebase (§10.7) is set up during development because push is needed then. Everything in this section that concerns the Pi (the Pi hosts and router of §10.1, §10.2, the registry and Pi deploy of §10.3, §10.5 TLS, publishing to the Pi in §10.6, the Drive upload of §10.9) is built by milestone M2c-pi, which runs after M8 and before M10.

**No SSH from the Mac to the Pis (D-100, revises D-023).** M2c-pi delivers a self-contained compose project in `infra/pi/` (D-125, revises D-103): `compose.yaml`, the env template `.env.example` and a `.gitignore`, with the owner's checklist in `infra/README.md` "Pi: what the owner does" (seven steps) and the restore runbook `infra/RESTORE.md`. The owner fills `infra/pi/.env` on the Mac, copies `compose.yaml`, `.env` and `secrets/` to `/home/jacobhagstedt/kvitt` (`~/kvitt`) on the Kvitt Pi and runs plain `docker compose` commands there; nothing on the Pi outside that folder is installed or changed, there is no install script and no script on the Pi at all, and Docker and the registry trust are prerequisites (D-125, owner decision 2026-10-20). Agents never connect to the Kvitt Pi, the Home Assistant Pi, Gitea or Google Drive and need no allowance for them; they check the project on the Mac (`docker compose config` with the env template, `shellcheck` on the scripts under `infra/`, a Podman rehearsal). Where §10.2 to §10.10 name a command on the Pi, the owner runs it in `~/kvitt`. M2c-pi runs as the last step before M10, after the app is proven on the phone against the development server. D-001 stands: development stays on the Mac. History: the first bundle landed on 2026-10-18 (`2476667`, D-103 to D-106: install, deploy, bootstrap, backup and APK scripts under `/opt/kvitt`); since D-120 (`d05f13a`, `62f5279`, landed with `9231a1d` on 2026-10-19) TLS terminates in the owner's Nginx Proxy Manager on the Home Assistant Pi (no Caddyfile, no Caddy, no cert-sync); since D-125 (`6e5981d`, 2026-10-20) the scripts `install.sh`, `deploy.sh`, `bootstrap.sh`, `backup-now.sh`, `install-apk.sh` and `lib.sh` are removed and their equivalents are the compose commands of §10.6, §10.9 and §10.10. Step 4 of the checklist sets up the NPM proxy host (§10.5).

### 10.1 Hosts and network

| Host | Role | Facts |
|---|---|---|
| Kvitt Pi | Runs the compose stack; publishes the server's port 8080 on the LAN for NPM (D-120) | Raspberry Pi 3, 1 GB RAM, 64-bit Raspberry Pi OS Lite (Debian bookworm or later), Docker Engine with the compose plugin (from Docker's Debian arm64 apt repository, D-104; a prerequisite, already installed, usable without sudo by the owner's user `jacobhagstedt`, uid and gid 1000, D-125), static LAN address. Kvitt runs from `/home/jacobhagstedt/kvitt` (D-125). LAN address `<kvitt-pi-address>`, known to the owner (OQ-3, D-100; no `.env` key since `200c99f`); also NPM's Forward Hostname / IP; no agent and no Mac script reaches it over SSH. Outbound HTTPS from the server container to `oauth2.googleapis.com` and `fcm.googleapis.com` (push) and, since D-175, to the Enable Banking API `api.enablebanking.com` (card purchases); nothing inbound but NPM's forward |
| Home Assistant Pi | Runs the owner's Nginx Proxy Manager (NPM), which owns ports 80/443: terminates TLS for the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen, recorded in HANDOFF) with NPM's own Let's Encrypt certificate (HTTP-01 on port 80) and forwards plain HTTP to `<kvitt-pi-address>:8080` (§10.5, D-120); closes every request from outside the home LAN without the app key (§8.5, D-126) | Its LAN IPv4 address is `HA_HOST` in the Pi's `.env`, filled by the owner (OQ-3), and is the server's `KVITT_TRUSTED_PROXY`. NPM is also the proxy host for Home Assistant under `icehack.asuscomm.com`, on the same port 443, and selects the proxy host by name, so Kvitt has its own name (D-124). The owner sets up the proxy host in NPM's web UI (§10.5.1); nothing of Kvitt runs there and nothing connects to it over SSH |
| Owner's M4 Mac | Builds release APKs (`infra/publish-apk.sh`); builds images only as the fallback of the Gitea workflow (`infra/build-images.sh`, D-104); runs the development server (D-001) | Apple Silicon, so `linux/arm64` builds run natively in Docker |
| Router (ASUS) | `icehack.asuscomm.com` DDNS (Home Assistant's name); the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen; currently `kvitt.suorra.duckdns.org`, HANDOFF) points at the same public address (a subdomain of the owner's DuckDNS family domain `suorra.duckdns.org`) | External TCP 443 → Home Assistant Pi 443 (NPM), already in place for Home Assistant, serves Kvitt too: no new rule (D-124; the owner confirmed the 443 forward, 2026-10-19); external 80 already reaches NPM for Let's Encrypt; nothing is forwarded to the Kvitt Pi (D-120) |
| Container registry | Holds Kvitt images | A Gitea instance on another Pi at `http://gitea.lan`: plain HTTP, reachable only on the home Wi-Fi (D-001). Kvitt images live under the owner path `gitea.lan/jacobh2` (D-104); Gitea Actions builds them (§10.3). Pushes use the Gitea secret `kvitt_cicd` (§10.3). The Kvitt packages are public, so the Pi pulls anonymously; were they private, the owner runs `docker login gitea.lan` once on the Pi with a `read:package` token (HUMAN, D-125). Agents never hold credentials (D-100) |

The Kvitt Pi's compose stack never builds anything. It only pulls images and runs them.

### 10.2 Compose stack

File `infra/pi/compose.yaml` (compose project name `kvitt`). The owner copies it with `.env` (from `infra/pi/.env.example`) and `secrets/` to `/home/jacobhagstedt/kvitt` (`~/kvitt`) on the Kvitt Pi, a self-contained compose project: every path in it is relative to that folder and nothing outside it is installed or changed (D-125, revises D-103; until then `install.sh` installed the stack to `/opt/kvitt`). The folder holds `compose.yaml`, `.env`, `secrets/` (`fcm-service-account.json`, `rclone.conf`) and the bind-mounted folders `data/` (SQLite, pictures, `data/apk/`), `backups/` and `import/`, which the owner creates before the first start (`mkdir -p data/apk backups import`; and `mkdir -p secrets/cards && chmod 700 secrets/cards` since K1, D-188), because a bind-mount source that Docker creates itself belongs to root and the containers cannot write to it. Services:

| Service | Image | Ports / volumes | Memory limit | Healthcheck |
|---|---|---|---|---|
| `server` | `${KVITT_REGISTRY}/kvitt-server:${KVITT_TAG}`, command `serve` | `./data:/data`; `./secrets/fcm-service-account.json` at `/secrets/fcm-service-account.json`, read-only, `create_host_path: false`; `./secrets/cards` at `/secrets/cards` (the Enable Banking private keys, D-175), read-only, `create_host_path: false` (an empty folder disables card features, but a missing one stops `docker compose up`, even with no card configured: the folder must exist from K1's image on, D-188); environment also `KVITT_EB_APP_ID=${KVITT_EB_APP_ID:-}` and `KVITT_EB_MEMBER_APP_ID=${KVITT_EB_MEMBER_APP_ID:-}`; `./import:/import:ro` (empty except during the one-off import, §10.8, D-025); publishes `8080:8080` on all of the Kvitt Pi's interfaces (NPM connects over the LAN, D-120); environment `TZ`, `KVITT_DATA_DIR=/data`, `KVITT_PUBLIC_URL=https://${KVITT_PUBLIC_HOST}` (port 443, D-124), `KVITT_TRUSTED_PROXY=${HA_HOST}`; the other settings keep their §10.4 defaults | 160 MiB (budget: RSS under 100 MB in steady state) | `kvitt-server healthcheck`, the binary's own `GET http://localhost:8080/health` (no curl in the image); every 30 s, timeout 5 s, 3 retries, start period 20 s |
| `backup` | `${KVITT_REGISTRY}/kvitt-backup:${KVITT_TAG}` | `./data:/data`; `./backups:/backups`; `./secrets/rclone.conf` at `/config/rclone/rclone.conf`, read-only, `create_host_path: false`; environment `TZ`, `HOME=/tmp`, `RCLONE_REMOTE=gdrive:` (fixed in `compose.yaml`, the `[gdrive]` remote of `rclone.conf`), `RCLONE_FOLDER_ID=${RCLONE_FOLDER_ID}` | 96 MiB | `/healthcheck.sh`: last successful run marker newer than 26 hours, or no run yet since start; every 5 min, start period 30 s |

* No named volumes: `data` and `backups` are the bind mounts `./data` and `./backups` (D-125; were the named volumes `data` and `backups`; `certs` and `caddy_data` were removed by D-120).
* Both services: `user: "${KVITT_UID}:${KVITT_GID}"`, the owner's uid and gid (1000:1000 on the Pi); `read_only: true` with a 16 MB tmpfs `/tmp`; `cap_drop: [ALL]`; `no-new-privileges`; `restart: unless-stopped`; logging driver `json-file` with `max-size: 10m`, `max-file: 3`; `TZ=Europe/Stockholm`.
* The compose default network (no network is declared; was the bridge network `kvitt`); only `server` publishes a port.
* No host firewall limits the published port 8080 to `HA_HOST`, so any device on the home LAN can reach the server over plain HTTP; the owner deferred such a rule on 2026-10-24 (D-156). It would be the owner's own step on the Pi, outside `~/kvitt` (D-125).
* The Memory limit column is advisory on the Kvitt Pi (D-156, owner 2026-10-24): `compose.yaml` keeps its `mem_limit` lines, but the Pi's kernel runs without the memory cgroup, so Docker warns at `docker compose up` and does not enforce the limits. The warning is accepted; the RSS budget is checked with `docker stats` (§10.10).
* One uid for both containers (D-105, revised by D-125): `sqlite3 .backup` on the WAL database must open the `-shm` file the server owns, so `backup` runs as the server's uid. On the Pi that uid is the owner's own, so every file in `data/` and `backups/` belongs to the owner, the two secret files are the owner's with mode 0600 (`chmod 700 secrets && chmod 600 secrets/*`), and a restore moves files with plain `mv` and `cp` (§10.9). The images need no particular uid: the server image's `USER 10001` is only its default, which compose's `user:` overrides (the binary needs no account and nothing writable outside `/data`), and supercronic runs as any uid; the owner's uid has no account inside either image, so `backup` gets `HOME=/tmp` for rclone's cache. rclone writes refreshed access tokens back to its config, and the mounted file is read-only, so `backup.sh` works on a private copy in `/tmp` on every run (D-105).
* Each container mounts only its own secrets, read-only (D-117): the server never sees the Drive token, and the backup container never sees the FCM key or the Enable Banking keys (`secrets/cards/`, D-175). `create_host_path: false` makes a missing secret file stop `docker compose up` with "bind source path does not exist" instead of Docker creating a root-owned directory in its place. These two, and since D-175 the Enable Banking key files in `secrets/cards/`, are the only secret files on the Pi.
* The development stack (`infra/dev/compose.yaml`) is unchanged by D-125: both containers there run as uid 10001 (§10 intro).

`.env` keys (exhaustive, D-125, revises D-103; two optional keys added by D-175): exactly the nine keys `compose.yaml` reads, and nothing else reads `.env` on the Pi. The two card keys `KVITT_EB_APP_ID` (the Enable Banking application id, shared by both users or the owner's) and `KVITT_EB_MEMBER_APP_ID` (the partner's own application, empty when the shared one serves her, CP-13) may be empty; an application id is not a secret (its private key is, in `secrets/cards/`). `KVITT_REGISTRY` (`gitea.lan/jacobh2`); `KVITT_TAG` (the image tag of both services, `v1.0.N`; a deploy or a rollback changes it, §10.10); `KVITT_PUBLIC_HOST` (the Kvitt host name, owner-chosen, recorded in HANDOFF; `kvitt.suorra.duckdns.org` in the template); `HA_HOST` (NPM's LAN IPv4 address, an IP literal rather than an mDNS name such as `homeassistant.local`, which the container cannot resolve; the template's only `CHANGE_ME`); `KVITT_UID` and `KVITT_GID` (`id -u` and `id -g` of the owner on the Pi; 1000 in the template); `RCLONE_FOLDER_ID` (the Drive folder id of OQ-4, filled in the template). Compose refuses to start while one of the seven required keys is unset (`${VAR:?…}`; the two card keys default to empty); nothing else checks the values, since there is no install script. Removed keys: `HA_PORT`, `HA_USER`, `HA_CERT_DIR` (D-120); the informational `KVITT_PI_HOST` and `KVITT_PI_SSH_USER`, read by nothing on the Pi (2026-10-20, `200c99f`, revises D-103; the owner's `scp` commands and NPM name `<kvitt-pi-address>` instead); `RCLONE_REMOTE` (fixed to `gdrive:` in `compose.yaml`); `KVITT_REGISTRY_USER` and `KVITT_REGISTRY_TOKEN` (D-125: private packages mean a one-time `docker login gitea.lan` on the Pi). On the Mac, `infra/publish-apk.sh` reads `KVITT_PUBLIC_HOST` from `infra/pi/.env` (§10.6).

### 10.3 Images, registry and build

* Image names (D-104, D-120): `${KVITT_REGISTRY}/kvitt-server`, `${KVITT_REGISTRY}/kvitt-backup`, with `KVITT_REGISTRY=gitea.lan/jacobh2` (was `${KVITT_REGISTRY}/kvitt/<name>`).
* The Gitea Actions workflow (D-104; the fallback since D-211, see the Mac build below): `.gitea/workflows/build-images.yaml`, following the owner's working example workflow. Runner label `host`: act_runner 0.6.1 on a Raspberry Pi 3 with 1 GB RAM, with an Alpine job container; the builds run on that Pi itself. `sh` steps, `apk add git docker-cli docker-cli-buildx`, `docker login gitea.lan` as `${{ github.actor }}` with `kvitt_cicd`, a user-level secret of the repository owner `jacobh2` (created by the owner; a user-level secret of the repository owner reaches the repository), a plain-HTTP buildx builder `local-http-builder` (`buildkitd.toml` with `http = true` for `gitea.lan`) created once and reused so its BuildKit cache survives, and `actions/checkout@v4` (below). The token is interpolated into the login step's `run` line (`printf '%s' "${{ secrets.kvitt_cicd }}" | docker login …`), the owner's proven form, because the env-based form (`env: REGISTRY_TOKEN: ${{ secrets.kvitt_cicd }}`) came through empty on act_runner 0.6.1 ("password is empty" on the first run, 2026-10-19); act_runner masks the value in the log (`4f69ae0`, D-120 point 7; this reverses the L-8 fix of `e70fe0d`). `kvitt_cicd` needs only the `write:package` scope, because the git tag push goes through the credentials `actions/checkout` stored (the job's own token) (D-117); the tag push worked on the first successful run (its `v1.0.0` tag is why the next run made `v1.0.1`). Checkout (`3820f9c`): a cone-mode sparse checkout (`sparse-checkout` `server`, `web`, `contracts` (both added by D-137) and `infra/backup`, `sparse-checkout-cone-mode: true`), what the two builds read (the server image builds from the repository root with the allowlist `.dockerignore` since D-137; the backup image from `infra/backup`), which makes the action fetch with `--filter=blob:none`, so only those paths' blobs are downloaded and the Android screenshot PNGs are not checked out; `fetch-depth: 0` stays, because "Determine Version" needs every `v1.0.*` tag and with a shallow fetch `fetch-tags` brings only the tags that point at the fetched tip (the full fetch carries commits and trees, no blobs). The temporary "Diagnose secrets" step (`dd07ca4`) is removed (`3820f9c`). Every `buildx` push passes `--provenance=false` and `--metadata-file`, and a step "Print image digests" prints each pushed image's digest, which the owner compares with the digest the Pi pulled (`docker image inspect`, §10.10; the Pi keeps no digest record since D-125, which revises D-117 point 5). Triggers: a push touching `server/**`, `web/**`, `contracts/**` (the last two added by D-137), `infra/backup/**` or `.gitea/workflows/**`, and `workflow_dispatch` (`infra/cert-sync/**` dropped by D-120). Version `v<MAJOR>.<MINOR>.<PATCH>` with MAJOR 1 and MINOR 0 set in the workflow: the next patch after the newest `v1.0.*` git tag (`v1.0.0` when there is none); each image is tagged with it and `latest`, and the git tag is pushed after the build. That tag is the Pi's `KVITT_TAG` (§10.2, §10.10); it says nothing about the APK version (§10.6). The Pi runner passes `--build-arg CARGO_BUILD_JOBS=1` to the server build (Pi 3, 1 GB), and `server/Dockerfile` honours it (`ARG CARGO_BUILD_JOBS` in its build stage, passed to cargo as `--jobs` only when set; unset on the Mac means one job per core; `b4d9467`). "Determine Version" also sets `VERSION_CODE` to `git rev-list --count HEAD` (the full history is fetched, `fetch-depth: 0`), and the server build passes `--build-arg KVITT_VERSION_CODE=$VERSION_CODE`, the web client's version code (§15.3, v0.34). Runs on the owner's Pi runner: the first run (2026-10-19) failed at the login with the env-based form; the next ones failed at the login with an empty secret, because the user-level secret was misnamed on the owner's side (found with the diagnostic step, fixed by the owner on 2026-10-19). Run 69 succeeded: login, version `v1.0.0`, `kvitt-backup` built and pushed in 5 min 20 s, `kvitt-server` in 2 h 42 min (the first build on the Pi 3 with `CARGO_BUILD_JOBS=1`; later runs reuse the builder's cargo cache), the git tag pushed. The push of the sparse checkout (`3820f9c`) produced `v1.0.1`, the tag the Pi uses. Since `28fa71b` (2026-10-20) the workflow's comments and `infra/build-images.sh`'s closing hint give the compose deploy (`cd ~/kvitt`, set `KVITT_TAG`, `docker compose pull && docker compose up -d`) and `docker image inspect` instead of `/opt/kvitt/deploy.sh` and `/opt/kvitt/deployed-digests`; the workflow's header still says "NOT YET RUN" and that the first build's duration is unknown. Unverified risk: the workflow pushes a git tag, and whether that push re-triggers the path-filtered workflow is not known.
* Script `infra/build-images.sh [tag]` on the Mac, the normal path since D-211 (the fallback under D-104 and D-156): builds the two images for `linux/arm64`, tag defaults to the short git SHA of `HEAD`, also tags `latest`; pushes when `infra/secrets/registry.env` (git-ignored: `KVITT_REGISTRY`, optional `KVITT_REGISTRY_USER` and `KVITT_REGISTRY_TOKEN`) exists, otherwise builds locally and prints the exact push commands. Refuses to run with a dirty working tree or while a Gradle build holds the `tools/gradle-serial.sh` lock (the lock check shared through `tools/gradle-lock.sh`, `2fac1ec`). Works with Docker buildx and with Podman.
* Where images are built (owner, 2026-10-24, D-211, revises D-156 point 5): on the owner's Mac with Podman, `infra/build-images.sh v1.0.N`; the Gitea workflow on the Pi 3 runner stays the fallback (about three hours per run and disk pressure on its 15 GB card; the owner cancels runs it queues). Tag rule: `git fetch --tags`, then the next `v1.0.N` after the highest `v1.0.*` tag on `origin`; the images carry that tag and `latest`, and the same tag is pushed as a git tag on the built commit (`git tag v1.0.N && git push origin v1.0.N`), so the workflow's own numbering continues after it (`v1.0.3` = `8fa9198`, the first Mac build). Registry from the Mac: `gitea.lan` on port 80, plain HTTP; `infra/secrets/registry.env` (git-ignored) holds `KVITT_REGISTRY=gitea.lan/jacobh2`, `KVITT_REGISTRY_USER` and a `write:package` token as `KVITT_REGISTRY_TOKEN`. The Pi's own `.env` keeps `KVITT_REGISTRY=gitea.lan:3001/jacobh2`, the port it reaches the same registry on locally; both name the same images. Podman marks the registry insecure in two places, `~/.config/containers/registries.conf.d/kvitt.conf` on the Mac and `/etc/containers/registries.conf.d/kvitt.conf` inside the Podman machine, each `[[registry]]` `location = "gitea.lan"` `insecure = true` (owner's allowance 2026-10-24 for these files outside the repository). Two script fixes made the Mac path work: the server build gets `--build-arg KVITT_VERSION_CODE=<git rev-list --count HEAD>` as the workflow passes it (`f15fa23`), and the engine test captures `docker version` before matching it (`8fa9198`: under `pipefail`, `grep -q` closed the pipe early, `docker version` died of SIGPIPE and the script chose docker over Podman). The script prints no image digests, so the digest comparison of §10.10 applies to workflow builds. If the fallback runs, the owner still runs `docker builder prune -af` on the runner Pi between builds (its disk reached 11 of 15 GB); that can drop the BuildKit cache, so the next server build there may be a full one.
* Web client (D-132, as built D-137, `50a0d67`): the server image's build context is the repository root (`docker build -f server/Dockerfile .`) with an allowlist `.dockerignore` at the root: everything is excluded except `server`, `web` and `contracts`, and inside them `server/target`, `server/data`, `web/node_modules`, `web/dist`, SQLite and `.db` files, APKs, `.pem` files, `.env` files and `.DS_Store` are excluded too, so the Android project, the docs, the goldens, worktrees and secrets never enter the context; `server/.dockerignore` is removed (`infra/backup/Dockerfile` builds from its own directory and does not read the root file). `server/Dockerfile` has three stages: (1) `web`: `docker.io/library/node:24.22.1-bookworm-slim` pinned by the digest of its multi-arch index (Node 24, the Active LTS line on 2026-10-21), on `$BUILDPLATFORM` (the output is static files, so an amd64 build never emulates npm), `npm ci` with a BuildKit npm cache, then `npm run build` in `/repo/web` beside `/repo/contracts` (the web build may read `../contracts`), failing unless `dist/index.html` exists; the stage has no `.git`, so `ARG KVITT_VERSION_CODE=1` is passed to `npm run build` as the environment variable `KVITT_VERSION_CODE`, the web's version code (§15.3; default 1, the workflow passes the commit count, v0.34); a `web/` without `package.json` and `package-lock.json` fails the build by design; (2) the Rust build stage, which copies the web stage's `dist` to `/out/web`, so it orders the two builds and npm and rustc never run at once on the 1 GB Pi 3 runner (BuildKit would otherwise run the independent stages in parallel; a web-only change re-runs the cargo step, which finds nothing to compile); `CARGO_BUILD_JOBS=1` stays; (3) the runtime stage, which copies `/out/web` to `/app` (owned by root, read-only for uid 10001; `KVITT_WEB_DIR` §10.4, serving §15.4). The workflow builds with context `.` and `file: server/Dockerfile`, its sparse checkout and path triggers add `web` and `contracts` (above); `infra/build-images.sh` builds `kvitt-server` with context `.`; `infra/dev/compose.yaml` has no build section, so `infra/dev/build.sh` builds with the repository root as context (`KVITT_SERVER_BUILD_CONTEXT` still overrides it). The Pi runner builds the Node stage too (its duration on the Pi 3 not yet measured); the web client adds no image and no service.
* `server` image: multi-stage (since D-137 the Node `web` stage above runs first; the stages below are the Rust build and the runtime). Stage 1 `rust:<version>-bookworm`, where `<version>` is the exact Rust release pinned in `server/rust-toolchain.toml` (the current stable when M2a pins it; the two always change together), builds `kvitt-server` and `kvitt-import` in release mode with `--locked` for `aarch64-unknown-linux-gnu` (native on the M4; no `target-cpu=native`, the Pi 3 is a Cortex-A53). Stage 2 `gcr.io/distroless/cc-debian12:nonroot` (arm64) pinned by digest, with the two binaries in `/usr/local/bin/`, user 10001, entrypoint `kvitt-server`, command `serve`. The Dockerfile selects the Rust target from `TARGETARCH`: `arm64` (`aarch64-unknown-linux-gnu`) is the shipped target; `amd64` (`x86_64-unknown-linux-gnu`) also builds, emulated on the Mac, for local use only. Since M4 the server depends on reqwest with rustls on aws-lc-rs and on jsonwebtoken (§6.3): aws-lc-rs compiles C code, so the arm64 build stage needs a C toolchain beside Rust, and the distroless runtime image must carry CA roots for the platform verifier to reach Google's endpoints. The dev image (`infra/dev`, linux/arm64 on the Mac) was rebuilt with these crates on 2026-10-18 and built cleanly. The Pi image's C stage and CA roots, and an OAuth plus FCM call from the image, were confirmed on the Mac on 2026-10-18 (`docs/spikes/pi-image-arm64.md`, landed `3e6c337`): arm64 image 63.8 MB, cold build 48 s, CA bundle from distroless, binaries run natively; running on the Pi itself is M2c-pi's.
* `backup` image: `alpine` with `sqlite`, `gzip`, `tar`, `rclone` and `tzdata`, and `infra/backup/backup.sh` run by supercronic; the healthcheck is `infra/backup/healthcheck.sh`.
* The backup sidecar schedules with supercronic instead of busybox `crond` (D-104): it runs as a non-root user, and busybox `crond` started as a non-root user runs no job (tested 2026-10-18 in alpine 3.24.2). The schedule is unchanged (`30 3 * * *`).
* Pinned versions (resolved 2026-10-18, D-104; table in `infra/README.md` "Versions"): Alpine `alpine:3.24.2@sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6` for the backup sidecar; backup packages supercronic 0.2.49 beside M2c-dev's sqlite, rclone and tar. The Caddy pin and the cert-sync packages left with D-120; Nginx Proxy Manager is the owner's existing install, and the block of §10.5.2 was written against NPM v2.16.0's templates. Docker Engine on the Kvitt Pi (a prerequisite, already installed, D-125) comes from Docker's Debian arm64 apt repository (docs.docker.com: the Raspberry Pi OS page is for 32-bit only), `docker-ce` 5:29.8.2 with `docker-ce-cli`, `containerd.io`, `docker-buildx-plugin` and `docker-compose-plugin`.
* No scripts on the Pi (D-125, revises D-103): `install.sh`, `deploy.sh`, `bootstrap.sh`, `backup-now.sh`, `install-apk.sh` and `lib.sh` were removed in `6e5981d`. Their equivalents are plain `docker compose` commands the owner runs in `~/kvitt`: install = copy `compose.yaml`, `.env` and `secrets/` from the Mac, `mkdir -p data/apk backups import`, `docker compose pull && docker compose up -d`, `curl localhost:8080/health`; bootstrap = `docker compose exec server kvitt-server bootstrap`; partner invite = `docker compose exec server kvitt-server invite-partner`; one backup = `docker compose exec backup /backup.sh`; deploy and rollback §10.10; APK §10.6; restore §10.9. A changed `compose.yaml` or `.env` is copied again the same way. The checks `install.sh` made on `.env` are gone (compose refuses an unset key, §10.2); its `/opt/kvitt/deployed-digests` record is replaced by `docker image inspect` (§10.10).
* The Pi's Docker daemon must trust `gitea.lan` as an insecure (plain HTTP) registry (`insecure-registries` in `/etc/docker/daemon.json`). This is a prerequisite the owner keeps (the Kvitt Pi already has it for another project); nothing of Kvitt edits the daemon or the system (D-125; `install.sh` added it with sudo, D-103). Were the packages private, the owner runs `docker login gitea.lan` once with a `read:package` token (D-125).

### 10.4 Server configuration and CLI

Environment variables (exhaustive):

| Variable | Default | Meaning |
|---|---|---|
| `KVITT_DATA_DIR` | `/data` | Holds `kvitt.sqlite`, `pictures/`, `apk/` |
| `KVITT_BIND` | `0.0.0.0:8080` | Listen address |
| `KVITT_PUBLIC_URL` | none: required (D-123) | Used in invite links and the landing page. Unset or empty, every `kvitt-server` command exits 1 with a configuration error (`configuration: KVITT_PUBLIC_URL is not set …` on stderr) before opening the database; there is no built-in host (the fallback `DEFAULT_PUBLIC_URL` was removed by D-123). The Pi's compose sets `https://${KVITT_PUBLIC_HOST}` (port 443, D-124) from the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen, recorded in HANDOFF) (D-120); the development stack sets `http://<Mac LAN address>:<port>` (`infra/dev/up.sh`; the dev compose falls back to `http://localhost:8080`) |
| `KVITT_FCM_CREDENTIALS` | `/secrets/fcm-service-account.json` | Service-account key; if the file is missing, push is disabled and a warning is logged at start |
| `KVITT_FCM_PROJECT_ID` | `kvitt-1337` | FCM project |
| `KVITT_TRUSTED_PROXY` | `none` | IP literal or host name whose resolved address may set `X-Forwarded-For` (not a CIDR). The default `none` (`NO_TRUSTED_PROXY` in `config.rs`, compared ignoring case and surrounding white space) means no proxy and is never looked up (D-123; was `caddy`); an empty value counts as unset. Compose sets it to `HA_HOST`, NPM's LAN IPv4 address (D-120). The server must start when the name does not resolve (as on the development stack, which has no proxy, D-022 unchanged); with `none` or an unresolvable name no peer is trusted and the peer address is the client IP (D-022). The name is re-resolved at most every 60 seconds (D-032) |
| `KVITT_WEB_DIR` | `/app` | Directory of the built web client, served under `/app/` (D-135, §15.4). Missing (an image without the web client, `cargo run` in development): every `/app` path is 404 `not_found` |
| `KVITT_EB_APP_ID` | empty | Enable Banking application id for card purchases (D-175, CP-13): the admin's, and the member's too unless `KVITT_EB_MEMBER_APP_ID` is set. Empty, or its key file missing or unreadable: card features are disabled for that user (E-36 `available` false), with one warning at start, as push is (§14.6) |
| `KVITT_EB_KEY_FILE` | `/secrets/cards/enable-banking.pem` | The PEM private key of `KVITT_EB_APP_ID`, as Enable Banking's control panel downloads it (`<application id>.pem`, renamed) |
| `KVITT_EB_MEMBER_APP_ID` | empty | The member's own Enable Banking application (CP-13 fallback); empty: the member uses `KVITT_EB_APP_ID` |
| `KVITT_EB_MEMBER_KEY_FILE` | `/secrets/cards/enable-banking-member.pem` | The PEM private key of `KVITT_EB_MEMBER_APP_ID` |
| `KVITT_EB_API_URL` | `https://api.enablebanking.com` | Enable Banking API base URL; tests point it at a local stub |
| `RUST_LOG` | `info` | tracing filter |

The time zone `Europe/Stockholm` is a constant in code, not configuration.

Files under `KVITT_DATA_DIR`:

* `kvitt.sqlite` (+ `-wal`, `-shm`)
* `pictures/<user_id>/<picture_version>-512.jpg` and `-128.jpg`; older versions are deleted after a successful upload. E-10 deletes the JPEGs and leaves an empty marker file `<picture_version>-removed` in `pictures/<user_id>/`; the next upload uses the highest version on disk (JPEG or marker) plus one, so a cache keyed by (`user_id`, `picture_version`) never shows a removed picture. The first upload is version 1 (D-030).
* `apk/latest.json` and `apk/kvitt-<version_code>.apk`

`kvitt-server` subcommands (exhaustive):

| Command | Effect | Exit codes |
|---|---|---|
| `serve` | Run migrations, start scheduler, push sender and HTTP server | 0 on clean shutdown (SIGTERM drains in-flight requests up to 10 s) |
| `bootstrap` | FR-1 | 0 ok, 2 already initialized |
| `pair-device --user <user_id>` | AC-1.6 | 0 ok, 3 unknown user |
| `invite-partner` | Creates a partner invite by the admin, as E-12 (D-113) | 0 ok, 2 household full, 3 no admin |
| `rotate-epoch` | Sets a new random `sync_epoch` and prints it on stdout (§10.9) | 0 ok, 1 database error |
| `healthcheck` | Calls `http://127.0.0.1:<port of KVITT_BIND>/health` (8080 by default), exit 0 if 200; used by the compose healthchecks of both stacks (no curl in the image) | 0 or 1 |
| `migrate` | Run migrations only | 0 |

Run them on the Pi in `~/kvitt` with `docker compose exec server kvitt-server <command>` (or `docker compose run --rm server <command>` when `server` is stopped) (D-125). Outside Docker, from the workspace root `server/`: `cargo run -p kvitt-server -- <command>` (the `-p` is needed because the workspace has two binaries), with `KVITT_DATA_DIR` set (`server/README.md`).

### 10.5 TLS

TLS terminates in the owner's Nginx Proxy Manager (NPM) on the Home Assistant Pi (D-120; Caddy and cert-sync, which held this section until v0.20, are removed). Kvitt has its own public host name, `KVITT_PUBLIC_HOST` (owner-chosen, recorded in `docs/HANDOFF.md`), because `icehack.asuscomm.com` is NPM's proxy host for Home Assistant and NPM selects the proxy host by name, not by port. `KVITT_PUBLIC_URL` is `https://${KVITT_PUBLIC_HOST}`, with no explicit port: Kvitt is served on the default HTTPS port 443, on which NPM listens for every proxy host and selects by name (D-124). Serving Kvitt under a path prefix of another name (for example `icehack.asuscomm.com/kvitt/`) is not supported. The router forwards external TCP 443 to the Home Assistant Pi's 443 (NPM), already in place for Home Assistant, which serves Kvitt too: no new router rule (D-124; the 8443 rule of D-120 is not used); nothing is forwarded to the Kvitt Pi. NPM issues and renews the name's Let's Encrypt certificate through the HTTP-01 challenge on port 80, which already reaches NPM. The owner sets up the proxy host in NPM's web UI from `infra/README.md` "Pi: what the owner does", step 4 (step 6 before D-125); no agent and no script touches NPM. The proxy host carries the app gate of §8.5 (D-126) in its Custom Nginx Configuration (§10.5.2), set up by step 4a once both phones run an APK that carries the key; an APK without the key cannot reach the server from outside the LAN, its update download included. Since D-130 the gate also lets the web client through (§8.5, §15.2): its files under `/app/`, the invite accept and bearer-token requests.

#### 10.5.1 Nginx Proxy Manager

NPM's web UI (Home Assistant, Settings, Add-ons, Nginx Proxy Manager, Open Web UI), Hosts, Proxy Hosts, Add Proxy Host:

| Tab | Field | Value |
|---|---|---|
| Details | Domain Names | `<KVITT_PUBLIC_HOST>` (currently `kvitt.suorra.duckdns.org`, HANDOFF) |
| Details | Scheme | `http` |
| Details | Forward Hostname / IP | `<kvitt-pi-address>` (the Kvitt Pi's LAN IPv4 address) |
| Details | Forward Port | `8080` |
| Details | Cache Assets | off |
| Details | Block Common Exploits | on |
| Details | Websockets Support | off |
| Details | Access List | Publicly Accessible (the app gate is in the Advanced block, D-126: an NPM access list checks addresses or HTTP basic auth, not a header, and basic auth would take the `Authorization` header the bearer token needs) |
| Custom Locations | (none) | left empty |
| SSL | SSL Certificate | Request a new Certificate: Let's Encrypt, HTTP challenge (Use DNS Challenge off), the owner's email address, Terms of Service accepted where shown |
| SSL | Force SSL | on |
| SSL | HTTP/2 Support | on |
| SSL | HSTS Enabled | on |
| SSL | HSTS Sub-domains | off |
| SSL | Trust Upstream Forwarded Proto Headers | off |
| Advanced | Custom Nginx Configuration | the block of §10.5.2, exactly, comments included |

* Plain HTTP on the LAN: NPM forwards plain HTTP over the home LAN to `<kvitt-pi-address>:8080`, accepted by the owner (D-120). Anyone on the home LAN can also reach that port directly; such requests count against their own address for the limits of §8.6, and only `HA_HOST` may set `X-Forwarded-For` (§8.9).
* Client IP: NPM's request to the server carries `X-Forwarded-For: <what the client sent>, <client address>`. The server takes the last entry only when the TCP peer is `KVITT_TRUSTED_PROXY`, which compose sets to `HA_HOST`, NPM's LAN IPv4 address (an IP literal in `.env`, because the container cannot resolve an mDNS name such as `homeassistant.local`; nothing checks it since D-125); the server is unchanged (D-032, D-115, D-119). The router's forward keeps the internet client's source address, and Docker's published port keeps NPM's (DNAT, no SNAT, for traffic arriving on the LAN interface), so the per-IP limits see real addresses (checked once, §10.10). The server does not use `X-Forwarded-Proto` or `Host`: links are built from `KVITT_PUBLIC_URL` (E-12).
* `X-Real-IP` (accepted): NPM's `nginx.conf` takes the client address from `X-Real-IP` when the connection comes from 10/8, 172.16/12 or 192.168/16 (and the CDN ranges it downloads), so a device on the home LAN can choose its own client address for the rate limits. Internet clients arrive with their public address (the router's forward keeps the source address), so their `X-Real-IP` is ignored.
* HSTS: NPM sends `Strict-Transport-Security` with `max-age=63072000; preload` (two years, NPM's value) at server level. A browser then uses only HTTPS for `<KVITT_PUBLIC_HOST>`, on every port, and refuses certificate warnings for it; turning HSTS off later does not clear browsers that already stored it. Because the name is Kvitt's own nothing else is affected, but anything ever served under `<KVITT_PUBLIC_HOST>` (any port) must be HTTPS with a valid certificate too. The app does not rely on HSTS (release builds allow no cleartext, §8.5); it protects the landing page in a browser.
* Health checks (D-125, revises D-120 point 6; no script runs them): after a start or a deploy the owner runs `curl -s localhost:8080/health` on the Kvitt Pi, and checks `/health` through NPM from the Pi (`curl -fsS --resolve <KVITT_PUBLIC_HOST>:443:<HA_HOST> https://<KVITT_PUBLIC_HOST>/health`, with the certificate checked; the Kvitt Pi is on the LAN, so no key is needed, D-126) and from outside: with the app gate in place (D-126) a browser outside the LAN gets a closed connection by design, so the outside check is the app's About screen (S-22) on the phone with Wi-Fi off, or `curl -fsS -H "X-Kvitt-App: $KEY" https://<KVITT_PUBLIC_HOST>/health` from outside the home network (before the gate: `https://<KVITT_PUBLIC_HOST>/health` in Chrome on the phone with Wi-Fi off); `infra/README.md` "Pi: what the owner does" steps 3, 4, 4a and 6.

#### 10.5.2 Custom Nginx Configuration

The block pasted into the proxy host's Advanced tab (D-120; it carries over D-117's response headers and log redaction). Written against NPM v2.16.0's proxy host template (`backend/templates/proxy_host.conf`); as of v0.28 it reads (`infra/README.md`, step 4, and the file `infra/npm/kvitt.conf`, three identical copies; the app gate lines added by D-126, the web client's gate lines and the `$kvitt_csp` variable by D-130 and D-132, the rest as of `62f5279`):

```nginx
# Kvitt (SPEC §10.5.2, D-120, D-126, D-130). NPM, Proxy Host <KVITT_PUBLIC_HOST>, Advanced tab, Custom Nginx Configuration.
# App gate (SPEC §8.5, D-126): outside the home LAN only a request carrying the key built into the app passes;
# everything else gets the connection closed (444: nothing sent, nothing to fingerprint). Put the key from
# android/local.properties (kvitt.appKey) in place of KVITT_APP_KEY. To rotate, add a second if-line with the new key.
# The LAN check reads $realip_remote_addr, the address that really connected: NPM replaces $remote_addr with the
# request's own X-Real-IP header for private peers, so $remote_addr could be forged. Let's Encrypt's renewal passes.
set $kvitt_gate 0;
if ($http_x_kvitt_app = "KVITT_APP_KEY") { set $kvitt_gate 1; }
if ($realip_remote_addr ~ "^192\.168\.1\.") { set $kvitt_gate 1; }
if ($uri ~ "^/\.well-known/acme-challenge/") { set $kvitt_gate 1; }
# Web client (SPEC §15, D-130): its files under /app/, the invite accept it logs in with, and any request carrying a
# bearer token (the server checks the token; unknown tokens are rate-limited per IP), except /health, /setup/, /i/
# and /apk/, which stay LAN-or-key only.
if ($uri ~ "^/app(/|$)") { set $kvitt_gate 1; }
if ($uri = "/invites/accept") { set $kvitt_gate 1; }
# Card connection (SPEC §9.12, D-163): the bank redirects the user's browser here, without the app key.
if ($uri = "/cards/callback") { set $kvitt_gate 1; }
set $kvitt_bearer 0;
if ($http_authorization ~ "^Bearer ") { set $kvitt_bearer 1; }
if ($uri ~ "^/(health|setup/|i/|apk/)") { set $kvitt_bearer 0; }
if ($kvitt_bearer = 1) { set $kvitt_gate 1; }
if ($kvitt_gate = 0) { return 444; }
# Server body: 1 MiB, PUT /me/picture 5 MiB (SPEC §8.6); the server answers anything larger with its own 413.
client_max_body_size 6m;
# No long-poll in the API (SPEC §14.3); 60 s between two reads from the server.
proxy_read_timeout 60s;
# Response headers (D-117). They live at server level, so no location below may use add_header (nginx would then
# drop all of these in it); NPM's HSTS line (SSL tab) sits at the same level. The server's own copy is hidden, so
# each header appears once (the landing page sends Referrer-Policy itself).
proxy_hide_header Content-Security-Policy;
proxy_hide_header X-Content-Type-Options;
proxy_hide_header X-Frame-Options;
proxy_hide_header Referrer-Policy;
# The web client under /app/ (D-132) needs its own scripts, styles, images and API calls: one variable, still one
# server-level add_header.
set $kvitt_csp "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
if ($uri ~ "^/app(/|$)") { set $kvitt_csp "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; font-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"; }
add_header Content-Security-Policy $kvitt_csp always;
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options DENY always;
add_header Referrer-Policy no-referrer always;
# Replaces NPM's own "location /" (NPM leaves it out when this field has one), whose add_header X-Served-By would
# drop the headers above. $forward_scheme, $server and $port are NPM's Details tab values.
location / {
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_pass $forward_scheme://$server:$port$request_uri;
}
# Invite links /i/<code>?from=<name>: neither the code nor the inviter's name may reach a log (SPEC §8.7). NPM's
# access log format writes the whole $request_uri, query string included, so this path is not logged at all, and
# its error log (which would carry the request line on a 502) goes nowhere.
location ^~ /i/ {
  access_log off;
  error_log /dev/null crit;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_pass $forward_scheme://$server:$port$request_uri;
}
# Card connection callback /cards/callback?code=…&state=… (SPEC §9.12, D-163): the query carries a one-time
# authorisation code and the attempt's state, so this path is not logged at all, a 502 included.
location = /cards/callback {
  access_log off;
  error_log /dev/null crit;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_pass $forward_scheme://$server:$port$request_uri;
}
```

* Card callback (D-163, v0.35): `/cards/callback` passes the gate from outside (the bank's redirect reaches it from the user's browser, a Custom Tab on mobile data included, which carries no app key) and is not logged by NPM (`location = /cards/callback`, as `/i/`), because its query holds the authorisation `code` and `state`. The exemption tests the normalised `$uri` exactly, so no other path rides on it. The server answers it with its own page (E-39) and the D-117 headers apply (the page needs no script; its one link is an `<a href>`). Before the gate goes in, the line is left out with the other gate lines. K1 updates `infra/npm/kvitt.conf` and `infra/README.md` step 4 and repeats the nginx check (`nginx -t`, a request to `/cards/callback` from a non-LAN address reaching the upstream, no access-log line).
* Response headers (D-117): `Content-Security-Policy`, `X-Content-Type-Options`, `X-Frame-Options` and `Referrer-Policy` are set at server level with `always`, and the server's own copies are hidden with `proxy_hide_header`, so each header appears once (the landing page sends `Referrer-Policy: no-referrer` itself, AC-2.5). NPM's HSTS line from the SSL tab sits at the same level.
* Its own `location /`: nginx drops every `add_header` inherited from the server level in a location that has an `add_header` of its own, and NPM's default `location /` has one (`X-Served-By`), which would silently drop the four headers. NPM leaves its default location out when the Custom Nginx Configuration contains `location /` (NPM matches it with the regex `^(?:.*;)?\s*?location\s*?\/\s*?{`), so the block brings its own, without `add_header`. Its `proxy_pass` uses NPM's Details values (`$forward_scheme`, `$server`, `$port`). If a later NPM release changes the proxy host template, the headers are checked again (§10.10).
* `client_max_body_size 6m`: above the server's own limits (1 MiB, 5 MiB for `PUT /me/picture`, §8.6), which answer `payload_too_large` themselves; larger bodies get NPM's 413. `proxy_read_timeout 60s`: the API has no long-poll.
* Logs (§8.7): NPM writes one access log line per request to `/data/logs/proxy-host-<id>_access.log` inside NPM, in its `proxy` format: time, cache and upstream status, status, method, scheme, host, `"$request_uri"` (the path with its query string), `[Client <address>]`, length, gzip ratio, `[Sent-to <KVITT_PI_HOST>]`, user agent and referer. It logs no request headers, so the `Authorization` token is never logged. Query strings are logged for every path except `/i/`; the API's other query parameters are `since` and `limit` (`GET /sync`) and `size` and `v` (pictures), which hold no personal content. `location ^~ /i/` turns the access log off and sends its error log to `/dev/null`, so neither the invite code nor the inviter's name (`?from=`) reaches a log, a 502 included. Errors on other paths (for example a 502 while the server is down) go to `proxy-host-<id>_error.log` with the request line.
* App gate (§8.5, D-126): `set`, `if` and `return` are rewrite-module directives; at server level they run in NPM's server rewrite phase, before a location is chosen, so the gate covers every location, `/i/` included, and no `add_header` is involved. `KVITT_APP_KEY` is replaced by the key from `android/local.properties`; a rotation adds a second `if ($http_x_kvitt_app = …)` line. `$realip_remote_addr` is the TCP peer: NPM's `nginx.conf` has `set_real_ip_from` 10/8, 172.16/12 and 192.168/16 with `real_ip_header X-Real-IP`, which would let a LAN client, or every client if NPM saw a Docker bridge address (security review I-5), choose `$remote_addr`. The Let's Encrypt exemption tests the normalised `$uri`, which location matching uses, so `/.well-known/acme-challenge/../../health` is closed; that path is served by NPM's own `location ^~ /.well-known/acme-challenge/` from its webroot, never proxied. NPM's own server-level rules come first in its template: Force SSL answers port 80 with a 301 to `https://` (Let's Encrypt follows it, which is why the exemption is needed on 443), and Block Common Exploits answers its patterns with 403. If NPM saw a Docker bridge address for every client, the LAN check would match nothing; if the router rewrote internet clients to its LAN address, everything; NAT hairpin makes a LAN client appear as the router's `192.168.1.1`, still inside the /24. The owner's acceptance test (`infra/README.md` step 4a): on the home Wi-Fi `https://<KVITT_PUBLIC_HOST>/i/TEST` shows the page in a browser, with Wi-Fi off it gives a connection error, and the app's About screen still shows the server version.
* Web client gate (D-130): `/app` and `/app/…` and `POST /invites/accept` pass on the normalised `$uri` (so `/app/../health` is closed); a bearer header passes through the helper variable `$kvitt_bearer`, which the next line clears for `/health`, `/setup/`, `/i/` and `/apk/`, because nginx's `if` takes one condition. The value of the bearer header is not checked by NPM (the server does). Before the gate first goes in (step 4a), the gate lines from `set $kvitt_gate 0;` to `return 444;` are left out together.
* Content-Security-Policy (D-132): `$kvitt_csp` holds the D-117 policy, and for `/app/` the web client's: its own origin for scripts, styles (inline styles allowed, as D-117 allows them), images (plus `blob:` for profile pictures fetched with the token and `data:`), fonts and API calls; `default-src 'none'`, `base-uri 'none'`, `form-action 'none'`, `frame-ancestors 'none'` as before. One server-level `add_header` with a variable keeps the rule that no location has an `add_header`. The server's own `/app/` header (W7) is hidden like the others and should carry the same policy (it is the one the development stack shows).
* Verified on the Mac on 2026-10-21 (D-130, D-132): `nginx -t` (nginx:alpine 1.31.7) of the block above with a test key in a server block whose upstream is a stub, and 17 requests from a non-LAN address: `/health`, `/sync` without a header, `/sync` with `Authorization: Basic`, `/invites/acceptx`, `/application`, `/app/../health` and, with a bearer header, `/health`, `/i/TEST`, `/apk/latest` and `/setup/status` were closed with no reply; `/health` with the key, `/app`, `/app/`, `/app/login`, `POST /invites/accept`, `/accounts` with a bearer header and the ACME path reached the upstream; `/app/` carried the web policy and `/accounts` the D-117 policy, each once, with the other three headers. Not checked: NPM's own template and `real_ip` settings with these lines (the 2026-10-21 D-126 rehearsal covered them for the earlier lines), the real proxy host.
* Verified on the Mac on 2026-10-21 (D-126): the block above, with a test key, inside a server block with NPM v2.16.0's `letsencrypt-acme-challenge.conf` and `block-exploits.conf` includes and its `real_ip` settings, run by the openresty 1.31.1.1 of the `jc21/nginx-proxy-manager:2` image (v2.16.0): `nginx -t` successful; without the header, with a wrong key, with a forged `X-Real-IP: 192.168.1.50`, on `/i/` and `/apk/files/` without the header, and on `/.well-known/acme-challenge/../../health`, the connection was closed with no reply; with the key `/health` and `/i/` reached the upstream with the D-117 headers; an ACME token file was served; a second key line passed; a peer matching the LAN pattern passed without the header; with `$remote_addr` instead of `$realip_remote_addr` the forged `X-Real-IP` passed (why the block uses the latter). Not checked: HTTPS and HTTP/2 through NPM's real proxy host, the router and the real LAN addresses (the owner's acceptance test).
* Verified on the Mac on 2026-10-19 (D-120): `nginx -t` (nginx:alpine 1.31.7) of the block inside a minimal server block and inside a copy of NPM v2.16.0's `nginx.conf` with the proxy host rendered as NPM's template renders it for the §10.5.1 settings, both successful; a Podman rehearsal of the server image built from `server/Dockerfile` (arm64, hardened as on the Pi) behind that nginx with a self-signed certificate, 21 checks passed: the four headers and `Strict-Transport-Security` once each over HTTP/2 and no `X-Served-By`; one `Referrer-Policy` on the landing page; `http://` answered 301 to `https://`; a 7 MB body refused by nginx (413), a 2 MB body answered by the server (`payload_too_large`); the rate limit applied per forwarded client and a forged `X-Forwarded-For` did not escape it; the invite code, the name and `/i/` absent from nginx's access and error logs after `/i/`, `//i/` and `/%69/` requests and a 502 on `/i/`. Not checked (needs the real hosts): NPM's own UI and Let's Encrypt for the Kvitt host name, the router forward.

#### 10.5.3 Fallback: NPM down

* NPM or the Home Assistant Pi down means Kvitt is unreachable from outside, and also from home over `https://<KVITT_PUBLIC_HOST>` (that path goes through NPM too). The server on the Kvitt Pi keeps running and nothing there needs to change; the phones keep working on their full local copy and sync when NPM is back (FR-15).
* On the home Wi-Fi only debug builds can reach the server directly, at `http://<kvitt-pi-address>:8080` (AC-2.8 allows `http://` to private LAN addresses in debug builds only). Release builds require HTTPS with a publicly trusted certificate (§8.5): there is no LAN fallback for the release app. A debug build is a separate app (`se.hagstedt.kvitt.debug`) with its own pairing and data, not a stand-in for the release app.
* If NPM cannot renew the Let's Encrypt certificate, it is fixed in NPM (SSL Certificates, the certificate, Renew Now; port 80 must reach NPM).
* The pinned-root switch of D-082 (`kvitt.tls.pinnedRoot=true` in `android/gradle.properties`; the pinned-root config is generated at build time from the template `android/app/src/releasePinnedRoot/network_security_config.xml` with the domain `kvitt.publicHost`, into the release resources only when `kvitt.tls.pinnedRoot=true`, a `domain-config` trusting only `@raw/kvitt_root_ca`; the build stops with a message while `android/app/src/release/res/raw/kvitt_root_ca.crt` is not committed, D-121, `038c603`) remains available for a self-made root whose certificate would be uploaded to NPM as a Custom certificate. It is not prepared: no such root exists and none is committed.

### 10.6 APK hosting and release

* `version_code` = `git rev-list --count HEAD` on the commit being released; `version_name` = `YYYY.MM.DD-<short sha>` of that commit (its commit date in Europe/Stockholm). Both are passed to Gradle as properties `kvitt.versionCode` and `kvitt.versionName` by the release script; debug builds use `1` and `dev`.
* The release keystore is created once on the Mac (by the owner, or by an agent the owner allows; §11, D-024, D-101) at the root of the main checkout as `kvitt-release.jks`, with exactly:

  ```
  keytool -genkeypair -v -keystore kvitt-release.jks -alias kvitt -keyalg RSA -keysize 4096 -validity 10000
  ```

  The file is git-ignored by the `*.jks` pattern and never committed (D-101, revises D-024's "outside the repository"). `android/local.properties` holds its absolute path and secrets in the keys `kvitt.release.storeFile`, `kvitt.release.storePassword`, `kvitt.release.keyAlias` (`kvitt`), `kvitt.release.keyPassword`. Losing it means the phones must uninstall and reinstall (data comes back by sync). The owner keeps a copy of the file and its password in their password manager. Without these keys in `local.properties`, `:app:assembleRelease` builds an unsigned APK (M8). Release signing was verified on 2026-10-18: alias `kvitt`, RSA 4096, APK signature scheme v2.
* Release builds are R8-shrunk, optimised and obfuscated (`isMinifyEnabled`, `isShrinkResources`, `proguard-android-optimize.txt` plus `android/app/proguard-rules.pro`, no project keep rules needed as of 2026-10-18; landed `c30a49e`); the signed APK is about 10 MB (10.0 MB at `a0259ab`; 43 MB before R8); `infra/publish-apk.sh` saves `mapping.txt` next to the APK as `kvitt-<version_code>.mapping.txt` for retrace; mappings are never served and stay on the Mac, outside the Pi's `data/` (D-103, D-125).
* `infra/publish-apk.sh` on the Mac (D-103): refuses a dirty working tree, reads `KVITT_PUBLIC_HOST` from `infra/pi/.env` (read, not sourced; it refuses a missing file or key, a `CHANGE_ME` value, anything that is not a host name, a URL included, and the old name `icehack.asuscomm.com`; landed `4b1ae0c`, D-122), builds `:app:assembleRelease` through `tools/gradle-serial.sh` with `-Pkvitt.versionCode`, `-Pkvitt.versionName` and `-Pkvitt.publicHost=<KVITT_PUBLIC_HOST>`, prints the release server `https://<KVITT_PUBLIC_HOST>` (D-124) in its header and summary, refuses an unsigned APK, computes SHA-256 and size, and writes into `infra/pi/out/apk/` (git-ignored) `kvitt-<version_code>.apk`, `kvitt-<version_code>.mapping.txt` and `latest.json` (written to a temp file, then renamed), keeping the newest 5 APKs with their mappings there. The owner then copies, from the Mac, the APK first and `latest.json` last straight into the server's `data/apk/` on the Pi (`scp infra/pi/out/apk/kvitt-<version_code>.apk jacobhagstedt@<kvitt-pi-address>:kvitt/data/apk/`, then the same for `infra/pi/out/apk/latest.json`), so the server, which reads `latest.json` on every request, never announces a file it does not have; `curl -s http://<kvitt-pi-address>:8080/apk/latest` then shows the new `version_code` (D-125; `install-apk.sh`, with its SHA-256 check against `latest.json` and its copy into the named volume, is removed). The mapping files stay on the Mac. `latest.json`:

```json
{
  "version_code": 412,
  "version_name": "2026.11.02-1a2b3c4",
  "file_name": "kvitt-412.apk",
  "size_bytes": 18234567,
  "sha256": "9f2c…64 hex chars…",
  "released_at": "2026-11-02T19:40:00.000Z"
}
```

* The release server's host name is a build property (D-121): `kvitt.publicHost` is read from the Gradle property (`-Pkvitt.publicHost=…`), else the key `kvitt.publicHost` in `android/local.properties` (the owner's, git-ignored), else the placeholder `kvitt.example.invalid` (RFC 2606; it never resolves, so a release built without the property cannot reach a real host). The build refuses a value that is not a host name. `:app` exposes it as `BuildConfig.PUBLIC_HOST`, as the manifest placeholder `publicHost` (the AC-2.6 `https` intent filter, no port, so it matches every port of the host, path prefix `/i/`, `android:autoVerify="false"`, D-124) and as `RELEASE_SERVER_URL` = `releaseServerUrl(host)` = `https://<host>` (`link/ReleaseServer.kt`, `releaseServerUrl` in `:feature:onboarding`'s `ServerAddress.kt`; `RELEASE_SERVER_PORT` removed, D-124); `:feature:onboarding` receives that URL through the Hilt qualifier `@ReleaseServerUrl` (§13.3 S-1), and `:data` through `AppBuildInfo.releaseServerUrl`, which S-22 shows before pairing (D-122). Invite-link parsing still accepts a server named by the link and drops an explicit default port (`:443`, `:80`) (AC-2.6, D-124). Tests and goldens use fixed fixture hosts. `infra/publish-apk.sh` passes `-Pkvitt.publicHost` from `KVITT_PUBLIC_HOST` in `infra/pi/.env` (above, §10.5, D-122); the owner may instead set the key in `android/local.properties`. Its sibling `kvitt.appKey` (D-126, next item) is read the same way.
* The app key is a build property too (D-126, modelled on D-121): `kvitt.appKey` from the Gradle property (`-Pkvitt.appKey=…`), else the key `kvitt.appKey` in `android/local.properties`, else empty (no `X-Kvitt-App` header sent); `BuildConfig.APP_KEY` (§8.5). A release APK carries the key it was built with, so the APK must be rebuilt after the key is set or rotated; `infra/publish-apk.sh` needs no change, because it builds on the Mac, where `android/local.properties` holds the key. An APK without the key cannot reach the server from outside the home LAN once the app gate is in NPM, its update download included, so both phones run a keyed APK before the gate goes in (`infra/README.md` step 4a). Anyone holding the APK holds the key; the owner alone distributes it (first install on both phones by hand) and rotates the key if an APK leaks (§8.5).
* With `--deploy` (D-139) the script copies the APK first and `latest.json` last itself, with the forced-command deploy key `infra/secrets/pi_deploy_ed25519` (scp into `data/apk/` only), and fails unless `https://<KVITT_PUBLIC_HOST>/apk/latest`, requested with `X-Kvitt-App`, returns the new `version_code`; the manual scp stays the fallback (`infra/README.md` "Publishing an APK").
* The server reads `latest.json` on each `GET /apk/latest` (no cache) and serves `GET /apk/files/{file_name}` only for a `file_name` matching `^kvitt-[0-9]+\.apk$` that exists, with `Content-Type: application/vnd.android.package-archive`.
* Downloads are limited to 10 per minute per client IP (§8.6, D-119); E-5 stays on the 60 per minute of the other unauthenticated endpoints. If one address still fetches `/apk/files/` over and over (NPM's access log), the owner's stop-gap is to disable Kvitt's proxy host in NPM (Hosts, Proxy Hosts, the row's menu, Disable) until it stops; the router's 443 forward stays, because it also serves Home Assistant (D-124, `infra/README.md`). Since the app gate (D-126) a request from outside without the app key never reaches the server, so this concerns the home LAN or a leaked key.
* Older APKs stay in `data/apk/` on the Pi until the owner removes them by hand (D-125; `install-apk.sh` kept the newest 5, D-103); `infra/pi/out/apk/` on the Mac keeps the newest 5.
* The web client (D-132) is part of the server image: it is published by deploying a server image (§10.10), with no step of its own here; a browser loads the new version on its next page load (`index.html` is never cached, §15.4).

### 10.7 Firebase setup (M2c-dev, with a HUMAN sign-in)

No new command-line tool is installed for this (D-022): `gcloud` exists on the Mac, the Firebase CLI is not used, and the Firebase project and Android apps are created through the Firebase Management REST API (`https://firebase.googleapis.com/v1beta1/`) with the access token of `gcloud auth print-access-token`. The agent confirms the exact requests from Google's official API reference at implementation time.

1. HUMAN: `gcloud auth login` on the Mac with the owner's Google account.
2. `gcloud config set project kvitt-1337`; `gcloud services enable fcm.googleapis.com firebase.googleapis.com`.
3. Add Firebase to the project (`projects.addFirebase`), skipped if it is already a Firebase project.
4. Create two Android apps (`projects.androidApps.create`): display name "Kvitt", package `se.hagstedt.kvitt`; display name "Kvitt debug", package `se.hagstedt.kvitt.debug`.
5. Fetch each app's config (`projects.androidApps.getConfig`) and merge them into one `google-services.json` holding both clients, written to `infra/secrets/google-services.json` in the main checkout (git-ignored). M8 copies it into `android/app/google-services.json` (git-ignored) with `infra/dev/copy-google-services.sh <main checkout>`, written by M2c-dev.
6. `gcloud iam service-accounts create kvitt-fcm --display-name "Kvitt FCM sender"`; grant `roles/firebasecloudmessaging.admin` on the project; `gcloud iam service-accounts keys create infra/secrets/fcm-service-account.json --iam-account kvitt-fcm@kvitt-1337.iam.gserviceaccount.com`.
7. Copy the key to `~/kvitt/secrets/fcm-service-account.json` on the Pi, owned by the owner, mode 0600 (D-125; was `/opt/kvitt/secrets/`, mode 0440, root:10001, installed by `install.sh`, D-103). Done by the owner (`infra/README.md` "Pi: what the owner does", steps 2 and 3).
8. If an organisation policy blocks service-account key creation, stop and report; do not change org policies.

The agent may write these git-ignored files under `infra/secrets/` in the main checkout and act on the Google Cloud project `kvitt-1337` for steps 2 to 6 (D-022); nothing else outside the repository.

State after M2c-dev (`c885aba`): steps 1 to 6 are done. Firebase is added to project `kvitt-1337`; Android apps exist for `se.hagstedt.kvitt` and `se.hagstedt.kvitt.debug`; the APIs `firebase.googleapis.com`, `fcm.googleapis.com`, `cloudresourcemanager.googleapis.com` and `iam.googleapis.com` are enabled; the service account is `kvitt-fcm@kvitt-1337.iam.gserviceaccount.com` with role `roles/firebasecloudmessaging.admin` (a role named `roles/firebasemessaging.admin` does not exist); `infra/secrets/fcm-service-account.json` and `infra/secrets/google-services.json` (both clients) exist in the main checkout. `infra/README.md` documents the REST calls for repeating or inspecting the setup. Step 7 is part of the owner's install on the Kvitt Pi (checklist steps 2 and 3, D-125).

The FCM free tier is sufficient; no billing account is required.

### 10.8 Splitwise import

Command (run on the Pi with the server stopped, or on the Mac against a copy of the database):

```
kvitt-import --db /data/kvitt.sqlite --file <csv> --account "<Kvitt account name>" \
  --user "<Splitwise name of the owner>=<owner user id or display name>" \
  --user "<Splitwise name of the partner>=<partner user id or display name>" \
  [--fx <CUR>=<SEK per unit>]... [--dry-run]
```

* One CSV file per Splitwise group (Splitwise's group "Export as spreadsheet"). The account is created with default 50/50 if no non-deleted account with that name exists; otherwise rows go into the existing one, and the existing account's stored name (not the spelling given to `--account`) is the account name used in the import key (D-046).
* `--user` (exactly two, distinct Splitwise names, one per household user) maps a member column to a Kvitt user given as a user id or as a display name that exactly one user has; anything else is a usage error (D-046).
* The importer never creates or migrates a database: `--db` must name an existing file whose `meta.schema_version` is the version the server's migrations produce (`3` since D-090; `2` from D-054), else it exits 1 (run `kvitt-server migrate` first) (D-046, D-054).
* The whole run is one `BEGIN IMMEDIATE` transaction: find or create the account, skip rows whose `import_key` exists, validate and insert the rest with the server's own push checks, write the audit entries, then reconcile (below). It commits only when every row is valid, the reconciliation is accepted and `--dry-run` is absent; otherwise it rolls back and nothing is written. A dry run runs the same transaction and rolls it back (D-046).
* Exit status (D-046): `0` imported (or, with `--dry-run`, would import); `1` database or file error; `2` usage (bad arguments, `--user` not resolving to the two household users); `3` the file cannot be imported (header, invalid rows, non-SEK rows without `--fx`); `4` reconciliation mismatch or missing totals row. Nothing is written unless the status is `0` and `--dry-run` is absent.
* Header (confirmed against both real exports, D-003; the exact header lines are recorded in PLAN-M9, not here): Splitwise localises the export, so two variants exist and the importer must accept both. English: `Date`, `Description`, `Category`, `Cost`, `Currency`; Swedish: `Datum`, `Beskrivning`, `Kategori`, `Kostnad`, `Valuta`. Then one column per group member, named by the member's full Splitwise name, holding that member's net effect for the row (positive = paid more than their share). The member columns appear in different orders in different files, so the importer reads member names from the header and matches them to the `--user` arguments; it never relies on column positions. Any other header fails the import with a clear message, writing nothing.
* Fields containing commas are double-quoted (CSV quoting). The file ends with an empty line followed by a row whose `Description` is `Total balance` (English) or `Totalsumma` (Swedish), the totals row, holding each member's balance; it creates no row and is used only for the reconciliation. Blank rows are ignored.
* Reconciliation (D-045): after the rows are written, inside the transaction, each user's balance of the whole account (`net(u)`, §9.3, over every non-deleted row of the account, not only the imported ones) must equal the sum of that member's values in the file's totals rows. One totals row is allowed per currency; a non-SEK totals row is converted with the `--fx` rate like any other value. A mismatch, or a file without a totals row, rolls the run back and exits `4`; a dry run reports the same. Importing into an account that already holds other rows therefore rolls back, since those rows enter the comparison. When any `--fx` conversion took place, per-value rounding can make an exact match impossible, so a mismatch is reported in the summary but accepted. A re-run of an already imported file skips every row and reconciles again on the same balance.
* `Date` is `YYYY-MM-DD`; `Cost` and member columns are decimal numbers with `.` as separator, converted to öre exactly by string parsing.
* For each expense row with members A and B and cost C (öre): the payer is the member with positive net. If `net_A > 0`: payer A, `share_B = net_A`, `share_A = C − net_A`, mode `exact`. Symmetric for B. If both nets are 0: payer is the owner, mode `full` on the owner (the owner pays and bears the whole cost, D-046). If `net_A + net_B ≠ 0` or a resulting share is negative, the row is reported as invalid and the import aborts (nothing written).
* Rows whose `Category` is `Payment` (English) or `Betalning` (Swedish) become settlements: `from` = the member with positive net, `to` = the other, amount = that net, one allocation to the account, `note` = the Splitwise description truncated to 200 code points (D-046).
* Rows whose `Currency` is not `SEK` abort the import unless a `--fx <CUR>=<rate>` is given for that currency; then every amount is converted with `round_half_up(amount_ore × rate)` per value, and for expenses the exact shares are recomputed as `share_payer = C' − share_nonpayer'`.
* `import_key` = lowercase hex SHA-256 of `splitwise|v1|<account name>|<Date>|<Description>|<Category>|<Cost>|<Currency>|<member nets in header order, joined with |>|<n>` where `<n>` is the 0-based occurrence index of an identical line earlier in the same file. Rows whose key exists are skipped. Idempotency uses the existing `import_key` columns of `expenses` and `settlements` (§14.1); no new column or table (D-046).
* Every created row: `created_by_user_id` = `updated_by_user_id` = the owner; `updated_by_device_id` null; `created_at` = `updated_at` = the import time; one audit entry `create` with `source` = `import`; new `server_version`s from the global sequence; no pushes.
* Description is truncated to 100 code points; the full original goes into `notes` when truncated. An empty description, or one over 1000 code points (the `notes` limit, §9.6), makes the row invalid (exit `3`, nothing written) (D-046).
* Category mapping (case-insensitive exact match on the `Category` column, English and Swedish names, D-003). The importer commits this table as the data file `server/crates/kvitt-import/data/splitwise_categories.csv` (columns `splitwise_name,language,default_key`) and reads it from there; it is the only mapping. Splitwise categories are mapped as finely as the fourteen categories of AC-7.2 allow (D-053); the Swedish names are those observed in the real Swedish export, each placed with its English Splitwise equivalent (D-044, D-053):

| Splitwise category (English) | Splitwise category (Swedish) | Kvitt `default_key` |
|---|---|---|
| Groceries, Food and drink - Other, Liquor | Livsmedel, Mat och dryck - Övrigt, Alkohol | `groceries` |
| Dining out | Restaurangbesök | `restaurants` |
| Rent, Mortgage | Hyra, Avbetalning/Amortering | `housing` |
| Electronics, Furniture, Household supplies, Maintenance, Services, Pets, Home - Other | Elektronik, Möbler, Förbrukningsvaror, Skötsel/underhåll, Tjänster, Husdjur, Hem - Övrigt | `home` |
| Electricity, Heat/gas, Water, Trash, TV/Phone/Internet, Cleaning, Utilities - Other | El, Värme/gas, Vatten, Sophämtning, TV/telefon/internet, Städning, Verktyg - Övrigt | `utilities` |
| Insurance | Försäkringar | `insurance` |
| Bicycle, Bus/train, Car, Gas/fuel, Parking, Taxi, Transportation - Other | Cykel, Buss/tåg, Bil, Bensin/bränsle, Parkering, Taxi, Transport - Övrigt | `transport` |
| Hotel, Plane | Hotell, Flyg | `travel` |
| Games, Movies, Music, Sports, Entertainment - Other | Spel, Filmer, Musik, Sport, Underhållning - Övrigt | `entertainment` |
| Medical expenses | Sjukvård/medicin | `health` |
| Childcare | Barnomsorg | `children` |
| Clothing, Gifts | Kläder, Presenter | `shopping` |
| Taxes | Skatter | `fees` |
| General, Education, Life - Other, Other | Allmänt, Utbildning, Livet - Övrigt | `other` |
| any other value | any other value | `other`, counted as unmapped |

  The Swedish names El, Värme/gas, Vatten, Sophämtning and Husdjur were not seen in the export; they are Splitwise's Swedish labels by analogy (D-053). A wrong guess only leaves such a row unmapped (`other`, counted), which the summary shows.
* The summary lists each unmapped category name with its row count, and the total count of unmapped rows as a warning.

Production run (M11, D-025), in this order:

1. On the Pi in `~/kvitt` (D-125), take a backup first: `docker compose exec backup /backup.sh` (it ends with `backup: ok <stamp>` once both files are confirmed on Drive with `rclone lsf`).
2. Resolve the two production user ids by display name from the database (a read-only `SELECT id, role, display_name FROM users` through the `backup` container's `sqlite3`); the owner is the `admin` user. The ids go into the `--user` arguments (an exact, unique display name is also accepted, D-046).
3. Copy the CSV files from the Mac to the Pi into `~/kvitt/import/` (`/home/jacobhagstedt/kvitt/import/`; `scp <file> jacobhagstedt@<kvitt-pi-address>:kvitt/import/`), which is bind-mounted read-only into `server` as `/import` (§10.2, D-125; was `/opt/kvitt/import/`).
4. `docker compose stop server`; for each file run `docker compose run --rm --entrypoint kvitt-import server --db /data/kvitt.sqlite --file /import/<file> --account "<name>" --user "…" --user "…"`, first with `--dry-run`, then without; each must exit `0` with the reconciliation `match` (D-045); the target accounts must not exist yet or be empty; `docker compose start server`; check `/health`. (`--entrypoint` is needed because the image's entrypoint is `kvitt-server`, §10.3.)
5. Delete the CSV files from `~/kvitt/import/`.

### 10.9 Backups and restore

Backup (`infra/backup/backup.sh`, daily 03:30 Europe/Stockholm, also runnable on the Pi in `~/kvitt` as `docker compose exec backup /backup.sh`, which ends with `backup: ok <stamp>` when the run succeeded; `backup-now.sh` is removed, D-125):

1. `sqlite3 /data/kvitt.sqlite ".backup /backups/staging/kvitt.sqlite"` (online, consistent).
2. `sqlite3 /backups/staging/kvitt.sqlite "PRAGMA integrity_check"` must print `ok`, else abort with a log line.
3. `gzip -9` to `/backups/kvitt-<UTC yyyyMMddTHHmmssZ>.sqlite.gz`; `tar -czf /backups/pictures-<same stamp>.tar.gz -C /data pictures`.
4. For every pending `kvitt-*.sqlite.gz` and `pictures-*.tar.gz` in `/backups` (this run's pair and any leftovers of an earlier failed run): `rclone copy <file> "${RCLONE_REMOTE}" --drive-root-folder-id "${RCLONE_FOLDER_ID}" --immutable` (copy only; never `sync`, never delete, never overwrite), then confirm it by name and size with `rclone lsf` (D-106). rclone uses a temporary copy of the read-only `rclone.conf` (D-105).
   The snapshot is the whole database, so it includes the card tables of migration 0004 (connections with their Enable Banking session ids, purchases, attempts; D-161): the backups on Drive therefore hold the users' card purchases, unencrypted like the rest (accepted risk M-1, §8.1). The Enable Banking private keys are in `secrets/cards/`, not `data/`, and are never backed up; a restore needs them copied again from the Mac (`infra/secrets/cards/`).
5. Only after every file is confirmed are the local copies deleted from the Pi's `backups/` folder (D-002), and only then is `/backups/last-success` written with the stamp (D-106). A failed upload or confirmation keeps the local files and leaves `last-success` unchanged; the next good run uploads the leftovers. Nothing on Drive is ever deleted. When `RCLONE_FOLDER_ID` is empty (the development stack, D-001), step 4 is skipped with a log line, the local files are kept and `last-success` is written.

rclone setup (HUMAN, once, done 2026-10-18): the owner ran `rclone authorize "drive"` and signed in; the token (`infra/secrets/rclone-drive-token.json`) became `infra/secrets/rclone.conf` with a `[gdrive]` remote (`type = drive`, `scope = drive`, `token`), both git-ignored. The owner copies it to `~/kvitt/secrets/rclone.conf` on the Pi, mode 0600 (§10.2, D-125); the folder id stays in `.env` as `RCLONE_FOLDER_ID`, not in the conf. The Drive destination root folder id is `1jDp1dGE5R3H2DBcXCqIPN1iWzQnPkdlV` (OQ-4, answered); it is the value of `RCLONE_FOLDER_ID` in the Pi's `.env`.

Restore (step by step in `infra/RESTORE.md`, run on the Pi in `~/kvitt` as the owner, D-125). The files in `data/` and `backups/` are the owner's (both containers run as the owner's uid), so they are moved on the host with plain `mv`, `cp`, `gunzip` and `tar`; only `rclone` (listing and downloading from Drive, on a temporary copy of `rclone.conf`) and `sqlite3` (`PRAGMA integrity_check`) run in the running `backup` container. Nothing is deleted. Not around 03:30, when the nightly backup runs.

1. `docker compose stop server`.
2. Download the chosen `kvitt-*.sqlite.gz` and `pictures-*.tar.gz` from Drive into `backups/restore/` (rclone in the `backup` container, or the browser and `scp` from the Mac).
3. `gunzip` on the host; `docker compose exec -T backup sqlite3 /backups/restore/<file> "PRAGMA integrity_check"` must print `ok`.
4. Move the current `data/kvitt.sqlite`, `-wal`, `-shm` and `data/pictures` aside into `data/pre-restore-<UTC stamp>/` (never delete), copy the restored file to `data/kvitt.sqlite`, extract the pictures into `data/`.
5. `docker compose run --rm server rotate-epoch`.
6. `docker compose start server`; `docker compose ps server` healthy; `curl -fsS http://localhost:8080/health`.
7. Open the app on both phones; they detect the new epoch and re-push their data (§14.4.8). Check the balances match on both phones.
8. Afterwards, `docker compose exec backup /backup.sh` once puts the restored state on Drive.

### 10.10 Operations

* Where: every command on the Pi in this section is run by the owner in `~/kvitt` (`/home/jacobhagstedt/kvitt`) with plain `docker compose` (D-125, revises D-103's scripts); the owner's operations table is in `infra/README.md` "Pi: what the owner does", Operations. Agents prepare and check the project on the Mac and never connect to the Pi (D-100).
* Status and logs: `docker compose ps`; `docker compose logs --tail 100 <service>`; NPM's own log files are inside NPM on the Home Assistant Pi (§10.5.2).
* Disk: `df -h ~` and `du -sh ~/kvitt/*`. SQLite is a few MB; pictures under 1 MB; APKs about 10 MB each since R8 (§10.6), older ones removed by hand.
* Deploy (upgrade), after `infra/build-images.sh v1.0.N` on the Mac pushed the images (D-211; or the Gitea workflow, the fallback, pushed a `v1.0.N` tag): `docker compose exec backup /backup.sh` first, continuing only after `backup: ok`, on every deploy, because the Pi cannot tell beforehand whether a tag carries a migration (D-103, kept by D-125); then set `KVITT_TAG` in `.env` (`sed -i 's/^KVITT_TAG=.*/KVITT_TAG=v1.0.N/' .env`, noting the previous tag), `docker compose pull && docker compose up -d`, and check `docker compose ps` and `curl -s localhost:8080/health`. Migrations run on start; a failed migration exits non-zero and the container restarts in a loop.
* Rollback: set the previous `KVITT_TAG` in `.env` and `docker compose pull && docker compose up -d` (no `previous-tag` file and no `--skip-backup` since D-125). Migrations are forward-only, so if a migration had partially applied, restore the pre-deploy backup (§10.9, `infra/RESTORE.md`); sqlx runs each migration in a transaction, so this should not happen.
* Bootstrap and invites: `docker compose exec server kvitt-server bootstrap` (first install only: the admin invite code, link and expiry of FR-1); once the admin is paired, the partner's invite `docker compose exec server kvitt-server invite-partner`; an extra device `docker compose exec server kvitt-server pair-device --user <user_id>` (§10.4).
* Memory check: `docker stats --no-stream` after the release milestone; server RSS must be under 100 MB with both phones syncing.
* Image digests (D-117 point 5, revised by D-125): the Pi keeps no digest record. After a pull, `docker image inspect --format '{{.RepoDigests}}' gitea.lan/jacobh2/kvitt-server:<tag>` (and `kvitt-backup`) prints the `sha256:` digest, which the owner compares with the workflow's "Print image digests" step for that run (§10.3); the registry is plain HTTP on the LAN (security review L-9), so a mismatch is investigated before the stack is trusted.
* Client IPs (once, after the NPM proxy host and the router check, D-117, D-120, D-124): with the phone off Wi-Fi, open the app's About screen (S-22; before the app gate of D-126, `https://<KVITT_PUBLIC_HOST>/health` in Chrome does as well), then within a minute on the Kvitt Pi `sudo conntrack -L -p tcp --orig-port-dst 8080` (package `conntrack`, installed once): in every line the first `src=` is `HA_HOST` and the reply half (from the second `src=`) has `dst=<HA_HOST>` with no `172.*` address, so the server sees NPM's address and trusts its `X-Forwarded-For`; a `172.*` address there means every internet client shares one per-IP limit of §8.6 (security review I-5; the commands are in `infra/README.md`'s operations table).
* Health from outside (D-126): the app's About screen (S-22) on the phone with Wi-Fi off shows the server version, or `curl -fsS -H "X-Kvitt-App: $KEY" https://<KVITT_PUBLIC_HOST>/health` from outside the home network; without the header the connection is closed (§8.5).
* Card purchases (D-175, K1 writes the runbook entry in `infra/README.md`): the private key files live in `~/kvitt/secrets/cards/` (mode 0600, the folder 0700), copied from `infra/secrets/cards/` on the Mac; the application ids in `.env`. Status: `docker compose logs server | grep card_fetch` shows the aggregate lines of §8.7. Every 180 days at most (CP-6) each user renews with BankID in the app; nothing on the Pi changes.
* Headers through NPM (after the first setup and after every NPM upgrade): `curl -sS -D - -o /dev/null --resolve <KVITT_PUBLIC_HOST>:443:<HA_HOST> https://<KVITT_PUBLIC_HOST>/health` lists `content-security-policy`, `x-content-type-options`, `x-frame-options`, `referrer-policy` and `strict-transport-security` once each and no `x-served-by` (§10.5.2).

---

## 11. Milestones

Each milestone is one plan (`PLAN-<id>.md`, written by the orchestrator's plans agent from this section) run by one Opus agent in its own worktree, unless the row says otherwise. "Gate" is what must pass before landing. The Android gate is `tools/gradle-serial.sh check`; the server gate is `cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo audit && cargo test` in `server/`; the web gate (D-131, §15.3) is `npm run check` in `web/`; "both gates" means the Android and server gates. HUMAN steps are what only the owner can do.

### 11.1 Dependency graph

```
M0 spec ──┬─► U1 directions ─(owner picks)─► U2 design spec ─► §9.7 colours ─► M6 design ─► M7a..M7f features ──┐
          │                                                                                                     │
          ├─► M1 contracts + vectors ─┬─► M2a server skeleton + domain ─┬─► M3 server core API ───────────┐       │
          │                           │                                 ├─► M4 server sync/audit/push ─┬──┤       │
          │                           │                                 │                              └──┼─► M9 importer
          │                           └─► M2b android skeleton + domain ┴─► M5 android data layer ───────┼───────┤
          │                                                                                               │       ▼
          └─► M2c-dev infra for development (Mac compose, Firebase, local backup) ─────────────────────┴──► M8 app integration
                                                                                                                  │
                                                     M2c-pi infra on the Pi (Pi, TLS, Gitea, router, Drive) ◄─────┤
                                                                              M10 first release ◄── M2c-pi, M8 ◄──┘
                                                                              M11 import real history ◄── M9, M10

Category contract v2 (D-054), after SPEC v0.8:
M12a contracts + :domain suggestCategory (landed aa765bb) ─┬─► M12b server (migration 0002, importer table; landed 6eaccec)
                                                            └─► M12c android (:core:model, :domain, :data, fakes; landed b09f322) ─► M6, M7c
M12d UI contract additions (D-059: frequentCategoryIds, deletable; landed 557af7e) ─► M7a..M7f   (ran in parallel with M6, landed 7730a31)

After the M7 wave (v0.11):
M7a..M7f (landed) ─► M6b core:design fixes (landed b24c8b5) ─┬─► M8 app integration (landed 3d9eea8)
                                                            └─► M7g feature cleanups (landed 3dda414)

After M8 (v0.13):
M8, M7g (landed) ─► M12e contract pass (landed 8c60715 and b7b7483; D-086 to D-095, server schema 3)

After the first phone test (v0.15):
M8 phone test (2026-10-18) ─► M8b UI fixes (landed 328c466, D-097) ─► M2c-pi bundle (D-100), last, after the app is proven ─► M10

After v0.15 (v0.16):
M8b ─► M8c goldens and About (landed 75b549f, a0c25b0, 7c453d8; D-098, D-099) ─► M8d editor rows (landed bacbd18, D-102) ─► M8e (D-107)
R8 release build (landed c30a49e)

After v0.16 (v0.17):
M2c-pi bundle (landed 2476667, D-103 to D-106) ─► owner runs the bundle on the Kvitt Pi ─► M10
M8e S-19 option rows (landed a59abeb, D-107) ─► chips cleanup (landed 1328afe)
M8f instant navigation (landed 956908a, D-108)

After v0.17 (v0.18):
history rewrite and first push (18c527f) ─► infra overhaul (2fac1ec..e70fe0d) ─► server gap pass (landed 8660b7f, D-113)
security review (18c527f)   ─┬─► infra security (landed 7fb86f5, D-117)
AC-coverage audit (956908a) ─┼─► M12f Android follow-ups (landed dc7a296..a0259ab, D-109 to D-112, D-116)
                             └─► server overhaul (landed 8103dae..b985ce9; D-114, D-115) ─► router forward ─► M10

After v0.18 (v0.19):
M12f ─► Android overhaul (landed e4e6e5d..c582363, D-118) ─► push to origin (c582363) ─► owner runs the M2c-pi bundle ─► M10

Web client programme (v0.28, D-129 to D-134):
SPEC v0.28 ─┬─► W0 web foundation (web/**) ──────────┬─► W1 home, accounts ─┐
            │                                         ├─► W2 expenses, search, export
            │                                         ├─► W3 settle up       ├─► image build and deploy (§10.10)
            │                                         ├─► W4 analytics, insights (W-11 waits for W7)
            │                                         └─► W5 settings ───────┘
            └─► W7 server: /app/ serving, /analytics/* (D-135..D-138, v0.29) ─┬─► W4's W-11
                                                                               └─► W6 Android Insights

Card purchases (v0.35, D-158 to D-176; K0 done, v0.36; K1 landed `671c00d`, its report recorded in v0.38, D-181 to D-188; K2 landed `a8f91ee`, its report recorded in v0.39, D-191 to D-200; K3 landed `faeb752`, its report recorded in v0.40, D-201 to D-207):
SPEC v0.35 ─► owner steps (Enable Banking account, ToS, application, key, linked cards) ─► K0 local test app on the Mac
   ─► K0 report ─► SPEC v0.36 (K0's answers, D-177 to D-180) ────────┬─► K1 server (schema 4, adapter, E-36..E-44, poller, NPM text) ──┐ lands first
                                                                     ├─► K2 Android (:feature:cards, Room 2, Kortköp tab) ──────────┼─► lands after K1
                                                                     └─► K3 web (W-21..W-23) ────────────────────────────────────────┘ lands after K2 (card strings)
```

After M1, M2a and M2b land, these run in parallel without touching each other's files (§14.7): M3, M4 (lands after M3, D-015), M5, M2c-dev, M6 (once U2 is approved and the §9.7 colour change from U2's proposal has landed in this spec), M7a to M7f (once M6 lands), M9 (once M4 lands). M2c-pi runs after M8 and before M10 (D-001), as the last step once the app is proven on the phone against the development server (D-100). Group M12 "Category contract v2" (D-049, D-054): M12a first; then M12b and M12c in parallel; M6 and M7c wait for M12c (all three landed: `aa765bb`, `6eaccec`, `b09f322`). M12d (D-059) ran in parallel with M6 (landed `557af7e` and `7730a31`); M7a to M7f ran in parallel and landed on 2026-10-18 (`1ea752c`, `0e1d99d`, `0b140aa`, `7380e50`, `ea7d494`, `c4ab35f`), followed by M6b, the `:core:design` fix pass (`b24c8b5`). M8 and M7g (feature cleanups) ran in parallel (disjoint paths: `android/app/**` and `android/adapter/fcm/**` against `android/feature/**`) and landed on 2026-10-18 (`3dda414`; `cb832a7` and `3d9eea8`). The contract pass M12e (D-086 to D-095) ran after them and landed on 2026-10-18 (`8c60715` contract pass, `b7b7483` launcher icon). The M2c-pi bundle (`2476667`, D-103 to D-106), M8e (`a59abeb`, D-107) and M8f (`956908a`, D-108) landed on 2026-10-18; what remains of M2c-pi is the owner running the bundle, and M10 waits for it.

### 11.2 Milestone table

| Id | Name | Deliverable | Gate | HUMAN | Depends on |
|---|---|---|---|---|---|
| M0 | Spec v0.1 | `SPEC.md`, filled `CLAUDE.md`, repository bootstrap | none (docs only) | Review the spec; answer §12 | none |
| U1 | UX directions | Landed `6da6b1b` (direction 3 "Kalas" muted picked, D-047). §13.4 phase 1 files in `docs/ux/` | Files exist and open; each direction shows the six phase-1 screens of §13.4 (S-4, S-7, S-5, S-9, S-11, S-8) in light and dark; Swedish copy, no placeholder text | Review 2-3 directions, pick one, give comments | M0 |
| U2 | UX design spec | Landed `6da6b1b`, approved by the owner: `docs/ux/design-spec.md` (binding, §13.4), `strings.csv` (558 rows), `screens/`; UX-9 (D-059). §13.4 phase 2 files in `docs/ux/` | Every string key has `en` and `sv`; every screen has every state that `design-spec.md` lists for it (§13.3) | Approve the design spec | U1 and the owner's pick |
| M1 | Contracts and vectors | `contracts/openapi.yaml`, `contracts/schema/server-v1.sql`, `contracts/test-vectors/*.json`, `contracts/examples/**/*.json`, `tools/contracts-check.py` | `python3 tools/contracts-check.py` passes: all JSON parses, every vector file matches §14.5.5, a stdlib-only Python reference of §9.1, §9.3, §9.4 reproduces every expected value, every example validates against the shapes of §14.3 by key set | none | M0 |
| M2a | Server skeleton and `kvitt-domain` | Cargo workspace, three crates, config, DB pool, migration `0001_init.sql` byte-identical to `contracts/schema/server-v1.sql`, error type with every §14.3.2 code, auth extractor (§8.2), all routes of §7 registered with handlers returning 501 `not_implemented`, utoipa document equal to `contracts/openapi.yaml`, `GET /health` and `GET /setup/status` implemented, `kvitt-domain` passing all vectors plus `next_occurrence_date`, `server/Dockerfile`; shell files in M3, M4 and M9 paths (D-004); the seams of §6.3 (D-015) | Server gate (includes the OpenAPI match test, the migration identity test, the vector tests) | none | M1 |
| M2b | Android skeleton and `:domain` | Gradle project in `android/` with every module of §6.2, version catalog, architecture check, `:core:model` types and repository interfaces of §14.2.4, `:domain` passing all vectors (including analytics), `:core:fakes` with the empty scenario (§6.2, D-018) for each repository, the Room 3 entities of §14.2.1 and §14.2.2 and `KvittDatabase` version 1 in `:data` with the exported schema (D-012), screenshot tests with Roborazzi (D-010), module shells for every module with one empty entry composable per feature (D-004), the feature convention of §6.2 in `build-logic` (D-017), `:app` launching to an empty themed screen, `:app` string files with the app name only in both languages, lint `MissingTranslation` as an error in every module | Android gate | Plug the phone in once to confirm `installDebug` works | M1 |
| M2c-dev | Infra for development (D-001, D-022) | Landed `c885aba`. `infra/dev/compose.yaml` (`server` built from `server/Dockerfile`, no Caddy, no TLS, bind-mounted data, `infra/secrets/` mounted read-only at `/secrets`, `backup` runnable on demand), `infra/dev/.env.example`, the dev scripts in `infra/dev/` (build, up, logs, backup, `copy-google-services.sh`), `infra/README.md` (dev stack and Firebase), `infra/backup/{Dockerfile, backup.sh}` (Drive upload skipped when `RCLONE_FOLDER_ID` is empty), Firebase project and apps through the REST API (§10.7), service-account key and `google-services.json` in `infra/secrets/` | `docker compose -f infra/dev/compose.yaml --env-file infra/dev/.env.example config` succeeds; `shellcheck $(find infra -name '*.sh')` clean; on the Mac (with the M2a image): `GET /health` answers 200 from the Mac; one local backup run produces a snapshot that passes `PRAGMA integrity_check` | `gcloud auth login`; on the phone on the home Wi-Fi, open the dev server's `/health` and answer yes/no that it shows `"status":"ok"` | M0 (uses the M2a image for the health check when available) |
| M2c-pi | Infra on the Pi (D-001, D-100, D-120, D-125) | Bundle landed `2476667` 2026-10-18 (D-103 to D-106); the NPM rework (D-120: `4f69ae0` workflow login, `d05f13a` stack without Caddy and cert-sync, `62f5279` and `9231a1d` README) landed `9231a1d` 2026-10-19; port 443 (D-124: `4852803` bundle) landed 2026-10-19; the sparse-checkout workflow (`3820f9c`, 2026-10-19), the `.env` without the informational keys (`200c99f`, 2026-10-20) and the self-contained compose project (D-125, `6e5981d`, 2026-10-20) landed. The NPM proxy host for `kvitt.suorra.duckdns.org` is Online with its Let's Encrypt certificate (owner, 2026-10-19); the Gitea workflow built and pushed `v1.0.0` (run 69) and `v1.0.1` (§10.3); the owner is installing on the Kvitt Pi (2026-10-20). Deliverable: a self-contained compose project in `infra/pi/` (`compose.yaml`, `.env.example`, `.gitignore`) that the owner copies to `/home/jacobhagstedt/kvitt` on the Kvitt Pi and runs with plain `docker compose` commands (D-100, D-125): `server` and `backup` as the owner's uid, the seven `.env` keys, relative bind mounts `./data`, `./backups`, `./import` (§10.2); a README checklist for the owner (`infra/README.md` "Pi: what the owner does": prerequisites, `.env` and secrets on the Mac and the copy, start, the NPM proxy host and its Custom Nginx Configuration of §10.5, the router check (external 443 → Home Assistant Pi 443, no new rule, D-124), from outside, first backup and bootstrap, deploy), `infra/RESTORE.md`, Drive backups to folder id `1jDp1dGE5R3H2DBcXCqIPN1iWzQnPkdlV`, Gitea Actions image build from the owner's example workflow in `.gitea/workflows/` | On the Mac: `docker compose -f infra/pi/compose.yaml config` succeeds with the env template (D-103); `shellcheck $(find infra -name '*.sh')` clean. Green at D-125 (2026-10-20): compose config valid; a Podman rehearsal of the project folder as uid 501 (not 10001): both containers healthy with read-only roots, `/health` 200 with `db_ok: true`, the database files and `data/apk` owned by 501 on the host, `kvitt-server bootstrap` through `exec`, an APK and `latest.json` copied into `data/apk/` served at once, `/backup.sh` in three modes (no folder id: files kept, `last-success` written; a local remote: uploaded, confirmed, local copies deleted; a failing remote: files kept, `last-success` unchanged), the `RESTORE.md` steps ending with `/health` 200. Still valid from the NPM rework: `nginx -t` of the §10.5.2 block against NPM v2.16.0's templates and the 21 checks of the server behind nginx (§10.5.2). Not verifiable from the Mac: NPM's UI and Let's Encrypt for the Kvitt host name, the router forward, pulls from `gitea.lan`, Docker Compose itself (`create_host_path: false`, which Podman ignores), Drive. On the Pi, run by the owner from the checklist: `docker compose ps` shows both services healthy and `curl localhost:8080/health` answers ok; `https://<KVITT_PUBLIC_HOST>/health` answers from the phone on mobile data without a certificate warning; one backup pair appears in the Drive folder | Fill `infra/pi/.env` on the Mac (`HA_HOST`; check `KVITT_UID`/`KVITT_GID` and `KVITT_TAG`), copy `compose.yaml`, `.env` and `secrets/` to `~/kvitt` on the Kvitt Pi and run the seven steps of `infra/README.md` "Pi: what the owner does" (prerequisites, Mac, start, NPM, router check, from outside with first backup and bootstrap, deploy), answering yes/no per check. Done: the Drive token (`rclone.conf`), the example workflow, the Gitea secret `kvitt_cicd` (renamed by the owner 2026-10-19; run 69 succeeded), the Kvitt host name `kvitt.suorra.duckdns.org` and its NPM proxy host (2026-10-19), Docker and the registry trust on the Pi (prerequisites). No allowances for agents on the Pis, Home Assistant, NPM, Gitea or Drive (D-100) | M2c-dev, M8; runs last, after the app is proven (D-100) |
| M3 | Server core API | Landed `7869ec4` (D-030 to D-034). E-3 to E-30 and E-33 implemented (§14.3; E-2 is M2a's, M3 tests it), invite landing page, pictures, rate limiting (`src/api/rate_limit.rs`), `bootstrap`, `pair-device`, the recurring generation function of §6.3 (D-015) | Server gate; integration tests per endpoint and per error code listed for it; every generation case of §9.5 (catch-up, clamping, split resolution, idempotency, resume without backfill, `next_occurrence_date`) | none | M2a |
| M4 | Server sync, audit, push, scheduler | Landed `15056dc` (D-035 to D-039). E-31, E-32, the real `AuditWriter` (writer and diff) and `PushQueue` (FCM sender), `src/tasks/**` starting them, `sync_mutations` pruning daily at 04:00 (D-021), scheduler, `rotate-epoch` | Server gate; integration tests for every sync rule of §14.4 and the scheduler cases of §9.5 (run at start, daily 06:00 on DST days, catch-up through M3's generation function); FCM sender tested against a local stub HTTP server | none | M2a; lands after M3 (D-015) |
| M5 | Android data layer | Landed `8f0e156` (D-026 to D-029, D-040 to D-043). DAOs on M2b's Room 3 entities and `KvittDatabase` v1 (§14.2, D-012; any change to the entities or the exported schema is a contract change, §14.8), Ktor client and DTOs, token store, sync engine and workers, real repositories, APK updater | Android gate; DTO round-trip tests over every file in `contracts/examples/`; sync engine tests with Ktor `MockEngine` covering §14.4 including the 14-day offline case (AC-15.6) | none | M1, M2b |
| M12a | Category contract v2: contracts | Landed `aa765bb`. `contracts/category-keywords.csv` (148 entries), `contracts/schema/migrations/0002_categories_v2.sql` (§14.1.1), `contracts/test-vectors/suggest_category.json` (65 cases), E-1 example `schema_version` 2, `tools/contracts-check.py` (keyword-table rules, 0002 loaded on a fresh and an in-use v1 database, Python reference of §9.11, new icon and colour tokens), and `:domain`'s `suggestCategory` with `UnicodeText` passing the vectors (§14.5.6). The OpenAPI `DefaultCategoryKey` extension and the new category examples were held back for M12b | `python3 tools/contracts-check.py` passes | none | M1, SPEC v0.8 |
| M12b | Category contract v2: server | Landed `6eaccec` (D-057, D-058). Migration `server/crates/kvitt-server/migrations/0002_categories_v2.sql` byte-identical to the contract file with its identity test; `SCHEMA_VERSION` 2; seed test of the fourteen defaults (ids, keys, icons, colours, sort orders, `server_version` from the sequence) on a fresh database and on a v1 database holding expenses (rows and references kept); icon and colour lists of §9.7 in `validate.rs`; `DefaultCategoryKey` with the fourteen keys in `contracts/openapi.yaml` (held back by M12a) and in the utoipa wire types, so the OpenAPI match test passes; the category examples M12a held back; importer table `splitwise_categories.csv` per §10.8 with its spec-parity test; importer schema check 2 (D-054); E-31 and other examples only where they enumerate the defaults | Server gate; `python3 tools/contracts-check.py` passes | none | M12a, M3, M4, M9 |
| M12c | Category contract v2: Android | Landed `b09f322` (D-055 to D-057). `:core:model`: `DefaultCategoryKey` (14), `ColorToken` (`SLATE`, `AMBER`), `CategoryIcons.ALL` (33), `ExpenseRepository.suggestCategory`; `:data`: the `UnicodeText` binding (`java.text.Normalizer`, `Character`), `suggestCategory` from Room, DataStore and the keyword table copied from `contracts/category-keywords.csv` at build time (D-055; a test asserts byte identity and the §14.8 rules), parsed by `:domain`'s `parseCategoryKeywords` (D-056); `:core:fakes`: fourteen defaults in the empty scenario and a fake `suggestCategory`; default-name string resources for the four new categories in English and Swedish (AC-7.2) where default names already live | Android gate | none | M12a, M2b, M5 |
| M12d | UI contract additions (D-059) | Landed `557af7e` (D-060 to D-062). `:core:model`: `ExpenseEditorOptions.frequentCategoryIds` and `CategoryRepository.deletable(id)` (§14.2.4 "Changes in v0.9"); `:data`: both computed from Room, with repository tests; `:core:fakes`: both computed from each scenario's own data; `ContractTest` updated | Android gate | none | M12c, M5 |
| M6 | Design system | Landed `7730a31` (D-063 to D-066). Built from `docs/ux/design-spec.md` §2 and §3 and `docs/ux/strings.csv`. `:core:design` theme, tokens, typography (Material 3 default typeface, D-020), shared components including the ledger rows and expense editor fields (D-019), charts (Compose `Canvas`, D-063), formatters (§9.8), shared strings (including the notification copy) per `docs/ux/design-spec.md` and `docs/ux/strings.csv`, screenshot tests of every component in light and dark, Swedish and English | Android gate | Look at the component screenshots the agent opens and posts (yes/no) | U2, M2b, M12c, the §9.7 colour change |
| M6b | Design-system fixes after M7 | Landed `b24c8b5` (D-075 to D-079). `:core:design` fixes the M7 agents asked for: `viewerPercentOf` reads basis points, `editor_split_full_on_you`, `AmountInput.of` with both decimals and `AmountInput.percent` (D-078), `quickRowCategories` (D-075), two-line category labels with an ellipsis (D-076), `DateFormatter.monthName` and `dayRangeLong` (D-077), resource-backed snackbars in `KvittScaffold`, optional `ConfirmDialog` body, `KvittButton` loading form, `InviteCodeField` wrapping, `EmptyState` icon tile, `AnalyticsFilterBar` period row, screen tokens in `KvittDimens`, `common_ok` and `common_undo`, the module keys of M7b to M7f recorded in `docs/ux/strings.csv` (D-079) | Android gate | none | M7a to M7f |
| M7a | Feature: onboarding | Landed `1ea752c` 2026-10-18 (D-071). `:feature:onboarding` screens S-1, S-2, S-3, S-18 | Android gate with screenshot tests of every state, sv and en, light and dark | none | M6, M12d |
| M7b | Feature: home and account | Landed `0e1d99d` 2026-10-18 (D-071). `:feature:home`, `:feature:account` screens S-4, S-5, S-6, S-16, S-17 | as M7a | none | M6, M12d |
| M7c | Feature: expense | Landed `0b140aa` 2026-10-18 (D-074, D-080). `:feature:expense` screens S-7, S-8, with the category suggestion of §9.11 (CS-2, CS-3, CS-7) | as M7a | none | M6, M12c, M12d |
| M7d | Feature: settle | Landed `7380e50` 2026-10-18 (D-074). `:feature:settle` screens S-9, S-10 | as M7a | none | M6, M12d |
| M7e | Feature: analytics | Landed `ea7d494` 2026-10-18 (D-069 to D-071). `:feature:analytics` screens S-11, S-12 | as M7a | none | M6, M12d |
| M7f | Feature: settings | Landed `c4ab35f` 2026-10-18 (D-071 to D-073). `:feature:settings` screens S-13, S-14, S-15, S-19, S-20, S-21, S-22 | as M7a | none | M6, M12d |
| M7g | Feature cleanups | Landed `3dda414` 2026-10-18. Cleanups in `android/feature/**` after M6b; scope in its brief | as M7a | none | M7a to M7f, M6b |
| M8 | App integration | Landed `cb832a7` and `3d9eea8` 2026-10-18 (D-081 to D-085). `:app` navigation and deep links (§13.2, D-071; each top-level screen draws its own bar), session gate (S-1 for Unpaired and Unrecognised, S-2, S-18 for Revoked, back on S-18 closes the app; Home shows S-3 while `partner == null`), deletion of the debug fakes module (both variants bind `:data`, D-081), `:adapter:fcm` with registration by Firebase Installation ID (D-083), push work and notification building (AC-13.5, D-085), invite links ignored while paired (D-084), `ProvideHousehold` as `LocalKvittHousehold`, `LocalKvittClock` from `:data`'s Clock, `LocalAvatarPictures` handing the `User` to `:data`'s Coil mapper, notification permission after the first successful sync after pairing (AC-2.9), update check in release only, revoke wipe, network security configs (§8.5, D-082), manifest hardening (§8.8), release signing and version properties (§10.6; unsigned without keystore keys), `google-services.json` copied with `infra/dev/copy-google-services.sh` | Android gate (green at landing: BUILD SUCCESSFUL, 710 actionable tasks); on the owner's phone against the development server on the Mac (D-001): pair, add an expense offline, reconnect, see it synced, receive a push (run on 2026-10-18 on the owner's S26 against the development server: pairing with the bootstrap code OK; a scripted partner joined through a second admin device paired with `kvitt-server pair-device`; Home showed the account; the offline expense showed the pending marker and synced after reconnect, pending 0, row on the server; the device registered `fcm_token` and `app_version_name`; a push by `fid` arrived and its tap worked). Follow-up M8b (landed `328c466`, D-097) fixed what the test showed: the invite-code field, the quick-row badge, the status-bar inset of `KvittTopAppBar`, the chart corners; `FcmMessageBody.fid` in `:data` followed (`6eb3f85`, D-096) | Tap through the pairing, offline and push test as relayed by the orchestrator | M3, M4, M5, M7a-M7f, M2c-dev (Firebase, development server) |
| M12e | Contract pass | Landed `8c60715` and `b7b7483` 2026-10-18 (D-086 to D-095). The §11.3 contract requests of M5 to M8 taken together on both sides: E-3 `invite_kind` and `Pairing` (D-086); the admin's name in E-12 links, passed on by E-4 (D-087); `SyncSummary.lastAttemptFailed` (D-088); `Rejection.actor` (D-089); `X-Kvitt-App-Version-Name`, `devices.app_version_name` by migration 0003, server schema 3 (D-090); `NewRecurringTemplate` (D-091); `UpdateCheck` (D-092); `SettleState.untouched` (D-093); the D-027 re-stamp in `:data` (D-094); `PushEvent` in `:core:model`, snackbar hosts in six screens, snackbar resource ids from S-7 and S-8, the adaptive launcher icon (D-095). Goldens re-recorded: S-20 devices (version name); new `s1_pairing_link_admin` and `s22_about_check_failed` | Both gates (green at landing: Android BUILD SUCCESSFUL, 710 actionable tasks, 906 tests; server 253 tests, the OpenAPI equality, vector and migration byte-identity tests included) | none (the development server must be rebuilt before the new APK is installed, §14.8) | M8, M7g, SPEC v0.12 |
| M12f | Audit and security follow-ups (Android) | Landed `dc7a296`, `5b2ed37`, `2bd6b58`, `c366fbd`, `a0259ab` 2026-10-18 (D-109 to D-112, D-116; no prompt file, orchestrator brief). S-16 read-only lost version (`Rejection.lost`, D-109); S-22 versions from `/health` (`AboutState.schemaVersion`, D-110); `SettlementRepository` without throws (D-111); E-17 retry (D-112); invite links dropped while paired (AC-2.6); private notifications (AC-13.9, D-116); `localeFilters` en, sv (AC-19.1); `:data` tests for the 429 retry, D-040 refusals and WorkManager unique work (`work-testing`, §6.2); the `:feature:home` and `:feature:account` screenshot harness fix (§6.2); the 19 string keys R8 found unused removed (`strings.csv` 562 rows, §13.4) | Android gate (green at landing, 941 tests); release APK 10.0 MB | Look at S-16 and S-22 on the next install (HANDOFF §3) | M8f, the AC-coverage audit and the security review (§11.4) |
| M9 | Splitwise importer | Landed `50339ae` (D-044 to D-046). `kvitt-import` per §10.8 with tests over synthetic CSV fixtures (`crates/kvitt-import/tests/import.rs`), reconciliation against the totals rows, the committed category table | Server gate | Provide the CSV files (kept outside git) when OQ-2 is answered | M2a, M4 |
| M10 | First release | Release build signed, published, both phones paired, push working both ways, nightly backup on Drive, restore drill report, memory check | `docs/validation/first-release.md` and `docs/validation/restore-drill.md` complete; server RSS under 100 MB | Create the release keystore with the `keytool` command of §10.6 at the repository root, or allow an agent to (D-101), and keep a copy and the password in the password manager; run the Pi steps of the M2c-pi compose project (D-100, D-125); install the APK on both phones from the landing page; allow "Install unknown apps"; partner pairs with the invite; confirm notifications arrive | M2c-pi (the owner's run of the bundle), M3, M4, M8 |
| M11 | Import history | Rehearsed on 2026-10-18: the real run reconciled on both files in a throwaway database (Vardag 1746 rows, Hemma 37 rows; 21 rows unmapped before D-044). Dry run of 2026-10-18 with the M12b mapping (D-053): Vardag 1746 rows, 0 unmapped; Hemma 37 rows, 0 unmapped; both reconciled. Real import run on the Pi per §10.8 "Production run" (D-025), `docs/validation/splitwise-import.md` with per-account totals compared to Splitwise's balances (aggregates only) | Imported balances equal Splitwise's "Total balance" rows per group | Provide the CSVs; confirm the balances on the phone match Splitwise | M9, M10 |
| W0 | Web foundation (D-131, D-134) | Landed `2ae65a5` (2026-10-21). `web/`: Vite, React 19, TypeScript strict, React Router 7, TanStack Query 5, `openapi-typescript` types in `web/src/api/schema.d.ts` and `openapi-fetch`, Vitest and Testing Library, ESLint and Prettier; design tokens from `docs/ux/design-spec.md` §2 as CSS custom properties; layout shell (sidebar, bottom bar under 720 px), router with every route of §15.3, keyboard shortcuts and W-20; login (W-1), token store and 401 handling; API client and household snapshot (§15.5); i18n (sv, en); formatting (§9.8); shared components; the money functions of §14.5.2 passing their vectors; `npm run check` | Web gate | none | SPEC v0.28 |
| W1 | Web: home and accounts | Landed `934eee7` (2026-10-21, D-144, D-145, SPEC v0.32). W-2, W-3, W-4 in `web/src/features/{home,accounts}/` | Web gate | Look at Home and an account in a browser against the development stack (yes/no); done on the Pi 2026-10-24 (D-211) | W0 |
| W2 | Web: expenses, search and export | Landed `a65ab71` (2026-10-21, D-146 to D-148, SPEC v0.32; the shared editor fields in `web/src/components/editor/`). W-5 with the §9.11 suggestion (`suggest_category.json`, in the vector test since `83f5293`), W-6 with the timeline, W-12 with the CSV export, in `web/src/features/{expenses,search,export}/` | Web gate | Add, edit and delete an expense in a browser; open an exported CSV in Numbers (yes/no); done 2026-10-24 (D-211) | W0 |
| W3 | Web: settle up | Landed `f9a9bfb` (2026-10-21, D-144, D-149, SPEC v0.32). W-7, W-8 in `web/src/features/settle/` | Web gate | Record and delete a settlement in a browser (yes/no); done 2026-10-24 (D-211) | W0 |
| W4 | Web: analytics and insights | Landed `1aecf51` (2026-10-21, D-151, D-152, SPEC v0.32). W-9, W-10 with the D-128 line chart, W-11 on the D-133 endpoints (E-34, E-35); `resolveRange` and `spendSeries` passing their vectors (`features/analytics/domain/analytics.vectors.test.ts`); in `web/src/features/analytics/` | Web gate | Look at the analytics pages in a browser (yes/no); done 2026-10-24, Insights included (D-211) | W0; W-11 needs W7 |
| W5 | Web: settings | Landed `3ebe57d` (2026-10-21, D-153, D-154, SPEC v0.32). W-13 to W-19 in `web/src/features/settings/` | Web gate | Pair a browser, see it on the phone's Devices, revoke it from the phone (yes/no); done 2026-10-24 (D-211) | W0 |
| W6 | Android: Insights | Landed `1c9856b` (2026-10-21, D-141 to D-143, SPEC v0.31; Android gate green, 40 `s11_insights_*` goldens). An Insights section on S-11 from the D-133 endpoints, online only (§9.9): a UI-contract change (§14.8) in `:core:model`, `:data`, `:core:fakes` and `:feature:analytics`, with goldens | Android gate | Look at S-11's Insights on the phone (yes/no); done 2026-10-24 against `v1.0.3` (D-211) | W7 landed, its image deployed |
| K0 | Card purchases spike: local test app (D-176) | The test app landed `2ce317f`: `docs/spikes/k0/app.py` and its `README.md`, one command (`python3 docs/spikes/k0/app.py`, the standard library only, the RS256 JWT signed with `openssl`), a page on `http://localhost:8765/` that runs the real Enable Banking flow (bank list, BankID, paste-back of the redirect address, accounts, "Uppdatera" with PSU headers, "Bakgrundshämtning" without, balances, the purchases, an aggregate "Analys", "Koppla från"), key and state in the git-ignored `docs/spikes/k0/.local/`. Done 2026-10-24: run with the owner on his card; report `docs/spikes/K0-enable-banking.md` (aggregates only), its answers recorded in SPEC v0.36 (D-177 to D-180); the partner's card and the next-day checks were not run (owner's decision, D-177) and move to K1's owner steps | The flow worked end to end with the owner's card (owner's yes); the report answers every K0 item; `git status` shows nothing from `.local/`; no gate (not part of any gate) | Done 2026-10-24: Enable Banking account and Terms of Service, the restricted production application, the key in `.local/`, the owner's card linked with BankID, the test app run (PLAN-K0 §8) | SPEC v0.35 |
| K1 | Card purchases: server (D-158 to D-175) | Landed `671c00d` (2026-10-24; D-181 to D-188, SPEC v0.38). Migration 0004 with its contract text and migration test, server schema 4; `src/cards/` (registry, Enable Banking adapter, the windowed fetch and de-duplication of §9.12 CP-7 and CP-8, poller, callback page); E-36 to E-44 in the server and `contracts/openapi.yaml` with examples; new error codes; the link clearing in §14.4.4 step 7; `contracts/test-vectors/match_card_purchase.json` and its Python reference in `tools/contracts-check.py`; config (§10.4), `infra/pi/compose.yaml`, `.env.example`, `infra/dev/**`, `infra/npm/kvitt.conf`, `infra/README.md` (step 4 block, card runbook); `web/src/api/schema.d.ts` regenerated | Server gate; `python3 tools/contracts-check.py`; the web gate (the regenerated types); an integration test suite against a local Enable Banking stub. At landing: server 356 tests (34 in `tests/cards_api/`), contracts-check 157 (17 `match_card_purchase` cases), web 609 (`match_card_purchase` listed as not ported until K3), the nginx check and both compose configs ok; the Android gate red by design until K2 lands (`VectorFilesTest`, `ExampleRoundTripTest` pin the contract's vector and example sets), so the commit bypassed the pre-commit hook (contract-first landing) | Copy the key (already on the Mac from K0) to `~/kvitt/secrets/cards/`, set the application id in `.env`, paste the new NPM block, deploy; once a client with the card screens runs: the partner's card, the next-day fetch without BankID and pending→booked (D-177) (PLAN-K1 §8) | SPEC v0.36 (K0's answers) |
| K2 | Card purchases: Android (D-169, D-170, D-172, D-173) | Landed `a8f91ee` (2026-10-24; D-191 to D-200, SPEC v0.39). `:feature:cards` (S-23 to S-27 and the sheet), Room version 2 with its migration test, the `CardRepository` UI contract in `:core:model`, `matchCardPurchase` in `:domain` passing its vectors, `:data` (DTOs, card sync, queued link changes, Custom Tab, deep link), fakes and scenarios, the fourth bottom destination, S-5's "Från kortköp", S-7's prefill and link, S-8's card line, the committed card artwork mapped (D-180), goldens; strings in `docs/ux/strings.csv` (77 rows); out-of-path edits ratified by the orchestrator: `ArchitectureRules.kt` knows `cards`, `:core:design` gains `ic_credit_card` / `KvittIcon.CreditCard`, the card measures in `KvittDimens` (D-200), the nav-label shrink-to-fit (D-197), `StringsCatalogueTest` takes `cards_` as a feature prefix | Android gate. At landing: `BUILD SUCCESSFUL`, 791 actionable tasks, 1154 tests, 0 failures; the 11 card examples (E-36 to E-44) round-trip, the 17 `match_card_purchase` cases pass, `VectorFilesTest` and `ExampleRoundTripTest` green again on `main`; 150 goldens added (`:feature:cards` 135 for every state of S-23 to S-27 with `_sv_light_200` for the long ones; `S-5-account-menu-card`, `s7_from_card`, `s7_from_card_foreign`, `s8_from_card`, `s13_hub_card_connected`) and 147 re-recorded for the fourth bar destination (S-3, S-4, S-11, S-13, S-17 and the navigation-bar component; only the bar changed) | Connect the card on the phone with BankID; create an expense from a purchase; link one; disconnect and reconnect (PLAN-K2 §8 steps 1 to 7, pending: the phone was not attached; the release APK with the card screens is installed by the orchestrator once K1's image runs on the Pi) | SPEC v0.36; may start then on the spec and fakes; lands after K1 |
| K3 | Card purchases: web (D-174) | Landed `faeb752` (2026-10-24; D-201 to D-207, SPEC v0.40). W-21 to W-23 in `web/src/features/cards/` (every §13.3 state but offline, the S-23 sheet actions, `?attempt=` polling, `?account=` as S-27), the Kortköp entry after Översikt in the sidebar and bottom bar, W-5's `?cardPurchase=` prefill (CP-9) and link on save, W-6's card line with "Ta bort koppling", W-3's "Från kortköp", W-13's "Anslut kort" row, the committed card artwork mapped (D-180), the card snapshot in `web/src/api/cards.ts`, `matchCardPurchase` in TypeScript passing its 17 vectors | Web gate. At landing: web 70 files, 684 tests, build ok; contracts-check 157 | Pending after image `v1.0.5` is deployed: connect the card from the laptop browser with BankID QR; create and link from W-21 (PLAN-K3 §8, three steps) | SPEC v0.36; lands after K1 and K2 (it takes the card strings K2 adds to `docs/ux/strings.csv`) |
| W7 | Server: web serving and analytics endpoints (D-132, D-133) | Landed `50a0d67` (2026-10-21, D-135 to D-138, SPEC v0.29; 299 server tests, contracts-check 136). `/app/` from `KVITT_WEB_DIR` with the SPA fallback, cache headers and the `/app/` CSP; the `/analytics/*` endpoints (D-135 to D-138, SPEC v0.29) in `contracts/openapi.yaml` and the server; the Node stage in `server/Dockerfile` with the repository root as build context (workflow, `infra/build-images.sh`, `infra/dev/**`) | Server gate; `python3 tools/contracts-check.py`; the web gate when `web/` exists and the contract changed (`web/src/api/schema.d.ts` regenerated) | Paste the v0.28 NPM block (`infra/README.md` step 4); deploy the new image (§10.10); deployed 2026-10-24 as `v1.0.3` (D-211) | SPEC v0.28 |

### 11.3 Notes per milestone

* **M1** writes the OpenAPI file by hand from §14.3 (no code exists yet). M2a then annotates handlers so the generated document matches it; the equality test compares parsed values, not text (D-016), after the normalisations of §14.8 (D-005). M2a may change `contracts/openapi.yaml` only representationally (key order, `$ref` naming, description wording), listed in the plan report, with no spec bump (§14.8). Any semantic change follows the contract-change rule (§14.8). `tools/contracts-check.py` checks the file's header: OpenAPI 3.1.0, title `Kvitt`, version `1` and one server `https://{host}` whose variable `host` has the default `kvitt.example.invalid` (v0.23, D-124; `https://{host}:8443` in v0.22, D-123; before that the literal `https://icehack.asuscomm.com:8443`).
* **M2a** owns the router and registers every route up front so that M3 and M4 only fill in handler bodies in their own files. The same for the utoipa `ApiDoc`. M2a creates the shell files of the later server milestones (D-004, §14.7) and the seams of §6.3 (D-015). `server/rust-toolchain.toml` pins the exact current stable Rust release and the Dockerfile uses the same version (§10.3).
* **M2b** writes the `*State` classes and repository interfaces of §14.2.4 so that M5 and M7 work against the same interfaces in parallel. It creates a module shell for every module of §6.2, with one empty entry composable per feature module (D-004), puts the feature convention of §6.2 (D-017) into the feature convention plugin, and fixes how `resolveRange` signals an invalid `CUSTOM` range (§14.5.4, D-018: `IncompleteCustomRangeException`, D-011). Its screenshot-test choice is D-010 (Roborazzi). It also created the Room 3 entities and `KvittDatabase` v1 in `:data` (D-012), so M5 builds on them.
* **M5** owns `:data` and builds on the entities, `KvittDatabase` v1 and the exported schema `android/data/schemas/se.hagstedt.kvitt.data.db.KvittDatabase/1.json` that M2b created (D-012); it adds DAOs, the API client, sync and the repositories. Room 3 migrations take an `SQLiteConnection` (§14.2.3).
* **M7x** features use `:core:fakes` only; they never depend on `:data`. Each feature agent adds its fake scenarios in `android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/<feature>/` and nowhere else in that module. Each fills in its own module shell from M2b, follows the feature convention of §6.2 and takes shared UI from `:core:design` (D-019). All six landed on 2026-10-18 (`1ea752c` M7a, `ea7d494` M7e, `7380e50` M7d, `0e1d99d` M7b, `0b140aa` M7c, `c4ab35f` M7f); their readings are D-069 to D-074 and D-080, the shared fixes they asked for went into M6b (`b24c8b5`, D-075 to D-079). M7g (landed `3dda414`) did the feature-side cleanups after M6b.
* **M6b** (landed `b24c8b5`) is the `:core:design` fix pass after the M7 wave, in M6's paths (§14.7); see the §11.2 row.
* **M12e** (landed `8c60715` and `b7b7483` on 2026-10-18, D-086 to D-095) took the contract requests that M5, M6, M7 and M8 had collected here, as one contract change on both sides (§14.8): the invite kind from `pair()` (D-086), the admin's name in invite links (D-087), `SyncSummary.lastAttemptFailed` (D-088), `Rejection.actor` (D-089), the device version name with server schema 3 (D-090), `NewRecurringTemplate` without an id (D-091), `UpdateCheck` (D-092), `SettleState.untouched` (D-093), the D-027 re-stamp in `:data` (D-094), and `PushEvent` in `:core:model`, the six screen-hosted snackbar hosts, snackbar resource ids from S-7 and S-8 and the launcher icon (D-095). The 128 px picture size was left unchanged by assumption: `:data` keeps fetching E-11 at 512 and no size parameter was added, since v1 does not need one (the owner confirmed on 2026-10-18 that it is not needed: single 512 size, §14.2.4). Room stays at schema 1 (the phone stores no devices). A phone running the M12e APK needs a server at schema 3 (§14.8 "Compatibility").
* **Remaining contract requests** (none is a contract change in v0.14; it needs the §14.8 rule when taken):
  * None open. S-22's "Licenser för öppen källkod" did nothing (no licences screen and no strings for one); the owner answered OQ-5 on 2026-10-18: no licences screen in v1, the row is removed (implemented by M8c, `a0c25b0`, D-099).

  The `fid` request was taken on 2026-10-18 (`f56dcbe`, D-096): the server sends the installation id in FCM HTTP v1 `message.fid` (§14.6).
* **M2c-dev / M2c-pi** (D-001, D-100): M2c-dev builds only what development needs on the Mac (landed); M2c-pi builds everything that concerns the Pi (registry trust, TLS through the owner's Nginx Proxy Manager since D-120, router, Pi deploy, APK publishing to the Pi, Drive upload, Gitea Actions) as the `infra/pi/` bundle the owner runs, and runs last, after M8 and the phone test, before M10.
* **M4** (landed `15056dc`) added `into_make_service_with_connect_info::<SocketAddr>()` to `serve` so the per-IP rate limits of §8.6 see the peer address (D-032). Its tests are three binaries, `tests/sync_api/`, `tests/push_fcm/` and `tests/scheduler_daily/` (§14.7); the scheduler lives in `src/tasks/scheduler.rs`.
* **M8** (landed `cb832a7` and `3d9eea8`, D-081 to D-085) is the only plan that edits `:app` after M2b. As built: both variants bind `:data` through `di/AppDataModule.kt`, which includes `DataBindingsModule`; the debug fakes module is deleted (D-081, revising D-041). The session gate shows S-1 for Unpaired and Unrecognised, S-2, and S-18 for Revoked (back on S-18 closes the app); Home shows S-3 while `partner == null`; each top-level screen draws its own bar (D-071). M6's `:app` requests are met: `ProvideHousehold` is implemented as `LocalKvittHousehold`, `LocalKvittClock` is provided from `:data`'s Clock, and `LocalAvatarPictures` passes the `User` model to `:data`'s Coil mapper. M5's requests are met: `AppBuildInfo` from `BuildConfig`; WorkManager with `KvittWorkerFactory` and the default initializer disabled; `SyncTriggers.onAppStart` on process start and `onForeground` on later returns; push handled by an expedited WorkManager job calling `syncForPush` (D-085); `UpdateRepository.check` on every start and resume, in release builds only (AC-16.5); Coil's singleton is `:data`'s `ImageLoader`. The notification permission is asked after the first successful sync after pairing (AC-2.9). Network security configs per §8.5 (D-082); the merged release manifest exports only `MainActivity` and permission-guarded library receivers (§8.8); `:app:assembleRelease` builds unsigned when `local.properties` has no keystore keys (§10.6); FCM registration by Firebase Installation ID (D-083); invite links ignored while paired (D-084). The end-to-end test ran on 2026-10-18 on the owner's S26 against the development server: pairing with the bootstrap code OK; a scripted partner joined through a second admin device paired with `kvitt-server pair-device` (the CLI had no partner-invite subcommand then; `kvitt-server invite-partner` followed in `8660b7f`, D-113); Home showed the account; an expense added offline showed the pending marker and synced after reconnect (pending 0, the server has the row); the owner's device registered `fcm_token` and `app_version_name`; a push by `fid` was delivered and the notification tap worked. **M8b** (landed `328c466`) fixed what the owner saw: the invite-code field holds the raw code and draws the hyphens as a `VisualTransformation` with an exact offset mapping (cursor bug fixed, unit test `InviteCodeFieldTest`); the quick-row and grid selected badge is drawn above the ripple clip (it was cut off); `KvittTopAppBar` pads for the status-bar inset through a `windowInsets` parameter and `KvittScaffold` follows; chart bar corners top 4, bottom 2 dp (D-097); 221 goldens re-recorded. `FcmMessageBody.fid` in `:data` followed in `6eb3f85` (D-096). Still unverified on the phone: the status-bar fix (next install) and the design-spec §2.7 typeface check (the owner looked and had no complaint). Its contract requests were taken by M12e (D-086 to D-095); the `fid` field followed in `f56dcbe` (D-096). **M8e** (landed `a59abeb`, D-107) turned S-19's account, payer and split chips into `EditorOptionRows`; the unused `AccountChip`, `PayerChip` and `SplitChip` were removed in `1328afe`. **M8f** (landed `956908a`, D-108) made navigation instant (`NavTransitions` in `:app`).
* **M10**: the orchestrator relays every HUMAN step in chat. The keystore is created with the command of §10.6 at the repository root and referenced from `android/local.properties` (D-024, D-101).
* **M2c-pi** (D-100, revises D-023): no SSH from the Mac to the Pis and no allowances for agents on the Kvitt Pi, the Home Assistant Pi, Gitea or Google Drive. The agent writes and checks the `infra/pi/` bundle on the Mac; the owner copies it to the Kvitt Pi, fills the `.env` placeholders (OQ-3) and runs the README checklist, answering yes/no per check. It runs as the last step before M10, after the app is proven on the phone. The bundle landed `2476667` on 2026-10-18 (D-103 to D-106: layout and scripts, image names and the Gitea workflow, the backup uid, the cert-sync and backup refinements); the NPM rework (D-120, `4f69ae0` to `9231a1d`, 2026-10-19) replaced Caddy and cert-sync with a proxy host in the owner's Nginx Proxy Manager (§10.5); `PLAN-M2c-pi.md` carries a note that it is superseded there. D-125 (`6e5981d`, 2026-10-20) made the bundle a self-contained compose project in `/home/jacobhagstedt/kvitt` with no scripts and nothing outside that folder (§10.2, §10.10); the plan's note names it too. The remaining part is HUMAN, the owner installing the project on the Kvitt Pi (in progress 2026-10-20), and M10 depends on it.
* **M9** (landed `50339ae`) reuses the server's own push validation (`kvitt_server::api::validate`, `rows`) and the `SqlAuditWriter`, so imported rows pass the same checks as synced ones (§14.4.4). Its tests are one binary, `crates/kvitt-import/tests/import.rs`, over synthetic fixtures only; one test checks the §10.8 category table against `data/splitwise_categories.csv`.
* **M12a, M12b, M12c** (D-049 to D-054) carry the owner's UX-session decisions into the contracts and the landed code: M3, M5 and M9 were built with ten defaults, so this is a contract change against `main`, not only the spec. M12a (landed `aa765bb`) wrote `contracts/`, the checker and `:domain`'s `suggestCategory`; M12b (landed `6eaccec`) and M12c (landed `b09f322`) ran in parallel (disjoint paths, §14.7); their outcomes are D-055 to D-058. The Room schema stays at version 1: category rows reach the phone through sync. The colour hex values of `slate` and `amber` are not needed by M12 (`:core:model` holds token names only); they arrive with U2 and M6.
* **M12d** (D-059, landed `557af7e`) added the two UI-contract members UX-9 found (`ExpenseEditorOptions.frequentCategoryIds`, `CategoryRepository.deletable`) to `:core:model`, `:data` and `:core:fakes`, in parallel with M6 (disjoint paths); its readings are D-060 to D-062 (§14.2.4 "Readings fixed in v0.10"). M7c and M7f consume them; the design spec's fallbacks (`docs/ux/design-spec.md` §3.7 and §6) are no longer needed.
* **M6** (landed `7730a31`) built `:core:design` with charts on Compose `Canvas` (D-063), the Material 3 Expressive fallbacks of D-064, the formatting tables of D-065 and the golden layout of D-066. Its contract requests for **M8** (no change now): `:app` provides `LocalAvatarPictures` with an `AvatarPictures` that builds the authenticated E-11 Coil request from the user id and `pictureVersion` (§14.3.4); `:app` wraps every screen in `ProvideHousehold(me, partner)`; `:app` provides `LocalKvittClock` (tests and previews pass a fixed clock); `SyncSummary` gains a "last attempt failed" field so `SyncStatusPill` can drop its `failed` parameter (§13.3 S-4); done by M12e: `SyncSummary.lastAttemptFailed`, and `SyncStatusPill`, `syncPillVariant` and `syncLineText` no longer take `failed` (D-088). The design-spec §2.7 open point (that `FontFamily.Default` keeps tabular figures and distinct weights 500/600/700 under every One UI font style on the S26) is checked at the M8 install on the owner's phone; on 2026-10-18 the owner looked and had no complaint (not checked under every One UI font style).
* **M12f** (landed `dc7a296` to `a0259ab`, D-109 to D-112, D-116) took the Android findings of the AC-coverage audit and the security review (§11.4); see the §11.2 row. The S-1 confirm step for an unusual server (security review L-6) was not built: it needs a design state (OQ-6).
* **Server gap pass** (landed `8660b7f`, D-113): `kvitt-server invite-partner` (§10.4), which closes the ops request of the M8 test; tests for `invite-partner`, `migrate` (schema at `SCHEMA_VERSION`, idempotent), `healthcheck` (200, 503, nothing listening) and the SIGTERM drain of `serve`; the push sender's `push sent` info line (§8.7); `tools/contracts-check.py` follows `invite_kind` (D-086), `app_version_name` (D-090) and `fid` (D-096), 134 checks pass.
* **Server overhaul** (landed `8103dae` to `b985ce9`, D-114, D-115): shared stored-row reads and inserts (`src/api/rows.rs`, `src/sync/rows.rs`), shared invite creation and CLI plumbing, one test harness (`tests/common/`, §14.7), clippy pedantic wins, synchronous `tasks::start` (§6.3), `not_implemented` no longer produced (§14.3.2); the security fixes H-1 (D-115), M-3 and L-4 (D-114). Gate at landing: 268 server tests; all crates at their latest versions.
* **Infra overhaul** (landed `2fac1ec` to `e70fe0d`, no decision): one Gradle lock helper `tools/gradle-lock.sh` for `tools/gradle-serial.sh`, `tools/clean-builds.sh` and `infra/build-images.sh`; the pre-commit hook runs the Android tests through `tools/gradle-serial.sh` with JDK 25 on `PATH`, `JAVA_HOME` untouched; `install.sh` keeps the deployed `KVITT_TAG` (moot since D-125: no `install.sh`); `--provenance=false` on buildx pushes and the workflow token through the environment (§10.3; reversed by D-120 point 7); `RCLONE_REMOTE` dropped from the development env (§10 intro). **Infra security** (landed `7fb86f5`, D-117): Caddy log redaction and response headers (§8.7, §10.5.2), the non-root Caddy container (§8.9, §10.2), the development stack's single secret (§10 intro), the digest record (§10.3, §10.10; dropped by D-125 for `docker image inspect`), `kvitt_cicd` with `write:package` only (§10.3), the restricted cert-sync key (§10.5.1). D-120 carries the log redaction and the headers over to NPM's Custom Nginx Configuration (§10.5.2) and removes the Caddy container, the digest of its image and the cert-sync key.
* **Overhaul outcomes** (2026-10-18). Server: landed through `b985ce9` (see the server overhaul above). Infra: landed through `e70fe0d` (see the infra overhaul above). **Android overhaul** (landed `e4e6e5d` to `c582363`, D-118, no prompt file, orchestrator brief): one screenshot and test harness in `:core:design`'s test fixtures and the convention plugin `kvitt.android.screenshots` (§6.2); the shared failure texts, limits and `savedSplitLabel` in `:core:design` (§6.2); dead code removed (`KvittMotion` down to the seesaw spring, `KvittIcon.Description`, unused dimens and shapes, catalogue and fake samples); the catalog entries `roborazzi-junit-rule`, `roborazzi-compose`, `androidx-hilt-navigation-compose` and `androidx-lifecycle-viewmodel-compose` removed; one `CopyCategoryKeywords` task in `build-logic` shared by `:data` and `:core:fakes` (D-055 holds); one `configureAndroidModule` for the application and library plugins; S-7's state types in `ExpenseEditorState.kt`. Gate at landing: 941 tests, no golden changed; release APK 10.46 MB. Pushed to `origin` at `c582363`.
* **M11** runs the import per §10.8 "Production run" (D-025). The rehearsal on 2026-10-18 ran both real files against a throwaway database and reconciled on both (Vardag 1746 rows, Hemma 37 rows); 21 rows were unmapped before D-044. The dry run of 2026-10-18 with M12b's mapping confirmed it: Vardag 1746 rows, 0 unmapped; Hemma 37 rows, 0 unmapped; both reconciled.
* **W0 to W7** (D-134, §15.9): the web client programme. W0 and W7 run first in parallel (disjoint paths); W1 to W5 run in parallel once W0 has landed; W4's W-11 and W6 wait for W7. W0 owns `web/**` except the feature folders, registers every route with a placeholder page per feature folder (as M2a registered every route, D-004), and lists its module paths in its report; W1 to W5 build only inside their feature folders and take everything shared from W0's modules (a missing shared piece is a request to the orchestrator, as M7x's requests went to M6b). A second agent to land that changed `web/package.json` resolves `web/package-lock.json` with `npm install` on rebase (as `Cargo.lock`, §14.7). A plan that changes `contracts/openapi.yaml` regenerates `web/src/api/schema.d.ts` (§15.3). Web agents do not use the phone or `tools/gradle-serial.sh`; a manual check runs against a throwaway server, never the owner's development or Pi data (§15.4). The orchestrator adds the web gate to `CLAUDE.md` "Build and verify" (D-131). W1 to W5 landed 2026-10-21 (`934eee7`, `a65ab71`, `f9a9bfb`, `1aecf51`, `3ebe57d`; D-144 to D-154, D-150 unused) with the web gate green on `main` (59 test files, 532 tests at `1aecf51`); a web fix (`83f5293`) followed (598 tests). Pieces built twice or three times in feature folders and other loose ends are listed for a W0b plan in `docs/HANDOFF.md` "Web follow-ups". W0b landed `5305f37` (v0.34). All of W0 to W7 are landed and verified: `v1.0.3` (built on the Mac from `8fa9198`, D-211) runs on the Kvitt Pi and the owner checked the web client and the phone's Insights against it on 2026-10-24 (§11.4).

* **K0 to K3** (D-176, §11.1): the card-purchase programme. K0 runs first, on the Mac only, with the owner (a local test app for fast feedback before any Android work, owner's refinement 2026-10-24; the app landed `2ce317f`); K0 is done (run 2026-10-24, report `docs/spikes/K0-enable-banking.md`) and its answers are in SPEC v0.36 (D-177 to D-180), so K1 to K3 can start. The reports of K1 to K3 propose spec text and decisions that a docs agent records: K1's in SPEC v0.38 (landed `671c00d`, D-181 to D-188), K2's in v0.39 (landed `a8f91ee`, D-191 to D-200), K3's in v0.40 (landed `faeb752`, D-201 to D-207) (decisions from D-191 to D-210, disjoint ranges per plan). Then K1, K2 and K3 run in parallel in their own worktrees (disjoint paths, §14.7): K1 owns the contract (`contracts/**`, the migration text, the vectors) and lands first; K2 and K3 build against the spec and fakes, and rebase on K1 before their gates (K2's DTO tests and K3's generated types need K1's contract); K3 lands after K2, whose `docs/ux/strings.csv` rows it imports (`npm run i18n:import`). K2 uses the phone only when its brief names it; K1 and K3 never use the phone. No plan connects to the owner's real card except through the owner's own BankID step; no plan stores, prints or commits a real purchase.

### 11.4 Validation reports

Reports in `docs/validation/` are deliverables (`CLAUDE.md`); they carry aggregates only and record the commit they were taken at. The release reports `first-release.md` and `restore-drill.md` (M10, AC-18.2) are still to be written.

* `docs/validation/ac-coverage.md`, the AC-coverage audit taken at `956908a` (`ed1b130` before the history rewrite; SPEC v0.16), read-only: 270 rows, 260 Done, 5 Partial, 1 Missing, 4 not verifiable without a device. Verdict: feature complete in code; not yet complete against §4's acceptance rule. Its two mismatches in shipped behaviour are fixed by M12f: S-16 opens the lost change read-only (D-109) and S-22 reads the server version from `/health` (D-110); M12f also added tests for the §9.2 effect cases, AC-2.9, the 429 retry, D-040 refusals and WorkManager unique work. Still open: the AC-18.2 restore drill (Missing), AC-20.1 observed on the Pi (M10), and a `KvittWorkerFactory` test. Observed 2026-10-24 (D-156): AC-18.1, the first backup on the Pi with its snapshot pair in the Drive folder (verified by the owner); AC-16.3, the real `PackageInstaller` install on both phones (release 140), once Samsung Auto Blocker was off; the editor keyboard fix (S-19, S-15, S-6, `05ec3f3`) on the device. Observed 2026-10-24 (D-211), the web client's first use (FR-21) and W6: image `v1.0.3` on the Kvitt Pi, `server` and `backup` healthy; `https://kvitt.suorra.duckdns.org/app/` paired from the laptop browser with a device invite; the owner reports "All seems to work" for Home and an account, add, edit and delete of an expense, the CSV export, recording and deleting a payment, analytics with a category drill-down and Insights, every settings page, revoking the browser from the phone, and the Android Insights section on S-11 against this server.
* `docs/validation/security-review.md`, the security review taken at `18c527f` (SPEC v0.17), read-only: Critical 0, High 1, Medium 3, Low 10, Info 8; the design matches §8 and is sound. Status at v0.18: L-6 kept as built and L-7 fixed (D-116); L-1, L-2, L-5, L-9 and M-2 fixed in infra (D-117); L-8 fixed (`e70fe0d`); H-1 (the in-memory rate limiter, `725901c`), M-3 (picture decoding memory, `baa5806`) and L-4 (`fcm_token` length, `b985ce9`) were fixed by the server overhaul (D-114, D-115); L-10 (a member gets `forbidden` rather than `not_found` for another user's device): owner answer 2026-10-24, `not_found` (D-156), fixed in `07c36d2` (E-16). Owner answers of 2026-10-19: M-1 (backup encryption) no, closed as an accepted risk (§8.1, §8.7); L-3 (APK download rate) accepted and fixed (`96e4cbd`, D-119: 10 per minute per IP for E-6); the 16 megapixel picture cap and the 512-character `fcm_token` limit (D-114) confirmed. H-1 had to be fixed before the server was opened to the internet (fixed, `725901c`). D-120 (2026-10-19): L-1's redaction and D-117's headers now live in NPM's Custom Nginx Configuration (§10.5.2); L-2 and M-2 are moot (no Caddy container, no Home Assistant SSH key); the L-8 fix is reversed (the token is interpolated in the run line again, masked by act_runner, §10.3); I-5's check is the conntrack check of §10.10. The review carries dated notes under those findings.

---

## 12. Open questions

Only things that cannot be decided without the owner. Everything else in this spec is decided.

| Id | Question | Needed by | Default if unanswered |
|---|---|---|---|
| OQ-1 | Answered (D-001): the registry is a Gitea instance on another Pi at `http://gitea.lan`, plain HTTP, reachable only on the home Wi-Fi; images are built by Gitea Actions from the owner's example workflow (provided; `.gitea/workflows/build-images.yaml`, D-104). | M2c-pi | answered |
| OQ-2 | Answered (D-003): two exports, English and Swedish header variants, member columns in either order, ISO dates, point decimal, double-quoted fields, trailing empty line and `Total balance` / `Totalsumma` row, payment category `Payment` / `Betalning`, all rows SEK. Group "hemma" becomes account "Hemma", the general group becomes account "Vardag". Details §10.8 and PLAN-M9. | M9, M11 | answered |
| OQ-3 | Answered by placeholders (D-100, revised by D-120): the LAN address of the Kvitt Pi (`<kvitt-pi-address>`; its `.env` key `KVITT_PI_HOST` was dropped in `200c99f`) and the LAN IPv4 address of the Home Assistant Pi, where NPM runs (`HA_HOST`); with D-120 also the Kvitt host name (`KVITT_PUBLIC_HOST`, owner-chosen, recorded in HANDOFF). ~~SSH port and user of the Home Assistant Pi; the directory holding `fullchain.pem` and `privkey.pem` there; which SSH add-on is used~~ (cert-sync removed by D-120). The owner fills `HA_HOST` in the Pi's `.env` (D-125) and uses the Kvitt Pi's address in NPM and in `scp`; no agent needs them. | M2c-pi | answered |
| OQ-4 | Answered: the Google Drive backup folder id is `1jDp1dGE5R3H2DBcXCqIPN1iWzQnPkdlV` (§10.9). | M2c-pi | answered |
| OQ-5 | Answered 2026-10-18 and implemented (D-099, `a0c25b0`): no licences screen in v1; S-22 has no "Licenser för öppen källkod" row. | M10 | answered |
| OQ-6 | Answered 2026-10-24 (D-156): no confirmation step on S-1 for an invite link that prefills a server other than the release default (`RELEASE_SERVER_URL`, AC-2.6) (security review L-6); the default stands: S-1 opens its server row expanded for a non-default server so the address is visible (AC-2.6, D-116). | M10 | answered |
| OQ-7 | Should a new card purchase raise a notification on the holder's phone (a local one, built from the holder's own data; never an FCM payload with content)? | K2 | Not in this version: purchases appear on the next sync without a notification (D-171) |
| OQ-8 | Should several purchases be turned into expenses at once ("Lägg till i konto…", one expense each with the account's default split)? | after K2 | Not in this version (D-171); one purchase at a time through S-7 |
| OQ-9 | `CardPurchase.linked` (§14.2.4) is null both when a purchase is unlinked and while its linked expense is not yet on the phone (for example a link made in the web client to an expense the phone has not pulled yet), so the purchase is listed under "Kopplade" without its "Kopplad till" line and its sheet briefly offers "Skapa utgift" and the matches. Add `linkedExpenseId` to `CardPurchase` so the sheet can say "Kopplad" without the expense's details (a UI-contract change, §14.8)? | next Android card pass | Not now: the window lasts until the next household sync brings the expense |

---

## 13. UX sprint

A brief for one UX agent (Opus) who has read this spec and nothing else. It runs right after M0, in parallel with M1, and before any UI work (M6, M7). It produces proposals; the owner chooses; the UX agent then writes the binding design spec. The UX agent writes no Kotlin.

### 13.1 Context the UX agent must design for

* Two adults in Sweden, one household, using Samsung Galaxy S26 (about 411 × 891 dp viewport, 6.3") and S26+ (about 411 × 891 dp at a higher density, 6.7"). Portrait only. Android 16, One UI on top; the app uses Material 3 (Expressive where stable) and must not imitate One UI.
* Most sessions are 10 seconds: add an expense right after paying. The add flow is the most important flow; it must need at most: open app, tap add, type amount, type description, tap save (category and account defaulted, AC-8.6).
* The second most important view is "who owes whom" on Home.
* Swedish is the primary language (both users' phones are Swedish), English must fit too. Swedish words are long ("Utgiftskonto", "Återkommande"); designs must survive them at 200 % font scale.
* Light and dark theme follow the system. Dynamic colour (Material You wallpaper colours) is offered as an option per direction only if the direction still works with it; the default is the direction's own palette.
* Money must be legible at a glance: amounts in tabular figures, direction ("owes you", "you owe") always in words plus colour, never colour alone.
* Accessibility: touch targets ≥ 48 dp, contrast ≥ 4.5:1 for text, TalkBack labels for every icon-only control, nothing conveyed by colour only, layouts that reflow at 200 % font scale.
* Category icons are Material Symbols from the set in §9.7; category colours are the tokens of §9.7 (the UX agent may change hex values, not token names, and must give light and dark values with contrast checked against both surfaces).
* Users are shown by avatar (picture or initials, AC-4.5) and display name. The viewer is always "you" / "du".

### 13.2 Navigation model (binding, D-048)

* Destination changes are instant, with no transition animation (D-108); motion stays inside screens (design-spec §2.11).
* ~~Bottom navigation with three destinations: **Home** (Översikt), **Analytics** (Statistik), **Settings** (Inställningar).~~ Revised by D-172 (owner, 2026-10-24): bottom navigation with four destinations, in this order: **Home** (Översikt), **Card purchases** (Kortköp, S-23), **Analytics** (Statistik), **Settings** (Inställningar). Kortköp sits next to Översikt because turning purchases into expenses is daily work beside the add flow, while Statistik is visited now and then and Inställningar stays last. Both users always see the tab; without a connection it shows its empty state with "Anslut kort". An "Aktivitet" feed (the other person's changes across accounts) was considered as a fourth destination and not taken for v1 (D-048).
* A floating action button "Add expense" (Lägg till utgift) on Home and on Account detail.
* Account detail, expense editor, expense detail, settle up, settlement detail and all settings sub-screens are pushed screens with a top app bar and back.
* The expense editor is a full-screen screen, not a bottom sheet (the numeric keyboard needs the room).
* Wiring (D-071, as built by M7a to M7f and connected by M8): the top-level screens S-3, S-4, S-11 and S-13 render their own `KvittNavigationBar` and take `onNavigate: (KvittDestination) -> Unit`; the `:app` scaffold draws no second bar, and the `NavHost` switches top-level destinations from those lambdas. Since D-172 S-23 is the fourth top-level screen that draws the bar, and `KvittDestination` (`:core:design`) gains `Cards` between `Home` and `Analytics` (as built by K2, `a8f91ee`: `enum class KvittDestination { Home, Cards, Analytics, Settings }`, icon `credit_card`, label `nav_cards`; a label that does not fit its slot at a large font scale shrinks to fit, down to 70 %, D-197). Navigation-argument keys are constants in each feature (`ARG_EXPENSE_ID` and `ARG_ACCOUNT_ID`; `SettleArgs.SETTLEMENT_ID` and `SettleArgs.ACCOUNT_ID`; `DrillDownArgs.KEYS`; settings `"categoryId"` and `"templateId"`), read through `SavedStateHandle`.
* Result snackbars (D-071): the result of S-7 ("Utgiften sparades"), of S-9 and of archiving an account is shown by the screen returned to; the account-archived snackbar has an undo action (`common_undo`, "Ångra"). As built by M12e (D-095): six screens host `:app`'s shared `snackbarHostState` in their own scaffold (Home, AccountDetail, ExpenseDetail, SettlementDetail, DrillDown, SyncStatus), so a snackbar never overlaps a FAB or the bottom bar; `:app` has no overlay host. Features hand `:app` string resource ids, never resolved strings: `ExpenseEditorScreen.onSaved(ExpenseId, @StringRes Int?)`, and `onDeleted()` on S-7 and S-8 takes no argument, `:app` then shows `snackbar_expense_deleted`.
* Session gate (as built by M8): S-1 for an unpaired or unrecognised session, S-2 for the profile step after a `partner` pairing only (AC-2.10, D-086; a member pairing a second phone with a `device` invite goes to Home), S-18 for a revoked device (back on S-18 closes the app). Home shows S-3 while the household has no partner (`partner == null`).

### 13.3 Screens and what each must show

Each screen must be designed in these states where they apply: **loaded**, **empty**, **offline** (with pending changes), **loading** (first sync only; afterwards data is local), **error** (a failed online action), and, for lists, **long content** (long Swedish names, 7-digit amounts). Which states apply to which screen is listed per screen in U2's `docs/ux/design-spec.md`; that list is the binding one for U2's gate and for the feature milestones' screenshot tests.

| Id | Screen | Must show | Actions |
|---|---|---|---|
| S-1 | Pairing | App name and one-line purpose; server URL field (prefilled; in release builds with `RELEASE_SERVER_URL`, which `:feature:onboarding` receives through the Hilt qualifier `@ReleaseServerUrl` for the prefill and for the non-default-server check of AC-2.6, D-121); invite code field (12 characters, shown in groups of 4); display name field ("Ditt namn", 1 to 40 code points, §9.6), required on a first pairing and hidden in the "Para ihop telefonen igen" variant (D-050); explanation of where the code comes from (`onboarding_code_help` with the admin's name when the invite link carries `from`, else the generic help line `onboarding_code_help_generic`; `PairingScreen(initialAdminName)` and `PairingViewModel.prefill` carry the name from `:app`'s `AppLink.Invite`, and a pasted link fills it too, D-087); progress while pairing; errors `invite_invalid`, network error, `rate_limited` | Pair; paste code |
| S-2 | Partner profile step | Display name field (prefilled; a blank name shows `onboarding_error_name_required` "Skriv ditt namn"), avatar with "Add picture"; the owner's name and avatar ("You are joining Jacob"). Shown only after a `partner` pairing (`Pairing.inviteKind`, D-086) | Continue |
| S-3 | Waiting for partner | Explanation that the partner must join first; the pending invite's expiry if any; error state when fetching the invite failed (snackbar with "Försök igen") | Invite partner (goes to S-21); Settings |
| S-4 | Home | Global balance header: both avatars, wording per §9.3, amount; "Settle up" button when non-zero; sync line: "Last synced …" and pending count when > 0, tap opens S-16 ("Sync failed" when `SyncSummary.lastAttemptFailed`; `SyncStatusPill` takes no `failed` parameter, D-088); update banner (S-17) when available ("Later" hides it for the ViewModel's lifetime only, so it returns on the next start); list of active accounts, each with name, balance wording and amount, number of expenses this month; collapsed "Archived (n)" section; empty state when no accounts ("Create your first account") | Add expense (FAB); Settle up; open account; New account; Pull to refresh (sync now, D-127) |
| S-5 | Account detail | Account name, default split with names (ratios written "60/40", `common_ratio`), balance header; list of expenses and settlements interleaved by date, grouped by month with month totals (household spend; month headers are not sticky), each expense row per AC-8.10, each settlement row per AC-11.7 (its title may wrap to 2 lines, 3 at 200 % font scale, and its second line is the type label `ledger_settlement_label` "Betalning" from `:core:design`, D-068); archived badge if archived (an archived account hides the add-expense FAB, AC-6.4, and keeps "Settle this account", D-052); pending-sync marker per row | Add expense (not on an archived account); Settle this account; Edit account; Archive / Unarchive; Delete (only if allowed); Pull to refresh (sync now, D-127); "Från kortköp" (overflow menu, first item, only while the viewer has a card connection and not on an archived account, D-199; opens S-27, AC-22.9) |
| S-6 | Account editor | Name field; default split control (one slider or stepper plus two percent fields that always sum to 100, two decimals allowed); preview "Of 100,00 kr: Jacob 60,00 kr, Anna 40,00 kr"; "Needs connection" state; the discard dialog has a title and no body text (D-080) | Save; Cancel |
| S-7 | Expense editor | Amount entry (large, numeric keyboard, `kr`); description; account picker (active accounts); category picker (grid of icon + colour + name, active categories; for a new expense the category is selected from the description per §9.11, with no marker); date (today default, date picker); payer toggle (two avatars: "Paid by"); account, date, payer and split shown as four fixed full-width rows in that order, which do not move when a value changes (D-102); split section: mode chooser (`default` "Account default 60/40", `ratio` "Custom ratio", `exact` "Exact amounts", `full` "All on one person") and its controls; live preview of each person's share; notes (collapsed by default); validation errors inline; delete in edit mode; opened from a card purchase (S-23's sheet or S-27, CP-9, D-169) it starts as a new expense prefilled from the purchase, and "Spara" also links the purchase (a foreign-currency purchase leaves the amount empty); after saving, the snackbar "Utgiften sparades" without "Ångra" (an undo would be an audited create and delete that also notifies the partner, D-052), shown by the screen returned to (D-071), `onSaved` handing `:app` the string resource id (D-095); the quick row is filled by `quickRowCategories` (D-075) and category labels take up to two centred lines, a longer custom name ending the second line in "…" (D-076); the discard dialog has no body text (D-080) | Save; Cancel; Delete (edit mode) |
| S-8 | Expense detail | Amount, description, category, account, date, payer, each user's share and the split mode, notes, "Recurring: <template>" when generated; for the card holder only, when a purchase of theirs is linked to it, the line "Från kortköp: <merchant>, <date>" (`expense_detail_from_card`) with "Ta bort koppling" (AC-22.10, D-169); timeline (AC-12.4, AC-12.5); "deleted" state when opened from a notification of a deletion; "missing" state (not yet on this phone) with "Synka nu" (`expense_detail_sync_now`), online only (§9.9, D-080); after a delete `:app` shows `snackbar_expense_deleted` on the screen returned to (D-095) | Edit; Delete |
| S-9 | Settle up | Direction ("Anna pays Jacob" with a swap control); amount; allocation list: account name, account debt, editable allocated amount, over-settle warning per row (AC-11.5); remaining-to-allocate indicator; "Add account"; date; note; per-account variant with a single fixed row, which keeps the direction swap (§9.4: per-account settle-ups go either way) and an editable amount (AC-11.4 "defaults to") (D-052); when editing, the saved rows count as edited and "Föreslå igen" re-proposes; the info line on untouched accounts reads `SettleState.untouched` (nets without the settlement being edited, empty for a per-account settle-up, D-093, revising D-074's reading of Home balances); the discard dialog has no body text (D-080) | Confirm; Cancel |
| S-10 | Settlement detail | Payer, recipient, amount, date, note, allocations per account; timeline; "missing" state with "Synka nu" (`settle_detail_sync_now`), online only (§9.9, D-080) | Edit; Delete |
| S-11 | Analytics | Range selector (presets of AC-14.2 plus custom); granularity toggle month/week; measure toggle household / my share; group-by toggle category/account; total for range; chart 1 stacked bars over time with legend; chart 2 category breakdown; chart 3 account breakdown; empty state ("No expenses in this period"); a chart whose range has no expenses shows only the 0 baseline, with no gridline values (D-068). Total card (D-069): caption "<range> · Hushållet" for the household measure and "<range> · N veckor" in week granularity; for my share the label is "Totalt · Min del" so the caption does not repeat it; month presets show whole-month ranges ("maj–okt 2026"), custom ranges and week granularity show days (§9.8, D-077). Legend and stacking order: categories by `sortOrder`, accounts in `AccountRepository.all()` order (`AnalyticsState.groups` order is unspecified, §14.2.4). Loading means `SyncSummary.lastSuccessAt == null` and shows skeleton cards; offline looks like loaded; no error state (analytics are local, AC-14.1). Insights section (D-142, D-143), online only. | Change filters; tap a bar or a row to open S-12; pick a category in Insights; "Försök igen" |
| S-12 | Analytics drill-down | Title naming the filter ("Mat & hushåll, oktober 2026"; a week as in `docs/ux/strings.csv`, "Vardag, vecka 41"; a category or account over the whole range "<name>, <range caption>") (D-070); total; expense rows as in S-5. A category or account over the range adds, above the total, its own range selector (AC-14.2 presets plus custom) and month/week toggle, both starting from S-11's values and changing S-12 only; below the total, the line chart of AC-14.11; then the rows. A range with no expenses reads "No expenses in this period" (D-128). No loading and no error state (D-070) | Open expense; change range or granularity |
| S-13 | Settings hub | Own avatar and name; partner's avatar and name; rows: Profile, Categories, Recurring expenses, Anslut kort ("Connect card", fourth row of the first group, subtitle "Ansluten · giltig till <date>", "Har upphört" for an expired connection (D-199) or "Läs in dina kortköp", D-172), Devices, Invite partner or Pair a device (admin), Sync status, About | Navigate |
| S-14 | Profile | Avatar with change/remove; display name; "Needs connection" state | Save |
| S-15 | Categories | List: icon, colour, name, archived section; editor: name (with "Reset name" for defaults), icon grid (33 icons of §9.7), colour swatches (14 tokens); delete or archive with the reason when delete is not allowed | Add; Edit; Reorder (drag); Archive; Delete |
| S-16 | Sync status | Last successful sync time; pending changes count with a list (the shared ledger rows of `:core:design`, D-019, not a separate 36 dp row); "Changes not synced" list from `sync_rejections` with what was lost and why (copy per §14.4.6 reasons); clock-skew warning; "Sync failed" when online and `SyncSummary.lastAttemptFailed` (D-088); the stale-change copy names `Rejection.actor`, the partner when it is null (D-089); "Sync now", online only (§9.9, D-080); "Öppna" on a rejection shows the phone's lost version read-only (D-109): a dialog "Din version" (`home_sync_lost_title`, body `home_sync_lost_body`) with the ledger row it would have been (read-only: the row's `onClick` is null), the account, payer, split and notes (`Rejection.lost`, §14.2.4), the badge "Du tog bort den här" (`home_sync_lost_deleted`) when the refused change was a deletion, and "Visa nuvarande version" (`home_sync_lost_show_current`), which opens S-8 or S-10; when `lost` is null (unreadable payload, or its category or a user is not on the phone) "Öppna" opens the current version directly | Sync now; open a rejected change (read-only); dismiss it |
| S-17 | Update available | Banner on Home with version name; dialog explaining "Install unknown apps" the first time; download progress; failure (download, or the install refused or failed with its reason, AC-16.7, D-155) | Update; Later |
| S-18 | Device removed | Explanation that this phone's access was removed and local data deleted | Pair again (goes to S-1) |
| S-19 | Recurring expenses | List: description, amount, account, "Every month on day 25", next date, paused badge; editor with the expense fields of S-7 (no date); account, payer and split as three fixed full-width rows (Konto, Betalt av, Delning; D-102, D-107) plus day of month (a new template defaults to today's day, AC-9.8, D-072), first month, optional last month, pause switch; a new template is sent as `NewRecurringTemplate` (`RecurringForm.newTemplate()`), an edit as `RecurringTemplate` (`RecurringForm.template(original, …)`), D-091; the discard dialog has no body text (D-080) | Add; Edit; Pause/Resume; Delete |
| S-20 | Devices | Rows per AC-3.1; the app version shows `Device.appVersionName` ("Kvitt 1.1"), else the version code (D-090) | Revoke (with confirmation) |
| S-21 | Invites | For the admin: "Invite partner" (only before the partner joins) and "Pair another device" for either user; a created invite shows the code in groups of 4, the link, expiry, and a share action (Android share sheet); list of pending invites with cancel | Create; Share; Cancel |
| S-22 | About | App version name and code, server URL (the paired server; before pairing the build's release server, `AppBuildInfo.releaseServerUrl`, D-122), server version from E-1 `/health`, fetched when S-22 opens while online, shown as "<version> (schema <n>)" (`settings_about_server_version_schema`, "1.1.0 (schema 3)"); offline or when the call fails, the `X-Kvitt-Server-Version` header of the last response without the schema (`AboutState`, §14.2.4, D-110); no open-source licences row (OQ-5, D-099); after "Check for update": `UpdateCheck.UpToDate` shows "Du har den senaste versionen" (`settings_about_up_to_date`), `UpdateCheck.Failed` shows "Kunde inte nå servern" (`common_could_not_reach_server`) (AC-16.6, D-092); the button calls `UpdateRepository.checkNow()`, which always asks the server (D-140) | Check for update |
| S-23 | Card purchases (Kortköp; `:feature:cards`, top-level, D-172) | Top app bar "Kortköp"; a header card with the card's artwork (small, `CardArt`), its name, "Bara du ser dina kortköp" and "Uppdaterad <relative time>" (§9.8 relative form) with an "Uppdatera" button (a spinner and "Uppdaterar…" while E-42 runs); filter chips "Att hantera" (default), "Kopplade", "Ignorerade", "Alla", each with its count; the purchases of the filter, newest first, grouped by day (day headers in the §9.8 list form), each row: merchant (one line, ellipsis), amount (`MoneyText`, or "<amount> <currency>" with "Utländsk valuta"), "Preliminär" chip when pending, "Insättning" for a credit (only under "Alla"), and under "Att hantera" the match chip of CP-10 ("Koppla till <description>" or "<n> möjliga utgifter"); under "Kopplade" the line "Kopplad till <description> · <account>". States: no connection (empty: large artwork, "Anslut ditt kort", "Se dina köp här och gör om dem till utgifter med några tryck. Bara du ser dem.", "Anslut kort" → S-24); first fetch ("Hämtar dina köp…" with a progress indicator, while connected and no fetch has finished); loaded; empty filter ("Inget att hantera" / "Nya kortköp visas här." for "Att hantera", "Inga köp här" for the others); offline (the stored list, "Uppdatera" disabled with "Kräver anslutning"; linking and ignoring still work, CP-9); expiring (warning banner "Kortanslutningen upphör <date>" with "Förnya med BankID", CP-6); expired (banner "Kortanslutningen har upphört" with "Förnya med BankID"; list kept); fetch failed (banner "Kunde inte hämta köp. Senast uppdaterad <time>" with "Försök igen", CP-14); long content (long merchant texts, 7-digit amounts). Purchase sheet (bottom sheet on tapping a row): merchant, the purchase date in the detail form, amount, status ("Preliminär" / "Bokförd"); for a debit purchase to handle: "Skapa utgift" (primary) → S-7 prefilled (CP-9); "Koppla till befintlig utgift" with up to 3 matches (each: description, account, payer, date, amount; one tap links and closes the sheet with the snackbar "Kopplad" and "Ångra"), or "Ingen utgift med samma belopp runt det här datumet"; "Välj en annan utgift" (the CP-10 list in a second sheet); "Ignorera" (snackbar "Ignorerad" with "Ångra"). Linked: "Öppna utgift" (S-8), "Ta bort koppling". Ignored: "Sluta ignorera". Credit: the note "Insättningar och återbetalningar är inga utgifter. Ändra den ursprungliga utgiften för hand vid behov." and no action. Foreign currency: the note "Beloppet är i <currency>: skriv beloppet i kronor." above "Skapa utgift". As built by K2 (`a8f91ee`, design-spec S-23): at most one banner, above the header card, expired before expiring before fetch failed; expired also disables "Uppdatera"; the header card opens S-26 (TalkBack click label "Kortanslutning", `cards_connection_settings`); during the first fetch the header has no "Uppdaterad" line and no filters show; the four filter chips wrap to a second row (D-198); a row shows "Utländsk valuta" as a badge next to "Preliminär" or "Insättning"; the one-match chip links in one tap (snackbar "Kopplad" with "Ångra"), the "<n> möjliga utgifter" chip opens the sheet; back from "Välj en annan utgift" returns to the purchase sheet; a failed "Uppdatera" on the network shows the snackbar "Kunde inte nå servern"; a purchase linked to an expense not yet on the phone is listed under "Kopplade" without the "Kopplad till" line and its sheet shows the to-handle actions until the expense arrives (`CardPurchase.linked` is null then, OQ-9) | Uppdatera; Pull to refresh; filter; open a purchase; Skapa utgift; link a match (also from the row's chip); Välj en annan utgift; Ignorera / Sluta ignorera; Ta bort koppling; Öppna utgift; Förnya med BankID; Anslut kort |
| S-24 | Connect card (Anslut kort; `:feature:cards`, pushed from S-13, D-172) | App bar "Anslut kort"; intro "Välj ditt kort. Kvitt läser dina köp men kan aldrig betala eller flytta pengar."; one large tile per catalogue entry (E-36): the card's artwork (`CardArt`, full width, card aspect ratio 1.586:1, corner radius 16), name, issuer; a connected card's tile adds "Ansluten · giltig till <date>" and opens S-26; a provider not available shows "Inte konfigurerat på servern" and is disabled (AC-22.1); loading (skeleton tile), offline ("Kräver anslutning", tiles disabled; the catalogue comes from the server), error ("Kunde inte nå servern" with "Försök igen"). As built by K2: offline shows the `NeedsConnectionBanner` "Listan över kort hämtas från servern. Anslut telefonen till internet." (`cards_connect_offline_body`, D-200) and the cached catalogue entry's tile disabled (D-194); E-36 is asked again when the phone comes online; the connected line's date is in the §9.8 list form | Open a card (S-25 or S-26) |
| S-25 | Connect a card (`:feature:cards`, pushed from S-24, or from "Förnya med BankID") | App bar with the card's name; the artwork (large); "Hämta köp från de senaste" with ~~a segmented choice~~ wrapping filter chips (D-198) "7 dagar", "30 dagar" (default), "90 dagar", "180 dagar" (CP-3); the note "Du kan korta perioden senare. En längre period kräver BankID igen."; the button "Anslut med BankID" (renewal: "Förnya med BankID", the history preset to the connection's). After the tap: waiting state "Väntar på BankID…" with "Slutför i webbläsaren och i BankID och kom sedan tillbaka hit." and "Avbryt" (stops polling; the attempt expires by itself); connected: "Kortet är anslutet" then S-23; failed: "Det gick inte att ansluta kortet" with "Försök igen"; timed out: "Anslutningsförsöket tog för lång tid" with "Försök igen"; offline: the button disabled with "Kräver anslutning". As built by K2: E-38 is polled every 2 s only while S-25 is open and resumed (the Custom Tab on top pauses it) and once at once when the return link arrives (D-196); "Kortet är anslutet" shows for 1.5 s, then S-23; "Avbryt" returns to the choice; E-37 failing on the network shows "Kunde inte nå servern" above the button, any other failure, or no browser to open the bank page, the failed state; timed out is shown when E-38 answers `expired` (the server's 15 minutes), with no clock check on the phone | Anslut med BankID; Avbryt; Försök igen |
| S-26 | Card connection (`:feature:cards`, pushed from S-24, or from S-23's header) | App bar with the card's name; artwork; status line ("Ansluten", "Har upphört"); "Giltig till <date>" (detail form); "Senast uppdaterad <time>"; "Historik vid anslutning" with the current value, shorter values selectable (E-41), a longer one only through "Förnya med BankID" with the note "En längre period kräver BankID igen" (CP-3); "Förnya med BankID" (always offered; highlighted from 14 days before `valid_until`, and when expired: filled instead of tonal); "Koppla från" (error colour) → dialog "Koppla från <card>?" / "Köp som du inte har kopplat eller ignorerat raderas. Utgifter du har skapat finns kvar." with the checkbox "Radera även kopplade och ignorerade köp" and "Koppla från" / "Avbryt" (CP-12); offline: every action disabled with "Kräver anslutning". As built by K2: artwork, then a facts card (status line with a filled `check_circle` in `owed` or a filled `error` in `error`, "Giltig till", "Senast uppdaterad"), then the history as wrapping chips listing only the current value and shorter ones (D-198), then the two buttons; a network failure shows the snackbar "Kunde inte nå servern"; after "Koppla från" the screen closes | Change history; Förnya med BankID; Koppla från |
| S-27 | From card purchases (Från kortköp; `:feature:cards`, pushed from S-5) | App bar "Från kortköp" with the account's name as subtitle; the viewer's purchases to handle (debit, SEK or foreign, neither linked nor ignored), newest first, as S-23's rows without chips, grouped by day under S-23's day headers (as built by K2); empty: "Inga kortköp att hantera"; works offline; S-7's "Utgiften sparades" shows here on return | Tap a purchase: S-7 prefilled with this account (CP-9) |

System notifications (copy needed in both languages, built per AC-13.5):

| Type | Title | Body |
|---|---|---|
| `expense_created` | "<Actor> added an expense" | "<description> · <amount> · <account>" |
| `expense_updated` | "<Actor> changed an expense" | "<description> · <amount>" |
| `expense_deleted` | "<Actor> deleted an expense" | "<description> · <amount>" |
| `settlement_created` | "<Actor> recorded a payment" | "<payer> paid <recipient> <amount>" |
| `settlement_updated` | "<Actor> changed a payment" | "<payer> paid <recipient> <amount>" |
| `settlement_deleted` | "<Actor> deleted a payment" | "<amount>" |
| `recurring_expense_created` | "Recurring expense added" | "<description> · <amount> · <account>" |
| `sync_batch` | "<Actor> made <count> changes" | "Open Kvitt to see them" |
| any, when the sync failed | "<Actor> changed something in Kvitt" (or "Kvitt" without actor name) | "Open Kvitt to see it" |

The UX agent writes the Swedish versions.

Invite landing page (E-4, AC-2.5). Server-rendered HTML, so these strings live in the server (M3's `src/api/landing.rs`), not in the app's resources:

| Element | English | Swedish |
|---|---|---|
| App name | Kvitt | Kvitt |
| Download button | Download Kvitt | Ladda ner Kvitt |
| Open button | Open in Kvitt | Öppna i Kvitt |
| Instruction sentence | Install Kvitt, then open this link again on your phone. | Installera Kvitt och öppna sedan den här länken igen på din telefon. |

The download button is omitted while no APK is published; the 404 page shows only "Kvitt" and "404" (AC-2.5).

Card callback page (E-39, CP-2). Server-rendered HTML in the language of `Accept-Language` (Swedish when it prefers `sv`, English otherwise), so these strings live in the server (K1's `src/cards/callback.rs`), not in the app's resources. It shows the app name, one heading, one sentence and one link; no amount, merchant, card name or any other personal data:

| Element | English | Swedish |
|---|---|---|
| App name | Kvitt | Kvitt |
| Heading, success | Card connected | Kortet är anslutet |
| Sentence, success | Your card purchases are being fetched. Go back to Kvitt to see them. | Dina kortköp hämtas nu. Gå tillbaka till Kvitt för att se dem. |
| Heading, failure | The card could not be connected | Det gick inte att ansluta kortet |
| Sentence, failure | Go back to Kvitt and try again. | Gå tillbaka till Kvitt och försök igen. |
| Link | Back to Kvitt | Tillbaka till Kvitt |

The link is `kvitt://cards/connected?attempt=<attempt id>` for an attempt started by the app and `/app/cards?attempt=<attempt id>` for one started by the web client; for an unknown, used or expired `state` the failure page has no link (the user closes the tab; the client's own screen shows the failure or the timeout from E-38). The page is sent with `Cache-Control: no-store` and `Referrer-Policy: no-referrer`; the attempt id is not a secret (it only names the attempt to its own user's devices, E-38).

Card purchase strings (K2 adds them to `docs/ux/strings.csv` with these keys; the web uses the same keys, §15.3). Keys of `:feature:cards` start with `cards_`; `nav_cards` is `:core:design`'s, `settings_cards*` `:feature:settings`'s, `account_from_card_purchases` `:feature:account`'s, `expense_detail_from_card` and `expense_detail_unlink_card` `:feature:expense`'s (§6.2, D-017). Existing keys are reused where the text is the same (`common_needs_connection`, `common_retry`, `common_undo`, `common_cancel`, `common_could_not_reach_server`, the §9.8 relative times). Plurals as `key:one` / `key:other`. TalkBack labels and any key not listed are K2's, recorded in its report.

| Key | English | Swedish |
|---|---|---|
| `nav_cards` | Card purchases | Kortköp |
| `settings_cards` | Connect card | Anslut kort |
| `settings_cards_connected` | Connected · valid until %1$s | Ansluten · giltig till %1$s |
| `settings_cards_none` | Read your card purchases | Läs in dina kortköp |
| `account_from_card_purchases` | From card purchases | Från kortköp |
| `expense_detail_from_card` | From card purchase: %1$s, %2$s | Från kortköp: %1$s, %2$s |
| `expense_detail_unlink_card` | Remove link | Ta bort koppling |
| `cards_title` | Card purchases | Kortköp |
| `cards_private_note` | Only you see your card purchases | Bara du ser dina kortköp |
| `cards_updated` | Updated %1$s | Uppdaterad %1$s |
| `cards_refresh` | Refresh | Uppdatera |
| `cards_refreshing` | Refreshing… | Uppdaterar… |
| `cards_filter_to_handle` | To handle | Att hantera |
| `cards_filter_linked` | Linked | Kopplade |
| `cards_filter_ignored` | Ignored | Ignorerade |
| `cards_filter_all` | All | Alla |
| `cards_pending` | Pending | Preliminär |
| `cards_booked` | Booked | Bokförd |
| `cards_credit` | Deposit | Insättning |
| `cards_foreign` | Foreign currency | Utländsk valuta |
| `cards_match_one` | Link to %1$s | Koppla till %1$s |
| `cards_match_many:one` | %1$d possible expense | %1$d möjlig utgift |
| `cards_match_many:other` | %1$d possible expenses | %1$d möjliga utgifter |
| `cards_linked_to` | Linked to %1$s · %2$s | Kopplad till %1$s · %2$s |
| `cards_empty_title` | Connect your card | Anslut ditt kort |
| `cards_empty_body` | See your purchases here and turn them into expenses in a few taps. Only you see them. | Se dina köp här och gör om dem till utgifter med några tryck. Bara du ser dem. |
| `cards_connect` | Connect card | Anslut kort |
| `cards_first_fetch` | Fetching your purchases… | Hämtar dina köp… |
| `cards_nothing_to_handle` | Nothing to handle | Inget att hantera |
| `cards_nothing_to_handle_body` | New card purchases show up here. | Nya kortköp visas här. |
| `cards_filter_empty` | No purchases here | Inga köp här |
| `cards_expiring` | Your card connection ends on %1$s | Kortanslutningen upphör %1$s |
| `cards_expired` | Your card connection has ended | Kortanslutningen har upphört |
| `cards_renew` | Renew with BankID | Förnya med BankID |
| `cards_fetch_failed` | Could not fetch purchases. Last updated %1$s | Kunde inte hämta köp. Senast uppdaterad %1$s |
| `cards_sheet_create` | Create expense | Skapa utgift |
| `cards_sheet_matches` | Link to an existing expense | Koppla till befintlig utgift |
| `cards_sheet_no_matches` | No expense with the same amount around this date | Ingen utgift med samma belopp runt det här datumet |
| `cards_sheet_other` | Choose another expense | Välj en annan utgift |
| `cards_sheet_ignore` | Ignore | Ignorera |
| `cards_sheet_unignore` | Stop ignoring | Sluta ignorera |
| `cards_sheet_unlink` | Remove link | Ta bort koppling |
| `cards_sheet_open_expense` | Open expense | Öppna utgift |
| `cards_sheet_credit_note` | Deposits and refunds are not expenses. Change the original expense by hand if needed. | Insättningar och återbetalningar är inga utgifter. Ändra den ursprungliga utgiften för hand vid behov. |
| `cards_sheet_foreign_note` | The amount is in %1$s: type the amount in kronor. | Beloppet är i %1$s: skriv beloppet i kronor. |
| `cards_snackbar_linked` | Linked | Kopplad |
| `cards_snackbar_ignored` | Ignored | Ignorerad |
| `cards_connect_title` | Connect card | Anslut kort |
| `cards_connect_intro` | Choose your card. Kvitt reads your purchases but can never pay or move money. | Välj ditt kort. Kvitt läser dina köp men kan aldrig betala eller flytta pengar. |
| `cards_provider_connected` | Connected · valid until %1$s | Ansluten · giltig till %1$s |
| `cards_provider_unavailable` | Not set up on the server | Inte konfigurerat på servern |
| `cards_history_label` | Fetch purchases from the last | Hämta köp från de senaste |
| `cards_history_days:one` | %1$d day | %1$d dag |
| `cards_history_days:other` | %1$d days | %1$d dagar |
| `cards_history_note` | You can shorten this later. A longer period needs BankID again. | Du kan korta perioden senare. En längre period kräver BankID igen. |
| `cards_connect_bankid` | Connect with BankID | Anslut med BankID |
| `cards_waiting` | Waiting for BankID… | Väntar på BankID… |
| `cards_waiting_body` | Finish in the browser and in BankID, then come back here. | Slutför i webbläsaren och i BankID och kom sedan tillbaka hit. |
| `cards_connected` | Card connected | Kortet är anslutet |
| `cards_connect_failed` | The card could not be connected | Det gick inte att ansluta kortet |
| `cards_connect_timeout` | The connection attempt took too long | Anslutningsförsöket tog för lång tid |
| `cards_status_active` | Connected | Ansluten |
| `cards_status_expired` | Ended | Har upphört |
| `cards_valid_until` | Valid until %1$s | Giltig till %1$s |
| `cards_last_updated` | Last updated %1$s | Senast uppdaterad %1$s |
| `cards_history_setting` | History when connecting | Historik vid anslutning |
| `cards_history_longer_note` | A longer period needs BankID again | En längre period kräver BankID igen |
| `cards_disconnect` | Disconnect | Koppla från |
| `cards_disconnect_title` | Disconnect %1$s? | Koppla från %1$s? |
| `cards_disconnect_body` | Purchases you have not linked or ignored are deleted. Expenses you created stay. | Köp som du inte har kopplat eller ignorerat raderas. Utgifter du har skapat finns kvar. |
| `cards_disconnect_erase_all` | Also delete linked and ignored purchases | Radera även kopplade och ignorerade köp |
| `cards_pick_title` | From card purchases | Från kortköp |
| `cards_pick_empty` | No card purchases to handle | Inga kortköp att hantera |

K2 added these keys to `docs/ux/strings.csv` (`a8f91ee`, 77 rows with `nav_cards` and the plural forms) and four more of its own (D-200): `cards_foreign_amount` ("%1$s %2$s", the bank's decimal amount and the currency, a decimal comma in Swedish), `cards_connection_settings` (TalkBack click label of S-23's header card: "Card connection" / "Kortanslutning"), `cards_connect_offline_body` (S-24's offline banner: "The list of cards comes from the server. Connect the phone to the internet." / "Listan över kort hämtas från servern. Anslut telefonen till internet.") and `settings_cards_expired` (S-13's subtitle of an expired connection: "Ended" / "Har upphört", D-199). Every card key is in both `strings.xml` files of its module.

### 13.4 Deliverables

**Phase 1 (U1): directions.** In `docs/ux/directions/`:

* 2 or 3 visual directions, each a self-contained HTML file `docs/ux/directions/<n>-<slug>/index.html` (no external requests except Google Fonts, if a direction uses a font whose licence allows bundling in an app; the font must then also be bundleable as an Android font resource) rendering at a 411 dp wide phone frame: S-4 Home, S-7 Expense editor, S-5 Account detail, S-9 Settle up, S-11 Analytics, S-8 Expense detail with timeline, each in light and dark, in Swedish, with realistic household data (names "Jacob" and "Anna", Swedish shops and amounts; no lorem ipsum).
* Each direction states: name and one-line idea; colour palette (primary, secondary, tertiary, surfaces, error, "owed" and "owing" semantic colours, the 12 category colours) in light and dark with contrast ratios; typography (Material 3 type scale and why; tabular figures for amounts; the app bundles no font and uses the Material 3 default typeface, D-020, so a direction that previews another typeface has it replaced by the default in U2's design spec); shape (corner radii per component size); elevation and motion principles; iconography (Material Symbols style: outlined, rounded or sharp, weight, fill rules); how the balance header looks in its three states; how it handles 200 % font scale (one screenshot).
* `docs/ux/directions/README.md`: a comparison table of the directions (character, strengths, risks, implementation cost in Compose), and the UX agent's recommendation with reasons.
* PNG exports of every screen of every direction (`docs/ux/directions/<n>-<slug>/png/`), so the orchestrator can show them to the owner without a browser.

Suggested starting points the UX agent may use, replace or merge (it must deliver at least two clearly different ones):

1. **"Kvitto"**: receipt-paper calm. Off-white surfaces, ink-black text, one accent colour, monospaced tabular amounts, dashed dividers like a till receipt. Expressive only in motion.
2. **"Skärgård"**: Material 3 Expressive with a cool sea-and-granite palette, large rounded shapes, bold balance header, playful but quiet.
3. **"Kontor"**: dense, utilitarian, data-forward. Neutral greys, strong typographic hierarchy, charts as the hero on Analytics, minimal decoration.

**Phase 2 (U2): design spec for the chosen direction.** After the owner picks (and comments), in `docs/ux/`. The owner picked direction 3 "Kalas" with the muted palette of `docs/ux/directions/3-kalas/`, typeface per D-020 (D-047). U2 landed `6da6b1b`, approved by the owner. `docs/ux/design-spec.md` is the binding design document for `:core:design` (§2 tokens, §3 components) and for every screen (§4, §5); this spec wins over it on rules. Amended after U2: chart bars have top corners 4 dp and bottom corners 2 dp (D-097, design-spec §2.9 and §3.10); S-7's account, date, payer and split options are four fixed rows, `EditorOptionRows`, and connected buttons have 8 dp side padding (D-102, design-spec §3.7 and §3.10); S-22 has no licences row (D-099, design-spec S-22); S-16's lost version (D-109) and S-22's "(schema <n>)" (D-110), design-spec S-16 and S-22; S-11's Insights section (D-142, D-143), design-spec S-11 and §3.10; the mock-up PNGs are compressed losslessly (D-098). `docs/ux/strings.csv` (558 rows at U2, header included; 559 since v0.10 with `ledger_settlement_label`, D-068, and English "Dining" for `category_default_restaurants`, D-067; 578 since v0.11 with the shared keys `common_ok`, `common_undo` and `editor_split_full_on_you` and the module keys of M7b to M7f recorded as built, D-079; 577 since v0.16 without `settings_about_licences`, D-099; 562 since v0.18: M12f added `home_sync_lost_title`, `home_sync_lost_body`, `home_sync_lost_deleted`, `home_sync_lost_show_current` (D-109) and `settings_about_server_version_schema` (D-110) and removed the 19 keys (20 rows) that R8 found unused (`a0259ab`); 569 since v0.27 with the seven S-12 line-chart keys `analytics_average`, `analytics_moving_average`, `analytics_vs_average_above`, `analytics_vs_average_below`, `analytics_vs_average_on`, `analytics_summary_line`, `analytics_summary_line_single` (D-128); 588 since v0.31 with the 16 S-11 Insights keys `analytics_insights_*`, three of them plurals (19 rows, D-142, D-143); keys with the D-017 prefixes; plurals as `key:one` / `key:other`) is the source of every string resource:

* `design-spec.md`: final tokens (colour roles light and dark, category colour hex values, typography scale, shapes, spacing scale in dp, elevation, motion durations and easing), component inventory (each with anatomy, states, sizes), and for every screen S-1 to S-22: layout description, all states of §13.3, interaction details, TalkBack labels.
* `strings.csv`: every user-visible string of the app with columns `key,en,sv,notes`, keys in `snake_case` prefixed by the feature module that holds them (`home_balance_owes_you`, `expense_save`; shared strings for `:core:design` never start with a feature name; the app name is the only `:app` string; §6.2, D-017), placeholders as Android format arguments (`%1$s`), plurals marked in `notes` with their quantities. This becomes `values/strings.xml` and `values-sv/strings.xml` in M6 and M7; feature agents add no strings that are not in this file without a decisions entry. Keys recorded by D-079 (v0.11): shared `common_ok`, `common_undo`, `editor_split_full_on_you` ("All on you" / "Allt på dig"; `ledger_settlement_label` was D-068); module keys as built: `analytics_granularity`, `analytics_measure`, `analytics_group_by`, `analytics_range_apply`; `settle_row_amount`, `settle_detail_delete`, `settle_detail_sync_now`; `expense_detail_sync_now`; `home_archived_expanded`, `home_archived_collapsed`; `settings_category_archived_snackbar`, `settings_category_unarchived_snackbar`, `settings_recurring_summary_none`, `settings_expanded`, `settings_collapsed`, `settings_partner_missing`.
* `screens/<S-id>-<slug>.png` for every screen and state, light and dark, Swedish.
* Updated colour hex values for the 14 tokens of §9.7 (the muted Kalas values, `slate` and `amber` included), proposed as a spec change (decisions entry, spec version bump) by the orchestrator (D-051).

### 13.5 Out of scope for the UX sprint

New features, changes to flows required by §4, changes to enums or limits, app icon production (a direction may sketch one), animations beyond descriptions, Kotlin code.

---

## 14. Contracts

Contracts are what lets agents work in parallel. Each subsection is binding. The files that M1 writes from this section are listed in §14.8. A change to any contract follows §14.8.

### 14.1 SQLite schema v1 (server) and migrations

The server schema is at version **4**: the v1 DDL below (migration 0001) plus migration 0002 (§14.1.1, D-054), migration 0003 (§14.1.2, D-090) and migration 0004 (§14.1.3, D-167). This DDL is the content of `contracts/schema/server-v1.sql` and of the server's first migration `server/crates/kvitt-server/migrations/0001_init.sql`, byte for byte (a test asserts equality). Conventions: ids `TEXT` (UUIDv7, see the conventions at the top of this file); money `INTEGER` öre; timestamps `TEXT` in the fixed RFC 3339 form; booleans `INTEGER` 0/1; `server_version` from `sync_sequence`. Enum and token lists that may grow (icons, colours) are checked in code, not in DDL. Every connection sets the pragmas of §8.9.

```sql
-- Kvitt server schema v1. Do not edit; add a new migration and bump the schema version (SPEC §14.8).

CREATE TABLE meta (
    key   TEXT PRIMARY KEY NOT NULL,
    value TEXT NOT NULL
) STRICT;

-- One global, strictly increasing counter for server_version. Exactly one row.
CREATE TABLE sync_sequence (
    id    INTEGER PRIMARY KEY CHECK (id = 1),
    value INTEGER NOT NULL
) STRICT;

CREATE TABLE users (
    id              TEXT PRIMARY KEY NOT NULL,
    role            TEXT NOT NULL CHECK (role IN ('admin', 'member')),
    display_name    TEXT NOT NULL CHECK (length(display_name) BETWEEN 1 AND 40),
    picture_version INTEGER CHECK (picture_version IS NULL OR picture_version >= 1),
    created_at      TEXT NOT NULL,
    updated_at      TEXT NOT NULL,
    server_version  INTEGER NOT NULL UNIQUE
) STRICT;
CREATE UNIQUE INDEX users_single_admin ON users (role) WHERE role = 'admin';

CREATE TABLE devices (
    id                 TEXT PRIMARY KEY NOT NULL,
    user_id            TEXT NOT NULL REFERENCES users (id),
    name               TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 60),
    token_hash         TEXT NOT NULL UNIQUE,
    fcm_token          TEXT,
    app_version_code   INTEGER,
    created_at         TEXT NOT NULL,
    last_seen_at       TEXT NOT NULL,
    revoked_at         TEXT,
    revoked_by_user_id TEXT REFERENCES users (id)
) STRICT;
CREATE INDEX devices_user ON devices (user_id);

CREATE TABLE invites (
    id                 TEXT PRIMARY KEY NOT NULL,
    kind               TEXT NOT NULL CHECK (kind IN ('admin_setup', 'partner', 'device')),
    code_hash          TEXT NOT NULL UNIQUE,
    target_user_id     TEXT REFERENCES users (id),
    created_by_user_id TEXT REFERENCES users (id),
    created_at         TEXT NOT NULL,
    expires_at         TEXT NOT NULL,
    accepted_at        TEXT,
    accepted_device_id TEXT REFERENCES devices (id),
    cancelled_at       TEXT,
    CHECK ((kind = 'device') = (target_user_id IS NOT NULL)),
    CHECK ((kind = 'admin_setup') = (created_by_user_id IS NULL) OR kind = 'device')
) STRICT;

CREATE TABLE accounts (
    id                 TEXT PRIMARY KEY NOT NULL,
    name               TEXT NOT NULL CHECK (length(name) BETWEEN 1 AND 60),
    name_key           TEXT NOT NULL,
    created_by_user_id TEXT NOT NULL REFERENCES users (id),
    created_at         TEXT NOT NULL,
    updated_at         TEXT NOT NULL,
    archived_at        TEXT,
    deleted_at         TEXT,
    server_version     INTEGER NOT NULL UNIQUE
) STRICT;
-- name_key = Unicode-lowercased, trimmed name, computed in Rust.
CREATE UNIQUE INDEX accounts_name_live ON accounts (name_key) WHERE deleted_at IS NULL;

CREATE TABLE account_default_shares (
    account_id TEXT NOT NULL REFERENCES accounts (id),
    user_id    TEXT NOT NULL REFERENCES users (id),
    share_bp   INTEGER NOT NULL CHECK (share_bp BETWEEN 0 AND 10000),
    PRIMARY KEY (account_id, user_id)
) STRICT, WITHOUT ROWID;

CREATE TABLE categories (
    id             TEXT PRIMARY KEY NOT NULL,
    default_key    TEXT UNIQUE CHECK (default_key IS NULL OR default_key IN
                       ('groceries', 'restaurants', 'home', 'utilities', 'transport',
                        'travel', 'entertainment', 'health', 'shopping', 'other')),
    name           TEXT CHECK (name IS NULL OR length(name) BETWEEN 1 AND 40),
    icon           TEXT NOT NULL,
    color          TEXT NOT NULL,
    sort_order     INTEGER NOT NULL,
    created_at     TEXT NOT NULL,
    updated_at     TEXT NOT NULL,
    archived_at    TEXT,
    deleted_at     TEXT,
    server_version INTEGER NOT NULL UNIQUE,
    CHECK (name IS NOT NULL OR default_key IS NOT NULL)
) STRICT;

CREATE TABLE recurring_templates (
    id                    TEXT PRIMARY KEY NOT NULL,
    account_id            TEXT NOT NULL REFERENCES accounts (id),
    category_id           TEXT NOT NULL REFERENCES categories (id),
    amount_ore            INTEGER NOT NULL CHECK (amount_ore BETWEEN 1 AND 1000000000),
    description           TEXT NOT NULL CHECK (length(description) BETWEEN 1 AND 100),
    notes                 TEXT NOT NULL DEFAULT '' CHECK (length(notes) <= 1000),
    payer_user_id         TEXT NOT NULL REFERENCES users (id),
    split_mode            TEXT NOT NULL CHECK (split_mode IN ('default', 'ratio', 'exact', 'full')),
    day_of_month          INTEGER NOT NULL CHECK (day_of_month BETWEEN 1 AND 31),
    start_period          TEXT NOT NULL,
    end_period            TEXT,
    paused                INTEGER NOT NULL DEFAULT 0 CHECK (paused IN (0, 1)),
    last_generated_period TEXT,
    created_by_user_id    TEXT NOT NULL REFERENCES users (id),
    updated_by_user_id    TEXT NOT NULL REFERENCES users (id),
    created_at            TEXT NOT NULL,
    updated_at            TEXT NOT NULL,
    deleted_at            TEXT,
    server_version        INTEGER NOT NULL UNIQUE
) STRICT;
CREATE INDEX recurring_templates_account ON recurring_templates (account_id);

-- Modes ratio and full: share_bp set, share_ore NULL. Mode exact: share_ore set, share_bp NULL. Mode default: no rows.
CREATE TABLE recurring_template_splits (
    template_id TEXT NOT NULL REFERENCES recurring_templates (id),
    user_id     TEXT NOT NULL REFERENCES users (id),
    share_bp    INTEGER CHECK (share_bp IS NULL OR share_bp BETWEEN 0 AND 10000),
    share_ore   INTEGER CHECK (share_ore IS NULL OR share_ore >= 0),
    PRIMARY KEY (template_id, user_id),
    CHECK ((share_bp IS NULL) <> (share_ore IS NULL))
) STRICT, WITHOUT ROWID;

CREATE TABLE expenses (
    id                    TEXT PRIMARY KEY NOT NULL,
    account_id            TEXT NOT NULL REFERENCES accounts (id),
    category_id           TEXT NOT NULL REFERENCES categories (id),
    amount_ore            INTEGER NOT NULL CHECK (amount_ore BETWEEN 1 AND 1000000000),
    description           TEXT NOT NULL CHECK (length(description) BETWEEN 1 AND 100),
    notes                 TEXT NOT NULL DEFAULT '' CHECK (length(notes) <= 1000),
    expense_date          TEXT NOT NULL,
    payer_user_id         TEXT NOT NULL REFERENCES users (id),
    split_mode            TEXT NOT NULL CHECK (split_mode IN ('default', 'ratio', 'exact', 'full')),
    recurring_template_id TEXT REFERENCES recurring_templates (id),
    recurring_period      TEXT,
    import_key            TEXT UNIQUE,
    created_by_user_id    TEXT NOT NULL REFERENCES users (id),
    updated_by_user_id    TEXT NOT NULL REFERENCES users (id),
    updated_by_device_id  TEXT REFERENCES devices (id),
    created_at            TEXT NOT NULL,
    updated_at            TEXT NOT NULL,
    deleted_at            TEXT,
    server_received_at    TEXT NOT NULL,
    server_version        INTEGER NOT NULL UNIQUE,
    CHECK ((recurring_template_id IS NULL) = (recurring_period IS NULL))
) STRICT;
CREATE UNIQUE INDEX expenses_recurring_once ON expenses (recurring_template_id, recurring_period)
    WHERE recurring_template_id IS NOT NULL;
CREATE INDEX expenses_account ON expenses (account_id);
CREATE INDEX expenses_category ON expenses (category_id);

-- Exactly two rows per expense, one per household user. share_bp NULL for mode exact.
CREATE TABLE expense_splits (
    expense_id TEXT NOT NULL REFERENCES expenses (id),
    user_id    TEXT NOT NULL REFERENCES users (id),
    share_ore  INTEGER NOT NULL CHECK (share_ore >= 0),
    share_bp   INTEGER CHECK (share_bp IS NULL OR share_bp BETWEEN 0 AND 10000),
    PRIMARY KEY (expense_id, user_id)
) STRICT, WITHOUT ROWID;

CREATE TABLE settlements (
    id                   TEXT PRIMARY KEY NOT NULL,
    from_user_id         TEXT NOT NULL REFERENCES users (id),
    to_user_id           TEXT NOT NULL REFERENCES users (id),
    amount_ore           INTEGER NOT NULL CHECK (amount_ore BETWEEN 1 AND 1000000000),
    settlement_date      TEXT NOT NULL,
    note                 TEXT NOT NULL DEFAULT '' CHECK (length(note) <= 200),
    import_key           TEXT UNIQUE,
    created_by_user_id   TEXT NOT NULL REFERENCES users (id),
    updated_by_user_id   TEXT NOT NULL REFERENCES users (id),
    updated_by_device_id TEXT REFERENCES devices (id),
    created_at           TEXT NOT NULL,
    updated_at           TEXT NOT NULL,
    deleted_at           TEXT,
    server_received_at   TEXT NOT NULL,
    server_version       INTEGER NOT NULL UNIQUE,
    CHECK (from_user_id <> to_user_id)
) STRICT;

CREATE TABLE settlement_allocations (
    settlement_id TEXT NOT NULL REFERENCES settlements (id),
    account_id    TEXT NOT NULL REFERENCES accounts (id),
    amount_ore    INTEGER NOT NULL CHECK (amount_ore >= 1),
    PRIMARY KEY (settlement_id, account_id)
) STRICT, WITHOUT ROWID;
CREATE INDEX settlement_allocations_account ON settlement_allocations (account_id);

-- Append-only. changes is a JSON array of {"field","old","new"} (SPEC §14.4.7).
CREATE TABLE audit_log (
    id              TEXT PRIMARY KEY NOT NULL,
    entity_type     TEXT NOT NULL CHECK (entity_type IN ('expense', 'settlement')),
    entity_id       TEXT NOT NULL,
    action          TEXT NOT NULL CHECK (action IN ('create', 'update', 'delete')),
    source          TEXT NOT NULL CHECK (source IN ('app', 'recurring', 'import')),
    actor_user_id   TEXT NOT NULL REFERENCES users (id),
    actor_device_id TEXT REFERENCES devices (id),
    client_at       TEXT NOT NULL,
    server_at       TEXT NOT NULL,
    changes         TEXT NOT NULL,
    server_version  INTEGER NOT NULL UNIQUE
) STRICT;
CREATE INDEX audit_log_entity ON audit_log (entity_type, entity_id);

-- Idempotency of POST /sync. Rows older than 90 days are pruned daily.
CREATE TABLE sync_mutations (
    mutation_id TEXT PRIMARY KEY NOT NULL,
    device_id   TEXT NOT NULL REFERENCES devices (id),
    entity_type TEXT NOT NULL CHECK (entity_type IN ('expense', 'settlement')),
    entity_id   TEXT NOT NULL,
    result      TEXT NOT NULL,
    received_at TEXT NOT NULL
) STRICT;
CREATE INDEX sync_mutations_received ON sync_mutations (received_at);

INSERT INTO sync_sequence (id, value) VALUES (1, 10);
INSERT INTO meta (key, value) VALUES ('schema_version', '1');
INSERT INTO meta (key, value) VALUES ('sync_epoch', lower(hex(randomblob(16))));

INSERT INTO categories (id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version) VALUES
    ('01920000-0000-7000-8000-000000000001', 'groceries',     NULL, 'shopping_cart',    'green',  10,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 1),
    ('01920000-0000-7000-8000-000000000002', 'restaurants',   NULL, 'restaurant',       'orange', 20,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 2),
    ('01920000-0000-7000-8000-000000000003', 'home',          NULL, 'home',             'brown',  30,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 3),
    ('01920000-0000-7000-8000-000000000004', 'utilities',     NULL, 'bolt',             'yellow', 40,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 4),
    ('01920000-0000-7000-8000-000000000005', 'transport',     NULL, 'directions_car',   'blue',   50,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 5),
    ('01920000-0000-7000-8000-000000000006', 'travel',        NULL, 'flight',           'teal',   60,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 6),
    ('01920000-0000-7000-8000-000000000007', 'entertainment', NULL, 'movie',            'purple', 70,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 7),
    ('01920000-0000-7000-8000-000000000008', 'health',        NULL, 'medical_services', 'red',    80,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 8),
    ('01920000-0000-7000-8000-000000000009', 'shopping',      NULL, 'shopping_bag',     'pink',   90,  '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 9),
    ('01920000-0000-7000-8000-00000000000a', 'other',         NULL, 'category',         'grey',   100, '2026-10-17T00:00:00.000Z', '2026-10-17T00:00:00.000Z', NULL, NULL, 10);
```

Server-side rules on top of the DDL:

* Every write transaction starts with `BEGIN IMMEDIATE`. Taking a `server_version` is `UPDATE sync_sequence SET value = value + 1 WHERE id = 1 RETURNING value` inside that transaction.
* At most two rows in `users` (checked in code; `household_full`).
* `meta.sync_epoch` is replaced by `kvitt-server rotate-epoch` with a new `lower(hex(randomblob(16)))`.
* No row of `users`, `devices`, `accounts`, `categories`, `recurring_templates`, `expenses`, `settlements` or `audit_log` is ever hard-deleted. Child rows (`account_default_shares`, `recurring_template_splits`, `expense_splits`, `settlement_allocations`) are replaced (delete and insert) when their parent is updated.
* Card rows (§14.1.3): `card_connections` are never deleted; `card_purchases` become content-erased tombstones (D-167); `card_auth_attempts` are pruned 7 days after creation by the same 04:00 job.
* `invites` rows are never deleted; `sync_mutations` rows are pruned after 90 days by a daily job at 04:00 Europe/Stockholm (DST-aware, always local 04:00) that deletes rows whose `received_at` is strictly older than 90 days; a row exactly 90 days old is kept (D-021, D-039).

#### 14.1.1 Migration 0002: schema version 2 (D-054)

Migration 0002 adds the four default categories `housing`, `insurance`, `children` and `fees` of AC-7.2 to every database, existing ones (the development stack included) on upgrade and new ones right after 0001. The SQL below is the content of the contract file `contracts/schema/migrations/0002_categories_v2.sql` as M12a committed it (`aa765bb`; the file wins over this copy) and of the server migration `server/crates/kvitt-server/migrations/0002_categories_v2.sql`, byte for byte (a test asserts equality, as for 0001); `contracts/schema/server-v1.sql` stays unchanged. Every later migration follows the same pattern: `contracts/schema/migrations/<NNNN>_<name>.sql` is its locked text.

* The v1 `CHECK` on `categories.default_key` lists ten keys and SQLite cannot alter a `CHECK`, so the migration rebuilds `categories` with the fourteen keys (the ten of v1 followed by the four new ones) and otherwise the same columns and constraints, keeping every row unchanged (custom categories, renames, archive state, `server_version`).
* sqlx runs the migration in one transaction on a connection with `foreign_keys = ON` (§8.9), where `PRAGMA foreign_keys` cannot change. `PRAGMA defer_foreign_keys = ON` defers the checks to the commit; the rows are copied out, the table dropped and recreated under its own name, and the rows copied back, so every reference from `expenses` and `recurring_templates` resolves again before the commit.
* Each new row takes its `server_version` from the global sequence (§14.1 rules), so phones receive the four rows in their next pull like any other change. Ids `01920000-0000-7000-8000-000000000011` to `…014`, `created_at` = `updated_at` = `2026-10-18T00:00:00.000Z`, `name` null.
* `meta.schema_version` becomes `2`; the server's `SCHEMA_VERSION` constant (E-1) becomes 2, and the importer's check (§10.8), which reads that constant, follows.
* The Room schema is unchanged (version 1): category rows reach the phone through sync (§14.2).

```sql
-- Kvitt server schema v2: four new default categories (housing, insurance, children, fees). Do not edit; add a new
-- migration and bump the schema version (SPEC §14.8). Applied on top of server-v1.sql (0001_init.sql).
--
-- The default_key CHECK of categories cannot be altered in place in SQLite, so the table is rebuilt: copy the rows
-- aside, drop the table, recreate it with the new CHECK and copy the rows back, ids and server_version unchanged.
-- The migration runs inside one transaction (sqlx wraps every migration in one) with foreign_keys = ON (SPEC §8.9).
-- defer_foreign_keys = ON lets expenses and recurring_templates point at categories while the table is briefly
-- absent; the deferred check at commit still fails the migration if any reference is left dangling. It resets
-- itself when the transaction ends. No other table, index or trigger refers to categories by anything but name.
PRAGMA defer_foreign_keys = ON;

CREATE TABLE categories_v1_copy AS SELECT * FROM categories;
DROP TABLE categories;

CREATE TABLE categories (
    id             TEXT PRIMARY KEY NOT NULL,
    default_key    TEXT UNIQUE CHECK (default_key IS NULL OR default_key IN
                       ('groceries', 'restaurants', 'home', 'utilities', 'transport',
                        'travel', 'entertainment', 'health', 'shopping', 'other',
                        'housing', 'insurance', 'children', 'fees')),
    name           TEXT CHECK (name IS NULL OR length(name) BETWEEN 1 AND 40),
    icon           TEXT NOT NULL,
    color          TEXT NOT NULL,
    sort_order     INTEGER NOT NULL,
    created_at     TEXT NOT NULL,
    updated_at     TEXT NOT NULL,
    archived_at    TEXT,
    deleted_at     TEXT,
    server_version INTEGER NOT NULL UNIQUE,
    CHECK (name IS NOT NULL OR default_key IS NOT NULL)
) STRICT;

INSERT INTO categories (id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version)
    SELECT id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version
    FROM categories_v1_copy;
DROP TABLE categories_v1_copy;

-- Each new row takes the next server_version from the global sequence, as every server write does (SPEC §14.1), so
-- phones receive the rows on their next pull whatever their cursor.
UPDATE sync_sequence SET value = value + 1 WHERE id = 1;
INSERT INTO categories (id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version)
    SELECT '01920000-0000-7000-8000-000000000011', 'housing', NULL, 'key', 'indigo', 25,
           '2026-10-18T00:00:00.000Z', '2026-10-18T00:00:00.000Z', NULL, NULL, value
    FROM sync_sequence WHERE id = 1;

UPDATE sync_sequence SET value = value + 1 WHERE id = 1;
INSERT INTO categories (id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version)
    SELECT '01920000-0000-7000-8000-000000000012', 'insurance', NULL, 'shield', 'slate', 45,
           '2026-10-18T00:00:00.000Z', '2026-10-18T00:00:00.000Z', NULL, NULL, value
    FROM sync_sequence WHERE id = 1;

UPDATE sync_sequence SET value = value + 1 WHERE id = 1;
INSERT INTO categories (id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version)
    SELECT '01920000-0000-7000-8000-000000000013', 'children', NULL, 'child_care', 'lime', 85,
           '2026-10-18T00:00:00.000Z', '2026-10-18T00:00:00.000Z', NULL, NULL, value
    FROM sync_sequence WHERE id = 1;

UPDATE sync_sequence SET value = value + 1 WHERE id = 1;
INSERT INTO categories (id, default_key, name, icon, color, sort_order, created_at, updated_at, archived_at, deleted_at, server_version)
    SELECT '01920000-0000-7000-8000-000000000014', 'fees', NULL, 'account_balance', 'amber', 95,
           '2026-10-18T00:00:00.000Z', '2026-10-18T00:00:00.000Z', NULL, NULL, value
    FROM sync_sequence WHERE id = 1;

UPDATE meta SET value = '2' WHERE key = 'schema_version';
```

#### 14.1.2 Migration 0003: schema version 3 (D-090)

Migration 0003 adds the column `devices.app_version_name` (the app's `versionName`, from the request header `X-Kvitt-App-Version-Name`, §14.3.1), written like `app_version_code` (§8.2). The SQL below is the content of the contract file `contracts/schema/migrations/0003_device_version_name.sql` as M12e committed it (`8c60715`; the file wins over this copy) and of the server migration `server/crates/kvitt-server/migrations/0003_device_version_name.sql`, byte for byte (a test asserts equality, as for 0001 and 0002).

* Existing devices keep every column and get `NULL` until their next request that carries the header (at most once per hour, §8.2); E-3 stores it at pairing.
* `meta.schema_version` becomes `3`; the server's `SCHEMA_VERSION` constant (E-1) becomes 3, and the importer's check (§10.8) follows. A migration test upgrades a v2 database in use to schema 3 and asserts that every row is kept.
* The Room schema is unchanged (version 1): the phone stores no devices (§14.2).

```sql
-- Kvitt server schema v3: the app's versionName per device (devices.app_version_name), sent in the
-- X-Kvitt-App-Version-Name header and written like app_version_code (SPEC §14.3.1, §8.2). Do not edit; add a new
-- migration and bump the schema version (SPEC §14.8). Applied on top of 0002_categories_v2.sql.
--
-- Existing devices keep every column and get NULL until their next request that carries the header.
ALTER TABLE devices ADD COLUMN app_version_name TEXT
    CHECK (app_version_name IS NULL OR length(app_version_name) BETWEEN 1 AND 32);

UPDATE meta SET value = '3' WHERE key = 'schema_version';
```

#### 14.1.3 Migration 0004: schema version 4 (D-167)

Migration 0004 adds the card-purchase tables of §9.12. The SQL below is the intended content of the contract file `contracts/schema/migrations/0004_card_purchases.sql`, which K1 commits (the file wins over this copy once committed; K1 may only make changes its report justifies, recorded by a docs agent), and of the server migration `server/crates/kvitt-server/migrations/0004_card_purchases.sql`, byte for byte (a test asserts equality, as for 0001 to 0003). K1 committed both files byte-identical to the copy below (`671c00d`, v0.38); server schema 4 is in code.

* No existing table changes: the household tables, `server_version` and `GET /sync` are untouched (card rows are not household rows, D-161). `card_version` comes from the new one-row `card_sequence`, taken like `server_version` (`UPDATE card_sequence SET value = value + 1 WHERE id = 1 RETURNING value`) inside the write's `BEGIN IMMEDIATE` transaction, so a card cursor never sees a gap that later fills (§6.4).
* Tombstones (D-167): a card purchase is never hard-deleted while the database lives; a deleted one keeps `id`, `user_id`, `connection_id` and its new `card_version`, gets `deleted_at`, and has its content erased (`provider_ref` `''`, `merchant` `''`, `amount_ore`, `original_amount`, `original_currency`, `booking_date` and `expense_id` null, `ignored` 0, `purchase_date` kept as `1970-01-01`), so a phone learns of the deletion and nothing of the purchase is left. Connections are never deleted; a disconnected one keeps only its id, user, provider, history and timestamps.
* `card_auth_attempts` rows are pruned 7 days after creation by the 04:00 job of §14.1 (they are not referenced by anything a client keeps).
* The validity rules of §9.6 and §9.12 are checked in code; the `CHECK`s below are a backstop, as for the household tables (enums that may grow, such as provider ids and history choices, are not listed in DDL).
* `meta.schema_version` becomes `4`; the server's `SCHEMA_VERSION` constant (E-1) becomes 4, and the importer's check (§10.8) follows. A migration test upgrades a v3 database in use (users, devices, accounts, expenses, audit entries) to schema 4 and asserts that every row is kept and that the new tables are empty except `card_sequence`.
* The Room schema becomes version 2 (§14.2.3): the phone mirrors its own user's card rows.

```sql
-- Kvitt server schema v4: card purchases (SPEC §9.12, FR-22, D-167). Do not edit; add a new migration and bump the
-- schema version (SPEC §14.8). Applied on top of 0003_device_version_name.sql.
--
-- Card data is private to the card holder (D-161): none of these rows is in the household sync stream (GET /sync), the
-- audit log or a push. Card rows carry card_version from their own sequence and are read through GET /cards/sync.

CREATE TABLE card_sequence (
    id    INTEGER PRIMARY KEY CHECK (id = 1),
    value INTEGER NOT NULL
) STRICT;
INSERT INTO card_sequence (id, value) VALUES (1, 0);

-- One connection per user and card provider. session_id is an Enable Banking session: a credential usable only with the
-- application's private key, which is never in the database or a backup (D-161). Erased when disconnected.
CREATE TABLE card_connections (
    id                 TEXT PRIMARY KEY NOT NULL,
    user_id            TEXT NOT NULL REFERENCES users (id),
    provider_id        TEXT NOT NULL CHECK (length(provider_id) BETWEEN 1 AND 64),
    status             TEXT NOT NULL CHECK (status IN ('active', 'expired', 'disconnected')),
    session_id         TEXT,
    account_uid        TEXT,
    valid_until        TEXT,
    history_days       INTEGER NOT NULL CHECK (history_days BETWEEN 1 AND 365),
    last_fetch_at      TEXT,
    last_fetch_error   TEXT,
    last_user_fetch_at TEXT,
    background_fetches TEXT NOT NULL DEFAULT '[]',
    created_at         TEXT NOT NULL,
    updated_at         TEXT NOT NULL,
    card_version       INTEGER NOT NULL UNIQUE,
    CHECK ((status = 'disconnected') = (session_id IS NULL))
) STRICT;
CREATE UNIQUE INDEX card_connections_user_provider ON card_connections (user_id, provider_id);

-- Single-use authorisation attempts (D-162); state is stored only as its SHA-256 hash. Pruned 7 days after creation.
CREATE TABLE card_auth_attempts (
    id            TEXT PRIMARY KEY NOT NULL,
    user_id       TEXT NOT NULL REFERENCES users (id),
    device_id     TEXT NOT NULL REFERENCES devices (id),
    provider_id   TEXT NOT NULL CHECK (length(provider_id) BETWEEN 1 AND 64),
    client        TEXT NOT NULL CHECK (client IN ('android', 'web')),
    state_hash    TEXT NOT NULL UNIQUE,
    history_days  INTEGER NOT NULL CHECK (history_days BETWEEN 1 AND 365),
    status        TEXT NOT NULL CHECK (status IN ('pending', 'connected', 'failed', 'expired')),
    failure       TEXT,
    connection_id TEXT REFERENCES card_connections (id),
    created_at    TEXT NOT NULL,
    expires_at    TEXT NOT NULL,
    finished_at   TEXT
) STRICT;
CREATE INDEX card_auth_attempts_created ON card_auth_attempts (created_at);

-- Purchases as the bank reports them, mapped per SPEC §9.12 CP-7. amount_ore is null only for a non-SEK purchase
-- (original_amount and original_currency then set) and for a tombstone. A tombstone has its content erased (D-167).
CREATE TABLE card_purchases (
    id                TEXT PRIMARY KEY NOT NULL,
    user_id           TEXT NOT NULL REFERENCES users (id),
    connection_id     TEXT NOT NULL REFERENCES card_connections (id),
    provider_ref      TEXT NOT NULL,
    status            TEXT NOT NULL CHECK (status IN ('pending', 'booked')),
    direction         TEXT NOT NULL CHECK (direction IN ('debit', 'credit')),
    purchase_date     TEXT NOT NULL,
    booking_date      TEXT,
    amount_ore        INTEGER CHECK (amount_ore IS NULL OR amount_ore >= 1),
    original_amount   TEXT,
    original_currency TEXT CHECK (original_currency IS NULL OR length(original_currency) = 3),
    merchant          TEXT NOT NULL CHECK (length(merchant) <= 140),
    expense_id        TEXT REFERENCES expenses (id),
    ignored           INTEGER NOT NULL DEFAULT 0 CHECK (ignored IN (0, 1)),
    created_at        TEXT NOT NULL,
    updated_at        TEXT NOT NULL,
    deleted_at        TEXT,
    card_version      INTEGER NOT NULL UNIQUE,
    CHECK (NOT (ignored = 1 AND expense_id IS NOT NULL)),
    CHECK (deleted_at IS NOT NULL OR (amount_ore IS NULL) = (original_currency IS NOT NULL))
) STRICT;
CREATE UNIQUE INDEX card_purchases_ref ON card_purchases (connection_id, provider_ref) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX card_purchases_expense_once ON card_purchases (user_id, expense_id)
    WHERE expense_id IS NOT NULL AND deleted_at IS NULL;
CREATE INDEX card_purchases_user_version ON card_purchases (user_id, card_version);
CREATE INDEX card_purchases_expense ON card_purchases (expense_id);

UPDATE meta SET value = '4' WHERE key = 'schema_version';
```

### 14.2 Room entities (phone)

Database class `KvittDatabase` in `:data`, file name `kvitt.db`, version **2** (version 1 until D-173, v0.35), `exportSchema = true` with schemas in `android/data/schemas/` (committed). Package `se.hagstedt.kvitt.data.db`. Room 3 (`androidx.room3`, KSP only) on an `SQLiteDriver` with `sqlite-bundled` (D-012). M2b created the entities and `KvittDatabase` version 1; the exported `android/data/schemas/se.hagstedt.kvitt.data.db.KvittDatabase/1.json` is a contract file (§14.8).

Rules:

* Table and column names are identical to the server's (§14.1) where the column exists on both. Kotlin properties are camelCase with `@ColumnInfo(name = "snake_case")`.
* **No foreign keys** in Room: sync pages may deliver a child before its parent (a parent updated later carries a higher `server_version`). Queries that feed the UI join and skip rows whose references do not resolve yet.
* Server-only columns are not mirrored: `token_hash`, `fcm_token`, `name_key`, `import_key`, `server_received_at`, `updated_by_device_id`, `code_hash`. Tables `devices`, `invites`, `meta`, `sync_sequence`, `sync_mutations` are not mirrored. Card tables (D-173): only the signed-in user's own rows, without `user_id`, `session_id`, `account_uid`, `last_user_fetch_at`, `background_fetches` and `provider_ref`; `card_auth_attempts` and `card_sequence` are not mirrored.
* Timestamps are `String` in the fixed RFC 3339 form; dates `String` `YYYY-MM-DD`; money `Long`; bp `Int`; booleans `Boolean`.
* `local_updated_at` (Long, epoch milliseconds, phone clock) is set on every local write and on every row written from the network. It orders the push queue and is never sent.

#### 14.2.1 Mirrored tables

| Entity class | Table | Columns (server columns unless marked local) | Primary key | Indices |
|---|---|---|---|---|
| `UserEntity` | `users` | `id`, `role`, `display_name`, `picture_version?`, `created_at`, `updated_at`, `server_version`, local `local_updated_at` | `id` | none |
| `AccountEntity` | `accounts` | `id`, `name`, `created_by_user_id`, `created_at`, `updated_at`, `archived_at?`, `deleted_at?`, `server_version`, local `local_updated_at` | `id` | `created_at` |
| `AccountDefaultShareEntity` | `account_default_shares` | `account_id`, `user_id`, `share_bp` | (`account_id`, `user_id`) | none |
| `CategoryEntity` | `categories` | `id`, `default_key?`, `name?`, `icon`, `color`, `sort_order`, `created_at`, `updated_at`, `archived_at?`, `deleted_at?`, `server_version`, local `local_updated_at` | `id` | none |
| `RecurringTemplateEntity` | `recurring_templates` | every server column, plus `next_occurrence_date?` (from the wire), local `local_updated_at` | `id` | `account_id` |
| `RecurringTemplateSplitEntity` | `recurring_template_splits` | `template_id`, `user_id`, `share_bp?`, `share_ore?` | (`template_id`, `user_id`) | none |
| `ExpenseEntity` | `expenses` | `id`, `account_id`, `category_id`, `amount_ore`, `description`, `notes`, `expense_date`, `payer_user_id`, `split_mode`, `recurring_template_id?`, `recurring_period?`, `created_by_user_id?` (null until the server accepted the create), `updated_by_user_id?`, `created_at`, `updated_at`, `deleted_at?`, `server_version?` (null until accepted); local `pending`, `pending_mutation_id?`, `local_updated_at` | `id` | `account_id`, `expense_date`, `pending` |
| `ExpenseSplitEntity` | `expense_splits` | `expense_id`, `user_id`, `share_ore`, `share_bp?` | (`expense_id`, `user_id`) | none |
| `SettlementEntity` | `settlements` | `id`, `from_user_id`, `to_user_id`, `amount_ore`, `settlement_date`, `note`, `created_by_user_id?`, `updated_by_user_id?`, `created_at`, `updated_at`, `deleted_at?`, `server_version?`; local `pending`, `pending_mutation_id?`, `local_updated_at` | `id` | `settlement_date`, `pending` |
| `SettlementAllocationEntity` | `settlement_allocations` | `settlement_id`, `account_id`, `amount_ore` | (`settlement_id`, `account_id`) | `account_id` |
| `CardConnectionEntity` (v2, D-173) | `card_connections` | `id`, `provider_id`, `status`, `history_days`, `valid_until?`, `last_fetch_at?`, `last_fetch_error?`, `created_at`, `updated_at`, `card_version`, local `local_updated_at` | `id` | none |
| `CardPurchaseEntity` (v2, D-173) | `card_purchases` | `id`, `connection_id`, `status`, `direction`, `purchase_date`, `booking_date?`, `amount_ore?`, `original_amount?`, `original_currency?`, `merchant`, `expense_id?`, `ignored`, `created_at`, `updated_at`, `deleted_at?`, `card_version`; local `pending`, `local_updated_at` | `id` | `purchase_date`, `expense_id`, `pending` |
| `AuditEntryEntity` | `audit_log` | `id`, `entity_type`, `entity_id`, `action`, `source`, `actor_user_id`, `client_at`, `server_at`, `changes` (JSON text as received), `server_version` | `id` | (`entity_type`, `entity_id`) |

Local-only semantics on `expenses` and `settlements`:

* `pending = true` means the row has a local change not yet accepted by the server. Every local create, edit or delete sets `pending = true`, sets a new UUIDv7 `pending_mutation_id`, sets `updated_at` to the phone's current time in the fixed RFC 3339 form (and `created_at` on create), and sets `local_updated_at`.
* A local delete sets `deleted_at` = `updated_at` = now. The row stays as a tombstone.
* The pending-changes count (AC-15.4) is `count(expenses where pending) + count(settlements where pending)`; pending card rows are not counted (they are the holder's own and need no attention, CP-9).
* Card purchases follow the same pattern for the holder's link and ignore changes (CP-9): a local `link`, `unlink` or `setIgnored` writes `expense_id` and `ignored`, sets `pending = true` and `local_updated_at`; the card cycle sends `PUT /cards/purchases/{id}` (E-44) for each pending row and, on 200, overwrites the row with the answer and clears `pending`; on `not_found` with `field` `expense_id` (the expense is not on the server yet) it stays pending for the next cycle; on `not_found` for the purchase it deletes the local row; on `expense_already_linked` or `validation_failed` it takes the server's state at the next pull and clears `pending`: the row's `card_version` is reset to 0 and `card_sync_state.cursor` moved back to just before the row's version when it is ahead, so the unchanged server row is pulled again (D-192). A link whose expense is not on the phone or is deleted there is cleared before E-44, and every link to an expense is cleared when the phone deletes it locally or removes it after a rejection (D-193). A card pull skips a pending local row, as §14.4.2 step 3 does. Deleted purchases (tombstones) are deleted locally.

#### 14.2.2 Local-only tables

| Entity class | Table | Columns | Primary key |
|---|---|---|---|
| `SyncStateEntity` | `sync_state` | `id` (always 1), `cursor` Long (last applied `next_since`, 0 initially), `epoch` String?, `last_success_at` String?, `last_attempt_at` String?, `last_error_code` String? (an error code of §14.3.2 or `network`), `clock_skew` Boolean | `id` |
| `CardSyncStateEntity` (v2, D-173) | `card_sync_state` | `id` (always 1), `cursor` Long (last applied `next_since` of E-40, 0 initially), `last_success_at` String? | `id` |
| `SyncRejectionEntity` | `sync_rejections` | `mutation_id`, `entity_type`, `entity_id`, `reason` (§14.4.6), `message`, `rejected_payload` (JSON of the entity as pushed), `server_current` (JSON or null), `rejected_at` String, `dismissed` Boolean | `mutation_id` |

Per-phone preferences (last used account, last used category per account, "install unknown apps" explanation shown, the installed version code that received a 426 `protocol_unsupported`, D-043, and the last card catalogue of E-36 as JSON under `card_providers`, D-194) live in DataStore `prefs.preferences_pb`, not Room. The pairing status lives in `auth.preferences_pb` with the token (§8.2, D-043).

#### 14.2.3 Migrations

Version 1 has no migrations. Every later Room version adds a `Migration` and a migration test in `:data` (`CLAUDE.md`), and is a contract change (§14.8). Version 2 (D-173, K2): `MIGRATION_1_2` creates `card_connections`, `card_purchases` and `card_sync_state` (with the row `id` 1, `cursor` 0) and changes no existing table; its test opens a version 1 database built from the exported `1.json` holding users, accounts, categories, expenses, settlements, audit entries, a pending expense and a rejection, migrates it, and asserts every row is kept and the new tables exist as in the exported `2.json`. The revoke wipe (AC-3.3) deletes the card tables with the rest. Landed by K2 (`a8f91ee`): `KvittDatabase` version 2 with `MIGRATION_1_2`, the exported `android/data/schemas/se.hagstedt.kvitt.data.db.KvittDatabase/2.json` committed (a contract file, §14.8) and the migration test in `:data`'s `MigrationTest`. Room 3 migrations operate on an `SQLiteConnection` (the driver API), not on a `SupportSQLiteDatabase` (D-012).

#### 14.2.4 UI contract: types and repository interfaces in `:core:model`

Package `se.hagstedt.kvitt.model`. Features see only these. `:data` implements them; `:core:fakes` fakes them. Flows are cold `kotlinx.coroutines.flow.Flow`; suspend functions are main-safe.

```kotlin
// Ids and enums
@JvmInline value class UserId(val value: String)
@JvmInline value class AccountId(val value: String)
@JvmInline value class CategoryId(val value: String)
@JvmInline value class ExpenseId(val value: String)
@JvmInline value class SettlementId(val value: String)
@JvmInline value class TemplateId(val value: String)
@JvmInline value class DeviceId(val value: String)
@JvmInline value class InviteId(val value: String)

enum class Role { ADMIN, MEMBER }
enum class SplitMode { DEFAULT, RATIO, EXACT, FULL }
enum class InviteKind { ADMIN_SETUP, PARTNER, DEVICE }
enum class EntityType { EXPENSE, SETTLEMENT }
enum class AuditAction { CREATE, UPDATE, DELETE }
enum class AuditSource { APP, RECURRING, IMPORT }
enum class DefaultCategoryKey { GROCERIES, RESTAURANTS, HOUSING, HOME, UTILITIES, INSURANCE, TRANSPORT, TRAVEL, ENTERTAINMENT, HEALTH, CHILDREN, SHOPPING, FEES, OTHER }   // AC-7.2 order (D-054)
enum class ColorToken { GREEN, ORANGE, BROWN, YELLOW, BLUE, TEAL, PURPLE, RED, PINK, GREY, INDIGO, LIME, SLATE, AMBER }
enum class RangePreset { THIS_MONTH, LAST_3_MONTHS, LAST_6_MONTHS, LAST_12_MONTHS, THIS_YEAR, ALL_TIME, CUSTOM }
enum class Granularity { MONTH, WEEK }
enum class Measure { HOUSEHOLD, MY_SHARE }
enum class GroupBy { CATEGORY, ACCOUNT }
enum class SyncRejectionReason { STALE, DELETED, VALIDATION_FAILED, REFERENCE_NOT_FOUND, CLOCK_SKEW }
// Wire value of every enum = lowercase name (SplitMode.DEFAULT <-> "default"). Icon tokens are Strings from CategoryIcons.ALL (§9.7).
object CategoryIcons { val ALL: List<String> /* the 33 tokens of §9.7, in that order */ }

// Plain records
data class User(val id: UserId, val role: Role, val displayName: String, val pictureVersion: Int?)
data class Account(val id: AccountId, val name: String, val defaultShares: Map<UserId, Int>, val createdAt: String, val archived: Boolean)
data class Category(val id: CategoryId, val defaultKey: DefaultCategoryKey?, val customName: String?, val icon: String, val color: ColorToken, val sortOrder: Int, val archived: Boolean)
data class Share(val userId: UserId, val shareOre: Long, val shareBp: Int?)

// Results
sealed interface OnlineResult<out T> {
    data class Ok<T>(val value: T) : OnlineResult<T>
    data object Offline : OnlineResult<Nothing>
    data class Failed(val code: String, val field: String?) : OnlineResult<Nothing>   // code from §14.3.2, or "network" when the server could not be reached (D-029)
}
sealed interface SaveResult<out T> {
    data class Saved<T>(val id: T) : SaveResult<T>
    data class Invalid(val errors: List<FieldError>) : SaveResult<Nothing>
}
data class FieldError(val field: String, val error: String)   // error = a domain error token of §14.5.3, "required", or "validation_failed" for a §9.6 rule without a domain token

// Session and onboarding (S-1, S-2, S-3, S-18)
data class Pairing(val user: User, val inviteKind: InviteKind)   // v0.13, D-086: the E-3 invite_kind; an unknown wire value reads as DEVICE
sealed interface SessionState {
    data object Unpaired : SessionState
    data class Paired(val me: User, val partner: User?, val deviceId: DeviceId) : SessionState
    data object Revoked : SessionState
    data object Unrecognised : SessionState   // 401 unauthorized: pair again, data kept (§14.4.8)
}
interface SessionRepository {
    val session: Flow<SessionState>
    suspend fun pair(serverUrl: String, code: String, displayName: String?, deviceName: String): OnlineResult<Pairing>   // v0.13, D-086
    suspend fun acknowledgeRevoked()   // wipes local data (AC-3.3) and moves to Unpaired
}

// Balances shared by several screens. netOre is the viewer's net (§9.3): > 0 partner owes viewer.
data class BalanceView(val netOre: Long, val partner: User)

// Home (S-4)
data class AccountSummary(val account: Account, val netOre: Long, val expensesThisMonth: Int)
data class SyncSummary(val lastSuccessAt: String?, val pendingCount: Int, val rejectedCount: Int, val clockSkew: Boolean, val running: Boolean, val lastAttemptFailed: Boolean)   // lastAttemptFailed: v0.13, D-088
data class HomeState(val me: User, val partner: User?, val global: BalanceView?, val active: List<AccountSummary>, val archived: List<AccountSummary>, val sync: SyncSummary, val update: UpdateInfo?)
interface HomeRepository { fun home(): Flow<HomeState> }

// Ledger rows (S-5, S-12)
sealed interface ExpenseEffect {
    data class Lent(val ore: Long) : ExpenseEffect
    data class Borrowed(val ore: Long) : ExpenseEffect
    data object NotInvolved : ExpenseEffect
    data object PaidForYourself : ExpenseEffect
}
sealed interface LedgerRow {
    data class ExpenseRow(val id: ExpenseId, val date: String, val description: String, val category: Category, val amountOre: Long, val effect: ExpenseEffect, val pending: Boolean) : LedgerRow
    data class SettlementRow(val id: SettlementId, val date: String, val from: User, val to: User, val amountOre: Long, val accountCount: Int, val pending: Boolean) : LedgerRow   // amountOre: in an account's list (S-5) the allocation to that account, elsewhere the total (AC-11.7); accountCount: allocations of the whole settlement
}
data class LedgerMonth(val period: String, val householdSpendOre: Long, val rows: List<LedgerRow>)

// Accounts (S-5, S-6)
data class AccountDetailState(val account: Account, val balance: BalanceView, val months: List<LedgerMonth>, val deletable: Boolean, val users: List<User>)
interface AccountRepository {
    fun detail(id: AccountId): Flow<AccountDetailState?>
    fun all(): Flow<List<Account>>
    suspend fun create(name: String, defaultShares: Map<UserId, Int>): OnlineResult<AccountId>
    suspend fun update(id: AccountId, name: String, defaultShares: Map<UserId, Int>): OnlineResult<Unit>
    suspend fun setArchived(id: AccountId, archived: Boolean): OnlineResult<Unit>
    suspend fun delete(id: AccountId): OnlineResult<Unit>
}

// Expenses (S-7, S-8)
data class ExpenseDraft(val id: ExpenseId?, val accountId: AccountId?, val categoryId: CategoryId?, val amountOre: Long?, val description: String, val notes: String, val date: String, val payer: UserId, val mode: SplitMode, val ratioBp: Map<UserId, Int>?, val exactOre: Map<UserId, Long>?, val fullOn: UserId?)
data class ExpenseEditorOptions(val me: User, val partner: User, val accounts: List<Account>, val categories: List<Category>, val defaultAccountId: AccountId?, val defaultCategoryFor: Map<AccountId, CategoryId>, val today: String, val frequentCategoryIds: Map<AccountId, List<CategoryId>>)   // frequentCategoryIds: v0.9, D-059
data class TimelineLine(val actor: User?, val action: AuditAction, val source: AuditSource, val clientAt: String, val changes: List<FieldChange>, val pendingLocal: Boolean)
data class FieldChange(val field: String, val oldDisplay: String?, val newDisplay: String?)   // ids already resolved to names; amounts and dates raw (öre as String, ISO date), formatted by the UI
data class ExpenseDetailState(val id: ExpenseId, val account: Account, val category: Category, val amountOre: Long, val description: String, val notes: String, val date: String, val payer: User, val mode: SplitMode, val shares: List<Share>, val recurringTemplateName: String?, val deleted: Boolean, val pending: Boolean, val timeline: List<TimelineLine>)
interface ExpenseRepository {
    fun editorOptions(): Flow<ExpenseEditorOptions>
    suspend fun load(id: ExpenseId): ExpenseDraft?
    fun preview(draft: ExpenseDraft): List<Share>?     // null while the draft cannot be computed
    suspend fun save(draft: ExpenseDraft): SaveResult<ExpenseId>
    suspend fun delete(id: ExpenseId)
    fun detail(id: ExpenseId): Flow<ExpenseDetailState?>
    suspend fun suggestCategory(accountId: AccountId?, description: String): CategoryId?   // §9.11, D-049; null only while the phone holds no categories
}

// Settlements (S-9, S-10)
data class AllocationLine(val account: Account, val payerNetOre: Long, val amountOre: Long, val overSettles: Boolean)
data class UntouchedAccount(val account: Account, val payerNetOre: Long)   // v0.13, D-093
data class SettleState(val payer: User, val recipient: User, val amountOre: Long?, val lines: List<AllocationLine>, val remainingOre: Long, val canConfirm: Boolean, val date: String, val note: String, val untouched: List<UntouchedAccount>)   // untouched: v0.13, D-093
data class SettleRequest(val editing: SettlementId?, val payer: UserId, val amountOre: Long?, val fixedAccount: AccountId?, val allocations: Map<AccountId, Long>?, val date: String, val note: String)
data class SettlementDetailState(val id: SettlementId, val from: User, val to: User, val amountOre: Long, val date: String, val note: String, val allocations: List<Pair<Account, Long>>, val deleted: Boolean, val pending: Boolean, val timeline: List<TimelineLine>)
interface SettlementRepository {
    suspend fun start(editing: SettlementId?, fixedAccount: AccountId?): SettleState?   // defaults per AC-11.3 / AC-11.4; null without a paired session or partner (v0.18, D-111)
    suspend fun recompute(request: SettleRequest): SettleState?  // allocations == null: propose (§9.4); else validate and warn; null as start (D-111)
    // save without a session or partner: SaveResult.Invalid([FieldError("payer", "validation_failed")]); no method throws (D-111)
    suspend fun save(request: SettleRequest): SaveResult<SettlementId>
    suspend fun delete(id: SettlementId)
    fun detail(id: SettlementId): Flow<SettlementDetailState?>
}

// Analytics (S-11, S-12)
data class AnalyticsFilter(val preset: RangePreset, val customStart: String?, val customEnd: String?, val granularity: Granularity, val measure: Measure, val groupBy: GroupBy)
data class GroupKey(val id: String, val label: String?, val color: ColorToken?)   // label null: UI uses the default category name
data class SpendBucket(val key: String, val start: String, val end: String, val totals: Map<String, Long>, val totalOre: Long)
data class AnalyticsState(val filter: AnalyticsFilter, val start: String, val end: String, val groups: List<GroupKey>, val buckets: List<SpendBucket>, val byCategory: List<Pair<GroupKey, Long>>, val byAccount: List<Pair<GroupKey, Long>>, val totalOre: Long)   // no error field: a CUSTOM filter with a missing date is resolved with today for that date; the S-11 range editor never sends one
data class DrillDownState(val title: String, val totalOre: Long, val rows: List<LedgerRow.ExpenseRow>)   // title: unlocalised parts joined by ", " (category custom name or default key, account name, bucket key); S-12 formats its visible title itself from the drillDown arguments
interface AnalyticsRepository {
    fun analytics(filter: AnalyticsFilter): Flow<AnalyticsState>
    fun drillDown(filter: AnalyticsFilter, bucketKey: String?, categoryId: CategoryId?, accountId: AccountId?): Flow<DrillDownState>
}

// Insights (S-11, v0.31, D-141): model/Insights.kt; the server's E-34 trends and E-35 forecast, online only (§9.9), nothing stored.
// Months "YYYY-MM" (Europe/Stockholm), amounts in öre for the requested measure, named after the E-34/E-35 fields (§14.5.7).
data class TrendPoint(val month: String, val amountOre: Long, val movingAverageOre: Long)
data class SpendTrend(val totalOre: Long, val averageOre: Long, val lastMonthOre: Long, val lastMonthVsAveragePct: Int?, val currentMonthOre: Long, val points: List<TrendPoint>)
data class CategoryTrend(val categoryId: CategoryId, val category: Category?, val trend: SpendTrend)   // category from Room, archived and deleted included; null when unknown
data class SpendTrends(val measure: Measure, val today: String, val currentMonth: String, val months: Int, val household: SpendTrend, val categories: List<CategoryTrend>)   // categories in the server's order
data class ForecastMonth(val month: String, val recurringOre: Long, val baselineOre: Long, val forecastOre: Long)
data class AccountForecast(val accountId: AccountId, val account: Account?, val currentMonthOre: Long, val months: List<ForecastMonth>)   // account from Room, null when unknown
data class SpendForecast(val measure: Measure, val today: String, val currentMonth: String, val accounts: List<AccountForecast>)   // accounts in the server's order
interface InsightsRepository {
    suspend fun trends(months: Int, measure: Measure): OnlineResult<SpendTrends>   // months 1..24
    suspend fun forecast(measure: Measure): OnlineResult<SpendForecast>
}

// Settings (S-13 to S-15, S-19 to S-22)
interface ProfileRepository {
    fun household(): Flow<List<User>>
    suspend fun setDisplayName(name: String): OnlineResult<Unit>
    suspend fun setPicture(bytes: ByteArray, mimeType: String): OnlineResult<Unit>
    suspend fun removePicture(): OnlineResult<Unit>
}
interface CategoryRepository {
    fun all(): Flow<List<Category>>
    suspend fun create(name: String, icon: String, color: ColorToken): OnlineResult<CategoryId>
    suspend fun update(id: CategoryId, name: String?, icon: String, color: ColorToken): OnlineResult<Unit>   // name null = reset default name
    suspend fun reorder(idsInOrder: List<CategoryId>): OnlineResult<Unit>
    suspend fun setArchived(id: CategoryId, archived: Boolean): OnlineResult<Unit>
    suspend fun delete(id: CategoryId): OnlineResult<Unit>
    fun deletable(id: CategoryId): Flow<Boolean>   // v0.9, D-059: false for a default category or one used by a non-deleted expense or non-deleted recurring template (AC-7.6)
}
data class RecurringTemplate(val id: TemplateId, val draft: ExpenseDraft, val dayOfMonth: Int, val startPeriod: String, val endPeriod: String?, val paused: Boolean, val nextOccurrence: String?)
data class NewRecurringTemplate(val draft: ExpenseDraft, val dayOfMonth: Int, val startPeriod: String, val endPeriod: String?, val paused: Boolean)   // v0.13, D-091
interface RecurringRepository {
    fun all(): Flow<List<RecurringTemplate>>
    suspend fun create(t: NewRecurringTemplate): OnlineResult<TemplateId>   // v0.13, D-091: the server mints the id
    suspend fun update(t: RecurringTemplate): OnlineResult<Unit>
    suspend fun delete(id: TemplateId): OnlineResult<Unit>
}
data class Device(val id: DeviceId, val user: User, val name: String, val pairedAt: String, val lastSeenAt: String, val appVersionCode: Int?, val appVersionName: String?, val current: Boolean, val revoked: Boolean)   // appVersionName: v0.13, D-090
interface DeviceRepository {
    suspend fun list(): OnlineResult<List<Device>>
    suspend fun revoke(id: DeviceId): OnlineResult<Unit>
}
data class Invite(val id: InviteId, val kind: InviteKind, val targetUser: UserId?, val code: String?, val link: String?, val createdAt: String, val expiresAt: String)   // code and link only right after creation
interface InviteRepository {
    suspend fun list(): OnlineResult<List<Invite>>
    suspend fun create(kind: InviteKind, targetUser: UserId?): OnlineResult<Invite>
    suspend fun cancel(id: InviteId): OnlineResult<Unit>
}
data class Rejection(val mutationId: String, val entityType: EntityType, val entityId: String, val reason: SyncRejectionReason, val summary: String, val rejectedAt: String, val actor: User?, val lost: RejectedVersion?)   // actor: v0.13, D-089; lost: v0.18, D-109
// D-109: the refused version as pushed (sync_rejections.rejected_payload), shown read-only on S-16; lost is null when the payload
// cannot be decoded or its category or a user is missing on the phone. row is the ledger row it would have been (pending false);
// for a settlement accountName, payer and mode are null and shares empty; notes is the expense's notes or the settlement's note.
data class RejectedVersion(val row: LedgerRow, val accountName: String?, val payer: User?, val mode: SplitMode?, val shares: List<Share>, val notes: String, val deleted: Boolean)
data class SyncStatusState(val summary: SyncSummary, val pending: List<LedgerRow>, val rejections: List<Rejection>)
interface SyncRepository {
    fun status(): Flow<SyncStatusState>
    suspend fun syncNow()
    suspend fun dismiss(mutationId: String)
}
data class UpdateInfo(val versionCode: Int, val versionName: String, val sizeBytes: Long)
sealed interface UpdateState {
    data object None : UpdateState
    data class Available(val info: UpdateInfo) : UpdateState
    data class Downloading(val info: UpdateInfo, val progress: Float) : UpdateState
    data class Failed(val info: UpdateInfo, val reason: UpdateFailure = UpdateFailure.Download) : UpdateState   // reason: v0.32, D-155
    data class NeedsInstallPermission(val info: UpdateInfo) : UpdateState
}
sealed interface UpdateFailure {   // v0.32, D-155: why Failed; the downloaded file is deleted in every case
    data object Download : UpdateFailure                    // no answer, an error, or size or SHA-256 mismatch (AC-16.4)
    data object Blocked : UpdateFailure                     // STATUS_FAILURE_BLOCKED: the phone's security settings
    data class Install(val detail: String?) : UpdateFailure // any other installer failure; detail = the installer's status message
}
sealed interface UpdateCheck {   // v0.13, D-092
    data object UpToDate : UpdateCheck
    data class Available(val info: UpdateInfo) : UpdateCheck
    data object Failed : UpdateCheck
}
interface UpdateRepository {
    val state: Flow<UpdateState>
    suspend fun check(): UpdateCheck   // v0.13, D-092
    suspend fun checkNow(): UpdateCheck = check()   // v0.30, D-140: S-22's button; skips the 6-hour throttle and restarts it
    suspend fun install()
}
data class AboutState(val versionName: String, val versionCode: Int, val serverUrl: String, val serverVersion: String?, val schemaVersion: Int?)   // schemaVersion: v0.18, D-110
// D-110: serverVersion and schemaVersion from E-1 /health when S-22 opens online; offline or on failure serverVersion is the
// X-Kvitt-Server-Version header of the last response and schemaVersion is null.
// D-122: serverUrl is the paired server's base URL; while none is stored, AppBuildInfo.releaseServerUrl.
interface AboutRepository { fun about(): Flow<AboutState> }
// Not a :core:model type: defined in :data (di/DataModule.kt), provided by :app (di/AppBuildInfoModule.kt) from BuildConfig and
// RELEASE_SERVER_URL = https://<kvitt.publicHost> (D-121, D-124), consumed by :data.
data class AppBuildInfo(val versionCode: Int, val versionName: String, val debug: Boolean, val releaseServerUrl: String)   // releaseServerUrl: v0.22, D-122
interface ConnectivityRepository { val online: Flow<Boolean> }   // §9.9

// Push (§14.6), v0.13, D-095: model/Push.kt; :adapter:fcm maps FCM data messages into it
data class PushEvent(val type: String, val entityType: String, val entityId: String, val actorUserId: String, val count: Int)
```

Agents may add fields to these types only through a contract change (§14.8). A feature that needs a value not listed asks the orchestrator.

Changes in v0.35 (D-169, D-170, D-173; card purchases, K2): a new file `model/Cards.kt`, and three members elsewhere. Names are binding; K2 may add fields only with a decision.

```kotlin
// Card purchases (S-23 to S-27, FR-22, §9.12). Only the signed-in user's own card rows exist on the phone (D-161).
@JvmInline value class CardConnectionId(val value: String)
@JvmInline value class CardPurchaseId(val value: String)
enum class CardConnectionStatus { ACTIVE, EXPIRED, DISCONNECTED }
enum class CardPurchaseStatus { PENDING, BOOKED }
enum class CardDirection { DEBIT, CREDIT }
enum class CardFilter { TO_HANDLE, LINKED, IGNORED, ALL }
enum class CardFetchError { BANK_UNAVAILABLE, RATE_LIMITED, CONSENT_EXPIRED, FAILED }   // wire: lowercase; an unknown value reads as FAILED

data class CardProvider(val id: String, val name: String, val issuer: String, val imageKey: String, val available: Boolean)   // id and imageKey are open strings (CP-1)
data class CardConnection(val id: CardConnectionId, val providerId: String, val status: CardConnectionStatus, val historyDays: Int, val validUntil: String?, val lastFetchAt: String?, val lastFetchError: CardFetchError?, val expiresSoon: Boolean)   // expiresSoon: ACTIVE and validUntil within 14 days (CP-6), computed with the phone's clock
data class LinkedExpense(val id: ExpenseId, val description: String, val accountName: String)
data class CardPurchase(val id: CardPurchaseId, val connectionId: CardConnectionId, val status: CardPurchaseStatus, val direction: CardDirection, val date: String, val bookingDate: String?, val amountOre: Long?, val originalAmount: String?, val originalCurrency: String?, val merchant: String, val linked: LinkedExpense?, val ignored: Boolean, val pendingLocal: Boolean)   // amountOre null: foreign currency (CP-7); linked null also while the expense is not on the phone
data class ExpenseMatch(val id: ExpenseId, val description: String, val accountName: String, val payer: User, val date: String, val amountOre: Long)
data class CardPurchaseRow(val purchase: CardPurchase, val matches: List<ExpenseMatch>)   // matches (CP-10) only under TO_HANDLE, else empty
data class CardDay(val date: String, val rows: List<CardPurchaseRow>)
data class CardsState(val provider: CardProvider?, val connection: CardConnection?, val filter: CardFilter, val counts: Map<CardFilter, Int>, val days: List<CardDay>, val fetching: Boolean)   // connection null: the empty state; fetching: an E-42 call of this phone is running
data class CardPurchaseDetail(val row: CardPurchaseRow, val others: List<ExpenseMatch>)   // others: "Välj en annan utgift" (CP-10)
data class CardConnectStart(val attemptId: String, val authUrl: String, val expiresAt: String)
sealed interface CardAttemptState {
    data object Pending : CardAttemptState
    data class Connected(val connection: CardConnection) : CardAttemptState
    data class Failed(val reason: String) : CardAttemptState   // E-38 failure token, e.g. "no_account", "bank_error", "cancelled"
    data object Expired : CardAttemptState
}

interface CardRepository {
    val hasConnection: Flow<Boolean>                                   // a connection with status ACTIVE or EXPIRED exists (S-5's "Från kortköp")
    fun cards(filter: CardFilter): Flow<CardsState>                    // S-23, from Room; works offline
    fun purchase(id: CardPurchaseId): Flow<CardPurchaseDetail?>        // the sheet
    fun toHandle(): Flow<List<CardPurchase>>                           // S-27: debit, neither linked nor ignored, newest first
    fun purchaseForExpense(id: ExpenseId): Flow<CardPurchase?>         // S-8's line
    suspend fun providers(): OnlineResult<List<CardProvider>>          // E-36, online only (S-24)
    suspend fun startConnect(providerId: String, historyDays: Int): OnlineResult<CardConnectStart>   // E-37, connect and renew
    suspend fun attempt(attemptId: String): OnlineResult<CardAttemptState>                           // E-38
    suspend fun refresh(): OnlineResult<Unit>                          // E-42, then a card pull
    suspend fun setHistoryDays(id: CardConnectionId, days: Int): OnlineResult<Unit>                  // E-41, shorter only
    suspend fun disconnect(id: CardConnectionId, eraseHandled: Boolean): OnlineResult<Unit>          // E-43
    suspend fun prefill(id: CardPurchaseId, accountId: AccountId?): ExpenseDraft?   // CP-9; accountId null: the AC-8.6 default; null when the purchase is unknown
    suspend fun link(id: CardPurchaseId, expenseId: ExpenseId)         // local at once, sent later (CP-9); never fails
    suspend fun unlink(id: CardPurchaseId)
    suspend fun setIgnored(id: CardPurchaseId, ignored: Boolean)
}
```

* **Where it is used.** `:feature:cards` (S-23 to S-27); `:feature:expense` (S-7 takes the optional navigation argument `cardPurchaseId`, starts from `prefill` and calls `link` after a successful save; S-8 reads `purchaseForExpense` and calls `unlink`); `:feature:account` (S-5 reads `hasConnection` for "Från kortköp"); `:feature:settings` (S-13 reads `cards(CardFilter.ALL).connection` for the "Anslut kort" subtitle, as built). `:app` binds `CardRepository` to `:data`'s `CardRepositoryImpl` in `DataBindingsModule`, routes `kvitt://cards/connected?attempt=<id>` to S-25 (or S-23 when S-25 is not open), and adds the destination `KvittDestination.Cards` (§13.2).
* **`:data`.** DTOs for E-36 to E-44 with round-trip tests over K1's examples; `CardRepositoryImpl` on the Room tables of §14.2.1 and `card_sync_state`; the card cycle (push pending card rows with E-44, then pull E-40 until `has_more` is false) runs after every household sync cycle (§14.4.1) and after `refresh`; a 404 `not_found` from E-40 (a server before schema 4) is treated as "no card support" and leaves the tables empty; `cursor_ahead` or a household epoch change drops the card cache (pending rows kept) and pulls from 0. `matches` and `others` come from `:domain`'s `matchCardPurchase` (§14.5.8) over Room's expenses. `prefill` applies CP-9 and the AC-8.6 default account; the editor runs the §9.11 suggestion itself as for any new expense. A local expense delete clears a local link to it (CP-9). The bank URL is opened by `:feature:cards` through a Custom Tab (`androidx.browser`, a catalog entry K2 adds).
* **`:core:fakes`.** `FakeCardRepository` with scenarios in `fakes/cards/`: no connection, first fetch, loaded (to handle, linked, ignored, credit, pending, foreign), empty filter, offline, expiring, expired, fetch failed, long content, attempt pending / connected / failed / expired; `matches` computed with `:domain`'s function, as every fake computes derived values (§6.2).
* **`ExpenseDraft`** is unchanged: a prefilled draft is a draft with `id` null.

Readings fixed in v0.39 (D-191 to D-196, as landed by K2 `a8f91ee`; no type changes: `model/Cards.kt` declares exactly the block above):

* **The card cycle (D-191).** `:data`'s `CardSync` runs after each successful household cycle (`SyncEngine`) and after `refresh`, one at a time; its outcome never changes the household outcome or `SyncSummary`. A 404 from E-40 is "no card support": nothing is stored and the next cycle asks again.
* **E-44 refusals and dead links (D-192, D-193).** See §14.2.1: a refused change resets the row's `card_version` and moves the card cursor back before it; links to expenses no longer on the phone are cleared before E-44 and at every local delete or rejection that removes an expense.
* **Catalogue cache (D-194).** `CardsState.provider` comes from the last E-36 answer, cached in DataStore (`card_providers`, §14.2.2), so S-23, S-25 and S-26 name the card and draw its artwork offline; `providers()` stays online only and refreshes the cache; after a connect or an "Uppdatera" the phone asks E-36 when the cache is empty or lacks the connected provider.
* **Following a fetch (D-195).** After `attempt` returns `Connected` or E-42 answers `fetching` true, `:data` pulls E-40 every 3 s, at most 40 times, until the connection's `last_fetch_at` or `last_fetch_error` changes. `refresh` while this phone's E-42 call runs returns `Ok` without a request; `CardsState.fetching` is true for the duration of the call.
* **Return link (D-196).** `:app` parses `kvitt://cards/connected?attempt=<id>` (`AppLink.CardConnected`, the id 1 to 64 ASCII letters, digits or `-`); S-25, when open, polls that attempt at once; otherwise `AppViewModel` calls `attempt` once and opens S-23.
* **`CardPurchase.linked` while the expense is missing (OQ-9).** `linked` is null both when the purchase is unlinked and when it is linked to an expense not yet on the phone; the filters read the stored link, so such a purchase is listed under "Kopplade", without its "Kopplad till" line, and its sheet shows the to-handle actions until the expense arrives. A `linkedExpenseId` field would tell the two apart; it is a contract change (§14.8) and waits for the owner (§12 OQ-9).

Readings fixed in v0.4 (no type changes):

* **`FieldError.error`.** Allowed values: a domain token of §14.5.3, `required` (a required value is missing or blank), or `validation_failed` (a §9.6 rule with no domain token: lengths, dates, `day_of_month`, periods).
* **Analytics range errors.** `AnalyticsState` has no error field. `AnalyticsRepository.analytics` never fails for a `CUSTOM` filter with `customStart` or `customEnd` null: it resolves the missing date as today. The S-11 custom-range editor does not let the user apply a range with a missing date, so this path is defensive only. `resolveRange` still throws `IncompleteCustomRangeException` (§14.5.4); the repository supplies today before calling it.
* **`DrillDownState.title`.** Stays a `String`. The repository fills it with the unlocalised parts as above, as the fakes do. S-12 does not display it as is: the feature formats the visible title ("Mat & hushåll, oktober 2026") from the arguments it passed to `drillDown` (the category or account, resolved through `GroupKey` with the default category name from resources, and the bucket key formatted with `DateFormatter`).
* **Settlement rows in an account's list** carry the allocation to that account (AC-11.7).
* **`Share` names.** `se.hagstedt.kvitt.model.Share` (a split share) and `se.hagstedt.kvitt.model.analytics.AnalyticsMeasure.Share` (the measure) share a simple name in different packages. Accepted; code that needs both imports one with an alias or qualifies it.

Changes in v0.8 (D-049, D-054):

* **Category suggestion types** live in `:domain`, not here (§14.5.6); `:core:model` gains only `ExpenseRepository.suggestCategory`.
* **Fourteen defaults.** `DefaultCategoryKey` gains `HOUSING`, `INSURANCE`, `CHILDREN`, `FEES` (wire values `housing`, `insurance`, `children`, `fees`), `ColorToken` gains `SLATE` and `AMBER`, `CategoryIcons.ALL` gains `key`, `shield`, `account_balance` at the end. The localised default names are those of AC-7.2.
* **`ExpenseRepository.suggestCategory`.** Computed in `:data` from Room (every non-deleted expense on the phone, pending ones included, across all accounts and both users; and the active categories, neither archived nor deleted), the per-phone last-used category of the account (DataStore, §14.2.2) and the keyword table copied from `contracts/category-keywords.csv` at build time (D-055) and parsed with `parseCategoryKeywords` (D-056), by calling `:domain`'s `suggestCategory` (§14.5.6). `:data` binds `:domain`'s `UnicodeText` with `java.text.Normalizer` and `Character`, since `:domain` may not use `java.*` (§14.5.6). `accountId` null (no active account) gives the fallback `other`. The result is null while the phone holds no categories (before the first sync), and when `other` is archived and no active last-used category exists; the editor then shows no category until the user picks one (AC-8.6, v0.9). Stored `expense_date` values are valid ISO dates (§9.6), so parsing them for the history cannot fail. The editor (S-7) calls it on every change of the description and of the account while the category was not picked by hand (§9.11 CS-2, CS-3) and never when editing an existing expense (CS-1). `ExpenseEditorOptions.defaultCategoryFor` stays: it is the step-4 default before any description is typed.

Changes in v0.9 (D-055 to D-057, D-059):

* **Keyword table on the phone (D-055).** `:data` and `:core:fakes` each copy `contracts/category-keywords.csv` at build time (tasks `:data:copyCategoryKeywords` and `:core:fakes:copyCategoryKeywords`, registered as an AGP generated resource directory); a missing file fails the build. It is packaged as the Java resource `se/hagstedt/kvitt/data/category-keywords.csv` (and `se/hagstedt/kvitt/fakes/category-keywords.csv` for the fakes, debug only). There is no committed copy. A `:data` test asserts byte identity with the contract file and the §14.8 rules.
* **Enum declaration order (D-057).** `DefaultCategoryKey` is declared in AC-7.2 sort order. The Rust wire enum, the OpenAPI `DefaultCategoryKey` enum and the 0002 `CHECK` list the ten v1 keys, then `housing`, `insurance`, `children`, `fees`. Wire values are unaffected (lowercase names; the OpenAPI equality test compares enums as sets).
* **`ExpenseEditorOptions.frequentCategoryIds` (D-059).** Per active account: the active (non-archived, non-deleted) categories ordered by the number of non-deleted expenses in that account that use them, descending; ties by `sort_order` ascending; at most 5 entries; categories with no use in the account are left out (the list may be shorter or empty). Counted over every expense in the phone's Room copy (both users, imported and recurring included), so both phones show the same order after sync; it is not a per-phone history like AC-8.6's "last used on this phone". The flow re-emits when expenses or categories change; the editor reads it once when it opens and on an account change, so tiles do not move while the user looks at them. UI rule (design, not contract): the row shows the account's list, filled up to five from the remaining active categories in `sort_order`; the selected category takes the fifth place when it is not among them. Fallback until M12d lands: the selected category first, then the first active categories in `sort_order` up to five.
* **`CategoryRepository.deletable(id)` (D-059).** Computed from Room: false for a default category (`defaultKey != null`) or one used by a non-deleted expense or non-deleted recurring template (AC-7.6). The server stays the authority: `delete` can still return `Failed("category_is_default")` or `Failed("category_in_use")` (for example when the partner's new expense has not synced yet), and the UI shows the same reason inline. The editor picks the text from `deletable` and `defaultKey`: default → `settings_category_delete_blocked_default_short`; in use and archived → `settings_category_delete_blocked_in_use_archived`; in use and active → `settings_category_delete_blocked_in_use`. Fallback until M12d lands: for a custom category "Ta bort kategori" is enabled and `Failed("category_in_use")` shows the in-use reason inline after the tap. Both members are implemented in `:data` and `:core:fakes` (every fake scenario computes them from its own data) by M12d.

Readings fixed in v0.10 (D-060 to D-062, as landed by M12d `557af7e`; no type changes):

* **`frequentCategoryIds` holds only used categories (D-060).** Each list holds only categories actually used in that account, so it may have fewer than five entries or be empty. Filling up to five from `sort_order` and placing the selected category fifth is the editor's job (UX-9, `docs/ux/design-spec.md` §3.7), not the repository's.
* **`frequentCategoryIds` keys and ties (D-061).** The map has a key for every active account (an empty list when nothing was used there) and no key for an archived account. Ties: use count descending, then `sort_order` ascending, then category id ascending, so Room and the fakes give the identical order.
* **`deletable` edge cases (D-062).** `CategoryRepository.deletable(id)` emits false for an unknown or already deleted id. Archived categories follow the same AC-7.6 rule as active ones. In `:core:fakes`, `delete` and `deletable` share one rule function, so a fake never offers a delete it then refuses.

Changes in v0.30 and v0.31 (D-140, `c0f4345`; D-141, `1c9856b`):

* **`UpdateRepository.checkNow()` (D-140).** S-22's "Check for update" calls it: it always asks E-5, whatever the 6-hour throttle of `check()` says, and restarts that window; the automatic checks on cold start and resume keep calling `check()`. The default implementation calls `check()`, so the fakes are unchanged; debug builds return `UpToDate` without a request (AC-16.5). Refines AC-16.2 and AC-16.6.
* **`InsightsRepository` (D-141).** `trends(months: 1..24, measure)`, `forecast(measure)`; online only (§9.9): `Offline` is returned without a request, `Failed("network", null)` when the server cannot be reached, else the §14.3.2 code. Category and account resolved from Room, archived and deleted rows included, null when unknown; nothing is stored. `:data`: `api/AnalyticsDtos.kt`, two `KvittApi` calls, `repo/InsightsRepositoryImpl.kt` (through the online gate), bound in `DataModule`; `ExampleRoundTripTest` round-trips the E-34 and E-35 examples. `:core:fakes`: `FakeInsightsRepository`, `analytics/InsightsScenarios.kt`, scenario flag `insightsFailure`. S-11's section and its rules: §13.3 S-11, D-142, D-143.

Readings fixed in v0.11 (D-069, D-073 to D-075, as landed by M7a to M7f and M6b; no type changes):

* **`AnalyticsState.groups` order (D-069).** Unspecified; the UI does not rely on it. S-11 sorts legends and stacks itself: categories by `sortOrder`, accounts in `AccountRepository.all()` order.
* **`FieldError.field` values (D-074).** The model property names: `amountOre`, `description`, `notes`, `date`, `split`, `accountId`, `categoryId`, `allocations`, as `:core:fakes` and `:data` emit them.
* **`UpdateRepository.check()` (D-073, revised by D-092 in v0.13).** ~~Returns nothing; S-22 reads `UpdateState` afterwards and treats a still-`None` state as "up to date".~~ Returns an `UpdateCheck` since v0.13 (below).
* **Quick row fill (D-075).** The D-060 fill lives in `:core:design`'s `quickRowCategories(categories, frequent, selected)`; editors pass the raw `frequentCategoryIds[accountId]`. An empty or short list is filled from `sort_order`; the selected category takes the fifth place when absent. This replaces `docs/ux/design-spec.md` §3.7's interim "selected first, then `sort_order`" and the v0.9 fallback above.

Changes in v0.13 (D-086 to D-095, as landed by M12e `8c60715`):

* **`Pairing` (D-086).** `SessionRepository.pair` returns `OnlineResult<Pairing(user, inviteKind)>`, `inviteKind` read from the E-3 `invite_kind`; a wire value the app does not know is read as `DEVICE`, which leads to Home. S-1 goes to S-2 only for `InviteKind.PARTNER`. Fakes: `FakeScenario.pairingInviteKind` (null: `partner` for a member, `admin_setup` for the admin).
* **Admin name from the invite link (D-087).** Not a `:core:model` type: `:feature:onboarding`'s `InviteLink` reads the optional `from` parameter of both link forms into `PastedInvite.adminName`, `:app`'s `AppLink.Invite(serverUrl, code, adminName)` carries it to `PairingScreen(initialAdminName)` and `PairingViewModel.prefill(serverUrl, code, adminName)`. A name that is not a §9.6 display name (1 to 40 code points after trimming, no control characters) or not valid percent-encoding is dropped.
* **`SyncSummary.lastAttemptFailed` (D-088).** True when the last finished cycle started (`sync_state.last_attempt_at`) after the last success (`last_success_at`), or none ever succeeded, and no cycle is running; false while one runs. Computed in `:data`'s `SyncSummaries` (the two fixed-form timestamps compared as text); fakes take `FakeScenario.lastAttemptFailed`. `SyncStatusPill`, `syncPillVariant` and `syncLineText` dropped their `failed` parameter; S-16 shows "failed" when online and `lastAttemptFailed`.
* **`Rejection.actor` (D-089).** The user named by `updated_by_user_id` of the server's `current` row stored with the rejection (`sync_rejections.server_current`, §14.4.3), resolved to a household user; null when the server had no row or the user is unknown, and S-16's stale copy then names the partner. No protocol or Room change.
* **`Device.appVersionName` (D-090).** From the Device wire object's `app_version_name` (E-7, E-15, E-3); null until the device has sent `X-Kvitt-App-Version-Name`. `:data` sends the header on every call, the Coil picture requests included, with the `BuildConfig` `versionName`, omitted when it is blank, longer than 32 characters or not printable ASCII.
* **`NewRecurringTemplate` (D-091).** `RecurringRepository.create` takes the template fields without an id (E-28's body never had one); the server mints the id, which `create` returns; `update` keeps taking a `RecurringTemplate`.
* **`UpdateCheck` (D-092, revising D-073).** `check()` returns `UpToDate` (nothing newer published, a 404 from E-5 included, or within 6 hours of the last check that reached the server with nothing newer known), `Available(info)` or `Failed` (no answer or another error; `state` unchanged, and after no answer the next call tries again at once). Debug builds return `UpToDate` without a request (AC-16.5).
* **`SettleState.untouched` (D-093).** The accounts not in `lines` where the payer is owed (`payerNetOre > 0`), with nets that exclude the settlement being edited (AC-11.6), in `AccountRepository.all()` order; empty for a per-account settle-up. Computed in `:data` and in `:core:fakes` alike. Revises D-074's reading of Home balances.
* **`PushEvent` (D-095).** Lives in `:core:model` (`model/Push.kt`) as the project's own record; `:adapter:fcm` keeps `PushListener` and `PushMapping`, which maps the FCM data message into it.
* **Pictures** (v0.5 reading below) unchanged by assumption: no size parameter, E-11 always at 512.

Readings fixed in v0.5 (no type changes):

* **`OnlineResult.Failed("network", null)`.** A REST call that fails on the network (no answer from the server) returns code `network`, the one token outside §14.3.2, so the UI can show "Could not reach the server" (§9.9) rather than the `Offline` state, which means the call was not attempted (D-029).
* **No "update required" state.** `HomeState` has no field for a 426. After a 426 `protocol_unsupported` the phone stops syncing until the installed version code changes (§14.3.1, D-043); the update banner shows only when `UpdateState.Available` reports a newer published APK. Accepted.
* **Pictures.** `:data` always requests E-11 with size 512 and no size parameter is added to the UI contract: the owner confirmed on 2026-10-18 that the 128 size is not needed on the phone (the server keeps storing both, AC-4.4).
* **Choices documented in `:data` and accepted:** `Rejection.summary` (the rejected entity's own text) in `android/data/src/main/kotlin/se/hagstedt/kvitt/data/repo/SettingsRepositories.kt`; `FieldChange` display of `splits`, `allocations` and default category names in `.../data/repo/Timeline.kt`; `RecurringTemplate.draft.date` in `.../data/repo/SettingsRepositories.kt` (template mapping).

### 14.3 OpenAPI 3.1 outline

Milestone M1 writes `contracts/openapi.yaml` (OpenAPI 3.1.0, `info.title` `Kvitt`, `info.version` `1`, one server `https://{host}` (port 443, D-124; `https://{host}:8443` in v0.22) with the server variable `host`, default `kvitt.example.invalid` (reserved by RFC 6761), description "the owner-chosen Kvitt host name, SPEC §10.5" (D-123; was `https://icehack.asuscomm.com:8443`; no operation changed), security scheme `device` = HTTP bearer) from this outline. This outline is binding; the YAML file must not add or drop anything.

#### 14.3.1 Common rules

* Content type `application/json; charset=utf-8` for every request and response body, except: `PUT /me/picture` (request `image/jpeg`, `image/png` or `image/webp`, raw bytes), `GET /users/{user_id}/picture` (response `image/jpeg`), `GET /i/{code}` and `GET /cards/callback` (response `text/html; charset=utf-8`), `GET /apk/files/{file_name}` (response `application/vnd.android.package-archive`).
* Request headers the app sends on every call: `X-Kvitt-Protocol: 1`, `X-Kvitt-App-Version: <versionCode>`, `X-Kvitt-App-Version-Name: <versionName>` (optional for the server; stored per device at E-3 and on the hourly last-seen update, §8.2; blank or longer than 32 characters is ignored; declared on every operation through `CommonRules`, D-090), `Accept-Language: <device locale>`, and `Authorization: Bearer <token>` on authenticated endpoints. A request to an authenticated endpoint without `X-Kvitt-Protocol` or with a value other than `1` gets 426 `protocol_unsupported` (the app then stops syncing until its installed version code changes, and shows the update banner when a newer APK is published, §14.2.4). The protocol check comes before the token check.
* `X-Kvitt-App: <key>` is a proxy-level header, not part of the API contract: the release app sends it on every request when built with `kvitt.appKey`, NPM's app gate checks it (§8.5, D-126), and the server neither reads nor declares it (`contracts/openapi.yaml` unchanged).
* Every response carries `X-Kvitt-Server-Version: <crate version>`.
* A known path with a method it does not support gets 405 with an empty body (no error code; the only error response without the JSON error shape), the `X-Kvitt-Server-Version` header included. An unknown path gets 404 `not_found` with the JSON error shape.
* Unknown JSON fields in requests are ignored. Missing required fields or wrong types: 400 `invalid_request`. Values outside §9.6: 422 `validation_failed` with `field`. The §9.6 value limits are not expressed as JSON Schema constraints in `contracts/openapi.yaml`; the schema fixes types only, and breaking a limit gives 422 `validation_failed`.
* Optional fields in responses are present with `null`, never omitted. (One exception: accepted and rejected results in the `POST /sync` response have different key sets, as the §14.4.3 example shows.)
* `PATCH` bodies: every field optional; absent = unchanged; at least one field required (`invalid_request`).
* Path ids that are not a UUID: 404 `not_found`.

#### 14.3.2 Error shape and error codes

```json
{ "code": "validation_failed", "message": "amount_ore must be between 1 and 1000000000", "field": "amount_ore" }
```

`message` is English developer text and is never shown to users; the app maps `code` (and `field`) to localised strings. `field` is the JSON key concerned or `null`.

Exhaustive list:

| `code` | HTTP | Meaning |
|---|---|---|
| `invalid_request` | 400 | Malformed JSON, missing required field, wrong type, bad query parameter, empty PATCH |
| `invite_invalid` | 400 | Invite code unknown, expired, used, cancelled or malformed |
| `unauthorized` | 401 | Missing, malformed or unknown bearer token |
| `device_revoked` | 401 | The token's device is revoked |
| `forbidden` | 403 | Role does not allow the action (§8.4), or editing another user's profile |
| `not_found` | 404 | Unknown or deleted id in the path; unknown APK file; no APK published; no picture |
| `household_full` | 409 | Partner invite or accept when two users exist |
| `household_incomplete` | 409 | Account, template, expense or settlement write before the partner joined |
| `name_taken` | 409 | Account name already used by a non-deleted account |
| `account_not_empty` | 409 | Account delete while referenced (AC-6.5) |
| `category_in_use` | 409 | Category delete while referenced (AC-7.6) |
| `category_is_default` | 409 | Delete of a default category, or `name: null` on a non-default category |
| `cannot_revoke_current_device` | 409 | Revoke of the calling device |
| `no_accounts` | 409 | Settlement proposal with no non-deleted accounts |
| `cursor_ahead` | 409 | `GET /sync` with `since` greater than the server's current sequence value |
| `cards_unavailable` | 409 | Card connection asked for while the server has no Enable Banking application for the caller (E-37, CP-13, D-175) |
| `card_consent_expired` | 409 | Card refresh on an expired or disconnected connection (E-42, CP-6) |
| `expense_already_linked` | 409 | The expense is already linked from another card purchase of the caller (E-44, CP-9) |
| `payload_too_large` | 413 | Body over the limit of §8.6 |
| `unsupported_media_type` | 415 | Picture with another content type |
| `validation_failed` | 422 | A value breaks §9.6 or a split/settlement rule |
| `image_invalid` | 422 | Picture cannot be decoded or exceeds 8000 × 8000 |
| `batch_too_large` | 422 | Number of mutations in `POST /sync` outside 1 to 100 (D-036) |
| `protocol_unsupported` | 426 | Missing or unsupported `X-Kvitt-Protocol` |
| `rate_limited` | 429 | §8.6, with `Retry-After` |
| `internal` | 500 | Unexpected server error (logged with a request id, returned in `message`) |
| `card_bank_unavailable` | 502 | Enable Banking or the bank did not answer or refused (E-37; D-165) |
| `not_implemented` | 501 | Route registered but not yet implemented (only during milestones M2a to M4); attached to no operation in `contracts/openapi.yaml`. No longer produced by the server since the server overhaul (`6c405e1`); it stays in the enum and the contract |
| `unavailable` | 503 | Database busy beyond `busy_timeout`, or server shutting down |

Each endpoint below lists the codes it can return besides the always-possible `unauthorized`, `device_revoked`, `protocol_unsupported`, `rate_limited`, `internal`, `unavailable` (authenticated) or `rate_limited`, `internal`, `unavailable` (unauthenticated).

#### 14.3.3 Wire objects

All server-produced objects. `?` marks nullable (always present). Types: `string`, `int` (64-bit), `bool`, `ts` (fixed RFC 3339), `date` (`YYYY-MM-DD`), `period` (`YYYY-MM`), `uuid`.

```jsonc
// User
{ "id": uuid, "role": "admin" | "member", "display_name": string, "picture_version": int?,
  "created_at": ts, "updated_at": ts, "server_version": int }

// Device (only in /me, /devices, /invites/accept)
{ "id": uuid, "user_id": uuid, "name": string, "app_version_code": int?, "app_version_name": string?, "created_at": ts,
  "last_seen_at": ts, "revoked_at": ts?, "is_current": bool }

// Invite (code and link only in the POST /invites response; null in GET /invites)
{ "id": uuid, "kind": "admin_setup" | "partner" | "device", "target_user_id": uuid?,
  "code": string?, "link": string?, "created_at": ts, "expires_at": ts }

// Share (of an account default)
{ "user_id": uuid, "share_bp": int }

// Account
{ "id": uuid, "name": string, "default_shares": [Share, Share], "created_by_user_id": uuid,
  "created_at": ts, "updated_at": ts, "archived_at": ts?, "deleted_at": ts?, "server_version": int }

// Category
{ "id": uuid, "default_key": "groceries" | "restaurants" | "housing" | "home" | "utilities" | "insurance" | "transport" |
  "travel" | "entertainment" | "health" | "children" | "shopping" | "fees" | "other" | null, "name": string?, "icon": string, "color": string,
  "sort_order": int, "created_at": ts, "updated_at": ts, "archived_at": ts?, "deleted_at": ts?, "server_version": int }

// Split (of an expense): share_bp null for mode exact
{ "user_id": uuid, "share_ore": int, "share_bp": int? }

// TemplateSplit: exactly one of share_bp / share_ore non-null; empty array for mode default
{ "user_id": uuid, "share_bp": int?, "share_ore": int? }

// Expense
{ "id": uuid, "account_id": uuid, "category_id": uuid, "amount_ore": int, "description": string, "notes": string,
  "expense_date": date, "payer_user_id": uuid, "split_mode": "default" | "ratio" | "exact" | "full",
  "splits": [Split, Split], "recurring_template_id": uuid?, "recurring_period": period?,
  "created_by_user_id": uuid, "updated_by_user_id": uuid, "created_at": ts, "updated_at": ts,
  "deleted_at": ts?, "server_version": int }

// Allocation
{ "account_id": uuid, "amount_ore": int }

// Settlement
{ "id": uuid, "from_user_id": uuid, "to_user_id": uuid, "amount_ore": int, "settlement_date": date, "note": string,
  "allocations": [Allocation, ...], "created_by_user_id": uuid, "updated_by_user_id": uuid,
  "created_at": ts, "updated_at": ts, "deleted_at": ts?, "server_version": int }

// RecurringTemplate
{ "id": uuid, "account_id": uuid, "category_id": uuid, "amount_ore": int, "description": string, "notes": string,
  "payer_user_id": uuid, "split_mode": "default" | "ratio" | "exact" | "full", "splits": [TemplateSplit, ...],
  "day_of_month": int, "start_period": period, "end_period": period?, "paused": bool,
  "last_generated_period": period?, "next_occurrence_date": date?, "created_by_user_id": uuid,
  "updated_by_user_id": uuid, "created_at": ts, "updated_at": ts, "deleted_at": ts?, "server_version": int }

// AuditEntry
{ "id": uuid, "entity_type": "expense" | "settlement", "entity_id": uuid, "action": "create" | "update" | "delete",
  "source": "app" | "recurring" | "import", "actor_user_id": uuid, "client_at": ts, "server_at": ts,
  "changes": [ { "field": string, "old": any?, "new": any? }, ... ], "server_version": int }

// Error
{ "code": string, "message": string, "field": string? }

// CardProvider (E-36; D-160): an entry of the card catalogue; available = the server can connect it for the caller (CP-13)
{ "id": string, "name": string, "issuer": string, "image_key": string, "available": bool }

// CardConnection (E-38, E-40, E-41, E-42; D-167). Only ever sent to its own user's devices. fetching: a fetch for it is
// running at the time of the response. No session id, account uid or provider reference is ever sent.
{ "id": uuid, "provider_id": string, "status": "active" | "expired" | "disconnected", "history_days": int,
  "valid_until": ts?, "last_fetch_at": ts?, "last_fetch_error": "bank_unavailable" | "rate_limited" | "consent_expired" | "failed" | null,
  "fetching": bool, "created_at": ts, "updated_at": ts, "card_version": int }

// CardPurchase (E-40, E-44; D-167, D-168). A tombstone has deleted_at set and its content erased (§14.1.3).
{ "id": uuid, "connection_id": uuid, "status": "pending" | "booked", "direction": "debit" | "credit",
  "purchase_date": date, "booking_date": date?, "amount_ore": int?, "original_amount": string?, "original_currency": string?,
  "merchant": string, "expense_id": uuid?, "ignored": bool, "created_at": ts, "updated_at": ts, "deleted_at": ts?,
  "card_version": int }

// CardAttempt (E-37, E-38; D-162). auth_url only in the E-37 response (null in E-38); connection once connected.
// failure stays a plain nullable string in the OpenAPI document, not an enum (D-187); its values are E-38's.
{ "id": uuid, "provider_id": string, "status": "pending" | "connected" | "failed" | "expired", "failure": string?,
  "auth_url": string?, "expires_at": ts, "connection": CardConnection? }
```

Arrays `splits` are sorted by `user_id`, `allocations` by `account_id`, `default_shares` by `user_id`.

#### 14.3.4 Endpoints

**E-1 `GET /health`** (none). 200:
```json
{ "status": "ok", "server_version": "0.1.0", "schema_version": 4, "db_ok": true }
```
`schema_version` comes from a constant in the server code (the version its embedded migrations produce), not from the database, so `/health` answers with the database down. When the database check (`SELECT 1`) fails: 503 with the same shape, `status` `"degraded"`, `db_ok` false. The OpenAPI document declares the 503 body as `oneOf` the health object or Error (an `unavailable` error from a shutting-down server is also possible).

**E-2 `GET /setup/status`** (none). 200 `{ "initialized": bool }`. `initialized` is true when a user with role `admin` exists (AC-1.5).

**E-3 `POST /invites/accept`** (none). Request:
```json
{ "code": "7K3MQX9D2HPA", "device_name": "Galaxy S26", "display_name": "Jacob" }
```
`display_name` is optional in the schema; it is required for `admin_setup` and `partner` (`invalid_request` if missing), ignored for `device`. 200:
```json
{ "token": "kvt_…", "invite_kind": "admin_setup" | "partner" | "device", "user": User, "device": Device, "household": [User, ...] }
```
`invite_kind` is the kind of the accepted invite (D-086); the app shows S-2 only after `partner` (AC-2.10). The new device's `app_version_code` and `app_version_name` come from the request headers (§8.2). Errors: `invalid_request`, `invite_invalid`, `household_full`, `validation_failed`.

**E-4 `GET /i/{code}?from=<name>`** (none). 200 HTML per AC-2.5, for any `code` string of 1 to 32 characters (validity is not checked). Otherwise 404 HTML, `GET /i/` with an empty code included. The optional query parameter `from` (the inviting admin's display name, set by E-12's link) is percent-decoded (`+` as space), trimmed and passed on only into the page's `kvitt://invite?server&code&from` link, never shown; a value that is not UTF-8, holds a control character or has more than 40 code points is dropped and the page still opens (D-087).

**E-5 `GET /apk/latest`** (none). 200 `latest.json` content (§10.6). Errors: `not_found` (nothing published).

**E-6 `GET /apk/files/{file_name}`** (none). 200 binary with `Content-Length`. Errors: `not_found`; 429 at 10 per minute per IP (§8.6).

**E-7 `GET /me`** (device). 200:
```json
{ "user": User, "device": Device, "household": [User, ...], "public_url": "https://<KVITT_PUBLIC_HOST>" }
```

The example (`contracts/examples/E-7-me/response.json`) has `"public_url": "https://kvitt.example.invalid"` (D-123, D-124).

**E-8 `PATCH /me`** (device). Request `{ "display_name": string }`. 200 `User`. Errors: `invalid_request`, `validation_failed`.

**E-9 `PUT /me/picture`** (device). Raw image body. 200 `User` (new `picture_version`). Errors: `payload_too_large`, `unsupported_media_type`, `image_invalid`.

**E-10 `DELETE /me/picture`** (device). 200 `User` (`picture_version` null). Idempotent. Leaves the `-removed` marker of §10.4 so the next upload gets a new version (D-030).

**E-11 `GET /users/{user_id}/picture?size=128|512&v=<picture_version>`** (device). 200 `image/jpeg`, `ETag: "<picture_version>"`, `Cache-Control: private, max-age=31536000, immutable`. `size` defaults to 512; other values `invalid_request`. `v` is a cache key only and is ignored. Errors: `not_found` (unknown user or no picture), `invalid_request`.

**E-12 `POST /invites`** (admin). Request `{ "kind": "partner" | "device", "target_user_id": uuid? }` (`target_user_id` is optional and nullable in the schema, absent meaning null; it is required for `device` and must be null for `partner`). 201 `Invite` with `code` (12 characters, no hyphens) and `link` (`<public_url>/i/<code>?from=<percent-encoded admin display name>`, D-087; the app also reads links without `from`; the example's `link` is `https://kvitt.example.invalid/i/4N8RVT2KW6ZC?from=Jacob`, D-123, D-124). Errors: `forbidden`, `invalid_request`, `household_full`, `not_found` (target user).

**E-13 `GET /invites`** (admin). 200 `{ "invites": [Invite, ...] }` (pending only: not accepted, not cancelled, not expired; `code` and `link` null). Errors: `forbidden`.

**E-14 `DELETE /invites/{invite_id}`** (admin). 204. Idempotent for already cancelled. An already accepted invite also answers 204 and nothing changes. Errors: `forbidden`, `not_found`.

**E-15 `GET /devices`** (device). 200 `{ "devices": [Device, ...] }` ordered by `created_at`, revoked included (with `revoked_at`).

**E-16 `DELETE /devices/{device_id}`** (device). 204. Revoking an already revoked device is 204. Errors: `not_found` (an unknown id, or, for a member, a device of the other user: D-156, security review L-10), `cannot_revoke_current_device`.

**E-17 `PUT /devices/current/push-token`** (device). Request `{ "fcm_token": string? }` (the key is required, its value nullable; null clears). A string must be non-empty: `""` is `invalid_request` (D-034); more than 512 characters after trimming is `invalid_request` with field `fcm_token` too (D-114, security review L-4). 204. Errors: `invalid_request`.

**E-18 `POST /accounts`** (device). Request:
```json
{ "name": "Vardag", "default_shares": [ { "user_id": "…", "share_bp": 5000 }, { "user_id": "…", "share_bp": 5000 } ] }
```
201 `Account`. Errors: `invalid_request`, `validation_failed`, `name_taken`, `household_incomplete`.

**E-19 `PATCH /accounts/{account_id}`** (device). Request `{ "name"?: string, "default_shares"?: [Share, Share] }`. 200 `Account`. Errors: `invalid_request`, `validation_failed`, `name_taken`, `not_found`.

**E-20 `POST /accounts/{account_id}/archive`**, **E-21 `POST /accounts/{account_id}/unarchive`** (device). No body. 200 `Account`. Idempotent: in the state already held the row is returned unchanged with no new `server_version` (D-034). Errors: `not_found`.

**E-22 `DELETE /accounts/{account_id}`** (device). 200 `Account` (tombstone). Errors: `not_found`, `account_not_empty`.

**E-23 `POST /categories`** (device). Request `{ "name": string, "icon": string, "color": string }`. 201 `Category`. Errors: `invalid_request`, `validation_failed`.

**E-24 `PATCH /categories/{category_id}`** (device). Request `{ "name"?: string | null, "icon"?: string, "color"?: string, "sort_order"?: int }` (`name: null` resets a default category's name). 200 `Category`. Reordering several categories is one PATCH per category whose `sort_order` changes. Errors: `invalid_request`, `validation_failed`, `not_found`, `category_is_default`.

**E-25 `POST /categories/{category_id}/archive`**, **E-26 `POST /categories/{category_id}/unarchive`** (device). 200 `Category`. Idempotent as E-20 and E-21 (D-034). Errors: `not_found`.

**E-27 `DELETE /categories/{category_id}`** (device). 200 `Category` (tombstone). Errors: `not_found`, `category_in_use`, `category_is_default`.

**E-28 `POST /recurring-templates`** (device). Request: the `RecurringTemplate` fields `account_id`, `category_id`, `amount_ore`, `description`, `notes`, `payer_user_id`, `split_mode`, `splits` (TemplateSplit, rules of §9.1: none for `default`; two bp entries for `ratio` and `full`; two öre entries summing to the amount for `exact`), `day_of_month`, `start_period`, `end_period`, `paused`; no `id`: the server mints it and returns it in the 201 body (D-091). 201 `RecurringTemplate`. If a period is already due (§9.5), the server generates it before responding. Archived accounts and categories are accepted (AC-6.4). Errors: `invalid_request`, `validation_failed` (also for an unknown or deleted `account_id` or `category_id`, with `field`), `household_incomplete`.

**E-29 `PATCH /recurring-templates/{template_id}`** (device). Any subset of the E-28 fields; `split_mode` and `splits` must be sent together. 200 `RecurringTemplate`. Errors: `invalid_request`, `validation_failed`, `not_found`.

**E-30 `DELETE /recurring-templates/{template_id}`** (device). 200 `RecurringTemplate` (tombstone). Errors: `not_found`.

**E-31 `GET /sync?since=<int>&limit=<int>`** (device). See §14.4.2. `since` is required (missing or negative: `invalid_request`); `limit` is optional. Errors: `invalid_request`, `cursor_ahead`.

**E-32 `POST /sync`** (device). See §14.4.3. Errors (whole request): `invalid_request`, `batch_too_large`, `payload_too_large`, `household_incomplete`.

**E-33 `POST /settlements/proposal`** (device). Request `{ "payer_user_id": uuid, "amount_ore": int, "exclude_settlement_id": uuid? }` (`exclude_settlement_id` optional and nullable, absent meaning null). 200:
```json
{ "allocations": [ { "account_id": "…", "amount_ore": 30000 } ], "excess_ore": 0, "over_settled_account_ids": [] }
```
Computed with `kvitt-domain::propose_allocation` over the server's non-deleted rows. Errors: `invalid_request`, `validation_failed`, `no_accounts`.

**E-34 `GET /analytics/trends?months=<int>&measure=<household|my_share>`** (device, read-only, D-133, D-138; operation `getAnalyticsTrends`). `months` 1 to 24, default 6; `measure` default `household` (AC-14.4). The two endpoints the D-134 brief named (averages, trends) are one. 200:
```json
{ "measure": "household", "today": "2026-10-17", "current_month": "2026-10", "months": 3,
  "household": Trend,
  "categories": [ { "category_id": "…", "trend": Trend } ] }
```
`Trend` = `{ "total_ore": int, "average_ore": int, "last_month_ore": int, "last_month_vs_average_pct": int?, "current_month_ore": int, "points": [ { "month": "YYYY-MM", "amount_ore": int, "moving_average_ore": int } ] }`: `points` are the `months` whole months before the current one, oldest first; `last_month_vs_average_pct` is null when the average is 0. `today` is the Europe/Stockholm date, `current_month` its `YYYY-MM`. Rules §14.5.7. Errors: `invalid_request` with `field` `months` or `measure`. Unknown query keys are ignored; the last occurrence of a key wins.

**E-35 `GET /analytics/forecast?measure=<household|my_share>`** (device, read-only, D-133, D-138; operation `getAnalyticsForecast`). `months` is not a parameter and is ignored like any unknown key. 200:
```json
{ "measure": "household", "today": "2026-10-17", "current_month": "2026-10",
  "accounts": [ { "account_id": "…", "current_month_ore": 12000,
                  "months": [ { "month": "2026-11", "recurring_ore": 4900, "baseline_ore": 40000, "forecast_ore": 44900 },
                              { "month": "2026-12", "recurring_ore": 0, "baseline_ore": 40000, "forecast_ore": 40000 } ] } ] }
```
One entry per non-deleted account (archived included), ordered by `created_at`, then id; `months` are always the two calendar months after the current one; `forecast_ore = recurring_ore + baseline_ore`. Rules §14.5.7. Errors: `invalid_request` with `field` `measure`.


**Card purchases (E-36 to E-44, D-158 to D-170).** Every authenticated card endpoint acts only on the caller's own user's rows (§8.4, CP-11): an id of the other user's connection, purchase or attempt is `not_found`. While the server has no card configuration at all, E-36 answers the catalogue with `available` false and the others behave as below. Rules in §9.12.

**E-36 `GET /cards/providers`** (device). 200 `{ "providers": [CardProvider, ...] }` in registry order (CP-1). Errors: none beyond the common ones.

**E-37 `POST /cards/auth`** (device). Request `{ "provider_id": string, "history_days": int, "client": "android" | "web" }`. Creates an attempt (CP-2) for a new connection or a renewal of the caller's existing one for that provider, calls Enable Banking `POST /auth` and answers 201 `CardAttempt` with `auth_url` and `status` `pending`. Errors: `invalid_request`, `validation_failed` (`history_days`, §9.6), `not_found` (unknown provider), `cards_unavailable` (no Enable Banking application for this user, CP-13), `card_bank_unavailable` (Enable Banking did not answer or refused, 502: when `GET /aspsps` or `POST /auth` fails, D-183; the OpenAPI document's `BadGateway` response).

**E-38 `GET /cards/auth/{attempt_id}`** (device). 200 `CardAttempt` (`auth_url` null). A `pending` attempt past `expires_at` is answered and stored as `expired`. `failure` is one of `cancelled` (the bank redirected with an error, the user cancelled), `no_account`, `bank_error` (the session could not be created), `state_invalid` (never sent to a client: an unknown state names no attempt). Errors: `not_found`.

**E-39 `GET /cards/callback?code=<code>&state=<state>`** (none; `?error=<error>&state=<state>` when the user cancels). 200 `text/html; charset=utf-8`, the page of §13.3 "Card callback page", for success and failure alike (the status code does not tell an attacker whether a `state` existed); `Cache-Control: no-store`, `Referrer-Policy: no-referrer`. Never logged with its query (§8.7, §10.5.2). Not in `contracts/openapi.yaml`'s JSON error shape: a malformed query also answers the failure page. Rate limit §8.6. The attempt rules (expired, used, no `code` and no `error`, the atomic claim, a session without accounts) are CP-2's (D-184).

**E-40 `GET /cards/sync?since=<int>&limit=<int>`** (device). The caller's card rows with `card_version > since`, in one read transaction, like §14.4.2: 200
```json
{ "since": 0, "next_since": 41, "has_more": false, "server_time": "2026-10-24T12:00:00.000Z",
  "connections": [CardConnection], "purchases": [CardPurchase] }
```
`next_since` is the highest `card_version` in the page, or `since` when empty; rows are counted together across both arrays, ordered by `card_version`, up to `limit` (default 500, max 1000); tombstones included. Errors: `invalid_request`, `cursor_ahead` (`since` greater than the current `card_sequence` value).

**E-41 `PATCH /cards/connections/{connection_id}`** (device). Request `{ "history_days": int }`, only a value ≤ the current one (CP-3; a longer one is a renewal through E-37). 200 `CardConnection`; the current value answers the unchanged connection with its existing `card_version`, no new version (D-187). Errors: `invalid_request`, `validation_failed`, `not_found`.

**E-42 `POST /cards/connections/{connection_id}/refresh`** (device). No body. Fetches with the user present (CP-5), at most once per 60 seconds per connection; waits up to 25 seconds. 200 `{ "connection": CardConnection, "fetched": bool }` (`fetched` false when the 60-second rule answered without contacting the bank, or the fetch is still running, then `connection.fetching` is true). A fetch that fails is recorded in `last_fetch_error` and still answers 200. Errors: `not_found`, `card_consent_expired` (status `expired` or `disconnected`, 409).

**E-43 `DELETE /cards/connections/{connection_id}?erase_handled=<bool>`** (device). Disconnects (CP-12); `erase_handled` defaults to false. 200 `CardConnection` (status `disconnected`). Idempotent on a disconnected connection: no new version of it, but `erase_handled=true` still erases its linked and ignored purchases (D-187). Errors: `invalid_request`, `not_found`.

**E-44 `PUT /cards/purchases/{purchase_id}`** (device). Request `{ "expense_id": uuid?, "ignored": bool }` (both keys required). Sets the link and the ignore flag (CP-9); the rules of §9.6. A credit purchase can be neither linked nor ignored: `validation_failed` with `field` the key wrongly set (`expense_id` when it is not null, else `ignored`, D-187). 200 `CardPurchase` with a new `card_version`, or the unchanged row with its existing `card_version` when nothing changes (idempotent). Errors: `invalid_request`, `validation_failed`, `not_found` (the purchase, or with `field` `expense_id` an unknown or deleted expense), `expense_already_linked` (409, another purchase of the caller links that expense).

#### 14.3.5 Examples as contract

M1 writes one JSON example per request and response body above, plus one per error code, in `contracts/examples/<E-id>-<name>/{request,response}.json` and `contracts/examples/errors/<code>.json`, and the sync examples of §14.4. Directory names are `E-<n>-<kebab-name>` (for example `E-1-health`, `E-32-sync-push`). The server's tests serialise its responses for the same fixtures and compare; the app's `:data` tests decode every example into its DTOs and re-encode it, comparing JSON values. The server's test harnesses seed the two users after the fourteen category seeds, so the users have `server_version` 15 and 16; `E-7-me/response.json` shows those values and its test compares them (D-058). E-34 and E-35 have response examples only (`E-34-analytics-trends/response.json`, `E-35-analytics-forecast/response.json`, v0.29, D-138); `tools/contracts-check.py` checks that the operations are exactly E-1 to E-35 (136 checks at `50a0d67`); since v0.35 E-1 to E-44 (K1; 157 checks at `671c00d`, 17 of them `match_card_purchase` cases), with request and response examples for E-36 to E-38 and E-40 to E-44 (`E-36-card-providers`, `E-37-card-auth`, `E-38-card-attempt`, `E-40-card-sync`, `E-41-card-connection-update`, `E-42-card-refresh`, `E-43-card-disconnect`, `E-44-card-purchase-update`) and one per new error code. E-39 returns HTML like E-4: it is in `contracts/openapi.yaml` with a `text/html` response and has no JSON example.

### 14.4 Sync protocol v1

#### 14.4.1 Principles

* The server is the authority. The phone keeps a full copy and a cursor.
* Every synced row carries `server_version` from one global sequence (§14.1). The cursor is the highest `server_version` the phone has applied.
* Phones push only expenses and settlements. Everything else changes through REST and comes back through pull (the REST response is also written locally at once).
* Card connections and purchases (D-161) are not part of this protocol: they are the holder's private rows with their own cursor (`card_version`, E-40) and their own writes (E-44); `X-Kvitt-Protocol` stays `1`. The phone runs its card cycle after each household cycle (§14.2.4).
* Conflict rule: per row, last write wins on the client `updated_at`; ties go to the server's copy; **deletes are final and always win**.
* Pushes are idempotent per `mutation_id`.
* Tombstones are kept forever on both sides and are synced like any other row.
* A sync cycle is: push all pending rows (in batches), then pull until `has_more` is false. One cycle at a time per process (a `Mutex` in the sync engine; WorkManager unique work names `kvitt-sync` for one-off work, policy `APPEND_OR_REPLACE`, and `kvitt-sync-periodic` for the periodic work, policy `KEEP`; WorkManager cannot share one unique name between periodic and one-off work, D-028). Triggers in AC-15.3; pushes go in batches of 100, pulls in pages of 500.

#### 14.4.2 Pull: `GET /sync?since=N&limit=L`

Server, in one read transaction per page (so the cursor check and the page see one snapshot):

0. `N` missing or negative, or `L` outside 1 to 1000: 400 `invalid_request`.
1. If `N` > current `sync_sequence.value`: 409 `cursor_ahead`.
2. Select the `L` (default 500, max 1000) rows with the lowest `server_version > N` across `users`, `categories`, `accounts`, `recurring_templates`, `expenses`, `settlements`, `audit_log` (a `UNION ALL` of `(server_version, table, id)` ordered by `server_version`), including tombstones. An expense with its splits, a settlement with its allocations, an account with its default shares and a template with its splits each count as one row.
3. Respond 200:

```json
{
  "epoch": "30b85fb529aac0016dc91650841005b9",
  "since": 0,
  "next_since": 512,
  "has_more": true,
  "server_time": "2026-10-17T12:00:00.000Z",
  "users": [User],
  "categories": [Category],
  "accounts": [Account],
  "recurring_templates": [RecurringTemplate],
  "expenses": [Expense],
  "settlements": [Settlement],
  "audit_entries": [AuditEntry]
}
```

`next_since` is the highest `server_version` in the page, or `N` when the page is empty. `has_more` is true when rows with `server_version > next_since` exist. Every array is present (possibly empty) and sorted by `server_version`.

Phone, per page, in one Room transaction:

1. If `sync_state.epoch` is non-null and differs from `epoch`: discard the page and run epoch recovery (§14.4.8).
2. Apply arrays in this order: `users`, `categories`, `accounts`, `recurring_templates`, `expenses`, `settlements`, `audit_entries`.
3. For each row: if the local row exists and has `server_version` ≥ the incoming one, skip. For `expenses` and `settlements`: if the local row is `pending`, skip (the push will resolve it). Otherwise upsert the row, replace its child rows, set `local_updated_at`. Audit entries are insert-or-ignore.
4. Set `sync_state.cursor = next_since`, `sync_state.epoch = epoch`.

Repeat while `has_more`. Then set `last_success_at`.

A 409 `cursor_ahead` answer to a pull is treated as epoch recovery (§14.4.8): cursor 0, epoch cleared, every local expense and settlement marked pending with a new `pending_mutation_id`, and the cycle restarted (D-026).

#### 14.4.3 Push: `POST /sync`

Request (1 to 100 mutations, body ≤ 1 MiB):

```json
{
  "mutations": [
    {
      "mutation_id": "01929c5e-6c1f-7d3a-9b2e-4f5a6b7c8d9e",
      "entity_type": "expense",
      "entity": {
        "id": "01929c5e-1111-7aaa-8bbb-000000000001",
        "account_id": "…", "category_id": "…", "amount_ore": 41200, "description": "ICA Maxi", "notes": "",
        "expense_date": "2026-10-16", "payer_user_id": "…", "split_mode": "default",
        "splits": [ { "user_id": "…", "share_ore": 20600, "share_bp": 5000 }, { "user_id": "…", "share_ore": 20600, "share_bp": 5000 } ],
        "created_at": "2026-10-16T17:02:11.123Z", "updated_at": "2026-10-16T17:02:11.123Z", "deleted_at": null
      }
    },
    {
      "mutation_id": "…",
      "entity_type": "settlement",
      "entity": {
        "id": "…", "from_user_id": "…", "to_user_id": "…", "amount_ore": 50000, "settlement_date": "2026-10-16", "note": "",
        "allocations": [ { "account_id": "…", "amount_ore": 50000 } ],
        "created_at": "…", "updated_at": "…", "deleted_at": null
      }
    }
  ]
}
```

The pushed `entity` contains exactly the client-writable fields: for expenses `id`, `account_id`, `category_id`, `amount_ore`, `description`, `notes`, `expense_date`, `payer_user_id`, `split_mode`, `splits`, `created_at`, `updated_at`, `deleted_at`; for settlements `id`, `from_user_id`, `to_user_id`, `amount_ore`, `settlement_date`, `note`, `allocations`, `created_at`, `updated_at`, `deleted_at`. Server-owned fields (`server_version`, `created_by_user_id`, `updated_by_user_id`, `recurring_template_id`, `recurring_period`) are ignored if sent. A delete is the full entity with `deleted_at` set. Every pushed id (`mutation_id`, `entity.id` and every id inside the entity) must be a UUID in the canonical form of the conventions (lowercase, hyphenated, 36 characters); another spelling of a valid UUID is not accepted (D-037).

Response 200, one result per mutation in request order:

```json
{
  "server_time": "2026-10-17T12:00:00.000Z",
  "results": [
    { "mutation_id": "…", "entity_type": "expense", "entity_id": "…", "status": "accepted", "server_version": 913, "entity": Expense },
    { "mutation_id": "…", "entity_type": "settlement", "entity_id": "…", "status": "rejected", "reason": "stale",
      "message": "a newer version exists", "current": Settlement }
  ]
}
```

`entity` and `current` are full wire objects (§14.3.3) or, for `current`, `null` when the server has no row with that id. Accepted and rejected results have different key sets exactly as in the example (accepted: `mutation_id`, `entity_type`, `entity_id`, `status`, `server_version`, `entity`; rejected: `mutation_id`, `entity_type`, `entity_id`, `status`, `reason`, `message`, `current`); this overrides the "present with `null`" rule of §14.3.1 for these objects. `server_version` is the row's version after processing.

#### 14.4.4 Server processing of one mutation

The whole request runs in one `BEGIN IMMEDIATE` transaction; each mutation in its own `SAVEPOINT`, rolled back on rejection. Pushes are enqueued after commit. Before the transaction, the whole request is checked: 0 or more than 100 mutations is 422 `batch_too_large` (D-036); a mutation whose `mutation_id` or `entity.id` is not a canonical UUID, or whose `entity_type` is not `expense` or `settlement`, makes the whole request fail with 400 `invalid_request` (without these keys no per-mutation result can be formed, D-035). Steps, in order:

1. **Replay.** If `mutation_id` exists in `sync_mutations`, return the stored `result` unchanged (no other effect).
2. **Household.** Fewer than two users: the whole request fails with 409 `household_incomplete` before any mutation.
3. **Shape.** Every other shape error (missing fields, wrong types, unknown enum values, ids that are not canonical UUIDs, timestamps not in the fixed form): `rejected`, `validation_failed`, per mutation (D-035).
4. **Clock.** `updated_at` > server now + 10 minutes: `rejected`, `clock_skew`.
5. **Load** the stored row by `id`.
6. **Stored row is a tombstone.** If the pushed entity is also a delete: `accepted`, no change, no audit, no push (idempotent delete). Otherwise `rejected`, `deleted`, `current` = the tombstone.
7. **Pushed entity is a delete** (`deleted_at` non-null):
   * Stored row exists: set `deleted_at` = pushed `deleted_at`, `updated_at` = the later of stored and pushed `updated_at`, keep every other stored field, `updated_by_*` from the caller, new `server_version`, audit `delete` with `changes` `[{"field":"deleted_at","old":null,"new":<deleted_at>}]`, push `*_deleted`. `accepted`. This applies even when the pushed `updated_at` is older (deletes always win). For an expense, in the same savepoint, every non-deleted card purchase linked to it gets `expense_id` null, `updated_at` = server now and a new `card_version` (CP-9, D-169), so its holder sees it under "Att hantera" again; nothing about it is audited or pushed.
   * No stored row (created and deleted before it ever synced): run the full validation of step 8 (field rules, domain rules and references), so the tombstone satisfies the schema; on failure `rejected` as in step 8. Otherwise insert the row as a tombstone with a new `server_version`, no audit, no push. `accepted` (D-037).
8. **Validate**, in this order: the field rules of §9.6, then the domain rules of §9.1 (expenses) or §9.4 settlement validity (settlements), then references: `account_id`, every allocation `account_id`, `category_id` must exist and not be deleted (`reference_not_found` otherwise; archived is fine); user ids must be household users (`validation_failed`). Failure: `rejected` with that reason, `current` = stored row or null.
9. **No stored row:** insert with `created_by_user_id` = `updated_by_user_id` = caller's user, `updated_by_device_id` = caller's device, `server_received_at` = now, new `server_version`; audit `create` with every diff field (`old` null); push `*_created`. `accepted`.
10. **Stored row exists, pushed `updated_at` ≤ stored `updated_at`:** `rejected`, `stale`, `current` = stored row.
11. **Stored row exists, newer:** compute the diff (§14.4.7). Empty diff: change nothing (not even `updated_at`), no audit, no push, `accepted` with the stored row and its existing `server_version`. Otherwise update fields and children, `updated_by_*` from the caller, new `server_version`, audit `update` with the diff, push `*_updated`. `accepted`. `recurring_template_id`, `recurring_period`, `created_by_user_id` and `created_at` keep their stored values (a pushed `created_at` is ignored on update, D-037).
12. Store `(mutation_id, device_id, entity_type, entity_id, result JSON, now)` in `sync_mutations`, for accepted and rejected results alike (step 1 then replays it).

Every rejection, at steps 3 and 4 too, carries `current` = the stored row with that `id`, or `null` when there is none (D-037).

#### 14.4.5 Phone push procedure

1. Read pending expenses and settlements ordered by `local_updated_at` ascending; take up to 100. Build each mutation from the row with `mutation_id = pending_mutation_id`.
2. `POST /sync`. On a network error or 5xx: stop the cycle, keep everything pending, let WorkManager retry with exponential backoff starting at 30 seconds. On 401 `device_revoked`: AC-3.3. On 401 `unauthorized`: `SessionState.Unrecognised` (§14.4.8). On 429: retry as for 5xx. On 426: stop syncing until the installed version code changes (§14.3.1). A push refused as a whole (400 `invalid_request`, 413 `payload_too_large`, 409 `household_incomplete`, 422 `batch_too_large`) counts as a batch with no progress: the cycle goes on to pull and records the code in `sync_state.last_error_code` (D-040).
3. Apply results in one Room transaction:
   * `accepted`: if the row's `pending_mutation_id` still equals the sent `mutation_id`, overwrite the local row with `entity`, set `pending = false`, `pending_mutation_id = null`. If it differs (edited again during the request), set only `server_version`, `created_by_user_id`, `updated_by_user_id` from `entity` and leave it pending.
   * `rejected` with `current` equal to the pushed entity in every client-writable field: treat as `accepted` with `current` (no rejection record). This covers re-pushes of an already stored state.
   * other `rejected`: if `pending_mutation_id` still matches, overwrite the local row with `current` (or delete the local row and its children if `current` is null), set `pending = false`, and insert a `sync_rejections` row with the pushed entity as `rejected_payload`. If it no longer matches, insert the rejection record only and leave the newer local edit pending. Reason `clock_skew`: do not overwrite and do not clear pending; give the row a new `pending_mutation_id` (the server stored the rejection under the old one and would replay it), set `sync_state.clock_skew = true` and stop the cycle (D-027). Re-stamp (D-094, revising D-027 as implemented by M12e): when `sync_state.clock_skew` is set at the start of a cycle, every pending expense and settlement whose `updated_at` is later than the phone's clock now gets `updated_at` = now (and a tombstone's `deleted_at` too, when it is later than now), in one Room transaction before pushing; rows stamped no later than now are untouched, so a row stamped by a clock that is still ahead is refused again until the clock is fixed, and a corrected clock heals it. Room schema unchanged.
4. Repeat until no pending rows remain or a batch made no progress, then pull.

#### 14.4.6 Rejection reasons

| `reason` (exhaustive) | When | Phone's user-facing explanation (S-16) |
|---|---|---|
| `stale` | Someone saved a newer version first | "Your change was replaced by a newer change from <actor>"; <actor> is `Rejection.actor`, the `updated_by_user_id` of the stored `current` (`sync_rejections.server_current`), the partner when unknown (D-089) |
| `deleted` | The row was deleted | "This was deleted before your change arrived" |
| `validation_failed` | The row breaks a rule (should not happen with a correct phone) | "This change was not valid and was not saved" |
| `reference_not_found` | Its account or category was deleted | "Its account or category no longer exists" |
| `clock_skew` | Phone clock more than 10 minutes ahead | "Your phone's clock is wrong. Fix it and sync again" |

For every reason S-16 can show what was lost: `Rejection.lost` is decoded from `sync_rejections.rejected_payload` and shown read-only (§13.3 S-16, D-109).

#### 14.4.7 Audit diff

Diff fields and their JSON value types:

| Entity | Field | Value |
|---|---|---|
| expense | `account_id`, `category_id`, `payer_user_id` | string (uuid) |
| expense | `amount_ore` | int |
| expense | `description`, `notes` | string |
| expense | `expense_date` | string (date) |
| expense | `split_mode` | string (enum) |
| expense | `splits` | array of Split sorted by `user_id` |
| settlement | `from_user_id`, `to_user_id` | string (uuid) |
| settlement | `amount_ore` | int |
| settlement | `settlement_date` | string (date) |
| settlement | `note` | string |
| settlement | `allocations` | array of Allocation sorted by `account_id` |
| both (delete only) | `deleted_at` | string (ts) |

* `create`: one change per field above except `deleted_at`, `old` null, in the table's order.
* `update`: one change per field whose JSON value differs, in the table's order.
* `delete`: exactly the `deleted_at` change.
* `client_at` = the pushed `updated_at` (for `delete`, the pushed `deleted_at`); `server_at` = server now. Scheduler and importer use server now for both.

The phone renders `changes` with ids resolved to names (FR-12).

#### 14.4.8 Epoch recovery and re-pairing

* `sync_epoch` changes only when the owner runs `rotate-epoch` after a restore (§10.9).
* When a pull returns a different epoch, the phone, in one transaction: sets `cursor = 0`, stores the new epoch, and marks every local expense and settlement (tombstones included) `pending` with a new `pending_mutation_id`, keeping `updated_at`. It then runs a normal cycle: push everything (rows the restored server lacks are inserted, rows it has with older `updated_at` are updated, identical rows come back as `stale` with equal content and are silently accepted per §14.4.5), then a full pull.
* Devices paired after the restored backup do not exist on the restored server; their requests get 401 `unauthorized`. The app keeps its local data and shows S-1 with "Pair this phone again". After pairing with a new invite: if the user id equals the previous one, the local data is kept and the epoch-recovery push runs; otherwise local data is wiped first.

#### 14.4.9 Limits and timing

| Item | Value |
|---|---|
| Mutations per push | 100 |
| Rows per pull page | default 500, max 1000 |
| Debounce after a local write | 2 seconds |
| Periodic background sync | 15 minutes (WorkManager minimum), requires a connected network |
| FCM-triggered sync | expedited one-off work |
| Retry backoff | exponential from 30 seconds (WorkManager) |
| `sync_mutations` retention | 90 days, pruned daily at 04:00 Europe/Stockholm; rows with `received_at` strictly older than 90 days are deleted (D-021, D-039) |
| Tombstone retention | forever |
| Token lifetime | until revoked |
| Notification sync wait (AC-13.5) | 20 seconds |

With these values a phone offline for 14 days loses nothing: tokens do not expire, cursors stay valid (versions only grow), and idempotency records outlive any realistic retry.

### 14.5 Domain rules as pure functions

Implemented twice: Kotlin in `:domain` (package `se.hagstedt.kvitt.domain`, input and output types in `:core:model` package `se.hagstedt.kvitt.model.money`) and Rust in `kvitt-domain`. Both are pure (no I/O, no clock, no randomness, no locale) and must pass every vector in `contracts/test-vectors/`. Analytics and the category suggestion (§14.5.6) exist only in Kotlin; `next_occurrence_date` and the day clamping exist only in Rust (D-015). The rules themselves are §9.1, §9.3 and §9.4; this section fixes signatures, error tokens and the vector format.

#### 14.5.1 Types

Ids are plain strings in domain inputs (the vectors use short ids like `"a"`, `"b"`, `"x"`; implementations must not assume UUID format). Money is `Long` / `i64` öre; bp is `Int` / `u32`. Because bp is `u32` in Rust, negative bp is unrepresentable there and the vectors contain none; `bp_out_of_range` means a value above 10000. All domain functions, analytics included, receive only non-deleted rows; excluding tombstones is the caller's job and is tested in `:data` and the server, not in the vectors.

Kotlin (`:core:model`, package `se.hagstedt.kvitt.model.money`):

```kotlin
sealed interface SplitSpec {
    data class Ratio(val bp: Map<String, Int>) : SplitSpec      // modes default and ratio
    data class Exact(val ore: Map<String, Long>) : SplitSpec    // mode exact
    data class Full(val bearerUserId: String) : SplitSpec       // mode full
}
enum class SplitError { AMOUNT_OUT_OF_RANGE, USERS_INVALID, PAYER_UNKNOWN, BP_OUT_OF_RANGE, BP_SUM_NOT_10000, EXACT_NEGATIVE, EXACT_SUM_MISMATCH, BEARER_UNKNOWN, SHARE_USERS_MISMATCH }
sealed interface SplitResult {
    data class Ok(val shares: Map<String, Long>) : SplitResult
    data class Err(val error: SplitError) : SplitResult
}

data class BalanceExpense(val accountId: String, val amountOre: Long, val payerUserId: String, val shares: Map<String, Long>)
data class BalanceSettlement(val fromUserId: String, val toUserId: String, val allocations: Map<String, Long>)   // accountId -> öre
data class Balances(val perAccount: Map<String, Map<String, Long>>, val global: Map<String, Long>)              // accountId -> userId -> net

data class AccountPosition(val accountId: String, val createdAt: String, val archived: Boolean, val payerNetOre: Long)
enum class AllocationError { AMOUNT_OUT_OF_RANGE, NO_ACCOUNTS }
data class Allocation(val accountId: String, val amountOre: Long)
sealed interface AllocationResult {
    data class Ok(val allocations: List<Allocation>, val excessOre: Long, val overSettledAccountIds: List<String>) : AllocationResult
    data class Err(val error: AllocationError) : AllocationResult
}

enum class SettlementError { AMOUNT_OUT_OF_RANGE, SAME_USER, USER_UNKNOWN, NO_ALLOCATIONS, TOO_MANY_ALLOCATIONS, ALLOCATION_NOT_POSITIVE, DUPLICATE_ACCOUNT, ALLOCATION_SUM_MISMATCH }
```

Rust (`kvitt-domain`):

```rust
pub enum SplitSpec { Ratio { bp: BTreeMap<String, u32> }, Exact { ore: BTreeMap<String, i64> }, Full { bearer_user_id: String } }
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")]
pub enum SplitError { AmountOutOfRange, UsersInvalid, PayerUnknown, BpOutOfRange,
    #[serde(rename = "bp_sum_not_10000")] BpSumNot10000,   // rename_all alone gives "bp_sum_not10000" (D-006)
    ExactNegative, ExactSumMismatch, BearerUnknown, ShareUsersMismatch }

pub struct BalanceExpense { pub account_id: String, pub amount_ore: i64, pub payer_user_id: String, pub shares: BTreeMap<String, i64> }
pub struct BalanceSettlement { pub from_user_id: String, pub to_user_id: String, pub allocations: BTreeMap<String, i64> }
pub struct Balances { pub per_account: BTreeMap<String, BTreeMap<String, i64>>, pub global: BTreeMap<String, i64> }

pub struct AccountPosition { pub account_id: String, pub created_at: String, pub archived: bool, pub payer_net_ore: i64 }
pub enum AllocationError { AmountOutOfRange, NoAccounts }
pub struct Allocation { pub account_id: String, pub amount_ore: i64 }
pub struct AllocationProposal { pub allocations: Vec<Allocation>, pub excess_ore: i64, pub over_settled_account_ids: Vec<String> }

pub enum SettlementError { AmountOutOfRange, SameUser, UserUnknown, NoAllocations, TooManyAllocations, AllocationNotPositive, DuplicateAccount, AllocationSumMismatch }
```

#### 14.5.2 Functions

| Function | Kotlin | Rust |
|---|---|---|
| Split | `fun computeSplit(amountOre: Long, payerUserId: String, userIds: List<String>, spec: SplitSpec): SplitResult` | `pub fn compute_split(amount_ore: i64, payer_user_id: &str, user_ids: &[String], spec: &SplitSpec) -> Result<BTreeMap<String, i64>, SplitError>` |
| Balances | `fun computeBalances(userIds: List<String>, accountIds: List<String>, expenses: List<BalanceExpense>, settlements: List<BalanceSettlement>): Balances` | `pub fn compute_balances(user_ids: &[String], account_ids: &[String], expenses: &[BalanceExpense], settlements: &[BalanceSettlement]) -> Balances` |
| Proposal | `fun proposeAllocation(amountOre: Long, accounts: List<AccountPosition>): AllocationResult` | `pub fn propose_allocation(amount_ore: i64, accounts: &[AccountPosition]) -> Result<AllocationProposal, AllocationError>` |
| Settlement check | `fun validateSettlement(amountOre: Long, fromUserId: String, toUserId: String, userIds: List<String>, allocations: List<Allocation>): SettlementError?` | `pub fn validate_settlement(amount_ore: i64, from_user_id: &str, to_user_id: &str, user_ids: &[String], allocations: &[Allocation]) -> Result<(), SettlementError>` |
| Over-settle warnings | `fun overSettledAccounts(allocations: List<Allocation>, accounts: List<AccountPosition>): List<String>` | `pub fn over_settled_accounts(allocations: &[Allocation], accounts: &[AccountPosition]) -> Vec<String>` |
| Recurring dates (D-015) | none | `next_occurrence_date` and the clamped occurrence date of a period (module `recurring.rs`); M2a fixes the exact signatures and lists them in its report |

Semantics beyond §9:

* `computeSplit`: `userIds` must have exactly 2 distinct entries (`users_invalid`); `payerUserId` must be one of them (`payer_unknown`); the `Ratio`/`Exact` map keys must equal `userIds` as a set (`share_users_mismatch`); `Full.bearerUserId` must be one of them (`bearer_unknown`); amount outside 1 to 1 000 000 000 is `amount_out_of_range`. Errors are checked in the order of the `SplitError` enum and the first failure is returned. The result map has both user ids. `Full` is computed as `Ratio` with bearer 10000 (so payer remainder rules apply trivially).
* `computeBalances`: inputs contain only non-deleted rows. `perAccount` has an entry for every id in `accountIds` (zeros included) and for any other account id referenced; each inner map has every id of `userIds`. `global` sums `perAccount`. Expenses' and settlements' account ids not in `accountIds` still count.
* `proposeAllocation`: `amountOre` outside 1 to 1 000 000 000 (§9.6) is `amount_out_of_range`. `accounts` are all non-deleted accounts with the payer's net per account (callers compute nets with `computeBalances`, excluding the settlement being edited). Errors in enum order. Allocations are in the order produced by §9.4. `overSettledAccountIds` lists the account that received `excessOre` (empty when `excessOre` is 0).
* `validateSettlement`: errors in enum order; `null` / `Ok(())` when valid. Reference existence is not checked here (the server checks it, §14.4.4).
* `overSettledAccounts`: ids, in allocation order, whose allocation exceeds `max(0, −payerNetOre)`; an allocation for an account not in `accounts` counts as net 0.
* Recurring dates (Rust only): the clamped date of period `YYYY-MM` for `day_of_month` 1 to 31 is that day, or the last day of the month when the month is shorter (§9.5, AC-9.2). `next_occurrence_date` takes the template's `day_of_month`, `start_period`, `end_period`, `last_generated_period`, `paused` and deleted state and returns the date defined in §9.5 (`null` when paused, deleted or past `end_period`). Pure: no clock, no time zone. No vector file covers them; M2a's unit tests cover every clamping case of AC-9.2 and the `null` cases.

#### 14.5.3 Error tokens on the wire and in vectors

Snake-case of the enum names: `amount_out_of_range`, `users_invalid`, `payer_unknown`, `bp_out_of_range`, `bp_sum_not_10000`, `exact_negative`, `exact_sum_mismatch`, `bearer_unknown`, `share_users_mismatch`, `no_accounts`, `same_user`, `user_unknown`, `no_allocations`, `too_many_allocations`, `allocation_not_positive`, `duplicate_account`, `allocation_sum_mismatch`. The server puts the token in the `message` of `validation_failed` errors and rejections; the phone uses it as `FieldError.error`. The token for a wrong bp sum is exactly `bp_sum_not_10000` on both sides (D-006): the Rust variant carries an explicit `#[serde(rename = "bp_sum_not_10000")]`, and the Kotlin side must emit the same string (the lowercase of `BP_SUM_NOT_10000`), never a token derived by a generic camel-to-snake conversion.

#### 14.5.4 Analytics (Kotlin only)

Types in `:core:model`, package `se.hagstedt.kvitt.model.analytics` (D-017); functions in `:domain`.

```kotlin
data class AnalyticsExpense(val date: LocalDate, val accountId: String, val categoryId: String, val amountOre: Long, val shares: Map<String, Long>)
data class DateRange(val start: LocalDate, val endInclusive: LocalDate)
enum class AnalyticsGranularity { MONTH, WEEK }
sealed interface AnalyticsMeasure { data object Household : AnalyticsMeasure; data class Share(val userId: String) : AnalyticsMeasure }
enum class AnalyticsGroupBy { CATEGORY, ACCOUNT }
data class Bucket(val key: String, val start: LocalDate, val endInclusive: LocalDate, val totals: Map<String, Long>, val total: Long)
data class SpendSeries(val buckets: List<Bucket>, val groupTotals: Map<String, Long>, val grandTotal: Long)

fun spendSeries(expenses: List<AnalyticsExpense>, range: DateRange, granularity: AnalyticsGranularity, measure: AnalyticsMeasure, groupBy: AnalyticsGroupBy): SpendSeries
fun resolveRange(preset: RangePreset, today: LocalDate, earliestExpense: LocalDate?, customStart: LocalDate?, customEnd: LocalDate?): DateRange
```

(`LocalDate` is `kotlinx.datetime.LocalDate`. `AnalyticsMeasure.Share` and `se.hagstedt.kvitt.model.Share` share a simple name; accepted, §14.2.4.)

* `spendSeries`: expenses outside the range are ignored. Buckets cover the range completely, in order, including empty ones. Month keys `YYYY-MM`, week keys `YYYY-Www` (ISO week-numbering year, week 1 contains the first Thursday). A bucket's `start`/`endInclusive` are clipped to the range. `totals` maps group id (category id or account id) to öre, omitting zero groups; `total` is their sum. Measure `Household` adds `amountOre`; `Share(u)` adds `shares[u]` (0 if absent). `groupTotals` sums over all buckets, omitting zeros.
* `resolveRange`: `THIS_MONTH` = first of the current month to `today`; `LAST_3_MONTHS`, `LAST_6_MONTHS`, `LAST_12_MONTHS` = first day of the month N−1 months before the current month to `today`; `THIS_YEAR` = 1 January to `today`; `ALL_TIME` = `earliestExpense` (or `today` when null) to `today`; `CUSTOM` = the custom dates, swapped if start > end. Expenses dated after `today` are therefore excluded from presets; a custom range may include future dates. `CUSTOM` with a null `customStart` or `customEnd` throws `IncompleteCustomRangeException`, a subclass of `IllegalArgumentException` declared in `:domain` (D-011); the caller (the `AnalyticsRepository` implementation in `:data`, and its fake) catches it and maps it to `validation_failed` (D-018; no vector covers it; in practice the repository resolves a missing custom date as today before calling, §14.2.4); `ALL_TIME` with `earliestExpense` after `today` gives the range `today`..`today`.

#### 14.5.5 Test-vector format

One file per function in `contracts/test-vectors/`: `compute_split.json`, `compute_balances.json`, `propose_allocation.json`, `validate_settlement.json`, `over_settled_accounts.json`, `spend_series.json` (Kotlin only), `resolve_range.json` (Kotlin only), `suggest_category.json` (Kotlin only, D-049), `match_card_purchase.json` (Kotlin and the web only, D-170, §14.5.8).

```json
{
  "format": 1,
  "function": "compute_split",
  "cases": [
    {
      "name": "50/50 odd amount, payer gets the extra öre",
      "input": {
        "amount_ore": 1001, "payer_user_id": "a", "user_ids": ["a", "b"],
        "spec": { "mode": "ratio", "bp": { "a": 5000, "b": 5000 } }
      },
      "expected": { "ok": { "a": 501, "b": 500 } }
    },
    {
      "name": "ratio does not sum to 10000",
      "input": {
        "amount_ore": 1000, "payer_user_id": "a", "user_ids": ["a", "b"],
        "spec": { "mode": "ratio", "bp": { "a": 5000, "b": 4000 } }
      },
      "expected": { "error": "bp_sum_not_10000" }
    }
  ]
}
```

Input keys are the snake_case parameter names of the Rust signatures. For the Kotlin-only analytics functions they are the snake_case names of the Kotlin parameters and fields: `spend_series` takes `expenses` (`[{"date", "account_id", "category_id", "amount_ore", "shares"}]`), `range` (`{"start", "end_inclusive"}`), `granularity`, `measure`, `group_by`; `resolve_range` takes `preset`, `today`, `earliest_expense`, `custom_start`, `custom_end`; `suggest_category` takes `description` (string), `history` (`[{"description", "category_id", "expense_date", "created_at"}]`), `keywords` (`[{"keyword", "match", "default_key"}]` in table order, `match` one of `token`, `prefix`, `phrase`), `active_categories` (`[{"id", "default_key"}]`, `default_key` null for a custom category) and `fallback` (category id or null), exactly as in `contracts/test-vectors/suggest_category.json` (`aa765bb`); the `unicode` parameter has no key (the test binds the platform implementation). `spec` is `{"mode":"ratio","bp":{…}}`, `{"mode":"exact","ore":{…}}` or `{"mode":"full","bearer_user_id":"…"}`. Outputs: `compute_split` `{"ok": {user: öre}}`; `compute_balances` `{"ok": {"per_account": {...}, "global": {...}}}`; `propose_allocation` `{"ok": {"allocations": [{"account_id","amount_ore"}], "excess_ore": n, "over_settled_account_ids": [...]}}`; `validate_settlement` `{"ok": null}`; `over_settled_accounts` `{"ok": [ids]}`; `spend_series` `{"ok": {"buckets": [{"key","start","end_inclusive","totals","total"}], "group_totals": {...}, "grand_total": n}}` with `measure` input `"household"` or `{"share": "a"}`, and dates as strings; `resolve_range` `{"ok": {"start","end_inclusive"}}`; `suggest_category` `{"ok": "<category id>"}` or `{"ok": null}` (it has no error case). Errors: `{"error": "<token>"}`.

Minimum cases M1 must include (more are welcome):

* `compute_split`: every row of the §9.1 example table; `full` on payer; `full` on non-payer; `exact` valid; `exact` sum mismatch; `exact` negative; amount 0; amount 1 000 000 001; amount 1 000 000 000 with 3333 bp; bp 10001; three user ids; payer not in users; map keys not matching users; one error case per `SplitError` value.
* `compute_balances`: empty; one account with the two expenses `(1001, payer a, 50/50)` and `(100, payer b, a 6000 bp)` giving `a` +440, `b` −440, then adding settlement `b → a 440` giving zeros; two accounts with opposite signs and a global sum; an account in `account_ids` with no rows (zeros).
* `propose_allocation`: payer owes in accounts X (created `2025-01-01T00:00:00.000Z`, net −30000), Y (`2025-02-01…`, −20000) and is owed in Z (`2024-12-01…`, +10000): amount 40000 gives X 30000, Y 10000, excess 0; amount 60000 gives X 30000, Y 30000, excess 10000, over-settled [Y]; amount 5000 with only Z gives Z 5000 over-settled [Z]; all accounts archived and none owing gives the oldest; equal `created_at` ordered by id; no accounts gives `no_accounts`; amount 0 gives `amount_out_of_range`.
* `validate_settlement`: one case per `SettlementError` value plus a valid case with 3 allocations and one with 50.
* `over_settled_accounts`: none, one, an unknown account.
* `spend_series`: monthly and weekly over a range crossing a year boundary (ISO week 2026-W53 exists: 28 Dec 2026 to 3 Jan 2027), household and share measures, category and account grouping, empty buckets, edge-clipped buckets.
* `resolve_range`: every preset with `today` = `2026-10-17`, `ALL_TIME` with and without an earliest expense, `CUSTOM` swapped.
* `suggest_category` (M12a): empty and punctuation-only descriptions (fallback); exact history match across case, `'`, `’`, `:` and other punctuation ("Willy:s" and "WILLYS"); most often beats most recent; ties broken by `expense_date`, then `created_at`, then category id; first-token match when no exact match; exact match taking precedence over first token; an archived category in history skipped (the next category, then the next step); `token`, `prefix` and `phrase` keywords; longest keyword wins; equal length, earlier entry wins; a keyword whose category is archived falls through to the next matching entry; a renamed default category found by its key; diacritics kept (`entre` and `entré` distinct); `&` and digits kept (`h&m`, `okq8`); NFC applied to non-NFC input; surrogate pairs counted as one code point; no match gives `fallback`; `fallback` null gives null. M12a's file has 65 cases.

#### 14.5.6 Category suggestion (Kotlin only)

The rule is §9.11 (D-049). Types and functions in `:domain`, package `se.hagstedt.kvitt.domain` (landed with M12a, `aa765bb`). The records live in `:domain`, not in `:core:model`: the keyword table is data, not a UI contract, and default keys are open strings there.

```kotlin
data class SuggestionHistoryEntry(val description: String, val categoryId: CategoryId, val expenseDate: LocalDate, val createdAt: String)
enum class KeywordMatch { TOKEN, PREFIX, PHRASE }
data class CategoryKeyword(val keyword: String, val match: KeywordMatch, val defaultKey: String)
data class ActiveCategory(val id: CategoryId, val defaultKey: String?)
interface UnicodeText {
    fun nfc(text: String): String
    fun isLetter(codePoint: Int): Boolean   // general category Lu, Ll, Lt, Lm or Lo
    fun isDigit(codePoint: Int): Boolean    // general category Nd
}

fun normalizeDescription(text: String, unicode: UnicodeText): String   // CS-4
fun parseCategoryKeywords(csv: String): List<CategoryKeyword>          // the §14.8 table; D-056
fun suggestCategory(description: String, history: List<SuggestionHistoryEntry>, keywords: List<CategoryKeyword>, activeCategories: List<ActiveCategory>, fallback: CategoryId?, unicode: UnicodeText): CategoryId?
```

(`CategoryId` is `se.hagstedt.kvitt.model.CategoryId`; `LocalDate` is `kotlinx.datetime.LocalDate`.)

* `UnicodeText` exists because pure modules may not use `java.*` and `kotlin.*` has neither NFC nor general categories. `:data` binds it with `java.text.Normalizer` (NFC) and `java.lang.Character` (`getType` for L and Nd); the `:domain` tests bind the same. `normalizeDescription` applies `nfc`, then `lowercase()`, then walks the string by code points (a surrogate pair is one code point), deleting `'`, `’` and `:`, keeping `&`, letters and digits, and turning every other code point into a space; then it collapses spaces and trims. Inputs need not be NFC; the vectors include non-NFC strings.
* `history` holds non-deleted expenses only (the caller's job, as for every domain function). Expenses whose `categoryId` is not in `activeCategories` are ignored (CS-5).
* History ranking (CS-5 steps 1 and 2): the highest count wins; on equal count, the category whose latest matching expense is latest by (`expenseDate`, then `createdAt`); then the lower category id (string order).
* Keyword ranking (CS-6): among the matching entries, the longest keyword in code points wins, then the earlier entry in table order (`keywords` are passed in table order, §14.8). An entry resolves to the active category with that `defaultKey`; none means the next entry in that ranking is tried.
* `parseCategoryKeywords` (D-056) reads the text of `contracts/category-keywords.csv`: header `keyword,match,default_key,source`, entries in file order (table order), `match` mapped to `KeywordMatch`; a malformed table (wrong header, wrong column count, unknown `match`) throws `IllegalArgumentException`. Pure; shared by `:data` and `:core:fakes`, which read the bundled resource (§14.2.4, D-055).
* `fallback` is the step-4 category id (AC-8.6), computed by the caller; it is returned as given when no earlier step applies, also when the normalised description is empty.

#### 14.5.7 Server analytics (Rust only, D-138)

The rules of E-34 and E-35 (D-133). Pure functions in `kvitt-domain` (module `analytics`, no clock, no time zone): `div_half_up`, `average`, `moving_average`, `percent_vs_average`, `occurs_in_period`, and the constant `MOVING_AVERAGE_WINDOW` = 3 (D-128's window, shared with the phone's `AnalyticsRules.MOVING_AVERAGE_WINDOW`; a change changes both). `kvitt-server` (`src/api/analytics.rs`) picks the months and sums in SQL per group and month; no vector file covers these rules (unit and integration tests do).

* **Months and today.** A month is the calendar month of the stored `expense_date` (`YYYY-MM-DD`, no time zone). "Today" is the Europe/Stockholm date. The whole months are the N months before the current month (E-34: N = `months`; E-35's baseline: N = 3). "Current month so far" runs from the 1st of the current month through today; expenses dated after today never count.
* **What counts.** Non-deleted expenses only; settlements never (AC-14.6); expenses in archived accounts and in archived or deleted categories do (AC-14.9). `household` adds full amounts, `my_share` the requesting user's shares (AC-14.4).
* **Averages.** Total of the N whole months ÷ N, empty months counting as 0, rounded half away from zero to öre (`div_half_up`: 3/2 = 2, −3/2 = −2; 0 for N = 0).
* **Percent.** `last_month_vs_average_pct` compares the last whole month with the rounded average: (last − average) × 100 ÷ average in whole percent, half away from zero, negative below the average; null when the rounded average is 0.
* **Moving average.** Trailing over 3 months: each point with the two before it; the first points average what exists (1, then 2 points), half away from zero.
* **Categories (E-34).** A category is listed only when it has a non-zero amount in a whole month or in the current month; ordered by `total_ore` descending, then category id. `household` is the sum over all categories.
* **Recurring (E-35).** Per account and forecast month, `recurring_ore` is the sum over the account's non-paused, non-deleted templates that occur in that month, once per template and month (templates are monthly only, on `day_of_month`, §9.5): `start_period` ≤ month, month ≤ `end_period` when set, and month > `last_generated_period` when set (`occurs_in_period`). For `my_share` it is the share a generation would write today (mode `default`: the account's current default ratio).
* **Baseline (E-35).** The account's spend over the last 3 whole months, expenses generated from a template excluded, ÷ 3, half away from zero (D-133); months without spend count, so a new account reads low. `current_month_ore` is the current month so far, generated expenses included.

#### 14.5.8 Card purchase matches (Kotlin and web only, D-170)

The rule is §9.12 CP-10. `:domain` (package `se.hagstedt.kvitt.domain`) and `web/src/lib/domain/`; not in Rust (the server never suggests matches). Pure: dates are passed in, no clock.

```kotlin
data class MatchablePurchase(val amountOre: Long?, val date: LocalDate, val direction: String)   // direction "debit" or "credit"
data class MatchableExpense(val id: String, val amountOre: Long, val date: LocalDate, val createdAt: String, val linkedByViewer: Boolean)
fun matchCardPurchase(purchase: MatchablePurchase, expenses: List<MatchableExpense>, windowDays: Int, max: Int): List<String>
```

* Returns the ids of the expenses with the purchase's `amountOre`, `|date − purchase.date| ≤ windowDays` and `linkedByViewer` false, ordered by the absolute day difference, then `createdAt` descending, then id ascending, at most `max`; empty for a `credit` purchase or `amountOre` null. CP-10 calls it with `windowDays` 3 and `max` 3; "Välj en annan utgift" is a different list (any amount, 14 days, CP-10) and has no vector. Callers pass non-deleted expenses only.
* Vectors (`match_card_purchase.json`, K1 writes them with a Python reference in `tools/contracts-check.py`; format §14.5.5, input keys `purchase` `{"amount_ore", "date", "direction"}`, `expenses` `[{"id", "amount_ore", "date", "created_at", "linked_by_viewer"}]`, `window_days`, `max`; output `{"ok": [ids]}`): no expenses; exact amount same day; ±3 days included, 4 days excluded; a different amount by 1 öre excluded; one linked by the viewer excluded; ordering by day difference, then `created_at`, then id; more than `max` candidates cut; a credit purchase; a null amount; a window across a month and a year boundary.

### 14.6 Push payload v1

FCM HTTP v1 message the server sends, one per target device (`POST https://fcm.googleapis.com/v1/projects/kvitt-1337/messages:send`):

```json
{
  "message": {
    "fid": "<device fcm_token>",
    "android": { "priority": "high", "ttl": "86400s" },
    "data": {
      "v": "1",
      "type": "expense_created",
      "entity_type": "expense",
      "entity_id": "01929c5e-1111-7aaa-8bbb-000000000001",
      "actor_user_id": "0192…",
      "count": "1"
    }
  }
}
```

`message.fid` holds the device's `fcm_token`, which is the Firebase Installation ID the phone registered (D-083, D-096). FCM HTTP v1 deprecates `message.token` ("Use fid instead"); `token`, `fid`, `topic` and `condition` are mutually exclusive, and the server sets only `fid`. The database column and the E-17 field keep the name `fcm_token`. `contracts/examples/push/*.json` use `fid`.

Data-only messages (no `notification` block), all values strings. Types (exhaustive):

| `type` | `entity_type` | `entity_id` | `actor_user_id` | `count` | Sent to |
|---|---|---|---|---|---|
| `expense_created` | `expense` | expense id | creator | `1` | other user's devices |
| `expense_updated` | `expense` | expense id | editor | `1` | other user's devices |
| `expense_deleted` | `expense` | expense id | deleter | `1` | other user's devices |
| `settlement_created` | `settlement` | settlement id | creator | `1` | other user's devices |
| `settlement_updated` | `settlement` | settlement id | editor | `1` | other user's devices |
| `settlement_deleted` | `settlement` | settlement id | deleter | `1` | other user's devices |
| `recurring_expense_created` | `expense` | expense id | template creator | `1` | both users' devices |
| `sync_batch` | `""` | `""` | pusher | number of notifiable changes, as a string | other user's devices |

Server sending rules:

* Sending happens on one background task fed by a bounded queue (capacity 100; when full, the oldest message is dropped with a warning log). It never delays an HTTP response.
* Authentication: the sender signs an RS256 JWT with header `kid` = the service account's `private_key_id`, exchanges it for an access token and caches the token until 5 minutes before its expiry (§6.3).
* Retries (D-038): one send plus up to three retries after 1 s, 5 s and 25 s (at most four sends) on 429, 5xx and network errors. On 401 the cached access token is dropped and that message is not retried; other 4xx are not retried. Retries run inside the single sender task, so one failing device can hold the queue for up to 31 s; accepted for two users.
* FCM `UNREGISTERED` or HTTP 404 for a token clears that device's `fcm_token`, only if the stored token is still the one that was sent (a token the phone replaced meanwhile is kept).
* Push is disabled (`NoopPushQueue`, one start-up warning) when the credentials file is missing or unusable (treated alike).

Phone handling (`:adapter:fcm`'s `PushMapping` maps the message to `PushEvent(type, entityType, entityId, actorUserId, count)`, a `:core:model` type in `model/Push.kt` since D-095; `:app` handles it in an expedited WorkManager job, D-085):

1. Call `syncForPush` and wait for it up to 20 seconds.
2. Build the notification text from Room per §13.3 copy (or the generic text if the sync failed or the entity or its actor is missing locally). Channel id `activity`, name "Activity" / "Aktivitet", importance default. Notification id = hash of `entity_id` (so an update replaces the create's notification); `sync_batch` uses id `1`.
3. Tap opens S-8 or S-10 for the entity; Home for deletions, `sync_batch` and the generic notification (D-085).
4. Unknown `type` or `v` other than `1`: sync only, no notification.

Card purchases send no push (D-161, D-171): nothing about a card purchase or connection is put in an FCM message, and no type is added; the payload stays version `1`. An expense created from a purchase sends `expense_created` like any other expense (AC-13.1). A notification for new card purchases is OQ-7.

### 14.7 Module layout and ownership map

Repository layout (paths are binding):

```
SPEC.md  CLAUDE.md  README-agents.md  PLAN-*.md
.gitea/workflows/      (Gitea Actions image build, M2c-pi)
contracts/
  openapi.yaml
  category-keywords.csv
  schema/server-v1.sql  schema/migrations/{0002_categories_v2.sql, 0003_device_version_name.sql, 0004_card_purchases.sql}
  test-vectors/*.json
  examples/<E-id>-<name>/{request,response}.json, examples/errors/<code>.json, examples/sync/*.json, examples/push/*.json
docs/  HANDOFF.md  decisions.md  ux/  spikes/ (spikes/k0/: K0's local test app, D-176)  validation/
prompts/
tools/  gradle-serial.sh  clean-builds.sh  install-git-hooks.sh  git-hooks/  dependency-report/  contracts-check.py
server/
  Cargo.toml (workspace)  Cargo.lock  Dockerfile  rust-toolchain.toml
  crates/kvitt-domain/  src/{lib.rs, split.rs, balance.rs, allocation.rs, settlement.rs, recurring.rs}  tests/vectors.rs
  crates/kvitt-server/  migrations/{0001_init.sql, 0002_categories_v2.sql, 0003_device_version_name.sql, 0004_card_purchases.sql}
                        src/{main.rs, lib.rs, config.rs, error.rs, router.rs, openapi.rs, auth.rs, time.rs}
                        src/db/{mod.rs, pool.rs, sequence.rs}
                        src/wire/{mod.rs, user.rs, device.rs, invite.rs, account.rs, category.rs, expense.rs, settlement.rs, recurring.rs, audit.rs, sync.rs, analytics.rs, card.rs}
                        src/api/{mod.rs, health.rs, setup.rs, invites.rs, landing.rs, me.rs, pictures.rs, devices.rs, accounts.rs, categories.rs, recurring.rs, proposal.rs, apk.rs, sync.rs, rate_limit.rs, rows.rs, validate.rs}
                        src/tasks/  src/sync/  src/audit/  src/push/
                        src/cards/{mod.rs, providers.rs, api.rs, fetch.rs, poller.rs, callback.rs}  src/cards/enable_banking/{mod.rs, mapping.rs}   (K1, D-160; the card wire types in src/wire/card.rs, the row helpers in src/cards/mod.rs, D-188)
                        src/cli/{mod.rs, bootstrap.rs, pair_device.rs, rotate_epoch.rs, healthcheck.rs, invite_partner.rs}
                        tests/  tests/common/{mod.rs, sync_fixtures.rs}  tests/cards_api/ (K1: against a local Enable Banking stub)   (shared harness, included through #[path] by every test binary)
  crates/kvitt-import/  src/  data/splitwise_categories.csv  tests/fixtures/
android/
  settings.gradle.kts  build.gradle.kts  gradle.properties  gradle/{libs.versions.toml, gradle-daemon-jvm.properties, wrapper/}
  build-logic/          (convention plugins, architecture check)
  core/model/  core/design/  core/fakes/  domain/  data/  adapter/fcm/
  feature/{onboarding, home, account, expense, settle, analytics, settings, cards}/
  app/
web/                   (the web client, D-131, §15)
  package.json  package-lock.json  vite.config.ts  tsconfig.json  eslint.config.js  index.html
  src/{app, api, i18n, design, components, lib}/   src/api/schema.d.ts (generated from contracts/openapi.yaml)
  src/features/{auth, home, accounts, expenses, search, export, settle, analytics, settings, cards}/
infra/
  build-images.sh  publish-apk.sh  README.md  RESTORE.md  .shellcheckrc  npm/kvitt.conf
  pi/{compose.yaml, .env.example, .gitignore}  pi/.env, pi/secrets/, pi/out/ (git-ignored)   (copied to /home/jacobhagstedt/kvitt on the Kvitt Pi, D-125)
  dev/{compose.yaml, .env.example, lib.sh, build.sh, up.sh, logs.sh, backup.sh, copy-google-services.sh}  dev/data/, dev/backups/ (git-ignored)
  backup/{Dockerfile, backup.sh, healthcheck.sh}  secrets/ (git-ignored)
```

Ownership (an agent edits only paths its milestone owns; anything else needs the orchestrator):

| Paths | Owner | After the owner lands |
|---|---|---|
| `SPEC.md`, `CLAUDE.md`, `README-agents.md`, `docs/HANDOFF.md`, `docs/decisions.md`, `PLAN-*.md`, `prompts/`, `tools/` (except `tools/contracts-check.py`) | docs agent briefed by the orchestrator | same |
| `contracts/**`, `tools/contracts-check.py` | M1 | contract-change plans only (§14.8) |
| `server/Cargo.toml`, `server/Cargo.lock`, every crate's `Cargo.toml`, `server/rust-toolchain.toml`, `server/Dockerfile`, `server/crates/kvitt-domain/**` | M2a | contract-change plans only for `kvitt-domain`; M3, M4 and M9 may add dependency lines to a crate's `Cargo.toml` (second to land resolves `Cargo.lock` on rebase) |
| `kvitt-server`: `migrations/`, `src/{main,lib,config,error,router,openapi,auth,time}.rs` (including the `serve` and `migrate` code), `src/db/**`, `src/wire/**`, `src/api/{mod,health,setup}.rs`, `src/cli/{mod,healthcheck}.rs`, M2a's own tests (any `tests/*.rs` without the prefixes `core_`, `sync_`, `scheduler_`, `push_`) | M2a | contract-change plans; M3/M4 may add one line per new module to `mod.rs` files they need; M3 edits the one marked rate-limit line in `router.rs` (D-015) |
| `kvitt-server`: `src/api/{invites,landing,me,pictures,devices,accounts,categories,recurring,proposal,apk,rate_limit}.rs`, `src/cli/{bootstrap,pair_device}.rs`, `tests/core_*.rs` (M3's tests are one binary, `tests/core_api/`) | M3 (M2a creates the shells, D-004) | later server plans |
| `kvitt-server`: `src/api/sync.rs`, `src/tasks/**`, `src/sync/**`, `src/audit/**`, `src/push/**`, `src/scheduler/**`, `src/cli/rotate_epoch.rs`, `tests/sync_*.rs`, `tests/scheduler_*.rs`, `tests/push_*.rs` (M4's tests are the binaries `tests/sync_api/`, `tests/push_fcm/`, `tests/scheduler_daily/`; its scheduler is `src/tasks/scheduler.rs`; there is no `src/scheduler/`; since the server overhaul (`8cb42f8`) every test binary includes the shared harness `tests/common/mod.rs` and `tests/common/sync_fixtures.rs` through `#[path]`, replacing `tests/core_api/common.rs` and `tests/sync_api/m4.rs`) | M4 (M2a creates the shells, the `tasks::start` stub and the `AuditWriter`/`PushQueue` traits with no-op implementations as described under "Server seams" in §6.3, D-004, D-015) | later server plans; the trait signatures change only with M3, M4 and M9 agreeing through the orchestrator |
| `server/crates/kvitt-import/**` | M9 (M2a creates a crate that builds with a usage-only `main.rs`, D-004) | same |
| `android/settings.gradle.kts`, `android/build.gradle.kts`, `android/gradle.properties`, `android/gradle/**`, `android/build-logic/**`, the module shells (build file, manifest, one empty entry composable per feature) of `:core:design`, `:data`, `:adapter:fcm` and every `:feature:*` (D-004) | M2b | later plans may add catalog entries and module includes (rebase resolves) |
| `android/core/model/**`, `android/domain/**` | M2b | contract-change plans only |
| `android/core/fakes/**` | M2b | M7x add files only under `fakes/<feature>/` |
| `android/core/design/**` | M6 (fix pass M6b, landed `b24c8b5`) | M7x may not edit; requests go through the orchestrator; later design plans |
| `android/data/**` | M5 (M2b created the Room 3 entities, `KvittDatabase` v1 and the exported schema, D-012) | later data plans; the exported schema is a contract file (§14.8) |
| `android/adapter/fcm/**`, `android/app/**` (after the M2b shell) | M8 | later integration plans |
| `android/feature/onboarding/**` | M7a | M7g (feature cleanups), later feature plans |
| `android/feature/home/**`, `android/feature/account/**` | M7b | M7g (feature cleanups), later feature plans |
| `android/feature/expense/**` | M7c | M7g (feature cleanups), later feature plans |
| `android/feature/settle/**` | M7d | M7g (feature cleanups), later feature plans |
| `android/feature/analytics/**` | M7e | M7g (feature cleanups), later feature plans |
| `android/feature/settings/**` | M7f | M7g (feature cleanups), later feature plans |
| `infra/**` | M2c-dev, then M2c-pi (D-001) | M10 updates runbooks |
| `.gitea/workflows/**` | M2c-pi (D-023) | later infra plans |
| git-ignored `infra/secrets/**` in the main checkout | M2c-dev (D-022), then M2c-pi | M8 copies `google-services.json` from it (§10.7) |
| `docs/ux/**` | U1, U2 | |
| M12 (D-054): `contracts/category-keywords.csv`, `contracts/schema/migrations/**`, `contracts/test-vectors/suggest_category.json` and the other `contracts/**` edits of §11.2 row M12a, `tools/contracts-check.py`, `android/domain/**` (`suggestCategory`, `UnicodeText`) | M12a (contract-change plan, landed `aa765bb`) | contract-change plans only |
| M12 (D-054): `contracts/openapi.yaml` (`DefaultCategoryKey`) and the category examples M12a held back; `kvitt-server` `migrations/0002_categories_v2.sql`, `src/db/mod.rs` (`SCHEMA_VERSION`), `src/api/validate.rs` (token lists), `src/wire/category.rs` and `src/wire/mod.rs` (key enum), their tests; `kvitt-import` `data/splitwise_categories.csv`, `src/categories.rs` and its tests | M12b (contract-change plan, landed `6eaccec`) | the usual owners |
| M12 (D-054): `android/core/model/**` (enums, icons, `ExpenseRepository`), `android/data/**` (`UnicodeText` binding, `suggestCategory`, the build-time copy of the keyword table, D-055), `android/core/fakes/**` (defaults, fake `suggestCategory`) | M12c (contract-change plan, landed `b09f322`) | the usual owners |
| D-059: `android/core/model/**` (`ExpenseEditorOptions`, `CategoryRepository`), `android/data/**` (`frequentCategoryIds`, `deletable`), `android/core/fakes/**` (both, outside the `fakes/<feature>/` folders) | M12d (contract-change plan, landed `557af7e`) | the usual owners; M7x keep their `fakes/<feature>/` folders |
| `web/**` except the feature folders below and `web/src/api/schema.d.ts`'s regeneration (D-134) | W0 | later web plans; W1 to W5 may add dependency lines to `web/package.json` (second to land resolves `web/package-lock.json` with `npm install` on rebase) |
| `web/src/api/schema.d.ts` (generated) | W0 | regenerated by whichever plan changes `contracts/openapi.yaml`, in the same landing (§15.3) |
| `web/src/features/home/**`, `web/src/features/accounts/**` | W1 (W0 creates the placeholder pages) | later web plans |
| `web/src/features/expenses/**`, `web/src/features/search/**`, `web/src/features/export/**` | W2 (W0 creates the placeholder pages) | later web plans |
| `web/src/features/settle/**` | W3 (W0 creates the placeholder page) | later web plans |
| `web/src/features/analytics/**` (W-9, W-10, W-11) | W4 (W0 creates the placeholder pages) | later web plans |
| `web/src/features/settings/**` | W5 (W0 creates the placeholder page) | later web plans |
| W7 (D-132, D-133): `server/**`, `contracts/**`, `tools/contracts-check.py`, `.gitea/**`, `infra/build-images.sh`, `infra/dev/**` | W7 (contract-change plan for `contracts/**`) | the usual owners |
| W6 (D-133): `android/feature/analytics/**`, and for the Insights contract `android/core/model/**`, `android/data/**`, `android/core/fakes/**` | W6 (contract-change plan, §14.8) | the usual owners |
| K0 (D-176): `docs/spikes/k0/**` (the test app of `2ce317f`; its key, config and state in the git-ignored `docs/spikes/k0/.local/`, root `.gitignore`), `docs/spikes/K0-enable-banking.md` | K0 | docs agent (the report is a deliverable, kept) |
| K1 (D-158 to D-175): `server/**`, `contracts/**`, `tools/contracts-check.py`, `infra/pi/compose.yaml`, `infra/pi/.env.example`, `infra/dev/**`, `infra/npm/kvitt.conf`, `infra/README.md` (step 4's block and the card runbook entry), and `web/src/api/schema.d.ts` for its regeneration only | K1 (contract-change plan for `contracts/**`) | the usual owners |
| K2 (D-169, D-170, D-172, D-173): `android/feature/cards/**` (new module), and as a contract-change plan `android/core/model/**`, `android/domain/**` (`matchCardPurchase`), `android/data/**` (Room 2, exported `2.json`), `android/core/fakes/**`; `android/core/design/**` (the fourth destination, `nav_cards`), `android/feature/account/**` (S-5's action), `android/feature/expense/**` (S-7's prefill, S-8's line), `android/feature/settings/**` (S-13's row), `android/app/**` (navigation, deep link, bindings), `android/settings.gradle.kts` and `android/gradle/libs.versions.toml` (the module and `androidx.browser`), `docs/ux/strings.csv` (the card keys of §13.3) | K2 | the usual owners |
| K3 (D-174): `web/src/features/cards/**` (new), and in W0's shared code the route, the sidebar entry and `web/src/lib/domain/` (`matchCardPurchase`); `web/src/features/expenses/**` (W-5's prefill, W-6's card line); `web/src/features/accounts/**` (W-3's "Från kortköp"); `web/src/features/settings/**` (W-13's row); the regenerated i18n dictionaries; as built also `web/src/api/cards.ts` and its test, `web/src/test/cards.ts`, `web/vite.config.ts` (`/cards` in the dev proxy), `web/scripts/gen-icons.mjs` and `web/src/design/icons.generated.ts`, `web/src/app/Shell.test.tsx` (ratified by the orchestrator at landing, `faeb752`) | K3 | later web plans |
| `docs/validation/<file>` | the milestone that names the file | |

Module shells (D-004): a shell file or module created by M2a or M2b in a path owned by a later milestone holds only what makes the build and the 501 stubs work; the later milestone owns it from the moment the shell lands and writes the body.

Strings: each feature module has its own `src/main/res/values/strings.xml` and `values-sv/strings.xml` with keys prefixed by the feature name; shared strings (the notification copy included) live in `:core:design`; `:app` holds only the app name; lint `MissingTranslation` is an error in every module (§6.2, D-017). Keys come from `docs/ux/strings.csv` (§13.4).

### 14.8 Contract files and the change rule

Contract files (exhaustive): `contracts/openapi.yaml`, `contracts/schema/server-v1.sql`, the locked migration texts `contracts/schema/migrations/*.sql` (0002 since D-054, §14.1.1; 0003 since D-090, §14.1.2; 0004 since D-167, §14.1.3, committed by K1), `contracts/category-keywords.csv`, `contracts/test-vectors/*.json`, `contracts/examples/**`, the Room exported schema `android/data/schemas/**` (version 1 exists since M2b, D-012; version 2 by K2, D-173), `android/core/model/**` (the UI contract and domain types), the sync protocol (§14.4) and the push payload (§14.6).

`contracts/category-keywords.csv` (D-049) is the keyword table of §9.11 CS-6: UTF-8 without BOM, `\n` line ends, header `keyword,match,default_key,source`, no quoting. `keyword` is non-empty and already normalised (CS-4 applied to it gives it back), unique in the file; `match` is `token`, `prefix` or `phrase`; a `token` or `prefix` keyword has no space and a `phrase` keyword has at least one; `default_key` is a key of AC-7.2 other than `other`; `source` is `data` (learned from the household's export) or `curated`, documentation only. Rows are sorted by `default_key`, then `keyword`, in code-point order. The phone bundles it through a build-time copy (D-055: `:data:copyCategoryKeywords` and `:core:fakes:copyCategoryKeywords`, no committed copy, a missing file fails the build, a `:data` test asserts byte identity and these rules, §14.2.4); M12a seeds the file from `docs/ux/category-keywords.csv` (148 entries). Changing an entry is a contract change like any other.

Representational edits to `contracts/openapi.yaml` (key order, `$ref` naming, description wording) do not change meaning and need no spec bump or decision entry; they are listed in the report of the plan that made them (D-016). The OpenAPI equality test compares parsed values, not text.

The equality test (`server/crates/kvitt-server/tests/openapi_contract.rs`, D-005) parses both documents and compares them after exactly these normalisations, every one representational; anything else that differs fails the test:

1. Key order is ignored (objects compared as maps).
2. Every local `$ref` is inlined, discriminator `mapping` values included, so component naming and placement do not matter.
3. `description` and `example`/`examples` keywords are dropped (properties named `description` are kept; `summary` and `operationId` are compared).
4. A nullable type array `type: [T, "null"]` equals `oneOf` with `{type: "null"}`; nested `oneOf`s are flattened and compared as sets.
5. `const: v` equals a single-value `enum: [v]`; `enum` values and `required` lists are compared as sets.
6. `required: false` and `deprecated: false` are dropped; a path parameter is always required.
7. Parameters are keyed by (`in`, `name`).
8. Each operation is compared on its effective security (its own `security`, else the document's).

The document-wide rules of §14.3.1 and §14.3.2 live in one place on the generated side, the `CommonRules` modifier in `server/crates/kvitt-server/src/openapi.rs`, never in a handler annotation: the common request headers and the `X-Kvitt-Server-Version` response header on every operation, the always-possible error responses of §14.3.2 (authenticated and unauthenticated sets), the document-level `device` security, and response headers marked required.

Rule: a change to any other contract file, or a semantic change to `contracts/openapi.yaml` or to §14 of this spec, requires, landed together by the orchestrator: a spec version bump (in the header and the change log), a `docs/decisions.md` entry, and the matching implementation changes on both sides, or a plan that schedules them. A schema change also bumps the schema version (`meta.schema_version` and a new migration on the server, whose locked text is the contract file `contracts/schema/migrations/<NNNN>_<name>.sql`, §14.1.1; there is no `server-v2.sql`, and `server-v1.sql` stays the text of 0001; a new Room version and migration on the phone). A sync protocol change bumps `X-Kvitt-Protocol`; a push payload change bumps `v`. Numbers come from the orchestrator's brief. Implementation agents never edit `SPEC.md` or `docs/decisions.md`: they put the proposed spec text and decision entry in their report, and the orchestrator has a docs agent record them (CLAUDE.md › Orchestration).

**Compatibility (v0.35, card purchases).** The K1 server (schema 4) works with every older APK and web build: they never call `/cards/*`. A K2 APK against a server before schema 4 gets 404 `not_found` from E-40 and shows the Kortköp tab's empty state, and E-36 fails, so S-24 shows its error state; nothing else changes. K1 is therefore deployed before the K2 APK is published, as M12e's rule below asks.

**Compatibility (v0.13, M12e).** The phone's DTOs give new wire fields no default, by design, so a phone running the M12e APK against a pre-M12e server (schema 2) cannot pair (E-3 lacks `invite_kind`) or list devices (Device lacks `app_version_name`). The server, the development stack included, is rebuilt and redeployed (migration 0003 runs at start) before the new APK is installed. Phones running an older APK work against the new server: they ignore the unknown fields and the server ignores a missing `X-Kvitt-App-Version-Name`.

---

## 15. Web client

Owner interview 2026-10-21 (D-129 to D-134). Kvitt has a web client, built in `web/` and served by `kvitt-server` under `/app/`. It is a second way into the same household: the same server, the same rules, the same data, read and written through the same API (§7, §14.3, §14.4). Nothing in the phone app changes because of it, except the Insights section of W6 (§15.8). This section is binding for the web plans W0 to W5 and for the web parts of W7; FR-21 holds the acceptance criteria.

**Status (2026-10-24, D-211).** W0 to W7 and W0b are landed; the web client is live at `https://kvitt.suorra.duckdns.org/app/` in image `v1.0.3`, paired from the owner's laptop browser and checked by the owner across its pages (§11.4). K3 (the card purchases of FR-22 on the web, W-21 to W-23) landed `faeb752` (D-201 to D-207, v0.40) and ships in image `v1.0.5`; its owner steps (PLAN-K3 §8) follow that deploy.

### 15.1 Scope (D-129)

* **Parity.** Everything the Android app does, except what only makes sense on a phone: the phone pairing flow (S-1's server field, `kvitt://` links, S-3 as a separate screen, S-18 as a separate screen), push notifications (FR-13), offline use and the sync screen (FR-15, S-16), the in-app update (FR-16, S-17). In: Home balances, account detail, account editor, expense add, edit and delete, expense detail with the audit timeline, settle up and settlement detail, analytics (S-11, S-12 with the D-128 line chart), categories, recurring templates, devices, profile, invite partner and pair a device (admin), about; and since v0.35 the card purchases of FR-22 (D-174, K3: W-21 to W-23), with BankID by QR in the desktop browser.
* **Extras the app lacks** (web only): free-text search across descriptions and notes with amount and date filters (W-12); CSV export of the filtered expense list (W-12); keyboard shortcuts `N` new expense, `/` search, `Esc` close, `?` help (W-20); a language choice (W-13).
* **Advanced analytics** (D-133) come from the server and are shown on the web (W-11) and later in the app (W6).
* **Form.** Designed desktop first and usable on a phone: one column under 720 px wide, a sidebar from 720 px. Swedish and English, like the app (G-8). Light and dark by `prefers-color-scheme`. Not a progressive web app: no service worker, no web app manifest, no offline use, nothing cached for offline.
* **Not in scope:** a receipt picture (none exists in the app, §2); the S-1 confirm step of OQ-6; anything §2 still lists.

### 15.2 Access and login (D-130)

* **Login.** A browser logs in with an invite code exactly like a phone pairs: E-3 `POST /invites/accept` with a `device` invite (the usual case: the owner creates one on S-21 or W-18 for himself or the partner), or a `partner` or `admin_setup` invite. The device name is `Web · <browser>` (the browser's name from the user agent, `Web` alone when unknown). `display_name` is sent when the login page's name field is filled; it is needed only for `partner` and `admin_setup` codes (E-3), and an `invalid_request` for a missing name shows the field's error. A pasted invite link (`https://<host>/i/<CODE>[?from=…]`) fills the code (§8.3 normalisation, as S-1). After a `partner` accept the web opens the profile page once (the S-2 step, AC-2.10); every other accept opens Home.
* **Token.** The bearer token is kept in the browser's `localStorage` and sent as `Authorization: Bearer <token>` on every API call (§8.2). It is never put in a URL, never logged, never shown. The browser is a device like a phone: listed on Devices (AC-3.1) with its name, revocable from another device like any device (AC-3.2), and a revoked or unknown token gets 401 (AC-3.3), on which the web forgets the token and shows the login page with the S-18 message (`device_revoked`) or the plain login page (`unauthorized`).
* **Log out** (W-13) forgets the token in this browser. The device stays on the Devices list, still valid, until it is revoked from another device, because a device cannot revoke itself (`cannot_revoke_current_device`, AC-3.2); the page says so. A sign-out endpoint that revokes the current device would be a contract change (§14.8) and is not part of v0.28.
* **First use** (owner, 2026-10-24, D-156): the web client is first used from a browser on the owner's laptop; the phones keep the app.
* **Headers** (§14.3.1): `X-Kvitt-Protocol: 1`; `X-Kvitt-App-Version` with the web build's version code and `X-Kvitt-App-Version-Name` with its version name (both from the build, W0; the name is at most 32 characters, so it shows on S-20 like a phone's); `Accept-Language` is the browser's own. No `X-Kvitt-App`: a browser cannot carry the app key (§8.5).
* **The NPM gate** (§8.5, §10.5.2, extends D-126). From outside the home LAN a request passes when it carries `X-Kvitt-App` with the key, comes from the LAN, is Let's Encrypt's challenge path, **or** its path is `/app` or starts with `/app/`, **or** its path is `/invites/accept`, **or** it carries an `Authorization: Bearer` header and its path does not start with `/health`, `/setup/`, `/i/` or `/apk/`. Everything else still gets 444. So the invite landing page (`/i/`), `/health`, `/setup/status` and the APK downloads stay LAN-or-key only, with or without a bearer header; the web client sends its bearer on API calls only.
* **Consequence (accepted).** The server's authenticated routes become reachable from the internet by anyone who sends some bearer token: a wrong token gets 401 `unauthorized` and counts against its address's unauthenticated limit of §8.6 (the H-1 fix, D-115, keeps junk tokens from ever counting as accepted), so the bound is 60 such requests per minute per address. `POST /invites/accept` is reachable from the internet and bounded by the 10-failures-per-hour lockout of AC-2.12 and the code's 60 bits (§8.3). The web client's static files are public (they hold no data and no secret). The security review's threat model (§8.1) assumed a reachable API before D-126; the gate stays a perimeter against scanners, and the device token stays the authentication.
* **Browser hardening.** The `/app/` pages get a Content-Security-Policy that allows only the server's own origin for scripts, styles, images (plus `blob:` and `data:`), fonts and API calls, with `frame-ancestors 'none'` (§10.5.2; the server sends the same policy itself on every `/app/` response, with `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY` and `Referrer-Policy: no-referrer`, D-135, so the development stack behaves as the Pi; behind NPM its `$kvitt_csp` header applies like the D-117 headers). No third-party script, font or CDN at run time: everything the page loads is in the image. `localStorage` is readable by any script on the origin, so the policy's `script-src 'self'` is what protects the token.

### 15.3 Stack and layout (D-131)

* `web/` at the repository root: Vite, React 19, TypeScript in strict mode, React Router 7, TanStack Query 5, `openapi-typescript` (types generated from `contracts/openapi.yaml` into `web/src/api/schema.d.ts`, generated and committed) and `openapi-fetch` as the API client, Recharts for charts, Vitest with Testing Library for tests, ESLint and Prettier, plain CSS modules. npm with a committed `package-lock.json`; Node 25 on the Mac. Exact versions are W0's, each the latest stable at the time (recorded in its report).
* **Design.** Tokens from `docs/ux/design-spec.md` §2 as CSS custom properties: the same colour roles (light and dark), category colours (§9.7), type scale, spacing, the 4/2 corner-radius language of the charts (D-097), the same icons (Material Symbols, Apache-2.0, bundled as SVG, never from a CDN). The typeface is the platform's system font stack (D-020's "no bundled font"), amounts with tabular figures. Components follow the design spec's anatomy where one exists (ledger rows, balance header, category tile, avatar, segmented controls); desktop layouts are W0's and each plan's, within the tokens.
* **Strings.** A small JSON dictionary per language (`sv.json`, `en.json`). A string that exists in `docs/ux/strings.csv` uses its key and its text; web-only strings get keys prefixed `web_` and are listed in the plan's report (they are not added to `strings.csv`, which is the app's). Placeholders are named (`{name}`), not Android format arguments. As built (W0, `web/README.md` "Strings"): `web/src/i18n/{sv,en}.json` are generated from `docs/ux/strings.csv` plus `web/src/i18n/web-strings.csv` (the shared web-only strings, W0's), with numbered placeholders `{1}`, `{2}` in place of `%1$s`; each feature keeps its own strings in `web/src/features/<name>/i18n/{sv,en}.json` (keys `web_<name>_…`), merged at build time; a string two features render moves to `web-strings.csv` (`83f5293`). Both languages always have every key; the gate checks it.
* **Language.** Swedish when the browser's preferred language is Swedish, English otherwise (G-8); W-13 offers a choice that overrides it in this browser (`localStorage`).
* **Money and dates.** Integer öre everywhere, formatting per §9.8 (the web formats with the same rules and the same outputs as the app for the same input). The money functions of §14.5.2 (`computeSplit`, `computeBalances`, `proposeAllocation`, `validateSettlement`, `overSettledAccounts`) exist in TypeScript and pass `contracts/test-vectors/*.json` for those functions in a Vitest test; `resolveRange` and `spendSeries` (§14.5.4) pass their vectors (W4), the category suggestion of §9.11 passes `suggest_category.json` (W2), `matchCardPurchase` (§14.5.8, `web/src/lib/domain/`) passes `match_card_purchase.json` (K3, listed as ported). The rules live in `kvitt-domain`, `:domain` and the web's ports of them; the vectors keep the three equal (G-1).
* **Source layout** (agreed for W0 to W5): `web/src/app/` (entry, providers, router with every route, layout shell, keyboard shortcuts), `web/src/api/` (generated schema, client, token store, household snapshot and writes, §15.5), `web/src/i18n/`, `web/src/design/` (tokens, global styles), `web/src/components/` (shared components), `web/src/lib/` (formatting, the money functions under `lib/domain/`, utilities), `web/src/features/<name>/` (one folder per feature plan, each with its own pages, components, tests and strings). Routes: `/app/` Home, `/app/login`, `/app/accounts/:id`, `/app/expenses/new`, `/app/expenses/:id`, `/app/settle`, `/app/settlements/:id`, `/app/analytics`, `/app/analytics/:groupKind/:groupId`, `/app/insights`, `/app/search`, `/app/cards` (K3, D-174), `/app/settings/*` (`/app/settings/cards` and `/app/settings/cards/:id` K3's); sub-routes and query parameters are the owning plan's.
* **As built (W0b, `5305f37`).** Shared web pieces live once in `web/src/components` (AccountTile, PageStates, Timeline, OverflowMenu, SwitchRow, `editor/`), `lib` (categories, timeline, accountColors), `api` (errors, invites) and `app` (useToday). A feature never imports another feature (`catalog.test.ts` also fails when a feature uses another feature's `web_` key). Amount fields follow the page language: sv `,` or `.` decimal with space grouping, en `.` decimal with `,` grouping. Recharts is its own chunk loaded by the analytics pages only (vendor 516 → 132 kB). The Vitest cache is off. The web's version code is the git commit count at build time, else `KVITT_VERSION_CODE`, else 1.
* **As built (K3, `faeb752`).** Shared card pieces: `web/src/api/cards.ts` (the card snapshot of §15.5 and the E-44 write, with `cards.test.ts`; in `api/` because W-21 to W-23, W-5, W-6, W-3 and W-13 read it), `web/src/test/cards.ts` (fixtures and the fake server's card endpoints), `/cards` in the dev proxy of `web/vite.config.ts`, the icons `credit_card`, `link_off` and `visibility_off` in `web/scripts/gen-icons.mjs` and the generated table, the query names `cardPurchase`, `attempt` and `provider` in `routes.ts` `QUERY` with the builders `cardsPath`, `connectCardPath` and `expensesNewPath({ cardPurchase })` (D-202). Web-only strings `web_cards_*` (load and catalogue failures, the catalogue's loading line, "Filter", the never-fetched failure, `expense_already_linked`, `card_bank_unavailable`, the empty "Välj en annan utgift" list) and `web_expenses_card_load_failed`, `web_expenses_card_missing_title`, `web_expenses_card_link_failed`; the rest are the §13.3 keys.
* **The web gate** (the third gate, beside the Android and server gates): `npm run check` in `web/`, which runs `tsc --noEmit`, `eslint .`, `vitest run`, `vite build` and the generated-types freshness check (it fails when `web/src/api/schema.d.ts` differs from what `openapi-typescript` generates from `contracts/openapi.yaml`). A change to `contracts/openapi.yaml` regenerates `web/src/api/schema.d.ts` in the same landing, by the agent that changes the contract; it is the one file under `web/` that a contract-change plan may write.

### 15.4 Build and serving (D-132)

* `server/Dockerfile` gets a Node stage that builds `web/` (`npm ci`, `vite build`); the runtime image carries `dist/` at `/app`. The build context becomes the repository root (`docker build -f server/Dockerfile .`), so the Gitea workflow, `infra/build-images.sh` and `infra/dev/**` change with it and the workflow's sparse checkout adds `web` (and `contracts` if the web build reads from it; W2's keyword table does, §15.7) (W7; as built §10.3, D-137). The web client is part of the server image and its version: there is no separate publish, no separate container and no change to `infra/pi/compose.yaml`; a deploy (§10.10) ships both.
* `kvitt-server` serves the files when the directory `KVITT_WEB_DIR` (default `/app`) exists: `GET /app/<file>` for files in it, `GET /app/` and every other path under `/app/` that is not a file get `index.html` (the client-side router handles the path), `/app` without the slash leads to `/app/`. Without the directory, `/app/*` is 404 `not_found`. As built (D-135, `50a0d67`, `src/api/web.rs`, a small handler without tower-http): `GET /app` → 308 to `/app/`; `/app/` and `/app/index.html` serve `index.html`; a safe path naming a file serves it; any other path falls back to `index.html`, except a missing file under `assets/`, which is 404 `not_found` (a vanished hashed asset must fail, not load HTML). `Cache-Control`: `assets/*` `public, max-age=31536000, immutable`, `index.html` `no-store`, other files `no-cache`. Every `/app/` response carries the CSP of NPM's `$kvitt_csp` web policy (§10.5.2) plus `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`. Path safety: at most 512 bytes and 8 segments, each 1 to 255 characters of `[A-Za-z0-9._-]` not starting with `.`; an unsafe path is never joined to the directory and falls back like a missing one. The routes are not in `contracts/openapi.yaml` (static files, not API). Rate limit §8.6 (D-136); `KVITT_WEB_DIR` §10.4.
* The development stack (`infra/dev`) serves the web client the same way, from its image. For work on the web client, `npm run dev` in `web/` runs Vite's dev server with `/app/` as its base and forwards API paths to a Kvitt server (W0 documents the setting); agents use a throwaway server (`cargo run -p kvitt-server -- serve` with a temporary `KVITT_DATA_DIR`), never the owner's development or Pi data.

### 15.5 Data: reads, writes, freshness

* **Reads.** Accounts, categories, templates, expenses, settlements, users and audit entries are readable only through `GET /sync` (§7). The web keeps an in-memory household snapshot built from it: after login and on every page load it pulls from `since=0` in pages until `has_more` is false and applies rows as §14.4.2 step 3 does (by `server_version`; the web has no pending rows); afterwards it pulls from its cursor on window focus and after every write. A different `epoch` or a 409 `cursor_ahead` drops the snapshot and pulls from 0. Nothing is persisted across a reload except the token, the language choice and per-viewer conveniences (a remembered filter); there is no IndexedDB copy. `GET /me` (E-7), `GET /devices`, `GET /invites` and the `/analytics/*` endpoints (D-133) are read directly.
* **Card purchases** (K3, D-201). The card snapshot (E-40) is held in memory beside the household snapshot, pulled from 0 on load, from its cursor on focus, every 60 s and after every card write; card writes are sent at once. A 409 `cursor_ahead` pulls it from 0; rows apply by `card_version`, tombstones included; only the viewer's own rows ever arrive (CP-11). W-21 re-reads it every 2 s while a connection is fetching or in its first fetch (CP-2's interval), otherwise at the shared 60 s (D-201). Refreshing it re-reads only the snapshot, not the catalogue (E-36) or an attempt (E-38) (`web/src/api/cards.ts`).
* **Computed in the browser**, as the phone does: balances (§9.3, `computeBalances`), effect lines (§9.2), the settle-up proposal (§9.4, `proposeAllocation`), the S-11 and S-12 analytics (§14.5.4) and the D-128 line chart. The advanced analytics of D-133 are not computed in the browser.
* **Writes.** Expenses and settlements are written with `POST /sync`, one mutation per user action (a new UUIDv7 id for a new row, a new `mutation_id` per attempt, the browser's clock for `updated_at`), and the result is applied to the snapshot at once: `accepted` updates the row; a rejection shows its §14.4.6 reason on the page and changes nothing. Everything else uses its REST endpoint (§7) and applies the returned row. The web never queues a write: a network error shows "Kunde inte nå servern" (`common_could_not_reach_server`) and the form keeps its values (§9.9's rule, for every write). Pictures (E-11) are fetched with the bearer header and shown from a `blob:` URL.

### 15.6 Screens

The web's pages. "Mirrors" names the app screen whose content, rules and states the page follows (§13.3 and `docs/ux/design-spec.md`); the web adapts layout to the desktop, not content. States per page: loaded, empty, loading (the first snapshot pull), error (a failed request, with retry), long content; there is no offline state.

| Id | Page | Route | Mirrors | Must show (beyond the mirrored screen) | Actions | Plan |
|---|---|---|---|---|---|---|
| W-1 | Login | `/app/login` | S-1 (code and name only), S-18's message | App name and one-line purpose; invite code field (12 characters in groups of 4, §8.3); name field for a first login; where the code comes from (S-21 on the owner's phone); errors `invite_invalid`, `rate_limited`, network | Log in | W0 |
| W-2 | Home | `/app/` | S-4; S-3 while there is no partner | Balance header, Settle up, active accounts with balance and this month's count, collapsed archived section (its open state kept for the page session, D-145), empty state with the "Du och <partner> är med" card in place of the balance header (D-145); no sync pill, no update banner, no pull to refresh | New expense (`N`), Settle up, open account, New account | W1 (`934eee7`) |
| W-3 | Account detail | `/app/accounts/:id` | S-5 | Month groups with month totals, expense and settlement rows, archived badge | New expense (`/app/expenses/new?account=<id>`), Settle this account (`/app/settle?account=<id>`, D-144), Edit, Archive / Unarchive, Delete; "Från kortköp" (`/app/cards?account=<id>`, while the viewer has a card connection, K3, AC-22.9) | W1 (`934eee7`) |
| W-4 | Account editor | `/app/accounts/new`, `/app/accounts/:id/edit` | S-6 | Name, default split with the 100,00 kr preview | Save, Cancel | W1 (`934eee7`) |
| W-5 | Expense editor | `/app/expenses/new` (`?account=<id>` presets the account, D-144), `/app/expenses/:id/edit` | S-7 | Amount, description, category grid with the §9.11 suggestion for a new expense, account, date, payer, split modes `default`, `ratio`, `exact`, `full` with live shares, notes; validation per §9.6 inline; a rejected or failed save in a banner with "Visa nuvarande version", the typed values kept; browser controls in place of S-7's keypad, slider and summary row (D-148) | Save, Delete (edit), Cancel (`Esc`, with the discard dialog); from a card purchase `?cardPurchase=<id>` (D-202) prefills per CP-9 and an accepted save links it with E-44: an unknown or deleted purchase shows "Kortköpet finns inte längre", a failed link keeps the expense and says "Utgiften sparades men kunde inte kopplas till kortköpet" (D-205; K3) | W2 (`a65ab71`); K3 (`faeb752`) |
| W-6 | Expense detail | `/app/expenses/:id` | S-8 | Every field, shares and mode, "Recurring: <template>", the audit timeline (AC-12.4, AC-12.5), deleted state; for the card holder the card line of AC-22.10 with the purchase date in the list form (D-206) | Edit, Delete; Ta bort koppling (K3) | W2 (`a65ab71`); K3 (`faeb752`) |
| W-7 | Settle up | `/app/settle` (`?account=<id>` one account, `?settlement=<id>` editing a payment, D-144) | S-9 | Direction with swap, amount, allocation rows with debts and over-settle warnings, allocation errors as you type (D-149), remaining indicator, add account, date, note, "Föreslå igen" | Confirm, Cancel | W3 (`f9a9bfb`) |
| W-8 | Settlement detail | `/app/settlements/:id` | S-10 | Payer, recipient, amount, date, note, allocations, timeline | Edit (`/app/settle?settlement=<id>`), Delete | W3 (`f9a9bfb`) |
| W-9 | Analytics | `/app/analytics` | S-11 | Range, granularity, measure, group-by; total; stacked bars with legend; category and account breakdowns; "Visa som tabell" under each chart, bar labels as keyboard stops (D-152) | Open a drill-down: a bar opens `/app/analytics/bucket/<key>`, a breakdown row `/app/analytics/:groupKind/:groupId`, the filter in the query string (D-151) | W4 (`1aecf51`) |
| W-10 | Drill-down | `/app/analytics/:groupKind/:groupId` (`groupKind` `category`, `account` or `bucket`; query `range`, `from`, `to`, `interval`, `measure`, `group`, `bucket`, D-151) | S-12 with D-128's line chart and average overlays | Title naming the filter, total, line chart for a category or account over the range, expense rows; its own period changes replace the query string (D-151) | Open expense | W4 (`1aecf51`) |
| W-11 | Insights | `/app/insights` | none (D-133) | Per-category averages and trends per month (overall and per category) over 3, 6 or 12 whole months (default 6, D-152), the 2-month forecast per account with its parts (recurring, average) | Choose category or account; choose months | W4 (`1aecf51`) |
| W-12 | Search | `/app/search` | none (D-129) | Free-text search in descriptions and notes (case-insensitive), filters for amount range, date range, account, category, payer, kept in the URL query string (D-147); result count and sum; expense rows | Open expense; Export CSV of the filtered list (format D-146) | W2 (`a65ab71`) |
| W-13 | Settings | `/app/settings` | S-13 | Own and partner's avatar and name; rows Profile, Categories, Recurring expenses, Devices, Invites (admin), About, Language; "Anslut kort" (S-13's row: none, connected with `valid_until` in the detail form (D-206), or `settings_cards_expired`; K3); Log out | Navigate; Log out | W5 (`3ebe57d`); K3 (`faeb752`) |
| W-14 | Profile | `/app/settings/profile` | S-14 (and S-2 once after a `partner` login, as an intro remembered per browser device in `kvitt.profileStepDone`, D-154) | Avatar with change and remove (file picker), display name | Save | W5 (`3ebe57d`) |
| W-15 | Categories | `/app/settings/categories`, editor `/app/settings/categories/new` and `/app/settings/categories/:id` (D-153) | S-15 | List with archived section; editor with name, reset name, 33 icons, 14 colours, delete or archive with the reason | Add, Edit, Reorder (drag, and by keyboard), Archive, Delete | W5 (`3ebe57d`) |
| W-16 | Recurring expenses | `/app/settings/recurring`, editor `/app/settings/recurring/new` and `/app/settings/recurring/:id` (D-153) | S-19 | List and editor as S-19 | Add, Edit, Pause / Resume, Delete | W5 (`3ebe57d`) |
| W-17 | Devices | `/app/settings/devices` | S-20 | Rows per AC-3.1; this browser marked as "This device" | Revoke (with confirmation; not this browser) | W5 (`3ebe57d`) |
| W-18 | Invites | `/app/settings/invite` (D-153; `/app/settings/invites` opens it too) | S-21 | Invite partner (before the partner joins) and pair a device; a created invite's code in groups of 4, link and expiry; pending invites | Create, Copy (code and link, to the clipboard), Cancel | W5 (`3ebe57d`) |
| W-19 | About | `/app/settings/about` | S-22 | The web build's version name and code; the server's version and schema from E-1 `/health` when it answers (on the LAN), otherwise the `X-Kvitt-Server-Version` header of a fresh `GET /me` without the schema (the S-22 fallback, D-110, D-154; `/health` is closed from outside, §15.2) | none | W5 (`3ebe57d`) |
| W-20 | Keyboard help | dialog on `?` | none (D-129) | The shortcuts and what they do | Close (`Esc`) | W0 |
| W-21 | Card purchases | `/app/cards` (`?attempt=<id>` after the bank's return, CP-2; `?account=<id>` from W-3's "Från kortköp", which shows the purchases to handle and presets that account for "Skapa utgift", as S-27) | S-23, S-27 (D-174) | The header card with artwork, "Uppdaterad", "Uppdatera"; filters; day groups; rows with the match chip; the purchase as a side panel from 720 px (a dialog below) with the S-23 sheet's actions; "Skapa utgift" opens W-5 at `/app/expenses/new?cardPurchase=<id>` (plus `&account=<id>` when W-21 was opened from an account; D-144's parameter style), prefilled per CP-9, and saving links the purchase; W-6 shows the card holder the line of AC-22.10; with `?attempt=` it polls E-38 until the attempt ends, then drops the parameter; states as S-23 without the offline one. As built: polling E-38 every 2 s; once `?attempt=` is dropped, a connected attempt shows the snackbar "Kortet är anslutet", a failed one a banner "Det gick inte att ansluta kortet" and an expired one "Anslutningsförsöket tog för lång tid", each with "Försök igen" to W-22 `?provider=` (D-204); E-40 re-read every 2 s while fetching (D-201); the expiring banner shows `valid_until` in the detail form (D-206); with `?account=` it is S-27: title "Från kortköp", rows open W-5 directly, no filter chips, no panel (D-207) | Uppdatera; filter; Skapa utgift; link; Välj en annan utgift; Ignorera; Ta bort koppling; Förnya med BankID | K3 (`faeb752`) |
| W-22 | Connect card | `/app/settings/cards` | S-24, S-25 (D-174) | The catalogue with artwork; for a card not connected, the history choice and "Anslut med BankID", which opens the bank's page in the same tab (BankID by QR on the computer); returning through the callback page's link lands on W-21. As built: `?provider=<id>` opens the connect step (S-25) for that card, also from "Förnya med BankID" (D-202); history 7, 30, 90 or 180 days; E-37 with `client` `web`; only an `https:` `auth_url` is followed, anything else shows "Det gick inte att ansluta kortet" (D-203); a connected card's tile shows `valid_until` in the detail form (D-206) | Anslut med BankID; open a connected card (W-23) | K3 (`faeb752`) |
| W-23 | Card connection | `/app/settings/cards/:id` | S-26 (D-174) | As S-26: status, `valid_until`, last fetch, history (a shorter one through E-41), the disconnect dialog with "erase handled purchases" (E-43 `erase_handled`) | Change history; Förnya med BankID (W-22 `?provider=`); Koppla från | K3 (`faeb752`) |

Navigation (W0): a sidebar from 720 px wide and a bottom bar under it, with Home, Card purchases (Kortköp, after Home, D-172, D-174; added by K3, `faeb752`), Analytics, Insights, Search and Settings; New expense is a button in the sidebar and on Home and account detail (the app's FAB). Dialogs close with `Esc`. Destination changes are instant (D-108).

### 15.7 Search, export and shortcuts (D-129)

* **Search** (W-12) runs in the browser over the snapshot (§15.5): non-deleted expenses whose description or notes contain the query, ignoring case; filters combine with AND. Settlements are not searched. Results sort by date, newest first. The query and filters live in the URL query string (`q`, `min` and `max` in öre, `from`, `to`, `account`, `category`, `payer`), so a search can be bookmarked (D-147).
* **CSV export** (W-12) downloads the filtered list as a file, one row per expense: date, description, category, account, payer, amount, each user's share, notes, with a header row in the page's language. The file format (D-146, W2 `a65ab71`): UTF-8 with a byte-order mark, `;` separator, CRLF, RFC 4180 quoting, amounts in kronor with a decimal comma and no grouping ("1234,50") in every page language, ISO dates, one share column per household user ("Andel <namn>"); a text cell starting with `=`, `+`, `-`, `@`, TAB or CR gets a leading `'`; file name `kvitt-utgifter-<YYYY-MM-DD>.csv` (Swedish) or `kvitt-expenses-<YYYY-MM-DD>.csv` (English). It opens correctly in Numbers and Excel with a Swedish locale. The export is built in the browser; the server has no export endpoint.
* **Keyboard shortcuts** (W0 binds them in the layout shell; the targets are the owning plans'): `N` opens W-5, `/` opens W-12 with the search field focused, `Esc` closes the open dialog or editor (with the discard rule of the mirrored screen), `?` opens W-20. `N`, `/` and `?` do nothing while focus is in a text field.
* **Category suggestion** (W-5, §9.11): the web ports the rule and passes `suggest_category.json`; the keyword table is read at build time from `contracts/category-keywords.csv` (the single source, never copied by hand), as the phone does (D-055); as built it is a raw import, allowed by `server.fs.allow` in `web/vite.config.ts` (D-148).

### 15.8 Advanced analytics on the server (D-133)

* Owner, 2026-10-21: "These calculations should be put in the backend because I will want to see this in the app as well." New read endpoints under `/analytics/*` (authenticated, any device), designed by W7: per-category averages and trends per month, overall and per category; and a forecast of the next 2 calendar months per account. As built (v0.29, D-138): E-34 `GET /analytics/trends` (averages and trends, household and per category; the two endpoints merged into one) and E-35 `GET /analytics/forecast` (§7, §14.3.4); averaging, rounding and month rules §14.5.7.
* **Forecast rule** (settled): for each account and each of the next two calendar months, forecast = the sum of the account's recurring templates due in that month (the known future expenses: active, not paused, inside their start and end periods, §9.5) + the average per month of the account's non-recurring spend (expenses not generated from a template) over the last 3 whole months. The 3-month window is the constant of D-128's trailing moving average (`AnalyticsRules.MOVING_AVERAGE_WINDOW`, 3, counted in buckets there and in whole months here), shared, not a second number; the server holds its own copy of the value and a change to it changes both.
* AC-14.1 is revised: the phone keeps computing S-11 and S-12 offline from Room; the advanced analytics come from the server, online only (§9.9), on the web (W-11) and in the app (W6, an "Insights" section on S-11; as built `1c9856b`, D-141 to D-143, v0.31).

### 15.9 Plans and parallel work (D-134)

Plans with disjoint paths (§14.7), one Opus agent each in its own worktree. W0 and W7 run first, in parallel; W1 to W5 run in parallel after W0 lands; W-11 (in W4) and W6 consume W7's endpoints once W7 has landed (W4 stubs W-11 until then). Web agents build with npm in their own worktree (`npm ci` in `web/`); Gradle and the phone are not involved, so W1 to W5 do not queue on `tools/gradle-serial.sh`; at most one `cargo` build per worktree (a throwaway server for a manual check).

| Plan | Paths | Content |
|---|---|---|
| W0 Web foundation | `web/**` except the feature folders of W1 to W5 | Scaffold, tokens, layout shell, router, login and token store, API client and household snapshot, i18n, formatting, shared components, money functions, test setup, the web gate; W-1, W-20 |
| W1 Home and accounts | `web/src/features/home/**`, `web/src/features/accounts/**` | W-2, W-3, W-4 |
| W2 Expenses and search | `web/src/features/expenses/**`, `web/src/features/search/**`, `web/src/features/export/**` | W-5, W-6, W-12, CSV export, the §9.11 port |
| W3 Settle up | `web/src/features/settle/**` | W-7, W-8 |
| W4 Analytics | `web/src/features/analytics/**` | W-9, W-10, W-11, the §14.5.4 port |
| W5 Settings | `web/src/features/settings/**` | W-13 to W-19 |
| W6 Android Insights | `android/feature/analytics/**`, and as a UI-contract change (§14.8) `android/core/model/**`, `android/data/**`, `android/core/fakes/**` | The D-133 endpoints on S-11 |
| W7 Server web serving and analytics | `server/**`, `contracts/**`, `tools/contracts-check.py`, `.gitea/**`, `infra/build-images.sh`, `infra/dev/**`, and `web/src/api/schema.d.ts` when it changes `contracts/openapi.yaml` | §15.4, §15.8 |
| K3 Web card purchases (D-174) | `web/src/features/cards/**`; in shared code the route, the sidebar entry and `web/src/lib/domain/` (`matchCardPurchase`); `web/src/features/expenses/**`, `web/src/features/accounts/**` and `web/src/features/settings/**` for W-5's prefill, W-6's card line, W-3's "Från kortköp" and W-13's row (§14.7) | W-21 to W-23; landed `faeb752` after K1 and K2 |


---

## 16. Change log

| Version | Date | Change |
|---|---|---|
| 0.1 | 2026-10-17 | First version, written from the owner interview: scope, requirements, data model, stack, API outline, security, business rules, deployment, milestones, UX sprint brief, contracts (schema v1, Room v1, OpenAPI outline, sync protocol v1, domain functions and vectors, push payload v1, ownership map). |
| 0.2 | 2026-10-17 | Owner answers. D-001: development-first deployment on the Mac; M2c split into M2c-dev (now) and M2c-pi (after M8, before M10); registry is Gitea at `http://gitea.lan` (OQ-1 answered). D-002: local backup files deleted as soon as confirmed on Drive. D-003: Splitwise CSV format confirmed for English and Swedish exports, Swedish category names mapped, accounts "Hemma" and "Vardag" (OQ-2 answered). OQ-4 answered (Drive folder id). §10, §11, §12, §14.7 updated. Clarifications from M1 (no new decisions): non-deleted rows only into domain functions, analytics vector keys, sync push result key sets, E-1 503 body, optional/nullable request fields of E-3, E-12, E-17, E-33, `since` required on E-31, proposal amount range, bp above 10000, `resolveRange` edge cases, §9.6 limits not in JSON Schema, example directory names, `not_implemented` on no operation (§14.3, §14.4.3, §14.5). |
| 0.3 | 2026-10-17 | Orchestrator resolutions of the plans' open points. D-004: M2a and M2b create shell files and modules in later milestones' paths, ownership of `Cargo.lock` and every `Cargo.toml` (§11.2, §11.3, §14.7). D-015: server seams: middleware in `router.rs`, rate limit in `src/api/rate_limit.rs` on one marked line, `src/tasks/` for M4, `AuditWriter`/`PushQueue` traits with no-op implementations, `next_occurrence_date` and day clamping in `kvitt-domain` (Rust only), M3 writes the recurring generation function, M4 lands after M3 (§6.3, §9.5, §11, §14.5.2, §14.7). D-016: the OpenAPI equality test compares parsed values; representational edits need no spec bump (§11.3, §14.8). D-017: feature convention, analytics types in `se.hagstedt.kvitt.model.analytics`, string placement and key prefixes, `MissingTranslation` in every module (§6.2, §13.4, §14.5.4, §14.7). D-018: empty fake scenario; `resolveRange` throws a typed `IllegalArgumentException` subclass for an incomplete `CUSTOM` range (§6.2, §14.5.4). D-019: ledger rows and expense editor fields in `:core:design` (§6.2, §11.2). D-020: no bundled font, Material 3 default typeface (§6.2, §13.4). D-021: `sync_mutations` pruning daily at 04:00 (§14.1, §14.4.9). D-022: development infrastructure as M2c-dev built it (`c885aba`): Firebase through the REST API with a gcloud token, no Firebase CLI, secrets and `google-services.json` in `infra/secrets/` copied by `infra/dev/copy-google-services.sh`, Firebase resources and the `kvitt-fcm` service account (`roles/firebasecloudmessaging.admin`) exist; dev stack without Caddy or TLS, bind-mounted data, `infra/secrets/` mounted at `/secrets`, env file `infra/dev/.env.example`, `healthcheck` used by compose; the server starts when `KVITT_TRUSTED_PROXY` does not resolve; new M2c-dev gate (§10 intro, §10.4, §10.7, §11.2, §14.7). D-023: M2c-pi allowances, HUMAN steps, `.gitea/workflows/`, secret modes for uid 1000 (§10.2, §10.3, §11.2, §14.7). D-024: release keystore command, kept outside the repository (§10.6). D-025: production import procedure and the `/opt/kvitt/import` bind mount (§10.2, §10.8). Without a decision id: exact Rust version pin shared by `rust-toolchain.toml` and the Dockerfile (§10.3); the §9.7 colour change lands before M6 (§11.1); per-screen states are U2's list (§13.3); landing page copy (§13.3, AC-2.5); M8 owns network security config, hardening, signing and version properties (§11.2); U1's gate names the six phase-1 screens (§11.2); category table path (§10.8); implementation agents never edit the spec or the decisions log (§14.8). |
| 0.4 | 2026-10-17 | Decisions from the M2a (`06f48ef`) and M2b (`c277ee3`) implementation reports. D-005: the eight normalisations of the OpenAPI equality test and the `CommonRules` modifier in `openapi.rs` (§11.3, §14.8). D-006: the wrong-bp-sum token is `bp_sum_not_10000` with an explicit serde rename in Rust; Kotlin emits the same token (§14.5.1, §14.5.3). D-007: the no-unwrap rule enforced per crate with `#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used))]` (CLAUDE.md). D-010: screenshot tests with Roborazzi 1.76.0 on Robolectric 4.17, `@Config(sdk = [36])`, `roborazzi.test.verify=true`, re-record with `recordRoborazziDebug` (§6.2, §11.2). D-011: `IncompleteCustomRangeException` for an incomplete `CUSTOM` range; `ALL_TIME` with the earliest expense after today gives today..today (§14.5.4). D-012: Room 3 (`androidx.room3` 3.0.3, KSP only, `SQLiteDriver` with `sqlite-bundled`, migrations on an `SQLiteConnection`); M2b created the entities and `KvittDatabase` v1, whose exported schema `1.json` is a contract file; M5 builds on them (§6.2, §11.2, §11.3, §14.2, §14.2.3, §14.7, §14.8). D-013: JDK 25 `--add-exports`/`--add-opens` for Robolectric in `build-logic` (§6.2). D-014: `failOnNoDiscoveredTests` off only for modules without `src/test` (§6.2). D-008 and D-009 unused. Clarifications without a decision id: exact Rust pin (1.99.1) shared by `rust-toolchain.toml` and the Dockerfile, `TARGETARCH` arm64 (shipped) and amd64, distroless pinned by digest (§6.3, §10.3); chrono stands (§6.3); `kvitt-domain` depends only on `serde` (§6.3, CLAUDE.md); `AuditWriter` and `PushQueue` as built (§6.3, §14.7); protocol check before token check (§6.3, §14.3.1); 405 with an empty body and the version header (§14.3.1); body limits as router layers (§8.6); `app_version_code` updated only from a present, parseable `X-Kvitt-App-Version` (§8.2); E-1 `schema_version` from a code constant; E-2 `initialized` means an admin user exists (§14.3.4); `healthcheck` uses the port of `KVITT_BIND`; `cargo run -p kvitt-server -- <command>` from the workspace root (§10.4); `minSdk` 36, `compileSdk` and `targetSdk` 37, Material 3 1.4.0 pinned beside the Compose BOM, AGP 9 `check` runs only the debug unit-test variant, version code and name from `kvitt.versionCode`/`kvitt.versionName` defaulting to `1`/`dev`, feature convention documented in `android/README.md` (§6.2); `FieldError.error` may be `validation_failed` for §9.6 rules without a domain token (§9.6, §14.2.4); `AnalyticsState` has no error field and a missing custom date resolves as today (§14.2.4, §14.5.4); `DrillDownState.title` stays a `String` of unlocalised parts and S-12 formats its own title (§14.2.4); a settlement row in an account's list shows that account's allocation (AC-11.7, §14.2.4); the `AnalyticsMeasure.Share` / `model.Share` name collision is accepted (§14.2.4, §14.5.4). |
| 0.5 | 2026-10-17 | Decisions from the M3 (`7869ec4`) and M5 (`8f0e156`) implementation reports. M3: D-030 picture version after a removal, `-removed` marker, next version = highest on disk + 1, first upload 1 (AC-4.4, §10.4, E-10); D-031 failed accept = any 4xx but 429, refused until 60 minutes after the first failure, fixed windows (AC-2.12); D-032 rate-limit keying by token hash, 401 counts against the IP, never-accepted tokens refused when the IP is over, `KVITT_TRUSTED_PROXY` re-resolved every 60 s, last `X-Forwarded-For` entry, `into_make_service_with_connect_info` added by M4 (§8.6, §10.4, §11.3); D-033 resume moves `last_generated_period` only to a period at or after `start_period` (§9.5); D-034 strings stored trimmed, transparency flattened onto white, `fcm_token` non-empty or null, revoke clears `fcm_token`, idempotent archive keeps `server_version`, new category `sort_order` over non-deleted (§8.6, §9.6, AC-3.5, AC-4.4, AC-7.3, E-17, E-20, E-21, E-25, E-26). M5 (renumbered: its D-030 to D-033 are D-040 to D-043): D-026 `cursor_ahead` is epoch recovery (§14.4.2); D-027 `clock_skew` gives a new `pending_mutation_id`, and the phone re-stamps `updated_at` on the next attempt (orchestrator decision, follow-up open) (§14.4.5); D-028 periodic work `kvitt-sync-periodic` (§14.4.1); D-029 `OnlineResult.Failed("network", null)` (§14.2.4); D-040 whole-request push refusals count as no progress, 429 retries, 426 stops (§14.4.5); D-041 `DataBindingsModule` (§6.2); D-042 Room tests on Robolectric, migrations from the exported JSON (§6.2); D-043 pairing status and 426 version code in DataStore (§8.2, §14.2.2). D-035 to D-039 reserved for M4. Clarifications without a decision id: control characters restricted only in `notes`, newlines accepted in names and descriptions (§8.6); landing page without download button while no APK is published, 404 page, `Referrer-Policy` and `Cache-Control` headers (AC-2.5, §13.3); generation sets the template's `updated_at` (§9.5); E-28 accepts archived accounts and categories (AC-6.4); E-14 on an accepted invite is 204 with no change; `/health` from the healthcheck counts against loopback (§8.6); M3's tests in one binary `tests/core_api/` (§14.7); sync triggers, batch and page sizes (AC-15.3, §14.4.1); 426 stops syncing until the installed version changes and `HomeState` has no update-required field (§14.2.4, §14.3.1); pictures always fetched at 512; `NeedsInstallPermission` once (AC-16.3); `Rejection.summary`, `FieldChange` display and `RecurringTemplate.draft.date` as documented in `:data` (§14.2.4); M8 contract requests (§11.3). |
| 0.6 | 2026-10-18 | Decisions from the M4 (`15056dc`) implementation report. D-035: a mutation whose `mutation_id`, `entity_type` or `entity.id` is unusable fails the whole request with 400 `invalid_request`; every other shape error is a per-mutation `validation_failed` (§14.4.4 step 3). D-036: `POST /sync` with 0 mutations is 422 `batch_too_large`, the code now reads "outside 1 to 100" (§9.6, §14.3.2, §14.4.4). D-037: a delete of a never-synced row runs the full step-8 validation; every rejection carries the stored row or null as `current`, also at steps 3 and 4; step 11 keeps the stored `created_at`; pushed ids must be canonical lowercase hyphenated UUIDs (§14.4.3, §14.4.4). D-038: FCM retries are one send plus up to three retries at 1 s, 5 s, 25 s; 401 drops the cached access token and is not retried, other 4xx are not retried; retries block the single sender task up to 31 s per device (§14.6). D-039: pruning deletes `received_at` strictly older than 90 days; seam change to D-015: `tasks::start` returns the `AppState` with the real push queue and `serve` builds the router from it, `AppState::new` defaults to `SqlAuditWriter`, `NoopAuditWriter` removed, `NoopPushQueue` kept for push disabled (§6.3, §14.1, §14.4.9; PLAN-M4). Clarifications without a decision id: §14.4.4 step 8 order is field rules, domain rules, references; a negative `since` is `invalid_request` and a pull reads one page in a single read transaction (§9.6, §14.3.4, §14.4.2); push runs in one `BEGIN IMMEDIATE` with a savepoint per mutation; the push queue is bounded at 100 and drops the oldest with a warning; the FCM JWT is RS256 with `kid` = `private_key_id`, the access token cached until 5 minutes before expiry, messages data-only with string values; `UNREGISTERED` or 404 clears the device token only if unchanged; an unusable credentials file disables push like a missing one (§6.3, §14.6); the scheduler reads the injected clock at least every 30 s, runs a missed job once after a forward jump and re-plans after a backward jump of more than a day (§9.5); `rotate-epoch` prints the new epoch, exit 0 or 1 on a database error (§10.4); `serve` uses `into_make_service_with_connect_info` (D-032 fulfilled, §8.6, §11.3); `GET /i/` with an empty code is the HTML 404 (E-4); reqwest (rustls, aws-lc-rs, platform verifier) and jsonwebtoken added, so the arm64 image needs a C toolchain stage and the distroless image CA roots, to be confirmed by M2c-pi or M10; the dev image was rebuilt with them on the Mac on 2026-10-18 (§6.3, §10.3); M4's test binaries and scheduler path (§11.3, §14.7). |
| 0.7 | 2026-10-18 | Decisions from the M9 (`50339ae`) implementation report and the importer rehearsal on the real exports. D-044: nine Swedish Splitwise category names added to the §10.8 table and to `splitwise_categories.csv` with the key of their English equivalent (Städning and Verktyg - Övrigt `utilities`, Tjänster `home`, Cykel `transport`, Flyg `travel`, Spel `entertainment`, Kläder `shopping`, Livet - Övrigt and Utbildning `other`). D-045: reconciliation: the run commits only if each user's balance of the whole account equals the sum of the file's totals rows (one per currency, converted with `--fx`); a mismatch or a missing totals row rolls back and exits 4, a dry run reports the same, an account already holding other rows rolls back, a mismatch after any `--fx` conversion is reported but accepted (§10.8, AC-17.5). D-046: CLI semantics: `--user` takes a user id or an exact unique display name; no database is created or migrated, `meta.schema_version` must be 1; a dry run runs the full transaction and rolls back; exit codes 0 ok, 1 database or file error, 2 usage, 3 cannot import, 4 reconciliation mismatch; the import key uses an existing account's stored name; an empty description or one over 1000 code points makes the row invalid; descriptions over 100 code points are cut with the full text in `notes`; settlement notes cut to 200; both nets zero is mode `full` on the owner; idempotency through the existing `import_key` columns (§10.8, AC-17.5). M9 marked landed, M11 rehearsal recorded (§11.2, §11.3). |
| 0.8 | 2026-10-18 | Decisions from the owner's UX session (`docs/ux/proposed-decisions.md` UX-1 to UX-8 on branch `UX-sprint`). D-047: direction 3 "Kalas" with the muted palette, typeface per D-020 (§9.7, §13.4). D-048: navigation stays at three destinations, an "Aktivitet" tab not taken for v1; §13.2 binding. D-049: category suggestion from the description, new §9.11 (CS-1 to CS-7: new expenses only, manual choice wins, history most often then first token, keyword table, AC-8.6 default, no marker), AC-8.6, `ExpenseRepository.suggestCategory` (§14.2.4), Kotlin-only `suggestCategory` in `:domain` with the `UnicodeText` interface bound by `:data` and `suggest_category.json` as landed by M12a (`aa765bb`) (§14.5.5, §14.5.6), contract file `contracts/category-keywords.csv` (§14.8). D-050: S-1 display-name field on a first pairing (AC-2.4, §13.3). D-051: §9.7 hex values become the muted Kalas values from U2, token names fixed, `slate` and `amber` `TODO(U2)`. D-052: "Utgiften sparades" without undo (S-7), archived account hides the FAB (S-5), per-account settle-up keeps the swap and an editable amount (S-9), avatar tokens `avatar-1` and `avatar-2` (AC-4.5), Swedish effect copy (AC-8.10). D-053: finer Splitwise mapping (§10.8). D-054: fourteen default categories (`housing`, `insurance`, `children`, `fees` added; AC-7.2), icons `key`, `shield`, `account_balance` (33), colours `slate`, `amber` (14), server schema 2 through migration 0002 rebuilding `categories` (§14.1.1, locked as `contracts/schema/migrations/0002_categories_v2.sql`, copied from M12a's file; no `server-v2.sql`, §14.8), importer schema check 2 (§10.8), enums in §14.2.4 and §14.3.3, E-1 `schema_version` 2; Room schema unchanged. New milestone group M12 "Category contract v2" (M12a contracts, then M12b server and M12c Android in parallel; M6 and M7c wait for M12c) (§11). |
| 0.9 | 2026-10-18 | Outcomes of M12b (`6eaccec`) and M12c (`b09f322`), U2 (landed `6da6b1b`) and UX-9. D-055: the keyword table is copied from `contracts/category-keywords.csv` at build time by `:data:copyCategoryKeywords` and `:core:fakes:copyCategoryKeywords` (AGP generated resource directory), a missing file fails the build, packaged as `se/hagstedt/kvitt/data/category-keywords.csv` (and the fakes path in debug), no committed copy, a `:data` test asserts byte identity and the §14.8 rules; supersedes the `android/data/src/main/resources` copy (§11.2 M12c, §14.2.4, §14.7, §14.8). D-056: pure `parseCategoryKeywords(csv)` in `:domain`, shared by `:data` and `:core:fakes` (§14.5.6). D-057: `DefaultCategoryKey` declared in AC-7.2 order; the Rust wire enum, the OpenAPI enum and the 0002 `CHECK` list the ten v1 keys then the four new ones; wire values unaffected (§14.2.4). D-058: test harnesses seed users after the fourteen category seeds (`server_version` 15 and 16); `E-7-me/response.json` shows 15 and 16 and its test compares them again (§14.3.5). D-051 fulfilled: §9.7 hex values from `docs/ux/design-spec.md` §2.3; `design-spec.md` is the binding design document and `strings.csv` (558 rows, D-017 prefixes, plurals as `key:one`/`key:other`) the source of string resources (§13.4). D-059: UX-9 accepted as a contract change: `ExpenseEditorOptions.frequentCategoryIds` and `CategoryRepository.deletable(id)` with their readings and fallbacks (§14.2.4), new milestone M12d (§11, §14.7); M7a to M7f depend on M6 and M12d. Clarifications without a decision id: `suggestCategory` history is every non-deleted expense (pending included, all accounts, both users), active categories neither archived nor deleted, fallback last-used in the account if active else `other`, null account gives `other`; when `other` is archived and no active last-used exists the result is null and the editor shows no category until the user picks one (AC-8.6, §9.11 CS-5, §14.2.4); stored `expense_date` values are valid ISO dates (§9.6), so parsing cannot fail. §11.2: M12a, M12b, M12c, U1, U2 landed, M6 started 2026-10-18; dry run of 2026-10-18 (Vardag 1746 rows, 0 unmapped; Hemma 37 rows, 0 unmapped; both reconciled) (§11.2, §11.3). §10: development stack migrated to schema 2 on 2026-10-18 after a backup. PLAN-M12b: bundled SQLite is 3.51.x (3.51.3), not 3.50. |
| 0.10 | 2026-10-18 | Outcomes of M12d (`557af7e`) and M6 (`7730a31`) and two owner-approved string decisions. D-060: `frequentCategoryIds` holds only categories used in the account (possibly fewer than five or empty); filling to five and placing the selected category fifth stays in the editor; not a contract change (§14.2.4). D-061: a key for every active account (empty list when unused), none for archived accounts; ties by count, `sort_order`, then category id (§14.2.4). D-062: `deletable` is false for an unknown or deleted id; archived categories follow AC-7.6; fake `delete` and `deletable` share one rule (§14.2.4). D-063: charts on Compose `Canvas` in `:core:design`, not Vico (3.3.1 cannot meet design-spec §3.10); Vico stays in the catalog unused, removable later (§6.2). D-064: Material 3 Expressive against material3 1.4.0: `ShortNavigationBar` used; `MaterialShapes`, `ButtonGroup`, `LoadingIndicator`, `LinearWavyProgressIndicator`, medium extended FAB, button sizes, segmented list items, expressive slider, `MotionScheme.expressive()` and the increased shapes take fallbacks; fulfils design-spec §6 open point 5 (§6.2). D-065: sv and en month and weekday tables in `DateFormatter`; chart labels without dots; file sizes in SI megabytes with one decimal (§9.8). D-066: golden layout per component sheet × light/dark × sv/en, plus 200 % for long states, switched through a configuration context; M7a to M7f follow it (§6.2). D-067: English default name of `restaurants` is "Dining" (AC-7.2, `strings.csv`, `:core:design`). D-068: shared `ledger_settlement_label` ("Payment" / "Betalning") for the settlement row's type label; settlement row titles may wrap to 2 lines (3 at 200 %); an empty chart range shows only the 0 baseline (§13.3, §13.4). Without a decision id: `:core:design` described as built (§6.2); `SyncStatusPill` takes a `failed` flag until `SyncSummary` gets a "last attempt failed" field (§13.3, M8 request); M6's M8 contract requests `LocalAvatarPictures`/`AvatarPictures` (authenticated E-11 request from user id and `pictureVersion`), `ProvideHousehold(me, partner)`, `LocalKvittClock`; design-spec §2.7 One UI font check at the M8 install (§11.3). §11.2: M12d and M6 landed, M7a to M7f started 2026-10-18. |
| 0.11 | 2026-10-18 | Outcomes of the M7 wave (M7a `1ea752c`, M7e `ea7d494`, M7d `7380e50`, M7b `0e1d99d`, M7c `0b140aa`, M7f `c4ab35f`) and the design-system fix pass M6b (`b24c8b5`); owner approved in advance. D-069: S-11 total caption "<range> · Hushållet" / "<range> · N veckor", label "Totalt · Min del" for my share, whole-month ranges for month presets and days otherwise, legend and stacking by `sortOrder` and `AccountRepository.all()` order, `AnalyticsState.groups` order unspecified, loading = `lastSuccessAt == null` with skeleton cards, offline looks like loaded (§13.3, §14.2.4). D-070: S-12 week title per `strings.csv` ("Vardag, vecka 41"), whole-range title "<name>, <range caption>", no error state on S-11/S-12, no loading state on S-12 (§13.3). D-071: top-level screens S-3, S-4, S-11, S-13 render their own `KvittNavigationBar` with `onNavigate`, no second bar in `:app`; navigation-argument keys are feature constants read through `SavedStateHandle`; result snackbars shown by the screen returned to, account-archived snackbar with undo (§13.2). D-072: a new template's day of month defaults to today (AC-9.8, S-19). D-073: S-22 "Sök efter uppdatering" reports "Du har den senaste versionen" when `UpdateState` stays `None`; network failure indistinguishable, accepted for v1 (new AC-16.6, §14.2.4, §11.3). D-074: `FieldError.field` values are the model property names; an edited settlement keeps its saved rows, "Föreslå igen" re-proposes; S-9's untouched-accounts line derives from Home balances (AC-11.6, §13.3, §14.2.4). D-075: the D-060 fill is `:core:design`'s `quickRowCategories`, replacing design-spec §3.7's interim rule (§14.2.4). D-076: category labels up to two centred lines, long custom names end in "…" (§13.3 S-7). D-077: day ranges in captions and summaries written out with the year, chip and S-12 title keep the short form (§9.8). D-078: stored amounts open for editing with both decimals, ratio percents trimmed (§9.6). D-079: shared keys `common_ok`, `common_undo`, `editor_split_full_on_you` and the M7b–M7f module keys recorded in `strings.csv` (578 rows, header included) (§13.4). D-080: "Synka nu" on S-8, S-10 and S-16 is online only; discard dialogs of S-6, S-7, S-9, S-19 have no body text (§9.9, §13.3). Without a decision id: §6.2 `:app` Hilt wiring before M8 (release binds `:data` since `6453932`, the debug fakes module `a41f240` is deleted by M8) and feature screenshot tests full screen at 411 × 891 dp xhdpi; §13.3 S-1 generic help line, S-2 blank-name error, S-3 error state, S-5 non-sticky month headers and "60/40" ratios (`common_ratio`), S-16 pending rows use the shared ledger rows, "Senare" hides the update banner for the ViewModel's lifetime; §11.3 contract requests for a later contract pass (M12e). §11: M7a–M7f and M6b landed, M8 and M7g started 2026-10-18 (M8 holds D-085 to D-089, renumbered to D-081 onwards on landing); §14.7 owners after landing. |
| 0.12 | 2026-10-18 | Outcome of M8 app integration (`cb832a7` and `3d9eea8`, gate green: BUILD SUCCESSFUL, 710 actionable tasks). D-081: both variants bind `:data` through `di/AppDataModule.kt` in `src/main` (includes `DataBindingsModule`); `DebugFakesModule` deleted; fakes only in tests and feature previews; `:app` tests on a plain `Application`; revises D-041 (§6.2, §11.3). D-082: a network security config cannot express IP ranges, so the debug config allows cleartext everywhere and `SessionRepositoryImpl.normaliseServerUrl` enforces the AC-2.8 limit; release config in `src/main`, debug override in `src/debug`, pinned-root config in `src/releasePinnedRoot/res` behind `kvitt.tls.pinnedRoot`; the debug `InsecureBaseConfiguration` lint warning is intended (§8.5, §10.5.3, AC-2.8). D-083: FCM registration by Firebase Installation ID (firebase-messaging 26.0.0, BoM 35.0.2, google-services 4.5.0): `register()` while paired and at each start, `onRegistered(fid)` sends `fcm_token` through E-17, `unregister()` on revoke, `firebase_messaging_installation_id_enabled` meta-data; no server change, `fid` field as a follow-up request (AC-13.7, §6.2, §14.6). D-084: an invite link opened while paired is ignored, never re-pairs (AC-2.6). D-085: a tap on the generic notification, a deletion or `sync_batch` opens Home; unknown type or `v` ≠ 1 only syncs; channel `activity`, notification id = hash of `entity_id`, `sync_batch` id 1; push handled by an expedited WorkManager job calling `syncForPush` (20 s) then building the text from Room (AC-13.6, §14.6). Without a decision id: the session gate (S-1, S-2, S-18; S-3 while `partner == null`) in §13.2; M8's `:app` wiring facts (`LocalKvittHousehold`, `LocalKvittClock`, `LocalAvatarPictures`, permission after the first sync, sync and update triggers, unsigned release without keys, exported components) in §11.2, §11.3, §8.8, §10.6, AC-2.9; M8's contract requests on the §11.3 M12e list (`PushEvent` to `:core:model`, S-22 licences, detail-screen snackbar hosts, S-7/S-8 snackbar strings, launcher icon, `fid`); new OQ-5 (licences screen, default not in v1). §11: M8 and M7g (`3dda414`) landed; M12e started 2026-10-18. The end-to-end pairing, offline and push test and the design-spec §2.7 typeface check on the phone are still to run. |
| 0.13 | 2026-10-18 | Outcome of the M12e contract pass (`8c60715` contract pass, `b7b7483` launcher icon; gates green: Android BUILD SUCCESSFUL, 710 actionable tasks, 906 tests; server 253 tests with the OpenAPI equality, vector and migration byte-identity tests). D-086: E-3 returns `invite_kind`; `SessionRepository.pair` returns `OnlineResult<Pairing(user, inviteKind)>`, an unknown kind reads as `device`; S-2 follows only a `partner` pairing; `FakeScenario.pairingInviteKind` (AC-2.4, AC-2.10, §13.2, §13.3 S-2, §14.2.4, E-3). D-087: E-12 link `<public_url>/i/<code>?from=<admin name>`; E-4 takes optional `from` and passes it only into `kvitt://invite?server&code&from`, never shown, an invalid value dropped; `InviteLink`, `AppLink.Invite`, `PairingScreen(initialAdminName)`, `PairingViewModel.prefill` carry it; S-1 shows `onboarding_code_help` with the name; links without a name still parse (AC-2.5, AC-2.6, §13.3 S-1, E-4, E-12). D-088: `SyncSummary.lastAttemptFailed`; `SyncStatusPill`, `syncPillVariant`, `syncLineText` drop `failed`; S-16 failed = online and `lastAttemptFailed` (§13.3 S-4, S-16, §14.2.4, §11.3). D-089: `Rejection.actor` from the stored `current.updated_by_user_id`, partner as fallback; no protocol change (§14.2.4, §14.4.6). D-090: optional request header `X-Kvitt-App-Version-Name` on every operation, stored at E-3 and the hourly last-seen update, blank or over 32 characters ignored; migration 0003 adds `devices.app_version_name`, server schema 3 (new §14.1.2, contract copy with byte-identity test, v2→v3 migration test); `app_version_name` on the Device wire object; `Device.appVersionName`; S-20 shows "Kvitt 1.1"; importer expects schema 3; Room unchanged at 1 (§8.2, §10, §10.8, §14.1, §14.3.1, §14.3.3, E-1, E-3, AC-3.1, §13.3 S-20). D-091: `RecurringRepository.create(NewRecurringTemplate)`, the server mints the id (§13.3 S-19, §14.2.4, E-28). D-092: `UpdateRepository.check(): UpdateCheck` (`UpToDate`, `Available`, `Failed`), 404 is up to date, debug reports `UpToDate`; S-22 up-to-date or could-not-reach-server; revises D-073 (AC-16.6, §13.3 S-22, §14.2.4). D-093: `SettleState.untouched` with nets excluding the edited settlement, empty per account; revises D-074's S-9 reading (§13.3 S-9, §14.2.4). D-094: the D-027 re-stamp as implemented: at the start of a cycle with `clock_skew` set, pending rows stamped later than now are re-stamped to now (§14.4.5). D-095: `PushEvent` in `:core:model`; six screens host the shared snackbar host, no `:app` overlay host; snackbar resource ids from S-7 and S-8; adaptive vector launcher icon (`#9C5238`, `receipt_long` at 48 dp, monochrome layer); revises D-071 (§6.2, §13.2, §13.3 S-7, S-8, §14.2.4, §14.6). Without a decision id: the 128 px picture size left unchanged by assumption (owner question open); the M12e list in §11.3 replaced by its outcome and a "Remaining contract requests" list (OQ-5 licences, `fid`); goldens re-recorded (S-20 devices; new `s1_pairing_link_admin`, `s22_about_check_failed`); compatibility note: the M12e APK needs a schema-3 server, so the server is redeployed first (§14.8); dev stack at schema 3, `up.sh --down` then `up.sh` on Podman (§10). §11: M12e landed (§11.1, §11.2). |
| 0.14 | 2026-10-18 | Follow-ups after M12e (`a312758`, `f56dcbe`, `3e6c337`). D-096: the server sends the stored `fcm_token` (the Firebase Installation ID of D-083) in FCM HTTP v1 `message.fid`, no longer in the deprecated `message.token`; no database or wire change, the column and the E-17 field keep the name `fcm_token`; `contracts/examples/push/*.json` use `fid`; revises D-083's "no server change" (§14.6, AC-13.7, §11.3). Without a decision id: the Pi image's C stage and CA roots and an OAuth plus FCM call from the arm64 image confirmed on the Mac (`docs/spikes/pi-image-arm64.md`; 63.8 MB, cold build 48 s), running on the Pi stays M2c-pi's (§10.3); Vico removed from the version catalog (`a312758`), D-063 pointer (§6.2); §11.3 remaining contract requests: only OQ-5. |
| 0.15 | 2026-10-18 | The first phone test, M8b (`328c466`) and owner answers. D-097: chart bars top corners 4 dp, bottom 2 dp, replacing 10/4 (§6.2, §13.4, design-spec §2.9, §3.10). D-100: no SSH from the Mac to the Pis; M2c-pi delivers the `infra/pi/` bundle the owner copies to the Kvitt Pi and runs, OQ-3 values as `.env` placeholders, M2c-pi last after the app is proven, no agent allowances on the Pis, Home Assistant, Gitea or Drive; revises D-023, keeps D-001 (§10 intro, §10.1, §10.10, §11.1, §11.2, §11.3, §12). D-101: the release keystore `kvitt-release.jks` at the repository root, git-ignored by `*.jks`, absolute path in `android/local.properties`, copy and password in the owner's password manager; revises D-024 (§10.6, §11.2 M10, §11.3). Without a decision id: the M8 end-to-end test passed on the owner's S26 against the development server (pairing, scripted partner via a second admin device, offline pending and sync, `fcm_token` and `app_version_name` registered, push by `fid` delivered and tapped); M8b fixes (invite-code `VisualTransformation`, quick-row badge above the ripple clip, `KvittTopAppBar` status-bar inset, 221 goldens) and `FcmMessageBody.fid` (`6eb3f85`) (§11.2 M8, §11.3); OQ-5 answered: licences button hidden in v1 (M8c); the 128 px picture size not needed (§14.2.4); the "boende" keyword keeps suggesting `travel` and the account page split bar stays as designed (no change). |
| 0.16 | 2026-10-18 | M8c (`75b549f`, `a0c25b0`, `7c453d8`), the R8 release build (`c30a49e`) and M8d (`bacbd18`). D-098: goldens in three variants `<name>_sv_light`, `<name>_sv_dark`, `<name>_en_light` plus `<name>_sv_light_200`, rendered at 1x through `w411dp-h<height>dp-mdpi`, every committed PNG compressed with `oxipng -o 4 --strip safe` (1143 PNGs / 131 MB to 865 / 26 MB, mock-ups 36.8 to 26.0 MB); revises D-066 (§6.2, §13.4). D-099: S-22 has no open-source licences row, `onOpenLicences` and `settings_about_licences` removed, `strings.csv` 577 rows; closes OQ-5 (§11.3, §12, §13.3, §13.4, design-spec S-22). D-102: S-7 options as four fixed full-width rows (Konto, Datum, Betalt av, Delning), `EditorOptionRows` in `:core:design`; connected buttons 8 dp side padding (§13.3, §13.4, design-spec §3.7, §3.10). Without a decision id: release builds R8-shrunk, optimised and obfuscated, APK about 11 MB (was 43 MB), `mapping.txt` kept beside the APK; release signing verified (alias `kvitt`, RSA 4096, v2) (§10.6); §11.1 graph. |
| 0.17 | 2026-10-18 | The M2c-pi bundle (`2476667`), M8e (`a59abeb`), M8f (`956908a`), the chips cleanup (`1328afe`) and the Dockerfile `CARGO_BUILD_JOBS` argument (`b4d9467`). D-103: the `infra/pi/` bundle (`compose.yaml`, was `infra/compose.yaml`; `.env.example`, was `infra/env.example`; `Caddyfile`; `install.sh`, `deploy.sh <tag> [--skip-backup]` with a backup before every deploy and `/opt/kvitt/previous-tag`, `bootstrap.sh`, `backup-now.sh`, `install-apk.sh`), the APK path `infra/publish-apk.sh` → `infra/pi/out/apk/` → `/opt/kvitt/apk/` → `install-apk.sh` into the `data` volume, mappings outside the volume, `.env` keys `KVITT_REGISTRY_USER`, `KVITT_REGISTRY_TOKEN`, `KVITT_PI_HOST`, `KVITT_PI_SSH_USER`, gate `docker compose -f infra/pi/compose.yaml config`; fulfils D-100 (§10 intro, §10.2, §10.3, §10.6, §10.7, §10.10, §11.2, §14.7). D-104: images `${KVITT_REGISTRY}/kvitt-server|kvitt-cert-sync|kvitt-backup` with `KVITT_REGISTRY=gitea.lan/jacobh2`, the Gitea workflow `.gitea/workflows/build-images.yaml` (runner `host`, secret `kvitt_cicd`, `v1.0.N` plus `latest`, git tag pushed, `CARGO_BUILD_JOBS=1`), `infra/build-images.sh` as the Mac fallback, supercronic instead of busybox crond, `openssl` in cert-sync, pinned versions and Docker Engine from Docker's Debian arm64 repository (§10.1, §10.2, §10.3, §12 OQ-1). D-105: `backup` runs as uid 10001 on the Pi, `rclone.conf` 0600 owned 10001:10001, a temporary copy for refreshed tokens, volume owners set once by `install.sh`; revises D-023 for `rclone.conf` (§10.2). D-106: cert-sync always requests the `tar` stream (both `authorized_keys` variants), refuses a mismatched key or an earlier-expiring certificate, an unreachable admin API at first start is no failure; backup uploads every pending file, confirms each by name and size, deletes and writes `last-success` only after all are confirmed (§10.5.1, §10.9). D-107: S-19's account, payer and split as three fixed `EditorOptionRows` (Konto, Betalt av, Delning), extending D-102 (§13.3, design-spec §3.7, S-19). D-108: navigation is instant, no enter, exit, pop or size transition on the app's `NavHost` (§13.2, design-spec §2.11). Without a decision id: the Drive token, the cert-sync key and the Gitea secret `kvitt_cicd` exist; `server/Dockerfile` honours `CARGO_BUILD_JOBS` (§10.3); the unused `AccountChip`, `PayerChip`, `SplitChip` removed (design-spec §3.7); Caddy's `Authorization` redaction verified (§10.5.2); APKs about 11 MB (§10.10); §11.1 graph. |
| 0.18 | 2026-10-18 | M12f (`dc7a296`, `5b2ed37`, `2bd6b58`, `c366fbd`, `a0259ab`), the server gap pass (`8660b7f`), the server overhaul (`8103dae` to `b985ce9`), the infra overhaul (`2fac1ec` to `e70fe0d`) and infra security fixes (`7fb86f5`), the AC-coverage audit and the security review. D-109: S-16 shows a rejected change's lost version read-only, `Rejection.lost: RejectedVersion?` with `RejectedVersion(row, accountName, payer, mode, shares, notes, deleted)` from `rejected_payload`, null when undecodable or a user or the category is missing; dialog "Din version", "Du tog bort den här", "Visa nuvarande version"; ledger rows take a null `onClick` (read-only); four `home_sync_lost_*` strings (§13.3 S-16, §14.2.4, §14.4.6, design-spec S-16). D-110: `AboutState.schemaVersion`; S-22 reads `/health` when it opens online and shows "<version> (schema <n>)" (`settings_about_server_version_schema`), header fallback offline (§13.3 S-22, §14.2.4, E-1, design-spec S-22). D-111: `SettlementRepository.start` and `recompute` return `SettleState?` (null without a session or partner), `save` returns `Invalid(payer, validation_failed)`; no throws (§14.2.4, AC-5.1). D-112: a failed E-17 send is retried after each successful sync until accepted, a newer FID replaces it (AC-13.7). D-113: `kvitt-server invite-partner` (0 ok, 2 household full, 3 no admin) and the `push sent` info line (§8.7, §10.4); `tools/contracts-check.py` 134 checks. D-116: notifications `VISIBILITY_PRIVATE` with the generic public version (new AC-13.9); L-6 kept as built, S-1's server row expanded for a non-default server, the confirm step listed as OQ-6 (AC-2.6, AC-2.8, §12). D-117: Caddy log redaction of `/i/<code>` and query strings, `Content-Security-Policy`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` (§8.7, §10.5.2, which now quotes `infra/pi/Caddyfile` at `7fb86f5`); Caddy as uid 10002 with group 1000, read-only, `cap_drop ALL` plus `NET_BIND_SERVICE`, tmpfs; `/certs` 0750 1000:1000, `caddy_data` 10002, extending D-105 (§8.9, §10.2); the development stack copies only `fcm-service-account.json` into `infra/dev/secrets/` (§10 intro); `/opt/kvitt/deployed-digests` with a WARNING on a changed digest and a workflow digest step; `kvitt_cicd` with `write:package` only (§10.3, §10.10); the plain root key (variant B) removed (§10.5.1); the `remote_ip` check (§10.10). D-114: pictures at most 16 000 000 pixels and 64 MB decoded, `image_invalid` (AC-4.4); `fcm_token` 1 to 512 characters, else `invalid_request` (§9.6, E-17). D-115: a token is accepted only after a 2xx, an unaccepted token counts against its IP, a 401 withdraws acceptance, entries pruned when their window expires; revises D-032 (§8.6). Without a decision id: the server overhaul (`8103dae` to `b985ce9`: shared row reads and inserts, invite creation and CLI helpers, one test harness `tests/common/`, clippy pedantic wins, synchronous `tasks::start`, `not_implemented` no longer produced; 268 server tests; all crates at their latest versions) (§6.3, §14.3.2, §14.7). Without a decision id: `install.sh` keeps the deployed `KVITT_TAG`, `--provenance=false`, the shared `tools/gradle-lock.sh`, `RCLONE_REMOTE` dropped from the development env (§10 intro, §10.3, §11.3); `strings.csv` 577 to 562 rows (§13.4); `localeFilters` en, sv (AC-19.1); `work-testing` and the screenshot harness fix (§6.2); release APK 10.0 MB (§10.6, §10.10); M12f row in §11.2 (941 tests); §11.4 validation reports (`docs/validation/ac-coverage.md`, `docs/validation/security-review.md`); the history rewrite and first push to `origin` (`18c527f`): every commit hash cited in this file is the rewritten one; `7c453d8` (the oxipng pass) no longer exists as a commit, its PNGs are in `18c527f`. |
| 0.19 | 2026-10-18 | The Android overhaul (`e4e6e5d` to `c582363`). D-118: shared test support in `:core:design`'s test fixtures (`se.hagstedt.kvitt.design.testing`: `Variant`, `TestClock`, `TestEnvironment`, `ScreenSnapshots` with `Root`/`Screen`/`ScreenWhenIdle`, `MainDispatcherRule`, `withMain`) through `testImplementation(testFixtures(project(":core:design")))`, not a module, the architecture check rejects test fixtures outside test configurations; the convention plugin `kvitt.android.screenshots`; `format/Failures.kt`, `format/Limits.kt` and `savedSplitLabel` in `:core:design`; `KvittMotion` only the seesaw spring, `KvittIcon.Description` and unused dimens and shapes removed; four catalog entries removed; one `CopyCategoryKeywords` task (§6.2 `:core:design` row and Screenshot tests, §11.1, §11.3; design-spec §2.11 and the icon table). Without a decision id: overhaul outcomes in §11.3 (Android `c582363`, server `b985ce9`, infra `e70fe0d`); 941 tests, no golden changed, release APK 10.46 MB; pushed to `origin` at `c582363`; `infra/README.md` APK size about 10 MB; pre-rewrite hashes in `PLAN-*.md` replaced by the rewritten ones. |
| 0.20 | 2026-10-19 | APK download rate limit (`96e4cbd`) and owner answers to the security review. D-119: E-6 `GET /apk/files/{file_name}` at most 10 requests per minute per client IP in its own fixed window, not counted against the 60 per minute of the other unauthenticated endpoints, every request counted (a 404 included), 429 `rate_limited` with `Retry-After`, client IP as in D-032, in memory; E-5 and E-4 stay on the 60 (§8.6, §10.6, E-6). Without a decision id: security review M-1 closed by the owner (backups stay unencrypted, rclone keeps the `drive` scope; accepted risk in §8.1 and §8.7); L-3 fixed; the D-114 limits (16 megapixels, 512-character `fcm_token`) confirmed by the owner (§11.4). |
| 0.21 | 2026-10-19 | The NPM rework (`4f69ae0`, `d05f13a`, `62f5279`, `9231a1d`) and the Android host property (`d090c6c`). D-120: TLS terminates in the owner's Nginx Proxy Manager on the Home Assistant Pi instead of Caddy and cert-sync, which are removed (`infra/cert-sync/**`, `infra/pi/Caddyfile`, images, volumes `certs` and `caddy_data`, secrets `ha_ssh_key` and `ha_known_hosts`, `.env` keys `HA_PORT`, `HA_USER`, `HA_CERT_DIR`); Kvitt gets its own host name `KVITT_PUBLIC_HOST` (owner-chosen, recorded in HANDOFF), `KVITT_PUBLIC_URL=https://${KVITT_PUBLIC_HOST}:8443`; router 8443 → NPM 443, nothing forwarded to the Kvitt Pi; the server publishes 8080 on the LAN, `KVITT_TRUSTED_PROXY=${HA_HOST}`; the NPM proxy host and its Custom Nginx Configuration carry over D-117's headers and log redaction (§10.5 rewritten: 10.5.1 Nginx Proxy Manager, 10.5.2 Custom Nginx Configuration, 10.5.3 Fallback: NPM down); health checks on 8080 and through NPM; the Gitea login interpolates the secret in the `run` line (reverses L-8's fix) (§1, AC-1.1, §6.1, §7, §8.5, §8.7, §8.9, §10 intro, §10.1 to §10.5, §10.7, §10.10, §11.2, §11.3, §11.4, OQ-3, OQ-6, E-7, §14.7). D-121 (`d090c6c`): the Android app's public host is the build property `kvitt.publicHost` (Gradle property, else `android/local.properties`, else the placeholder `kvitt.example.invalid`), exposed as `BuildConfig.PUBLIC_HOST`, the manifest placeholder `publicHost` and `RELEASE_SERVER_URL` = `https://<host>:8443`, injected into `:feature:onboarding` as `@ReleaseServerUrl` (AC-2.6, AC-2.7, §8.5, §10.5.3, §10.6, §13.3 S-1, OQ-6). Without a decision id: `cargo audit` in the server gate (`f1abb0d`). |
| 0.22 | 2026-10-19 | The D-121 follow-ups (`4a4e45f`, `4b1ae0c`), the server's host defaults (`c9abd24`, `e381e37`) and the `install.sh` step number (`ac17b41`, no decision). D-122 (`4a4e45f`, `4b1ae0c`; extends D-121): `AppBuildInfo` (defined in `:data`'s `DataModule.kt`, provided by `:app`'s `AppBuildInfoModule`) gains `releaseServerUrl` = `RELEASE_SERVER_URL`; S-22 shows the paired server, before pairing `AppBuildInfo.releaseServerUrl`; `DataModule.DEFAULT_SERVER_URL` removed; fakes and tests on `https://kvitt.example.org:8443` (30 S-21/S-22 goldens re-recorded); `infra/publish-apk.sh` reads `KVITT_PUBLIC_HOST` from `infra/pi/.env` and passes `-Pkvitt.publicHost` (§6.2, §10.6, §13.3 S-22, §14.2.4). D-123 (`c9abd24`, `e381e37`; revises D-120's leftovers): `KVITT_PUBLIC_URL` has no default and every `kvitt-server` command refuses to start without it; `KVITT_TRUSTED_PROXY` defaults to `none`, never looked up; the OpenAPI server is `https://{host}:8443` with variable `host` (default `kvitt.example.invalid`), representational for §14.8; E-7 and E-12 examples on `kvitt.example.invalid`; `tools/contracts-check.py` expects the `{host}` URL; 276 server tests (§10.4, §11.3, §14.3, E-7, E-12). The owner's Kvitt host name `kvitt.suorra.duckdns.org` (2026-10-19, recorded in HANDOFF; §10.1, §10.5, §10.5.1). |
| 0.23 | 2026-10-19 | Port 443 (`a86ad24` server and contracts, `4852803` bundle, `038c603` Android, `ad35231` portless Android fixtures, 30 S-21/S-22 goldens re-recorded) and the pinned-root template (`038c603`, no decision). D-124 (owner decision 2026-10-19): Kvitt is served on port 443 (`https://<host>`, no explicit port) because NPM listens on 443 and selects by host name; the router's existing external-443 forward to the Home Assistant Pi serves Kvitt, no 8443 rule. Server and contracts: OpenAPI server `https://{host}`; E-7 and E-12 examples without a port; `tools/contracts-check.py` expects the portless header. Bundle: `KVITT_PUBLIC_URL=https://${KVITT_PUBLIC_HOST}`; health checks through NPM on 443; README router step "no new rule"; the APK-abuse stop-gap is disabling Kvitt's proxy host in NPM. Android: `releaseServerUrl(host)` = `https://<host>` (`RELEASE_SERVER_PORT` removed); the AC-2.6 intent filter has no port and matches every port of the host, so an old `:8443` link still opens S-1 with the server it names; invite-link parsing drops an explicit default port (`:443`, `:80`); S-1 goldens on `https://kvitt.example.org` (28 re-recorded) (§1, AC-1.1, AC-2.6, §6.1, §7, §8.1, §8.5, §10.1, §10.2, §10.4, §10.5, §10.5.3, §10.6, §10.10, §11.2, §11.3, §11.4, §14.2.4, §14.3, E-7, E-12). Without a decision id: the pinned-root config is generated at build time from the template `android/app/src/releasePinnedRoot/network_security_config.xml` with the domain `kvitt.publicHost`, only when `kvitt.tls.pinnedRoot=true`, and the build stops while `android/app/src/release/res/raw/kvitt_root_ca.crt` is not committed (§8.5, §10.5.3). |
| 0.24 | 2026-10-20 | The self-contained Pi compose project (`6e5981d`), the `.env` without informational keys (`200c99f`) and the sparse-checkout workflow (`3820f9c`, no decision), with the workflow's first results; the compose deploy hint in the workflow and `infra/build-images.sh` (`28fa71b`, no decision). D-125 (owner decision 2026-10-20, revises D-103, D-105, D-117 point 5, D-120 point 6): the Kvitt Pi runs Kvitt from `/home/jacobhagstedt/kvitt`, a self-contained compose project (`compose.yaml`, `.env`, `secrets/`, relative bind mounts `./data`, `./backups`, `./import`); both containers run as the owner's uid/gid (`KVITT_UID`/`KVITT_GID`, 1000 on the Pi) with a read-only root and a 16 MB tmpfs `/tmp`, backup `HOME=/tmp`; each mounts only its own secret file read-only (`create_host_path: false`), secret files the owner's, mode 0600; `.env` holds exactly the seven keys compose reads, `RCLONE_REMOTE` fixed to `gdrive:`; no install script, no `/opt`, no Docker daemon or system changes (Docker and the registry trust are prerequisites; private packages mean a one-time `docker login gitea.lan`); the scripts `install.sh`, `deploy.sh`, `bootstrap.sh`, `backup-now.sh`, `install-apk.sh`, `lib.sh` removed, their equivalents plain `docker compose` commands (backup `exec backup /backup.sh`, bootstrap and partner invite through `exec server kvitt-server`, deploy = backup, set `KVITT_TAG`, `pull`, `up -d`, rollback = the previous tag, APK = `scp` of the APK and then `latest.json` into `data/apk/`, old APKs removed by hand, digests with `docker image inspect`, no digest record, health checks by hand); restore moves files on the host, only rclone and sqlite3 run in the backup container; the compose default network; the development stack unchanged (uid 10001); rehearsed with Podman as uid 501 (§8.5, §8.9, §10 intro, §10.1, §10.2, §10.3, §10.4, §10.5, §10.5.1, §10.6, §10.7, §10.8, §10.9, §10.10, §11.2, §11.3, §12 OQ-3, §14.7). Without a decision id: the `.env` keys `KVITT_PI_HOST` and `KVITT_PI_SSH_USER` dropped (`200c99f`, revises D-103), `<KVITT_PI_HOST>` is now `<kvitt-pi-address>` (§8.9, §10.1, §10.5.1, §10.5.3, OQ-3); the Gitea workflow's results on the owner's Pi runner (act_runner 0.6.1, Alpine job container): the first failures were an empty secret (a misnamed user-level secret, fixed by the owner 2026-10-19), run 69 built `v1.0.0` (`kvitt-backup` 5 min 20 s, `kvitt-server` 2 h 42 min, first build with `CARGO_BUILD_JOBS=1`), the sparse-checkout push built `v1.0.1`, the tag the Pi uses; the checkout is a cone-mode sparse checkout of `server` and `infra/backup` with `fetch-depth: 0` and `--filter=blob:none`; the diagnostic step removed (§10.3, §11.2). |
| 0.25 | 2026-10-21 | The app gate (D-126, owner decision 2026-10-21; Android `34e5cad`): outside the home LAN `192.168.1.0/24` NPM closes the connection (`return 444`) of every request without `X-Kvitt-App: <key>`, every route included (`/health`, `/setup/status`, `/invites/accept`, `/i/{code}`, `/apk/*`); only `/.well-known/acme-challenge/` passes (Let's Encrypt renewal), tested on `$uri`; the LAN check reads `$realip_remote_addr`, because NPM's `real_ip_header X-Real-IP` for private peers makes `$remote_addr` forgeable; the server and `contracts/openapi.yaml` are unchanged, the bearer token stays the authentication. The app sends the header in `KvittApi`'s common headers and `PictureAuth` when built with `kvitt.appKey` (Gradle property, else `android/local.properties`, else empty = no header; 16 to 128 printable ASCII characters without white space; `BuildConfig.APP_KEY`, `AppBuildInfo.appKey`; 952 Android tests); the key is the owner's `openssl rand -hex 32`, only in `local.properties` and NPM; rotation by a second `if` line, a new APK through FR-16, then the old line removed. Accepted: landing page and browser use only on the LAN, outside health check through the app's About screen or `curl -H`, a leaked APK leaks the key until rotation, no flood protection. The gate rehearsed in NPM v2.16.0's openresty with its includes (AC-2.5, §8.1, §8.5, §10.1, §10.5, §10.5.1, §10.5.2, §10.6, §10.10, §14.3.1). Without a decision id: `infra/README.md` step 4a (key, APK, gate, acceptance test), its `CARGO_BUILD_JOBS` text (in effect since `b4d9467`; run 69: `kvitt-server` 2 h 42 min) and its owner decisions marked answered. |
| 0.26 | 2026-10-21 | Pull-to-refresh on Home and account detail (D-127, owner request 2026-10-21; Android `3778f5f`; revises design-spec S-4 "Pull-to-refresh is not offered"): pulling S-4 or S-5 past the threshold runs `SyncRepository.syncNow()`, the call behind S-16 "Synka nu"; the indicator stays while the sync runs and goes when it returns, success or failure; a failure shows only in the sync pill (S-5 has none, so a failed pull there shows nothing until Home's pill); offline the pull ends at once without a sync; a pull while a sync runs starts no second one. Shared `KvittPullToRefresh` in `:core:design` (`component/Refresh.kt`): Material 3 `PullToRefreshBox` with a Kvitt indicator (48 dp `primary-container` disc, the `sync` icon 18 dp turning 270° with the pull and popping from 80 % at the threshold on the new `KvittMotion.spatialFast()` with a `GestureThresholdActivate` haptic, a 32 dp `primary` arc that fills to the threshold and turns indeterminate while refreshing); `ContainedLoadingIndicator` replaces the arc once the pinned Material 3 (1.4.0) ships it. TalkBack reads "Synkar…" (`sync_syncing`, reused) as a polite live region; S-16 stays the TalkBack path. New goldens `S-4-home-refreshing` and `S-5-account-refreshing`; 959 Android tests. No change to `:core:model`, Room, the sync protocol, the server or `docs/ux/strings.csv` (AC-15.3, §9.9, §13.3; design-spec §2.11, §3.1, §3.6, S-4, S-5). |
| 0.27 | 2026-10-21 | S-12 line chart for a category or account over the range (D-128, owner request 2026-10-21; Android `12e2508`). S-12 opened from a breakdown row shows its own period chip (AC-14.2 presets plus custom) and Month/Week toggle, both starting from S-11's values and changing chart, total and list on S-12 only (S-11 keeps its state; measure and group-by come from S-11 and are fixed on S-12), the header total, the "Utgifter över tid" card and the expense rows; a drill-down from a bar is unchanged. One point per bucket, empty buckets as zero (AC-14.7), from the group's bucket totals of `spendSeries` (§14.5.4); an empty range shows only the 0 baseline (D-068) and "Inga utgifter i den här perioden". Overlays: the range average (total ÷ buckets, half-up to öre) as a dashed line in the group colour with its amount at the right end; a trailing moving average over 3 buckets (`AnalyticsRules.MOVING_AVERAGE_WINDOW`; the first buckets use the 1 or 2 that exist) as a thinner neutral line; legend "Snitt", "Glidande snitt (3)"; caption "<Bucket>: N % över snittet" / "under snittet" / "på snittet" for the latest bucket the range does not cut short, N a whole percent half-up. Overlays and caption omitted when the average is 0 or the range has one bucket; caption omitted when no bucket is whole. Not interactive; one TalkBack summary. `:core:design` gains `SpendLineChart` and `LineLegend` (`chart/LineChart.kt`), axis code shared with `StackedBarChart` in `Charts.kt`; `AnalyticsFilterBar` measure and group-by toggles optional. Seven `strings.csv` keys (569 rows). New goldens `s12_category_groceries`, `s12_category_week`, `s12_category_empty_range`, `line_chart`, `line_chart_variants`; `s12_category`, `s12_account`, `s12_long` re-recorded; 977 Android tests. No change to `:core:model`, `:domain`, `:core:fakes`, Room, the server or the contracts (new AC-14.11; §13.3 S-12, §13.4; design-spec §3.10, S-12). |
| 0.28 | 2026-10-21 | The web client programme (owner interview 2026-10-21; no implementation yet; v0.27 is D-128's). D-129: a web client with the Android app's features except the phone-only ones (pairing flow, push, offline, in-app update), plus free-text search, CSV export of the filtered list, keyboard shortcuts N, /, Esc, ? and a language choice; desktop first, one column under 720 px, sv and en, not a PWA (§1, §2 revised, new §15, FR-21). D-130: the browser logs in with an invite code through E-3 as device `Web · <browser>`, token in `localStorage`, revocable on Devices; the NPM gate also passes `/app` and `/app/…`, `POST /invites/accept` and bearer-token requests except `/health`, `/setup/`, `/i/` and `/apk/` (§8.5, §10.5, §10.5.2, `infra/README.md` steps 4 and 4a, `infra/npm/kvitt.conf`; checked with nginx 1.31.7, 17 requests). D-131: `web/` stack (Vite, React 19, TypeScript strict, React Router 7, TanStack Query 5, `openapi-typescript` and `openapi-fetch`, Recharts, Vitest, ESLint, Prettier, CSS modules with design-spec tokens, JSON dictionaries), the money functions passing the vectors, the web gate `npm run check` (§11, §15.3). D-132: the web client is built by a Node stage of `server/Dockerfile` (context the repository root) and served by `kvitt-server` under `/app/` from `KVITT_WEB_DIR` with an SPA fallback; immutable hashed assets, `no-store` `index.html`; the `/app/` CSP through `$kvitt_csp` in NPM (§10.3, §10.5.2, §10.6, §15.4). D-133: advanced analytics on the server under `/analytics/*` (per-category averages and trends, a two-month forecast per account = recurring templates due + the 3-month average of non-recurring spend), for the web and the app; AC-14.1 and G-5 revised (§15.8; endpoints D-135 to D-138, v0.29). D-134: plans W0 to W7 with disjoint paths (§11.1, §11.2, §11.3, §14.7, §15.9; `PLAN-W0.md` to `PLAN-W7.md`, `prompts/W0.md` to `prompts/W7.md`). The change log becomes §16. |
| 0.29 | 2026-10-21 | The server side of the web client programme (W7, `50a0d67`) and the unattended APK deploy (`70cb25c`). D-135 web serving: `KVITT_WEB_DIR` (default `/app`); `GET /app` → 308 `/app/`; files from the directory, every other path `index.html`, a missing `assets/*` 404; `assets/*` `public, max-age=31536000, immutable`, `index.html` `no-store`, others `no-cache`; the `$kvitt_csp` web policy plus `nosniff`, `DENY`, `no-referrer`; safe paths at most 512 bytes and 8 segments of `[A-Za-z0-9._-]` not starting with `.`; no directory → `/app` 404 (§10.4, §15.4, AC-21.1). D-136: `/app`, `/app/`, `/app/*` count against the unauthenticated 60/min per IP, bearer token or not (§8.6). D-137 image build: repository-root context with an allowlist `.dockerignore` (`server`, `web`, `contracts`), `server/.dockerignore` removed; a Node `node:24.22.1-bookworm-slim` stage pinned by digest on the build platform, its `dist` passed through the Rust stage so npm and rustc never run together on the Pi 3; workflow context `.`, sparse checkout and path filter add `web` and `contracts`; `infra/build-images.sh` and `infra/dev/build.sh` follow; `Cargo.lock` bumps `rustls-webpki` 0.103.16 and `webpki-root-certs` 1.0.10 (RUSTSEC-2026-0382, -0383) (§10.3). D-138 analytics: E-34 `GET /analytics/trends` and E-35 `GET /analytics/forecast`, authenticated, read-only, with examples; rules in new §14.5.7 (`kvitt-domain::analytics`) (§7, §14.3.4, §14.3.5, AC-14.1, §15.8). D-139 (`70cb25c`): `infra/publish-apk.sh --deploy` copies the APK and `latest.json` with a forced-command key and checks `/apk/latest` (§10.6). Server tests 299; contracts-check 136. |
| 0.30 | 2026-10-21 | The manual update check (`c0f4345`). D-140 (owner, 2026-10-21): S-22 "Check for update" shared the throttled automatic check, so a tap within 6 hours of the last automatic check reported the stored answer (the owner deployed a new APK and was told "You have the latest version"); `UpdateRepository.checkNow()` (default implementation calls `check()`, so fakes are unchanged) always asks the server and restarts the 6-hour window, debug builds still return `UpToDate` without a request; `AboutViewModel.check()` calls `checkNow()`; the automatic checks on cold start and resume keep the throttle (AC-16.2, AC-16.6, §13.3 S-22, §14.2.4). |
| 0.31 | 2026-10-21 | Android Insights on S-11 (W6, `1c9856b`; Android gate green, which also fixes the E-34/E-35 example tests red since `50a0d67`). D-141 UI contract: `:core:model` `InsightsRepository` with `trends(months: 1..24, measure)` and `forecast(measure)`, both `OnlineResult` (`Offline` without a request, `Failed("network")` when unreachable); types `SpendTrends`, `SpendTrend`, `TrendPoint`, `CategoryTrend` (`category: Category?`), `SpendForecast`, `AccountForecast` (`account: Account?`), `ForecastMonth`, named after the E-34/E-35 fields; names resolved from Room, archived and deleted included, unknown id → null; nothing stored; `:data` `AnalyticsDtos.kt`, `InsightsRepositoryImpl`, two `KvittApi` calls; fakes `FakeInsightsRepository`, `InsightsScenarios`, `insightsFailure` (§14.2.4). D-142 placement and loading: an "Insights" ("Insikter") section below S-11's local analytics, following S-11's measure toggle, always 6 whole months (E-34's default); loads when S-11 opens, when the measure changes to one not yet loaded, when the phone comes online and on "Försök igen"; data kept in memory per measure while S-11 is open; the last data stays visible under the offline or error banner; S-11's offline analytics unchanged (AC-14.1) (§13.3 S-11, design-spec S-11). D-143 display rules: the household chart and a per-category chart on D-128's `SpendLineChart` with the server's average and moving average; categories in the server's order, the open one defaults to the largest total; unknown category ids skipped; one forecast card per account (archived badge) with the current month so far and two months as "Recurring + average = forecast"; an all-zero card shows one line "No recurring expenses and no recent spending" (design-spec S-11, §3.10). `strings.csv` 588 rows (16 `analytics_insights_*` keys, 19 rows) (§13.4). Goldens `s11_insights_<state>` for 13 states in three variants plus `s11_insights_long_sv_light_200`. |
| 0.32 | 2026-10-21 | The web feature plans W1 to W5 (`934eee7`, `a65ab71`, `f9a9bfb`, `1aecf51`, `3ebe57d`; web gate on `main` 59 files, 532 tests at `1aecf51`, 598 at `83f5293` with the `suggest_category` vectors) and the update install-failure fix (`d686ee0`). D-144: the preset account travels as `?account=<id>` for `/app/expenses/new` and `/app/settle`, a payment being edited as `/app/settle?settlement=<id>`; builders in `features/accounts/links.ts` and `features/settle/links.ts` until W0 adds them to `routes.ts`. D-145: web Home's empty state shows the "Du och <partner> är med" card in place of the balance header; the archived section's open state lasts for the page session in memory. D-146: CSV export format (UTF-8 with BOM, `;`, CRLF, RFC 4180 quoting, "1234,50" in every language, ISO dates, header in the page language, one share column per user, formula cells prefixed `'`, `kvitt-utgifter-<date>.csv` / `kvitt-expenses-<date>.csv`). D-147: AC-8.6's "on this phone" is this browser (`localStorage`); search filters in the URL (amounts in öre). D-148: web expense editor: rejections and failures in a banner with S-16's text and "Visa nuvarande version", the server's row into the snapshot, typed values kept; "Utgiften sparades" after edits too; the discard dialog on `Esc` and in-app navigation; browser controls in place of S-7's keypad, ratio slider and summary row; shared fields in `web/src/components/editor/`; the keyword table imported raw (`server.fs.allow`). D-149: W-7 shows the §14.5.3 allocation errors as you type. D-150 unused. D-151: a bar opens `/app/analytics/bucket/<key>`; the filter in the query string (`range`, `from`, `to`, `interval`, `measure`, `group`, `bucket`), replaced by W-10's own period changes. D-152: chart SVGs hidden from screen readers, bar labels as keyboard stops, "Visa som tabell"; W-11 offers 3, 6 or 12 months. D-153: W-18's route is `/app/settings/invite` (`/invites` still opens it); W-15 and W-16 editor routes. D-154: the partner's first-login step is an intro on W-14 remembered in `kvitt.profileStepDone` (the device id); W-19's fallback reads the server-version header of a fresh `GET /me` (§15.3, §15.6, §15.7, AC-8.6). D-155 (`d686ee0`): a refused or failed install shows "Kunde inte installera uppdateringen" with the reason (blocked by the security settings, or the installer's message) and "Försök igen", which downloads again; a declined dialog returns to `Available`; `UpdateState.Failed` gains `reason: UpdateFailure` (`Download`, `Blocked`, `Install(detail)`) (new AC-16.7, §13.3 S-17, §14.2.4; design-spec §3.6, S-17, S-22). `strings.csv` 590 rows (`update_install_failed`, `update_install_blocked`). Goldens `S-17-install-blocked`, `S-17-install-failed`, `s22_about_install_blocked` new, `update_banner` re-recorded. contracts-check 136. |
| 0.33 | 2026-10-24 | Owner answers and phone observations of 2026-10-24 (D-156) and the small-edits working rule (D-157). D-156: OQ-6 answered, no confirm step on S-1 for an unusual server (§12); security review L-10 answered, a member naming the other user's device gets `not_found` (AC-3.2, §8.4, E-16; to implement, the server answers `forbidden` today); no host firewall rule limiting port 8080 to `HA_HOST` for now (§10.2, deferred); `mem_limit` kept and advisory on the Pi (§10.2); images keep being built on the Pi 3 runner until the current run's result, `infra/build-images.sh` the fallback, `docker builder prune -af` between builds (runner disk 11 of 15 GB, §10.3); Samsung Auto Blocker must be off for the in-app install (AC-16.3); AC-18.1 verified by the owner, AC-16.3 and the editor keyboard fix observed on the phones, both phones on release 140 (AC-18.1, §11.4); the web client is first used from the laptop browser (§15.2). D-157: small edits by a Haiku or Sonnet agent directly in the main checkout, committed on `main` by the orchestrator (working rule, `CLAUDE.md`). `infra/README.md` "Pi: what the owner does" gains the prune and Auto Blocker notes. contracts-check 136. |
| 0.34 | 2026-10-24 | L-10 implemented (`07c36d2`, D-156) and the web shared follow-ups (W0b, `5305f37`), no new decision. L-10: a member naming the other user's device gets E-16's `not_found`, the same body as an unknown id; `contracts/openapi.yaml` drops E-16's 403 and `web/src/api/schema.d.ts` is regenerated (contract change, §14.8); the "to implement" notes of AC-3.2, E-16 (§14.3.4) and §11.4 removed; `Cargo.lock` bumps `ctutils` 0.4.3 → 0.4.4 (RUSTSEC-2026-0385, published 2026-10-23, which failed `cargo audit` on `main`). Server tests 300; contracts-check 136. W0b: shared web pieces once in `components`, `lib`, `api` and `app`, no feature imports another (`catalog.test.ts` also checks `web_` keys); amount fields per page language; Recharts in its own chunk (vendor 516 → 132 kB); Vitest cache off; Testing Library's `findBy`/`waitFor` limit 5 s in `web/src/test/setup.ts` (load on the Mac during parallel agents); the version code from the commit count, else `KVITT_VERSION_CODE`, else 1 (§15.3). Web gate 609 tests. Image build: `server/Dockerfile`'s Node stage takes `ARG KVITT_VERSION_CODE=1` into `npm run build`, and the Gitea workflow passes `--build-arg KVITT_VERSION_CODE=<git rev-list --count HEAD>` (§10.3). |
| 0.35 | 2026-10-24 | Card purchases through Enable Banking (owner's request and answers of 2026-10-24, D-158 to D-176) and plans K0 to K3. D-158: card purchases in scope, §2's card and bank non-goal struck through with a pointer, new US-18, US-19, FR-22 (AC-22.1 to AC-22.15), §9.12 (CP-1 to CP-14). D-159: Enable Banking in restricted production for the SJ Prio Mastercard (SEB Kort), G-7 allows it, PSD2 limits stated as facts, ToS as the owner's licence step. D-160: server-only credentials, one adapter `src/cards/enable_banking/`, provider registry, card catalogue E-36. D-161: only the card holder sees their purchases (owner's answer): own endpoints and cursor, not in `GET /sync`, audit, push or analytics, `not_found` for the other user, no card content in logs, session id protected by separation from the private key (§8.1, §8.4, §8.7, §10.9). D-162: connect flow with single-use attempts (E-37, E-38), the callback E-39 and its bilingual page, `kvitt://cards/connected`, polling. D-163: `/cards/callback` through the app gate and never logged (§10.5.2 block). D-164: history 7/30/90/180 days, default 30. D-165: background fetches at 06:45, 11:45, 16:45, 21:45, at most 4 per 24 hours; user-present "Uppdatera" with Enable Banking's PSU headers, once per 60 s; incremental fetch with a 10-day overlap; `card_bank_unavailable`. D-166: consent up to 180 days, notice 14 days before, renewal with BankID; `card_consent_expired`. D-167: migration 0004, server schema 4 (`card_sequence`, `card_connections`, `card_auth_attempts`, `card_purchases`, §14.1.3); disconnect rules (E-43). D-168: transaction mapping, pending→booked de-duplication, foreign currency, credits listed only under "Alla". D-169: "Skapa utgift" prefill, links (E-44), offline-capable link changes, unlink on expense delete (§14.4.4), `expense_already_linked`. D-170: suggested matches (same amount, ±3 days), `matchCardPurchase` with vectors `match_card_purchase.json` (§14.5.8). D-171: no bulk add, no card push (OQ-7, OQ-8). D-172: four bottom destinations, Översikt, Kortköp, Statistik, Inställningar (revises D-048); "Anslut kort" in Settings. D-173: `:feature:cards`, S-23 to S-27, Room version 2, `CardRepository` (§14.2.4), the owner's SJ Prio artwork with a drawn fallback. D-174: web W-21 to W-23 (K3). D-175: `KVITT_EB_*` configuration, `secrets/cards/`, two optional `.env` keys; `cards_unavailable`. D-176: plans K0 (the local test app of `2ce317f`, owner's refinement) to K3; K0's `TODO(spec)` answers go into v0.36 before K1. Endpoints E-36 to E-44; strings for the card screens and the callback page in §13.3; ownership rows K0 to K3 (§14.7); contract files 0004 and the new vector file (§14.8). |
| 0.36 | 2026-10-24 | K0's results (the spike run on the owner's SJ Prio Mastercard on 2026-10-24 with `docs/spikes/k0/app.py`, report `docs/spikes/K0-enable-banking.md`), D-177 to D-180; no contract file changes, server schema 4 and Room 2 as specified in v0.35. D-177: K0's outcome; every K0 `TODO(spec)` of §9.12 answered: ASPSP `SJ Prio Mastercard`, `SE` (CP-1); one `CARD` account per session (CP-2); at least 150 days of history right after BankID, so 7/30/90/180 stay (CP-3, §9.6); a background fetch without PSU headers accepted (CP-4); `required_psu_headers` [`psu-ip-address`], compared case-insensitively (CP-5); `maximum_consent_validity` 180 days, `valid_until` 2027-04-22 (CP-6); foreign purchases arrive in SEK (CP-7); credits were card-bill payments (CP-8); and the owner's assumptions of 2026-10-24 for what was not measured: the partner's card links to the owner's application (CP-13, the D-175 fallback stays), a pending transaction keeps its `entry_reference` when booked (CP-8, the amount-and-date rule becomes the secondary rule), the session is reused on later days without BankID (CP-6), all three verified by K1's owner steps. D-178: the card returns at most 100 transactions per response and never a `continuation_key`, so history is fetched in windows of at most 30 days, newest first, a window at 100 rows split in half down to one day, de-duplicated across windows by `provider_ref`; `strategy=longest` dropped; `WRONG_TRANSACTIONS_PERIOD` ends the walk back; only a complete fetch deletes vanished pending purchases (CP-7, CP-8); `card_fetch` counts requests, splits, truncated windows, `booked_by_ref` and `booked_by_match` (§8.7). D-179: transaction mapping from K0's field survey: merchant = `remittance_information`, else `creditor.name`, else "Kortköp"; `purchase_date` = `booking_date`, else `value_date`, else `transaction_date`; `bank_transaction_code` unused, so a debit `FEE` is a purchase to handle; the holder's name, the masked card number (`CPAN`) and the merchant's address are never stored, logged or shown (CP-7). D-180: the owner's SJ Prio Mastercard artwork cropped to the card (1313 × 829) and committed for Android and the web, mapped from the first commit of K2 and K3, the goldens use it, the owner's artwork steps removed (revises D-173, D-174). The K plans' proposed spec text goes into v0.37 (§11.1, §11.3). |
| 0.37 | 2026-10-24 | D-211: image builds on the Mac with Podman (`infra/build-images.sh v1.0.N`) are the normal path, the Gitea workflow on the Pi 3 runner the fallback (revises D-156 point 5); tag rule (the next `v1.0.N` after the highest tag on `origin`, pushed as a git tag too, `v1.0.3` = `8fa9198`); the registry from the Mac is `gitea.lan` on port 80, the Pi's `.env` keeps `gitea.lan:3001`; Podman's insecure-registry files on the Mac and in the Podman machine; the script fixes `f15fa23` and `8fa9198` (§10.3, §10.10). `v1.0.3` deployed on the Kvitt Pi and the web client and S-11's Insights verified by the owner (§11.2 W1 to W7, §11.3, §11.4, §15). No contract file changes. |
| 0.38 | 2026-10-24 | K1's report (card purchases on the server, landed `671c00d`: migration 0004 byte-identical to §14.1.3, server schema 4 in code, E-36 to E-44 with four new error codes and a 502 `BadGateway` response in `contracts/openapi.yaml`, examples, `match_card_purchase.json` with its Python reference; gates at landing: server 356 tests, contracts-check 157, web 609, nginx check and compose configs ok, the Android gate red until K2 lands), D-181 to D-188 (D-189 and D-190 unused). D-181: the history counts today, `date_from` = today − (`history_days` − 1), 6 windows for 180 days (revises CP-3 and CP-7). D-182: the server's CS-4 first token for CP-8 uses Rust's standard Unicode classes without NFC. D-183: Enable Banking's errors mapped to CP-14 (`EXPIRED_SESSION`, `CLOSED_SESSION`, `REVOKED_SESSION`, `SESSION_DOES_NOT_EXIST` → `consent_expired` and `expired`; `ASPSP_RATE_LIMIT_EXCEEDED` or 429 → `rate_limited`; `ASPSP_ERROR`, `ASPSP_TIMEOUT`, 408, 5xx or no answer → `bank_unavailable`; anything else `failed`); E-37's `card_bank_unavailable` when `/aspsps` or `/auth` fails. D-184: the callback (an expired `state` stores `expired`, revising CP-2's `failed`; a used one changes nothing; neither `code` nor `error` → `failed`/`bank_error`; a session without accounts is revoked; the atomic claim). D-185: the poller's start-up slot, background starts counted whatever their outcome, deletion after `WRONG_TRANSACTIONS_PERIOD` only over the windows that answered, a split window's cut rows discarded. D-186: PSU headers only with a value, `/aspsps` cached 24 hours, the two fixed headers when it fails. D-187: E-41 with the current value and E-43 on a disconnected connection make no new version (`erase_handled=true` still erases), E-44's `field` for a credit purchase, `CardAttempt.failure` a plain nullable string. D-188: `src/wire/card.rs`, row helpers in `src/cards/mod.rs`, the client IP in a request extension, and the Pi's `compose.yaml` refusing to start until `secrets/cards/` exists. Changed: §9.12 CP-2, CP-3, CP-4, CP-5, CP-7, CP-8, CP-14; §10.2; §11.1, §11.2 K1 row, §11.3 (K2's text goes into v0.39, K3's into v0.40); §14.1.3; §14.3.3; §14.3.4 E-1 (`schema_version` 4), E-37, E-39, E-41, E-43, E-44; §14.3.5; §14.7. |
| 0.39 | 2026-10-24 | K2's report (card purchases on Android, landed `a8f91ee`: Room version 2 with `MIGRATION_1_2`, its test and the exported `2.json`; the `CardRepository` UI contract of §14.2.4 unchanged in its names; the card cycle; `:feature:cards` S-23 to S-27; S-5, S-7, S-8, S-13 and the fourth bottom destination; Android gate at landing `BUILD SUCCESSFUL`, 791 actionable tasks, 1154 tests, 0 failures, `VectorFilesTest` and `ExampleRoundTripTest` green again; 150 goldens added, 147 re-recorded for the bar), D-191 to D-200. D-191: the card cycle after each successful household cycle and after `refresh`, never changing the household outcome; E-40's 404 is "no card support", retried every cycle. D-192: E-44's `expense_already_linked` or `validation_failed` resets the row's `card_version` to 0 and moves the card cursor back before it (§14.2.1). D-193: links to expenses no longer on the phone cleared before E-44 and at every local delete or rejection that removes an expense. D-194: the E-36 catalogue cached in DataStore (`card_providers`, §14.2.2). D-195: after a connect or E-42's `fetching`, E-40 every 3 s, at most 40 times, until `last_fetch_at` or `last_fetch_error` changes. D-196: the return link held by `AppViewModel`: S-25 polls it at once, else one E-38 call and S-23. D-197: bottom-bar labels shrink to fit down to 70 % (design-spec §3.11). D-198: S-23's filter chips wrap; S-25's and S-26's history as wrapping chips (revises S-25's segmented choice). D-199: S-13 "Har upphört" for an expired connection; S-5's "Från kortköp" hidden on archived accounts. D-200: four added string keys and the card artwork measures in `KvittDimens`. §13.2 (the destination enum as built), §13.3 S-5, S-13, S-23 to S-27 as built and the added keys, §14.2.1 to §14.2.4 (Room 2 landed; readings fixed in v0.39), §11.2 K2 row, §11.3, new OQ-9 (`CardPurchase.linked` while the expense is missing, §12). `docs/ux/design-spec.md`: S-23 to S-27 sections from the goldens, §3.11 four destinations and shrink-to-fit, §3.12 card artwork, the `credit_card` icon, S-5, S-7, S-8, S-13 card states. No contract file changes in this pass (Room 2 is K2's). contracts-check 157. |
| 0.40 | 2026-10-24 | K3's report (card purchases on the web, landed `faeb752`; web gate at landing 70 files, 684 tests, build ok; contracts-check 157), D-201 to D-207 (D-208 to D-210 unused). Built: W-21 `/app/cards` (every §13.3 state but offline, the S-23 sheet actions, `?attempt=` polling E-38 every 2 s, `?account=` as S-27), W-22 `/app/settings/cards` (catalogue, connect step `?provider=`), W-23 `/app/settings/cards/:id` (history, renew, disconnect with erase); W-5's `?cardPurchase=` prefill (CP-9) and link on save; W-6's card line with "Ta bort koppling"; W-3's "Från kortköp"; W-13's "Anslut kort" row; Kortköp after Översikt in the sidebar and bottom bar; `matchCardPurchase` in `web/src/lib/domain/` passing the 17 vectors (ported). Shared pieces outside PLAN-K3 §4, ratified at landing: `web/src/api/cards.ts` with its test, `web/src/test/cards.ts`, `/cards` in the dev proxy, the icons `credit_card`, `link_off`, `visibility_off`, `Shell.test.tsx`; a refresh of the card snapshot no longer re-reads the catalogue and attempt queries (shared key prefix, now exact). D-201: W-21 re-reads E-40 every 2 s while a connection is fetching or in its first fetch, otherwise every 60 s. D-202: query names `cardPurchase` (W-5), `attempt` (W-21), `provider` (W-22, S-25, also "Förnya med BankID"). D-203: only an `https:` `auth_url` is followed. D-204: the outcome after `?attempt=` is dropped (snackbar "Kortet är anslutet"; a banner with "Försök igen" to W-22 `?provider=`). D-205: W-5 for an unknown or deleted purchase, and a failed E-44 after save. D-206: `valid_until` in the detail date form (W-21 banner, W-22 tile, W-13 row), W-6's line in the list form. D-207: W-21 with `?account=` is S-27 (title "Från kortköp", rows open W-5, no chips, no panel). Changed: §11.1, §11.2 K3 row, §11.3, §14.7 K3 row, §15 status, §15.3, §15.5 (the card snapshot), §15.6 W-5, W-6, W-13, W-21 to W-23 and the navigation paragraph, §15.9. No contract file changes. |