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

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 ──
@@ -16,9 +16,6 @@ import * as v from "ak-tools";
 
 dayjs.extend(utc);
 const chance = u.initChance(SEED);
-const NOW = dayjs();
-const DATASET_START = NOW.subtract(num_days, "days");
-
 /** @typedef  {import("../../types").Dungeon} Config */
 
 const hotelIds = v.range(1, 200).map(() => `HTL_${v.uid(6)}`);
@@ -48,7 +45,16 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
 
 /**
  * ═══════════════════════════════════════════════════════════════
- * ANALYTICS HOOKS (8 hooks)
+ * ANALYTICS HOOKS (10 hooks)
+ *
+ * NOTE: All cohort effects are HIDDEN — no flag stamping. Discoverable via
+ * raw-prop breakdowns (booking_window, day, segment) or behavioral cohorts.
+ *
+ * Adds 9. BOOKING TIME-TO-CONVERT (Business 1.35x faster, Budget 1.25x slower)
+ *      [funnel-post: visible only in Mixpanel funnel median TTC; cross-event
+ *      MIN→MIN SQL queries do NOT show this]
+ * and 10. HOTEL-VIEWED MAGIC NUMBER (sweet 5-10 → +30% nightly_rate;
+ * over 11+ → drop 35% of bookings).
  * ═══════════════════════════════════════════════════════════════
  *
  * ───────────────────────────────────────────────────────────────
@@ -206,8 +212,10 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
 const config = {
 	token,
 	seed: SEED,
-	numDays: num_days,
-	numEvents: num_users * avg_events_per_user,
+	datasetStart: "2026-01-01T00:00:00Z",
+	datasetEnd: "2026-04-28T23:59:59Z",
+	// numDays: num_days,
+	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -222,7 +230,6 @@ const config = {
 	hasCampaigns: false,
 	isAnonymous: false,
 	hasAdSpend: false,
-	percentUsersBornInDataset: 35,
 	hasAvatar: true,
 	concurrency: 1,
 	writeToDisk: false,
@@ -640,36 +647,34 @@ const config = {
 			}
 		}
 
-		// ── HOOK 8: REPEAT DESTINATION CLUSTERING (funnel-pre) ─
-		// conversionRate modifications moved to everything hook (event filtering)
-		// to avoid dilution by organic events
-		if (type === "funnel-pre") {
-			// 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 9 (T2C): BOOKING TIME-TO-CONVERT (funnel-post)
+		// Business travelers complete the Search-to-Book funnel 1.35x faster
+		// (factor 0.74); leisure_family/budget customers 1.25x slower (1.25).
+		if (type === "funnel-post") {
+			const segment = meta?.profile?.customer_segment;
+			if (Array.isArray(record) && record.length > 1) {
+				const factor = (
+					segment === "business_traveler" ? 0.74 :
+					segment === "budget_hunter" || segment === "leisure_family" ? 1.25 :
+					1.0
+				);
+				if (factor !== 1.0) {
+					for (let i = 1; i < record.length; i++) {
+						const prev = dayjs(record[i - 1].time);
+						const newGap = Math.round(dayjs(record[i].time).diff(prev) * factor);
+						record[i].time = prev.add(newGap, "milliseconds").toISOString();
+					}
 				}
 			}
+		}
 
-			// ── 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 1: WEEKEND LEISURE SURGE ────────────
+		// Moved to everything hook (sessionization reassigns times after event hook)
+
+		// ── 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,17 +694,45 @@ 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 ─────
+			const datasetEndForBooking = dayjs.unix(meta.datasetEnd);
+			events.forEach(e => {
+				if (e.event === "booking completed") {
+					const eventTime = dayjs(e.time);
+					const daysUntilEnd = datasetEndForBooking.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
 			// conversion (was conversionRate * 1.3 / 1.15 in funnel-pre)
 			const segment = profile && profile.customer_segment;
-			if (segment !== "business_traveler" && segment !== "luxury_seeker") {
+			if (segment !== "business_traveler" && segment !== "luxury_seeker"
+					&& chance.bool({ likelihood: 25 })) {
 				for (let i = events.length - 1; i >= 0; i--) {
 					if (events[i].event === "booking completed") {
-						if (chance.bool({ likelihood: 25 })) {
-							events.splice(i, 1);
-						}
+						events.splice(i, 1);
 					}
 				}
 			}
@@ -716,7 +749,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 })) {
@@ -743,7 +798,8 @@ const config = {
 				}
 			}
 
-			// ── HOOK 6: REVIEW QUALITY BY STAY RATING ────────
+			// HOOK 6: REVIEW QUALITY BY STAY RATING — high avg ratings get
+			// review_length 1.5x; low avg ratings get 0.5x. Mutates raw prop.
 			let totalRating = 0;
 			let ratingCount = 0;
 			events.forEach(e => {
@@ -763,6 +819,26 @@ const config = {
 				}
 			});
 
+			// HOOK 10: HOTEL-VIEWED MAGIC NUMBER (in-funnel, no flags)
+			// Sweet 5-10 hotel-viewed events → +30% on booking nightly_rate
+			// (decisive comparison shoppers book higher-tier rooms).
+			// Over 11+ → drop 35% of booking-completed events (analysis
+			// paralysis blocks conversion).
+			const hotelViews = events.filter(e => e.event === "hotel viewed").length;
+			if (hotelViews >= 5 && hotelViews <= 10) {
+				events.forEach(e => {
+					if (e.event === "booking completed" && typeof e.nightly_rate === "number") {
+						e.nightly_rate = Math.round(e.nightly_rate * 1.3);
+					}
+				});
+			} else if (hotelViews >= 11) {
+				for (let i = events.length - 1; i >= 0; i--) {
+					if (events[i].event === "booking completed" && chance.bool({ likelihood: 35 })) {
+						events.splice(i, 1);
+					}
+				}
+			}
+
 			return record;
 		}
 

package/index.js

@@ -25,7 +25,7 @@ import { makeMirror } from './lib/generators/mirror.js';
 import { makeGroupProfile, makeProfile } from './lib/generators/profiles.js';
 
 // Utilities
-import { initChance } from './lib/utils/utils.js';
+import { initChance, setDatasetNow } from './lib/utils/utils.js';
 
 // External dependencies
 import dayjs from "dayjs";
@@ -33,12 +33,8 @@ import utc from "dayjs/plugin/utc.js";
 import { timer } from 'ak-tools';
 import { dataLogger as logger } from './lib/utils/logger.js';
 
-// Initialize dayjs and time constants
+// Initialize dayjs (window anchors are now resolved per-config in config-validator)
 dayjs.extend(utc);
-const FIXED_NOW = dayjs('2024-02-02').unix();
-global.FIXED_NOW = FIXED_NOW;
-let FIXED_BEGIN = dayjs.unix(FIXED_NOW).subtract(90, 'd').unix();
-global.FIXED_BEGIN = FIXED_BEGIN;
 
 
 /**
@@ -134,18 +130,21 @@ async function runDungeon(config) {
 			initChance(config.seed);
 		}
 
-		// Step 1: Validate and enrich configuration
+		// Step 1: Validate and enrich configuration (resolves dataset window)
 		validatedConfig = validateDungeonConfig(config);
 
-		// Compute FIXED_BEGIN from validated numDays
-		const configNumDays = validatedConfig.numDays || 30;
-		const fixedBegin = dayjs.unix(FIXED_NOW).subtract(configNumDays, 'd').unix();
+		// validateDungeonConfig always resolves these to unix seconds, but the
+		// public Dungeon type accepts string | number on input. Narrow here.
+		const fixedNow = /** @type {number} */ (validatedConfig.datasetEnd);
+		const fixedBegin = /** @type {number} */ (validatedConfig.datasetStart);
 
-		// Keep globals for backwards compatibility with tests/dungeons that read them
-		global.FIXED_BEGIN = fixedBegin;
+		// Anchor the wall-clock-free reference used by date()/day() helpers in
+		// dungeon configs. Without this, those factories produce values relative
+		// to process-start, which leaks wall-clock time into the output.
+		setDatasetNow(fixedNow);
 
 		// Step 2: Create context with validated config (pass time constants explicitly)
-		const context = createContext(validatedConfig, null, { fixedNow: FIXED_NOW, fixedBegin });
+		const context = createContext(validatedConfig, null, { fixedNow, fixedBegin });
 
 		// Step 3: Initialize storage containers
 		const storageManager = new StorageManager(context);
@@ -237,11 +236,12 @@ async function generateAdSpendData(context) {
 	const { config, storage } = context;
 	const { numDays } = config;
 
-	const timeShift = context.TIME_SHIFT_SECONDS;
 	for (let day = 0; day < numDays; day++) {
-		const fixedDay = dayjs.unix(context.FIXED_BEGIN).add(day, 'day').unix();
-		const shiftedDay = Math.min(fixedDay + timeShift, context.MAX_TIME);
-		const targetDay = dayjs.unix(shiftedDay).toISOString();
+		const dayUnix = Math.min(
+			dayjs.unix(context.FIXED_BEGIN).add(day, 'day').unix(),
+			context.FIXED_NOW
+		);
+		const targetDay = dayjs.unix(dayUnix).toISOString();
 		const adSpendEvents = await makeAdSpend(context, targetDay);
 
 		if (adSpendEvents.length > 0) {

package/lib/core/config-validator.js

@@ -12,9 +12,82 @@ 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();
+/**
+ * Resolve dataset window from config. Returns { datasetStartUnix, datasetEndUnix, numDays }.
+ * Three modes:
+ *   1. Both `datasetStart` AND `datasetEnd` provided → pin window. Recompute numDays from the
+ *      window (ignore any user-supplied numDays — warn on conflict). Bit-exact deterministic.
+ *   2. Neither provided → fall back to (today_start - numDays, today_start). Deterministic
+ *      within a single calendar day; slides across days. Warn once.
+ *   3. Exactly one provided → throw.
+ *
+ * Accepts ISO strings, unix seconds, or anything dayjs() can parse.
+ *
+ * @param {*} datasetStart
+ * @param {*} datasetEnd
+ * @param {number} [userNumDays]
+ * @returns {{ datasetStartUnix: number, datasetEndUnix: number, numDays: number }}
+ */
+function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays) {
+	const hasStart = datasetStart !== undefined && datasetStart !== null;
+	const hasEnd = datasetEnd !== undefined && datasetEnd !== null;
+
+	if (hasStart !== hasEnd) {
+		throw new Error(
+			`datasetStart and datasetEnd must be specified together (got datasetStart=${datasetStart}, datasetEnd=${datasetEnd}). ` +
+			`Provide both to pin the window, or neither to fall back to numDays.`
+		);
+	}
+
+	if (hasStart && hasEnd) {
+		const startUnix = parseToUnix(datasetStart, 'datasetStart');
+		const endUnix = parseToUnix(datasetEnd, 'datasetEnd');
+		if (endUnix <= startUnix) {
+			throw new Error(`datasetEnd (${datasetEnd}) must be after datasetStart (${datasetStart}).`);
+		}
+		const derivedNumDays = Math.max(1, Math.round((endUnix - startUnix) / 86400));
+		if (userNumDays !== undefined && userNumDays !== null && userNumDays !== derivedNumDays) {
+			console.warn(
+				`⚠️  datasetStart/datasetEnd take precedence; user-supplied numDays=${userNumDays} ignored, derived numDays=${derivedNumDays}.`
+			);
+		}
+		return { datasetStartUnix: startUnix, datasetEndUnix: endUnix, numDays: derivedNumDays };
+	}
+
+	// Fallback: anchor to today's start-of-day, walk back numDays
+	const fallbackNumDays = (typeof userNumDays === 'number' && userNumDays > 0) ? userNumDays : 30;
+	const todayStart = dayjs().startOf('day').unix();
+	const fallbackStart = todayStart - fallbackNumDays * 86400;
+	console.warn(
+		`⚠️  No 'datasetStart'/'datasetEnd' set — dataset window anchored to today's date and will shift across runs. Pin both for full determinism.`
+	);
+	return { datasetStartUnix: fallbackStart, datasetEndUnix: todayStart, numDays: fallbackNumDays };
+}
+
+/**
+ * Parse a value (ISO string, unix seconds, dayjs-parseable) into unix seconds.
+ * Throws if the value can't be parsed into a valid date.
+ * @param {*} value
+ * @param {string} fieldName
+ * @returns {number}
+ */
+function parseToUnix(value, fieldName) {
+	// Treat numbers as unix seconds (or unix milliseconds if too large)
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value) || value <= 0) {
+			throw new Error(`${fieldName} must be a positive finite number (got ${value}).`);
+		}
+		// Heuristic: > 10^12 means milliseconds, otherwise seconds
+		return value > 1e12 ? Math.floor(value / 1000) : Math.floor(value);
+	}
+	const parsed = dayjs(value);
+	if (!parsed.isValid()) {
+		throw new Error(`${fieldName} could not be parsed as a date (got ${JSON.stringify(value)}).`);
+	}
+	return parsed.unix();
+}
 
 /**
  * Infers funnels from the provided events
@@ -87,9 +160,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,35 +222,83 @@ 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) };
 	}
 
-	// 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();
-	if (epochStart && numDays) { } // noop
-	if (!epochStart && !numDays) {
-		throw new Error("Either epochStart or numDays must be provided");
+	// 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})`);
+	}
+
+	// ── Resolve dataset window ──
+	// Preferred path: explicit datasetStart + datasetEnd → pinned, deterministic window.
+	// Fallback: numDays only → today_start - numDays back (sliding, warn-emitted).
+	const windowResolution = resolveDatasetWindow(config.datasetStart, config.datasetEnd, config.numDays);
+	const datasetStartUnix = windowResolution.datasetStartUnix;
+	const datasetEndUnix = windowResolution.datasetEndUnix;
+	numDays = windowResolution.numDays;
+
+	// Mirror window into legacy epoch* surface (still consumed by inferFunnels callers
+	// and any external code that read these from validated config).
+	epochStart = datasetStartUnix;
+	epochEnd = datasetEndUnix;
+
+	// 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 (must happen after numDays is computed)
+	// 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 +342,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) {
@@ -299,7 +421,7 @@ export function validateDungeonConfig(config) {
 	// Feature 2: World Events
 	let worldEvents = config.worldEvents || null;
 	if (worldEvents) {
-		worldEvents = resolveWorldEvents(worldEvents, numDays);
+		worldEvents = resolveWorldEvents(worldEvents, datasetStartUnix);
 	}
 
 	// Feature 3: Engagement Decay
@@ -341,7 +463,7 @@ export function validateDungeonConfig(config) {
 	// Feature 9: Anomalies
 	let anomalies = config.anomalies || null;
 	if (anomalies) {
-		anomalies = resolveAnomalies(anomalies, numDays);
+		anomalies = resolveAnomalies(anomalies, datasetStartUnix);
 	}
 
 	// Build final config object
@@ -354,8 +476,11 @@ export function validateDungeonConfig(config) {
 		numEvents,
 		numUsers,
 		numDays,
+		avgEventsPerUserPerDay,
 		epochStart,
 		epochEnd,
+		datasetStart: datasetStartUnix,
+		datasetEnd: datasetEndUnix,
 		events: validatedEvents,
 		superProps,
 		userProps,
@@ -385,6 +510,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,
@@ -495,12 +625,11 @@ function validatePersonas(personas) {
 /**
  * Resolves world events to absolute timestamps
  * @param {import('../../types').WorldEvent[]} worldEvents
- * @param {number} numDays
+ * @param {number} beginUnix - Dataset start (unix seconds)
  * @returns {import('../../types').ResolvedWorldEvent[]}
  */
-function resolveWorldEvents(worldEvents, numDays) {
+function resolveWorldEvents(worldEvents, beginUnix) {
 	if (!Array.isArray(worldEvents) || worldEvents.length === 0) return null;
-	const beginUnix = dayjs.unix(FIXED_NOW).subtract(numDays, 'day').unix();
 
 	return worldEvents.map(we => {
 		const startUnix = beginUnix + (we.startDay * 86400);
@@ -664,12 +793,11 @@ function resolveFeatures(features, numDays) {
 /**
  * Resolves anomaly configs with absolute timestamps
  * @param {import('../../types').AnomalyConfig[]} anomalies
- * @param {number} numDays
+ * @param {number} beginUnix - Dataset start (unix seconds)
  * @returns {import('../../types').AnomalyConfig[]}
  */
-function resolveAnomalies(anomalies, numDays) {
+function resolveAnomalies(anomalies, beginUnix) {
 	if (!Array.isArray(anomalies) || anomalies.length === 0) return null;
-	const beginUnix = dayjs.unix(FIXED_NOW).subtract(numDays, 'day').unix();
 	return anomalies.map(a => {
 		if (!a.type) throw new Error('Each anomaly must have a type');
 		if (!a.event) throw new Error('Each anomaly must have an event name');

package/lib/core/context.js

@@ -156,30 +156,16 @@ export function createContext(config, storage = null, timeConstants = {}) {
 			return runtime.isBatchMode;
 		},
 
-		// Time helper methods
-		getTimeShift() {
-			const actualNow = dayjs().subtract(1, "hour");
-			return actualNow.diff(dayjs.unix(this.FIXED_NOW), "seconds");
-		},
-
-		getDaysShift() {
-			const actualNow = dayjs().subtract(1, "hour");
-			return actualNow.diff(dayjs.unix(this.FIXED_NOW), "days");
-		},
-
-		// Time constants (passed explicitly from index.js; global fallback only for direct test usage)
-		FIXED_NOW: timeConstants.fixedNow || global.FIXED_NOW,
-		FIXED_BEGIN: timeConstants.fixedBegin || global.FIXED_BEGIN,
-
-		// PERFORMANCE: Pre-calculated time shift (instead of calculating per-event)
-		TIME_SHIFT_SECONDS: (() => {
-			const fixedNow = timeConstants.fixedNow || global.FIXED_NOW;
-			const actualNow = dayjs().subtract(1, "hour");
-			return actualNow.diff(dayjs.unix(fixedNow), "seconds");
-		})(),
-
-		// Max timestamp (unix seconds) — clamp here to prevent future events
-		MAX_TIME: dayjs().unix(),
+		// Dataset window anchors (resolved by config-validator). FIXED_BEGIN and
+		// FIXED_NOW are the authoritative window — events are generated directly
+		// inside this range, no time-shift step. DATASET_*_SECONDS are aliases
+		// kept for the existing `meta.datasetStart`/`meta.datasetEnd` hook surface.
+		// Resolution: explicit timeConstants override, otherwise pull from validated config.
+		// validateDungeonConfig always normalizes datasetStart/datasetEnd to unix seconds.
+		FIXED_NOW: /** @type {number} */ (timeConstants.fixedNow || config.datasetEnd),
+		FIXED_BEGIN: /** @type {number} */ (timeConstants.fixedBegin || config.datasetStart),
+		get DATASET_START_SECONDS() { return this.FIXED_BEGIN; },
+		get DATASET_END_SECONDS() { return this.FIXED_NOW; },
 	};
 
 	return context;

package/lib/core/storage.js

@@ -111,7 +111,12 @@ export async function createHookArray(arr = [], opts) {
 			}
 		} else {
 			// Slow path for actual transformation hooks
-			const allMetaData = { ...rest, ...meta };
+			const allMetaData = {
+				...rest,
+				...meta,
+				datasetStart: context?.DATASET_START_SECONDS,
+				datasetEnd: context?.DATASET_END_SECONDS
+			};
 
 			// Helper to validate events have required properties
 			// Note: event-type hooks are handled in the fast path (alreadyHooked),