feat: subscription v2 — quantity pricing, plan timeframes (tariff bridge), reserved spots

Three subscriber enhancements driven by real scenarios (migration 0011, all
additive columns — backward-compatible).

1. QUANTITY. One subscription covers N cars (a family pays once for two). Sale
   amount = span price × quantity; maxConcurrent defaults to the quantity so all
   N cars can be inside. Quantity rides in the payment payload.

2. PLAN TIMEFRAMES → TARIFF BRIDGE. A plan may restrict WHEN a subscriber may
   park (e.g. weekday 20:00→08:00, weekend all-day). A scan outside the window is
   NOT refused — the out-of-window minutes are charged at the normal TRANSIENT
   tariff (the subscriber is a transient for that time):
     - early entry: arrival → window-open, DEFERRED (signed as windowOwedMinor on
       the vehicle_entry payload), collected at exit;
     - late exit: window-close → departure, and exit is GATED
       (sub.refused.unpaidWindow) until paid at the booth.
   Pure, tz-aware outOfWindowGap in @parking/shared (12 unit tests); pricing
   reuses computeFee + the active tariff version
   (apps/server/src/subscription-window.ts). The exit refusal is a host-ONLINE
   business gate — the fail-open rule still governs the offline path.

3. RESERVED SPOTS. Site toggle reserve_subscriber_spots: occupancy holds
   max(0, quantity − itsCarsInside) per active subscription, so transients see
   "full" sooner; effectiveFree = capacity − count − reserved. Subscribers are
   never gated by full.

UI: quantity field + ×N quote (SubscriptionManager); timeframes editor
(SubscriptionPlansManager); reserve checkbox (SiteSettings); booth pay modal
shows an "OUT-OF-WINDOW" charge and takes payment to clear the exit gate.

Verified on a copy of the live DB: qty 2 = 2× price; a night-plan 19:30 entry →
30min/15,000 ALL owed, stamped + paid → gate clears, chain verifies; the reserve
toggle holds a qty-2 sub's 2 spots. Build+lint 12/12; 80 shared tests pass.

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

wiki/concepts/capacity-occupancy.md

@@ -33,6 +33,23 @@ editable and drifts; the chain is the truth). Spaces-free = `capacity − occupa
   loop count, or the [[opencv-anpr-service|vision]] count) reconciles it — surfaced as an anomaly,
   not silently corrected.
 
+## Reserved subscriber spots (admin toggle, built 2026-06-20)
+
+By default occupancy counts only cars **physically inside** — a subscriber who isn't parked frees
+their spot to transients, and the operator handles any overflow by valet/key-juggling. A site can
+instead **hold a spot for every active subscriber**, so the lot reads "full" to transients sooner and
+the subscriber's place is guaranteed:
+
+- `site_config.reserve_subscriber_spots` (bool, default off). When ON,
+  `reservedSubscriberSpots(db)` sums, over every **active** subscription (status active AND
+  `now ∈ [validFrom, validTo]`), `max(0, quantity − itsCarsCurrentlyInside)` — i.e. it reserves only
+  the **not-yet-parked** portion of each subscription's [[subscription|quantity]] (a parked
+  subscriber already occupies a real spot; counting them twice would over-reserve).
+- `getOccupancy` gains `reserved` + `effectiveFree = capacity − count − reserved`. The transient FULL
+  gate becomes **`count + reserved ≥ capacity`**. Subscribers are still **never** gated by full
+  (their flow ignores it) — reservation only tightens the *transient* gate.
+- OFF = the prior behaviour exactly (`reserved = 0`).
+
 ## "Full" is a soft, operator-configurable policy
 
 Refusing at capacity is the **default**, not an absolute. An operator may opt into

wiki/concepts/tariff.md

@@ -20,6 +20,12 @@ beyond the host).
 > reproducible repricing. The operator selects a plan + span; the price is looked up, never typed.
 > Tariffs price *transient* stays by duration; plans price *subscription* spans by ceil(periods).
 
+> **The tariff also prices SUBSCRIBERS now (2026-06-20).** A [[subscription]] plan with time windows
+> charges the **transient tariff** for any out-of-window parking (early entry / late exit) — the
+> subscriber temporarily *becomes* a transient for those minutes. `computeFee` is reused unchanged;
+> the gap is a normal `[start, end]` priced against the active version (recorded `tariffVersionId` for
+> reproducibility). See [[subscription]] "the tariff bridge".
+
 > Decisions (2026-06-15): (1) tariffs are **effective-dated, immutable versions** — editing
 > publishes a new version, never mutates an old one; (2) **one active tariff per site** (versioned
 > over time), modelled with an id/scope so multiple rate cards can be added later without migration;

wiki/entities/subscription.md

@@ -78,6 +78,45 @@ subscription row, one window. The amount the operator should collect is **N × t
   `now` ∈ [validFrom, validTo]** — so a 3-month window simply stays valid for three months.
 - An explicit **`validTo` override** is still accepted (manual end date) when `months` isn't used.
 
+### v2 — quantity, plan timeframes (tariff bridge), reserved spots (built 2026-06-20)
+
+Three enhancements driven by real scenarios (migration `0011`):
+
+**Quantity (`subscriptions.quantity`, default 1).** One subscription can cover **N cars** — a family
+where the husband pays once for two cars. The sale amount is `priceSubscriptionSpan(...) × quantity`;
+`maxConcurrent` defaults to the quantity (so both cars can be inside). The payment payload carries
+`quantity`. Credentials/plates for all N cars live on the one subscription.
+
+**Plan timeframes → the TARIFF BRIDGE (`subscription_plans.timeframes`).** A plan may restrict WHEN a
+subscriber may park (e.g. weekday allowed 20:00→08:00, weekend all-day). Instead of **refusing**
+out-of-window scans, the system **charges the out-of-window minutes at the normal transient
+[[tariff]]** — the subscriber becomes a transient customer for the time outside their window:
+
+- `PlanTimeframes` = per day-type `DayWindow` ({ allDay | fromMin, toMin } minutes-of-local-midnight;
+  `toMin ≤ fromMin` wraps past midnight for a night window) + `graceMin` + the site `tz` (frozen in
+  the plan version, like a V2 tariff's tz). null timeframes = 24/7, no charge ever.
+- `outOfWindowGap(timeframes, tz, at, edge)` (pure, tz-aware, unit-tested in `@parking/shared`)
+  returns the `[start, end]` portion outside the window. **Early entry**: gap = arrival → next
+  window-open (a 09:00 arrival to a 20:00 window owes 09:00→20:00, capped by the tariff's daily cap).
+  **Late exit**: gap = window-close → departure. The gap is priced with `computeFee` (the same engine
+  transient stays use) at the active tariff version (`apps/server/src/subscription-window.ts`).
+- **Early entry is DEFERRED:** the barrier opens now; the owed amount is **signed onto the
+  `vehicle_entry` payload** (`windowOwedMinor` + the priced gap + `windowTariffVersionId`) — the
+  on-chain source of truth, read back at exit.
+- **Late exit is GATED:** at exit, `totalOwed = carried entry charge + a fresh late-exit charge −
+  payments`. If `> 0`, the exit is **REFUSED** with a new signed reason `sub.refused.unpaidWindow`;
+  the subscriber settles at the booth (a signed `payment` keyed to the occurrence — folds into the
+  shift/drawer/Z-report like any taking) and re-scans. The booth pay modal surfaces the amount as an
+  "OUT-OF-WINDOW" charge (`PayStation.lookup`/`pay` handle the subscription-window case).
+  > ⚠ **Exit gate vs. "never trap a vehicle."** This refusal is a **host-ONLINE business gate**,
+  > identical in kind to the existing transient `exit.refused.unpaid`/overstay gate — a working host
+  > *choosing* to refuse an unpaid car. The standing **fail-open** rule governs the *can't-decide*
+  > (power/host/network loss) path, which still opens. The two are not in conflict; don't conflate them.
+
+**Reserved subscriber spots** — see [[capacity-occupancy]] (an admin toggle that holds a spot per
+active subscriber's car in the [[occupancy]] full-gate). The subscriber flow itself is never gated by
+"full"; reservation only tightens the *transient* gate.
+
 ### Collecting the fee is a SHIFT transaction — BUILT 2026-06-20
 
 Selling/renewing a subscription is a **financial transaction a common operator makes during their

wiki/log.md

@@ -1152,3 +1152,24 @@ hotel sale prices to 2,400 ALL, appends ONE signed payment with planVersionId, c
 Build + lint 12/12. Updated [[subscription]] (plan catalog supersedes typed price; data model) +
 [[tariff]] (shared versioned-config pattern). The site default price column is kept only to seed the
 first plan.
+
+## [2026-06-20] feat | Subscription v2 — quantity, plan timeframes (tariff bridge), reserved spots
+
+Three subscriber enhancements (migration 0011, additive columns):
+(1) QUANTITY — one subscription covers N cars (a family pays once for 2); sale = span price × quantity,
+maxConcurrent defaults to it.
+(2) PLAN TIMEFRAMES → TARIFF BRIDGE — a plan may restrict when a subscriber may park (weekday
+20:00→08:00, weekend all-day). Outside the window they're charged the TRANSIENT tariff for the gap
+(not refused): early entry = arrival→window-open (deferred, signed as windowOwedMinor on the
+vehicle_entry); late exit = window-close→departure, and exit is GATED (sub.refused.unpaidWindow) until
+paid at the booth. Pure tz-aware outOfWindowGap in @parking/shared (12 unit tests); pricing reuses
+computeFee + the active tariff version (apps/server/src/subscription-window.ts). The exit refusal is a
+host-ONLINE business gate — fail-open still governs the offline path (flagged in the wiki).
+(3) RESERVED SPOTS — site toggle reserve_subscriber_spots: occupancy holds max(0, quantity−inside) per
+active sub, so transients see "full" sooner; effectiveFree = capacity − count − reserved. Subscribers
+never gated by full.
+UI: quantity field + ×N quote (SubscriptionManager); timeframes editor (SubscriptionPlansManager);
+reserve checkbox (SiteSettings); booth pay modal shows an "OUT-OF-WINDOW" charge + takes payment.
+Verified on a copy of the live DB: qty 2 = 2× price; night-plan 19:30 entry → 30min/15,000 ALL owed,
+stamped + paid → gate clears, chain verifies; reserve toggle holds a qty-2 sub's 2 spots. Build+lint
+12/12; 80 shared tests. Updated [[subscription]], [[capacity-occupancy]], [[tariff]].