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

package/dungeons/technical/mirror-strategies.js

@@ -1,49 +1,47 @@
-// ── TWEAK THESE ──
-const SEED = "mirror-strategies";
-const num_days = 30;
-const num_users = 500;
-const avg_events_per_user_per_day = 2;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+// ── IMPORTS ──
+import { weighNumRange } from "../../lib/utils/utils.js";
+/** @typedef {import("../../types").Dungeon} Config */
 
-/**
- * Mirror Strategies — tests all 4 mirror data strategies.
- *
- * Exercises: create, update, fill, delete mirror transformations.
- * Each mirror prop targets a different event and uses a different
- * strategy so the output can be diffed against the original data.
- *
- * - 500 users, 30K events, 30 days
- * - 5 simple events, no funnels, no hooks
+// ── OVERVIEW ──
+/*
+ * NAME:       mirror-strategies
+ * PURPOSE:    exercises all 4 mirrorProps strategies (create, update, fill, delete)
+ * SCALE:      500 users, ~30K events, 30 days
+ * EVENTS (5): page view, checkout, profile update, subscription change, login
+ * FUNNELS (0): none
  */
 
-import Chance from 'chance';
-let chance = new Chance();
-import { weighNumRange, weighChoices } from "../../lib/utils/utils.js";
+// ── SCALE ──
+const SEED = "mirror-strategies";
+const NUM_DAYS = 30;
+const NUM_USERS = 500;
+const EVENTS_PER_DAY = 2;
+const token = process.env.MP_TOKEN || "";
 
-/** @typedef {import("../../types").Dungeon} Config */
-/** @type {import('../../types').Dungeon} */
+// ── 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",
-	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,
+	},
 	concurrency: 1,
 	writeToDisk: false,
 

package/dungeons/technical/nested-objects.js

@@ -1,35 +1,31 @@
-// ── TWEAK THESE ──
-const SEED = "dm4-nested-objects";
-const num_days = 30;
-const num_users = 500;
-const avg_events_per_user_per_day = 2;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
-
-import Chance from 'chance';
-let chance = new Chance();
+// ── IMPORTS ──
+import Chance from "chance";
 import dayjs from "dayjs";
 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";
-
+import { weighNumRange, integer } from "../../lib/utils/utils.js";
 /** @typedef {import("../../types").Dungeon} Config */
-/**
- * ═══════════════════════════════════════════════════════════════
- * TECHNICAL TEST: Nested Objects & High Cardinality
- * ═══════════════════════════════════════════════════════════════
- *
- * Tests Mixpanel's handling of:
- * - Array-of-object event properties (cart items, search results, form fields)
- * - Deeply nested object properties (metadata.browser.name, etc.)
- * - High cardinality string properties (10K product IDs, unique session IDs)
- *
- * 500 users, 30K events, 30 days. No hooks.
+
+// ── OVERVIEW ──
+/*
+ * NAME:       nested-objects
+ * PURPOSE:    Exercises array-of-object event properties, deeply nested object
+ *             properties, and high-cardinality string properties.
+ * SCALE:      500 users, ~30K events, 30 days
+ * EVENTS (4): checkout, search performed, form submitted, page view
+ * FUNNELS (0): none
  */
 
+// ── SCALE ──
+const SEED = "dm4-nested-objects";
+const NUM_DAYS = 30;
+const NUM_USERS = 500;
+const EVENTS_PER_DAY = 2;
+const token = process.env.MP_TOKEN || "";
+
+const chance = new Chance();
+
+// ── DATA ARRAYS ──
 const productCategories = ["electronics", "books", "clothing", "home", "garden", "toys", "sports", "automotive", "beauty", "health", "grocery", "jewelry", "shoes", "tools", "office"];
 const browsers = ["Chrome", "Firefox", "Safari", "Edge", "Opera", "Brave"];
 const browserVersions = ["120.0", "121.0", "119.0", "118.0", "117.0", "116.0", "115.0"];
@@ -38,98 +34,7 @@ const osList = ["Windows 11", "macOS 14", "iOS 17", "Android 14", "Linux", "Chro
 const cities = ["New York", "London", "Tokyo", "Berlin", "Sydney", "Toronto", "Paris", "Mumbai", "Seoul", "Mexico City", "Cairo", "Lagos", "Dubai", "Bangkok", "Istanbul"];
 const countries = ["US", "UK", "JP", "DE", "AU", "CA", "FR", "IN", "KR", "MX", "EG", "NG", "AE", "TH", "TR"];
 
-/** @type {import('../../types').Dungeon} */
-const config = {
-	token,
-	seed: SEED,
-	name: "nested-objects",
-	numDays: num_days,
-	avgEventsPerUserPerDay: avg_events_per_user_per_day,
-	numUsers: num_users,
-	format: 'json',
-	region: "US",
-	hasAnonIds: false,
-	hasSessionIds: false,
-	hasAdSpend: false,
-	hasLocation: false,
-	hasAndroidDevices: false,
-	hasIOSDevices: false,
-	hasDesktopDevices: true,
-	hasBrowser: false,
-	hasCampaigns: false,
-	isAnonymous: false,
-	alsoInferFunnels: false,
-	concurrency: 1,
-	writeToDisk: false,
-
-	events: [
-		{
-			event: "checkout",
-			weight: 3,
-			properties: {
-				// Array of objects: cart items
-				cart: makeCartItems(),
-				total_amount: weighNumRange(10, 2000, .25),
-				currency: ["USD", "EUR", "GBP", "JPY", "CAD"],
-				// High cardinality: unique session per event
-				session_id: () => chance.guid(),
-				// Deeply nested metadata
-				metadata: makeMetadata(),
-			}
-		},
-		{
-			event: "search performed",
-			weight: 5,
-			properties: {
-				query: ["laptop", "shoes", "headphones", "jacket", "phone case", "coffee maker", "backpack", "monitor", "keyboard", "mouse"],
-				// Array of objects: search results
-				results: makeSearchResults(),
-				result_count: weighNumRange(0, 50),
-				// High cardinality product ID
-				top_result_id: () => `prod_${integer(1, 10000)}`,
-				session_id: () => chance.guid(),
-				metadata: makeMetadata(),
-			}
-		},
-		{
-			event: "form submitted",
-			weight: 4,
-			properties: {
-				form_name: ["checkout", "signup", "contact", "feedback", "settings", "profile"],
-				// Array of objects: form fields
-				fields: makeFormFields(),
-				submission_valid: [true, true, true, false],
-				session_id: () => chance.guid(),
-				metadata: makeMetadata(),
-			}
-		},
-		{
-			event: "page view",
-			weight: 8,
-			properties: {
-				page: ["/", "/products", "/cart", "/search", "/account", "/help", "/about"],
-				// High cardinality
-				product_id: () => `prod_${integer(1, 10000)}`,
-				session_id: () => chance.guid(),
-				metadata: makeMetadata(),
-			}
-		},
-	],
-	funnels: [],
-	superProps: {},
-	userProps: {
-		plan: ["free", "basic", "pro", "enterprise"],
-	},
-	scdProps: {},
-	mirrorProps: {},
-	groupKeys: [],
-	groupProps: {},
-	lookupTables: [],
-	hook: function (record, type, meta) {
-		return record;
-	}
-};
-
+// ── HELPER FUNCTIONS ──
 /**
  * Generates an array-of-objects property for cart items.
  * Each cart has 1-5 items with product_id, name, price, quantity, category.
@@ -215,4 +120,100 @@ function makeMetadata() {
 	};
 }
 
+// ── CONFIG ──
+/** @type {Config} */
+const config = {
+	seed: SEED,
+	name: "nested-objects",
+	numDays: NUM_DAYS,
+	avgEventsPerUserPerDay: EVENTS_PER_DAY,
+	numUsers: NUM_USERS,
+	format: 'json',
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: false,
+		hasAdSpend: false,
+		hasLocation: false,
+		hasAndroidDevices: false,
+		hasIOSDevices: false,
+		hasDesktopDevices: true,
+		hasBrowser: false,
+		hasCampaigns: false,
+		isAnonymous: false,
+		alsoInferFunnels: false,
+	},
+	concurrency: 1,
+	writeToDisk: false,
+
+	events: [
+		{
+			event: "checkout",
+			weight: 3,
+			properties: {
+				// Array of objects: cart items
+				cart: makeCartItems(),
+				total_amount: weighNumRange(10, 2000, .25),
+				currency: ["USD", "EUR", "GBP", "JPY", "CAD"],
+				// High cardinality: unique session per event
+				session_id: () => chance.guid(),
+				// Deeply nested metadata
+				metadata: makeMetadata(),
+			}
+		},
+		{
+			event: "search performed",
+			weight: 5,
+			properties: {
+				query: ["laptop", "shoes", "headphones", "jacket", "phone case", "coffee maker", "backpack", "monitor", "keyboard", "mouse"],
+				// Array of objects: search results
+				results: makeSearchResults(),
+				result_count: weighNumRange(0, 50),
+				// High cardinality product ID
+				top_result_id: () => `prod_${integer(1, 10000)}`,
+				session_id: () => chance.guid(),
+				metadata: makeMetadata(),
+			}
+		},
+		{
+			event: "form submitted",
+			weight: 4,
+			properties: {
+				form_name: ["checkout", "signup", "contact", "feedback", "settings", "profile"],
+				// Array of objects: form fields
+				fields: makeFormFields(),
+				submission_valid: [true, true, true, false],
+				session_id: () => chance.guid(),
+				metadata: makeMetadata(),
+			}
+		},
+		{
+			event: "page view",
+			weight: 8,
+			properties: {
+				page: ["/", "/products", "/cart", "/search", "/account", "/help", "/about"],
+				// High cardinality
+				product_id: () => `prod_${integer(1, 10000)}`,
+				session_id: () => chance.guid(),
+				metadata: makeMetadata(),
+			}
+		},
+	],
+	funnels: [],
+	superProps: {},
+	userProps: {
+		plan: ["free", "basic", "pro", "enterprise"],
+	},
+	scdProps: {},
+	mirrorProps: {},
+	groupKeys: [],
+	groupProps: {},
+	lookupTables: [],
+	hook: function (record, type, meta) {
+		return record;
+	}
+};
+
 export default config;

package/dungeons/technical/pattern-aggregate-by-bin.js

@@ -1,15 +1,29 @@
-/**
- * Phase 4 reference dungeon — aggregate per user, by bin.
- *
- * Users in the high-Browse cohort have 4× higher Purchase amounts on average;
- * mid cohort 2×; low cohort 1×. Verified via the aggregatePerUser emulator.
- */
-
+// ── IMPORTS ──
 import dayjs from 'dayjs';
 import { applyAggregateByBin } from '../../lib/hook-patterns/index.js';
 
+// ── OVERVIEW ──
+/*
+ * NAME:       pattern-aggregate-by-bin
+ * PURPOSE:    Phase 4 reference fixture — aggregate per user, by bin. Users in
+ *             the high-Browse cohort have 4× higher Purchase amounts on average;
+ *             mid 2×; low 1×. Verified via the aggregatePerUser emulator.
+ * SCALE:      1,000 users, ~180K events, 30 days
+ * EVENTS (2): Browse (6) > Purchase (2)
+ * FUNNELS (0): none
+ */
+
+// ── HOOK STORIES ──
+/*
+ * PATTERN: Bin users by Browse count (low 0-5, mid 5-15, high 15+);
+ * scale Purchase `amount` by {low:1, mid:2, high:4}. Verified via
+ * the aggregatePerUser emulator.
+ */
+
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── CONFIG ──
 export default {
 	name: 'pattern-agg-by-bin',
 	seed: 'phase4-aggbybin',
@@ -18,7 +32,6 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 6,
 	percentUsersBornInDataset: 30,
-	hasAnonIds: false,
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,

package/dungeons/technical/pattern-attributed-by-source.js

@@ -1,16 +1,31 @@
-/**
- * Phase 4 reference dungeon — conversions attributed by source.
- *
- * Touch events carry one of three random sources; conversions are stamped with
- * the user's first-touch source weighted google:facebook:twitter = 10:5:1.
- * Verified via the attributedBy emulator.
- */
-
+// ── IMPORTS ──
 import dayjs from 'dayjs';
 import { applyAttributedBySource } from '../../lib/hook-patterns/index.js';
 
+// ── OVERVIEW ──
+/*
+ * NAME:       pattern-attributed-by-source
+ * PURPOSE:    Phase 4 reference fixture — conversions attributed by source.
+ *             Touch events carry one of three random sources; conversions are
+ *             stamped with the user's first-touch source weighted
+ *             google:facebook:twitter = 10:5:1. Verified via the attributedBy
+ *             emulator.
+ * SCALE:      1,000 users, ~120K events, 30 days
+ * EVENTS (2): Touch (5) > Convert (2)
+ * FUNNELS (0): none
+ */
+
+// ── HOOK STORIES ──
+/*
+ * PATTERN: First-touch attribution — stamp each Convert event with the
+ * source of the user's first Touch, weighted google:facebook:twitter =
+ * 10:5:1. Verified via the attributedBy emulator.
+ */
+
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── CONFIG ──
 export default {
 	name: 'pattern-attributed-by-source',
 	seed: 'phase4-attrib',
@@ -19,7 +34,6 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 4,
 	percentUsersBornInDataset: 50,
-	hasAnonIds: false,
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,

package/dungeons/technical/pattern-frequency-by-frequency.js

@@ -1,15 +1,29 @@
-/**
- * Phase 4 reference dungeon — frequency × frequency.
- *
- * Engages users into low / mid / high "Browse" cohorts; high-cohort users get 3×
- * Purchase events. Verified by the Phase 4 patterns test + verify-runner.
- */
-
+// ── IMPORTS ──
 import dayjs from 'dayjs';
 import { applyFrequencyByFrequency } from '../../lib/hook-patterns/index.js';
 
+// ── OVERVIEW ──
+/*
+ * NAME:       pattern-frequency-by-frequency
+ * PURPOSE:    Phase 4 reference fixture — frequency × frequency. Engages users
+ *             into low/mid/high "Browse" cohorts; high-cohort users get 3×
+ *             Purchase events. Verified by the Phase 4 patterns test + verify-runner.
+ * SCALE:      1,000 users, ~180K events, 30 days
+ * EVENTS (2): Browse (6) > Purchase (2)
+ * FUNNELS (0): none
+ */
+
+// ── HOOK STORIES ──
+/*
+ * PATTERN: Bin users by Browse count (low 0-5, mid 5-15, high 15+);
+ * scale Purchase event count by {low:1, mid:2, high:3}. Verified via
+ * the frequencyByFrequency emulator.
+ */
+
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── CONFIG ──
 export default {
 	name: 'pattern-freq-by-freq',
 	seed: 'phase4-freqxfreq',
@@ -18,7 +32,6 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 6,
 	percentUsersBornInDataset: 30,
-	hasAnonIds: false,
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,

package/dungeons/technical/pattern-funnel-frequency.js

@@ -1,20 +1,39 @@
-/**
- * Phase 4 reference dungeon — funnel frequency breakdown.
- *
- * Engaged-cohort users (high count of `Browse`) are 1.5× more likely to complete
- * the activation funnel's last step than low-cohort users. Verified via the
- * funnelFrequency emulator.
+// ── IMPORTS ──
+import dayjs from 'dayjs';
+import { applyFunnelFrequencyBreakdown } from '../../lib/hook-patterns/index.js';
+
+// ── OVERVIEW ──
+/*
+ * NAME:       pattern-funnel-frequency
+ * PURPOSE:    Phase 4 reference fixture — funnel frequency breakdown.
+ *             Engaged-cohort users (high count of `Browse`) are 1.5× more likely
+ *             to complete the activation funnel's last step than low-cohort
+ *             users. Verified via the funnelFrequency emulator.
+ * SCALE:      1,000 users, ~120K events, 30 days
+ * EVENTS (4): Browse (5) > Land (1) > Sign Up (1) > Activate (1)
+ * FUNNELS (1): Activation: Land → Sign Up → Activate (70%)
+ */
+
+// ── HOOK STORIES ──
+/*
+ * PATTERN: Bin users by Browse count (low 0-3, high 3+); within funnel-post,
+ * drop final-step `Activate` events at rates {low:0.5, high:0.95}, lifting
+ * the high cohort's conversion-per-step.
  *
- * Note: this pattern is funnel-post; it edits the funnel's own events. Combined
- * with the per-user funnel attempts, the breakdown should show a stronger
+ * Note: this pattern is funnel-post; it edits the funnel's own events.
+ * Combined with per-user funnel attempts, the breakdown shows a stronger
  * conversion-per-step lift in the high cohort.
+ *
+ * In funnel-post we don't have the user's full event stream — the pattern
+ * accepts null for `allUserEvents` and falls back to counting cohortEvent
+ * inside the funnel-only events. Real dungeons usually wire this via
+ * `everything` instead.
  */
 
-import dayjs from 'dayjs';
-import { applyFunnelFrequencyBreakdown } from '../../lib/hook-patterns/index.js';
-
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── CONFIG ──
 export default {
 	name: 'pattern-funnel-freq',
 	seed: 'phase4-funnel-freq',
@@ -23,7 +42,6 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 4,
 	percentUsersBornInDataset: 100,
-	hasAnonIds: false,
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,
@@ -41,9 +59,6 @@ export default {
 	hook: function (record, type, meta) {
 		if (type !== 'funnel-post' || !Array.isArray(record)) return;
 		if (!meta.isFirstFunnel) return;
-		// In funnel-post we don't have the user's full event stream — pattern accepts
-		// null for `allUserEvents` and falls back to counting cohortEvent inside the
-		// funnel-only events. Real dungeons usually wire this via `everything` instead.
 		applyFunnelFrequencyBreakdown(null, meta.profile || {}, record, {
 			cohortEvent: 'Browse',
 			bins: { low: [0, 3], high: [3, Infinity] },

package/dungeons/technical/pattern-ttc-by-segment.js

@@ -1,15 +1,29 @@
-/**
- * Phase 4 reference dungeon — time to convert by segment.
- *
- * Trial users take 4× longer to complete the activation funnel than enterprise
- * users (0.5× faster). Verified via the timeToConvert emulator.
- */
-
+// ── IMPORTS ──
 import dayjs from 'dayjs';
 import { applyTTCBySegment } from '../../lib/hook-patterns/index.js';
 
+// ── OVERVIEW ──
+/*
+ * NAME:       pattern-ttc-by-segment
+ * PURPOSE:    Phase 4 reference fixture — time-to-convert by segment. Trial
+ *             users take 4× longer to complete the activation funnel; enterprise
+ *             0.5× faster. Verified via the timeToConvert emulator.
+ * SCALE:      1,000 users, ~120K events, 30 days
+ * EVENTS (4): Browse (5) > Land (1) > Sign Up (1) > Activate (1)
+ * FUNNELS (1): Activation: Land → Sign Up → Activate (100%)
+ */
+
+// ── HOOK STORIES ──
+/*
+ * PATTERN: Scale the activation funnel's time-to-convert by user tier:
+ * trial users 4× slower, enterprise 0.5× faster. Verified via the
+ * timeToConvert emulator.
+ */
+
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── CONFIG ──
 export default {
 	name: 'pattern-ttc-by-segment',
 	seed: 'phase4-ttc-seg',
@@ -18,7 +32,6 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 4,
 	percentUsersBornInDataset: 100,
-	hasAnonIds: false,
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,