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

package/dungeons/technical/retention-cadence.js

@@ -1,38 +1,25 @@
-// ── TWEAK THESE ──
-const SEED = "kurby-retention";
-const num_days = 360;
-const num_users = 100;
-const avg_events_per_user_per_day = 0.14;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
-
-import dayjs from 'dayjs';
-import utc from 'dayjs/plugin/utc.js';
+// ── IMPORTS ──
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
 dayjs.extend(utc);
 import * as u from "../../lib/utils/utils.js";
-import * as v from 'ak-tools';
-const chance = u.initChance(SEED);
-
+import * as v from "ak-tools";
 /** @typedef {import("../../types").Dungeon} Config */
 
-/**
- * ═══════════════════════════════════════════════════════════════
- * DATASET OVERVIEW
- * ═══════════════════════════════════════════════════════════════
- *
- * Retention Cadence — tests behavior frequency and color-based churn.
- * - 100 users over 360 days, ~5K base events (replaced by cadenced events)
- * - 4 behavior cadences: hourly, daily, weekly, monthly
- * - Churn rates vary by user's "favorite color" (red, blue, green, yellow, purple)
- * - The everything hook REPLACES all generated events with precisely
- *   cadenced behavior events, making this a pure retention analysis dataset
- *
- * ═══════════════════════════════════════════════════════════════
- * ANALYTICS HOOKS (1 pattern — everything hook)
- * ═══════════════════════════════════════════════════════════════
- *
+// ── OVERVIEW ──
+/*
+ * NAME:       retention-cadence
+ * PURPOSE:    Exercises retention shaping — the everything hook REPLACES all
+ *             generated events with precisely cadenced behavior streams
+ *             (hourly/daily/weekly/monthly) with color-driven churn.
+ * SCALE:      100 users, ~5K base events (replaced by cadenced events), 360 days
+ * EVENTS (6): first behavior, hourly behavior, daily behavior, weekly behavior,
+ *             monthly behavior, placeholder
+ * FUNNELS (0): none
+ */
+
+// ── HOOK STORIES ──
+/*
  * 1. COLOR-BASED CADENCED CHURN (everything hook)
  *    All raw events are replaced with 4 cadenced behavior streams
  *    (hourly/daily/weekly/monthly). Each user's "favorite color"
@@ -52,6 +39,16 @@ const chance = u.initChance(SEED);
  *      Expected: each color dominates its respective cadence's churn events
  */
 
+// ── SCALE ──
+const SEED = "kurby-retention";
+const NUM_DAYS = 360;
+const NUM_USERS = 100;
+const EVENTS_PER_DAY = 0.14;
+const token = process.env.MP_TOKEN || "";
+
+const chance = u.initChance(SEED);
+
+// ── KNOBS (tweak these to reshape stories) ──
 // Churn rates by favorite color per behavior type (percentage likelihood)
 const CHURN_RATES = {
 	red:    { hourly: 15, daily: 40, weekly: 15, monthly: 10 },
@@ -61,7 +58,7 @@ const CHURN_RATES = {
 	purple: { hourly: 40, daily: 15, weekly: 15, monthly: 10 },
 };
 
-// Behavior cadence definitions: [intervalAmount, intervalUnit, jitterMax, jitterUnit]
+// Behavior cadence definitions: interval + unit + jitter window
 const BEHAVIORS = {
 	hourly:  { interval: 1,  unit: 'hour',  jitterMax: 10, jitterUnit: 'minute' },
 	daily:   { interval: 1,  unit: 'day',   jitterMax: 2,  jitterUnit: 'hour' },
@@ -69,6 +66,7 @@ const BEHAVIORS = {
 	monthly: { interval: 30, unit: 'day',   jitterMax: 2,  jitterUnit: 'day' },
 };
 
+// ── HELPER FUNCTIONS ──
 function generateCadencedEvents(behaviorName, cadence, startTime, endTime, churnTime, userId) {
 	const events = [];
 	let cursor = dayjs(startTime);
@@ -105,26 +103,94 @@ function generateCadencedEvents(behaviorName, cadence, startTime, endTime, churn
 	return events;
 }
 
+function handleEverythingHooks(record, meta) {
+	if (!record.length) return record;
+
+	const userId = record[0].user_id || record[0].device_id;
+	if (!userId) return record;
+
+	const favoriteColor = meta.profile?.["favorite color"] || "green";
+	const colorChurnRates = CHURN_RATES[favoriteColor] || CHURN_RATES.green;
+
+	// Find the time range from the raw events
+	const times = record.map(e => new Date(e.time).getTime()).filter(t => !isNaN(t));
+	if (!times.length) return record;
+	const startTime = dayjs(Math.min(...times));
+	const endTime = dayjs(Math.max(...times));
+	const totalSpanHours = endTime.diff(startTime, 'hour');
+
+	if (totalSpanHours < 1) return record;
+
+	// Keep the "first behavior" event from the original stream
+	const firstBehavior = record.find(e => e.event === "first behavior");
+	const newEvents = [];
+
+	if (firstBehavior) {
+		newEvents.push(firstBehavior);
+	} else {
+		// Create a first behavior event at the start
+		newEvents.push({
+			event: "first behavior",
+			time: startTime.toISOString(),
+			user_id: userId,
+			insert_id: v.uid(12),
+		});
+	}
+
+	// For each behavior type, determine churn and generate cadenced events
+	for (const [behaviorKey, cadence] of Object.entries(BEHAVIORS)) {
+		const churnRate = colorChurnRates[behaviorKey];
+		let churnTime = null;
+
+		if (chance.bool({ likelihood: churnRate })) {
+			// Pick churn time between 20% and 80% into the active period
+			const churnOffsetHours = chance.integer({
+				min: Math.floor(totalSpanHours * 0.2),
+				max: Math.floor(totalSpanHours * 0.8),
+			});
+			churnTime = startTime.add(churnOffsetHours, 'hour');
+		}
+
+		const behaviorEvents = generateCadencedEvents(
+			behaviorKey,
+			cadence,
+			startTime,
+			endTime,
+			churnTime,
+			userId
+		);
+		newEvents.push(...behaviorEvents);
+	}
+
+	// Sort all events by time
+	newEvents.sort((a, b) => new Date(a.time) - new Date(b.time));
+	return newEvents;
+}
+
+// ── CONFIG ──
 /** @type {Config} */
 const config = {
-	token,
 	seed: SEED,
-	numDays: num_days,
-	avgEventsPerUserPerDay: avg_events_per_user_per_day,
-	numUsers: num_users,
-	hasAnonIds: false,
-	hasSessionIds: false,
+	numDays: NUM_DAYS,
+	avgEventsPerUserPerDay: EVENTS_PER_DAY,
+	numUsers: NUM_USERS,
 	format: "json",
-	alsoInferFunnels: false,
-	hasLocation: false,
-	hasAndroidDevices: false,
-	hasIOSDevices: false,
-	hasDesktopDevices: false,
-	hasBrowser: false,
-	hasCampaigns: false,
-	isAnonymous: false,
-	hasAdSpend: false,
-	hasAvatar: false,
+	credentials: {
+		token,
+	},
+	switches: {
+		hasSessionIds: false,
+		alsoInferFunnels: false,
+		hasLocation: false,
+		hasAndroidDevices: false,
+		hasIOSDevices: false,
+		hasDesktopDevices: false,
+		hasBrowser: false,
+		hasCampaigns: false,
+		isAnonymous: false,
+		hasAdSpend: false,
+		hasAvatar: false,
+	},
 	concurrency: 1,
 	writeToDisk: false,
 
@@ -177,70 +243,7 @@ const config = {
 	lookupTables: [],
 
 	hook: function (record, type, meta) {
-		if (type === "everything") {
-			if (!record.length) return record;
-
-			const userId = record[0].user_id || record[0].device_id;
-			if (!userId) return record;
-
-			const favoriteColor = meta.profile?.["favorite color"] || "green";
-			const colorChurnRates = CHURN_RATES[favoriteColor] || CHURN_RATES.green;
-
-			// Find the time range from the raw events
-			const times = record.map(e => new Date(e.time).getTime()).filter(t => !isNaN(t));
-			if (!times.length) return record;
-			const startTime = dayjs(Math.min(...times));
-			const endTime = dayjs(Math.max(...times));
-			const totalSpanHours = endTime.diff(startTime, 'hour');
-
-			if (totalSpanHours < 1) return record;
-
-			// Keep the "first behavior" event from the original stream
-			const firstBehavior = record.find(e => e.event === "first behavior");
-			const newEvents = [];
-
-			if (firstBehavior) {
-				newEvents.push(firstBehavior);
-			} else {
-				// Create a first behavior event at the start
-				newEvents.push({
-					event: "first behavior",
-					time: startTime.toISOString(),
-					user_id: userId,
-					insert_id: v.uid(12),
-				});
-			}
-
-			// For each behavior type, determine churn and generate cadenced events
-			for (const [behaviorKey, cadence] of Object.entries(BEHAVIORS)) {
-				const churnRate = colorChurnRates[behaviorKey];
-				let churnTime = null;
-
-				if (chance.bool({ likelihood: churnRate })) {
-					// Pick churn time between 20% and 80% into the active period
-					const churnOffsetHours = chance.integer({
-						min: Math.floor(totalSpanHours * 0.2),
-						max: Math.floor(totalSpanHours * 0.8),
-					});
-					churnTime = startTime.add(churnOffsetHours, 'hour');
-				}
-
-				const behaviorEvents = generateCadencedEvents(
-					behaviorKey,
-					cadence,
-					startTime,
-					endTime,
-					churnTime,
-					userId
-				);
-				newEvents.push(...behaviorEvents);
-			}
-
-			// Sort all events by time
-			newEvents.sort((a, b) => new Date(a.time) - new Date(b.time));
-			return newEvents;
-		}
-
+		if (type === "everything") return handleEverythingHooks(record, meta);
 		return record;
 	},
 };

package/dungeons/technical/sanity.js

@@ -1,60 +1,100 @@
-// ── TWEAK THESE ──
-const SEED = "foo bar";
-const num_days = 90;
-const num_users = 500;
-const avg_events_per_user_per_day = 1.11;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
-
+// ── IMPORTS ──
 import Chance from 'chance';
-const chance = new Chance();
-import dayjs from 'dayjs';
-import utc from 'dayjs/plugin/utc.js';
-dayjs.extend(utc);
 import { weighNumRange, integer } from "../../lib/utils/utils.js";
-
 /** @typedef {import("../../types").Dungeon} Config */
-/**
- * ═══════════════════════════════════════════════════════════════
- * DATASET OVERVIEW
- * ═══════════════════════════════════════════════════════════════
- *
- * Sanity Test — lightweight dungeon for module integration testing.
- * - 500 users over 30 days, ~50K events
- * - 10 abstract events (foo-yak) with no properties
- * - Super props: color, number — for quick breakdown testing
- * - Groups, SCDs, inferred funnels all disabled
- *
- * ═══════════════════════════════════════════════════════════════
- * ANALYTICS HOOKS (2 patterns)
- * ═══════════════════════════════════════════════════════════════
- *
+
+// ── OVERVIEW ──
+/*
+ * NAME:       sanity
+ * PURPOSE:    lightweight dungeon for module integration testing — abstract foo-yak events, inferred funnels
+ * SCALE:      500 users, ~50K events, 90 days
+ * EVENTS (10): foo, bar, baz, qux, garply, durtle, linny, fonk, crumn, yak
+ * FUNNELS (2): qux→garply→durtle→linny→fonk→crumn→yak; foo→bar→baz (first)
+ */
+
+// ── HOOK STORIES ──
+/*
  * 1. TEMPERATURE TAGGING (event hook)
  *    foo/bar/baz = "hot", crumn/yak = "cold", everything else = "warm".
+ *    (NOTE: current implementation stamps an integer engagement_score
+ *    bucketed by event name — high/mid/low engagement bands.)
  *
  * 2. HASH-BASED POWER USERS (everything hook)
  *    ~10% of users (by distinct_id hash) get 3 extra duplicate events.
+ *    (NOTE: current implementation trims the tail of users with 4-7
+ *    events to simulate light-user churn.)
  */
 
+// ── SCALE ──
+const SEED = "foo bar";
+const NUM_DAYS = 90;
+const NUM_USERS = 500;
+const EVENTS_PER_DAY = 1.11;
+const token = process.env.MP_TOKEN || "";
+
+const chance = new Chance();
+
+// ── DATA ARRAYS ──
+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"];
+const colors = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
+
+// ── HELPER FUNCTIONS ──
+function handleUserHook(record) {
+	// tag power users based on luckyNumber
+	record.userTier = record.luckyNumber > 300 ? "power" : "regular";
+	return record;
+}
+
+function handleEventHook(record) {
+	// add an engagement score based on event type
+	const highEngagement = ["fonk", "crumn", "yak"];
+	const midEngagement = ["garply", "durtle", "linny"];
+	if (highEngagement.includes(record.event)) {
+		record.engagement_score = chance.integer({ min: 70, max: 100 });
+	} else if (midEngagement.includes(record.event)) {
+		record.engagement_score = chance.integer({ min: 30, max: 69 });
+	} else {
+		record.engagement_score = chance.integer({ min: 1, max: 29 });
+	}
+	return record;
+}
+
+function handleEverythingHook(record, meta) {
+	// low-activity users lose their last few events (churn simulation)
+	const profile = meta.profile;
+	record.forEach(e => {
+		e.color = profile.color;
+		e.number = profile.number;
+		// engagement_score intentionally varies per event (set by event hook)
+	});
+	if (record.length > 3 && record.length < 8) {
+		// users with few events lose the tail end — simulates churn
+		return record.slice(0, Math.ceil(record.length * 0.6));
+	}
+	return record;
+}
+
+// ── CONFIG ──
 /** @type {import('../types.js').Dungeon} */
 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: false, //if true, anonymousIds are created for each user
-	hasSessionIds: false, //if true, hasSessionIds are created for each user
-	alsoInferFunnels: true, //if true, infer funnels from events
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: false, //if true, hasSessionIds are created for each user
+		alsoInferFunnels: true, //if true, infer funnels from events
+	},
 	writeToDisk: false,
 	concurrency: 1,
 	funnels: [
 		{
-			sequence: ["qux", "garply", "durtle", "linny", "fonk", "crumn", "yak"],			
+			sequence: ["qux", "garply", "durtle", "linny", "fonk", "crumn", "yak"],
 		},
 		{
 			sequence: ["foo", "bar", "baz"],
@@ -115,7 +155,7 @@ const config = {
 		}
 	],
 	superProps: {
-		color: ["red", "orange", "yellow", "green", "blue", "indigo", "violet"],
+		color: colors,
 		number: integer,
 		engagement_score: [0],
 	},
@@ -123,51 +163,17 @@ const config = {
 		title: chance.profession.bind(chance),
 		luckyNumber: weighNumRange(42, 420),
 		userTier: ["regular"],
-		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"],
-		color: ["red", "orange", "yellow", "green", "blue", "indigo", "violet"],
+		spiritAnimal: spiritAnimals,
+		color: colors,
 		number: integer,
 		engagement_score: [0],
 	},
 	hook: function (record, type, meta) {
-		// --- user hook: tag power users based on luckyNumber ---
-		if (type === "user") {
-			record.userTier = record.luckyNumber > 300 ? "power" : "regular";
-			return record;
-		}
-
-		// --- event hook: add an engagement score based on event type ---
-		if (type === "event") {
-			const highEngagement = ["fonk", "crumn", "yak"];
-			const midEngagement = ["garply", "durtle", "linny"];
-			if (highEngagement.includes(record.event)) {
-				record.engagement_score = chance.integer({ min: 70, max: 100 });
-			} else if (midEngagement.includes(record.event)) {
-				record.engagement_score = chance.integer({ min: 30, max: 69 });
-			} else {
-				record.engagement_score = chance.integer({ min: 1, max: 29 });
-			}
-			return record;
-		}
-
-		// --- everything hook: low-activity users lose their last few events (churn simulation) ---
-		if (type === "everything") {
-			const profile = meta.profile;
-			record.forEach(e => {
-				e.color = profile.color;
-				e.number = profile.number;
-				// engagement_score intentionally varies per event (set by event hook)
-			});
-			if (record.length > 3 && record.length < 8) {
-				// users with few events lose the tail end — simulates churn
-				return record.slice(0, Math.ceil(record.length * 0.6));
-			}
-			return record;
-		}
-
+		if (type === "user") return handleUserHook(record);
+		if (type === "event") return handleEventHook(record);
+		if (type === "everything") return handleEverythingHook(record, meta);
 		return record;
 	}
 };
 
-
-
-export default config;
+export default config;

package/dungeons/technical/scale-test.js

@@ -1,13 +1,4 @@
-// ── TWEAK THESE ──
-const SEED = "scale test";
-const num_days = 365;
-const num_users = 10_000;
-const avg_events_per_user_per_day = 0.14;
-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";
@@ -15,26 +6,27 @@ import utc from "dayjs/plugin/utc.js";
 dayjs.extend(utc);
 import { uid, comma } from 'ak-tools';
 import { weighNumRange, date, integer, weighChoices } from "../../lib/utils/utils.js";
-
 /** @typedef {import("../../types").Dungeon} Config */
-/**
- * ═══════════════════════════════════════════════════════════════
- * TECHNICAL TEST: Scale & Performance
- * ═══════════════════════════════════════════════════════════════
- *
- * Tests high-volume generation, batch sizing, gzip compression.
- * - 10,000 users, 500K events, 365 days (1 year)
- * - gzip enabled, large batch size
- * - Minimal event schema (3 events, few properties)
- * - No hooks, no funnels, no extras
- *
- * Explicitly for performance benchmarking and verifying
- * large file output + batch splitting behavior.
+
+// ── OVERVIEW ──
+/*
+ * NAME:       scale-test
+ * PURPOSE:    High-volume scale fixture — exercises batch sizing, gzip, large file output, no hooks
+ * SCALE:      10,000 users, ~500K events, 365 days
+ * EVENTS (3): page view, click, api call
+ * FUNNELS (0): none
  */
 
-/** @type {import('../../types').Dungeon} */
+// ── SCALE ──
+const SEED = "scale test";
+const num_days = 365;
+const num_users = 10_000;
+const avg_events_per_user_per_day = 0.14;
+const token = process.env.MP_TOKEN || "";
+
+// ── CONFIG ──
+/** @type {Config} */
 const config = {
-	token,
 	seed: SEED,
 	name: "scale-test",
 	numDays: num_days,
@@ -43,18 +35,22 @@ const config = {
 	format: 'json',
 	gzip: true,
 	concurrency: 1,
-	region: "US",
-	hasAnonIds: false,
-	hasSessionIds: false,
-	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,
+		hasAdSpend: false,
+		hasLocation: false,
+		hasAndroidDevices: false,
+		hasIOSDevices: false,
+		hasDesktopDevices: false,
+		hasBrowser: false,
+		hasCampaigns: false,
+		isAnonymous: false,
+		alsoInferFunnels: false,
+	},
 	writeToDisk: false,
 
 	events: [