@ak--47/dungeon-master 1.2.3 → 1.3.1

package/lib/templates/soup-presets.js

@@ -1,6 +1,13 @@
 /**
- * TimeSoup preset configurations
- * Each preset defines time distribution parameters that produce distinct patterns.
+ * Soup preset configurations.
+ *
+ * Soup presets shape the INTRA-WEEK and INTRA-DAY rhythm: how many Gaussian
+ * peaks to sample from, how tightly each clusters, and how to weight each
+ * day-of-week and hour-of-day during accept/reject sampling.
+ *
+ * Soup is the orthogonal axis to macro presets (lib/templates/macro-presets.js).
+ * Macro shapes the big-picture trend (births, growth, decline). Soup shapes
+ * the texture inside that trend (weekly cycle, daily peak, burstiness).
  *
  * Parameters:
  * - peaks(numDays): function returning number of Gaussian clusters
@@ -8,9 +15,6 @@
  * - mean: offset from chunk center (0 = centered)
  * - dayOfWeekWeights: 7-element array [Sun..Sat], max=1.0, null to disable
  * - hourOfDayWeights: 24-element array [0h..23h UTC], max=1.0, null to disable
- *
- * Some presets also suggest bornRecentBias and percentUsersBornInDataset,
- * but those are top-level dungeon config — presets only set them if not already specified.
  */
 
 // Real-world Mixpanel DOW pattern: weekday-heavy, Saturday valley
@@ -27,11 +31,11 @@ export const REAL_HOD = [
 export const FLAT_DOW = [1, 1, 1, 1, 1, 1, 1];
 export const FLAT_HOD = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1];
 
-/** @type {Record<string, {peaks: (numDays: number) => number, deviation: number, mean: number, dayOfWeekWeights: number[]|null, hourOfDayWeights: number[]|null, bornRecentBias?: number, percentUsersBornInDataset?: number}>} */
+/** @type {Record<string, {peaks: (numDays: number) => number, deviation: number, mean: number, dayOfWeekWeights: number[]|null, hourOfDayWeights: number[]|null}>} */
 export const SOUP_PRESETS = {
 	/**
 	 * steady — Mature SaaS / Stable Product
-	 * Nearly flat day-over-day, slight weekly pattern, minimal growth trend.
+	 * Tighter clusters, real-world DOW/HOD weights.
 	 */
 	steady: {
 		peaks: (numDays) => Math.max(5, numDays * 2),
@@ -39,13 +43,11 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: REAL_DOW,
 		hourOfDayWeights: REAL_HOD,
-		bornRecentBias: 0.1,
-		percentUsersBornInDataset: 10,
 	},
 
 	/**
 	 * growth — Growing Startup (DEFAULT)
-	 * Gradual uptrend with visible weekly peaks. This is the default behavior.
+	 * Standard clustering with real-world weekly + daily rhythm.
 	 */
 	growth: {
 		peaks: (numDays) => Math.max(5, numDays * 2),
@@ -53,13 +55,11 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: REAL_DOW,
 		hourOfDayWeights: REAL_HOD,
-		bornRecentBias: 0.3,
-		percentUsersBornInDataset: 15,
 	},
 
 	/**
 	 * spiky — Event-Driven / Bursty
-	 * Clear peaks and valleys, dramatic variation. Fewer Gaussian clusters + tight deviation.
+	 * Fewer Gaussian clusters + tight deviation = visible peaks and valleys.
 	 */
 	spiky: {
 		peaks: (numDays) => Math.max(4, Math.ceil(numDays / 15)),
@@ -67,13 +67,11 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: REAL_DOW,
 		hourOfDayWeights: REAL_HOD,
-		bornRecentBias: 0.3,
-		percentUsersBornInDataset: 20,
 	},
 
 	/**
 	 * seasonal — Strong Cyclical Patterns
-	 * 3-4 major waves across the dataset. Very few peaks create dramatic macro trends.
+	 * 4 major waves across the dataset for dramatic macro trends.
 	 */
 	seasonal: {
 		peaks: () => 4,
@@ -81,13 +79,11 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: REAL_DOW,
 		hourOfDayWeights: REAL_HOD,
-		bornRecentBias: 0.2,
-		percentUsersBornInDataset: 25,
 	},
 
 	/**
 	 * global — Distributed Users Across Timezones
-	 * Very flat hourly + daily distribution. No cyclical patterns.
+	 * Flat hourly + daily distribution. No cyclical patterns.
 	 */
 	global: {
 		peaks: (numDays) => Math.max(5, numDays * 2),
@@ -95,15 +91,12 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: FLAT_DOW,
 		hourOfDayWeights: FLAT_HOD,
-		bornRecentBias: 0,
-		percentUsersBornInDataset: 10,
 	},
 
 	/**
 	 * churny — High Churn / Declining Product
-	 * Flat distribution (no growth trend). All users pre-exist the dataset,
-	 * so there's no acceleration. Combine with an "everything" hook that
-	 * filters late events to create a true declining shape.
+	 * Standard intra-week rhythm. Combine with macro: "decline" and an
+	 * "everything" hook that filters late events to create a true declining shape.
 	 */
 	churny: {
 		peaks: (numDays) => Math.max(5, numDays * 2),
@@ -111,8 +104,6 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: REAL_DOW,
 		hourOfDayWeights: REAL_HOD,
-		bornRecentBias: 0,
-		percentUsersBornInDataset: 5,
 	},
 
 	/**
@@ -125,8 +116,6 @@ export const SOUP_PRESETS = {
 		mean: 0,
 		dayOfWeekWeights: REAL_DOW,
 		hourOfDayWeights: REAL_HOD,
-		bornRecentBias: 0.5,
-		percentUsersBornInDataset: 40,
 	},
 };
 
@@ -137,7 +126,7 @@ export const PRESET_NAMES = Object.keys(SOUP_PRESETS);
  * Resolves a soup config — handles string presets, preset+overrides, and raw objects.
  * @param {string | object} soup - Soup config from dungeon
  * @param {number} numDays - Number of days in the dataset
- * @returns {{ soup: object, suggestedBornRecentBias?: number, suggestedPercentUsersBornInDataset?: number }}
+ * @returns {{ soup: object }}
  */
 export function resolveSoup(soup, numDays) {
 	if (!soup) return { soup: {} };
@@ -156,8 +145,6 @@ export function resolveSoup(soup, numDays) {
 				dayOfWeekWeights: preset.dayOfWeekWeights,
 				hourOfDayWeights: preset.hourOfDayWeights,
 			},
-			suggestedBornRecentBias: preset.bornRecentBias,
-			suggestedPercentUsersBornInDataset: preset.percentUsersBornInDataset,
 		};
 	}
 
@@ -176,11 +163,7 @@ export function resolveSoup(soup, numDays) {
 		};
 		// Apply overrides (excluding the 'preset' key itself)
 		const { preset: _, ...overrides } = soup;
-		return {
-			soup: { ...base, ...overrides },
-			suggestedBornRecentBias: preset.bornRecentBias,
-			suggestedPercentUsersBornInDataset: preset.percentUsersBornInDataset,
-		};
+		return { soup: { ...base, ...overrides } };
 	}
 
 	// Raw object: { peaks: 10, deviation: 2 } — pass through unchanged

package/lib/utils/utils.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import Chance from 'chance';
 import readline from 'readline';
-import { comma, uid } from 'ak-tools';
+import { comma } from 'ak-tools';
 import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc.js';
 import path from 'path';
@@ -24,7 +24,27 @@ const { NODE_ENV = "unknown" } = process.env;
 let globalChance;
 let chanceInitialized = false;
 
-const ACTUAL_NOW = dayjs.utc();
+// Module-scoped memoization cache for weighted-array resolvers in `choose()`.
+// Lives for the lifetime of the node process; key is the function source string.
+const weightedArrayCache = new Map();
+
+// Reference "now" used by date() and day() factories. Defaults to wall-clock at
+// import time; the orchestrator overrides this via setDatasetNow() once the dataset
+// window is resolved, so date helpers in dungeon configs produce deterministic
+// values relative to the dataset end (not the process start).
+let DATASET_NOW = dayjs.utc();
+
+/**
+ * Override the reference "now" used by date()/day() factories. Called by the
+ * orchestrator with the resolved dataset end so every date helper produces
+ * deterministic values relative to the dataset window.
+ * @param {number} unixSeconds
+ */
+function setDatasetNow(unixSeconds) {
+	if (typeof unixSeconds === 'number' && Number.isFinite(unixSeconds)) {
+		DATASET_NOW = dayjs.unix(unixSeconds).utc();
+	}
+}
 
 
 import { Storage as cloudStorage } from '@google-cloud/storage';
@@ -102,7 +122,7 @@ function pick(items) {
  */
 function date(inTheLast = 30, isPast = true, format = 'YYYY-MM-DD') {
 	const chance = getChance();
-	const now = ACTUAL_NOW;
+	const now = DATASET_NOW;
 	if (Math.abs(inTheLast) > 365 * 10) inTheLast = chance.integer({ min: 1, max: 180 });
 	return function () {
 		const when = chance.integer({ min: 0, max: Math.abs(inTheLast) });
@@ -159,8 +179,8 @@ function datesBetween(start, end) {
  */
 function day(start, end) {
 	// if (!end) end = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
-	if (!start) start = ACTUAL_NOW.subtract(30, 'd').toISOString();
-	if (!end) end = ACTUAL_NOW.toISOString();
+	if (!start) start = DATASET_NOW.subtract(30, 'd').toISOString();
+	if (!end) end = DATASET_NOW.toISOString();
 	const chance = getChance();
 	const format = 'YYYY-MM-DD';
 	return function (min, max) {
@@ -219,20 +239,15 @@ function choose(value) {
 		while (typeof value === 'function') {
 			const funcString = value.toString();
 
-			// Check cache for weighted array functions
-			if (typeof global.weightedArrayCache === 'undefined') {
-				global.weightedArrayCache = new Map();
-			}
-
-			if (global.weightedArrayCache.has(funcString)) {
-				value = global.weightedArrayCache.get(funcString);
+			if (weightedArrayCache.has(funcString)) {
+				value = weightedArrayCache.get(funcString);
 				break;
 			}
 
 			const result = value();
 			if (Array.isArray(result) && result.length > 10) {
 				// Cache large arrays (likely weighted arrays)
-				global.weightedArrayCache.set(funcString, result);
+				weightedArrayCache.set(funcString, result);
 			}
 			value = result;
 		}
@@ -1143,7 +1158,7 @@ CORE
 //the function which generates $distinct_id + $anonymous_ids, $session_ids, and created, skewing towards the present
 function generateUser(user_id, opts, amplitude = 1, frequency = 1, skew = 1) {
 	const chance = getChance();
-	const { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds } = opts;
+	const { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix } = opts;
 	// Uniformly distributed `u`, then skew applied
 	let u = Math.pow(chance.random(), skew);
 
@@ -1155,7 +1170,7 @@ function generateUser(user_id, opts, amplitude = 1, frequency = 1, skew = 1) {
 
 	// Clamp values to ensure they are within the desired range
 	daysAgoBorn = Math.min(daysAgoBorn, numDays);
-	const props = person(user_id, daysAgoBorn, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds);
+	const props = person(user_id, daysAgoBorn, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix);
 
 	const user = {
 		distinct_id: user_id,
@@ -1188,7 +1203,7 @@ const DEFAULT_HOD_WEIGHTS = [
 	0.584, 0.574, 0.554, 0.576, 0.604, 0.655, 0.722, 0.816
 ];
 
-function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0, dayOfWeekWeights = DEFAULT_DOW_WEIGHTS, hourOfDayWeights = DEFAULT_HOD_WEIGHTS, timeShiftSeconds = 0) {
+function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0, dayOfWeekWeights = DEFAULT_DOW_WEIGHTS, hourOfDayWeights = DEFAULT_HOD_WEIGHTS) {
 	if (!earliestTime) earliestTime = global.FIXED_BEGIN ? global.FIXED_BEGIN : dayjs().subtract(30, 'd').unix();
 	if (!latestTime) latestTime = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
 	const chance = getChance();
@@ -1215,7 +1230,7 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
 	// Phase 2: DOW accept/reject — retry if day-of-week doesn't pass weight check
 	if (dayOfWeekWeights) {
 		for (let attempt = 0; attempt < 50; attempt++) {
-			const dow = new Date((candidate + timeShiftSeconds) * 1000).getUTCDay();
+			const dow = new Date(candidate * 1000).getUTCDay();
 			if (chance.random() < dayOfWeekWeights[dow]) break;
 			// Rejected — resample from Gaussian chunks
 			const pi = integer(0, peaks - 1);
@@ -1231,8 +1246,7 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
 
 	// Phase 3: Redistribute hour-of-day (changes only hour within same day)
 	if (hourOfDayWeights) {
-		const shifted = candidate + timeShiftSeconds;
-		const d = new Date(shifted * 1000);
+		const d = new Date(candidate * 1000);
 		const currentMinute = d.getUTCMinutes();
 		const currentSecond = d.getUTCSeconds();
 
@@ -1244,9 +1258,8 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
 			if (roll <= 0) { newHour = h; break; }
 		}
 
-		const dayStartShifted = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 1000;
-		const newShifted = dayStartShifted + newHour * 3600 + currentMinute * 60 + currentSecond;
-		candidate = newShifted - timeShiftSeconds;
+		const dayStart = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 1000;
+		candidate = dayStart + newHour * 3600 + currentMinute * 60 + currentSecond;
 		candidate = Math.max(earliestTime, Math.min(latestTime, candidate));
 	}
 
@@ -1264,7 +1277,7 @@ function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0,
  * @param {boolean} hasSessionIds
  * @return {Person}
  */
-function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false, hasAnonIds = false, hasSessionIds = false) {
+function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false, hasAnonIds = false, hasSessionIds = false, datasetEndUnix) {
 	const chance = getChance();
 	//names and photos
 	const l = chance.letter.bind(chance);
@@ -1278,7 +1291,11 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 	let randomAvatarNumber = integer(1, 99);
 	let avPath = gender === 'male' ? `/men/${randomAvatarNumber}.jpg` : `/women/${randomAvatarNumber}.jpg`;
 	let avatar = avatarPrefix + avPath;
-	let created = dayjs().subtract(bornDaysAgo, 'day').format('YYYY-MM-DD');
+	// Birth date: anchor to dataset end (post-resolution) so user.created lives inside
+	// the configured window, not wall-clock time. Falls back to dayjs() only when
+	// person() is called outside the normal generation pipeline (e.g. direct unit tests).
+	const anchor = datasetEndUnix ? dayjs.unix(datasetEndUnix) : dayjs();
+	let created = anchor.subtract(bornDaysAgo, 'day').format('YYYY-MM-DD');
 
 
 	// const created = date(bornDaysAgo, true)();
@@ -1307,7 +1324,8 @@ function person(userId, bornDaysAgo = 30, isAnonymous = false, hasAvatar = false
 	if (hasAnonIds) {
 		const clusterSize = integer(2, 10);
 		for (let i = 0; i < clusterSize; i++) {
-			const anonId = uid(42);
+			// Use seeded chance, not ak-tools uid() (which uses Math.random).
+			const anonId = chance.string({ length: 42, pool: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' });
 			user.anonymousIds.push(anonId);
 		}
 	}
@@ -1429,11 +1447,26 @@ function deepClone(thing, opts) {
 
 
 /**
- * Generates a session ID in the standard format
+ * Generates a session ID in the standard format. Derives it deterministically
+ * from a seed string (first event time + user_id, typically) via quickHash so
+ * we don't consume from the main seeded RNG stream — that consumption would
+ * cascade into all downstream events whenever the number of sessions changed
+ * (e.g. when sessionTimeout differs).
+ * @param {string} [seedStr] - Stable input string. If absent, falls back to a
+ *   chance.string() pull (only used by tests / direct callers without a seed).
  * @returns {string} Session ID like "xxxxx-xxxxx-xxxxx-xxxxx"
  */
-function generateSessionId() {
-	return [uid(5), uid(5), uid(5), uid(5)].join("-");
+function generateSessionId(seedStr) {
+	if (seedStr) {
+		// quickHash returns ~16 hex chars; expand to 4×5 segments via re-hashing.
+		const h1 = quickHash(seedStr);
+		const h2 = quickHash(h1);
+		const all = (h1 + h2).replace(/[^a-zA-Z0-9]/g, '').padEnd(20, '0');
+		return [all.slice(0, 5), all.slice(5, 10), all.slice(10, 15), all.slice(15, 20)].join('-');
+	}
+	const c = getChance();
+	const seg = () => c.string({ length: 5, pool: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' });
+	return [seg(), seg(), seg(), seg()].join("-");
 }
 
 /**
@@ -1459,7 +1492,7 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 
 	const chance = getChance();
 	const { earliestTime, latestTime, peaks, deviation, mean,
-		dayOfWeekWeights, hourOfDayWeights, timeShiftSeconds, maxTime } = soupParams;
+		dayOfWeekWeights, hourOfDayWeights } = soupParams;
 
 	// Sort by time first
 	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
@@ -1472,8 +1505,8 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 	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
+			dayOfWeekWeights, hourOfDayWeights);
+		anchors.push(soupTime);
 	}
 	anchors.sort((a, b) => a - b);
 
@@ -1485,7 +1518,6 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 	}
 
 	// Retime events within each session
-	let writeIndex = 0;
 	for (let s = 0; s < numSessions; s++) {
 		const bucket = sessionBuckets[s];
 		if (bucket.length === 0) continue;
@@ -1493,17 +1525,13 @@ function bunchIntoSessions(events, timeoutMinutes, soupParams) {
 		let currentTime = anchors[s];
 		for (let e = 0; e < bucket.length; e++) {
 			const ev = bucket[e];
-			const clampedTime = Math.min(currentTime, maxTime);
+			const clampedTime = Math.min(currentTime, latestTime);
 
 			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 });
 		}
@@ -1532,7 +1560,10 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 	const timeoutMs = timeoutMinutes * 60 * 1000;
 	const maxSessionMs = 24 * 60 * 60 * 1000;
 
-	let currentSessionId = generateSessionId();
+	// Derive a stable seed from the first event so session IDs are deterministic
+	// across runs without consuming the main seeded RNG stream.
+	const userKey = events[0].user_id || events[0].device_id || events[0].distinct_id || '';
+	let currentSessionId = generateSessionId(`${userKey}-${events[0].time}`);
 	let sessionStartMs = new Date(events[0].time).getTime();
 	let lastEventMs = sessionStartMs;
 
@@ -1542,7 +1573,7 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 		const sessionDuration = eventMs - sessionStartMs;
 
 		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
-			currentSessionId = generateSessionId();
+			currentSessionId = generateSessionId(`${userKey}-${event.time}`);
 			sessionStartMs = eventMs;
 		}
 
@@ -1606,4 +1637,5 @@ export {
 	generateSessionId,
 	assignSessionIds,
 	bunchIntoSessions,
+	setDatasetNow,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.2.3",
+	"version": "1.3.1",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -19,10 +19,16 @@
 		"lib/",
 		"dungeons/",
 		"!dungeons/customers/",
+		"!dungeons/user/",
 		"scripts/",
+		"!scripts/experiments/",
 		"package.json",
-		"README.md"
+		"README.md",
+		"CHANGELOG.md"
 	],
+	"engines": {
+		"node": ">=18.0.0"
+	},
 	"publishConfig": {
 		"access": "public"
 	},

package/scripts/smoke-test-all.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Smoke-test runner — runs every dungeon at tiny scale in parallel to verify it
+ * loads, generates events, and writes output without crashing.
+ *
+ * Default scale: 100 users, 1000 events per dungeon. NOT for verification —
+ * use scripts/verify-runner.mjs at full fidelity for that.
+ *
+ * Usage:
+ *   node scripts/smoke-test-all.mjs
+ *   node scripts/smoke-test-all.mjs --dir dungeons/vertical    # default
+ *   node scripts/smoke-test-all.mjs --dir dungeons/technical
+ *   node scripts/smoke-test-all.mjs --dir dungeons             # both subdirs
+ *   node scripts/smoke-test-all.mjs --concurrency 4            # default: cpu count
+ *   node scripts/smoke-test-all.mjs --users 500 --events 5000  # override scale
+ *
+ * Output: per-dungeon PASS/FAIL line + a final summary table. Spawns each
+ * dungeon as a child node process so a crash in one doesn't abort the run.
+ */
+import { spawn } from 'child_process';
+import { readdirSync, statSync, rmSync, existsSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+const args = process.argv.slice(2);
+function arg(name, fallback) {
+	const i = args.indexOf(`--${name}`);
+	return i === -1 ? fallback : args[i + 1];
+}
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+const dirArg = arg('dir', 'dungeons/vertical');
+const numUsers = parseInt(arg('users', '100'), 10);
+const numEvents = parseInt(arg('events', '1000'), 10);
+const concurrency = parseInt(arg('concurrency', String(Math.max(2, os.cpus().length))), 10);
+const keep = args.includes('--keep');
+
+function findDungeons(dir) {
+	const abs = path.resolve(ROOT, dir);
+	if (!existsSync(abs)) return [];
+	const stat = statSync(abs);
+	if (stat.isFile()) return [abs];
+	const out = [];
+	for (const entry of readdirSync(abs)) {
+		const full = path.join(abs, entry);
+		const s = statSync(full);
+		if (s.isDirectory()) out.push(...findDungeons(full));
+		else if (entry.endsWith('.js')) out.push(full);
+	}
+	return out;
+}
+
+const dungeons = findDungeons(dirArg).sort();
+if (dungeons.length === 0) {
+	console.error(`No dungeons found under ${dirArg}`);
+	process.exit(1);
+}
+
+const dataDir = path.join(ROOT, 'data');
+mkdirSync(dataDir, { recursive: true });
+
+const RUNNER = `
+import generate from '${path.join(ROOT, 'index.js')}';
+// With node -e, process.argv = [nodePath, ...userArgs] — no script slot.
+const [dungeonPath, name, numUsers, numEvents] = process.argv.slice(1);
+const r = await generate(dungeonPath, {
+	numUsers: parseInt(numUsers, 10),
+	numEvents: parseInt(numEvents, 10),
+	avgEventsPerUserPerDay: undefined,  // force numEvents path
+	writeToDisk: true,
+	name,
+	format: 'json',
+	verbose: false,
+	concurrency: 1,
+	token: '',
+	serviceAccount: 'fake', serviceSecret: 'fake', projectId: '1',
+});
+console.log(JSON.stringify({ eventCount: r.eventCount, userCount: r.userCount }));
+`;
+
+function runOne(dungeonPath) {
+	const base = path.basename(dungeonPath, '.js');
+	const namePrefix = `smoke-${base}`;
+	return new Promise(resolve => {
+		const start = Date.now();
+		const child = spawn(
+			process.execPath,
+			['--input-type=module', '-e', RUNNER, dungeonPath, namePrefix, String(numUsers), String(numEvents)],
+			{ cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'] }
+		);
+		let out = '';
+		let err = '';
+		child.stdout.on('data', d => { out += d.toString(); });
+		child.stderr.on('data', d => { err += d.toString(); });
+		child.on('close', code => {
+			const ms = Date.now() - start;
+			let result;
+			try {
+				const lastLine = out.trim().split('\n').filter(Boolean).pop() || '{}';
+				result = JSON.parse(lastLine);
+			} catch {
+				result = {};
+			}
+			const ok = code === 0 && result.eventCount > 0;
+			if (!keep) {
+				try {
+					for (const f of readdirSync(dataDir)) {
+						if (f.startsWith(`${namePrefix}-`)) rmSync(path.join(dataDir, f));
+					}
+				} catch {}
+			}
+			resolve({
+				dungeon: path.relative(ROOT, dungeonPath),
+				ok,
+				code,
+				ms,
+				eventCount: result.eventCount || 0,
+				userCount: result.userCount || 0,
+				err: ok ? '' : (err.trim().split('\n').slice(-3).join(' | ') || `exit ${code}`),
+			});
+		});
+	});
+}
+
+console.log(`Smoke test: ${dungeons.length} dungeons, ${numUsers} users / ${numEvents} events each, concurrency=${concurrency}`);
+const queue = [...dungeons];
+const results = [];
+const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+	while (queue.length) {
+		const d = queue.shift();
+		const res = await runOne(d);
+		const tag = res.ok ? 'PASS' : 'FAIL';
+		console.log(`  [${tag}] ${path.basename(res.dungeon)} — ${res.eventCount} events, ${res.userCount} users, ${(res.ms / 1000).toFixed(2)}s${res.ok ? '' : ` — ${res.err}`}`);
+		results.push(res);
+	}
+});
+await Promise.all(workers);
+
+results.sort((a, b) => a.dungeon.localeCompare(b.dungeon));
+const fails = results.filter(r => !r.ok);
+
+console.log('\n┌─────────────────────────────────────────────────┬───────┬────────┬───────┬──────┐');
+console.log('│ Dungeon                                         │ State │ Events │ Users │   ms │');
+console.log('├─────────────────────────────────────────────────┼───────┼────────┼───────┼──────┤');
+for (const r of results) {
+	const name = r.dungeon.padEnd(47).slice(0, 47);
+	const state = (r.ok ? 'PASS' : 'FAIL').padEnd(5);
+	const ev = String(r.eventCount).padStart(6);
+	const u = String(r.userCount).padStart(5);
+	const ms = String(r.ms).padStart(4);
+	console.log(`│ ${name} │ ${state} │ ${ev} │ ${u} │ ${ms} │`);
+}
+console.log('└─────────────────────────────────────────────────┴───────┴────────┴───────┴──────┘');
+
+console.log(`\n${results.length - fails.length}/${results.length} passed`);
+if (fails.length > 0) {
+	console.log('\nFailures:');
+	for (const f of fails) {
+		console.log(`  ✗ ${f.dungeon}: ${f.err}`);
+	}
+	process.exit(1);
+}