@ak--47/dungeon-master 1.4.5 → 1.5.1

package/lib/verify/verify-dungeon.js

@@ -30,6 +30,28 @@ import { validateSchema } from './schema-validator.js';
  * @property {(rows: Array<Object>, ctx: { events: Array<Object>, profiles: Array<Object> }) => { pass: boolean, detail?: string }} assert
  */
 
+/**
+ * Try to find the dungeon funnel whose `sequence` matches the breakdown's funnel
+ * steps. Used to auto-apply v1.5 `conversionWindowDays` + `order`-mode dispatch
+ * without forcing every check author to thread these args by hand.
+ * @param {Array<Object>} funnels
+ * @param {string[]} steps
+ * @returns {Object | null}
+ */
+function findMatchingFunnel(funnels, steps) {
+	if (!Array.isArray(funnels) || !Array.isArray(steps) || !steps.length) return null;
+	for (const f of funnels) {
+		if (!f || !Array.isArray(f.sequence)) continue;
+		if (f.sequence.length !== steps.length) continue;
+		let same = true;
+		for (let i = 0; i < steps.length; i++) {
+			if (f.sequence[i] !== steps[i]) { same = false; break; }
+		}
+		if (same) return f;
+	}
+	return null;
+}
+
 /**
  * @param {Object} config - Dungeon config (or path; passed straight to DUNGEON_MASTER).
  * @param {VerifyCheck[]} checks
@@ -44,12 +66,48 @@ export async function verifyDungeon(config, checks) {
 	const schemaReport = validateSchema(events, config);
 	const ctx = { events, profiles, schemaReport };
 	const results = [];
+	// `validateDungeonConfig` mutates funnels in place — by the time we read here,
+	// `conversionWindowDays` is populated and `order` is the validated value.
+	const validatedFunnels = (config && Array.isArray(config.funnels)) ? config.funnels : [];
 	for (const check of checks) {
 		try {
 			const breakdownArgs = { ...check.breakdown };
 			if (breakdownArgs.type === 'timeToConvert' && !breakdownArgs.profiles) {
 				breakdownArgs.profiles = profiles;
 			}
+			// v1.5: auto-apply funnel-level config when the check targets a funnel.
+			if (breakdownArgs.type === 'funnelFrequency' || breakdownArgs.type === 'timeToConvert') {
+				const targetSteps = breakdownArgs.steps
+					|| (breakdownArgs.fromEvent && breakdownArgs.toEvent
+						? [breakdownArgs.fromEvent, breakdownArgs.toEvent]
+						: null);
+				const matched = findMatchingFunnel(validatedFunnels, targetSteps);
+				if (matched) {
+					if (breakdownArgs.conversionWindowMs === undefined && Number.isFinite(matched.conversionWindowDays)) {
+						breakdownArgs.conversionWindowMs = matched.conversionWindowDays * 86400000;
+					}
+					if (breakdownArgs.funnelOrder === undefined && matched.order) {
+						breakdownArgs.funnelOrder = matched.order;
+					}
+					// v1.5.0: thread Funnel-level extension hints through to the verifier.
+					if (breakdownArgs.reentry === undefined && matched.reentry !== undefined) {
+						breakdownArgs.reentry = matched.reentry;
+					}
+					if (breakdownArgs.exclusionSteps === undefined && Array.isArray(matched.exclusionEvents) && matched.exclusionEvents.length) {
+						breakdownArgs.exclusionSteps = matched.exclusionEvents.map(name => ({ event: name }));
+					}
+					// stepFilters: Record<number, { prop, op, value }> → mutate steps to attach where-clause.
+					if (matched.stepFilters && breakdownArgs.steps && Array.isArray(breakdownArgs.steps)) {
+						breakdownArgs.steps = breakdownArgs.steps.map((s, i) => {
+							const filter = matched.stepFilters[i];
+							if (!filter) return s;
+							const stepObj = typeof s === 'string' ? { event: s } : { ...s };
+							if (!stepObj.where) stepObj.where = filter;
+							return stepObj;
+						});
+					}
+				}
+			}
 			const rows = emulateBreakdown(events, breakdownArgs);
 			const verdict = check.assert(rows, ctx);
 			results.push({ name: check.name, pass: !!verdict.pass, detail: verdict.detail, rows });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.4.5",
+	"version": "1.5.1",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -23,7 +23,9 @@
 		"dungeons/",
 		"!dungeons/customers/",
 		"!dungeons/user/",
+		"!dungeons/capstone/",
 		"scripts/",
+		".claude/skills/",
 		"package.json",
 		"README.md",
 		"CHANGELOG.md",
@@ -41,11 +43,19 @@
 		"test:coverage": "NODE_ENV=test vitest run --coverage",
 		"typecheck": "tsc --noEmit",
 		"dev": "nodemon scratch.mjs --ignore ./data/*",
-		"prune": "rm -f ./data/* && rm -f ./tmp/* && rm -f vscode-profile-*",
+		"prune": "find ./data -mindepth 1 -not -name .gitkeep -delete && find ./tmp -mindepth 1 -not -name .gitkeep -delete && rm -f vscode-profile-*",
 		"dungeon:run": "node ./scripts/run-dungeon.mjs",
 		"dungeon:to-json": "node ./scripts/dungeon-to-json.mjs",
 		"dungeon:from-json": "node ./scripts/json-to-dungeon.mjs",
-		"dungeon:schema": "node ./scripts/extract-dungeon-schema.mjs"
+		"dungeon:schema": "node ./scripts/extract-dungeon-schema.mjs",
+		"kodiak:deploy": "gcloud builds submit --config dungeons/user/kodiak/cloudbuild.yaml",
+		"kodiak:plan": "node dungeons/user/kodiak/kickoff.mjs --plan-only",
+		"kodiak:smoke:local": "bash dungeons/user/kodiak/smoke-local.sh",
+		"kodiak:smoke": "node dungeons/user/kodiak/kickoff.mjs --total-events 1000000000 --chunk-cap 10",
+		"kodiak:generate": "node dungeons/user/kodiak/kickoff.mjs --no-wait",
+		"kodiak:status": "node dungeons/user/kodiak/status.mjs",
+		"kodiak:run": "bash dungeons/user/kodiak/run-all.sh",
+		"kodiak:load": "node dungeons/user/kodiak/load-bq.mjs --replace --no-wait"
 	},
 	"repository": {
 		"type": "git",
@@ -68,6 +78,7 @@
 	},
 	"homepage": "https://github.com/ak--47/dungeon-master#readme",
 	"dependencies": {
+		"@google-cloud/bigquery": "^7.9.4",
 		"@google-cloud/storage": "^7.14.0",
 		"ak-tools": "^1.1.12",
 		"chance": "^1.1.11",

package/scripts/run-dungeon.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import path from 'path';
+import fs from 'fs';
 import generate from '../index.js';
 const { NODE_ENV = "unknown" } = process.env;
 
@@ -14,10 +15,20 @@ if (!dungeonPath) {
 }
 
 // Resolve the absolute path
-const absolutePath = path.isAbsolute(dungeonPath)
+let absolutePath = path.isAbsolute(dungeonPath)
 	? dungeonPath
 	: path.resolve(process.cwd(), dungeonPath);
 
+// Extension fallback: ESM requires explicit extension. Try .js / .mjs / .json.
+if (!fs.existsSync(absolutePath)) {
+	for (const ext of ['.js', '.mjs', '.json']) {
+		if (fs.existsSync(absolutePath + ext)) {
+			absolutePath += ext;
+			break;
+		}
+	}
+}
+
 // Handle Ctrl+C gracefully — let user-loop finish current user, then exit
 process.on('SIGINT', () => {
 	// Second Ctrl+C forces immediate exit

package/types.d.ts

@@ -12,10 +12,66 @@ type Primitives = string | number | boolean | Date | Record<string, any>;
  */
 export type ValueValid = Primitives | ValueValid[] | (() => ValueValid);
 
+/**
+ * v1.5.1 — credentials sub-object. Groups Mixpanel project credentials. Top-level
+ * `token` / `region` / etc. remain functional as a back-compat alias; when both
+ * are set, the top-level value wins with a verbose warning.
+ */
+export interface DungeonCredentials {
+    token?: string;
+    region?: 'US' | 'EU' | 'IN';
+    serviceAccount?: string;
+    serviceSecret?: string;
+    projectId?: string;
+}
+
+/**
+ * v1.5.1 — switches sub-object. Groups data-shape booleans. Top-level keys
+ * remain functional as a back-compat alias; same precedence rules as
+ * `DungeonCredentials`.
+ */
+export interface DungeonSwitches {
+    hasLocation?: boolean;
+    hasCampaigns?: boolean;
+    hasAdSpend?: boolean;
+    hasSessionIds?: boolean;
+    hasAvatar?: boolean;
+    hasIOSDevices?: boolean;
+    hasAndroidDevices?: boolean;
+    hasDesktopDevices?: boolean;
+    hasBrowser?: boolean;
+    isAnonymous?: boolean;
+    alsoInferFunnels?: boolean;
+    hasAttributionFlags?: boolean;
+}
+
+/**
+ * v1.5.1 — identity sub-object. Groups identity-model knobs. Top-level
+ * `avgDevicePerUser` / `sessionTimeout` remain functional as a back-compat
+ * alias.
+ *
+ * `hasAnonIds` is DEPRECATED — when present here, it maps to
+ * `avgDevicePerUser: 1` with a verbose warning. Use `avgDevicePerUser` instead.
+ */
+export interface DungeonIdentity {
+    avgDevicePerUser?: number;
+    sessionTimeout?: number;
+    /** @deprecated v1.5.1 — use `avgDevicePerUser: 1` instead. */
+    hasAnonIds?: boolean;
+}
+
 /**
  * main config object for the entire data generation
  */
 export interface Dungeon {
+    // ── v1.5.1 sub-object grouping (optional) ──
+    /** v1.5.1 — credentials sub-object. See `DungeonCredentials`. */
+    credentials?: DungeonCredentials;
+    /** v1.5.1 — switches sub-object. See `DungeonSwitches`. */
+    switches?: DungeonSwitches;
+    /** v1.5.1 — identity sub-object. See `DungeonIdentity`. */
+    identity?: DungeonIdentity;
+
     // ── Core Parameters ──
     /** Optional dungeon version. Not used by the engine — serves as metadata for tracking revisions when configs are saved/shared. */
     version?: string | number;
@@ -25,9 +81,27 @@ export interface Dungeon {
     token?: string;
     /** RNG seed for reproducible output. Same seed + concurrency=1 = identical data. */
     seed?: string;
+    /**
+     * Optional separate RNG seed dedicated to `distinct_id` generation.
+     *
+     * When set, two runs with the same `userSeed` but different `seed` produce
+     * the SAME pool of user IDs but DIFFERENT events. Designed for sharded /
+     * massively-parallel runs (e.g., Cloud Run Job fan-out) that need cross-shard
+     * user identity — every shard generating bucket N pulls from the same 3M
+     * user IDs while producing unique events of its own.
+     *
+     * When unset, the engine falls back to `seed` for user-id generation —
+     * existing dungeons stay byte-identical.
+     */
+    userSeed?: string;
     /**
      * Number of days the dataset spans. Default: 30.
      *
+     * Safe range: `[14, 365]`. Below 14 → strict-bar engine-validation metrics use
+     * 14-day windows; results are noisy. Above 365 → memory cost grows linearly.
+     * Validator emits a warning below 14; does not clamp (because the window may have
+     * been pinned via `datasetStart`/`datasetEnd` upstream).
+     *
      * Three resolution modes:
      * 1. **`numDays` alone (no datasetStart/End):** Window = `[today - numDays, today]`.
      *    Simplest API for ad-hoc dungeons. NOT deterministic across runs (today changes).
@@ -58,7 +132,14 @@ export interface Dungeon {
     numEvents?: number;
     /** Number of unique users to generate. */
     numUsers?: number;
-    /** Average events per user per active day. The canonical event-volume primitive — born-late users get this rate × their remaining window, so per-day density stays constant. If both this and numEvents are set, this wins. */
+    /**
+     * Average events per user per active day. The canonical event-volume primitive —
+     * born-late users get this rate × their remaining window, so per-day density stays
+     * constant. If both this and numEvents are set, this wins.
+     *
+     * Safe range: `[0.1, 50]`. Above 50 → unrealistic load + memory cost; the v1.5
+     * validator strict-clamps to 50 with a warning.
+     */
     avgEventsPerUserPerDay?: number;
     /** Output format for files written to disk. */
     format?: "csv" | "json" | "parquet" | string;
@@ -242,12 +323,107 @@ export interface Dungeon {
     // ── Distribution Controls ──
     // These three knobs are normally set by the `macro` preset (default "flat").
     // Setting them on the dungeon config directly overrides the preset's value.
-    /** Percentage of users whose account creation falls within the dataset window (vs. pre-existing). Default (from macro: "flat"): 50 */
+    /**
+     * Percentage of users whose account creation falls within the dataset window (vs. pre-existing).
+     *
+     * Safe range: `[0, 100]` (sanity-clamped). Recommended `[0, 60]`. **v1.5 strict-clamp:**
+     * when `macro` is set to a named preset AND the user explicitly sets this field, it is
+     * clamped to the preset's default born% (flat=12, steady=12, growth=30, viral=55,
+     * decline=5) to preserve the macro's characteristic shape. Users who need higher born%
+     * should switch macros (flat→growth, growth→viral). When `macro` is not set, no clamp
+     * fires (legacy backward-compat).
+     */
     percentUsersBornInDataset?: number;
-    /** Bias for birth dates of users born in dataset. -1..1; negative = early skew, positive = recent skew, 0 = uniform. Default (from macro: "flat"): 0 */
+    /**
+     * Bias for birth dates of users born in dataset. -1..1; negative = early skew,
+     * positive = recent skew, 0 = uniform.
+     *
+     * Safe range: `[-0.5, 0.5]`. **v1.5 strict-clamp:** values outside `[-0.5, 0.5]` are
+     * clamped to the nearest bound (above 0.5 = unusable right-skew; below -0.5 = unusable
+     * left-skew). Compound clamp: when explicit `percentUsersBornInDataset > 60` AND
+     * explicit `bornRecentBias > 0.4`, bias is clamped to 0.3 to prevent right-edge
+     * cumulative-acquisition explosion. Macro presets (e.g., viral=0.6) are exempt.
+     */
     bornRecentBias?: number;
     /** How pre-existing users' first event time is placed. "pinned" stacks them all at FIXED_BEGIN; "uniform" spreads across [FIXED_BEGIN-30d, FIXED_BEGIN]. Default (from macro: "flat"): "uniform" */
     preExistingSpread?: "pinned" | "uniform";
+
+    // ── v1.5 Distinct-Day + Mixpanel Cap Primitives ──
+    /**
+     * Mean number of distinct UTC days each user fires events on. CONCENTRATOR semantic —
+     * total event count is preserved (still `avgEventsPerUserPerDay × userActiveDays`),
+     * but events cluster onto fewer days. Per-user count drawn from
+     * `normal(mean=avgActiveDaysPerUser, sd=mean/3)`, clamped to `[1, userActiveDays]`.
+     *
+     * Default: undefined (legacy — every window-day potentially active, no concentration).
+     *
+     * Per-active-day rate inflates: `(avgEventsPerUserPerDay × numDays) / avgActiveDaysPerUser`.
+     * Validator warns when implied per-active-day rate > 50.
+     *
+     * Day picking: weighted-without-replacement from candidate UTC days using
+     * `soup.dayOfWeekWeights`, so weekly rhythm is preserved at the cohort level.
+     *
+     * **Incompatibility with `engagementDecay`:** decay drops events from late picked days,
+     * eroding the effective active-day count below the configured target. Use one or the
+     * other; if you need both, write decay logic in an `everything` hook scoped to specific
+     * cohorts. See HOOKS.md §2.5.
+     *
+     * Safe range: `[1, numDays * 0.5]`. Above 50% of `numDays` defeats the concentrator
+     * purpose; the v1.5 validator strict-clamps to `floor(numDays * 0.5)` with a warning.
+     */
+    avgActiveDaysPerUser?: number;
+    /**
+     * v1.5.1 — target retention shape. Anchor points `day1`, `day7`, `day30`
+     * etc. define the per-day-offset weight a user is active. When set, biases
+     * `buildActiveDayPlan` toward the curve and the effective
+     * `avgActiveDaysPerUser` is derived from the curve's sum across the user's
+     * window (curve wins over an explicit `avgActiveDaysPerUser`).
+     *
+     * - `type`: `'logarithmic'` (default, real-world retention shape) or `'linear'`.
+     * - `dayN` keys: fraction active on day N from birth (0..1). Day 0 is
+     *   implicitly 1.0 (every user is active on their birth day).
+     * - Days beyond the largest anchor extrapolate from the last segment.
+     *
+     * Example: `{ day1: 0.40, day7: 0.20, day30: 0.08 }` produces a curve that
+     * approximates a typical product's 30-day retention.
+     */
+    retentionCurve?: {
+        type?: 'logarithmic' | 'linear';
+        day1?: number;
+        day3?: number;
+        day7?: number;
+        day14?: number;
+        day30?: number;
+        day60?: number;
+        day90?: number;
+        [dayKey: string]: number | 'logarithmic' | 'linear' | undefined;
+    };
+    /**
+     * Maximum number of UTM-stamped events per user. Matches Mixpanel's `TOUCHPOINTS_LIMIT`
+     * (`backend/libquery/properties_over_time/attributed_value_reader.cpp` line 16).
+     *
+     * Default: 10.
+     *
+     * When `hasCampaigns: true` and a user has more eligible events than the cap, the
+     * engine takes a uniform-random sample of size `cap` from the eligible pool (seeded,
+     * deterministic), sorts the sample chronologically, then stamps UTMs. Sampling
+     * across the user's lifetime — NOT first-N-chronological — preserves realistic
+     * touch distribution and lets Mixpanel's last-10-window report give meaningful
+     * first/last-touch attribution.
+     *
+     * Set to `Infinity` to disable the cap (legacy behavior, ~25% of eligible events stamped).
+     */
+    maxTouchpointsPerUser?: number;
+    /**
+     * If true (default), the engine sorts each user's events ascending by `time` after
+     * the `everything` hook returns, before the events are pushed to storage. Defends
+     * against the most common new footgun: hooks that `push()` cloned events with arbitrary
+     * timestamps and break the greedy funnel engine's chronological-order requirement.
+     *
+     * Set to `false` to preserve the hook's order (advanced — hook must guarantee its own
+     * ordering for downstream Mixpanel-aligned counting).
+     */
+    autoSortAfterEverything?: boolean;
 }
 
 export type SCDProp = {
@@ -820,6 +996,22 @@ export interface Funnel {
      * the time it takes (on average) to convert in hours
      */
     timeToConvert?: number;
+    /**
+     * Mixpanel-style conversion window cap, in DAYS. Funnel-step events after step 0 must
+     * land within `conversionWindowDays * 86400000` ms of step 0's timestamp (strict `<`,
+     * matching `is_within_conversion_window` in `backend/arb/reader/funnels/conversion_window.cpp`).
+     *
+     * Default: 30 (Mixpanel UI default).
+     *
+     * If unset and `timeToConvert / 24 >= 30`, the validator auto-bumps to
+     * `min(180, ceil(timeToConvert / 24 * 1.5))` and warns. Hard cap: 180 days
+     * (Mixpanel's maximum). Validator throws if explicitly set above 180.
+     *
+     * The generator caps funnel runs at `conversionWindowDays * 86400000 - 1` ms (1ms slack
+     * to clear the strict-`<` boundary). The verifier (`verifyDungeon`) reads this field
+     * and applies it automatically when emulating funnel breakdowns.
+     */
+    conversionWindowDays?: number;
     /**
      * funnel properties go onto each event in the funnel and are held constant
      */
@@ -858,6 +1050,32 @@ export interface Funnel {
 	 * @see AttemptsConfig
 	 */
 	attempts?: AttemptsConfig;
+
+	// v1.5.0 — funnel extensions
+	/**
+	 * v1.5.0 — Events that terminate the funnel attempt for non-converters. The generator
+	 * stamps 1-2 cloned exclusion events between the last completed step and where the next
+	 * step would have been; the verifier reads this and applies them as exclusionSteps to
+	 * `evaluateFunnel`. Each entry MUST be declared in `events[]` (schema-first) — the
+	 * validator throws otherwise.
+	 */
+	exclusionEvents?: string[];
+	/**
+	 * v1.5.0 — Verifier-only hint. When `true`, the verifier evaluates with reentry
+	 * enabled (counts every completion). Generator behavior unchanged.
+	 */
+	reentry?: boolean;
+	/**
+	 * v1.5.0 — Verifier-only hint. Per-step property conditions; the verifier mutates
+	 * its step list to attach `where`-clauses at the matching index. Generator behavior
+	 * unchanged.
+	 */
+	stepFilters?: Record<number, {
+		prop: string;
+		op: 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains';
+		value: unknown;
+	}>;
+
 	/** @internal Resolved experiment config set by config-validator. */
 	_experiment?: { name: string; variants: Array<{ name: string; conversionMultiplier: number; ttcMultiplier: number; weight: number }>; startUnix: number | null };
 	/** @internal Set by funnels.js during experiment handling. */
@@ -992,6 +1210,15 @@ export interface UserProfile {
     avatar?: string;
     created: string | undefined;
     distinct_id: string;
+    /**
+     * v1.5.1: when `true`, the engine considers this profile "anonymous" — the
+     * user never reached an `isAuthEvent` step. Profile still exists in
+     * `userProfilesData` (so hooks and downstream tools can see the full
+     * population), but `mixpanel-sender` filters it out before pushing to
+     * `/engage`. Hooks can rescue by deleting the flag inside the `everything`
+     * hook.
+     */
+    _drop?: boolean;
     [key: string]: ValueValid;
 }
 
@@ -1077,6 +1304,12 @@ export type Result = {
     userCount?: number;
     groupCount?: number;
     avgEPS?: number;
+    /**
+     * v1.5.1: count of profiles eligible for Mixpanel `/engage` push (i.e., not
+     * flagged with `_drop: true`). Anonymous non-converters carry `_drop: true`
+     * so `userProfilesData.length - profilesPushed` = dropped profile count.
+     */
+    profilesPushed?: number;
     /** Progress callback summary. Only present when `onProgress` was provided. */
     progress?: ProgressSummary;
 };
@@ -1627,7 +1860,7 @@ declare module '@ak--47/dungeon-master/hook-patterns' {
  * | `attributedBy` | `conversionEvent`, `attributionEvent`, `attributionProperty` | `model` (default: `'lastTouch'`) |
  */
 export interface EmulateOptions {
-    type: 'frequencyByFrequency' | 'funnelFrequency' | 'aggregatePerUser' | 'timeToConvert' | 'attributedBy';
+    type: 'frequencyByFrequency' | 'funnelFrequency' | 'aggregatePerUser' | 'timeToConvert' | 'attributedBy' | 'sessionMetrics' | 'retention' | 'distinctCount';
     metricEvent?: string;
     breakdownByFrequencyOf?: string;
     perUser?: boolean;
@@ -1643,6 +1876,78 @@ export interface EmulateOptions {
     attributionEvent?: string;
     attributionProperty?: string;
     model?: 'firstTouch' | 'lastTouch';
+    /**
+     * Pre-built device→user map (e.g. from `buildIdentityMap(profiles)`). When omitted but
+     * `profiles` are supplied with `device_ids`, the map is built automatically. Threaded
+     * through every breakdown type so pre-auth (device_id) events resolve to the same
+     * canonical user as post-auth (user_id) events.
+     */
+    identityMap?: Map<string, string>;
+    /** v1.5.0 — funnel reentry. After completing all steps, reset and continue scanning. Used by funnelFrequency + timeToConvert sequential modes. */
+    reentry?: boolean;
+    /** v1.5.0 — funnel exclusion steps. If an exclusion event fires between specified steps, terminate the attempt. */
+    exclusionSteps?: Array<{ event: string; afterStep?: number; beforeStep?: number }>;
+    /** v1.5.0 — funnel step property tracking. Captures matched event properties at each step into FunnelResult.stepProperties. */
+    trackStepProperties?: boolean | string[];
+    /** v1.5.0 — partition funnel evaluation by `session_id`; only steps in the same session can complete. */
+    sessionScoped?: boolean;
+    /** v1.5.0 — cross-cutting time-bucketed output. Wraps any breakdown type, returning rows tagged with `period` per UTC bucket. */
+    timeBucket?: 'day' | 'week' | 'month';
+    /**
+     * v1.5.0 — when set with `timeBucket`, enumerates EVERY bucket in `[from, to]`
+     * and emits a `{ period, _empty: true }` marker for buckets with no events
+     * (Mixpanel normal_query.cpp emits zero rows for empty intervals). Without
+     * this, only buckets containing events are returned.
+     *
+     * **Empty-row contract:** consumers MUST filter `r._empty` before any
+     * numerical aggregation. Populated rows have full breakdown fields plus
+     * `period`; empty rows have ONLY `period` and `_empty: true`.
+     */
+    timeBucketRange?: { from: number | string; to: number | string };
+    /** v1.5.0 — sessionMetrics: filter to sessions containing this event. Omit for all sessions. */
+    metrics?: Array<'count' | 'duration' | 'eventsPerSession'>;
+
+    // v1.5.0 retention extensions
+    /** Retention birth event name. */
+    cohortEvent?: string;
+    /** Retention return event name. */
+    returnEvent?: string;
+    /** Day buckets to check (offsets from birth, ≥1). */
+    dayBuckets?: number[];
+    /** Segment cohort by birth event property value (Mixpanel segment_event=FIRST). */
+    segmentBy?: string;
+    /** CARRY_FORWARD unbounded mode — once retained, counted on all later buckets. */
+    carry_forward?: boolean;
+    /**
+     * v1.5.0 — Mixpanel `birth_can_retain` (retention_query.cpp:1097-1109). Default
+     * `false`: a return event at the EXACT birth ms is NOT counted (strict `<`).
+     * Set `true` to count exact-birth-ms returns (rare; usually a same-event-as-birth
+     * pattern requires COMPOUNDED retention which is not supported here).
+     */
+    birthCanRetain?: boolean;
+
+    // v1.5.1 distinctCount extensions
+    /** Optional cap on the number of top-N values returned in `top_values`. Defaults to 25 (matches Mixpanel UI). */
+    topN?: number;
+}
+
+/** v1.5.0 — config for `emulateBreakdown({ type: 'retention' })`. */
+export interface RetentionConfig extends EmulateOptions {
+    type: 'retention';
+    cohortEvent: string;
+    returnEvent: string;
+    dayBuckets: number[];
+    segmentBy?: string;
+    carry_forward?: boolean;
+}
+
+/** v1.5.0 — config for `emulateBreakdown({ type: 'sessionMetrics' })`. */
+export interface SessionMetricsConfig extends EmulateOptions {
+    type: 'sessionMetrics';
+    /** Optional event filter — only sessions containing this event qualify. */
+    event?: string;
+    /** Which metrics to compute. Default: `['count', 'duration', 'eventsPerSession']`. */
+    metrics?: Array<'count' | 'duration' | 'eventsPerSession'>;
 }
 
 declare module '@ak--47/dungeon-master/verify' {
@@ -1650,6 +1955,48 @@ declare module '@ak--47/dungeon-master/verify' {
     export function verifyDungeon(config: Dungeon, checks: Array<{ name: string; breakdown: EmulateOptions; assert: (rows: Array<Record<string, unknown>>, ctx: { events: EventSchema[]; profiles: UserProfile[] }) => { pass: boolean; detail?: string } }>): Promise<{ pass: boolean; results: Array<{ name: string; pass: boolean; detail?: string; rows?: Array<Record<string, unknown>> }>; schemaReport: SchemaReport }>;
     export function deriveExpectedSchema(config: Dungeon): Map<string, Set<string>>;
     export function validateSchema(events: EventSchema[], config: Dungeon): SchemaReport;
+    /** Build a `Map<device_id, canonical_user_id>` by inverting each profile's `device_ids` array. */
+    export function buildIdentityMap(profiles: UserProfile[]): Map<string, string>;
+    /** Resolve canonical user id for an event using the identity map (device→user merge). */
+    export function resolveUserId(event: EventSchema | Record<string, unknown>, identityMap?: Map<string, string>): string | undefined;
+
+    /** Funnel step type — string OR `{ event, where? }` for step-level property filters. */
+    export type FunnelStep = string | { event: string; where?: { prop: string; op: 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains'; value: unknown } };
+    /** Exclusion step config — fires between `afterStep` and `beforeStep` to terminate the funnel attempt. */
+    export interface ExclusionStep { event: string; afterStep?: number; beforeStep?: number }
+    /** Greedy single-pass funnel evaluator options. */
+    export interface FunnelOptions {
+        conversionWindowMs?: number;
+        graceperiod?: boolean;
+        reentry?: boolean;
+        exclusionSteps?: ExclusionStep[];
+        trackStepProperties?: boolean | string[];
+        countMode?: 'uniques' | 'totals';
+        sessionScoped?: boolean;
+    }
+    /** Per-attempt funnel result. */
+    export interface FunnelResult {
+        completed: boolean;
+        reached: number;
+        stepEvents: Array<Record<string, unknown> | null>;
+        stepTimes: Array<number | null>;
+        ttcMs: number | null;
+        completions: number;
+        stepProperties?: Array<Record<string, unknown>>;
+        sessionId?: string;
+    }
+    /** Evaluate a funnel against a user's events. Returns FunnelResult or array (totals mode). */
+    export function evaluateFunnel(events: Array<Record<string, unknown>>, steps: FunnelStep[], options?: FunnelOptions): FunnelResult | FunnelResult[];
+    /** Hold Property Constant — runs parallel sub-funnels per unique value of `holdProperty`. */
+    export function evaluateFunnelHPC(events: Array<Record<string, unknown>>, steps: FunnelStep[], holdProperty: string, options?: FunnelOptions): Map<string | number, FunnelResult | FunnelResult[]>;
+    /** Pick a property snapshot from a FunnelResult for the given segment mode. */
+    export function resolveFunnelSegment(result: FunnelResult, mode: 'first' | 'last' | { step: number }): Record<string, unknown> | undefined;
+    /** Normalize a FunnelStep to the `{ event, where? }` canonical shape. */
+    export function normalizeStep(step: FunnelStep): { event: string; where?: { prop: string; op: string; value: unknown } };
+    /** Test whether an event qualifies for a step's where-clause. */
+    export function matchesStepFilter(event: Record<string, unknown>, where?: { prop: string; op: string; value: unknown }): boolean;
+    /** Partition events into UTC `day` / `week` (ISO) / `month` buckets. */
+    export function partitionByTimeBucket(events: Array<Record<string, unknown>>, bucket: 'day' | 'week' | 'month'): Array<{ period: string; events: Array<Record<string, unknown>> }>;
 
     interface SchemaReport {
         pass: boolean;
@@ -1673,6 +2020,8 @@ declare module '@ak--47/dungeon-master/utils' {
     export function weighNumRange(min: number, max: number, skew?: number, size?: number): number[];
     export function pickAWinner(items: string[], mostChosenIndex?: number): () => string[];
     export function initChance(seed?: string): unknown;
+    export function initUserChance(seed?: string): unknown;
+    export function getUserChance(): unknown;
     export function TimeSoup(earliestTime: number, latestTime: number, peaks?: number, deviation?: number, mean?: number, dayOfWeekWeights?: number[] | null, hourOfDayWeights?: number[] | null): number;
     export function weighArray<T>(items: T[]): T[];
     export function generateUser(user_id: string, opts: Record<string, unknown>): Record<string, unknown>;