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

package/dungeons/vertical/social.js

@@ -1,7 +1,7 @@
 // ── TWEAK THESE ──
 const SEED = "harness-social";
-const num_days = 100;
-const num_users = 5_000;
+const num_days = 120;
+const num_users = 10_000;
 const avg_events_per_user_per_day = 1.2;
 let token = "your-mixpanel-token";
 
@@ -107,7 +107,7 @@ const chance = u.initChance(SEED);
  * receive follow-backs and post more frequently.
  *
  * -------------------------------------------------------------------------------------
- * 3. ALGORITHM CHANGE (event)
+ * 3. ALGORITHM CHANGE (everything)
  * -------------------------------------------------------------------------------------
  *
  * PATTERN: On day 45, the dominant `source` for "post viewed" flips from
@@ -146,7 +146,7 @@ const chance = u.initChance(SEED);
  * quality is awful, dragging down avg watch time.
  *
  * -------------------------------------------------------------------------------------
- * 5. NOTIFICATION RE-ENGAGEMENT (event)
+ * 5. NOTIFICATION RE-ENGAGEMENT (everything)
  * -------------------------------------------------------------------------------------
  *
  * PATTERN: After day 30, 30% of "post viewed" events have source flipped
@@ -190,14 +190,14 @@ const chance = u.initChance(SEED);
  * 7. TOXICITY CHURN (everything)
  * -------------------------------------------------------------------------------------
  *
- * PATTERN: Users with 3+ "report submitted" events lose 60% of activity
+ * PATTERN: Users with 2+ "report submitted" events lose 60% of activity
  * after day 30. No flag — discover via retention or per-user activity drop.
  *
  * HOW TO FIND IT IN MIXPANEL:
  *
  *   Report 1: Retention by Toxicity
  *   - Report type: Retention
- *   - Cohort A: users with >= 3 "report submitted"
+ *   - Cohort A: users with >= 2 "report submitted"
  *   - Cohort B: rest
  *   - Expected: A ~ 40% retention vs B ~ 80%
  *
@@ -276,15 +276,17 @@ const postIds = v.range(1, 1001).map(n => `post_${v.uid(8)}`);
 
 /** @type {Config} */
 const config = {
+	version: 2,
 	token,
 	seed: SEED,
 	datasetStart: "2026-01-01T00:00:00Z",
-	datasetEnd: "2026-04-28T23:59:59Z",
+	datasetEnd: "2026-05-01T23:59:59Z",
 	soup: { dayOfWeekWeights: [1.0, 1.0, 1.0, 1.0, 1.0, 1.2, 1.2] },
 	// numDays: num_days,
 	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
-	hasAnonIds: false,
+	hasAnonIds: true,
+	avgDevicePerUser: 2,
 	hasSessionIds: true,
 	format: "json",
 	gzip: true,
@@ -379,6 +381,7 @@ const config = {
 			event: "account created",
 			weight: 1,
 			isFirstEvent: true,
+			isAuthEvent: true,
 			properties: {
 				"signup_method": ["email", "google", "apple", "sso"],
 				"referred_by": ["organic", "friend", "ad", "influencer"],
@@ -576,43 +579,6 @@ const config = {
 		}
 
 
-		// ─── EVENT-LEVEL HOOKS ───────────────────────────────────────────
-
-		if (type === "event") {
-			const datasetStart = dayjs.unix(meta.datasetStart);
-			const ALGORITHM_CHANGE_DAY = datasetStart.add(45, 'days');
-			const REENGAGEMENT_START = datasetStart.add(30, 'days');
-			const EVENT_TIME = dayjs(record.time);
-
-			// Hook #3: ALGORITHM CHANGE - Day 45 flips feed -> explore.
-			// Mutates the existing config-defined `source` prop.
-			if (record.event === "post viewed") {
-				if (EVENT_TIME.isAfter(ALGORITHM_CHANGE_DAY)) {
-					if (chance.bool({ likelihood: 70 })) {
-						record.source = "explore";
-					}
-				} else {
-					if (chance.bool({ likelihood: 70 })) {
-						record.source = "feed";
-					}
-				}
-			}
-
-			// Hook #4: ENGAGEMENT BAIT - 20% of post views get crushed view duration.
-			// No flag — analyst sees bimodal duration distribution + low-tail share.
-			if (record.event === "post viewed") {
-				if (chance.bool({ likelihood: 20 })) {
-					record.view_duration_sec = chance.integer({ min: 1, max: 5 });
-				}
-
-				// Hook #5: NOTIFICATION RE-ENGAGEMENT — after day 30, 30% of views
-				// flip source to "notification". Mutates existing source prop.
-				if (EVENT_TIME.isAfter(REENGAGEMENT_START) && chance.bool({ likelihood: 30 })) {
-					record.source = "notification";
-				}
-			}
-		}
-
 		// ─── EVERYTHING-LEVEL HOOKS ──────────────────────────────────────
 
 		if (type === "everything") {
@@ -782,9 +748,42 @@ const config = {
 				}
 			}
 
+			// Hook #3: ALGORITHM CHANGE — day 45 flips feed → explore on post viewed.
+			// Hook #4: ENGAGEMENT BAIT — 20% of post-viewed events get crushed duration.
+			// Hook #5: NOTIFICATION RE-ENGAGEMENT — after day 30, 30% of views → notification.
+			// All three run AFTER injection passes so they apply to cloned events too.
+			const ALGORITHM_CHANGE_DAY = datasetStart.add(45, 'days');
+			const REENGAGEMENT_START = datasetStart.add(30, 'days');
+			userEvents.forEach(e => {
+				if (e.event === "post viewed") {
+					const eventTime = dayjs(e.time);
+
+					// Hook #3: Algorithm Change
+					if (eventTime.isAfter(ALGORITHM_CHANGE_DAY)) {
+						if (chance.bool({ likelihood: 70 })) {
+							e.source = "explore";
+						}
+					} else {
+						if (chance.bool({ likelihood: 70 })) {
+							e.source = "feed";
+						}
+					}
+
+					// Hook #4: Engagement Bait — 20% crushed view duration
+					if (chance.bool({ likelihood: 20 })) {
+						e.view_duration_sec = chance.integer({ min: 1, max: 5 });
+					}
+
+					// Hook #5: Notification Re-engagement (runs after #3 so can override)
+					if (eventTime.isAfter(REENGAGEMENT_START) && chance.bool({ likelihood: 30 })) {
+						e.source = "notification";
+					}
+				}
+			});
+
 			// Hook #7: TOXICITY CHURN — drop 60% of activity after day 30 for high reporters.
-			// Discovery: cohort users with >=3 report-submitted events, observe retention drop.
-			if (reportSubmittedCount >= 3) {
+			// Discovery: cohort users with >=2 report-submitted events, observe retention drop.
+			if (reportSubmittedCount >= 2) {
 				const churnCutoff = datasetStart.add(30, 'days');
 				for (let i = userEvents.length - 1; i >= 0; i--) {
 					const evt = userEvents[i];

package/dungeons/vertical/travel.js

@@ -1,7 +1,7 @@
 // ── TWEAK THESE ──
 const SEED = "dm4-travel";
-const num_days = 100;
-const num_users = 5_000;
+const num_days = 120;
+const num_users = 10_000;
 const avg_events_per_user_per_day = 1.2;
 let token = "your-mixpanel-token";
 
@@ -29,7 +29,7 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
  * StayQuest — a hotel booking platform for business and leisure travelers.
  * Users search destinations, compare hotels, book rooms, and leave reviews.
  *
- * - 5,000 users over 100 days, ~600K events
+ * - 5,000 users over 120 days, ~600K events
  * - Segments: business travelers (weekday), leisure families, luxury, budget
  * - Core loop: search → view hotel → compare → book → stay → review
  * - Revenue: commission per booking + premium loyalty membership
@@ -210,14 +210,16 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
 
 /** @type {Config} */
 const config = {
+	version: 2,
 	token,
 	seed: SEED,
 	datasetStart: "2026-01-01T00:00:00Z",
-	datasetEnd: "2026-04-28T23:59:59Z",
+	datasetEnd: "2026-05-01T23:59:59Z",
 	// numDays: num_days,
 	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
-	hasAnonIds: false,
+	hasAnonIds: true,
+	avgDevicePerUser: 2,
 	hasSessionIds: true,
 	format: "json",
 	gzip: true,
@@ -250,6 +252,7 @@ const config = {
 			event: "account created",
 			weight: 1,
 			isFirstEvent: true,
+			isAuthEvent: true,
 			properties: {
 				signup_source: ["organic", "google", "instagram", "tripadvisor", "referral", "email_campaign"],
 			},

package/lib/core/config-validator.js

@@ -145,6 +145,106 @@ function inferFunnels(events) {
 	return createdFunnels;
 }
 
+/**
+ * Config keys removed from the engine in 1.4. Silently stripped by
+ * `validateDungeonConfig` with a single warning per dungeon. To recreate any of these
+ * patterns, use hooks (see `lib/hook-patterns/*`).
+ */
+const KILLED_CONFIG_KEYS = ['subscription', 'attribution', 'geo', 'features', 'anomalies'];
+
+/**
+ * Strip killed config keys in place, log one deprecation warning per dungeon.
+ * @param {Partial<Dungeon>} config
+ */
+function stripKilledConfigKeys(config) {
+	const found = KILLED_CONFIG_KEYS.filter(k => config[k] !== undefined && config[k] !== null);
+	if (!found.length) return;
+	for (const k of found) delete config[k];
+	if (config.verbose !== false) {
+		console.warn(
+			`⚠️  dungeon-master 1.4 removed engine support for: ${found.join(', ')}. ` +
+			`These config keys are silently ignored. Recreate via hooks (see lib/hook-patterns/* once Phase 4 lands).`
+		);
+	}
+}
+
+/**
+ * Validate `Funnel.attempts` config in place. Coerces missing/invalid bounds so callers
+ * downstream don't have to re-defend. Throws on logically invalid configs (max < min).
+ * @param {import('../../types.js').Funnel[]} funnels
+ */
+function validateAttempts(funnels) {
+	for (const f of funnels) {
+		if (!f || !f.attempts) continue;
+		const a = f.attempts;
+		const min = Number.isFinite(a.min) ? Math.max(0, Math.floor(a.min)) : 0;
+		const max = Number.isFinite(a.max) ? Math.max(0, Math.floor(a.max)) : min;
+		if (max < min) {
+			throw new Error(`Funnel "${f.name || f.sequence?.join(' > ')}" attempts.max (${a.max}) must be >= attempts.min (${a.min})`);
+		}
+		a.min = min;
+		a.max = max;
+		if (a.conversionRate !== undefined) {
+			if (!Number.isFinite(a.conversionRate)) {
+				throw new Error(`Funnel "${f.name || f.sequence?.join(' > ')}" attempts.conversionRate must be a finite number 0-100`);
+			}
+			a.conversionRate = Math.max(0, Math.min(100, a.conversionRate));
+		}
+	}
+}
+
+/**
+ * Normalize `Funnel.experiment` in place. `true` → default 3-variant config.
+ * Object → validated and resolved. Stores `funnel._experiment` for downstream.
+ * @param {import('../../types.js').Funnel[]} funnels
+ * @param {number} datasetEndUnix
+ */
+function normalizeExperiments(funnels, datasetEndUnix) {
+	const DEFAULT_VARIANTS = [
+		{ name: 'Variant A', conversionMultiplier: 0.7, ttcMultiplier: 1.5, weight: 1 },
+		{ name: 'Variant B', conversionMultiplier: 1.3, ttcMultiplier: 0.7, weight: 1 },
+		{ name: 'Control', conversionMultiplier: 1.0, ttcMultiplier: 1.0, weight: 1 },
+	];
+	for (const f of funnels) {
+		if (!f || !f.experiment) continue;
+		const raw = f.experiment === true ? {} : f.experiment;
+		const name = raw.name || (f.name ? f.name + ' Experiment' : 'Unnamed Experiment');
+		const variants = (raw.variants && raw.variants.length)
+			? raw.variants.map(v => ({
+				name: v.name || 'Unnamed Variant',
+				conversionMultiplier: Number.isFinite(v.conversionMultiplier) ? Math.max(0.01, v.conversionMultiplier) : 1.0,
+				ttcMultiplier: Number.isFinite(v.ttcMultiplier) ? Math.max(0.01, v.ttcMultiplier) : 1.0,
+				weight: Number.isFinite(v.weight) && v.weight > 0 ? v.weight : 1,
+			}))
+			: DEFAULT_VARIANTS;
+		const startDays = Number.isFinite(raw.startDaysBeforeEnd) && raw.startDaysBeforeEnd > 0
+			? raw.startDaysBeforeEnd : 0;
+		const startUnix = startDays > 0 ? datasetEndUnix - startDays * 86400 : null;
+		f._experiment = { name, variants, startUnix };
+	}
+}
+
+/**
+ * Resolve `avgDevicePerUser` per Section 3.3 rules. Returns the integer device count
+ * the engine should use (0 = no device_id stamping at all, 1+ = pool size).
+ *
+ * @param {Partial<Dungeon>} config
+ * @returns {number}
+ */
+function resolveDevicesPerUser(config) {
+	const raw = config.avgDevicePerUser;
+	const hasAnon = config.hasAnonIds === true;
+	if (raw === undefined || raw === null) {
+		return hasAnon ? 1 : 0;
+	}
+	if (!Number.isFinite(raw)) {
+		return hasAnon ? 1 : 0;
+	}
+	const n = Math.round(raw);
+	if (n <= 0) return hasAnon ? 1 : 0;
+	return n;
+}
+
 /**
  * Validates and enriches a dungeon configuration object
  * @param {Partial<Dungeon>} config - Raw configuration object
@@ -153,6 +253,9 @@ function inferFunnels(events) {
 export function validateDungeonConfig(config) {
 	const chance = u.getChance();
 
+	// Phase 1 — strip killed config keys before anything else reads them.
+	stripKilledConfigKeys(config);
+
 	// Transform SCD props to regular props if credentials are missing
 	// This MUST happen BEFORE we extract values from the config
 	transformSCDPropsWithoutCredentials(config);
@@ -436,35 +539,31 @@ export function validateDungeonConfig(config) {
 		dataQuality = validateDataQuality(dataQuality);
 	}
 
-	// Feature 5: Subscription
-	let subscription = config.subscription || null;
-	if (subscription) {
-		subscription = validateSubscription(subscription);
-	}
+	// Phase 1: validate Funnel.attempts on every funnel (additive — most have none).
+	validateAttempts(funnels);
 
-	// Feature 6: Attribution
-	let attribution = config.attribution || null;
-	if (attribution) {
-		attribution = validateAttribution(attribution, numDays);
-	}
+	// Normalize experiment configs: true → default 3-variant, object → validated.
+	normalizeExperiments(funnels, datasetEndUnix);
 
-	// Feature 7: Geo
-	let geo = config.geo || null;
-	if (geo) {
-		geo = validateGeo(geo);
-	}
+	// Phase 1: resolve multi-device config. `avgDevicePerUser` is the canonical knob;
+	// `hasAnonIds: true` aliases to 1. Default 0 = no device_id stamping (legacy).
+	const avgDevicePerUser = resolveDevicesPerUser(config);
+	// Keep hasAnonIds in sync — downstream code (utils.generateUser) still reads it.
+	// Setting it true here when avgDevicePerUser >= 1 lets the legacy device-pool
+	// generation in `person()` continue to allocate `anonymousIds[]` for the user.
+	const hasAnonIdsResolved = avgDevicePerUser >= 1;
 
-	// Feature 8: Features (progressive adoption)
-	let features = config.features || null;
-	if (features) {
-		features = resolveFeatures(features, numDays);
+	// Warn if isAuthEvent is set but avgDevicePerUser=0 — pre-auth device_only
+	// stamping degrades to user_id via the floor guard, defeating the identity model.
+	if (avgDevicePerUser === 0 && validatedEvents.some(e => e.isAuthEvent)) {
+		console.warn(
+			`⚠️  isAuthEvent requires avgDevicePerUser >= 1 to produce pre-auth anonymous events. ` +
+			`Set avgDevicePerUser or hasAnonIds: true.`
+		);
 	}
 
-	// Feature 9: Anomalies
-	let anomalies = config.anomalies || null;
-	if (anomalies) {
-		anomalies = resolveAnomalies(anomalies, datasetStartUnix);
-	}
+	// Precompute whether any event has isAttributionEvent for UTM stamping logic.
+	const hasAttributionFlags = validatedEvents.some(e => e.isAttributionEvent);
 
 	// Build final config object
 	const validatedConfig = {
@@ -489,7 +588,8 @@ export function validateDungeonConfig(config) {
 		groupKeys,
 		groupProps,
 		lookupTables,
-		hasAnonIds,
+		hasAnonIds: hasAnonIdsResolved,
+		avgDevicePerUser,
 		hasSessionIds,
 		sessionTimeout: (typeof sessionTimeout === 'number' && sessionTimeout > 0) ? sessionTimeout : 30,
 		format,
@@ -501,6 +601,7 @@ export function validateDungeonConfig(config) {
 		hook,
 		hasAdSpend,
 		hasCampaigns,
+		hasAttributionFlags,
 		hasLocation,
 		hasAvatar,
 		isAnonymous,
@@ -515,16 +616,17 @@ export function validateDungeonConfig(config) {
 		bornRecentBias,
 		percentUsersBornInDataset,
 		preExistingSpread,
-		// Advanced features
+		// Advanced features (kept after 1.4)
 		personas,
 		worldEvents,
 		engagementDecay,
 		dataQuality,
-		subscription,
-		attribution,
-		geo,
-		features,
-		anomalies
+		// Killed in 1.4 — set to null so hooks/external code that reads these get a falsy value.
+		subscription: null,
+		attribution: null,
+		geo: null,
+		features: null,
+		anomalies: null
 	};
 
 	return validatedConfig;
@@ -689,131 +791,8 @@ function validateDataQuality(dq) {
 	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} beginUnix - Dataset start (unix seconds)
- * @returns {import('../../types').AnomalyConfig[]}
- */
-function resolveAnomalies(anomalies, beginUnix) {
-	if (!Array.isArray(anomalies) || anomalies.length === 0) return null;
-	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;
-	});
-}
+// validateSubscription / validateAttribution / validateGeo / resolveFeatures /
+// resolveAnomalies were removed in 1.4 along with their respective config keys.
+// `stripKilledConfigKeys` deletes the inputs before they reach the validator body.
 
 export { inferFunnels, transformSCDPropsWithoutCredentials };