@ak--47/dungeon-master 1.3.0 → 1.4.0

package/lib/utils/utils.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import Chance from 'chance';
 import readline from 'readline';
-import { comma, uid } from 'ak-tools';
+import { comma } from 'ak-tools';
 import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc.js';
 import path from 'path';
@@ -24,7 +24,27 @@ const { NODE_ENV = "unknown" } = process.env;
 let globalChance;
 let chanceInitialized = false;
 
-const ACTUAL_NOW = dayjs.utc();
+// Module-scoped memoization cache for weighted-array resolvers in `choose()`.
+// Lives for the lifetime of the node process; key is the function source string.
+const weightedArrayCache = new Map();
+
+// Reference "now" used by date() and day() factories. Defaults to wall-clock at
+// import time; the orchestrator overrides this via setDatasetNow() once the dataset
+// window is resolved, so date helpers in dungeon configs produce deterministic
+// values relative to the dataset end (not the process start).
+let DATASET_NOW = dayjs.utc();
+
+/**
+ * Override the reference "now" used by date()/day() factories. Called by the
+ * orchestrator with the resolved dataset end so every date helper produces
+ * deterministic values relative to the dataset window.
+ * @param {number} unixSeconds
+ */
+function setDatasetNow(unixSeconds) {
+	if (typeof unixSeconds === 'number' && Number.isFinite(unixSeconds)) {
+		DATASET_NOW = dayjs.unix(unixSeconds).utc();
+	}
+}
 
 
 import { Storage as cloudStorage } from '@google-cloud/storage';
@@ -102,7 +122,7 @@ function pick(items) {
  */
 function date(inTheLast = 30, isPast = true, format = 'YYYY-MM-DD') {
 	const chance = getChance();
-	const now = ACTUAL_NOW;
+	const now = DATASET_NOW;
 	if (Math.abs(inTheLast) > 365 * 10) inTheLast = chance.integer({ min: 1, max: 180 });
 	return function () {
 		const when = chance.integer({ min: 0, max: Math.abs(inTheLast) });
@@ -159,8 +179,8 @@ function datesBetween(start, end) {
  */
 function day(start, end) {
 	// if (!end) end = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
-	if (!start) start = ACTUAL_NOW.subtract(30, 'd').toISOString();
-	if (!end) end = ACTUAL_NOW.toISOString();
+	if (!start) start = DATASET_NOW.subtract(30, 'd').toISOString();
+	if (!end) end = DATASET_NOW.toISOString();
 	const chance = getChance();
 	const format = 'YYYY-MM-DD';
 	return function (min, max) {
@@ -219,20 +239,15 @@ function choose(value) {
 		while (typeof value === 'function') {
 			const funcString = value.toString();
 
-			// Check cache for weighted array functions
-			if (typeof global.weightedArrayCache === 'undefined') {
-				global.weightedArrayCache = new Map();
-			}
-
-			if (global.weightedArrayCache.has(funcString)) {
-				value = global.weightedArrayCache.get(funcString);
+			if (weightedArrayCache.has(funcString)) {
+				value = weightedArrayCache.get(funcString);
 				break;
 			}
 
 			const result = value();
 			if (Array.isArray(result) && result.length > 10) {
 				// Cache large arrays (likely weighted arrays)
-				global.weightedArrayCache.set(funcString, result);
+				weightedArrayCache.set(funcString, result);
 			}
 			value = result;
 		}
@@ -1141,21 +1156,14 @@ CORE
 */
 
 //the function which generates $distinct_id + $anonymous_ids, $session_ids, and created, skewing towards the present
-function generateUser(user_id, opts, amplitude = 1, frequency = 1, skew = 1) {
+function generateUser(user_id, opts) {
 	const chance = getChance();
-	const { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds } = opts;
-	// Uniformly distributed `u`, then skew applied
-	let u = Math.pow(chance.random(), skew);
-
-	// Sine function for a smoother curve
-	const sineValue = (Math.sin(u * Math.PI * frequency - Math.PI / 2) * amplitude + 1) / 2;
-
-	// Scale the sineValue to the range of days
-	let daysAgoBorn = Math.round(sineValue * (numDays - 1)) + 1;
-
-	// Clamp values to ensure they are within the desired range
+	const { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix, avgDevicePerUser } = opts;
+	// Birth date placement is overridden by bornRecentBias in user-loop.js;
+	// use a simple uniform distribution as the seed value.
+	let daysAgoBorn = Math.round(chance.random() * (numDays - 1)) + 1;
 	daysAgoBorn = Math.min(daysAgoBorn, numDays);
-	const props = person(user_id, daysAgoBorn, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds);
+	const props = person(user_id, daysAgoBorn, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix, avgDevicePerUser);
 
 	const user = {
 		distinct_id: user_id,
@@ -1188,7 +1196,7 @@ const DEFAULT_HOD_WEIGHTS = [
 	0.584, 0.574, 0.554, 0.576, 0.604, 0.655, 0.722, 0.816
 ];
 
-function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0, dayOfWeekWeights = DEFAULT_DOW_WEIGHTS, hourOfDayWeights = DEFAULT_HOD_WEIGHTS, timeShiftSeconds = 0) {
+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();
 	const chance = getChance();
@@ -1215,7 +1223,7 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
 	// Phase 2: DOW accept/reject — retry if day-of-week doesn't pass weight check
 	if (dayOfWeekWeights) {
 		for (let attempt = 0; attempt < 50; attempt++) {
-			const dow = new Date((candidate + timeShiftSeconds) * 1000).getUTCDay();
+			const dow = new Date(candidate * 1000).getUTCDay();
 			if (chance.random() < dayOfWeekWeights[dow]) break;
 			// Rejected — resample from Gaussian chunks
 			const pi = integer(0, peaks - 1);
@@ -1231,8 +1239,7 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
 
 	// Phase 3: Redistribute hour-of-day (changes only hour within same day)
 	if (hourOfDayWeights) {
-		const shifted = candidate + timeShiftSeconds;
-		const d = new Date(shifted * 1000);
+		const d = new Date(candidate * 1000);
 		const currentMinute = d.getUTCMinutes();
 		const currentSecond = d.getUTCSeconds();
 
@@ -1244,9 +1251,8 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
 			if (roll <= 0) { newHour = h; break; }
 		}
 
-		const dayStartShifted = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 1000;
-		const newShifted = dayStartShifted + newHour * 3600 + currentMinute * 60 + currentSecond;
-		candidate = newShifted - timeShiftSeconds;
+		const dayStart = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 1000;
+		candidate = dayStart + newHour * 3600 + currentMinute * 60 + currentSecond;
 		candidate = Math.max(earliestTime, Math.min(latestTime, candidate));
 	}
 
@@ -1262,9 +1268,13 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
  * @param {boolean} hasAvatar
  * @param {boolean} hasAnonIds
  * @param {boolean} hasSessionIds
+ * @param {number} [datasetEndUnix]
+ * @param {number} [avgDevicePerUser] - Whole number ≥ 0. When ≥ 1 (and `hasAnonIds: true`),
+ *   sets the per-user device pool size. `1` = exactly one device. `>1` = drawn from
+ *   `chance.normal({mean: avgDevicePerUser, dev: avgDevicePerUser/2})`, clamped ≥ 1, integer.
  * @return {Person}
  */
-function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false, hasAnonIds = false, hasSessionIds = false) {
+function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false, hasAnonIds = false, hasSessionIds = false, datasetEndUnix, avgDevicePerUser) {
 	const chance = getChance();
 	//names and photos
 	const l = chance.letter.bind(chance);
@@ -1278,7 +1288,11 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 	let randomAvatarNumber = integer(1, 99);
 	let avPath = gender === 'male' ? `/men/${randomAvatarNumber}.jpg` : `/women/${randomAvatarNumber}.jpg`;
 	let avatar = avatarPrefix + avPath;
-	let created = dayjs().subtract(bornDaysAgo, 'day').format('YYYY-MM-DD');
+	// Birth date: anchor to dataset end (post-resolution) so user.created lives inside
+	// the configured window, not wall-clock time. Falls back to dayjs() only when
+	// person() is called outside the normal generation pipeline (e.g. direct unit tests).
+	const anchor = datasetEndUnix ? dayjs.unix(datasetEndUnix) : dayjs();
+	let created = anchor.subtract(bornDaysAgo, 'day').format('YYYY-MM-DD');
 
 
 	// const created = date(bornDaysAgo, true)();
@@ -1303,11 +1317,28 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 
 	if (!hasAvatar) delete user.avatar;
 
-	//anon Ids
+	// Device pool ("anonymousIds" — name preserved for backwards compat).
+	// Phase 2 identity model: pool size is governed by `avgDevicePerUser` when set,
+	// else legacy 2–10 random pool size for any dungeon that just sets `hasAnonIds: true`
+	// without `avgDevicePerUser`. (Validator coerces `hasAnonIds: true` to an effective
+	// `avgDevicePerUser >= 1`, so this branch fires whenever there's a device pool to build.)
 	if (hasAnonIds) {
-		const clusterSize = integer(2, 10);
+		let clusterSize;
+		if (typeof avgDevicePerUser === 'number' && avgDevicePerUser >= 1) {
+			if (avgDevicePerUser === 1) {
+				clusterSize = 1;
+			} else {
+				const sd = avgDevicePerUser / 2;
+				const sample = chance.normal({ mean: avgDevicePerUser, dev: sd });
+				clusterSize = Math.max(1, Math.round(sample));
+			}
+		} else {
+			// Legacy fallback (pre-1.4 behavior): random pool of 2–10 devices.
+			clusterSize = integer(2, 10);
+		}
 		for (let i = 0; i < clusterSize; i++) {
-			const anonId = uid(42);
+			// Use seeded chance, not ak-tools uid() (which uses Math.random).
+			const anonId = chance.string({ length: 42, pool: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' });
 			user.anonymousIds.push(anonId);
 		}
 	}
@@ -1429,11 +1460,26 @@ function deepClone(thing, opts) {
 
 
 /**
- * Generates a session ID in the standard format
+ * Generates a session ID in the standard format. Derives it deterministically
+ * from a seed string (first event time + user_id, typically) via quickHash so
+ * we don't consume from the main seeded RNG stream — that consumption would
+ * cascade into all downstream events whenever the number of sessions changed
+ * (e.g. when sessionTimeout differs).
+ * @param {string} [seedStr] - Stable input string. If absent, falls back to a
+ *   chance.string() pull (only used by tests / direct callers without a seed).
  * @returns {string} Session ID like "xxxxx-xxxxx-xxxxx-xxxxx"
  */
-function generateSessionId() {
-	return [uid(5), uid(5), uid(5), uid(5)].join("-");
+function generateSessionId(seedStr) {
+	if (seedStr) {
+		// quickHash returns ~16 hex chars; expand to 4×5 segments via re-hashing.
+		const h1 = quickHash(seedStr);
+		const h2 = quickHash(h1);
+		const all = (h1 + h2).replace(/[^a-zA-Z0-9]/g, '').padEnd(20, '0');
+		return [all.slice(0, 5), all.slice(5, 10), all.slice(10, 15), all.slice(15, 20)].join('-');
+	}
+	const c = getChance();
+	const seg = () => c.string({ length: 5, pool: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' });
+	return [seg(), seg(), seg(), seg()].join("-");
 }
 
 /**
@@ -1459,7 +1505,7 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 
 	const chance = getChance();
 	const { earliestTime, latestTime, peaks, deviation, mean,
-		dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds, maxTime } = soupParams;
+		dayOfWeekWeights, hourOfDayWeights } = soupParams;
 
 	// Sort by time first
 	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
@@ -1472,8 +1518,8 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 	const anchors = [];
 	for (let i = 0; i < numSessions; i++) {
 		const soupTime = TimeSoup(earliestTime, latestTime, peaks, deviation, mean,
-			dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds);
-		anchors.push(soupTime + timeShiftSeconds); // shifted to present time
+			dayOfWeekWeights, hourOfDayWeights);
+		anchors.push(soupTime);
 	}
 	anchors.sort((a, b) => a - b);
 
@@ -1485,7 +1531,6 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 	}
 
 	// Retime events within each session
-	let writeIndex = 0;
 	for (let s = 0; s < numSessions; s++) {
 		const bucket = sessionBuckets[s];
 		if (bucket.length === 0) continue;
@@ -1493,17 +1538,13 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 		let currentTime = anchors[s];
 		for (let e = 0; e < bucket.length; e++) {
 			const ev = bucket[e];
-			const clampedTime = Math.min(currentTime, maxTime);
+			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}`);
 
-			if (currentTime > maxTime) {
-				ev._drop = true;
-			}
-
 			// Advance time within session: 5-300 seconds (5s to 5min)
 			currentTime += chance.integer({ min: 5, max: 300 });
 		}
@@ -1532,7 +1573,10 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 	const timeoutMs = timeoutMinutes * 60 * 1000;
 	const maxSessionMs = 24 * 60 * 60 * 1000;
 
-	let currentSessionId = generateSessionId();
+	// Derive a stable seed from the first event so session IDs are deterministic
+	// across runs without consuming the main seeded RNG stream.
+	const userKey = events[0].user_id || events[0].device_id || events[0].distinct_id || '';
+	let currentSessionId = generateSessionId(`${userKey}-${events[0].time}`);
 	let sessionStartMs = new Date(events[0].time).getTime();
 	let lastEventMs = sessionStartMs;
 
@@ -1542,7 +1586,7 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 		const sessionDuration = eventMs - sessionStartMs;
 
 		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
-			currentSessionId = generateSessionId();
+			currentSessionId = generateSessionId(`${userKey}-${event.time}`);
 			sessionStartMs = eventMs;
 		}
 
@@ -1606,4 +1650,5 @@ export {
 	generateSessionId,
 	assignSessionIds,
 	bunchIntoSessions,
+	setDatasetNow,
 };

package/lib/verify/emulate-breakdown.js

@@ -0,0 +1,281 @@
+/**
+ * Mixpanel breakdown emulator.
+ *
+ * Best-effort approximation of the table shapes Mixpanel produces for the five
+ * analyses the Phase 4 hook patterns target. Used by `verify-hooks` to assert
+ * that engineered patterns actually produce the expected ratios in the data, AND
+ * by consumers who want to validate dungeons against expected business shapes
+ * outside of Mixpanel.
+ *
+ * Reference: Mixpanel Insights / Funnels / Flows reports, as of 2026-05.
+ *
+ * Caveats:
+ * - Mixpanel applies its own per-account UTC offset and time-bucketing rules. This
+ *   emulator uses raw event times unless the breakdown explicitly involves a window.
+ * - Mixpanel "users" are typically distinct profiles with at least one event in
+ *   the date range; this emulator counts unique `user_id` (falling back to
+ *   `distinct_id`) found across the events array.
+ * - This is not bit-exact — it's the *shape* check Phase 4 verification needs.
+ */
+
+/**
+ * @typedef {Object} EmulateOptions
+ * @property {'frequencyByFrequency'|'funnelFrequency'|'aggregatePerUser'|'timeToConvert'|'attributedBy'} type
+ *
+ * @property {string} [metricEvent]
+ * @property {string} [breakdownByFrequencyOf]
+ * @property {boolean} [perUser]
+ *
+ * @property {string[]} [steps]
+ *
+ * @property {string} [event]
+ * @property {string} [property]
+ * @property {'avg'|'sum'|'count'|'max'|'min'} [agg]
+ *
+ * @property {string} [fromEvent]
+ * @property {string} [toEvent]
+ * @property {string} [breakdownByUserProperty]
+ * @property {Array<Object>} [profiles]
+ *
+ * @property {string} [conversionEvent]
+ * @property {string} [attributionEvent]
+ * @property {string} [attributionProperty]
+ * @property {'firstTouch'|'lastTouch'} [model]
+ */
+
+/**
+ * Run a Mixpanel breakdown emulation against an events array.
+ * Routes to the type-specific implementation based on `config.type`.
+ *
+ * @param {Array<Object>} events
+ * @param {EmulateOptions} config
+ * @returns {Array<Object>} Breakdown table rows.
+ */
+export function emulateBreakdown(events, config) {
+	if (!Array.isArray(events)) throw new Error('emulateBreakdown: events must be an array');
+	if (!config || !config.type) throw new Error('emulateBreakdown: config.type is required');
+	switch (config.type) {
+		case 'frequencyByFrequency': return frequencyByFrequency(events, /** @type {*} */ (config));
+		case 'funnelFrequency':      return funnelFrequency(events, /** @type {*} */ (config));
+		case 'aggregatePerUser':     return aggregatePerUser(events, /** @type {*} */ (config));
+		case 'timeToConvert':        return timeToConvert(events, /** @type {*} */ (config));
+		case 'attributedBy':         return attributedBy(events, /** @type {*} */ (config));
+		default: throw new Error(`emulateBreakdown: unknown type "${config.type}"`);
+	}
+}
+
+// ── Frequency × Frequency (Insights, Frequency Distribution by per-user count of B) ──
+
+function frequencyByFrequency(events, { metricEvent, breakdownByFrequencyOf }) {
+	if (!metricEvent || !breakdownByFrequencyOf) {
+		throw new Error('frequencyByFrequency requires metricEvent and breakdownByFrequencyOf');
+	}
+	const userMetric = new Map();
+	const userBreakdown = new Map();
+	const uids = new Set();
+	for (const ev of events) {
+		const uid = userIdOf(ev);
+		if (!uid) continue;
+		uids.add(uid);
+		if (ev.event === metricEvent) userMetric.set(uid, (userMetric.get(uid) || 0) + 1);
+		if (ev.event === breakdownByFrequencyOf) userBreakdown.set(uid, (userBreakdown.get(uid) || 0) + 1);
+	}
+	const cell = new Map(); // `${m}|${b}` → user_count
+	for (const uid of uids) {
+		const m = userMetric.get(uid) || 0;
+		const b = userBreakdown.get(uid) || 0;
+		const key = `${m}|${b}`;
+		cell.set(key, (cell.get(key) || 0) + 1);
+	}
+	return [...cell.entries()].map(([k, count]) => {
+		const [m, b] = k.split('|').map(Number);
+		return { metric_freq: m, breakdown_freq: b, user_count: count };
+	}).sort((x, y) => x.breakdown_freq - y.breakdown_freq || x.metric_freq - y.metric_freq);
+}
+
+// ── Funnel Frequency Breakdown (Funnel report broken down by per-user count of X) ──
+
+function funnelFrequency(events, { steps, breakdownByFrequencyOf }) {
+	if (!Array.isArray(steps) || !steps.length) throw new Error('funnelFrequency requires steps[]');
+	if (!breakdownByFrequencyOf) throw new Error('funnelFrequency requires breakdownByFrequencyOf');
+	const userEvents = groupByUser(events);
+	const userBreakdown = new Map();
+	for (const [uid, evs] of userEvents) {
+		const c = evs.filter(e => e && e.event === breakdownByFrequencyOf).length;
+		userBreakdown.set(uid, c);
+	}
+	const result = [];
+	for (let s = 0; s < steps.length; s++) {
+		const stepName = steps[s];
+		const conversions = new Map(); // breakdown_freq → count
+		for (const [uid, evs] of userEvents) {
+			const sorted = sortByTime(evs);
+			let stepIdx = 0;
+			for (const ev of sorted) {
+				if (ev.event === steps[stepIdx]) stepIdx++;
+				if (stepIdx > s) break;
+			}
+			if (stepIdx > s) {
+				const b = userBreakdown.get(uid) || 0;
+				conversions.set(b, (conversions.get(b) || 0) + 1);
+			}
+		}
+		for (const [b, c] of conversions) {
+			result.push({ step: stepName, step_index: s, breakdown_freq: b, conversions: c, conversion_pct: 0 });
+		}
+	}
+	// Conversion % at each step relative to its own breakdown_freq's step-0 baseline.
+	const baseline = new Map();
+	for (const r of result) {
+		if (r.step_index === 0) baseline.set(r.breakdown_freq, r.conversions);
+	}
+	for (const r of result) {
+		const denom = baseline.get(r.breakdown_freq) || 0;
+		r.conversion_pct = denom ? (r.conversions / denom) * 100 : 0;
+	}
+	return result.sort((a, b) => a.step_index - b.step_index || a.breakdown_freq - b.breakdown_freq);
+}
+
+// ── Aggregate per user (Insights, sum/avg of property X by per-user count of B) ──
+
+function aggregatePerUser(events, { event, property, agg = 'avg', breakdownByFrequencyOf }) {
+	if (!event) throw new Error('aggregatePerUser requires event');
+	if (!breakdownByFrequencyOf) throw new Error('aggregatePerUser requires breakdownByFrequencyOf');
+	if (agg !== 'count' && !property) throw new Error('aggregatePerUser requires property unless agg is "count"');
+	const userVals = new Map();
+	const userBreakdown = new Map();
+	for (const ev of events) {
+		const uid = userIdOf(ev);
+		if (!uid) continue;
+		if (ev.event === event) {
+			// `agg: 'count'` → count occurrences of the event regardless of property type.
+			// All other aggs only consider numeric property values.
+			if (agg === 'count') {
+				if (!userVals.has(uid)) userVals.set(uid, []);
+				userVals.get(uid).push(1);
+			} else if (property && typeof ev[property] === 'number') {
+				if (!userVals.has(uid)) userVals.set(uid, []);
+				userVals.get(uid).push(ev[property]);
+			}
+		}
+		if (ev.event === breakdownByFrequencyOf) userBreakdown.set(uid, (userBreakdown.get(uid) || 0) + 1);
+	}
+	const userAgg = new Map();
+	for (const [uid, vals] of userVals) userAgg.set(uid, applyAgg(vals, agg));
+	const buckets = new Map(); // breakdown_freq → [aggregates]
+	for (const [uid, v] of userAgg) {
+		const b = userBreakdown.get(uid) || 0;
+		if (!buckets.has(b)) buckets.set(b, []);
+		buckets.get(b).push(v);
+	}
+	return [...buckets.entries()].map(([b, vs]) => ({
+		breakdown_freq: b,
+		user_count: vs.length,
+		avg_aggregate: vs.reduce((a, x) => a + x, 0) / vs.length,
+	})).sort((x, y) => x.breakdown_freq - y.breakdown_freq);
+}
+
+// ── Time to Convert (Funnel TTC, broken down by user property) ──
+
+function timeToConvert(events, { fromEvent, toEvent, breakdownByUserProperty, profiles = [] }) {
+	if (!fromEvent || !toEvent) throw new Error('timeToConvert requires fromEvent and toEvent');
+	const userEvents = groupByUser(events);
+	const profileByUid = new Map();
+	for (const p of profiles) {
+		if (!p) continue;
+		const uid = p.distinct_id || p.user_id;
+		if (uid) profileByUid.set(uid, p);
+	}
+	const buckets = new Map(); // segValue → [ttcMs]
+	for (const [uid, evs] of userEvents) {
+		const sorted = sortByTime(evs);
+		const a = sorted.find(e => e && e.event === fromEvent);
+		if (!a) continue;
+		const aIdx = sorted.indexOf(a);
+		const b = sorted.slice(aIdx + 1).find(e => e && e.event === toEvent);
+		if (!b) continue;
+		const ttcMs = toMs(b.time) - toMs(a.time);
+		if (!Number.isFinite(ttcMs) || ttcMs < 0) continue;
+		const profile = profileByUid.get(uid);
+		const segValue = breakdownByUserProperty
+			? (profile ? (profile[breakdownByUserProperty] ?? 'unknown') : 'unknown')
+			: 'all';
+		if (!buckets.has(segValue)) buckets.set(segValue, []);
+		buckets.get(segValue).push(ttcMs);
+	}
+	return [...buckets.entries()].map(([seg, ttcs]) => ({
+		segment_value: seg,
+		user_count: ttcs.length,
+		avg_ttc_ms: ttcs.reduce((a, x) => a + x, 0) / ttcs.length,
+		median_ttc_ms: median(ttcs),
+	})).sort((x, y) => String(x.segment_value).localeCompare(String(y.segment_value)));
+}
+
+// ── Attributed By (first-/last-touch attribution by event property value) ──
+
+function attributedBy(events, { conversionEvent, attributionEvent, attributionProperty, model = 'firstTouch' }) {
+	if (!conversionEvent || !attributionEvent || !attributionProperty) {
+		throw new Error('attributedBy requires conversionEvent, attributionEvent, attributionProperty');
+	}
+	const userEvents = groupByUser(events);
+	const counts = new Map();
+	for (const [uid, evs] of userEvents) {
+		const sorted = sortByTime(evs);
+		const conversion = sorted.find(e => e && e.event === conversionEvent);
+		if (!conversion) continue;
+		const conversionTime = toMs(conversion.time);
+		const touches = sorted.filter(e =>
+			e && e.event === attributionEvent && toMs(e.time) <= conversionTime
+		);
+		if (!touches.length) continue;
+		const touch = model === 'lastTouch' ? touches[touches.length - 1] : touches[0];
+		const v = touch[attributionProperty] ?? 'unknown';
+		counts.set(v, (counts.get(v) || 0) + 1);
+	}
+	return [...counts.entries()].map(([source, count]) => ({
+		attribution_value: source,
+		conversions: count,
+	})).sort((a, b) => b.conversions - a.conversions);
+}
+
+// ── shared helpers ──
+
+function userIdOf(ev) {
+	return ev && (ev.user_id || ev.distinct_id || ev.device_id);
+}
+
+function groupByUser(events) {
+	const userEvents = new Map();
+	for (const ev of events) {
+		const uid = userIdOf(ev);
+		if (!uid) continue;
+		if (!userEvents.has(uid)) userEvents.set(uid, []);
+		userEvents.get(uid).push(ev);
+	}
+	return userEvents;
+}
+
+function sortByTime(evs) {
+	return evs.slice().sort((a, b) => toMs(a && a.time) - toMs(b && b.time));
+}
+
+import { toMs } from '../hook-helpers/_internal.js';
+
+function applyAgg(vals, agg) {
+	if (!vals || !vals.length) return 0;
+	switch (agg) {
+		case 'sum': return vals.reduce((a, b) => a + b, 0);
+		case 'count': return vals.length;
+		case 'max': return Math.max(...vals);
+		case 'min': return Math.min(...vals);
+		case 'avg':
+		default: return vals.reduce((a, b) => a + b, 0) / vals.length;
+	}
+}
+
+function median(arr) {
+	if (!arr.length) return 0;
+	const sorted = arr.slice().sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}

package/lib/verify/index.js

@@ -0,0 +1,12 @@
+/**
+ * @ak--47/dungeon-master/verify — Phase 4 verification surface.
+ *
+ * `emulateBreakdown` produces the table shapes Mixpanel shows for the five
+ * supported analyses (frequencyByFrequency, funnelFrequency, aggregatePerUser,
+ * timeToConvert, attributedBy). `verifyDungeon` is the higher-level wrapper
+ * that runs a dungeon and asserts emulator outputs match expected ratios — wire
+ * this into your CI to catch dungeon drift.
+ */
+
+export { emulateBreakdown } from './emulate-breakdown.js';
+export { verifyDungeon } from './verify-dungeon.js';

package/lib/verify/verify-dungeon.js

@@ -0,0 +1,61 @@
+/**
+ * verifyDungeon — run a dungeon (in-memory) and run a series of emulator checks
+ * against its output, returning a structured report. Designed for CI use:
+ *
+ *   const report = await verifyDungeon(dungeonConfig, [
+ *     {
+ *       name: 'engaged users do 2x purchases',
+ *       breakdown: { type: 'frequencyByFrequency',
+ *                    metricEvent: 'Purchase', breakdownByFrequencyOf: 'Browse' },
+ *       assert: (rows) => {
+ *         // custom assertion against the emulator's output table
+ *         return { pass: true, detail: 'looks good' };
+ *       }
+ *     }
+ *   ]);
+ *   if (!report.pass) process.exit(1);
+ *
+ * The dungeon is run via the same default-export entry point external consumers
+ * use, so this is a true end-to-end check.
+ */
+
+import DUNGEON_MASTER from '../../index.js';
+import { emulateBreakdown } from './emulate-breakdown.js';
+
+/**
+ * @typedef {Object} VerifyCheck
+ * @property {string} name - Human-readable name for the check.
+ * @property {Object} breakdown - Argument passed to `emulateBreakdown`.
+ * @property {(rows: Array<Object>, ctx: { events: Array<Object>, profiles: Array<Object> }) => { pass: boolean, detail?: string }} assert
+ */
+
+/**
+ * @param {Object} config - Dungeon config (or path; passed straight to DUNGEON_MASTER).
+ * @param {VerifyCheck[]} checks
+ * @returns {Promise<{ pass: boolean, results: Array<{ name: string, pass: boolean, detail?: string, rows?: Array<Object> }> }>}
+ */
+export async function verifyDungeon(config, checks) {
+	if (!checks || !checks.length) throw new Error('verifyDungeon: at least one check required');
+	let result = await DUNGEON_MASTER(config);
+	if (Array.isArray(result)) result = result[0];
+	const events = Array.isArray(result.eventData) ? result.eventData : Array.from(result.eventData);
+	const profiles = Array.isArray(result.userProfilesData) ? result.userProfilesData : Array.from(result.userProfilesData);
+	const ctx = { events, profiles };
+	const results = [];
+	for (const check of checks) {
+		try {
+			const breakdownArgs = { ...check.breakdown };
+			// timeToConvert + attributedBy may want profiles; auto-inject if not provided.
+			if (breakdownArgs.type === 'timeToConvert' && !breakdownArgs.profiles) {
+				breakdownArgs.profiles = profiles;
+			}
+			const rows = emulateBreakdown(events, breakdownArgs);
+			const verdict = check.assert(rows, ctx);
+			results.push({ name: check.name, pass: !!verdict.pass, detail: verdict.detail, rows });
+		} catch (err) {
+			results.push({ name: check.name, pass: false, detail: `error: ${err.message}` });
+		}
+	}
+	const pass = results.every(r => r.pass);
+	return { pass, results };
+}