@bash-app/bash-common 30.226.0 → 30.227.0

package/prisma/schema.prisma

@@ -393,6 +393,7 @@ model EventTask {
   notificationsReferencingMe Notification[]
   comments                   TaskComment[]
   invitations                TaskInvitation[]
+  expenses                   Expense[]
   potluckItem                PotluckItem?         @relation("PotluckItemTask")
   bashEventSuggestion        BashEventSuggestion? @relation("SuggestionTask")
 }
@@ -693,7 +694,7 @@ model BashEvent {
   servicePreferences          Json? // New tiered status: { "Entertainment": "need", "Sponsors": "booked_closed", ... }
   bookedServices              Json? // Booked service details: { "Entertainment": { serviceId: "...", providerId: "...", bookedAt: "..." }, ... }
   serviceVisibility           Json? // DEPRECATED: Use servicePreferences instead. Kept for backward compatibility during migration.
-  plannedServiceIds           String[] @default([]) // Service IDs the host has flagged as "plan to book" in the wizard
+  plannedServiceIds           String[]        @default([]) // Service IDs the host has flagged as "plan to book" in the wizard
   originalCreatorId           String?
   transferredAt               DateTime?
   transferredFromId           String?
@@ -749,6 +750,9 @@ model BashEvent {
   maxGuestsPerMember       Int? // Guest limit per member (null = unlimited)
   restrictToOrgDepartments String[] @default([]) // Empty = all departments can see/join
 
+  /// When true, new event expenses default to Pending until host/org approves (see Expense.status).
+  requireExpenseApproval Boolean @default(false)
+
   associatedBashesReferencingMe   AssociatedBash[]
   comments                        BashComment[]
   amountOfGuests                  AmountOfGuests?                @relation(fields: [amountOfGuestsId], references: [id], onDelete: Cascade)
@@ -848,11 +852,27 @@ model BashEvent {
 
   bashEventArtists BashEventArtist[]
   vanityPaths      EventVanityPath[]
+  flyerCampaigns   FlyerCampaign[]
+
+  /// Latest AI moderator verdict (see `bashApprovalAiService` + `mapAiResultToDecision`).
+  /// Null = never reviewed by AI. Recomputed each time the bash transitions to Pending
+  /// or a super-user clicks "Re-run AI review".
+  aiApprovalVerdict     AiApprovalVerdict?
+  aiApprovalConfidence  Float?
+  /// Structured `AiApprovalReasons` (criteria scores + hostFacingMessage + adminFacingNotes).
+  /// Schema lives in `bash-common/src/extendedSchemas.ts`.
+  aiApprovalReasons     Json?
+  aiApprovalReviewedAt  DateTime?
+  aiApprovalModel       String?
+  aiApprovalRunCount    Int                @default(0)
+  /// SHA-256 of the snapshot fed to the AI; lets us skip a re-run when nothing changed.
+  aiApprovalContentHash String?
 
   @@index([templateId])
   @@index([parentEventId])
   @@index([organizationId])
   @@index([eventSeriesId])
+  @@index([status, aiApprovalVerdict])
 }
 
 /// Lineup / attribution roster for an event (optional act list for checkout tagging).
@@ -872,6 +892,197 @@ model BashEventArtist {
   @@index([serviceId])
 }
 
+// --- Flyer Blast (USPS EDDM neighborhood mail campaigns) ---
+enum FlyerTargetingMode {
+  RADIUS
+  CUSTOM
+}
+
+enum FlyerFulfillmentType {
+  SELF_MAIL
+  DONE_FOR_YOU
+}
+
+enum FlyerCampaignStatus {
+  DRAFT
+  ARTWORK_REVIEW
+  PAID
+  PRINTING
+  IN_TRANSIT
+  DELIVERED
+  CANCELLED
+}
+
+enum FlyerSponsorSlot {
+  FEATURED
+  SUPPORTING_1
+  SUPPORTING_2
+}
+
+enum FlyerConversionType {
+  QR_SCAN
+  RSVP
+  TICKET_PURCHASE
+  SPONSOR_QR_SCAN
+}
+
+model FlyerCampaign {
+  id          String @id @default(cuid())
+  bashEventId String
+  hostUserId  String
+
+  targetingMode   FlyerTargetingMode @default(RADIUS)
+  radiusMiles     Float?
+  centerLat       Float?
+  centerLng       Float?
+  customPolygon   Json?
+  totalHouseholds Int?
+
+  fulfillmentType FlyerFulfillmentType @default(DONE_FOR_YOU)
+
+  printPostageCostCents Int?
+  bashFeeCents          Int?
+  sponsorRevenueCents   Int?
+  hostTotalCostCents    Int?
+  stripePaymentIntentId String?
+  paidAt                DateTime?
+
+  campaignQrSlug    String  @unique
+  campaignPromoCode String?
+
+  ctaLabel        String?
+  templateVariant String  @default("default")
+
+  status FlyerCampaignStatus @default(DRAFT)
+
+  vendorOrderRef String?
+  vendorStatus   String?
+
+  bashEvent       BashEvent              @relation(fields: [bashEventId], references: [id], onDelete: Cascade)
+  host            User                   @relation(fields: [hostUserId], references: [id], onDelete: Cascade)
+  routes          FlyerMailingRoute[]
+  artworkVersions FlyerArtwork[]
+  sponsors        FlyerCampaignSponsor[]
+  conversions     FlyerConversion[]
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([bashEventId])
+  @@index([hostUserId])
+}
+
+model FlyerMailingRoute {
+  id         String        @id @default(cuid())
+  campaignId String
+  campaign   FlyerCampaign @relation(fields: [campaignId], references: [id], onDelete: Cascade)
+
+  crrtCode       String
+  zipCode        String
+  city           String
+  state          String @default("UT")
+  householdCount Int
+
+  medianIncomeBand String?
+  avgHouseholdSize Float?
+  medianAge        Float?
+
+  createdAt DateTime @default(now())
+
+  @@unique([campaignId, crrtCode, zipCode])
+  @@index([campaignId])
+}
+
+model FlyerArtwork {
+  id         String        @id @default(cuid())
+  campaignId String
+  campaign   FlyerCampaign @relation(fields: [campaignId], references: [id], onDelete: Cascade)
+
+  version         Int
+  s3KeyPrintPdf   String?
+  s3KeyPreviewPng String?
+
+  widthIn         Float   @default(6.25)
+  heightIn        Float   @default(11)
+  isEddmCompliant Boolean @default(false)
+
+  createdAt DateTime @default(now())
+
+  @@index([campaignId])
+}
+
+model FlyerCampaignSponsor {
+  id         String        @id @default(cuid())
+  campaignId String
+  campaign   FlyerCampaign @relation(fields: [campaignId], references: [id], onDelete: Cascade)
+
+  slotType      FlyerSponsorSlot
+  businessName  String
+  logoS3Key     String?
+  ctaText       String?
+  sponsorQrSlug String?          @unique
+
+  slotPriceCents        Int       @default(0)
+  stripePaymentIntentId String?
+  paidAt                DateTime?
+
+  hostPayoutCents Int?
+  bashFeeCents    Int?
+
+  conversions FlyerConversion[]
+
+  createdAt DateTime @default(now())
+
+  @@unique([campaignId, slotType])
+  @@index([campaignId])
+}
+
+model FlyerConversion {
+  id         String        @id @default(cuid())
+  campaignId String
+  campaign   FlyerCampaign @relation(fields: [campaignId], references: [id], onDelete: Cascade)
+
+  type      FlyerConversionType @default(QR_SCAN)
+  sponsorId String?
+  ticketId  String?
+
+  crrtCode  String?
+  userAgent String?
+
+  occurredAt DateTime @default(now())
+
+  sponsor FlyerCampaignSponsor? @relation(fields: [sponsorId], references: [id], onDelete: SetNull)
+  ticket  Ticket?               @relation(fields: [ticketId], references: [id], onDelete: SetNull)
+
+  @@index([campaignId])
+  @@index([occurredAt])
+  @@index([sponsorId])
+  @@index([ticketId])
+}
+
+/// USPS carrier-route catalog (Utah MVP; expand for national rollout).
+model PostalCarrierRoute {
+  id               String  @id @default(cuid())
+  crrtCode         String
+  zipCode          String
+  city             String
+  state            String  @default("UT")
+  latitude         Float
+  longitude        Float
+  householdCount   Int
+  residentialOnly  Boolean @default(true)
+  medianIncomeBand String?
+  avgHouseholdSize Float?
+  medianAge        Float?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([zipCode, crrtCode])
+  @@index([latitude, longitude])
+  @@index([zipCode])
+}
+
 enum BashCreativeStatus {
   Pending
   InReview
@@ -1502,6 +1713,7 @@ model Ticket {
   transferInvite     TicketTransferInvite?
   appliedDiscounts   AppliedDiscount[] // NEW - Discounts applied to this ticket
   eventReferral      EventReferral? // When this ticket was purchased via a referral link
+  flyerConversions   FlyerConversion[]
 
   @@index([bashEventId])
   @@index([waitlistUserId])
@@ -1931,26 +2143,26 @@ model User {
 
   givenName                       String?
   familyName                      String?
-  nameChangeCount                 Int            @default(0)
+  nameChangeCount                 Int                   @default(0)
   hash                            String?
-  previousPasswordHashes          String[]       @default([]) // Last 5 bcrypt hashes (oldest first) for password-reuse prevention
+  previousPasswordHashes          String[]              @default([]) // Last 5 bcrypt hashes (oldest first) for password-reuse prevention
   emailVerified                   DateTime?
   image                           String?
   imageUpdatedAt                  DateTime? // When Google/OAuth image was last updated
   uploadedImage                   String?
   uploadedImageUpdatedAt          DateTime? // When manually uploaded image was last updated
   dob                             DateTime?
-  showBirthdayOnProfile           Boolean        @default(false) // If true, show month/day on public profile
+  showBirthdayOnProfile           Boolean               @default(false) // If true, show month/day on public profile
   // Part B: Birthday Rewards full product
-  birthdayRewardsOptIn            Boolean        @default(false)
+  birthdayRewardsOptIn            Boolean               @default(false)
   birthdayRewardsOptInAt          DateTime?
   birthdayLocationId              String? // FK UserLocation (birthday home base)
-  birthdayMaxDistanceMiles        Int            @default(25)
-  birthdayNoPurchaseOnly          Boolean        @default(false)
+  birthdayMaxDistanceMiles        Int                   @default(25)
+  birthdayNoPurchaseOnly          Boolean               @default(false)
   /// Email reminder N days before birthday (birthday rewards plan nudge)
-  birthdayReminderEnabled         Boolean        @default(true)
-  birthdayReminderDaysAdvance     Int            @default(7)
-  birthdayCategories              String[]       @default([]) // e.g. restaurant, coffee, dessert
+  birthdayReminderEnabled         Boolean               @default(true)
+  birthdayReminderDaysAdvance     Int                   @default(7)
+  birthdayCategories              String[]              @default([]) // e.g. restaurant, coffee, dessert
   /// Calendar year when we last sent the "your birthday month freebies" reminder (cron on 1st of month).
   birthdayMonthReminderSentYear   Int?
   idDocumentUrl                   String? // Optional: secure ID upload for verification
@@ -1959,41 +2171,41 @@ model User {
   genderIdentity                  String?
   sex                             Sex?
   /// Public-profile visibility flags for self-reported demographics
-  showAgeOnProfile                Boolean        @default(true)
-  showGenderOnProfile             Boolean        @default(true)
+  showAgeOnProfile                Boolean               @default(true)
+  showGenderOnProfile             Boolean               @default(true)
   /// Master visibility toggle for ID/Payment/Host/Student trust badges
-  showVerifiedBadgesOnProfile     Boolean        @default(true)
+  showVerifiedBadgesOnProfile     Boolean               @default(true)
   organization                    String?
   jobTitle                        String?
-  roles                           UserRole[]     @default([User])
+  roles                           UserRole[]            @default([User])
   aboutMe                         String?
   levelBadge                      String?
-  temporaryBadges                 String[]       @default([])
+  temporaryBadges                 String[]              @default([])
   status                          UserStatus
   hostRating                      Float?
   totalRatings                    Int?
-  totalEventsHosted               Int?           @default(0) // Total published/completed events hosted
-  totalAttendeesHosted            Int?           @default(0) // Total checked-in attendees across all events
-  totalBookingsAccepted           Int?           @default(0) // Service provider stat
-  totalBookingsCompleted          Int?           @default(0) // Service provider stat
+  totalEventsHosted               Int?                  @default(0) // Total published/completed events hosted
+  totalAttendeesHosted            Int?                  @default(0) // Total checked-in attendees across all events
+  totalBookingsAccepted           Int?                  @default(0) // Service provider stat
+  totalBookingsCompleted          Int?                  @default(0) // Service provider stat
   magicLink                       String?
   magicLinkExpiration             DateTime?
   hostNumber                      Int?
-  foundingHostBadgeAwarded        Boolean        @default(false)
+  foundingHostBadgeAwarded        Boolean               @default(false)
   firstBashWithAttendeesDate      DateTime?
-  bashesCreatedCount              Int            @default(0)
-  bashesPublishedCount            Int            @default(0)
-  bashesApprovedCount             Int            @default(0)
-  bashesCompletedCount            Int            @default(0)
+  bashesCreatedCount              Int                   @default(0)
+  bashesPublishedCount            Int                   @default(0)
+  bashesApprovedCount             Int                   @default(0)
+  bashesCompletedCount            Int                   @default(0)
   magicLinkUsed                   DateTime?
   idVerified                      DateTime?
   street                          String?
   city                            String?
   state                           String?
   zipCode                         String?
-  country                         String?        @default("US")
+  country                         String?               @default("US")
   phone                           String?
-  documentIDId                    String?        @unique
+  documentIDId                    String?               @unique
   /// Encrypted-S3 key for the user's stored government-ID image (deleted per retention policy / on ID expiration)
   govIdImageS3Key                 String?
   /// When the gov-ID image becomes deletable (null = "indefinite, until I remove it").
@@ -2012,40 +2224,40 @@ model User {
   schoolName                      String?
   /// Whether `schoolName` came from the AI vision model or was edited by the user
   schoolNameSource                SchoolNameSource?
-  accepted                        Boolean?       @default(false)
-  boughtTicket                    Boolean?       @default(false)
-  noPay                           Boolean?       @default(false)
-  supportedEvent                  Boolean?       @default(false)
+  accepted                        Boolean?              @default(false)
+  boughtTicket                    Boolean?              @default(false)
+  noPay                           Boolean?              @default(false)
+  supportedEvent                  Boolean?              @default(false)
   suspendedUntil                  DateTime?
   suspendedById                   String?
-  isLightweightAccount            Boolean        @default(false)
-  notifyForTrendingBashes         Boolean        @default(false)
-  trendingBashThreshold           Int            @default(10)
-  artistsToSee                    String[]       @default([])
+  isLightweightAccount            Boolean               @default(false)
+  notifyForTrendingBashes         Boolean               @default(false)
+  trendingBashThreshold           Int                   @default(10)
+  artistsToSee                    String[]              @default([])
   googleCalendarSyncSettings      String?
-  membershipTier                  MembershipTier @default(Basic)
+  membershipTier                  MembershipTier        @default(Basic)
   membershipExpiresAt             DateTime?
-  membershipAutoRenew             Boolean        @default(false)
+  membershipAutoRenew             Boolean               @default(false)
   membershipBillingInterval       String?
   membershipLastBilledAt          DateTime?
-  membershipFeaturedEventsUsed    Int            @default(0)
-  membershipStripeSubscriptionId  String?        @unique
+  membershipFeaturedEventsUsed    Int                   @default(0)
+  membershipStripeSubscriptionId  String?               @unique
   /// Optional consumer BashPass subscription (waives guest platform fee on tickets; monthly BashPoints).
-  bashPassStripeSubscriptionId    String?        @unique
+  bashPassStripeSubscriptionId    String?               @unique
   bashPassCurrentPeriodEnd        DateTime?
   /// Stripe price tier for standalone BashPass; effective tier may also come from membership bundle.
   bashPassTier                    BashPassTier?
-  bashPassEventsUsedThisMonth     Int            @default(0)
+  bashPassEventsUsedThisMonth     Int                   @default(0)
   bashPassMonthlyCapResetAt       DateTime?
-  isVerified                      Boolean        @default(false)
+  isVerified                      Boolean               @default(false)
   verificationMethod              String?
   verifiedAt                      DateTime?
-  verificationScore               Int            @default(0)
+  verificationScore               Int                   @default(0)
   /// $1 card verification (Stripe) — distinct from Stripe Identity / isVerified
-  paymentVerified                 Boolean        @default(false)
+  paymentVerified                 Boolean               @default(false)
   paymentVerifiedAt               DateTime?
   /// One-time BashPoints bonus after $1 verification payment succeeded
-  paymentVerificationBonusAwarded Boolean        @default(false)
+  paymentVerificationBonusAwarded Boolean               @default(false)
   biometricFingerprint            String?
   venmoUsername                   String?
   venmoQRCodeUrl                  String?
@@ -2054,17 +2266,17 @@ model User {
   paymentHandle                   String?
   zellePhone                      String?
   zelleQRCodeUrl                  String?
-  isAmbashador                    Boolean        @default(false)
+  isAmbashador                    Boolean               @default(false)
   ambashadorAwardedAt             DateTime?
-  isBashInsider                   Boolean        @default(false)
+  isBashInsider                   Boolean               @default(false)
   insiderAwardedAt                DateTime?
-  scoutTier                       ScoutTier      @default(None)
+  scoutTier                       ScoutTier             @default(None)
   scoutAwardedAt                  DateTime?
   agentAwardedAt                  DateTime?
-  totalServiceReferrals           Int            @default(0)
-  isFirstInCity                   Boolean        @default(false)
+  totalServiceReferrals           Int                   @default(0)
+  isFirstInCity                   Boolean               @default(false)
   firstInCityAt                   DateTime?
-  fcmTokens                       String[]       @default([]) // Firebase Cloud Messaging tokens for push notifications
+  fcmTokens                       String[]              @default([]) // Firebase Cloud Messaging tokens for push notifications
 
   // BashPoints System Fields
   bashPointsBalance        Int     @default(0)
@@ -2104,6 +2316,7 @@ model User {
   referredTransactions           BashCreditTransaction[]      @relation("ReferredUser")
   creditTransactions             BashCreditTransaction[]
   createdEvents                  BashEvent[]                  @relation("CreatedEvent")
+  flyerCampaigns                 FlyerCampaign[]
   bashEventsTransferredFrom      BashEvent[]                  @relation("TransferredFrom")
   bashEventsPayoutRecipient      BashEvent[]                  @relation("BashEventsPayoutRecipient")
   bashEventMessagesSent          BashEventMessage[]           @relation("BashMessageSender")
@@ -2798,6 +3011,7 @@ model Service {
   entertainerMatches                 VenueEntertainmentMatch[]  @relation("EntertainerMatches")
   includes                           ServiceInclude[]
   addonRequests                      ServiceAddonRequest[]
+  serviceBudgets                     Budget[]                   @relation("ServiceBudgets")
 
   @@index([serviceListingStripeSubscriptionId])
   @@index([isFreeFirstListing])
@@ -3430,6 +3644,8 @@ model Budget {
   clubId         String?
   departmentId   String?
   userId         String? // For personal event budgets
+  /// Optional: budgets tied to a service profile (vendor/exhibitor/sponsor owner costs).
+  serviceId      String?
 
   // Budget details
   totalAllocatedCents Int
@@ -3462,6 +3678,7 @@ model Budget {
   club         Club?         @relation("ClubBudgets", fields: [clubId], references: [id], onDelete: Cascade)
   department   Department?   @relation("DepartmentBudgets", fields: [departmentId], references: [id], onDelete: Cascade)
   user         User?         @relation("UserBudgets", fields: [userId], references: [id], onDelete: Cascade)
+  service      Service?      @relation("ServiceBudgets", fields: [serviceId], references: [id], onDelete: Cascade)
   submitter    User?         @relation("BudgetSubmitter", fields: [submittedBy], references: [id])
   approver     User?         @relation("BudgetApprover", fields: [approverId], references: [id])
   expenses     Expense[]
@@ -3471,10 +3688,18 @@ model Budget {
   @@index([clubId])
   @@index([departmentId])
   @@index([userId])
+  @@index([serviceId])
   @@index([status])
   @@index([fiscalYear])
 }
 
+enum ExpenseExtractionStatus {
+  none
+  pending
+  complete
+  failed
+}
+
 model Expense {
   id              String    @id @default(cuid())
   budgetId        String
@@ -3490,6 +3715,29 @@ model Expense {
   rejectionReason String?
   createdAt       DateTime  @default(now())
   updatedAt       DateTime  @updatedAt
+
+  /// Optional link to an event task (e.g. volunteer receipt for a specific task).
+  eventTaskId String?
+  eventTask   EventTask? @relation(fields: [eventTaskId], references: [id], onDelete: SetNull)
+
+  /// User-confirmed or extracted metadata (Textract suggestions are confirmed before save).
+  vendorName   String?
+  taxCents     Int?
+  subtotalCents Int?
+  currency     String? @default("USD")
+
+  extractionStatus ExpenseExtractionStatus @default(none)
+  textractRaw        Json?
+
+  /// Vendor invoice number (manual or extracted).
+  invoiceNumber   String?
+  /// When payment is due (separate from expenseDate / receipt date).
+  invoiceDueDate  DateTime?
+  /// Host marked invoice as paid outside the app — stops due-date reminders.
+  invoicePaidAt   DateTime?
+  /// Tracks which invoice due reminders were sent: { dueSoon, dueDay, pastDue1, pastDue15 }.
+  invoiceDueRemindersSent Json?
+
   budget          Budget    @relation(fields: [budgetId], references: [id], onDelete: Cascade)
   submitter       User      @relation("ExpenseSubmitter", fields: [submittedBy], references: [id])
   approver        User?     @relation("ExpenseApprover", fields: [approvedBy], references: [id])
@@ -3497,6 +3745,8 @@ model Expense {
   @@index([budgetId])
   @@index([submittedBy])
   @@index([status])
+  @@index([eventTaskId])
+  @@index([invoiceDueDate])
 }
 
 model ServiceRange {
@@ -4418,6 +4668,12 @@ enum NotificationType {
   HostTopPromoter // Host: "Top promoter: Alex (6 tickets today)"
   HostSalesSlowing // Host: "Sales slowed today. Try sharing your event."
   TicketSold // Host: a ticket was purchased for your event (debounced in webhook)
+  BudgetExpenseSubmitted // Host/organizer: assignee or member submitted an expense
+  BudgetLineThreshold // Host/organizer: budget line crossed a spend threshold (e.g. 80% / 100%)
+  BudgetInvoiceDueSoon // Host/organizer: invoice due in ~3 days
+  BudgetInvoiceDueToday // Host/organizer: invoice due today
+  BudgetInvoicePastDue // Host/organizer: invoice 1 day past due
+  BudgetInvoicePastDueFinal // Host/organizer: invoice 15+ days past due
 }
 
 enum NotificationPriority {
@@ -4744,6 +5000,15 @@ enum CustomScopeStatus {
   Rejected
 }
 
+/// AI bash-approval reviewer verdict (see `bashApprovalAiService`).
+/// `Approve` and `Reject` are recommendations; whether the system acts on them
+/// vs. queues for a human depends on confidence + AI_BASH_APPROVAL_MODE.
+enum AiApprovalVerdict {
+  Approve
+  Flag
+  Reject
+}
+
 /// How a user is associated with a bash (for BashFeedPost display: "Sarah attended...", "Mike is hosting...")
 enum BashAssociationType {
   Hosting
@@ -5026,6 +5291,7 @@ enum FoodAndBeverageSubType {
   Bartenders
   DessertBar
   BeverageCart
+  ConcessionStand
 }
 
 enum CleaningSubType {
@@ -5057,6 +5323,9 @@ enum RentalEquipmentSubType {
   Generators
   DanceFloor
   PhotoBooth
+  BounceHouse
+  WaterSlide
+  CarnivalGames
 }
 
 enum MediaProductionAndCreativeSubType {

package/src/aiApproval.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared shapes for the AI bash-approval reviewer.
+ *
+ * The Zod runtime envelope lives in `api/src/utils/ai/aiApprovalEnvelope.ts` (zod is an api
+ * dependency, not a bash-common one). This file is the type-only source of truth that both
+ * the api worker and bash-app's admin UI/host-facing banners read.
+ *
+ * The persisted `BashEvent.aiApprovalReasons` JSON column is exactly an `AiApprovalReasons`.
+ */
+
+import type { AiApprovalVerdict } from "@prisma/client";
+
+/**
+ * Each criterion the model grades on.
+ *
+ * Keep this list short and stable — it controls the persisted JSON shape, the prompt
+ * the model sees, and the badges the admin UI renders. Adding a new criterion is a
+ * schema change (existing rows will be missing it).
+ */
+export const AI_APPROVAL_CRITERION_KEYS = [
+  "completeness",
+  "authenticity",
+  "safety",
+  "policyFit",
+] as const;
+
+export type AiApprovalCriterionKey = (typeof AI_APPROVAL_CRITERION_KEYS)[number];
+
+/**
+ * Display labels for criteria — used in the admin queue and any host-facing breakdown.
+ * Keep keys exhaustive against `AiApprovalCriterionKey` (compiler will yell if drift).
+ */
+export const AiApprovalCriterionLabel: Record<AiApprovalCriterionKey, string> = {
+  completeness: "Completeness",
+  authenticity: "Authenticity",
+  safety: "Safety",
+  policyFit: "Policy fit",
+};
+
+/**
+ * One criterion's grade. `score` is 0..1; `notes` is short free-text the model wrote
+ * about why (shown in the admin UI tooltip / host rejection reasons).
+ */
+export interface AiApprovalCriterionResult {
+  score: number;
+  notes: string;
+}
+
+/**
+ * Persisted shape for `BashEvent.aiApprovalReasons` (Json column).
+ *
+ * - `criteria` keys are exhaustive over `AiApprovalCriterionKey`.
+ * - `hostFacingMessage` is shown to the host on rejection; written specifically to be
+ *   actionable ("Add a start time and a location, then resubmit"), not generic.
+ *   Null on approve.
+ * - `adminFacingNotes` is for super-users in the review queue; can be more candid
+ *   ("Looks like a duplicate of bash xyz" / "Probably a service ad in disguise").
+ */
+export interface AiApprovalReasons {
+  criteria: Record<AiApprovalCriterionKey, AiApprovalCriterionResult>;
+  hostFacingMessage: string | null;
+  adminFacingNotes: string;
+}
+
+/**
+ * Runtime values for the Prisma `AiApprovalVerdict` enum.
+ *
+ * Browser code (bash-app) cannot rely on `@prisma/client`'s runtime enum exports — the
+ * package's `browser` resolution doesn't reliably surface them when imported transitively
+ * via `@bash-app/bash-common`. So we mirror the enum here as a plain string-keyed object
+ * and `satisfies Record<AiApprovalVerdict, AiApprovalVerdict>` to guarantee at compile
+ * time that the keys/values stay in lockstep with `schema.prisma`. Prefer
+ * `AI_APPROVAL_VERDICTS.Approve` over `AiApprovalVerdict.Approve` in any code path that
+ * may be bundled for the browser.
+ */
+export const AI_APPROVAL_VERDICTS = {
+  Approve: "Approve",
+  Flag: "Flag",
+  Reject: "Reject",
+} as const satisfies Record<AiApprovalVerdict, AiApprovalVerdict>;
+
+/**
+ * Display labels for the Prisma `AiApprovalVerdict` enum, used in admin pills and the
+ * host rejection banner so callers don't reach for ad-hoc switch statements.
+ *
+ * The `Record<AiApprovalVerdict, string>` annotation enforces exhaustiveness at compile
+ * time, so adding/renaming an enum member in `schema.prisma` will fail tsc here.
+ */
+export const AiApprovalVerdictLabel: Record<AiApprovalVerdict, string> = {
+  Approve: "Approve",
+  Flag: "Flag for review",
+  Reject: "Reject",
+};
+
+/**
+ * Feature-flag values for `AI_BASH_APPROVAL_MODE`.
+ *
+ * - `off`             - AI service is never invoked. Existing manual-only workflow.
+ * - `shadow`          - AI runs and persists verdict + reasons, but every outcome is `flag`.
+ *                       Admins still decide everything; we use the data to tune thresholds.
+ * - `auto-with-flag`  - High-confidence approve/reject act automatically; the rest flag for human.
+ * - `auto-approve-only` - High-confidence approve acts automatically; rejects always flag for human.
+ */
+export const AI_BASH_APPROVAL_MODES = [
+  "off",
+  "shadow",
+  "auto-with-flag",
+  "auto-approve-only",
+] as const;
+
+export type AiBashApprovalMode = (typeof AI_BASH_APPROVAL_MODES)[number];
+
+/**
+ * Default thresholds. Tune in the api consumer if behavior needs to change post-rollout;
+ * exporting here so tests in api can import a single source of truth.
+ */
+export const AI_APPROVAL_AUTO_APPROVE_CONFIDENCE = 0.85;
+export const AI_APPROVAL_AUTO_REJECT_CONFIDENCE = 0.9;