feat(booth): refusal snapshots, subscriber access medium, one-car-one-ticket entry

Three booth-integrity improvements that share the entry/exit flows and activity log. Refusal snapshots: previously only an accepted open captured a camera image; now every refusal/hold anomaly fires the directional camera too (a turned-away car is exactly the evidence wanted) — entry refused-full/held, exit refused closed/no-session/unpaid/grace-expired (booth + reader paths), refused subscription. A refused entry has no ticket id, so a synthetic REFUSED- ref keys the anomaly + photo together. Same fire-and-forget contract; failed captures still show as tiles. Subscriber access medium: the subscription flow already signed `via` (qr|card|plate) into entry/exit payloads; surface it as a typed LedgerPayload.via, a cyan chip in the ticker, and an "Entry medium" modal row (sq+en). Display-only. One car = one ticket: the entry button could be mashed to mint many tickets per car (corrupting occupancy + enabling ticket-shopping at exit) — the old #inFlight guard only blocked overlapping presses. Add a per-relay guard configured on the relay spec: PRESENCE mode (presenceInput ties ticketing to a vehicle loop on a Dingtian input — one ticket per car, re-armed when the loop clears) or COOLDOWN fallback (entryCooldownSec) when there's no barrier feedback. A suppressed press is unsigned device_events telemetry, not a signed anomaly. SetupWizard exposes both fields. Fail-closed entry and barrier-is-not-a-door invariants untouched; guard state is in-memory/rebuildable, starts armed after restart. Wiki: new entry-double-press; updated entry-exit-points, booth-console, index. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
2026-06-19 12:54:54 +02:00
parent bfb6ab0b36
commit 30e7fe85de
14 changed files with 436 additions and 28 deletions
@@ -11,7 +11,7 @@ export type Direction = "entry" | "exit" | "both";
 export type FlowDirection = "entry" | "exit";

 /** One relay on an access controller: which barrier it opens, in which direction,
- *  and (optionally) the input terminal its entry button is wired to. */
+ *  and (optionally) the input terminals its entry button + presence loop are wired to. */
 export interface RelaySpec {
  /** 1-based relay channel on the board (the driver's pulseOpen(doorId)). */
  readonly relay: number;
@@ -19,6 +19,21 @@ export interface RelaySpec {
  /** 1-based input terminal of the entry button that fires this relay (transient
   *  entry). Absent = no button at this barrier (subscriber/reader-driven only). */
  readonly button?: number;
+  /**
+   * Anti-double-press for the transient entry button (one car must yield ONE ticket).
+   * Two modes, chosen by what barrier feedback exists at this lane:
+   *  - PRESENCE (preferred, when a vehicle loop is wired): `presenceInput` = the
+   *    1-based input terminal of an induction loop / barrier presence signal on THIS
+   *    controller. A press prints only while a car is present, and no second ticket
+   *    issues until the loop CLEARS (car drove in) and a new car re-occupies it. This
+   *    makes one-car-one-ticket physical.
+   *  - COOLDOWN (fallback, no feedback): `entryCooldownSec` suppresses repeat presses
+   *    on this relay for N seconds after a ticket prints. A pure timer — mitigation,
+   *    not a guarantee. Used when `presenceInput` is unset (or as a secondary guard).
+   * Both absent = no guard (legacy behaviour). See wiki/concepts/entry-double-press.md.
+   */
+  readonly presenceInput?: number;
+  readonly entryCooldownSec?: number;
 }

 /** Access controller config (the `relays[]` map + connection fields). */
@@ -38,11 +53,17 @@ interface BoundConfig {
  readonly [k: string]: unknown;
 }

-/** A resolved barrier: the controller row + the specific relay to pulse. */
+/** A resolved barrier: the controller row + the specific relay to pulse. Carries the
+ *  transient-entry anti-double-press config (presence loop / cooldown) when resolved
+ *  from a button press, so the entry flow can enforce one-car-one-ticket. */
 export interface ResolvedRelay {
  readonly controller: DeviceRow;
  readonly relay: number;
  readonly direction: Direction;
+  /** 1-based presence-loop input gating this relay's entry (when wired). */
+  readonly presenceInput?: number;
+  /** Cooldown seconds suppressing repeat presses (fallback when no presence loop). */
+  readonly entryCooldownSec?: number;
 }

 /** All enabled access controller rows. */
@@ -76,6 +97,31 @@ export function relayForButton(db: Db, controllerId: string, terminal: number):
  const spec = relaysOf(row).find((r) => r.button === terminal);
  if (!spec) return null;
  if (spec.direction !== "entry" && spec.direction !== "both") return null;
+  return {
+    controller: row,
+    relay: spec.relay,
+    direction: spec.direction,
+    presenceInput: spec.presenceInput,
+    entryCooldownSec: spec.entryCooldownSec,
+  };
+}
+
+/**
+ * Resolve a PRESENCE-LOOP input edge to the entry relay it gates: the controller with
+ * this deviceId, and the relay whose `presenceInput` terminal matches the fired input.
+ * Lets the entry flow track "a car is physically at this entry barrier" so it issues
+ * exactly one ticket per car. Only entry/both relays gate transient entry. Null otherwise.
+ */
+export function relayForPresence(db: Db, controllerId: string, terminal: number): ResolvedRelay | null {
+  const row = db
+    .select()
+    .from(devices)
+    .where(and(eq(devices.id, controllerId), eq(devices.category, "access")))
+    .get();
+  if (!row || !row.enabled) return null;
+  const spec = relaysOf(row).find((r) => r.presenceInput === terminal);
+  if (!spec) return null;
+  if (spec.direction !== "entry" && spec.direction !== "both") return null;
  return { controller: row, relay: spec.relay, direction: spec.direction };
 }

@@ -1,5 +1,5 @@
-import { randomInt } from "node:crypto";
-import { eq, sessions, siteConfig, type Db, type DeviceRow } from "@parking/db";
+import { randomInt, randomUUID } from "node:crypto";
+import { deviceEvents as deviceEventsTable, eq, sessions, siteConfig, type Db, type DeviceRow } from "@parking/db";
 import {
  NoPrinterAvailableError,
  printWithFailover,
@@ -15,7 +15,7 @@ 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 { devicesByDirection, relayForButton, type ResolvedRelay } from "./device-resolve.js";
+import { devicesByDirection, relayForButton, relayForPresence, type ResolvedRelay } from "./device-resolve.js";
 import { snapshotAsync } from "./snapshot.js";

 // The transient ENTRY flow: a button press → print a ticket → sign a vehicle_entry
@@ -35,6 +35,31 @@ import { snapshotAsync } from "./snapshot.js";
 //
 // Ordering: print → (ok) sign vehicle_entry → pulseOpen → snapshot → cache session.
 //                   (fail) sign anomaly, stop.
+//
+// ONE CAR = ONE TICKET (anti-double-press). The entry button can be physically held
+// or mashed; without a guard each press mints a fresh ticket + signed vehicle_entry
+// (corrupting occupancy and letting a transient shop the cheapest ticket at exit). The
+// guard is per-relay and CONFIGURED on the relay spec (config.relays[]), chosen by what
+// barrier feedback exists at the lane:
+//   - PRESENCE loop (preferred): `presenceInput` ties ticketing to a real vehicle. A
+//     press prints only while a car is present, and NO second ticket issues until the
+//     loop CLEARS (car drove in) and a new car re-occupies it. We observe the loop's
+//     input edges to track presence + "armed" per relay.
+//   - COOLDOWN (fallback, no feedback): `entryCooldownSec` suppresses repeat presses on
+//     the relay for N seconds after a ticket. A timer — mitigation, not a guarantee.
+// A suppressed press is recorded as UNSIGNED telemetry (a no-op, not a fraud anomaly).
+// See wiki/concepts/entry-double-press.md.
+
+/** Per-relay anti-double-press state, keyed `controllerId:relay`. */
+interface RelayGuardState {
+  /** Last successful ticket time (ms epoch) — drives the cooldown check. */
+  lastTicketAt: number;
+  /** PRESENCE mode: is a vehicle currently on the loop? (from loop input edges) */
+  present: boolean;
+  /** PRESENCE mode: ready to issue a ticket for a NEW car. Set false after a ticket
+   *  prints; re-armed when the loop CLEARS (the car drove through). */
+  armed: boolean;
+}

 export class EntryFlow {
  readonly #db: Db;
@@ -42,6 +67,8 @@ export class EntryFlow {
  readonly #logger: FastifyBaseLogger;
  /** Guard against double-fire from the same physical press (on edge only). */
  readonly #inFlight = new Set<string>();
+  /** Per-relay one-car-one-ticket state (presence + cooldown), keyed controllerId:relay. */
+  readonly #guard = new Map<string, RelayGuardState>();

  constructor(db: Db, log: EventLog, logger: FastifyBaseLogger) {
    this.#db = db;
@@ -49,10 +76,20 @@ export class EntryFlow {
    this.#logger = logger;
  }

-  /** Handle a device input edge. Acts only on the rising ("on") edge of an entry
-   *  button — an input terminal mapped to an entry relay on its controller. */
+  /** Handle a device input edge. Two kinds of edge matter to this flow:
+   *  (1) an ENTRY BUTTON press (rising edge) → run entry, subject to the per-relay
+   *      anti-double-press guard; (2) a PRESENCE LOOP edge (either direction) → update
+   *      presence state so the guard knows when a car arrives/leaves. The same physical
+   *      input is never both, so we resolve each independently. */
  async onInput(e: DeviceInputEvent): Promise<void> {
-    if (e.edge !== "on") return; // release edge is just telemetry
+    // Presence-loop edge (both directions matter): keep the per-relay state current.
+    const presence = relayForPresence(this.#db, e.deviceId, e.input);
+    if (presence) {
+      this.#onPresenceEdge(presence, e.edge);
+      return; // a loop input is not a button — nothing else to do
+    }
+
+    if (e.edge !== "on") return; // for buttons, the release edge is just telemetry

    // The firing device must be an access controller, and the pressed input terminal
    // must map to an ENTRY (or both) relay — that's an entry button. Anything else
@@ -60,6 +97,14 @@ export class EntryFlow {
    const resolved = relayForButton(this.#db, e.deviceId, e.input);
    if (!resolved) return;

+    // ANTI-DOUBLE-PRESS: is this press allowed to issue a ticket? (presence/cooldown)
+    const suppressed = this.#suppressReason(resolved);
+    if (suppressed) {
+      this.#recordSuppressedPress(e, resolved, suppressed);
+      this.#logger.info(`entry press suppressed (${this.#relayKey(resolved)}): ${suppressed}`);
+      return;
+    }
+
    const key = `${e.deviceId}:${e.input}`;
    if (this.#inFlight.has(key)) return; // ignore re-fire while one is processing
    this.#inFlight.add(key);
@@ -72,6 +117,88 @@ export class EntryFlow {
    }
  }

+  /** Stable per-relay key for the guard map. */
+  #relayKey(r: ResolvedRelay): string {
+    return `${r.controller.id}:${r.relay}`;
+  }
+
+  /** Lazily get (or create) the guard state for a relay. New relays start ARMED and
+   *  with no car present, so the first press on a fresh lane works immediately. */
+  #guardState(r: ResolvedRelay): RelayGuardState {
+    const key = this.#relayKey(r);
+    let s = this.#guard.get(key);
+    if (!s) {
+      s = { lastTicketAt: 0, present: false, armed: true };
+      this.#guard.set(key, s);
+    }
+    return s;
+  }
+
+  /** Apply a presence-loop edge to a relay's state. The car ARRIVING re-arms ticketing;
+   *  the car LEAVING the loop (after its entry) re-arms for the NEXT car. */
+  #onPresenceEdge(r: ResolvedRelay, edge: "on" | "off"): void {
+    const s = this.#guardState(r);
+    if (edge === "on") {
+      s.present = true; // a vehicle is at the barrier
+    } else {
+      // Loop cleared: the car drove through (or backed off). Re-arm for the next car —
+      // this is the gate that makes a *new* car necessary before another ticket.
+      s.present = false;
+      s.armed = true;
+    }
+  }
+
+  /** Why a press should be SUPPRESSED (no ticket), or null if it may proceed.
+   *  PRESENCE mode is authoritative when a loop is wired; otherwise COOLDOWN; else no
+   *  guard (legacy). The two can coexist — presence first, cooldown as a backstop. */
+  #suppressReason(r: ResolvedRelay): string | null {
+    const s = this.#guardState(r);
+
+    if (typeof r.presenceInput === "number") {
+      // Physical one-car-one-ticket: a car must be present AND we must be armed (no
+      // ticket already issued for this still-present car).
+      if (!s.present) return "no vehicle at the barrier (presence loop clear)";
+      if (!s.armed) return "ticket already issued for the car at the barrier";
+      return null;
+    }
+
+    if (typeof r.entryCooldownSec === "number" && r.entryCooldownSec > 0) {
+      const elapsed = Date.now() - s.lastTicketAt;
+      if (elapsed < r.entryCooldownSec * 1000) {
+        const remain = Math.ceil((r.entryCooldownSec * 1000 - elapsed) / 1000);
+        return `within ${r.entryCooldownSec}s entry cooldown (${remain}s left)`;
+      }
+    }
+    return null;
+  }
+
+  /** Record a suppressed (repeat/no-car) entry press as UNSIGNED telemetry — a no-op,
+   *  not a fraud anomaly, so the signed ledger stays clean (the operator's choice). */
+  #recordSuppressedPress(e: DeviceInputEvent, r: ResolvedRelay, reason: string): void {
+    try {
+      this.#db
+        .insert(deviceEventsTable)
+        .values({
+          id: randomUUID(),
+          deviceId: e.deviceId,
+          category: "access",
+          kind: "input",
+          detail: {
+            driverId: e.driverId,
+            input: e.input,
+            edge: e.edge,
+            entrySuppressed: true,
+            relay: r.relay,
+            reason,
+          },
+          occurredAt: e.at,
+        })
+        .run();
+    } catch (err) {
+      this.#logger.error(`suppressed-press telemetry insert failed: ${(err as Error).message}`);
+    }
+  }
+
  async #runEntry(resolved: ResolvedRelay): Promise<void> {
    // CAPACITY GATE (transient only). When the lot is full, refuse transient entry:
    // no ticket, no vehicle_entry, no open — sign an anomaly. Subscribers are NOT
@@ -80,14 +207,20 @@ export class EntryFlow {
    // capacity later. See wiki/concepts/capacity-occupancy.md.
    const occ = getOccupancy(this.#db);
    if (occ.full) {
+      // No ticket id exists for a refused entry, so mint a synthetic ref to key the
+      // anomaly + its evidence snapshot together. The operator wants the photo of WHO
+      // was turned away (a fraud/dispute signal), so we still fire the entry camera.
+      const refusedRef = `REFUSED-${randomUUID().replace(/-/g, "").slice(0, 12)}`;
      await this.#log.append({
        type: "anomaly",
+        identity: refusedRef,
        payload: {
          ...reasonPayload("entry.refused.full", { count: occ.count, capacity: occ.capacity ?? 0 }),
          entryRefused: true,
          full: true,
        },
      });
+      this.#fireSnapshot("entry", refusedRef);
      this.#logger.warn(`transient entry REFUSED: full (${occ.count}/${occ.capacity})`);
      return;
    }
@@ -103,6 +236,13 @@ export class EntryFlow {
        d.printTicket(ticket),
      );
      this.#logger.info(`entry ticket ${ticketId} printed on ${printedBy}`);
+      // ONE CAR = ONE TICKET: a ticket is now out for the car at this barrier. Disarm +
+      // stamp the cooldown so a repeat press (held button / mashing) issues no second
+      // ticket. PRESENCE mode re-arms when the loop clears (car drove in); COOLDOWN mode
+      // re-allows after entryCooldownSec. Done on the print success, NOT the open.
+      const guard = this.#guardState(resolved);
+      guard.lastTicketAt = Date.now();
+      guard.armed = false;
    } catch (err) {
      // HOLD: do not open, do not record a vehicle_entry. Sign an anomaly so the
      // failed attempt is in the tamper-evident record for the operator.
@@ -113,6 +253,8 @@ export class EntryFlow {
        identity: ticketId,
        payload: { ...reasonPayload("entry.held.noTicket", { detail: reason }), ticketPrinted: false },
      });
+      // Capture who is held at the barrier (evidence for the operator handling the car).
+      this.#fireSnapshot("entry", ticketId);
      this.#logger.warn(`entry HELD: ${reason} (barrier NOT opened)`);
      return;
    }
@@ -146,12 +288,7 @@ export class EntryFlow {

    // 3b. SNAPSHOT — fire the entry camera(s), never awaited (evidence, not a gate;
    //     a camera failure must not delay or block the already-open barrier).
-    void snapshotAsync({
-      db: this.#db,
-      direction: "entry",
-      identity: ticketId,
-      logger: this.#logger,
-    }).catch((err) => this.#logger.error(`entry snapshot error: ${(err as Error).message}`));
+    this.#fireSnapshot("entry", ticketId);

    // 4. Update the session projection cache (rebuildable from the ledger; this is
    //    just a fast read-model, never the source of truth).
@@ -167,6 +304,15 @@ export class EntryFlow {
    }
  }

+  /** Fire the entry camera(s) for an identity; never awaited (evidence, not a gate).
+   *  Used on both the OPEN path and the refused/held anomaly paths — a turned-away or
+   *  held car is exactly when the operator wants the photo. */
+  #fireSnapshot(direction: "entry", identity: string): void {
+    void snapshotAsync({ db: this.#db, direction, identity, logger: this.#logger }).catch((err) =>
+      this.#logger.error(`entry snapshot error: ${(err as Error).message}`),
+    );
+  }
+
  /** Build a live access adapter from a resolved controller row, or null. */
  #buildAccess(row: DeviceRow): AccessControlDevice | null {
    const driver = registry.get(row.driverId);
@@ -99,6 +99,7 @@ export class ExitFlow {
      if (!view || !view.open) {
        const rp = reasonPayload(view ? "exit.refused.closed" : "exit.refused.noSession");
        await this.#log.append({ type: "anomaly", identity: id, payload: { ...rp, exitRefused: true, source: "booth" } });
+        this.#fireExitSnapshot(id);
        this.#logger.warn(`booth exit refused (${id}): ${rp.reason}`);
        return { ok: false, status: view ? "closed" : "no_session", reason: rp.reason };
      }
@@ -112,6 +113,7 @@ export class ExitFlow {
      if (!freeGrace && (!paid || !withinGrace)) {
        const rp = reasonPayload(paid ? "exit.refused.graceExpired" : "exit.refused.unpaid");
        await this.#log.append({ type: "anomaly", identity: id, payload: { ...rp, exitRefused: true, source: "booth" } });
+        this.#fireExitSnapshot(id);
        this.#logger.warn(`booth exit refused (${id}): ${rp.reason}`);
        return { ok: false, status: paid ? "grace_expired" : "unpaid", reason: rp.reason };
      }
@@ -274,6 +276,7 @@ export class ExitFlow {
        identity: e.value,
        payload: { ...rp, exitRefused: true },
      });
+      this.#fireExitSnapshot(e.value);
      this.#logger.warn(`exit refused: no open session for ${e.value}`);
      return { accepted: false, direction: "exit", reason: rp.reason };
    }
@@ -314,6 +317,7 @@ export class ExitFlow {
        identity: e.value,
        payload: { ...rp, exitRefused: true, sessionRef: e.value },
      });
+      this.#fireExitSnapshot(e.value);
      this.#logger.warn(`exit refused (${e.value}): ${rp.reason}`);
      return { accepted: false, direction: "exit", reason: rp.reason };
    }
@@ -98,8 +98,11 @@ export class SubscriptionFlow {
  }

  async #run(resolved: ResolvedRelay, e: DeviceReadEvent, m: SubscriptionMatch): Promise<ReadOutcome> {
+    // The physical side the reader sits at — used to fire the right camera on a refusal
+    // that happens BEFORE we infer the entry/exit verb ("both" defers to entry).
+    const lane: FlowDirection = resolved.direction === "exit" ? "exit" : "entry";
    const sub = this.#db.select().from(subscriptions).where(eq(subscriptions.id, m.subscriptionId)).get();
-    if (!sub) return { accepted: false, reason: await this.#reject(m, "sub.refused.notFound") };
+    if (!sub) return { accepted: false, reason: await this.#reject(m, lane, "sub.refused.notFound") };

    // Validity: active + within the coverage window.
    const now = new Date().toISOString();
@@ -108,7 +111,7 @@ export class SubscriptionFlow {
      (sub.validFrom != null && now < sub.validFrom) ||
      (sub.validTo != null && now > sub.validTo);
    if (invalid) {
-      const reason = await this.#reject(m, "sub.refused.outOfWindow", { status: sub.status });
+      const reason = await this.#reject(m, lane, "sub.refused.outOfWindow", { status: sub.status });
      return { accepted: false, reason };
    }

@@ -136,7 +139,7 @@ export class SubscriptionFlow {
      // subscription has NOTHING open, an exit read is a no-op anti-passback signal.
      const oldest = open[0];
      if (!oldest) {
-        const reason = await this.#reject(m, "sub.refused.noSession");
+        const reason = await this.#reject(m, "exit", "sub.refused.noSession");
        return { accepted: false, direction: "exit", reason };
      }
      const occurrenceId = oldest.identity;
@@ -156,7 +159,7 @@ export class SubscriptionFlow {
    // ENTRY: enforce the car-count binding (maxConcurrent), then sign + open. Mint a
    // fresh per-occurrence id so a fleet can have several open at once.
    if (sub.maxConcurrent != null && open.length >= sub.maxConcurrent) {
-      const reason = await this.#reject(m, "sub.refused.atCapacity", {
+      const reason = await this.#reject(m, "entry", "sub.refused.atCapacity", {
        inUse: open.length,
        max: sub.maxConcurrent,
      });
@@ -227,10 +230,14 @@ export class SubscriptionFlow {
    return open;
  }

-  /** Sign a refused-subscription anomaly with a localizable reason code, and return
-   *  the rendered English reason for the caller's ReadOutcome. */
+  /** Sign a refused-subscription anomaly with a localizable reason code, fire the
+   *  directional evidence camera, and return the rendered English reason for the
+   *  caller's ReadOutcome. `dir` is the lane the refusal happened at (entry/exit) so
+   *  the right camera captures the turned-away subscriber. `via` records which
+   *  credential was presented. */
  async #reject(
    m: SubscriptionMatch,
+    dir: FlowDirection,
    code: ReasonCode,
    params?: Record<string, string | number>,
  ): Promise<string> {
@@ -239,24 +246,28 @@ export class SubscriptionFlow {
      type: "anomaly",
      identity: m.carKey,
      // `permitId`/`permitRefused` are the on-chain field names (immutable).
-      payload: { ...rp, permitId: m.subscriptionId, permitRefused: true },
+      payload: { ...rp, permitId: m.subscriptionId, permitRefused: true, via: m.via },
    });
+    this.#fireSnapshot(dir, m.carKey);
    this.#logger.warn(`subscription refused (${m.carKey}): ${rp.reason}`);
    return rp.reason;
  }

+  /** Fire the directional camera(s) for a refused-subscription event; never awaited
+   *  (evidence, not a gate). The accepted entry/exit paths snapshot inside #open. */
+  #fireSnapshot(dir: FlowDirection, identity: string): void {
+    void snapshotAsync({ db: this.#db, direction: dir, identity, logger: this.#logger }).catch((err) =>
+      this.#logger.error(`subscription snapshot error: ${(err as Error).message}`),
+    );
+  }
+
  async #open(resolved: ResolvedRelay, dir: FlowDirection, carKey: string, what: string): Promise<void> {
    const access = this.#buildAccess(resolved.controller);
    if (access) await access.pulseOpen(resolved.relay);
    else this.#logger.warn(`${what} signed for ${carKey} but the ${dir} relay won't build`);

    // SNAPSHOT — fire the directional camera(s), never awaited (evidence, not a gate).
-    void snapshotAsync({
-      db: this.#db,
-      direction: dir,
-      identity: carKey,
-      logger: this.#logger,
-    }).catch((err) => this.#logger.error(`subscription snapshot error: ${(err as Error).message}`));
+    this.#fireSnapshot(dir, carKey);
  }

  #closeCache(carKey: string): void {
@@ -91,6 +91,16 @@ function eventBadges(p: LedgerEvent["payload"]): string[] {
  return keys;
 }

+/** The i18n key for a subscriber's access medium (`via`), or null. Lets the activity
+ *  log show HOW a subscriber entered/left — QR code, RFID card/chip, or plate. */
+function viaKey(p: LedgerEvent["payload"]): string | null {
+  if (!p) return null;
+  if (p.via === "qr") return "booth.viaQr";
+  if (p.via === "card") return "booth.viaCard";
+  if (p.via === "plate") return "booth.viaPlate";
+  return null;
+}
+
 /** A short money summary for payment events (e.g. "350.00 ALL"). */
 function paymentSummary(p: LedgerEvent["payload"]): string | null {
  if (!p || typeof p.amountMinor !== "number" || !p.currency) return null;
@@ -115,8 +125,9 @@ function EventRow({ e, onOpen }: { e: LedgerEvent; onOpen: (e: LedgerEvent) => v
  const reason = renderReason(p, t);
  const amount = paymentSummary(p);
  const badges = eventBadges(p);
+  const via = viaKey(p);
  const detail = reason ?? amount ?? (isAnomaly ? t("booth.evtNoReason") : null);
-  const showDetail = detail != null || badges.length > 0;
+  const showDetail = detail != null || badges.length > 0 || via != null;

  // The whole row is a button → opens the event-detail modal (full payload + the
  // session's entry/exit snapshots). A grid keeps the time/label/identity/index
@@ -144,6 +155,11 @@ function EventRow({ e, onOpen }: { e: LedgerEvent; onOpen: (e: LedgerEvent) => v
              {t(k)}
            </span>
          ))}
+          {via && (
+            <span className="rounded-sm bg-term-cyan/15 px-1.5 py-px text-[10px] font-semibold uppercase tracking-wide text-term-cyan">
+              {t(via)}
+            </span>
+          )}
          {detail && (
            <span className={`text-[11px] ${isAnomaly ? "text-term-red/90" : "text-term-muted"}`}>{detail}</span>
          )}
@@ -238,6 +254,11 @@ function EventDetailModal({ e, onClose }: { e: LedgerEvent; onClose: () => void
            </DetailRow>
          )}
          {typeof p?.tender === "string" && <DetailRow label={t("booth.edTender")}>{p.tender}</DetailRow>}
+          {viaKey(p) && (
+            <DetailRow label={t("booth.edVia")}>
+              <span className="text-term-cyan">{t(viaKey(p)!)}</span>
+            </DetailRow>
+          )}
          {category && <DetailRow label={t("booth.edCategory")}>{category}</DetailRow>}
          {plate && <DetailRow label={t("booth.edPlate")}>{plate}</DetailRow>}
          {operator && <DetailRow label={t("booth.edOperator")}>{operator}</DetailRow>}
@@ -422,6 +422,8 @@ function DeviceForm({
        relay: r.relay,
        direction: r.direction,
        ...(r.button ? { button: r.button } : {}),
+        ...(r.presenceInput ? { presenceInput: r.presenceInput } : {}),
+        ...(r.entryCooldownSec ? { entryCooldownSec: r.entryCooldownSec } : {}),
      }));
    } else if (controllerId && boundRelay !== "") {
      out.controllerId = controllerId;
@@ -698,6 +700,36 @@ function RelayEditor({ relays, onChange }: { relays: RelaySpec[]; onChange: (r:
              />
            </label>
          )}
+          {(r.direction === "entry" || r.direction === "both") && (
+            <label className="inline-flex items-center gap-1.5 text-[12px] text-term-muted" title={t("setup.presenceInputHint")}>
+              {t("setup.presenceInput")}
+              <input
+                type="number"
+                min={1}
+                value={r.presenceInput ?? ""}
+                placeholder="—"
+                className="input input-sm w-16"
+                onChange={(e) =>
+                  update(i, { presenceInput: e.target.value === "" ? undefined : Number(e.target.value) })
+                }
+              />
+            </label>
+          )}
+          {(r.direction === "entry" || r.direction === "both") && !r.presenceInput && (
+            <label className="inline-flex items-center gap-1.5 text-[12px] text-term-muted" title={t("setup.entryCooldownHint")}>
+              {t("setup.entryCooldown")}
+              <input
+                type="number"
+                min={0}
+                value={r.entryCooldownSec ?? ""}
+                placeholder="—"
+                className="input input-sm w-16"
+                onChange={(e) =>
+                  update(i, { entryCooldownSec: e.target.value === "" ? undefined : Number(e.target.value) })
+                }
+              />
+            </label>
+          )}
          {relays.length > 1 && (
            <button type="button" className="btn btn-ghost btn-sm" onClick={() => remove(i)}>
              ✕
@@ -254,6 +254,11 @@ export interface RelaySpec {
  direction: Direction;
  /** Input terminal of the entry button that fires this relay (transient entry). */
  button?: number;
+  /** Anti-double-press (one car = one ticket). PRESENCE: input terminal of a vehicle
+   *  loop/barrier-feedback signal; a press prints only with a car present + re-arms when
+   *  it clears. COOLDOWN (fallback, no feedback): suppress repeat presses for N seconds. */
+  presenceInput?: number;
+  entryCooldownSec?: number;
 }

 export interface TestResult {
@@ -160,6 +160,10 @@ export const en: Catalog = {
    edRawPayload: "Raw signed payload",
    edOccurrence: "Occurrence id",
    subscriber: "Subscriber",
+    edVia: "Entry medium",
+    viaQr: "QR code",
+    viaCard: "RFID card/chip",
+    viaPlate: "Plate",
  },
  // Localized messages for the signed REASON_CODES (see @parking/shared). Keys MUST
  // match the codes 1:1; {{param}} placeholders are filled from the event's
@@ -286,6 +290,12 @@ export const en: Catalog = {
      "Each relay opens one barrier. Set its direction; for transient entry, set which input terminal the entry button is wired to.",
    relay: "Relay",
    entryButtonTerminal: "Entry button on terminal",
+    presenceInput: "Presence loop (terminal)",
+    presenceInputHint:
+      "Input terminal the vehicle-presence loop / barrier feedback is wired to. When set, exactly ONE ticket issues per car: the button prints only while a car is present, and no second ticket issues until the loop clears (the car drove in) and a new car re-occupies it. Preferred mode.",
+    entryCooldown: "Cooldown after ticket (s)",
+    entryCooldownHint:
+      "When there's no presence loop: repeat button presses are suppressed for this many seconds after a ticket. A fallback (not a guarantee) — a determined abuser can wait it out.",
    addRelay: "+ Add relay",
    whichBarrier: "Which barrier does this device serve?",
    controller: "Controller",
@@ -164,6 +164,10 @@ export const sq = {
    edRawPayload: "Të dhënat e papërpunuara të nënshkruara",
    edOccurrence: "ID e hyrjes",
    subscriber: "Abonent",
+    edVia: "Mënyra e hyrjes",
+    viaQr: "Kod QR",
+    viaCard: "Kartë/çip RFID",
+    viaPlate: "Targë",
  },
  // Mesazhet e përkthyera për REASON_CODES e nënshkruara (shih @parking/shared).
  // Çelësat përputhen 1:1 me kodet; {{param}} mbushet nga reasonParams i eventit.
@@ -295,6 +299,12 @@ export const sq = {
      "Çdo rele hap një barrierë. Cakto drejtimin e saj; për hyrje kalimtare, cakto në cilin terminal hyrës është lidhur butoni i hyrjes.",
    relay: "Rele",
    entryButtonTerminal: "Butoni i hyrjes në terminalin",
+    presenceInput: "Sensori i pranisë (terminali)",
+    presenceInputHint:
+      "Terminali hyrës ku është lidhur sensori/laku i pranisë së automjetit. Kur vendoset, lëshohet vetëm NJË biletë për automjet: butoni printon vetëm kur ka makinë, dhe nuk lëshon biletë të dytë derisa laku të lirohet (makina hyri) dhe një makinë e re ta zërë. Mënyra e preferuar.",
+    entryCooldown: "Pritje pas biletës (sek)",
+    entryCooldownHint:
+      "Kur nuk ka sensor pranie: shtypjet e përsëritura të butonit shtypen për kaq sekonda pas një bilete. Zgjidhje rezervë (jo garanci) — një abuzues mund ta presë afatin.",
    addRelay: "+ Shto rele",
    // Binding picker.
    whichBarrier: "Cilën barrierë shërben kjo pajisje?",
@@ -152,6 +152,11 @@ export interface LedgerPayload {
  /** Interpolation values for `reasonCode`'s message template (counts, ids, ratios).
   *  Signed alongside the code so the rendered sentence is reproducible. */
  readonly reasonParams?: Record<string, string | number>;
+  /** subscription entry/exit: which credential the subscriber presented — `"qr"`
+   *  (QR code), `"card"` (RFID/NFC card or chip), or `"plate"` (bound plate / LPR).
+   *  Signed so the activity log can show HOW a subscriber entered/left (e.g. "via QR"),
+   *  and so a lost-card investigation can trace which credential was used. */
+  readonly via?: "card" | "qr" | "plate";
  /** plate/vehicle from the vision service (advisory). */
  readonly plate?: string;
  readonly plateConfidence?: number;
@@ -90,6 +90,18 @@ what happened." Now every event is **self-describing and clickable**:
  operator can tell "no camera" from "camera failed". (Surfaced a real incident: a subscriber's entry
  snapshot failed `EHOSTUNREACH` while the exit one succeeded — by design a snapshot is *evidence, not
  a gate*, so the open proceeded and only the image was missing.)
+- **Subscriber access medium (`via`).** A subscription entry/exit row now shows HOW the subscriber was
+  identified — **QR code / RFID card·chip / plate** — as a cyan chip in the ticker and a labelled
+  "Entry medium" row in the detail modal. The flow already signed `via` (`"qr"|"card"|"plate"`) into
+  the [[subscription]] entry/exit payload; this just surfaces it (a lost-card investigation can now see
+  which credential opened a barrier). Rides the existing localized-display pattern, not a new signed
+  field.
+- **Refused entry/exit now carry a snapshot too (2026-06-19).** Previously only an *accepted* open
+  captured an image. Now refusal/hold anomalies fire the directional camera as well (the photo of a
+  turned-away car is exactly the evidence an operator/auditor wants) — so the detail modal's snapshot
+  strip is populated for "lot full", unpaid-exit, no-session, and refused-subscription events. See
+  [[entry-exit-points]] for the coverage list and the synthetic `REFUSED-…` key used when a refused
+  entry has no ticket id.

 ## The shift control (header) + the booth gate

@@ -0,0 +1,90 @@
+---
+type: concept
+tags: [parking, entry, anti-fraud, safety, devices]
+sources: []
+updated: 2026-06-19
+status: open
+---
+
+# One car = one ticket (entry anti-double-press)
+
+A transient [[parking-session|entry]] is a button press → print a ticket → sign a `vehicle_entry`
+→ open the barrier. **Nothing stopped a driver pressing the button repeatedly** and minting a fresh
+ticket each time — a real flaw found 2026-06-19. The damage is threefold:
+
+- **Ticket spam.** One car walks away with a fistful of tickets.
+- **Occupancy corruption.** Each press signs a `vehicle_entry`, so [[capacity-occupancy|occupancy]]
+  (a fold over open sessions) counts one car as many — the lot reads "full" with empty spaces.
+- **Ticket-shopping at exit.** With several open sessions for the same car, the driver pays the
+  cheapest and exits on it; the rest linger. A direct [[threat-model|booth/customer]] abuse.
+
+The old `#inFlight` guard only blocked *overlapping* presses (it released in `finally`), so
+press → print → press again issued a second ticket immediately. That is not enough.
+
+## The fix is PER-RELAY CONFIG, chosen by available barrier feedback
+
+The guard lives on the entry relay's spec (`config.relays[]` — see [[entry-exit-points]]), because
+whether real one-car-one-ticket is *possible* depends on the hardware at that lane. Two modes:
+
+### PRESENCE mode (preferred — when a vehicle loop is wired)
+`relays[].presenceInput` = the 1-based input terminal of an **induction loop / barrier presence
+signal** on the same [[dingtian-relay|controller]] (the Dingtian's inputs are decoupled from its
+relays, and loops are already in the [[bom]]). The rule makes one-car-one-ticket **physical**:
+
+- A press prints **only while a car is present** on the loop.
+- After a ticket prints, the relay is **disarmed** — no second ticket — **until the loop CLEARS**
+  (the car drove through = it entered) **and a new car re-occupies** it.
+
+So mashing the button while sitting on the loop does nothing; a *new* car must physically arrive
+before another ticket can issue. The flow observes the loop's input edges (both directions) to track
+`present` + `armed` per relay. This is how real lanes behave.
+
+### COOLDOWN mode (fallback — no barrier feedback)
+When no loop is wired, `relays[].entryCooldownSec` suppresses repeat presses on that relay for N
+seconds after a ticket (default unset = no guard; a sensible value is ~10–12 s — long enough for the
+car to pull through, short enough not to block the next legitimate car). It is a **timer, a
+mitigation, not a guarantee** — a determined abuser can wait it out. Use it only where presence
+feedback isn't available; prefer wiring a loop.
+
+The two can coexist (presence first, cooldown as a backstop), but presence is authoritative when set.
+
+## A suppressed press is a NO-OP, not an anomaly
+
+A blocked/repeat press is recorded as **unsigned [[device-events|telemetry]]** (a `device_events`
+`kind:"input"` row with `entrySuppressed:true` + the reason), **not** a signed ledger anomaly. It
+isn't fraud — it's the system correctly refusing to double-issue — so it stays out of the immutable
+chain and off the red activity-log feed. (Operator's call, 2026-06-19.) The press is still auditable
+in telemetry if ever needed.
+
+## Invariants preserved
+
+- **Fail-closed entry is untouched.** A suppressed press simply does nothing; the printer-down HOLD
+  path ([[append-only-event-chain]]) and the [[fail-state-safety]] rules are unchanged.
+- **The barrier is still intent-only.** No timed close; presence is only a *gate on ticketing*, not
+  a barrier-close trigger ([[barrier-not-a-door]]).
+- **State is in-memory + rebuildable.** The per-relay `armed/present` map is runtime state on the
+  host (single-writer); it is derived from live input edges, never the source of truth. A restart
+  starts armed (the first press after a restart works), which is the safe default.
+
+## As-built (2026-06-19)
+
+- `RelaySpec` gains `presenceInput?` + `entryCooldownSec?` (`device-resolve.ts`); `relayForButton`
+  carries them onto the `ResolvedRelay`, and a new `relayForPresence()` resolves a loop-input edge to
+  the entry relay it gates.
+- `EntryFlow` (`entry-flow.ts`) keeps a `#guard` map keyed `controllerId:relay`: `#onPresenceEdge`
+  tracks the loop, `#suppressReason` decides presence/cooldown, `#recordSuppressedPress` writes the
+  telemetry. The guard disarms + stamps the cooldown on **print success** (not on open).
+- [[first-run-setup|SetupWizard]] relay editor: entry/both relays expose a **Presence loop
+  (terminal)** field and, when no loop is set, a **Cooldown after ticket (s)** field (localized
+  sq+en — see [[i18n]]).
+
+## Open
+
+- **No automated test yet** (the standing harness gap) — verify on hardware: with a loop, a held
+  button issues one ticket; after the car clears the loop a new car gets a fresh one. Without a loop,
+  a cooldown blocks the repeat and the suppressed press lands in telemetry.
+- **Exit side:** the symmetric concern (re-reading a ticket at exit) is already handled differently —
+  exit validates against an open session, so a second read finds the session closed (no double-exit).
+  No presence gate needed there today.
+- **Loop as a safety/anti-tailgate signal** is a larger future use of the same input (free-exit
+  detection is noted in [[bom]]); this change uses it only to gate ticketing.
@@ -30,6 +30,9 @@ config: {
 - `direction`: `entry` | `exit` | `both` (`both` = one barrier/relay serving in and out).
 - `button`: the **input terminal** the transient **entry button** is wired to. Only entry/both
  relays have one. Absent = no button at that barrier (subscriber/reader-driven only).
+- `presenceInput` / `entryCooldownSec`: the **one-car-one-ticket** guard for the entry button —
+  `presenceInput` is the input terminal of a vehicle-presence loop (physical guard), or
+  `entryCooldownSec` a fallback timer when there's no barrier feedback. See [[entry-double-press]].

 The four real layouts all fall out of this:

@@ -103,6 +106,18 @@ backed-up DB, nothing scattered on disk), in its own table so hot telemetry scan
 bytes and images prune independently. Linked to the signed `vehicle_entry/exit` by `identity`.
 Served read-only via `GET /api/snapshots/:id`. **Retention is unresolved** — see [[open-questions]].

+### Refused entry/exit ALSO snapshots (2026-06-19)
+A snapshot is evidence of **who was at the barrier** — which matters *most* when the barrier is
+**refused** (a turned-away car is a fraud/dispute signal: "lot full" denial, an unpaid exit attempt,
+a no-session ticket, an out-of-window subscription). Originally only the OPEN paths captured; now
+**every refusal/hold anomaly fires the directional camera too**, keyed to the same `identity` the
+anomaly carries so the [[booth-console|activity-log]] evidence strip finds it. Coverage: entry
+refused-full / held-no-ticket (a refused entry has no ticket id → mint a synthetic `REFUSED-…` ref
+to key the anomaly + photo together), exit refused closed/no-session/unpaid/grace-expired (booth
+*and* reader paths), and a refused [[subscription]] (the lane the reader sits at picks the camera).
+Same fire-and-forget contract — a refusal is never delayed by a camera. Failed captures still surface
+as "⚠ camera unreachable" tiles (see [[booth-console]]).
+
 ## Related

 [[entry-exit-readers]] · [[device-events]] · [[parking-session]] · [[anti-passback]] ·
@@ -75,6 +75,7 @@ Counts: 4 sources · 19 entities · 44 concepts · 5 decision records.
 - [[challenge-response-auth]] — asymmetric nonce scheme for the ESP32 (auth + anti-replay).
 - [[entry-exit-readers]] — two populations, two integration paths; both can share a relay.
 - [[entry-exit-points]] — pool-of-spaces model (no lane); per-relay direction, reader→relay binding, camera snapshots.
+- [[entry-double-press]] — one car = one ticket: per-relay presence-loop gate (preferred) or cooldown fallback; suppressed press = telemetry.
 - [[uhppote-vs-esp32]] — comparison: detection vs. prevention.

 ## Concepts — business domain