docs(wiki): merchant validations settled + as-built; scan input decided (camera paths postponed)

validation-discounts: driving cases → the settled validation-only model (all
money/paper at the booth) → setup UX/storage/RBAC → full as-built record.
DECIDED: merchant stations scan with a USB/HID barcode scanner on the
web/desktop app (hand-keying + Luhn as fallback); POSTPONED with analysis:
web getUserMedia scanning (secure-context TLS prerequisite on the LAN +
Code128-via-camera weakness → QR-on-ticket first) and a Tauri v2 Android
merchant app (native ML Kit scanning; Android build/sideload overhead +
configurable-server-URL prerequisite). Also: wsl-dev-networking gains the
mirrored-mode gotcha where a Windows-side listener makes a port EADDRINUSE
inside WSL while invisible to ss — Vite auto-increments and tauri dev's fixed
devUrl waits on the wrong port.

Claude-Session: https://claude.ai/code/session_01YYkpEsLmoQPaize5ec3oUm

wiki/concepts/validation-discounts.md

@@ -2,7 +2,7 @@
 type: concept
 tags: [parking, domain, business, pricing, revenue]
 sources: []
-updated: 2026-06-15
+updated: 2026-07-13
 status: open
 ---
 
@@ -11,6 +11,133 @@ status: open
 A merchant (shop, hotel, clinic) **validates** a customer's parking so they pay less or nothing —
 a common revenue/retention feature that modifies what a [[parking-session]] owes.
 
+## Driving cases (owner requirements, 2026-07-13)
+
+The feature moved from "industry gap" to **asked-for**: the park may contain an in-park
+**car-wash (al. "lavazh")** and/or a **bar**, and the owner wants their customers discharged
+(fully or partly) for the parking stay:
+
+- **Car-wash**: parking free entirely, **or** free for an owner-set duration (30 min / 1 h / 2 h …)
+  after which the stay prices like any transient → `comp` or `time-credit`.
+- **Bar**: subtract the bar consumption from the parking fee (consumed 300 ALL, park fee 500 ALL →
+  pay 200 ALL) → `fixed` with a **per-use variable amount**; or parking free for bar customers → `comp`.
+- These must be **admin-composable at runtime like tariffs/subscription plans** — the owner
+  defines the programs and their parameters; nothing hard-coded.
+
+**Refined the same day (settled): the merchant is a VALIDATION-ONLY system user; ALL money and
+paper stay at the booth.** Ownership is immaterial and the [[validation-sponsorship]]
+sponsor/settlement layer is **not needed** for this. The model:
+
+- A **merchant user** (the "bar user", "lavazh user") logs into the system on their own device and
+  **scans the customer's ticket** there — the scan-and-apply *is* the validation, a signed event
+  attributed to that user (accountability sits with the merchant, not the booth operator). That is
+  the merchant's ENTIRE surface: no payment collection, no printer, no shift.
+- **Every car still checks in at the booth to settle** — even a fully-comped one. The booth quote
+  applies the session's validation events (`gross − discounts`, floor 0); the operator collects the
+  **net** (possibly 0 — a zero-amount settlement is still a signed `payment` event so grace/exit
+  work unchanged) and **prints the detailed receipt there** (gross fee, each validation line, net
+  paid).
+- Exit is the unchanged [[booth-exit-flow]] (immediate exit or voucher self-exit at the reader).
+
+This DISSOLVES the two consequences flagged by the earlier merchant-collects variant (rejected
+2026-07-13, same conversation): the [[shift]] site-wide single-open invariant and single till stay
+as built (Z/X-reports just gain gross/discount/net lines so cash reconciles to net), and the exit
+reader needs no live due=0 branch (the booth settlement covers the zero-due case; time-credit is
+priced at booth check-in, inside the normal walk-back-grace flow).
+
+## Settled design (2026-07-13) — setup UX, storage, RBAC
+
+- **Setup lives on `/setup/site`** (gated by the page's existing `site:update`): the left card
+  gains **Bar** and **Lavazh** checkboxes; the empty right column renders the enabled station's
+  config panel (tabs when both). Panel per station: **mode** (comp / time-credit N-min / fixed
+  amount-typed-at-scan with a max cap / percent), **caps** (max per validation, max per day,
+  one-per-session default), **receipt label**, **bound users**.
+- **Fixed UI, generic storage**: a `validation_programs` table (+ user binding) where Bar and
+  Lavazh are two **well-known rows** created on first enable — a third merchant later is a data
+  row, not a migration (honours the "composable like tariffs" requirement). Config is plainly
+  **mutable, no versioning**: the applied validation is a signed ledger event carrying the
+  RESOLVED values (minutes/amountMinor + programId), so reproducibility never depends on the row.
+  Enabling/saving signs a `config_change` ([[entry-presence-bypass]] precedent).
+- **RBAC**: new `validation` resource in the code-defined grid — `validation:create` (apply; the
+  merchant's only permission) + `validation:read` (reports/history). Guard = permission **AND**
+  station binding (data), so a bar user can never apply the lavazh program. Merchant users land on
+  a new **`/validate`** screen (scan → session → apply); the permission-driven nav shows them
+  nothing else. Program composition needs no new permission (`site:update`).
+- **Mistake handling**: a merchant may **void their own validation while unused** (before it
+  entered a payment) — a signed void event, never a delete. Booth/admin can void via the normal
+  event-void path.
+- Open (non-blocking): per-customer mode choice (v1 = one mode per station); merchant scan
+  hardware — lean: also print a **QR** of the ticket id so any phone camera works
+  ([[ticket-encoding]]).
+
+## As-built (2026-07-13)
+
+- **Shared (`@parking/shared`)**: `validation` resource (`validation:create`/`read`) in the
+  permission grid; `ValidationMode`/`ValidationProgram`/`SessionValidation`/`ValidationLine`;
+  `priceSession(…, validations[])` folds the discounts in a **canonical order** — timeCredit
+  (shifts the billed period's start forward, so grace/steps/windowed cards price the remainder
+  correctly) → percent (of the remainder) → fixed (clamped) → comp — net floors at 0 and
+  **Σ lines ≡ gross − net** by construction. Unit-tested (incl. overstay + settled cases).
+- **Ledger**: new `validation` event type — payload carries the **resolved** values
+  (`programId`, `programLabel`, `mode`, `minutes`/`amountMinor`/`percent`) + `operator` (the
+  merchant username); `refId` set = a VOID of the referenced validation (append-only, mirrors
+  `cash_review`). The settling `payment` records `grossMinor`/`discountMinor`/`validationIds`
+  (**consumption** — an overstay's fresh period never re-applies them) + `validationLines`
+  (receipt reproducibility).
+- **DB**: `validation_programs` + `validation_program_users` (migration `0024`; both in
+  reset-db's `config` category). Mutable master data, soft-deletable.
+- **Server**: `routes/validations.ts` — programs GET/PUT (`site:read`/`site:update`, signed
+  `config_change` on real change only), `/mine`, `/session/:identity` (deliberately no money
+  data), `/apply` (guards in order: program live+active → user **bound** → open **transient** →
+  no live duplicate of the program → `maxPerDay` → fixed-amount bounds), `/void` (own +
+  unconsumed only). `PayStation.quote/lookup/pay` fold `liveValidations` (applied − voided −
+  consumed); `activeSessions` amounts are net automatically. Receipt (`renderReceipt`) prints
+  gross (`Tarifa`) + one line per discount; the big amount is the NET. Z/X-report gained
+  `discountTotalMinor` (leakage; takings stay net) — printed as `Zbritje (validime)` only when
+  non-zero, so old slips stay byte-identical.
+- **Web**: `/setup/site` is two-column — Bar/Lavazh checkboxes on the left card (a flip persists
+  `active` at once = signed config change), `ValidationSetup.tsx` panel on the right (tabs when
+  both; mode/params/caps/receipt-label/bound-users). `/validate` (`ValidateScreen.tsx`) is the
+  merchant's whole surface (scan/key → apply → void own unused), mobile-friendly, autofocused
+  input works with HID scanners; merchant-only users (no `session:read`) land there on login and
+  the permission-gated nav shows them nothing else. Booth pay modal shows gross → lines → net;
+  the zero-net comp settles through the normal pay path (grace starts, voucher/exit unchanged).
+  Feed label `VALIDIM`/`VALIDATION`. RolesManager picks the new resource up generically.
+- **Verified**: 8 route-level integration tests (guards, signed events, money cycle, void locks,
+  per-day cap) + the shared fold suite; whole-workspace build/typecheck/test green; migration
+  applied to the dev DB.
+- **Remaining polish (not blocking)**: show `discountTotalMinor` in the X-report/close-modal/
+  shift-history UI (it's already in the signed payload + printed Z); a validations/leakage
+  **report** (per program/user/day) under [[reporting-analytics]].
+
+## Merchant scan input — DECIDED 2026-07-13: barcode scanner on the web/desktop app; camera paths POSTPONED
+
+**v1 (in force):** the merchant scans with a **USB/HID barcode scanner** into the `/validate`
+screen on the web (or desktop) app — the scanner types the 11-digit id + Enter into the
+autofocused input, exactly like the booth. Hand-keying is the zero-hardware fallback; the
+[[ticket-encoding|Luhn check digit]] catches typos. The park site is expected to equip the
+bar/lavazh station accordingly — no phone-camera path for now.
+
+**Postponed (evaluated 2026-07-13, both viable, deliberately deferred):**
+
+1. **Web camera scanning** — `BarcodeDetector` (Chromium/Android native) + the `barcode-detector`
+   polyfill on **zxing-wasm** (Apache/MIT — license-clean, bundles offline). Two prerequisites
+   killed it for now: (a) `getUserMedia` needs a **secure context** — a merchant phone on
+   `http://<booth-ip>` gets NO camera, so the appliance needs a TLS story (realistically a
+   self-signed CA minted on the booth + one-time cert install per device — fold into the
+   [[booth-deploy-networking|reverse-proxy]] plan); (b) Code128 via phone camera on thermal
+   paper decodes poorly — would want the **QR-of-ticket-id** addition first (the ESC/POS driver
+   already has `qrCode()`; `renderTicket` is a one-line change — still a good idea whenever any
+   camera path revives).
+2. **Tauri Android merchant app** (a SECOND small Tauri target, e.g. `apps/validator` — NOT an
+   extension of [[desktop-shell-tauri|apps/desktop]], which is a booth kiosk hardwired to
+   localhost:3000): Tauri v2 mobile + the official `barcode-scanner` plugin (ML Kit — reads
+   Code128 well natively, and the tauri:// origin is secure so the TLS problem vanishes).
+   Costs that drove the postponement: Android SDK/NDK + Rust-target build infra (+CI), APK
+   sideload distribution/updates to merchant devices, effectively Android-only (iOS needs a
+   paid signing account), and it needs the configurable-server-URL work the desktop shell also
+   wants. Revisit if the owner issues dedicated Android tablets to merchants.
+
 ## Model: a discount is a signed event, applied at fee time
 
 A validation is **not** an edit to the session or a mutable "discount applied" flag — same reason