@ak--47/dungeon-master 1.1.0 → 1.2.1

package/dungeons/vertical/travel.js

@@ -1,16 +1,23 @@
+// ── TWEAK THESE ──
+const SEED = "dm4-travel";
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user = 120;
+let token = "your-mixpanel-token";
+
+// ── env overrides ──
+if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 import "dotenv/config";
 import * as u from "../../lib/utils/utils.js";
 import * as v from "ak-tools";
 
-const SEED = "dm4-travel";
 dayjs.extend(utc);
 const chance = u.initChance(SEED);
-const num_users = 5_000;
-const days = 100;
 const NOW = dayjs();
-const DATASET_START = NOW.subtract(days, "days");
+const DATASET_START = NOW.subtract(num_days, "days");
 
 /** @typedef  {import("../../types").Dungeon} Config */
 
@@ -164,10 +171,10 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
  * with consistent, high-frequency booking patterns.
  *
  * ───────────────────────────────────────────────────────────────
- * 8. REPEAT DESTINATION CLUSTERING (funnel-pre hook)
+ * 8. REPEAT DESTINATION CLUSTERING (everything hook — event filtering)
  * ───────────────────────────────────────────────────────────────
- * PATTERN: Business travelers convert 1.3x better through the
- * search-to-book funnel (repeat bookings are habitual).
+ * PATTERN: Non-business/luxury users have ~25% of "booking completed"
+ * events dropped, simulating lower funnel conversion for casual segments.
  *
  * HOW TO FIND IT IN MIXPANEL:
  *   Report 1: Conversion by Segment
@@ -197,10 +204,10 @@ const destinationCities = ["New York", "London", "Paris", "Tokyo", "Barcelona",
 
 /** @type {Config} */
 const config = {
-	token: "",
+	token,
 	seed: SEED,
-	numDays: days,
-	numEvents: num_users * 120,
+	numDays: num_days,
+	numEvents: num_users * avg_events_per_user,
 	numUsers: num_users,
 	hasAnonIds: false,
 	hasSessionIds: true,
@@ -217,10 +224,16 @@ const config = {
 	hasAdSpend: false,
 	percentUsersBornInDataset: 35,
 	hasAvatar: true,
-	batchSize: 2_500_000,
 	concurrency: 1,
 	writeToDisk: false,
-	scdProps: {},
+	scdProps: {
+		membership_tier: {
+			values: ["member", "silver", "gold", "platinum"],
+			frequency: "month",
+			timing: "fuzzy",
+			max: 8
+		}
+	},
 	mirrorProps: {},
 	lookupTables: [],
 
@@ -439,7 +452,7 @@ const config = {
 
 	// ── SuperProps ──────────────────────────────────────────
 	superProps: {
-		platform: ["ios", "android", "web", "web"],
+		Platform: ["ios", "android", "web", "web"],
 		membership_tier: ["standard", "standard", "standard", "gold", "platinum"],
 	},
 
@@ -450,6 +463,8 @@ const config = {
 		company_name: ["none"],
 		preferred_destination: chance.pickone.bind(chance, destinationCities),
 		avg_budget_per_night: u.weighNumRange(50, 400, 0.4, 150),
+		Platform: ["ios", "android", "web", "web"],
+		membership_tier: ["standard", "standard", "standard", "gold", "platinum"],
 	},
 
 	// ── Personas ──────────────────────────────────
@@ -626,14 +641,10 @@ const config = {
 		}
 
 		// ── HOOK 8: REPEAT DESTINATION CLUSTERING (funnel-pre) ─
+		// conversionRate modifications moved to everything hook (event filtering)
+		// to avoid dilution by organic events
 		if (type === "funnel-pre") {
-			if (meta && meta.profile) {
-				if (meta.profile.customer_segment === "business_traveler") {
-					record.conversionRate = Math.min(record.conversionRate * 1.3, 90);
-				} else if (meta.profile.customer_segment === "luxury_seeker") {
-					record.conversionRate = Math.min(record.conversionRate * 1.15, 85);
-				}
-			}
+			// prop-setting only; no conversionRate changes
 		}
 
 		// ── HOOK 1: WEEKEND LEISURE SURGE (event) ────────────
@@ -666,6 +677,33 @@ const config = {
 			const events = record;
 			if (!events.length) return record;
 
+			const profile = meta.profile;
+
+			// ─── Stamp superProps from profile (consistent per user) ───
+			const stampPlatform = profile && profile.Platform ? profile.Platform : undefined;
+			const stampTier = profile && profile.membership_tier ? profile.membership_tier : undefined;
+			if (stampPlatform || stampTier) {
+				events.forEach(e => {
+					if (stampPlatform) e.Platform = stampPlatform;
+					if (stampTier) e.membership_tier = stampTier;
+				});
+			}
+
+			// ─── Bug 2 fix: Repeat destination clustering conversion filtering ───
+			// Drop ~25% of "booking completed" events for users who are NOT
+			// business_traveler or luxury_seeker to simulate their lower funnel
+			// conversion (was conversionRate * 1.3 / 1.15 in funnel-pre)
+			const segment = profile && profile.customer_segment;
+			if (segment !== "business_traveler" && segment !== "luxury_seeker") {
+				for (let i = events.length - 1; i >= 0; i--) {
+					if (events[i].event === "booking completed") {
+						if (chance.bool({ likelihood: 25 })) {
+							events.splice(i, 1);
+						}
+					}
+				}
+			}
+
 			// ── HOOK 3: LOYALTY TIER UPGRADE PATH ────────────
 			let bookingCount = 0;
 			events.forEach(e => { if (e.event === "booking completed") bookingCount++; });
@@ -688,7 +726,6 @@ const config = {
 			}
 
 			// ── HOOK 5: UPSELL SUCCESS BY SEGMENT ────────────
-			const profile = meta.profile;
 			if (profile && profile.customer_segment === "luxury_seeker") {
 				const templateUpgrade = events.find(e => e.event === "room upgrade selected");
 				if (templateUpgrade) {

package/index.js

@@ -109,6 +109,9 @@ async function DUNGEON_MASTER(input, overrides = {}) {
 			const textConfig = await loadFromText(value);
 			return await runDungeon({ ...textConfig, ...overrides });
 		}
+
+		default:
+			throw new Error(`Unexpected input type: ${type}`);
 	}
 }
 
@@ -216,7 +219,7 @@ async function runDungeon(config) {
 			files: await extractFileInfo(storage, validatedConfig),
 			time: { start, end, delta, human },
 			operations: context.getOperations(),
-			eventCount: context.getEventCount(),
+			eventCount: context.getStoredEventCount(),
 			userCount: context.getUserCount()
 		};
 

package/lib/core/config-validator.js

@@ -24,7 +24,6 @@ const FIXED_NOW = dayjs('2024-02-02').unix();
 function inferFunnels(events) {
 	const createdFunnels = [];
 	const firstEvents = events.filter((e) => e.isFirstEvent).map((e) => e.event);
-	const strictEvents = events.filter((e) => e.isStrictEvent).map((e) => e.event);
 	const usageEvents = events
 		.filter((e) => !e.isFirstEvent && !e.isStrictEvent)
 		.map((e) => e.event);
@@ -106,6 +105,7 @@ export function validateDungeonConfig(config) {
 		lookupTables = [],
 		hasAnonIds = false,
 		hasSessionIds = false,
+		sessionTimeout = 30,
 		format = "csv",
 		token = null,
 		region = "US",
@@ -140,6 +140,14 @@ export function validateDungeonConfig(config) {
 		concurrency = 1;
 	}
 
+	// Throw if token is the placeholder and nothing will be written to disk
+	if (token === "your-mixpanel-token" && !writeToDisk) {
+		throw new Error(
+			"No Mixpanel token set and writeToDisk is false — nothing useful will happen.\n" +
+			"Either set process.env.MP_TOKEN, change the token in the dungeon file, or set writeToDisk to true."
+		);
+	}
+
 	// Auto-enable batch mode for large datasets to prevent OOM
 	if (numEvents >= 2_000_000 && config.batchSize === undefined) {
 		batchSize = 1_000_000;
@@ -148,7 +156,9 @@ export function validateDungeonConfig(config) {
 
 	// Ensure defaults for deep objects
 	if (!config.superProps) config.superProps = superProps;
-	if (!config.userProps || Object.keys(config?.userProps || {})) config.userProps = userProps;
+	if (!config.userProps || Object.keys(config.userProps).length === 0) {
+		userProps = { spiritAnimal: chance.animal.bind(chance) };
+	}
 
 	// Setting up "TIME"
 	if (epochStart && !numDays) numDays = dayjs.unix(epochEnd).diff(dayjs.unix(epochStart), "day");
@@ -356,6 +366,7 @@ export function validateDungeonConfig(config) {
 		lookupTables,
 		hasAnonIds,
 		hasSessionIds,
+		sessionTimeout: (typeof sessionTimeout === 'number' && sessionTimeout > 0) ? sessionTimeout : 30,
 		format,
 		token,
 		region,

package/lib/core/context.js

@@ -71,6 +71,7 @@ function createRuntimeState() {
 	return {
 		operations: 0,
 		eventCount: 0,
+		storedEventCount: 0,
 		userCount: 0,
 		isBatchMode: false,
 		verbose: false
@@ -143,6 +144,14 @@ export function createContext(config, storage = null, timeConstants = {}) {
 			runtime.eventCount++;
 		},
 
+		incrementStoredEvents(count = 1) {
+			runtime.storedEventCount += count;
+		},
+
+		getStoredEventCount() {
+			return runtime.storedEventCount;
+		},
+
 		isBatchMode() {
 			return runtime.isBatchMode;
 		},

package/lib/core/storage.js

@@ -99,8 +99,10 @@ export async function createHookArray(arr = [], opts) {
 			// Fast path for passthrough hooks - no transformation needed
 			if (Array.isArray(item)) {
 				arr.push(...item);
+				if (type === "event" && context.incrementStoredEvents) context.incrementStoredEvents(item.length);
 			} else {
 				arr.push(item);
+				if (type === "event" && context.incrementStoredEvents) context.incrementStoredEvents(1);
 			}
 		} else {
 			// Slow path for actual transformation hooks

package/lib/generators/events.js

@@ -116,14 +116,12 @@ export async function makeEvent(
         eventTemplate.time = dayjs.unix(Math.min(shiftedTimestamp, context.MAX_TIME)).toISOString();
     }
 
-    // Add anonymous and session identifiers
+    // Add anonymous identifiers
     if (anonymousIds.length) {
         eventTemplate.device_id = u.pickRandom(anonymousIds);
     }
-    
-    if (sessionIds.length) {
-        eventTemplate.session_id = u.pickRandom(sessionIds);
-    }
+
+    // Session IDs are assigned post-hoc in user-loop.js based on temporal gaps
 
     // Sometimes add user_id (for attribution modeling)
     if (!isFirstEvent && chance.bool({ likelihood: 42 })) {

package/lib/orchestrators/user-loop.js

@@ -359,6 +359,8 @@ export async function userLoop(context) {
 
 			// ALL SUBSEQUENT EVENTS (funnels for converted users, standalone for all)
 			let userChurned = false;
+			const sessionTimeout = config.sessionTimeout || 30;
+
 			while (numEventsPreformed < numEventsThisUserWillPreform && !cancelled) {
 				let newEvents;
 				if (usageFunnels.length && userConverted) {
@@ -397,7 +399,10 @@ export async function userLoop(context) {
 			// Subscription events (trial, upgrade, cancel) must not be randomly dropped by decay
 			const userDecay = persona?.engagementDecay || globalEngagementDecay;
 			if (userDecay && userDecay.model !== 'none' && usersEvents.length > 0) {
-				usersEvents = applyEngagementDecay(usersEvents, userDecay, adjustedCreated, context, chance);
+				// adjustedCreated is in FIXED time space, but ev.time is in PRESENT time (shifted).
+				// Shift adjustedCreated to present so daysSinceBirth reflects within-dataset age.
+				const adjustedCreatedPresent = adjustedCreated.add(context.TIME_SHIFT_SECONDS, 'seconds');
+				usersEvents = applyEngagementDecay(usersEvents, userDecay, adjustedCreatedPresent, context, chance);
 			}
 
 			// Feature 5: Subscription lifecycle — inject after decay (exempt from decay filtering)
@@ -445,6 +450,24 @@ export async function userLoop(context) {
 				}
 			}
 
+			// Session clustering: redistribute events into temporal bursts, then assign session IDs
+			if (hasSessionIds && usersEvents.length > 0) {
+				const soupCfg = /** @type {import('../../types').SoupConfig} */ (config.soup) || {};
+				const defaultPeaks = Math.max(5, (config.numDays || 30) * 2);
+				const { mean: soupMean = 0, deviation: soupDev = 2, peaks: soupPeaks = defaultPeaks,
+					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD } = soupCfg;
+
+				u.bunchIntoSessions(usersEvents, sessionTimeout, {
+					earliestTime: userFirstEventTime,
+					latestTime: context.FIXED_NOW,
+					peaks: soupPeaks, deviation: soupDev, mean: soupMean,
+					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD,
+					timeShiftSeconds: context.TIME_SHIFT_SECONDS,
+					maxTime: context.MAX_TIME
+				});
+				u.assignSessionIds(usersEvents, sessionTimeout);
+			}
+
 			// Hook for processing all user events (hooks override everything)
 			if (config.hook) {
 				const newEvents = await config.hook(usersEvents, "everything", {

package/lib/utils/utils.js

@@ -1314,15 +1314,7 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 
 	if (!hasAnonIds) delete user.anonymousIds;
 
-	//session Ids
-	if (hasSessionIds) {
-		const sessionSize = integer(5, 30);
-		for (let i = 0; i < sessionSize; i++) {
-			const sessionId = [uid(5), uid(5), uid(5), uid(5)].join("-");
-			user.sessionIds.push(sessionId);
-		}
-	}
-
+	// Session IDs are now assigned post-hoc in user-loop.js based on temporal gaps
 	if (!hasSessionIds) delete user.sessionIds;
 
 	return user;
@@ -1436,6 +1428,131 @@ function deepClone(thing, opts) {
 };
 
 
+/**
+ * Generates a session ID in the standard format
+ * @returns {string} Session ID like "xxxxx-xxxxx-xxxxx-xxxxx"
+ */
+function generateSessionId() {
+	return [uid(5), uid(5), uid(5), uid(5)].join("-");
+}
+
+/**
+ * Redistributes events into temporal clusters (sessions).
+ *
+ * Algorithm:
+ * 1. Sort events by time
+ * 2. Determine number of sessions (total events / avg events per session)
+ * 3. Generate session anchor times using TimeSoup
+ * 4. Assign events round-robin to sessions
+ * 5. Within each session, retime events with tight spacing (5-300s apart)
+ * 6. Regenerate insert_ids for retimed events
+ * 7. Re-sort by time
+ *
+ * Mutates events in place. Does NOT assign session_id (call assignSessionIds after).
+ *
+ * @param {Object[]} events - Array of event objects with .time (ISO string)
+ * @param {number} timeoutMinutes - Session timeout in minutes (used to determine intra-session spacing)
+ * @param {Object} soupParams - Parameters for TimeSoup anchor generation
+ */
+function bunchIntoSessions(events, timeoutMinutes, soupParams) {
+	if (events.length < 2) return;
+
+	const chance = getChance();
+	const { earliestTime, latestTime, peaks, deviation, mean,
+		dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds, maxTime } = soupParams;
+
+	// Sort by time first
+	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
+
+	// Determine number of sessions: target 3-8 events per session
+	const eventsPerSession = chance.integer({ min: 3, max: 8 });
+	const numSessions = Math.max(1, Math.ceil(events.length / eventsPerSession));
+
+	// Generate session anchor times using TimeSoup
+	const anchors = [];
+	for (let i = 0; i < numSessions; i++) {
+		const soupTime = TimeSoup(earliestTime, latestTime, peaks, deviation, mean,
+			dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds);
+		anchors.push(soupTime + timeShiftSeconds); // shifted to present time
+	}
+	anchors.sort((a, b) => a - b);
+
+	// Distribute events across sessions round-robin (preserving original order → temporal order)
+	const sessionBuckets = anchors.map(() => []);
+	for (let i = 0; i < events.length; i++) {
+		const bucketIndex = Math.min(i % numSessions, numSessions - 1);
+		sessionBuckets[bucketIndex].push(events[i]);
+	}
+
+	// Retime events within each session
+	let writeIndex = 0;
+	for (let s = 0; s < numSessions; s++) {
+		const bucket = sessionBuckets[s];
+		if (bucket.length === 0) continue;
+
+		let currentTime = anchors[s];
+		for (let e = 0; e < bucket.length; e++) {
+			const ev = bucket[e];
+			const clampedTime = Math.min(currentTime, maxTime);
+
+			ev.time = dayjs.unix(clampedTime).toISOString();
+			// Regenerate insert_id to match new time
+			const distinctId = ev.user_id || ev.device_id || ev.distinct_id || '';
+			ev.insert_id = quickHash(`${ev.event}-${ev.time}-${distinctId}`);
+
+			if (currentTime > maxTime) {
+				ev._drop = true;
+			}
+
+			// Advance time within session: 5-300 seconds (5s to 5min)
+			currentTime += chance.integer({ min: 5, max: 300 });
+		}
+	}
+
+	// Re-sort by time
+	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
+}
+
+/**
+ * Assigns session IDs to a chronologically sorted array of events.
+ * A new session starts when:
+ *   - Gap between consecutive events exceeds timeoutMinutes
+ *   - Session duration exceeds 24 hours
+ *
+ * Events MUST be sorted by time before calling this function.
+ * Mutates events in place (adds session_id property).
+ *
+ * @param {Object[]} events - Sorted array of event objects with .time (ISO string)
+ * @param {number} timeoutMinutes - Session timeout in minutes (default 30)
+ * @returns {Object[]} Same array, with session_id added to each event
+ */
+function assignSessionIds(events, timeoutMinutes = 30) {
+	if (!events.length) return events;
+
+	const timeoutMs = timeoutMinutes * 60 * 1000;
+	const maxSessionMs = 24 * 60 * 60 * 1000;
+
+	let currentSessionId = generateSessionId();
+	let sessionStartMs = new Date(events[0].time).getTime();
+	let lastEventMs = sessionStartMs;
+
+	for (const event of events) {
+		const eventMs = new Date(event.time).getTime();
+		const gapFromLast = eventMs - lastEventMs;
+		const sessionDuration = eventMs - sessionStartMs;
+
+		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
+			currentSessionId = generateSessionId();
+			sessionStartMs = eventMs;
+		}
+
+		event.session_id = currentSessionId;
+		lastEventMs = eventMs;
+	}
+
+	return events;
+}
+
 export {
 	pick,
 	date,
@@ -1486,4 +1603,7 @@ export {
 	wrapFunc,
 	bytesHuman,
 	formatDuration,
+	generateSessionId,
+	assignSessionIds,
+	bunchIntoSessions,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.1.0",
+	"version": "1.2.1",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",

package/scripts/extract-dungeon-schema.mjs

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 
 /**
- * Extracts an abbreviated schema from a JavaScript dungeon file.
+ * Extracts a complete schema from a JavaScript dungeon file.
  *
- * Output contains only the event/property relationships, superProps, userProps,
- * and funnels — no hooks, no config flags, no functions.
+ * Output contains everything about the dungeon EXCEPT:
+ *   - hook function (runtime logic, not schema)
+ *   - credentials (token, serviceAccount, serviceSecret, projectId)
+ *   - execution params (seed, format, gzip, verbose, concurrency, batchSize, writeToDisk, region)
  *
  * Property values are simplified:
  *   - Plain arrays → deduplicated
  *   - weighNumRange(min,max) arrays → { "$range": [min, max] }
  *   - Functions (pickAWinner, weighChoices, etc.) → sampled and deduplicated
- *   - High-cardinality / complex values → omitted
+ *   - High-cardinality / complex values → type hint
  *
  * Usage:
  *   node scripts/extract-dungeon-schema.mjs <input.js> [output.json]
@@ -61,12 +63,16 @@ async function processOne(inputFile, outputFile) {
 
 	const schema = {};
 
-	// Events
+	// ── Events ──────────────────────────────────────────────────────
 	if (config.events?.length) {
 		schema.events = config.events.map(evt => {
 			const entry = { event: evt.event };
 			if (evt.weight && evt.weight !== 1) entry.weight = evt.weight;
 			if (evt.isFirstEvent) entry.isFirstEvent = true;
+			if (evt.isChurnEvent) entry.isChurnEvent = true;
+			if (evt.returnLikelihood !== undefined) entry.returnLikelihood = evt.returnLikelihood;
+			if (evt.isStrictEvent) entry.isStrictEvent = true;
+			if (evt.isSessionStartEvent) entry.isSessionStartEvent = true;
 			if (evt.properties && Object.keys(evt.properties).length) {
 				const props = extractProps(evt.properties);
 				if (Object.keys(props).length) entry.properties = props;
@@ -75,22 +81,11 @@ async function processOne(inputFile, outputFile) {
 		});
 	}
 
-	// Super props
-	if (config.superProps && Object.keys(config.superProps).length) {
-		const sp = extractProps(config.superProps);
-		if (Object.keys(sp).length) schema.superProps = sp;
-	}
-
-	// User props
-	if (config.userProps && Object.keys(config.userProps).length) {
-		const up = extractProps(config.userProps);
-		if (Object.keys(up).length) schema.userProps = up;
-	}
-
-	// Funnels
+	// ── Funnels ─────────────────────────────────────────────────────
 	if (config.funnels?.length) {
 		schema.funnels = config.funnels.map(f => {
 			const entry = { sequence: f.sequence };
+			if (f.name) entry.name = f.name;
 			if (f.isFirstFunnel) entry.isFirstFunnel = true;
 			if (f.conversionRate !== undefined) entry.conversionRate = f.conversionRate;
 			if (f.timeToConvert !== undefined) entry.timeToConvert = f.timeToConvert;
@@ -98,6 +93,8 @@ async function processOne(inputFile, outputFile) {
 			if (f.weight && f.weight !== 1) entry.weight = f.weight;
 			if (f.requireRepeats) entry.requireRepeats = true;
 			if (f.experiment) entry.experiment = true;
+			if (f.bindPropsIndex !== undefined) entry.bindPropsIndex = f.bindPropsIndex;
+			if (f.conditions) entry.conditions = f.conditions;
 			if (f.props && Object.keys(f.props).length) {
 				const fp = extractProps(f.props);
 				if (Object.keys(fp).length) entry.props = fp;
@@ -106,6 +103,55 @@ async function processOne(inputFile, outputFile) {
 		});
 	}
 
+	// ── Super props ─────────────────────────────────────────────────
+	if (config.superProps && Object.keys(config.superProps).length) {
+		const sp = extractProps(config.superProps);
+		if (Object.keys(sp).length) schema.superProps = sp;
+	}
+
+	// ── User props ──────────────────────────────────────────────────
+	if (config.userProps && Object.keys(config.userProps).length) {
+		const up = extractProps(config.userProps);
+		if (Object.keys(up).length) schema.userProps = up;
+	}
+
+	// ── Group keys ──────────────────────────────────────────────────
+	if (config.groupKeys?.length) {
+		schema.groupKeys = config.groupKeys.map(gk => {
+			if (Array.isArray(gk)) {
+				const entry = { key: gk[0], count: gk[1] };
+				if (gk[2]) entry.affectsEvents = gk[2];
+				return entry;
+			}
+			return gk;
+		});
+	}
+
+	// ── Group props ─────────────────────────────────────────────────
+	if (config.groupProps && Object.keys(config.groupProps).length) {
+		schema.groupProps = {};
+		for (const [groupKey, props] of Object.entries(config.groupProps)) {
+			schema.groupProps[groupKey] = extractProps(props);
+		}
+	}
+
+	// ── SCD props ───────────────────────────────────────────────────
+	if (config.scdProps && Object.keys(config.scdProps).length) {
+		schema.scdProps = {};
+		for (const [key, scd] of Object.entries(config.scdProps)) {
+			const entry = {};
+			entry.type = scd.type || "user";
+			if (scd.frequency) entry.frequency = scd.frequency;
+			if (scd.timing) entry.timing = scd.timing;
+			if (scd.max !== undefined) entry.max = scd.max;
+			if (scd.values) {
+				const simplified = simplifyValue(scd.values);
+				if (simplified) entry.values = simplified;
+			}
+			schema.scdProps[key] = entry;
+		}
+	}
+
 	writeFileSync(outputPath, JSON.stringify(schema, null, 2) + '\n', 'utf-8');
 	console.log(`  ✅ ${baseName}-schema.json`);
 }

package/types.d.ts

@@ -72,8 +72,10 @@ export interface Dungeon {
     verbose?: boolean;
     /** If true, users get anonymous device IDs in addition to distinct_id. */
     hasAnonIds?: boolean;
-    /** If true, users get session IDs attached to events. */
+    /** If true, users get session IDs attached to events based on temporal clustering. */
     hasSessionIds?: boolean;
+    /** Session timeout in minutes. Events with gaps exceeding this start a new session. Default: 30. Only used when hasSessionIds is true. */
+    sessionTimeout?: number;
     /** If true, auto-generates funnels from the events array in addition to any explicit funnels. */
     alsoInferFunnels?: boolean;
     /** Restrict all location data to a single country (e.g., "US", "GB"). */
@@ -231,8 +233,8 @@ export interface hookArrayOptions<T> {
  * an enriched array is an array that has a hookPush method that can be used to transform-then-push items into the array
  */
 export interface HookedArray<T> extends Array<T> {
-    hookPush: (item: T | T[], ...meta: any[]) => any;
-    flush: () => void;
+    hookPush: (item: T | T[], ...meta: any[]) => Promise<any>;
+    flush: () => Promise<void>;
     getWriteDir: () => string;
     getWritePath: () => string;
     [key: string]: any;
@@ -266,6 +268,7 @@ export interface Storage {
 export interface RuntimeState {
     operations: number;
     eventCount: number;
+    storedEventCount: number;
     userCount: number;
     isBatchMode: boolean;
     verbose: boolean;
@@ -305,11 +308,13 @@ export interface Context {
     incrementOperations(): void;
     incrementEvents(): void;
     incrementUsers(): void;
+    incrementStoredEvents(count?: number): void;
     setStorage(storage: Storage): void;
 
     // State getter methods
     getOperations(): number;
     getEventCount(): number;
+    getStoredEventCount(): number;
     getUserCount(): number;
     incrementUserCount(): void;
     incrementEventCount(): void;