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

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);
+}

package/scripts/verify-runner.mjs

@@ -1,42 +1,90 @@
 /**
- * Verify Runner — runs a dungeon at constrained params for hook verification.
+ * Verify Runner — runs a dungeon for hook verification.
  *
- * Usage: node scripts/verify-runner.mjs <dungeon-path> [run-name]
+ * Default mode: FULL FIDELITY — runs the dungeon with its own configured
+ *   numUsers / avgEventsPerUserPerDay / numDays. This is the only way to
+ *   verify the trends a benchmark consumer will actually see.
  *
- * Example: node scripts/verify-runner.mjs dungeons/streaming.js verify-streaming
+ * --small mode: ~1K users with avgEventsPerUserPerDay scaled proportionally
+ *   so total events stay near 100K. Use only for fast smoke checks; do NOT
+ *   ship verification verdicts based on --small runs.
+ *
+ * Usage:
+ *   node scripts/verify-runner.mjs <dungeon-path> [run-name] [--small]
+ *
+ * Examples:
+ *   node scripts/verify-runner.mjs dungeons/vertical/gaming.js verify-gaming
+ *   node scripts/verify-runner.mjs dungeons/vertical/gaming.js verify-gaming --small
  */
 import generate from '../index.js';
 import path from 'path';
 
-const dungeonPath = process.argv[2];
+const args = process.argv.slice(2);
+const flags = new Set(args.filter(a => a.startsWith('--')));
+const positional = args.filter(a => !a.startsWith('--'));
+
+const dungeonPath = positional[0];
 if (!dungeonPath) {
-	console.error('Usage: node scripts/verify-runner.mjs <dungeon-path> [run-name]');
+	console.error('Usage: node scripts/verify-runner.mjs <dungeon-path> [run-name] [--small]');
 	process.exit(1);
 }
 
-const runName = process.argv[3] || 'verify-hooks';
+const runName = positional[1] || 'verify-hooks';
+const isSmall = flags.has('--small');
 const absolutePath = path.isAbsolute(dungeonPath)
-  ? dungeonPath
-  : path.resolve(process.cwd(), dungeonPath);
+	? dungeonPath
+	: path.resolve(process.cwd(), dungeonPath);
 
 const { default: config } = await import(absolutePath);
 
-const results = await generate({
-  ...config,
-  token: "",
-  numUsers: 1000,
-  numEvents: 100_000,
-  format: "json",
-  gzip: false,
-  writeToDisk: true,
-  name: runName,
-  concurrency: 1,
-  verbose: false,
-});
+let override;
+
+if (isSmall) {
+	// SMALL mode: 1K users, scaled per-day rate so total events ≈ 100K.
+	// Preserves the dungeon's per-user-per-day shape while shrinking the dataset.
+	// Use only for quick smoke checks — verdicts must come from full fidelity.
+	const numUsers = 1000;
+	const numDays = config.numDays || 100;
+	const targetTotal = 100_000;
+	const scaledRate = targetTotal / (numUsers * numDays);
+	override = {
+		...config,
+		token: '',
+		numUsers,
+		numDays,
+		avgEventsPerUserPerDay: scaledRate,
+		numEvents: undefined,
+		format: 'json',
+		gzip: false,
+		writeToDisk: true,
+		name: runName,
+		concurrency: 1,
+		verbose: false,
+	};
+} else {
+	// FULL FIDELITY: use the dungeon's own scale settings as-shipped.
+	// Full-scale runs can take minutes for 50K-user dungeons; that's expected.
+	override = {
+		...config,
+		token: '',
+		format: 'json',
+		gzip: false,
+		writeToDisk: true,
+		name: runName,
+		concurrency: config.concurrency || 1,
+		verbose: false,
+	};
+}
+
+const t0 = Date.now();
+const results = await generate(override);
+const wallMs = Date.now() - t0;
 
 console.log(JSON.stringify({
-  eventCount: results.eventCount,
-  userCount: results.userCount,
-  files: results.files,
-  duration: results.time?.human || results.time?.delta + 'ms'
+	mode: isSmall ? 'small' : 'full',
+	eventCount: results.eventCount,
+	userCount: results.userCount,
+	files: results.files,
+	duration: results.time?.human || `${wallMs}ms`,
+	wallMs,
 }));

package/types.d.ts

@@ -21,11 +21,22 @@ export interface Dungeon {
     token?: string;
     /** RNG seed for reproducible output. Same seed + concurrency=1 = identical data. */
     seed?: string;
-    /** Number of days the dataset spans (from "now" looking backward). Default: 30 */
+    /** Number of days the dataset spans. Used as fallback when datasetStart/datasetEnd are NOT both set — window becomes (today_start - numDays, today_start). Default: 30. When datasetStart/datasetEnd ARE both set, numDays is recomputed from the window and any user-supplied value is ignored (with a warning). */
     numDays?: number;
-    /** Explicit start of dataset window (unix seconds). Alternative to numDays. */
+    /**
+     * Explicit start of the dataset window. Pin BOTH `datasetStart` and `datasetEnd` for
+     * bit-exact deterministic runs. Accepts ISO string ("2026-01-01T00:00:00Z"), unix
+     * seconds (1735689600), unix milliseconds (1735689600000), or anything `dayjs()`
+     * can parse. Setting only one of datasetStart/datasetEnd throws.
+     */
+    datasetStart?: string | number;
+    /**
+     * Explicit end of the dataset window. See `datasetStart` — both must be set together.
+     */
+    datasetEnd?: string | number;
+    /** @deprecated Legacy alias internally aliased to datasetStart on validated config. Prefer `datasetStart`. */
     epochStart?: number;
-    /** Explicit end of dataset window (unix seconds). Defaults to FIXED_NOW. */
+    /** @deprecated Legacy alias internally aliased to datasetEnd on validated config. Prefer `datasetEnd`. */
     epochEnd?: number;
     /** Target total number of events to generate across all users. Fallback when avgEventsPerUserPerDay is not set; otherwise derived from rate × numUsers × numDays. */
     numEvents?: number;
@@ -279,8 +290,20 @@ export type hookTypes =
  */
 export type Hook<T> = (record: any, type: hookTypes, meta: any) => T;
 
+/**
+ * Time-window anchors present on every hook's `meta`. Use these to derive relative
+ * dates inside hooks (e.g. `dayjs.unix(meta.datasetStart).add(45, 'days')`). NEVER
+ * read wall-clock `dayjs()` inside a hook — it makes hooks non-deterministic.
+ */
+export interface HookMetaTimeAnchors {
+    /** Start of the dataset window (unix seconds). Same value the engine uses to bound event generation. */
+    datasetStart: number;
+    /** End of the dataset window (unix seconds). Same value the engine uses to bound event generation. */
+    datasetEnd: number;
+}
+
 /** Meta passed to the "event" hook. */
-export interface HookMetaEvent {
+export interface HookMetaEvent extends HookMetaTimeAnchors {
     /** The user this event belongs to (only `distinct_id` is guaranteed). */
     user: { distinct_id: string };
     /** The fully-resolved dungeon config. */
@@ -288,7 +311,7 @@ export interface HookMetaEvent {
 }
 
 /** Meta passed to the "user" hook (fires when a user profile is created). */
-export interface HookMetaUser {
+export interface HookMetaUser extends HookMetaTimeAnchors {
     /** The user object being constructed (mutate in place). */
     user: UserProfile;
     /** The fully-resolved dungeon config. */
@@ -298,7 +321,7 @@ export interface HookMetaUser {
 }
 
 /** Meta passed to the "scd-pre" hook (fires per SCD prop, before insertion). */
-export interface HookMetaScdPre {
+export interface HookMetaScdPre extends HookMetaTimeAnchors {
     /** The user profile that owns these SCD entries. */
     profile: UserProfile;
     /** The SCD prop key being generated (e.g. "plan", "tier"). */
@@ -312,7 +335,7 @@ export interface HookMetaScdPre {
 }
 
 /** Meta passed to the "funnel-pre" hook (mutate funnel before generating events). */
-export interface HookMetaFunnelPre {
+export interface HookMetaFunnelPre extends HookMetaTimeAnchors {
     user: { distinct_id: string };
     profile: UserProfile;
     scd: Record<string, SCDSchema[]>;
@@ -323,7 +346,7 @@ export interface HookMetaFunnelPre {
 }
 
 /** Meta passed to the "funnel-post" hook (mutate generated funnel events in place). */
-export interface HookMetaFunnelPost {
+export interface HookMetaFunnelPost extends HookMetaTimeAnchors {
     user: { distinct_id: string };
     profile: UserProfile;
     scd: Record<string, SCDSchema[]>;
@@ -332,7 +355,7 @@ export interface HookMetaFunnelPost {
 }
 
 /** Meta passed to the "everything" hook — most powerful hook (sees all events for one user). */
-export interface HookMetaEverything {
+export interface HookMetaEverything extends HookMetaTimeAnchors {
     /** The user's profile, including merged persona/region/attribution properties. */
     profile: UserProfile;
     /** All SCD entries for this user, keyed by prop name. */
@@ -463,10 +486,14 @@ export interface Context {
     /** Pre-built UTM campaign pool (used when `hasCampaigns: true`). */
     campaigns: Record<string, ValueValid>[];
     runtime: RuntimeState;
+    /** End of the resolved dataset window (unix seconds). Equal to the user-supplied `datasetEnd`, or fallback `today_start`. */
     FIXED_NOW: number;
+    /** Start of the resolved dataset window (unix seconds). Equal to the user-supplied `datasetStart`, or fallback `today_start - numDays`. */
     FIXED_BEGIN?: number;
-    TIME_SHIFT_SECONDS: number;
-    MAX_TIME: number;
+    /** Alias of `FIXED_BEGIN` — surfaced on hook `meta.datasetStart`. */
+    DATASET_START_SECONDS: number;
+    /** Alias of `FIXED_NOW` — surfaced on hook `meta.datasetEnd`. */
+    DATASET_END_SECONDS: number;
 
     // State update methods
     incrementOperations(): void;
@@ -483,10 +510,6 @@ export interface Context {
     incrementUserCount(): void;
     incrementEventCount(): void;
     isBatchMode(): boolean;
-
-    // Time helper methods
-    getTimeShift(): number;
-    getDaysShift(): number;
 }
 
 /**

package/dungeons/technical/ad-spend-schema.json

@@ -1,128 +0,0 @@
-{
-  "events": [
-    {
-      "event": "sign up",
-      "isFirstEvent": true,
-      "properties": {
-        "method": [
-          "email",
-          "google",
-          "facebook",
-          "github"
-        ]
-      }
-    },
-    {
-      "event": "page view",
-      "weight": 10,
-      "properties": {
-        "page": [
-          "/",
-          "/pricing",
-          "/features",
-          "/docs",
-          "/blog",
-          "/signup"
-        ]
-      }
-    },
-    {
-      "event": "purchase",
-      "weight": 2,
-      "properties": {
-        "amount": {
-          "$range": [
-            108,
-            392
-          ]
-        },
-        "currency": [
-          "USD",
-          "EUR",
-          "GBP"
-        ],
-        "item_count": {
-          "$range": [
-            2,
-            7
-          ]
-        }
-      }
-    },
-    {
-      "event": "ad click",
-      "weight": 6,
-      "properties": {
-        "partner": [
-          "google",
-          "facebook",
-          "linkedin",
-          "twitter",
-          "bing",
-          "tiktok"
-        ],
-        "ad_format": [
-          "banner",
-          "video",
-          "carousel",
-          "native",
-          "search"
-        ],
-        "placement": [
-          "feed",
-          "sidebar",
-          "header",
-          "interstitial"
-        ]
-      }
-    },
-    {
-      "event": "search",
-      "weight": 5,
-      "properties": {
-        "query_length": {
-          "$range": [
-            3,
-            28
-          ]
-        },
-        "results_count": {
-          "$range": [
-            21,
-            79
-          ]
-        }
-      }
-    },
-    {
-      "event": "share",
-      "weight": 3,
-      "properties": {
-        "platform": [
-          "twitter",
-          "facebook",
-          "linkedin",
-          "email"
-        ],
-        "content_type": [
-          "product",
-          "page",
-          "deal"
-        ]
-      }
-    }
-  ],
-  "userProps": {
-    "plan": [
-      "free",
-      "starter",
-      "pro",
-      "enterprise"
-    ],
-    "signup_source": [
-      "organic",
-      "paid",
-      "referral"
-    ]
-  }
-}

package/dungeons/technical/anonymous-users-schema.json

@@ -1,92 +0,0 @@
-{
-  "events": [
-    {
-      "event": "page view",
-      "weight": 10,
-      "properties": {
-        "page": [
-          "/",
-          "/features",
-          "/pricing",
-          "/docs",
-          "/blog"
-        ],
-        "referrer": [
-          "direct",
-          "google",
-          "twitter",
-          "linkedin"
-        ]
-      }
-    },
-    {
-      "event": "signup",
-      "isFirstEvent": true,
-      "properties": {
-        "method": [
-          "email",
-          "google",
-          "github",
-          "sso"
-        ]
-      }
-    },
-    {
-      "event": "feature used",
-      "weight": 7,
-      "properties": {
-        "feature": [
-          "dashboard",
-          "reports",
-          "settings",
-          "export",
-          "import",
-          "search"
-        ]
-      }
-    },
-    {
-      "event": "purchase",
-      "weight": 2,
-      "properties": {
-        "amount": {
-          "$range": [
-            114,
-            397
-          ]
-        },
-        "plan": [
-          "monthly",
-          "annual"
-        ]
-      }
-    },
-    {
-      "event": "button click",
-      "weight": 8,
-      "properties": {
-        "button": [
-          "cta",
-          "nav",
-          "menu",
-          "submit",
-          "cancel",
-          "back"
-        ],
-        "location": [
-          "header",
-          "body",
-          "footer",
-          "sidebar"
-        ]
-      }
-    }
-  ],
-  "userProps": {
-    "plan": [
-      "free",
-      "pro",
-      "enterprise"
-    ]
-  }
-}