parking_solution/wiki/concepts/capacity-occupancy.md

type, tags, sources, updated, status

type	tags	sources	updated	status
concept	parking domain business occupancy		2026-06-15	open

Capacity & Occupancy

How many vehicles are inside, how many spaces remain, and what happens when the lot is full.

Occupancy is a projection (like everything else)

occupancy = count(open [[parking-session|sessions]]) — an entry with no matching exit. It is a fold over the signed append-only-event-chain, never a hand-maintained counter (a counter is editable and drifts; the chain is the truth). Spaces-free = capacity − occupancy.

• capacity is admin-set per site (and per zone/level if the lot has sections — model a zone on capacity + on the entry so multi-level is a later addition, not a rewrite).
• Permit concurrency (maxConcurrent, see permit) is the same kind of fold, scoped to one permit's open sessions.

Full → refuse entry + FULL sign

• When occupancy ≥ capacity, the entry flow refuses (no vehicle_entry, no barrier open) and can drive a "FULL" sign (a relay/output, via the device adapter layer).
• Safety/policy nuance: "full" blocks entry only — exit always works (fail-state-safety: exit fails open; never trap a vehicle). Permit holders may be allowed in past a "transient full" threshold (reserve spaces for subscribers) — an optional policy knob.
• Counting drift is real: tailgating (two cars, one entry) and missed reads make the live count diverge from physical reality. The count is the system's occupancy; periodic ground-truth (a loop count, or the opencv-anpr-service count) reconciles it — surfaced as an anomaly, not silently corrected.

"Full" is a soft, operator-configurable policy

Refusing at capacity is the default, not an absolute. An operator may opt into valet-overcapacity — accept the car into operator custody (keys handed over, stacked beyond the marked count) instead of refusing. So the FULL gate is a policy knob (refuse vs. valet-accept), set by the operator per site. Valet is a manned-mode feature with its own custody/session shape — see valet-overcapacity (deferred).

As-built (2026-06-16)

• Occupancy = occupancyCount (apps/server/src/occupancy.ts): a fold over the ledger — entries minus exits per identity, count those > 0. getOccupancy returns {count, capacity, free, full}.
• Capacity is a single-row site_config table (admin-set; null = uncapped). Routes (routes/site.ts): GET /api/occupancy + GET /api/site-config (any role), PUT /api/site-config (admin; non-negative int or null).
• FULL gate is in the transient entry flow: occupancy.full → refuse (no ticket, no vehicle_entry, no open) + signed anomaly. Permit entry is NOT gated here — subscribers are admitted past transient-full (their own maxConcurrent still applies); occupancy can read over-capacity (free negative) when permits enter a full lot, as intended.
• UI SiteSettings: live occupancy + FULL badge (everyone); capacity editor (admin).
• Verified: fill to cap → 3rd transient refused; permit still admitted past full; exit frees a slot; RBAC (operator can't set capacity); verifyChain ok. Physical FULL-sign relay output is deferred (needs a sign device).

Open

• Zone/level granularity at launch vs. single capacity number.
• Reserve-for-permits threshold (a soft transient cap below the hard capacity) — currently permits are simply ungated; a tunable threshold is the richer version.
• Physical FULL-sign relay output (a sign-device role).
• The valet over-capacity mode + custody model (valet-overcapacity).