@ak--47/dungeon-master 1.0.0 → 1.1.0

package/index.js

@@ -61,15 +61,15 @@ global.FIXED_BEGIN = FIXED_BEGIN;
  *
  * @example
  * // file path
- * const result = await DUNGEON_MASTER('./dungeons/simple.js');
+ * const result = await DUNGEON_MASTER('./dungeons/technical/simple.js');
  *
  * @example
  * // JSON dungeon (from UI export)
- * const result = await DUNGEON_MASTER('./dungeons/simple-schema.json');
+ * const result = await DUNGEON_MASTER('./dungeons/technical/simple-schema.json');
  *
  * @example
  * // multiple dungeons
- * const results = await DUNGEON_MASTER(['./dungeons/gaming.js', './dungeons/media.js']);
+ * const results = await DUNGEON_MASTER(['./dungeons/vertical/gaming.js', './dungeons/vertical/media.js']);
  *
  * @example
  * // raw JS text
@@ -83,7 +83,7 @@ global.FIXED_BEGIN = FIXED_BEGIN;
  *
  * @example
  * // with overrides
- * const result = await DUNGEON_MASTER('./dungeons/simple.js', { writeToDisk: true, verbose: true });
+ * const result = await DUNGEON_MASTER('./dungeons/technical/simple.js', { writeToDisk: true, verbose: true });
  */
 async function DUNGEON_MASTER(input, overrides = {}) {
 	const { type, value } = detectInputType(input);
@@ -124,21 +124,25 @@ async function runDungeon(config) {
 	if (config.verbose) logger.info({ seed: config.seed }, 'Configuring dungeon');
 	let validatedConfig;
 	try {
+		// Initialize seeded RNG BEFORE validation — config-validator captures a
+		// chance reference for default userProps (spiritAnimal). If we init after,
+		// run 1 binds an unseeded instance while run 2 binds a stale one → non-deterministic.
+		if (config.seed) {
+			initChance(config.seed);
+		}
+
 		// Step 1: Validate and enrich configuration
 		validatedConfig = validateDungeonConfig(config);
 
-		// Ensure seeded RNG is initialized (dungeons do this at module scope,
-		// but npm-module consumers pass seed via config object)
-		if (validatedConfig.seed) {
-			initChance(validatedConfig.seed);
-		}
-
-		// Update FIXED_BEGIN based on configured numDays
+		// Compute FIXED_BEGIN from validated numDays
 		const configNumDays = validatedConfig.numDays || 30;
-		global.FIXED_BEGIN = dayjs.unix(FIXED_NOW).subtract(configNumDays, 'd').unix();
+		const fixedBegin = dayjs.unix(FIXED_NOW).subtract(configNumDays, 'd').unix();
+
+		// Keep globals for backwards compatibility with tests/dungeons that read them
+		global.FIXED_BEGIN = fixedBegin;
 
-		// Step 2: Create context with validated config
-		const context = createContext(validatedConfig);
+		// Step 2: Create context with validated config (pass time constants explicitly)
+		const context = createContext(validatedConfig, null, { fixedNow: FIXED_NOW, fixedBegin });
 
 		// Step 3: Initialize storage containers
 		const storageManager = new StorageManager(context);
@@ -232,7 +236,7 @@ async function generateAdSpendData(context) {
 
 	const timeShift = context.TIME_SHIFT_SECONDS;
 	for (let day = 0; day < numDays; day++) {
-		const fixedDay = dayjs.unix(global.FIXED_BEGIN).add(day, 'day').unix();
+		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 adSpendEvents = await makeAdSpend(context, targetDay);

package/lib/core/config-validator.js

@@ -13,6 +13,9 @@ import { makeName } from "ak-tools";
 import * as u from "../utils/utils.js";
 import { resolveSoup } from "../templates/soup-presets.js";
 
+/** Fixed reference point for time calculations (2024-02-02) */
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
 /**
  * Infers funnels from the provided events
  * @param {EventConfig[]} events - Array of event configurations
@@ -275,6 +278,62 @@ export function validateDungeonConfig(config) {
 	// Event validation 
 	const validatedEvents = u.validateEventConfig(events);
 
+	// ── Validate and resolve advanced features ──
+
+	// Feature 1: Personas
+	let personas = config.personas || null;
+	if (personas) {
+		personas = validatePersonas(personas);
+	}
+
+	// Feature 2: World Events
+	let worldEvents = config.worldEvents || null;
+	if (worldEvents) {
+		worldEvents = resolveWorldEvents(worldEvents, numDays);
+	}
+
+	// Feature 3: Engagement Decay
+	let engagementDecay = config.engagementDecay || null;
+	if (engagementDecay) {
+		engagementDecay = validateEngagementDecay(engagementDecay);
+	}
+
+	// Feature 4: Data Quality
+	let dataQuality = config.dataQuality || null;
+	if (dataQuality) {
+		dataQuality = validateDataQuality(dataQuality);
+	}
+
+	// Feature 5: Subscription
+	let subscription = config.subscription || null;
+	if (subscription) {
+		subscription = validateSubscription(subscription);
+	}
+
+	// Feature 6: Attribution
+	let attribution = config.attribution || null;
+	if (attribution) {
+		attribution = validateAttribution(attribution, numDays);
+	}
+
+	// Feature 7: Geo
+	let geo = config.geo || null;
+	if (geo) {
+		geo = validateGeo(geo);
+	}
+
+	// Feature 8: Features (progressive adoption)
+	let features = config.features || null;
+	if (features) {
+		features = resolveFeatures(features, numDays);
+	}
+
+	// Feature 9: Anomalies
+	let anomalies = config.anomalies || null;
+	if (anomalies) {
+		anomalies = resolveAnomalies(anomalies, numDays);
+	}
+
 	// Build final config object
 	const validatedConfig = {
 		...config,
@@ -314,7 +373,17 @@ export function validateDungeonConfig(config) {
 		hasDesktopDevices,
 		hasIOSDevices,
 		name,
-		strictEventCount
+		strictEventCount,
+		// Advanced features
+		personas,
+		worldEvents,
+		engagementDecay,
+		dataQuality,
+		subscription,
+		attribution,
+		geo,
+		features,
+		anomalies
 	};
 
 	return validatedConfig;
@@ -392,4 +461,220 @@ function transformSCDPropsWithoutCredentials(config) {
 	if (config.verbose !== false) console.log('\u2713 SCD properties converted to static properties\n');
 }
 
+// ── Advanced Feature Validation Functions ──
+
+/**
+ * Validates persona configurations
+ * @param {import('../../types').Persona[]} personas
+ * @returns {import('../../types').Persona[]}
+ */
+function validatePersonas(personas) {
+	if (!Array.isArray(personas) || personas.length === 0) return null;
+	for (const p of personas) {
+		if (!p.name) throw new Error('Each persona must have a name');
+		if (typeof p.weight !== 'number' || p.weight <= 0) throw new Error(`Persona "${p.name}" must have a positive weight`);
+		if (p.eventMultiplier === undefined) p.eventMultiplier = 1.0;
+		if (p.conversionModifier === undefined) p.conversionModifier = 1.0;
+		if (p.churnRate === undefined) p.churnRate = 0;
+		if (p.properties === undefined) p.properties = {};
+	}
+	return personas;
+}
+
+/**
+ * Resolves world events to absolute timestamps
+ * @param {import('../../types').WorldEvent[]} worldEvents
+ * @param {number} numDays
+ * @returns {import('../../types').ResolvedWorldEvent[]}
+ */
+function resolveWorldEvents(worldEvents, numDays) {
+	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);
+		let endUnix;
+		if (we.duration === null || we.duration === undefined) {
+			endUnix = Infinity; // permanent
+		} else {
+			endUnix = startUnix + (we.duration * 86400);
+		}
+		const aftermathEndUnix = (we.aftermath && we.aftermath.duration !== undefined)
+			? endUnix + (we.aftermath.duration * 86400)
+			: undefined;
+		const resolved = { ...we, startUnix, endUnix, aftermathEndUnix };
+		if (!we.affectsEvents) resolved.affectsEvents = "*";
+		if (!we.volumeMultiplier) resolved.volumeMultiplier = 1.0;
+		if (!we.conversionModifier) resolved.conversionModifier = 1.0;
+		return resolved;
+	}).sort((a, b) => a.startUnix - b.startUnix || (a.name || '').localeCompare(b.name || ''));
+}
+
+/**
+ * Validates engagement decay config
+ * @param {import('../../types').EngagementDecay} decay
+ * @returns {import('../../types').EngagementDecay}
+ */
+function validateEngagementDecay(decay) {
+	const valid = ['exponential', 'linear', 'step', 'none'];
+	if (!valid.includes(decay.model)) throw new Error(`engagementDecay.model must be one of: ${valid.join(', ')}`);
+	if (decay.model === 'none') return decay;
+	if (decay.halfLife === undefined) decay.halfLife = 45;
+	if (decay.halfLife <= 0) throw new Error('engagementDecay.halfLife must be > 0');
+	if (decay.floor === undefined) decay.floor = 0.1;
+	decay.floor = Math.max(0, Math.min(1, decay.floor));
+	if (decay.reactivationChance === undefined) decay.reactivationChance = 0;
+	if (decay.reactivationMultiplier === undefined) decay.reactivationMultiplier = 2.0;
+	return decay;
+}
+
+/**
+ * Validates data quality config
+ * @param {import('../../types').DataQuality} dq
+ * @returns {import('../../types').DataQuality}
+ */
+function validateDataQuality(dq) {
+	if (dq.nullRate === undefined) dq.nullRate = 0;
+	if (dq.duplicateRate === undefined) dq.duplicateRate = 0;
+	if (dq.lateArrivingRate === undefined) dq.lateArrivingRate = 0;
+	if (dq.botUsers === undefined) dq.botUsers = 0;
+	if (dq.botEventsPerUser === undefined) dq.botEventsPerUser = 1000;
+	if (dq.timezoneConfusion === undefined) dq.timezoneConfusion = 0;
+	if (dq.emptyEvents === undefined) dq.emptyEvents = 0;
+	if (!dq.nullProps) dq.nullProps = "*";
+	// Clamp rates to [0, 1]
+	for (const key of ['nullRate', 'duplicateRate', 'lateArrivingRate', 'timezoneConfusion', 'emptyEvents']) {
+		dq[key] = Math.max(0, Math.min(1, dq[key]));
+	}
+	return dq;
+}
+
+/**
+ * Validates subscription config
+ * @param {import('../../types').Subscription} sub
+ * @returns {import('../../types').Subscription}
+ */
+function validateSubscription(sub) {
+	if (!sub.plans || !Array.isArray(sub.plans) || sub.plans.length === 0) {
+		throw new Error('subscription.plans must be a non-empty array');
+	}
+	const hasDefault = sub.plans.some(p => p.default);
+	if (!hasDefault) sub.plans[0].default = true;
+	if (!sub.lifecycle) sub.lifecycle = {};
+	const lc = sub.lifecycle;
+	if (lc.trialToPayRate === undefined) lc.trialToPayRate = 0.3;
+	if (lc.upgradeRate === undefined) lc.upgradeRate = 0.1;
+	if (lc.downgradeRate === undefined) lc.downgradeRate = 0.03;
+	if (lc.churnRate === undefined) lc.churnRate = 0.05;
+	if (lc.winBackRate === undefined) lc.winBackRate = 0.1;
+	if (lc.winBackDelay === undefined) lc.winBackDelay = 30;
+	if (lc.paymentFailureRate === undefined) lc.paymentFailureRate = 0.02;
+	if (!sub.events) sub.events = {};
+	const ev = sub.events;
+	if (!ev.trialStarted) ev.trialStarted = "trial started";
+	if (!ev.subscribed) ev.subscribed = "subscription started";
+	if (!ev.upgraded) ev.upgraded = "plan upgraded";
+	if (!ev.downgraded) ev.downgraded = "plan downgraded";
+	if (!ev.renewed) ev.renewed = "subscription renewed";
+	if (!ev.cancelled) ev.cancelled = "subscription cancelled";
+	if (!ev.paymentFailed) ev.paymentFailed = "payment failed";
+	if (!ev.wonBack) ev.wonBack = "subscription reactivated";
+	return sub;
+}
+
+/**
+ * Validates attribution config
+ * @param {import('../../types').Attribution} attr
+ * @param {number} numDays
+ * @returns {import('../../types').Attribution}
+ */
+function validateAttribution(attr, numDays) {
+	if (!attr.campaigns || !Array.isArray(attr.campaigns)) {
+		throw new Error('attribution.campaigns must be an array');
+	}
+	if (attr.model === undefined) attr.model = "last_touch";
+	if (attr.window === undefined) attr.window = 7;
+	if (attr.organicRate === undefined) attr.organicRate = 0.4;
+	for (const c of attr.campaigns) {
+		if (!c.name) throw new Error('Each attribution campaign must have a name');
+		if (!c.source) throw new Error(`Attribution campaign "${c.name}" must have a source`);
+		if (!c.activeDays) throw new Error(`Attribution campaign "${c.name}" must have activeDays [start, end]`);
+		if (!c.dailyBudget) c.dailyBudget = [50, 200];
+		if (c.acquisitionRate === undefined) c.acquisitionRate = 0.02;
+	}
+	return attr;
+}
+
+/**
+ * Validates geo config
+ * @param {import('../../types').GeoConfig} geo
+ * @returns {import('../../types').GeoConfig}
+ */
+function validateGeo(geo) {
+	if (geo.sticky === undefined) geo.sticky = false;
+	if (geo.regions && !Array.isArray(geo.regions)) throw new Error('geo.regions must be an array');
+	if (geo.regionalLaunches && !Array.isArray(geo.regionalLaunches)) throw new Error('geo.regionalLaunches must be an array');
+	return geo;
+}
+
+/**
+ * Resolves feature configs with logistic curve parameters
+ * @param {import('../../types').FeatureConfig[]} features
+ * @param {number} numDays
+ * @returns {import('../../types').FeatureConfig[]}
+ */
+function resolveFeatures(features, numDays) {
+	if (!Array.isArray(features) || features.length === 0) return null;
+	const curvePresets = {
+		fast: { k: 0.3, midpoint: 7 },
+		slow: { k: 0.08, midpoint: 30 },
+		instant: { k: 10, midpoint: 0 }
+	};
+	return features.map(f => {
+		if (!f.name) throw new Error('Each feature must have a name');
+		if (f.launchDay === undefined) throw new Error(`Feature "${f.name}" must have a launchDay`);
+		if (!f.property) throw new Error(`Feature "${f.name}" must have a property`);
+		if (!f.values || !Array.isArray(f.values) || f.values.length === 0) {
+			throw new Error(`Feature "${f.name}" must have a non-empty values array`);
+		}
+		if (!f.affectsEvents) f.affectsEvents = "*";
+		if (!f.adoptionCurve) f.adoptionCurve = "slow";
+		if (typeof f.adoptionCurve === 'string') {
+			f._resolvedCurve = curvePresets[f.adoptionCurve] || curvePresets.slow;
+		} else {
+			f._resolvedCurve = f.adoptionCurve;
+		}
+		// Pre-compute adopted values to avoid array allocation in hot loop
+		f._adoptedValues = f.values.length > 1 ? f.values.slice(1) : f.values;
+		return f;
+	});
+}
+
+/**
+ * Resolves anomaly configs with absolute timestamps
+ * @param {import('../../types').AnomalyConfig[]} anomalies
+ * @param {number} numDays
+ * @returns {import('../../types').AnomalyConfig[]}
+ */
+function resolveAnomalies(anomalies, numDays) {
+	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');
+		const resolved = { ...a };
+		if (a.day !== undefined) {
+			resolved._startUnix = beginUnix + (a.day * 86400);
+			if (a.duration) {
+				resolved._endUnix = resolved._startUnix + (a.duration * 86400);
+			} else if (a.window) {
+				resolved._endUnix = resolved._startUnix + (a.window * 86400);
+			} else {
+				resolved._endUnix = resolved._startUnix + 86400; // default 1 day
+			}
+		}
+		return resolved;
+	});
+}
+
 export { inferFunnels, transformSCDPropsWithoutCredentials };

package/lib/core/context.js

@@ -81,9 +81,10 @@ function createRuntimeState() {
  * Context factory that creates a complete context object for data generation
  * @param {Dungeon} config - Validated configuration object
  * @param {Storage|null} storage - Storage containers (optional, can be set later)
+ * @param {{ fixedNow?: number, fixedBegin?: number }} [timeConstants] - Time constants (avoids globals)
  * @returns {Context} Context object containing all state and dependencies
  */
-export function createContext(config, storage = null) {
+export function createContext(config, storage = null, timeConstants = {}) {
 	// Import campaign data (could be made configurable)
 	const campaignData = campaigns;
 
@@ -157,14 +158,15 @@ export function createContext(config, storage = null) {
 			return actualNow.diff(dayjs.unix(this.FIXED_NOW), "days");
 		},
 
-		// Time constants (previously globals)
-		FIXED_NOW: global.FIXED_NOW,
-		FIXED_BEGIN: global.FIXED_BEGIN,
+		// 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(global.FIXED_NOW), "seconds");
+			return actualNow.diff(dayjs.unix(fixedNow), "seconds");
 		})(),
 
 		// Max timestamp (unix seconds) — clamp here to prevent future events

package/lib/generators/adspend.js

@@ -67,9 +67,9 @@ function createAdSpendEvent(network, campaign, day, chance) {
     const views = Math.floor(impressions * avgCTR);
 
     // Generate UTM parameters
-    const utm_medium = u.choose(u.pickAWinner(network.utm_medium)());
-    const utm_content = u.choose(u.pickAWinner(network.utm_content)());
-    const utm_term = u.choose(u.pickAWinner(network.utm_term)());
+    const utm_medium = u.choose(network.utm_medium);
+    const utm_content = u.choose(network.utm_content);
+    const utm_term = u.choose(network.utm_term);
 
     // Create unique identifiers
     const id = network.utm_source[0] + '-' + campaign;

package/lib/generators/events.js

@@ -13,6 +13,9 @@ import dayjs from "dayjs";
 import * as u from "../utils/utils.js";
 import { dataLogger as logger } from "../utils/logger.js";
 
+// Keys that must never be nulled by data quality gremlins
+const NULL_EXEMPT_KEYS = new Set(['event', 'time', 'insert_id', 'user_id', 'device_id', 'distinct_id', '_drop', '_anomaly', '_persona']);
+
 /**
  * Creates a Mixpanel event with a flat shape
  * @param {Context} context - Context object containing config, defaults, etc.
@@ -28,16 +31,17 @@ import { dataLogger as logger } from "../utils/logger.js";
  * @returns {Promise<Object>} Generated event object
  */
 export async function makeEvent(
-    context, 
-    distinct_id, 
-    earliestTime, 
-    chosenEvent, 
-    anonymousIds = [], 
-    sessionIds = [], 
-    superProps = {}, 
-    groupKeys = [], 
-    isFirstEvent = false, 
-    skipDefaults = false
+    context,
+    distinct_id,
+    earliestTime,
+    chosenEvent,
+    anonymousIds = [],
+    sessionIds = [],
+    superProps = {},
+    groupKeys = [],
+    isFirstEvent = false,
+    skipDefaults = false,
+    featureCtx = {}
 ) {
     // Validate required parameters
     if (!distinct_id) throw new Error("no distinct_id");
@@ -168,17 +172,140 @@ export async function makeEvent(
     // Add group properties
     addGroupProperties(eventTemplate, groupKeys);
 
+    // ── Event-level features (applied before hooks, so hooks can override) ──
+    const { userLocation, persona, worldEventsTimeline, resolvedFeatures, resolvedAnomalies, dataQuality: dq, geo: geoConfig, userCampaign } = featureCtx;
+
+    // Feature 6: Attribution — stamp UTM properties on events as touchpoints
+    // Mixpanel attribution analysis needs UTM on EVENTS, not just profiles.
+    // Pattern: first events carry acquisition UTM, later events occasionally carry re-engagement UTM.
+    if (userCampaign) {
+        // ~40% of events carry UTM (simulates page loads, session starts, ad clicks)
+        // First events (isFirstEvent) always carry UTM (acquisition touchpoint)
+        if (isFirstEvent || chance.bool({ likelihood: 40 })) {
+            eventTemplate.utm_source = userCampaign.source;
+            eventTemplate.utm_campaign = userCampaign.name;
+            if (userCampaign.medium) eventTemplate.utm_medium = userCampaign.medium;
+            if (userCampaign.utm_content) eventTemplate.utm_content = userCampaign.utm_content;
+            if (userCampaign.utm_term) eventTemplate.utm_term = userCampaign.utm_term;
+        }
+    }
+
+    // Feature 7: Sticky geo location
+    if (userLocation && geoConfig?.sticky) {
+        // Override the random location with user's sticky location
+        for (const key in userLocation) {
+            eventTemplate[key] = userLocation[key];
+        }
+    }
+
+    // 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)
+    let eventUnix = null;
+    if ((worldEventsTimeline || resolvedFeatures) && eventTemplate.time) {
+        eventUnix = dayjs(eventTemplate.time).subtract(context.TIME_SHIFT_SECONDS, 'seconds').unix();
+    }
+
+    // Feature 2: World events — inject props for active events at this timestamp
+    if (worldEventsTimeline && eventUnix !== null) {
+        for (const we of worldEventsTimeline) {
+            const inMainWindow = eventUnix >= we.startUnix && eventUnix < we.endUnix;
+            const inAftermath = we.aftermathEndUnix && eventUnix >= we.endUnix && eventUnix < we.aftermathEndUnix;
+            if (inMainWindow || inAftermath) {
+                const affects = we.affectsEvents;
+                if (affects === "*" || (Array.isArray(affects) && affects.includes(eventTemplate.event))) {
+                    // Inject properties
+                    if (we.injectProps && inMainWindow) {
+                        for (const [k, v] of Object.entries(we.injectProps)) {
+                            eventTemplate[k] = v;
+                        }
+                    }
+                    // Volume modulation via accept/reject: if volumeMultiplier < 1, randomly drop
+                    const volMult = inAftermath ? (we.aftermath?.volumeMultiplier || 1.0) : we.volumeMultiplier;
+                    if (volMult < 1.0 && !chance.bool({ likelihood: volMult * 100 })) {
+                        eventTemplate._drop = true;
+                    }
+                }
+            }
+        }
+    }
+
+    // Feature 8: Progressive feature adoption
+    if (resolvedFeatures && eventUnix !== null) {
+        const daysSinceBegin = (eventUnix - context.FIXED_BEGIN) / 86400;
+        for (const feat of resolvedFeatures) {
+            const affects = feat.affectsEvents;
+            if (affects !== "*" && !(Array.isArray(affects) && affects.includes(eventTemplate.event))) continue;
+            if (daysSinceBegin < feat.launchDay) {
+                if (feat.defaultBefore !== undefined) {
+                    eventTemplate[feat.property] = feat.defaultBefore;
+                }
+            } else {
+                const daysSinceLaunch = daysSinceBegin - feat.launchDay;
+                const { k, midpoint } = feat._resolvedCurve || { k: 0.08, midpoint: 30 };
+                const adoptionProb = 1 / (1 + Math.exp(-k * (daysSinceLaunch - midpoint)));
+                if (chance.bool({ likelihood: Math.min(100, adoptionProb * 100) })) {
+                    eventTemplate[feat.property] = u.pickRandom(feat._adoptedValues);
+                } else if (feat.defaultBefore !== undefined) {
+                    eventTemplate[feat.property] = feat.defaultBefore;
+                } else if (feat.values.length > 0) {
+                    eventTemplate[feat.property] = feat.values[0];
+                }
+            }
+        }
+    }
+
+    // Feature 9: Anomaly extreme values
+    if (resolvedAnomalies && eventTemplate.event) {
+        for (const a of resolvedAnomalies) {
+            if (a.type === 'extreme_value' && a.event === eventTemplate.event && a.property) {
+                if (chance.bool({ likelihood: (a.frequency ?? 0.001) * 100 })) {
+                    const currentVal = eventTemplate[a.property];
+                    if (typeof currentVal === 'number') {
+                        eventTemplate[a.property] = currentVal * (a.multiplier || 10);
+                    }
+                    if (a.tag) eventTemplate._anomaly = a.tag;
+                    if (a.properties) Object.assign(eventTemplate, a.properties);
+                }
+            }
+        }
+    }
+
+    // Feature 4: Data quality — null injection and timezone confusion
+    if (dq) {
+        // Null injection
+        if (dq.nullRate > 0) {
+            const propsToNull = dq.nullProps === "*"
+                ? Object.keys(eventTemplate).filter(k => !NULL_EXEMPT_KEYS.has(k))
+                : (Array.isArray(dq.nullProps) ? dq.nullProps : []);
+            for (const prop of propsToNull) {
+                if (eventTemplate[prop] !== undefined && chance.bool({ likelihood: dq.nullRate * 100 })) {
+                    eventTemplate[prop] = null;
+                }
+            }
+        }
+        // Timezone confusion
+        if (dq.timezoneConfusion > 0 && chance.bool({ likelihood: dq.timezoneConfusion * 100 })) {
+            const offsetHours = chance.integer({ min: -12, max: 12 });
+            eventTemplate.time = dayjs(eventTemplate.time).add(offsetHours, 'hours').toISOString();
+        }
+        // Empty events
+        if (dq.emptyEvents > 0 && chance.bool({ likelihood: dq.emptyEvents * 100 })) {
+            eventTemplate.event = "";
+        }
+    }
+
     // Generate unique insert_id
 	const distinctId = eventTemplate.user_id || eventTemplate.device_id || eventTemplate.distinct_id || distinct_id;
 	const tuple = `${eventTemplate.event}-${eventTemplate.time}-${distinctId}`;
     eventTemplate.insert_id = u.quickHash(tuple);
 
-    // Call hook if configured (before returning the event)
+    // Call hook if configured (hooks override everything — they are the final authority)
     const { hook } = config;
     if (hook) {
-        const hookedEvent = await hook(eventTemplate, "event", { 
-            user: { distinct_id }, 
-            config 
+        const hookedEvent = await hook(eventTemplate, "event", {
+            user: { distinct_id },
+            config,
+            persona: featureCtx.persona || null
         });
         // If hook returns a modified event, use it; otherwise use original
         if (hookedEvent && typeof hookedEvent === 'object') {