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

package/lib/orchestrators/user-loop.js

@@ -15,6 +15,7 @@ import { makeEvent } from "../generators/events.js";
 import { makeFunnel } from "../generators/funnels.js";
 import { makeUserProfile } from "../generators/profiles.js";
 import { makeSCD } from "../generators/scd.js";
+import { buildCurveWeightFn, expectedActiveDays } from "../utils/retention-curve.js";
 
 /**
  * Main user generation loop that creates users, their profiles, events, and SCDs
@@ -42,6 +43,8 @@ export async function userLoop(context) {
 		scdProps,
 		numDays,
 		avgEventsPerUserPerDay,
+		avgActiveDaysPerUser,
+		retentionCurve,
 		percentUsersBornInDataset = 15,
 		strictEventCount = false,
 		bornRecentBias = 0, // -1..1; positive = births skew toward end of window
@@ -66,7 +69,10 @@ export async function userLoop(context) {
 	// Track if we've already logged the strict event count message
 	let hasLoggedStrictCountReached = false;
 
-	// Handle graceful shutdown on SIGINT (Ctrl+C)
+	// Handle graceful shutdown on SIGINT (Ctrl+C).
+	// CRITICAL: listener MUST be removed in a `finally` block — pre-fix, throws /
+	// cancellation paths leaked listeners across test runs, accumulating until
+	// Node fired the MaxListenersExceededWarning AND test workers stalled.
 	let cancelled = false;
 	const onSigint = () => {
 		cancelled = true;
@@ -75,6 +81,7 @@ export async function userLoop(context) {
 	};
 	process.on('SIGINT', onSigint);
 
+	try {
 	for (let i = 0; i < numUsers; i++) {
 		const userPromise = USER_CONN(async () => {
 			// Bail out if cancelled
@@ -114,7 +121,12 @@ export async function userLoop(context) {
 				percentComplete: Math.min(100, Math.round((context.getUserCount() / numUsers) * 100))
 			});
 
-			const userId = chance.guid();
+			// v1.5.1: distinct_id sourced from a separate `userChance` when
+			// `Dungeon.userSeed` is set. This lets sharded runs (e.g., kodiak
+			// Cloud Run Job) generate the SAME user pool with DIFFERENT events
+			// across shards. Falls back to the event chance when userSeed is
+			// unset so existing dungeons stay byte-identical.
+			const userId = u.getUserChance().guid();
 			const user = u.generateUser(userId, { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix: context.FIXED_NOW, avgDevicePerUser });
 			const { distinct_id, created } = user;
 			const userDevicePool = (user.anonymousIds && user.anonymousIds.length) ? user.anonymousIds.slice() : null;
@@ -214,9 +226,14 @@ export async function userLoop(context) {
 				dataQuality,
 			};
 
-			// Call user hook after profile creation (hooks override persona properties)
+			// Call user hook after profile creation (hooks override persona properties).
+			// v1.5.1: an explicit `null` return is interpreted as "drop the user
+			// PROFILE record" — the user's events still generate normally. Used
+			// by sharded runs that have one canonical chunk per bucket emit profiles
+			// while every other chunk skips them (see dungeons/user/kodiak/).
+			let dropUserProfile = false;
 			if (config.hook) {
-				await config.hook(profile, "user", {
+				const hookedProfile = await config.hook(profile, "user", {
 					user,
 					config,
 					userIsBornInDataset,
@@ -224,6 +241,9 @@ export async function userLoop(context) {
 					datasetStart: context.DATASET_START_SECONDS,
 					datasetEnd: context.DATASET_END_SECONDS
 				});
+				if (hookedProfile === null) {
+					dropUserProfile = true;
+				}
 			}
 
 			// SCD creation
@@ -263,24 +283,71 @@ export async function userLoop(context) {
 				: numDays;
 			const userEventBudget = ratePerDay * userActiveDays;
 
-			let numEventsThisUserWillPreform = Math.floor(chance.normal({
+			// v1.5.1 (TODO #10): per-user event budget.
+			//
+			// Removed:
+			//   - the 0.714 magic dampening factor (pre-existing vestigial constant)
+			//   - the ×5 / ×0.333 "power user" / "low activity" dice rolls
+			//     (E[dice mult] ≈ 1.62, combined with 0.714 ≈ 1.16x inflation
+			//     by design — produced 60-100% systematic overshoot on
+			//     `numEvents` targets across all macros).
+			//
+			// New: pure normal distribution around `userEventBudget` with
+			// `dev = userEventBudget / 3` (~68% of users within ±1σ of target,
+			// ~95% within ±2σ). Real heavy-tail behavior should come from
+			// `personas` (`eventMultiplier`) — explicit, opt-in, documented.
+			let numEventsThisUserWillPreform = Math.max(0, Math.round(chance.normal({
 				mean: userEventBudget,
-				dev: userEventBudget / u.integer(u.integer(2, 5), u.integer(2, 7))
-			}) * 0.714159265359);
-
-			// Power users and low-activity users logic
+				dev: userEventBudget / 3,
+			})));
 			if (persona) {
-				// Persona-driven event multiplier replaces the old dice rolls
 				numEventsThisUserWillPreform *= persona.eventMultiplier;
-			} else {
-				// Legacy behavior when no personas configured
-				chance.bool({ likelihood: 20 }) ? numEventsThisUserWillPreform *= 5 : null;
-				chance.bool({ likelihood: 15 }) ? numEventsThisUserWillPreform *= 0.333 : null;
 			}
 			numEventsThisUserWillPreform = Math.round(numEventsThisUserWillPreform);
 
 			let userFirstEventTime;
 
+			// ── v1.5 Active-day scheduling ──
+			// When `avgActiveDaysPerUser` is set, build a per-user day plan: a list
+			// of UTC day-start unix-seconds, one entry per planned event. Each event
+			// generation call pops the next day from the plan and constrains TimeSoup
+			// to that day's [start, end] range. Funnel events anchor on the picked
+			// day; subsequent funnel steps spill within `timeToConvert` hours.
+			//
+			// When unset, dayPlan stays null and behavior is fully legacy (TimeSoup
+			// across [adjustedCreated, FIXED_NOW]).
+			const soupCfgForActiveDay = /** @type {import('../../types').SoupConfig} */ (config.soup) || {};
+			// v1.5 follow-up (Fix #1): buildActiveDayPlan returns
+			// `{ plan, pickedDayBuckets }`. `pickedDayBuckets` flows into
+			// `applyEngagementDecay` so the decay filter never drops the last event
+			// on a picked day — preserving the configured distinct-day count.
+			// v1.5.1: also fires when `retentionCurve` is set (curve wins over
+			// explicit `avgActiveDaysPerUser` — see TODO #4 resolution (b)).
+			const hasActiveDaysKnob = (avgActiveDaysPerUser !== undefined && avgActiveDaysPerUser !== null && Number.isFinite(avgActiveDaysPerUser));
+			const hasRetentionCurve = !!retentionCurve;
+			const dayPlanResult = (hasActiveDaysKnob || hasRetentionCurve)
+				? buildActiveDayPlan({
+					adjustedCreated, fixedBegin: context.FIXED_BEGIN, fixedNow: context.FIXED_NOW,
+					avgActiveDaysPerUser, userActiveDays,
+					numEvents: numEventsThisUserWillPreform,
+					dowWeights: soupCfgForActiveDay.dayOfWeekWeights,
+					retentionCurve,
+					chance,
+				})
+				: null;
+			const dayPlan = dayPlanResult ? dayPlanResult.plan : null;
+			const pickedDayBuckets = dayPlanResult ? dayPlanResult.pickedDayBuckets : null;
+			let dayPlanCursor = 0;
+			const nextDayBounds = () => {
+				if (!dayPlan || !dayPlan.length) return null;
+				// When the plan is exhausted, wrap (over-generation due to noise rounding;
+				// bounded re-use keeps remaining events on picked days rather than spilling).
+				const dayStartSec = dayPlan[dayPlanCursor % dayPlan.length];
+				dayPlanCursor++;
+				const dayEndSec = Math.min(dayStartSec + 86400 - 1, context.FIXED_NOW);
+				return { earliest: Math.max(dayStartSec, context.FIXED_BEGIN), latest: dayEndSec };
+			};
+
 			const firstFunnels = funnels.filter((f) => f.isFirstFunnel)
 				.filter((f) => !f.conditions || matchConditions(profile, f.conditions))
 				.reduce(weighFunnels, []);
@@ -320,7 +387,16 @@ export async function userLoop(context) {
 			// PATH FOR USERS BORN IN DATASET AND PERFORMING FIRST FUNNEL
 			if (firstFunnels.length && userIsBornInDataset) {
 				const firstFunnel = chance.pickone(firstFunnels, user);
-				let cursor = adjustedCreated.subtract(noise(), 'seconds').unix();
+				// Active-day mode: anchor the first funnel on a picked day so the user's
+				// signup lands within their planned active window. Legacy mode: anchor at
+				// adjustedCreated minus a noise offset.
+				let cursor;
+				if (dayPlan) {
+					const bounds = nextDayBounds();
+					cursor = bounds ? bounds.earliest : adjustedCreated.subtract(noise(), 'seconds').unix();
+				} else {
+					cursor = adjustedCreated.subtract(noise(), 'seconds').unix();
+				}
 
 				// Resolve attempts plan. `attempts.{min,max}` count FAILED PRIORS; total
 				// passes = failedPriors + 1.  Validator coerced bounds; default both 0.
@@ -372,9 +448,13 @@ export async function userLoop(context) {
 
 				userFirstEventTime = firstAttemptFirstEventTime !== null
 					? firstAttemptFirstEventTime
-					: adjustedCreated.subtract(noise(), 'seconds').unix();
+					: Math.max(adjustedCreated.subtract(noise(), 'seconds').unix(), context.FIXED_BEGIN);
 			} else {
-				userFirstEventTime = adjustedCreated.subtract(noise(), 'seconds').unix();
+				// v1.5.1: clamp at FIXED_BEGIN so pre-existing-user events stay strictly
+				// inside the dataset window. Without this, `noise()` (up to 1 day) can
+				// shift the first-event time before FIXED_BEGIN — fine when the dataset
+				// is years long, but visible at sub-day chunk windows (kodiak shards).
+				userFirstEventTime = Math.max(adjustedCreated.subtract(noise(), 'seconds').unix(), context.FIXED_BEGIN);
 			}
 
 			// ALL SUBSEQUENT EVENTS (funnels for converted users, standalone for all)
@@ -391,20 +471,121 @@ export async function userLoop(context) {
 			// Usage funnels for converted users: identity already stitched, just default 'both'.
 			const usageAttemptMeta = { isFirstFunnel: false, isBorn: userIsBornInDataset, devicePool: userDevicePool };
 
-			let usageFunnelCursor = userFirstEventTime;
-			while (numEventsPreformed < numEventsThisUserWillPreform && !cancelled) {
+			// v1.5 follow-up (engine bunchiness fix, 2026-05-09):
+			// REMOVED `usageFunnelCursor` accumulator. Each funnel call now uses
+			// `userFirstEventTime` (constant) as the anchor. Without this, the cursor
+			// chained `last_event_time + small_gap` between funnel runs, walking past
+			// FIXED_NOW and producing the right-edge bunchiness regression. See
+			// `plans/ENGINE-BUNCHINESS/FIX.md` for the full diagnosis.
+			//
+			// Loop budget now counts SURVIVING events (post `_drop`), not raw output.
+			// Combined with the cursor removal, this gives each funnel an independent
+			// uniform-in-window anchor (via TimeSoup) and lets the budget loop iterate
+			// until the user actually has the target event count.
+			//
+			// v1.5: when auto-promote marks every event strict (e.g. all events appear in
+			// the only funnel), there's nothing for the standalone branch to pick. Bail
+			// out cleanly rather than crashing on `pick([])`.
+			const hasUsageFunnels = usageFunnels.length > 0;
+			const hasStandaloneEvents = weightedEvents.length > 0;
+			// v1.5.1 (TODO #10): shortest usage-funnel length. Used to decide
+			// whether the remaining budget can fit another funnel run — funnels
+			// add N events at once, so iterations near the budget ceiling
+			// systematically overshot. Now we redirect to standalone (or break)
+			// when the remaining headroom is smaller than the smallest funnel.
+			const minUsageFunnelLen = hasUsageFunnels
+				? Math.min(...usageFunnels.map(f => Array.isArray(f.sequence) ? f.sequence.length : 1))
+				: Infinity;
+			// Hard ceiling on iterations: defends against pathological configs where
+			// every funnel produces 0 surviving events (e.g. ttc > numDays so step1
+			// uniform anchor always lands too late). Cap at 2× expected iteration count
+			// based on average funnel length (~7 steps) to avoid infinite loops.
+			const MAX_ITERATIONS = Math.max(100, numEventsThisUserWillPreform * 2);
+			let iterationCount = 0;
+			while (numEventsPreformed < numEventsThisUserWillPreform && !cancelled && iterationCount < MAX_ITERATIONS) {
+				iterationCount++;
 				let newEvents;
-				if (usageFunnels.length && userConverted) {
+				// v1.5 active-day: pop next picked-day bounds. Pass `latestTime` through
+				// featureCtx so makeEvent's TimeSoup confines to that day. Funnel cursor
+				// gets re-anchored to the picked day's start (subsequent funnel steps
+				// spill within `timeToConvert` hours; this is intentional).
+				const dayBounds = dayPlan ? nextDayBounds() : null;
+				// Compute step1's `latestTime` so the funnel's relative span fits before
+				// FIXED_NOW. Without this, born-late users + long-ttc funnels generate
+				// large numbers of `_drop`'d events that consume budget cycles. The
+				// safety margin is `timeToConvert * 3600 - 1` seconds (matches v1.5
+				// conversion window contract).
+				const standaloneFeatureCtx = dayBounds
+					? { ...featureCtx, latestTime: dayBounds.latest }
+					: featureCtx;
+				// Nothing to generate: user converted via firstFunnel only and has no
+				// usage funnels and no standalone events. Stop attempting.
+				if ((!hasUsageFunnels || !userConverted) && !hasStandaloneEvents) break;
+				// v1.5.1 (TODO #10): if the remaining budget can't fit even the
+				// shortest usage funnel, prefer a standalone event (or break if
+				// no standalone). Without this, the funnel branch added N events
+				// at once and overshot `numEvents` by `(funnel_length - 1)` per
+				// terminal iteration — measured ~5-15% systematic overshoot.
+				const remainingBudget = numEventsThisUserWillPreform - numEventsPreformed;
+				const useFunnel = hasUsageFunnels && userConverted && remainingBudget >= minUsageFunnelLen;
+				// Budget exhausted for funnels AND no standalone → break.
+				if (!useFunnel && !hasStandaloneEvents) break;
+				if (useFunnel) {
 					const currentFunnel = chance.pickone(usageFunnels);
-					const [data, converted] = await makeFunnel(context, currentFunnel, user, usageFunnelCursor, profile, userSCD, persona, featureCtx, usageAttemptMeta);
+					const ttcSec = (currentFunnel.timeToConvert || 0) * 3600;
+					// Anchor cursor at picked day's start when active-day mode is on,
+					// otherwise pass userFirstEventTime (constant). NO cursor accumulation.
+					const funnelCursor = dayBounds ? dayBounds.earliest : userFirstEventTime;
+					// Constrain funnel step1's TimeSoup latestTime so the full funnel fits in
+					// window. Without this, late steps spill past FIXED_NOW and get `_drop`'d.
+					//
+					// v1.5 final (2026-05-09): `FUNNEL_DEAD_ZONE_CAP_SEC = 0` — funnels can
+					// anchor step1 right up to FIXED_NOW. Earlier rounds defended against a
+					// cursor-accumulation bug by reserving a `ttc`-sized dead zone at the
+					// right edge; round 1 fixed cursor accumulation directly, leaving the
+					// dead zone as defense-in-depth. The future-time guard at storage step
+					// 14 (per CLAUDE.md "Execution Order") drops any event with `time >
+					// FIXED_NOW`, so spillover from late funnel steps is filtered there
+					// instead of by anchoring upstream. Removing the dead zone eliminated
+					// the last-day cliff for funnel-heavy dungeons WITHOUT re-introducing
+					// `futureEvents > 0` — verified across the 194-combo engine-validation
+					// sweep (`scripts/sweep-engine.mjs`, `plans/ENGINE-VALIDATION/FIX.md`).
+					//
+					// Trade-off retained: long-ttc funnels still lose some late steps to
+					// `_drop`. Budget loop iterates more to compensate. Catch-all funnel
+					// (`ttc=1d`, set in config-validator) is unaffected.
+					//
+					// Born-late edge case: when `funnelCursor > FN`, the `safeLatest >
+					// funnelCursor` check below falls back to `FN` so the user can emit.
+					const FUNNEL_DEAD_ZONE_CAP_SEC = 0;
+					const deadZoneSec = Math.min(ttcSec, FUNNEL_DEAD_ZONE_CAP_SEC);
+					const safeLatest = context.FIXED_NOW - deadZoneSec;
+					const funnelLatestTime = dayBounds
+						? dayBounds.latest
+						: (safeLatest > funnelCursor ? safeLatest : context.FIXED_NOW);
+					const funnelEventFeatureCtx = { ...featureCtx, latestTime: funnelLatestTime };
+					const [data, converted] = await makeFunnel(context, currentFunnel, user, funnelCursor, profile, userSCD, persona, funnelEventFeatureCtx, usageAttemptMeta);
+					// Budget counts raw output (matches pre-fix semantics). For short-ttc
+					// funnels (≤1d), almost no events `_drop` so the loop terminates at the
+					// expected count. For long-ttc funnels (>1d), some late steps `_drop` —
+					// loop iterates more to compensate, world-event `_drop`s still reduce
+					// the user's surviving total since they fire on dropped events too.
 					numEventsPreformed += data.length;
 					newEvents = data;
-					if (data.length) {
-						const lastTime = dayjs(data[data.length - 1].time).unix();
-						usageFunnelCursor = lastTime + chance.integer({ min: 60, max: 30 * 60 });
-					}
 				} else {
-					const data = await makeEvent(context, distinct_id, userFirstEventTime, u.pick(weightedEvents), user.anonymousIds, {}, config.groupKeys, true, false, featureCtx, standaloneIdentityCtx);
+					// Active-day mode: standalone event uses picked-day start as earliestTime
+					// + day-end as latestTime (passed via eventFeatureCtx).
+					// `isFirstEvent: false` (8th arg) so TimeSoup distributes the timestamp
+					// — passing `true` here would pin every standalone event to the same
+					// `earliestTime`, which the now-deleted bunchIntoSessions used to paper
+					// over. With bunchIntoSessions removed, TimeSoup is the time source.
+					const standaloneEarliest = dayBounds ? dayBounds.earliest : userFirstEventTime;
+					// v1.5.1: pass `config.superProps` so standalone events get super-property
+					// stamping. Pre-1.5.1, standalone events received `{}` here, but the
+					// validator's auto-funnel (catch-all) consumed all non-strict events so
+					// the bug was invisible. The TODO #10 `useFunnel` gate redirects some
+					// budget-boundary iterations to standalone, exposing the gap.
+					const data = await makeEvent(context, distinct_id, standaloneEarliest, u.pick(weightedEvents), user.anonymousIds, config.superProps || {}, config.groupKeys, false, false, standaloneFeatureCtx, standaloneIdentityCtx);
 					numEventsPreformed++;
 					newEvents = [data];
 				}
@@ -434,7 +615,7 @@ export async function userLoop(context) {
 			const userDecay = persona?.engagementDecay || globalEngagementDecay;
 			if (userDecay && userDecay.model !== 'none' && usersEvents.length > 0) {
 				// adjustedCreated and event times now share the same dataset window — no shift.
-				usersEvents = applyEngagementDecay(usersEvents, userDecay, adjustedCreated, context, chance);
+				usersEvents = applyEngagementDecay(usersEvents, userDecay, adjustedCreated, context, chance, pickedDayBuckets);
 			}
 
 			// Feature 4: Data quality — duplicates and late-arriving
@@ -460,18 +641,17 @@ export async function userLoop(context) {
 				}
 			}
 
-			// Session clustering: redistribute events into temporal bursts, then assign session IDs
+			// Session clustering: assign session IDs based on natural temporal gaps.
+			// v1.5: bunchIntoSessions deleted — was a redundant wholesale time-overwrite
+			// that scrambled multi-step funnels (round-robin into anchor buckets) and
+			// clobbered v1.5 active-day picking. assignSessionIds operates on the original
+			// TimeSoup-driven timestamps (Mixpanel-aligned 30-min-gap rule).
 			if (hasSessionIds && usersEvents.length > 0) {
-				const soupCfg = /** @type {import('../../types').SoupConfig} */ (config.soup) || {};
-				const defaultPeaks = Math.max(5, (config.numDays || 30) * 2);
-				const { mean: soupMean = 0, deviation: soupDev = 2, peaks: soupPeaks = defaultPeaks,
-					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD } = soupCfg;
-
-				u.bunchIntoSessions(usersEvents, sessionTimeout, {
-					earliestTime: userFirstEventTime,
-					latestTime: context.FIXED_NOW,
-					peaks: soupPeaks, deviation: soupDev, mean: soupMean,
-					dayOfWeekWeights: soupDOW, hourOfDayWeights: soupHOD
+				// assignSessionIds requires events sorted ascending by time.
+				usersEvents.sort((a, b) => {
+					const ta = typeof a.time === 'string' ? Date.parse(a.time) : Number(a.time);
+					const tb = typeof b.time === 'string' ? Date.parse(b.time) : Number(b.time);
+					return ta - tb;
 				});
 				u.assignSessionIds(usersEvents, sessionTimeout);
 
@@ -493,6 +673,23 @@ export async function userLoop(context) {
 				}
 			}
 
+			// v1.5: Touchpoint cap. Sample up to `maxTouchpointsPerUser` (default 10,
+			// matching Mixpanel `TOUCHPOINTS_LIMIT`) eligible events from the user's
+			// lifetime and stamp UTMs on the sample. Lifetime-distributed sampling
+			// preserves realistic touch shape — last-10-window attribution then
+			// gives meaningful first/last-touch results.
+			if (config.hasCampaigns && usersEvents.length > 0) {
+				applyTouchpointCap(usersEvents, config, defaults, chance);
+			}
+
+			// v1.5.1: anonymous non-converters never call $identify in production,
+			// so Mixpanel never creates a profile for them. Stamp `_drop: true` so
+			// mixpanel-sender skips the /engage push. Stamped BEFORE the everything
+			// hook fires so hooks can rescue a profile by deleting the flag.
+			if (userIsBornInDataset && !userAuthed) {
+				profile._drop = true;
+			}
+
 			// Hook for processing all user events (hooks override everything)
 			if (config.hook) {
 				// `meta.isPreAuth(event)` predicate bound to this user's auth state.
@@ -521,17 +718,44 @@ export async function userLoop(context) {
 				if (Array.isArray(newEvents)) usersEvents = newEvents;
 			}
 
+			// v1.5: auto-sort by time after everything hook. 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. Opt out with `autoSortAfterEverything: false`.
+			if (config.autoSortAfterEverything !== false && usersEvents.length > 1) {
+				usersEvents.sort((a, b) => {
+					const ta = (a && typeof a.time === 'string') ? Date.parse(a.time) : Number(a && a.time);
+					const tb = (b && typeof b.time === 'string') ? Date.parse(b.time) : Number(b && b.time);
+					if (!Number.isFinite(ta) && !Number.isFinite(tb)) return 0;
+					if (!Number.isFinite(ta)) return 1;
+					if (!Number.isFinite(tb)) return -1;
+					return ta - tb;
+				});
+			}
+
 			// Defensive guard: drop any events whose timestamp landed past the
 			// configured dataset end. Hooks that duplicate events with time offsets
 			// (weekend surges, viral spreads) can leak a few past the boundary.
+			// v1.5 follow-up (`reccomendations-agent-1.md` Fix #2): surface the drop
+			// in verbose mode. Silent dropping made determinism failures hard to debug
+			// — events vanished without trace. Per-user log helps the owner see which
+			// users + how many events were affected.
+			const beforeFutureFilter = usersEvents.length;
 			usersEvents = usersEvents.filter(e => {
 				if (!e || !e.time) return true;
 				const t = typeof e.time === 'string' ? Date.parse(e.time) / 1000 : Number(e.time);
 				return Number.isFinite(t) ? t <= context.FIXED_NOW : true;
 			});
+			const droppedFuture = beforeFutureFilter - usersEvents.length;
+			if (droppedFuture > 0 && config.verbose) {
+				console.warn(`⚠️  Dropped ${droppedFuture} future-dated event(s) for user ${distinct_id}`);
+			}
 
-			// Store all user data
-			await userProfilesData.hookPush(profile);
+			// Store all user data (skip profile push when a hook returned null
+			// for type='user' — see dropUserProfile above).
+			if (!dropUserProfile) {
+				await userProfilesData.hookPush(profile);
+			}
 
 			if (Object.keys(userSCD).length) {
 				for (const [key, changesArray] of Object.entries(userSCD)) {
@@ -553,18 +777,34 @@ export async function userLoop(context) {
 		});
 
 		userPromises.push(userPromise);
+
+		// v1.5.1: V8's Promise.all has a hard ceiling (~65K elements). Sharded
+		// kodiak runs pass numUsers in the millions per chunk, which blows that
+		// limit. Drain the in-flight buffer in batches of 50K to keep Promise.all
+		// well under the cap. With p-limit honoring `concurrency`, this is purely
+		// a backpressure boundary — no behavior change for existing dungeons that
+		// have numUsers under 50K.
+		if (userPromises.length >= 50_000) {
+			await Promise.all(userPromises);
+			userPromises.length = 0;
+		}
 	}
 
-	// Wait for all users to complete
-	await Promise.all(userPromises);
+	// Drain whatever's left in the final partial batch.
+	if (userPromises.length > 0) {
+		await Promise.all(userPromises);
+		userPromises.length = 0;
+	}
 
 	// Feature 4: Generate bot users (after regular users)
 	if (dataQuality && dataQuality.botUsers > 0) {
 		await generateBotUsers(context, dataQuality, storage);
 	}
-
-	// Clean up SIGINT handler
-	process.removeListener('SIGINT', onSigint);
+	} finally {
+		// Always remove the SIGINT listener — even if userLoop throws or is
+		// cancelled. Pre-fix this leaked across test runs and stalled workers.
+		process.removeListener('SIGINT', onSigint);
+	}
 }
 
 
@@ -583,12 +823,285 @@ export function matchConditions(profile, conditions) {
 	return true;
 }
 
+// ── v1.5 Active-Day Plan Helpers ──
+
+/**
+ * Build a deterministic per-user "day plan" for active-day mode.
+ *
+ * Each element of `plan` names the day on which the event-i should land. Events
+ * naturally concentrate onto `targetActiveDays` distinct days (drawn from a normal
+ * around `avgActiveDaysPerUser`, clamped to `[1, userActiveDays]`).
+ *
+ * Day picking uses weighted-without-replacement against soup DOW weights so the
+ * cohort-level weekly rhythm is preserved. Event distribution across picked days
+ * is proportional to those same weights, with a floor of 1 event per picked day.
+ *
+ * **Return shape (v1.5 follow-up — `reccomendations-agent-1.md` Fix #1):**
+ *   `{ plan, pickedDayBuckets }` — `plan` is the shuffled per-event day-start
+ *   unix-seconds array; `pickedDayBuckets` is a `Set<number>` of UTC-day-index
+ *   buckets (`Math.floor(timestamp_ms / 86400000)`). Downstream consumers like
+ *   `applyEngagementDecay` use `pickedDayBuckets` to enforce the v1.5
+ *   distinct-day contract — see Fix #1 below.
+ *
+ * @param {Object} args
+ * @param {import('dayjs').Dayjs} args.adjustedCreated - User's "created" timestamp
+ * @param {number} args.fixedBegin - Dataset start (unix seconds)
+ * @param {number} args.fixedNow - Dataset end (unix seconds)
+ * @param {number} args.avgActiveDaysPerUser
+ * @param {number} args.userActiveDays - Capacity (max possible distinct days)
+ * @param {number} args.numEvents - Total events to schedule for this user
+ * @param {number[]} [args.dowWeights] - 7-element soup DOW weights (Sun..Sat)
+ * @param {import('../utils/retention-curve.js').RetentionCurveConfig} [args.retentionCurve]
+ *   v1.5.1 — when set, weights candidate days by curve(day_offset_from_birth)
+ *   instead of DOW weights AND derives the effective avgActiveDaysPerUser from
+ *   the curve's sum across the window.
+ * @param {Object} args.chance - Seeded chance instance
+ * @returns {{ plan: number[], pickedDayBuckets: Set<number> } | null} Day plan
+ *   + bucket set, or null if not applicable (no candidate days, no events, etc.).
+ */
+function buildActiveDayPlan({ adjustedCreated, fixedBegin, fixedNow, avgActiveDaysPerUser, userActiveDays, numEvents, dowWeights, retentionCurve, chance }) {
+	if (!Number.isFinite(numEvents) || numEvents <= 0) return null;
+
+	// Candidate day buckets: UTC days intersecting [max(adjustedCreated, FIXED_BEGIN), FIXED_NOW].
+	// Pre-existing users with 'uniform' preExistingSpread have adjustedCreated < FIXED_BEGIN;
+	// active-day mode constrains them to in-window days only (matches what Mixpanel sees).
+	const userStartUnix = Math.max(
+		Math.floor(adjustedCreated.unix()),
+		Math.floor(fixedBegin)
+	);
+	const userEndUnix = Math.floor(fixedNow);
+	if (userEndUnix < userStartUnix) return null;
+
+	const dayMs = 86400;
+	const firstDay = Math.floor(userStartUnix / dayMs);
+	const lastDay = Math.floor(userEndUnix / dayMs);
+	const candidateDays = [];
+	for (let d = firstDay; d <= lastDay; d++) {
+		candidateDays.push(d * dayMs);
+	}
+	if (!candidateDays.length) return null;
+
+	// v1.5.1 (TODO #4): when `retentionCurve` is set, weight candidate days by
+	// curve(day_offset_from_birth) — biases active-day selection toward the
+	// requested retention shape. Replaces DOW weighting entirely (curve wins).
+	// Otherwise: legacy DOW weights.
+	let weights;
+	if (retentionCurve) {
+		const curveFn = buildCurveWeightFn(retentionCurve);
+		const birthDay = Math.floor(userStartUnix / dayMs);
+		weights = candidateDays.map(daySec => {
+			const dayOffset = (daySec / dayMs) - birthDay;
+			const w = curveFn(dayOffset);
+			return Number.isFinite(w) && w > 0 ? w : 0.0001;
+		});
+	} else {
+		weights = candidateDays.map(daySec => {
+			if (!Array.isArray(dowWeights) || dowWeights.length !== 7) return 1;
+			const dow = new Date(daySec * 1000).getUTCDay();
+			const w = Number(dowWeights[dow]);
+			return Number.isFinite(w) && w > 0 ? w : 0.0001;
+		});
+	}
+
+	// Draw target active-day count: normal(mean, sd=mean/3), clamped.
+	// v1.5.1: when `retentionCurve` is set, the mean is derived from the curve's
+	// sum across the user's window (resolution (b): curve wins, explicit
+	// avgActiveDaysPerUser ignored).
+	const effectiveMean = retentionCurve
+		? Math.max(1, expectedActiveDays(retentionCurve, candidateDays.length))
+		: avgActiveDaysPerUser;
+	const meanActive = Math.max(1, Math.min(effectiveMean, candidateDays.length));
+	const sd = Math.max(0.5, meanActive / 3);
+	let targetActiveDays = Math.round(chance.normal({ mean: meanActive, dev: sd }));
+	targetActiveDays = Math.max(1, Math.min(targetActiveDays, candidateDays.length));
+
+	// Pick which days are active.
+	const pickedDays = weightedSampleNoReplacement(candidateDays, weights, targetActiveDays, chance);
+	if (!pickedDays.length) return null;
+	pickedDays.sort((a, b) => a - b);
+
+	// Recompute weights aligned to picked days for event distribution.
+	const pickedWeights = pickedDays.map(daySec => {
+		if (!Array.isArray(dowWeights) || dowWeights.length !== 7) return 1;
+		const dow = new Date(daySec * 1000).getUTCDay();
+		const w = Number(dowWeights[dow]);
+		return Number.isFinite(w) && w > 0 ? w : 0.0001;
+	});
+	const totalWeight = pickedWeights.reduce((s, x) => s + x, 0);
+
+	// Allocate event counts across picked days. Each picked day gets at least 1
+	// event so every day is "used" — distinct-day count actually hits target.
+	const k = pickedDays.length;
+	let allocations;
+	if (numEvents <= k) {
+		// Fewer events than picked days: distribute one each, sample which days get them.
+		const subPicks = weightedSampleNoReplacement(pickedDays, pickedWeights, numEvents, chance);
+		const subSet = new Set(subPicks);
+		allocations = pickedDays.map(d => subSet.has(d) ? 1 : 0);
+	} else {
+		// Floor 1 per picked day, distribute remainder proportionally.
+		const remainder = numEvents - k;
+		allocations = pickedWeights.map(w => Math.floor((remainder * w) / totalWeight));
+		// Add floor of 1 to each
+		for (let i = 0; i < k; i++) allocations[i] += 1;
+		// Distribute rounding remainder by descending weight order
+		let assigned = allocations.reduce((s, x) => s + x, 0);
+		let rem = numEvents - assigned;
+		const order = pickedDays.map((_, i) => i).sort((a, b) => pickedWeights[b] - pickedWeights[a]);
+		for (let i = 0; i < rem; i++) {
+			allocations[order[i % order.length]]++;
+		}
+	}
+
+	// Expand into a flat plan and shuffle deterministically.
+	const plan = [];
+	for (let i = 0; i < k; i++) {
+		for (let j = 0; j < allocations[i]; j++) {
+			plan.push(pickedDays[i]);
+		}
+	}
+	// v1.5 follow-up (Fix #1): expose the picked-day bucket set so engagement
+	// decay can protect the last surviving event per picked day. Buckets use
+	// the same `floor(ms / 86400000)` formula that decay applies to event times.
+	const pickedDayBuckets = new Set(pickedDays.map(daySec => Math.floor(daySec / 86400)));
+	// chance.shuffle uses seeded RNG → deterministic.
+	return { plan: chance.shuffle(plan), pickedDayBuckets };
+}
+
+/**
+ * v1.5 Touchpoint cap: sample up to `maxTouchpointsPerUser` eligible events from
+ * the user's stream and stamp UTMs on the sample. Mirrors Mixpanel's
+ * `TOUCHPOINTS_LIMIT = 10` (`backend/libquery/properties_over_time/attributed_value_reader.cpp`).
+ *
+ * Eligibility:
+ *   - If any event in `config.events[]` has `isAttributionEvent: true`: candidate
+ *     pool = events whose name carries that flag.
+ *   - Else (legacy fallback): candidate pool = ALL events in the user's stream.
+ *
+ * Sampling:
+ *   - If `eligible.length <= cap`: stamp all of them.
+ *   - Else: uniform random sample of size `cap` (seeded `chance.pickset`,
+ *     deterministic). Sort sample chronologically before stamping so UTMs land
+ *     in time order.
+ *
+ * Mutates `events` in place.
+ *
+ * @param {Object[]} events - User's events (flat shape with .event, .time)
+ * @param {Object} config - Validated dungeon config
+ * @param {Object} defaults - Context.defaults (provides campaigns())
+ * @param {Object} chance - Seeded chance instance
+ */
+function applyTouchpointCap(events, config, defaults, chance) {
+	const cap = Number.isFinite(config.maxTouchpointsPerUser)
+		? config.maxTouchpointsPerUser
+		: 10;
+	if (cap <= 0) return;
+
+	// Build event-name → config map for isAttributionEvent lookup.
+	const eventCfgByName = new Map();
+	for (const e of (config.events || [])) {
+		if (e && e.event) eventCfgByName.set(e.event, e);
+	}
+
+	// Determine eligible events.
+	let eligible;
+	if (config.hasAttributionFlags) {
+		eligible = events.filter(e => {
+			if (!e || !e.event) return false;
+			const cfg = eventCfgByName.get(e.event);
+			return cfg && cfg.isAttributionEvent === true;
+		});
+	} else {
+		eligible = events.slice();
+	}
+	if (eligible.length === 0) return;
+
+	// Sample up to cap (uniform random without replacement, seeded).
+	let sample;
+	if (eligible.length <= cap) {
+		sample = eligible;
+	} else {
+		sample = chance.pickset(eligible, cap);
+	}
+
+	// Sort sample chronologically so UTMs land in time order.
+	sample.sort((a, b) => {
+		const ta = typeof a.time === 'string' ? Date.parse(a.time) : Number(a.time);
+		const tb = typeof b.time === 'string' ? Date.parse(b.time) : Number(b.time);
+		return ta - tb;
+	});
+
+	// Stamp UTMs on each sampled event using a campaign template.
+	for (const ev of sample) {
+		const campaignTemplate = u.pickRandom(defaults.campaigns());
+		if (!campaignTemplate || typeof campaignTemplate !== 'object') continue;
+		for (const [k, v] of Object.entries(campaignTemplate)) {
+			ev[k] = u.choose(v);
+		}
+	}
+}
+
+/**
+ * Weighted-without-replacement sampler. Samples `count` items from `items` without
+ * replacement, with selection probability proportional to `weights`.
+ *
+ * @param {*[]} items
+ * @param {number[]} weights
+ * @param {number} count
+ * @param {Object} chance - Seeded chance instance
+ * @returns {*[]}
+ */
+function weightedSampleNoReplacement(items, weights, count, chance) {
+	if (count >= items.length) return items.slice();
+	const pool = items.slice();
+	const w = weights.slice();
+	const result = [];
+	for (let i = 0; i < count; i++) {
+		const total = w.reduce((s, x) => s + x, 0);
+		let chosen;
+		if (total <= 0) {
+			chosen = chance.integer({ min: 0, max: pool.length - 1 });
+		} else {
+			let roll = chance.floating({ min: 0, max: total });
+			chosen = 0;
+			for (let j = 0; j < w.length; j++) {
+				roll -= w[j];
+				if (roll <= 0) { chosen = j; break; }
+			}
+		}
+		result.push(pool[chosen]);
+		pool.splice(chosen, 1);
+		w.splice(chosen, 1);
+	}
+	return result;
+}
+
 // ── Advanced Feature Helper Functions ──
 
 /**
- * Feature 3: Apply engagement decay to a user's events
+ * Feature 3: Apply engagement decay to a user's events.
+ *
+ * Filters events probabilistically per the configured decay model
+ * (`exponential` / `linear` / `step`). Late events drop more often.
+ *
+ * **v1.5 follow-up (`reccomendations-agent-1.md` Fix #1):** when
+ * `pickedDayBuckets` is provided (active-day mode), the filter NEVER drops the
+ * last surviving event on any picked day. Without this, decay can silently
+ * undershoot the configured `avgActiveDaysPerUser` by killing all events on
+ * sparse late days (e.g., exponential decay with short half-life). The protect-
+ * last-event logic preserves the v1.5 distinct-day contract.
+ *
+ * @param {Object[]} events - User's events (mutated by filter; new array returned)
+ * @param {Object} decay - `engagementDecay` config (model/halfLife/floor/etc.)
+ * @param {*} userCreated - dayjs object or ISO string of user's creation time
+ * @param {Object} context - Engine context (unused; kept for future use)
+ * @param {Object} chance - Seeded chance instance
+ * @param {Set<number> | null} [pickedDayBuckets=null] - From `buildActiveDayPlan`.
+ *   Each bucket = `Math.floor(timestamp_ms / 86400000)`. When non-null, the
+ *   filter protects the last surviving event on each bucket.
+ * @returns {Object[]} Filtered events array
  */
-function applyEngagementDecay(events, decay, userCreated, context, chance) {
+function applyEngagementDecay(events, decay, userCreated, context, chance, pickedDayBuckets = null) {
 	if (!events.length) return events;
 	// Perf 2: Use Date.parse instead of dayjs for hot loop
 	const userStartUnix = new Date(userCreated.toISOString ? userCreated.toISOString() : userCreated).getTime() / 1000;
@@ -597,6 +1110,23 @@ function applyEngagementDecay(events, decay, userCreated, context, chance) {
 	const reactivationChance = decay.reactivationChance || 0;
 	const reactivationMult = decay.reactivationMultiplier || 2.0;
 
+	// v1.5 Fix #1: pre-compute per-bucket counts so we can enforce "at least one
+	// event survives on each picked day". Only counts events that fall within a
+	// picked-day bucket (events spilled to other days don't count toward the
+	// per-bucket survivor budget).
+	const dayMs = 86400000;
+	const dayCounts = new Map(); // bucket → remaining (mutable) event count
+	if (pickedDayBuckets && pickedDayBuckets.size) {
+		for (const ev of events) {
+			const t = new Date(ev.time).getTime();
+			if (!Number.isFinite(t)) continue;
+			const bucket = Math.floor(t / dayMs);
+			if (pickedDayBuckets.has(bucket)) {
+				dayCounts.set(bucket, (dayCounts.get(bucket) || 0) + 1);
+			}
+		}
+	}
+
 	return events.filter(ev => {
 		const evUnix = new Date(ev.time).getTime() / 1000;
 		const daysSinceBirth = Math.max(0, (evUnix - userStartUnix) / 86400);
@@ -621,7 +1151,27 @@ function applyEngagementDecay(events, decay, userCreated, context, chance) {
 			retention = Math.min(1.0, retention * reactivationMult);
 		}
 
-		return chance.bool({ likelihood: retention * 100 });
+		const keep = chance.bool({ likelihood: retention * 100 });
+
+		// v1.5 Fix #1: protect the last surviving event on each picked day.
+		// Determinism preserved: no extra RNG calls, just a count check.
+		if (pickedDayBuckets && pickedDayBuckets.size) {
+			const bucket = Math.floor(new Date(ev.time).getTime() / dayMs);
+			if (pickedDayBuckets.has(bucket)) {
+				const remaining = dayCounts.get(bucket) || 0;
+				if (!keep) {
+					if (remaining <= 1) {
+						// Last event on this picked day — protect it. Leave dayCounts
+						// at 1 so subsequent events on this bucket can still drop.
+						return true;
+					}
+					dayCounts.set(bucket, remaining - 1);
+				}
+				// If keep===true, no decrement — the survivor still counts.
+			}
+		}
+
+		return keep;
 	});
 }