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

package/dungeons/vertical/sass.js

@@ -2,7 +2,7 @@
 const SEED = "harness-sass";
 const num_days = 100;
 const num_users = 5_000;
-const avg_events_per_user = 120;
+const avg_events_per_user_per_day = 1.2;
 let token = "your-mixpanel-token";
 
 // ── env overrides ──
@@ -258,7 +258,7 @@ const config = {
 	token,
 	seed: SEED,
 	numDays: num_days,
-	numEvents: num_users * avg_events_per_user,
+	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -273,7 +273,6 @@ const config = {
 	hasCampaigns: false,
 	isAnonymous: false,
 	hasAdSpend: false,
-	percentUsersBornInDataset: 50,
 	hasAvatar: true,
 	concurrency: 1,
 	writeToDisk: false,

package/dungeons/vertical/social.js

@@ -2,7 +2,7 @@
 const SEED = "harness-social";
 const num_days = 100;
 const num_users = 5_000;
-const avg_events_per_user = 120;
+const avg_events_per_user_per_day = 1.2;
 let token = "your-mixpanel-token";
 
 // ── env overrides ──
@@ -172,7 +172,7 @@ const config = {
 	token,
 	seed: SEED,
 	numDays: num_days,
-	numEvents: num_users * avg_events_per_user,
+	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -187,7 +187,6 @@ const config = {
 	hasCampaigns: false,
 	isAnonymous: false,
 	hasAdSpend: false,
-	percentUsersBornInDataset: 50,
 	hasAvatar: true,
 	concurrency: 1,
 	writeToDisk: false,
@@ -521,15 +520,7 @@ const config = {
 				}
 			}
 
-			// Hook #8: WEEKEND CONTENT SURGE - tag weekend content (duplication handled in everything hook)
-			if (record.event === "post created" || record.event === "story created") {
-				const dayOfWeek = EVENT_TIME.day(); // 0 = Sunday, 6 = Saturday
-				if (dayOfWeek === 0 || dayOfWeek === 6) {
-					record.weekend_surge = true;
-				} else {
-					record.weekend_surge = false;
-				}
-			}
+			// Hook #8: WEEKEND CONTENT SURGE - tagging moved to everything hook (sessionization reassigns times after event hook)
 		}
 
 		// ─── EVERYTHING-LEVEL HOOKS ──────────────────────────────────────
@@ -721,7 +712,18 @@ const config = {
 				}
 			}
 
-			// Hook #8: WEEKEND CONTENT SURGE - inject duplicate events for weekend content
+			// Hook #8: WEEKEND CONTENT SURGE - tag weekend content AFTER sessionization has finalized times
+			userEvents.forEach(event => {
+				if (event.event === "post created" || event.event === "story created") {
+					const dow = new Date(event.time).getUTCDay(); // 0 = Sunday, 6 = Saturday
+					if (dow === 0 || dow === 6) {
+						event.weekend_surge = true;
+					} else {
+						event.weekend_surge = false;
+					}
+				}
+			});
+			// Inject duplicate events for weekend content
 			for (let idx = userEvents.length - 1; idx >= 0; idx--) {
 				const event = userEvents[idx];
 				if (event.weekend_surge && !event.weekend_duplicate) {

package/dungeons/vertical/travel.js

@@ -2,7 +2,7 @@
 const SEED = "dm4-travel";
 const num_days = 100;
 const num_users = 5_000;
-const avg_events_per_user = 120;
+const avg_events_per_user_per_day = 1.2;
 let token = "your-mixpanel-token";
 
 // ── env overrides ──
@@ -207,7 +207,7 @@ const config = {
 	token,
 	seed: SEED,
 	numDays: num_days,
-	numEvents: num_users * avg_events_per_user,
+	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -222,7 +222,6 @@ const config = {
 	hasCampaigns: false,
 	isAnonymous: false,
 	hasAdSpend: false,
-	percentUsersBornInDataset: 35,
 	hasAvatar: true,
 	concurrency: 1,
 	writeToDisk: false,
@@ -647,29 +646,13 @@ const config = {
 			// prop-setting only; no conversionRate changes
 		}
 
-		// ── HOOK 1: WEEKEND LEISURE SURGE (event) ────────────
-		if (type === "event") {
-			if (record.event === "booking completed") {
-				const dayOfWeek = dayjs(record.time).day();
-				// Friday=5, Saturday=6, Sunday=0
-				if (dayOfWeek === 0 || dayOfWeek === 5 || dayOfWeek === 6) {
-					record.nightly_rate = Math.floor((record.nightly_rate || 150) * 1.3);
-					record.total_cost = Math.floor((record.total_cost || 450) * 1.3);
-				}
-			}
+		// ── HOOK 1: WEEKEND LEISURE SURGE ────────────
+		// Moved to everything hook (sessionization reassigns times after event hook)
 
-			// ── HOOK 2: ADVANCE BOOKING DISCOUNT (event) ─────
-			if (record.event === "booking completed") {
-				const eventTime = dayjs(record.time);
-				const daysUntilEnd = NOW.diff(eventTime, "days");
-				if (daysUntilEnd > 21) {
-					record.booking_window = "advance";
-					record.nightly_rate = Math.floor((record.nightly_rate || 150) * 0.8);
-				} else if (daysUntilEnd < 3) {
-					record.booking_window = "last_minute";
-					record.nightly_rate = Math.floor((record.nightly_rate || 150) * 1.4);
-				}
-			}
+		// ── HOOK 2: ADVANCE BOOKING DISCOUNT ─────
+		// Moved to everything hook (sessionization reassigns times after event hook)
+		if (type === "event") {
+			// no-op: DOW-dependent hooks moved to everything hook
 		}
 
 		// ── EVERYTHING HOOKS ─────────────────────────────────
@@ -689,6 +672,34 @@ const config = {
 				});
 			}
 
+			// ── HOOK 1: WEEKEND LEISURE SURGE ────────────
+			// Apply AFTER sessionization has finalized times
+			events.forEach(e => {
+				if (e.event === "booking completed") {
+					const dayOfWeek = new Date(e.time).getUTCDay();
+					// Friday=5, Saturday=6, Sunday=0
+					if (dayOfWeek === 0 || dayOfWeek === 5 || dayOfWeek === 6) {
+						e.nightly_rate = Math.floor((e.nightly_rate || 150) * 1.3);
+						e.total_cost = Math.floor((e.total_cost || 450) * 1.3);
+					}
+				}
+			});
+
+			// ── HOOK 2: ADVANCE BOOKING DISCOUNT ─────
+			events.forEach(e => {
+				if (e.event === "booking completed") {
+					const eventTime = dayjs(e.time);
+					const daysUntilEnd = NOW.diff(eventTime, "days");
+					if (daysUntilEnd > 21) {
+						e.booking_window = "advance";
+						e.nightly_rate = Math.floor((e.nightly_rate || 150) * 0.8);
+					} else if (daysUntilEnd < 3) {
+						e.booking_window = "last_minute";
+						e.nightly_rate = Math.floor((e.nightly_rate || 150) * 1.4);
+					}
+				}
+			});
+
 			// ─── Bug 2 fix: Repeat destination clustering conversion filtering ───
 			// Drop ~25% of "booking completed" events for users who are NOT
 			// business_traveler or luxury_seeker to simulate their lower funnel
@@ -716,7 +727,29 @@ const config = {
 			}
 
 			// ── HOOK 4: CANCELLATION BY BOOKING WINDOW ───────
-			// Last-minute bookers rarely cancel.
+			// Match each cancellation to its nearest preceding booking
+			// and copy the booking's booking_window. This replaces the
+			// random booking_window that the event config assigns to
+			// cancellation events independently.
+			const bookingsByTime = events
+				.filter(e => e.event === "booking completed")
+				.sort((a, b) => new Date(a.time) - new Date(b.time));
+			events.forEach(e => {
+				if (e.event === "booking cancelled" && bookingsByTime.length > 0) {
+					const cancelTime = new Date(e.time).getTime();
+					// Find the nearest preceding booking (or the first one)
+					let matched = bookingsByTime[0];
+					for (let b = bookingsByTime.length - 1; b >= 0; b--) {
+						if (new Date(bookingsByTime[b].time).getTime() <= cancelTime) {
+							matched = bookingsByTime[b];
+							break;
+						}
+					}
+					e.booking_window = matched.booking_window;
+				}
+			});
+
+			// Last-minute bookers rarely cancel — drop 40%.
 			for (let i = events.length - 1; i >= 0; i--) {
 				if (events[i].event === "booking cancelled" && events[i].booking_window === "last_minute") {
 					if (chance.bool({ likelihood: 40 })) {

package/lib/core/config-validator.js

@@ -12,6 +12,7 @@ import dayjs from "dayjs";
 import { makeName } from "ak-tools";
 import * as u from "../utils/utils.js";
 import { resolveSoup } from "../templates/soup-presets.js";
+import { resolveMacro } from "../templates/macro-presets.js";
 
 /** Fixed reference point for time calculations (2024-02-02) */
 const FIXED_NOW = dayjs('2024-02-02').unix();
@@ -87,9 +88,10 @@ export function validateDungeonConfig(config) {
 	// Extract configuration with defaults
 	let {
 		seed,
-		numEvents = 100_000,
+		numEvents,
 		numUsers = 1000,
 		numDays = 30,
+		avgEventsPerUserPerDay,
 		epochStart = 0,
 		epochEnd = dayjs().unix(),
 		events = [{ event: "foo" }, { event: "bar" }, { event: "baz" }],
@@ -148,18 +150,24 @@ export function validateDungeonConfig(config) {
 		);
 	}
 
-	// Auto-enable batch mode for large datasets to prevent OOM
-	if (numEvents >= 2_000_000 && config.batchSize === undefined) {
-		batchSize = 1_000_000;
-		console.warn(`⚠️  Auto-enabling batch mode: numEvents (${numEvents.toLocaleString()}) >= 2M. Using batchSize of ${batchSize.toLocaleString()}.`);
-	}
-
 	// Ensure defaults for deep objects
 	if (!config.superProps) config.superProps = superProps;
 	if (!config.userProps || Object.keys(config.userProps).length === 0) {
 		userProps = { spiritAnimal: chance.animal.bind(chance) };
 	}
 
+	// Guard against zero/negative numUsers up front (would produce NaN budgets).
+	if (!Number.isFinite(numUsers) || numUsers <= 0) {
+		throw new Error(`numUsers must be a positive number (got ${numUsers})`);
+	}
+
+	// Reject explicit zero/negative numDays from the caller before falling through
+	// to the epoch-derivation branches below (which would otherwise replace 0
+	// with a derived value or throw a less-specific message).
+	if (config.numDays !== undefined && (!Number.isFinite(config.numDays) || config.numDays <= 0)) {
+		throw new Error(`numDays must be a positive number (got ${config.numDays})`);
+	}
+
 	// Setting up "TIME"
 	if (epochStart && !numDays) numDays = dayjs.unix(epochEnd).diff(dayjs.unix(epochStart), "day");
 	if (!epochStart && numDays) epochStart = dayjs.unix(epochEnd).subtract(numDays, "day").unix();
@@ -168,15 +176,57 @@ export function validateDungeonConfig(config) {
 		throw new Error("Either epochStart or numDays must be provided");
 	}
 
-	// Resolve soup presets (must happen after numDays is computed)
+	// Final sanity check (e.g. epochStart/epochEnd produced a non-positive numDays).
+	if (!Number.isFinite(numDays) || numDays <= 0) {
+		throw new Error(`numDays must be a positive number (got ${numDays})`);
+	}
+
+	// Resolve event-rate primitive: avgEventsPerUserPerDay is the canonical knob.
+	// numEvents is supported as a fallback (legacy + total-volume target). Whichever
+	// is set, derive the other so downstream code (batching, progress, mixpanel-sender)
+	// can use either.
+	if (avgEventsPerUserPerDay !== undefined && numEvents !== undefined) {
+		// Both provided: avgEventsPerUserPerDay wins. Recompute numEvents from rate.
+		numEvents = Math.round(avgEventsPerUserPerDay * numUsers * numDays);
+	} else if (avgEventsPerUserPerDay !== undefined) {
+		numEvents = Math.round(avgEventsPerUserPerDay * numUsers * numDays);
+	} else if (numEvents !== undefined) {
+		avgEventsPerUserPerDay = numEvents / numUsers / numDays;
+	} else {
+		// Neither set — fall back to legacy default (100K total).
+		numEvents = 100_000;
+		avgEventsPerUserPerDay = numEvents / numUsers / numDays;
+	}
+
+	// Auto-enable batch mode for large datasets to prevent OOM.
+	// MUST run after rate→numEvents resolution above, otherwise dungeons that set
+	// only avgEventsPerUserPerDay would never trigger auto-batch.
+	if (numEvents >= 2_000_000 && config.batchSize === undefined) {
+		batchSize = 1_000_000;
+		console.warn(`⚠️  Auto-enabling batch mode: numEvents (${numEvents.toLocaleString()}) >= 2M. Using batchSize of ${batchSize.toLocaleString()}.`);
+	}
+
+	// Resolve soup presets (intra-week / intra-day shape — must happen after numDays is computed)
 	const resolved = resolveSoup(soup, numDays);
 	soup = resolved.soup;
-	// Apply suggested birth distribution params if not explicitly set by the dungeon
-	if (resolved.suggestedBornRecentBias !== undefined && config.bornRecentBias === undefined) {
-		config.bornRecentBias = resolved.suggestedBornRecentBias;
-	}
-	if (resolved.suggestedPercentUsersBornInDataset !== undefined && config.percentUsersBornInDataset === undefined) {
-		config.percentUsersBornInDataset = resolved.suggestedPercentUsersBornInDataset;
+
+	// Resolve macro preset (big-picture trend shape across the window).
+	// Default is "flat" — see lib/templates/macro-presets.js. Top-level
+	// bornRecentBias / percentUsersBornInDataset / preExistingSpread on the
+	// dungeon config win over the macro preset's values, so existing dungeons
+	// that set these explicitly continue to render the same way.
+	// Resolve into local vars (do NOT mutate input config).
+	const macroResolved = resolveMacro(config.macro);
+	let bornRecentBias = config.bornRecentBias !== undefined ? config.bornRecentBias : macroResolved.bornRecentBias;
+	let percentUsersBornInDataset = config.percentUsersBornInDataset !== undefined ? config.percentUsersBornInDataset : macroResolved.percentUsersBornInDataset;
+	let preExistingSpread = config.preExistingSpread !== undefined ? config.preExistingSpread : macroResolved.preExistingSpread;
+
+	// Clamp bornRecentBias to [-1, 1] — values outside this range produce
+	// nonsensical exponents (e.g. Math.pow(0, -0.4) = Infinity in user-loop.js).
+	if (typeof bornRecentBias === 'number' && Number.isFinite(bornRecentBias)) {
+		bornRecentBias = Math.max(-1, Math.min(1, bornRecentBias));
+	} else {
+		bornRecentBias = 0;
 	}
 
 	// Use provided name if non-empty string, otherwise generate one
@@ -220,7 +270,7 @@ export function validateDungeonConfig(config) {
 	}
 
 	// Validate: if every user is born in dataset, we need either isFirstEvent or isFirstFunnel
-	const percentBorn = config.percentUsersBornInDataset ?? 15;
+	const percentBorn = percentUsersBornInDataset;
 	const hasFirstEvent = events.some(e => e.isFirstEvent);
 	const hasFirstFunnel = funnels.some(f => f.isFirstFunnel);
 	if (percentBorn >= 100 && !hasFirstEvent && !hasFirstFunnel) {
@@ -354,6 +404,7 @@ export function validateDungeonConfig(config) {
 		numEvents,
 		numUsers,
 		numDays,
+		avgEventsPerUserPerDay,
 		epochStart,
 		epochEnd,
 		events: validatedEvents,
@@ -385,6 +436,11 @@ export function validateDungeonConfig(config) {
 		hasIOSDevices,
 		name,
 		strictEventCount,
+		// Macro trend (resolved from preset + per-dungeon overrides; clamped)
+		macro: config.macro,
+		bornRecentBias,
+		percentUsersBornInDataset,
+		preExistingSpread,
 		// Advanced features
 		personas,
 		worldEvents,

package/lib/core/storage.js

@@ -8,7 +8,7 @@
 /** @typedef {import('../../types.js').Storage} Storage */
 /** @typedef {import('../../types.js').hookArrayOptions<any>} hookArrayOptions */
 
-import { existsSync } from "fs";
+import { existsSync, mkdirSync } from "fs";
 import pLimit from 'p-limit';
 import os from "os";
 import path from "path";
@@ -60,8 +60,13 @@ export async function createHookArray(arr = [], opts) {
 		writeDir = path.resolve(os.tmpdir());
 	}
 
-	if (typeof config.writeToDisk === "string" && config.writeToDisk.startsWith('gs://')) {
-		writeDir = config.writeToDisk;
+	if (typeof config.writeToDisk === "string") {
+		if (config.writeToDisk.startsWith('gs://')) {
+			writeDir = config.writeToDisk;
+		} else {
+			writeDir = path.resolve(config.writeToDisk);
+			if (!existsSync(writeDir)) mkdirSync(writeDir, { recursive: true });
+		}
 	}
 
 	function getWritePath() {
@@ -213,7 +218,7 @@ export async function createHookArray(arr = [], opts) {
 			while (isWriting) {
 				await new Promise(resolve => setTimeout(resolve, 10));
 			}
-			
+
 			isWriting = true;
 			try {
 				batch++;
@@ -221,6 +226,11 @@ export async function createHookArray(arr = [], opts) {
 				const dataToWrite = [...arr];
 				arr.length = 0; // Clear array after copying data
 				await FILE_CONN(() => writeToDisk(dataToWrite, { writePath }));
+				// Data now lives on disk, not in arr — mirror what transformThenPush
+				// does when crossing BATCH_SIZE so the Mixpanel sender knows to read
+				// from disk instead of from the (now empty) in-memory array.
+				isBatchMode = true;
+				runtime.isBatchMode = true;
 			} finally {
 				isWriting = false;
 			}

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
@@ -160,7 +165,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
@@ -297,9 +313,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
@@ -480,6 +504,16 @@ export async function userLoop(context) {
 				if (Array.isArray(newEvents)) usersEvents = newEvents;
 			}
 
+			// Defensive guard: drop any events whose timestamp landed past real "now".
+			// Mixpanel rejects future-dated events, and hooks that duplicate events with
+			// time offsets (weekend surges, viral spreads) can otherwise leak a few past
+			// the boundary even after the per-event _drop check in events.js.
+			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.MAX_TIME : true;
+			});
+
 			// Store all user data
 			await userProfilesData.hookPush(profile);
 

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 };
+}