Centralize seat capacity accounting and the payment provider registry.

Replace manualProviders.ts with a paymentProviders.ts registry
(automatic vs manual settlement) and move all seat counting into
capacity.ts as the single source of truth: only paid/checked-in tickets
and pending_approval payments hold a seat, so abandoned checkouts never
block sales. Admins can now knowingly approve a payment over capacity
(allowOverCapacity), with the booking and admin UIs updated to match.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

backend/src/lib/bookingCleanup.ts

@@ -18,7 +18,7 @@ import { and, eq, lt, inArray, notInArray } from 'drizzle-orm';
 import { db, dbAll, tickets, payments } from '../db/index.js';
 import { getNow, toDbDate } from './utils.js';
 import { getLock } from './stores/lock.js';
-import { MANUAL_PAYMENT_PROVIDERS } from './manualProviders.js';
+import { MANUAL_PAYMENT_PROVIDERS } from './paymentProviders.js';
 
 function getTtlMs(): number {
   const minutes = parseInt(process.env.PENDING_BOOKING_TTL_MINUTES || '30', 10);

backend/src/lib/capacity.ts

@@ -0,0 +1,70 @@
+// Single source of truth for event seat accounting.
+//
+// A seat is held by a booking the moment the money is real or claimed to be:
+//   - ticket 'confirmed' or 'checked_in' (paid), or
+//   - ticket 'pending' whose payment is 'pending_approval' (customer clicked
+//     "I've paid" and is waiting for admin verification).
+//
+// A bare 'pending' payment — an opened checkout that was never paid nor claimed,
+// on any provider — holds NO seat, so abandoned bookings can never block sales.
+// The accepted trade-off is a small oversell window when several people book the
+// last seats and all later pay/claim; admin approval is the backstop and may
+// knowingly approve over capacity (see routes/payments.ts).
+//
+// 'pending_approval' is a payment status (the ticket row stays 'pending'), so
+// every capacity count joins tickets to payments. There is exactly one payment
+// row per ticket (created together in routes/tickets.ts).
+//
+// Every place that counts seats — booking creation, public availability,
+// hold recovery, admin dashboards — must go through these builders so the
+// formula cannot diverge between surfaces.
+
+import { sql, and, eq, inArray } from 'drizzle-orm';
+import { tickets, payments } from '../db/index.js';
+
+// COALESCE keeps the predicate two-valued under the LEFT JOIN (a ticket with no
+// payment row must count as "not holding" — NULL would poison NOT ...).
+export const seatHoldingSql = sql`(${(tickets as any).status} IN ('confirmed', 'checked_in') OR (${(tickets as any).status} = 'pending' AND COALESCE(${(payments as any).status}, '') = 'pending_approval'))`;
+
+/**
+ * Query: number of seats currently held for an event.
+ * `executor` is the db, or a transaction (sync sqlite tx: finish with `.get()`;
+ * async pg tx / plain db: await via dbGet).
+ */
+export function seatHolderCountQuery(executor: any, eventId: string) {
+  return executor
+    .select({ count: sql<number>`count(distinct ${(tickets as any).id})` })
+    .from(tickets)
+    .leftJoin(payments, eq((payments as any).ticketId, (tickets as any).id))
+    .where(and(eq((tickets as any).eventId, eventId), seatHoldingSql));
+}
+
+/**
+ * Query: how many of the given tickets do NOT currently hold a seat (and so
+ * would need fresh capacity if promoted to a seat-holding state).
+ */
+export function unseatedTicketCountQuery(executor: any, ticketIds: string[]) {
+  return executor
+    .select({ count: sql<number>`count(distinct ${(tickets as any).id})` })
+    .from(tickets)
+    .leftJoin(payments, eq((payments as any).ticketId, (tickets as any).id))
+    .where(and(inArray((tickets as any).id, ticketIds), sql`NOT ${seatHoldingSql}`));
+}
+
+/**
+ * Query: per-event breakdown of paid vs claimed seats, grouped by event.
+ * paidCount = confirmed + checked_in; claimedCount = pending_approval-held.
+ * Pass `eventId` to restrict to one event (still returns a grouped row).
+ */
+export function eventSeatBreakdownQuery(executor: any, eventId?: string) {
+  const query = executor
+    .select({
+      eventId: (tickets as any).eventId,
+      paidCount: sql<number>`sum(case when ${(tickets as any).status} IN ('confirmed', 'checked_in') then 1 else 0 end)`,
+      claimedCount: sql<number>`sum(case when ${(tickets as any).status} = 'pending' AND COALESCE(${(payments as any).status}, '') = 'pending_approval' then 1 else 0 end)`,
+    })
+    .from(tickets)
+    .leftJoin(payments, eq((payments as any).ticketId, (tickets as any).id));
+  return (eventId ? query.where(eq((tickets as any).eventId, eventId)) : query)
+    .groupBy((tickets as any).eventId);
+}

backend/src/lib/holdRecovery.ts

@@ -1,19 +1,22 @@
-// Shared capacity-checked recovery for released bookings.
+// Shared capacity-checked recovery for bookings that don't currently hold a seat.
 //
-// When a booking is put on hold (or failed/cancelled), its ticket(s) drop out of the
-// capacity-counting statuses ('pending', 'confirmed', 'checked_in'), releasing the seat.
-// Recovering such a booking (user "I've paid" again, or an admin reactivating / marking
-// it paid / reopening a failed payment) must atomically re-check that the event still has
-// room before re-reserving the seat, exactly like the original booking-creation flow in
-// routes/tickets.ts.
+// Under the seat-holding rule (lib/capacity.ts) a seat is held by paid/checked-in
+// tickets and by 'pending_approval' payments. Promoting a booking INTO one of those
+// states — user clicking "I've paid", an admin approving/reactivating a payment —
+// must atomically re-check that the event still has room, exactly like the original
+// booking-creation flow in routes/tickets.ts. Demoting back to bare 'pending'
+// (e.g. reopening a failed payment) claims no seat and skips the check.
 //
-// Callers choose which ticket statuses are eligible to be re-reserved via
-// `options.fromTicketStatuses` (default ['on_hold']); tickets not in that list — and
-// tickets that already hold a seat — are left untouched and don't consume capacity.
+// Callers choose which ticket statuses are eligible to be flipped via
+// `options.fromTicketStatuses` (default ['on_hold']); tickets not in that list are
+// left untouched. Tickets that already hold a seat cost no new capacity.
+// `options.skipCapacityCheck` lets an admin knowingly approve over capacity —
+// the UI warns first (routes/payments.ts /approve with allowOverCapacity).
 
-import { eq, and, inArray, sql } from 'drizzle-orm';
+import { eq, and, inArray } from 'drizzle-orm';
 import { db, dbGet, tickets, payments, events, isSqlite } from '../db/index.js';
 import { getNow, calculateAvailableSeats, isEventSoldOut } from './utils.js';
+import { seatHolderCountQuery, unseatedTicketCountQuery } from './capacity.js';
 
 export class HoldCapacityError extends Error {
   constructor(public available: number) {
@@ -26,6 +29,8 @@ interface ReserveOptions {
   extraPaymentFields?: Record<string, any>;
   /** Ticket statuses eligible to be flipped to targetTicketStatus. Default: ['on_hold']. */
   fromTicketStatuses?: Array<'on_hold' | 'cancelled' | 'pending'>;
+  /** Admin override: reserve even when it puts the event over capacity. */
+  skipCapacityCheck?: boolean;
 }
 
 /**
@@ -34,7 +39,8 @@ interface ReserveOptions {
  * Only tickets whose current status is in `fromTicketStatuses` are flipped.
  * Capacity is asserted against the number of those tickets that don't already
  * hold a seat, so re-reserving tickets that are already seated is a no-op.
- * Throws HoldCapacityError if the event no longer has room.
+ * Throws HoldCapacityError if the event no longer has room (unless the target
+ * state holds no seat, or skipCapacityCheck is set).
  */
 export async function reserveOnHoldBooking(
   eventId: string,
@@ -46,6 +52,10 @@ export async function reserveOnHoldBooking(
   if (ticketIds.length === 0) return;
 
   const fromTicketStatuses = options.fromTicketStatuses ?? ['on_hold'];
+  // Bare 'pending' payments hold no seat, so moving a booking back to 'pending'
+  // consumes no capacity and needs no check.
+  const targetHoldsSeat = targetPaymentStatus !== 'pending' || targetTicketStatus === 'confirmed';
+  const checkCapacity = targetHoldsSeat && !options.skipCapacityCheck;
 
   const event = await dbGet<any>(
     (db as any).select().from(events).where(eq((events as any).id, eventId))
@@ -66,7 +76,7 @@ export async function reserveOnHoldBooking(
   }
 
   // `needed` is how many of these tickets don't currently hold a seat and so must
-  // be found new capacity; tickets already in a seat-holding status cost nothing.
+  // be found new capacity; tickets already in a seat-holding state cost nothing.
   const assertCapacity = (reserved: number, needed: number) => {
     if (needed <= 0) return;
     if (isEventSoldOut(event.capacity, reserved)) {
@@ -80,23 +90,11 @@ export async function reserveOnHoldBooking(
 
   if (isSqlite()) {
     (db as any).transaction((tx: any) => {
-      const countRow = tx
-        .select({ count: sql<number>`count(*)` })
-        .from(tickets)
-        .where(and(
-          eq((tickets as any).eventId, eventId),
-          sql`${(tickets as any).status} IN ('pending', 'confirmed', 'checked_in')`
-        ))
-        .get();
-      const neededRow = tx
-        .select({ count: sql<number>`count(*)` })
-        .from(tickets)
-        .where(and(
-          inArray((tickets as any).id, ticketIds),
-          sql`${(tickets as any).status} NOT IN ('pending', 'confirmed', 'checked_in')`
-        ))
-        .get();
-      assertCapacity(Number(countRow?.count || 0), Number(neededRow?.count || 0));
+      if (checkCapacity) {
+        const countRow = seatHolderCountQuery(tx, eventId).get();
+        const neededRow = unseatedTicketCountQuery(tx, ticketIds).get();
+        assertCapacity(Number(countRow?.count || 0), Number(neededRow?.count || 0));
+      }
 
       tx.update(tickets)
         .set({ status: targetTicketStatus })
@@ -113,25 +111,11 @@ export async function reserveOnHoldBooking(
     });
   } else {
     await (db as any).transaction(async (tx: any) => {
-      const countRow = await dbGet<any>(
-        tx
-          .select({ count: sql<number>`count(*)` })
-          .from(tickets)
-          .where(and(
-            eq((tickets as any).eventId, eventId),
-            sql`${(tickets as any).status} IN ('pending', 'confirmed', 'checked_in')`
-          ))
-      );
-      const neededRow = await dbGet<any>(
-        tx
-          .select({ count: sql<number>`count(*)` })
-          .from(tickets)
-          .where(and(
-            inArray((tickets as any).id, ticketIds),
-            sql`${(tickets as any).status} NOT IN ('pending', 'confirmed', 'checked_in')`
-          ))
-      );
-      assertCapacity(Number(countRow?.count || 0), Number(neededRow?.count || 0));
+      if (checkCapacity) {
+        const countRow = await dbGet<any>(seatHolderCountQuery(tx, eventId));
+        const neededRow = await dbGet<any>(unseatedTicketCountQuery(tx, ticketIds));
+        assertCapacity(Number(countRow?.count || 0), Number(neededRow?.count || 0));
+      }
 
       await tx.update(tickets)
         .set({ status: targetTicketStatus })

backend/src/lib/holdSweep.ts

@@ -1,23 +1,24 @@
-// Auto-hold stale manual-payment bookings.
+// Auto-hold stale unsettled manual-payment bookings.
 //
-// This job releases the seat held by an abandoned manual-payment booking (bank
-// transfer / TPago / cash) after HOLD_THRESHOLD_HOURS. It covers two states, both of
-// which keep a seat reserved while awaiting a human:
-//   - 'pending_approval': the user clicked "I've paid" and is waiting for an admin.
-//   - 'pending' on a manual provider (see MANUAL_PAYMENT_PROVIDERS): the booking was
-//     never settled (these are exempt from the 30-min auto-fail in bookingCleanup.ts,
-//     so this is their only seat-release path).
-// In either case the payment (and its ticket) is silently moved to 'on_hold', which
-// drops it out of the capacity-counting statuses ('pending', 'confirmed', 'checked_in')
-// and so releases the seat back to the event. The user receives no notification — they
-// can recover via "I've paid" again, and an admin can reactivate or mark it paid
-// directly, both re-checking capacity.
+// This job moves abandoned manual-payment bookings (bank transfer / TPago / cash)
+// to 'on_hold' after HOLD_THRESHOLD_HOURS — bookings still in bare 'pending', i.e.
+// the customer never clicked "I've paid" and no admin settled them. These are exempt
+// from the 30-min auto-fail in bookingCleanup.ts, and under the capacity rule in
+// lib/capacity.ts they hold no seat, so this sweep is pure list hygiene: it keeps
+// dead checkouts out of the admin's pending queues.
+//
+// 'pending_approval' (customer claims they paid) is deliberately NOT swept: a
+// claimed payment keeps its seat until an admin approves or rejects it — the admin
+// UI surfaces aging claims instead of silently releasing them.
+//
+// The user receives no notification — they can recover via "I've paid", and an
+// admin can approve/reactivate directly; every recovery path re-checks capacity.
 
-import { and, or, eq, lt, inArray } from 'drizzle-orm';
+import { and, eq, lt, inArray } from 'drizzle-orm';
 import { db, dbAll, tickets, payments } from '../db/index.js';
 import { getNow, toDbDate } from './utils.js';
 import { getLock } from './stores/lock.js';
-import { MANUAL_PAYMENT_PROVIDERS } from './manualProviders.js';
+import { MANUAL_PAYMENT_PROVIDERS } from './paymentProviders.js';
 
 function getThresholdMs(): number {
   const hours = parseInt(process.env.HOLD_THRESHOLD_HOURS || '72', 10);
@@ -25,9 +26,9 @@ function getThresholdMs(): number {
 }
 
 /**
- * Move stale awaiting-verification payments (and their tickets) to 'on_hold'.
- * Covers 'pending_approval' payments and 'pending' payments on manual providers.
- * Returns the number of payments put on hold.
+ * Move stale unsettled manual payments (and their tickets) to 'on_hold'.
+ * Covers only bare 'pending' payments on manual providers; 'pending_approval'
+ * is never swept. Returns the number of payments put on hold.
  */
 export async function sweepStaleApprovals(): Promise<number> {
   const cutoff = toDbDate(new Date(Date.now() - getThresholdMs()));
@@ -40,13 +41,8 @@ export async function sweepStaleApprovals(): Promise<number> {
       })
       .from(payments)
       .where(and(
-        or(
-          eq((payments as any).status, 'pending_approval'),
-          and(
-            eq((payments as any).status, 'pending'),
-            inArray((payments as any).provider, [...MANUAL_PAYMENT_PROVIDERS])
-          )
-        ),
+        eq((payments as any).status, 'pending'),
+        inArray((payments as any).provider, [...MANUAL_PAYMENT_PROVIDERS]),
         lt((payments as any).createdAt, cutoff)
       ))
   );
@@ -72,7 +68,7 @@ export async function sweepStaleApprovals(): Promise<number> {
       ));
   }
 
-  console.log(`[HoldSweep] Put ${stale.length} stale awaiting-verification payment(s) on hold.`);
+  console.log(`[HoldSweep] Put ${stale.length} stale unsettled manual payment(s) on hold.`);
   return stale.length;
 }
 

backend/src/lib/manualProviders.ts

@@ -1,7 +0,0 @@
-// Payment providers that require a human to verify the money arrived.
-//
-// These methods (bank transfer / TPago / cash) are never auto-confirmed and —
-// crucially — are never auto-failed by the stale-booking cleanup: an admin settles
-// them by hand. Note this is broader than the set of methods that expose an online
-// "I've paid" step (bank transfer / TPago only); cash is settled at the door.
-export const MANUAL_PAYMENT_PROVIDERS = ['bank_transfer', 'tpago', 'cash'] as const;

backend/src/lib/paymentProviders.ts

@@ -0,0 +1,37 @@
+// Payment provider registry.
+//
+// Every provider is either:
+//   - 'automatic': the gateway itself confirms the payment (webhook/invoice
+//     settlement) and the booking is auto-approved on success. No admin involved.
+//     Currently Lightning; future online gateways (e.g. Stripe) go here.
+//   - 'manual': a human must verify the money arrived (TPago, bank transfer,
+//     card handled offline, cash at the door). These are never auto-confirmed
+//     and never auto-failed; an admin settles them by hand. Bank transfer and
+//     TPago additionally expose an online "I've paid" step that moves the
+//     payment to 'pending_approval'.
+//
+// Capacity note (see lib/capacity.ts): only paid/checked-in tickets and
+// 'pending_approval' payments hold a seat. A bare 'pending' payment — of either
+// kind — holds no seat, so an abandoned checkout can never block sales.
+
+export type PaymentProviderKind = 'automatic' | 'manual';
+
+export const PAYMENT_PROVIDERS: Record<string, { kind: PaymentProviderKind }> = {
+  lightning: { kind: 'automatic' },
+  tpago: { kind: 'manual' },
+  bank_transfer: { kind: 'manual' },
+  card: { kind: 'manual' },
+  cash: { kind: 'manual' },
+};
+
+export const MANUAL_PAYMENT_PROVIDERS = Object.keys(PAYMENT_PROVIDERS).filter(
+  (p) => PAYMENT_PROVIDERS[p].kind === 'manual'
+);
+
+export function isManualProvider(provider: string): boolean {
+  return PAYMENT_PROVIDERS[provider]?.kind === 'manual';
+}
+
+export function isAutomaticProvider(provider: string): boolean {
+  return PAYMENT_PROVIDERS[provider]?.kind === 'automatic';
+}