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

package/lib/orchestrators/user-loop.js

@@ -42,6 +42,7 @@ export async function userLoop(context) {
 		scdProps,
 		numDays,
 		avgEventsPerUserPerDay,
+		avgActiveDaysPerUser,
 		percentUsersBornInDataset = 15,
 		strictEventCount = false,
 		bornRecentBias = 0, // -1..1; positive = births skew toward end of window
@@ -66,7 +67,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 +79,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
@@ -104,6 +109,16 @@ export async function userLoop(context) {
 				]);
 			}
 
+			context.reportProgress({
+				phase: "generation",
+				users: context.getUserCount(),
+				events: context.getEventCount(),
+				eps,
+				memory: memUsed,
+				elapsed: duration,
+				percentComplete: Math.min(100, Math.round((context.getUserCount() / numUsers) * 100))
+			});
+
 			const userId = chance.guid();
 			const user = u.generateUser(userId, { numDays, isAnonymous, hasAvatar, hasAnonIds, hasSessionIds, datasetEndUnix: context.FIXED_NOW, avgDevicePerUser });
 			const { distinct_id, created } = user;
@@ -271,6 +286,42 @@ export async function userLoop(context) {
 
 			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.
+			const dayPlanResult = (avgActiveDaysPerUser !== undefined && avgActiveDaysPerUser !== null && Number.isFinite(avgActiveDaysPerUser))
+				? buildActiveDayPlan({
+					adjustedCreated, fixedBegin: context.FIXED_BEGIN, fixedNow: context.FIXED_NOW,
+					avgActiveDaysPerUser, userActiveDays,
+					numEvents: numEventsThisUserWillPreform,
+					dowWeights: soupCfgForActiveDay.dayOfWeekWeights,
+					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, []);
@@ -310,7 +361,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.
@@ -381,20 +441,99 @@ 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;
+			// 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;
+				if (hasUsageFunnels && userConverted) {
 					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;
+					const data = await makeEvent(context, distinct_id, standaloneEarliest, u.pick(weightedEvents), user.anonymousIds, {}, config.groupKeys, false, false, standaloneFeatureCtx, standaloneIdentityCtx);
 					numEventsPreformed++;
 					newEvents = [data];
 				}
@@ -424,7 +563,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
@@ -450,18 +589,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);
 
@@ -483,6 +621,15 @@ 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);
+			}
+
 			// Hook for processing all user events (hooks override everything)
 			if (config.hook) {
 				// `meta.isPreAuth(event)` predicate bound to this user's auth state.
@@ -511,14 +658,38 @@ 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);
@@ -552,9 +723,11 @@ export async function userLoop(context) {
 	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);
+	}
 }
 
 
@@ -573,12 +746,261 @@ 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 {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, 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;
+
+	// Weight by soup DOW (Sun=0..Sat=6). Default uniform if no weights configured.
+	const 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.
+	const meanActive = Math.max(1, Math.min(avgActiveDaysPerUser, 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;
@@ -587,6 +1009,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);
@@ -611,7 +1050,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;
 	});
 }