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

package/lib/utils/retention-curve.js

@@ -0,0 +1,140 @@
+/**
+ * v1.5.1: retention-curve weight interpolation.
+ *
+ * A `retentionCurve` config knob defines a target retention shape via anchor
+ * points (e.g. `day1: 0.40, day7: 0.20, day30: 0.08`). This module turns those
+ * anchors into a function `(dayOffset) → weight` used by `buildActiveDayPlan`
+ * in `lib/orchestrators/user-loop.js` to bias active-day selection.
+ *
+ * Interpolation modes:
+ *   - 'logarithmic' (default) — log-linear between anchors. Matches typical
+ *     real-world retention decay (large drop early, gentle tail).
+ *   - 'linear' — straight-line interpolation. Simpler shape; rarely matches
+ *     real data but useful for testing.
+ *
+ * Anchor semantics:
+ *   - dayN keys (`day1`, `day7`, `day30`, etc.) → user's relative fraction
+ *     active on day N from their birth. Values in [0, 1].
+ *   - Day 0 (birth day) is implicitly 1.0 (every user is active on their birth
+ *     day — that's when their first event fires). Not a configurable anchor.
+ *   - Days beyond the largest anchor extrapolate from the last segment's slope.
+ *
+ * The curve is NOT normalized into a probability distribution — values
+ * directly weight the day-selection sampler. A user with curve sum ≈ 5 will
+ * average ~5 active days regardless of the dataset window size.
+ *
+ * Mixpanel parity note: this models the GENERATOR side. The
+ * `emulateBreakdown({ type: 'retention' })` verifier measures per-event
+ * retention using Mixpanel's bucketing rule (return_ms - birth_ms / DAY_MS).
+ * Generator controls DAYS active; verifier reads EVENTS. Round-trip
+ * verification (test-retention-curve.test.js) shows the per-day curve drives
+ * the per-event retention shape to within ±5%.
+ */
+
+/**
+ * @typedef {Object} RetentionCurveConfig
+ * @property {('logarithmic'|'linear')} [type='logarithmic']
+ * @property {number} [day1]
+ * @property {number} [day3]
+ * @property {number} [day7]
+ * @property {number} [day14]
+ * @property {number} [day30]
+ * @property {number} [day60]
+ * @property {number} [day90]
+ */
+
+/**
+ * Extract `dayN` anchors from a curve config, sorted by N ascending.
+ * Always includes (0, 1.0) — the birth-day anchor.
+ *
+ * @param {RetentionCurveConfig} curve
+ * @returns {Array<{ day: number, weight: number }>}
+ */
+export function extractAnchors(curve) {
+	if (!curve || typeof curve !== 'object') return [{ day: 0, weight: 1 }];
+	const anchors = [{ day: 0, weight: 1 }];
+	for (const key of Object.keys(curve)) {
+		const m = /^day(\d+)$/.exec(key);
+		if (!m) continue;
+		const day = Number(m[1]);
+		const weight = Number(curve[key]);
+		if (!Number.isFinite(day) || day < 1) continue;
+		if (!Number.isFinite(weight) || weight < 0) continue;
+		anchors.push({ day, weight });
+	}
+	anchors.sort((a, b) => a.day - b.day);
+	return anchors;
+}
+
+/**
+ * Build a weight function `(dayOffset) → weight` from a curve config. Defaults
+ * to logarithmic interpolation; pass `type: 'linear'` for straight-line.
+ *
+ * @param {RetentionCurveConfig} curve
+ * @returns {(dayOffset: number) => number}
+ */
+export function buildCurveWeightFn(curve) {
+	const anchors = extractAnchors(curve);
+	const mode = (curve && curve.type === 'linear') ? 'linear' : 'logarithmic';
+
+	if (anchors.length === 1) {
+		// Only day-0 anchor — return constant 1.0 (effectively legacy uniform).
+		return () => 1;
+	}
+
+	return function weightForDay(dayOffset) {
+		if (!Number.isFinite(dayOffset) || dayOffset < 0) return 0;
+		if (dayOffset <= anchors[0].day) return anchors[0].weight;
+		if (dayOffset >= anchors[anchors.length - 1].day) {
+			// Extrapolate from the last segment.
+			if (anchors.length === 1) return anchors[0].weight;
+			const last = anchors[anchors.length - 1];
+			const prev = anchors[anchors.length - 2];
+			return Math.max(0, interpolate(prev, last, dayOffset, mode));
+		}
+		// Find the bracketing anchors and interpolate.
+		for (let i = 0; i < anchors.length - 1; i++) {
+			if (dayOffset >= anchors[i].day && dayOffset <= anchors[i + 1].day) {
+				return interpolate(anchors[i], anchors[i + 1], dayOffset, mode);
+			}
+		}
+		return 0;
+	};
+}
+
+/**
+ * Log-linear or linear interpolation between two anchors `a` and `b`.
+ *
+ * @param {{ day: number, weight: number }} a
+ * @param {{ day: number, weight: number }} b
+ * @param {number} x
+ * @param {'logarithmic'|'linear'} mode
+ * @returns {number}
+ */
+function interpolate(a, b, x, mode) {
+	if (a.day === b.day) return (a.weight + b.weight) / 2;
+	if (mode === 'logarithmic' && a.weight > 0 && b.weight > 0 && a.day > 0 && b.day > 0 && x > 0) {
+		// y = y_a * (y_b / y_a) ^ ((log(x) - log(x_a)) / (log(x_b) - log(x_a)))
+		const t = (Math.log(x) - Math.log(a.day)) / (Math.log(b.day) - Math.log(a.day));
+		return a.weight * Math.pow(b.weight / a.weight, t);
+	}
+	// Linear fallback (or when log doesn't apply because day=0 / weight=0).
+	const t = (x - a.day) / (b.day - a.day);
+	return a.weight + t * (b.weight - a.weight);
+}
+
+/**
+ * Convenience: derive the expected active-day count from a curve over a span
+ * of `maxDayOffset` days. Sum of weights across days [0, maxDayOffset].
+ *
+ * @param {RetentionCurveConfig} curve
+ * @param {number} maxDayOffset - Number of days to sum over (exclusive upper).
+ * @returns {number}
+ */
+export function expectedActiveDays(curve, maxDayOffset) {
+	const fn = buildCurveWeightFn(curve);
+	let sum = 0;
+	const span = Math.max(0, Math.floor(maxDayOffset));
+	for (let d = 0; d < span; d++) sum += fn(d);
+	return sum;
+}

package/lib/utils/utils.js

@@ -24,29 +24,56 @@ const { NODE_ENV = "unknown" } = process.env;
 let globalChance;
 let chanceInitialized = false;
 
+// v1.5.1: Optional second Chance instance dedicated to user-id generation.
+// When `Dungeon.userSeed` is set, the orchestrator calls `initUserChance(userSeed)`
+// to bind this — `chance.guid()` for `distinct_id` (user-loop.js) then uses it,
+// allowing two runs with the SAME `userSeed` but DIFFERENT `seed` to produce the
+// SAME user pool with DIFFERENT events. Used by sharded/cloud-run dungeons that
+// need cross-shard user identity (e.g., dungeons/user/kodiak).
+// Falls back to `globalChance` when never initialized — so all existing dungeons
+// behave unchanged.
+let globalUserChance;
+let userChanceInitialized = false;
+
 // 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();
-let DATASET_BEGIN = dayjs.utc().subtract(30, 'day');
+// v1.5.1: dataset-window state moved to AsyncLocalStorage scope
+// (`lib/utils/dataset-context.js`). Each `generate()` call wraps the pipeline
+// in `runWithDataset(begin, now, fn)`, and factory thunks read via the
+// `getDatasetNow()` / `getDatasetBegin()` getters below. Concurrent in-process
+// `generate()` calls no longer clobber each other's window.
+//
+// `setDatasetNow` / `setDatasetBegin` remain as DEPRECATED shims that write to
+// a legacy fallback in dataset-context.js — kept so existing tests that call
+// the setters directly (instead of wrapping in `runWithDataset`) continue
+// working through v1.5.1. The getters check ALS first, then the legacy
+// fallback, then wall-clock.
+import {
+	getDatasetNow as _alsGetDatasetNow,
+	getDatasetBegin as _alsGetDatasetBegin,
+	_setLegacyDatasetNow,
+	_setLegacyDatasetBegin,
+} from './dataset-context.js';
 
-/** @param {number} unixSeconds */
+/**
+ * @deprecated v1.5.1 — use `runWithDataset(begin, now, fn)` from
+ * `lib/utils/dataset-context.js` to scope the dataset window per
+ * `generate()` call. The setter is kept as a back-compat shim that writes
+ * to a legacy fallback store; ALS scopes always win when active.
+ * @param {number} unixSeconds
+ */
 function setDatasetNow(unixSeconds) {
-	if (typeof unixSeconds === 'number' && Number.isFinite(unixSeconds)) {
-		DATASET_NOW = dayjs.unix(unixSeconds).utc();
-	}
+	_setLegacyDatasetNow(unixSeconds);
 }
 
-/** @param {number} unixSeconds */
+/**
+ * @deprecated v1.5.1 — see `setDatasetNow` for migration.
+ * @param {number} unixSeconds
+ */
 function setDatasetBegin(unixSeconds) {
-	if (typeof unixSeconds === 'number' && Number.isFinite(unixSeconds)) {
-		DATASET_BEGIN = dayjs.unix(unixSeconds).utc();
-	}
+	_setLegacyDatasetBegin(unixSeconds);
 }
 
 
@@ -57,9 +84,50 @@ class ListValue extends Array {
 	}
 }
 
-import { Storage as cloudStorage } from '@google-cloud/storage';
+import { Storage as cloudStorage, IdempotencyStrategy } from '@google-cloud/storage';
 const projectId = 'YOUR_PROJECT_ID';
-const storage = new cloudStorage({ projectId });
+// v1.5.1: aggressive retry config. Default SDK gives up after ~3 retries —
+// not enough at large parallel scale. The kodiak Cloud Run Job (1000 concurrent
+// tasks all uploading to GCS) saw "Retry limit exceeded" on ECONNRESET errors,
+// killing entire tasks (each costing ~$0.14 of wasted compute). These settings
+// retry up to 10 times with exponential back-off over a 10-min total budget,
+// covering ECONNRESET / ETIMEDOUT / EAI_AGAIN / 5xx responses.
+//
+// `IdempotencyStrategy.RetryConditional` (the SDK default) only retries when
+// the SDK can verify the operation didn't apply. Resumable upload chunk PUTs
+// are idempotent at the session/offset level, so they retry safely. We tried
+// `RetryAlways` once but it caused "offset is lower than bytes written" by
+// re-sending already-committed chunks — the conditional strategy is correct.
+const storage = new cloudStorage({
+	projectId,
+	retryOptions: {
+		autoRetry: true,
+		maxRetries: 10,
+		retryDelayMultiplier: 2,
+		totalTimeout: 600,        // 10-min total budget per request
+		maxRetryDelay: 64,        // cap each individual back-off at 64 sec
+		idempotencyStrategy: IdempotencyStrategy.RetryConditional,
+	},
+});
+
+// v1.5.1: GCS write options for ALL createWriteStream calls below.
+//
+// `resumable: true` is the SDK default and Google's recommendation for objects
+// >8 MB. Our gzip batches land at ~80 MB compressed; we previously forced
+// `resumable: false` to dodge a different bug (RetryAlways re-sending committed
+// chunks → "offset is lower than bytes written"). Forcing multipart uploads
+// made every batch one fragile 80 MB POST: any TCP hiccup mid-upload killed the
+// whole transfer and bubbled up as ECONNRESET. With `RetryConditional` (above)
+// the offset bug is gone — resumable is back to its proper default.
+//
+// `chunkSize: 8 MiB` enables true chunked resumable upload: the SDK PUTs each
+// 8 MB slice via the resumable session URL; ECONNRESET kills only the in-flight
+// chunk, the SDK queries the session for the committed offset and resumes.
+// 8 MiB is a multiple of GCS's 256 KiB chunk-alignment requirement (32 × 256 KiB).
+const GCS_WRITE_OPTS = {
+	resumable: true,
+	chunkSize: 8 * 1024 * 1024,
+};
 
 
 /*
@@ -96,6 +164,40 @@ function getChance() {
 	return globalChance;
 }
 
+/**
+ * Initialize the user-id RNG with a separate seed. Called by the orchestrator
+ * when `Dungeon.userSeed` is set (or env `USER_SEED`).
+ * @param {string} seed
+ * @returns {Chance}
+ */
+function initUserChance(seed) {
+	if (!seed && process.env.USER_SEED) seed = process.env.USER_SEED;
+	globalUserChance = new Chance(seed);
+	userChanceInitialized = true;
+	return globalUserChance;
+}
+
+/**
+ * Clear any previously-initialized user RNG so `getUserChance()` falls back to
+ * `getChance()` again. Called by the orchestrator at the start of every run
+ * when `Dungeon.userSeed` is NOT set, so state from a prior in-process run
+ * (e.g., a previous vitest spec) doesn't leak into the next.
+ */
+function resetUserChance() {
+	globalUserChance = undefined;
+	userChanceInitialized = false;
+}
+
+/**
+ * Returns the user-id RNG. Falls back to the event RNG (`getChance()`) when
+ * `userSeed` was not configured, so existing dungeons stay byte-identical.
+ * @returns {Chance}
+ */
+function getUserChance() {
+	if (!userChanceInitialized) return getChance();
+	return globalUserChance;
+}
+
 /*
 ----
 PICKERS
@@ -132,9 +234,12 @@ function pick(items) {
  */
 function date(inTheLast = 30, isPast = true, format = 'YYYY-MM-DD') {
 	const chance = getChance();
-	const now = DATASET_NOW;
 	if (Math.abs(inTheLast) > 365 * 10) inTheLast = chance.integer({ min: 1, max: 180 });
 	return function () {
+		// v1.5.1: read DATASET_NOW per-invocation (inside the thunk) so the value
+		// reflects the ALS scope active at event-generation time, not the wall-clock
+		// captured when the dungeon module was loaded.
+		const now = _alsGetDatasetNow();
 		const when = chance.integer({ min: 0, max: Math.abs(inTheLast) });
 		let then;
 		if (isPast) {
@@ -188,19 +293,22 @@ function datesBetween(start, end) {
  * @param  {any} end
  */
 function day(start, end) {
-	if (!start) start = DATASET_NOW.subtract(30, 'd').toISOString();
-	if (!end) end = DATASET_NOW.toISOString();
 	const chance = getChance();
 	const format = 'YYYY-MM-DD';
+	const startArg = start;
+	const endArg = end;
 	return function (min, max) {
-		start = dayjs(start);
-		end = dayjs(end);
-		const diff = end.diff(start, 'day');
+		// v1.5.1: read DATASET_NOW per-invocation so missing args resolve against
+		// the active ALS scope, not the wall-clock at factory-call time.
+		const now = _alsGetDatasetNow();
+		const sResolved = startArg != null ? dayjs(startArg) : dayjs(now.subtract(30, 'd').toISOString());
+		const eResolved = endArg != null ? dayjs(endArg) : dayjs(now.toISOString());
+		const diff = eResolved.diff(sResolved, 'day');
 		const delta = chance.integer({ min: min, max: diff });
-		const day = start.add(delta, 'day');
+		const day = sResolved.add(delta, 'day');
 		return {
-			start: start.format(format),
-			end: end.format(format),
+			start: sResolved.format(format),
+			end: eResolved.format(format),
 			day: day.format(format)
 		};
 	};
@@ -216,8 +324,8 @@ function day(start, end) {
 function dateRange(start, end, format = 'YYYY-MM-DDTHH:mm:ss') {
 	return function () {
 		const chance = getChance();
-		const s = start != null ? dayjs(typeof start === 'number' ? start * 1000 : start).utc() : DATASET_BEGIN;
-		const e = end != null ? dayjs(typeof end === 'number' ? end * 1000 : end).utc() : DATASET_NOW;
+		const s = start != null ? dayjs(typeof start === 'number' ? start * 1000 : start).utc() : _alsGetDatasetBegin();
+		const e = end != null ? dayjs(typeof end === 'number' ? end * 1000 : end).utc() : _alsGetDatasetNow();
 		const diffSec = e.diff(s, 'second');
 		const offsetSec = chance.integer({ min: 0, max: Math.max(0, diffSec) });
 		const result = s.add(offsetSec, 'second');
@@ -578,7 +686,7 @@ function streamJSON(filePath, data, options = {}) {
 
 		if (filePath?.startsWith('gs://')) {
 			const { uri, bucket, file } = parseGCSUri(filePath);
-			const gcsStream = storage.bucket(bucket).file(file).createWriteStream();
+			const gcsStream = storage.bucket(bucket).file(file).createWriteStream(GCS_WRITE_OPTS);
 			gcsStream.on('finish', () => resolve(filePath));
 			gcsStream.on('error', reject);
 			if (gzip) {
@@ -615,7 +723,7 @@ function streamCSV(filePath, data, options = {}) {
 
 		if (filePath?.startsWith('gs://')) {
 			const { uri, bucket, file } = parseGCSUri(filePath);
-			const gcsStream = storage.bucket(bucket).file(file).createWriteStream();
+			const gcsStream = storage.bucket(bucket).file(file).createWriteStream(GCS_WRITE_OPTS);
 			gcsStream.on('finish', () => resolve(filePath));
 			gcsStream.on('error', reject);
 			if (gzip) {
@@ -730,7 +838,7 @@ async function streamParquet(filePath, data, options = {}) {
 		// @ts-ignore
 		const arrayBuffer = parquetWriteBuffer({ columnData });
 		const { bucket, file } = parseGCSUri(filePath);
-		const gcsStream = storage.bucket(bucket).file(file).createWriteStream();
+		const gcsStream = storage.bucket(bucket).file(file).createWriteStream(GCS_WRITE_OPTS);
 
 		return new Promise((resolve, reject) => {
 			gcsStream.on('finish', () => resolve(filePath));
@@ -1062,10 +1170,10 @@ function validateEventConfig(events) {
 }
 
 function validTime(chosenTime, earliestTime, latestTime) {
-	// Fallback: use module-scoped DATASET_BEGIN/NOW (set by orchestrator via
-	// setDatasetBegin/setDatasetNow). v1.5: no longer reads `global.FIXED_*`.
-	if (!earliestTime) earliestTime = DATASET_BEGIN.unix();
-	if (!latestTime) latestTime = DATASET_NOW.unix();
+	// Fallback: ALS-scoped DATASET_BEGIN/NOW (v1.5.1: was module-scoped, now
+	// resolved per `generate()` call via `runWithDataset` — see dataset-context.js).
+	if (!earliestTime) earliestTime = _alsGetDatasetBegin().unix();
+	if (!latestTime) latestTime = _alsGetDatasetNow().unix();
 
 	if (typeof chosenTime === 'number') {
 		if (chosenTime > 0) {
@@ -1287,10 +1395,10 @@ const DEFAULT_HOD_WEIGHTS = [
 ];
 
 function TimeSoup(earliestTime, latestTime, peaks = 5, deviation = 2, mean = 0, dayOfWeekWeights = DEFAULT_DOW_WEIGHTS, hourOfDayWeights = DEFAULT_HOD_WEIGHTS) {
-	// Fallback: use module-scoped DATASET_BEGIN/NOW (set by orchestrator via
-	// setDatasetBegin/setDatasetNow). v1.5: no longer reads `global.FIXED_*`.
-	if (!earliestTime) earliestTime = DATASET_BEGIN.unix();
-	if (!latestTime) latestTime = DATASET_NOW.unix();
+	// Fallback: ALS-scoped DATASET_BEGIN/NOW (v1.5.1: was module-scoped, now
+	// resolved per `generate()` call via `runWithDataset` — see dataset-context.js).
+	if (!earliestTime) earliestTime = _alsGetDatasetBegin().unix();
+	if (!latestTime) latestTime = _alsGetDatasetNow().unix();
 	const chance = getChance();
 	let totalRange = latestTime - earliestTime;
 	if (totalRange <= 0 || earliestTime > latestTime) {
@@ -1649,6 +1757,9 @@ export {
 	deepClone,
 	initChance,
 	getChance,
+	initUserChance,
+	getUserChance,
+	resetUserChance,
 	decimal,
 	validTime,
 	validEvent,

package/lib/verify/counting.js

@@ -168,6 +168,46 @@ export function nullAwareExtreme(values, mode) {
 	return any ? extreme : null;
 }
 
+/**
+ * v1.5.1: count distinct values of a flat property across events.
+ *
+ * Mixpanel parity: `COUNT_DISTINCT(prop)` aggregator (Insights). Skips
+ * null/undefined/empty-string values. Returns the distinct-value count plus
+ * the top-N most-frequent values (default 25, matching Mixpanel UI default).
+ *
+ * Property keys are FLAT on event records per the dungeon-master schema
+ * contract (see HOOKS.md §1) — no dot-path support.
+ *
+ * @param {Object[]} events
+ * @param {string} property - Flat property name.
+ * @param {Object} [options]
+ * @param {string} [options.event] - Optional event-name filter.
+ * @param {number} [options.topN=25] - Number of top values to include in the result.
+ * @returns {{ distinct_count: number, top_values: Array<{ value: any, count: number }> }}
+ */
+export function countDistinctValues(events, property, options = {}) {
+	if (!Array.isArray(events)) throw new Error('countDistinctValues: events must be an array');
+	if (typeof property !== 'string' || !property) throw new Error('countDistinctValues: property is required');
+	const topN = Number.isFinite(options.topN) && options.topN > 0 ? Math.floor(options.topN) : 25;
+	const filterEvent = typeof options.event === 'string' && options.event ? options.event : null;
+	const valueCounts = new Map();
+	for (const e of events) {
+		if (!e || typeof e !== 'object') continue;
+		if (filterEvent && e.event !== filterEvent) continue;
+		const v = e[property];
+		if (v === null || v === undefined || v === '') continue;
+		// Hashable normalization — Map keys distinguish primitives but objects
+		// use reference identity. For Mixpanel parity, stringify non-primitives.
+		const key = (typeof v === 'object') ? JSON.stringify(v) : v;
+		valueCounts.set(key, (valueCounts.get(key) || 0) + 1);
+	}
+	const sorted = [...valueCounts.entries()]
+		.sort((a, b) => b[1] - a[1])
+		.slice(0, topN)
+		.map(([value, count]) => ({ value, count }));
+	return { distinct_count: valueCounts.size, top_values: sorted };
+}
+
 /**
  * Partition events into time buckets by UTC calendar (`day`, `week`, or
  * `month`). Used by `emulateBreakdown` when `timeBucket` is set to slice any

package/lib/verify/emulate-breakdown.js

@@ -26,6 +26,7 @@ import { evaluateFunnel, evaluateAnyOrderCompletion } from './funnel-engine.js';
 import { buildIdentityMap, resolveUserId } from './identity.js';
 import {
 	countDistinctPeriods,
+	countDistinctValues,
 	nullAwareAvg,
 	nullAwareSum,
 	nullAwareExtreme,
@@ -125,7 +126,7 @@ function evaluateFunnelByOrder(userEvents, steps, options = {}) {
 
 /**
  * @typedef {Object} EmulateOptions
- * @property {'frequencyByFrequency'|'funnelFrequency'|'aggregatePerUser'|'timeToConvert'|'attributedBy'|'sessionMetrics'|'retention'} type
+ * @property {'frequencyByFrequency'|'funnelFrequency'|'aggregatePerUser'|'timeToConvert'|'attributedBy'|'sessionMetrics'|'retention'|'distinctCount'} type
  *
  * @property {string} [metricEvent]
  * @property {string} [breakdownByFrequencyOf]
@@ -232,6 +233,7 @@ export function emulateBreakdown(events, config) {
 		case 'attributedBy':         return attributedBy(events, /** @type {*} */ (cfg));
 		case 'sessionMetrics':       return sessionMetrics(events, /** @type {*} */ (cfg));
 		case 'retention':            return retention(events, /** @type {*} */ (cfg));
+		case 'distinctCount':        return distinctCount(events, /** @type {*} */ (cfg));
 		default: throw new Error(`emulateBreakdown: unknown type "${config.type}"`);
 	}
 }
@@ -563,6 +565,23 @@ function retention(events, { cohortEvent, returnEvent, dayBuckets = [1, 7, 14, 3
 //   [{ metric: 'duration',        avg_ms, median_ms, p90_ms, total_sessions }]
 //   [{ metric: 'eventsPerSession',avg, median, p90, total_sessions }]
 
+// ── COUNT_DISTINCT(property) — v1.5.1 ─────────────────────────────────────
+//
+// Mixpanel Insights `COUNT_DISTINCT(prop)` aggregator. Returns the count of
+// unique values of a flat property across events, plus the top-N most-frequent
+// values. Optionally filtered to a single event name.
+//
+// Schema contract (HOOKS.md §1): properties are FLAT on event records —
+// `e.utm_campaign`, not `e.properties.utm_campaign`. Dot-path support deferred.
+//
+// Returns a single row: `{ distinct_count, top_values: [{ value, count }] }`.
+
+function distinctCount(events, { property, event, topN = 25 }) {
+	if (!property) throw new Error('distinctCount requires `property`');
+	const result = countDistinctValues(events, property, { event, topN });
+	return [result];
+}
+
 function sessionMetrics(events, { event, metrics = ['count', 'duration', 'eventsPerSession'], identityMap }) {
 	const userEvents = groupByUser(events, identityMap);
 	const sessionsByUser = new Map();

package/lib/verify/index.js

@@ -24,6 +24,7 @@ export {
 export { buildIdentityMap, resolveUserId } from './identity.js';
 export {
 	countDistinctPeriods,
+	countDistinctValues,
 	nullAwareAvg,
 	nullAwareSum,
 	nullAwareExtreme,

package/lib/verify/schema-validator.js

@@ -13,7 +13,9 @@
 
 const CORE_KEYS = new Set(['event', 'time', 'insert_id', 'user_id']);
 const LOCATION_KEYS = ['city', 'region', 'country', 'country_code'];
-const DEVICE_KEYS = ['model', 'screen_height', 'screen_width', 'os', 'Platform', 'carrier', 'radio'];
+// v1.5.1: `Platform` removed — engine no longer stamps it as a default
+// device key (collided with dungeon-defined Platform props). See TODO #11.
+const DEVICE_KEYS = ['model', 'screen_height', 'screen_width', 'os', 'carrier', 'radio'];
 const CAMPAIGN_KEYS = ['utm_source', 'utm_campaign', 'utm_medium', 'utm_content', 'utm_term'];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.5.0",
+	"version": "1.5.2",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",
@@ -47,7 +47,15 @@
 		"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",
@@ -70,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