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

package/lib/utils/dataset-context.js

@@ -0,0 +1,103 @@
+/**
+ * v1.5.1: AsyncLocalStorage-scoped dataset-window context.
+ *
+ * Replaces the legacy module-scoped `DATASET_NOW` / `DATASET_BEGIN` mutable
+ * state in `lib/utils/utils.js`. Each `generate()` call wraps the pipeline in
+ * `runWithDataset(begin, now, fn)`, and the factory thunks (`date`, `day`,
+ * `dateRange`, `TimeSoup`, `validTime`) read from the ALS store via
+ * `getDatasetNow()` / `getDatasetBegin()` instead of module globals.
+ *
+ * This makes concurrent in-process `generate()` calls safe with respect to
+ * the dataset-window dimension. RNG scoping is a SEPARATE concurrency hole
+ * — see TODOs.md "Considered but punted" for the follow-up plan.
+ *
+ * Trip-ups (see plans/archived/globals-killplan-1.5.1/kill-globals.md §7):
+ *   - ALS does NOT propagate across child_process.fork / worker_threads.
+ *   - Tests that import dungeon configs at top-level evaluate thunks at
+ *     import time — those thunks fall back to wall-clock if invoked outside
+ *     a `runWithDataset` scope.
+ *   - Callbacks scheduled via setImmediate / setTimeout / native event
+ *     emitters MAY lose context. Audit at the orchestrator level.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc.js';
+dayjs.extend(utc);
+
+/** @type {AsyncLocalStorage<{ begin: number, now: number }>} */
+const datasetALS = new AsyncLocalStorage();
+
+/**
+ * Legacy fallback — written by the deprecated `setDatasetNow` / `setDatasetBegin`
+ * shims in `lib/utils/utils.js`. Used ONLY when no ALS scope is active. This
+ * keeps existing tests that call the setters directly (instead of wrapping in
+ * `runWithDataset`) functional through v1.5.1. v1.6 may remove the shims.
+ *
+ * @type {{ begin: number|null, now: number|null }}
+ */
+const legacyFallback = { begin: null, now: null };
+
+/** @internal — used by `setDatasetNow` / `setDatasetBegin` shims. */
+export function _setLegacyDatasetNow(unixSeconds) {
+	if (typeof unixSeconds === 'number' && Number.isFinite(unixSeconds)) {
+		legacyFallback.now = unixSeconds;
+	}
+}
+
+/** @internal — used by `setDatasetNow` / `setDatasetBegin` shims. */
+export function _setLegacyDatasetBegin(unixSeconds) {
+	if (typeof unixSeconds === 'number' && Number.isFinite(unixSeconds)) {
+		legacyFallback.begin = unixSeconds;
+	}
+}
+
+/**
+ * Run `fn` inside a dataset-window scope. Factory thunks invoked anywhere in
+ * the async call chain (sync or via `await`) will read the scoped window
+ * instead of the module fallback.
+ *
+ * @template T
+ * @param {number} datasetBeginUnix
+ * @param {number} datasetNowUnix
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithDataset(datasetBeginUnix, datasetNowUnix, fn) {
+	return datasetALS.run({ begin: datasetBeginUnix, now: datasetNowUnix }, fn);
+}
+
+/**
+ * Read the scoped dataset-now value. Resolution order:
+ *   1. ALS store (active `runWithDataset` scope) — production pipeline path.
+ *   2. Legacy fallback (set via deprecated `setDatasetNow` shim) — for tests.
+ *   3. Wall-clock `dayjs.utc()` — last-resort default.
+ *
+ * @returns {dayjs.Dayjs}
+ */
+export function getDatasetNow() {
+	const store = datasetALS.getStore();
+	if (store) return dayjs.unix(store.now).utc();
+	if (legacyFallback.now !== null) return dayjs.unix(legacyFallback.now).utc();
+	return dayjs.utc();
+}
+
+/**
+ * Read the scoped dataset-begin value. Same resolution as `getDatasetNow`,
+ * falling back to wall-clock minus 30 days.
+ *
+ * @returns {dayjs.Dayjs}
+ */
+export function getDatasetBegin() {
+	const store = datasetALS.getStore();
+	if (store) return dayjs.unix(store.begin).utc();
+	if (legacyFallback.begin !== null) return dayjs.unix(legacyFallback.begin).utc();
+	return dayjs.utc().subtract(30, 'day');
+}
+
+/**
+ * @returns {boolean} true when called inside a runWithDataset scope.
+ */
+export function hasDatasetScope() {
+	return datasetALS.getStore() !== undefined;
+}

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,20 +293,22 @@ function datesBetween(start, end) {
  * @param  {any} end
  */
 function day(start, end) {
-	// if (!end) end = global.FIXED_NOW ? global.FIXED_NOW : dayjs().unix();
-	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)
 		};
 	};
@@ -217,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');
@@ -579,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) {
@@ -616,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) {
@@ -731,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));
@@ -1063,8 +1170,10 @@ function validateEventConfig(events) {
 }
 
 function validTime(chosenTime, earliestTime, latestTime) {
-	if (!earliestTime) earliestTime = global.FIXED_BEGIN ? global.FIXED_BEGIN : dayjs().subtract(30, 'd').unix(); // 30 days ago
-	if (!latestTime) latestTime = global.FIXED_NOW ? global.FIXED_NOW : dayjs().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) {
@@ -1286,8 +1395,10 @@ const DEFAULT_HOD_WEIGHTS = [
 ];
 
 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();
+	// 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) {
@@ -1571,78 +1682,6 @@ function generateSessionId(seedStr) {
 	return [seg(), seg(), seg(), seg()].join("-");
 }
 
-/**
- * Redistributes events into temporal clusters (sessions).
- *
- * Algorithm:
- * 1. Sort events by time
- * 2. Determine number of sessions (total events / avg events per session)
- * 3. Generate session anchor times using TimeSoup
- * 4. Assign events round-robin to sessions
- * 5. Within each session, retime events with tight spacing (5-300s apart)
- * 6. Regenerate insert_ids for retimed events
- * 7. Re-sort by time
- *
- * Mutates events in place. Does NOT assign session_id (call assignSessionIds after).
- *
- * @param {Object[]} events - Array of event objects with .time (ISO string)
- * @param {number} timeoutMinutes - Session timeout in minutes (used to determine intra-session spacing)
- * @param {Object} soupParams - Parameters for TimeSoup anchor generation
- */
-function bunchIntoSessions(events, timeoutMinutes, soupParams) {
-	if (events.length < 2) return;
-
-	const chance = getChance();
-	const { earliestTime, latestTime, peaks, deviation, mean,
-		dayOfWeekWeights, hourOfDayWeights } = soupParams;
-
-	// Sort by time first
-	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
-
-	// Determine number of sessions: target 3-8 events per session
-	const eventsPerSession = chance.integer({ min: 3, max: 8 });
-	const numSessions = Math.max(1, Math.ceil(events.length / eventsPerSession));
-
-	// Generate session anchor times using TimeSoup
-	const anchors = [];
-	for (let i = 0; i < numSessions; i++) {
-		const soupTime = TimeSoup(earliestTime, latestTime, peaks, deviation, mean,
-			dayOfWeekWeights, hourOfDayWeights);
-		anchors.push(soupTime);
-	}
-	anchors.sort((a, b) => a - b);
-
-	// Distribute events across sessions round-robin (preserving original order → temporal order)
-	const sessionBuckets = anchors.map(() => []);
-	for (let i = 0; i < events.length; i++) {
-		const bucketIndex = Math.min(i % numSessions, numSessions - 1);
-		sessionBuckets[bucketIndex].push(events[i]);
-	}
-
-	// Retime events within each session
-	for (let s = 0; s < numSessions; s++) {
-		const bucket = sessionBuckets[s];
-		if (bucket.length === 0) continue;
-
-		let currentTime = anchors[s];
-		for (let e = 0; e < bucket.length; e++) {
-			const ev = bucket[e];
-			const clampedTime = Math.min(currentTime, 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}`);
-
-			// Advance time within session: 5-300 seconds (5s to 5min)
-			currentTime += chance.integer({ min: 5, max: 300 });
-		}
-	}
-
-	// Re-sort by time
-	events.sort((a, b) => a.time < b.time ? -1 : a.time > b.time ? 1 : 0);
-}
-
 /**
  * Assigns session IDs to a chronologically sorted array of events.
  * A new session starts when:
@@ -1661,6 +1700,7 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 
 	const timeoutMs = timeoutMinutes * 60 * 1000;
 	const maxSessionMs = 24 * 60 * 60 * 1000;
+	const DAY_MS = 86400 * 1000;
 
 	// Derive a stable seed from the first event so session IDs are deterministic
 	// across runs without consuming the main seeded RNG stream.
@@ -1668,15 +1708,21 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 	let currentSessionId = generateSessionId(`${userKey}-${events[0].time}`);
 	let sessionStartMs = new Date(events[0].time).getTime();
 	let lastEventMs = sessionStartMs;
+	let sessionDayIdx = Math.floor(sessionStartMs / DAY_MS);
 
 	for (const event of events) {
 		const eventMs = new Date(event.time).getTime();
 		const gapFromLast = eventMs - lastEventMs;
 		const sessionDuration = eventMs - sessionStartMs;
+		const dayIdx = Math.floor(eventMs / DAY_MS);
 
-		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs) {
+		// Mixpanel session_query.cpp:828-830, 911 — sessions terminate on a
+		// day-index change in qtz (UTC here). Three reset triggers: timeout
+		// gap, max-session cap, OR day boundary crossed.
+		if (gapFromLast > timeoutMs || sessionDuration > maxSessionMs || dayIdx !== sessionDayIdx) {
 			currentSessionId = generateSessionId(`${userKey}-${event.time}`);
 			sessionStartMs = eventMs;
+			sessionDayIdx = dayIdx;
 		}
 
 		event.session_id = currentSessionId;
@@ -1711,6 +1757,9 @@ export {
 	deepClone,
 	initChance,
 	getChance,
+	initUserChance,
+	getUserChance,
+	resetUserChance,
 	decimal,
 	validTime,
 	validEvent,
@@ -1747,7 +1796,6 @@ export {
 	formatDuration,
 	generateSessionId,
 	assignSessionIds,
-	bunchIntoSessions,
 	setDatasetNow,
 	setDatasetBegin,
 	dateRange,