@ak--47/dungeon-master 1.5.0 → 1.5.1

package/dungeons/technical/simple.js

@@ -1,42 +1,22 @@
-// ── TWEAK THESE ──
-const SEED = "simple is best";
-const num_days = 100;
-const num_users = 5_000;
-const avg_events_per_user_per_day = 1;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
-
+// ── IMPORTS ──
 import Chance from 'chance';
-let chance = new Chance();
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 dayjs.extend(utc);
-import { uid, comma } from 'ak-tools';
 import { pickAWinner, weighNumRange, date, integer, weighChoices } from "../../lib/utils/utils.js";
-
 /** @typedef {import("../../types").Dungeon} Config */
-const itemCategories = ["Books", "Movies", "Music", "Games", "Electronics", "Computers", "Smart Home", "Home", "Garden", "Pet", "Beauty", "Health", "Toys", "Kids", "Baby", "Handmade", "Sports", "Outdoors", "Automotive", "Industrial", "Entertainment", "Art", "Food", "Appliances", "Office", "Wedding", "Software"];
 
-const videoCategories = ["funny", "educational", "inspirational", "music", "news", "sports", "cooking", "DIY", "travel", "gaming"];
+// ── OVERVIEW ──
+/*
+ * NAME:       simple
+ * PURPOSE:    simple e-commerce + media dungeon — exercises event/everything hooks, campaigns, signup funnel A/B
+ * SCALE:      5,000 users, ~500K events, 100 days
+ * EVENTS (9): ad impression, ad click, checkout, add to cart, page view, watch video, view item, save item, sign up
+ * FUNNELS (1): page view → view item → save item → page view → sign up (Signup Flow, A/B experiment)
+ */
 
-/**
- * ═══════════════════════════════════════════════════════════════
- * DATASET OVERVIEW
- * ═══════════════════════════════════════════════════════════════
- *
- * Simple E-Commerce + Media App
- * - 5,000 users over 100 days, ~500K events
- * - Events: ad impressions/clicks, page views, video watching,
- *   item browsing/saving, cart, checkout, signup
- * - Signup funnel with A/B experiment
- * - Campaigns, location, browser, and device data enabled
- *
- * ═══════════════════════════════════════════════════════════════
- * ANALYTICS HOOKS (3 patterns)
- * ═══════════════════════════════════════════════════════════════
- *
+// ── HOOK STORIES ──
+/*
  * 1. TEMPORAL IMPROVEMENT (event hook)
  *    After 15 days ago: checkout amounts 1.5x, watch times 1.5x.
  *    Before that: 33% of events are dropped (tagged _drop, filtered in everything).
@@ -68,29 +48,129 @@ const videoCategories = ["funny", "educational", "inspirational", "music", "news
  *      Expected: low-quality cohort volume thins out after midpoint
  */
 
-/** @type {import('../../types').Dungeon} */
+// ── SCALE ──
+const SEED = "simple is best";
+const NUM_DAYS = 100;
+const NUM_USERS = 5_000;
+const EVENTS_PER_DAY = 1;
+const token = process.env.MP_TOKEN || "";
+
+const chance = new Chance();
+
+// ── KNOBS (tweak these to reshape stories) ──
+const IMPROVEMENT_DAYS_AGO = 15;
+const IMPROVEMENT_MULTIPLIER = 1.5;
+const PRE_IMPROVEMENT_DROP_LIKELIHOOD = 33;
+const CUSTOM_THEME_CHECKOUT_AMOUNT_MULT = 2;
+const LOW_QUALITY_CHURN_LIKELIHOOD = 50;
+const LOW_QUALITY_TIERS = ["480p", "360p", "240p"];
+
+// ── DATA ARRAYS ──
+const itemCategories = ["Books", "Movies", "Music", "Games", "Electronics", "Computers", "Smart Home", "Home", "Garden", "Pet", "Beauty", "Health", "Toys", "Kids", "Baby", "Handmade", "Sports", "Outdoors", "Automotive", "Industrial", "Entertainment", "Art", "Food", "Appliances", "Office", "Wedding", "Software"];
+const videoCategories = ["funny", "educational", "inspirational", "music", "news", "sports", "cooking", "DIY", "travel", "gaming"];
+const spiritAnimals = ["duck", "dog", "otter", "penguin", "cat", "elephant", "lion", "cheetah", "giraffe", "zebra", "rhino", "hippo", "whale", "dolphin", "shark", "octopus", "squid", "jellyfish", "starfish", "seahorse", "crab", "lobster", "shrimp", "clam", "snail", "slug", "butterfly", "moth", "bee", "wasp", "ant", "beetle", "ladybug", "caterpillar", "centipede", "millipede", "scorpion", "spider", "tarantula", "tick", "mite", "mosquito", "fly", "dragonfly", "damselfly", "grasshopper", "cricket", "locust", "mantis", "cockroach", "termite", "praying mantis", "walking stick", "stick bug", "leaf insect", "lacewing", "aphid", "cicada", "thrips", "psyllid", "scale insect", "whitefly", "mealybug", "planthopper", "leafhopper", "treehopper", "flea", "louse", "bedbug", "flea beetle", "weevil", "longhorn beetle", "leaf beetle", "tiger beetle", "ground beetle", "lady beetle", "firefly", "click beetle", "rove beetle", "scarab beetle", "dung beetle", "stag beetle", "rhinoceros beetle", "hercules beetle", "goliath beetle", "jewel beetle", "tortoise beetle"];
+
+// ── HELPER FUNCTIONS ──
+function flip(likelihood = 50) {
+	return chance.bool({ likelihood });
+}
+
+function handleEventHook(record, meta) {
+	// Anchor relative dates to the resolved dataset window — never wall-clock.
+	const datasetEnd = dayjs.unix(meta.datasetEnd);
+	const OVER_THINGS_GET_BETTER = datasetEnd.subtract(IMPROVEMENT_DAYS_AGO, 'day');
+	const EVENT_TIME = dayjs(record.time);
+
+	if (EVENT_TIME.isAfter(OVER_THINGS_GET_BETTER)) {
+		// checkouts are bigger
+		if (record.event === "checkout") {
+			record.amount = Math.round(record.amount * IMPROVEMENT_MULTIPLIER);
+		}
+
+		// videos are longer
+		if (record.event === "watch video") {
+			record.watchTimeSec = Math.round(record.watchTimeSec * IMPROVEMENT_MULTIPLIER);
+		}
+	}
+
+	if (EVENT_TIME.isBefore(OVER_THINGS_GET_BETTER)) {
+		// tag 33% for removal (filtered in "everything" hook)
+		if (chance.bool({ likelihood: PRE_IMPROVEMENT_DROP_LIKELIHOOD })) record._drop = true;
+	}
+
+	return record;
+}
+
+function handleEverythingHook(record, meta) {
+	const profile = meta.profile;
+	record.forEach(e => {
+		e.theme = profile.theme;
+	});
+
+	// custom themes purchase more:
+	const numCustomMode = record.filter(a => a.theme === 'custom').length;
+	const numLightMode = record.filter(a => a.theme === 'light').length;
+	const numDarkMode = record.filter(a => a.theme === 'dark').length;
+	if (numCustomMode > numLightMode || numCustomMode > numDarkMode) {
+		// triple their checkout events
+		const checkoutEvents = record.filter(a => a.event === 'checkout');
+		const newCheckouts = checkoutEvents.map(a => {
+			const randomInt = integer(-48, 48);
+			const newCheckout = {
+				...a,
+				time: dayjs(a.time).add(randomInt, 'hour').toISOString(),
+				event: "checkout",
+				amount: a.amount * CUSTOM_THEME_CHECKOUT_AMOUNT_MULT,
+				coupon: "50%OFF"
+			};
+			return newCheckout;
+		});
+		record.push(...newCheckouts);
+	}
+
+	// users who watch low quality videos churn more:
+	const lowQualityWatches = record.filter(a => a.event === 'watch video' && LOW_QUALITY_TIERS.includes(a.quality));
+	const highQualityWatches = record.filter(a => a.event === 'watch video' && !LOW_QUALITY_TIERS.includes(a.quality));
+	if (lowQualityWatches.length > highQualityWatches.length) {
+		if (flip(LOW_QUALITY_CHURN_LIKELIHOOD)) {
+			// find midpoint of records
+			const midpoint = Math.floor(record.length / 2);
+			record = record.slice(0, midpoint);
+		}
+	}
+
+	// Filter out events tagged for removal in the event hook
+	return record.filter(e => !e._drop);
+}
+
+// ── CONFIG ──
+/** @type {Config} */
 const config = {
-	token,
 	seed: SEED,
-	numDays: num_days,
-	avgEventsPerUserPerDay: avg_events_per_user_per_day,
-	numUsers: num_users,
+	numDays: NUM_DAYS,
+	avgEventsPerUserPerDay: EVENTS_PER_DAY,
+	numUsers: NUM_USERS,
 	format: 'json', //csv or json
-	region: "US",
-	hasAnonIds: true, //if true, anonymousIds are created for each user
-	hasSessionIds: true, //if true, hasSessionIds are created for each user
-	hasAdSpend: false,
-	hasLocation: true,
-	hasAndroidDevices: true,
-	hasIOSDevices: true,
-	hasDesktopDevices: true,
-	hasBrowser: true,
-	hasCampaigns: true,
-	isAnonymous: false,
-	alsoInferFunnels: true,
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: true, //if true, hasSessionIds are created for each user
+		hasAdSpend: false,
+		hasLocation: true,
+		hasAndroidDevices: true,
+		hasIOSDevices: true,
+		hasDesktopDevices: true,
+		hasBrowser: true,
+		hasCampaigns: true,
+		isAnonymous: false,
+		alsoInferFunnels: true,
+	},
+	identity: {
+		avgDevicePerUser: 1,
+	},
 	concurrency: 1,
-
-
 	events: [
 		{
 			event: "ad impression",
@@ -114,7 +194,6 @@ const config = {
 				currency: ["USD", "CAD", "EUR", "BTC", "ETH", "JPY"],
 				coupon: weighChoices(["none", "none", "none", "none", "10%OFF", "20%OFF", "10%OFF", "20%OFF", "30%OFF", "40%OFF", "50%OFF"]),
 				numItems: weighNumRange(1, 10),
-
 			}
 		},
 		{
@@ -147,7 +226,6 @@ const config = {
 				quality: ["2160p", "1440p", "1080p", "720p", "480p", "360p", "240p"],
 				format: ["mp4", "avi", "mov", "mpg"],
 				uploader_id: chance.guid.bind(chance)
-
 			}
 		},
 		{
@@ -177,7 +255,6 @@ const config = {
 				referral: weighChoices(["none", "none", "none", "friend", "ad", "ad", "ad", "friend", "friend", "friend", "friend"]),
 			}
 		},
-
 	],
 	funnels: [
 		{
@@ -189,111 +266,27 @@ const config = {
 			timeToConvert: 2,
 			experiment: true,
 			name: "Signup Flow"
-
 		}
-
 	],
 	superProps: {
 		theme: ["light", "dark", "custom", "light", "dark"],
 	},
-	/*
-	user properties work the same as event properties
-	each key should be an array or function reference
-	*/
 	userProps: {
 		theme: ["light", "dark", "custom", "light", "dark"],
 		title: chance.profession.bind(chance),
 		luckyNumber: weighNumRange(42, 420, .3),
-		spiritAnimal: ["duck", "dog", "otter", "penguin", "cat", "elephant", "lion", "cheetah", "giraffe", "zebra", "rhino", "hippo", "whale", "dolphin", "shark", "octopus", "squid", "jellyfish", "starfish", "seahorse", "crab", "lobster", "shrimp", "clam", "snail", "slug", "butterfly", "moth", "bee", "wasp", "ant", "beetle", "ladybug", "caterpillar", "centipede", "millipede", "scorpion", "spider", "tarantula", "tick", "mite", "mosquito", "fly", "dragonfly", "damselfly", "grasshopper", "cricket", "locust", "mantis", "cockroach", "termite", "praying mantis", "walking stick", "stick bug", "leaf insect", "lacewing", "aphid", "cicada", "thrips", "psyllid", "scale insect", "whitefly", "mealybug", "planthopper", "leafhopper", "treehopper", "flea", "louse", "bedbug", "flea beetle", "weevil", "longhorn beetle", "leaf beetle", "tiger beetle", "ground beetle", "lady beetle", "firefly", "click beetle", "rove beetle", "scarab beetle", "dung beetle", "stag beetle", "rhinoceros beetle", "hercules beetle", "goliath beetle", "jewel beetle", "tortoise beetle"]
+		spiritAnimal: spiritAnimals,
 	},
 	scdProps: {},
 	mirrorProps: {},
-
-	/*
-	for group analytics keys, we need an array of arrays [[],[],[]] 
-	each pair represents a group_key and the number of profiles for that key
-	*/
 	groupKeys: [],
 	groupProps: {},
 	lookupTables: [],
 	hook: function (record, type, meta) {
-
-		// Anchor relative dates to the resolved dataset window — never wall-clock.
-		const datasetEnd = dayjs.unix(meta.datasetEnd);
-		const OVER_THINGS_GET_BETTER = datasetEnd.subtract(15, 'day');
-
-		if (type === "event") {
-			const EVENT_TIME = dayjs(record.time);
-
-			if (EVENT_TIME.isAfter(OVER_THINGS_GET_BETTER)) {
-				// checkouts are bigger
-				if (record.event === "checkout") {
-					record.amount = Math.round(record.amount * 1.5);
-				}
-
-				// videos are longer
-				if (record.event === "watch video") {
-					record.watchTimeSec = Math.round(record.watchTimeSec * 1.5);
-				}
-			}
-
-			if (EVENT_TIME.isBefore(OVER_THINGS_GET_BETTER)) {
-				// tag 33% for removal (filtered in "everything" hook)
-				if (chance.bool({ likelihood: 33 })) record._drop = true;
-			}
-		}
-
-		if (type === "everything") {
-			const profile = meta.profile;
-			record.forEach(e => {
-				e.theme = profile.theme;
-			});
-
-			//custom themes purchase more:
-			const numCustomMode = record.filter(a => a.theme === 'custom').length;
-			const numLightMode = record.filter(a => a.theme === 'light').length;
-			const numDarkMode = record.filter(a => a.theme === 'dark').length;
-			if (numCustomMode > numLightMode || numCustomMode > numDarkMode) {
-				//triple their checkout events
-				const checkoutEvents = record.filter(a => a.event === 'checkout');
-				const newCheckouts = checkoutEvents.map(a => {
-					const randomInt = integer(-48, 48);
-					const newCheckout = {
-						...a,
-						time: dayjs(a.time).add(randomInt, 'hour').toISOString(),
-						event: "checkout",
-						amount: a.amount * 2,
-						coupon: "50%OFF"
-					};
-					return newCheckout;
-				});
-				record.push(...newCheckouts);
-			}
-
-			//users who watch low quality videos churn more:
-			const loQuality = ["480p", "360p", "240p"];
-			const lowQualityWatches = record.filter(a => a.event === 'watch video' && loQuality.includes(a.quality));
-			const highQualityWatches = record.filter(a => a.event === 'watch video' && !loQuality.includes(a.quality));
-			if (lowQualityWatches.length > highQualityWatches.length) {
-				if (flip()) {
-					// find midpoint of records
-					const midpoint = Math.floor(record.length / 2);
-					record = record.slice(0, midpoint);
-
-				}
-			}
-
-			// Filter out events tagged for removal in the event hook
-			record = record.filter(e => !e._drop);
-		}
-
+		if (type === "event") return handleEventHook(record, meta);
+		if (type === "everything") return handleEverythingHook(record, meta);
 		return record;
 	}
 };
 
-function flip(likelihood = 50) {
-	return chance.bool({ likelihood });
-}
-
-
-export default config;
+export default config;

package/dungeons/technical/simplest.js

@@ -1,76 +1,71 @@
-// ── TWEAK THESE ──
+// ── IMPORTS ──
+import Chance from 'chance';
+let chance = new Chance();
+import { pickAWinner, weighNumRange, integer, weighChoices, dateRange, listOf, objectList } from "../../lib/utils/utils.js";
+/** @typedef {import("../../types").Dungeon} Config */
+
+// ── OVERVIEW ──
+/*
+ * NAME:       simplest
+ * PURPOSE:    Engine-validation baseline — no hooks. Engine + TimeSoup alone produce the trend shape. Used by engine-shape canary + full sweep.
+ * SCALE:      2,500 users, ~250K events, 100 days
+ * EVENTS (25): page view (10) > view item (9) > view category (8) > login (8) > search (7) > notification received (7) > watch video (6) > add to cart (5) > notification clicked (5) > rate item (4) > add to wishlist (4) > checkout (3) > remove from cart (3) > update profile (3) > compare items (3) > share content (2) > support ticket (2) > apply coupon (2) > leave review (2) > sign up (1) > add payment method (1) > invite friend (1) > save address (1) > subscribe newsletter (1) > redeem reward (1)
+ * FUNNELS (11): Signup Funnel, Purchase Funnel, Content Engagement, Review Funnel, Browse to Cart, Notification Engagement, Wishlist to Purchase, Post-Purchase Advocacy, Coupon Purchase Flow, Newsletter to Purchase, Support Recovery
+ * USER PROPS:  theme, title, spiritAnimal, luckyNumber, emailOptIn, signupDate, favoriteCategories, preferences, recentOrders
+ * SUPER PROPS: theme
+ * GROUPS:      none
+ *
+ * USE CASES:
+ *   - Engine sweep harness baseline (`scripts/sweep-engine.mjs`). Strict-bar regression
+ *     testing across the 184-combo macro/born/rate/active-day matrix.
+ *   - Reference for "what an average dungeon looks like" — diverse events + funnels +
+ *     user props with no hook architecting on top.
+ *   - Starting template for new dungeons before adding bespoke hooks.
+ *   - At least one property of every Mixpanel data type:
+ *       string, numeric, boolean, date, list, object, list-of-objects
+ *     on both event properties and user properties.
+ *   - No device/location/campaign data — pure event stream.
+ *   - **No hooks.** This is the engine-validation baseline; engine + TimeSoup alone
+ *     produce the trend shape. Hook authors should reach for vertical dungeons or
+ *     write hooks against this template; do NOT add hooks here.
+ */
+
+// ── SCALE ──
 const SEED = "simple is best";
 const num_days = 100;
 const num_users = 2_500;
 const avg_events_per_user_per_day = 1;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
-
-import Chance from 'chance';
-let chance = new Chance();
-import dayjs from "dayjs";
-import utc from "dayjs/plugin/utc.js";
-dayjs.extend(utc);
-import { uid, comma } from 'ak-tools';
-import { pickAWinner, weighNumRange, date, integer, weighChoices, dateRange, listOf, objectList } from "../../lib/utils/utils.js";
+const token = process.env.MP_TOKEN || "";
 
-/** @typedef {import("../../types").Dungeon} Config */
+// ── DATA ARRAYS ──
 const itemCategories = ["Books", "Movies", "Music", "Games", "Electronics", "Computers", "Smart Home", "Home", "Garden", "Pet", "Beauty", "Health", "Toys", "Kids", "Baby", "Handmade", "Sports", "Outdoors", "Automotive", "Industrial", "Entertainment", "Art", "Food", "Appliances", "Office", "Wedding", "Software"];
 
 const videoCategories = ["funny", "educational", "inspirational", "music", "news", "sports", "cooking", "DIY", "travel", "gaming"];
 
-/**
- * ═══════════════════════════════════════════════════════════════
- * DATASET OVERVIEW
- * ═══════════════════════════════════════════════════════════════
- *
- * Simplest E-Commerce App — the canonical no-hook baseline dungeon.
- * - 2,500 users over 100 days, ~250K events
- * - 25 event types covering browse, search, cart, checkout,
- *   notifications, reviews, wishlists, rewards
- * - 11 funnels with diverse weights (1-10) covering signup, purchase,
- *   content engagement, browse-to-cart, post-purchase advocacy, etc.
- * - At least one property of every Mixpanel data type:
- *     string, numeric, boolean, date, list, object, list-of-objects
- *   on both event properties and user properties.
- * - No device/location/campaign data — pure event stream
- * - **No hooks.** This is the engine-validation baseline; engine + TimeSoup
- *   alone produce the trend shape. Hook authors should reach for vertical
- *   dungeons or write hooks against this template; do NOT add hooks here.
- *
- * ═══════════════════════════════════════════════════════════════
- * USE CASES
- * ═══════════════════════════════════════════════════════════════
- *
- * - Engine sweep harness baseline (`scripts/sweep-engine.mjs`). Strict-bar
- *   regression testing across the 184-combo macro/born/rate/active-day matrix.
- * - Reference for "what an average dungeon looks like" — diverse events
- *   + funnels + user props with no hook architecting on top.
- * - Starting template for new dungeons before adding bespoke hooks.
- */
-
+// ── CONFIG ──
 /** @type {import('../types.js').Dungeon} */
 const config = {
-	token,
 	seed: SEED,
 	numDays: num_days,
 	avgEventsPerUserPerDay: avg_events_per_user_per_day,
 	numUsers: num_users,
 	format: 'json', //csv or json
-	region: "US",
-	hasAnonIds: false, //if true, anonymousIds are created for each user
-	hasSessionIds: false, //if true, hasSessionIds are created for each user
-	hasAdSpend: false,
-	hasLocation: false,
-	hasAndroidDevices: false,
-	hasIOSDevices: false,
-	hasDesktopDevices: false,
-	hasBrowser: false,
-	hasCampaigns: false,
-	isAnonymous: false,
-	alsoInferFunnels: false,
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: false, //if true, hasSessionIds are created for each user
+		hasAdSpend: false,
+		hasLocation: false,
+		hasAndroidDevices: false,
+		hasIOSDevices: false,
+		hasDesktopDevices: false,
+		hasBrowser: false,
+		hasCampaigns: false,
+		isAnonymous: false,
+		alsoInferFunnels: false,
+	},
 	concurrency: 1,
 	writeToDisk: false,
 
@@ -447,7 +442,7 @@ const config = {
 	mirrorProps: {},
 
 	/*
-	for group analytics keys, we need an array of arrays [[],[],[]] 
+	for group analytics keys, we need an array of arrays [[],[],[]]
 	each pair represents a group_key and the number of profiles for that key
 	*/
 	groupKeys: [],
@@ -457,7 +452,4 @@ const config = {
 	// alone produce the trend shape. To experiment with hooks, fork this file.
 };
 
-
-
-
-export default config;
+export default config;