@ak--47/dungeon-master 1.4.5 → 1.5.0

package/lib/templates/macro-presets.js

@@ -23,55 +23,85 @@
  *   across [FIXED_BEGIN - 30d, FIXED_BEGIN] so they don't all stack at day 0).
  */
 
+/**
+ * Tuned tail_ratio targets (foobar 89-day, post-engine-bunchiness fix):
+ *
+ *   flat:    ~1.1  (≈ 1.0 baseline + small cumulative-acquisition uptick)
+ *   steady:  ~1.1  (slightly higher uptick from 0.1 bias)
+ *   growth:  ~1.4  (clear visible uptrend)
+ *   viral:   ~2.2  (hockey stick — clearly distinguishable)
+ *   decline: ~1.0  (flat — pure-dungeon limitation, see decline JSDoc)
+ *
+ * All five remain DIRECTIONALLY distinguishable on aggregate event count over
+ * time. Magnitude diverges from `research/end-bunchiness.md` v1.3 targets
+ * (which were measured pre-engine-bunchiness-fix); the new targets are what's
+ * achievable with the v1.5 engine fix's per-cluster trapezoidal shape.
+ */
+
 /** @type {Record<string, {bornRecentBias: number, percentUsersBornInDataset: number, preExistingSpread: 'pinned'|'uniform'}>} */
 export const MACRO_PRESETS = {
 	/**
 	 * flat (DEFAULT) — Mature product, no growth narrative.
-	 * Tail ratio ≈ 1.0. Pure weekly oscillation, no net drift.
+	 * Foobar tail_ratio ≈ 1.1 (very slight uptrend from 12% acquisition).
+	 * Pure weekly oscillation dominates the visual.
 	 */
 	flat: {
 		bornRecentBias: 0,
-		percentUsersBornInDataset: 50,
+		percentUsersBornInDataset: 12,
 		preExistingSpread: 'uniform',
 	},
 
 	/**
 	 * steady — Lightly-growing SaaS.
-	 * Slight uptrend without any visible spike at the right edge.
+	 * Foobar tail_ratio ≈ 1.1. Slight uptrend without any visible spike.
+	 * Effectively similar to "flat" on a flat dungeon — the slight bornRecentBias
+	 * shows up more clearly when paired with hooks that magnify late-cohort
+	 * activity (e.g., engagement decay scoped to early users).
 	 */
 	steady: {
 		bornRecentBias: 0.1,
-		percentUsersBornInDataset: 35,
+		percentUsersBornInDataset: 12,
 		preExistingSpread: 'uniform',
 	},
 
 	/**
 	 * growth — Visible uptrend story without the meteoric blow-up.
+	 * Foobar tail_ratio ≈ 1.4. Clearly distinguishable from flat/steady.
 	 * Use when the dataset wants to show clear acquisition over time.
 	 */
 	growth: {
 		bornRecentBias: 0.3,
-		percentUsersBornInDataset: 60,
+		percentUsersBornInDataset: 30,
 		preExistingSpread: 'pinned',
 	},
 
 	/**
 	 * viral — Hockey-stick acquisition.
-	 * Strong late-window ramp. Pair with persona/feature hooks for the full effect.
+	 * Foobar tail_ratio ≈ 2.2. Strong late-window ramp.
+	 * Pair with persona/feature hooks for the full effect.
 	 */
 	viral: {
 		bornRecentBias: 0.6,
-		percentUsersBornInDataset: 95,
+		percentUsersBornInDataset: 55,
 		preExistingSpread: 'pinned',
 	},
 
 	/**
 	 * decline — Sunsetting product, churning users.
-	 * Few new users, those that exist are born early. Pair with churn hooks.
+	 * Foobar tail_ratio ≈ 1.0 — **the bornRecentBias mechanism alone CANNOT
+	 * produce a downtrend** without a churn mechanism. Born-early users
+	 * generate events throughout `[birth, FIXED_NOW]`, so they contribute to
+	 * the right edge as much as the left. To get a real visible downtrend,
+	 * pair this preset with `engagementDecay` or a hook that drops late
+	 * events for early-cohort users (see HOOKS.md). On a pure dungeon
+	 * (foobar) this preset is effectively flat with a slight early-cohort
+	 * skew. v1.3-era pre-engine-fix verticals (ai-platform/sass/dating)
+	 * measured tail_ratio ≈ 0.80 for decline because their hooks include
+	 * implicit churn behavior.
 	 */
 	decline: {
 		bornRecentBias: -0.3,
-		percentUsersBornInDataset: 25,
+		percentUsersBornInDataset: 5,
 		preExistingSpread: 'uniform',
 	},
 };

package/lib/utils/utils.js

@@ -188,7 +188,6 @@ function datesBetween(start, end) {
  * @param  {any} end
  */
 function day(start, end) {
-	// if (!end) end = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
 	if (!start) start = DATASET_NOW.subtract(30, 'd').toISOString();
 	if (!end) end = DATASET_NOW.toISOString();
 	const chance = getChance();
@@ -1063,8 +1062,10 @@ function validateEventConfig(events) {
 }
 
 function validTime(chosenTime, earliestTime, latestTime) {
-	if (!earliestTime) earliestTime = global.FIXED_BEGIN ? global.FIXED_BEGIN : dayjs().subtract(30, 'd').unix(); // 30 days ago
-	if (!latestTime) latestTime = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
+	// Fallback: use module-scoped DATASET_BEGIN/NOW (set by orchestrator via
+	// setDatasetBegin/setDatasetNow). v1.5: no longer reads `global.FIXED_*`.
+	if (!earliestTime) earliestTime = DATASET_BEGIN.unix();
+	if (!latestTime) latestTime = DATASET_NOW.unix();
 
 	if (typeof chosenTime === 'number') {
 		if (chosenTime > 0) {
@@ -1286,8 +1287,10 @@ const DEFAULT_HOD_WEIGHTS = [
 ];
 
 function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0, dayOfWeekWeights = DEFAULT_DOW_WEIGHTS, hourOfDayWeights = DEFAULT_HOD_WEIGHTS) {
-	if (!earliestTime) earliestTime = global.FIXED_BEGIN ? global.FIXED_BEGIN : dayjs().subtract(30, 'd').unix();
-	if (!latestTime) latestTime = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
+	// Fallback: use module-scoped DATASET_BEGIN/NOW (set by orchestrator via
+	// setDatasetBegin/setDatasetNow). v1.5: no longer reads `global.FIXED_*`.
+	if (!earliestTime) earliestTime = DATASET_BEGIN.unix();
+	if (!latestTime) latestTime = DATASET_NOW.unix();
 	const chance = getChance();
 	let totalRange = latestTime - earliestTime;
 	if (totalRange <= 0 || earliestTime > latestTime) {
@@ -1571,78 +1574,6 @@ function generateSessionId(seedStr) {
 	return [seg(), seg(), seg(), seg()].join("-");
 }
 
-/**
- * Redistributes events into temporal clusters (sessions).
- *
- * Algorithm:
- * 1. Sort events by time
- * 2. Determine number of sessions (total events / avg events per session)
- * 3. Generate session anchor times using TimeSoup
- * 4. Assign events round-robin to sessions
- * 5. Within each session, retime events with tight spacing (5-300s apart)
- * 6. Regenerate insert_ids for retimed events
- * 7. Re-sort by time
- *
- * Mutates events in place. Does NOT assign session_id (call assignSessionIds after).
- *
- * @param {Object[]} events - Array of event objects with .time (ISO string)
- * @param {number} timeoutMinutes - Session timeout in minutes (used to determine intra-session spacing)
- * @param {Object} soupParams - Parameters for TimeSoup anchor generation
- */
-function bunchIntoSessions(events, timeoutMinutes, soupParams) {
-	if (events.length < 2) return;
-
-	const chance = getChance();
-	const { earliestTime, latestTime, peaks, deviation, mean,
-		dayOfWeekWeights, hourOfDayWeights } = soupParams;
-
-	// Sort by time first
-	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
-
-	// Determine number of sessions: target 3-8 events per session
-	const eventsPerSession = chance.integer({ min: 3, max: 8 });
-	const numSessions = Math.max(1, Math.ceil(events.length / eventsPerSession));
-
-	// Generate session anchor times using TimeSoup
-	const anchors = [];
-	for (let i = 0; i < numSessions; i++) {
-		const soupTime = TimeSoup(earliestTime, latestTime, peaks, deviation, mean,
-			dayOfWeekWeights, hourOfDayWeights);
-		anchors.push(soupTime);
-	}
-	anchors.sort((a, b) => a - b);
-
-	// Distribute events across sessions round-robin (preserving original order → temporal order)
-	const sessionBuckets = anchors.map(() => []);
-	for (let i = 0; i < events.length; i++) {
-		const bucketIndex = Math.min(i % numSessions, numSessions - 1);
-		sessionBuckets[bucketIndex].push(events[i]);
-	}
-
-	// Retime events within each session
-	for (let s = 0; s < numSessions; s++) {
-		const bucket = sessionBuckets[s];
-		if (bucket.length === 0) continue;
-
-		let currentTime = anchors[s];
-		for (let e = 0; e < bucket.length; e++) {
-			const ev = bucket[e];
-			const clampedTime = Math.min(currentTime, latestTime);
-
-			ev.time = dayjs.unix(clampedTime).toISOString();
-			// Regenerate insert_id to match new time
-			const distinctId = ev.user_id || ev.device_id || ev.distinct_id || '';
-			ev.insert_id = quickHash(`${ev.event}-${ev.time}-${distinctId}`);
-
-			// Advance time within session: 5-300 seconds (5s to 5min)
-			currentTime += chance.integer({ min: 5, max: 300 });
-		}
-	}
-
-	// Re-sort by time
-	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
-}
-
 /**
  * Assigns session IDs to a chronologically sorted array of events.
  * A new session starts when:
@@ -1661,6 +1592,7 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 
 	const timeoutMs = timeoutMinutes * 60 * 1000;
 	const maxSessionMs = 24 * 60 * 60 * 1000;
+	const DAY_MS = 86400 * 1000;
 
 	// Derive a stable seed from the first event so session IDs are deterministic
 	// across runs without consuming the main seeded RNG stream.
@@ -1668,15 +1600,21 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 	let currentSessionId = generateSessionId(`${userKey}-${events[0].time}`);
 	let sessionStartMs = new Date(events[0].time).getTime();
 	let lastEventMs = sessionStartMs;
+	let sessionDayIdx = Math.floor(sessionStartMs / DAY_MS);
 
 	for (const event of events) {
 		const eventMs = new Date(event.time).getTime();
 		const gapFromLast = eventMs - lastEventMs;
 		const sessionDuration = eventMs - sessionStartMs;
+		const dayIdx = Math.floor(eventMs / DAY_MS);
 
-		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
+		// Mixpanel session_query.cpp:828-830, 911 — sessions terminate on a
+		// day-index change in qtz (UTC here). Three reset triggers: timeout
+		// gap, max-session cap, OR day boundary crossed.
+		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs || dayIdx !== sessionDayIdx) {
 			currentSessionId = generateSessionId(`${userKey}-${event.time}`);
 			sessionStartMs = eventMs;
+			sessionDayIdx = dayIdx;
 		}
 
 		event.session_id = currentSessionId;
@@ -1747,7 +1685,6 @@ export {
 	formatDuration,
 	generateSessionId,
 	assignSessionIds,
-	bunchIntoSessions,
 	setDatasetNow,
 	setDatasetBegin,
 	dateRange,

package/lib/verify/counting.js

@@ -0,0 +1,320 @@
+/**
+ * Counting and aggregation helpers matching Mixpanel's analytics semantics.
+ *
+ * These primitives differ from naive SQL in important ways. Each helper
+ * documents the Mixpanel source file that defines the rule and the
+ * specific divergence from `COUNT(*)` / `AVG(x)` / etc.
+ *
+ * References (from `mixpanel/analytics`):
+ *   - `backend/arb/reader/queries/addiction_query.cpp` — distinct-period counting
+ *   - `backend/arb/reader/queries/normal_query.cpp` — null-aware AVG/SUM/MIN/MAX
+ */
+
+import { toMs } from '../hook-helpers/_internal.js';
+
+const SECONDS_PER_UNIT = {
+	hour: 3600,
+	day: 86400,
+	week: 7 * 86400,
+};
+
+/**
+ * Count distinct time periods on which a user fired a given event.
+ *
+ * Two related rules exist in Mixpanel:
+ *
+ * 1. **Calendar bucket** (default here, `algorithm: 'calendar'`):
+ *    `COUNT(DISTINCT date_trunc(unit, time))` in UTC. This is what the
+ *    Mixpanel UI presents — frequency distribution charts bucket events
+ *    into calendar hours/days/weeks.
+ *
+ * 2. **Rolling window** (`algorithm: 'rolling'`): the addiction_query.cpp
+ *    rule, `qtz_time >= last_counted + seconds_for_unit(unit)`. This is
+ *    Mixpanel's internal C++ implementation. It diverges from calendar
+ *    bucketing at unit boundaries — events at 23:59 and 00:01 next day
+ *    register as 1 rolling-window period (gap 120s < 86400s) but 2
+ *    calendar-day periods.
+ *
+ * The default is `calendar` because:
+ *   - It matches what users actually see in Mixpanel reports.
+ *   - It aligns with `injectOnNewDays`, which classifies days by
+ *     `Math.floor(t / DAY_MS)` to find empty days. Mixing the two
+ *     algorithms causes the atom and verifier to disagree at boundaries.
+ *
+ * Use `algorithm: 'rolling'` only when you're verifying behavior that
+ * specifically depends on the C++ rolling-window check.
+ *
+ * Reference: `mixpanel/analytics`
+ *   - calendar bucketing: implicit in the UI / Insights reports
+ *   - rolling-window: `backend/arb/reader/queries/addiction_query.cpp`
+ *
+ * @param {Object[]} events - Events to scan (mixed types OK).
+ * @param {string} eventName - Event name to filter for.
+ * @param {('hour'|'day'|'week')} [unit='day']
+ * @param {Object} [options]
+ * @param {('calendar'|'rolling')} [options.algorithm='calendar']
+ * @returns {number} Distinct period count.
+ */
+export function countDistinctPeriods(events, eventName, unit = 'day', options = {}) {
+	const seconds = SECONDS_PER_UNIT[unit];
+	if (!seconds) throw new Error(`countDistinctPeriods: unsupported unit "${unit}"`);
+	if (!Array.isArray(events) || !events.length) return 0;
+	const matches = events
+		.filter(e => e && e.event === eventName)
+		.map(e => toMs(e.time))
+		.filter(ms => Number.isFinite(ms));
+	if (!matches.length) return 0;
+	const unitMs = seconds * 1000;
+	const { algorithm = 'calendar' } = options;
+
+	if (algorithm === 'calendar') {
+		// Calendar bucket — UTC floor by unit. Matches what Mixpanel's UI
+		// shows and what `injectOnNewDays` uses internally.
+		const buckets = new Set();
+		for (const t of matches) buckets.add(Math.floor(t / unitMs));
+		return buckets.size;
+	}
+
+	// Rolling window — addiction_query.cpp semantics.
+	matches.sort((a, b) => a - b);
+	let count = 0;
+	let lastCountedMs = -Infinity;
+	for (const t of matches) {
+		if (t >= lastCountedMs + unitMs) {
+			count++;
+			lastCountedMs = t;
+		}
+	}
+	return count;
+}
+
+/**
+ * Null-aware average matching Mixpanel's aggregation semantics.
+ *
+ * Reference: `backend/arb/reader/queries/normal_query.cpp` ACTION_TYPE_AVERAGE:
+ *
+ *     if (action_value.type == VALUE_TYPE_NUMBER && !std::isnan(value)) {
+ *         v->average.sum += number;
+ *         v->average.count += upsampling_factor;
+ *     }
+ *
+ * Skips null, undefined, NaN, and non-numeric values from BOTH numerator
+ * and denominator. Returns null when no numeric values exist.
+ *
+ * Differs from naive `SUM(x) / COUNT(*)` which inflates the denominator
+ * by counting rows where x is missing — diluting the average toward 0.
+ *
+ * @param {*[]} values
+ * @returns {number|null}
+ */
+export function nullAwareAvg(values) {
+	if (!Array.isArray(values) || !values.length) return null;
+	let sum = 0;
+	let count = 0;
+	for (const v of values) {
+		if (typeof v === 'number' && Number.isFinite(v)) {
+			sum += v;
+			count++;
+		}
+	}
+	return count ? sum / count : null;
+}
+
+/**
+ * Null-aware sum. Skips null/undefined/NaN/non-numeric silently.
+ *
+ * Reference: `normal_query.cpp` ACTION_TYPE_SUM — same numeric guard as AVG.
+ * Differs from naive SQL SUM only when missing values are coalesced to 0
+ * upstream; in JS arrays missing values are typically `undefined` which
+ * produces NaN under `+`.
+ *
+ * @param {*[]} values
+ * @returns {number}
+ */
+export function nullAwareSum(values) {
+	if (!Array.isArray(values) || !values.length) return 0;
+	let sum = 0;
+	for (const v of values) {
+		if (typeof v === 'number' && Number.isFinite(v)) sum += v;
+	}
+	return sum;
+}
+
+/**
+ * Null-aware min/max. Returns null when no numeric values exist.
+ *
+ * Reference: `normal_query.cpp` ACTION_TYPE_EXTREMES — only records numeric
+ * values. Mixpanel starts max at -Infinity and min at +Infinity; we return
+ * null instead of those sentinels when no values were recorded.
+ *
+ * @param {*[]} values
+ * @param {('min'|'max')} mode
+ * @returns {number|null}
+ */
+export function nullAwareExtreme(values, mode) {
+	if (!Array.isArray(values) || !values.length) return null;
+	let extreme = mode === 'min' ? Infinity : -Infinity;
+	let any = false;
+	for (const v of values) {
+		if (typeof v === 'number' && Number.isFinite(v)) {
+			any = true;
+			if (mode === 'min') {
+				if (v < extreme) extreme = v;
+			} else {
+				if (v > extreme) extreme = v;
+			}
+		}
+	}
+	return any ? extreme : null;
+}
+
+/**
+ * Partition events into time buckets by UTC calendar (`day`, `week`, or
+ * `month`). Used by `emulateBreakdown` when `timeBucket` is set to slice any
+ * breakdown into a trend over time.
+ *
+ * Period labels:
+ *   - `'day'`   → `YYYY-MM-DD`
+ *   - `'week'`  → ISO week `YYYY-Www` (Monday-anchored)
+ *   - `'month'` → `YYYY-MM`
+ *
+ * Mixpanel parity: bucket boundaries are computed in UTC. Production Mixpanel
+ * uses query timezone (qtz); pass timestamps already shifted to qtz if you
+ * need that behavior. ISO week is Monday-anchored
+ * (matches `eval_node.c:3641-3643`).
+ *
+ * Empty-bucket backfill (Mixpanel `normal_query.cpp:352-356, 310-313` emits
+ * zero rows for empty intervals): when `options.from` AND `options.to` are
+ * provided, the result enumerates every bucket in `[from, to]` and emits
+ * `{ period, events: [] }` for buckets with no events. Without `from`/`to`,
+ * only buckets that contain at least one event are returned.
+ *
+ * @param {Object[]} events
+ * @param {('day'|'week'|'month')} bucket
+ * @param {Object} [options]
+ * @param {number|string} [options.from] - Inclusive range start (ms or ISO).
+ * @param {number|string} [options.to] - Inclusive range end (ms or ISO).
+ * @returns {Array<{ period: string, events: Object[] }>}
+ */
+export function partitionByTimeBucket(events, bucket, options = {}) {
+	const groups = new Map();
+	if (Array.isArray(events)) {
+		for (const ev of events) {
+			const ms = toMs(ev && ev.time);
+			if (!Number.isFinite(ms)) continue;
+			const period = formatBucket(ms, bucket);
+			if (!groups.has(period)) groups.set(period, []);
+			groups.get(period).push(ev);
+		}
+	}
+	const fromMs = options.from != null ? toMs(options.from) : null;
+	const toMsBound = options.to != null ? toMs(options.to) : null;
+	if (Number.isFinite(fromMs) && Number.isFinite(toMsBound)) {
+		// Enumerate every bucket period in [from, to] and seed empties.
+		for (const period of enumerateBucketPeriods(fromMs, toMsBound, bucket)) {
+			if (!groups.has(period)) groups.set(period, []);
+		}
+	}
+	return [...groups.entries()]
+		.map(([period, evs]) => ({ period, events: evs }))
+		.sort((a, b) => a.period.localeCompare(b.period));
+}
+
+/**
+ * Enumerate canonical bucket period labels covering `[fromMs, toMs]` UTC.
+ * Used to backfill empty rows when the caller supplies a trend axis.
+ *
+ * @param {number} fromMs
+ * @param {number} toMs
+ * @param {('day'|'week'|'month')} bucket
+ * @returns {string[]}
+ */
+function enumerateBucketPeriods(fromMs, toMs, bucket) {
+	const out = [];
+	if (!(toMs >= fromMs)) return out;
+	if (bucket === 'day') {
+		const start = Math.floor(fromMs / 86400_000);
+		const end = Math.floor(toMs / 86400_000);
+		for (let d = start; d <= end; d++) out.push(formatBucket(d * 86400_000, 'day'));
+	} else if (bucket === 'week') {
+		// Walk by 7 days starting from fromMs; rely on label dedup via Set.
+		const seen = new Set();
+		for (let t = fromMs; t <= toMs; t += 7 * 86400_000) {
+			const p = formatBucket(t, 'week'); if (!seen.has(p)) { seen.add(p); out.push(p); }
+		}
+		const last = formatBucket(toMs, 'week');
+		if (!seen.has(last)) out.push(last);
+	} else if (bucket === 'month') {
+		const seen = new Set();
+		const start = new Date(fromMs);
+		const end = new Date(toMs);
+		let y = start.getUTCFullYear(), m = start.getUTCMonth();
+		const yEnd = end.getUTCFullYear(), mEnd = end.getUTCMonth();
+		while (y < yEnd || (y === yEnd && m <= mEnd)) {
+			const p = formatBucket(Date.UTC(y, m, 1), 'month');
+			if (!seen.has(p)) { seen.add(p); out.push(p); }
+			m++; if (m > 11) { m = 0; y++; }
+		}
+	}
+	return out;
+}
+
+function pad2(n) { return n < 10 ? `0${n}` : `${n}`; }
+
+function formatBucket(ms, bucket) {
+	const d = new Date(ms);
+	if (bucket === 'day') {
+		return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+	}
+	if (bucket === 'month') {
+		return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}`;
+	}
+	if (bucket === 'week') {
+		// ISO week: Mon-anchored. Algorithm: shift to Thursday of the week,
+		// take year of that Thursday + week number relative to Jan-1 of that
+		// year's Monday-of-Thursday.
+		const date = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+		const dayNum = (date.getUTCDay() + 6) % 7; // Mon=0..Sun=6
+		date.setUTCDate(date.getUTCDate() - dayNum + 3); // Thursday of this week
+		const year = date.getUTCFullYear();
+		const jan4 = new Date(Date.UTC(year, 0, 4));
+		const jan4DayNum = (jan4.getUTCDay() + 6) % 7;
+		const week1Mon = new Date(Date.UTC(year, 0, 4 - jan4DayNum));
+		const weekNum = Math.floor((date.getTime() - week1Mon.getTime()) / (7 * 86400_000)) + 1;
+		return `${year}-W${pad2(weekNum)}`;
+	}
+	throw new Error(`partitionByTimeBucket: unsupported bucket "${bucket}"`);
+}
+
+/**
+ * Bin a user by their distinct-period count of an event. Combines
+ * `countDistinctPeriods` with bin classification for cohort assignment.
+ *
+ * Each bin entry is `[min, max]` with `min` inclusive, `max` exclusive.
+ * Returns the first matching bin name, or `null` if no bin matches.
+ *
+ * Uses calendar-bucket counting by default (matches Mixpanel UI). Pass
+ * `options.algorithm: 'rolling'` to use the addiction_query.cpp rule
+ * instead — see `countDistinctPeriods` for the difference.
+ *
+ * Replaces total-event counting for any analysis that targets Mixpanel's
+ * frequency distribution (which counts distinct periods, not total events).
+ *
+ * @param {Object[]} events
+ * @param {string} eventName
+ * @param {Object<string, [number, number]>} bins
+ * @param {('hour'|'day'|'week')} [unit='day']
+ * @param {Object} [options]
+ * @param {('calendar'|'rolling')} [options.algorithm='calendar']
+ * @returns {string|null}
+ */
+export function binByDistinctPeriods(events, eventName, bins, unit = 'day', options = {}) {
+	const periods = countDistinctPeriods(events, eventName, unit, options);
+	if (!bins || typeof bins !== 'object') return null;
+	for (const [name, range] of Object.entries(bins)) {
+		if (!Array.isArray(range) || range.length !== 2) continue;
+		const [min, max] = range;
+		if (periods >= min && periods < max) return name;
+	}
+	return null;
+}