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

package/lib/orchestrators/user-loop.js

@@ -6,6 +6,7 @@
 /** @typedef {import('../../types').Context} Context */
 
 import dayjs from "dayjs";
+import { randomUUID } from "node:crypto";
 import pLimit from 'p-limit';
 import os from 'os';
 import * as u from "../utils/utils.js";
@@ -33,6 +34,7 @@ export async function userLoop(context) {
 		isAnonymous,
 		hasAvatar,
 		hasAnonIds,
+		avgDevicePerUser = 0,
 		hasSessionIds,
 		hasLocation,
 		funnels,
@@ -48,11 +50,6 @@ export async function userLoop(context) {
 		worldEvents,
 		engagementDecay: globalEngagementDecay,
 		dataQuality,
-		subscription,
-		attribution,
-		geo,
-		features,
-		anomalies
 	} = config;
 
 	const { eventData, userProfilesData, scdTableData } = storage;
@@ -108,8 +105,9 @@ export async function userLoop(context) {
 			}
 
 			const userId = chance.guid();
-			const user = u.generateUser(userId, { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix: context.FIXED_NOW });
+			const user = u.generateUser(userId, { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix: context.FIXED_NOW, avgDevicePerUser });
 			const { distinct_id, created } = user;
+			const userDevicePool = (user.anonymousIds && user.anonymousIds.length) ? user.anonymousIds.slice() : null;
 			const userIsBornInDataset = chance.bool({ likelihood: percentUsersBornInDataset });
 
 			// Feature 1: Assign persona
@@ -178,41 +176,8 @@ export async function userLoop(context) {
 				}
 			}
 
-			// Feature 7: Geographic intelligence — assign sticky location
 			let userLocation = null;
-			let userRegion = null;
-			let userTimezoneOffset = 0;
-			if (geo && geo.sticky && geo.regions && geo.regions.length > 0) {
-				// Assign region using weighted selection
-				const regionWeights = geo.regions.map(r => r.weight);
-				const totalRegionWeight = regionWeights.reduce((a, b) => a + b, 0);
-				let regionRoll = chance.floating({ min: 0, max: totalRegionWeight });
-				for (const r of geo.regions) {
-					regionRoll -= r.weight;
-					if (regionRoll <= 0) { userRegion = r; break; }
-				}
-				if (!userRegion) userRegion = geo.regions[geo.regions.length - 1];
-				userTimezoneOffset = userRegion.timezoneOffset || 0;
-
-				// Pick a location matching one of this region's countries
-				const regionLocations = u.choose(defaults.locationsUsers).filter(
-					loc => userRegion.countries.includes(loc.country_code || loc.country)
-				);
-				if (regionLocations.length > 0) {
-					userLocation = u.pickRandom(regionLocations);
-				} else {
-					userLocation = u.pickRandom(u.choose(defaults.locationsUsers));
-				}
-				for (const key in userLocation) {
-					user[key] = userLocation[key];
-				}
-				// Inject region properties
-				if (userRegion.properties) {
-					for (const [k, v] of Object.entries(userRegion.properties)) {
-						user[k] = v;
-					}
-				}
-			} else if (hasLocation) {
+			if (hasLocation) {
 				const location = u.pickRandom(u.choose(defaults.locationsUsers));
 				for (const key in location) {
 					user[key] = location[key];
@@ -220,24 +185,6 @@ export async function userLoop(context) {
 				userLocation = location;
 			}
 
-			// Feature 6: Attribution — assign campaign to users born in dataset
-			let userCampaign = null;
-			if (attribution && userIsBornInDataset) {
-				// adjustedCreated is in the internal FIXED time range
-				const birthUnix = adjustedCreated.unix();
-				const birthDay = Math.max(0, (birthUnix - context.FIXED_BEGIN) / 86400);
-				const isOrganic = chance.bool({ likelihood: (attribution.organicRate || 0.4) * 100 });
-				if (!isOrganic) {
-					// Find active campaigns at birth day
-					const activeCampaigns = attribution.campaigns.filter(c =>
-						birthDay >= c.activeDays[0] && birthDay <= c.activeDays[1]
-					);
-					if (activeCampaigns.length > 0) {
-						userCampaign = chance.pickone(activeCampaigns);
-					}
-				}
-			}
-
 			// Profile creation
 			const profile = await makeUserProfile(context, userProps, user);
 
@@ -249,30 +196,12 @@ export async function userLoop(context) {
 				profile._persona = persona.name;
 			}
 
-			// Feature 6: Add attribution to profile
-			if (userCampaign) {
-				profile.utm_source = userCampaign.source;
-				profile.utm_campaign = userCampaign.name;
-				if (userCampaign.medium) profile.utm_medium = userCampaign.medium;
-			}
-
-			// Feature 7: Add region to profile
-			if (userRegion) {
-				profile._region = userRegion.name;
-			}
-
 			// Build feature context for event generation
 			const featureCtx = {
 				persona,
 				userLocation,
 				worldEventsTimeline: worldEvents,
-				resolvedFeatures: features,
-				resolvedAnomalies: anomalies,
 				dataQuality,
-				geo,
-				userCampaign,
-				userRegion,
-				userTimezoneOffset
 			};
 
 			// Call user hook after profile creation (hooks override persona properties)
@@ -354,8 +283,9 @@ export async function userLoop(context) {
 			let usersEvents = [];
 			let userConverted = true;
 
-			// Pre-compute weighted events array for standalone event selection
-			const weightedEvents = config.events.reduce((acc, event) => {
+			// Pre-compute weighted events array for standalone event selection.
+			// Filter out isStrictEvent events — they only appear inside funnels.
+			const weightedEvents = config.events.filter(e => !e.isStrictEvent).reduce((acc, event) => {
 				const w = Math.max(1, Math.min(Math.floor(event.weight) || 1, 10));
 				for (let i = 0; i < w; i++) acc.push(event);
 				return acc;
@@ -369,16 +299,70 @@ export async function userLoop(context) {
 				}
 			}
 
+			// ── Phase 2 identity tracking ──
+			// Pre-existing users are considered already-stitched before the dataset window —
+			// `userAuthed` starts true. Born-in-dataset users start anonymous and only flip
+			// authed once the stitch (`isAuthEvent` step in their `isFirstFunnel`) actually
+			// fires. `userAuthTimeMs` is the unix-millisecond timestamp of that stitch event.
+			let userAuthed = !userIsBornInDataset;
+			let userAuthTimeMs = null;
+
 			// PATH FOR USERS BORN IN DATASET AND PERFORMING FIRST FUNNEL
 			if (firstFunnels.length && userIsBornInDataset) {
 				const firstFunnel = chance.pickone(firstFunnels, user);
-				const firstTime = adjustedCreated.subtract(noise(), 'seconds').unix();
-				const [data, converted] = await makeFunnel(context, firstFunnel, user, firstTime, profile, userSCD, persona, featureCtx);
-				userConverted = converted;
+				let cursor = adjustedCreated.subtract(noise(), 'seconds').unix();
+
+				// Resolve attempts plan. `attempts.{min,max}` count FAILED PRIORS; total
+				// passes = failedPriors + 1.  Validator coerced bounds; default both 0.
+				const attemptsCfg = firstFunnel.attempts || null;
+				const minA = attemptsCfg ? (attemptsCfg.min || 0) : 0;
+				const maxA = attemptsCfg ? (attemptsCfg.max || 0) : 0;
+				const failedPriors = (maxA > 0) ? chance.integer({ min: minA, max: maxA }) : 0;
+				const totalAttempts = failedPriors + 1;
+				let firstAttemptFirstEventTime = null;
+
+				for (let attemptNum = 1; attemptNum <= totalAttempts; attemptNum++) {
+					const isFinal = attemptNum === totalAttempts;
+					// On the final attempt, `attempts.conversionRate` (when set) overrides the
+					// funnel's normal conversionRate. Clone the funnel object so we don't
+					// mutate the shared config.
+					const funnelToRun = (isFinal && attemptsCfg && attemptsCfg.conversionRate !== undefined)
+						? { ...firstFunnel, conversionRate: attemptsCfg.conversionRate }
+						: firstFunnel;
+					const attemptMeta = {
+						isFirstFunnel: true,
+						isBorn: true,
+						attemptsConfig: attemptsCfg,
+						attemptNumber: attemptNum,
+						totalAttempts,
+						isFinalAttempt: isFinal,
+						truncateBeforeAuth: !isFinal,
+						devicePool: userDevicePool,
+					};
+					const [data, converted, authMs] = await makeFunnel(
+						context, funnelToRun, user, cursor, profile, userSCD, persona, featureCtx, attemptMeta
+					);
+					if (isFinal) userConverted = converted;
+					if (data && data.length) {
+						if (firstAttemptFirstEventTime === null) {
+							firstAttemptFirstEventTime = dayjs(data[0].time).unix();
+						}
+						// Advance the cursor for the next attempt by a small abandon-and-retry gap.
+						const lastTime = dayjs(data[data.length - 1].time).unix();
+						cursor = lastTime + chance.integer({ min: 60, max: 30 * 60 }); // 1–30 min later
+						numEventsPreformed += data.length;
+						usersEvents = usersEvents.concat(data);
+					}
+					if (authMs) {
+						// First time we see a stitch wins — should only happen on the final attempt.
+						if (userAuthTimeMs === null) userAuthTimeMs = authMs;
+						userAuthed = true;
+					}
+				}
 
-				userFirstEventTime = dayjs(data[0].time).unix();
-				numEventsPreformed += data.length;
-				usersEvents = usersEvents.concat(data);
+				userFirstEventTime = firstAttemptFirstEventTime !== null
+					? firstAttemptFirstEventTime
+					: adjustedCreated.subtract(noise(), 'seconds').unix();
 			} else {
 				userFirstEventTime = adjustedCreated.subtract(noise(), 'seconds').unix();
 			}
@@ -387,15 +371,30 @@ export async function userLoop(context) {
 			let userChurned = false;
 			const sessionTimeout = config.sessionTimeout || 30;
 
+			// Standalone identity stamping mode: pre-existing or post-auth users get both
+			// user_id + device_id; born-in-dataset users who never authed (final firstFunnel
+			// attempt failed) stay device_only forever per the Phase 2 model.
+			const standaloneStamping = userAuthed ? 'both' : 'device_only';
+			const standaloneIdentityCtx = (userDevicePool || standaloneStamping !== 'both')
+				? { stamping: standaloneStamping, devicePool: userDevicePool }
+				: null;
+			// Usage funnels for converted users: identity already stitched, just default 'both'.
+			const usageAttemptMeta = { isFirstFunnel: false, isBorn: userIsBornInDataset, devicePool: userDevicePool };
+
+			let usageFunnelCursor = userFirstEventTime;
 			while (numEventsPreformed < numEventsThisUserWillPreform && !cancelled) {
 				let newEvents;
 				if (usageFunnels.length && userConverted) {
 					const currentFunnel = chance.pickone(usageFunnels);
-					const [data, converted] = await makeFunnel(context, currentFunnel, user, userFirstEventTime, profile, userSCD, persona, featureCtx);
+					const [data, converted] = await makeFunnel(context, currentFunnel, user, usageFunnelCursor, profile, userSCD, persona, featureCtx, usageAttemptMeta);
 					numEventsPreformed += data.length;
 					newEvents = data;
+					if (data.length) {
+						const lastTime = dayjs(data[data.length - 1].time).unix();
+						usageFunnelCursor = lastTime + chance.integer({ min: 60, max: 30 * 60 });
+					}
 				} else {
-					const data = await makeEvent(context, distinct_id, userFirstEventTime, u.pick(weightedEvents), user.anonymousIds, user.sessionIds, {}, config.groupKeys, true, false, featureCtx);
+					const data = await makeEvent(context, distinct_id, userFirstEventTime, u.pick(weightedEvents), user.anonymousIds, {}, config.groupKeys, true, false, featureCtx, standaloneIdentityCtx);
 					numEventsPreformed++;
 					newEvents = [data];
 				}
@@ -421,34 +420,13 @@ export async function userLoop(context) {
 			// Remove events flagged as future timestamps (before dungeon hooks see them)
 			usersEvents = usersEvents.filter(e => !e._drop);
 
-			// Feature 3: Engagement decay — filter behavioral events BEFORE subscription injection
-			// Subscription events (trial, upgrade, cancel) must not be randomly dropped by decay
+			// Feature 3: Engagement decay — filter behavioral events
 			const userDecay = persona?.engagementDecay || globalEngagementDecay;
 			if (userDecay && userDecay.model !== 'none' && usersEvents.length > 0) {
 				// adjustedCreated and event times now share the same dataset window — no shift.
 				usersEvents = applyEngagementDecay(usersEvents, userDecay, adjustedCreated, context, chance);
 			}
 
-			// Feature 5: Subscription lifecycle — inject after decay (exempt from decay filtering)
-			if (subscription && userIsBornInDataset) {
-				const subEvents = generateSubscriptionEvents(
-					subscription, user, persona, adjustedCreated, context, chance
-				);
-				if (subEvents.length > 0) {
-					usersEvents = usersEvents.concat(subEvents);
-					// Perf 3: ISO strings sort lexicographically — avoid Date() allocation
-					usersEvents.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
-				}
-				// Set current plan on profile
-				if (subEvents.length > 0) {
-					const lastSubEvent = subEvents[subEvents.length - 1];
-					if (lastSubEvent._currentPlan) {
-						profile.subscription_plan = lastSubEvent._currentPlan;
-						profile.subscription_status = lastSubEvent._subStatus || 'active';
-					}
-				}
-			}
-
 			// Feature 4: Data quality — duplicates and late-arriving
 			if (dataQuality) {
 				if (dataQuality.duplicateRate > 0) {
@@ -457,9 +435,7 @@ export async function userLoop(context) {
 						if (chance.bool({ likelihood: dataQuality.duplicateRate * 100 })) {
 							const dupe = { ...ev };
 							dupe.time = dayjs(ev.time).add(chance.integer({ min: 1, max: 60 }), 'seconds').toISOString();
-							// Fix 2: Regenerate insert_id so Mixpanel doesn't silently deduplicate
-							const dupeId = dupe.user_id || dupe.device_id || '';
-							dupe.insert_id = u.quickHash(`${dupe.event}-${dupe.time}-${dupeId}-dupe`);
+							dupe.insert_id = randomUUID();
 							dupes.push(dupe);
 						}
 					}
@@ -488,10 +464,39 @@ export async function userLoop(context) {
 					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD
 				});
 				u.assignSessionIds(usersEvents, sessionTimeout);
+
+				// Phase 2: per-session sticky device. After session_ids exist, deterministically
+				// pick one device per session from the user's pool and overwrite each event's
+				// device_id so all events in that session share a device. Skip when there's no
+				// pool (avgDevicePerUser=0) or only one device (no choice to make).
+				if (userDevicePool && userDevicePool.length > 1) {
+					const sessionToDevice = new Map();
+					for (const ev of usersEvents) {
+						if (!ev || !ev.device_id || !ev.session_id) continue;
+						let dev = sessionToDevice.get(ev.session_id);
+						if (!dev) {
+							dev = userDevicePool[Number(u.quickHash(`${distinct_id}:${ev.session_id}`)) % userDevicePool.length];
+							sessionToDevice.set(ev.session_id, dev);
+						}
+						ev.device_id = dev;
+					}
+				}
 			}
 
 			// Hook for processing all user events (hooks override everything)
 			if (config.hook) {
+				// `meta.isPreAuth(event)` predicate bound to this user's auth state.
+				// - Pre-existing user: authed throughout; never pre-auth.
+				// - Born-in-dataset, never converted (userAuthTimeMs===null): all pre-auth.
+				// - Born-in-dataset, converted: pre-auth strictly before the stitch event.
+				const userAuthTimeMsLocal = userAuthTimeMs;
+				const userIsBornLocal = userIsBornInDataset;
+				const isPreAuth = (event) => {
+					if (!event || !event.time) return false;
+					if (userAuthTimeMsLocal === null) return userIsBornLocal;
+					const t = typeof event.time === 'string' ? Date.parse(event.time) : Number(event.time);
+					return Number.isFinite(t) ? t < userAuthTimeMsLocal : false;
+				};
 				const newEvents = await config.hook(usersEvents, "everything", {
 					profile,
 					scd: userSCD,
@@ -499,7 +504,9 @@ export async function userLoop(context) {
 					userIsBornInDataset,
 					persona,
 					datasetStart: context.DATASET_START_SECONDS,
-					datasetEnd: context.DATASET_END_SECONDS
+					datasetEnd: context.DATASET_END_SECONDS,
+					authTime: userAuthTimeMs,
+					isPreAuth,
 				});
 				if (Array.isArray(newEvents)) usersEvents = newEvents;
 			}
@@ -546,11 +553,6 @@ export async function userLoop(context) {
 		await generateBotUsers(context, dataQuality, storage);
 	}
 
-	// Feature 9: Anomaly burst/coordinated injection (after all users)
-	if (anomalies) {
-		await generateAnomalyBursts(context, anomalies, storage);
-	}
-
 	// Clean up SIGINT handler
 	process.removeListener('SIGINT', onSigint);
 }
@@ -613,121 +615,6 @@ function applyEngagementDecay(events, decay, userCreated, context, chance) {
 	});
 }
 
-/**
- * Feature 5: Generate subscription lifecycle events for a user
- */
-function generateSubscriptionEvents(subscription, user, persona, userCreated, context, chance) {
-	const { plans, lifecycle, events: eventNames } = subscription;
-	const lc = lifecycle;
-	const subEvents = [];
-
-	const defaultPlan = plans.find(p => p.default) || plans[0];
-	let currentPlan = defaultPlan;
-	let currentStatus = 'active';
-	const paidPlans = plans.filter(p => p.price > 0);
-
-	const userStartUnix = dayjs(userCreated).unix();
-	const endUnix = context.FIXED_NOW;
-
-	// Persona modifiers for subscription behavior
-	const personaChurnMod = persona?.churnRate ? (1 + persona.churnRate) : 1.0;
-	const personaUpgradeMod = persona?.conversionModifier || 1.0;
-
-	let currentUnix = userStartUnix;
-	const monthSeconds = 30 * 86400;
-
-	// If the default plan has a trial, start a trial
-	const firstPaidPlan = paidPlans[0];
-	if (firstPaidPlan && firstPaidPlan.trialDays) {
-		const trialStart = currentUnix + chance.integer({ min: 0, max: 86400 });
-		if (trialStart < endUnix) {
-			subEvents.push(makeSubEvent(eventNames.trialStarted, trialStart, user, firstPaidPlan.name, 'trial'));
-			currentUnix = trialStart + (firstPaidPlan.trialDays * 86400);
-
-			// Trial to paid conversion
-			if (chance.bool({ likelihood: lc.trialToPayRate * personaUpgradeMod * 100 })) {
-				if (currentUnix < endUnix) {
-					subEvents.push(makeSubEvent(eventNames.subscribed, currentUnix, user, firstPaidPlan.name, 'active'));
-					currentPlan = firstPaidPlan;
-					currentStatus = 'active';
-				}
-			} else {
-				currentStatus = 'expired_trial';
-				return subEvents; // didn't convert, no more sub events
-			}
-		}
-	}
-
-	// Monthly lifecycle loop
-	while (currentUnix < endUnix) {
-		currentUnix += monthSeconds + chance.integer({ min: -86400, max: 86400 });
-		if (currentUnix >= endUnix) break;
-		if (currentStatus === 'cancelled') {
-			// Win-back check
-			if (chance.bool({ likelihood: lc.winBackRate * 100 })) {
-				currentUnix += lc.winBackDelay * 86400;
-				if (currentUnix >= endUnix) break;
-				subEvents.push(makeSubEvent(eventNames.wonBack, currentUnix, user, currentPlan.name, 'active'));
-				currentStatus = 'active';
-			}
-			break;
-		}
-
-		// Payment failure
-		if (currentPlan.price > 0 && chance.bool({ likelihood: lc.paymentFailureRate * 100 })) {
-			subEvents.push(makeSubEvent(eventNames.paymentFailed, currentUnix, user, currentPlan.name, 'payment_issue'));
-		}
-
-		// Churn
-		if (chance.bool({ likelihood: lc.churnRate * personaChurnMod * 100 })) {
-			subEvents.push(makeSubEvent(eventNames.cancelled, currentUnix, user, currentPlan.name, 'cancelled'));
-			currentStatus = 'cancelled';
-			continue;
-		}
-
-		// Upgrade
-		const currentPlanIndex = plans.indexOf(currentPlan);
-		if (currentPlanIndex < plans.length - 1 && chance.bool({ likelihood: lc.upgradeRate * personaUpgradeMod * 100 })) {
-			const newPlan = plans[currentPlanIndex + 1];
-			subEvents.push(makeSubEvent(eventNames.upgraded, currentUnix, user, newPlan.name, 'active', currentPlan.name));
-			currentPlan = newPlan;
-			continue;
-		}
-
-		// Downgrade
-		if (currentPlanIndex > 0 && currentPlan.price > 0 && chance.bool({ likelihood: lc.downgradeRate * 100 })) {
-			const newPlan = plans[currentPlanIndex - 1];
-			subEvents.push(makeSubEvent(eventNames.downgraded, currentUnix, user, newPlan.name, 'active', currentPlan.name));
-			currentPlan = newPlan;
-			continue;
-		}
-
-		// Renewal
-		if (currentPlan.price > 0) {
-			subEvents.push(makeSubEvent(eventNames.renewed, currentUnix, user, currentPlan.name, 'active'));
-		}
-	}
-
-	return subEvents;
-}
-
-function makeSubEvent(eventName, unixTime, user, planName, status, previousPlan) {
-	// Callers already guard `unixTime < endUnix` before invoking, so no clamp here.
-	// Previous code clamped against `dayjs()` (wall-clock now) — leaked wall-clock into
-	// timestamps and wasn't even the right upper bound.
-	const ev = {
-		event: eventName,
-		time: dayjs.unix(unixTime).toISOString(),
-		user_id: user.distinct_id,
-		insert_id: u.quickHash(`${eventName}-${unixTime}-${user.distinct_id}`),
-		subscription_plan: planName,
-		_currentPlan: planName,
-		_subStatus: status
-	};
-	if (previousPlan) ev.previous_plan = previousPlan;
-	return ev;
-}
-
 /**
  * Feature 4: Generate bot users with repetitive patterns
  */
@@ -772,40 +659,3 @@ async function generateBotUsers(context, dataQuality, storage) {
 		await storage.eventData.hookPush(botEvents, { profile: { distinct_id: botId, is_bot: true } });
 	}
 }
-
-/**
- * Feature 9: Generate anomaly burst and coordinated events
- */
-async function generateAnomalyBursts(context, anomalies, storage) {
-	const chance = u.getChance();
-
-	for (const a of anomalies) {
-		if (a.type !== 'burst' && a.type !== 'coordinated') continue;
-		if (!a._startUnix || !a.count) continue;
-
-		const burstEvents = [];
-		const startUnix = a._startUnix;
-		const endUnix = a._endUnix;
-		const windowSeconds = endUnix - startUnix;
-
-		for (let i = 0; i < a.count; i++) {
-			const eventTime = startUnix + chance.integer({ min: 0, max: Math.max(1, windowSeconds) });
-			if (eventTime > context.FIXED_NOW) continue;
-			const userId = a.type === 'coordinated'
-				? `anomaly_${chance.guid().slice(0, 8)}`
-				: `burst_${chance.integer({ min: 1, max: 100 })}`;
-
-			const ev = {
-				event: a.event,
-				time: dayjs.unix(eventTime).toISOString(),
-				user_id: userId,
-				insert_id: u.quickHash(`${a.event}-${eventTime}-${userId}-${i}`),
-			};
-			if (a.tag) ev._anomaly = a.tag;
-			if (a.properties) Object.assign(ev, a.properties);
-			burstEvents.push(ev);
-		}
-
-		await storage.eventData.hookPush(burstEvents, {});
-	}
-}

package/lib/utils/utils.js

@@ -1156,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, datasetEndUnix } = 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, datasetEndUnix);
+	const props = person(user_id, daysAgoBorn, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix, avgDevicePerUser);
 
 	const user = {
 		distinct_id: user_id,
@@ -1275,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, datasetEndUnix) {
+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);
@@ -1320,9 +1317,25 @@ 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++) {
 			// Use seeded chance, not ak-tools uid() (which uses Math.random).
 			const anonId = chance.string({ length: 42, pool: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' });