Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@f5d374366a16dd9dc17e2158bb613a27bd41d568

Author: github-actions[bot]

common/src/__tests__/freebuff-placements.test.ts

@@ -20,6 +20,10 @@ import {
   PLACEMENT_SLOTS,
   SPONSOR_BREAK_CREATIVE_LIMITS,
   SPONSOR_BREAK_FORMATS,
+  INTERRUPTING_BREAK_FORMATS,
+  isInterruptingBreakFormat,
+  isInterruptingBreakPlacement,
+  isSponsorBreakFormat,
   SPONSOR_BREAK_HERO_SPEC,
   TRACKED_LINK_PLACEMENT_ID,
   isSponsorBreakPlacement,
@@ -271,6 +275,33 @@ describe('copy and configuration', () => {
     ])
   })
 
+  it('caps the two INTERRUPTING breaks and never Showcase (COD-455)', () => {
+    // Two predicates, two questions. The creative rules (hero required, no
+    // text-only house floor) are the same for all three; the daily cap, the
+    // min-session floor and the fail-closed-with-no-Redis are the price of
+    // TAKING THE SCREEN AWAY, which Showcase does not do -- it is the same
+    // above-composer slot drawn taller, on the same rotation as the banner it
+    // is being compared against. Capping it at one a day would leave the
+    // treatment arm byte-identical to control for all but one rotation, so the
+    // format test would measure nothing.
+    expect(INTERRUPTING_BREAK_FORMATS).toEqual(['spotlight', 'intermission'])
+    expect(isInterruptingBreakFormat('showcase')).toBe(false)
+    expect(isSponsorBreakFormat('showcase')).toBe(true)
+
+    const interrupting = PLACEMENT_SLOTS.filter((slot) =>
+      isInterruptingBreakPlacement(slot.id),
+    ).map((slot) => slot.id)
+    expect(interrupting).toEqual(['Desktop-Spotlight', 'Desktop-Intermission'])
+    expect(isInterruptingBreakPlacement('Desktop-Showcase')).toBe(false)
+
+    // Still the conservative fallback for an unknown id, in both directions.
+    expect(isInterruptingBreakPlacement('some-future-grain')).toBe(false)
+    // Every interrupting format is a break; the reverse does not hold.
+    for (const format of INTERRUPTING_BREAK_FORMATS) {
+      expect([format, isSponsorBreakFormat(format)]).toEqual([format, true])
+    }
+  })
+
   it('answers inline for an id it does not know, never undefined', () => {
     // The conservative direction. An unknown id guessed as a break would turn
     // one typo into a full-screen interruption; guessed as inline it renders

common/src/ads/__tests__/sponsor-break-events.test.ts

@@ -7,10 +7,12 @@ import {
   buildSponsorBreakEvent,
   clampDwellMs,
   isSponsorBreakCloseMethod,
+  isSponsorBreakEvent,
   readDwellMs,
   SPONSOR_BREAK_ACCIDENTAL_CLICK_MS,
   SPONSOR_BREAK_CLOSE_METHODS,
   SPONSOR_BREAK_DWELL_MAX_MS,
+  SPONSOR_BREAK_EVENTS,
 } from '../sponsor-break-events'
 
 import {
@@ -247,3 +249,27 @@ describe('the Axiom allowlist', () => {
     }
   })
 })
+
+describe('isSponsorBreakEvent', () => {
+  test('admits the three names and nothing else', () => {
+    // A CLOSED set at the boundary, for the same reason the close methods
+    // are: these become the `event` field every break readout groups on, and
+    // a client that could invent one would widen that field's cardinality
+    // with rows nothing queries.
+    for (const event of SPONSOR_BREAK_EVENTS) {
+      expect(isSponsorBreakEvent(event)).toBe(true)
+    }
+    for (const value of [
+      'ads.break_exploded',
+      'ads.fetch_completed',
+      '',
+      ' ads.break_shown',
+      null,
+      undefined,
+      42,
+      { event: 'ads.break_shown' },
+    ]) {
+      expect(isSponsorBreakEvent(value)).toBe(false)
+    }
+  })
+})

common/src/ads/sponsor-break-events.ts

@@ -46,6 +46,23 @@ export const SPONSOR_BREAK_EVENTS = [
 ] as const
 export type SponsorBreakEvent = (typeof SPONSOR_BREAK_EVENTS)[number]
 
+/**
+ * Whether an untrusted value names one of the three break events.
+ *
+ * A CLOSED set at the boundary, for the same reason
+ * {@link isSponsorBreakCloseMethod} is: these names become the `event` field
+ * every break readout groups on, and a client that could invent one would
+ * widen that field's cardinality with rows nothing queries.
+ */
+export function isSponsorBreakEvent(
+  value: unknown,
+): value is SponsorBreakEvent {
+  return (
+    typeof value === 'string' &&
+    (SPONSOR_BREAK_EVENTS as readonly string[]).includes(value)
+  )
+}
+
 /**
  * How a break ended. A CLOSED vocabulary, like the census codes: these are a
  * histogram dimension and an open set would let a new renderer widen the
@@ -165,11 +182,18 @@ export interface SponsorBreakEventPayload {
   timer_ms?: number
   timer_completed?: boolean
   /**
-   * SPOTLIGHT'S DISMISS LOCK (COD-454): how long the ways OUT were held, in
-   * milliseconds of VISIBLE time. Separate from `timer_ms` because the two
-   * hold different things -- the countdown gates the whole card, the lock only
-   * the dismissals -- and pooling them would make the readout unable to say
-   * which format a row came from without joining on `format`.
+   * THE DISMISS LOCK: how long the ways OUT were held, in milliseconds of
+   * VISIBLE time. Spotlight (COD-454) and Showcase (COD-455) both hold their
+   * dismissals, so this is ONE field across the formats and `format` is what
+   * separates them.
+   *
+   * Separate from `timer_ms` because the two hold different things -- the
+   * countdown gates the whole card, the lock only the dismissals -- and
+   * pooling them would make the readout unable to say which format a row came
+   * from without joining on `format`. Concretely: Intermission's `timer_ms`
+   * counts down to a Continue button the person is waiting ON, while this
+   * counts down to a control they may never look for, on a card that is fully
+   * clickable and fully ignorable throughout.
    */
   dismiss_lock_ms?: number
   /**

common/src/constants/freebuff-placements.ts

@@ -120,6 +120,40 @@ export function isSponsorBreakFormat(format: PlacementFormat): boolean {
   return format !== 'inline'
 }
 
+/**
+ * The formats that INTERRUPT, which is a strictly narrower question than
+ * {@link isSponsorBreakFormat} and the only one the daily cap may ask.
+ *
+ * The two predicates exist because COD-453 conflated two properties that
+ * happen to coincide for two of the three break formats:
+ *
+ * - WHAT A CREATIVE MUST LOOK LIKE. Image-led, hero required, tight copy, and
+ *   never the text-only house floor. True of all three, which is what
+ *   {@link isSponsorBreakFormat} answers, and it stays the predicate every
+ *   creative-shape rule reads.
+ * - WHAT IT COSTS THE READER. `spotlight` and `intermission` take the screen
+ *   away from the work in front of them, which is why they are rationed: one
+ *   per UTC day, never inside the first ten minutes of a session, and never at
+ *   all on a deployment with no Redis to count them. `showcase` takes nothing
+ *   away -- it is the SAME slot above the composer that already holds a
+ *   sponsored banner every sixty seconds, drawn taller (COD-455).
+ *
+ * Capping Showcase makes its own experiment unrunnable rather than merely
+ * conservative: the treatment arm would see the tall card for at most one
+ * rotation a day and be byte-identical to control for the rest of it, so the
+ * format test would measure nothing and the null result would read as "the
+ * format made no difference". A frequency cap on a unit whose frequency is
+ * fixed by the arm it is being compared against is not a safety margin.
+ */
+export const INTERRUPTING_BREAK_FORMATS: readonly PlacementFormat[] = [
+  'spotlight',
+  'intermission',
+]
+
+export function isInterruptingBreakFormat(format: PlacementFormat): boolean {
+  return INTERRUPTING_BREAK_FORMATS.includes(format)
+}
+
 /**
  * Placements an advertiser can buy.
  *
@@ -301,6 +335,15 @@ export function isSponsorBreakPlacement(placementId: string): boolean {
   return isSponsorBreakFormat(placementFormat(placementId))
 }
 
+/**
+ * Whether this placement id INTERRUPTS, and is therefore subject to the daily
+ * cap. See {@link INTERRUPTING_BREAK_FORMATS} for why this is not the same
+ * question as {@link isSponsorBreakPlacement}.
+ */
+export function isInterruptingBreakPlacement(placementId: string): boolean {
+  return isInterruptingBreakFormat(placementFormat(placementId))
+}
+
 /**
  * What a creative must look like to fill a SPONSOR BREAK.
  *