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

package/dungeons/technical/experiments.js

@@ -1,50 +1,52 @@
-// ── TWEAK THESE ──
-const SEED = "experiments";
-const num_days = 60;
-const num_users = 2_000;
-const avg_events_per_user_per_day = 0.83;
-let token = "";
-
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+// ── IMPORTS ──
+import Chance from "chance";
+import { weighNumRange, weighChoices } from "../../lib/utils/utils.js";
+/** @typedef {import("../../types").Dungeon} Config */
 
-/**
- * Experiments — tests funnel experiments with A/B/C variants.
- *
- * Exercises: experiment: true for variant generation, bindPropsIndex
- * for property binding, and multiple funnel ordering modes
- * (sequential, random, first-and-last-fixed).
- *
- * - 2000 users, 100K events, 60 days
- * - 7 events, 4 funnels with different experiment/order configs
- * - No hooks
+// ── OVERVIEW ──
+/*
+ * NAME:       experiments
+ * PURPOSE:    Exercises funnel experiments (A/B/C variants), bindPropsIndex,
+ *             and multiple funnel ordering modes (sequential, first-and-last-fixed, random).
+ * SCALE:      2,000 users, ~100K events, 60 days
+ * EVENTS (7): page view, signup, feature viewed, action taken, checkout, button click, help viewed
+ * FUNNELS (4): Onboarding Flow (sequential, experiment), Purchase Funnel (first-and-last-fixed, experiment),
+ *              Feature Adoption (random, experiment, bindPropsIndex), Quick Signup (sequential, control)
  */
 
-import Chance from 'chance';
-let chance = new Chance();
-import { weighNumRange, weighChoices } from "../../lib/utils/utils.js";
+// ── SCALE ──
+const SEED = "experiments";
+const NUM_DAYS = 60;
+const NUM_USERS = 2_000;
+const EVENTS_PER_DAY = 0.83;
+const token = process.env.MP_TOKEN || "";
 
-/** @typedef {import("../../types").Dungeon} Config */
-/** @type {import('../../types').Dungeon} */
+const chance = new Chance();
+
+// ── 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: true,
-	hasAdSpend: false,
-	hasLocation: false,
-	hasAndroidDevices: true,
-	hasIOSDevices: true,
-	hasDesktopDevices: true,
-	hasBrowser: true,
-	hasCampaigns: false,
-	isAnonymous: false,
-	alsoInferFunnels: false,
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: true,
+		hasAdSpend: false,
+		hasLocation: false,
+		hasAndroidDevices: true,
+		hasIOSDevices: true,
+		hasDesktopDevices: true,
+		hasBrowser: true,
+		hasCampaigns: false,
+		isAnonymous: false,
+		alsoInferFunnels: false,
+	},
 	concurrency: 1,
 	writeToDisk: false,
 

package/dungeons/technical/foobar.js

@@ -1,63 +1,39 @@
-// ── TWEAK THESE ──
-const SEED = "dm4-foobar";
-const num_days = 30;
-const num_users = 4_000_000;
-const avg_events_per_user_per_day = 16.67;
-let token = "";
+// ── IMPORTS ──
+/** @typedef {import("../../types").Dungeon} Config */
 
-// ── env overrides ──
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+// ── OVERVIEW ──
+/*
+ * NAME:       foobar
+ * PURPOSE:    minimal stress/sanity dungeon — abstract event names, weight-driven distribution, no funnels, no event properties
+ * SCALE:      4,000,000 users, ~2B events, 30 days (configurable for stress testing)
+ * EVENTS (10): foo, bar, baz, qux, garply, durtle, linny, fonk, crumn, yak
+ * FUNNELS (0): none
+ */
 
-/**
- * ═══════════════════════════════════════════════════════════════
- * DATASET OVERVIEW
- * ═══════════════════════════════════════════════════════════════
- *
- * Foobar — minimal test/sanity dungeon with abstract event names.
- * - Configurable scale (default 2 billion events for stress testing)
- * - 10 events: foo, bar, baz, qux, garply, durtle, linny, fonk, crumn, yak
- * - Super props: string, number, boolean, date
- * - No funnels, no properties on events — pure weight-driven distribution
- *
- * ═══════════════════════════════════════════════════════════════
- * ANALYTICS HOOKS (2 patterns)
- * ═══════════════════════════════════════════════════════════════
- *
+// ── HOOK STORIES ──
+/*
  * 1. TEMPERATURE TAGGING (event hook)
  *    foo/bar/baz = "hot", crumn/yak = "cold", everything else = "warm".
- *
- *    Mixpanel Report:
- *    - Insights: any event, total events, breakdown by temperature
- *      Expected: "hot" dominates (highest-weight events)
+ *    Mixpanel report: Insights, any event, total events, breakdown by temperature.
+ *    Expected: "hot" dominates (highest-weight events).
  *
  * 2. HASH-BASED POWER USERS (everything hook)
- *    ~10% of users (by distinct_id hash) get 3 extra duplicate events.
- *
- *    Mixpanel Report:
- *    - Insights: any event, total per user, breakdown by is_duplicate
- *      Expected: ~10% of users have extra events tagged is_duplicate=true
+ *    ~10% of users (by distinct_id charCode mod 10) get 3 extra duplicate events
+ *    tagged is_duplicate=true.
+ *    Mixpanel report: Insights, any event, total per user, breakdown by is_duplicate.
+ *    Expected: ~10% of users have extra events tagged is_duplicate=true.
  */
 
+// ── SCALE ──
+const SEED = "dm4-foobar";
+const NUM_DAYS = 30;
+const NUM_USERS = 4_000_000;
+const EVENTS_PER_DAY = 16.67;
+const token = process.env.MP_TOKEN || "";
 
-
-
-function integer(min = 1, max = 100) {
-	// If min equals max, just return the value
-	if (min === max) {
-		return min;
-	}
-
-	// Swap min and max if min is greater than max
-	if (min > max) {
-		[min, max] = [max, min];
-	}
-
-	// Generate a random integer between min and max (inclusive)
-	return Math.floor(Math.random() * (max - min + 1)) + min;
-}
-
-/** @typedef {import("../../types").Dungeon} Config */
-
+// ── DATA ARRAYS ──
+const colors = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
+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 dates = [
 	"2024-09-18T21:48:28.173Z",
 	"2024-12-09T03:17:46.661Z",
@@ -161,26 +137,88 @@ const dates = [
 	"2024-06-03T06:52:21.652Z"
 ];
 
-/** @type {import('../../types').Dungeon} */
+// ── HELPER FUNCTIONS ──
+function integer(min = 1, max = 100) {
+	// If min equals max, just return the value
+	if (min === max) {
+		return min;
+	}
+
+	// Swap min and max if min is greater than max
+	if (min > max) {
+		[min, max] = [max, min];
+	}
+
+	// Generate a random integer between min and max (inclusive)
+	return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+function handleEventHook(record) {
+	// H1: temperature tagging — high-weight events "hot", low-weight "cold", rest "warm"
+	const hotEvents = ["foo", "bar", "baz"];
+	const coldEvents = ["crumn", "yak"];
+	if (hotEvents.includes(record.event)) {
+		record.temperature = "hot";
+	} else if (coldEvents.includes(record.event)) {
+		record.temperature = "cold";
+	} else {
+		record.temperature = "warm";
+	}
+	return record;
+}
+
+function handleEverythingHook(record, meta) {
+	// stamp profile-derived superProps for consistency
+	const profile = meta.profile;
+	record.forEach(e => {
+		e.string = profile.string;
+		e.number = profile.number;
+		e.boolean = profile.boolean;
+		e.date = profile.date;
+		e.temperature = profile.temperature;
+	});
+
+	// H2: hash-based power users — ~10% of users (distinct_id charCode mod 10) get 3 extra duplicate events
+	if (record.length > 0) {
+		const userId = record[0].user_id || record[0].distinct_id || "";
+		if (userId && userId.charCodeAt(0) % 10 === 0) {
+			const extras = record.slice(0, 3).map(e => ({
+				...e,
+				event: e.event,
+				user_id: e.user_id,
+				time: e.time,
+				is_duplicate: true,
+			}));
+			return record.concat(extras);
+		}
+	}
+	return record;
+}
+
+// ── 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: false, //if true, anonymousIds are created for each user
-	hasSessionIds: false, //if true, hasSessionIds are created for each user
-	hasAdSpend: false,
-	hasAvatar: false,
-	hasBrowser: false,
-	hasCampaigns: false,
-	hasIOSDevices: false,
-	hasLocation: false,
-	isAnonymous: true,
-	hasAndroidDevices: false,
-	hasDesktopDevices: false,
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: false, //if true, hasSessionIds are created for each user
+		hasAdSpend: false,
+		hasAvatar: false,
+		hasBrowser: false,
+		hasCampaigns: false,
+		hasIOSDevices: false,
+		hasLocation: false,
+		isAnonymous: true,
+		hasAndroidDevices: false,
+		hasDesktopDevices: false,
+	},
 	writeToDisk: false,
 	concurrency: 1,
 
@@ -237,7 +275,7 @@ const config = {
 		}
 	],
 	superProps: {
-		string: ["red", "orange", "yellow", "green", "blue", "indigo", "violet"],
+		string: colors,
 		number: integer,
 		boolean: [true, false],
 		date: dates,
@@ -245,9 +283,9 @@ const config = {
 	},
 	userProps: {
 		luckyNumber: integer,
-		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,
 		created: dates,
-		string: ["red", "orange", "yellow", "green", "blue", "indigo", "violet"],
+		string: colors,
 		number: integer,
 		boolean: [true, false],
 		date: dates,
@@ -257,56 +295,14 @@ const config = {
 	scdProps: {},
 	mirrorProps: {},
 	lookupTables: [],
-	groupKeys: [
-	],
-	groupProps: {
-	},
+	groupKeys: [],
+	groupProps: {},
 
 	hook: function (record, type, meta) {
-		// event hook: high-weight events get a "hot" flag, low-weight get "cold"
-		if (type === "event") {
-			const hotEvents = ["foo", "bar", "baz"];
-			const coldEvents = ["crumn", "yak"];
-			if (hotEvents.includes(record.event)) {
-				record.temperature = "hot";
-			} else if (coldEvents.includes(record.event)) {
-				record.temperature = "cold";
-			} else {
-				record.temperature = "warm";
-			}
-		}
-
-		// everything hook: hash-based cohort — 10% of users (by distinct_id) get doubled events
-		if (type === "everything") {
-			const profile = meta.profile;
-			record.forEach(e => {
-				e.string = profile.string;
-				e.number = profile.number;
-				e.boolean = profile.boolean;
-				e.date = profile.date;
-				e.temperature = profile.temperature;
-			});
-			if (record.length > 0) {
-				const userId = record[0].user_id || record[0].distinct_id || "";
-				if (userId && userId.charCodeAt(0) % 10 === 0) {
-					// power user: duplicate each event with a slight time offset
-					const extras = record.slice(0, 3).map(e => ({
-						...e,
-						event: e.event,
-						user_id: e.user_id,
-						time: e.time,
-						is_duplicate: true,
-					}));
-					return record.concat(extras);
-				}
-			}
-			return 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/group-analytics.js

@@ -1,50 +1,52 @@
-// ── TWEAK THESE ──
-const SEED = "group-analytics";
-const num_days = 60;
-const num_users = 500;
-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';
+import { weighNumRange, weighChoices } from "../../lib/utils/utils.js";
+/** @typedef {import("../../types").Dungeon} Config */
 
-/**
- * Group Analytics — tests multiple group keys with varied entity counts.
- *
- * Exercises: 3 group keys (company, team, project) at different scales,
- * each with distinct event associations and group-level properties.
- *
- * - 500 users, 30K events, 60 days
- * - 3 group keys: company_id (50), team_id (200), project_id (500)
- * - groupProps with varied property types per key
- * - No hooks
+// ── OVERVIEW ──
+/*
+ * NAME:       group-analytics
+ * PURPOSE:    exercises 3 groupKeys (company/team/project) at varied scales with per-key groupProps
+ * SCALE:      500 users, ~30K events, 60 days
+ * EVENTS (8): feature used, subscription change, support ticket, task completed,
+ *             meeting scheduled, code committed, deployment run, login
+ * FUNNELS (0): none
+ * GROUPS:     company_id (50), team_id (200), project_id (500)
  */
 
-import Chance from 'chance';
-let chance = new Chance();
-import { weighNumRange, weighChoices } from "../../lib/utils/utils.js";
+// ── SCALE ──
+const SEED = "group-analytics";
+const NUM_DAYS = 60;
+const NUM_USERS = 500;
+const EVENTS_PER_DAY = 1;
+const token = process.env.MP_TOKEN || "";
 
-/** @typedef {import("../../types").Dungeon} Config */
-/** @type {import('../../types').Dungeon} */
+const chance = new Chance();
+
+// ── 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: true,
-	hasBrowser: true,
-	hasCampaigns: false,
-	isAnonymous: false,
-	alsoInferFunnels: false,
+	credentials: {
+		token,
+		region: "US",
+	},
+	switches: {
+		hasSessionIds: false,
+		hasAdSpend: false,
+		hasLocation: false,
+		hasAndroidDevices: false,
+		hasIOSDevices: false,
+		hasDesktopDevices: true,
+		hasBrowser: true,
+		hasCampaigns: false,
+		isAnonymous: false,
+		alsoInferFunnels: false,
+	},
 	concurrency: 1,
 	writeToDisk: false,
 

package/dungeons/technical/hook-helpers-verify.js

@@ -1,28 +1,40 @@
-/**
- * Phase 3 hook-helpers verification fixture.
+// ── IMPORTS ──
+import dayjs from 'dayjs';
+import {
+	binUsersByEventCount,
+	scalePropertyValue,
+	injectBurst,
+	cloneEvent,
+} from '../../lib/hook-helpers/index.js';
+/** @typedef {import("../../types").Dungeon} Config */
+
+// ── OVERVIEW ──
+/*
+ * NAME:       hook-helpers-verify
+ * PURPOSE:    Phase 3 fixture — exercises binUsersByEventCount + scalePropertyValue + injectBurst atoms
+ * SCALE:      1,000 users, ~120K events, 30 days
+ * EVENTS (2): Browse, Purchase
+ * FUNNELS (0): none
  *
- * Exercises three atoms inside one `everything` hook:
+ * Verified by DuckDB queries against the events output (see
+ * scripts/verify-runner.mjs + the Phase 3 verification gate notes in the plan).
+ */
+
+// ── HOOK STORIES ──
+/*
+ * Inside one `everything` hook:
  *   1. `binUsersByEventCount` — classify users into "casual" / "engaged" / "power"
  *      based on their count of `Browse` events.
  *   2. `scalePropertyValue` — engaged users get 2x `amount` on Purchase events;
  *      power users get 3x.
  *   3. `injectBurst` — power users also get a burst of 5 cloned `Browse` events
  *      around the midpoint of their stream.
- *
- * Verified by DuckDB queries against the events output (see
- * scripts/verify-runner.mjs + the Phase 3 verification gate notes in the plan).
  */
 
-import dayjs from 'dayjs';
-import {
-	binUsersByEventCount,
-	scalePropertyValue,
-	injectBurst,
-	cloneEvent,
-} from '../../lib/hook-helpers/index.js';
-
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── KNOBS (tweak these to reshape stories) ──
 const BINS = {
 	casual: [0, 5],
 	engaged: [5, 15],
@@ -32,7 +44,46 @@ const BINS = {
 const SCALE_BY_BIN = { casual: 1, engaged: 2, power: 3 };
 const BURST_COUNT_BY_BIN = { casual: 0, engaged: 0, power: 5 };
 
-export default {
+// ── HELPER FUNCTIONS ──
+function handleEverythingHooks(record, meta) {
+	// 1. Classify the user via cohort atom
+	const bin = binUsersByEventCount(record, 'Browse', BINS);
+	if (!bin) return record;
+
+	// Stamp the bin onto each Purchase so verification queries can group by it
+	// without re-deriving. Non-flag-stamping: this property is config-defined when
+	// dungeons add `cohort` to Purchase.properties; here we accept the small bend
+	// for the verification fixture so DuckDB queries are clean.
+	for (const ev of record) {
+		if (ev.event === 'Purchase') ev.cohort = bin;
+	}
+
+	// 2. Scale Purchase amounts via mutate atom (engaged 2x, power 3x)
+	const factor = SCALE_BY_BIN[bin] || 1;
+	if (factor !== 1) {
+		scalePropertyValue(record, e => e.event === 'Purchase', 'amount', factor);
+	}
+
+	// 3. Power users get a Browse burst clustered at the dataset midpoint
+	const burstCount = BURST_COUNT_BY_BIN[bin] || 0;
+	if (burstCount > 0 && record.length) {
+		const midUnixMs = (meta.datasetStart + (meta.datasetEnd - meta.datasetStart) / 2) * 1000;
+		// Use the user's first Browse as a clone template so we honor the schema.
+		const template = record.find(e => e.event === 'Browse');
+		if (template) {
+			const tpl = cloneEvent(template, { cohort: bin });
+			injectBurst(record, tpl, burstCount, midUnixMs, 60 * 60 * 1000); // ±1h spread
+		}
+	}
+
+	// Re-sort by time after burst injection so downstream pipeline sees ordered events.
+	record.sort((a, b) => (a.time < b.time ? -1 : a.time > b.time ? 1 : 0));
+	return record;
+}
+
+// ── CONFIG ──
+/** @type {Config} */
+const config = {
 	name: 'hook-helpers-verify',
 	seed: 'phase3-helpers-verify',
 	datasetStart: FIXED_NOW - 30 * 86400,
@@ -40,7 +91,6 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 4,
 	percentUsersBornInDataset: 30,
-	hasAnonIds: false,
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,
@@ -51,39 +101,8 @@ export default {
 	],
 	hook: function (record, type, meta) {
 		if (type !== 'everything' || !Array.isArray(record)) return record;
-
-		// 1. Classify the user via cohort atom
-		const bin = binUsersByEventCount(record, 'Browse', BINS);
-		if (!bin) return record;
-
-		// Stamp the bin onto each Purchase so verification queries can group by it
-		// without re-deriving. Non-flag-stamping: this property is config-defined when
-		// dungeons add `cohort` to Purchase.properties; here we accept the small bend
-		// for the verification fixture so DuckDB queries are clean.
-		for (const ev of record) {
-			if (ev.event === 'Purchase') ev.cohort = bin;
-		}
-
-		// 2. Scale Purchase amounts via mutate atom (engaged 2x, power 3x)
-		const factor = SCALE_BY_BIN[bin] || 1;
-		if (factor !== 1) {
-			scalePropertyValue(record, e => e.event === 'Purchase', 'amount', factor);
-		}
-
-		// 3. Power users get a Browse burst clustered at the dataset midpoint
-		const burstCount = BURST_COUNT_BY_BIN[bin] || 0;
-		if (burstCount > 0 && record.length) {
-			const midUnixMs = (meta.datasetStart + (meta.datasetEnd - meta.datasetStart) / 2) * 1000;
-			// Use the user's first Browse as a clone template so we honor the schema.
-			const template = record.find(e => e.event === 'Browse');
-			if (template) {
-				const tpl = cloneEvent(template, { cohort: bin });
-				injectBurst(record, tpl, burstCount, midUnixMs, 60 * 60 * 1000); // ±1h spread
-			}
-		}
-
-		// Re-sort by time after burst injection so downstream pipeline sees ordered events.
-		record.sort((a, b) => (a.time < b.time ? -1 : a.time > b.time ? 1 : 0));
-		return record;
+		return handleEverythingHooks(record, meta);
 	},
 };
+
+export default config;

package/dungeons/technical/identity-model-verify.js

@@ -1,16 +1,23 @@
-/**
- * Phase 2 identity model — verification fixture (intentionally simple).
- *
- * 1K born-in-dataset users with isAuthEvent on `Sign Up` (the stitch step) and a
- * 3-step first funnel. Dataset window pinned for determinism. avgDevicePerUser:2
- * exercises the multi-device sticky-per-session model. Used by phase 2 verification
- * gate (DuckDB queries against the events output).
- */
-
+// ── IMPORTS ──
 import dayjs from 'dayjs';
 
+// ── OVERVIEW ──
+/*
+ * NAME:       identity-model-verify
+ * PURPOSE:    Phase 2 identity model verification fixture (intentionally simple).
+ *             1K born-in-dataset users with isAuthEvent on `Sign Up` (the stitch
+ *             step) and a 3-step first funnel. avgDevicePerUser:2 exercises the
+ *             multi-device sticky-per-session model. Used by the phase 2
+ *             verification gate (DuckDB queries against the events output).
+ * SCALE:      1,000 users, ~90K events, 30 days
+ * EVENTS (6): Browse (5) > Save Item (2) > Land (1) > View Pricing (1) > Sign Up (1) > Onboarding (1)
+ * FUNNELS (1): Acquisition: Land → View Pricing → Sign Up → Onboarding (80%, attempts 0-2)
+ */
+
+// ── SCALE ──
 const FIXED_NOW = dayjs('2024-02-02').unix();
 
+// ── CONFIG ──
 export default {
 	name: 'identity-model-verify',
 	seed: 'phase2-identity-verify',
@@ -19,9 +26,12 @@ export default {
 	numUsers: 1_000,
 	avgEventsPerUserPerDay: 3,
 	percentUsersBornInDataset: 100,
-	hasAnonIds: true,
-	avgDevicePerUser: 2,
-	hasSessionIds: true,
+	switches: {
+		hasSessionIds: true,
+	},
+	identity: {
+		avgDevicePerUser: 2,
+	},
 	format: 'json',
 	concurrency: 1,
 	writeToDisk: true,