@bash-app/bash-common 30.236.0 → 30.238.0

package/src/utils/service/eventPromoterUtils.ts

@@ -0,0 +1,644 @@
+import {
+  PricingModel,
+  PromotionAndMarketingSubType,
+} from "@prisma/client";
+
+/**
+ * Event Promoter is a productized hire-a-promoter service profile under
+ * `EventService` → `PromotionAndMarketing` → `Promoter`. Its pricing model
+ * is intentionally locked to PER_ATTENDEE so:
+ *
+ * 1. Bookings can compute a deposit at booking time from
+ *    `bashEvent.expectedAttendees * baseRateCents`.
+ * 2. The bash-close settlement job can run a delta charge/refund based on
+ *    final checked-in attendee count (see
+ *    `apiEventPromoterSettlementMath` below).
+ *
+ * Keep the disambiguation: this is the **Event Promoter** service, not the
+ * **Promo-code Promoter** referral program (`model Promoter` +
+ * `BashEventPromoCode`), which earns BashPoints per ticket purchased.
+ */
+
+/**
+ * Returns true when the given `PromotionAndMarketing` subtype is locked to a
+ * specific `PricingModel`. Today only `Promoter` is locked (PER_ATTENDEE).
+ *
+ * Compared with the **string literal** rather than the Prisma enum object
+ * because the browser bundle (`index-browser`) does not always re-export
+ * Prisma enums as runtime values — see `bash-common/src/mirroredPrismaEnums.ts`
+ * for the same pattern.
+ */
+export function isPerAttendeeLockedPromotionSubType(
+  subType: PromotionAndMarketingSubType | string | null | undefined
+): boolean {
+  return subType === "Promoter";
+}
+
+/**
+ * Build the URL the host clicks from an Event Promoter booking thread to
+ * issue/edit a `BashEventPromoCode` with the promoter pre-selected. The
+ * landing page reads `promoterUserId` from the query string and opens the
+ * promo-code create modal already focused on that user.
+ *
+ * Keeping this in `bash-common` so api emails + bash-app threads + push
+ * notifications all generate the same deep link.
+ */
+export function buildIssuePromoCodeDeepLink(args: {
+  bashEventId: string;
+  promoterUserId: string;
+  /** Optional preselected ticket tier (skip the chooser screen when set). */
+  ticketTierId?: string | null;
+}): string {
+  const params = new URLSearchParams({
+    promoterUserId: args.promoterUserId,
+    source: "event-promoter-booking",
+  });
+  if (args.ticketTierId) {
+    params.set("ticketTierId", args.ticketTierId);
+  }
+  return `/bashes/${args.bashEventId}/edit?step=how&open=promo-codes&${params.toString()}`;
+}
+
+/** Hours-before-bash threshold under which a host cancellation is "late". */
+export const EVENT_PROMOTER_LATE_CANCEL_HOURS = 48;
+
+/**
+ * Late-cancellation penalty as a fraction of the deposit (0..1). 0.25 means
+ * the host forfeits 25% of the deposit when they cancel inside the
+ * `EVENT_PROMOTER_LATE_CANCEL_HOURS` window — covers the promoter's
+ * sunk planning time.
+ */
+export const EVENT_PROMOTER_LATE_CANCEL_PENALTY_FRACTION = 0.25;
+
+/** Who is cancelling the Event Promoter booking. Maps to refund policy. */
+export type EventPromoterCanceller = "host" | "promoter" | "admin";
+
+export interface EventPromoterCancellationInput {
+  who: EventPromoterCanceller;
+  /** ISO timestamp of "now" — injected so callers can test edge cases. */
+  nowMs: number;
+  /** Bash start time. */
+  bashStartMs: number | null;
+  /** Bash end time — once we're past this, settlement takes over instead. */
+  bashEndMs: number | null;
+  /** Deposit cents already charged at booking. */
+  depositCents: number;
+  /** Has settlement already run? If so, cancellation is a no-op. */
+  alreadySettled: boolean;
+}
+
+export interface EventPromoterCancellationDecision {
+  /** Whether the cancellation can run automatically right now. */
+  allow: boolean;
+  /**
+   * Outcome category for telemetry + thread messaging:
+   * - `FullRefund` — full deposit returned (host cancel outside window, or
+   *   promoter cancel any time before the bash).
+   * - `PartialRefund` — host cancels inside the late-cancel window; promoter
+   *   keeps `EVENT_PROMOTER_LATE_CANCEL_PENALTY_FRACTION` of the deposit.
+   * - `NoRefund` — bash already happened; settlement handles it instead.
+   * - `Blocked` — booking already settled, or impossible state; admin only.
+   */
+  outcome: "FullRefund" | "PartialRefund" | "NoRefund" | "Blocked";
+  /** Refund amount in cents (0 when outcome is NoRefund/Blocked). */
+  refundCents: number;
+  /** Penalty fraction applied (0 when not late-cancelled by host). */
+  penaltyFraction: number;
+  /** Human-readable reason, suitable for booking-thread system messages. */
+  reason: string;
+}
+
+/**
+ * Pure decision function that returns what should happen when someone tries
+ * to cancel an Event Promoter booking. Mirrors the matrix called out in the
+ * plan:
+ *
+ *   - Host, bash hasn't started, > 48h out → FullRefund.
+ *   - Host, bash hasn't started, ≤ 48h out → PartialRefund (25% penalty).
+ *   - Host, bash already running/ended → NoRefund (settlement takes over).
+ *   - Promoter, bash not started → FullRefund + promoter notified
+ *     (Bash never holds a promoter to a job they can't do).
+ *   - Promoter, bash already running/ended → Blocked (use the booking thread
+ *     to coordinate; nothing automatic).
+ *   - Admin always allowed; refund amount decided by caller.
+ *   - Already settled → Blocked (no automatic cancel).
+ *
+ * The actual Stripe refund + DB mutation lives in the api-side counterpart;
+ * this function only encodes policy so the same matrix surfaces in tests,
+ * the booking thread copy, and the audit log.
+ */
+export function decideEventPromoterCancellation(
+  input: EventPromoterCancellationInput
+): EventPromoterCancellationDecision {
+  if (input.alreadySettled) {
+    return {
+      allow: false,
+      outcome: "Blocked",
+      refundCents: 0,
+      penaltyFraction: 0,
+      reason: "Booking already settled — cancellation no longer applies.",
+    };
+  }
+
+  const bashHasStarted =
+    input.bashStartMs != null && input.nowMs >= input.bashStartMs;
+  const bashHasEnded =
+    input.bashEndMs != null && input.nowMs >= input.bashEndMs;
+  const bashInProgressOrPast = bashHasStarted || bashHasEnded;
+  const hoursUntilStart =
+    input.bashStartMs != null
+      ? (input.bashStartMs - input.nowMs) / (60 * 60 * 1000)
+      : Number.POSITIVE_INFINITY;
+
+  if (input.who === "admin") {
+    if (bashInProgressOrPast) {
+      return {
+        allow: true,
+        outcome: "NoRefund",
+        refundCents: 0,
+        penaltyFraction: 0,
+        reason: "Admin cancel after bash started — settlement handles money.",
+      };
+    }
+    return {
+      allow: true,
+      outcome: "FullRefund",
+      refundCents: input.depositCents,
+      penaltyFraction: 0,
+      reason: "Admin cancel — full refund of deposit.",
+    };
+  }
+
+  if (input.who === "promoter") {
+    if (bashInProgressOrPast) {
+      return {
+        allow: false,
+        outcome: "Blocked",
+        refundCents: 0,
+        penaltyFraction: 0,
+        reason:
+          "Bash already started — promoter must coordinate with host in the thread, not auto-cancel.",
+      };
+    }
+    return {
+      allow: true,
+      outcome: "FullRefund",
+      refundCents: input.depositCents,
+      penaltyFraction: 0,
+      reason:
+        "Promoter cancelled — full refund of host deposit. Bash notifies the host and re-opens the slot.",
+    };
+  }
+
+  // who === "host"
+  if (bashInProgressOrPast) {
+    return {
+      allow: false,
+      outcome: "NoRefund",
+      refundCents: 0,
+      penaltyFraction: 0,
+      reason:
+        "Bash already in progress or over — the post-event settlement will calculate any refund automatically.",
+    };
+  }
+
+  if (hoursUntilStart >= EVENT_PROMOTER_LATE_CANCEL_HOURS) {
+    return {
+      allow: true,
+      outcome: "FullRefund",
+      refundCents: input.depositCents,
+      penaltyFraction: 0,
+      reason: `Host cancelled with more than ${EVENT_PROMOTER_LATE_CANCEL_HOURS}h notice — full refund of deposit.`,
+    };
+  }
+
+  const penaltyFraction = EVENT_PROMOTER_LATE_CANCEL_PENALTY_FRACTION;
+  const refundCents = Math.max(
+    0,
+    Math.round(input.depositCents * (1 - penaltyFraction))
+  );
+  return {
+    allow: true,
+    outcome: "PartialRefund",
+    refundCents,
+    penaltyFraction,
+    reason: `Host cancelled inside the ${EVENT_PROMOTER_LATE_CANCEL_HOURS}h window — promoter keeps ${Math.round(
+      penaltyFraction * 100
+    )}% of the deposit to cover planning time.`,
+  };
+}
+
+/**
+ * The single allowed pricing model for the locked promotion subtype. Exposed
+ * as a constant so wizard + api validators share the same source of truth.
+ *
+ * Retained for backwards compatibility; new call sites should prefer
+ * {@link EVENT_PROMOTER_LOCKED_PRICING_MODELS} to allow Phase 3's
+ * `PER_PAID_ATTENDEE` and `PER_BASHPOINTS_ATTENDEE`.
+ */
+export const EVENT_PROMOTER_LOCKED_PRICING_MODEL: PricingModel =
+  "PER_ATTENDEE";
+
+/**
+ * Phase 3 — set of pricing models the locked Event Promoter subtype may use.
+ * Any of these guarantees a per-head settlement at bash close, which is the
+ * actual constraint the worker cares about. Wizard offers them as a choice;
+ * api validator accepts any.
+ */
+export const EVENT_PROMOTER_LOCKED_PRICING_MODELS: ReadonlyArray<PricingModel> = [
+  "PER_ATTENDEE",
+  "PER_PAID_ATTENDEE",
+  "PER_BASHPOINTS_ATTENDEE",
+];
+
+export type EventPromoterPricingValidation =
+  | { ok: true }
+  | { ok: false; reason: string; expected: ReadonlyArray<PricingModel> };
+
+/**
+ * Validates that an `EventService` save with `subType === "Promoter"` uses
+ * one of the {@link EVENT_PROMOTER_LOCKED_PRICING_MODELS}. Intended for both:
+ *
+ * - the Event Services wizard (block save with a friendly message), and
+ * - the api save path (reject the request even if the wizard is bypassed).
+ *
+ * Returns `{ ok: true }` for any non-locked subtype.
+ */
+export function validateEventPromoterPricing(args: {
+  eventServiceSubType: PromotionAndMarketingSubType | string | null | undefined;
+  pricingModel: PricingModel | null | undefined;
+}): EventPromoterPricingValidation {
+  if (!isPerAttendeeLockedPromotionSubType(args.eventServiceSubType)) {
+    return { ok: true };
+  }
+
+  if (
+    args.pricingModel != null &&
+    EVENT_PROMOTER_LOCKED_PRICING_MODELS.includes(args.pricingModel)
+  ) {
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    expected: EVENT_PROMOTER_LOCKED_PRICING_MODELS,
+    reason: `Event Promoter services must use one of: ${EVENT_PROMOTER_LOCKED_PRICING_MODELS.join(
+      ", "
+    )}. Got: ${args.pricingModel ?? "null"}.`,
+  };
+}
+
+/**
+ * Computes the deposit cents to charge a host at Event Promoter booking time.
+ *
+ * Logic:
+ * - Baseline = max(`bashExpectedAttendees`, `minimumQuantity ?? 0`).
+ * - Deposit = baseline * `baseRateCents`.
+ *
+ * Returns `null` if `baseRateCents` is not set (caller should surface a
+ * validation error rather than silently charge $0).
+ */
+export function computeEventPromoterDepositCents(args: {
+  bashExpectedAttendees: number;
+  baseRateCents: number | null | undefined;
+  minimumQuantity: number | null | undefined;
+}): number | null {
+  if (args.baseRateCents == null || args.baseRateCents <= 0) {
+    return null;
+  }
+  const baseline = Math.max(
+    Math.max(0, args.bashExpectedAttendees),
+    Math.max(0, args.minimumQuantity ?? 0)
+  );
+  return baseline * args.baseRateCents;
+}
+
+export interface EventPromoterSettlementInput {
+  baseRateCents: number;
+  expectedAttendeesAtBooking: number;
+  totalCheckedInAttendees: number;
+  /** Per-booking host-set ceiling on attributable attendees; `null` = no cap. */
+  maxAttendeesAttributable?: number | null;
+  /** Optional floor — usually `EventService.minimumQuantity` at booking time. */
+  minimumQuantity?: number | null;
+}
+
+export interface EventPromoterSettlementResult {
+  /**
+   * Attendee count actually used to bill, after applying the ceiling and any
+   * minimum-quantity floor. Always ≥ 0.
+   */
+  finalCount: number;
+  /**
+   * True iff `maxAttendeesAttributable` capped `finalCount`. Useful for
+   * analytics — high `ceilingHit` rates signal v2 (per-ticket attribution).
+   */
+  ceilingHit: boolean;
+  /**
+   * Signed delta in cents:
+   * - positive → charge the host this additional amount.
+   * - negative → refund the host this amount (refund magnitude = |delta|).
+   * - 0 → no Stripe action needed; mark `settledAt`.
+   */
+  settlementDeltaCents: number;
+  /**
+   * Total cents the host owes for the booking after settlement
+   * (`finalCount * baseRateCents`). Useful for receipts / analytics.
+   */
+  totalCents: number;
+}
+
+/**
+ * Pure function: compute the per-attendee settlement delta for an Event
+ * Promoter `ServiceBooking`. Caller is responsible for translating the result
+ * into Stripe API calls (charge if positive delta, refund if negative).
+ *
+ * Worked example (host hires two promoters for the same bash @ $5/attendee):
+ *
+ *   Promoter A: expected=200, ceiling=250, checked-in=220
+ *     → finalCount=220, delta = (220-200) * 500 = +$100
+ *
+ *   Promoter B: expected=100, ceiling=150, same 220 checked-in
+ *     → finalCount=min(220,150)=150, delta = (150-100) * 500 = +$250
+ *
+ * @see plan: docs/design/CONTENT-PATTERNS.md, .cursor/plans/ambashadors_page_tiers_ux_*.plan.md
+ */
+export function computeEventPromoterSettlement(
+  input: EventPromoterSettlementInput
+): EventPromoterSettlementResult {
+  const checkedIn = Math.max(0, input.totalCheckedInAttendees);
+  const ceiling =
+    input.maxAttendeesAttributable != null && input.maxAttendeesAttributable >= 0
+      ? input.maxAttendeesAttributable
+      : Number.POSITIVE_INFINITY;
+  const minQty = Math.max(0, input.minimumQuantity ?? 0);
+
+  // Apply ceiling first, then enforce minimum-quantity floor for the
+  // billing-floor case (host committed to paying for at least `minQty`
+  // attendees regardless of turnout).
+  const cappedByCeiling = Math.min(checkedIn, ceiling);
+  const finalCount = Math.max(cappedByCeiling, minQty);
+  const ceilingHit = checkedIn > ceiling;
+
+  const totalCents = finalCount * input.baseRateCents;
+  const expectedCents = input.expectedAttendeesAtBooking * input.baseRateCents;
+  const settlementDeltaCents = totalCents - expectedCents;
+
+  return {
+    finalCount,
+    ceilingHit,
+    settlementDeltaCents,
+    totalCents,
+  };
+}
+
+// --------------------------------------------------------------------------
+// Phase 3 — PER_PAID_ATTENDEE + PER_BASHPOINTS_ATTENDEE settlement helpers.
+// --------------------------------------------------------------------------
+
+/**
+ * Which checked-in attendees count toward the settlement headcount?
+ *
+ * - `AllCheckedIn` — every checked-in, non-comp guest (legacy PER_ATTENDEE).
+ * - `PaidUsdOnly` — only guests on USD-priced tiers (PER_PAID_ATTENDEE without
+ *   `countsBashPointsTickets`).
+ * - `PaidBpOnly` — only guests on BashPoints-priced tiers
+ *   (PER_BASHPOINTS_ATTENDEE).
+ * - `PaidAny` — paid guests on either currency
+ *   (PER_PAID_ATTENDEE with `countsBashPointsTickets = true`).
+ */
+export type EventPromoterCountingBasis =
+  | "AllCheckedIn"
+  | "PaidUsdOnly"
+  | "PaidBpOnly"
+  | "PaidAny";
+
+/**
+ * Choose the correct counting basis given the pricing model and the
+ * per-booking `countsBashPointsTickets` knob. Pure function so wizard +
+ * worker share one mapping.
+ */
+export function eventPromoterCountingBasisFor(args: {
+  pricingModel: PricingModel | string | null | undefined;
+  countsBashPointsTickets?: boolean | null;
+}): EventPromoterCountingBasis {
+  switch (args.pricingModel) {
+    case "PER_PAID_ATTENDEE":
+      return args.countsBashPointsTickets ? "PaidAny" : "PaidUsdOnly";
+    case "PER_BASHPOINTS_ATTENDEE":
+      return "PaidBpOnly";
+    case "PER_ATTENDEE":
+    default:
+      return "AllCheckedIn";
+  }
+}
+
+/**
+ * Pick the matching checked-in count from the snapshots a worker has gathered
+ * at settlement time. Returns the **paying** head count regardless of
+ * currency, narrowed by basis.
+ */
+export interface EventPromoterAttendeeSnapshots {
+  /** All checked-in attendees (`AllCheckedIn` basis). */
+  totalCheckedInAttendees: number;
+  /** Checked-in attendees on USD-priced tiers (`PaidUsdOnly` / `PaidAny`). */
+  paidAttendeesAtSettle?: number | null;
+  /** Checked-in attendees on BP-priced tiers (`PaidBpOnly` / `PaidAny`). */
+  paidInBashPointsAttendeesAtSettle?: number | null;
+}
+
+export function pickCheckedInForBasis(
+  basis: EventPromoterCountingBasis,
+  s: EventPromoterAttendeeSnapshots
+): number {
+  switch (basis) {
+    case "AllCheckedIn":
+      return Math.max(0, s.totalCheckedInAttendees);
+    case "PaidUsdOnly":
+      return Math.max(0, s.paidAttendeesAtSettle ?? 0);
+    case "PaidBpOnly":
+      return Math.max(0, s.paidInBashPointsAttendeesAtSettle ?? 0);
+    case "PaidAny":
+      return (
+        Math.max(0, s.paidAttendeesAtSettle ?? 0) +
+        Math.max(0, s.paidInBashPointsAttendeesAtSettle ?? 0)
+      );
+  }
+}
+
+export interface EventPromoterMixedSettlementInput {
+  /** Per-attendee USD rate (cents). 0/null = no USD owed. */
+  baseRateCents?: number | null;
+  /** Per-attendee BP rate. 0/null = no BP owed. */
+  baseRateBashPoints?: number | null;
+  /** Expected USD-paying head count at booking. */
+  expectedPaidAttendeesAtBooking?: number | null;
+  /** Expected BP-paying head count at booking. */
+  expectedBpAttendeesAtBooking?: number | null;
+  /** Snapshots from the bash checkout (see `EventPromoterAttendeeSnapshots`). */
+  snapshots: EventPromoterAttendeeSnapshots;
+  /** Optional ceilings — separate caps for USD and BP. */
+  maxUsdAttendeesAttributable?: number | null;
+  maxBpAttendeesAttributable?: number | null;
+  /** Optional dollar cap on USD side (from `maxBillableCents`). */
+  maxBillableCents?: number | null;
+  /** Optional BP cap on BP side (from `maxBillableBashPoints`). */
+  maxBillableBashPoints?: number | null;
+}
+
+export interface EventPromoterMixedSettlementResult {
+  /** USD owed at settlement. */
+  usdTotalCents: number;
+  /** USD delta vs the deposit pre-paid at booking. */
+  usdDeltaCents: number;
+  /** BashPoints owed at settlement. */
+  bpTotal: number;
+  /** BP delta vs the deposit pre-paid at booking. */
+  bpDelta: number;
+  /** True if either cap kicked in. */
+  cappedUsd: boolean;
+  cappedBp: boolean;
+}
+
+/**
+ * Pure function for mixed PER_PAID_ATTENDEE / PER_BASHPOINTS_ATTENDEE
+ * settlement. Either side can be unset (the worker only computes the side
+ * that applies). Caller is responsible for the actual Stripe + BP ledger
+ * postings.
+ */
+export function computeEventPromoterMixedSettlement(
+  input: EventPromoterMixedSettlementInput
+): EventPromoterMixedSettlementResult {
+  // --- USD side -----------------------------------------------------------
+  const usdRate = Math.max(0, input.baseRateCents ?? 0);
+  let usdCount = pickCheckedInForBasis("PaidUsdOnly", input.snapshots);
+  const usdCeiling =
+    input.maxUsdAttendeesAttributable != null &&
+    input.maxUsdAttendeesAttributable >= 0
+      ? input.maxUsdAttendeesAttributable
+      : Number.POSITIVE_INFINITY;
+  usdCount = Math.min(usdCount, usdCeiling);
+
+  let usdTotalCents = usdRate * usdCount;
+  let cappedUsd = false;
+  if (
+    input.maxBillableCents != null &&
+    input.maxBillableCents >= 0 &&
+    usdTotalCents > input.maxBillableCents
+  ) {
+    usdTotalCents = input.maxBillableCents;
+    cappedUsd = true;
+  }
+  const usdExpected =
+    Math.max(0, input.expectedPaidAttendeesAtBooking ?? 0) * usdRate;
+  const usdDeltaCents = usdTotalCents - usdExpected;
+
+  // --- BP side ------------------------------------------------------------
+  const bpRate = Math.max(0, input.baseRateBashPoints ?? 0);
+  let bpCount = pickCheckedInForBasis("PaidBpOnly", input.snapshots);
+  const bpCeiling =
+    input.maxBpAttendeesAttributable != null &&
+    input.maxBpAttendeesAttributable >= 0
+      ? input.maxBpAttendeesAttributable
+      : Number.POSITIVE_INFINITY;
+  bpCount = Math.min(bpCount, bpCeiling);
+
+  let bpTotal = bpRate * bpCount;
+  let cappedBp = false;
+  if (
+    input.maxBillableBashPoints != null &&
+    input.maxBillableBashPoints >= 0 &&
+    bpTotal > input.maxBillableBashPoints
+  ) {
+    bpTotal = input.maxBillableBashPoints;
+    cappedBp = true;
+  }
+  const bpExpected =
+    Math.max(0, input.expectedBpAttendeesAtBooking ?? 0) * bpRate;
+  const bpDelta = bpTotal - bpExpected;
+
+  return {
+    usdTotalCents,
+    usdDeltaCents,
+    bpTotal,
+    bpDelta,
+    cappedUsd,
+    cappedBp,
+  };
+}
+
+// --------------------------------------------------------------------------
+// Phase 3 — BashPoints payout source resolver (pool-then-wallet).
+// --------------------------------------------------------------------------
+
+export type BashPointsPayoutSourceValue = "HostWallet" | "BashBpPool";
+
+export interface BashPointsPayoutResolverInput {
+  /** From `BashEvent.bashPointsPayoutSource`. */
+  source: BashPointsPayoutSourceValue;
+  /** BP the worker owes the provider for this settlement. */
+  payoutBp: number;
+  /** BP the host has in their wallet at settlement time. */
+  hostWalletBp: number;
+  /**
+   * For `BashBpPool` source: live remaining BP in the bash's BP pool. This is
+   * `sum(BP from BP-ticket purchases) − sum(BP already paid out) −
+   * sum(outstanding BP-refund obligations)`. Caller computes; resolver only
+   * drains.
+   */
+  bashPoolBp?: number;
+}
+
+export interface BashPointsPayoutResolverResult {
+  /** BP drained from the bash's BashPoints pool. */
+  fromPoolBp: number;
+  /** BP debited from the host's wallet. */
+  fromWalletBp: number;
+  /** BP that could NOT be sourced (resulting failure → dunning). */
+  shortfallBp: number;
+  /** True when fromWalletBp > 0 — used to surface UI / push notifications. */
+  walletDebited: boolean;
+}
+
+/**
+ * Pure function that decides which BashPoints buckets to drain to satisfy a
+ * provider payout. Mirrors the worker's behavior:
+ *
+ *   - `HostWallet`: take everything from the host's wallet; any shortfall is
+ *     a payment failure (`SettlementPaymentFailed`).
+ *   - `BashBpPool`: drain the pool first; pay the remainder from the host's
+ *     wallet; if still short, mark `SettlementPaymentFailed`.
+ *
+ * Negative inputs are clamped to zero so the resolver never returns a
+ * negative bucket.
+ */
+export function resolveBashPointsPayoutSources(
+  input: BashPointsPayoutResolverInput
+): BashPointsPayoutResolverResult {
+  const need = Math.max(0, Math.floor(input.payoutBp));
+  const wallet = Math.max(0, Math.floor(input.hostWalletBp));
+  const pool = Math.max(0, Math.floor(input.bashPoolBp ?? 0));
+
+  if (input.source === "HostWallet") {
+    const fromWalletBp = Math.min(need, wallet);
+    const shortfallBp = need - fromWalletBp;
+    return {
+      fromPoolBp: 0,
+      fromWalletBp,
+      shortfallBp,
+      walletDebited: fromWalletBp > 0,
+    };
+  }
+
+  // BashBpPool
+  const fromPoolBp = Math.min(need, pool);
+  const remainAfterPool = need - fromPoolBp;
+  const fromWalletBp = Math.min(remainAfterPool, wallet);
+  const shortfallBp = remainAfterPool - fromWalletBp;
+  return {
+    fromPoolBp,
+    fromWalletBp,
+    shortfallBp,
+    walletDebited: fromWalletBp > 0,
+  };
+}