Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@cfc7760af31f29f1acc7153a7e9fcb48d35f730b

Author: github-actions[bot]

bun.lock

@@ -11,6 +11,8 @@ import {
   PLACEMENT_METRIC_LABELS,
   PLACEMENT_PREVIEW_WIDTHS,
   PLACEMENT_SLOTS,
+  TRACKED_LINK_PLACEMENT_ID,
+  placementSlotLabel,
   PLACEMENT_STATUS_LABELS,
   PRIMARY_METRICS,
   UNDERSPEND_COPY,
@@ -246,3 +248,48 @@ describe('copy and configuration', () => {
     expect(PLACEMENT_METRIC_LABELS.ecpm).toBe('Effective CPM')
   })
 })
+
+/**
+ * The reporting grain is wider than the slot catalog, and the labeller has to
+ * know it.
+ *
+ * `PLACEMENT_SLOTS` lists what an advertiser can buy a position in. A tracked
+ * link is not one of those — nothing auctions it and nothing serves an
+ * impression into it — but the delivery rollup groups by `placement_id`, so
+ * every surface that labels a placement will meet it.
+ */
+describe('placementSlotLabel', () => {
+  it('renders every real slot exactly as the breakdown table already did', () => {
+    // This is a behaviour-preservation assertion, not a new format: these
+    // strings are what the table showed before the labeller moved here.
+    expect(placementSlotLabel('waiting-room-1')).toBe('Waiting room 1')
+    expect(placementSlotLabel('CLI-Chat-Inline')).toBe('CLI Chat Inline')
+    expect(placementSlotLabel('Web-Chat-After-User-Message')).toBe(
+      'Web Chat After User Message',
+    )
+    for (const slot of PLACEMENT_SLOTS) {
+      expect(placementSlotLabel(slot.id).length).toBeGreaterThan(0)
+    }
+  })
+
+  it('names the tracked-link grain, which no slot describes', () => {
+    expect(placementSlotLabel(TRACKED_LINK_PLACEMENT_ID)).toBe('Tracked links')
+    // That it is not a slot is proved by the compiler rather than asserted
+    // here: `PLACEMENT_SLOTS` is `as const`, so comparing a slot id against
+    // this constant is a type error ("no overlap"). Adding it to the catalog
+    // would put a tracked link in front of an advertiser choosing where their
+    // ad appears, which is not what it is.
+    expect(
+      (PLACEMENT_SLOTS as readonly { id: string }[]).some(
+        (slot) => slot.id === TRACKED_LINK_PLACEMENT_ID,
+      ),
+    ).toBe(false)
+  })
+
+  it('degrades an unknown grain to something readable, never undefined', () => {
+    // The next grain after tracked links must render as a string a human can
+    // read, not as a gap that looks like a bug in the numbers beside it.
+    expect(placementSlotLabel('some-future-grain')).toBe('Some future grain')
+    expect(placementSlotLabel('')).toBe('')
+  })
+})

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

@@ -121,6 +121,39 @@ export const PLACEMENT_SLOTS = [
   },
 ] as const
 
+/**
+ * The reporting grain a TRACKED LINK click lands on.
+ *
+ * Deliberately NOT a `PLACEMENT_SLOTS` entry: a tracked link is not a slot,
+ * nothing auctions it, nothing serves an impression into it, and adding it to
+ * that list would put it in front of an advertiser choosing where their ad
+ * appears. But the delivery rollup groups by `placement_id` and `surface`, so
+ * an external click has to carry SOME value for both, and every surface that
+ * labels a placement will meet these two.
+ *
+ * `placementSlotLabel` below is what stops that meeting rendering `undefined`.
+ */
+export const TRACKED_LINK_PLACEMENT_ID = 'tracked-link'
+export const TRACKED_LINK_SURFACE = 'tracked_link'
+
+/**
+ * A human label for any `placement_id`, including grains no slot describes.
+ *
+ * `PLACEMENT_SLOTS` is a catalog of things an advertiser can BUY, and the
+ * reporting grain is strictly wider than it -- tracked links today, and
+ * whatever the next one is. So this is a formatter with a special case, not a
+ * dictionary lookup with a hole: `waiting-room-1` still becomes
+ * `Waiting room 1` and `CLI-Chat-Inline` still becomes `CLI Chat Inline`,
+ * exactly as the breakdown table already rendered them, and an unknown id
+ * degrades to a readable string rather than to `undefined`.
+ */
+export function placementSlotLabel(placementId: string): string {
+  if (placementId === TRACKED_LINK_PLACEMENT_ID) return 'Tracked links'
+  const [head, ...rest] = placementId.split('-')
+  if (!head) return placementId
+  return [head[0]!.toUpperCase() + head.slice(1), ...rest].join(' ')
+}
+
 /**
  * The metrics an advertiser sees, split by role.
  *

common/src/constants/freebuff-placements.ts

@@ -6,6 +6,7 @@ import {
   IMPREZIA_EXPERIMENT_PERCENT,
   adExperimentArmForUser,
   firstPartyAdRouteForUser,
+  firstPartyPrimaryBasisPoints,
   isImpreziaAudienceEmail,
 } from '../ad-experiment'
 
@@ -53,6 +54,13 @@ describe('imprezia experiment arm', () => {
 })
 
 describe('first-party request routing', () => {
+  test('normalizes decimal percentages to the same integer basis points used by campaign allocation', () => {
+    expect(firstPartyPrimaryBasisPoints(1.234)).toBe(123)
+    expect(firstPartyPrimaryBasisPoints(-1)).toBe(0)
+    expect(firstPartyPrimaryBasisPoints(101)).toBe(10_000)
+    expect(firstPartyPrimaryBasisPoints(Number.NaN)).toBe(0)
+  })
+
   test('keeps an absent runtime configuration on the paid-network-only path', () => {
     expect(DEFAULT_FIRST_PARTY_PRIMARY_PERCENT).toBe(0)
     expect(DEFAULT_FIRST_PARTY_BACKFILL).toBe(false)

common/src/util/__tests__/ad-experiment.test.ts

@@ -156,6 +156,10 @@ describe('getAxiomOnlyLogEvent', () => {
         first_party_route: 'gravity_then_first_party',
         first_party_primary_percent: 10,
         first_party_backfill_enabled: true,
+        first_party_primary_cohort: 'pilot-a',
+        first_party_primary_cohort_percent: 1,
+        first_party_served_cohort: 'pilot-a',
+        first_party_entrypoint: 'primary',
         gravity_outcome: 'no_fill',
         selection_reason: 'gravity_no_fill_backfill',
         ad_count: 1,
@@ -186,6 +190,10 @@ describe('getAxiomOnlyLogEvent', () => {
         first_party_route: 'gravity_then_first_party',
         first_party_primary_percent: 10,
         first_party_backfill_enabled: true,
+        first_party_primary_cohort: 'pilot-a',
+        first_party_primary_cohort_percent: 1,
+        first_party_served_cohort: 'pilot-a',
+        first_party_entrypoint: 'primary',
         gravity_outcome: 'no_fill',
         selection_reason: 'gravity_no_fill_backfill',
         ad_count: 1,
@@ -204,6 +212,7 @@ describe('getAxiomOnlyLogEvent', () => {
         axiomEvent: ADS_FIRST_PARTY_DECISION_EVENT,
         outcome: 'no_fill',
         no_fill_reason: 'no_eligible_campaign',
+        primary_allocation_invalid: true,
         placement_count: 2,
         candidate_count: 4,
         candidate_load_ms: 8,
@@ -223,6 +232,7 @@ describe('getAxiomOnlyLogEvent', () => {
       data: {
         outcome: 'no_fill',
         no_fill_reason: 'no_eligible_campaign',
+        primary_allocation_invalid: true,
         placement_count: 2,
         candidate_count: 4,
         candidate_load_ms: 8,

common/src/util/__tests__/axiom-only-log.test.ts

@@ -52,6 +52,19 @@ export interface FirstPartyRoutingConfig {
   backfill: boolean
 }
 
+/**
+ * Normalize the percentage knob to the 10,000-bucket precision used by both
+ * request routing and campaign allocation. Keeping this conversion shared
+ * prevents decimal environment values from opening a route that the campaign
+ * selector later rejects (or vice versa).
+ */
+export function firstPartyPrimaryBasisPoints(primaryPercent: number): number {
+  const configuredPercent = Number.isFinite(primaryPercent)
+    ? primaryPercent
+    : DEFAULT_FIRST_PARTY_PRIMARY_PERCENT
+  return Math.round(Math.min(100, Math.max(0, configuredPercent)) * 100)
+}
+
 export type AdExperimentArm = 'imprezia_forced' | 'imprezia_first' | 'control'
 
 export function isImpreziaAudienceEmail(
@@ -104,11 +117,9 @@ export function firstPartyAdRouteForUser(
   config: FirstPartyRoutingConfig,
 ): FirstPartyAdRoute {
   if (!userId) return 'paid_network_only'
-  const configuredPercent = Number.isFinite(config.primaryPercent)
-    ? config.primaryPercent
-    : DEFAULT_FIRST_PARTY_PRIMARY_PERCENT
-  const primaryPercent = Math.min(100, Math.max(0, configuredPercent))
   const bucket = fnv1a(`${FIRST_PARTY_ROUTING_EXPERIMENT}:${userId}`) % 10_000
-  if (bucket < primaryPercent * 100) return 'first_party_primary'
+  if (bucket < firstPartyPrimaryBasisPoints(config.primaryPercent)) {
+    return 'first_party_primary'
+  }
   return config.backfill ? 'gravity_then_first_party' : 'paid_network_only'
 }

common/src/util/ad-experiment.ts

@@ -75,6 +75,18 @@ const ADS_FETCH_COMPLETED_FIELDS = {
   first_party_route: 'string',
   first_party_primary_percent: 'number',
   first_party_backfill_enabled: 'boolean',
+  /**
+   * Exact primary allocation is intentionally represented by an opaque,
+   * operator-chosen cohort label rather than a campaign or advertiser id.
+   * Producers emit `none` / 0 when the request is not assigned to a primary
+   * cohort, so an absent field is distinguishable from a deliberate control.
+   */
+  first_party_primary_cohort: 'string',
+  first_party_primary_cohort_percent: 'number',
+  /** The opaque cohort that actually produced a first-party fill, or `none`. */
+  first_party_served_cohort: 'string',
+  /** `primary`, `gravity_no_fill_backfill`, or `none`. */
+  first_party_entrypoint: 'string',
   /** Whether the immediately preceding Gravity attempt filled, no-filled, or
    * failed. This makes recovered no-fill inventory observable without logging
    * any campaign or creative identity. */
@@ -96,6 +108,7 @@ const ADS_FETCH_COMPLETED_FIELDS = {
  */
 const ADS_FIRST_PARTY_DECISION_FIELDS = {
   outcome: 'string',
+  primary_allocation_invalid: 'boolean',
   no_fill_reason: 'string',
   selection_reason: 'string',
   ad_count: 'number',