Decision Log

Ported the fix, following the identical pattern PR #1256 proved out (fixed isNewAccount tracking via a new findOrCreateGuestAccountWithStatus, RACE_WINDOW_MS + anon-placeholder-downgrade guards, deleteOrphanedGuestAccount called on the race loser) — the different facility-linking model turned out NOT to change whether the orphan-cleanup fix is needed (a customer created via apps/pos's till-style order-screen "New Customer" flow, apps/pos/src/components/terminal/customer-selector.tsx, that loses the phone race is just as untied/unreferenced in apps/pos's model as in apps/terminal's — zero bookings/orders/tickets/memberships, so isTiedToAnyFacility correctly flags it as an orphan regardless of which facility-linking mechanism a given app uses), only how to verify it. Explicitly did NOT port linkCustomerToFacilityDirectory/crm_customer_directory tie-in to apps/pos — that's a separate, deliberate architectural difference (apps/pos customers become visible once they have real activity, not via an explicit directory row) outside this bug's scope; porting it would do nothing anyway since search_facility_customers never reads crm_customer_directory. Duplicated rather than shared via packages/common: apps/pos never imports @setpoint/database/admin (uses raw `createClient(url, serviceRoleKey)` throughout its own action files instead), and find-or-create-guest-by-phone.ts's own existing header comment already documents this repo's established convention for these specific action files as "POS-side mirror ... kept in one place to avoid drift between the two near-identical action files this repo's per-app server-action convention already produces" — so a new apps/pos-local delete-orphaned-guest-account.ts + customer-facility-access.ts (isTiedToAnyFacility only; apps/pos has no edit-guard caller for the single-facility isTiedToFacility terminal also exports) matches the pattern already in place rather than introducing a new shared-module precedent unilaterally. Verified live, not assumed: reproduced the orphan-leaving failure against local Supabase before porting the fix (two concurrent same-phone "New Customer" submissions through the real UI left 2 customer rows for 1 phone number on the unfixed code), then confirmed exactly 1 row survives + 3 new Playwright e2e tests pass (phone-only race, email+phone race, permanent-conflict non-race) across two separate runs post-fix. Also re-verified apps/terminal's own #1256 fix still passes live (its existing customer-create-phone-race.spec.ts, 3/3, run fresh against current main) rather than trusting the merged PR's report.

Alternatives considered

• Skip the orphan-cleanup port since apps/pos has no crm_customer_directory tie-in — rejected: the "different facility-linking model" only changes HOW a customer becomes visible/searchable, not whether a phone-race loser is genuinely orphaned (zero bookings/orders/tickets/memberships either way); isTiedToAnyFacility's tie-check is already generic across all seven tie tables, none of which are terminal-specific.
• Share delete-orphaned-guest-account.ts / customer-facility-access.ts via packages/common instead of duplicating into apps/pos — rejected for this fix: apps/pos has zero existing usage of @setpoint/database/admin or any shared "use server" action module, and the sibling find-or-create-guest*.ts files this fix extends already establish (in their own comments) that this repo's convention for these specific action files is one copy per app; introducing a new shared-module precedent is a larger, separate refactor better scoped on its own, not smuggled into an urgent fix.
• Port linkCustomerToFacilityDirectory to apps/pos too, for parity with apps/terminal — rejected: apps/pos's search_facility_customers RPC never reads crm_customer_directory, so writing to it from apps/pos would be a dead write that fixes nothing and adds a false signal that the two apps' facility-linking models are now equivalent when they are not.

Ship the interim mitigation now: a new deleteOrphanedGuestAccount server action (apps/terminal/src/app/actions/delete-orphaned-guest-account.ts), called only when the race-recovery branch confirms a winner exists for the phone. Before deleting, it independently re-verifies the target server-side rather than trusting the call site's comment: the email matches what THIS call just set on the row (a lightweight ownership proof — not a cryptographic token, but a fact an unrelated id/email pair won't coincidentally share), no phone landed on it, it has zero ties to any facility (isTiedToAnyFacility, sharing customer-facility-access.ts's six-plus-player_packages-table check with the three existing update actions' facility-scoped edit guard, rather than a second, independently-fallible copy), and it was created within the last 5 minutes (with a clock-skew tolerance, since Vercel and Supabase are different machines). Any error anywhere in that chain refuses the delete (fails CLOSED) rather than risking an irreversible cascade-delete on unverified data. This is explicitly an INTERIM MITIGATION, not the architectural fix — it narrows the exploit/accident surface a lot (from "any real customer, any time" to "an untied, phoneless, <5-minutes-old record whose exact email you also know") but cannot fully close it without either a request-scoped ownership token or the atomic claim-or-create redesign described above. ARCHITECTURAL FOLLOW-UP (not yet filed as a ticket — flagging here so it isn't silently forgotten): redesign guest-account creation so the phone claim happens atomically via the DB's own `customers_phone_key` unique constraint (e.g. create the auth user lazily only after a server-side upsert/RPC confirms this phone isn't already claimed, or hold a short-lived claim row keyed by phone before ever calling auth.admin.createUser), eliminating the speculative-create-then-maybe-delete shape entirely rather than cleaning up after it.

Alternatives considered

• Do nothing until the atomic redesign ships — rejected: this is a live, confirmed, recurring production bug (staff-facing creation/edit failures, real customer records permanently orphaned); CLAUDE.md's own "live security incidents / prod outages — patch first, file the architectural follow-up immediately" exception applies directly.
• Delete the loser unconditionally, trusting the call site — rejected (code review, 2026-10-13): deleteOrphanedGuestAccount is an exported Next.js Server Action, reachable independent of its one intended call site; an unguarded delete would be a strictly MORE destructive, UNGUARDED sibling of the facility-scoped isTiedToFacility() guard every other customer-mutating action in this directory already enforces.
• Build the full atomic claim-or-create now, in the same PR — rejected for THIS fix: it's the correct long-term shape, but redesigning how guest accounts are created (touching find-or-create-guest.ts, find-or-create-guest-by-phone.ts, and their apps/pos sibling) is a larger, riskier change than an urgent production hotfix should carry same-day; shipping the narrower, well-tested mitigation now and scoping the redesign separately matches the repo's own incident-response exception.
• Scope the tie-check to just this one facility instead of globally — rejected: the account being deleted was never tied to ANY facility yet (it's seconds old), so a facility-scoped check would be meaningless here; a global check is the correct safety bar for a delete, same reasoning as why isTiedToFacility itself must stay facility-scoped for the EDIT guard it protects (the two must never be the same check for the two different decisions).

Template: the four existing right Sheet panels (academy-member-detail-panel, academy-collections-detail-panel, customer-detail-panel, academy-payments-reminder-panel) — full-height Sheet from the right, `w-full` on phones, `sm:max-w-xl` on desktop, no <Table> inside — and booking details is converted to that pattern first, so the surface Nestor named becomes the thing it describes. Rule, applied to all 56 component files: a RIGHT PANEL when the operator works inside it — any detail/record view, and any form that already needed its own scrollbar (max-h + overflow-y-auto) or sticky footer, or that has sections/steps/tabs (create/edit booking, schedule lesson, class, coach, package, academy settings, assign package, pricing rule, discount rule, court images, the two report edit forms, program form, match form, match detail). A CENTRED DIALOG when the operator answers it — confirm and destructive prompts (archive/delete/cancel/remove), pickers (add to shift, assign coach, add from segment, cancellation reason), result/alert displays (API key created, payment link, chase results, send result), and one-block quick-entry forms that fit on screen without scrolling (customer, team member, court, membership plan, assign subscription, add credits, enroll user, create group, new API key, record payment, adjust/extend sessions, record a note, add tier). Also a DIALOG regardless of size when the content is intrinsically wider than the sm:max-w-xl panel and would need a sideways scroll or a table inside a panel, both banned: coach-schedule-editor (max-w-3xl weekly grid), message-templates-manager (max-w-3xl editor + preview), lesson-roster-panel (max-w-4xl/5xl roster table), the two email-preview dialogs, court-schedule-editor's week rows. Outcome: 17 panels / 39 dialogs. Ten panels converted and browser-verified tonight; the other seven stay Dialogs and are listed in v0.53.20 for a follow-up — three of them (program/match form, match detail) are PARKED features and are not modified by rule anyway. Primitive untouched: sheet.tsx stays as it is, converted panels take `flex flex-col gap-4` on SheetContent to reproduce DialogContent's vertical rhythm. Files keep their *-dialog.tsx names and *Dialog exports.

Alternatives considered

• Convert all 57 in one pass — rejected: the ask is consistency, not a blanket swap; Nestor explicitly carved out simple dialogs, and a confirmation prompt sliding in from the right is worse UX than a centred one. 57 unverified conversions on a same-night deploy was also exactly what the coordinator ruled out.
• Give sheet.tsx a sticky SheetHeader that holds the close button (mirroring DialogHeader, which this codebase made sticky on purpose) — deferred, not rejected: it is the industry shape (Polaris sheets, Linear side panels pin the header) and the long forms lose their pinned X on scroll by moving to Sheet, but it changes the four existing panels that other workstreams are editing tonight and that this PR does not verify. Escape and the sticky Cancel/Submit footer still close every long form. Proposed as the next panel-chrome change, applied to all panels at once.
• Rename the converted files to *-panel.tsx and the exports to *Panel — rejected for this PR: it touches every mount point (calendar-grid, week-calendar-grid, bookings-list, five list components) and multiplies merge conflicts with the academy revenue work in flight; the file header comment states what the container is. Rename when the remaining seven are converted.
• A new DetailPanel wrapper component over Sheet — rejected (anti-abstraction): the four house panels use Sheet directly with a one-line className; a wrapper would be a second place for the chrome to drift.
• Treat booking details as the template as-is (a centred Dialog) and convert nothing — rejected: it contradicts the instruction's intent ("a sliding one from right"); the file's name says dialog but his words say panel, and the Sheet panels he already uses daily are what he is comparing against.

(1) pos_catalog_items.price_mode text NOT NULL DEFAULT 'fixed' CHECK IN ('fixed','open') — not a boolean — to match this table's existing mode-column convention (tracking_type, availability_status are both text+CHECK) so a third mode never needs a second migration to widen a boolean into an enum. pos_item_variations.price_cents is untouched (stays NOT NULL); for an open item it's simply read as an optional suggested starting value, never enforced. (2) Open price is staff-allowed, NOT manager-gated — Pablo's phrasing ("ask for a price") describes a normal sale mechanic, not a discount; gating it behind a PIN would make an everyday sale (e.g. a market-rate racquet restring) slower than a scripted item for no safety reason POS-08 doesn't already cover. (3) POS-08 took the activity-log-only approach: setLinePriceOverride (terminal-store.ts) mutates the cart line's unitPriceCents directly (same mechanism a discount does NOT use — a discount is a separate deduction; an override replaces the price), and use-order-mutations.ts logs one pos_activity_logs row per overridden line (action: price_override_applied, entity_type: 'order', entity_id: the real order id) right after checkout commits — never touching pos_order_items or the checkout RPC. order-detail-modal matches a line back to its log entry by (item_variation_id, unit_price_cents) since there's no FK, which is an accepted, documented ambiguity only two co-priced identical-variation lines on the same order could ever hit. (4) Scoped to apps/terminal only for both the at-sale open-price prompt and the price-override control: apps/pos's own /terminal checkout route is a live but nav-unlinked dead surface (flagged separately, DEC-501) with no manual-discount/PIN-approval gate to reuse at all — POS-08 explicitly says reuse the EXISTING gate, and apps/pos has none. The price_mode TOGGLE itself ships in BOTH apps' item-modal.tsx (catalog management happens from either app), but only apps/terminal's menu-grid actually prompts for a price at sale.

Alternatives considered

• is_open_price boolean on pos_catalog_items — rejected: inconsistent with tracking_type/availability_status's existing text+CHECK pattern on the exact same table, and a boolean can't cleanly grow a third price mode later (e.g. a tiered/quantity-break mode) without another migration.
• Gate open-price entry behind the same manager PIN as POS-08's override — rejected: conflates "staff sells something without a fixed catalog price" (normal) with "staff changes an already-priced item's price" (needs oversight); the first is Pablo's explicit ask for staff-allowed behavior.
• Add pos_order_items.original_unit_price_cents / is_overridden columns, written by the checkout RPC — rejected per the ticket's own guidance: create_pos_order_atomic is the single most heavily-coordinated object in this codebase this week (6+ concurrent SEC-01/remediation branches touch it); a schema+RPC change for an audit-trail-only feature isn't worth that collision risk when an activity-log row accomplishes the same outcome.
• Build apps/pos a parallel override UI with its own new PIN gate — rejected: no existing gate to reuse there, and building a second, independent PIN-approval mechanism (risking exactly the ManagerPinSheet-vs-DiscountApprovalGate duplication PR #1216 already had to fix once) for a route that's flagged dead (DEC-501) isn't justified without a product decision on whether that route should even keep existing.

Same bug, confirmed independently by reading the checkout RPCs' own INSERT statements (not trusting DEC-497's finding secondhand): checkout-dialog.tsx's pendingDiscount carries {type, input} right up to use-order-mutations.ts, which only ever sends discountCents and hardcodes type: 'fixed' on the RPC payload — the percent is dropped on the client side, before it ever reaches the database. Fix is at INSERT time inside create_pos_order_atomic (the immutability triggers confirm UPDATE is a dead end), via one new nullable pos_order_discounts.percent column, written only when the client sends type='percentage' with a sane [0,100] value — covering till-checkout (apps/terminal AND apps/pos, which keep independently-drifted copies of use-order-mutations.ts/checkout-dialog.tsx) and the payment-link cron path (check-payment-links/route.ts), all three of which had the identical hardcode. Bundled into the SAME migration: get_bill_payload_for_order (already the one function feeding both the printed receipt via enqueue_bill_print_job_for_order AND the emailed bill via send-bill-email) gains `discounts` (per-row name/type/percent/amount_cents) and `payments` (per-tender method/amount/tip/card info) plus a `change_given_cents` scalar derived from pos_drawer_transactions — genuinely one coherent change since both tickets' data needs route through the same RPC, not forced together.

Alternatives considered

• Derive percent purely client-side from amount_cents/subtotal_cents (DEC-497's own approach for the Discounts report) instead of adding a column — rejected for THIS screen: a report comparing many discounts at once benefits from one uniform derived-and-labeled convention, but an order-detail screen/receipt showing one specific bill's own discount should show the EXACT percent the cashier actually typed when it's available, not an approximation of it. Landed on a hybrid instead: persist the real value going forward (this migration), fall back to the exact same ≈-derived convention only for rows where it's genuinely unknown (pre-migration, or a type the column was never meant to cover) — see the rationale below.
• Backfill pos_order_discounts.percent for historical rows from amount_cents/subtotal_cents — rejected: that would store a DERIVED value as if it were the cashier's real input, indistinguishable from an exact capture once it's in the column. Leaving historical rows NULL and deriving-with-≈ only at render time (client/receipt) keeps 'exact' and 'approximate' honestly distinguishable forever, matching DEC-497's own rationale almost verbatim.
• Compute change-due from pos_payments.amount_cents vs. a client-sent 'cash tendered' field — rejected: pos_payments.amount_cents is always the amount OWED (not what was physically handed over), and no table carries 'cash tendered' directly against the order. pos_drawer_transactions DOES carry order_id on the 'pay_out' row create_pos_order_atomic already writes for change given back — reusing that (schema-reuse-before-new-columns) avoids a new column entirely for this part.

Detect the Next.js stale-action error (Failed to find Server Action / Server Action '…' was not found on the server) in one shared helper (lib/stale-server-action.ts). A global QueryClient MutationCache/QueryCache onError shows ONE persistent sonner toast ('Setpoint was updated while this page was open. Finish the current sale, then reload to continue.') with a Reload button; useCreateFacilityCustomer skips its own toast for this error so staff never see 'Failed to create customer'. The handler covers every Server Action called through React Query (all terminal mutations/queries); the few actions called directly from event handlers are out of its reach. FOLLOW-UP (not part of this change): enable Vercel Skew Protection on the terminal project (project setting) as the platform-level fix.

Alternatives considered

• Auto-reload on detection — rejected: a till can hold an unsaved cart or a half-entered payment, and a surprise reload loses it. Staff reload when ready.
• Per-mutation handling only — rejected: every Server Action call (customers, guest accounts, facility directory) has the same failure mode; one global handler covers every React Query call.
• Do nothing app-side and rely on Skew Protection alone — rejected: Skew Protection only keeps old deployments alive for a window; a till open longer than that still hits this error.

Whole-order EXISTS match: a payment matches if its order has ANY line item in ANY selected category — `exists (select 1 from pos_order_items oi where oi.order_id = o.id and oi.category_id = any(p_category_ids))`. The filtered row shows the full order (every line, the real total), never a line-item-truncated view. No recursive parent/child expansion — p_category_ids is a plain, flat array; selecting a parent category does NOT implicitly pull in its children's items. Multi-select is how a 'group' of categories gets filtered at once.

Alternatives considered

• Filter down to just the matching line item(s) within an order, not the whole order/payment row. Rejected: this is a payment/receipt-level list — a payment's displayed amount must always equal the sum of ALL its lines, and showing a subset of lines next to the full total would actively mislead an operator reconciling a bill. It would also require maintaining two different representations of the same order_items relation (one for display, one for the filter match), doubling the surface area for drift.
• Recursively include a selected parent category's children (standard 'group' semantics in some POS products). Rejected: no other category picker in this product (the discount category-assignment flow, the items list's own Group/Category editor) expands a parent into its children anywhere today — introducing it only for this one filter would be a new, undocumented, inconsistent rule rather than following an established pattern. The Bali punch-list ask ('filter by category/group') is fully satisfied by multi-select: picking several categories in one go.
• Route the browse-mode (non-search) list and the CSV export through search_pos_transactions' own RPC-returned, capped (≤1000) id set, same as the search box, instead of building a genuine client-side order-id/payment-id allowlist. Rejected for the two direct-query paths (useTransactionsInfinite's 'Load more' pagination, both CSV export fetchers): a capped RPC result would silently truncate a facility's full category-filtered export/scroll history past 1000 rows — unacceptable for a CSV export whose entire job is completeness. Built fetchOrderIdsByCategory/fetchPaymentIdsByOrderIds instead, chunked via the existing SEARCH_ID_CHUNK-style `.or()` pattern, genuinely uncapped via fetchAllPages.

One concrete, fixed finding and one flagged-not-fixed finding; everything else investigated and ruled out. FIXED: create_pos_order_atomic's two still-live SEC-01 RAISE EXCEPTION messages ("this facility requires a PIN-verified identity to close a bill", "bar staff cannot close a bill" — confirmed against the LATEST migration, 20261006103519, not a stale earlier copy; the third, "manager PIN approval" message was removed by that same migration per DEC-490 and correctly left unmapped) were unmatched in BOTH apps' friendly-error.ts, falling through to raw RPC text — the exact "[object Object]"-class incident that file's own header exists to prevent. Added matchers + 2 unit tests in apps/terminal; mirrored in apps/pos. FLAGGED, NOT FIXED (needs Alba's call, not a bug fix): apps/pos retains a fully live, functional /terminal checkout route (own CheckoutDialog + useCreateOrder, drawer-session-gate ported to it as recently as remediation Phase 3) that is unlinked from any nav/UI anywhere in the app — reachable only by direct URL — and has never been wired to pass p_acting_user_id to create_pos_order_atomic. DEC-458 already decided the facility-wide gate must bind EVERY caller once a facility adopts PINs, apps/pos included — but no PIN-entry UI was ever built for apps/pos to satisfy that. Default pin_lock_enabled is false for every facility (DEC-480), so there is no CURRENT production impact, but the first facility to flip that toggle will find every checkout through that orphaned route hard-failing with no way to resolve it in place. Fails CLOSED (no data corruption / security bypass — the server correctly rejects the write), so this is an availability/business-continuity landmine, not an exploitable hole. RULED OUT, with reasoning: (a) void/refund attribution has the identical shared-login-vs-PIN gap (void_pos_order has never been updated to accept p_acting_user_id since 2026-09-18, predating SEC-01) — explicitly out of scope per #1227's own scope notes ("a separate, larger ticket another session is handling") and this sweep's own collision-awareness instructions; left untouched to avoid racing that session. (b) The discount-approval-gate PIN fast-path is a pure client-side unlock with no server-side cap/consumed-verification-row, meaning any direct RPC caller could in principle apply an unapproved discount — but this mirrors the PRE-EXISTING email-code approval flow's exact trust model (same migration's own header comment), is not a new regression from the last 36 hours, and closing it would mean inventing a new "server-enforced discount cap" feature never scoped by this ticket. (c) terminal-lock-provider.tsx's client-side lock state has a well-documented history of fail-open bugs (DEC-459/480/485 and others), but every one is now covered by defense-in-depth: even if the client fails open, create_pos_order_atomic's DB-level gate still blocks the actual bill close without a real PIN. (d) RLS widenings reviewed in the last 10 days (pos_activity_logs to cashier, crm_customer_groups_staff_read, pos_resolve_facility_display_names) are each explicitly tenant-scoped (caller's own facility role re-checked inside the function/policy) and return only display-safe fields — no cross-tenant or over-broad-role leak found. (e) create_pos_order_atomic's tenant checks (location, item_variation_id, category_id, modifier_id, tax_id, service_charge_id, gift_card_id, sold_by) are all independently facility-scoped — no IDOR found on the one SECURITY DEFINER function most of this week's writes funnel through.

Alternatives considered

• Also build apps/pos a PIN-entry flow so it satisfies DEC-458's facility-wide requirement itself. Rejected for this sweep: that's a real feature (new UI, new trust decisions about whether apps/pos's own session should even be allowed to mint a PIN-verified identity) requiring product input on whether that route should exist at all — not a bug fix a security sweep should ship autonomously.
• Delete/redirect apps/pos's orphaned /terminal route outright, since it's unlinked and apps/terminal is the shipped replacement. Rejected for the same reason: removing a live, functional checkout surface is a product call (is anyone still bookmarking/using it?), not something to do unilaterally mid-sweep.
• Fix void/refund attribution now, since it's the same bug class this sweep was asked to hunt for. Rejected: the task's own collision-awareness section names this exact ticket as already claimed by another concurrent session; duplicating it would race, not help.

(1) Group selected items by their current catalogue_id client-side and call useBulkMoveToCatalogue once per source group (each call removes only its own items from its own source catalogue's pos_item_catalogues junction row before adding all selected items to the target) — in BOTH apps now (see (3)). (2) The two apps diverge on purpose: apps/pos nulls category_id immediately after a successful inline group switch (mirroring the modal) and reopens the category cell; apps/terminal can't null it (required), so it instead reopens the category cell scoped to the new group WITHOUT clearing, forcing an explicit re-pick while the stale category value sits untouched in the DB until then — mitigated with a toast if the operator dismisses the re-pick without choosing. Bulk group moves (toolbar + the pre-existing per-row "Move to catalogue" kebab action in both apps) deliberately do NOT clear/rescope category on either app, matching the kebab action's pre-existing behavior — only the new inline single-item group edit does. (3) Yes — fixed apps/terminal's useMoveItemToCatalogue/useBulkMoveToCatalogue to sync pos_item_catalogues (delete the old catalogue_id row, upsert the new one), matching apps/pos's existing behavior, and updated every call site including the pre-existing kebab action (not just this PR's new ones) so the fix closes the bug everywhere it's reachable, not just in the new code paths.

Alternatives considered

• Single combined bulk-move call ignoring source grouping (always pass a single fromCatalogueId, e.g. the first selected item's) — rejected: would silently fail to remove the OTHER source groups' junction rows for the rest of the batch, leaving items cross-listed in both their old and new group.
• Make apps/terminal's useBulkMoveToCatalogue/useMoveItemToCatalogue accept nullable category to match apps/pos — rejected: that mutation layer's null-category guard (assertCategoryIdProvided) is itself a deliberate POS-01/02/03 hardening against a real historical data-integrity gap; reintroducing a null path to make this one feature's UX symmetrical would undo that protection for every future caller.
• Also clear/rescope category on bulk group moves, for full consistency with the new inline flow — rejected as out of scope: the existing per-row kebab "Move to catalogue" action (shipped, unchanged by this PR) has never cleared category either, and retrofitting that behavior onto it wasn't part of Pablo's request.
• Leave apps/terminal's junction-table gap unfixed and file it as a separate follow-up ticket, since it predates this PR — rejected on self-debate: the gap is only LATENT (zero live UI called either mutation before this PR) and this PR is exactly what makes it reachable, so shipping the feature without the fix means knowingly shipping a new, reachable billing-correctness bug in the same PR that created the only path to it. "It's pre-existing" doesn't hold when the PR itself is what makes it exploitable.
• Fix only the NEW call sites (inline editor + bulk toolbar) and leave the pre-existing per-row kebab action's call site unpatched, since fixing it wasn't technically in scope — rejected on a second self-debate round: the mutation signature changed either way (fromCatalogueId added), so the kebab's call site needed touching regardless to keep compiling correctly scoped; leaving it passing no fromCatalogueId would have the junction-sync code run with fromCatalogueId=null, cross-listing the item in both its old and new catalogue instead of moving it — a worse, newly-introduced bug, not a neutral no-op.

(1) FIXED: loadCartFromTicket's id assignment changed from unconditionally minting a fresh cli-restored-<counter>-<timestamp> id for every line to reusing item.id when the restored row already has one, falling back to a freshly generated id only for a genuinely id-less legacy/malformed row. The id cart_json already carries is true for every line ever written through buildTicketCartJson — the overwhelming common case — so this is purely additive: nothing else in loadCartFromTicket changed. Re-ran line-edit-attribution.spec.ts after the fix: clean pass, line_ref now matches across the add event and the later remove event for the same physical cart line, across a real save-reset-reopen-save cycle. (2) REJECTED the 'parallelize the pre-read and the update via Promise.all' suggestion: the entire point of reading cart_json BEFORE the update is to capture the true prior state for the diff; racing the two can return the pre-read reflecting post-update data depending on ordering, silently corrupting the diff baseline for a latency win that doesn't matter at this write volume (one save per cashier action, not a hot loop). (3) ACCEPTED as a known, pre-existing limitation (not introduced by this feature): the read-then-write pair has no optimistic-concurrency guard, so two genuinely simultaneous saves of the SAME ticket (two devices/staff editing one open ticket at the same instant) can each diff against a stale 'before' snapshot, producing an attribution-log entry that doesn't perfectly match the final persisted cart_json. facility_tickets.cart_json itself has always been last-write-wins with no version column — every other mutation in this file (split, move, close) already inherits that same race; this diff's accuracy is a cosmetic casualty of the SAME pre-existing gap, not a new one, and a real fix (transactional server-side diff via an RPC, matching create_ticket/create_pos_order_atomic's pattern) is a materially larger change than what 'no database migration needed' scoped this ticket for.

Alternatives considered

• Leave loadCartFromTicket's id regeneration alone and instead change diffCartLines to match lines by content (itemId+variationId+unitPriceCents+note+modifiers fingerprint) instead of id — rejected: this would have WORKED AROUND the real bug instead of fixing it, left the stale, pointless id-churn-on-every-reopen behavior in place for whatever else might someday rely on CartLineItem.id being stable (nothing currently does, but that's exactly the kind of latent trap this class of bug is), and a content fingerprint has its own real failure mode this id-based diff doesn't: two genuinely distinct lines that happen to share item/variation/price/note/modifiers (e.g. two identical ฿100 custom-amount lines) would be indistinguishable to the diff.
• Build the real transactional fix (server-side RPC doing read+diff+write atomically) now instead of accepting the concurrent-save limitation — rejected for this ticket specifically: it's a materially larger, architecturally different change (a new Postgres function, not a client-side plumbing change) than this item's own scope ("no database migration needed"), and the race it closes is narrow (two staff/devices editing the identical open ticket in the same instant) against a codebase where that race has always existed for cart_json itself. Flagged here, not silently dropped, so a future session scoping a stronger version of this can find the reasoning.

(1) Extended LogActivityInput (apps/terminal/src/app/actions/log-activity.ts) with optional actingUserId/approvedByUserId, written straight through to pos_activity_logs.acting_user_id/approved_by_user_id when supplied, both defaulting to null — every existing caller that omits them is unaffected, and the columns start getting used without a migration since they already exist. (2) useSaveTicketCart (apps/terminal/src/mutations/use-ticket-mutations.ts) now reads the ticket's cart_json BEFORE the update (mirroring this file's own existing fetch-then-write pattern in useCloseTicket/useBatchMoveItemsToTickets), runs both the before and after cart through readTicketCart (packages/common/src/ticket-cart-json.ts) to strip the discount_meta/wrapper-shape noise, and diffs the two CartLineItem[] by `id` — the only stable per-line identity cart_json actually has. The plan's own wording asked for a diff "by line_ref"; cart_json has no such field (that name is already taken by a DIFFERENT concept in packages/common/src/discounts.ts, a discount-application ref keyed to a persisted pos_order_items.id that doesn't exist yet at cart-save time) — CartLineItem.id is reused as the identity and surfaced as `line_ref` only in the emitted activity-log payload, matching the ticket's vocabulary without pretending the data model has a field it doesn't. (3) Three new granular events — ticket_line_added / ticket_line_removed / ticket_line_qty_changed — fire alongside the pre-existing generic ticket_cart_updated (kept, not retired: it's still the only event covering a save with no line add/remove/qty-change at all, e.g. a modifier/note/discount-only edit, which the line diff deliberately doesn't cover). The granular events carry actingUserId from useTerminalLock().identity?.userId (the live PIN-verified operator) while actorId stays `user?.id` (the shared till login) on all events, generic and granular alike — unchanged. (4) activity-logs/page.tsx's ACTION_CONFIG gained entries for the three new actions; it already had a titleized fallback for anything unmapped, so this is a labelling improvement, not a functional requirement.

Alternatives considered

• Add a real line_ref column/field to cart_json's shape instead of reusing CartLineItem.id — rejected as out of scope: this is a client-persisted JSONB blob with ~5,902 live rows across two existing shapes (plain array, {items,discount} wrapper); minting a new persisted field through it is a cart_json schema change, which this ticket's own brief explicitly ruled out ("no database migration needed") and which the id field already serves the same purpose for, just under a different name.
• Retire ticket_cart_updated entirely once the granular events exist — rejected: a discount-only or note-only save has no line add/remove to report, and would silently stop being logged at all; keeping both is strictly additive and every existing consumer of ticket_cart_updated (reports, the activity-logs page itself) keeps working unchanged.
• Diff by array index/position instead of CartLineItem.id — rejected: the cart is routinely reordered by split/move operations elsewhere in this same file (useBatchMoveItemsToTickets appends moved items; useSplitItemToTickets/useSplitBillToTickets write new synthetic items to OTHER tickets), so position is not a stable identity and would misreport an unrelated line as "changed" whenever the array shifts.
• Thread the previous cart_json through from the client (the caller already holds the pre-edit cart in the Zustand store) instead of a server-side pre-read — rejected: useSaveTicketCart is called from six different components (cart-sidebar, split-bill-modal, split-move-modal, split-item-detail-modal, checkout-dialog, generate-payment-link's own copy) with varying local state shapes; a server-side read-before-write keeps the diff's correctness independent of what each caller happens to still have in memory, and matches this file's own existing fetch-then-write convention rather than inventing a second one.

"Category" resolves to four REAL, derivable dimensions — discount name (as applied), type (percent vs fixed, two inconsistent spellings normalized to one), scope (bill-level vs item-level, DERIVED from order_item_id IS NULL since pos_order_discounts has no scope column of its own), and source (preset vs manual, DERIVED from discount_id IS NULL). "%" is ALWAYS derived, never read from a stored value, for every row regardless of type — amount_cents / the order's own subtotal_cents for a bill-level discount, amount_cents / the specific item's total_cents for an item-level one — and rendered with a ≈ prefix everywhere, not just for fixed-type rows as the original plan assumed (it believed percent-type rows carried a stored percent; they don't, confirmed by reading every pos_order_discounts INSERT in the checkout RPCs).

Alternatives considered

• Build only the unambiguous per-bill list and ship the filter as a separate follow-up PR — the plan's own explicitly-offered fallback if the category interpretation wasn't confident. Rejected once the four dimensions were checked against the actual schema: name/scope/source are exact (not guesses — scope and source are structurally derivable from columns that already exist), and type only needed a two-way spelling normalization. That's confident enough to ship, not a guess dressed up as one.
• Show the preset discount's configured amount (pos_discounts.amount) as "the" percent for a preset-sourced discount, falling back to derivation only for manual ones — rejected: a preset's configured rate can drift from what was actually applied (edited after the fact, partially applied, stacked with another discount), and a manual discount has no preset row to read at all. One consistent derivation rule for every row is honest about what the data actually supports; a rule that looks "more authoritative" for half the rows and falls back for the other half invites someone to trust the preset number as exact when it isn't.
• Treat pos_order_discounts.order_item_id as unreliable and ask the operator to pick scope manually in a settings screen — rejected: order_item_id is written by the checkout RPC's own discount-application loop (20260916100333_checkout_rpc_ticket_claim_drawer_guard_batch_line_items.sql) specifically to distinguish a per-item discount from an order-level one; it's exactly as authoritative as any other column this report already reads.

INTENDED, NOT A REGRESSION. Once any report page sets a range (preset or custom), useReportDateRange (apps/pos/src/components/ui/date-range-picker.tsx) now restores it from a new sessionStorage-backed store (apps/pos/src/stores/report-range-store.ts) on every subsequent page that uses the hook — Sales, Discounts, Payments, Transactions, every other reports/* page, and the dashboard — until the user picks a different range or signs out. This explicitly supersedes each page's own `defaultPreset` argument (e.g. Discounts' "today", Sales' "last7") for every visit after the first range is set in that session. Precedence is URL-carried range (REP-05's item-sales drill-down state) > the persisted session range > the page's own default — unchanged, nothing about REP-05 regresses.

Alternatives considered

• Scope the shared range to only the explicitly-named pages (Sales, Discounts, Payments, Transactions) and leave every other reports/* page on its own default — rejected: the bug report's own phrasing ("every page of the POS admin") and the shared-hook architecture both point the same way, and a partial fix would reintroduce the identical complaint the moment Pablo's workflow touches an unlisted report page. One hook, one store, no page-by-page allowlist to maintain.
• Make persistence opt-in per page (a boolean flag passed to useReportDateRange) so pages keep their own default unless they ask to share — rejected as unnecessary complexity: no report page has a documented reason to WANT a different range than whatever the operator was just looking at elsewhere in the same session; the one page that structurally can't use this cleanly (REP-05's URL-carried drill-down state) already wins on precedence without any flag.
• Persist to localStorage instead of sessionStorage, matching useLocationStore's facility/location pick — rejected: Pablo's ask was explicitly "until changed or logged out," a per-session default, not a permanent one that silently reopens Monday's custom range on a fresh Wednesday login. sessionStorage also means a crashed/force-closed tab self-clears without relying on the sign-out path alone.

Investigation found two confirmed bugs, independent of each other: (1) terminal-lock-provider.tsx's visibilitychange→hidden handler called lockNow("idle") the INSTANT the tab reported hidden, with zero duration threshold — on an iPad PWA this fires from a Control Center swipe, a notification banner, or the app-switcher gesture, none of which mean the staff member stepped away, and it was tagged with the same "idle" lockReason the real multi-minute timer uses, so there was no way to tell a real idle-out apart from a half-second flicker. (2) apps/terminal's closed_by_name resolution queried `customers` directly by id, which only matches a user who ALSO has their own booking/order/membership row — a till-only cashier, exactly who closes bills by PIN, never does, so the lookup silently returned nothing and the (already-built, correctly gated) "Closed by" UI line never rendered; apps/pos (the actual back-office Sales Transactions screen) had no closed_by handling at all. Fixed by: (a) giving the visibilitychange trigger a 12s threshold before locking, cancelled if the tab returns to visible first, tagged with its own new "backgrounded" lockReason instead of reusing "idle"; pagehide is deliberately left instant (navigation-away/unload, where a deferred callback may not survive); (b) broadening the activity-reset listeners (pointerdown/keydown only, before) to also include scroll/touchmove/wheel, debounced, so passive use (scrolling a catalogue) counts as activity; (c) swapping the broken `customers` lookup for pos_resolve_facility_display_names — the established fix for this exact gap class (ALB-83, ALB-99) — and extending that RPC's evidence clause (migration 20261007042156) to cover pos_orders.closed_by_user_id/close_approved_by_user_id, which it didn't before; (d) raising the idle-lock default from 3 to 10 minutes (packages/common/src/lock-cadence.ts + migration 20261007043444, which also backfills any facility still sitting on the never-actually-confirmed 3-minute placeholder) — "lock after every bill" already re-locks at the moment that actually matters, so the idle timer only needs to be a backstop. Verified via a real e2e run (not just code reading): pin-lock-screen.spec.ts extended to open the real Transactions list and assert "Closed by <name>" actually renders after a PIN-verified close, not just that closed_by_user_id is set in the DB.

Alternatives considered

• Lower the idle timeout further instead of fixing the activity-listener gap — rejected: the actual bug Alba hit was the zero-threshold visibility trigger, not the idle timer's own length; narrowing idle further would not have touched the real cause and would add more friction for no benefit.
• Leave the instant visibilitychange lock as-is and just rename its lockReason — rejected: the underlying problem is the till locking during active use, not merely a mislabeled reason; a 0s threshold was never correct regardless of its label.
• Debounce/delay pagehide the same way as visibilitychange — rejected: pagehide fires on genuine navigation-away/tab-close/OS-reclaim, where the page's own JS may not survive long enough to run a deferred callback; it has to lock synchronously or not at all, so it's left untouched.
• Leave idle_minutes at 3 and only fix the client bug — rejected: the number itself was shipped as an explicitly-flagged, never-confirmed placeholder ("Default TBC with ops"); fixing the trigger bug without resolving the still-open placeholder would leave the same unconfirmed-decision debt in place.

REMOVED FROM THE NAV AS INSTRUCTED, NOT DESTROYED. The Sessions tab is gone and there is no Sessions nav entry. Its component (AcademySessionsLedger) is re-mounted on the new Billing screen as a COLLAPSED "Package deductions" section, and its API route plus _lib (api/admin/package-transactions/route.ts, _lib/ledger.ts and ledger.test.ts) are completely untouched and still tested. A link carrying ?tab=sessions redirects to /academy/billing?section=deductions, which arrives with the section already expanded. The premise behind the instruction is half right and the half that is wrong is the expensive half: Academy → Lessons is the SCHEDULE — what is coming up. This ledger is the record of deductions ALREADY TAKEN: which package paid for each past session, how many were left afterwards, and — the part Lessons cannot show at all — which lessons were cancelled without the student's credit being returned. On production that is 15 unambiguous cases plus 4 ambiguous ones, i.e. money the club kept by mistake. Deleting the UI would have removed a capability while looking like removing a duplicate.

Alternatives considered

• Delete the tab, the component, the route and the _lib outright, as the literal reading of "we don't need it" suggests — rejected: the instruction is explicitly reasoned from "sessions exists already as lessons", and that reason is false for the ledger half. Acting on an instruction whose stated premise is wrong, without saying so, destroys a capability silently. The nav change he asked for is delivered in full; what is preserved costs one collapsed section.
• Keep Sessions as its own nav entry and only move Billing — rejected: he named Sessions specifically and said he did not want it in the menu. The nav is his call and it is now his nav. Preservation does not require a menu slot.
• Keep only the API and _lib, delete the UI, and leave re-mounting for later — rejected as the second-best option, and it is what the fallback would have been: re-mounting it here is cheap (the component takes only facilitySlug, holds its own state and reads no URL params) and unobtrusive (collapsed by default, so its fetch does not even run on a normal visit to Billing). The capability staying REACHABLE rather than merely recoverable is the whole difference between a preserved feature and a deleted one with the pieces in a drawer.
• Put the ledger on Members instead — rejected: Members is now the enrolment screen. A deduction that was taken and never returned is money, and the money screen is Billing.

(a) BILLING GETS /{facility}/academy/billing, NOT /academy/payments. The nav label is Billing, and this nav has already paid for letting the label and the address disagree: v0.52.0 relabelled an entry "Members" while leaving its route at /academy/subscriptions, and the fix (2026-09-17) was to move the route so the two agreed. Shipping a screen labelled Billing at /academy/payments would recreate that defect deliberately. /academy/payments stays what it has been since it stopped being a page — a permanent redirect — now aimed straight at /academy/billing rather than bouncing through Members. (b) ?tab= IS NOW A ROUTING DECISION, READ SERVER-SIDE, ONCE. All three paths that can receive it (/academy/members, /academy/payments, /academy/subscriptions) share one helper, src/lib/forward-search-params.ts: `payments` and `sessions` redirect to Billing, everything else resolves to Members, the dead `tab` key is stripped at the redirect, and every other param survives verbatim including repeated keys. `sessions` additionally arrives as ?section=deductions so the ledger it asked for is open. (c) THE MEMBERS PAGE ONLY BOUNCES A BILLING TAB. ?tab=members, no tab, and any unrecognised tab render in place — they already resolve to that screen, so a redirect would be a wasted hop. (d) withDefaultTab IS RETIRED, its job absorbed as an options.defaultTab on the new dispatcher, so /academy/payments still means the money screen when the caller names no tab, and an explicit ?tab=members on it still wins.

Alternatives considered

• Reuse /academy/payments as Billing's real address — genuinely attractive, and rejected: it is the most-bookmarked money URL and reusing it would cost zero redirects. But the label is Billing, "payments" is already an overloaded word in this app (POS payments, /api/admin/academy-payments), and the nav-vs-address divergence is a named, already-paid-for mistake here. The redirect cost is one 308 on a path that already serves one today.
• Express the tab dispatch as next.config redirects with `has: [{type:'query', key:'tab'}]` — rejected: it would be six-plus rules across a dynamic [facility] segment, untestable without booting Next, and split from the Members page which must make the same decision anyway. The shared pure function is unit-testable (20 tests) and is the same "two redirects meant to behave identically must not drift apart" reasoning that created this file.
• Forward ?tab= through to the new routes untouched — rejected: it would be a parameter that reads as if it still selects something and selects nothing. It is dropped at the one moment the URL is already being rewritten, so removing it costs no extra hop.
• Redirect /academy/members?tab=members to the bare /academy/members for tidiness — rejected: that is the single most common published deep link onto this screen, and it already resolves here. Adding a hop to strip an inert param is a cost with no benefit.
• Route on the presence of ?open= or ?view= as well as ?tab= — rejected as speculative: verified in the code that AcademyPaymentsClient reflects `tab=payments` into the URL alongside `view=`, so any copied Billing URL already carries the tab. ?tab= is a sufficient and unambiguous discriminator.

Investigated the full history (PR #1188 → incident/revert #1203 → rebuild #1204, and DEC-453/455): the mandatory manager-PIN-approval gate on EVERY close (even for a manager themselves) was logged as a deliberate rule attributed to Alba ("only a manager can close"), but (a) no original ticket/brief document exists anywhere in the repo to source that claim against — it only ever appears as the building agent's own paraphrase, (b) PR #1188 was explicitly marked "do not merge until Néstor approves via Alba" and was merged anyway with no visible written approval in the thread, (c) it broke production checkout for ~35 minutes within 43 minutes of merging, requiring an emergency revert, and (d) the reviewer (Néstor) flagged it as a real operating-model change ("a manager has to be physically on the floor every shift") that was never explicitly re-confirmed before the rebuild re-shipped the same core rule. Researched how Square/Toast/Clover/SpotOn actually do this: all of them reserve manager-PIN approval for sensitive overrides specifically (voids, refunds, discounts above a cap, no-sale drawer opens) — none of them gate a routine bill close behind manager approval; a normal close is authenticated only by the operator's own PIN (for attribution), exactly what Alba originally asked for. Removed business rule 3 entirely (client: checkout-dialog.tsx's ManagerPinSheet gate on handleComplete/handleCompleteSplitPayment; server: create_pos_order_atomic's p_manager_pin_verification_id requirement, migration 20261006103519). Business rule 2 (bar staff can never close) and the operator-attribution half (p_acting_user_id / closed_by_user_id, stamped from the PIN-login identity) are both fully unchanged — those were never in question.

Alternatives considered

• Keep the gate and just ask Alba to confirm she still wants it — rejected: she'd already given a direct, explicit instruction to remove it ("first remove this last step") before the research was even requested; re-confirming something she'd already decided would be re-litigating a settled instruction, not diligence.
• Silently remove it with no investigation into where it came from — rejected: the repo's own standing process is to flag a connection to a prior named decision rather than quietly undo it, in case there was real context behind it worth surfacing even when the removal itself proceeds regardless.
• Narrow the gate instead of removing it (e.g. require manager-PIN only above a dollar threshold, or only for flagged operators) — not done now: this is a genuinely different, new rule that needs its own explicit design, not a smaller version of the one being removed. The underlying data model (pos_manager_pin_verifications, pos_verify_manager_pin, pos_request_bill_close_approval) is deliberately left in place, unused but intact, specifically so this remains easy to build later if wanted.

It was neither TerminalLockGate's flash/gate logic nor the close-gate's business logic (handleComplete's actual branching — bar-staff block, pinLockActive fail-safe, setPendingComplete — was already correct and unchanged). It was pure CSS stacking. checkout-dialog.tsx's own root is `fixed inset-0 z-[70] bg-background` — a deliberate, documented pattern in that same file: every OTHER overlay opened from inside the full-screen checkout (EmailCaptureDialog, CreateCustomerSheet's popovers, even a `<Select>` dropdown in keypad.tsx, which carries its own comment explaining exactly this) uses a custom z-index ABOVE 70 for precisely this reason. ManagerPinSheet (manager-pin-sheet.tsx) was the one exception: built on the shared `<Dialog>`/`<DialogContent>` primitive, whose default is a plain z-60 (ui/dialog.tsx). z-60 < z-70, so every time handleComplete opened it with PIN-lock on, it mounted correctly, in the right state, with `open=true` — and painted entirely behind the opaque, full-viewport checkout screen. A cashier tapping "Mark as Paid" saw literally nothing change, indistinguishable from a dead button. Confirmed by reproducing it in a real browser (screenshot evidence in the PR, matching Alba's report pixel-for-pixel) and by a deterministic check of the two elements' actual computed z-index (60 vs 70) — not by trusting any `isVisible()`/`toBeVisible()` assertion, which passed even on the broken code (see rationale). Fix: `DialogContent` now accepts an `overlayClassName` prop so a caller can override the overlay's z-index too (previously hardcoded, not overridable at all), and `ManagerPinSheet` passes `z-[80]` on both the content and the overlay — the minimal bump clear of checkout's z-70, matching the file's existing convention rather than inventing a new one.

Alternatives considered

• Raise the SHARED `<Dialog>` component's default z-60 globally instead of overriding it per-instance. Rejected — at least one other caller (the "Enter Amount" dialog's own `<SelectContent>` dropdown, keypad.tsx) deliberately sits ABOVE that same Dialog at z-[70]; bumping the Dialog's own baseline past that would invert and break THAT relationship instead. A scoped, per-instance override (the new `overlayClassName` prop, used only by ManagerPinSheet) fixes exactly the one broken case with zero blast radius on every other Dialog consumer in the app.
• Move the manager-PIN-to-close gate out of a Dialog entirely, into a custom fixed-overlay component matching EmailCaptureDialog/CreateCustomerSheet's own pattern. Rejected as unnecessarily invasive for this fix — the shared Dialog primitive (focus trap, Escape-to-cancel via onOpenChange, accessible title/description) is the right component here; it only needed to be told to stack higher, not replaced.

Re-examined the screenshot pixel-by-pixel: a real OS-drawn translucent blur overlay (the #1212 theory) should show color/content bleed-through, like frosted glass. What's actually in the screenshot is uniformly soft text and icons with NO translucency — the signature of a different, well-documented Flutter web bug class instead: CanvasKit/Skia's rendering surface can end up with its raster buffer size mismatched from its CSS display size (flutter/flutter#122541, #126795 — "canvas size and the CSS size are off by one"), forcing the browser to resample the canvas instead of showing it 1:1. That specific historical bug was fixed upstream in early 2024, before this app's Flutter version (3.44.1) — but the same CLASS of mismatch can recur any time the real viewport settles AFTER Flutter's first paint, which is exactly the sequence of launching a standalone iOS PWA (status bar / safe-area / address-bar-hidden layout resolves asynchronously after launch, unlike a stable browser tab). Fix (#1214): dispatch a synthetic `resize` event — what's known to self-resolve this bug class on desktop (manually resizing the window) — once on Flutter's own `flutter-first-frame` readiness event, plus once more 500ms later to also catch iOS's own post-paint safe-area settling. Gated to iOS only (`navigator.platform` sniffing, same approach Flutter's own web engine uses internally) so Android/desktop never pay for it.

Alternatives considered

• A blind `setTimeout(..., 400)` from script-parse time (the PR's own first draft) — rejected on code review: on a cold, uncached launch (the exact scenario reported) CanvasKit's multi-MB WASM payload can easily take longer than any guessed delay to load and attach Flutter's resize listener, making the dispatch a no-op. Flutter's compiled output confirms it fires a `flutter-first-frame` window event once its engine actually renders a first frame — anchoring on that real readiness signal instead of a guess is deterministic, not probabilistic.
• Firing the resize kick unconditionally on every platform (also the first draft) — rejected: resizing an HTML canvas clears its pixel buffer per spec, so if Flutter's resize handler doesn't diff against the previous size before re-rastering, this could cause an unnecessary blank-then-repaint flash on platforms (Android, desktop) that never had the bug being targeted. Scoped to iOS only instead.
• Revert #1212's IOSBlurGuard mechanism now that the diagnosis changed — not done. This round found `apple-mobile-web-app-status-bar-style` is `"default"`, not `"black-translucent"`, which (per #1212's own research) means `env(safe-area-inset-top)` likely reports 0 in this app's actual configuration, so that guard's `padding.top > 0` gate may never fire in practice — inert, not actively harmful. Reverting it now is unnecessary churn versus landing the fix that addresses what the screenshot actually shows; worth revisiting if the real root cause gets fully confirmed later.
• Round 2 (code review): tightened the iOS detection to exactly match Flutter's own upstream check (`ui_web/src/ui_web/browser_detection.dart`'s `maxTouchPoints > 2`, not the first draft's `> 1`), and added a `navigator.standalone === true` gate — the root-cause narrative is specifically about a standalone home-screen launch's async viewport settling, so an ordinary (non-installed) Safari tab has nothing for this to correct and shouldn't pay even the small cost of a synthetic resize. Re-verified empirically across 5 simulated contexts (iPhone standalone, iPhone regular tab, iPad-spoofing-Mac standalone, real Mac, Android): fires only in the two standalone-iOS cases, 0 elsewhere, 0 errors anywhere.

The facility route tree is server-rendered (app/(dashboard)/[facility]/layout.tsx is an async Server Component). localStorage does not exist on the server, so the very first HTML the browser paints — before any client JS has loaded, let alone hydrated — can only ever be the fail-closed default: locked. DEC-485's cache made the client CORRECT that a moment later, which is the flash itself, not a fix for it. No client-side state logic can change what the server already sent and the browser already painted. The actual fix: TerminalLockGate now withholds a committal answer (locked or unlocked) until the client has mounted — `useState(false)` + `useEffect(() => setMounted(true), [])`, returning `null` while `!mounted`. Server and client render IDENTICALLY on first paint (nothing to flash, no hydration mismatch); DEC-485's cached value is already resolved synchronously by the time `mounted` flips true, so the reveal goes straight to the right answer.

Alternatives considered

• Keep speeding up the client-side correction (smaller staleTime, earlier fetch, etc.) — this is what DEC-485 already was, and it cannot work: the flash is a function of what gets PAINTED FIRST, not how fast the correction after that arrives. Confirmed by extracting and visually inspecting individual video frames from a real demo recording after DEC-485 shipped — lock-screen frames appeared immediately after a navigation marker, proving the flash was real, not a misreading.
• Fallback to a dark loading skeleton instead of `null` while unmounted — rejected: for the common toggle-off case a dark skeleton still LOOKS like the pin screen flashing (same background color, just without the keypad), which is exactly the complaint this exists to fix. `null` doesn't lean toward locked or unlocked at all.

useFacilityPinLockActive's last-confirmed answer is now persisted to localStorage (keyed per facility) and handed back as the query's placeholderData — a synchronous, zero-network starting value a returning device already has the instant it boots. For a facility that's had pin-lock off for a while (the case this was reported about), the lock screen now has no reason to ever render on a normal boot: "off" is the free, already-known default, not something that has to be earned fresh via a network round-trip every time. The real fetch still always runs in the background and corrects this if it's actually wrong (e.g. a manager just turned the toggle on from elsewhere) — this only removes the unnecessary network DEPENDENCY for the unchanged, common case. Verified directly: a returning session with a cached "off" value never renders the lock screen at all, confirmed via a MutationObserver watching for it across a second boot, not just checking the end state.

Alternatives considered

• Keep stacking defensive layers on the symptom (this is what the four same-day fixes before this one did). Rejected as the actual answer once the pattern became obvious across four attempts — every one of them was still paying for a network round-trip on every boot that a returning, unchanged-state device didn't need to pay for at all.
• Default `locked` to `false` unconditionally and only lock once the server says to. Rejected — this is the EXACT failure mode fail-closed-by-default was built to prevent (a facility that's never configured this at all, or a first-ever cold boot before anything is cached, would briefly show a usable, PIN-free till). The cache only kicks in once there's an actual prior answer to trust; absent that, the original fail-closed default is still correct and still applies.

Fix each writer so it changes lesson + bookings in ONE transaction: update_lesson_status_for_staff and update_lesson_and_bookings_status cancel live legs through set_booking_outcome (refund rules + audit event), the admin court change moves into replace_lesson_courts, and the cancelled-lesson 409 guard is extended to the students check-in route. Cancelled lessons cannot be reopened through these RPCs. A read-only view lesson_booking_orphans defines 'orphan' for monitoring. KNOWN GAP (follow-up): these RPCs do not refund package sessions the way cancelLessonCascade does. A trigger on lessons.status is NOT shipped — left for Alba's call.

Alternatives considered

• Trigger on lessons: cancel any live linked booking when status becomes cancelled — not shipped. It fixes every future writer automatically, but cancelling inside a trigger has to reproduce set_booking_outcome's refund semantics and audit event, and it hides which writer is wrong. Needs an explicit decision once the writer fixes have run for a week.
• Constraint refusing a live booking linked to a cancelled lesson — not shipped: it would turn a stale client write into a user-facing error instead of repairing the state.
• Point the PWA at update_lesson_and_bookings_status only and drop update_lesson_status_for_staff — rejected: installed older PWA builds still call the old RPC, so it must be made safe, not removed.

Stop chasing the exact mechanism and reproduce the fix that's already confirmed to work, every time, by hand: force-quitting and reopening the app IS a full page reload — the most reliable reset there is, since it re-initializes everything (auth session, every query, the whole provider tree) from scratch with no code path left that can leave any piece of state stuck. terminal-lock-provider.tsx now does this automatically: on resuming from having been hidden for more than 30 seconds (targeting an actual device sleep, not a quick glance away), it reloads the page — but ONLY when the cart is empty. The cart lives in a plain, non-persisted Zustand store, so reloading with items in it would silently wipe an in-progress sale — a new, worse problem than a stuck lock screen. The common case (till idle, no sale in progress when the device slept) self-heals completely automatically; a till mid-sale is deliberately left alone, accepting that the rarer case could still need a manual kill rather than ever risking a lost sale. Verified directly: an empty-cart till reloads after a simulated 31s-hidden period; a till with an item in cart does not reload and the item is still there afterward.

Alternatives considered

• Keep debugging the exact root cause (token refresh timing, Safari background-tab throttling specifics) before shipping anything further. Rejected given the three days already spent and that none of it can be verified from this environment anyway — a verified-working brute-force fix beats an unverified precise one, same reasoning DEC-483 already used for pulling out the unverifiable Realtime attempt.
• Reload unconditionally, regardless of cart contents. Rejected outright — silently losing a cashier's in-progress sale is a strictly worse failure than a stuck lock screen requiring a manual kill.
• Prompt the cashier to confirm before reloading, even with an empty cart. Rejected as needless friction for the common, safe case — an empty till has nothing to lose, so there's nothing to confirm.

Layered fix, no single silver bullet: (1) useFacilityPinLockActive's staleTime cut from 2 minutes to 10 seconds — bounds any gap to a short, practical window; (2) refetchOnWindowFocus added — covers the actual scenario that happened, switching from the Settings tab back to the Terminal tab refetches immediately, using React Query's own built-in behavior, nothing new to verify; (3) checkout-dialog.tsx's performComplete/performCompleteSplitPayment now catch this exact server rejection (matched on the RPC's error message, not instanceof Error — the RPC throws the raw Postgrest error object, not a wrapped Error) and recover: invalidate the stale query, show a clear actionable toast ('Security settings just changed — tap to charge again'), so the very next tap succeeds instead of needing a reload to unstick. Verified end-to-end: a stale client's first charge attempt is cleanly rejected with the friendly message (no unhandled rejection), and the second attempt correctly routes through the manager-PIN gate and completes. New permanent e2e regression test covers exactly this sequence.

Alternatives considered

• Supabase Realtime subscription (postgres_changes on pos_terminal_security_settings) pushing an instant invalidation to every open tab/device — the architecturally 'right' fix, same pattern apps/admin's use-realtime-availability.ts already uses for bookings, and initially built. Pulled back out: the channel reported SUBSCRIBED in local testing but no change event ever actually arrived after multiple debugging passes (publication membership confirmed correct, container restarted, event payload logging added) — given this whole feature exists because of an incident already caused by shipping something not thoroughly verified, shipping a fix I could not prove works was judged worse than a simpler one that is verified. Left as a legitimate follow-up, not abandoned as wrong — just not blocking this fix.
• Leave staleTime at 2 minutes and rely solely on the error-recovery catch. Rejected — a 2-minute window where the UI confidently shows the wrong security state (either direction) is itself a bad experience even with a clean recovery message once hit; shortening staleTime makes hitting that window the uncommon case rather than routine.

Manual stays the default; a small "Generate a random PIN instead" link/button sits below the PIN pad. Tapping it generates and assigns immediately (no second confirm step) and swaps the dialog into a reveal view — large PIN, Copy PIN, Done — using the same one-time-reveal wording and clipboard pattern as the existing bulk-generate flow. Extracted the retry-on-collision loop both flows need into a shared assignRandomPin() helper rather than duplicating it.

Alternatives considered

• Random-first (flip the default, "Type a PIN instead" as the link). Rejected for now: resetting to a PIN the staff member specifically asked for ("make mine 2206 again") is the common case for a single reset; bulk/random is the common case for onboarding, which already has its own dedicated flow. Revisit if managers turn out to prefer generating by default.
• A toggle or tabs component for the two modes. Rejected — two states don't justify the extra UI chrome; a single contextual link reads clearly enough.
• Pre-filled-but-editable random PIN in the same PinPad. Rejected — PinPad is a dot-indicator keypad with auto-submit on the 4th digit, not an editable text field; retrofitting that would touch a shared component for one caller's benefit.

No — two real bugs surfaced only through manual + e2e testing. (1) Flipping the switch ON force-relocked the CURRENT session immediately, because TerminalLockProvider is mounted at the facility layout level (wraps every route, Settings included) — a manager turning the feature on got yanked out of the Settings page they were using to configure it. Fixed by removing the force-relock-on-adoption transition entirely; propagation is now natural (a fresh navigation, or DEFAULT_LOCK_CADENCE's own lock-after-bill/idle defaults), never forced on an already-mounted session. (2) checkout-dialog.tsx's manager-PIN sheet still unconditionally appeared with the toggle off, contradicting the Settings page's own 'bills close without a PIN' copy — handleComplete/handleCompleteSplitPayment now check the provider's new pinLockActive signal and skip straight to performComplete(method, null) when it's explicitly false.

Alternatives considered

• Ship the plan as written and fix issues in a follow-up once reported. Rejected: this is exactly the discipline gap that caused the original incident (SEC-01 reached production without a real end-to-end checkout test ever being run) — the standing lesson from that incident is to find these before deploying, not after.

One boolean column, pin_lock_enabled, on pos_terminal_security_settings (the existing per-facility terminal-security table — not facilities, not a new table). DEFAULT false for new facilities (opt-in, matching Square's 'require passcodes at point of sale' — a bolt-on toggle over an identity system that doesn't otherwise require a PIN, the closer analog than Toast/Clover where PIN login IS the identity system with no off-state — and matching this repo's own checkout_tips_enabled/checkout_offline_enabled precedent of optional features defaulting off). A new RPC, pos_facility_pin_lock_active(p_facility_id), returns EXISTS(pos_staff_pins) AND pin_lock_enabled — the single combined signal the client reads; pos_facility_has_staff_pins is left untouched for its own literal 'has any PIN rows' meaning, since nothing else needed its meaning changed and a future admin/export tool might. create_pos_order_atomic's gate keeps its own INLINE copy of the same two-clause predicate rather than calling the new RPC — that RPC raises when the caller has no resolvable facility role (correct for an authenticated client read), which would be a new failure mode for the checkout RPC's own direct callers (apps/pos included) that this change must not introduce.

Alternatives considered

• A pin_lock_status enum (never_enabled/enabled/disabled) plus a pin_lock_first_enabled_at timestamp, to preserve onboarding/support-triage signal about whether a facility tried and abandoned the feature. Rejected on the same grounds DEC-452 rejected a station enum for is_bar: every current reader (the order-gate, the lock-provider effect, the new UI toggle) asks one binary question, and no code reads a third state. If that triage need becomes real later, it's a normal additive migration then, not a reason to ship unused state now.
• A blanket DEFAULT true for all facilities, preserving today's fused 'generate PINs = lock is on' behavior unconditionally. Rejected as not actually engaging with the question of what a brand-new facility should get — it just avoids deciding, and the research (Toast/Square/Lightspeed/Clover) argues Square's opt-in model is the closer fit for Setpoint's single-shared-login starting point.
• Calling the new pos_facility_pin_lock_active RPC from inside create_pos_order_atomic's gate instead of duplicating the predicate. Rejected — see decision text; the duplication is accepted as the smaller risk, cross-referenced by comment so the two can't silently drift without a human noticing.

A new SECURITY DEFINER RPC, pos_facility_has_staff_pins(p_facility_id) — callable by any authenticated facility role, not just manager+, since it has to answer BEFORE a PIN identity exists — tells TerminalLockProvider whether the facility has adopted SEC-01 at all (any pos_staff_pins row). While that answer is false, the provider passes straight through (locked stays false, matching today's pre-SEC-01 behavior exactly); it fails closed (locked=true) while the answer is still loading, and the moment the facility's row count flips to "has PINs", the provider force-locks immediately rather than waiting for the next idle/bill trigger. Rollout runbook unchanged otherwise: a manager+ signs into apps/terminal on their OWN device/session (not the shared till) to set PINs for every staff member before enabling this for real tills.

Alternatives considered

• Exempt Settings > Staff & security from the lock gate so a staff-role till session could reach it directly. Rejected: that page is deliberately manager+-gated on the SESSION's own role (owner/admin/manager), independent of SEC-01 entirely — a staff-role session can't reach it today, PIN lock or not, and loosening that gate to solve a bootstrap problem would reopen a different, unrelated hole (any staff member could then reassign anyone's PIN).
• Ship a one-time 'first PIN wins, no auth required' bootstrap flow on the lock screen itself. Rejected: that's a standing backdoor disguised as a one-time affordance — nothing distinguishes 'legitimate first setup' from 'an attacker resets everyone's PIN the moment this deploys' from the lock screen's own vantage point.

Enforce it facility-wide: a new check resolves v_facility_has_staff_pins (EXISTS any pos_staff_pins row for p_facility_id) before the existing gate, and raises if that's true while p_acting_user_id is NULL. Once a single facility has set up even one staff PIN, EVERY caller creating an order there — apps/terminal, apps/pos, or any future direct caller — must supply a verified p_acting_user_id; there is no more opt-out. A facility that has never adopted staff PINs sees zero behavior change.

Alternatives considered

• Keep it terminal-path-only (DB gate stays genuinely opt-in) and rewrite the header comment + DEC-453 to say so plainly instead of implying it's unconditional. Rejected: business rule 3 ('every single close, every operator, no exceptions' — DEC-453) is a hard requirement, not a terminal-UI convenience; a gate that any other direct caller can simply skip by omitting one field doesn't satisfy it, it just hides the gap behind confident-sounding prose. The whole point of putting this check in the DB instead of the client (this migration's own header, on create_pos_order_atomic) was that the RPC is directly callable — an opt-in DB gate is exactly as bypassable as the client-only gate it was meant to replace.

Resolve names with a second, explicit query against public.customers (id IN (closed_by_user_id, close_approved_by_user_id)) inside useOrder(), attaching closed_by_name/close_approved_by_name onto the returned object — not a PostgREST embed.

Alternatives considered

• Add a foreign-key-based embed (closed_by:closed_by_user_id(...)) directly in the select string. Rejected: PostgREST can only embed via FKs it can see in its exposed schema graph, and auth.users isn't in it — this fails outright, not just awkwardly.
• Change closed_by_user_id/close_approved_by_user_id to reference public.customers instead of auth.users. Rejected: pos_verify_staff_pin and pos_verify_manager_pin already resolve a staff member's identity via auth.uid() (an auth.users id), and pos_staff_pins.user_id already references auth.users — switching just these two columns to a different target would break that consistency for no real benefit, since customers.id already equals the same uuid for any staff member (the existing join pattern those RPCs already rely on).

PIN entry is the default (first thing shown) when the gate renders, reusing the same PinPad + pos_verify_manager_pin RPC as manager-pin-sheet.tsx. The original approver-picker → email-code flow survives unchanged as an explicit fallback, reachable via a "No manager here — send a code by email instead" link, with a matching link back from the email flow's approver-picker step.

Alternatives considered

• Replace the email flow entirely. Rejected: the email flow is the only path that works when no manager is physically at the till (remote approval) — removing it would regress that case, which the PIN fast-path can't cover.
• Keep email as the default, add PIN as a secondary option. Rejected: a manager standing at the till entering a 4-digit PIN is strictly faster than anyone waiting on an email round-trip, so defaulting to the slower path when the faster one is equally always-available doesn't serve the common case — the ticket that prompted this (Pablo's traceability concern → the wider staff-PIN request) exists specifically because staff and managers are physically present at the till.

Built and committed, in this order: (1) the full additive data model + RPCs + create_pos_order_atomic patch, manually functional-tested end to end against local Postgres before committing (caught and fixed two real bugs — see DEC-451); (2) packages/common pure helpers (PIN format, lock cadence) with unit tests; (3) the PIN identity provider, lock screen, PIN pad, manager-PIN sheet, and their wiring into the till route; (4) the manager-PIN close gate + bar-block wired into checkout-dialog.tsx (business rules 2 and 3 — the actual core ask). Stopped there and reported status rather than also building the discount-approval-gate PIN fast-path, the bill-detail activity-log UI, the Settings > Staff & security page, and e2e tests in the same pass.

Alternatives considered

• Build the entire ticket's scope before any check-in. Rejected: this is a multi-thousand-line, multi-surface feature: continuing uninterrupted for the several more hours the remaining UI-only surfaces (discount gate, activity log, settings page, e2e tests) would take, with no intermediate checkpoint, risks losing a large amount of unreviewed work to a single mistake, and the coordinator explicitly asked for a status check partway through.
• Build only the migration and stop, since the ticket is design-approval-gated anyway and the deepest technical risk (does the server-side gate actually work) is fully resolved by that alone. Rejected: business rules 2/3 (bar-block, manager-PIN-required-to-close) are the actual point of the ticket — a migration with no client wired to it doesn't let anyone (including Nestor, reviewing the prototype-vs-build gap) see or try the core behavior.

Manager-driven only for this pass: pos_set_staff_pin requires the caller to hold owner/admin/manager (or be service_role); there's no path for a staff member to set their own PIN. Settings > Staff & security (not yet built in this pass — see DEC-455) will be the only place a PIN gets assigned or reset.

Alternatives considered

• Build a first-login 'pick your own PIN' wizard matching the prototype's descriptive copy literally. Rejected: not asked for in the ticket's explicit build list, adds a whole new onboarding flow's worth of UX (network of: unset-PIN detection, forced-setup screen, its own validation) for a ticket that's already large and design-approval-gated, and the prototype's own INTERACTIVE surface (the only screen actually built and clickable) is manager-driven, not self-serve — the descriptive copy reads more like a plausible future extension than the agreed interaction model.

Closing NEVER gets the shortcut — every close opens ManagerPinSheet and requires an explicit PIN entry, even when the operator who tapped Charge is themselves owner/admin/manager. This is implemented as the literal absence of an auto-approve branch in checkout-dialog.tsx's handleComplete/handleCompleteSplitPayment (unlike, say, a future discount fast-path, which per the ticket text explicitly CAN auto-approve for a manager+ operator) and mirrored server-side: create_pos_order_atomic's gate has no 'skip if p_acting_user_id is already manager+' branch either — it unconditionally requires and consumes a fresh pos_manager_pin_verifications row whenever p_acting_user_id is set.

Alternatives considered

• Match the prototype's stepUp() shortcut exactly (auto-approve when already manager+), since that's the ONE interaction pattern the prototype actually built and the ticket says to 'reuse the prototype's elevated-action interstitial pattern'. Rejected: business rule 3's own text is explicit and specific — 'every single close, not just an occasional spot-check' and the parenthetical about admins/owners — which reads as a deliberate, called-out exception to the general elevated-action pattern, not an oversight. The ticket text itself flags closing as needing 'its own explicit treatment' distinct from the reused pattern.

pos_staff_pins.is_bar boolean NOT NULL DEFAULT false — a single flag, not a station enum. Per-facility, per-staff-member (same granularity as user_facility_roles), toggled independently of resetting a PIN via its own RPC (pos_set_staff_bar_flag).

Alternatives considered

• A `station text CHECK (station IN ('front_desk','bar'))` enum column, matching pos_print_stations' own naming convention for 'station' as a concept in this schema. Rejected (for now): nothing else in this ticket, or in the confirmed business rules, needs a THIRD value — a two-value enum with one real alternative to the default is just a boolean wearing a bigger costume. Introducing an enum ahead of an actual second use case is exactly the kind of premature generality CLAUDE.md's Article VII-style 'no future-proofing' bias (via the Engineer persona's constitutional gates) argues against.

SHA-256, unsalted, via Postgres's existing pgcrypto extension (`encode(extensions.digest(p_pin, 'sha256'), 'hex')`) — identical to pos_discount_approvals.code_hash. A straight UNIQUE(facility_id, pin_hash) constraint enforces 'PINs are unique within a club' natively, which an unsalted hash makes possible without a loop-compare (a salted hash would need one, since the same PIN produces a different hash per row).

Alternatives considered

• bcrypt/scrypt via pgcrypto's crypt()/gen_salt('bf') — the textbook-correct choice for a long-lived low-entropy secret, and pgcrypto (with the bf/blowfish support crypt() needs) is already enabled in this project (00000000000000_initial_schema.sql). Rejected after explicit self-debate: for a STRICTLY 4-digit PIN, the keyspace is only 10,000 values — an attacker with the hash (DB leak) can precompute all 10,000 SHA-256 digests once, in milliseconds, and reverse every PIN in the table instantly; a salt does not meaningfully raise that bar (the attacker just re-hashes 0000-9999 per salt, still instant). bcrypt's deliberate slowness buys, at most, a few hundred extra milliseconds per row before the full 10k space is exhausted offline — real, but marginal for a keyspace this small, and it would be the only slow-hash usage in an otherwise entirely-SHA-256 codebase for no meaningful security gain against the actual threat model.

DELETED, all three files: lib/academy-period.ts, lib/academy-period.test.ts and components/admin/academy-period-filter.tsx. Billing, Sessions and Lessons take MAIN's period hunks verbatim — the shared <DateRangePicker>, the Month-to-date default, the reset/isDefault rule — and this branch keeps only its NON-period hunks on those three files: the settled-row gating (DEC-457), the Due/Paid/All switch defaulting to All, and the tab pinning (DEC-460). Enrollments is the one screen the picker did not reach — on main it had no date filter at all, which DEC-432 says in as many words — so it gets `useDateRange(timezone)` + `<DateRangePicker … testIdPrefix="player-subscriptions">` HERE, together with the route's interval-overlap filter (DEC-458), because the control and those semantics are only safe when they arrive together. 🔴 NOTHING WAS REIMPLEMENTED: after this rebase there is no second resolver and no second picker anywhere on this branch. The date arithmetic this branch measured and tested survives as lib/date-range.ts, ported case for case and extended from 24 tests to 32 upstream.

Alternatives considered

• Keep the pill and the academy-period resolver, letting the two controls coexist on different screens. Rejected: that is the fifth date-filter design the convergence exists to remove, and Nestor named it directly — “stop doing new and different designs all over the place”.
• Keep lib/academy-period.ts as a thin re-export of lib/date-range.ts so the import lines did not have to change. Rejected: a second name for one module is the same drift with an extra hop, and the rename costs five import lines once.
• Convert Enrollments to the picker upstream in #1185 rather than here. Rejected there and still rejected: its route filter is interval overlap rather than start date, with production measurements behind it that live on this branch — deriving it upstream would have either conflicted with this branch or quietly diverged from it.
• Rebase this branch on top of feature/academy-collections so both period swaps ship as one. Rejected: they are independent branches onto main, and stacking them would make neither mergeable alone.

On SETTLED_STATUSES (paid, cancelled, expired), the one list the server refuses on, moved to lib/payment-request-status.ts — a leaf module with no imports — and re-exported from payment-requests/_lib/reminders.ts so every existing import path is unchanged. The client imports the same constant, so the two cannot drift because there is only one. 🔴 IT CANNOT BE GATED ON THE FEED’S OWN status: requestStatus() maps an EXPIRED request to feed status ‘overdue’ (an expired hosted checkout means the LINK lapsed, not the debt), and ‘expired’ is a settled status — so gating on the feed vocabulary would leave exactly the rows the server refuses still being offered a reminder. The feed row therefore carries a new request_status field with the raw payment_requests.status, null on the two sources that have no request. Null is explicitly NOT settled: an unpaid package nobody has chased yet is the row a reminder SHOULD be offered on, since sending one is what creates the request. Hidden rather than disabled, matching the Assign button. Reminder history stays (a READ, and a legitimate thing to want on a paid package); Revert to due stays (it applies BECAUSE the row is settled). The reminder panel itself is also gated — it is reachable on a settled row via Reminder history, and a row can settle while it is open — so its channel picker and Send button are withdrawn and handleSend refuses with a toast rather than silently.

Alternatives considered

• Gate on row.status === ‘paid’. Rejected: it is a second list, invented client-side, and it misses cancelled and expired — including the expired-request-reads-as-overdue case above, which is the whole reason the raw status had to be plumbed through.
• Import SETTLED_STATUSES straight from reminders.ts into the client component. Rejected: that module pulls in the admin Supabase client, the messaging provider and the template renderer — server code in a ‘use client’ bundle.
• Put the constant in academy-payments-types.ts. Rejected: that file is explicitly the CLIENT’s view of a wire shape, and having the reminder pipeline import the browser’s view of a feed row to learn a database rule points the dependency the wrong way.
• Disable the menu items with a tooltip instead of hiding them. Rejected for consistency with how this screen already gates the Assign button and the inline Mark-paid control, and because a disabled row action in a dropdown is the thing that reads as broken.
• Derive settledness server-side and send a boolean. Rejected: the raw status is more useful — the panel names it back to the operator (‘this payment is paid/cancelled/expired’) — and a boolean would have to be recomputed anyway the first time a second rule needed it.

OVERLAP, not start date: starts_at <= periodEnd AND expires_at >= periodStart, resolved through facilityDateRangeBoundaries at the club’s midnight and applied on the query builder so it lands BEFORE count: ‘exact’ and before .range() — total and page describe one set. ‘Month to date’ therefore means ‘was enrolled at some point in that window’, not ‘signed up inside it’.

Alternatives considered

• Filter on starts_at, matching the other three screens literally. REJECTED ON MEASURED DATA, and this is the decision the numbers made rather than taste: verified read-only on production 2026-09-18, pad-thai-padel holds 155 enrolments of which only 30 started this month, and only 16 of the 81 ACTIVE ones did. A starts_at filter under the Month-to-date default would have hidden 65 of 81 active members — on the tab that, as of the same day, is the one an operator lands on. Overlap returns all 155 for this month and 125 for last month, so the filter still does real work without gutting the landing view.
• Give Enrollments no period control, as the one screen where it does not fit. Rejected: the explicit ask was all four screens, consistently, and the control IS meaningful here once the semantics match the data — it is only the naive reading that breaks.
• Filter on expires_at (‘whose enrolment ends in this window’). Rejected: it is a renewals question, not a ‘who is enrolled’ question, and it would be an equally arbitrary half of the interval.
• Add a computed ‘live during’ column or view. Rejected as unnecessary — two comparisons on columns that already exist express it exactly.

Two fixes, and the second is the one that matters. (1) The chips become Active · Expiring soon · Exhausted · Expired · Cancelled, ordered by the life of an enrolment and labelled explicitly rather than via status.replace, which gave lower-case ‘expiring soon’ beside capitalised siblings. (2) status and payment_status are now WHITELISTED and answer 400 on an unrecognised value, using the same parser contract as product one filter over on the same route (undefined = no filter, null = reject). They were previously a bare .eq() on whatever arrived, so an unknown value returned an EMPTY LIST — which is exactly why a missing chip was invisible instead of loud. The whitelist mirrors player_subscriptions_status_check (all seven legal values), NOT the five chips: a filter on a legal column value should return an honest empty list, not a 400, and a whitelist derived from the schema cannot go stale against the data the way a hand-picked list would.

Alternatives considered

• Add the exhausted chip and stop. Rejected: it fixes one instance and leaves the mechanism that hid it. The next missing chip would be just as silent.
• Whitelist only the four statuses the mirror can produce (player_packages_status_check). Rejected: expiring_soon and pending ARE reachable — compute_subscription_status, the BEFORE UPDATE trigger, returns them from the date window — so 400ing them would refuse a legal column value.
• Remove expiring_soon as a phantom, since production holds zero. Rejected after checking WHY it is zero: it is transient rather than unreachable (a row lands in it only when written within 7 days of expiry), and a census is a snapshot, not a proof. Deleting a chip because it was empty on the day you looked is the exhausted gap in reverse.
• Offer chips for all seven legal values. Rejected: suspended cannot be produced at all (the mirror copies player_packages.status, whose CHECK does not admit it), and pending would put a second unrelated meaning of that word directly beside the Payment column, which already shows pending for money owed. Both remain accepted by the route, so a deep link to either returns an honest empty list.
• Silently widen an unknown status to ‘all’. Rejected outright — answering a request to narrow with the full list answers a question nobody asked, and the operator has no way to tell.

Order becomes Enrollments → Sessions → Billing, Enrollments becomes the default tab, the money tab is relabelled Billing, and its Due/Paid/All switch defaults to All. 🔴 THE TAB KEYS AND TESTIDS ARE UNCHANGED — members is still Enrollments and payments is still Billing — because ?tab= is a published deep link that both /academy/subscriptions and /academy/payments forward verbatim, and the Enrollments tab already carries this scar once (its key stayed members when it was relabelled). onTabChange now derives ‘which tab owns the bare URL’ from DEFAULT_TAB rather than hardcoding payments, which after the reorder would have inverted what a bare link means.

Alternatives considered

• Rename the keys to match the labels (tab=billing, tab=enrollments). Rejected: it silently drops everyone holding an existing link onto whichever tab is default — a page that still loads, still 200, just the wrong screen. Nobody reports that.
• Keep Due as the Billing default. Rejected by the same sentence that settles the reorder: ‘this won’t be a section to track due payments’ makes the tab a RECORD of academy money, with Due as one filter within it rather than the screen’s purpose.
• Leave /academy/payments forwarding its query string untouched, as before. 🔴 REJECTED, AND THIS WAS A REGRESSION CAUGHT DURING THE CHANGE RATHER THAN A DESIGN CHOICE: that redirect could forward an empty query and still be correct ONLY because a bare /academy/members defaulted to the money tab. With the default now Enrollments, every existing /academy/payments bookmark — the address literally named after the money screen — would have silently landed on a different screen. A new withDefaultTab helper now pins ?tab=payments on that path when, and only when, the caller has not named a tab themselves; an explicit ?tab=members on the old path still wins. /academy/subscriptions deliberately does NOT pin, because it always meant ‘the Members screen’, whose default is now Enrollments.

Fix it here, in the route, by adding `.eq('facility_id', facility_id)` to the template read — the facility that requireFacilityAccess has already authorised one screen up. A foreign or unknown package_id now returns 404 with NO row written, and the two cases are deliberately indistinguishable in the response: saying which it was would confirm that some other club owns that id. TWO THINGS THE OBVIOUS FIX DOES NOT COVER, both checked rather than assumed. (1) `package_items` CANNOT take the same filter — it has no facility_id column at all, verified against production's information_schema and not merely against the generated types: its columns are id, package_id, class_id, class_type, session_count. Its scoping is TRANSITIVE through package_id, and the template read above is what proves that package_id belongs to this facility. That is the rule satisfied one join away, not an exception to it, and the code says so — including the warning that moving this read above the template read would silently un-scope it. (2) `assign_package_with_credits` has the SAME class of hole and is NOT fixed here, deliberately — see the rationale.

Alternatives considered

• Leave it — it is pre-existing, and the dialog cannot reach it. Rejected. The branch promotes Assign from four levels down a settings screen to a primary button on Members; 'the UI cannot send that request' has never been an access control, and this one writes both cross-tenant data and cross-tenant money. A facility filter is one line.
• Return 403 for a package that exists at another club and 404 only for an id that exists nowhere. Rejected: it turns the endpoint into an oracle for whether an arbitrary uuid is a real template at some other club. 404 for both is the same answer the rest of the admin API gives.
• Filter in application code after the read (fetch by id, then compare pkg.facility_id to facility_id). Rejected: it reads the foreign row before rejecting it, so the row crosses the tenant boundary into this process either way, and every future edit to the handler has to remember the check. The database filter cannot be forgotten.
• Write the migration that scopes assign_package_with_credits in this PR too. Rejected for this PR — it is a change to a live SECURITY DEFINER function with its own blast radius (the wallet subsystem), and it belongs in a migration reviewed on its own terms, not folded into an admin-route fix. Reported instead, with the reachability measured.
• Also scope the GET handler's reads while here. Rejected as unnecessary: GET already filters player_packages by facility_id, and its customers / player_package_sessions reads are keyed off that filtered set, so they are transitively scoped. Nothing to fix.

Surface it, and make the two empty states visibly different, because that difference is the entire point: a destructive-styled message naming the failure when the fetch throws or returns non-OK, and a plain 'This club has no active packages to assign.' when the fetch succeeded and the list is genuinely empty. A non-OK response is now thrown rather than parsed as data, so a 500 can no longer arrive as `packages: undefined` and read as zero packages. Styling reuses this file's own searchError idiom (border-destructive/30 / bg-destructive/5) rather than inventing a third error treatment inside one dialog.

Alternatives considered

• Leave it — it is verbatim from the code that already shipped. Rejected: 'it was already like that' stops being an argument when the same code moves onto a primary action. An operator who concludes the club's packages were deleted, and goes to re-create them, is being actively misled by a network blip.
• Toast the failure. Rejected: the toast outlives the dialog and leaves the empty dropdown behind with nothing beside it, so the state on screen is still wrong once the toast fades. The message belongs next to the control it explains.
• Close the dialog on failure. Rejected: it destroys the player the operator has already selected and gives them nothing to act on — a dead end dressed as a decision.
• Retry automatically. Rejected for this pass: the operator can close and reopen, which is the same request, and a silent retry loop behind a dialog that shows nothing is how the original bug reads to begin with.

No — it was verifiably broken, so the WORKING dialog was promoted instead and the broken one deleted. AssignPackageDialog moved out of player-packages-list.tsx into its own module, imported by both Player Packages and Members. Evidence against the orphan, all read from the live code: (1) it consumed `data.players` from /api/admin/players/search, which returns `{ results }` at route line 102 — the student list was always empty, so no assignment could ever begin; (2) it read `pkg.price` and `pkg.type` from /api/admin/lesson-packages, which does `select("*")` on lesson_packages — a table whose generated Row type has price_amount and package_type and NO price or type — so `pkg.price.toFixed(2)` threw as soon as the package list rendered; (3) it fetched /api/admin/players/<email>/balance, which does not exist anywhere in app/api (the real route is /api/admin/wallet/customer-balance, keyed by user_id, returning balance_amount). It also hardcoded '$', violating DEC-108. git grep confirmed it had never been rendered by any component, which is why none of this had ever surfaced.

Alternatives considered

• Follow the brief literally and mount it as-is — rejected: it ships a primary action that cannot complete a single assignment, and the first operator to click it hits a TypeError.
• Repair the orphan's three contract bugs and mount it — rejected: that is rebuilding it, and it leaves two assign dialogs to drift apart for no gain.
• Export AssignPackageDialog from player-packages-list.tsx in place — rejected: makes the Members screen import from a Setup screen's list module; a shared dialog belongs in its own file.

From /api/admin/facilities/my — the endpoint the sidebar's facility switcher already calls — matching on the current slug, with canAssign = role !== null && WRITE_ROLES.includes(role) and WRITE_ROLES mirroring player-packages/_lib/write-roles.ts (owner/admin/manager). The button is hidden, not disabled, while the role is unknown or insufficient. A failed probe fails CLOSED and is console.error'd with a comment saying why dropping it is safe.

Alternatives considered

• Add `role: access.role` to /api/admin/player-subscriptions and thread it up via onRoleResolved (the academy-payments pattern) — rejected: Radix unmounts inactive TabsContent, so the role would resolve only while the Enrollments tab is open, and the button lives above both tabs.
• Reuse the role the Payments tab already resolves — rejected for the same reason, in mirror image: it is gone whenever Enrollments is the open tab.
• Show the button to everyone and let the 403 explain — rejected: it invites a coach into a refusal for an action they can never perform.

Remove TC-255, TC-258, TC-259 and TC-261 outright, each with a header note in its file recording what they covered and why they went. Keep TC-256/257 (student profile + Customer 360, which still exist), TC-261f (the /api/admin/students paging contract — the route is NOT dead, the groups panel calls it for unassigned students) and TC-261g (Setup → Player Packages, never part of this screen). TC-262 simply stops clicking a tab that no longer exists.

Alternatives considered

• test.skip() them — rejected: a skipped test against a deleted screen is permanent noise that implies the coverage is coming back.
• Rewrite them against the groups list — rejected: they assert roster semantics (recency windows, coach breakdowns, package badges) that the group list does not have; a rewrite would be a new test wearing an old name.
• Delete the whole /api/admin/students route and TC-261f with it — rejected: git grep shows the groups panel depends on it.

(a) ported the identical fixed sibling-sync logic into a new apps/pos/src/lib/split-discount-sync.ts (not shared via packages/common or a cross-app import — apps/pos and apps/terminal each define their own local CartLineItem type; forcing one shared module across that boundary for a six-call-site helper wasn't worth the added generic/import-path complexity this close to shipping, same trade-off as DEC-355/362 already made within a single app). (b) ported payableItems() into apps/pos/src/lib/line-item-pricing.ts and wired it into pendingTotal/pendingItemCount; also added the isBooking/isPrePaid fields (optional) to apps/pos's own CartLineItem interface, since apps/pos never WRITES a booking cart line itself (no check-in flow there) but its ticket-modal.tsx DOES read cart_json rows that apps/terminal wrote, and the interface previously didn't even declare these fields even though the runtime data can carry them. (c) added .eq('orders.status', 'completed') to usePaymentMethodsReport's query, matching useFullReport. (d) hardened computeTicketDiscountCents() with the explicit isNaN/negative guard the two inline copies already had (parseFloat('') is caught by discount.input || '0', but parseFloat of a non-numeric string like 'abc' is NaN and wasn't previously guarded, which could have made the shared function return NaN where the inline versions correctly returned 0) and routed both checkout-dialog.tsx and cart-sidebar.tsx through it, closing the last two copies of this formula.

Alternatives considered

• For (a)/(b), move the shared logic into packages/common now that a second app needs it — considered seriously (the finding itself suggested checking this) — deferred: packages/common has no existing CartLineItem type, and both apps' local types, while structurally similar, aren't guaranteed identical field-for-field forever; introducing a new shared package export this late in a branch Alba wants shipped now is exactly the kind of scope expansion the final-round instruction warned against. Logged as a legitimate follow-up (a real, not urgent, DRY opportunity) rather than done here.
• For (b), also give apps/pos its own booking-check-in flow / full readTicketCart port to fully match apps/terminal's cart handling — rejected as far out of scope: the actual reported bug was narrowly about payableItems() being missing, not apps/pos lacking booking-cart functionality it was never designed to have.

Documented as a deliberate, tracked limitation — not redesigned this round. An inline code comment already existed at the query site; this adds the proper DEC entry so the split is tracked as a known, decided trade-off rather than something a future engineer rediscovers as a mystery. The split is real but narrow: it only matters for orders/payments within a few hours of either edge of a report's date range whose order-creation and payment-capture moments straddle midnight — for the vast majority of orders (payment captured in the same transaction as the order, per create_pos_order_atomic) the two bases agree exactly.

Alternatives considered

• Re-derive order_count/gross_sales/daily_revenue/peak_hours/peak_days from the payment-date-scoped payments set instead of the order-date-scoped orders set — rejected for THIS round: gross_sales/discounts are order-row properties (subtotal_cents/discount_total_cents), not payment properties, so this would require joining back from payments to their orders and being careful not to double-count a split-tender order (multiple payment rows) — a real, bigger redesign of this report's whole data-fetching shape, not a small follow-on fix, and explicitly out of scope for a branch Alba wants shipped now.
• Leave it as only an inline code comment, no DEC entry — rejected: this is exactly the kind of non-trivial, deliberate decision CLAUDE.md requires logging to decisions.ts; an inline comment doesn't survive a refactor of that specific code block the way a DEC entry does.

Checked both real write paths directly: order-detail-modal.tsx's useIssueRefund and the academy-reversal RPC (20260902172043_academy_payment_pos_reversal.sql) BOTH insert a pos_refunds row with status: 'completed' directly, atomically, in the same statement that flips pos_payments.status to 'refunded' — there is no intermediate 'pending' phase anywhere in this codebase's actual refund flow; 'pending' is the column's DEFAULT but no code path ever creates or leaves a row in that state. The schema shape (nullable processed_at alongside the pending default) implies an original intent of 'pending' meaning 'requested but not yet confirmed by a gateway — money hasn't left yet,' which the actual synchronous, always-already-completed write paths never needed. Tightened the SQL side's filter (v_returns and refund_totals) from NOT IN ('failed','cancelled') to = 'completed', matching apps/pos's existing (and, per this investigation, semantically correct) filter — the SQL side was the one that was wrong, not the TS side; no change was needed on the TS side.

Alternatives considered

• Widen the TS side to NOT IN ('failed','cancelled') to match the SQL side instead — rejected once the write paths were actually checked: this would have meant BOTH sides continue to (harmlessly, today, since no 'pending' row is ever created — but incorrectly in principle) count an unsettled refund as already-collected money reduced, the exact semantic error the review flagged as a real possibility worth checking before blindly aligning.
• Leave both sides mismatched since neither can currently produce a different result (no 'pending' row is ever created) — rejected: 'currently produces the same result' isn't the same guarantee as 'is correct' — a future async refund-confirmation flow (the schema's own processed_at column suggests one may have been originally planned) would silently activate the wrong semantics on whichever side wasn't fixed.

Widened the trigger's condition from OLD.status = 'payment_requested' to OLD.status IN ('payment_requested', 'closed'). Verified directly (not assumed) that the only path that ever sets status: 'closed' — useCloseTicket, in both apps — is invoked exclusively as checkout-dialog.tsx's post-order-creation step (both the regular and split-payment paths, confirmed by reading the call sites), and never touches cart_json itself. No 'reopen a closed ticket' mutation exists in either app (confirmed by grep), so unlike 'payment_requested' (which has two legitimate exit transitions: ticket-close-on-settlement and staff cancellation) there's no third legitimate transition to account for on the 'closed' side — 'closed' is a terminal state in this codebase's current design, making it a safe, sufficient proxy for 'this ticket already produced an order' without needing a live EXISTS (SELECT ... FROM pos_orders) check inside the trigger.

Alternatives considered

• Check EXISTS (SELECT 1 FROM pos_orders WHERE ticket_id = OLD.id) instead of trusting status = 'closed' as the proxy — rejected: adds a subquery to every facility_tickets UPDATE (a much higher-traffic table than pos_orders) for a case that's already covered by status alone once confirmed that 'closed' and 'has an order' are equivalent in this codebase's actual usage; would only be necessary if a 'close with no order' flow existed, which direct investigation ruled out.
• Leave 'closed' unlocked and rely on client-side checks in the four newly-identified callers instead — rejected outright: this is the exact whack-a-mole pattern DEC-360 was created specifically to stop; adding four more client-side checks now just delays finding the fifth missed caller later.

(a)+(e) fixed together: extracted the sibling-sync logic into a new apps/terminal/src/lib/split-discount-sync.ts (syncSplitDiscountToSiblings), used by both useSaveTicketCart and generate-payment-link/route.ts, and added .eq('status','open') to its per-sibling UPDATE (not just the initial SELECT) plus a thrown error check on that write — closing the SAME two gaps (write-time race, no error check) in BOTH call sites at once, since useSaveTicketCart's original copy had them too and was never separately flagged. (b) added .eq('status','open') + .select('id').single() to generate-payment-link/route.ts's own ticket update — throws instead of silently no-op-ing if the ticket wasn't actually 'open' when the update ran. (c) isSourceIdConflict now matches the exact, double-quoted constraint name (/"idx_pos_orders_source_id"/) instead of the bare substring, in both the cron and the webhook. (d) restored a cheap early idempotency check in pos-stripe-webhook/index.ts: look up an existing order by source_id FIRST, before touching cart_json at all, and return success immediately if found (also closes the ticket defensively on that path, matching the pre-round-8 behavior).

Alternatives considered

• Rely solely on the new facility_tickets_prevent_locked_cart_mutation trigger (DEC-360) instead of also adding the .eq('status','open') write-time guard for (a) — rejected: the trigger is the authoritative guarantee against actual corruption, but it enforces by RAISING an exception on the narrow, expected race this finding describes, whereas a status-guarded write just silently (and correctly) no-ops — better UX for something that isn't actually an error, without weakening the trigger as the real backstop.
• For (d), keep re-deriving totals on every redelivery and only skip the RPC call itself if an order is found partway through — rejected: cart_json can genuinely change between an order's original successful delivery and a later redelivery (a reopened, re-edited, re-sent ticket), so re-deriving totals from CURRENT cart_json before checking for an existing order risks the new consistency check (round 9) failing a redelivery that should have been a trivial no-op. Checking for the existing order FIRST, before any cart_json read, is the only version of this that's unconditionally safe.

Superseded DEC-341's order-date basis with EVENT-date basis for v_returns (r.created_at), payment_methods' scoped_payments (p.created_at), and fees (p.created_at) — a financial EVENT (a refund, a payment capture) is now attributed to the day it actually happened, not to an ancestor record's (the order's) creation date, matching how a bookkeeper reconciling cash movements for a specific day would want to see it: today's deposits minus today's refunds, regardless of which day's sale a refund traces back to. gross_sales/discounts/net_sales's own numerator/total_collected/avg_order_cents stay on ORDER-date basis deliberately — those are intrinsic properties of the order record itself (subtotal/discount/total set atomically at order creation), not separate events that can happen on a different day, so they carry none of the permanent-invisibility risk that motivated this change for refunds and payments. apps/pos/src/queries/use-reports.ts's useFullReport switched its payments fetch to scope by the payment's own created_at (matching usePaymentMethodsReport's pre-existing convention) instead of deriving payments transitively via order ids already filtered by order date — this also required decoupling the payments fetch from the orders-pagination step entirely (a payment can now belong to an order outside [dateFrom, dateTo]) and adding its own pagination loop, since it's no longer bounded by the same order-id list.

Alternatives considered

• Leave order-date basis for a live dashboard's convenience of being 'eventually correct on re-query,' and treat the one-shot email's blind spot as an accepted, documented limitation — rejected: the whole point of Alba's original report ('X Total Collected vs Y Sales by Category') was that these emails need to be trustworthy AS SENT, not eventually-correct-if-you-happen-to-look-again; an email that permanently omits a real cash outflow is a worse failure mode than the original category-gap bug this branch exists to fix.
• Refund-date basis for v_returns only, leave payment_methods/fees on order-date — rejected: this would reintroduce exactly the kind of silent internal disagreement DEC-358 just closed (v_returns and payment_methods' refund_totals disagreeing about what counts as in-window) by a different route; the SAME event-vs-ancestor-record principle has to apply everywhere it's relevant or the email's own totals stop reconciling with each other again.
• Also switch gross_sales/net_sales/total_collected/avg_order_cents to some event-date basis — rejected: these aren't separate temporal events, they're columns ON the order row itself, set once at order creation and never independently timestamped; there's nothing to reconsider the basis of.

Verified directly, not assumed: NOT every write path shares one function — cart-sidebar.tsx's Save/Charge/Send-to-Kitchen route through useSaveTicketCart, but split-move-modal.tsx's own move/split flows call separate mutations (saveSourceCart, splitItem, splitBill) that write facility_tickets.cart_json independently, and split-item-detail-modal.tsx (DEC-354) writes directly via its own supabase calls. An app-level check in any one shared function would leave the others exposed — confirming the DB is the only place this can be enforced for every current AND future caller. Added facility_tickets_prevent_locked_cart_mutation (20260907071623), a BEFORE UPDATE trigger mirroring pos_orders_prevent_completed_mutation's exact pattern: rejects any cart_json change when OLD.status = 'payment_requested', with no exception needed — the two legitimate transitions OUT of that state (ticket-close on settlement, and useCancelPaymentRequest's revert-to-open) both verified (by reading their actual update payloads) to never touch cart_json themselves, only status/closed_at/payment_link_url/payment_link_id. discount_json (the table's only other jsonb column) confirmed dead — referenced only in generated types, never read or written by any app code — so cart_json is the table's one customer-facing, total-affecting column and the only one that needs locking.

Alternatives considered

• Add the check inside useSaveTicketCart only, since it's the most-used shared mutation — rejected outright once split-move-modal.tsx's separate mutations were found; an app-level fix that provably misses real callers isn't a fix, it's the fourth instance of the same whack-a-mole pattern with extra steps.
• Lock the entire facility_tickets row while payment_requested (mirroring pos_orders' own full-row immutability guard) instead of scoping to cart_json alone — rejected: facility_tickets has legitimate metadata writes (closed_by, note, opened_by corrections) that aren't total-affecting and shouldn't be blocked just because a payment happens to be outstanding; pos_orders' broader guard makes sense there because a COMPLETED order is meant to be fully immutable except two narrow, explicitly-carved-out exceptions, whereas a payment_requested TICKET is still a live, editable-in-other-ways record.

Both of the two options raised in review, not just one: (1) a new backfill migration (20260907041748_backfill_pos_orders_idempotency_key.sql) sets idempotency_key = 'payment_link:' || source_id for every existing pos_orders row where source = 'stripe_payment_link' AND idempotency_key IS NULL — safe to run more than once (only ever touches still-NULL rows), and gives every legacy row the EXACT key the new code will compute for it, so the very first post-deploy redelivery hits the RPC's own ON CONFLICT path directly. (2) Belt-and-suspenders: both the webhook and the cron also catch a unique_violation (code 23505) specifically mentioning idx_pos_orders_source_id/source_id, fall back to looking up the existing order by source_id, self-heal by backfilling that row's idempotency_key on the spot, and return it as an idempotent replay — covering the case where the code deploy somehow races ahead of the migration (this repo's own deploy runbook already sequences 'run migration' before 'deploy functions', but a belt-and-suspenders client-side guard costs little and removes the dependency on getting that order exactly right).

Alternatives considered

• Backfill migration only, no app-side fallback — rejected: cheaper, and matches this repo's documented deploy order (migration before function deploy), but leaves a real failure mode if that order is ever violated (a hotfix redeploy of just the Vercel functions, a migration that's queued but not yet run) with no way to recover except re-running the backfill — the app-side catch is cheap insurance against exactly that.
• App-side catch-and-fallback only, no backfill migration — rejected: correct and self-healing on its own, but means every LEGACY order's first redelivery after deploy takes the slower catch-and-lookup path instead of the RPC's fast, native ON CONFLICT path — the backfill migration makes the common case (a session that's never redelivered again) hit the fast path immediately instead of leaning on the fallback for its entire remaining redelivery window (Stripe retries a webhook for up to 3 days).
• Fix inside create_pos_order_atomic itself (a new CREATE OR REPLACE FUNCTION migration adding a secondary conflict-handling branch for source_id) — rejected for THIS fix, not dismissed outright: architecturally the most correct single source of truth (protects every future caller, not just these two), but retyping this ~600-line SECURITY DEFINER function's full body in a new migration to patch one exception handler is real transcription risk in a production financial RPC, for a benefit (protecting hypothetical future callers) neither of this branch's two actual callers currently needs beyond what the backfill + client-side fallback already cover.

Investigated, did not merge — instead aligned v_returns's WHERE clause to add the SAME p.status IN ('captured','settled','refunded') filter payment_methods' scoped_payments already applies, so the two blocks can no longer silently disagree about what counts as a refund-eligible payment (the actual correctness gap), while leaving them as two separate queries (the performance question). pos_refunds is small and rarely written relative to pos_payments/pos_orders — refunds are a small fraction of orders in any real POS — so this query's real cost is bounded and cheap, unlike the O(payments) correlated-subquery pattern (a per-row LATERAL) that caused the RPC's actual historical 8s timeout. A true merge is achievable (one shared WITH clause populating v_returns via a scalar subquery and v_payment_methods via a second subquery in the same top-level SELECT) but requires restructuring this function's statement order — v_returns is needed before the financial jsonb block runs, ahead of where payment_methods currently computes its own CTEs — real, nontrivial surgery on a production financial-reporting RPC for a performance gain very unlikely to matter at pos_refunds' realistic volume.

Alternatives considered

• Merge into one shared CTE now — rejected for this pass: the restructuring (moving payment_methods' CTE computation earlier, splitting one query's results into two plpgsql variables via multi-target INTO) is real, achievable surgery with genuine risk of a subtle bug in a revenue-reporting function this branch cannot empirically test against the shared local Supabase instance without risking other concurrent work on it — the alignment fix closes the actual correctness gap the review raised at a fraction of the risk.
• Leave the filter mismatch as-is, since a refund can only realistically exist against an already-captured payment in this codebase's actual write paths (order-detail-modal.tsx's useIssueRefund requires a captured/settled/refunded payment to issue against) — rejected: true in every real write path today, but 'the schema doesn't currently enforce it' is not the same guarantee as 'the query filters for it' — aligning the filter costs one line and removes the dependency on that invariant holding forever.

avg_order_cents now subtracts v_returns in its own numerator too, matching apps/pos's useFullReport.avg_order convention (net_sales / order_count) exactly. Separately, apps/pos/src/queries/use-reports.ts's usePaymentMethodsReport and useFullReport both now admit 'refunded' alongside 'captured'/'settled' on pos_payments and net each payment's own refund(s) (via pos_refunds.payment_id, chunked the same way this file already chunks other large id lists) before rolling up by method — the identical DEC-344 fix, applied to the in-app reports it was never ported to.

Alternatives considered

• Leave avg_order_cents on the old numerator since it's 'just an average, not a hard total' — rejected: the whole point of DEC-341 was internal consistency inside one email; a figure that silently uses pre-fix math right next to two that use post-fix math is a worse, harder-to-spot version of the original bug (looks intentional instead of obviously broken).
• Fix apps/pos's reports by pointing them at facility_business_report instead of their own client-side aggregation — rejected as out of scope for this pass: a real architectural question (should the in-app reports and the emailed report share one server-side source of truth?) worth raising separately, not something to fold into a bug-fix-only branch already carrying a large merge.

Extracted buildOrderRpcLineItems/buildOrderRpcItemDiscounts/buildOrderRpcStockTargets into a new apps/terminal/src/lib/order-rpc-payload.ts, used by both use-order-mutations.ts (till checkout) and check-payment-links/route.ts (cron). Order-level discount rows (till-checkout's cashier/resolver split vs. the payment-link paths' single ticket discount) stay inline at each call site — different enough semantics that forcing them through one shared builder would obscure real differences rather than remove duplication. The catalog-items stock-target FETCH also stays at each call site (a trivial .from().select() call against a differently-typed client per caller); only the pure transformation from fetched rows to the RPC's target/delta shape moved into the shared module.

Alternatives considered

• Leave the duplication since 'it's a cron endpoint vs. a mutation hook, different subsystems' — rejected: same reasoning DEC-352 already rejected for the lower-level math — organizational separation isn't a real technical barrier the way the Deno webhook's runtime actually is.
• Extract the ENTIRE stock-target fetch-and-transform (including the .from().select() call) into one generically-typed function accepting either client — rejected: use-order-mutations.ts's browser client and check-payment-links/route.ts's service-role admin client are different generated types; forcing one function signature to accept both cleanly would need either a loose `any`-typed client parameter (a new any this fix would be adding, not removing) or nontrivial generic plumbing for a single six-line query — not worth it for the amount of duplication actually removed.

Fixed both call sites in ticket-modal.tsx (handleSave AND handleRequestPayment) via two new local helpers (getLocalSplitDiscountSource/buildLocalCartJsonWithSplitDiscount) that mirror cart-sidebar.tsx's getSplitDiscountSource/buildCartJsonWithSplitDiscount exactly, now passing sourceTicketNumber/splitDiscountSource through both saveTicketCart.mutateAsync (handleSave) and the new requestPaymentLink.mutateAsync fields (handleRequestPayment). generate-payment-link/route.ts (a server route using the admin client, not the browser client useSaveTicketCart runs on) got its own copy of the sibling-sync loop rather than importing the hook — same 'server route can't call a React Query hook' constraint that already applies to Deno vs. app-local modules elsewhere in this branch.

Alternatives considered

• Fix only generate-payment-link/route.ts, leave handleSave's identical pre-existing gap alone since it predates this branch — rejected: same underlying bug, same file, trivial to fix alongside, and Alba's explicit direction this round is to fix reporting/cart accuracy thoroughly rather than patch only the literally-flagged symptom.
• Route generate-payment-link/route.ts's write through useSaveTicketCart somehow (e.g. by calling the API route from a client context that also fires the mutation) — rejected: the payment-link generation is fundamentally a server-side action (creates the Stripe session, needs the admin client for cross-cutting facility checks); forcing a client-side hook into that path would be a much larger, riskier restructure for the same net effect as duplicating ~25 lines of already-well-understood sync logic.

Added isTicketLocked(status) (true for anything other than 'open') as a guard applied in two layers: (1) an authoritative, fresh re-check immediately before every write — persistOwnTicket now re-selects status alongside cart_json and throws if locked; every sibling-write loop (removeSplitFromSiblings, both handleQty branches, handleRevert) now selects status alongside cart_json and skips (not writes to) any locked sibling, collecting skipped tickets into a toast summary rather than silently dropping the sync; (2) a UI-hint layer — an ownTicketLocked state fetched once when the modal opens disables the qty stepper/revert button up front and shows a lock badge, plus a per-sibling 'Payment sent — locked' badge in the right panel, so staff see WHY a sync didn't happen instead of it looking like nothing was wrong. Locked siblings still count toward newParts/newShareCents in the redistribution math (their own share isn't recomputed, but the remaining split's total-parts denominator is unchanged) — a known, pre-existing approximation of this redistribution math, not something this guard introduces or was asked to redesign.

Alternatives considered

• Hide locked siblings from the split view entirely instead of showing them read-only — rejected: staff still need to SEE that ticket exists in the split (it's still owed money, still part of the group) even though its own share can no longer change; hiding it would look like the split shrank by one ticket instead of one ticket being frozen.
• Exclude locked siblings from newParts/newShareCents when redistributing a removed share — rejected as a redesign, not a guard: doing this correctly requires knowing the locked ticket's already-committed share and subtracting it from originalTotalCents before dividing the remainder among the still-open tickets — a real, separate feature (partial-refund-aware split-payment coordination), not the 'stop silently overwriting a frozen ticket' fix this finding actually asked for.

Redid the fix on top of create_pos_order_atomic rather than ship on a superseded pattern. Merged origin/main into this branch (git merge, not rebase — check-payment-links/route.ts had been independently rewritten on both sides, and replaying 9 commits against a file that diverged via a full rewrite would have been far more error-prone than resolving two merge conflicts once). check-payment-links/route.ts now extends main's existing create_pos_order_atomic call with p_line_items (nested modifiers, kitchen_sent_qty, payableItems-filtered prepaid-booking exclusion, item-level discounts), p_discounts (order-level + per-item, matching the migration's exact per-entry shape), and p_stock_targets (replacing the old hand-rolled stock-decrement loop) — closing the category gap the RPC-only call left open, while keeping the DEC-345/350 fresh-cart_json-fetch-before-use fix (now feeding the RPC payload instead of a separate insert). pos-stripe-webhook/index.ts — untouched by #1063 — was separately migrated to call the SAME RPC with the SAME payment_link:<id> idempotency key format the cron uses, so a webhook-fires-first or cron-fires-first race now converges on one order via the RPC's own idempotency short-circuit instead of two independent non-atomic insert sequences. This closes a duplicate-order vulnerability class in the webhook that predates this branch entirely — discovered while integrating with #1063, not caused by it, and not something #1063 itself introduced or was ever responsible for closing (it never touched this file).

Alternatives considered

• Ship the branch's existing hand-rolled category-gap fix as-is and file the webhook/cron atomic-RPC migration as a separate follow-up PR — rejected: this branch's own fix, if merged first, would immediately need to be re-migrated onto create_pos_order_atomic anyway (main's own use-order-mutations.ts and till-checkout already only speak the atomic-RPC shape), and shipping a brand-new hand-rolled insert sequence in the same week #1063 proved that exact pattern causes prod duplicate-order incidents is not a defensible engineering call just to avoid a bigger merge.
• Rebase this branch's 9 commits onto origin/main instead of merging — rejected: check-payment-links/route.ts was independently rewritten on both sides (this branch's hand-rolled insert sequence vs. main's atomic-RPC call), so a rebase would have replayed the same content conflict on every one of the 9 commits that touched this file instead of once; a single merge commit resolves the same conflict exactly once and preserves this branch's own commit history unmangled.
• Leave pos-stripe-webhook/index.ts on its old pattern for now, since #1063's own scope never included it, and file the webhook migration as separate follow-up work unrelated to this branch's actual bug-fix scope — rejected: this branch was ALREADY rewriting the webhook's order-creation logic (for the category-gap fix), so extending that in-flight rewrite to call the atomic RPC instead of hand-rolling a now-known-unsafe insert sequence is strictly less total work than doing the hand-rolled version now and the atomic-RPC migration later, and leaves zero window where a newly-written insert sequence is live in a still-vulnerable shape.

Extracted payableItems/grossLineTotalCents/computeGrossSubtotal/computeTicketDiscountCents into line-item-pricing.ts as new exports, alongside the existing effectiveUnitPriceCents/effectiveLineTotalCents/lineItemDiscountCents/lineItemDiscountName. Both ticket-modal.tsx and the cron route now import all of it — ticket-modal.tsx's local getLineTotal (an exact duplicate of the module's own effectiveLineTotalCents) and its inline cart_json-parsing-plus-gross-formula in pendingTotal/pendingItemCount (which also re-parsed cart_json inline instead of using the already-imported readTicketCart) were deleted entirely, not left as dead code. The Deno webhook keeps its own hand-port (real constraint, not swept), but the TODO comments on both files now point at a single shared module instead of two independently-evolving Next.js copies.

Alternatives considered

• Leave the third copy in the cron route since it's technically 'in a different subsystem' (a cron endpoint vs. a UI component) — rejected: 'different subsystem' isn't a real technical barrier here (unlike the Deno webhook), just an organizational one, and the same-app import already works cleanly for lineItemDiscountCents/lineItemDiscountName in this exact file.
• Only extract for the cron route, leave ticket-modal.tsx's getLineTotal/inline math as-is to minimize the UI diff — rejected: ticket-modal.tsx's getLineTotal was the EXACT function this whole investigation started from (DEC-347's root cause was ticket-modal.tsx's math not being mirrored elsewhere) — leaving it as a fourth un-deduplicated copy while fixing the other three would have missed the actual point of the finding.

Treat "Send payment link" as an implicit save, at the source: generate-payment-link/route.ts now accepts an optional cartJson in its request body and includes it in the SAME facility_tickets update call that already sets status/payment_link_url/payment_link_id — the identical plain `cart_json` write use-ticket-mutations.ts's useSaveTicketCart already does for an existing ticket, not a new persistence path or a second write. ticket-modal.tsx's handleRequestPayment now sends buildTicketCartJson(localCart, localDiscount) (the same call handleSave uses) alongside the amount. Guarded with Array.isArray(cartJson) so an old/defensive caller that omits it leaves the ticket's last-saved cart_json untouched rather than risk overwriting it with null.

Alternatives considered

• Require the client to call handleSave() before handleRequestPayment() — rejected: adds a second network round-trip + toast ("Ticket saved") the operator didn't ask for, purely to satisfy an internal consistency requirement; also two separate mutations racing is strictly worse than one atomic update carrying both the Stripe session fields and cart_json together.
• Make generate-payment-link/route.ts re-derive amountCents from a fresh cart_json read server-side instead of trusting the client's totalCents — rejected: would require duplicating ticket-modal.tsx's entire localSubtotal/discountCents/localTotal computation server-side (now shared via DEC-352, but still a third call site), and doesn't remove the need to persist cart_json anyway — the report still needs to know what was actually in the cart, not just the total charged.

Both fixed by importing/porting the actual shared formulas, not re-deriving them a third time. (1) Item-level discounts: apps/terminal/src/lib/line-item-pricing.ts's effectiveUnitPriceCents/lineItemDiscountCents/lineItemDiscountName — the same functions use-order-mutations.ts itself imports — are now imported directly in the cron (same app) and hand-ported in the Deno webhook (same duplication pattern as everything else there). pos_order_items.total_cents stays GROSS per line (till-checkout's own convention — item discounts are NOT baked into it), and a new buildDiscountInserts() writes one pos_order_discounts row per discounted item (order_item_id set) plus one order-level row for the ticket-level discount, mirroring use-order-mutations.ts's cashierPortion/resolverPortion + per-item forEach exactly. discount_total_cents is now itemDiscountTotalCents + ticketDiscountCents (till's own totalDiscountCents formula), and the ticket-level discount's own percent base was corrected to itemDiscountedSubtotal (grossSubtotal minus item discounts) rather than raw grossSubtotal — ticket-modal.tsx's localSubtotal (the actual percent base Stripe's charge is computed from) is itself already item-discount-net via getLineTotal(). (2) Prepaid bookings: a new payableItems() filter (`!(li.isBooking && li.isPrePaid)`), applied to the parsed cart items BEFORE computeGrossSubtotal, buildOrderItemInserts, item-discount summation, and stock decrement, mirroring ticket-modal.tsx's `.filter((i) => !(i.isBooking && i.isPrePaid))` verbatim.

Alternatives considered

• Re-derive the item-discount math independently in each of the three call sites (till, cron, webhook) — rejected: this is exactly the drift line-item-pricing.ts's own header comment describes already happening once before (use-order-mutations.ts silently dropped appliedDiscount/splitInfo before that module existed). Importing/porting the one canonical implementation is the whole point of that module existing.
• Bake item-level discounts into pos_order_items.total_cents directly (so line items sum to the discounted total without a separate ledger) — rejected for the same reason as DEC-347's ticket-level equivalent: till-checkout deliberately keeps total_cents gross so every existing reader (refund math, category reports) isn't double-subtracting the discount.
• For prepaid bookings: zero out unitPriceCents on the item itself instead of filtering the array — rejected: unitPriceCents is documented as 'MAY be 0 for prepaid' (not guaranteed) depending on how the line entered cart_json, and ticket-modal.tsx's own explicit filter is the one actually proven to match what Stripe charged — matching that exactly, not a plausible-sounding shortcut, was the point.

Rewritten as two CTEs computed once each, not per-row: scoped_payments filters pos_payments/pos_orders to the report window exactly as before, and refund_totals pre-aggregates pos_refunds by payment_id (joined to scoped_payments so it only scans refunds against payments actually in this window, not the whole table) — then the final SELECT does one hash join between the two pre-aggregated sets. Same O(1)-aggregate-plus-join shape every other block in this function already uses (categories, top_items, payment_methods' own gross sum), instead of the one LATERAL that was the odd one out.

Alternatives considered

• Leave the LATERAL as-is on the theory that idx_pos_refunds_payment_id makes each per-row lookup cheap — rejected: an index lookup per outer row is still O(payments) round trips inside the planner's execution, not O(1) — the exact pattern this RPC's own migration history shows can push it over an 8s statement timeout as pos_payments/pos_refunds grow, and pre-aggregation is a strict improvement with no correctness trade-off (proven by producing identical output — just computed once instead of N times).

Checked, don't guess: read order-detail-modal.tsx's RefundModal in full. Its item-selection refund path (the common one — 'Select items to refund') computes refundAmount from pos_order_items.total_cents (pre-tax) net of item/order-level discounts via effectiveItemPrice/itemTotal, with order_taxes read ONLY for the order-detail display elsewhere in the same file — never folded into the refund calculation. So a typical item-selection refund is actually PRE-tax, not tax-inclusive, and the 'custom amount' fallback is free-text with no enforced basis either way. pos_refunds has no column recording which basis a given row used. Given the data itself doesn't reliably carry a tax-inclusive/exclusive distinction, there is no honest way to carve out a tax-exclusive-only figure for net_sales without guessing per refund row — left as a documented, accepted approximation (SQL comment at the financial jsonb_build_object) rather than inventing an unsupported split.

Alternatives considered

• Assume refunds are always tax-inclusive and compute a tax-exclusive companion figure for net_sales by backing out an assumed tax rate — rejected: would fabricate a number from an assumption the data (and the RefundModal's own math) actively contradicts for the common item-selection path.
• Track a new is_tax_inclusive flag on pos_refunds going forward and use it to split old vs. new correctly — rejected as out of scope here: a schema change plus a RefundModal rewrite belongs with the deeper issue this investigation surfaced (below), not bolted onto a reporting-accuracy fix.

Mirrored till-checkout's approach exactly, not invented: (1) parse cart_json via a readTicketCart port (Deno webhook) / the actual imported readTicketCart (Next.js cron, same app) instead of a raw array cast — this strips the discount_meta pseudo-item out of `items` and returns the discount separately, fixing the insert-crash risk as a side effect. (2) Compute grossSubtotal from the SAME per-line formula buildOrderItemInserts uses (guaranteeing Sum(pos_order_items.total_cents) === pos_orders.subtotal_cents, exactly the invariant till-checkout's own subtotalCents/lineItemInserts pair relies on) and set pos_orders.subtotal_cents to that GROSS figure instead of Stripe's post-discount amountTotal. (3) Compute discountCents with ticket-modal.tsx's own percent/fixed formula against grossSubtotal, clamped to [0, grossSubtotal], and record it as pos_orders.discount_total_cents — total_cents stays amountTotal (the real amount Stripe charged), matching till-checkout's convention that line items stay GROSS/undiscounted while the order carries the discount separately. (4) Also insert one pos_order_discounts row (order_item_id null, type 'fixed') when discountCents > 0, mirroring use-order-mutations.ts's cashierPortion/resolverPortion rows, so the ledger this report doesn't even read stays consistent with every other order type for order-detail display and refund math.

Alternatives considered

• Bake the discount into each line item's total_cents so items sum directly to the discounted total — rejected: till-checkout deliberately does NOT do this ('total_cents stays GROSS — every existing reader ... already assumes total_cents is gross and separately subtracts pos_order_discounts', use-order-mutations.ts's own comment) specifically to avoid double-subtracting the discount wherever it's read alongside the discount ledger. Matching till's actual convention, not a plausible-sounding alternative, was the explicit instruction.
• Record discount_total_cents without also writing a pos_order_discounts ledger row — considered, since this report's own RPC only reads discount_total_cents and would have been fixed either way. Rejected for consistency: every other order type in this codebase that carries an order-level discount also gets a ledger row, and skipping it here would make a payment-link order's discount invisible to order-detail display and to the refund modal's per-item discount attribution (DEC-288) for no reporting benefit.

No clean line-level attribution exists — left as a documented gap, not fixed. pos_refunds has no order_item_id and no line-breakdown column at all: it FKs to exactly one pos_payments row and stores a single amount_cents lump sum. Confirmed further against order-detail-modal.tsx's RefundModal: staff CAN select specific items in the UI, but that selection only computes a suggested lump `amountCents` client-side — the selection itself is never sent to the server or persisted anywhere. There is no data path from a pos_refunds row back to which item(s) it covered. Documented with an explicit SQL comment at both the categories and top_items CTEs in the migration, referencing this entry, so it reads as a deliberate, known gap rather than an oversight.

Alternatives considered

• Add an order_item_id (or a new pos_refund_items join table) so refunds CAN be attributed to specific items — the architecturally correct fix, but a real schema change + a RefundModal rewrite to actually persist the item selection it already computes client-side and throws away. Out of scope for this bug-fix PR; flagged here as the real follow-up rather than attempted piecemeal.
• Approximate by netting the refund proportionally across the order's items (or its top item) — rejected: fabricates a distribution the data doesn't support, and given DEC-342 showed exact attribution IS achievable for payment_methods, shipping a guess here when the honest answer is 'we don't know' would be a worse failure mode than an explicitly labeled gap.

Traced the full path rather than assuming either way: send_ticket_items_to_kitchen never touches pos_order_items — it writes print_jobs directly against the open ticket and records progress back into facility_tickets.cart_json's own kitchenSentQty field (same field this PR's buildOrderItemInserts already reads via `li.kitchenSentQty ?? 0`, mirroring use-order-mutations.ts). No pos_orders/pos_order_items row exists for a payment-link ticket until settlement, so this PR's insert is the ONLY set of pos_order_items rows ever created for it, not a second one. Because kitchenSentQty carries through into the new row's kitchen_sent_qty column, an item already fully sent pre-payment correctly triggers no reprint (kitchen_sent_qty = quantity), while an item never sent before payment finally reaches the kitchen for the first time. Confirmed as a pre-existing gap this PR incidentally closes (kitchen was never notified for unsent payment-link food items before), not a new duplicate-ticket bug — no code change made beyond the explanatory comment left at both kitchen_sent_qty call sites (webhook + cron) so this trace doesn't need re-doing later.

Alternatives considered

• Assume the worst and add defensive de-dup (check for an existing print_jobs/pos_order_items row before inserting) — rejected once the trace showed there is nothing to de-dup against: send_ticket_items_to_kitchen's writes never touch pos_order_items, so there's no prior row that could collide.
• Set kitchen_sent_qty = quantity unconditionally on these inserts (matching the academy-payment bridge's pattern) to guarantee no print ever fires — rejected: unlike an academy package sale (never prepared by a kitchen station), a payment-link order CAN carry real food/bar items that were never sent to kitchen at all if staff forgot or the customer paid before ordering was flagged — suppressing the print unconditionally would silently reintroduce the very 'kitchen never notified' gap this trace found and this PR's default behavior now closes.

Checked the actual status space before changing anything: apps/terminal's transactions page FILTER_STATUSES enumerates the canonical set as captured / settled / refunded / failed (no separate 'voided' or 'cancelled' status exists for pos_payments — those belong to other tables like bookings.payment_status and pos_refunds.status). Added 'refunded' to the filter (now `IN ('captured', 'settled', 'refunded')`) so a refunded payment's row survives into the aggregate and the existing LATERAL can net its refunded_cents against amount_cents as originally intended. Left 'failed' excluded — a failed payment never actually captured money, so including it would count revenue that was never collected.

Alternatives considered

• Add 'refunded' AND 'failed' (admit everything) — rejected: a failed payment has no real amount_cents to net against; including it would inflate gross before the refund logic even applies, a different and unrelated bug.
• Leave the filter as-is and instead join pos_refunds without going through pos_payments' own status — rejected: the payment ROW itself (amount_cents, method) is what payment_methods aggregates on, so excluding the row from the outer query regardless of any inner-join refund logic will always zero it out; the fix has to be in the outer WHERE, not the LATERAL.

Left triplicated, not extracted. supabase/functions/pos-stripe-webhook/index.ts keeps its own hand-written copies (plus a duplicated UUID_RE and a duplicated stock-decrement port of packages/common/src/stock.ts's isTrackedStockCartLine/resolveSaleStockTargets), each commented '// TODO(follow-up)' pointing at its sibling copy in apps/terminal/src/app/api/cron/check-payment-links/route.ts.

Alternatives considered

• Extract buildOrderItemInserts/buildModifierInserts into packages/common/src/stock.ts (or a new module) and have both the cron route and the webhook import it — rejected for the webhook half: this repo's edge functions never import packages/common at all. pos-stripe-webhook already duplicates businessDateForTimezone (from packages/common/src/datetime.ts) and UUID_RE (from packages/common/src/stock.ts) with comments explaining why; send-daily-sales-report duplicates packages/common/src/payment-methods.ts; send-payment-reminder duplicates packages/common/src/merge-tags.ts. Every existing precedent hand-mirrors rather than imports, because Deno's module resolution doesn't consume this monorepo's workspace packages the way the Next.js apps' bundler does. Extracting would dedupe only the cron-route copy against a shared module while the webhook still carries its own mirrored copy regardless — a partial win, not the full fix the finding describes.
• Set up a Deno import map / relative-path import so the edge function CAN pull from packages/common — rejected as out of scope for a bug-fix commit: it would be the first edge function in the repo to do so, is untested against the other ~10 edge functions' bundling, and risks becoming its own investigation rather than a two-line change.

Yes — checked the schema first rather than guessing. pos_refunds.payment_id is a required FK straight to one pos_payments row (not to an order or a generic ledger entry), and pos_payments.method is a single text column per row — confirmed against order-detail-modal.tsx's refund insert (`.from("pos_refunds").insert({ payment_id: paymentId, ... })`), which always names one specific payment. A split-tender order already creates one pos_payments row per tender, so a refund against one tender only ever points at that tender's own payment_id/method — there's no split-tender ambiguity to resolve. Fixed properly: payment_methods now LEFT JOIN LATERALs each payment to the sum of its own non-failed/non-cancelled refunds and subtracts that before aggregating by method, using the same order-created_at window and refund-status filter as v_returns (DEC-341), so the two sections net out consistently. (Note: the outer query's own status filter turned out to also need a fix for this LATERAL to actually take effect — see DEC-344.)

Alternatives considered

• Leave payment_methods gross-only and document it as a known, accepted gap — this was the reviewer's fallback if attribution turned out to be unclean (e.g. split tenders, a refund with no clear single method). Not taken: the schema check showed the attribution IS 1:1 and unambiguous (payment_id is required, not nullable or many-to-many), so shipping a known-wrong number when the correct one was one JOIN away would have been the same category of bug this whole fix exists to close.
• Subtract v_returns as a single lump sum from whichever method has the largest total, or split it proportionally across methods — rejected without serious consideration: both fabricate an attribution the data doesn't actually require guessing at, when the real payment_id linkage already gives the exact method for free.

Order-date basis. v_returns now joins pos_refunds → pos_payments → pos_orders and filters on the ORDER's created_at against the report window (ro.created_at), not the refund's own created_at. Checked for precedent first: apps/pos/src/queries/use-reports.ts's Sales Summary already scopes refunds this way — it fetches refunds by payment_id off a payments list that was already filtered down to orders in the report's date range, never filtering by the refund row's own timestamp. Matches that existing convention rather than introducing a second, different one.

Alternatives considered

• Keep refund-date scoping (cash basis: count money movement in the period it actually happened) but floor net_sales/total_collected at 0 so a mismatched period can't go negative — this was the reviewer's offered fallback if cash-basis turned out to be the codebase's real convention. Not taken once apps/pos's existing report query showed the opposite convention already in use; introducing a second, inconsistent refund-attribution rule across the two POS report surfaces (apps/pos vs. this RPC) would have been its own future reconciliation bug.

Five rulings, all in service of one idea: every cell in this table is a claim about money and must be true or absent, never approximately right. (1) DUE IS THE DEFAULT VIEW. The status dropdown becomes a Due | Paid | All segment, Due selected on open, persisted in the URL (?view=). Chasing money is the daily job; reconciling what already came in is the occasional one. (2) MARK PAID IS ONE TAP, on the row, not buried in the overflow menu — a popover taking tender, amount and an optional note. The overflow keeps the slower actions. (3) 'pending' IS NOT A PAYMENT METHOD. It is the ABSENCE of a recorded tender: DEC-321 maps a payment_link package sale to it, and create_lesson_atomic defaults a roster seat to it. It now renders as an em dash. One METHOD_LABELS map is the vocabulary for the column, the filter and the settle popover, and one server-side settlementMethod() helper is the single place the value is interpreted. A paid payment_request reports the tender from the payments row that settled it rather than its checkout provider, and an unpaid one reports nothing at all. (4) CADENCE IS THE TEMPLATE'S TO DECLARE. lesson_packages.billing_period is what says money recurs and how often; player_packages.next_billing_date is only a date. Without a period the row is One-off and carries no next date. (5) REVERT TO DUE IS APPEND-ONLY. A new payments row with the negative amount, status 'succeeded', pointing at the original via payments.reverses_payment_id, with an operator reason that is mandatory. The original row is never updated and never deleted.

Alternatives considered

• Keep the status dropdown and add Due/Paid as two more options — rejected: the whole ask was fewer clicks between the two states an operator lives in, and a dropdown makes them equals with waived/refunded/cancelled, which they are not.
• Render 'pending' as the word 'Unsettled' in the Method column — rejected: it is still an answer in the wrong column. The row's Status already says whether money arrived; the Method column exists to say HOW, and inventing a value for 'we never captured that' makes the column unreliable everywhere else.
• Change the STATUS instead, so a 'pending'-method sale reads as unpaid — rejected: the club really did record the sale as paid at the counter (player_packages.payment_status is set to 'paid' at point of sale, DEC-321). The status is true; only the tender was never captured. Rewriting the status to fix a display problem would have made the Payments view disagree with the packages list about whether a student owes money.
• Revert by UPDATE-ing the original payments row to status 'refunded' — rejected twice over. It destroys the audit trail (the settlement genuinely happened and someone genuinely undid it — that is two events), and the Collected tile filters status 'refunded' out of its sum, so the reversal would vanish from the arithmetic and the tile would keep reporting money the club had already handed back.
• Give the reversal row status 'refunded' and a positive amount — rejected for the same tile-filter reason. Negative-and-'succeeded' nets out under a plain SUM(amount) with no special-casing, so every existing and future consumer is correct by default rather than by remembering a rule.
• Mark the reversal with a string in `notes` instead of a column — rejected: the POS bridge trigger has to tell a reversal from a fresh sale BEFORE deciding whether to open an order or refund one, and string-matching a free-text field is not a basis for a money decision. The FK also makes a reversal that points at nothing impossible, and the partial unique index makes a double-revert impossible rather than merely unlikely.
• Add a payments.payment_request_id FK so 'which payment settled this request' is a stored fact rather than a nearest-timestamp match — NOT rejected, deferred: it is the right shape and is recorded as a follow-up. It needs an edit to payment-requests/[id]/route.ts and settle-payment-request.ts, both outside this agent's file ownership on a concurrently-edited worktree.
• Let a WhatsApp-only club queue automatic reminders now that the idempotency index carries `channel` — rejected: there is still no automatic WhatsApp transport (DEC-323 ships the manual wa.me lane, the Cloud provider throws, and send-payment-reminder 400s a non-email row), so the rows would sit at 'queued' forever, re-dispatched hourly, while the club believed a reminder was pending. The skip is now REPORTED (reminders_skipped_channels) instead of silent.

billing_mode DEFAULT 'manual', and the migration explicitly stamps every pre-existing lesson_packages row 'manual'. Automatic billing is opt-in per package, chosen by an operator in the package form. The only packages that keep billing themselves on deploy are the ones already carrying a Stripe subscription, which continue down the untouched invoice.paid path.

Alternatives considered

• DEFAULT 'automatic' — rejected: it silently arms a billing scheduler over every historical package row on a live club. A migration must never change what a running business charges people.
• Infer the mode from package_type ('recurring' -> automatic) — rejected: package_type describes what was SOLD, billing_mode describes how it is COLLECTED, and the whole point of the feature is that a recurring package at a cash/QR club is collected manually. Conflating them re-creates the exact overloaded-column problem the bookings.status split had to undo.
• NOT NULL with no default, forcing every row to be set — rejected: a non-additive migration on a live table for no gain.

pg_cron dispatcher -> net.http_post -> Supabase edge function, with the internal secret read from Vault, copied verbatim from dispatch_daily_sales_reports. Two hourly jobs: dispatch-package-billing and dispatch-payment-reminders. Each dispatcher selects only the rows due in the facility's local hour and fires one HTTP call per unit of work with a 10s timeout.

Alternatives considered

• Vercel cron in apps/admin — rejected: apps/admin has no crons key at all today, the scheduling predicate is a SQL query over facility timezones and due dates, and routing it through Next.js adds a deploy-coupled hop for zero benefit. The one Vercel cron in the monorepo (terminal's payment-link reconciler) exists because it talks to Stripe, not to our own rows.
• A single every-minute job doing everything — rejected: the existing house cadence for recipient-style dispatch is hourly with a local-hour predicate, and a minute cadence multiplies wasted wakeups by 60 for work that is due on a date.
• Supabase pg_net direct from a trigger on payment_requests — rejected: reminders are scheduled for a future offset, not fired at write time; a queue drained on a clock is the correct shape.

Billing cycles become a Setpoint-side scheduler with three lanes. Automatic-with-card stays exactly as it is (Stripe subscription, invoice.paid -> reset_package_sessions, no regression). Automatic-without-card rolls the cycle on next_billing_date, creates a payment_request for the period and schedules its reminders, and grants the new period's sessions ONLY when that request is marked paid. Manual never bills on its own: the package surfaces under 'Renewals due' in the Payments view and an operator's click creates the request. billing_period is widened additively to weekly/monthly/quarterly/annual, and rollover is computed in the facility's timezone with month-end anchor clamping.

Alternatives considered

• Require Stripe for recurring packages — rejected: it excludes every club we actually run today, and the Thai market collects at the counter. A billing feature that only works for card-on-file clubs is not a billing feature.
• Grant the sessions on schedule and chase the money afterwards — rejected: that is unsecured credit issued by a cron job. The club's exposure grows silently with every unpaid cycle.
• Model manual billing as a recurring reminder with no payment_request — rejected: without a durable request there is nothing to mark paid, nothing to age into 'overdue', and no way to reconcile a cycle that was collected in cash.
• Reuse membership billing (user_memberships/membership_plans) for academy packages — rejected: different lifecycle (session banks and expiry vs continuous entitlement) and the webhook already treats them as separate subjects; merging them would overload both.

A message_templates table keyed by (facility_id, key, channel), where facility_id NULL is the seeded system default and a facility row overrides it. Resolution is facility-then-default, so a club that never opens the editor still sends correct copy. applyMergeTags is extracted from the CRM campaign send route into packages/common so exactly one merge-tag implementation exists, and merge-tag VALUES are HTML-escaped on the email path.

Alternatives considered

• Resend-hosted templates — rejected: Resend has no public templates CRUD API, which is precisely why apps/admin/src/app/api/admin/crm/templates/route.ts is already a placeholder returning domains. Building on it would strand the feature.
• Keep template literals in the edge function and expose a few toggles (the report_subscriptions.sections model) — rejected: Nestor asked for manageable templates, meaning editable copy, not visibility switches.
• Reuse crm_campaigns as the template store — rejected: campaigns are one-shot broadcast sends to a segment with their own send/analytics lifecycle; a transactional template is a long-lived named resource resolved per message. Same words, different object.
• A second copy of applyMergeTags for reminders — rejected outright: two merge-tag parsers drift, and one of them will be the one that forgets to escape.

Ship the manual lane now and stub the automated one, both behind a MessagingProvider interface that mirrors the existing payments provider abstraction. The manual lane renders the template server-side and returns a wa.me deep link carrying the message and the payment link; the operator clicks and WhatsApp opens pre-filled, and the reminder is recorded with status 'sent_manual'. The whatsapp_cloud provider throws a clear not-configured error until credentials exist. Enabling automated sending later is a facility setting plus one provider file.

Alternatives considered

• Meta WhatsApp Cloud API now — deferred, not rejected: it needs Business verification, a dedicated sending number that cannot already be on a personal WhatsApp account, and Meta-approved template messages, because free-form sending is blocked outside a 24-hour customer-initiated window. That is a business decision with a lead time, and blocking the whole feature on it would have stalled the Payments view, the ledger and the billing cycles too.
• Twilio as the WhatsApp gateway — rejected for now: per-message cost on top of the identical Meta template-approval requirement, so it buys convenience rather than removing the gating constraint.
• Email only, drop WhatsApp — rejected: it is where these customers actually read messages, and silently narrowing the stated scope is not ours to do.
• A tel:/SMS fallback — rejected: no SMS provider exists either, and it would be a third unbuilt channel rather than a shortcut.

A first-class payment_requests table (facility, user, subject_type/subject_id, amount, currency, status, provider, checkout_id/url/expiry, due_date, created_by, paid_at). The hosted link is generated lazily through the existing resolvePaymentProvider(facility_id) abstraction at send time, and regenerated if it has expired, so the operator never pastes a link by hand. Provider webhooks settle the request by checkout_id, idempotently.

Alternatives considered

• Reuse facility_tickets (which already carries payment_link_url/payment_link_id) — rejected: tickets are a POS counter concept owned by another part of the team, scoped to an open till session, with no due date and no notion of a subject like a package renewal.
• Generate the link at reminder-send time and never store it — rejected: nothing would be left to mark paid, age into overdue, or reconcile a cash collection against, and a customer re-opening yesterday's message would need a link that still resolves.
• Create a Stripe object up front for every upcoming cycle — rejected: it breaks entirely when payment_provider IS NULL (the state of every facility right now), it litters the provider with objects for cycles that may be cancelled, and hosted sessions expire.
• Store the request inside player_packages as more columns — rejected: one package has many requests over its life, and lessons and memberships need the same object.

Yes, and the root cause gets fixed rather than papered over: payments.type is widened additively with 'package', and the assignment route writes a payments row for in_club, payment_link and credits sales with the method mapped honestly (cash / pending / credits). Complimentary and zero-price sales write no payments row, because no money moved.

Alternatives considered

• Build the Payments view by unioning player_packages directly and leave payments alone — rejected: it hides the real defect (academy cash revenue is absent from the money table), and every future report would have to re-implement the same union or silently under-count.
• Backfill historical package sales into payments — rejected for this feature: the historical rows have no trustworthy paid_at or method beyond 'someone marked it paid', and inventing payment records is worse than a documented gap. The view reads player_packages for history and payments going forward.
• Add a new type value per sale channel — rejected: channel is payment_method's job; 'package' is the subject, matching how booking/lesson/membership already work.

Inside the existing plpgsql RPCs (consume_package_session, refund_package_session, reset_package_sessions) and a new adjust_package_sessions RPC, in the same transaction as the counter mutation. The one exception is purchase_grant: session buckets are created by plain INSERTs from at least three places (the POST route, assign_package_with_credits, the Stripe webhook), so those rows are written by an AFTER INSERT trigger on player_package_sessions. The rejected trigger alternative below is an AFTER UPDATE trigger on counter changes; an INSERT trigger carries no ambiguity about cause, since a newly created bucket can only be a grant. A failure to write the ledger row aborts the balance change. The admin PATCH route stops writing player_package_sessions directly and calls the RPC, so the reason the UI already collects is finally persisted along with actor_id.

Alternatives considered

• An AFTER UPDATE trigger on player_package_sessions — rejected: a trigger sees a delta but not its cause. It cannot know whether -1 was a booking, an admin correction or a renewal reset, nor which lesson caused it, and reason plus lesson_id are the entire point of the log.
• Write the ledger from the API routes after calling the RPC — rejected: consumption already happens in four different call sites plus inside create_lesson_atomic, so the ledger would be silently incomplete the first time someone adds a fifth, and a failure between the two writes leaves the counters and the ledger disagreeing.
• Emit an or_events row and derive the log from the outbox — rejected: or_events is the OpenRally webhook outbox with its own retention and delivery semantics; an internal financial audit trail should not be a side effect of an integration channel.

A new append-only package_session_transactions table: one row per balance change, carrying delta, balance_after, reason (purchase_grant / consume / refund / admin_adjust / backfill_balance / renewal_reset / expiry_forfeit / cancellation_forfeit), lesson_id, class_id, actor_id, note and source (live / backfill). No UPDATE or DELETE path exists in application code. Existing packages are backfilled from surviving lesson links with source='backfill', and the ledger's running sum must reconcile to sessions_remaining for every package.

Alternatives considered

• Add updated_at to player_package_sessions — rejected: it records only the most recent change and loses every intermediate event, which is the whole log.
• Derive the history from lessons.player_package_id and lesson_players.player_package_id — rejected, and this is the sharpest finding of the audit: refund_package_session NULLs lessons.player_package_id, so cancelling a package-funded lesson erases the evidence it ever consumed a session. The derivation is provably lossy.
• Keep counters as the source of truth and show a computed view — rejected for a third reason: reset_package_sessions sets sessions_used back to 0 on every recurring renewal, so a renewing student's entire prior period vanishes.
• Reuse pos_activity_logs — rejected: it is a POS-owned, app-written, deliberately best-effort audit stream whose writer swallows errors on purpose. A session balance is an entitlement customers pay for; its ledger must be transactional.

Yes, as a stacked follow-up on PR #1028. group_report_subscriptions rows (name, facility_ids[], one recipient each, frequencies, send hour anchored to an explicit IANA timezone since the group spans Bangkok/Bali) + dispatch_group_reports() hourly cron + send-group-report edge function + an owner-only card in Settings → Reports. The email is fixed-format and compact by design (Pablo's call — no per-recipient section toggles): group hero with totals PER CURRENCY (THB and IDR are never converted or summed together — honesty over a fake single number), the club comparison table (collected/occupancy/played/no-show/new customers per club with deltas), a 5-line mini-scorecard per club (vs previous period AND vs last-week-same-day for daily / vs last year otherwise), and the group's on-the-books outlook. Computation is pure reuse: facility_business_report once per club over the SAME calendar period — zero new analytics SQL. Access is the strictest gate yet: create/see/edit requires the OWNER role at EVERY club in the group, enforced three times (RLS policy over unnest(facility_ids), requireOwnerOfAll in every API route — including the union of old+new club sets on edit, so an owner of A+B can't re-point a subscription at clubs they don't own — and the UI card self-hides for anyone owning <2 clubs).

Alternatives considered

• Full 10-section report per club concatenated into one email — rejected by Pablo explicitly ('que no sea tan extenso'): 2 clubs × 10 sections is unreadable, and each club's own report already exists for depth.
• FX-convert everything to THB for a single group total — rejected: any conversion rate baked into a report is an editorial claim the PMS has no business making; per-currency totals are honest and still comparable over time.
• An organizations/accounts table as the grouping primitive — rejected for now: Setpoint has no org layer and inventing one for a report is scope inversion; facility_ids[] on the subscription + owner-of-all access expresses exactly today's need, and an org layer can absorb it later.
• Per-recipient section toggles like the per-club report — rejected for v1: fewer knobs, fixed compact format; the group audience is three account owners with the same needs.

Access: a two-tier explicit allowlist (report_access table). The facility OWNER always has full access and is the only one who can edit the list; allowlisted emails get 'view' (settings + previews) or 'manage' (also recipients). RLS floor is owner-only on both report tables; every API re-checks via requireReportAccess; the sidebar nav entry is hidden for anyone off the list (the APIs enforce regardless). Report v2 grew from 7 to 10 per-recipient sections: a three-period scorecard (every key metric: same period last year / previous period / now, with vs-period and vs-year ▲/▼ chips, red/green inverted for no-shows and cancellations), POS deep-dive (per-category trend chips, sales by area/till via pos_locations, top-15 sellers — widened from 5 on Pablo's follow-up), bookings behaviour (lead-time buckets + averages), academy fill rate (enrolled vs classes.max_pax — the 'event fill %' ask mapped to the data that actually exists; the parked Events feature has no tables) plus coach ratings (lesson_players.coach_rating), customers & loyalty (repeat-player %, all-time visit-frequency histogram), top customers (most frequent + most guests brought, names masked to 'First L.' in the email per Pablo's choice), and looking-ahead (next period already on the books with same-lead-point pace comparison, large groups and regulars coming). Weather + Thai-holidays context was explicitly deferred to v3 by Pablo. All delivered into the same open PR #1028 (his call: one review of the complete feature).

Alternatives considered

• Keep the v1 owner+admin gate — rejected by Pablo directly: admins of the PMS are a wider circle than the people who should see full club financials.
• Per-facility jsonb settings key for the allowlist instead of a table — rejected: no RLS surface of its own, no clean unique constraint per email, and mixing an access-control list into a general settings blob is exactly how it stops being auditable.
• Show full customer names in the email — offered, Pablo chose 'First L.' masking: the email leaves the system (forwarding), and his own reference report masks guest contact details for the same reason.
• Compute YoY only when a full year of data exists — rejected: the RPC always returns the last-year period and the template renders honest zeros/dashes; PTP's migrated booking history makes bookings-side YoY real today even though POS-side YoY only becomes meaningful in 2027.
• Weather/holiday context via Open-Meteo now — deferred to v3 by Pablo (zero external dependencies in v2).

New, separate report (send-business-report edge function + facility_business_report RPC + report_subscriptions table + Admin Settings → Reports UI) rather than evolving the POS one. The POS daily email is left running untouched: this feature originally shipped a companion migration unscheduling its cron, dropped before merge once PR #1037 (Item Sales section, same week) showed the POS team is still actively investing in that email — retiring a report someone else is building is a product decision for its owners, not a side effect of shipping ours. Per-recipient rows carry frequencies (daily/weekly/monthly, combinable), a jsonb map of section toggles (financial/categories/payments/occupancy/bookings/academy/customers), a send hour, and an enabled flag; an hourly pg_cron dispatcher fires per distinct (facility, frequency, hour) and the function re-filters recipients itself. Money sections (financial/categories/payments) come EXCLUSIVELY from pos_orders/pos_payments — court fees and lessons settled at the till are already inside those totals — while bookings.booked_value_cents and academy.coaching_paid_cents are labelled operational values and never added to collected totals, which is what prevents double-counting. The email HTML has a single owner (functions/_shared/business-report-html.ts); the Admin preview/test-send proxies the edge function (which accepts the service-role key as a machine caller alongside the existing x-internal-secret) instead of duplicating the template in Next.js.

Alternatives considered

• Evolve send-daily-sales-report/pos_report_settings in place — rejected: POS is owned by a different part of the team (CLAUDE.md ownership rule), pos_report_settings is one-settings-row-per-facility (can't express per-recipient frequency/sections without a breaking reshape), and the club report is a PMS-level product surface.
• Sum bookings.price_amount + lesson paid amounts into the collected totals for a 'complete' revenue number — rejected: bookings checked in at the POS flow through facility_tickets into pos_orders (DEC-307 territory), so adding both sides double-counts exactly the busiest clubs' court revenue. Reconciling collected-vs-booked across systems is real future work, filed as a follow-up, not silently faked in v1.
• Configure reports from the POS back-office (where the old report's settings UI lives) — rejected per Pablo's explicit call: the config belongs in the PMS Admin (Settings → Reports), and the report reads POS data; POS app code is untouched.
• localStorage-style same-content-for-everyone recipient list (the old model) — rejected: the entire point of the feature is per-recipient shaping ('quitar o poner algún parámetro depende de para quién').

Merge Coaches, Classes and Packages into a single new route /{facility}/academy/setup, sidebar 8 -> 6: Overview · Lessons · Planning · Students · Reports · Setup, in that order. Setup is a TABBED page (Coaches · Classes · Packages · Academy, Coaches default), NOT a stacked one-pager — Nestor rejected the one-page layout explicitly. Above the tabs sit three clickable summary cards (Coaches / Classes / Packages) whose counts come from the SAME list endpoints the tabs below already call, fetched in one parallel wave; no summary API route was added. Each tab renders the EXISTING component unchanged: CoachesList, ClassesList, and the packages page's own catalogue/player-packages sub-tabs verbatim. A fourth Academy tab shows name/description/focus-areas/facilities as a read view whose Edit button opens the EXISTING AcademySettingsDialog — no new form. /academy/coaches, /academy/classes and /academy/packages remain live URLs and 307-redirect to /academy/setup?tab=<x>; /academy/coaches/[id] (coach detail) is untouched. The three thin *-page-client.tsx wrappers those routes used were deleted rather than left orphaned: the setup page resolves academy id, facility id and court count ONCE and passes them down, so the merge REMOVES three duplicate /api/admin/academies bootstrap calls instead of adding any. The name 'Setup' is provisional — chosen from five candidates Nestor reviewed in the mockup.

Alternatives considered

• One-page stacked layout (all four sections on a single scrolling page, no tabs) — REJECTED BY NESTOR directly. It was the mockup's first shape. Four full data tables stacked vertically turns every visit into a scroll hunt, and the reused list components each own a toolbar, a search box and an empty state that only read correctly as the top of their own pane.
• Leave the three as separate sidebar pages and merely reorder them — REJECTED. It preserves the actual complaint: rarely-touched configuration outranks daily work purely because it is a separate entity in the schema.
• Move player packages under Students in the same PR (the mockup shows it there) — DEFERRED deliberately, at Nestor's instruction. Player packages stay as the second sub-tab inside the Packages tab for now. That leaves a temporary 'Packages' tab nested inside a 'Packages' tab, which is mildly redundant and resolves itself when the move happens.
• Alternative names for the merged tab, all shown to Nestor in the mockup: Configuration (accurate but cold, and collides with the existing Settings section), Curriculum (only fits Classes, not Coaches or Packages), Blueprint (evocative but not operator vocabulary), Foundations (same problem). 'Setup' won on being operator-plain; its known risk is sounding one-time when it is in fact revisited.
• next.config redirects instead of page-level redirect() — REJECTED. Config redirects default to permanent 308s that browsers cache indefinitely, which would make restoring a standalone coaches page require cache-busting on a live product. A page-level redirect() is a 307 and keeps the forwarding visible in the route folder where someone looking for the old page will actually look.

Middleware signs a minimal `{ id, exp }` claim for the user it just verified and forwards it to the handler on an internal request header (`x-setpoint-internal-identity` + `x-setpoint-internal-identity-sig`), HMAC-SHA256 with a 60s expiry, domain-separated by the label `setpoint/admin/internal-identity/v1.` and keyed on SUPABASE_SERVICE_ROLE_KEY (already required server-side, never exposed to the browser, so no new production env var and therefore no window where it is unset). Three properties make it safe. (1) The signature covers METHOD + PATHNAME as well as the claim, and the verifier recomputes it from the request it is actually serving — so a signed header is valid only for the exact request it was minted for and can never be replayed onto another route or verb. (2) Middleware strips every inbound `x-setpoint-internal-*` header on every request it sees, including the paths it deliberately does not authenticate (/auth, /api/v1, the external-auth webhook and lesson routes). (3) The matcher lists `/api/:path*` unconditionally, because the pre-existing image-extension carve-out is extension-based rather than directory-based and therefore also exempted any API URL a caller suffixed with one (`/api/admin/lessons/<id>.png` still resolved to the real dynamic route while skipping middleware entirely — no 401 gate and no header strip). getSessionUser() checks Bearer first (unchanged), then the signed header, then falls back to the original cookie/getUser() path. Failure is always 'slow', never 'open': missing secret, WebCrypto fault, bad signature, tampered claim, wrong route, or expired claim all return null and the handler re-authenticates exactly as before — nothing in the module throws, on either the signing or the verifying side. The claim carries ONLY the user id (~150 bytes): every /api/admin consumer reads user.id and nothing else, so getSessionUser returns a `SessionUser` (id guaranteed, everything else optional) rather than fabricating placeholder fields to satisfy the full Supabase `User` shape. Measured result: 2 GoTrue round trips per admin API call become 1. SCOPE OF THAT WIN, precisely: it applies to routes that authenticate through lib/auth.ts (requireFacilityAccess / requireSessionUser / withFacilityAccess), which is the large majority. It does NOT apply to 18 route files (21 call sites) that call supabase.auth.getUser() directly and never touch lib/auth.ts — crm/campaigns/*, crm/customers/[id]/notes+tags, crm/segments, crm/tags, crm/templates, crm/email-settings, bookings, facilities, facilities/my, facility-contacts. Those still pay the duplicate hop and are a target of the follow-up PR alongside the facility-lookup merge.

Alternatives considered

• Plain unsigned header (`x-setpoint-user-id`) relying only on the inbound-strip + 'middleware always runs' — REJECTED, and this was the closest call. It is the cheapest option and it is what a naive reading of the Next.js docs' `NextResponse.next({ request: { headers } })` pattern suggests. It fails on the second assumption: CVE-2025-29927 (Next.js, March 2025) was precisely a middleware bypass via a crafted `x-middleware-subrequest` header, and a matcher typo or a future route-group/runtime change reproduces the same hole quietly. Under any bypass, a bare identity header is full account takeover for any user id an attacker can name — and admin API responses hand out staff/coach `user_id`s freely (GET /api/admin/coaches returns them), so the ids are not secret. The signature costs ~50us of CPU to remove a ~70ms network hop; refusing that trade to save 40 lines is not a defensible risk posture for a live multi-tenant admin panel handling real money.
• Verify the Supabase JWT locally instead (supabase.auth.getClaims() with cached JWKS) so middleware itself makes zero network calls — REJECTED although it is the only path to a literal '1 round trip total'. getUser() hits the auth server, which means a revoked/signed-out session stops working immediately; local claim verification trusts the token until it expires (up to an hour). That is a real weakening of revocation, the brief explicitly said 'without weakening security', and tc-044-auth asserts sign-out behaviour that this would break. Worth revisiting only as its own decision with Alba, not smuggled in as a perf change.
• Migrate the 116 routes to the existing withFacilityAccess() wrapper, which already threads the user through and avoids the second getUser() — REJECTED as the mechanism for THIS change: it fixes the same problem 116 files at a time with 116 opportunities to get a resolver wrong, and leaves any new route written the old way paying the tax again. The header approach fixes it once, in shared plumbing, for every route including future ones. withFacilityAccess remains the right wrapper for routes that need auth-aware row resolution; it now simply gets a cheaper getSessionUser underneath it.
• A dedicated new secret (e.g. ADMIN_INTERNAL_AUTH_SECRET) instead of deriving from the service role key — REJECTED for this change: it introduces a deploy ordering hazard where production runs with the variable unset and every request silently takes the slow path, which is exactly the failure this PR exists to remove. Domain separation is achieved with the signing label instead. Revisit if the key ever needs to rotate independently.
• Cache the verified user per-request in-process (React cache / AsyncLocalStorage) rather than crossing the middleware->handler boundary — REJECTED: middleware and route handlers do not share a request context in Next.js, which is the whole reason the second getUser() exists.

Rewrote both booking_players policies as a correlated EXISTS keyed on `b.id = booking_players.booking_id` (bookings_pkey, indexed) instead of the unbound IN-subquery. The SELECT policy's EXISTS body is deliberately bare — `EXISTS (SELECT 1 FROM bookings b WHERE b.id = booking_players.booking_id)`, no copied status/own/role predicate — a first draft hand-copied bookings' own SELECT predicate into it, but /code-review caught that this duplicates logic that drifts silently if bookings' own policies ever change; a bare EXISTS against a single primary-key-matched row already transitively evaluates bookings' OWN RLS at the exact same indexed cost (confirmed via EXPLAIN: ~1.1ms either way), so it inherits 'readable via its parent booking' automatically instead of maintaining a second copy of the rule. The ALL (manage) policy keeps its own explicit owner/admin/manager check — that's a genuinely distinct, independent business rule (who may WRITE, not who may read), not a copy of bookings' read policy, so no drift risk there. Verified via EXPLAIN ANALYZE in a transaction against prod that was rolled back before ever touching real data: the identical 10-booking_id lookup dropped from 2554ms to ~1.1ms (~2000x) — now an indexed nested-loop instead of two full sequential scans. Applied via the standard new-migration approved deploy path after local verification (E2E: tc-271, which exercises booking_players through the terminal's own split-by-player-count flow and directly re-loads the Bookings tab that was reportedly broken, passed cleanly end-to-end, both before and after the bare-EXISTS simplification).

Alternatives considered

• Add an index to make the existing IN-subquery pattern faster — rejected: the subquery has no facility/user boundary to index against in the first place (it selects ALL of bookings.id, full stop); an index can't bound a query that doesn't filter on anything indexable. The correlated-EXISTS rewrite is what makes the lookup indexable at all, via the existing primary key.
• Hand-copy bookings' own SELECT predicate (status/own/role) into booking_players' EXISTS body — this WAS the first version of this fix, caught by /code-review: it duplicates a rule that already lives on bookings itself, at identical performance cost to just referencing it, so the only effect of copying it is a second copy that can silently drift the next time bookings' own policies change (e.g. a new role added to one but not the other).
• Cap/paginate booking_players lookups more aggressively instead of fixing the RLS — rejected: the query cost here doesn't scale with the number of booking_ids being looked up (that part was already small, e.g. 10-44 ids) — it scales with the TOTAL size of `bookings` across the whole platform, which pagination on this side of the query does nothing to reduce.
• Leave it and let this be 'the Bookings tab is just slow for busy facilities' — rejected: it isn't slow, it's now a hard failure (timeout) for any facility with enough total booking history, growing worse every day as more rows accumulate — not something that degrades gracefully.

Root-cause fix: a new SECURITY DEFINER RPC, `mark_bookings_paid(p_booking_ids uuid[])`, scoped to exactly the status='completed' + payment_status='paid' transition, checking each booking's OWN facility_id via user_facility_role() against ['owner','admin','manager','staff','cashier'] — narrower than widening the bookings UPDATE policy itself, which would let staff/cashier edit any column on any booking (time, court, price) via a direct REST call. checkout-dialog.tsx's markBookingsCompletePaid helper now calls this RPC instead of a raw update. The cron fallback got a raw equivalent write instead (admin/service-role client already bypasses RLS, so the RPC's role check would be redundant there), added after it closes a ticket, parsing bookingIds out of the ticket's cart_json the same way checkout-dialog.tsx does; its failure path returns a `bookingSyncFailures` array in the cron's JSON response rather than only console.error()-ing, since a cron has no operator to toast. TC-278's E2E coverage was also switched from an owner-role seed account to a staff-role one — an owner-role test could never have caught the RLS gap in the first place, since owner was never blocked by the policy. A SECOND /code-review pass (after this fix's first version routed apps/pos's useUpdateBookingStatus 'Mark completed' through the same RPC) caught two more issues: that action has no payment context at all — it sits next to 'No show'/'Cancel' on a confirmed booking with no ticket or charge involved — so forcing payment_status='paid' there would have silently mislabeled genuinely-unpaid completions as paid; apps/pos's fix was reverted to a plain status-only update, left as its own separate product decision (does POS 'Mark completed' ever mean paid?) rather than assumed here. The same review pass also caught that the untouched sibling branch of that same function was writing `bookings.updated_at`, a column that doesn't exist on the table at all (confirmed against the CREATE TABLE) — pre-existing, but in the exact function this PR touched, so removed.

Alternatives considered

• Widen the existing bookings UPDATE RLS policy to include staff/cashier — rejected: RLS USING clauses gate rows, not columns, so this would let a staff/cashier account edit ANY field on ANY booking at their facility (reschedule, change court, change price) via a direct REST call, a much bigger permission increase than 'let the till mark its own just-charged tickets paid'.
• Leave the raw .update() and just fix the silent-failure toast to fire more reliably — rejected: a louder failure isn't a fix; staff/cashier operators (who run the till) would still be permanently unable to sync payment_status, they'd just get told so every time.
• Skip the apps/pos and cron fallback fixes, ship only the terminal charge-flow fix — rejected per the standing rule that a bug found in one Setpoint surface (admin/pos-admin/pos-terminal) must be checked against the other two before considering the fix done; the cron fallback was a confirmed live instance of the identical root bug (never touched bookings at all), not speculative.
• Route apps/pos's generic 'Mark completed' through mark_bookings_paid too, matching the terminal and cron fixes exactly — this WAS the first version of this fix, reverted after /code-review: that action has no ticket, no charge, no payment signal of any kind behind it, so blanket-marking payment_status='paid' would fix nothing (nothing was broken there in the reported-bug sense) while introducing a new, silent financial-correctness bug for every non-payment completion.

Extended DialogDescription itself (dialog.tsx) with an opt-in `visible?: boolean` prop, defaulting to false (sr-only, unchanged for the ~25 existing call sites using it for genuine taglines). When a dialog's description IS real, data-carrying content — a confirmation code, an account identifier, a live operation's status — `<DialogDescription visible>` renders that SAME node as normal visible text instead of sr-only, staying wired to aria-describedby with no duplicate node and no double screen-reader announcement. Fixed at 7 call sites: booking-detail-dialog.tsx (the reported bug), edit-api-key-dialog.tsx, delete-customer-dialog.tsx, merge-customer-dialog.tsx, add-credits-dialog.tsx, team-member-dialog.tsx, and lesson-roster-panel.tsx (consolidated its existing two-node workaround down to one). match-detail-dialog.tsx has the identical bug but was deliberately left UNFIXED and reverted mid-PR: CLAUDE.md marks the Matches feature 'PARKED — do not modify without an explicit go-ahead,' and touching it here would have been an undiscussed drive-by edit to parked code, caught by /code-review. NOT YET FIXED, logged as follow-up (not blocking this PR, per explicit direction to close this out): a further /code-review pass found at least 3 more live instances outside this PR's original scope — player-packages-list.tsx's 'Cancel Package' dialog (destructive action; the highest-priority of the three, since it hides which player/package/forfeited-session-count is about to be cancelled), enroll-user-dialog.tsx, and group-detail-client.tsx. Also NOT fixed: `sheet.tsx`'s SheetDescription has the same structural pattern with no equivalent opt-in; no lint/type-level enforcement exists to catch a future dialog shipping real data sr-only again (the alternatives below explain why `visible` stayed opt-in despite this gap).

Alternatives considered

• Patch each call site independently (render a second, visible <p> alongside the still-sr-only Description, duplicating the same text) — this was the FIRST version of this fix, and lesson-roster-panel.tsx had already independently arrived at the same workaround before this PR touched it. Rejected after /code-review: causes screen readers to announce the same text twice (once via aria-describedby on open, again as a sighted user reads through the visible duplicate), and leaves no single place to change how a 'visible description' should look/behave — the next dialog needing this would paste the pattern a 9th time instead of reusing anything.
• Make `visible` required with no default, forcing every existing DialogDescription call site to explicitly opt in or out — rejected: would touch ~25 files that are correctly using the sr-only default today for genuine taglines, for a marginal safety gain. The failure mode of the CURRENT opt-in default (something that should be visible silently stays hidden) is the same class of bug this PR fixes but not a NEW one introduced by keeping it opt-in — whereas flipping the default outright (visible-by-default, sr-only opt-in) would risk the opposite, worse failure mode: a future dialog's genuinely decorative tagline unintentionally rendering as visible clutter across the whole app on day one.
• Stop using DialogDescription's sr-only convention at all, make every description visible by default — rejected: the original convention exists for a real reason (compact sticky dialog headers across ~25 dialogs where a visible tagline would add clutter for no informational gain); the bug was specific data ending up in the wrong place, not the convention itself being wrong.

Resolved the removal-semantics ambiguity by asking directly: removing the court from the ticket does NOT cancel the actual booking — the reservation stays confirmed and the court slot stays reserved, it only detaches the fee from this cart (useful if it was added to the wrong ticket and needs to be re-added to the right one). Redesigned the tap flow: the booking card now opens the same CartItemModal every other cart item uses (item info, auto/engine discounts, then actions) instead of jumping straight into SplitBillModal — CartItemModal already had partial isBooking-awareness (a bare Remove button, discount section explicitly excluded) suggesting this was the intended long-term shape. Extended it: the manual discount section is now offered for booking items too (same setItemDiscount()/splitLineItemWithDiscount() logic every other item already uses — no new discount mechanism). The actions row gained a proper isBooking branch: Split cost (opens SplitBillModal, pre-selected via DEC-301's initialSelectedItemId) + Remove, and Remove now requires a second confirm tap (with inline copy stating the booking stays confirmed) before removeFromCart() actually fires — mirroring the existing Cancel/confirm shape already used elsewhere in the app rather than inventing a new confirmation pattern. Also removed the now-redundant 'Split cost' toggle button inside SplitBillModal's by-items panel for booking items specifically — with Move hidden (DEC-299), it was a button that's always the only, already-active option and does nothing when tapped, which was exactly the 'two confirm buttons' confusion Alba flagged; only the explanatory hint text remains, and the real confirm action is the existing 'Apply N assignment' button.

Alternatives considered

• Build a new lightweight action-sheet component specifically for the booking card (Split / Discount / Remove as three menu rows) instead of extending CartItemModal — rejected: CartItemModal already has 80% of this (header, price, engine discounts, a Remove button) and was visibly built with an isBooking case in mind (the `!liveItem.isBooking && ...` guards throughout implied a future where it WOULD apply); finishing that existing partial support is less new surface area than a parallel component, and keeps one place staff learn for 'tap any cart item' instead of two different interaction patterns depending on item type.
• Cancel the actual booking on removal (the other option offered) — not chosen; Alba's call, and the safer default besides: cancelling immediately releases the court slot and would need to also decide whether that triggers OpenRally/TPS cancellation propagation for a bookable-via-protocol facility, which 'just detach it from this ticket' avoids needing to reason about at all.
• Leave the SplitBillModal 'Split cost' toggle button in place even though it's now inert for booking items — rejected: a button that looks interactive, is already visually 'pressed', and does nothing when tapped is worse than no button, especially right next to a second, real confirm action ('Apply N assignment') doing the actual work — exactly the confusion reported.

Fixed the price display to match checkout-dialog.tsx: only isPrePaid hides the price behind 'Paid'; every other case (including the normal unpaid cash/pay-at-club state) shows the real formatted price. Made the card tappable when unpaid (a settled booking has nothing left to split, so it stays inert) — tapping it opens SplitBillModal directly in 'by-items' mode, the SAME modal and safety logic (resolveItemAction forcing split-only, hidden Move button, DEC-299's hint) the Charge flow already uses, rather than routing through CartItemModal + SplitMoveModal (the OTHER split/move path reached from a regular item's card, which has zero isBooking awareness and would have needed the same booking-safety logic duplicated a second time).

Alternatives considered

• Route the booking card through CartItemModal (like regular items) and teach SplitMoveModal about isBooking too — rejected: CartItemModal already explicitly excludes isBooking from its Split/Move buttons (`!liveItem.isBooking && ...`), so extending it means adding booking-item logic to a SECOND modal (SplitMoveModal, 563 lines, no existing isBooking references at all) that would need to independently reimplement the exact 'never Move a booking item' safety rule DEC-299 just spent four /code-review rounds hardening in SplitBillModal — the two would immediately be able to drift out of sync the same way the price-display logic already had between checkout-dialog.tsx and cart-sidebar.tsx.
• Build a lightweight, booking-specific quick-split popover directly on the card — rejected: more new surface area to get right and test from scratch, when the fully-vetted (TC-272), already-safety-hardened SplitBillModal does exactly what's needed and is one prop (`initialMode="by-items"`) away from opening in the right state.

A page-size cap (50 bookings) via a real useInfiniteQuery, plus a 'Load more' button. usePmsBookings(range, pageSize) pages with a keyset cursor on (start_time, id) — .or("start_time.gt.<cursor>,and(start_time.eq.<cursor>,id.gt.<cursorId>)") rather than OFFSET/LIMIT, so a booking inserted (or one that changes status) between fetches can't shift a later page's boundary and cause a duplicate or skipped row; getNextPageParam returns the last row's (start_time, id) or undefined once a page comes back short. Each 'Load more' click fetches and enriches only the NEW page, never re-fetching or re-enriching pages already loaded. Switching dayFilter/customRange changes the query key (different from/to), so the page automatically starts fresh at page 1 with no manual reset needed. Search/status/type filters auto-load the rest of the window (so a real match on a not-yet-loaded page isn't silently missed) but capped at 10 pages (500 bookings) — past that, search only covers what's loaded and the operator pages in more deliberately, with the status-count badges showing a '+' suffix whenever more of the window is still unloaded so a partial count is never presented as the true total.

Alternatives considered

• Growing a single `limit` argument and re-fetching from offset 0 each 'Load more' click (the first implementation) — rejected after /code-review: every click re-fetched and re-enriched ALL previously-loaded rows again, not just the new page, which doesn't actually fix the cost problem for an operator who pages in several times on a busy facility — just moves the unbounded-growth failure mode one click later instead of eliminating it.
• OFFSET/LIMIT pagination via .range(offset, offset+pageSize-1) (the second implementation) — rejected after a FOURTH /code-review pass: on the exact 'busy facility, operator actively viewing today/tomorrow' scenario this fix targets, a booking inserted between two page fetches (or one whose status enters/leaves the [confirmed, completed, no_show] filter) shifts every row after it by one, so a later page's offset can re-show an already-seen booking (duplicate React key) or silently skip one. The (start_time, id) keyset cursor above is immune to this — it identifies 'the row after the last one I saw', not 'the Nth row', so insertions/deletions elsewhere in the ordering don't move it.
• Uncapped auto-load-on-filter (the first implementation of the search fix) — rejected after a second /code-review pass: it silently reintroduced the exact unbounded-fetch/timeout failure this decision exists to close, for the specific 'wide custom range on a busy facility' scenario the original report described, the moment an operator typed one character into search on such a range. The 10-page cap keeps search useful for the common case while never regressing to the original bug under a large range.
• Virtualized infinite scroll (auto-load on scroll-to-bottom) — rejected for now: more moving parts (IntersectionObserver, scroll-container plumbing inside the existing ScrollArea) for a marginal UX gain over an explicit button on a touch/iPad-first surface where a tap is already the primary interaction; can layer on top of the same infinite-query hook later without changing its shape.
• Cap custom-range span instead of paginating (e.g. reject/clamp ranges over 31 days) — rejected: doesn't fix the report as asked, and a single day can itself exceed the page size at a large multi-court facility; the fetch needs to bound itself regardless of how the range was produced.
• Server-side search (push the search term into the SQL query instead of filtering loaded rows client-side) — the architecturally cleanest long-term fix, since it would never need to load unmatched rows at all. Deferred: today's search matches guestName (resolved via a separate customers-table lookup, not a bookings column), court name (a joined table), guest_email, and confirmation_code — replicating that as one robust server-side predicate is a real sub-project, not a same-day addition, and risked introducing new bugs under the time pressure of this live bug report. The capped auto-load closes the immediate correctness gap (a real match not silently hidden) without that risk; server-side search remains the right follow-up.
• Keep the pre-existing refetchInterval: 30_000 unchanged after switching to useInfiniteQuery — rejected after a THIRD /code-review pass, verified directly against the installed @tanstack/query-core source: any infinite-query refetch without an explicit fetch-more direction (interval, window-focus, invalidateQueries, remount) re-fetches AND re-enriches every currently-loaded page, not just the newest. A perpetual 30s timer would silently repeat that full-page-set cost forever while the tab stays open — the same unbounded-fetch failure this decision exists to close, just recurring automatically instead of on a click, and invisible to TC-273/273b since they only exercise fetchNextPage. Removed refetchInterval entirely; staleTime (30s) plus the existing mutation-driven invalidateQueries(["pms-bookings"]) calls (check-in, ticket actions) still keep the list current, and those are event-bounded — they only pay the multi-page-refetch cost when a booking actually changed, not on a blind clock tick.

Restrict the UI: a booking line item (isBooking) can only be split, never moved. curAction resolves to "split" unconditionally for a booking item (ignoring any stored itemAction), the 'Move to ticket' button isn't rendered for one, and a short hint explains why ('A booking fee can only be split, not moved — it stays on this ticket'). Added a defense-in-depth guard in handleAssignItems too — moveEntries filters out any item.isBooking, in case stale itemAction state ever slips through some other path.

Alternatives considered

• Allow Move but also move facility_tickets.booking_id to the destination ticket — rejected: a ticket's booking_id is 1:1 with the ticket that represents that booking's tab; reassigning it on an item-level cart action conflates two different concepts (which ticket owns this line item vs. which ticket IS this booking's official record) and would ripple into check-in status, payment-status sync, and reporting that all key off booking_id today.
• Allow Move but warn with a confirmation dialog — rejected: the underlying data shape is still wrong afterward (the booking's own ticket shows zero court fee), a confirmation only makes the mistake harder to make by accident, not correct when made on purpose.
• Leave Move available but hide the booking item from the by-items list entirely, evenly-split only — rejected: this was the exact prior complaint ("we want to be able to click on it as if it is an item") — the fix scopes what's safe to do TO the item, not whether the item is selectable at all.

Root-cause fix in protocol/server: payment_method only flips to 'external' when external_ref is present AND method_type is NOT 'pay_at_venue' — matches the meaning DEC-160's own follow-up migration (20260727025048) already committed to in writing: "'external' keeps its current meaning — an OpenRally consumer collected the money and reported it back." A pay_at_venue booking stays 'pending', which is what it actually is. Admin's booking-detail-dialog override-warning gate, payment-method label, and external-ref display were all switched to call a single exported isExternallySettled(paymentMethod, externalPaymentMethodType) (packages/common/src/check-in.ts) instead of each re-deriving its own condition — the same function derivePricing() already calls internally for check-in pricing, computed once per render as isSettledExternally. /code-review caught that the first pass of this fix used a LOOSER admin-side check (paymentMethod==='external' && type!=='pay_at_venue', i.e. treating credit/other as settled) that disagreed with derivePricing()'s pre-existing, narrower EXTERNAL_SETTLED_TYPES=['prepaid','comp'] (which treats credit/other as unpaid) — a booking could have shown 'already paid' in admin while still being charged at check-in. Sharing one function closes that gap by construction: credit/other now consistently read as NOT settled everywhere (label says 'Pay at club', no override warning, still charged at check-in) until someone confirms their real settlement semantics and updates the one shared list. Already-mistagged rows in production display and behave correctly the moment admin deploys — no data backfill required to resolve the immediate report, though one (payment_method='external' AND external_payment_method_type='pay_at_venue' → 'pending') is still worth running for reporting cleanliness.

Alternatives considered

• Patch only the admin UI condition, leave protocol/server as-is — rejected: every future pay_at_venue booking from any OpenRally consumer keeps getting mistagged; the UI patch would need to be re-applied at every other current or future call site that reads payment_method (reports, exports, the payment-method label directly under the price) instead of being true everywhere the column is read.
• Give admin its own, separately-tuned settlement check instead of sharing derivePricing()'s — rejected after /code-review flagged the resulting drift: two independently-maintained definitions of the same concept ('is this booking settled') are exactly how this class of bug happens, and a future edit to one without the other silently reopens the same inconsistency this PR closes.
• Also change 'other' and 'credit' to count as settled everywhere — rejected: 'pay_at_venue' has an unambiguous, spec-defined meaning (money not yet collected) and a test (payment_block.rs) whose own comment already stated the correct intent, making it a confirmed, provable bug. 'credit'/'other' have no equivalent test or documented settlement semantics in this codebase; changing their behavior here would be a guess, not a fix — they now consistently fall on the safe (not-yet-settled) side everywhere via the shared function, rather than settled in one place and unpaid in another.

Fixed all of them in this PR rather than filing follow-ups. Two were financial-correctness bugs matching the exact bug class this PR exists to eliminate (Request-Payment could generate a link for the wrong amount; ticket-restore could silently re-charge an already-settled booking) — shipping the feature while leaving known instances of its own bug alive would defeat the point of the fix. Also exported derivePricing() from check-in.ts so terminal-store.ts calls the one real implementation instead of a second hand-rolled copy, closing off the class of bug rather than just this occurrence.

Alternatives considered

• Ship the 4-file scope as planned, file the other 3 as follow-up tickets — rejected: 2 of the 3 are financial-correctness bugs in the exact class this PR was written to close; shipping known re-occurrences of the bug undermines the fix.
• Patch each site with its own local isBooking && isPrePaid check instead of sharing derivePricing() — rejected: this is exactly how the fix got split across 7 files in the first place (each surface re-deriving the same predicate); sharing one function is the actual fix for the fragmentation, not just this bug instance.

Ships as a pre-fill helper on the EXISTING split-bill flow ('Split for this booking's N players' banner, shown only when the ticket's booking has ≥2 booking_players) — not a new standalone feature. It pre-creates and pre-selects tickets from booking_players, reusing checkInPlayer's own resolveCustomerId/findOrCreateProfile pattern for profile resolution, then hands off to the exact same manual-confirm split action every other split already uses. Only the initial selection state is new; 100% of the actual split mutation path (useSplitBillToTickets, bulkApplySplitToBill) is shared, untouched code.

Alternatives considered

• New dedicated 'Split by booking' screen/action — rejected: doubles the split UI surface for a feature that's really just smarter default selection; per this repo's principle 2 (reuse a protocol/pattern, don't reinvent), the existing split-bill flow already does everything needed once the right tickets are selected.

Kept the Court Booking card's distinct visual treatment (icon, badge, separate section above the regular item list) — only the price/badge logic changed (isPrePaid → 'Paid' badge; every other state → the real formatted price, never the booking ref/dash).

Alternatives considered

• Fold the booking line item into the regular items list once it's a real charge — rejected: Alba's ask was that the fee be discountable and splittable, not that it visually stop being a court booking; losing the distinct court/time context (which court, which slot) from the checkout screen is a regression for a cashier reconciling the ticket against the schedule.

Formula corrected to `isPrePaid ? 0 : price` for the two court flows (checkInBooking, checkInPlayer) — matching the pattern checkInLessonStudent already used correctly (only isPrePaid zeros the price; DEC-147–149 govern its own per-student payment_method logic). checkInLessonStudent itself is left untouched — its pricing already worked correctly, and its per-student payment_method shape isn't a generalization target for this PR (verified via existing E2E coverage, tc-113/tc-114, still passing after this branch's changes).

Alternatives considered

• Generalize checkInLessonStudent onto the same derivePricing() call while in the file anyway — rejected: no bug exists there to fix, it has a genuinely different data shape (per-student payment_method, not a single booking-level payment_status), and touching working, tested code outside the PR's actual scope is exactly the kind of unscoped change this repo's workflow tries to avoid.

derivePricing() reads bookings.payment_status as the primary settled/unsettled signal (isPrePaid when paymentStatus === 'paid'), with payment_method (stripe/credits/package) and payment_method='external' + external_payment_method_type ('prepaid'|'comp') as secondary always-settled cases. No new column, no migration — payment_status and external_payment_method_type already exist and are already written by the admin UI and the OpenRally write path; the bug was purely that check-in ignored them.

Alternatives considered

• Add a new tps_paid or paid_externally boolean column — rejected: payment_status + the existing Mark-as-Paid override already model this correctly end-to-end (including the external-override-warning panel); a parallel column would either duplicate the same fact or, worse, be able to disagree with it.

Refuse. PATCH /api/admin/bookings now returns 409 with the lesson_id and a pointer to PATCH /api/admin/lessons/[id] when a reschedule field (court_id, start_time, end_time, duration_minutes) targets a booking that is a lesson leg. Cancel and no_show keep their existing cascades — those are state transitions the lesson route already models identically. Separately, the lesson dialog's slot grid stopped labelling every unavailable time 'outside coach hours': a time inside the coach's own windows that the coach-scoped endpoint still refuses is now labelled 'coach not free', so the grid no longer contradicts the 'Coach available 11:00 AM–12:00 PM' banner directly above it.

Alternatives considered

• Cascade the move from the booking side (update lessons + every sibling leg in the same request) — rejected: the lesson route already owns num_courts validation, per-court conflict checks, the coach-reservation gate and the override toggle. A second implementation of that ruleset on the bookings route is precisely the drift that produced these 17 rows; two writers of one invariant is the bug, not the missing cascade.
• A DB-level constraint or trigger keeping bookings and lessons in lockstep — rejected for now, not on merit: the lesson route legitimately writes the two sides in sequence, so the invariant holds between statements but not within a transaction step, and a naive trigger would reject the legitimate path. Worth revisiting as a deferred constraint once the write paths are consolidated.
• Leave the API open and rely on the UI guard from #946 (which already routes lesson bookings to the lesson form) — rejected: the guard is one client of a public-shaped admin route, and every desynced row predates it. An invariant enforced only by the screen that happens to call the route is not enforced.
• Let the availability endpoints fall back to the booking when the two disagree — rejected: it hides a data-integrity fault behind a heuristic, and picks a winner silently in the one place nobody is watching.

A partial unique index on (booking_id, provider) where provider IS NOT NULL and fulfilment_status is one of pending/scheduled/recording/ready. Both callers are made to fail gracefully into it rather than each carrying its own copy of the rule: createAddOns skips a camera the booking already has and the route answers 409, and or_create_booking_add_on raises a named add_on_already_on_booking that the protocol maps to 409 with a sentence. 'failed' and 'cancelled' are outside the index on purpose — a camera that refused is holding nothing, so a second attempt must stay possible. 'ready' is inside it: the device is free but the recording was sold, and selling it twice for one session is the double charge this exists to stop.

Alternatives considered

• Check in createAddOns only — rejected: it is the caller the protocol does not go through, so a consumer could still double-sell. The bug is exactly that there is now more than one caller.
• Check in both callers and skip the index — rejected for the reason DEC-305 gave: a rule kept in callers is a rule the next caller forgets, and this one is worth real money each time it is forgotten.
• Key the index on facility_add_on_id — rejected: consumer-sold rows carry facility_add_on_id = NULL by design (they name and price what they sold), so the two sides would never collide, which is the only collision that matters.
• Include 'failed' in the index so a booking gets one recording attempt ever — rejected: a device_offline on the first try would permanently deny a customer a recording they are willing to pay for, and the operator's Try again button would silently stop working.

Match the RPC, not the surrounding convention. The new lessons query filters on coach_id + status <> 'cancelled' + half-open overlap and nothing else — no court filter, no facility filter — which is byte-for-byte the guard `hold_lesson_slot` runs before it looks at courts. The invariant being bought is one-directional: a slot this endpoint calls 'available' must never be one the RPC rejects. Any predicate NARROWER than the RPC's re-opens the exact class of bug being fixed, just in a rarer case. The pass is also deliberately expiry-blind for the same reason (the RPC ignores hold expiry, so an abandoned checkout keeps the hour blocked on every reserved court until the cleanup cron sweeps, ~1 min) — the handler carries a load-bearing comment saying that window must only ever be narrowed on BOTH sides together. Slot status became the max of the two passes (available < held < booked) rather than last-write-wins, so the passes are order-independent and an in-flight lesson hold reports 'held' on parallel courts, matching what the court pass reports on the lesson's own.

Alternatives considered

• Scope the lesson lookup to the facility, matching every other query in the handler — rejected: a coach whose academy serves two facilities would still be advertised as free at facility A while teaching at facility B, and the RPC (which is coach-global) would still 409 them. Same bug, narrower blast radius, and harder to find the second time. A coach is a person; being busy is a property of the person, not of the facility asking.
• Scope the lesson lookup to the slot's court, matching the existing bookings pass — rejected: this IS the bug. A lesson occupies the coach, not a court; court-scoping is what let the parallel slots survive.
• Skip lessons whose linked bookings have all expired, so an abandoned checkout frees the hour immediately instead of waiting for the cron — rejected during code review: the RPC would still reject the hold on that lesson, so availability would lead the RPC and re-create the disagreement in the other direction. Correct fix if the ~1-min window ever matters is to change both sides at once.
• Solve it consumer-side by having TPS cross-check the coach's own bookings before showing a slot — rejected: pushes protocol-level correctness onto every consumer and violates consumer-agnostic; the protocol must not publish a slot it will refuse to sell.

Extracted the effective-price formula (getLineItemTotal's exact logic) into line-item-pricing.ts in each app so display and any future persistence math share one implementation. pos_order_items.total_cents and unit_price_cents are UNCHANGED — still gross, pre-item-discount — because every existing reader already assumes that. Only two things changed: pos_orders.discount_total_cents now includes the sum of item-level discounts alongside the existing order-level (cashier/resolver) discount, and pos_order_discounts (schema already had order_item_id, never populated) gets one row per discounted line, attributed via order_item_id. total_cents = subtotal - discount_total_cents was already correct once discount_total_cents was fixed. A second /code-review pass caught a further consequence: apps/terminal's RefundModal computed a single order-wide discountFactor = (subtotal - discountCents) / subtotal applied uniformly to every item's gross total — correct when discountCents was order-level-only, but wrong now that it can include item-specific amounts (an order with one discounted and one undiscounted item would over-refund one and under-refund the other). Fixed by having RefundModal read pos_order_discounts directly: item-tagged rows subtract from that specific item first, then the remaining (untagged, order-level) discount spreads proportionally across what's left — item-specific discounts apply exactly, order-level discounts still spread as before.

Alternatives considered

• Make pos_order_items.total_cents net-of-item-discount (the first shipped version, before /code-review caught it) — rejected: silently redefines a field several consumers already read as gross, without auditing them. Confirmed to break RefundModal's discountFactor math (double-discounts a refund), Gross Sales / category-sales reports (understate revenue by the discount amount with no metric rename), and both apps' order-detail-modal Subtotal display (double-subtracts the same discount once via the now-net line total and again via the newly-inserted pos_order_discounts row). Exact same trap DEC-286 hit once already for tax attribution — total_cents' meaning is load-bearing in more places than the write path that produces it.
• Skip persisting to pos_order_discounts, only fix discount_total_cents — rejected: leaves the Discounts report blind to item-level discounts the same way it was blind to order-level ones before the original pos_order_discounts fix; the column (order_item_id) was already built for exactly this and had never been written to.

A trigger on bookings (AFTER UPDATE, status → 'cancelled') marks every live add-on on that booking 'cancelled' and leaves external_ref in place, which is exactly what releaseCancelledRecordings() looks for. Rows in 'ready' are untouched: the session happened and the customer has the video. The provider is NOT called from the trigger — that is an HTTP call and has no place in a user's transaction — and bookings.price_amount is not rewritten, because a cancelled booking's total is history. Automatic release is then scoped to origin='setpoint': whoever booked the device releases it, and a consumer-booked recording is released by the consumer's own cancel path. A consumer-owned row still holding a device is surfaced on the booking with an explicit 'Release camera' action rather than quietly cleaned up by us.

Alternatives considered

• Call cancelRecordings() from the protocol handler — rejected: that is the second caller to remember, not the last. Cancels arrive from the admin route, the protocol, expiry sweeps and whatever ships next; the bug was that the rule lived in a caller instead of on the data.
• Have the trigger call the provider directly — rejected: a third-party HTTP call inside the transaction that cancels a booking, where a slow camera would hold locks and a dead one would fail the cancel.
• Release every cancelled row regardless of origin — rejected: two systems reaching for one device is what every other guard in this feature exists to prevent, and a cancel is the worst moment to guess what the other side is mid-way through.
• Wrap the trigger body in an EXCEPTION handler like the outbound-sync triggers — rejected here: those enqueue to an external queue and must never fail a user's write. This is a plain UPDATE on rows keyed to the booking being cancelled, and the half-done state it would hide (booking gone, camera still booked) is the exact thing this fixes.

Additive protocol surface at 0.5.0: GET /facilities/{id}/add-ons (catalogue + available_resources, so a consumer never offers a camera on a court without one), GET/POST /bookings/{id}/add-ons, DELETE /bookings/{id}/add-ons/{id}, add_ons[] on the single-booking read, and four events — booking_addon_added | cancelled | ready | failed — emitted from a trigger into or_events so the existing fan-out and delivery worker carry them with no new endpoint. Adding and cancelling go through two Setpoint functions (or_create_booking_add_on / or_cancel_booking_add_on) because the protocol server is a stateless translator that never authors booking rows. The provider is NEVER called inside a consumer request: the row lands as status='pending' and the admin reconcile cron books the device, releases devices for cancelled rows (which keep external_ref precisely so it can), and polls results. Scheduling ownership is 'the PMS that owns the courts owns the recording' — for Setpoint facilities that is Setpoint, and the consumer mirrors for display only.

Alternatives considered

• Carry add_ons[] in the booking_created payload — rejected: add-ons are written after the booking row, so the trigger would fire before they exist; a dedicated per-add-on event is race-free.
• Have the protocol server call the camera provider directly — rejected: it would put a third-party HTTP call inside a consumer's request path, and would mean two services holding provider credentials.
• Let both sides schedule and de-duplicate at the provider — rejected: the provider's own answer to a double booking is FAILED_DEVICE_OCCUPIED, which has already happened 55 times in the consumer app's history; one owner per device is the only safe rule.
• A new webhook endpoint family for add-ons — rejected: every add-on event is about a booking the consumer already mirrors, so it rides the booking webhook and provisioning stays one row.

Two tables: facility_add_ons (catalogue an operator edits) and booking_add_ons (what is actually on a booking, with name/price/currency/time snapshotted). The add-on price is added to bookings.price_amount so every existing money path — checkout, payments, reports — keeps working with no changes, while the breakdown lives on the add-on row. A Setpoint booking is one court over one time range, so one add-on row per booking is one recording; a multi-court booking is sibling bookings and each sibling gets its own independently. Devices are booked AFTER the booking is written and never inside its success path: a provider that is down leaves fulfilment_status='failed' with a readable failure_reason on a booking that still exists. Cancelling a booking releases the device; editing its time, court or duration cancels and re-books it. Removing one add-on cancels just that recording and subtracts its price.

Alternatives considered

• Mirror the consumer app exactly — attach only after the booking exists, all-or-nothing across courts, no reschedule — rejected: it can't satisfy the request (add at creation), it fails a whole 2-court booking when one court lacks a camera, and its missing reschedule means the camera records the original slot after a booking moves.
• Keep add-on money out of bookings.price_amount and sum it at every read site — rejected: every report, checkout and payment path would have to learn about add-ons, for a number that is already part of what the customer pays.
• Schedule the device inside the booking-create transaction — rejected: a third-party outage would fail the booking itself, which is exactly backwards; the court reservation is the thing that must not be lost.
• One add-on row per slot like the consumer app — rejected here: Setpoint bookings are not sliced into slots, so a row per booking already is a row per recording.

New `facility_integrations` (facility_id, provider, base_url, auth_username, auth_secret_name, config, is_active; unique per facility+provider), owner/admin-only including SELECT. The password is NOT a column: `set_facility_integration_secret` writes it to Vault and the row keeps only the secret's name; `get_facility_integration_secret` reads it back. Both are SECURITY DEFINER and service-role-only, with the calling admin route enforcing facility access; an AFTER DELETE trigger drops the Vault secret with the row. Resolution order is facility row (active, with username + secret) -> env fallback -> ProviderNotConfiguredError, so the club running today keeps working with no data entry. Provider adapters became per-connection factories with the login-token cache keyed by account, so two facilities can never share a token. Settings → Integrations gains a Recording Provider card with a write-only password field and a Test connection button.

Alternatives considered

• Copy the consumer app's shape — one global row per provider (`third_party_integrations` with `config.auth`), with per-club use inferred by joining the club's add-on to it — rejected: that is exactly the model that cannot express two clubs with two accounts (its service reads the single row with .single()), and it stores the password in plain jsonb.
• Follow the repo's own webhook_subscriptions precedent and keep a plaintext `secret` column — rejected: a table dump or one over-broad SELECT hands over a working provider login; Vault is already enabled and used here for internal_function_secret.
• Per-facility env vars / one Vercel env var per club — rejected: not something a club operator can self-serve, and it does not scale past a handful of facilities.
• Encrypt in application code with a key from env — rejected: reinvents Vault, and the key ends up in the same env we were trying to move away from.

v1 is read-only and provider-direct: Setpoint stores only the court→device mapping (`court_cameras`, owner/admin write, staff read) and an admin-side service (`apps/admin/src/lib/cameras`, one adapter per provider) calls the camera API itself on page view. Status is never stored — `GET /api/admin/facilities/[facilityId]/camera-status` fetches live, in parallel, 5s timeout per device, behind a 60s per-facility in-process cache with `?refresh=1` to bypass. Statuses normalise to available | unavailable | unknown, where unknown ('we could not ask') is deliberately distinct from unavailable ('the camera answered and is down'). Nothing is written back to the consumer, no pricing/catalogue/selling moves, and the consumer's camera pipeline is untouched.

Alternatives considered

• Read status back from the consumer app instead of the provider — rejected: its hourly cron only posts to Slack and persists nothing, so there is no source to read; making it persist would add a schema + deploy on that side just to relay data Setpoint can fetch itself.
• Store status in Setpoint and refresh on a cron — rejected for v1: any stored value is stale by definition and would need its own invalidation story; the page-view read is simpler and always current.
• Move the whole add-on (catalogue, pricing, scheduling, selling) into Setpoint now — deferred: much larger change, and it depends on an open product decision about whether the club still sells camera recordings at all.
• Let the courts page call the provider from the browser — rejected: provider credentials must stay server-side.

Hybrid list-price in calculate_member_price (signature unchanged). If the booking interval has no internal window boundaries from matching rules, keep DEC-273 exact duration match. If it spans 2+ windows, split at those boundaries and price each segment as ROUND(overlap_minutes/60 × winning 60-min row price) with the same court/sport/dow/priority cascade per segment start. Partial hours (e.g. 10:00–11:30 → 800+250=1050) are included. Fail-closed to 0 if any segment has no 60-min rule. Member hard override when spanning sums prorated 60-min member amounts only when every segment has member_price_amount; otherwise resolve_discounts runs on the summed list total. One RPC fix covers admin, web, OpenRally, and TPS.

Alternatives considered

• Always sum from 60-min rows even inside one window — rejected: breaks DEC-273 fixed mode (120 ≠ 2×60).
• Fix only in TPS/UI — rejected: admin Price Preview and OpenRally share the same RPC; single source of truth must move.
• Materialize every cross-window (duration, start) combination at write time — rejected: combinatorial explosion across abutting windows.

Unify all three apps to OTP-only, invite-only login (shouldCreateUser: false), porting Admin's exact two-step email→code flow into both apps' own visual design (not a wholesale copy — each app already has its own login page styling and its own createClient() singleton wrapper, both preserved). Self-serve register pages and forgot-password pages in both apps are closed (redirect to /login), mirroring how Admin's auth/signup was gutted. Includes Terminal, per Alba's explicit call — full consistency won over the shared-device friction concern.

Alternatives considered

• Keep Terminal on password auth given it's shared hardware with multiple logins per shift (considered and explicitly rejected by Alba in favor of full consistency — flagged as a real trade-off before deciding, not silently assumed)
• Leave POS/Terminal as-is since they predate the Admin migration and 'it's always been this way' (rejected — this is drift, not a considered design; POS's register page in particular self-serve-creates a whole new facility with hardcoded UTC/USD defaults from the open internet, which is a real gap once Admin is already invite-only)

Admin's /auth/login was rewritten to a two-step OTP flow (signInWithOtp with shouldCreateUser: false, then verifyOtp) and /auth/signup was gutted to redirect to /auth/login — no more self-serve admin account creation. Existing users' encrypted_password was left untouched (not cleared), since Supabase Auth supports password and OTP as independent, simultaneous grant types per user — this was a UI-level cutover, not a backend migration.

Alternatives considered

• (Not recorded at the time this decision was made — reconstructed from the code/commit only. See DEC-056 for the alternatives considered when password auth was originally chosen; this entry only captures that the reversal happened and why it was safe, not the original debate for switching to OTP.)

Guest bookings deliberately create ZERO customer/CRM footprint — user_id stays null, the typed label goes straight into bookings.guest_first_name, and the players[]/resolveOrCreatePlayerAccount path is never touched. This is a genuinely separate, explicit toggle in create-booking-dialog.tsx (guestBookingMode), not inferred from "player with no email," specifically so it can never be confused with (or accidentally regress) the walk-in-account pathway find-or-create-user.ts protects. Implemented with zero backend or schema changes — bookings.user_id was already nullable, guest_first_name/guest_last_name already existed and were already handled correctly end-to-end (calendar rendering, search, RLS; supabase/migrations/20260520100304_add_identity_to_booking_created_payload.sql's own comment — 'If both are null (anonymous walk-in) the field is null and the consumer skips — correct' — confirms a null-user_id, guest-named booking was already an anticipated state for the OpenRally booking-created event) — the feature was blocked purely by the dialog always requiring at least one player before allowing submit.

Alternatives considered

• Reuse the existing walk-in pattern (create a placeholder account) for guest bookings too (rejected — the whole point is club-internal events with zero CRM noise; every 'Ladies Night' or 'Tournament Prep' booking would otherwise permanently pollute customer search/CRM)
• Infer guest mode from 'no players added' instead of an explicit toggle (rejected — too easy to confuse with a genuine walk-in customer who just hasn't been searched/added yet; an explicit toggle makes the no-account trade-off a deliberate operator choice each time)

New route apps/admin/src/app/api/admin/packages/[id]/payment-link/route.ts (+ /email sibling + send-lesson-package-payment-link edge function), built on the Stripe Checkout Sessions API (mode: 'payment', inline price_data) — the exact pattern already used by the bookings/lessons/memberships admin payment-link routes and the reusable PaymentLinkActions UI component, NOT the PaymentIntent pattern the existing purchase route uses. A new webhook branch (metadata.type = 'lesson_package_payment') creates the player_packages + player_package_sessions rows on checkout.session.completed, mirroring confirm-purchase's writes exactly (status: 'active', stripe_payment_intent_id, expires_at from valid_days). v1 restricted to session_bank packages only (route 400s on package_type='recurring') — recurring packages already have a subscribe flow and extending payment links to them raises the same billing-period rollover question flagged in ALB-7, deferred until that's answered.

Alternatives considered

• Reuse /v1/lesson-packages/[id]/purchase's PaymentIntent directly and just surface its client_secret as a link (rejected — PaymentIntents pair with Stripe Elements embedded in the app, not a standalone hosted payment page; would require building a new hosted checkout page from scratch instead of reusing Stripe's own Checkout page like every other admin payment-link route already does)
• Extend payment links to recurring packages now, defaulting to a one-off charge with no forward subscription (rejected — silently produces a package that never renews, which likely doesn't match what an admin sharing a 'recurring package' link expects; needs a product decision, not a silent default)

Added 'any' as a third explicit literal to package_items.class_type (CHECK widened to ARRAY['private','group','any']), following the exact precedent already set by the discount engine's scope_domain column (ARRAY['booking','lesson','program','pos','any']). consume_package_session() gained a third matching tier: exact class_id match, then class_type = the lesson's concrete type, then class_type = 'any' as the last-resort fallback — an 'any' bucket only drains after a more specific bucket of the correct type is exhausted, so specific-type packages aren't silently starved by a wildcard one.

Alternatives considered

• Reuse NULL for 'unrestricted' (rejected — collides with the existing package_items_check invariant where class_type IS NULL already means 'class_id is set instead'; would require distinguishing two different NULL meanings)
• Client-only 'any' sentinel converted to NULL before hitting the DB, mirroring class-form-dialog.tsx's 'any coach' pattern (rejected — that pattern works because 'any coach' really does mean 'no constraint row', but here class_type NULL is already spoken for; would silently re-collide with package_items_check)

(1) Replaced ai-feedback-auth.ts entirely — GET /roster and PATCH /ai-feedback now authenticate via the existing hashed, per-facility api_keys system (validateApiKey from api/v1/_lib/api-key.ts, previously-unused infrastructure) and verify the resolved facility_id matches the lesson's. One real api_keys row per club, same as any other third-party integration. (2) emit_group_lesson_player_event now holds back session_feedback_updated while feedback_generated_by='ai' AND feedback_reviewed_at IS NULL; the transition of feedback_reviewed_at from null to set now also triggers emission, so reviewed feedback still reaches OpenRally/TPS, just at review time instead of draft time. (3)+(4) Moved the overwrite-protection + write into one atomic SQL function (apply_ai_feedback_to_lesson_player, SETOF return) with the protection condition inside the UPDATE...WHERE clause itself (re-evaluated against current row state, closing the race) and extended to cover coach_rating, not just coach_feedback text.

Alternatives considered

• Patch the facility check into the existing static-secret helper instead of migrating to api_keys (rejected — doesn't fix the no-rotation/no-revocation/no-admin-visibility gap DEC-265 already flagged as a tradeoff)
• Fix the overwrite race with an app-level re-fetch-and-retry instead of a DB function (rejected — still a race, just a smaller window; the DB is the only place that can make the check-and-write atomic)
• Gate the OpenRally broadcast in the ai-feedback route instead of the trigger (rejected — any other future write path to these columns would still leak; the trigger is the one place all writes funnel through)

Extended the middleware's existing external-auth allowlist (previously a single literal path for the Resend webhook, renamed EXTERNAL_AUTH_PATHS) with a second, pattern-based list (EXTERNAL_AUTH_PATH_PATTERNS, regex) to match the dynamic /lessons/:id/ segment, and skip the session check for both.

Alternatives considered

• Give these two routes their own auth check only, leaving the middleware's blanket 401 to fire first (routes would be unreachable — caught by e2e testing before this was fixed)
• Move session-auth enforcement into each route handler instead of middleware (much larger refactor, touches every /api/admin/* route)

A row is finalized (shown) when feedback_generated_by='coach' (any coach-written row, regardless of feedback_reviewed_at) OR feedback_generated_by='ai' AND feedback_reviewed_at IS NOT NULL. Unreviewed AI drafts never surface here.

Alternatives considered

• Show any row with non-null coach_feedback regardless of source/review state
• Require feedback_reviewed_at for every row including coach-written ones

Yes. PATCH /api/admin/lessons/[id]/players sets feedback_generated_by='coach' whenever coach_feedback or coach_rating is included in the request body (attendance-only edits don't flip it).

Alternatives considered

• Leave feedback_generated_by='ai' forever once AI-set, only using it as a historical 'AI ever touched this' marker

Second screen inside the same Dialog, via internal step state ('roster' | 'review'), matching the existing convention in merge-customer-dialog.tsx (search → confirm → resolve → done).

Alternatives considered

• Separate new modal opened on top of/after the roster panel

Model a paid join/enroll as hold-seat → pay → confirm, and choose RECORD-ONLY against Stripe TEST keys as the launch semantics. Migration 20260605094626 (all additive): (1) match_players gains a TTL'd 'held' join_status + hold_expires_at; (2) the update_match_player_count trigger now counts join_status IN ('joined','held') so a held seat reserves capacity (everything else — results, elo, RLS — still keys off 'joined' and is unchanged); (3) program_enrollments gains a real 'pending_payment' status (stops overloading 'waitlisted') + a partial-unique index; (4) hold_match_seat RPC locks the match row FOR UPDATE, re-counts, and inserts a 'held' seat (or 'joined' for free/pay-at-club) — fixing the last-seat race and raising match_full/already_in_match; (5) confirm_match_seat + confirm_program_enrollment RPCs flip held→joined / pending_payment→enrolled idempotently (program one also writes the payments ledger row once per PaymentIntent); (6) expire_match_holds + a per-minute pg_cron sweep free abandoned holds. Routes: matches/[id]/join inserts a held seat then creates the PaymentIntent (metadata type=match_join, match_player_id) and returns client_secret — never marking paid; the Stripe webhook payment_intent.succeeded gains match_join + program_enrollment cases that call the confirm RPCs; programs/[id]/enroll uses 'pending_payment'; confirm-enrollment routes through the same shared idempotent RPC. The same flow flips to real card charges later by swapping Stripe to live keys — no code change.

Alternatives considered

• Real card charge (flip Setpoint to live Stripe) at launch — REJECTED for step-1: pulls in PCI/refund/dispute readiness and is a separate decision; the plan explicitly decouples the live-keys cutover from this feature.
• Pending / collect-at-venue only — REJECTED as the build target: it never exercises the PaymentIntent → webhook → confirm reconciliation that IS the fix, so it wouldn't prove the gate is closed.
• Keep the immediate-'joined' shape and bolt on reconciliation later — REJECTED: leaves the phantom-paid window (capacity occupied by unsettled seats) open, which is the exact gate we must close before any paid OpenRally exposure.
• Count only 'joined' for capacity and gate held seats in app code — REJECTED: the gate must be atomic; counting joined+held in the locking RPC + trigger is race-free, where an app-level recount is not.
• Un-hide the admin Matches/Programs nav (revive the UI) in this PR — DEFERRED to step 2: the payment fix is backend and fully testable via the API/RPCs; reviving the operator UI is a separate concern, kept out to keep this the focused no-go-gate PR.

Make `availabilityWindowsForDate` the single source of truth for recurrence matching + per-court exception subtraction, and propagate DEC-237 court scoping to all 8 affected surfaces. (1) packages/common/src/coach-availability.ts: `validateLessonAgainstAvailability` gains an optional 4th param `courtIds?: string[] | null`; it pre-filters exceptions to (ex.court_id == null || courtIds.includes(ex.court_id)) before calling `availabilityWindowsForDate`. courtIds undefined/null ⇒ apply every exception (pre-v0.30.0 back-compat for callers that don't track the court). (2) apps/admin/.../calendar-grid.tsx (day view, the reported surface): exceptions SELECT adds court_id; exceptions are filtered to (ex.court_id == null || ex.court_id === r.court_id) BEFORE both the whole-day check AND subtractTimeRanges. (3) .../coaches/[id]/available-slots/route.ts: REPLACED its hand-rolled per-row subtraction with `availabilityWindowsForDate` grouped per court (court_id added to the exceptions SELECT); removed the now-unused parseHM. (4) .../lessons/available/route.ts: REPLACED hand-rolled subtraction with `availabilityWindowsForDate` per (coach, court); court_id added to the SELECT + exceptionsByCoach; removed the now-unused toMinutes; whole-day handling is now per-court (was a single global coachIsOff set). (5,6,7) .../admin/lessons/route.ts (POST), .../admin/lessons/[id]/route.ts (PATCH), and .../player-packages/_lib/generate-lessons.ts: exceptions SELECT adds court_id, and each passes the lesson's courts into `validateLessonAgainstAvailability` (POST: court_ids; PATCH: courtIds, undefined on time-only edits ⇒ legacy all-exceptions; generate: sched.court_ids || [defaultCourtId]). (8) .../v1/facilities/[slug]/coaches/[id]/route.ts: added court_id to the public exceptions projection (a contract gap — DEC-237-aware consumers can now scope). The known-correct reference twin already doing per-court scoping is availability/route.ts (per-court loop with courtId); the other surfaces now match it.

Alternatives considered

• Targeted per-site patch keeping each hand-rolled subtraction copy and just inserting the court filter inline at each call: REJECTED — debt that drifts again. The defect WAS N divergent copies of the same interval math; re-patching them in place re-creates the exact divergence that caused this bug (and DEC-256's OpenRally twin). Routing every surface through the one `availabilityWindowsForDate` helper (which already does DEC-237 scoping) is the no-debt fix and guarantees the calendar read, the slot pickers, and the lesson gates can't disagree.
• Fix the remaining court-agnostic availabilityWindowsForDate call sites in THIS PR: DEFERRED/intentional, documented (not in this commit). FOUR sites still call the helper WITHOUT a courtId, and NONE can reproduce BUG-104 — all are conservative under-show (they can only make a coach look LESS available, never make a held court look free): (i) availability/range/route.ts — coarse calendar day-DOTS ('does ANY coach have ANY 60-min slot'); the file documents the no-courtId call as a deliberate ballpark and the exact drill-in is availability/route.ts (LOW; clean fix = group coachRows by court) — a genuine low-priority follow-up. (ii) coach-calendar-tab.tsx — single-coach MONTH overview rendering one MERGED bar from schedule-GET rows coalesced with court_ids[] (a list, no single-court grain to scope); it over-subtracts a per-court exception into the merged bar = conservative under-show; proper fix is per-court rendering/union (cosmetic backlog) — a genuine follow-up. (iii) lesson-form-fields.tsx and (iv) lesson-form-dialog.tsx — INTENTIONALLY court-agnostic 'when is the coach available at all' date HINTS that already delegate the authoritative per-court slot/court-chip computation to the available-slots route (FIXED in (3) above); correct by design, no change needed. So this PR closes every surface that can mis-show a held court as free; the four no-courtId sites are either conservative coarse/secondary views or intentional hints over a now-correct authoritative path.
• Add a real unit-test runner (vitest) for coach-availability before shipping: DEFERRED as a recommended follow-up. The repo has NO unit-test runner today and builds/dev are blocked this session (the build configs are malware-infected), so verification instead used a Node type-stripping harness that exercised the ACTUAL edited coach-availability.ts (10/10 cases). A proper vitest suite covering these scenarios is the right durable home for them and is recommended once the build path is clean.

Replace the single-exception @> containment test with subtract-then-overlap, computed PER COACH. For each coach with a strict (blocks_courts=true) availability applicable on the date on this court, compute (range_agg(time_range) MINUS range_agg(that coach's date+court-scoped windowed exceptions)); drop a coach that has a whole-day exception (start_time IS NULL) for the scope; BLOCK iff ANY coach's surviving multirange OVERLAPS (&&) the booking. Mirrors the lesson_court branch and coach_blocked_intervals_for_facility, keeps the blocks_courts=true filter (DEC-245), the per-court predicate (ae.court_id IS NULL OR ae.court_id = p_court_id, DEC-237), the whole-day-zeroes-the-day rule, and the same court_reserved_for_coach RAISE/DETAIL. Shipped as one additive, reversible CREATE OR REPLACE migration (20260604100847_fix_court_booking_gate_exception_subtraction.sql) that changes ONLY the court_booking branch — signature, DECLAREs, tz/midnight/seconds setup, the DEC-247/DEC-248 lesson_court branch, and the triggers are byte-identical to 20260527141545. Regression coverage: a 24-case SQL matrix run against the locally-applied function (incident allowed; 12:00–14:00 still blocked; split-window; whole-day; open-mode; control) plus a 4-case lesson_court no-regression check, and E2E tc-250 (incident booking succeeds via /api/admin/bookings, remaining-hold still 400s, cross-coach orphan-safety still 400s, calendar shows the freed hours bookable).

Alternatives considered

• DEC-256 §follow-up: harden the existing containment to range_agg(exceptions) @> v_lesson_range (coach-exception-interval-fix-plan.md §6.1): rejected — INSUFFICIENT for this incident. The booking starts before any exception, so no containment test can lift it: range_agg({[11:00,12:00)}) @> [10:00,12:00) is FALSE (verified in prod SQL). That hardening only addresses adjacent-exceptions-jointly-covering; the leading-edge case needs subtraction. The prior triage that called the @> branch 'errs safe — over-blocks, never orphans, NOT a bug' was wrong: over-blocking makes a legitimate, conflict-free booking impossible.
• Lift the lesson_court branch verbatim (single-coach subtraction) into court_booking as a cross-coach aggregate: REJECTED — orphan-court hazard. court_booking scans EVERY coach on the court, so a single range_agg(all availabilities) − range_agg(all exceptions) lets one coach's (or an over-wide) exception cancel another coach's genuine hold (proven: coach B [11,13)+over-wide off, coach C [13,15) un-excepted → global aggregate frees 13:00–14:00 that C holds → double booking). The subtraction MUST be GROUP BY coach_id; block if ANY coach's surviving hold overlaps.
• Add an override button / let the operator force the booking: rejected — the gate is correct in intent; the math was wrong. Fix the math, don't add an escape hatch (consistent with DEC-15 no-override stance).
• Also flip the reverse gate coach_availability_conflicting_bookings (origin 20260527073858) to subtraction in the same PR: deferred to a coordinated follow-up. It answers a different question (which existing bookings conflict with a proposed availability) and changing it alters the editor conflict panel / 'Ignore this conflict' UX (DEC-239); per .claude/rules/coach-availability.md 'change one, audit the twin' it needs its own regression test + explicit approval.

(1) Reuse player_ratings. Add a single generic level_type='consumer' to the CHECK (additive); the provider identity lives in the existing `source` column (a consumer namespace supplied by the caller, e.g. or_providers.namespace) — never a hardcoded vendor name. (2) New SECURITY DEFINER RPC `or_upsert_player_level(email, facility_id, sport, level, level_type, source)` email-matches a customer (reusing the ExternalBookingCreationService pattern) and upserts READ-ONLY on the EXISTING UNIQUE(user_id,facility_id,sport_type,level_type); it RAISEs user_not_found and blocks internal level_types from consumer ingest. (3) New additive OpenRally endpoint `POST /openrally/v1/players/by-email/level-ingest` (version 0.1.0→0.2.0, idempotent, API-key auth) — facility comes from the authenticated key, never the body. (4) Club config in facilities.settings.enabled_level_systems (per-sport list); admin Leveling Systems settings tab; GET ratings filters external systems by it (internal self_assessed/admin_override/coach_set always shown). (5) Admin customer page shows external levels READ-ONLY (lock icon); no admin edit, no migration. (6) The literal 'tps' appears ONLY in padel-backend (consumer side). (7) The consumer's push runs in the BACKGROUND (padel-backend, via EdgeRuntime.waitUntil), off the match-scoring path, so a slow/down OpenRally never delays or fails match certification. POST-LAUNCH the push was broadened beyond match certification to ALL TPS level sources: onboarding + manual edits are caught by a 5-min pg_cron reading historical_leveling (padel-backend #232), and a daily reconciliation cron (padel-backend #235; rate-limit pacing fixes #236/#237) re-pushes current levels in rolling id%144 slices every 10 min so newly-matched customers with static levels and any drift self-heal; existing customers were seeded once by an email-matched backfill (4,018 at Pad Thai, run via the same RPC). Fixed two adjacent latent bugs surfaced by the feature: the ratings API slug/id param mismatch and the facilities PATCH that clobbered settings (now merges); plus an orphaned facility_customers role-trigger that broke user_facility_roles inserts + db reset.

Alternatives considered

• level_type='tps' (the auto-generated plan's first cut): REJECTED — 'tps' is a specific consumer's brand name; CLAUDE.md forbids naming a consumer anywhere in Setpoint's DB/API/UI. wpr/dupr/ntrp are fine (neutral industry standards); a consumer app is not. Use generic 'consumer' + provider-supplied `source`.
• Swap UNIQUE key to (user,facility,sport,level_type,source) to allow many consumer providers per player/sport: REJECTED for v1 — dropping/re-adding a unique constraint on a live table is not additive, and because internal rows have source=NULL (NULLs distinct in Postgres) it would WEAKEN the existing one-row-per-internal-system guarantee and break the existing admin_override upsert's onConflict. One consumer feed today needs no source in the key; revisit with NULLS NOT DISTINCT only if a second generic-consumer provider ever appears.
• First-class leveling-systems registry table + facility join (the 'purer' design): DEFERRED — more tables + a backfill on live prod for marginal benefit while only one external feed exists; the enum+jsonb config ships safely in one PR. Graft later if provider count grows.
• Separate external_rating_sync identity table: DEFERRED to a follow-up — email-matching is the established, trusted cross-system identity bridge (booking reverse-write, coach discovery). Add a typed mapping only if email collisions actually arise.
• Show levels in the public web app (apps/web) / wire into match-join: REJECTED — apps/web and the Matches feature are PARKED in CLAUDE.md. Admin-app display only.
• Let admins edit/override external levels, or migrate existing levels in: REJECTED — explicit CEO constraints (leveling lives in TPS; no migrate; no admin edit).
• Two-way protocol via Setpoint LIVE-PULLING the level from the consumer (OpenRally fetches TPS on each profile view): REJECTED. OpenRally is a one-way adapter (consumers read/write Setpoint; it has no path to fetch FROM a consumer), so live-pull needs new outbound infra on BOTH sides, is untestable locally (needs the live consumer), and couples Setpoint's page load to consumer uptime. Mature booking protocols have the data-owner PUSH its data — so OpenRally's two-way direction is 'consumers PROVIDE player attributes' (a background push the PMS stores + displays), not a synchronous PMS-pull. This was debated explicitly with the product owner.

Make blocks_courts faithful end-to-end and fail loud on a missing flag rather than defaulting (CLAUDE.md 'No silent errors'). (1) `coach_schedule_replace` removes the `COALESCE(...,true)` default and RAISEs if any availability element lacks an explicit boolean blocks_courts; it also takes a per-(facility,court) `pg_advisory_xact_lock` to serialize concurrent same-court replaces. (2) The admin route `apps/admin/src/app/api/admin/coaches/[id]/schedule/route.ts` stops doing `blocks_courts ?? true`, returns 422 on a missing/non-boolean flag, and calls a new pre-save check. (3) New STABLE function `coach_availability_overlaps(p_coach_id, p_facility_id, p_availabilities)` enumerates strict×strict same-court overlaps using the IDENTICAL predicate as the `coach_availabilities_check_overlap` trigger (half-open numrange `&&`, symmetric recurrence-date intersection via `coach_availability_dates` / `coach_availability_applies_on_date`, both blocks_courts=true, including intra-payload sibling pairs and excluding the edited coach's own existing rows). The route surfaces the result as a 409 with an actionable `overlaps[]` list instead of an opaque DB raise. The overlap TRIGGER itself is unchanged (it is the correct DEC-254 relaxed version). New e2e `apps/admin/e2e/tc-248-open-window-saves-over-existing-strict.e2e.ts`. One additive migration `20260530074244_coach_overlap_consistency.sql` (CREATE OR REPLACE only, no data mutation, no DROP). Survived a 3-round adversarial debate; matches industry single-unit-resource semantics (Acuity qty-1 resource, Playtomic open-match-doesn't-hold-court, Matchi single-unit court).

Alternatives considered

• Re-add a COALESCE/`?? true` default for the missing flag: rejected. This is exactly the bug — it silently coerces an open window to strict, secretly holding the court and removing bookable time from customers. Defaulting hides a real client mistake; 'No silent errors' requires a loud 422/RAISE so the wrong payload is caught, not absorbed.
• Tighten the overlap trigger to also reject open windows: rejected. The trigger is correct (DEC-254) — open windows are SUPPOSED to overlap freely because they don't hold the court. The bug was the INPUT being coerced, not the rule; changing the rule would break the open-availability feature.
• Enforce same-court non-overlap with a Postgres EXCLUDE constraint instead of a pre-check + advisory lock: rejected. An EXCLUDE constraint cannot express recurrence-date intersection — it would falsely reject legitimate strict pairs that overlap in clock time but whose recurrence dates never coincide (prod has ~34 such time-overlapping pairs that save fine because their dates don't intersect). A per-(facility,court) `pg_advisory_xact_lock` plus a date-aware pre-check is the right tool.
• Only fix one layer (route OR rpc): rejected in favour of defense-in-depth — both the route (422) and `coach_schedule_replace` (RAISE) reject a missing flag so no write path can coerce open→strict.

Strategy A0: add ONE shared STABLE SQL helper `coach_lesson_windows_for_date(p_facility_id uuid, p_coach_id uuid, p_date date)` returning surviving local-time sub-windows `(court_id, start_time, end_time) = range_agg(availability) − range_agg(exceptions)` via Postgres multirange subtraction, per-coach, with per-court exception scoping `(ae.court_id IS NULL OR ae.court_id = a.av_court_id)`, whole-day exceptions (start_time NULL) zeroing the day, half-open `[)` semantics so a boundary touch does not overlap, and — per DEC-247 — NO `blocks_courts` filter (lesson eligibility ≠ court hold). It is the lesson-eligibility twin of the proven in-prod `coach_blocked_intervals_for_facility`. Both buggy Rust sites now call it: the `coach_availability.rs` handler `SELECT … FROM coach_lesson_windows_for_date(...)` (the `NOT EXISTS` deleted; the slot-slicing loop unchanged), and `coach_search.rs` `has_availability = EXISTS(SELECT 1 FROM coach_lesson_windows_for_date(...))`. Dead `list_availabilities` / `list_availability_exceptions` helpers (which carried the same buggy pattern) and their unused structs were removed. New migration `20260601043321_coach_lesson_windows_for_date.sql`; 12 cargo tests over the real HTTP endpoints for both sites (split, whole-day, boundary-touch, window-split, adjacent-cover, per-court DEC-237) asserting parity vs Setpoint's `availabilityWindowsForDate` and the blocked-intervals helper. Response SHAPE is unchanged (it just returns the slots it was wrongly dropping) so no protocol version bump.

Alternatives considered

• Keep the 'drop the whole window on any overlap' filter: rejected — it is the bug. The canonical primitive across Google Calendar FreeBusy, Cal.com, Calendly/Acuity is interval-set difference A∖B, never deleting the whole block when an exception partially overlaps. A partial time-off must TRIM or SPLIT the window, never erase it.
• Inline the multirange subtraction separately in each of the two Rust SQL queries (Strategy A-inline): rejected. The bug WAS two duplicated SQL copies that drifted; inlining re-creates that duplication and invites the next drift. One shared helper mirroring a proven in-prod function is the no-debt choice.
• Subtract the intervals in Rust by porting the TS `subtractWindow` into the handler (Strategy B): rejected. It re-implements logic that already exists twice in SQL plus once in TS and needs a model change (adding court_id to the exception row), with no upside over the shared SQL helper.
• Treat it as a timezone/DST problem (Asia/Bangkok shift): rejected — a red herring. BKK has no DST; the data (partial coach time-off) was valid; the defect was purely the overlap-exclusion SQL, and the per-court leak from the missing `(ae.court_id IS NULL OR ae.court_id = court)` predicate.

OpenRally lesson-hold endpoint (setpoint protocol/server) gains a hold_duration_minutes request field that the consumer supplies; the server uses it as the hold TTL when present and falls back to a default. The default was raised 5→15 min so even a consumer that doesn't send the field gets a window that comfortably covers a typical payment flow. The protocol stays consumer-agnostic — it exposes a duration knob, it does not encode TPS's 10-minute number. The consumer (padel-backend) sends 15 (= its 10-min payment window + a 5-min buffer) so the hold always outlives the payment window. Shipped as setpoint OpenRally server PR #688 (merged, flyctl-deployed). Verified live 2026-05-28 (coaching booking #60839, Sandbox Pad Thai Padel / club 625, court "The Padel Society" / 1273): paying slowly through the full window still completed and the court was not taken mid-payment.

Alternatives considered

• Hardcode a 15-minute lesson-hold TTL on the server with no request field: rejected. The right window depends on the consumer's own payment UX (its checkout timeout, retry policy, 3DS step-ups). The protocol must let the consumer state its need rather than guess — baking a single number in is a consumer-specific assumption the next OpenRally consumer would inherit blindly.
• Leave the default at 5 min and require every consumer to always send hold_duration_minutes: rejected. A consumer that forgets the field would silently regress to the too-short window. A safer default (15) plus an override is the no-silent-failure choice.
• Extend (re-issue) the hold from the consumer side as the payment window ticks: rejected. Adds round-trips and a renewal race; a single hold that already covers the window is simpler and has no renewal failure mode.

Two coordinated changes in padel-backend (PR #221). (1) Court passthrough: the court the picker displayed is carried through to the OpenRally hold, so the hold reserves THAT court — not a fresh "first available" pick that could differ from what the player saw. (2) Hold buffer: the OpenRally hold is requested with a TTL that exceeds the TPS payment window — a 15-minute hold over the 10-minute payment window (a 5-minute buffer) — via the hold_duration_minutes field added on the server (DEC-244). Verified live 2026-05-28 (booking #60839): the hold landed on the displayed court "The Padel Society" / 1273 and survived the full payment window.

Alternatives considered

• Keep selecting "first available" at hold time: rejected. Native-equivalence violation — the player picked a court (implicitly, via the slot the picker showed) and the system silently held a different one. The displayed court and the held court must be the same court.
• Match the hold TTL exactly to the payment window (no buffer): rejected. Clock skew between systems plus the latency of the final confirm could let the hold lapse a moment before confirm lands. A buffer (payment window + 5) removes the edge.
• Re-pick the court only if the displayed one became unavailable between display and hold: rejected for this fix — silently substituting a court still breaks the player's expectation. If the displayed court is gone, the correct behavior is to fail the hold and re-fetch availability, not swap courts behind the player's back.

Coaching pricing now comes from the coach's class price — classes.price_per_pax_amount — which is all-inclusive of the court, matching how Setpoint prices a native lesson. It no longer uses the court rental price. Shipped as padel-backend PR #220. Verified live 2026-05-28: THB 3,000 (the coach's class price) was charged, not the court rental rate.

Alternatives considered

• Keep court-rental pricing for coaching: rejected. It charges the wrong amount and breaks native-equivalence — a TPS-booked lesson would cost a different amount than the same lesson booked in Setpoint admin. The class price is the single source of truth for what a lesson costs.
• Sum court rental + a separate coaching fee: rejected. classes.price_per_pax_amount is already defined as all-inclusive of the court; adding the court again would double-charge the court component.

The OpenRally branch of get-coaching-availability-v2 now sources both the reserved-court set and the court combinations from OpenRally instead of TPS's local booked_slots. (1) reservedCourtIds are derived from OpenRally (padel-backend PR #218) — the picker reads what OpenRally reports as reserved rather than inferring from stale local slot rows. (2) court combos are built from the coach's OpenRally availability (padel-backend PR #219) — so the picker offers the coach's actual court(s), reading coach_availabilities + availability_exceptions correctly through the protocol. Result: the picker shows the correct coach AND the correct court. Shipped + verified live 2026-05-28 (booking #60839, Sandbox Pad Thai Padel / club 625, court "The Padel Society" / 1273).

Alternatives considered

• Mirror Setpoint coach availability into TPS's local booked_slots (fix it on the TPS side by keeping a local copy fresh): rejected. Violates 'Setpoint + OpenRally are consumer-agnostic' (CLAUDE.md) — every future OpenRally consumer would have to re-mirror. The protocol must tell the truth; the consumer must trust the protocol, not maintain a shadow copy that drifts.
• Leave the picker reading booked_slots and only fix it once a coach's slots visibly fail to appear: rejected. That was the original DEFERRED stance; the gap is a correctness bug (wrong court shown, fresh availability invisible) that the no-debt mindset says to close at the source rather than wait for it to bite a real booking.
• Read availability from OpenRally but keep court selection from booked_slots: rejected. Half-measure — the court is exactly what was wrong; combos must come from the same OpenRally availability so the displayed court matches what the hold (DEC-243) will reserve.

No. Open-mode coach slots return as plain 'available' to the protocol. No coach_floating / open_mode / bookable_by_coach field. Consumers see one truth: 'court X at time T is bookable.' Whether a coach also has open availability there is the producer's internal concern; if a future consumer needs to render 'coach available here', they query /coach-availability separately (that surface already exists).

Alternatives considered

• Add coach_open_mode:true metadata on the slot: rejected. Violates 'OpenRally is consumer-agnostic' — once added, every consumer has to decide how to render it, and the protocol is no longer transport-only, it carries product semantics.
• Two endpoints — 'coach hours' and 'open court hours': rejected. Two surfaces for one conceptual thing, hard to keep in sync, and TPS-side adapters would have to merge results back together.

Allow when both overlapping rows have blocks_courts=false. The trigger only rejects overlap when BOTH rows have blocks_courts=true. Open+open is allowed; open+strict is allowed (strict wins the court claim); two strict still rejected (current behavior).

Alternatives considered

• Reject any overlap regardless of mode: rejected. The whole point of open mode is 'I'm OK sharing the court.' Forbidding two coaches from open-sharing the same court at the same time fights the feature.
• Allow open+open across coaches but reject open+open for the same coach: rejected. A coach declaring overlapping open windows is plausibly intentional (back-to-back lesson formats, drop-in coverage). The schema shouldn't gatekeep this.
• Add a UNIQUE constraint per (coach, court, time, blocks_courts): rejected. Same as above plus extra schema baggage.

UI greys out per-court exception chips when the parent availability row is open, with tooltip 'Exceptions only apply in strict mode.' PUT /api/admin/coaches/[id]/schedule returns 422 (code: exception_on_open_availability) if a save attempt creates an exception whose intersect set contains only open availabilities. Route-layer validation, not a CHECK constraint, because the join is non-local.

Alternatives considered

• Silently accept the exception, no-op at runtime: rejected. Dead data, confusing UI ('why isn't my exception working?'), maintenance liability.
• Hard CHECK constraint at the table level: rejected. The join from availability_exceptions to coach_availabilities is non-local (matches by coach_id + facility_id + date + court_id intersection) — too complex for a row-level CHECK.
• Delete the exception data when the parent flips to open: rejected. Data loss on toggle — if the operator flips back to strict, the exception is gone. Persistence is cheap; data loss is not.

Label: 'Open availability — court stays bookable.' UNCHECKED is strict (default). Operators opt INTO open mode by ticking the box. The DB column blocks_courts also DEFAULTS true — the polarity matches end-to-end (unchecked toggle ↔ blocks_courts=true).

Alternatives considered

• 'Strict reservation' labeled toggle, default checked: rejected. Inverts the meaning of 'default ON' — the absence of a click would mean 'I want the new feature' which is wrong on day one.
• Three-state radio (strict / open / inherit-from-coach): rejected. No coach-level default exists in schema; inventing one for a binary opt-in is over-engineering.

Open rows still count. The toggle is about court reservation, not coach presence. An open availability means 'coach is physically here, but the court can be used by others.' For program scheduling and package eligibility, the coach IS available — the court question is downstream of 'is this coach offering hours this slot?'

Alternatives considered

• Filter open rows out of program/package eligibility: rejected. Conflates coach presence with court reservation. A coach offering open hours is still offering hours.
• Add a separate is_available_for_teaching boolean: rejected. Over-engineering; the existing semantics survive unchanged with a one-line load-bearing comment.

Open-mode tiles render with: dashed border, reduced opacity (~60%), and a small 'Open' badge in the corner. Solid tiles = strict (current behavior). BOTH calendar-grid.tsx (day view) AND week-calendar-grid.tsx (week view) get the same treatment — no divergence. Hover tooltip on open tiles: 'Open coaching slot — court remains bookable by customers and other coaches' lessons.'

Alternatives considered

• No visual distinction (project the column but render identically): rejected. Operator sees 'Reserved' tile but customer can book on top of it — pure UX lie. Critic's 'ghost block' trap.
• Use a new color (e.g. amber for open): rejected. The repo's calendar already uses color for booking type / sport; adding another color dimension fights the existing system and would require legend updates.
• Hide open tiles entirely from the calendar: rejected. Operators still need to see the coach's intended hours for planning, even if the court is shared.
• Day view only (skip week view): rejected. Operators planning Tuesday at 4pm switch between both views; either rendering wrong without the distinction guarantees confusion.

Add a Postgres trigger on coach_availabilities AFTER INSERT/UPDATE/DELETE that (a) deletes affected rows from or_materialized_slots for the impacted (facility_id, court_id, [date range]) so the next read re-materializes, and (b) calls pg_notify('coach_availability_changed', facility_id::text). Add a Rust LISTEN handler in protocol/server (new file: src/cache/listen.rs, spawned from main.rs) that subscribes to coach_availability_changed and invalidates L1 cache prefix 'availability:{facility_id}:' on each notification.

Alternatives considered

• Wait for the 60s materializer pass: rejected. UX-breaking — admin toggles a slot to open, customer can't book it for up to 60s, support tickets follow.
• HTTP webhook from admin to OpenRally: rejected. Requires admin to know OpenRally's URL (consumer-agnostic violation — admin shouldn't be a client of its own consumers), more network hops, requires shared secret management.
• Force admin to manually trigger rematerialize via a button: rejected. Operator burden, easy to forget, exactly the kind of 'remember to also do X' pattern CLAUDE.md 'Zero manual setup' rejects.
• Reduce materializer cadence to 5s: rejected. Constant DB pressure for a rare event. Trigger-based invalidation is event-driven, not poll-driven.

Add a NEW guard to the lesson_court branch of check_booking_against_coach_reservations: when the matched coach_availabilities row has blocks_courts=false, additionally check that no confirmed/held booking already overlaps the requested (court_id, time window). If one does, raise lesson_displaced_by_booking with DETAIL JSON containing { displaced_by_booking_id, displaced_by_type ('court_booking' | 'lesson') }. The admin UI surfaces a human-readable explanation via translate-coach-error.ts.

Alternatives considered

• No guard, accept the double-booking: rejected. Same court double-booked = customer arrives, lesson student arrives, operator scrambles. CLAUDE.md 'No silent errors' — fail loud.
• Auto-pick another court for the lesson (auto-fallback): rejected per DEC-246. Out of scope this PR. Logged as deferred follow-up.
• Block the customer's court booking too if a lesson is later attempted on the same court: rejected — defeats the entire point of open mode (the customer should win — that's the manager's stated rationale for small clubs).

No. The lesson_court primary aggregate stays mode-agnostic — a lesson must lie within the coach's stated availability regardless of whether the row is strict or open. Open mode only relaxes the 'block others' rule, not the 'this coach's lesson must be inside their own declared time window' rule. A load-bearing SQL comment cites TC-243 as the regression test that prevents this from being 'cleaned up' later.

Alternatives considered

• Filter lesson_court on blocks_courts=true (symmetric with court_booking branch): rejected. A coach with open availability could no longer book their own lessons on their declared time/court — defeats the feature. The toggle is about who else can use the court, not about the coach's own claim.
• Filter lesson_court on blocks_courts=false (inverse symmetric): nonsensical — would mean lessons can only land on open rows, the inverse of intent.

Ship ONLY the toggle. Auto-fallback is explicitly deferred to a future feature. When the coach's preferred court is taken under open mode, the coach's own lesson FAILS LOUDLY with the DEC-248 enriched error rather than auto-migrating to another court.

Alternatives considered

• Bundle auto-fallback into this PR: rejected. Adds significant complexity (court eligibility pool, conflict-aware resolver, race-safety against concurrent customer bookings, ordering / preference rules). The toggle is independently valuable and the enriched error is sufficient operator UX for now.
• Implement only auto-fallback (no toggle): rejected. Toggle is the operator-facing decision; auto-fallback is the implementation detail behind it. Toggle must ship first or auto-fallback has no toggle to attach to.

blocks_courts boolean NOT NULL DEFAULT true. Predicate-style verb phrase reads as a predicate at the call site (WHERE ca.blocks_courts = true), describes the row's observable behavior directly, and future-proofs via additive booleans rather than a re-encoded enum.

Alternatives considered

• is_strict boolean: rejected. Opaque without docs ('strict relative to what?'); reader has to chase the term to a glossary.
• mode coach_availability_mode enum('strict','open'): rejected. A 2-value enum is over-engineering for today's needs — pay enum migration cost (custom type, ALTER TYPE for new values) for a hypothetical third state. CLAUDE.md 'No-debt, no-compromise mindset' says: don't pay the enum cost speculatively. If a third mode appears later, promote then via a new migration.
• exclusive boolean: rejected. Overloads with DB lock vocabulary (FOR UPDATE, exclusive lock) — code-review confusion and grep noise.

New SQL function coach_blocked_intervals_for_facility(p_facility_id uuid, p_start_date date, p_end_date date) returning TABLE(court_id uuid, start_time timestamptz, end_time timestamptz). Mirrors the court_booking branch of check_booking_against_coach_reservations in reverse: instead of 'is this candidate booking blocked?', returns 'what intervals are blocked?'. Uses the existing coach_availability_applies_on_date() helper for recurrence, subtracts whole-day + per-court windowed availability_exceptions via numrange/range_agg/multirange algebra (same primitives the trigger already uses), and projects facility-local seconds-of-day → UTC timestamptz via facilities.timezone so the materializer compares overlaps in its native currency. Migration: 20260527115454_or_coach_blocked_intervals_for_facility.sql. Rust: materializer fetches Vec<CoachBlockedInterval> once per pass (right after the bookings fetch) and the per-slot match becomes 'real booking wins → blocked → available' (real bookings keep their booking_id so the slot still renders as booked, not as an empty block). Status 'blocked' was already a valid value in the or_materialized_slots CHECK constraint (unused until now) so no table migration. The trigger remains the authoritative write-time guard, untouched — function exists purely so consumers stop advertising slots the trigger will reject. Materializer's existing 60s refresh cycle handles freshness; no new cache invalidation wired. Rust integration tests (tests/materializer_coach_block.rs) cover both the basic weekly-coach case and the per-court windowed-exception multirange subtraction.

Alternatives considered

• Reimplement the recurrence + exception subtraction in Rust inside materializer.rs: rejected. Two encodings of the same invariant (SQL trigger vs Rust query) will drift the moment a 4th blocker type lands (maintenance windows, holiday closures, weather). Violates Architecture-first and the no-debt mindset.
• Add a generic or_court_blocked_intervals view that UNIONs bookings + coach availability + future blockers, and refactor the trigger to read from it: the architecturally cleanest endpoint, but rejected for THIS PR because it would also touch the working write-time trigger (regression risk on something tested) and the immediate user-visible fix doesn't require it. Documented as the destination — to be picked up when a 4th blocker type creates the natural pressure to converge.
• Mirror Setpoint coach availability into TPS's local DB (BUG-097's sibling problem fixed in TPS instead): rejected. Violates 'Setpoint + OpenRally are consumer-agnostic' — every future OpenRally consumer would have to re-mirror. The protocol must tell the truth; consumers must trust the protocol.
• Filter coach-blocked slots out of the materialized table entirely (no slot row at all): rejected. Loses the ability for consumers to render 'Reserved for lessons' as a distinct state (vs 'Booked' vs 'Past'), and the existing CHECK constraint already had 'blocked' reserved for exactly this kind of structural reason. 'Blocked' is more honest than absence.
• Mark coach-reserved slots with the same 'booked' status as actual bookings: rejected. Conflates two semantically different things — a booking has a booking_id and a payer; a coach reservation has neither. Downstream code that joins on booking_id would break. 'Blocked' is the right name.
• Real booking wins over coach reservation on the same slot (chosen): when both apply, status='booked' with the real booking_id, not 'blocked'. Alternative was 'blocked wins' — rejected because (a) it loses the booking_id reference downstream, (b) it doesn't match what an operator would expect to see on the calendar (an existing reservation should still display as such), (c) the booking is real money/state and the coach reservation is policy.

Add an 'Ignore this conflict' button next to each row in the red conflict panel inside the coach schedule editor (apps/admin/src/components/admin/coach-schedule-editor.tsx, the existing conflict-panel block rendered when conflicts.length > 0). One click injects a new ExceptionEntry into editor state pre-filled with court_id = conflict.court_id, date = conflict.date, start_time + end_time parsed from the conflict's time-range string. The new exception row scrolls into view; the corresponding conflict-panel row is muted/struck to indicate 'handled — re-save to clear'. Operator clicks Save Schedule a second time; the gate (now exception-aware per DEC-238) accepts. The manual 'Add exception' button at the top stays as a fallback for ad-hoc exceptions outside the conflict-resolution path.

Alternatives considered

• No inline button (manual path only): rejected. Operator must remember the court, copy the date, copy the time. Discoverability fail — the tool isn't surfaced where the friction is.
• Auto-add the exception silently on save without explicit click: rejected. Silent state mutations on save are hostile — the operator should see and approve the carve-out before it persists.
• Two-step (button → modal asks 'Add exception for Court X on Jun 25 from 11–13?' → confirm): rejected. The button label already states the intent; an additional modal is friction without value. The injected exception is visible in the editor and can be removed before save if the operator changes their mind.

Three coordinated changes in the same migration as DEC-237. (1) Reorder coach_schedule_replace (migration 20260512115124, the existing replace RPC) to DELETE-old then INSERT exceptions FIRST and INSERT availabilities SECOND in the same transaction. The per-row backstop trigger on coach_availabilities fires on each availability INSERT and must be able to see the new exceptions — which requires they exist BEFORE the trigger reads. (2) Update check_booking_against_coach_reservations (migration 20260512102224) to scope its existing exception subtraction by court_id (ae.court_id IS NULL OR ae.court_id = ca.court_id) — both court_booking and lesson_court branches. (3) Update coach_availability_conflicting_bookings (the route-level matcher, migration 20260522082857) to subtract exceptions identically using the same court-scoped predicate. Both layers now see the same shape — DEC-228's 'consistency between layers' rationale for ignoring exceptions is satisfied.

Alternatives considered

• Leave R6 open: rejected. Without this fix, the manager can add an exception but the gate still refuses to save. The per-court column from DEC-237 would be dead config — the predicate filters wouldn't fire. R6 fix is a prerequisite for the user-visible feature.
• Fix R6 keeping all-courts-only exceptions (no court_id): rejected — see DEC-237 alternatives (multi-court silent destruction).
• Fix R6 by making the matcher accept proposed (in-request-body, not-yet-persisted) exceptions so the gate can be checked before commit: considered. Would let the operator preview 'if I add this exception, would the gate clear?' without persisting. Deferred — the INSERT-reorder approach achieves the same end-state simpler. Could revisit later if operators want preview-without-commit.

Add optional court_id uuid NULL REFERENCES courts(id) ON DELETE CASCADE to availability_exceptions. NULL = all reserved courts (preserves today's semantics for every existing row). NOT NULL = scoped to that one court. Matches the per-court grain of coach_availabilities (one row per court). New optional column, zero data migration, additive change. The R6 gate fix (DEC-238) is bundled in the same PR because gate-honors-exceptions is a prerequisite for either A or B to actually unblock the manager. The inline 'Ignore this conflict' button (DEC-239) is the UI affordance that makes per-court remediation discoverable at the point of friction.

Alternatives considered

• Option A — Fix R6 only (gate honors all-courts exceptions, no schema change): rejected. Works for the manager TODAY because she's only reserving one court, but the moment any operator reserves a coach across two courts and only one has a conflict, an all-courts exception silently destroys BOTH reservations. Schema-level lie waiting for the next multi-court use case. The minimalist agent originally proposed Option A and conceded in round 2 after seeing the multi-court silent-destruction case.
• Option C — Per-availability-row exceptions (1:1 FK to coach_availabilities.id): rejected. Over-normalized; cascading delete on availability replace orphans exception semantics (every schedule edit DELETEs old availabilities, would orphan all their exceptions); 3 migrations + complex backfill (must match each old exception to a recurring availability row by running coach_availability_applies_on_date in SQL during the migration); UI restructuring required (exceptions become children of availability rows). DB auditor flagged backfill complexity HIGH risk.
• Option B alone (no inline button): rejected — misses the discoverability win at the point of friction. The manager would still need to navigate from the conflict panel to Add exception, manually pick the court she just saw in the conflict, manually copy the date and time. The inline button collapses this to one click.
• Option D alone — inline 'Ignore this conflict' button on top of A (no court_id column): the architect's mid-debate flip position in round 2. Rejected because under A the auto-injected exception is all-courts — same multi-court silent-destruction problem. D is strictly better with B's per-court scope. Both ship together.

Composite (a)+(b)+(c-without-the-DB-invariant). UI: drop the `> 1` guard at booking-players-input.tsx:266 (+ aria-label, data-testid, refocus search on empty). Dialog: onPlayersChange branches on `updated.length === 0` and fully resets organizer-derived state (guestEmail, guestFirstName/LastName/Phone, customerMatch, memberInfo, passInfo) so the wrong pick's member/pass/contact fields can't leak into the next submit. Backend: DELETE /api/admin/bookings/[id]/players promotes a remaining player to organizer when the organizer row is removed (mirrors the UI's handleRemovePlayer behavior; covers non-UI consumers too). Originally included a partial unique index `booking_players_one_organizer_per_booking` ON booking_players (booking_id) WHERE is_organizer = true with a fail-loud DO-block pre-flight check. **Update 2026-05-27T16:30: the partial unique index was REVERTED before prod deploy.** The pre-flight correctly aborted on 1 pre-existing prod booking (Alba Garrido, 2026-04-24) where bookings.user_id/guest_email point at Alba but Alba is not in booking_players at all (4 players present, 0 organizers). Filed as BUG-096. The partial unique would not have prevented this case anyway (it only guards >1, not 0), so re-introducing it requires deciding the orphan-organizer cleanup pattern first — out of scope for this PR. The application-layer invariant (POST/UI always sets is_organizer=true only for index 0; the new DELETE promotes a successor) is maintained without the DB constraint; the constraint was defense-in-depth, not load-bearing. Deferred (d) and several UX adjacents (labeled 'Change' affordance, click-crown-to-swap-organizer, dropdown disambiguation, full organizer-as-first-class column refactor) to follow-up PRs — blast radius (payment-link emails, check-in, TPS webhooks) warrants its own scope; dual-state risk between `guestEmail` and `players[0].email` is dormant today and this PR's parent-state reset closes the only active manifestation.

Alternatives considered

• Minimalist-only — drop the guard at line 266 and clear guestEmail on empty. Two lines, ships fast, but leaves member/pass info contaminated on the next pick AND leaves the backend DELETE asymmetric (a direct API caller deleting the organizer leaves the booking organizer-less, no DB invariant to catch it). Rejected: silent-error risk + asymmetric API surface.
• Add a labeled 'Change' button on the organizer row in addition to the X. UX Advocate's proposal; rejected because none of the four Operator Empathy scenarios (three Somchais, ghost duplicate, 'book under my wife's name', fat-finger iPad) are prevented by a labeled affordance — they're all remove-and-re-search flows that the X already handles. Industry refs (Calendly/Google Calendar/OpenTable/Resy/Booking.com Extranet) all apply to POST-creation organizer edits; this dialog is PRE-creation, where Cal.com / Square Appointments / Mindbody all use icon-only X + typeahead.
• Refactor 'organizer' into a first-class column (`bookings.organizer_player_id`) eliminating the dual source of truth between `guestEmail` state and `players[0].email`. Architecture Skeptic's smell 1+2. Rejected for THIS PR: blast radius covers payment-link emails, check-in flow, TPS webhooks via openrally-lesson-webhook — deserves its own scoped PR with separate review. Skeptic's own stress-test confirmed dormant-risk threshold.
• Add a CHECK constraint `≥1 organizer per booking` alongside the partial unique. Rejected: would block legitimate intermediate states in multi-statement transactions (e.g. promote-then-delete swap orderings in the route). Out of scope.

Two parts. (1) changeRecurrenceType (coach-schedule-editor.tsx:179) carries start_date/end_date across weekly/monthly/date_range switches. For days_of_week, the carry is ASYMMETRIC: date_range→weekly carries it (an explicit operator selection like 'Wed' is worth preserving), but weekly→date_range does NOT (a freshly-added row defaults to weekly+Mon as a non-empty placeholder — not an intentional selection — and silently carrying [1] into date_range would surprise operators who expected 'every day in range'). Switching to single_date drops everything. (2) When date_range has no days_of_week key, render all 7 chips as visually selected with muted '(all weekdays — tap to restrict)' helper text. On first chip toggle, materialize days_of_week to [all 7 except toggled]. If toggling brings the array back to all 7, collapse the key to undefined (omit from save). NEVER materialize [0,1,2,3,4,5,6] explicitly — that pollutes JSONB with a redundant default, breaks coalesceRows hash compatibility with pre-A+B rows, and makes an operator who never touched the chips have a row that LOOKS edited.

Alternatives considered

• Default to no days (empty array): means 'no days match' under our SQL — would render the schedule inert until the operator picks days. Hostile UX.
• Default to [0..6] explicitly: makes data shape uniform but breaks coalesceRows dedup against legacy rows and creates an artifact-of-edit on every newly-created date_range row.
• Don't carry fields across switches: simpler but matches no PMS we surveyed; operators expect their selections to persist as they experiment with the dropdown.

Yes — REWRITE validateProgramSessionsAgainstAvailability (packages/common/src/coach-availability.ts:185). (a) Drop the recurrence_type === 'weekly' filter. (b) Add a new required ProgramSpan { start_date, end_date } argument. (c) For each session, enumerate dow occurrences inside the span. (d) Require at least one row that applies on each occurrence AND covers the time window. This makes bounded weekly AND date_range[days_of_week] both program-compatible iff they cover the full span. Both callers (programs POST at apps/admin/src/app/api/admin/programs/route.ts:175, programs PATCH at apps/admin/src/app/api/admin/programs/[id]/route.ts:118) thread the program's effective start/end through. Without this rewrite, an operator who bounds a weekly schedule OR uses date_range[days] sees program creation silently fail with 'Instructor has no recurring weekly schedule' even though the schedule covers every session.

Alternatives considered

• Leave validator weekly-only: every operator who adopts A+B and then creates a program gets a confusing 'no weekly schedule' error. Silent failure mode — worse than the bug A+B was shipped to fix.
• Accept both shapes but skip the bounds check: bounded weekly with end_date < program end would be silently approved as 'covers the program' even though the row stops applying mid-program. Defeats the purpose of bounds.
• Validate against the materialized date set instead of recurrence shape: more robust but couples the validator to the 12-month materializer horizon; programs longer than 12 months would falsely fail.

Accept the semantic redundancy. Both shapes produce identical SQL filtering — coach_availability_applies_on_date returns the same boolean for the same (date, config) pair under both shapes — and identical materialized date sets via coach_availability_dates. The editor preserves whichever shape the operator chose: coalesceRows (apps/admin/src/app/api/admin/coaches/[id]/schedule/route.ts:254) uses JSON.stringify(recurrence_config) as bucket key, so the row round-trips as written. No DB-level normalization, no migration to collapse shapes.

Alternatives considered

• Normalize at write time (e.g., always store as weekly+bounds when days_of_week is present): hidden semantic flip — the operator picks 'Date range' on purpose and sees the row reshape itself on reload. Surprises analysts who read the table directly.
• Reject one shape with a CHECK constraint: forces operators to learn which on-ramp is canonical; breaks the dual-on-ramp UX that DEC-232 is designed to enable.
• Add a canonical-form view for analytics: solves analytics ambiguity but adds a layer of indirection. Defer until an analytics query actually needs it.

Ship A+B together as one feature in v0.29.0. (A) date_range.recurrence_config gains optional days_of_week — rows match dates in [start_date, end_date] AND in days_of_week if present. (B) weekly and monthly recurrence_config gain optional start_date/end_date — rows match the recurrence AND fall inside the bounds if present. Both fields are additive; omitting them preserves today's behavior. No new recurrence_type. SQL update lands in coach_availability_applies_on_date + coach_availability_dates (new migration); TS in packages/common/src/coach-availability.ts. No data migration of existing rows. No Rust changes (recurrence_config is opaque JsonValue on the Rust side). validateProgramSessionsAgainstAvailability is rewritten — see DEC-234. Editor preserves whichever on-ramp the operator chose — see DEC-233 (redundancy accepted) and DEC-235 (carryover + chip defaults).

Alternatives considered

• Option A only — day filter on date_range alone (smallest change, matches manager's literal navigation): rejected. Leaves the secondary complaint ('weekly takes this week into consideration') unfixed. Operators would hit unbounded-weekly the moment they want bounded recurring through a different on-ramp.
• Option B only — bounds on weekly/monthly alone (RRULE-aligned, matches Google Calendar / Outlook / Calendly / Acuity / Apple Calendar): rejected after round-2 of the multi-agent debate. PMS-domain product survey (Mindbody, Mews, Cloudbeds, Resy, Tock, Playtomic) showed operator-side scheduling tools are bounded-first, day-of-week-as-filter — opposite of personal calendars. Manager's 'range first, then days' is the domain-correct mental model, not a workaround. The personal-calendar survey was wrong-domain evidence.
• Option C — full RRULE (RFC 5545) faithfulness: every type gains bounds + day-of-week + interval + nth-of-month: rejected as over-engineering. Padel club operators don't ask for 'every other Wed', 'first Mon of month', or BYSETPOS features. Largest surface (~11–12 files / 5–6 new E2E tests / full materializer + Rust struct rewrite) for capability not on the roadmap. A+B doesn't block future C — every C addition is additive.
• Add a fifth recurrence_type 'bounded_weekly': rejected. Doubles type-discrimination surface across editor, validators, RPC, Rust, materializer. Only fixes Weekly — date_range[days] still needed for the manager's literal on-ramp. More code for less coverage.
• Normalize at write to a single canonical shape: rejected — see DEC-233.

(A) Add `.lte('start_time', now.toISOString())` to the bookings query so every downstream JS filter inherits a bounded window — fixes Bug 1 in one place for both the 7d cards and the 30d chart. (B) Replace the `12 * 60 * 7 * courtCount` constant with a new shared helper `apps/admin/src/lib/court-open-hours.ts → computeAvailableMinutes()` that reads `court_schedules` and sums per-(court, day_of_week) open minutes across the rolling 7-day window. Returns both `total` and `byCourtId` so the top-card and per-court tables share the same denominator. (C) Wrap every utilization percentage in `Math.min(100, Math.round(...))` as defense-in-depth — the formula is already bounded ≤ 100% when the window is correct, but a stale schedule (court closed in DB, bookings still on it) would otherwise read >100% again.

Alternatives considered

• Hot-patch only Bug 1 (add the upper bound) and ship the Math.min clamp without fixing the hardcoded denominator. Rejected per CLAUDE.md 'Architecture-first, not patches': the clamp would mask the wrong-denominator bug indefinitely — every new facility with non-12h hours would silently misreport utilization, just no longer >100%. Worse, because the clamp hides the error, nobody would notice.
• Read facility.operating_hours (the existing JSONB column) instead of court_schedules. Rejected: court_schedules is per-court and is the source of truth the availability + price + coach gates already use; operating_hours is facility-wide and not always populated. Using court_schedules keeps utilization aligned with what the booking-side enforces.
• Move both the bookings query AND the denominator into one SQL view / RPC. Rejected for this PR: would require a new migration and broaden the change footprint beyond a calculation fix. The TS helper is read-only and idempotent — same idea, no schema thrash. Worth revisiting if more reports get added.
• Switch the dashboard to fixed 'past calendar week' instead of rolling 7d so denominator and numerator perfectly align. Rejected: the current product surface is labeled '(7d)' = rolling; changing it is a product decision, not a calculation fix. The rolling-window numbers are correct after this fix (validated against prod read-only SQL: 218 bookings / 12,180 booked min / 20,790 available min = 59% utilization at PTP).

(1) One shared cancelLessonCascade() helper (apps/admin/src/lib/cancel-lesson-cascade.ts): idempotent (status-gated, link-nulled refunds), refunds package sessions once, cancels every linked court booking, then flips lessons.status='cancelled' so the existing emit_lesson_status_event trigger emits lesson_cancelled. Called from ALL three cancel surfaces — PATCH /api/admin/lessons/[id] (refactor), PATCH /api/admin/bookings (when the cancelled booking is lesson-linked via lesson_courts), and POST /api/v1/me/bookings/[id]/cancel. (2) Migration 20260525163034: emit_booking_event early-returns for booking_type='lesson', so a lesson's court booking never emits booking_* — lessons travel only on the lesson_* channel (DEC-226). The already-shipped TPS lesson webhook (padel-backend #211) then cancels the coaching record idempotently. No new protocol surface, no Rust change.

Alternatives considered

• DB trigger bookings→lessons cancel — rejected: package + credit refunds are app-level orchestration (refund_package_session per player + link-nulling); a trigger would split refund logic across SQL+TS and would also fire on the OpenRally/TPS-initiated cancel path that deliberately does NOT refund. A status-only trigger as defense-in-depth is acceptable later, but the load-bearing fix is the shared app helper.
• UI-only: make the calendar/bookings-list cancel call the lessons endpoint — rejected (architecture-first): leaves PATCH /api/admin/bookings orphaning lessons for every other caller (e2e, automation, the player self-cancel route). Fix the server contract once, not the 3 UI callers.
• Reuse cancel_lesson_booking RPC as-is for the admin path — rejected: it computes refund_eligible but does NOT refund package sessions (it's the consumer-initiated path where TPS refunds). Its status-gate + multi-court cascade pattern was adopted into the helper instead.

Mirror the forward gate's occupying set exactly: count confirmed / checked_in / completed AND active (non-expired) holds; exclude cancelled / expired / no_show. Include OTHER coaches' lessons (a reservation over another coach's lesson on the court is a real conflict); exclude THIS coach's own lessons (a reservation over the coach's own lesson is consistent, not a conflict). Only future/ongoing bookings (end_time > now()). availability_exceptions are NOT subtracted — both the route enumerate fn and the backstop trigger ignore them so the two layers agree.

Alternatives considered

• Confirmed-and-stronger only (ignore transient holds) — rejected: asymmetric with the forward booking gate, which treats active holds as occupying. The two directions of the same invariant must agree, otherwise a hold blocks a booking-vs-reservation but not a reservation-vs-booking.
• Subtract availability_exceptions (a booking on an excepted date is not a real conflict) — DEFERRED to a follow-up. The backstop trigger fires on coach_availabilities INSERT, before coach_schedule_replace inserts the same payload's exceptions, so the trigger cannot see them; making only the route exception-aware would let the route pass while the trigger rejects (self-inflicted inconsistency). Ignoring exceptions in BOTH layers is consistent and only ever OVER-flags (a booking on an excepted date is still listed) — it never MISSES a real conflict, so no orphan state can slip through. Exception-aware refinement (insert exceptions first + trigger reads them + route accepts proposed exceptions) is logged as a follow-up.

Hybrid. One shared SQL matcher (coach_availability_conflicting_bookings) consumed two ways: (1) coach_availability_booking_conflicts() enumerates ALL conflicts for a proposed payload — the PUT /coaches/[id]/schedule route calls it BEFORE coach_schedule_replace and returns a structured 409 listing every conflict (court + date + time + customer), writing nothing; (2) a per-row BEFORE trigger on coach_availabilities (coach_availabilities_check_booking_conflict_trigger) raises 'court_has_existing_booking' as the correctness backstop for the check→replace TOCTOU race and any future non-route writer. Migration 20260522082857, shipped/deployed BEFORE the feature PR per Hole 23.

Alternatives considered

• App-only pre-check (spec Option B) — rejected: re-introduces the exact pattern the context doc already rejected for the forward direction ('app-level booking gate only (no DB trigger)' — Hole 6/7/17). Leaves the reverse invariant unenforced at the DB and a TOCTOU gap. Verified single writer today (only coach_schedule_replace), but the no-debt/architecture-first bias plus the team's own recorded standard ('the gate lives in the DB') win.
• In-RPC, all-DB (spec Option A) — rejected: enumerating with court + customer NAMES means resolving presentation data in SQL and shipping it in a Postgres exception DETAIL payload (the 'presentation strings in the DB layer' smell CLAUDE.md warns against), and the route would re-query for display anyway.
• Naive per-row trigger only — rejected: a BEFORE INSERT FOR EACH ROW trigger RAISEs on the FIRST conflicting row and aborts, so it cannot enumerate ALL conflicts — violating the CEO's 'list everything' requirement. The trigger is therefore the backstop, not the UX path.

Extend the reverse-flow to admin-originated court bookings, origin-discriminated TPS-side. (1) Setpoint: new migration 20260520100304 adds primary_player_email (COALESCE(NEW.guest_email, customers.email via NEW.user_id)) + primary_player_phone to the emit_booking_event payload — bookings has no created_by column, so identity (not origin) is all the payload carries. (2) TPS (padel-backend, owned by TPS team): dispatcher routes booking_created to a new delegate_creation action; index.ts reuses its existing booking_third_party_references lookup as the LOOP GUARD — ref exists ⇒ TPS-originated ⇒ ack (no write); ref absent ⇒ admin-originated ⇒ ExternalBookingCreationService writes the full TPS-native row shape. CRITICAL: the BTPR key is the RAW or://setpoint/booking/<uuid> URI (NOT the bare uuid the lesson handler uses), because TPS's own outbound court bookings store the URI in third_party_reference and index.ts + the cancel path look up by it — diverging would silently miss the loop guard and break cancel.

Alternatives considered

• Thin write per the bug doc (bookings + booked_slots + BTPR only) — REJECTED. Empirically court bookings are match-centric: native confirm (bookingRepository.createMatchFromBooking) creates a matches row + 2 ephemeral_teams (booker on Team A) and links booked_slots.match_id, and EVERY My Bookings query is match-gated (getPastBookings/getUpcomingBooking use matches!inner; getAllUpcomingBookings reads from(matches) filtered by team membership). Without the match + teams the booking renders NOWHERE. Final shape: bookings → ephemeral_teams x2 → matches → booked_slots(match_id) → BTPR.
• Mirror the lesson handler's bare-uuid BTPR key — REJECTED. Lessons flow through the separate openrally-lesson-webhook which uses extractOpenRallyUuid end-to-end; court bookings flow through webhook-setpoint-booking-update/index.ts which keys by the raw URI. A bare-uuid key would make redelivery double-write and the existing cancel path skip (not_found).
• Blanket-write on every booking_created — REJECTED: double-writes TPS-originated bookings (the TPS→Setpoint→TPS round-trip). The BTPR-existence check is the discriminator that prevents this.
• Shared lesson+court writer abstraction — REJECTED (CLAUDE.md guidance + over-engineering): court maps to bookings type 'booking' with match/teams rows; lessons map to coach_reservations/coaching_slot_details. A dedicated per-type service is clearer.

(A) — revert DEC-205/DEC-208 and write full TPS-native row shape for OpenRally coach bookings in both directions. Forward flow (create-coaching-booking-v2 + confirm-coaching-booking-v2) writes coach_reservations at HOLD + flips to confirmed + inserts coaching_slot_details at CONFIRM, mirroring legacy lifecycle. Reverse flow (openrally-lesson-webhook) writes all 5 native rows (bookings, booked_slots, coach_reservations, coaching_slot_details, btpr) on inbound lesson_created. Cancel path already symmetric via existing webhook handler. Idempotent via btpr unique constraint. Costs paid once at the integration boundary — every downstream consumer screen renders unchanged.

Alternatives considered

• (B) Keep the simpler 'thin reference' shape and add OpenRally-aware branches in every TPS app screen that touches coach bookings (coaching list, booking detail, cancel flow, push notification handler, calendar widget, etc.) — rejected: ~5-8 screens minimum, forever. Each future consumer would re-implement the same branches. Defeats the protocol abstraction. Network roundtrip on every list render. Offline support breaks. The asymmetry strongly favors absorbing complexity at the integration boundary.
• (C) Hybrid stub + lazy-load (write a placeholder coach_reservations row but fetch details on tap) — rejected: still requires the placeholder to be shaped enough for list filtering, and adds a worse UX (spinner on every detail tap). Ends up needing the same row shape anyway, just with extra complexity.

(B) — webhook-driven writeback. The full chain: AFTER INSERT trigger on Setpoint `lessons` inserts an `or_events` row with `lesson_created` event including the primary player's email. The existing OpenRally webhook dispatcher (already live, line 37 of webhook_dispatcher.rs) POSTs that event to TPS's registered endpoint. A new TPS-side Edge Function receives the webhook, looks up the TPS user by email (per DEC-223), and writes the three rows TPS's existing UI reads from: `bookings`, `coach_reservations`, `booking_third_party_references` (mirroring the proven Sterling/Kross/Playtomic pattern). TPS's `ProfileCoachingScreen` and its `getMyCoachingSessions()` query are unchanged — they render the writeback rows identically to TPS-initiated bookings. Setpoint admin UI is also unchanged — the existing Create Lesson dialog with its email field is the only entry point. Cancel symmetry handled by the same Edge Function listening for `lesson_cancelled` events (already wired by `trg_lessons_emit_status_event`).

Alternatives considered

• (A) TPS polls a new OpenRally GET /lessons-by-email endpoint — rejected: polling has worst-case 5+ minute staleness, requires new OpenRally endpoint, requires TPS-side polling logic, and the existing webhook infrastructure already covers this exact case for free. Polling is the right pattern only when the producer can't push; OpenRally CAN push.
• (C) Shared DB read — TPS reads Setpoint Supabase directly — rejected: violates OpenRally's protocol boundary (TPS would gain a second source of truth), creates tight coupling that makes any Setpoint schema change a TPS-breaking change, and there's no existing pattern for cross-tenant DB access. Catastrophic for the consumer-agnostic principle.
• (D) Build a 'My TPS bookings includes Setpoint lessons via on-demand fetch' — TPS fetches per lesson via OpenRally GET on every render. Rejected: same polling problems as (A), plus n+1 fetches per ProfileCoachingScreen render. Latency unacceptable.
• (E) Hybrid push + verification poll — push via webhook, but TPS also polls on app open to catch missed webhooks. Rejected for v0.27.0: webhooks already have retry-with-backoff (3x exponential 1s/4s/16s), so missed-webhook scenarios are rare; if it becomes a problem, add later. YAGNI for the first version.

(b) — extend confirm_lesson_from_hold to insert the lesson_players row atomically with the existing bookings UPDATE. Two-part migration (20260515084759_openrally_confirm_lesson_inserts_player.sql): (1) CREATE OR REPLACE FUNCTION confirm_lesson_from_hold adding INSERT INTO lesson_players (lesson_id, user_id, email, phone, is_primary, payment_method) reading from the just-UPDATEd booking row, idempotent via NOT EXISTS guard, mirrors create_lesson_atomic column-for-column; is_primary=TRUE since OpenRally coach lessons are 1-on-1 by design (DEC-207). (2) One-row backfill for the existing OpenRally lesson already in prod (booking #59352 / lesson 3f0177c3-…) with WHERE clauses that structurally exclude admin-native lessons (lp.id IS NULL on the LEFT JOIN). Verified end-to-end via Android emulator on 2026-05-15 evening: new booking #59389 → lesson bc7a0c28-… auto-populated lesson_players (email=gianfranco+1@omnigpt.co, is_primary=true, payment_method=external). TC-143 extended with a lesson_players assertion to lock the regression.

Alternatives considered

• (a) Insert from the OpenRally Rust handler before calling confirm_lesson_from_hold — rejected: opens a race window where the booking could be confirmed but the player row missing (or vice-versa) if the Rust handler crashes between the two writes. Also leaves the RPC's documented contract ('hold → confirmed transition') incomplete: any future caller would have to remember to insert separately, recreating the bug.
• (c) Refactor all 10 lesson_players write paths into a shared helper RPC — rejected for this PR: scope explosion. Sub-agent audit found the 10 paths cover 4 distinct lifecycle operations (create initial player, add additional player, update payment/check-in, remove player) with different input shapes — a shared helper would have to handle all of them. Logged as optional follow-up; revisit when a 5th initial-create path is added.
• Insert from the TPS Edge Function (confirm-coaching-booking-v2) after OpenRally call returns — rejected: makes the TPS layer responsible for Setpoint's internal data shape. Violates consumer-agnostic principle (CLAUDE.md). Any other future OpenRally consumer (BookAndGo, Taykus, bots) would face the same empty-roster bug.

Read C — email-matching with ZERO TPS prod writes. Steps: (1) Pick any real existing TPS coach with populated users.email. (2) Mirror that coach into Setpoint admin's coaches table with the SAME email, mark default_class set at Pad Thai (the OpenRally-routed test club) so they're bookable via OpenRally. (3) OpenRally coach response payloads gain an `email` field + new `GET /coaches/by-email` lookup endpoint (additive, backward-compatible). (4) TPS discovery extension matches OpenRally coaches to existing TPS coach_profiles by `users.email = openrally_coach.email`; on no match, skip + warn (don't fail loud — protects against drift). (5) TPS booking dispatcher reads email from the coach_profile and calls OpenRally's /coaches/by-email to translate to Setpoint UUID, then proceeds with the lesson hold/booking. TPS prod stays read-only this release. The previous `openrally_coach_uri` column migration is dropped (deferred for the future automation work — see handoff-future-coach-mapping-automation.md).

Alternatives considered

• Dynamic lazy upsert into TPS coach_profiles (DEC-215 + DEC-222 as merged in #609/#612) — rejected for v0.26.0: greenfield writes against production tables with no existing INSERT patterns to reference; manual schema discovery raises real risk of broken triggers / missing NOT-NULL columns; cost of the safety guards (atomic, idempotent, observable) doesn't pay back at today's scale (1 OpenRally club, 1 coach). Keeps as eventual target — see deferred-work doc.
• Read A — manual one-time INSERT into TPS prod (keep the new openrally_coach_uri column + 2 stub rows applied by the TPS team) — rejected: still writes to TPS prod (2 INSERTs + 1 ALTER TABLE); same greenfield-schema-discovery risk; doesn't save much vs. Read C in scope; email-matching is cleaner because the link is the natural identifier the operator already manages.
• JSONB reuse — populate coach_profiles.config = {setpoint_coach_id} manually for the demo coach — rejected: same 2 TPS prod INSERTs as Read A, just no migration. Locks in a magic-JSONB-string pattern we'd refactor away from later; email-matching is more general and consumer-agnostic.
• Read B — put TPS ids into Setpoint admin (e.g., coaches.tps_coach_profile_id column) — rejected as consumer-agnostic violation: Setpoint admin must not bake TPS-specific identifiers. Future consumers (BookAndGo, bots) would each demand their own column. Reaffirmed in this round.

(4) Two-stage hybrid: /coaches/search is the cheap pre-filter and the authoritative distance source; /facilities/{id}/coaches/{id}/availability fills the slot times for coaches that pre-filtered positive on the requested date. TPS calls /coaches/search per OpenRally-routed club with the user's lat/lng + radius_km + ?date=, gets coaches with has_availability + distance_km, then fans out per-coach availability ONLY for coaches with has_availability === true. Skip the fan-out entirely for coaches the pre-filter excluded (saves N round-trips when most coaches have no availability that day). Maps the returned LessonSlotResponse[] into TPS's existing ClubCoachAvailabilityResult shape so filterCourtsByAllCoachesAvailability and downstream rendering work unchanged.

Alternatives considered

• (1) Existing v0.25.0 endpoints only, no /coaches/search — rejected: forces TPS to compute distance itself from facility lat/lng, re-baking geography knowledge into the consumer and violating the consumer-agnostic principle (CLAUDE.md). Also wastes slot-fetch round-trips on coaches with zero availability on the requested date.
• (2) Inline slot-level data in /coaches/search — rejected: breaks the just-shipped contract (response schema, integration test, OpenAPI), conflates discovery with calendar semantics, causes per-coach × per-date payload explosion that kills `Cache-Control: max-age=60` reuse, and violates the universal two-stage discovery pattern (thin search → per-item detail).
• (3) Drop /coaches/search entirely — rejected: same as (1) plus throws away forward-compatible infrastructure DEC-213/DEC-214 already locked. /coaches/search is NOT dead code — it's the cheap pre-filter for THIS flow and the authoritative distance source.
• (5) Background mirror sync (Approach B revival) — rejected: same as DEC-213. Webhook revoke is unenforceable; PII fanout remains.

(c) — per-court swim lanes inside each day-cell in all-courts mode. When `selectedCourt === "all"`, each cell flexes into one sub-lane per court (horizontal, left-to-right, ordered by the `courts` array so Court 1 is always leftmost). Each lane has its own empty `+` button bound to its specific court via a new `handleEmptySlotClick(d, tick, court)` signature; the `courts[0]` fallback is deleted entirely. Each lane independently renders its own bookings with a span based on duration. Day-column min-width scales to `max(110px, 36px × courts.length)` so lanes stay usably wide as court counts grow. The day-header shows a chips strip naming each court aligned to the lanes below. 2hr bookings span vertically within their own court's lane only (TC-142 invariant preserved). Single-court mode (when a specific court tab is selected) renders as one lane with no visual change — zero regression. New helpers: `getBookingsForCellAndCourt`, `isSlotOccupiedForCourt`. `data-testid` hooks on each lane and empty button (`week-lane-{ds}-{tick}-{courtId}`, `week-empty-{ds}-{tick}-{courtId}`) make the per-lane interactions assertable. TC-145 locks the new behavior.

Alternatives considered

• (a) Keep the aggregated cell and add a court-picker inside CreateBookingDialog — rejected: fixes defect 1 (ambiguous click target) but NOT defect 2 (empty `+` still disappears once any court is booked). Adds an extra click per booking even in the trivial one-free-court case. No industry product does this.
• (b) Overlay a `+` button on top of the bookings layer — rejected: the operator still can't tell which court the click maps to (equivalent to 'guess the first court' with extra steps). Click position would have to be reverse-mapped to a court via x-coordinate which is fragile and inscrutable.
• Patch only `handleEmptySlotClick` to fall back to a 'pick a court' modal — rejected: same as (a). Doesn't address the missing-click-target regression after the first booking.

TPS team applies migrations manually — same workflow as Setpoint. Verified 2026-05-14 by comparing local supabase/migrations/ in padel-backend (9 files) to the remote schema_migrations table in TPS prod (1 row, unrelated). The mismatch proves `supabase db push` is NOT used. The migrations directory is a change-log for code review and history; SQL is applied by a TPS team member via the dashboard editor or `supabase db query --linked --file` after PR merge.

Alternatives considered

• Assume TPS uses `supabase db push` and auto-apply — rejected: factually wrong, would risk applying our migration via a workflow they don't use.
• Set up CI to auto-apply — rejected: out of scope, TPS team's choice not ours, and CLAUDE.md bans `db push` to Setpoint prod anyway for the same reasons (uncontrolled migration ordering risk).

Merged. Single sorted list, no sectioning, no badge identifying source. The user sees 'coaches near me' and books one; the protocol is invisible.

Alternatives considered

• Sectioned with 'Powered by OpenRally' label — rejected: leaks implementation detail to user, breaks 'mobile UI/UX unchanged' contract operator stated, and matches no industry pattern (Kayak, OpenTable, ClassPass do not label by source).

Single optional `?date=YYYY-MM-DD` (facility timezone). Response includes `has_availability: boolean | null` per coach (null if ?date absent, boolean if present). Defer date-range and per-day slot counts to a later release.

Alternatives considered

• Date range with per-day slot counts — rejected: TPS mobile's current UI shows one selected day at a time, so the richer query is unused. Add when a consumer's UI actually needs week-at-a-glance.
• No time filter at v1 — rejected: forces N extra round-trips per search just to know which coaches have any slots at all. Single-date filter is the cheapest server-side gain.

Defer. No /facilities/search at v1. Reserve the path in the OpenAPI spec as 'planned' for future consumers to see the direction.

Alternatives considered

• Ship both endpoints at v1 — rejected on lean-now-extend-later grounds. No concrete consumer use case today: TPS uses its own clubs list (TPS-native, not OpenRally-sourced), and no other consumer has requested facility-first discovery.

Defer. OpenRally response does not include rating/review fields at v1. TPS mobile renders 'New' or hides the rating row for OpenRally coaches (TPS-side rendering decision). When Setpoint builds a review system (separate product cycle), the fields are added to the OpenRally response shape — purely additive, backward compatible.

Alternatives considered

• Build Setpoint review system before shipping D — rejected: multi-week scope (schema, write flow, moderation, spam, anonymity policy). Bolting it into a discovery PR is scope creep that delays the immediate demo blocker.

Add `coach_profiles.openrally_coach_uri text UNIQUE` to TPS DB (nullable). When TPS backend gets discovery results from OpenRally, it upserts a coach_profiles row keyed by URI. Mobile sees a normal coach_profile with a numeric ID, sends that ID back for booking, TPS backend reads the row, sees openrally_coach_uri is set, routes via OpenRally. Discovery still queries OpenRally LIVE on every search — the upsert is a translation cache, not the search index.

Alternatives considered

• Store the URI in coach_profiles.config JSONB (no schema change) — viable but weaker: no UNIQUE constraint risks duplicate mirror rows, no index slows lookups, no type check makes misformatting silent.
• Change TPS mobile to send URI strings for OpenRally coaches — rejected by operator constraint: mobile UI/UX must remain unchanged.
• Sync at provisioning via webhook (B-style mirror) — rejected per DEC-213 adversarial review: revoke is unenforceable.

Use existing facility-scoped api_keys as-is. /coaches/search resolves the key to its facility_id and restricts results to coaches at that facility. The endpoint NAME is forward-compatible (cross-facility-shaped URL) but the BEHAVIOR at v1 is per-facility-per-call. When a real second-facility use case emerges (TPS opens Pad Thai Sathorn, or a new consumer integrates with multi-facility access), extend the auth model then — driven by an actual use case, not speculation.

Alternatives considered

• Add consumer_label text column to api_keys — rejected as the worst-of-both: a half-extension with no FK integrity, no metadata place, no proper rotation primitive.
• Build consumers + consumer_facility_access + api_keys-with-FK proper model — rejected as premature: no concrete multi-facility consumer today, the refactor would touch admin UI + auth middleware + tests for a feature nobody is using yet.

Approach D: protocol-owned cross-facility discovery. Add `GET /openrally/v1/coaches/search` to OpenRally. TPS backend calls it during discovery, lazy-upserts results into coach_profiles via the new openrally_coach_uri column (DEC-214), merges with TPS-native coaches, returns to mobile unchanged. Discovery aggregation lives in the protocol (where it belongs), not in consumer code.

Alternatives considered

• Approach A — TPS backend fan-out per-facility (loop over OpenRally clubs, call /facilities/{id}/coaches per club, merge): rejected after adversarial sub-agent review. Bakes consumer-side aggregation into TPS that every future consumer would reinvent. Failure modes: O(N_facilities) latency, pagination semantics break across heterogeneous sources, ranking incoherence, same-coach-at-two-facilities causes duplicate cards with wrong booking routing. Violates 'Setpoint + OpenRally are consumer-agnostic' (CLAUDE.md) — bakes 'TPS is the single big consumer' assumption.
• Approach B — push-based mirror via webhook (Setpoint pushes coach data to TPS on every change): rejected by sub-agent review. Push-based mirrors cannot be reliably un-pushed; revoke is unenforceable if a consumer's webhook is down. Spreads PII without ownership. O(coaches × consumers) storage. Inverts the protocol from query-source to replication-pipeline.
• Approach C — full consumer entity refactor (consumers + facility_access tables, consumer-level keys) AT v1: rejected as premature — see DEC-214. Architecturally correct long-term but no concrete multi-facility consumer today; defer until real use case.

(b) — turn `enableSystem` off in apps/admin/src/app/layout.tsx and make the toggle read `resolvedTheme` (what's rendered) instead of `theme` (the chosen setting) in both apps/admin/src/components/ui/theme-toggle.tsx and apps/admin/src/components/admin/admin-sidebar.tsx. Drop the suppressHydrationWarning band-aids in admin-sidebar.tsx and replace with a proper mounted gate. No new UI surface. The two-mode toggle now actually means two modes.

Alternatives considered

• (a) Add a third 'system' option to the toggle UI — rejected: scope creep, the boss hasn't asked for it, and the toggle is already shipped in two-mode form. We'd be adding UI to expose a behavior we don't want as the default.
• Leave it as-is and document the OS-follow behavior — rejected: the UI lies. A two-button toggle that secretly has three states is a UX contract violation.
• Replace next-themes with a custom theme provider — rejected: massive scope for a 15-line bug. The library is fine; we just had a misconfigured option.

Extend the existing cancellation_policies table with `applies_to_lessons` (boolean, default true). Backfill existing rows to true. Existing operator UI in operations-settings-tab.tsx gains a third toggle. OpenRally cancel endpoint returns refund_eligible based on the facility's policy + hours-until-start.

Alternatives considered

• New table `lesson_cancellation_policies` parallel to the existing one — rejected: duplicates structure, splits the operator UX, and means the SQL helper functions that read v_policy in the booking flow get two cousins to maintain.
• Per-coach or per-class window column — rejected: more admin UI, more migration, no operator demand yet. Can be added later as a column on `coaches` or `classes` if needed.
• No TPS-initiated cancellation in v1 — rejected: worst player UX; player would have to message the club. Court bookings already let players self-cancel; lesson parity is the obvious move.

Add HTTP webhook out from OpenRally (lesson_created, lesson_modified, lesson_cancelled, plus existing booking_* events). Each facility configures one or more `openrally_webhook_endpoints` rows (url + signing_secret + event_types). Signed via HMAC-SHA256. Retries 3x with exponential backoff on 5xx/timeout. SSE stream stays — consumers can subscribe to either or both.

Alternatives considered

• SSE only — rejected: fragile under network drops, no retry, not the industry pattern for at-least-once state replication. No production system relies on SSE for billable state sync.
• Polling — rejected: high latency between Setpoint cancel and TPS reflecting it, bandwidth wasteful, and CLAUDE.md's built-in-first bias favors push notifications over polling when the protocol already has the option.

Mirror admin behavior: OpenRally lesson booking calls find_or_create_customer_by_email with the TPS user's email + name + phone. If the customer exists, lesson links to that user_id; otherwise a new customers row is created. Setpoint admin sees a real customer record (no 'guest' badge for TPS bookings).

Alternatives considered

• Guest lesson with no auth.users record (guest_email/guest_first_name/guest_last_name only) — rejected: breaks continuity if the same TPS user returns or signs up directly to Setpoint later. Also makes 'view this customer's lesson history' impossible from admin until manual claim.
• Store TPS user_id on the lesson as external_booker_id, no Setpoint customer — rejected: requires schema changes (new column) and adds polymorphism to a flow that's currently uniform. Doesn't fit the existing lesson_players model.

OpenRally lesson bookings get a hold phase identical to court bookings. New atomic RPC hold_lesson_slot mirrors hold_slot: inserts lesson + bookings + lesson_courts in 'hold' status with hold_expires_at = NOW() + ttl. Confirm RPC transitions to 'scheduled'/'confirmed'. Setpoint admin's direct-commit path is unchanged (admin trust is implicit; protocol consumers need the soft-lock).

Alternatives considered

• Skip the hold phase for lessons (mirror admin) — rejected: if TPS payment hangs or fails after the OpenRally call, Setpoint sees a phantom confirmed lesson with no payment, breaking operator trust. The hold phase is what makes the protocol resilient to consumer-side payment failures.
• Reuse bookings.status='hold' on the existing court rows, skip creating lessons row until confirm — rejected: increases state-machine complexity in OpenRally (hold metadata carries a lesson-to-be), and breaks the invariant that lesson_courts.lesson_id points to a real row.

V1 scope: 1-on-1 private single-court lessons only. Group lessons stay admin-only for v1 and will be handled in a follow-up feature (NOT through TPS events, per CEO override). Multi-court lessons out of scope entirely for v1.

Alternatives considered

• Include single-court group lessons in v1 (TPS player joins pre-scheduled group with open spots) — deferred: requires extra TPS mobile UI for 'X spots left' indicator and group-enrollment flow. CEO ruling 2026-05-13: 'first we will do 1:1 classes ... later we will work on group coaching case independently'.
• Include all lesson types — rejected as too large for v1; multi-court has no real demand yet.

Add `coaches.default_class_id` (uuid, nullable, FK to classes.id). Setpoint operator marks ONE class per coach as the TPS-bookable default via a dropdown on the coach edit page. OpenRally /coaches endpoint only lists coaches whose default_class_id is set. Coach edit page shows a 'Not bookable on TPS — set a default class' warning when null. The coach owns the relationship (one FK column on coaches, not a partial unique index on classes).

Alternatives considered

• classes.is_openrally_default boolean (with partial unique index on (coach_id) where is_openrally_default = true) — rejected: more constraint plumbing, and 'which class is the default' belongs on the coach, not the class.
• Cheapest matching class wins — rejected: operator loses control over which tier TPS players see. CEO ruling: 'option A for this' (operator-picked default).
• Expose all matching classes; TPS picks via a new UI step — rejected: violates the 'OpenRally is a backend protocol, TPS UI stays vendor-agnostic' principle (boss directive 2026-05-13).
• Assume one class per duration per coach, fail loud if multiple — rejected: fragile; one operator misconfig breaks TPS bookings on that coach.

Approach B — coaches as first-class resources. New endpoints: GET /facilities/{id}/coaches, GET /facilities/{id}/coaches/{coach_id}/availability, POST /lesson-holds, POST /lesson-bookings, POST /lesson-bookings/{id}/cancel. New URI variant: or://setpoint/lesson_slot/{coach_uuid}_{court_uuid}_{YYYYMMDD}_{HHmm}. Materializer extended to emit lesson slots in addition to court slots. SSE + webhook events get lesson_created / lesson_modified / lesson_cancelled types.

Alternatives considered

• Approach A — lesson as a court-booking variant with type tag and coach field on slots — rejected: TPS already separates coach booking from court booking at every layer (separate edge functions create-booking-v2 vs create-coaching-booking-v2, separate mobile screens booking_court_screen vs booking_coaching_screen, separate TPS-side tables coach_profiles/coach_availabilities/coach_reservations). Flattening them on the protocol side just forces re-splitting on both consumer sides.
• Approach C — courts carry optional coach metadata — rejected: doesn't match how Setpoint coaches work (a coach reserves a specific court for a specific window via coach_availabilities — they don't 'attach' to a court slot from elsewhere). Also doesn't match the TPS coach-first UX (pick coach → see slots) which would have to invert to (pick slot → see coach options).

Per-occurrence facilityLocalToUTC(localDate, clickTime, tz). Each occurrence's wall-clock hour stays the same regardless of DST transitions in the range. No millisecond addition anywhere in the recurring path.

Alternatives considered

• Keep `+ N * 86400000 * 7` for backward-bug-compat — rejected: Bangkok-only production today happens to dodge the bug, but v0.19.0 (international addresses) is about to ship and DST facilities (US/EU) would silently book the wrong hour for half the year. Fixing the latent bug costs nothing in this PR.
• Use Postgres `+ INTERVAL '7 days'` inside an RPC — rejected: keeps the daylight-shift bug (interval arithmetic in tz-aware columns is the same shape) and concentrates logic server-side without a real benefit; the JS path is the canonical source today.

Rewrite TC-116 to use the new shape (six atomicity scenarios preserved verbatim, inputs translated via a `recurrencePayloadFor(start, occurrences)` helper). Add TC-141 as a separate file dedicated to the new fanout + validation surface (multi-day, coach skip, error matrix, UI happy path). tc-075 and tc-078 each carry one line that sends `recurring_weeks` for unrelated reasons — migrated in the same PR.

Alternatives considered

• Keep `recurring_weeks` as a thin legacy alias only so TC-116 stays untouched — rejected: DEC-198's whole point is single source of truth. A read-only legacy alias would leak into autocomplete, docs, and the next test author's example list. Half a replacement is worse than a clean break in a pre-production repo.
• Delete TC-116, fold its scenarios into TC-141 — rejected: TC-116 is BUG-039's regression gate (atomicity guarantees that the new shape is orthogonal to). Keeping them in separate files preserves the regression story and prevents accidental dilution when TC-141 inevitably grows.

Pre-check coach reservations in Pass 1 alongside the booking-conflict check. The route calls `public.check_booking_against_coach_reservations(p_check_kind='court_booking', p_coach_id=NULL, …)` per candidate occurrence and treats the raise of `court_reserved_for_coach` as a skip with `reason: 'coach_reserved'`. Distinct reason in `skipped_occurrences` so the UI can say 'court reserved for a coach' instead of a generic conflict.

Alternatives considered

• Let the trigger raise during Pass 2 insert; catch and tag as generic conflict — rejected: collapses two semantically different reasons ('court already booked' vs 'reserved for a coach') into one bucket. Operators routinely treat them differently (coach reservations are an internal scheduling artefact, conflicts are real demand).
• Pre-check by re-implementing the recurrence-applies-on-date query in JS — rejected: that logic lives in `coach_availability_applies_on_date` and `availability_exceptions` joins. Duplicating it in the route guarantees drift.

Chips win. The clicked slot supplies the time-of-day for every occurrence and the default Start Date — its DoW is purely a chip pre-selection hint that the operator can deselect. Click Tue 5 PM, pick [Wed] → batch creates Wednesdays only, no Tuesday.

Alternatives considered

• Validate the click DoW is in chips — rejected: blocks the boss's natural flow ('I clicked any free Tuesday slot just to open the dialog; I actually want every Wednesday'). Validation would force the operator to deselect/reselect chips just to satisfy a phantom constraint.
• Always include the click slot as an anchor regardless of chips — rejected: produces a Tue + every-Wed batch that nobody asked for; confuses the 'every Wednesday for 4 weeks' use case the boss's QA comment specifically called out.

`skipped_occurrences: Array<{date: 'YYYY-MM-DD', day_of_week: 0-6, reason: 'conflict' | 'coach_reserved' | 'error'}>`. `skipped_weeks` is removed (DEC-198 hard break, no deprecation window). UI renders skipped dates with their reason ('Wed May 27 — court reserved for a coach'). `created_count`, `total_requested`, and `bookings` remain.

Alternatives considered

• Keep `skipped_weeks` indices and add `skipped_occurrences` alongside — rejected: two parallel shapes for the same concept invite drift, and the indices reference week numbers that no longer exist as a coherent unit.
• Return both `skipped_weeks` (deprecated) and `skipped_occurrences` (new) for one release — rejected: DEC-198 already mandates a hard break for `recurring_weeks`; carrying a half-deprecated companion shape is incoherent.

Chips only in this PR. The dropdown is pure UI sugar — picking 'Weekdays' just toggles five chips. Presets can ship in a follow-up without an API change.

Alternatives considered

• Chips + dropdown together — rejected: not blocking the boss's QA case (every-Wed scenario), and bloats the smallest-correct-PR.
• Skip presets entirely — rejected: the boss may still want them later; calling them out as deferred (not declined) keeps the option open.

Replace `recurring_weeks` entirely. New canonical fields: `recurrence_end_date` (YYYY-MM-DD, facility-local) + `recurrence_days_of_week` (number[] of 0-6). The route hard-rejects any request carrying `recurring_weeks` with `error: 'recurring_weeks_removed'`. The dialog's two callers (calendar-grid, week-calendar-grid) and the e2e tests (TC-075, TC-078, TC-116, TC-103) are migrated in the same PR.

Alternatives considered

• Keep both shapes for one release — rejected: half-deprecation in a pre-production repo leaves a legacy field in autocomplete, docs, and the dialog's payload type for no real benefit (no external callers; admin UI is the only known consumer). CLAUDE.md's pre-production-boldness bias says rip the band-aid.
• Translate `recurring_weeks` to the new shape inside the route — rejected: silent translation papers over stale callers; an explicit 400 makes them fail fast.

90-day soft cap (UI default + browser-enforced `max` attribute on the End Date input), 180-day hard cap (route rejects with `recurrence_exceeds_max`). Operators get the documented '90 days max' guidance but the API gives one safety budget if they really need a 6-month season.

Alternatives considered

• 90 days hard, matching the reference verbatim — rejected: no headroom. Operators occasionally book a full term (e.g., academy 12-week + buffer); a one-time 120-day batch wouldn't be unreasonable.
• Keep the 52-week cap — rejected: a slip in the date pickers can spawn ~52 conflicting occurrences. The new fanout multiplies that by the chip count (up to 7), so the failure mode is worse than the old `recurring_weeks` shape.

Rename `coach_schedules` → `coach_availabilities`, DROP `day_of_week` entirely, and move weekly data into `recurrence_config.days_of_week` via in-migration backfill. `is_available` was already dropped in A5 — the new exceptions table is the supported way to express unavailability. Single source of truth (the trigger + helper functions read `recurrence_config`, not the old column) and the table name finally matches what operators call it.

Alternatives considered

• Additive: keep `coach_schedules` name, keep `day_of_week`, add `recurrence_type` + `recurrence_config` jsonb — rejected: two sources of truth for weekly recurrence (the column and the jsonb) which inevitably drift, and the table name was never accurate (it was always availability windows, not 'schedules'). Pre-production, the rename cost is small and the cleaner schema is worth it. CLAUDE.md explicitly bans 'smallest blast radius' as a default for architectural choices.
• Drop `day_of_week` but keep the `coach_schedules` table name — rejected: the name was already wrong before A5 (it referred to 'when a coach is on the schedule', not 'when court/coach is reserved'); now that the table also holds monthly/single_date/date_range recurrence, 'schedules' is even less accurate. One rename in this PR is cheaper than two later.
• Rename only, keep `day_of_week` and ignore the jsonb's days_of_week for weekly — rejected: requires application code to special-case weekly rows (read column) vs. other types (read jsonb), instead of having one helper `coach_availability_applies_on_date(rec_type, rec_config, date)` that branches once on type.

Per-type bounds. `coach_availability_dates(rec_type, rec_config)` materializes exactly the row's occurrences: 1 date for single_date, generate_series(start_date, end_date) for date_range, and the 12-month forward cap only for the genuinely unbounded weekly/monthly types.

Alternatives considered

• Flat 12-month forward horizon for every recurrence type (A6's approach) — rejected: pessimizes bounded types unnecessarily. A single_date 18 months out would still be materialized as 365 dates in the function call cost just to compare against existing rows; date_range materializes its actual extent regardless.
• No horizon — let weekly/monthly enumerate forever — rejected: the trigger would never terminate.
• Defer overlap detection to the EXCLUDE constraint on (court_id, time_range) only — rejected: doesn't catch cross-type conflicts (e.g., a single_date that falls on a Monday vs. a weekly Monday rule at the same court). The whole point of the trigger is cross-type.

Both. The CHECK constraint enforces (start_time AND end_time both NULL) OR (start_time AND end_time both set with end > start). The trigger function branches: whole-day exceptions zero out the coach's applicable multirange for that date; time-windowed exceptions are aggregated via range_agg and subtracted from the applicable multirange. The booking trigger uses both paths against (coach, facility, date) so a customer booking 14–16 is allowed only if either a whole-day exception covers the date OR a time-windowed exception fully contains 14–16.

Alternatives considered

• Whole-day only — rejected: QA boss explicitly cited time slots, and operators routinely need to express '2-hour personal appointment' without dropping the rest of the day's availability.
• Time-windowed only (require operators to specify a 00:00–23:59 window for a whole day off) — rejected: clunky UX, and the CHECK constraint can model the cleaner shape natively.

Compute at query time. Each of the three routes already builds per-customer aggregates in JS over fetched rows (lastVisitMap, bookingCountMap, spendMap); extending those reducers with two more sources (pos_orders.created_at, facility_tickets.closed_at|opened_at) is a few lines per route with no new write-path complexity. `facility_customers.id → facility_customers.profile_id` is the existing join for the POS side; the customer-detail route already uses this exact pattern. Don't add a `customers.last_visit_at` column, don't add triggers, don't backfill.

Alternatives considered

• Denormalized `customers.last_visit_at` column maintained by three triggers (bookings INSERT/UPDATE OF start_time; pos_orders INSERT/UPDATE OF created_at; facility_tickets INSERT/UPDATE OF closed_at,opened_at) plus a one-time backfill UPDATE in the same migration — rejected: at ~3000 customers per facility (Pad Thai Padel scale), the query-time scan across 3 tables + JS reduction is fast enough that the read-path bottleneck doesn't exist. Adding 3 triggers introduces race-handling (what if two writers fire on the same customer concurrently?), bumps every order-line/ticket INSERT cost, and requires the one-time backfill to be re-runnable on `supabase db reset` — write-path complexity for a read-path problem.
• Hybrid: cache the value in a customers column refreshed by a periodic pg_cron job rather than triggers — rejected: introduces lag (a customer who just ordered food still shows 'Never' until the next cron tick), adds a cron job to monitor, and complicates `supabase db reset` semantics (the value would be stale immediately after reset until cron fires).
• Compute in a Postgres VIEW or materialized view — rejected: a VIEW would re-execute the 3-table aggregate on every query (no win over the route's existing JS reducers, plus the route also reduces tags/memberships/etc. in the same pass); a MATERIALIZED VIEW would need REFRESH triggers, which is just the column-with-triggers path in disguise.
• Only fix the list route, leave the detail route + segments preview pointing at bookings-only — rejected: the boss explicitly mentioned the customer detail page in the report (Alba's profile), and segment filters on `last_visit_days` would silently misclassify POS-active customers as inactive in the 90-day cohort. One definition of 'Last visit' across all surfaces is the right contract.

Fix here. Rename the SELECT to `price_amount` everywhere in the three CRM routes already being touched for E1. The customer-detail route's response keeps the `price_cents` field name in the JSON (API contract) — only the SQL column reference + internal usages move. This is a one-line-per-spot change that makes the E1 'no regression for bookings' DoD actually hold (otherwise the path was vacuously 'not regressed' because it was already broken). Out of scope (separate PR): the same typo in /api/admin/crm/customers/[id]/timeline (separate route) and crm/customers/[id]/page.tsx (UI render — the page reads the API's `price_cents` field, which the API still returns under that name).

Alternatives considered

• Defer the typo to a separate PR, weaken the booking-only assertion in tc-135 to a soft 'doesn't crash' — rejected: the E1 spec's DoD #3 'existing customers with only bookings still show their booking-based last_visit (no regression)' would hold vacuously since the bookings path was already broken. Without the typo fix, Alba's profile would show her latest POS order date and entirely ignore any bookings she has, which is a *new* regression introduced by E1 (the boss's complaint was about POS-only customers, not 'replace bookings with POS').
• Defer the typo + open a tiny follow-up PR — rejected (user choice via prompt clarification): the fix is 6 lines across files already in this PR's diff. Two PRs for the same feature is more reviewer overhead than one slightly wider PR.
• Rename the API response field from `price_cents` to `price_amount` to match the DB column — rejected as scope-creep: the customer-detail page UI consumes `b.price_cents` (apps/admin/src/app/[facility]/crm/customers/[id]/page.tsx:55 + :795). Renaming the field would force a UI change here too. Keep API contract; fix only the SQL column reference + internal arithmetic.
• Add a database VIEW that exposes `price_cents` as an alias for `price_amount` — rejected: solves a code typo with a schema object, and would mask the typo in any future SELECTs against the underlying table.

Keep the existing payment_status CHECK constraint as-is (pending|paid|refunded|partial_refund). The fix is two-part: (a) create_lesson_atomic flips bookings.payment_status to 'paid' inside the same transaction whenever payment_method='package' and consumption has succeeded — package-paid bookings ARE fully paid; the only differentiator is the *method*, and payment_method already captures that; (b) the badge UI on booking-detail-dialog.tsx and bookings-list.tsx derives the new 'Paid with Package' label from (payment_status='paid' AND payment_method='package'). Existing 'Paid'/'Refunded'/'Partially Refunded' variants are unchanged.

Alternatives considered

• Add 'paid_with_package' to the payment_status CHECK constraint and migrate existing rows — rejected: payment_status is the *state* of the payment, payment_method is the *means*. Folding the method into the state duplicates information already on the row (any consumer querying for payment_status='paid_with_package' could equivalently query for payment_status='paid' AND payment_method='package'). It also opens a combinatorial mess if a future method joins (paid_with_credits? paid_with_stripe?) — every new method would force a payment_status enum extension AND a CHECK migration AND code-paths everywhere querying payment_status.
• Add a 'payment_status_display' column rendered by the DB and read verbatim by the UI — rejected: presentation logic in the data model. The UI is where labels live; mirroring strings into a column means the next change (translation, copy tweak) requires a migration.
• Backfill via an out-of-band script (e.g., manual SQL Editor run after deploy) — rejected: bundles state with deploy timing. The backfill is part of the same migration file as the RPC change, in one transaction — fully reproducible on `supabase db reset` and atomic on prod via `db query --linked --file`.
• Update the booking row to a four-state status the moment the package is debited — equivalent to the rejected enum extension, no new information.

Editor switches from a single Scope-target dropdown to a list-of-rows pattern (modeled on coach-schedule-editor.tsx): row 1 defaults to 'Anything in this domain' as today; an 'Add target' button below the list appends a new row defaulting to the first non-`any` option for the current scope_domain (so the operator's intent for granular targeting is reflected immediately, avoiding a jarring 'any twice' default). Each row has a Trash icon to remove. A soft amber warning surfaces when 'any' is mixed with specifics (since `any` makes the others redundant), but save is not blocked — operators may have legitimate reasons (e.g. authoring partial rules, intermediate state). Empty targets[] is rejected at both UI and API layers (400) instead of silently defaulting to `any`, since a rule with zero targets applies to nothing and the silent default hides operator error. Rules-list page gains type-labeled target chips so multi-target rules are visible without opening the editor (full name resolution would need an extra fetch and is deferred). The API routes (POST + PUT /api/admin/crm/discount-rules) already accept and persist targets[] of any length — only the empty-array check was new.

Alternatives considered

• Multi-pick checkbox / chip input instead of list-of-rows — rejected: the booking domain has many courts (10+ options for some facilities), a checkbox grid is awkward, and 'any vs specific' semantics are clearer in a row-based layout. The list-of-rows pattern is also already established in this codebase (coach-schedule-editor) so operator UX stays consistent.
• Filter targetOptions per-row to prevent duplicates — rejected as over-engineered: the resolver handles duplicate target rows correctly (after the EXISTS fix in DEC-190), the soft 'any-mixed-with-specifics' warning catches the only meaningful confusion, and filtering would add complexity around initial-state edits where existing rules might already contain duplicates.
• Silently default empty targets[] to [{ target_type: 'any' }] (the previous behavior) — rejected per CLAUDE.md 'No silent errors' bias: a rule with zero specified targets is operator intent of 'apply to nothing', not 'apply to everything'. Surfacing the 400 forces the caller to be explicit.
• Disable 'Add target' when all targetOptions are exhausted — rejected: tracks state we don't otherwise track (which options the user has already picked), and the resolver already deduplicates correctly. Operators picking duplicate rows is harmless.
• Resolve target names server-side and return label strings on the rule list — rejected for now: the GET /discount-rules response would need a JOIN per target, and the chip-with-type-label is enough for the boss's DoD ('labels visible OR equivalent rendered indicator'). Full name resolution can be added later if operators ask.

Fix in this PR. New migration supabase/migrations/20260511054837_fix_resolve_discounts_target_dedup.sql replaces the JOIN with EXISTS: `WHERE ... AND EXISTS (SELECT 1 FROM crm_discount_rule_targets t WHERE t.rule_id = r.id AND <target match conditions>)`. The outer query no longer multiplies by t, so each rule appears at most once. EXISTS short-circuits at the first matching target so 'OR across targets' semantics are preserved. Function signature and return shape unchanged — all callers continue to work. Idempotent CREATE OR REPLACE FUNCTION; safe to re-apply. For single-target rules (every existing prod rule before this PR) the output is byte-for-byte identical.

Alternatives considered

• Defer to a follow-up PR — rejected: this PR is shipping multi-target rules, and shipping the feature with a known double-count bug latent in the resolver is exactly the regression operators will hit. Ship the fix atomically with the feature it enables.
• SELECT DISTINCT r.id, r.name, ... — works but has to enumerate every column in the SELECT/DISTINCT, more brittle to add new fields to the jsonb_agg projection. EXISTS keeps the projection clean.
• GROUP BY r.id (with appropriate aggregates) — collides with jsonb_agg's existing ORDER BY r.stackable DESC, r.priority DESC, r.created_at DESC. Possible but less clean than EXISTS.
• Keep the JOIN and add a SELECT DISTINCT inside a CTE — works but extra ceremony for the same outcome. EXISTS is the canonical PostgreSQL way to express 'does at least one matching row exist?'

Enforce per-court coach reservation at the DB-trigger layer with strict-Calendly semantics. Schema: coach_schedules gains court_id NOT NULL REFERENCES courts(id), drops is_available (absence of a row = unavailable), gains a generated time_range numrange column, and a no_court_overlap EXCLUDE constraint (no two coaches reserve the same court+day+time-range). A shared SQL function check_booking_against_coach_reservations is wired into three triggers: bookings (BEFORE INSERT/UPDATE — rejects court/match bookings overlapping any coach's reservation on that court+day; lesson-typed bookings skip and rely on lesson_courts), lesson_courts (BEFORE INSERT/UPDATE — strict-Calendly: range_agg(coach reservations on this court+day_of_week) must @> the lesson's time range), and lessons (AFTER UPDATE OF coach_id/start_time/end_time/status — re-runs the lesson_courts validation when the lesson's window shifts). Errors raise SQLSTATE P0001 with a JSON DETAIL payload; apps/admin/src/lib/translate-coach-error.ts translates them into operator-readable messages on bookings, lessons, hold, and the schedule editor. The migration also rewrites hold_lesson_slot and create_lesson_with_bookings to set booking_type='lesson' on the bookings they insert (otherwise the new bookings trigger correctly rejects those holds as court_reserved_for_coach for any coach reserved on the booked court).

Alternatives considered

• App-layer-only enforcement (validate in /api/admin/bookings + /api/admin/lessons routes, no DB triggers) — rejected: every consumer (admin, web, OpenRally, future POS, Edge Functions, direct DB inserts in tests/seeds, manual SQL Editor work in prod) would have to re-implement the rule, and any miss is a silent contract violation. The triggers move the rule to a single enforcement point that all writers must pass through.
• Keep coach_schedules as a coach-level rather than per-court availability and add a separate court_reservations table — rejected as a mid-fix data-model split: every operator UX surface (calendar, schedule editor, public availability) would need to read both tables and reason about their intersection. Putting court_id directly on coach_schedules collapses the concept (availability = reservation in this product) and avoids a JOIN in every query.
• Permissive lesson check (lesson allowed even if it extends past the coach's reservation, treating the reservation as a 'preferred' window) — rejected after the user pushed back on the initial 'flexible' recommendation in round 3 of stress-testing. Industry-standard scheduling products (Calendly/Acuity/Mindbody/Booksy) reject scheduling outside the provider's published window; permissive semantics would invite operator surprise when a coach silently picks up an out-of-window lesson. Strict-Calendly is the sane default.
• Add a no_coach_overlap EXCLUDE preventing the same coach from reserving two courts at once — rejected on second pass: multi-court group lessons (one coach teaching across two courts simultaneously, num_courts > 1 in classes) need exactly that pattern, so a hard exclusion would block a legitimate product use case. Only no_court_overlap (no two coaches on the same court at once) survives at the schema layer.
• Solve via the validateSessionsAgainstCoachSchedule() shared validator in packages/common/src/coach-schedule.ts only (no DB triggers) — rejected: the validator already enforced no-empty-schedule semantics at the API layer, but tests and seeds insert directly via the Supabase admin client, bypassing it. The DB triggers catch every writer including those direct inserts, and the validator becomes a friendly-error fast-path instead of the source of truth.

Architectural rework. Add `crm_discount_rules.is_auto_mirrored boolean NOT NULL DEFAULT false` as the structural marker, replacing every `name LIKE 'auto:%'` reference (unique partial index, both auto-mirror trigger functions, all consumer code). Add SQL helper `public.credit_tier_label(slug text) RETURNS text` (IMMUTABLE, STRICT) as the single source of truth for the four-tier slug→label map; the credit-tier sync trigger calls it. Backfill in the same migration: flip is_auto_mirrored for rows whose actor_id matches a real source row (rigorous predicate, not a blind name-prefix UPDATE), strip the legacy 'auto: ' prefix from name, rewrite credit-tier names to use credit_tier_label(tier_name), replace internal 'Auto-mirrored from <table>.<column>' boilerplate descriptions with operator-facing UX copy ('Mirrored from Loyalty → Memberships' / '→ Wallet'). Drop the prior partial unique index keyed on `name LIKE 'auto:%'` and create a new one keyed on `is_auto_mirrored = true`. UI deletes its TIER_LABEL map + prettifySnake + isAutoRule + formatRuleName + formatRuleDescription helpers and renders r.name / r.description directly; the auto badge reads from r.is_auto_mirrored.

Alternatives considered

• Keep the v0.24.1 UI patch (TIER_LABEL map + regex parser + name-prefix sniff) — rejected: CLAUDE.md mandates pre-production boldness and architecture-first fixes. Three smells (enum duplication, magic-prefix marker, regex re-parsing) compound: the next auto-derived rule type (e.g. holiday surcharge mirror) would repeat the hack, and POS/Terminal consumer code would inherit it.
• Add a `tier_label` text NOT NULL column to credit_tier_configs and have operators set the label per row — rejected after stress-test as over-engineering: the slug list is a fixed 4-value enum (validated by `validTierNames` in the credit-tiers API route), there's no operator-creates-custom-tiers product feature, and CLAUDE.md's 'Don't design for hypothetical future requirements' rule applies. A SQL helper function captures the same map without widening the schema.
• Drop the auto-mirror triggers entirely — make resolve_discounts() UNION crm_discount_rules with virtual rows derived from membership_plans + credit_tier_configs at query time — rejected as out-of-scope: this is a fundamental architectural change to the resolver pattern from v0.24.0 (mirroring → no-mirror) that would invalidate the CRM page's edit/audit story (auto rules currently appear as editable rows; under the no-mirror design they don't exist as rows). Worth its own decision later, not bundled into this fix.
• Add `is_auto_mirrored` but skip the credit_tier_label SQL function — keep the snake_case slug in name and have the UI prettify on render — rejected: solves only half the problem. The DB still emits 'hall_of_fame tier discount' and the UI still needs a slug→label map. Centralising the map in SQL means triggers produce already-pretty names and the UI renders verbatim.
• Use a TS shared module (packages/common/src/credit-tiers.ts) for the slug→label map instead of a SQL function — rejected: the consumer that needs labels is the credit-tier trigger (PL/pgSQL), which can't import TS. Triggers building 'auto: ' || slug || ' discount' was the original sin; the fix has to put the label resolution where the trigger can reach it, i.e. in SQL. The TS-side validator only needs the slug list (no labels), so no shared module is required.

Land the engine + admin only — pure foundation, no POS/Terminal consumer code. In scope: the SQL foundation (5 new crm_* tables, polymorphic actor validation trigger, resolve_discounts() + commit_discount_applications() functions, calculate_member_price refactor delegating to the resolver, auto-mirror triggers on membership_plans + credit_tier_configs, ALTER pos_orders + pos_order_items for the locked-in Deliverable B columns, RLS), the admin API surface (15 endpoints for groups + discount-rules CRUD + members + preview + applications + customer-detail discounts), the admin UI (sidebar + /crm/groups + /crm/discount-rules + customer-detail panel), and the admin PMS booking-route wiring (resolve + commit post-insert) which serves as the canonical consumer pattern. The pos_orders.discount_kind / discount_note + pos_order_items.is_foc / foc_reason columns ship as the locked-in contract for the consumer. Defer: POS/Terminal consumer wiring (BUG-082, delegated to POS/Terminal dev — see plan-pos-terminal-discount-integration.md), OpenRally protocol bump (BUG-073, boss decision pending TPS-Setpoint integration go-live), Programs/Open-matches surface wiring (features nav-hidden today; 'program' reserved in scope_domain enum), Lesson + program consumer wiring (BUG-074), legacy POS group-stack retirement (BUG-075, POS-dev-owned), Deliverable B cashier-typed UI + per-line FOC affordance (UX design pending).

Alternatives considered

• Land all 6 milestones (M1–M6) including OpenRally — rejected: TPS-Setpoint integration not live; member-aware Rust code can't be validated end-to-end. Boss explicit: skip M5.
• Land only the database foundation (M1) — rejected: user explicit 'we have all the time in the world, do everything in one PR'. M2–M4 + M6's data plumbing all ship together for one atomic boss-reviewable PR.
• Hard-cut the legacy POS group tables in this PR — rejected: POS dev (2026-05-06) confirmed those tables are 'suspended' but he owns retirement on his timeline. γ pure: leave them functional, add the new engine alongside.
• Land the cashier ad-hoc + FOC UI in this PR — rejected: UX design implications (gating, receipt template, manager-PIN threshold) need designer/operator review before shipping. Schema is ready; UI is one focused follow-up PR.
• Wire the POS + Terminal apps in this PR (initially in scope) — rejected on 2026-05-07 after build-quality review with the user: ownership lives with the code's author. The POS/Terminal dev owns apps/pos and apps/terminal; if a discount-related bug surfaces at the till post-launch, they should not be reverse-engineering code I wrote under deadline. Cleaner seam: ship the engine + contract + the admin booking route as the canonical consumer pattern; the POS dev's agent mirrors the pattern in their own PR. The 250 lines of consumer code reverted in this branch were causing tight coupling between the engine and POS-specific cart conventions (how I plumbed into useOrderMutations, how the resolver line maps to a cart line item) that the dev is better positioned to choose. Tracked as BUG-082 with the full handoff in plan-pos-terminal-discount-integration.md.

Render two independent stacked Card sections — Memberships (top) and Wallets (bottom). No tabs. The Memberships section holds subscription Plans configuration plus a Pending Payments sub-list (orphan user_memberships awaiting Stripe Checkout); its CardHeader carries the Assign Membership entry point. The Wallets section holds tier configuration (tier-config-tab no longer wraps its own Card; the parent Wallets card provides the chrome). Per-customer browsing is delegated to CRM Customers (`/crm/customers` and the detail page), which already exposes membership, wallet balance, and tier per customer. The unified-members-list.tsx component is deleted with no compat shim.

Alternatives considered

• Keep the unified Members tab but render it as a third section above the two — rejected: contradicts the boss's 'two sections' framing and re-introduces the redundancy with /crm/customers (which already lists every customer with full filters/search/tags).
• Drop the unified list entirely with no replacement — rejected: tc-110 specifically tests the orphan-payment-link flow (admin assigns a plan, customer pays later), and the only UI entry point lived on the unified Members tab. Removing it without a replacement would either skip the test (forbidden by CLAUDE.md) or strand the orphan-payment flow.
• Move the orphan-payment-link affordance to the CRM customer detail page instead of the Memberships section — rejected: it's an operations queue, not a per-customer attribute. Operators routinely scan 'who haven't I closed payment with yet?' across all orphans, not one customer at a time. Also: bigger diff (new API surface, new UI on a different page), more selectors to migrate.
• Use raw `<section>` + `<h2>` instead of Card — rejected: every other admin settings-style page uses Card (operations-settings-tab, facility-settings-form). Consistency wins.
• Use an accordion / collapsible — rejected: the boss explicitly contrasted 'sections' with 'tabs' — the intent is visibility-by-default, not a different toggle.

Drop all four columns from credit_tier_configs and rewrite calculate_credit_tier to no longer return them. Tiers are now exactly threshold + court_discount_pct — symmetric to how subscription plans expose price + discount_percentage. Operators on either side configure 'qualify at X, discount Y%' and that's it.

Alternatives considered

• Keep the columns + label them 'coming soon' — rejected: the pre-prod boldness rule. We'd be shipping known-fake configurability on the operator UX. The user explicitly called out the wrap-around 'Program (%) (%)' label as 'awful' — leaving the field in even after a label fix would still surface a control that doesn't do anything.
• Hide from UI but keep columns + RPC fields — rejected: leaves dead schema, confusing API consumers (web's use-my-credits.ts typed all four), and pretends a future PR might wire them. Pre-prod = clean break.
• Wire booking_window_days now (BUG-036) — rejected: scope creep on a feature that's about parallel subscriptions/tiers, not booking-window enforcement. If a future loyalty PR wants per-tier booking windows, it can re-add the column with the enforcement at the same time.

Use a 'better-of' rule. Compute the subscription discount % (from active user_memberships row's plan.discount_percentage) and the credit-tier court_discount_pct independently. If both apply, take GREATEST(sub_pct, tier_pct). If only one applies, use that. If neither applies, no discount. The membership_model JSON key in facilities.settings is no longer read by the pricing engine and is no longer exposed by /api/v1/facilities/{slug}/membership-plans or /api/admin/credit-tiers. Pricing-rule member_price_amount remains a hard per-slot override (operator's exact 'member rate' for a slot) ahead of either percentage path. tier_name surfaces only when the tier path wins (or ties) — never when subscription wins outright.

Alternatives considered

• Stack the discounts (apply both successively) — rejected: easier to game than to understand. Customers who hold both already paid for the subscription; stacking encourages 'collect every discount' optimisation that's hard for operators to model.
• Subscription always wins (hard override) — rejected: punishes long-time topup customers who eventually subscribe to a small plan; a subscriber with 5% subscription beats a Hall-of-Fame tier with 15%, which is the wrong consumer signal.
• Cap the combined discount at some ceiling — rejected: adds an admin knob nobody asked for. Better-of is already bounded by the larger of two configured values.
• Keep the toggle and add a third 'parallel' value — rejected: the toggle has zero load-bearing reason to exist post-better-of. Simpler to delete.

Rename ONLY the operator-visible surface — sidebar nav label, page H1, route path (/memberships deleted, /loyalty added — clean break, no redirect), and the 'Membership Model' settings card → 'Loyalty Model'. Leave DB tables (user_memberships, membership_plans), API routes (/api/admin/membership-plans, /api/v1/memberships/subscribe), the membership_model JSON key in facilities.settings, the 'membership-model-select' data-testid, and component file names (memberships-page-client.tsx etc.) untouched.

Alternatives considered

• Full rename including API routes — rejected: API rename is a breaking change for OpenRally and any future external consumers; the value (operator clarity) is on the UI side only.
• Full rename including DB tables — rejected: requires migration + RLS-policy rewrites + RPC updates; pure naming churn for zero operator benefit.
• Rename component files (memberships-page-client.tsx → loyalty-page-client.tsx) — rejected: lots of import-site churn for low payoff; the file name is internal-only. The plan explicitly marked this as optional and skip-fine.
• Keep 'Memberships' — rejected: operator-side, the page is no longer scoped to paid memberships. 'Loyalty' covers subscriptions AND credit tiers AND wallet engagement.
• Add a /memberships → /loyalty 308 redirect (initial choice) — rejected: pre-production, admin app is auth-walled, no search-engine indexing, zero internal callers (verified by grep). A redirect for hypothetical bookmarks is exactly the kind of backwards-compat shim CLAUDE.md says to avoid. Old URL just 404s.

Tie every credit add to a paid payment row and let a DB trigger mint the wallet transaction(s). Cash and Stripe both flow through payments.status pending → succeeded for type='credit_topup'; the grant_credits_on_topup_payment trigger maps payment_method (stripe → customer_payment, cash → admin) and calls record_credit_transaction. Bonus credits get a second transaction with source='system' on the same payment_id. Six transaction types collapse to three (topup, booking_payment, booking_refund); is_topup is dropped (subsumed by type='topup'); a CHECK invariant enforces topup⇒payment_id-and-no-reference_id and booking_*⇒reference_id-and-no-payment_id. record_credit_transaction is the single write RPC and raises insufficient_balance with structured DETAIL on overdraft instead of clamping to 0. Trigger idempotency guarded by WHEN (NEW.status = 'succeeded' AND OLD.status IS DISTINCT FROM 'succeeded') so Stripe redeliveries don't double-credit.

Alternatives considered

• Keep two RPCs but rename + add invariants — rejected: the duplicate-write surface was the original sin; renaming it doesn't fix the operator-facing 'which button do I click?' problem or the fact that bonus_amount lived in two unrelated places.
• One RPC with a `source` parameter, no trigger — rejected: every call site has to remember to pass the right source. The webhook would have to flip status AND call the RPC, which means two writes that can desync. Trigger consolidates the contract to a single FROM-payments edge.
• Keep adjust_club_credits and add a payment_id column passively — rejected: silent-clamp behaviour is wrong for booking_payment (you cannot pay for a court with credits you don't have) but right for refunds. The plan calls for raise-not-clamp; that would have broken refund call sites that relied on clamping. record_credit_transaction is a clean break.
• Stripe webhook owns the trigger logic in TypeScript — rejected: cash path doesn't have a webhook. Putting the wallet write in two different layers (webhook for Stripe, PATCH endpoint for cash) is exactly the duplication we're collapsing. DB trigger is the one place both flips converge.

Keep both. Document the deviation in the migration header and in this decision. Update wallet_evals.sql so the schema-shape assertion no longer requires either column to be dropped. Loyalty PR (sister scope) can revisit memberships rename and decide on stripe_price_id afresh; tier-based pricing's relationship to booking_window_days is a different conversation that doesn't belong in a wallet PR.

Alternatives considered

• Drop both as the plan said, fix the breakage as it surfaced — rejected: would have broken 5+ files including E2E tests for an unrelated PR (memberships) and the Model B pricing calculator. Worse, neither column was actually 'redundant'; the audit was stale.
• Drop stripe_price_id but keep booking_window_days (partial compliance) — rejected: stripe_price_id has equally clear active uses. Half-applying the plan without justifying why one drop was wrong is worse than rejecting both.
• File a follow-up to drop both later — rejected for stripe_price_id (its replacement model is a memberships rename in the loyalty PR; that's where the call lives) and rejected for booking_window_days (it's actively rendered in the API; nothing 'dead' about it).

One mount, on the CRM customer detail page, in the overview tab between the stat cards and Membership. Strip the side-panel mount, point TC-117 at the CRM page. The CRM page already houses notes, tags, bookings, ratings, KPIs — wallet belongs there too, not buried in a side-panel that only opens after a row click.

Alternatives considered

• Both mounts, perpetually — rejected: two mounts of the same component is duplication. The side-panel was a placeholder, not a deliberate second surface.
• Side-panel only, defer CRM mount to a follow-up — rejected: the CRM customer detail page is where operators do everything else for a customer; sending them to a separate /customers list to add credits is a UX regression even if the side-panel works.
• New dedicated /wallet page per customer — rejected: violates the 'one customer, one page' shape of the CRM. Wallet is a section, not a screen.

Batch in TypeScript, reuse the existing per-row RPC unchanged. The route splits into two passes: Pass 1 conflict-checks every week and builds a viable-weeks list; Pass 2 calls create_booking_with_credits once per viable week. Before Pass 2 starts, the route pre-checks the customer's balance against `viable.length × price` and returns HTTP 400 if they can't afford the full set, so we never enter a partial-debit state. A per-week RPC failure (rare race) skips that week with no orphan ledger row, mirroring how the existing loop already handles per-week INSERT errors.

Alternatives considered

• Write a new batch RPC that takes an array of (start, end) tuples and loops in plpgsql — rejected: would force the conflict check to also live in SQL (it currently lives in the route, where the rest of the booking-create logic lives), and would duplicate validation already in create_booking_with_credits. Centralising in SQL also makes partial-success-on-conflict semantics harder to express cleanly than a JS loop.
• Wrap all N weeks in one all-or-nothing transaction (SAVEPOINT-per-week with batch commit) — rejected: changes the semantics. Today, conflict on week 2 still creates weeks 1, 3, 4 (best-effort partial success); operators rely on this. An all-or-nothing batch would refuse the whole request on any conflict, which is a UX regression for a fix that's only meant to repair the credit ledger.
• Do the deduction once for the whole batch via a single adjust_club_credits call with amount = -N × price, separate from the per-week INSERTs — rejected: that's exactly the non-atomic structure that caused BUG-021 in the first place. If the third INSERT fails, the customer's wallet is already debited for all N weeks.
• Pre-check up front, then use create_booking_with_credits' own internal balance check as the only line of defence (no batch pre-check) — rejected: without the pre-check, a 4-week request with credit for only 3 would create weeks 1-3 and fail week 4 with `Insufficient`, leaving the operator to figure out a partial state. The up-front pre-check gives a clean error before any write.

Add a new wrapper RPC public.create_booking_with_credits that does INSERT INTO bookings RETURNING id then calls adjust_club_credits(p_reference_id := <new booking id>, ...) inside one implicit transaction. The route handler delegates to the new RPC for single-booking + payment_method=credits + price>0 only; everything else (non-credits, free-on-credits, recurring) uses the direct insert path unchanged. adjust_club_credits is not touched. Validation of sufficient balance is done in the wrapper (RAISE EXCEPTION 'Insufficient club credits...') because adjust_club_credits clamps negative results to 0 — relying on it for sufficiency would silently under-deduct.

Alternatives considered

• Modify adjust_club_credits to accept an optional booking-insert payload — rejected: it's called from four other paths (refund, top-up, match payment, cancel auto-refund); broadening its contract for one consumer would risk the others and force every caller to handle a new return shape.
• Wrap the three steps in a Postgres function that calls the existing INSERT directly (no new RPC) — same as chosen, just structured differently; the wrapper-RPC framing makes the boundary explicit and lets the route call a single named function.
• Use a SERIALIZABLE transaction at the application layer via Supabase JS — rejected: the JS client doesn't expose multi-statement transactions on a single connection; the only realistic path to atomicity is server-side (RPC or Edge Function).
• Edge Function — rejected: extra HTTP hop with no upside for code that can run as a SECURITY DEFINER plpgsql function.
• Fix the recurring path in the same PR — rejected (scope guard from prompt): recurring already has a different, more dangerous bug (it never deducts credits at all, see BUG-039), and a correct fix needs its own atomicity story for the N-week loop. Bundling them would balloon the diff and the test surface.
• Add a feature flag / fallback to the old non-atomic flow — rejected: a quiet auto-fallback would re-introduce the bug silently; loud failure between merge and the manual SQL run is preferable per the deploy ceremony.

Strict mirror of the court per-player flow, deviating only where the lesson data model forces it. Four sub-decisions: (1) Sibling function checkInLessonStudent next to checkInPlayer in packages/common/src/check-in.ts — same shape, same return type, reuses derivePricing/resolveFacilityCustomer/buildBookingLineItem helpers. (2) New admin endpoint PATCH /api/admin/lessons/[id]/students keyed by lesson_id (not booking_id) — multi-court lessons would otherwise be ambiguous on /bookings/[id]/.... (3) Per-student tickets attach to the primary lesson_courts.booking_id (is_primary=true); the 'all in' flip spans every booking row linked to the lesson via lesson_courts. (4) Pricing reads each student's lesson_players.payment_method × class.price_per_pax_amount — pending students get pricePerPax on their own ticket so the till can collect from them individually. Court's 'organizer pays the booking_price, everyone else 0' model does NOT apply (lessons charge per-student per DEC-147–149). Schema gets one new column: lesson_players.checked_in_at. Tickets do NOT get a lesson_player_id FK — match court's existing ticket_name match pattern; a unified participant_id is tracked as followup #1.

Alternatives considered

• Extend checkInPlayer with a lesson branch — rejected: the table differs, the 'all in' check spans N booking rows, and the pricing formula differs. Branching one function would be messier than two siblings sharing helpers.
• Postgres RPC — rejected for the same reasons as DEC-174: auth.admin.createUser() can't run inside Postgres.
• Edge Function — rejected for the same reasons as DEC-174: HTTP hop with no upside for a route that's already server-side.
• Admin-only this PR, terminal as follow-up — initially considered to keep the diff small, walked back: DEC-174 explicitly ships parity together so both surfaces stay aligned. The shared module is the hard part; terminal's plumbing (hook + query extension + sheet section) is small and ships in the same PR.
• Add lesson_player_id FK to facility_tickets in this PR — rejected: court tickets don't have booking_player_id either, so the schema asymmetry would be worse than the matching ticket_name fragility. Followup #1 retrofits both surfaces in one cleanup.

One unified Type column (Court / Coaching / Event badge via the existing BookingTypeBadge) replaces Coach + Match. Created On becomes the leftmost sortable column AND the default sort (created_at desc), so the most recently booked row sits on top. Date/Time column renamed to Booking Time for clarity. Add to Calendar button removed from the booking detail dialog and its orphaned lib/ics.ts deleted. Existing Court/Coaching chip filter preserved as-is. Date range filter inputs widened from w-36 to w-48 so the native picker content no longer overflows. No tabs, no separate routes, no schema change.

Alternatives considered

• Split Court vs Coaching into two top-level sidebar entries — rejected by boss: solves a non-problem and adds navigation depth.
• Tabs on the bookings page (Court / Coaching) — rejected by boss for the same reason; an earlier iteration shipped this and was rolled back before merge.
• Keep the chip filter AND the dedicated Coach/Match columns — rejected: redundant; Type column conveys the same info, and per-row Coach/Match details are better surfaced inside the detail dialog.
• Add an updated_at column + trigger so operators can also sort by last modified — rejected: bookings table has no updated_at today, and adding one is a schema change out of scope for a UI cleanup.

Shared TypeScript module at packages/common/src/check-in.ts with two exported functions (checkInBooking, checkInPlayer). Both admin (PATCH /api/admin/bookings + PATCH /api/admin/bookings/[id]/players) and terminal (useCheckInBooking + useCheckInPlayer hooks) import and call these functions. The module is pure: it takes a Supabase client + a findOrCreateProfile(email, name) injection as parameters, so each surface passes its own auth context (admin → service-role client + findOrCreateUserByEmail; terminal → user-JWT client + findOrCreateGuestAccount server action). Results are discriminated unions (`{ ok: true, ... } | { ok: false, code, message }`); admin maps ok/false codes to NextResponse status codes, terminal re-throws so react-query's onError fires exactly as it did before. The module also unifies three safety checks that existed only on admin: full-booking idempotency (via ticketMode: 'idempotentIfExists'), per-player ALREADY_CHECKED_IN precheck, and full rollback on per-player ticket failure (reverts booking_players.checked_in_at AND bookings.checked_in when the latter was flipped by this check-in). Terminal gains all three as strict safety improvements — no happy-path UI changes.

Alternatives considered

• Postgres RPC — rejected: auth.admin.createUser() cannot be called from PL/pgSQL, so the flow would split into DB-side RPC + app-side wrapper and the rollback would have to cross the seam.
• Supabase Edge Function — rejected: adds a Deno cold-start + HTTP hop for admin which is already server-side. Reasonable to revisit only if a third consumer appears (mobile app, webhook) that can't link TypeScript.
• Keep admin's 3 defensive checks admin-only, move only the shared 95% — rejected: introduces behavior flags (the Flag Argument anti-pattern) for no benefit. The 3 checks are defensive improvements every caller benefits from, not admin-specific policy.

Full parity with terminal, ported inline into admin (server + UI). Two endpoints: (1) PATCH /api/admin/bookings with checked_in=true mirrors useCheckInBooking — resolves facility_customer via profile RPC → email lookup with auth-account creation (findOrCreateUserByEmail) → fallback profile-less insert; allocates ticket number; writes facility_tickets with a populated cart_json booking line item (isBooking, isPrePaid/isUnpaid from payment_method, bookingRef, bookingDisplayPriceCents); idempotent. (2) PATCH /api/admin/bookings/[id]/players with {player_id, checked_in:true} mirrors useCheckInPlayer — sets booking_players.checked_in_at, creates a per-player ticket (organizer pays the court fee line, non-organizers get ₿0), flips bookings.checked_in=true only once every player is checked in; rolls back on failure. UI matches terminal: per-player rows show a Check-In button OR 'checked at HH:MM' + ticket number; booking-level button becomes 'Check In All (N)' when players.length > 0 and is hidden once everyone is in. enrich-bookings.ts now returns checked_in_at + ticket_number per player (cross-referenced to facility_tickets by ticket_name). All ticket notes / times use the facility timezone.

Alternatives considered

• Extract the shared flow into a Postgres RPC that both surfaces call — rejected for this PR: the guest-account creation step needs Supabase Auth admin APIs (auth.admin.createUser), which cannot run inside a Postgres function. Would require a thin app-layer wrapper anyway.
• Build a Supabase Edge Function that both admin and terminal invoke — rejected for this PR: cleanest single-source-of-truth option, but adds an HTTP hop from a route that already runs server-side, and would require changes to terminal (currently out of scope). Revisit as a follow-up.
• Ship only booking-level parity and defer per-player — rejected: boss asked for full terminal parity in one PR, including per-player check-in and the matching 'Check In All' UX. Split would leave admins unable to back-office check-in split-cost bookings.
• Remove admin check-in entirely and force all check-ins through the terminal — rejected: admins legitimately need a back-office check-in path (phone check-ins, pre-event prep, fixing missed check-ins).

Organizer pays in full. The lesson's primary player (is_primary=true) becomes the payer; a single Stripe Checkout Session is created for price_per_pax × player_count. When the webhook fires, every lesson_players row on that lesson is marked paid with its per-pax share so reporting rolls up correctly. The multi-player radio picker in the admin UI is removed — admin clicks Get Payment Link once per lesson regardless of player count. No data-model changes; only endpoint, UI, and webhook logic simplified.

Alternatives considered

• Keep the per-player flow shipped in v0.21.2 — rejected: admin had to repeat the action once per player (click menu → open dialog → pick player → send → close, ×N). Painful at 4+ players and inconsistent with the court-booking one-link-per-booking pattern.
• Add a 'Send to all players' bulk-send button on top of per-player — rejected: keeps the complexity of per-player sessions + webhook metadata for no real benefit; still need a picker for the 'just one player' case; more code surface than the revert.
• Add a cost-splitting toggle now — rejected: DEC-152 already deferred cost splitting to a future web-app feature; a UI toggle with only one state (full) is misleading until the other state actually ships.

Decouple. OpenRally materializer emits atomic slots at a fixed 30-min stride regardless of pricing rules. Pricing rules continue to define bookable durations (60/90/120 etc.). Availability endpoint accepts a requested duration only when (duration % 30 == 0) AND (duration >= min pricing-rule duration).

Alternatives considered

• Keep the 2026-04-16 behaviour (stride = min pricing-rule duration) — rejected: forces operators to create fake small pricing rules to get finer start-time granularity, conflating 'what the facility prices' with 'what the calendar displays'.
• Add a facility.slot_stride_minutes column with default 30 — deferred: adds schema surface with no current operator need. The 30-min default covers every consumer app (admin, mobile, web). Revisit if a facility ever asks for 15- or 60-min stride.
• Hardcode 30-min in the mobile/admin clients and leave OpenRally emitting hourly — rejected: pushes presentation logic into every consumer, duplicates generation code.

Admin day and week grids render 30-min ticks with hour labels only on :00 rows and a lighter gridline at :30 (Google Calendar pattern). Duration chips in create/edit booking dialogs are 60/90/120 min (was 60/120/180).

Alternatives considered

• Keep hourly grid + add a 30-min override toggle — rejected: two modes complicates QA and muscle memory.
• Label both :00 and :30 — rejected: visually noisy; industry standard is single label per hour.

Admin-only across three surfaces (court bookings, lessons, memberships). Public-web Memberships stays hidden. The admin flow closes the collection gap for BUG-019's descendant case — admin-assigned unpaid memberships — plus extends to lesson and court bookings on boss's direction so the same collection primitive covers every admin-side revenue surface.

Alternatives considered

• Unhide the public-web Memberships page so players self-serve — rejected: public web isn't production-ready for memberships, and the boss wants admin-initiated collection for hand-held onboarding
• Leave it as manual WhatsApp/email with URLs generated out-of-band — rejected: no audit trail, no facility branding, no 'paid externally' capture path

Stripe Checkout hosted URL. All Checkout Sessions use session.url verbatim — no custom page, no embedded Payment Element.

Alternatives considered

• Embedded Stripe Payment Element on a Setpoint-hosted page — rejected: expands PCI scope, forces us to rebuild the mobile/Apple-Pay/Google-Pay UX that Stripe already provides free, adds no value for an admin-to-player share flow
• A custom Setpoint redirect page that bounces to Stripe — rejected: adds a hop with no purpose; admins share one URL, that URL must be the real thing

Two separate buttons rendered side by side. 'Get Payment Link' = existing copy flow (POST, shows read-only URL + Copy button). 'Send via Email' = reveals an inline recipient-confirmation panel showing 'Send to alice@example.com' with Confirm + Cancel; on confirm, POSTs the sibling /email endpoint, sends via Resend, toasts success, AND displays the generated URL so the admin has a copy.

Alternatives considered

• Single button with a dropdown offering Copy or Email — rejected: one more click for the common case (Copy) and hides the Email affordance
• Send-on-click without confirmation — rejected: emailing a third party from a list view is exactly where fat-finger mistakes hurt; Gmail's Undo-send, Stripe Dashboard's confirm, and Intercom's confirm-step all exist for this reason
• Generate once and let the admin choose to email the existing URL — rejected: complicates client state (what if URL expired between generate and email?); two stateless endpoints is simpler

Separate /email sibling routes per surface. Four pairs total: bookings/[id]/payment-link + /email, lessons/[id]/payment-link + /email, user-memberships/[id]/payment-link + /email, memberships/payment-link + /email. Each route is stateless — it creates a fresh Stripe Checkout Session on every call; the /email variant also resolves the recipient server-side, invokes the edge function, and returns { checkout_url, session_id, sent_to }.

Alternatives considered

• POST /payment-link with { send_email, recipient? } in the body — rejected: two verbs behind one URL, harder to rate-limit independently, and the client always needs the URL back anyway so the copy-vs-email distinction is only about side-effects
• POST /payment-link that returns the URL + a separate POST /send-email that accepts an already-generated URL — rejected: stateful client, URL could be stale, double round-trip

Three granular edge functions: send-booking-payment-link, send-lesson-payment-link, send-membership-payment-link. Each is self-contained — it renders its surface-specific HTML + plain-text template, calls Resend, and returns 200/5xx. A small inline helper for the Resend fetch + HTML shell is duplicated across the three files (not extracted to a shared package) to keep each function independently deployable.

Alternatives considered

• One dispatcher function with a type discriminator — rejected: one deploy failure takes down three flows, and the template logic dwarfs the dispatcher logic anyway
• Inline Resend calls in the Next.js route handlers instead of edge functions — rejected: diverges from the existing pattern (send-booking-confirmation, send-match-invite, send-program-enrollment are all edge functions); keeps templates next to Stripe webhook email sends

notifications@omnigpt.co (same domain as send-booking-confirmation), with display name = facility name. Single SPF/DKIM/DMARC surface across all transactional email — deliverability stays consistent as volume grows.

Alternatives considered

• Per-facility sender domain read from crm/email-settings — rejected for v0.21.2: requires facility-side DNS work; revisit when a facility actually asks for branded sender
• A new domain dedicated to payment emails — rejected: more DNS to maintain, no deliverability benefit at current scale

Server-side resolution per surface: Booking → bookings.guest_email → fallback auth email via user_id. Lesson → the player selected in the inline picker (auto for single-player lessons). User-membership row → auth email via user_memberships.user_id. Plans-tab typeahead → auth email of the picked user. If no email resolvable, the 'Send via Email' button renders disabled with tooltip 'No email on file'; the 'Get Payment Link' (copy) button stays enabled so admin can still hand-share via WhatsApp.

Alternatives considered

• Let the admin type an arbitrary recipient email in a free-text field — rejected: spam risk, typo risk, no audit trail linking email to user
• Send to every player on a multi-player lesson — rejected: one Stripe Checkout is per-payer; fanning out would require N sessions and confuses 'who owes what'

No persistence. Each POST creates a fresh Stripe Checkout Session. Stateless, idempotent-per-call, zero schema migration. Stripe Checkout Sessions expire after 24h anyway — persisting a URL would routinely surface stale links.

Alternatives considered

• Store session_id on the parent row and only regenerate if expired — rejected: adds a column, a TTL check, and a race window for negligible UX gain
• Cache the URL in-memory for N minutes on the route — rejected: multiple instances in prod, cache invalidation is a bug farm

v0.21.2 patch. Builds directly on the v0.21.1 webhook-hardening (orphan adoption is the exact path exercised by admin-assigned memberships paying via this new flow). v0.22.0 is allocated to Unified Calendar and v0.23.0 to OpenRally Payment Sync; injecting v0.24.0 for a small cross-surface UI addition would mis-advertise scope.

Alternatives considered

• v0.24.0 minor — rejected: overstates the size; this is three UI buttons + four admin API routes + three edge functions, no schema change
• Fold silently into v0.21.1 retroactively — rejected: v0.21.1 is shipped, immutable

Add an optional `payment` block to POST /openrally/v1/bookings (echoed in all booking responses + SSE/webhook event payloads). Three required fields (status / method_type / external_ref) plus optional amount/currency. Vendor-neutral enums (`paid|pending|partial` and `prepaid|pay_at_venue|comp|credit|other`); consumer-specific detail (Stripe PI, PromptPay txn, Kross ref, etc.) lives behind the opaque `external_ref` string. OpenRally never interprets the ref — it's stored and echoed for PMS-side audit only. Backward compatible: legacy consumers (BookAndGo, Taykus, pre-1.1 TPS) that omit the block continue to land bookings as payment_status='pending'. OpenAPI bumped 0.1.0 → 0.2.0.

Alternatives considered

• Extend Setpoint's existing payment_method enum with vendor-specific values (e.g. 'tps_stripe', 'tps_promptpay') — rejected: couples protocol to TPS
• Embed card tokens / full payment shape in the protocol (OTA XML-era approach) — rejected as over-engineering; Stripe Connect / Google Reserve use opaque refs for the same reason
• Make payment a separate /bookings/{id}/payment sub-resource — rejected: fragments the single-booking create flow into two round trips and adds idempotency surface

Extend `emit_booking_event()` to watch `payment_status` and `payment_method` in addition to existing columns. A change on either fires a `booking_modified` event with the full payment block in the payload, which flows through the or_events → webhook_subscriptions → delivery worker pipe already shipped 2026-04-20. Closes the reverse-sync gap reported in scenario B (TPS pay-at-club booking settled in person → admin marks paid → TPS never knew).

Alternatives considered

• A new event type `payment_updated` distinct from booking_modified — rejected as adding consumer complexity for no new semantic (every existing modified-consumer already handles booking_modified)
• Rely on consumers polling GET /bookings/{id} — rejected: defeats the push model shipped 2026-04-20
• Keep payment_status out of the watch list and require consumers to call a separate endpoint — rejected: fragments the surface, violates the "same pipe as cancellation" principle

Add a new enum value `'external'` to the bookings_payment_method_check constraint (alongside the existing stripe|credits|pending|other|package). When payment_method='external', two new columns MUST be populated: `external_payment_ref` (opaque consumer string) and `external_payment_method_type` (the OpenRally v1.1 protocol enum: prepaid|pay_at_venue|comp|credit|other). DB-level consistency CHECK enforces this.

Alternatives considered

• Reuse the existing 'other' value — rejected: admin reports lose the ability to segregate 'paid via external system' from miscellaneous legacy payments
• Collapse method_type into payment_method (values like 'external_prepaid', 'external_pay_at_venue') — rejected: tight coupling between local enum and protocol enum makes future protocol evolution a migration

No reverse sync for manual admin overrides — changes stay LOCAL to Setpoint. The admin UI (booking-detail-dialog) intercepts the Mark-as-Paid click on external-paid bookings and shows an inline amber warning panel explicitly stating "Changes made here will not sync back to the originating system". Admin must click "Override anyway" to proceed. The local PATCH still fires the booking_modified webhook (DEC-159), but consumers that receive it are advised in the protocol docs to treat local overrides as audit-only unless they explicitly opt into accepting them.

Alternatives considered

• Automatic reverse sync: send a PATCH /openrally/v1/bookings/{id}/payment back to the consumer — rejected: introduces echo/loop risk and requires consumers to define who's source of truth for payment state
• Disable the Mark-as-Paid button entirely on external-paid bookings — rejected: operators legitimately need the override for edge cases (consumer system outage, manual reconciliation at the front desk)
• Silent local override with no warning — rejected: surprises admins when their change doesn't reach the consumer

Every `.insert()`/`.update()`/`.rpc()` in apps/admin/src/app/api/v1/webhooks/stripe/route.ts now checks `.error`. On any unexpected error the handler logs structured context (`event.id`, `event.type`, the operation that failed, redacted identifiers — never PII or full payloads) via `console.error` and returns HTTP 500, so Stripe retries the delivery and the failure surfaces in both the Stripe Dashboard Event deliveries tab and Vercel logs. For checkout.session.completed on type=membership_subscription specifically, the handler now probes for an existing active row on (user_id, facility_id) *before* inserting: if present and its stripe_subscription_id is NULL (orphan from a prior Stripe account or admin manual-assign), it UPDATEs that row in place to adopt the new subscription; if present with a *different* non-null sub_id it returns 500 (don't silently overwrite a concurrent subscription).

Alternatives considered

• Catch only unique_violation on the insert and retry as UPDATE (reactive try/catch approach — less explicit, couples error handling to a specific Postgres error code at the SDK layer)
• Add an upsert with onConflict targeting the partial unique index (Supabase JS upsert + partial indexes need careful ignore_duplicates/onConflict handling; more magic, harder to reason about failure modes)
• Run a one-off migration to mark orphan active rows as `expired` and rely on existing INSERT path (one-time fix; does not prevent future orphans from admin manual-assign or account-switch scenarios, still leaves swallowed-error bug unfixed elsewhere)
• Return 200 even on unexpected errors to avoid webhook retry noise (matches pre-fix behavior; exactly the bug that caused BUG-019 — silent prod failures)

Single event source (`or_events` table) with two independent delivery paths. A Postgres trigger `emit_booking_event()` writes to `or_events` on booking lifecycle changes. Path A: OpenRally SSE stream `/openrally/v1/stream` (untouched — served by the Rust protocol server for live-dashboard / channel-manager consumers). Path B (new): `webhook_subscriptions` table + `fan_out_or_event` trigger on or_events + `webhook-delivery-worker` edge function that POSTs Stripe-style envelopes (`id`/`type`/`created`/`data`) with 10s/60s/600s retry backoff and dead-letter. TPS consumes via Path B (new inbound edge function `webhook-setpoint-booking-update` in padel-backend).

Alternatives considered

• Pure SSE: add a Dart SSE client to the mobile app consuming /openrally/v1/stream directly
• Direct DB triggers calling pg_net.http_post to TPS's webhook (no subscriptions table, no retry model)
• Supabase Realtime on bookings publication, consumed by the mobile app

Lock cost split to 'organizer pays in full' in admin app. The toggle is visible but disabled. Per-player cost splitting (each player pays their share) is deferred to the online/web app booking flow as a future feature.

Alternatives considered

• Allow split + credits: deduct only organizer's share from credits, leave rest pending
• Disable credits entirely when multiple players (too restrictive)
• Allow split + per-player payment collection in admin (complex, not needed for walk-ins)

Add confirmation_code column to bookings table. Format: SP- + 6 alphanumeric chars (30-char alphabet excluding 0/O/1/I/L). Generated server-side at booking creation/confirmation. Stored once, read everywhere. Postgres trigger as safety net.

Alternatives considered

• Continue deriving references client-side from UUID (status quo — causes inconsistency)
• Use sequential numeric codes (risk: exposes booking volume)
• Use first 8 UUID chars like the web app already does (not human-friendly, still hex)

Use the existing booking_type column. Fix match booking creation to set booking_type='match' (was defaulting to 'court'). Backfill existing match bookings via migration. Add type filter param to admin search API and type filter badges to admin UI.

Alternatives considered

• Derive type client-side from joined match/lesson data without fixing booking_type
• Create a new enum column instead of using the existing text column

Add payment_method (text, nullable) and player_package_id (uuid, FK to player_packages) columns to the existing lesson_players table.

Alternatives considered

• New lesson_player_payments junction table
• Store payment info in a JSONB column on lessons

Purchase time. Package revenue is recognized when the package is purchased (lump sum). Per-lesson revenue only counts non-package players to avoid double-counting.

Alternatives considered

• Count all players as revenue (current behavior — double-counts packages)
• Show both non-package revenue and package sessions consumed separately

Keep it for backward compatibility with private lessons. Private lessons use lesson-level package (one package covers all players). Group lessons use per-player payment on lesson_players.

Alternatives considered

• Remove lessons.player_package_id entirely
• Make all lessons use per-player payment including private

Per-player. Each player in a group lesson pays individually — via their own package session or other payment method. Group lessons are public classes that players join independently.

Alternatives considered

• Per-lesson: one player (or booking party) pays for all players
• Keep current: primary player's package covers the whole lesson

Yes — both POST and PATCH endpoints validate player count against class max_pax. Return 400 if exceeded.

Alternatives considered

• Client-side only validation
• Soft warning without blocking

No — player name comes from customers JOIN via user_id. For guests without accounts, display email as identifier.

Alternatives considered

• Add name column to lesson_players for guest display

No — min_pax is informational only. Lessons can be created with 0 players. Operators need flexibility to create lessons first and add players later.

Alternatives considered

• Enforce min_pax as hard constraint on save
• Warn but allow save

Yes — private lessons can have multiple players (e.g., couple's padel lesson). class_type is about session format (dedicated vs shared), not headcount.

Alternatives considered

• Force max_pax=1 for private class type

No — player removal just deletes the lesson_players row. Payment/refund is a separate concern handled through the payments system.

Alternatives considered

• Auto-refund on removal
• Prompt admin to handle refund

No — recurring lessons is a separate feature. Build it in its own PR after multi-court and multi-player are both merged.

Alternatives considered

• Add recurring lesson toggle to the lesson form now, handle multi-court in the generation logic

No — skip for now. Admin picks specific courts by name from a list, so mixing is a user choice, not a bug. Only relevant for facilities with mixed sport courts.

Alternatives considered

• Add sport_type filter to available-slots API and only count same-sport courts toward num_courts

Deferred — we are focusing on admin app only. The admin POST /api/admin/lessons already validates this. Public API will be fixed when the public web app is updated for multi-court.

Alternatives considered

• Fix it now to prevent invalid holds from any client

Build court editing in PATCH now — cancel old bookings, create new ones, update lesson_courts.

Alternatives considered

• Defer to a follow-up PR and use cancel+recreate as a workaround

Show on both court rows with a visual link (matching color, icon, '1/2' and '2/2' labels).

Alternatives considered

• Show only on primary court row with '+1 court' badge
• Show on both rows with subtle indicator (dot or border)

No — keep dots as approximate 'something is available' hints. Per-day detail APIs filter by num_courts when user drills in.

Alternatives considered

• Make range API accept num_courts and check N courts free simultaneously
• Check minimum num_courts across all active classes

price_amount = 0. Lesson-type bookings exist only to block the court calendar. The lesson owns the revenue (price_per_pax_amount). Payments table tracks actual money.

Alternatives considered

• Keep per-pax price on each booking (current behavior — duplicates revenue)
• Set booking price to the court's hourly rate (tracks opportunity cost / margin)

Dynamic — cap at the facility's actual court count.

Alternatives considered

• Fixed max (e.g., 10)
• No max — rely on DB constraint (num_courts >= 1) only

Add 'checked_in' to the bookings.status CHECK constraint via migration.

Alternatives considered

• Remove the CHECK constraint entirely and rely on application-level validation
• Use a status enum type instead of CHECK constraint

Court Booking and Coach Booking.

Alternatives considered

• Regular Booking / Lesson Booking (previous naming)
• Court Reservation / Coaching Session

Each app enhances its own calendar.tsx independently. No shared UI package.

Alternatives considered

• Create @setpoint/ui with shared BookingCalendar component
• Put calendar in @setpoint/common (currently utilities only)

All bookings happen on the homepage calendar. Academy page is informational only (coaches, classes, packages). Coach profile links to homepage with ?coach= param.

Alternatives considered

• Keep separate booking flows on academy page and homepage
• Remove academy page entirely and merge content into homepage

Cal.com / Calendly pattern: month calendar on left (or top on mobile), available slots on right (or below). No booking window limit.

Alternatives considered

• Hotel-style date range picker (Airbnb/Booking.com)
• Flight-style departure time picker
• Extended date strip (current pattern but with 30+ days)

Yes. All booking display locations must LEFT JOIN through lesson_courts → lessons → coaches/classes. Show coach name, class info, and a visual lesson indicator. 6 admin spots + 2 web spots + 4 API routes need updating.

Alternatives considered

• Keep lesson info only in dedicated lesson views
• Add a booking_type column to bookings table

Coach-first for web — player picks coach, then sees available classes for that coach. Admin stays class-first. If coach has one class, auto-select and show as info. If multiple, show cards with name/type/duration/price. Manual private/group and duration pickers removed — class selection determines these.

Alternatives considered

• Class-first for both admin and web
• Keep current flow (coach-first, class silently auto-assigned)

Yes — classes are mandatory templates for lessons. Every lesson is an instance of a class. The lessons.class_id NOT NULL constraint is correct and intentional.

Alternatives considered

• Make class_id nullable (allow standalone lessons)
• Remove class_id entirely (original PRD design)

Member loyalty view lives at apps/web /account/loyalty only. OpenRally and TPS do not expose loyalty data in v1.4.

Alternatives considered

• Build OpenRally loyalty endpoints in v1.4
• No member view at all

Redemption is staff-only in v1.4 — performed by staff in the CRM admin. Members see rewards but cannot self-redeem. Self-serve deferred to v1.5/v2.0.

Alternatives considered

• Full self-serve redemption in v1.4
• No redemption UI at all

One program per facility — enforced by UNIQUE constraint on crm_loyalty_programs(facility_id). No multi-program support in v1.4.

Alternatives considered

• Multiple programs per facility
• No constraint — document by convention

Tier is calculated from lifetime_points (total ever earned) — never decrements when points are spent. Redeeming rewards decrements points_balance only; tier is permanent once reached.

Alternatives considered

• Tier based on current balance — punishes redemption
• Tier locked after first reach — inflexible

Unified replacement: one CRM loyalty program per facility replaces both pos_loyalty_programs (POS-only loyalty) and credit_tier_configs (membership discount tiers). All earning, tier calculation, and discount application goes through crm_loyalty_accounts.

Alternatives considered

• Keep pos_loyalty and credit_tier_configs separate
• Only migrate pos_loyalty and keep credit_tier_configs

No transformation needed. Existing USD values are already in cents (smallest subunit). The rename is column-name-only — data stays identical.

Alternatives considered

• Migrate data to a different representation

Predefined roles: owner, manager, admin, reception, coach, sales, other. 'Other' as escape hatch.

Alternatives considered

• Free-text roles
• No role field

TypeScript constants in packages/common (currency.ts). Shared across admin, web, and POS apps.

Alternatives considered

• Database tables
• Per-app constants
• External API

Yes — include district and neighborhood columns. Building for Asia first (Bangkok has districts/neighborhoods, not just city/state).

Alternatives considered

• Only address_line1/line2/city/state/zip
• Flexible key-value pairs

Rename existing columns (address → address_line1, state → state_province, zip → postal_code, country → country_code) + add new (address_line2, district, neighborhood, lat/lng).

Alternatives considered

• Add new columns alongside old ones
• Separate addresses table

Two separate PRs. PR 1: multi-currency (column rename + currency utilities + UI). PR 2: settings overhaul (address + contacts).

Alternatives considered

• Single large PR

Rename _cents → _amount. Store in the currency's smallest subunit (cents for USD, satang for THB). THB is a two-decimal currency (NOT zero-decimal in Stripe). ฿1,400 stored as 140,000 satang. Display is always ÷ 100 for two-decimal currencies. Conversion service needed only for truly zero-decimal Stripe currencies (JPY, KRW) if ever supported.

Alternatives considered

• Keep _cents naming
• Store in Stripe's API unit (zero-decimal convention)

All three products (Setpoint, OpenRally, TPS) and the club (Pad Thai Padel) are ours — built and owned by SuperStack. Setpoint PMS handles internal club operations. The Padel Society (TPS) is our consumer-facing mobile app. OpenRally Protocol is the middleware that connects them. TPS never connects to Setpoint directly — OpenRally is always the middleman.

Alternatives considered

• TPS connects directly to Setpoint API
• OpenRally as optional layer

All post-login, post-create, and facility-switch redirects now land on /dashboard instead of /calendar

Alternatives considered

• Keep Calendar as default landing
• Make it configurable per user

Rename Reports → Dashboard, move to first nav position, add facility root redirect, change icon to LayoutDashboard

Alternatives considered

• Keep Reports as-is and add a separate Dashboard page
• Rename but keep nav position

Remove all seed data from migrations (pure schema only), delete seed.sql entirely, and populate exclusively through a 73-test Playwright suite (demo-populate) that creates everything via real user flows — admin UI + web OTP + Stripe payments.

Alternatives considered

• Keep seed.sql for local, use --no-seed for production
• SQL seed scripts with ON CONFLICT guards
• Admin API scripts

No. Migrations are strictly schema — CREATE TABLE, ALTER TABLE, CREATE POLICY, CREATE FUNCTION. Zero INSERT statements for demo data. Seed data was removed from 8 migration files (PR #154).

Alternatives considered

• Keep seed data in migrations with ON CONFLICT DO NOTHING
• Separate seed migrations from schema migrations

Permanently banned. Production data is populated through real user flows and must never be wiped. Schema changes go through additive migrations via supabase db push only.

Alternatives considered

• Allow reset with confirmation
• Reset only in staging

Fully aligned. All 65 existing tests pass without changes. v0.16 match-linked bookings are compatible by design — materializer treats them as regular bookings. No code changes required.

Alternatives considered

• Refactor materializer to handle match_id explicitly
• Add match-specific API endpoints

Comprehensive real-world scenario tests (25 new tests) covering match-linked bookings, multi-facility isolation, hold lifecycle, booking lifecycle edge cases, availability edge cases, SSE events, and discovery/auth. Total: 90 tests.

Alternatives considered

• Schema comparison tests
• Contract tests against a spec file

Three-tier auth: (1) Public read endpoints (facility, courts, availability, matches, coaches, plans, etc.) require NO auth — open to everyone including guests. (2) User mutation endpoints (booking, payment, join, enroll, profile) require Supabase JWT. (3) API key auth kept as ALTERNATIVE for third-party consumers (OpenRally). Web app removes NEXT_PUBLIC_API_KEY entirely. ~19 GET routes become auth-free, ~10 booking mutation routes move from API key to JWT.

Alternatives considered

• Per-facility web app deployments
• Master API key for all facilities
• Proxy layer in web app server components

No. Setpoint Web keeps its own Setpoint APIs. OpenRally is exclusively for external consumers — third-party apps, aggregators, channel managers, and Google Reserve.

Alternatives considered

• Dogfooding: migrate Setpoint Web to consume OpenRally endpoints

Verify redirect to checkout.stripe.com (T10). Full round-trip webhook test in payments-membership.e2e.ts skips gracefully if STRIPE_WEBHOOK_SECRET not configured. Stripe CLI is a manual prerequisite, not automated.

Alternatives considered

• Mock webhook endpoint
• Use Stripe test clocks
• Skip membership tests entirely

No — Stripe CLI requires interactive login and a persistent process. Keep it as a manual prerequisite documented in the test file. Membership webhook tests skip gracefully if not running.

Alternatives considered

• Auto-start stripe listen in globalSetup
• Use Stripe webhook simulator
• Docker container with Stripe CLI

Browser-first E2E tests using Playwright frameLocator() to interact with Stripe PaymentElement iframes. 10 tests in payments.e2e.ts + 2 in payments-membership.e2e.ts. Covers: court booking, credit top-up, program enrollment (paid + free), match join (paid + free), declined cards, membership redirect.

Alternatives considered

• API-level tests with Stripe test helpers
• Mock Stripe entirely
• Manual QA only

Added admin server (port 3000) to web playwright.config.ts webServer array, matching the pattern already used in admin config.

Alternatives considered

• Require admin server to be started manually before web tests
• Mock the admin API in web tests

Root cause: PL/pgSQL RECORD IS NOT NULL returns false when any field is NULL. user_memberships has nullable stripe_* fields. Fixed by using FOUND special variable instead of IS NOT NULL. Applied same fix to the v_rule check.

Alternatives considered

• Select only non-nullable columns into the record
• Use a boolean flag variable set after the query

Replaced auth.admin.createUser() with POST /auth/v1/signup endpoint. Falls back to sign-in + profile lookup for existing users.

Alternatives considered

• Only fix for local dev (conditional logic)
• Use service_role key with HS256 signing

7 E2E tests in apps/web/e2e/match-emails.e2e.ts using Mailosaur for real email verification. Tests cover: match creation with invite → email received → content validated → invite page loads → result submission → result email received → result content validated.

Alternatives considered

• Mock Edge Functions
• Use Mailpit (local only, no real Resend delivery)
• Manual testing via production

Consolidate 51 short clips (9 files) into 4 journey-based demos (4 files): Admin Operations, Academy & Lessons, Matches & Ratings, Public Web User Journey. Each demo is a single continuous 2-5 min recording covering a complete user journey.

Alternatives considered

• Keep version-based short clips
• One mega demo covering everything
• Interactive demo app instead of videos

E2E only — no unit or integration tests. Keep admin API-based E2E tests (Playwright request client). Web app tests use browser UI. No additional test layers.

Alternatives considered

• Add unit tests for business logic
• Add integration tests for API routes
• Remove admin API-based tests and go browser-only

Separate demo videos into apps/admin/e2e/demos/ (own Playwright project, excluded from test runs). Replace API-only tests with web app UI E2E tests that exercise the same endpoints through real browser flows. 80/20 approach: happy paths + key errors, no exhaustive parameter testing.

Alternatives considered

• Keep demos mixed with tests
• Keep API-only tests alongside UI tests
• Test APIs separately and UI separately

Public API endpoints are tested through web app UI E2E tests only. No separate API-only test files. Admin app only tests admin dashboard UI + admin API endpoints.

Alternatives considered

• Keep both API and UI tests
• Test APIs in a standalone test suite
• Use contract tests instead

Consolidate all per-app env files into two root files: .env.local (local dev) and .env.production (production testing). Each Next.js app loads from root via dotenv in next.config.ts. Templates: env.local.example and env.production.example.

Alternatives considered

• Keep per-app .env.local files
• Use Turborepo env passthrough
• Use Vercel env integration locally

Use Mailosaur test inboxes as recipients. Edge Functions send real emails via Resend → Mailosaur intercepts → tests verify content via Mailosaur API. Requires Resend domain verification (omnigpt.co).

Alternatives considered

• Skip email verification entirely
• Mock Resend API
• Send to personal email and check manually

JSON state file (e2e/production/.state/run-state.json) — each test writes data (facility slug, match IDs, tokens) for later tests to read. File is gitignored.

Alternatives considered

• Environment variables
• Playwright fixtures/storage
• Database queries at start of each test

Drop court_id, sport_type, start_time, end_time, duration_minutes, cost_split, total_price_amount, cost_per_player_amount, currency — all derived from booking join.

Alternatives considered

• Keep columns with denormalized data
• Only drop some columns

Keep client-side Elements confirm (no `confirm: true`). Use `automatic_payment_methods: { enabled: true }`. Wrap in try/catch.

Alternatives considered

• Server-side confirm (confirm: true)
• Two-step: create then confirm

Yes — admin and organizer can toggle visibility after creation.

Alternatives considered

• Lock visibility after creation
• Only admin can change

Keep max_players the same — court-driven, not visibility-driven.

Alternatives considered

• Auto-limit private matches to fewer players
• Remove max_players for private

Backfill: create booking rows for orphan matches, then set NOT NULL constraint.

Alternatives considered

• Allow NULL booking_id forever
• Delete orphan matches

~8-10 visible fields. Sport derived from court selection. Level range optional. Remove cost inputs (auto-calculated from booking).

Alternatives considered

• Keep all 15+ fields
• Wizard-style multi-step form

Bidirectional cascade: cancel match → cancel booking, cancel booking → cancel match.

Alternatives considered

• One-way only (match→booking)
• No cascade, independent status

Pricing model (total, cost_split, per_player) on booking. Per-player Stripe payment tracking stays on match_players.

Alternatives considered

• All pricing on match
• Duplicate on both

`public` / `private` — two states only.

Alternatives considered

• Three states: public/private/unlisted
• Four states with friends-only

None — v0.15.2/v0.15.3 already shipped.

Keep both: booking_players (court access) + match_players (game data).

Alternatives considered

• Single unified players table
• Drop booking_players

Rename to `matches` — drop the `open_` prefix.

Alternatives considered

• Keep as open_matches
• Rename to facility_matches

Match auto-creates booking (single action). Booking = foundation (court, time, price). Match = optional layer on top.

Alternatives considered

• Separate creation flows
• Match is a booking type

Immediately available. No draft/live concept.

Alternatives considered

• Draft/live toggle
• Manual 'go live' step in settings

No. Automatic. OpenRally server reads from the same DB — any facility in the facilities table is discoverable.

Alternatives considered

• Explicit OpenRally registration step
• Feature flag per facility

They land on the facility selector empty state with 'Create your first facility' CTA. No partial facility state — creation is atomic.

Alternatives considered

• Multi-step wizard with save-and-resume
• Force facility creation before dashboard access

Auto-suggest alternative by appending -2, -3, etc. User can edit. Real-time validation.

Alternatives considered

• Reject and force manual rename
• Use UUID-based slugs

Show explicit message: 'Already have an account? Log in' with link to /auth/login.

Alternatives considered

• Silent redirect to login
• Generic error message

No. Start clean. Excellent empty states with CTAs guide the admin through setup.

Alternatives considered

• Seed sample courts + pricing
• Optional 'populate with demo data' checkbox