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

package/lib/generators/events.js

@@ -101,19 +101,13 @@ export async function makeEvent(
 
     // Set event time using TimeSoup for realistic distribution
     if (earliestTime) {
-        let shiftedTimestamp;
+        let unixTime;
         if (isFirstEvent) {
-            shiftedTimestamp = earliestTime + context.TIME_SHIFT_SECONDS;
+            unixTime = earliestTime;
         } else {
-            // TimeSoup returns unix seconds; shift and convert to ISO once
-            const soupTimestamp = u.TimeSoup(earliestTime, context.FIXED_NOW, peaks, deviation, mean, dayOfWeekWeights, hourOfDayWeights, context.TIME_SHIFT_SECONDS);
-            shiftedTimestamp = soupTimestamp + context.TIME_SHIFT_SECONDS;
+            unixTime = u.TimeSoup(earliestTime, context.FIXED_NOW, peaks, deviation, mean, dayOfWeekWeights, hourOfDayWeights);
         }
-        // Drop events that would land in the future (Mixpanel rewrites these to "now", causing pile-ups)
-        if (shiftedTimestamp > context.MAX_TIME) {
-            eventTemplate._drop = true;
-        }
-        eventTemplate.time = dayjs.unix(Math.min(shiftedTimestamp, context.MAX_TIME)).toISOString();
+        eventTemplate.time = dayjs.unix(unixTime).toISOString();
     }
 
     // Add anonymous identifiers
@@ -196,11 +190,12 @@ export async function makeEvent(
         }
     }
 
-    // Perf 1: Compute eventUnix once for all time-based checks
-    // Subtracts TIME_SHIFT to convert real time back to FIXED time (world events/features use FIXED time)
+    // Perf 1: Compute eventUnix once for all time-based checks. World events &
+    // features were resolved against the dataset window (no shift), and event
+    // times now also live in that same window — direct unix conversion works.
     let eventUnix = null;
     if ((worldEventsTimeline || resolvedFeatures) && eventTemplate.time) {
-        eventUnix = dayjs(eventTemplate.time).subtract(context.TIME_SHIFT_SECONDS, 'seconds').unix();
+        eventUnix = dayjs(eventTemplate.time).unix();
     }
 
     // Feature 2: World events — inject props for active events at this timestamp
@@ -303,7 +298,9 @@ export async function makeEvent(
         const hookedEvent = await hook(eventTemplate, "event", {
             user: { distinct_id },
             config,
-            persona: featureCtx.persona || null
+            persona: featureCtx.persona || null,
+            datasetStart: context.DATASET_START_SECONDS,
+            datasetEnd: context.DATASET_END_SECONDS
         });
         // If hook returns a modified event, use it; otherwise use original
         if (hookedEvent && typeof hookedEvent === 'object') {

package/lib/generators/funnels.js

@@ -68,7 +68,11 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	}
 
 	// Call pre-funnel hook
-	await hook(funnel, "funnel-pre", { user, profile, scd, funnel, config, firstEventTime });
+	await hook(funnel, "funnel-pre", {
+		user, profile, scd, funnel, config, firstEventTime,
+		datasetStart: context.DATASET_START_SECONDS,
+		datasetEnd: context.DATASET_END_SECONDS
+	});
 
 	// Extract funnel configuration
 	let {
@@ -206,7 +210,11 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	);
 
 	// Call post-funnel hook
-	await hook(finalEvents, "funnel-post", { user, profile, scd, funnel, config });
+	await hook(finalEvents, "funnel-post", {
+		user, profile, scd, funnel, config,
+		datasetStart: context.DATASET_START_SECONDS,
+		datasetEnd: context.DATASET_END_SECONDS
+	});
 
 	return [finalEvents, doesUserConvert];
 }
@@ -446,8 +454,8 @@ async function generateFunnelEvents(
 
 		try {
 			let computedTime = dayjs(funnelStartTime).add(event.relativeTimeMs, "milliseconds");
-			// Drop events that would land in the future
-			if (context.MAX_TIME && computedTime.unix() > context.MAX_TIME) {
+			// Drop events that would land past the dataset window
+			if (context.FIXED_NOW && computedTime.unix() > context.FIXED_NOW) {
 				newEvent._drop = true;
 			}
 			if (computedTime.isValid()) {

package/lib/generators/mirror.js

@@ -22,8 +22,9 @@ export async function makeMirror(context) {
     if (!mirrorProps || Object.keys(mirrorProps).length === 0) {
         return; // No mirror properties configured
     }
-    
-    const now = dayjs();
+
+    // Anchor to the resolved dataset end (not wall-clock) so mirror behavior is deterministic.
+    const now = context.FIXED_NOW ? dayjs.unix(context.FIXED_NOW) : dayjs();
 
     for (const oldEvent of eventData) {
         let newEvent = null;

package/lib/generators/product-names.js

@@ -119,7 +119,7 @@ export const productComparisonGen = createTextGenerator({
 	authenticityLevel: 0.7,
 	specificityLevel: 0.8,
 	min: 100,
-	max: 300,
+	max: 254,  // capped at Mixpanel string property limit
 	includeMetadata: false
 });
 

package/lib/generators/scd.js

@@ -48,7 +48,8 @@ export async function makeSCD(context, scdProp, scdKey, distinct_id, mutations,
 
     const scdEntries = [];
     let lastInserted = dayjs(created);
-    const now = dayjs();
+    // Anchor to the resolved dataset end (not wall-clock) so SCD count is deterministic.
+    const now = context.FIXED_NOW ? dayjs.unix(context.FIXED_NOW) : dayjs();
     const deltaDays = now.diff(lastInserted, "day");
     const uuidKeyName = type === 'user' ? 'distinct_id' : type;
     let lastStartTime = null; // Track for monotonic ordering

package/lib/generators/text.js

@@ -524,7 +524,7 @@ class OrganicTextGenerator {
             intensity: 'medium',
             formality: 'casual',
             min: 100,
-            max: 500,
+            max: 254,  // default capped at Mixpanel string property limit; override per-generator if needed
             seed: null,
             keywords: null,
             keywordDensity: 0.15,

package/lib/orchestrators/user-loop.js

@@ -39,9 +39,11 @@ export async function userLoop(context) {
 		userProps,
 		scdProps,
 		numDays,
+		avgEventsPerUserPerDay,
 		percentUsersBornInDataset = 15,
 		strictEventCount = false,
-		bornRecentBias = 0.3, // 0 = uniform distribution, 1 = heavily biased toward recent births
+		bornRecentBias = 0, // -1..1; positive = births skew toward end of window
+		preExistingSpread = 'uniform', // 'pinned' (FIXED_BEGIN ± 1d) | 'uniform' ([FIXED_BEGIN-30d, FIXED_BEGIN])
 		personas,
 		worldEvents,
 		engagementDecay: globalEngagementDecay,
@@ -54,7 +56,10 @@ export async function userLoop(context) {
 	} = config;
 
 	const { eventData, userProfilesData, scdTableData } = storage;
-	const avgEvPerUser = numEvents / numUsers;
+	// Per-user-per-day rate is the canonical event-volume primitive (config-validator
+	// guarantees it is set). Each user's event count is rate × their active days, so
+	// born-late users don't compress a full per-user budget into a tiny window.
+	const ratePerDay = avgEventsPerUserPerDay ?? (numEvents / numUsers / numDays);
 	const startTime = Date.now();
 
 	// Create batches for parallel processing
@@ -103,7 +108,7 @@ export async function userLoop(context) {
 			}
 
 			const userId = chance.guid();
-			const user = u.generateUser(userId, { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds });
+			const user = u.generateUser(userId, { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix: context.FIXED_NOW });
 			const { distinct_id, created } = user;
 			const userIsBornInDataset = chance.bool({ likelihood: percentUsersBornInDataset });
 
@@ -123,14 +128,13 @@ export async function userLoop(context) {
 
 			if (!userIsBornInDataset) delete user.created;
 
-			// Calculate time adjustments
-			const daysShift = context.getDaysShift();
-
-			// Apply recency bias to birth dates for users born in dataset
+			// Apply recency bias to birth dates for users born in dataset.
+			// `created` (from generateUser → person) is anchored to the dataset end,
+			// so it already lives inside [FIXED_BEGIN, FIXED_NOW]. No shift needed.
 			// bornRecentBias: 0 = uniform distribution, 1 = heavily biased toward recent
 			let adjustedCreated;
 			if (userIsBornInDataset) {
-				let biasedCreated = dayjs(created).subtract(daysShift, 'd');
+				let biasedCreated = dayjs(created);
 
 				if (bornRecentBias !== 0) {
 					// Calculate how far into the dataset this user was born (0 = start, 1 = end/recent)
@@ -160,7 +164,18 @@ export async function userLoop(context) {
 				// Update user.created to match biased timestamp for profile consistency
 				user.created = adjustedCreated.toISOString();
 			} else {
-				adjustedCreated = dayjs.unix(context.FIXED_BEGIN);
+				// Pre-existing user: choose where their "first ever event" lives.
+				// 'pinned' (legacy): exactly at FIXED_BEGIN — all pre-existing users stack
+				//   at day 0, which front-loads early-window event density.
+				// 'uniform' (default): sample uniformly from [FIXED_BEGIN - 30d, FIXED_BEGIN]
+				//   so pre-existing users have varied "born before dataset" timestamps.
+				//   Their TimeSoup-distributed events still mostly land in [FIXED_BEGIN, FIXED_NOW].
+				if (preExistingSpread === 'uniform') {
+					const offsetDays = chance.floating({ min: 0, max: 30 });
+					adjustedCreated = dayjs.unix(context.FIXED_BEGIN).subtract(offsetDays, 'day');
+				} else {
+					adjustedCreated = dayjs.unix(context.FIXED_BEGIN);
+				}
 			}
 
 			// Feature 7: Geographic intelligence — assign sticky location
@@ -266,7 +281,9 @@ export async function userLoop(context) {
 					user,
 					config,
 					userIsBornInDataset,
-					persona
+					persona,
+					datasetStart: context.DATASET_START_SECONDS,
+					datasetEnd: context.DATASET_END_SECONDS
 				});
 			}
 
@@ -288,7 +305,9 @@ export async function userLoop(context) {
 						type: 'user',
 						scd: { [key]: scdProps[key] },
 						config,
-						allSCDs: userSCD
+						allSCDs: userSCD,
+						datasetStart: context.DATASET_START_SECONDS,
+						datasetEnd: context.DATASET_END_SECONDS
 					});
 					if (Array.isArray(hookResult)) {
 						changes = hookResult;
@@ -297,9 +316,17 @@ export async function userLoop(context) {
 				}
 			}
 
+			// User's active days = how much of the dataset window they're alive for.
+			// Pre-existing users: full window. Born-in-dataset: from birth to FIXED_NOW.
+			// Floor at 1 day so users born on the very last day still emit a few events.
+			const userActiveDays = userIsBornInDataset
+				? Math.max(1, (context.FIXED_NOW - adjustedCreated.unix()) / 86400)
+				: numDays;
+			const userEventBudget = ratePerDay * userActiveDays;
+
 			let numEventsThisUserWillPreform = Math.floor(chance.normal({
-				mean: avgEvPerUser,
-				dev: avgEvPerUser / u.integer(u.integer(2, 5), u.integer(2, 7))
+				mean: userEventBudget,
+				dev: userEventBudget / u.integer(u.integer(2, 5), u.integer(2, 7))
 			}) * 0.714159265359);
 
 			// Power users and low-activity users logic
@@ -349,8 +376,7 @@ export async function userLoop(context) {
 				const [data, converted] = await makeFunnel(context, firstFunnel, user, firstTime, profile, userSCD, persona, featureCtx);
 				userConverted = converted;
 
-				const timeShift = context.getTimeShift();
-				userFirstEventTime = dayjs(data[0].time).subtract(timeShift, 'seconds').unix();
+				userFirstEventTime = dayjs(data[0].time).unix();
 				numEventsPreformed += data.length;
 				usersEvents = usersEvents.concat(data);
 			} else {
@@ -399,10 +425,8 @@ export async function userLoop(context) {
 			// Subscription events (trial, upgrade, cancel) must not be randomly dropped by decay
 			const userDecay = persona?.engagementDecay || globalEngagementDecay;
 			if (userDecay && userDecay.model !== 'none' && usersEvents.length > 0) {
-				// adjustedCreated is in FIXED time space, but ev.time is in PRESENT time (shifted).
-				// Shift adjustedCreated to present so daysSinceBirth reflects within-dataset age.
-				const adjustedCreatedPresent = adjustedCreated.add(context.TIME_SHIFT_SECONDS, 'seconds');
-				usersEvents = applyEngagementDecay(usersEvents, userDecay, adjustedCreatedPresent, context, chance);
+				// 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)
@@ -461,9 +485,7 @@ export async function userLoop(context) {
 					earliestTime: userFirstEventTime,
 					latestTime: context.FIXED_NOW,
 					peaks: soupPeaks, deviation: soupDev, mean: soupMean,
-					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD,
-					timeShiftSeconds: context.TIME_SHIFT_SECONDS,
-					maxTime: context.MAX_TIME
+					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD
 				});
 				u.assignSessionIds(usersEvents, sessionTimeout);
 			}
@@ -475,11 +497,22 @@ export async function userLoop(context) {
 					scd: userSCD,
 					config,
 					userIsBornInDataset,
-					persona
+					persona,
+					datasetStart: context.DATASET_START_SECONDS,
+					datasetEnd: context.DATASET_END_SECONDS
 				});
 				if (Array.isArray(newEvents)) usersEvents = newEvents;
 			}
 
+			// Defensive guard: drop any events whose timestamp landed past the
+			// configured dataset end. Hooks that duplicate events with time offsets
+			// (weekend surges, viral spreads) can leak a few past the boundary.
+			usersEvents = usersEvents.filter(e => {
+				if (!e || !e.time) return true;
+				const t = typeof e.time === 'string' ? Date.parse(e.time) / 1000 : Number(e.time);
+				return Number.isFinite(t) ? t <= context.FIXED_NOW : true;
+			});
+
 			// Store all user data
 			await userProfilesData.hookPush(profile);
 
@@ -594,8 +627,7 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 	const paidPlans = plans.filter(p => p.price > 0);
 
 	const userStartUnix = dayjs(userCreated).unix();
-	const endUnix = context.MAX_TIME;
-	const timeShift = context.TIME_SHIFT_SECONDS;
+	const endUnix = context.FIXED_NOW;
 
 	// Persona modifiers for subscription behavior
 	const personaChurnMod = persona?.churnRate ? (1 + persona.churnRate) : 1.0;
@@ -608,14 +640,14 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 	const firstPaidPlan = paidPlans[0];
 	if (firstPaidPlan && firstPaidPlan.trialDays) {
 		const trialStart = currentUnix + chance.integer({ min: 0, max: 86400 });
-		if (trialStart + timeShift < endUnix) {
-			subEvents.push(makeSubEvent(eventNames.trialStarted, trialStart + timeShift, user, firstPaidPlan.name, 'trial'));
+		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 + timeShift < endUnix) {
-					subEvents.push(makeSubEvent(eventNames.subscribed, currentUnix + timeShift, user, firstPaidPlan.name, 'active'));
+				if (currentUnix < endUnix) {
+					subEvents.push(makeSubEvent(eventNames.subscribed, currentUnix, user, firstPaidPlan.name, 'active'));
 					currentPlan = firstPaidPlan;
 					currentStatus = 'active';
 				}
@@ -627,15 +659,15 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 	}
 
 	// Monthly lifecycle loop
-	while (currentUnix + timeShift < endUnix) {
+	while (currentUnix < endUnix) {
 		currentUnix += monthSeconds + chance.integer({ min: -86400, max: 86400 });
-		if (currentUnix + timeShift >= endUnix) break;
+		if (currentUnix >= endUnix) break;
 		if (currentStatus === 'cancelled') {
 			// Win-back check
 			if (chance.bool({ likelihood: lc.winBackRate * 100 })) {
 				currentUnix += lc.winBackDelay * 86400;
-				if (currentUnix + timeShift >= endUnix) break;
-				subEvents.push(makeSubEvent(eventNames.wonBack, currentUnix + timeShift, user, currentPlan.name, 'active'));
+				if (currentUnix >= endUnix) break;
+				subEvents.push(makeSubEvent(eventNames.wonBack, currentUnix, user, currentPlan.name, 'active'));
 				currentStatus = 'active';
 			}
 			break;
@@ -643,12 +675,12 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 
 		// Payment failure
 		if (currentPlan.price > 0 && chance.bool({ likelihood: lc.paymentFailureRate * 100 })) {
-			subEvents.push(makeSubEvent(eventNames.paymentFailed, currentUnix + timeShift, user, currentPlan.name, 'payment_issue'));
+			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 + timeShift, user, currentPlan.name, 'cancelled'));
+			subEvents.push(makeSubEvent(eventNames.cancelled, currentUnix, user, currentPlan.name, 'cancelled'));
 			currentStatus = 'cancelled';
 			continue;
 		}
@@ -657,7 +689,7 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 		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 + timeShift, user, newPlan.name, 'active', currentPlan.name));
+			subEvents.push(makeSubEvent(eventNames.upgraded, currentUnix, user, newPlan.name, 'active', currentPlan.name));
 			currentPlan = newPlan;
 			continue;
 		}
@@ -665,14 +697,14 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 		// Downgrade
 		if (currentPlanIndex > 0 && currentPlan.price > 0 && chance.bool({ likelihood: lc.downgradeRate * 100 })) {
 			const newPlan = plans[currentPlanIndex - 1];
-			subEvents.push(makeSubEvent(eventNames.downgraded, currentUnix + timeShift, user, newPlan.name, 'active', currentPlan.name));
+			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 + timeShift, user, currentPlan.name, 'active'));
+			subEvents.push(makeSubEvent(eventNames.renewed, currentUnix, user, currentPlan.name, 'active'));
 		}
 	}
 
@@ -680,9 +712,12 @@ function generateSubscriptionEvents(subscription, user, persona, userCreated, co
 }
 
 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(Math.min(unixTime, dayjs().unix())).toISOString(),
+		time: dayjs.unix(unixTime).toISOString(),
 		user_id: user.distinct_id,
 		insert_id: u.quickHash(`${eventName}-${unixTime}-${user.distinct_id}`),
 		subscription_plan: planName,
@@ -708,14 +743,14 @@ async function generateBotUsers(context, dataQuality, storage) {
 		const botId = `bot_${chance.guid().slice(0, 8)}`;
 		const botEvents = [];
 
-		// Bots generate events at machine-like intervals
-		let currentTime = context.FIXED_BEGIN + context.TIME_SHIFT_SECONDS;
-		const interval = Math.floor(((context.MAX_TIME - currentTime) / botEventsPerUser));
+		// Bots generate events at machine-like intervals across the dataset window
+		let currentTime = context.FIXED_BEGIN;
+		const interval = Math.floor(((context.FIXED_NOW - currentTime) / botEventsPerUser));
 
 		for (let e = 0; e < botEventsPerUser; e++) {
 			const chosenEvent = botEventTypes[e % botEventTypes.length];
 			currentTime += interval + chance.integer({ min: 0, max: 10 });
-			if (currentTime > context.MAX_TIME) break;
+			if (currentTime > context.FIXED_NOW) break;
 			botEvents.push({
 				event: chosenEvent.event,
 				time: dayjs.unix(currentTime).toISOString(),
@@ -743,20 +778,19 @@ async function generateBotUsers(context, dataQuality, storage) {
  */
 async function generateAnomalyBursts(context, anomalies, storage) {
 	const chance = u.getChance();
-	const timeShift = context.TIME_SHIFT_SECONDS;
 
 	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 + timeShift;
-		const endUnix = a._endUnix + timeShift;
+		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.MAX_TIME) continue;
+			if (eventTime > context.FIXED_NOW) continue;
 			const userId = a.type === 'coordinated'
 				? `anomaly_${chance.guid().slice(0, 8)}`
 				: `burst_${chance.integer({ min: 1, max: 100 })}`;

package/lib/templates/macro-presets.js

@@ -0,0 +1,111 @@
+/**
+ * Macro preset configurations.
+ *
+ * Macro presets shape the BIG-PICTURE trend across the dataset window —
+ * how user births are distributed in time and what fraction of users are
+ * born inside the window vs already existing at its start. These are the
+ * knobs that determine whether the chart tilts up, tilts down, or stays flat.
+ *
+ * Soup presets (lib/templates/soup-presets.js) are the orthogonal axis:
+ * they shape intra-week and intra-day rhythm (DOW/HOD weights, peak count,
+ * deviation). The two are independent — pick a macro and a soup separately.
+ *
+ * The default macro is "flat" so a brand-new dungeon produces a steady
+ * baseline. Layer hooks on top to inject deliberate trends/spikes.
+ *
+ * Parameters:
+ * - bornRecentBias: -1..1. Negative pushes births toward dataset start,
+ *   positive toward the end. Power-function shaped in user-loop.js.
+ * - percentUsersBornInDataset: 0..100. Fraction of users created inside the
+ *   window. The rest are pre-existing (first event ≈ FIXED_BEGIN).
+ * - preExistingSpread: "pinned" (current behavior — pre-existing users start
+ *   at FIXED_BEGIN ± 1 day) | "uniform" (sample first event time uniformly
+ *   across [FIXED_BEGIN - 30d, FIXED_BEGIN] so they don't all stack at day 0).
+ */
+
+/** @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.
+	 */
+	flat: {
+		bornRecentBias: 0,
+		percentUsersBornInDataset: 15,
+		preExistingSpread: 'uniform',
+	},
+
+	/**
+	 * steady — Lightly-growing SaaS.
+	 * Slight uptrend without any visible spike at the right edge.
+	 */
+	steady: {
+		bornRecentBias: 0.1,
+		percentUsersBornInDataset: 10,
+		preExistingSpread: 'uniform',
+	},
+
+	/**
+	 * growth — Visible uptrend story without the meteoric blow-up.
+	 * Use when the dataset wants to show clear acquisition over time.
+	 */
+	growth: {
+		bornRecentBias: 0.3,
+		percentUsersBornInDataset: 25,
+		preExistingSpread: 'pinned',
+	},
+
+	/**
+	 * viral — Hockey-stick acquisition.
+	 * Strong late-window ramp. Pair with persona/feature hooks for the full effect.
+	 */
+	viral: {
+		bornRecentBias: 0.6,
+		percentUsersBornInDataset: 50,
+		preExistingSpread: 'pinned',
+	},
+
+	/**
+	 * decline — Sunsetting product, churning users.
+	 * Few new users, those that exist are born early. Pair with churn hooks.
+	 */
+	decline: {
+		bornRecentBias: -0.3,
+		percentUsersBornInDataset: 5,
+		preExistingSpread: 'uniform',
+	},
+};
+
+/** @type {string[]} */
+export const MACRO_PRESET_NAMES = Object.keys(MACRO_PRESETS);
+
+/**
+ * Resolve a macro config — accepts string presets, preset+overrides objects, or raw objects.
+ * Defaults to "flat" if nothing is provided.
+ *
+ * @param {string | object | undefined} macro - Macro config from dungeon
+ * @returns {{bornRecentBias: number, percentUsersBornInDataset: number, preExistingSpread: 'pinned' | 'uniform'}}
+ */
+export function resolveMacro(macro) {
+	if (!macro) return { ...MACRO_PRESETS.flat };
+
+	if (typeof macro === 'string') {
+		const preset = MACRO_PRESETS[macro];
+		if (!preset) {
+			throw new Error(`Unknown macro preset: "${macro}". Valid presets: ${MACRO_PRESET_NAMES.join(', ')}`);
+		}
+		return { ...preset };
+	}
+
+	if (typeof macro === 'object' && macro.preset) {
+		const preset = MACRO_PRESETS[macro.preset];
+		if (!preset) {
+			throw new Error(`Unknown macro preset: "${macro.preset}". Valid presets: ${MACRO_PRESET_NAMES.join(', ')}`);
+		}
+		const { preset: _, ...overrides } = macro;
+		return { ...preset, ...overrides };
+	}
+
+	// Raw object: pass through, filling in flat defaults for missing fields
+	return { ...MACRO_PRESETS.flat, ...macro };
+}