server+web: capacity / FULL gate (occupancy fold + transient refuse)

Occupancy is a fold over the signed ledger (entries minus exits per identity);
getOccupancy returns {count, capacity, free, full}. Capacity is a single-row
site_config table (admin-set; null = uncapped; migration 0001, additive).

FULL gate lives in the transient entry flow: when full, refuse (no ticket, no
vehicle_entry, no open) and sign an anomaly. Permit entry is NOT gated --
subscribers are admitted past transient-full (their own maxConcurrent still
applies), so occupancy can read over capacity by design (reserve-for-permits).

Routes: GET /api/occupancy + GET /api/site-config (any role), PUT
/api/site-config (admin; non-negative int or null). Web SiteSettings: live
occupancy + FULL badge (everyone), capacity editor (admin).

Verified: fill to cap -> 3rd transient refused; permit admitted past full; exit
frees a slot; RBAC (operator can't set, -5 -> 400); verifyChain ok. Physical
FULL-sign relay output deferred.

apps/server/src/entry-flow.ts

@@ -11,6 +11,7 @@ import {
 } from "@parking/devices";
 import type { FastifyBaseLogger } from "fastify";
 import type { DeviceInputEvent } from "./device-events.js";
+import { getOccupancy } from "./occupancy.js";
 import type { EventLog } from "./event-log.js";
 import type { LaneMap } from "./lane-map.js";
 
@@ -77,6 +78,22 @@ export class EntryFlow {
   }
 
   async #runEntry(lane: number, input: number, access: AccessControlDevice): Promise<void> {
+    // CAPACITY GATE (transient only). When the lot is full, refuse transient entry:
+    // no ticket, no vehicle_entry, no open — sign an anomaly. Permit holders are NOT
+    // gated here (their flow ignores site-full; their own maxConcurrent applies), so
+    // subscribers aren't locked out. "Full" is a soft policy seam for valet over-
+    // capacity later. See wiki/concepts/capacity-occupancy.md.
+    const occ = getOccupancy(this.#db);
+    if (occ.full) {
+      await this.#log.append({
+        type: "anomaly",
+        lane,
+        payload: { reason: `transient entry refused — lot full (${occ.count}/${occ.capacity})`, entryRefused: true, full: true },
+      });
+      this.#logger.warn(`transient entry REFUSED on lane ${lane}: full (${occ.count}/${occ.capacity})`);
+      return;
+    }
+
     const ticketId = newTicketId();
     const issuedAt = new Date().toISOString();
     const printers = await this.#loadPrinters(lane);

apps/server/src/occupancy.ts

@@ -0,0 +1,49 @@
+import { eq, ledgerEvents, siteConfig, type Db } from "@parking/db";
+
+// Occupancy = a FOLD over the signed ledger: the count of vehicle_entry events
+// with no matching vehicle_exit. Never a hand-maintained counter (which is
+// editable + drifts) — the chain is the truth. See wiki/concepts/capacity-occupancy.md.
+
+export interface Occupancy {
+  /** Cars currently inside (open sessions). */
+  readonly count: number;
+  /** Admin-set nominal capacity, or null = no limit. */
+  readonly capacity: number | null;
+  /** capacity − count, or null when uncapped. Can read 0 (or below) when full. */
+  readonly free: number | null;
+  /** True when count ≥ capacity (always false when uncapped). */
+  readonly full: boolean;
+}
+
+/** Count cars inside: entries minus exits, per identity, over the ledger. */
+export function occupancyCount(db: Db): number {
+  const rows = db
+    .select({ type: ledgerEvents.type, identity: ledgerEvents.identity })
+    .from(ledgerEvents)
+    .all();
+  const balance = new Map<string, number>();
+  for (const r of rows) {
+    if (r.type === "vehicle_entry") balance.set(r.identity ?? "", (balance.get(r.identity ?? "") ?? 0) + 1);
+    else if (r.type === "vehicle_exit") balance.set(r.identity ?? "", (balance.get(r.identity ?? "") ?? 0) - 1);
+  }
+  let open = 0;
+  for (const v of balance.values()) if (v > 0) open += 1;
+  return open;
+}
+
+/** Admin-set capacity (null = uncapped). */
+export function siteCapacity(db: Db): number | null {
+  const row = db.select().from(siteConfig).where(eq(siteConfig.id, 1)).get();
+  return row?.capacity ?? null;
+}
+
+export function getOccupancy(db: Db): Occupancy {
+  const count = occupancyCount(db);
+  const capacity = siteCapacity(db);
+  return {
+    count,
+    capacity,
+    free: capacity == null ? null : capacity - count,
+    full: capacity != null && count >= capacity,
+  };
+}

apps/server/src/routes/site.ts

@@ -0,0 +1,43 @@
+import type { FastifyInstance } from "fastify";
+import { eq, siteConfig, type Db } from "@parking/db";
+import { requireRole } from "../auth.js";
+import { getOccupancy } from "../occupancy.js";
+
+// Site config (capacity) + live occupancy. Occupancy is a fold over the signed
+// ledger; capacity is an admin-set knob. The FULL gate (refuse transient entry at
+// capacity) lives in the entry flow. See wiki/concepts/capacity-occupancy.md.
+
+interface SiteConfigBody {
+  /** Nominal capacity; null = no limit. */
+  capacity: number | null;
+}
+
+export async function siteRoutes(app: FastifyInstance, db: Db): Promise<void> {
+  const readGuard = requireRole("admin", "operator", "cashier", "readonly");
+  const writeGuard = requireRole("admin");
+
+  // Live occupancy: cars inside, capacity, free, full. Any signed-in role.
+  app.get("/api/occupancy", { preHandler: readGuard }, async () => getOccupancy(db));
+
+  // Read site config (capacity).
+  app.get("/api/site-config", { preHandler: readGuard }, async () => {
+    const row = db.select().from(siteConfig).where(eq(siteConfig.id, 1)).get();
+    return { capacity: row?.capacity ?? null };
+  });
+
+  // Set capacity (admin). null or 0+ integer.
+  app.put<{ Body: SiteConfigBody }>("/api/site-config", { preHandler: writeGuard }, async (req, reply) => {
+    const { capacity } = req.body ?? ({} as SiteConfigBody);
+    if (capacity != null && (!Number.isInteger(capacity) || capacity < 0)) {
+      return reply.code(400).send({ error: "capacity must be a non-negative integer or null" });
+    }
+    const existing = db.select().from(siteConfig).where(eq(siteConfig.id, 1)).get();
+    const updatedAt = new Date().toISOString();
+    if (existing) {
+      db.update(siteConfig).set({ capacity: capacity ?? null, updatedAt }).where(eq(siteConfig.id, 1)).run();
+    } else {
+      db.insert(siteConfig).values({ id: 1, capacity: capacity ?? null, updatedAt }).run();
+    }
+    return { capacity: capacity ?? null };
+  });
+}

apps/server/src/server.ts

@@ -21,6 +21,7 @@ import { eventRoutes } from "./routes/events.js";
 import { payRoutes } from "./routes/pay.js";
 import { permitRoutes } from "./routes/permits.js";
 import { shiftRoutes } from "./routes/shift.js";
+import { siteRoutes } from "./routes/site.js";
 import { tariffRoutes } from "./routes/tariffs.js";
 import { printerRoutes } from "./routes/printers.js";
 import { setupRoutes } from "./routes/setup.js";
@@ -129,6 +130,10 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
   const shiftService = new ShiftService(db, eventLog, app.log);
   await shiftRoutes(app, shiftService);
 
+  // Site config (capacity) + live occupancy. The FULL gate (refuse transient entry
+  // at capacity) is in the entry flow. See wiki/concepts/capacity-occupancy.md.
+  await siteRoutes(app, db);
+
   const unsubscribeInput = deviceEvents.onInput((e) => {
     // Resolve which lane the device belongs to. -1 marks "device fired but isn't
     // mapped to a lane" (assigned without a lane, or a stale id) — still recorded

apps/web/src/App.tsx

@@ -4,6 +4,7 @@ import { Login } from "./Login.js";
 import { PermitManager } from "./PermitManager.js";
 import { SetupWizard } from "./SetupWizard.js";
 import { ShiftControl } from "./ShiftControl.js";
+import { SiteSettings } from "./SiteSettings.js";
 import { TariffComposer } from "./TariffComposer.js";
 
 // Operator UI shell. Plain React (no admin framework) — the operator UI is
@@ -41,6 +42,7 @@ export function App() {
           </button>
         </span>
       </header>
+      <SiteSettings canEdit={user.role === "admin"} />
       {user.role !== "readonly" && <ShiftControl />}
       {user.role === "admin" ? (
         <>

apps/web/src/SiteSettings.tsx

@@ -0,0 +1,65 @@
+import { useEffect, useState } from "react";
+import { fetchOccupancy, fetchSiteConfig, setCapacity, type Occupancy } from "./api.js";
+
+// Live occupancy + capacity. Occupancy is shown to everyone (it's a fold over the
+// signed ledger); the capacity field is admin-editable. The FULL gate (refuse
+// transient entry at capacity) is enforced server-side in the entry flow.
+// See wiki/concepts/capacity-occupancy.md.
+
+export function SiteSettings({ canEdit }: { canEdit: boolean }) {
+  const [occ, setOcc] = useState<Occupancy | null>(null);
+  const [capInput, setCapInput] = useState("");
+  const [msg, setMsg] = useState<string | null>(null);
+
+  function reload() {
+    fetchOccupancy().then(setOcc).catch(() => {});
+  }
+  useEffect(() => {
+    reload();
+    fetchSiteConfig()
+      .then((c) => setCapInput(c.capacity == null ? "" : String(c.capacity)))
+      .catch(() => {});
+  }, []);
+
+  async function save() {
+    setMsg(null);
+    const raw = capInput.trim();
+    const capacity = raw === "" ? null : Math.round(Number(raw));
+    try {
+      await setCapacity(capacity);
+      reload();
+      setMsg("Capacity saved.");
+    } catch (e) {
+      setMsg((e as Error).message);
+    }
+  }
+
+  return (
+    <section style={{ marginTop: "1.5rem", padding: "0.75rem 1rem", border: "1px solid #ddd", borderRadius: 6, maxWidth: 460 }}>
+      <strong>Occupancy:</strong>{" "}
+      {occ == null ? (
+        "…"
+      ) : (
+        <>
+          <span style={{ fontWeight: 600 }}>{occ.count}</span>
+          {occ.capacity != null ? ` / ${occ.capacity}` : " (no capacity set)"}
+          {occ.capacity != null && (
+            <span style={{ color: "#666" }}> · {occ.free} free</span>
+          )}
+          {occ.full && <span style={{ color: "crimson", marginLeft: "0.5rem", fontWeight: 600 }}>FULL</span>}{" "}
+          <button type="button" onClick={reload} style={{ marginLeft: "0.5rem" }}>↻</button>
+        </>
+      )}
+      {canEdit && (
+        <div style={{ marginTop: "0.6rem" }}>
+          <label>
+            Capacity (blank = no limit):{" "}
+            <input value={capInput} onChange={(e) => setCapInput(e.target.value)} style={{ width: 80 }} placeholder="e.g. 120" />
+          </label>{" "}
+          <button type="button" onClick={save}>Save</button>
+          {msg && <span style={{ marginLeft: "0.5rem", color: "#555" }}>{msg}</span>}
+        </div>
+      )}
+    </section>
+  );
+}

apps/web/src/api.ts

@@ -304,3 +304,22 @@ export function openShift(): Promise<{ startedAt: string }> {
 export function closeShift(): Promise<ShiftReport> {
   return apiFetch("/api/shift/close", { method: "POST" });
 }
+
+// --- Site config / occupancy ----------------------------------------------
+
+export interface Occupancy {
+  count: number;
+  capacity: number | null;
+  free: number | null;
+  full: boolean;
+}
+
+export function fetchOccupancy(): Promise<Occupancy> {
+  return apiFetch("/api/occupancy");
+}
+export function fetchSiteConfig(): Promise<{ capacity: number | null }> {
+  return apiFetch("/api/site-config");
+}
+export function setCapacity(capacity: number | null): Promise<{ capacity: number | null }> {
+  return apiFetch("/api/site-config", { method: "PUT", body: JSON.stringify({ capacity }) });
+}