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

package/lib/core/config-validator.js

@@ -168,6 +168,85 @@ function stripKilledConfigKeys(config) {
 	}
 }
 
+/**
+ * v1.5: validate / default `Funnel.conversionWindowDays` in place.
+ *
+ *   - Missing field + `timeToConvert/24 < 30`     → set to 30 (Mixpanel UI default)
+ *   - Missing field + `timeToConvert/24 >= 30`    → auto-bump to `min(180, ceil(ttc * 1.5))` + warn
+ *   - Field set > 180                              → throw (Mixpanel hard cap)
+ *
+ * Reference: `backend/arb/reader/funnels/conversion_window.cpp`.
+ *
+ * @param {import('../../types.js').Funnel[]} funnels
+ */
+function validateConversionWindow(funnels) {
+	const DEFAULT_WINDOW_DAYS = 30;
+	const MAX_WINDOW_DAYS = 180;
+	for (const f of funnels) {
+		if (!f) continue;
+		const ttcHours = Number.isFinite(f.timeToConvert) ? f.timeToConvert : 24;
+		const ttcDays = ttcHours / 24;
+		if (f.conversionWindowDays === undefined || f.conversionWindowDays === null) {
+			if (ttcDays >= DEFAULT_WINDOW_DAYS) {
+				f.conversionWindowDays = Math.min(MAX_WINDOW_DAYS, Math.ceil(ttcDays * 1.5));
+				console.warn(
+					`⚠️  Funnel "${f.name || (f.sequence && f.sequence.join(' > '))}": ` +
+					`timeToConvert (${ttcDays.toFixed(1)}d) exceeds default 30d conversion window. ` +
+					`Auto-set conversionWindowDays=${f.conversionWindowDays}. Set explicitly to silence.`
+				);
+			} else {
+				f.conversionWindowDays = DEFAULT_WINDOW_DAYS;
+			}
+		} else {
+			if (!Number.isFinite(f.conversionWindowDays) || f.conversionWindowDays <= 0) {
+				throw new Error(
+					`Funnel "${f.name || (f.sequence && f.sequence.join(' > '))}": ` +
+					`conversionWindowDays must be a positive finite number (got ${f.conversionWindowDays})`
+				);
+			}
+			if (f.conversionWindowDays > MAX_WINDOW_DAYS) {
+				throw new Error(
+					`Funnel "${f.name || (f.sequence && f.sequence.join(' > '))}": ` +
+					`conversionWindowDays cannot exceed ${MAX_WINDOW_DAYS} (Mixpanel hard cap)`
+				);
+			}
+		}
+	}
+}
+
+/**
+ * v1.5.0: validate `Funnel.exclusionEvents` in place.
+ *   - Each entry must reference an event in `events[]` (schema-first guarantee).
+ *   - Warn (don't throw) when an exclusion event is also a step in the funnel — the
+ *     verifier will treat its presence as a terminator, but the same name appearing as
+ *     a step is ambiguous.
+ *
+ * @param {import('../../types.js').Funnel[]} funnels
+ * @param {Array<{event?: string}>} events
+ */
+function validateExclusionEvents(funnels, events) {
+	if (!Array.isArray(funnels) || !Array.isArray(events)) return;
+	const eventNames = new Set(events.map(e => e && e.event).filter(Boolean));
+	for (const f of funnels) {
+		if (!f || !Array.isArray(f.exclusionEvents) || !f.exclusionEvents.length) continue;
+		for (const name of f.exclusionEvents) {
+			if (!eventNames.has(name)) {
+				throw new Error(
+					`Funnel "${f.name || (f.sequence && f.sequence.join(' > '))}": ` +
+					`exclusionEvents entry "${name}" is not declared in events[]. ` +
+					`Add it as an event (schema-first) before referencing it as an exclusion.`
+				);
+			}
+			if (Array.isArray(f.sequence) && f.sequence.includes(name)) {
+				console.warn(
+					`⚠️  Funnel "${f.name || (f.sequence && f.sequence.join(' > '))}": ` +
+					`exclusion event "${name}" is also a funnel step — semantics are ambiguous.`
+				);
+			}
+		}
+	}
+}
+
 /**
  * Validate `Funnel.attempts` config in place. Coerces missing/invalid bounds so callers
  * downstream don't have to re-defend. Throws on logically invalid configs (max < min).
@@ -373,6 +452,26 @@ export function validateDungeonConfig(config) {
 		avgEventsPerUserPerDay = numEvents / numUsers / numDays;
 	}
 
+	// ── v1.5 Active-day primitive validation ──
+	// `avgActiveDaysPerUser` is a CONCENTRATOR — total event count is preserved
+	// (`avgEventsPerUserPerDay × numDays`), but events cluster onto fewer days.
+	// The implied per-active-day rate inflates: warn when it exceeds 50.
+	const avgActiveDaysPerUser = config.avgActiveDaysPerUser;
+	if (avgActiveDaysPerUser !== undefined && avgActiveDaysPerUser !== null) {
+		if (!Number.isFinite(avgActiveDaysPerUser) || avgActiveDaysPerUser <= 0) {
+			throw new Error(`avgActiveDaysPerUser must be a positive finite number (got ${avgActiveDaysPerUser})`);
+		}
+		const impliedRatePerActiveDay = (avgEventsPerUserPerDay * numDays) / avgActiveDaysPerUser;
+		if (impliedRatePerActiveDay > 50) {
+			console.warn(
+				`⚠️  avgActiveDaysPerUser=${avgActiveDaysPerUser} concentrates ` +
+				`${Math.round(avgEventsPerUserPerDay * numDays).toLocaleString()} events into ${avgActiveDaysPerUser} day(s) ` +
+				`→ ${impliedRatePerActiveDay.toFixed(0)} events per active day. ` +
+				`If you want fewer total events, lower avgEventsPerUserPerDay.`
+			);
+		}
+	}
+
 	// Auto-enable batch mode for large datasets to prevent OOM.
 	// MUST run after rate→numEvents resolution above, otherwise dungeons that set
 	// only avgEventsPerUserPerDay would never trigger auto-batch.
@@ -396,14 +495,126 @@ export function validateDungeonConfig(config) {
 	let percentUsersBornInDataset = config.percentUsersBornInDataset !== undefined ? config.percentUsersBornInDataset : macroResolved.percentUsersBornInDataset;
 	let preExistingSpread = config.preExistingSpread !== undefined ? config.preExistingSpread : macroResolved.preExistingSpread;
 
-	// Clamp bornRecentBias to [-1, 1] — values outside this range produce
-	// nonsensical exponents (e.g. Math.pow(0, -0.4) = Infinity in user-loop.js).
-	if (typeof bornRecentBias === 'number' && Number.isFinite(bornRecentBias)) {
-		bornRecentBias = Math.max(-1, Math.min(1, bornRecentBias));
-	} else {
+	// ── v1.5 Engine-validation strict clamps ──────────────────────────────
+	// Pathological knob combinations produce nosedive / right-edge explosion
+	// patterns that no engine fix can rescue. We clamp them at validation time
+	// with a clear warning so dungeon authors fix the config rather than ship
+	// a broken-looking dataset. See `plans/ENGINE-VALIDATION/FIX.md` for the
+	// sweep evidence behind each rule.
+	// User-explicit detection. Fires when the value comes from EITHER top-level
+	// dungeon config OR macro-object override (e.g., `macro: { preset: 'growth',
+	// bornRecentBias: 0.5 }`). Both paths represent user intent to override; only
+	// raw preset names (e.g., `macro: 'growth'`) are exempt — their preset values
+	// are designed to be safe.
+	const macroAsObj = (config.macro && typeof config.macro === 'object' && !Array.isArray(config.macro))
+		? /** @type {{preset?: string, percentUsersBornInDataset?: number, bornRecentBias?: number}} */ (config.macro)
+		: null;
+	const userBornExplicit =
+		(config.percentUsersBornInDataset !== undefined && config.percentUsersBornInDataset !== null)
+		|| (macroAsObj !== null && macroAsObj.percentUsersBornInDataset !== undefined && macroAsObj.percentUsersBornInDataset !== null);
+	const userBiasExplicit =
+		(config.bornRecentBias !== undefined && config.bornRecentBias !== null)
+		|| (macroAsObj !== null && macroAsObj.bornRecentBias !== undefined && macroAsObj.bornRecentBias !== null);
+
+	// Coerce non-finite to 0 first (sanity)
+	if (typeof bornRecentBias !== 'number' || !Number.isFinite(bornRecentBias)) {
 		bornRecentBias = 0;
 	}
 
+	// Clamp 1: hard absolute bounds on born% (data sanity)
+	if (typeof percentUsersBornInDataset !== 'number' || !Number.isFinite(percentUsersBornInDataset)) {
+		percentUsersBornInDataset = 0;
+	}
+	if (percentUsersBornInDataset > 100) {
+		console.warn(`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} clamped to 100. Values above 100 are not meaningful.`);
+		percentUsersBornInDataset = 100;
+	}
+	if (percentUsersBornInDataset < 0) {
+		console.warn(`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} clamped to 0. Negative values are not meaningful.`);
+		percentUsersBornInDataset = 0;
+	}
+
+	// Clamp 2: per-macro born compatibility — fires when the user explicitly opts
+	// into a named macro AND explicitly sets born%. Macro = contract: "produce
+	// the shape this preset describes". Born% over the cap breaks that contract
+	// (cumulative-acquisition right-edge explosion). Caps match each preset's
+	// default `percentUsersBornInDataset` to preserve the macro's characteristic
+	// shape. Users who need higher born% should switch macros (flat→growth,
+	// growth→viral). When no macro is set, the clamp does NOT fire — legacy
+	// dungeons that set percentUsersBornInDataset directly without picking a
+	// macro keep their existing behavior. Tuned empirically against the
+	// engine-validation sweep matrix (research/engine-sweep-pass*.json).
+	const MACRO_BORN_CAP = { flat: 12, steady: 12, growth: 30, viral: 55, decline: 5 };
+	const macroExplicit = config.macro !== undefined && config.macro !== null;
+	const macroKey = (typeof config.macro === 'string')
+		? config.macro
+		: (config.macro && config.macro.preset) ? config.macro.preset : 'flat';
+	if (userBornExplicit && macroExplicit && MACRO_BORN_CAP[macroKey] !== undefined) {
+		const cap = MACRO_BORN_CAP[macroKey];
+		if (percentUsersBornInDataset > cap) {
+			console.warn(
+				`⚠️  macro="${macroKey}" + percentUsersBornInDataset=${percentUsersBornInDataset} ` +
+				`clamped to ${cap}. High born% with macro="${macroKey}" produces cumulative-acquisition ` +
+				`right-edge explosion. Use macro="growth" or "viral" for genuinely high-born configs. ` +
+				`To suppress, fix the config.`
+			);
+			percentUsersBornInDataset = cap;
+		}
+	}
+
+	// Clamp 3: bornRecentBias safe range. Plan PROMPT.md "[-0.5, 0.5]". Only fires
+	// on user-set values — viral preset (0.6) is allowed by design.
+	if (userBiasExplicit) {
+		if (bornRecentBias > 0.5) {
+			console.warn(`⚠️  bornRecentBias=${bornRecentBias} clamped to 0.5. Above 0.5 produces unusable right-skew. To suppress, fix the config.`);
+			bornRecentBias = 0.5;
+		}
+		if (bornRecentBias < -0.5) {
+			console.warn(`⚠️  bornRecentBias=${bornRecentBias} clamped to -0.5. Below -0.5 produces unusable left-skew. To suppress, fix the config.`);
+			bornRecentBias = -0.5;
+		}
+	}
+
+	// Clamp 4: bias × born compound check (only on explicit user values).
+	// Plan PROMPT.md: "born > 80 + bias > 0.4 → clamp bias to 0.3".
+	if ((userBornExplicit || userBiasExplicit) && percentUsersBornInDataset > 60 && bornRecentBias > 0.4) {
+		console.warn(
+			`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} + bornRecentBias=${bornRecentBias} ` +
+			`compounds to right-edge explosion. Clamping bornRecentBias to 0.3. To suppress, fix the config.`
+		);
+		bornRecentBias = 0.3;
+	}
+
+	// Final sanity: bias must be in [-1, 1] (Math.pow guards)
+	bornRecentBias = Math.max(-1, Math.min(1, bornRecentBias));
+
+	// Clamp 5: avgEventsPerUserPerDay safe range. Above 50 produces unrealistic
+	// load + memory cost. Plan PROMPT.md: clamp to 50.
+	if (Number.isFinite(avgEventsPerUserPerDay) && avgEventsPerUserPerDay > 50) {
+		console.warn(`⚠️  avgEventsPerUserPerDay=${avgEventsPerUserPerDay} clamped to 50. Above 50 is unrealistic load + memory cost. To suppress, fix the config.`);
+		avgEventsPerUserPerDay = 50;
+		numEvents = Math.round(avgEventsPerUserPerDay * numUsers * numDays);
+	}
+
+	// Clamp 6: avgActiveDaysPerUser cap at numDays/2. Above defeats the
+	// concentrator purpose. Reassign config so the user-loop sees the clamped value.
+	let avgActiveDaysClamped = avgActiveDaysPerUser;
+	if (avgActiveDaysPerUser !== undefined && avgActiveDaysPerUser !== null && avgActiveDaysPerUser > numDays * 0.5) {
+		const cap = Math.max(1, Math.floor(numDays * 0.5));
+		console.warn(`⚠️  avgActiveDaysPerUser=${avgActiveDaysPerUser} > numDays/2 (${numDays}/2); clamped to ${cap}. Above 50% defeats the concentrator purpose. To suppress, fix the config.`);
+		avgActiveDaysClamped = cap;
+	}
+
+	// Clamp 7: numDays minimum. Below 14 makes the strict-bar 14-day window
+	// meaningless. We WARN but do NOT clamp here because the dataset window has
+	// already been resolved upstream — clamping numDays alone would desync the
+	// engine. Pre-validator numDays bound is preferred (validator throws on
+	// numDays <= 0 already at line ~422). Just warn for visibility.
+	if (numDays < 14) {
+		console.warn(`⚠️  numDays=${numDays} < 14. Strict-bar engine-validation metrics use 14-day windows; results are noisy below 14 days. Consider increasing numDays.`);
+	}
+	// ──────────────────────────────────────────────────────────────────────
+
 	// Use provided name if non-empty string, otherwise generate one
 	if (!name || name === "") {
 		name = makeName();
@@ -461,6 +672,26 @@ export function validateDungeonConfig(config) {
 		funnels = [...funnels, ...inferredFunnels];
 	}
 
+	// v1.5: auto-promote funnel-step events to `isStrictEvent: true`. Run BEFORE the
+	// catch-all funnel below so the catch-all only sweeps non-strict events. Without
+	// this, the greedy single-pass funnel engine consumes standalone instances as
+	// funnel step matches — corrupting both the standalone count AND the funnel TTC.
+	// Explicit `isStrictEvent: false` opts out (advanced; preserves mixed semantics).
+	// Skip `$experiment_started` since it's prepended by experiments, not user-declared.
+	const userDeclaredFunnelSteps = new Set(funnels.flatMap(f => Array.isArray(f.sequence) ? f.sequence : []));
+	userDeclaredFunnelSteps.delete('$experiment_started');
+	for (const ev of events) {
+		if (!ev || typeof ev.event !== 'string') continue;
+		if (!userDeclaredFunnelSteps.has(ev.event)) continue;
+		if (ev.isStrictEvent === false) continue; // explicit opt-out
+		if (ev.isStrictEvent === true) continue;  // already set
+		ev.isStrictEvent = true;
+		console.warn(
+			`⚠️  Auto-promoted "${ev.event}" to isStrictEvent: true (appears as a funnel step). ` +
+			`Set isStrictEvent: false to opt out and allow standalone instances.`
+		);
+	}
+
 	// Create funnel for events not in other funnels
 	const eventContainedInFunnels = Array.from(funnels.reduce((acc, f) => {
 		const events = f.sequence;
@@ -494,7 +725,15 @@ export function validateDungeonConfig(config) {
 			sequence,
 			conversionRate: 50,
 			order: 'random',
-			timeToConvert: 24 * 14,
+			// v1.5 engine bunchiness fix: shortened catch-all ttc from 14d → 1d.
+			// The user-loop fix constrains funnel step1's TimeSoup `latestTime` to
+			// `FIXED_NOW - ttc` to prevent spillover-and-_drop. With ttc=14d, this
+			// created a 14-day "no event zone" at the right edge of every dataset
+			// — flattening growth/viral macros into near-baseline shapes. ttc=1d
+			// gives the catch-all a 1-day right-edge zone, restoring magnitude
+			// distinction across macro presets while keeping spillover near zero.
+			// Explicit user-defined funnels keep their declared `timeToConvert`.
+			timeToConvert: 24,
 			requireRepeats: false,
 		});
 	}
@@ -510,7 +749,7 @@ export function validateDungeonConfig(config) {
 
 
 
-	// Event validation 
+	// Event validation
 	const validatedEvents = u.validateEventConfig(events);
 
 	// ── Validate and resolve advanced features ──
@@ -542,6 +781,12 @@ export function validateDungeonConfig(config) {
 	// Phase 1: validate Funnel.attempts on every funnel (additive — most have none).
 	validateAttempts(funnels);
 
+	// v1.5: default + auto-bump Funnel.conversionWindowDays.
+	validateConversionWindow(funnels);
+
+	// v1.5.0: validate Funnel.exclusionEvents — entries must exist in events[].
+	validateExclusionEvents(funnels, validatedEvents);
+
 	// Normalize experiment configs: true → default 3-variant, object → validated.
 	normalizeExperiments(funnels, datasetEndUnix);
 
@@ -565,6 +810,16 @@ export function validateDungeonConfig(config) {
 	// Precompute whether any event has isAttributionEvent for UTM stamping logic.
 	const hasAttributionFlags = validatedEvents.some(e => e.isAttributionEvent);
 
+	// v1.5: Touchpoint cap. Default 10 (Mixpanel TOUCHPOINTS_LIMIT). Setting Infinity
+	// disables the cap (every eligible event gets stamped). Negative or zero disables
+	// stamping entirely (treat as "don't apply touchpoint cap pass").
+	let maxTouchpointsPerUser = config.maxTouchpointsPerUser;
+	if (maxTouchpointsPerUser === undefined || maxTouchpointsPerUser === null) {
+		maxTouchpointsPerUser = 10;
+	} else if (maxTouchpointsPerUser !== Infinity && (!Number.isFinite(maxTouchpointsPerUser) || maxTouchpointsPerUser < 0)) {
+		throw new Error(`maxTouchpointsPerUser must be a non-negative finite number or Infinity (got ${maxTouchpointsPerUser})`);
+	}
+
 	// Build final config object
 	const validatedConfig = {
 		...config,
@@ -616,6 +871,14 @@ export function validateDungeonConfig(config) {
 		bornRecentBias,
 		percentUsersBornInDataset,
 		preExistingSpread,
+		// v1.5 distinct-day primitive (concentrator). undefined = legacy behavior.
+		avgActiveDaysPerUser: avgActiveDaysClamped !== undefined && avgActiveDaysClamped !== null
+			? avgActiveDaysClamped
+			: undefined,
+		// v1.5 attribution touchpoint cap (Mixpanel TOUCHPOINTS_LIMIT = 10).
+		maxTouchpointsPerUser,
+		// v1.5 auto-sort after everything hook. Default true. Opt out with explicit `false`.
+		autoSortAfterEverything: config.autoSortAfterEverything !== false,
 		// Advanced features (kept after 1.4)
 		personas,
 		worldEvents,

package/lib/core/dungeon-loader.js

@@ -4,14 +4,11 @@
  */
 
 import path from 'path';
+import os from 'os';
 import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from 'fs';
-import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
 import Chance from 'chance';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
-
 /**
  * Detect what kind of input was passed and normalize it
  * @param {any} input - The raw input to DUNGEON_MASTER
@@ -221,7 +218,7 @@ function reviveFunctionObject(obj) {
  * @returns {Promise<import('../../types').Dungeon>}
  */
 export async function loadFromText(code) {
-	const tmpDir = path.join(PACKAGE_ROOT, '.dungeon-tmp');
+	const tmpDir = path.join(os.tmpdir(), 'dungeon-master');
 	const tmpId = randomBytes(8).toString('hex');
 	const tmpFile = path.join(tmpDir, `dungeon-${tmpId}.mjs`);
 

package/lib/generators/events.js

@@ -92,30 +92,29 @@ export async function makeEvent(
         defaultProps.browser = u.choose(defaults.browsers());
     }
 
-    // Add campaigns with attribution likelihood.
-    // When any event has isAttributionEvent, only stamp UTMs on those events (25% chance).
-    // Otherwise, backwards-compat: ~25% of all events get UTMs.
-    if (hasCampaigns) {
-        const shouldStamp = config.hasAttributionFlags
-            ? (chosenEvent.isAttributionEvent && chance.bool({ likelihood: 25 }))
-            : chance.bool({ likelihood: 25 });
-        if (shouldStamp) {
-            defaultProps.campaigns = u.pickRandom(defaults.campaigns());
-        }
-    }
+    // v1.5: UTM stamping moved to per-user post-generation pass in user-loop.js
+    // (`applyTouchpointCap`). The pass identifies eligible events (per
+    // `isAttributionEvent` flag presence), samples up to `maxTouchpointsPerUser`
+    // (default 10) across the user's lifetime, and stamps UTMs on the sample.
+    // Stamping here per-event would defeat the lifetime-distributed sampling.
     
     // PERFORMANCE: Use pre-computed device pool instead of rebuilding every time
     if (defaults.allDevices.length) {
         defaultProps.device = u.pickRandom(defaults.allDevices);
     }
 
-    // Set event time using TimeSoup for realistic distribution
+    // Set event time using TimeSoup for realistic distribution.
+    // v1.5: active-day mode passes `featureCtx.latestTime` to constrain TimeSoup
+    // to a specific UTC day. When unset, defaults to FIXED_NOW (legacy behavior).
     if (earliestTime) {
         let unixTime;
         if (isFirstEvent) {
             unixTime = earliestTime;
         } else {
-            unixTime = u.TimeSoup(earliestTime, context.FIXED_NOW, peaks, deviation, mean, dayOfWeekWeights, hourOfDayWeights);
+            const latestTime = (featureCtx && Number.isFinite(featureCtx.latestTime))
+                ? featureCtx.latestTime
+                : context.FIXED_NOW;
+            unixTime = u.TimeSoup(earliestTime, latestTime, peaks, deviation, mean, dayOfWeekWeights, hourOfDayWeights);
         }
         eventTemplate.time = dayjs.unix(unixTime).toISOString();
     }

package/lib/generators/funnels.js

@@ -249,19 +249,42 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		numStepsUserWillTake
 	);
 
+	// v1.5: cap the funnel's total span at conversionWindowDays * 86400000 - 1 ms
+	// (1ms slack to clear Mixpanel's strict-`<` boundary in conversion_window.cpp).
+	// When a funnel's `timeToConvert` would push the last step past the window, scale
+	// all relative offsets proportionally to fit. Validator already auto-bumped
+	// `conversionWindowDays` for long-TTC funnels, so this rarely fires — but it
+	// makes the contract explicit at generation time.
+	const conversionWindowDays = funnel.conversionWindowDays;
+	if (Number.isFinite(conversionWindowDays) && conversionWindowDays > 0 && funnelEventsWithTiming.length > 1) {
+		const maxSpanMs = conversionWindowDays * 86400000 - 1;
+		const lastEvent = funnelEventsWithTiming[funnelEventsWithTiming.length - 1];
+		if (Number.isFinite(lastEvent.relativeTimeMs) && lastEvent.relativeTimeMs > maxSpanMs) {
+			const scale = maxSpanMs / lastEvent.relativeTimeMs;
+			for (let i = 1; i < funnelEventsWithTiming.length; i++) {
+				if (Number.isFinite(funnelEventsWithTiming[i].relativeTimeMs)) {
+					funnelEventsWithTiming[i].relativeTimeMs = Math.floor(funnelEventsWithTiming[i].relativeTimeMs * scale);
+				}
+			}
+		}
+	}
+
 	// Add session start event if configured (clone to avoid mutating shared config)
 	if (sessionStartEvents.length) {
 		const sessionStartEvent = { ...chance.pickone(sessionStartEvents), relativeTimeMs: -15000 };
 		funnelEventsWithTiming.push(sessionStartEvent);
 	}
 
-	// Build complete feature context: merge passed-in featureCtx with config fallbacks
+	// Build complete feature context: merge passed-in featureCtx with config fallbacks.
+	// v1.5: preserve `latestTime` if active-day mode is in effect, so makeEvent's
+	// TimeSoup constrains the funnel's first event to the picked day.
 	const funnelFeatureCtx = {
 		persona: featureCtx.persona || persona || null,
 		userCampaign: featureCtx.userCampaign || null,
 		userLocation: featureCtx.userLocation || null,
 		worldEventsTimeline: featureCtx.worldEventsTimeline || context.config.worldEvents || null,
 		dataQuality: featureCtx.dataQuality || context.config.dataQuality || null,
+		latestTime: Number.isFinite(featureCtx.latestTime) ? featureCtx.latestTime : undefined,
 	};
 
 	// Pre-compute per-step stamping modes for execution order. For isFirstFunnel + isBorn
@@ -306,6 +329,54 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		? Date.parse(finalEvents[runAuthExecIdx].time) || null
 		: null;
 
+	// v1.5.0: inject exclusion events for non-converters. When `funnel.exclusionEvents`
+	// is set and the user dropped off mid-funnel (≥1 step completed but < sequence.length),
+	// stamp 1-2 cloned events bearing one of the listed exclusion event names between the
+	// last completed step and where the next step would have been. The verifier reads
+	// `funnel.exclusionEvents` and applies them as exclusionSteps to terminate the attempt.
+	//
+	// Schema-first: copy ONLY identity + super props + group keys from the source event,
+	// plus props declared on the exclusion event's own config. Source-event-specific
+	// props (e.g. `cart_value` on `Add to Cart`) MUST NOT bleed onto a different event
+	// type or the schema validator will flag undeclared columns.
+	if (Array.isArray(funnel.exclusionEvents) && funnel.exclusionEvents.length
+		&& !doesUserConvert && finalEvents.length > 0 && finalEvents.length < sequence.length) {
+		const lastEvent = finalEvents[finalEvents.length - 1];
+		const lastTimeMs = Date.parse(lastEvent.time);
+		if (Number.isFinite(lastTimeMs)) {
+			const IDENTITY_KEYS = ['user_id', 'device_id', 'distinct_id', 'session_id', 'insert_id'];
+			const superPropKeys = Object.keys(superProps || {});
+			const groupKeyNames = (groupKeys || []).map(gk => Array.isArray(gk) ? gk[0] : gk).filter(Boolean);
+			const numToInject = chance.integer({ min: 1, max: 2 });
+			for (let i = 0; i < numToInject; i++) {
+				const excName = chance.pickone(funnel.exclusionEvents);
+				const excConfig = (config.events || []).find(e => e.event === excName);
+				const offsetMs = (i + 1) * chance.integer({ min: 30_000, max: 300_000 });
+				const cloned = {
+					event: excName,
+					time: new Date(lastTimeMs + offsetMs).toISOString(),
+				};
+				// Identity from source event (correct user/device/session attribution).
+				for (const k of IDENTITY_KEYS) {
+					if (k in lastEvent) cloned[k] = lastEvent[k];
+				}
+				// Super props + group keys carry over (user-stable values).
+				for (const k of superPropKeys) if (k in lastEvent) cloned[k] = lastEvent[k];
+				for (const k of groupKeyNames) if (k in lastEvent) cloned[k] = lastEvent[k];
+				// Resolve declared props on the exclusion event's config.
+				if (excConfig && excConfig.properties) {
+					for (const k of Object.keys(excConfig.properties)) {
+						try { cloned[k] = u.choose(excConfig.properties[k]); }
+						catch (e) { cloned[k] = null; }
+					}
+				}
+				// Fresh insert_id so the new event isn't a duplicate of the source.
+				cloned.insert_id = `${excName}-${cloned.time}-${chance.string({ length: 10, alpha: true })}`;
+				finalEvents.push(cloned);
+			}
+		}
+	}
+
 	// Call post-funnel hook
 	await hook(finalEvents, "funnel-post", {
 		user, profile, scd, funnel, config,

package/lib/hook-helpers/index.js

@@ -36,6 +36,7 @@ export {
 	injectAfterEvent,
 	injectBetween,
 	injectBurst,
+	injectOnNewDays,
 } from './inject.js';
 
 export {

package/lib/hook-helpers/inject.js

@@ -97,3 +97,98 @@ export function injectBurst(events, templateEvent, count, anchorTime, spreadMs,
 	return created;
 }
 
+const DAY_MS = 86400000;
+
+/**
+ * Inject cloned events on days where the user had no activity for this event
+ * type. Increases distinct-day frequency without disturbing existing event
+ * ordering or inflating same-day counts.
+ *
+ * Designed for use in `everything` hooks to move users between frequency bins
+ * in Mixpanel's frequency distribution reports — which count DISTINCT DAYS
+ * (not total events). See `lib/verify/counting.js#countDistinctPeriods` and
+ * `mixpanel/analytics` `addiction_query.cpp` for the counting rule.
+ *
+ * Behavior:
+ *   1. Collect all existing distinct UTC days for `eventName`.
+ *   2. If the user already has >= `targetDays` distinct days, return unchanged.
+ *   3. Restrict candidate days to the user's active window (first event time
+ *      to last event time, by default).
+ *   4. Pick `targetDays - existing` random days that have no `eventName`
+ *      activity (uses seeded RNG).
+ *   5. Find a template event of `eventName`; if none exist for this user,
+ *      return unchanged (we honor schema-first: don't fabricate events).
+ *   6. Clone the template onto each picked day at a random hour within the
+ *      day. `insert_id` is stripped (Mixpanel re-deduplicates on import).
+ *   7. Append clones to the array. Caller's downstream sort handles ordering.
+ *
+ * @param {Object[]} events - Full user event array (from `everything` hook).
+ * @param {string} eventName - Event name to inject.
+ * @param {number} targetDays - Desired absolute count of distinct active days.
+ * @param {Object} [options]
+ * @param {('active')} [options.timeRange='active'] - 'active' = user's
+ *   first-to-last event window. Reserved for future range modes.
+ * @param {Object} [options.overrides] - Property overrides applied via spread
+ *   on top of the cloned template.
+ * @returns {Object[]} The (possibly mutated) events array. Same reference as
+ *   the input — convenient to return from an `everything` hook.
+ */
+export function injectOnNewDays(events, eventName, targetDays, options = {}) {
+	if (!Array.isArray(events) || !eventName || typeof targetDays !== 'number' || targetDays <= 0) return events;
+	const overrides = options.overrides || {};
+
+	// Collect timestamps for the named event + global window for the user.
+	const matches = [];
+	const allTimes = [];
+	let template = null;
+	for (const ev of events) {
+		if (!ev) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t)) allTimes.push(t);
+		if (ev.event === eventName && Number.isFinite(t)) {
+			matches.push(t);
+			template = template || ev;
+		}
+	}
+	if (!template) return events;
+	if (!allTimes.length) return events;
+
+	// Distinct UTC days that already have an event of `eventName`.
+	const existingDays = new Set();
+	for (const t of matches) existingDays.add(Math.floor(t / DAY_MS));
+	if (existingDays.size >= targetDays) return events;
+
+	const minMs = Math.min(...allTimes);
+	const maxMs = Math.max(...allTimes);
+	const firstDay = Math.floor(minMs / DAY_MS);
+	const lastDay = Math.floor(maxMs / DAY_MS);
+
+	const candidateDays = [];
+	for (let d = firstDay; d <= lastDay; d++) {
+		if (!existingDays.has(d)) candidateDays.push(d);
+	}
+	const need = targetDays - existingDays.size;
+	if (candidateDays.length === 0 || need <= 0) return events;
+
+	const chance = getChance();
+	// Use chance.pickset for a unique-without-replacement sample from the
+	// candidate day pool. If `need` exceeds candidates, fall back to all.
+	const pickCount = Math.min(need, candidateDays.length);
+	const picked = chance.pickset(candidateDays, pickCount);
+
+	for (const day of picked) {
+		// Pick a random ms within this UTC day. Clamp to active window.
+		const dayStart = day * DAY_MS;
+		const dayEnd = dayStart + DAY_MS - 1;
+		const lo = Math.max(dayStart, minMs);
+		const hi = Math.min(dayEnd, maxMs);
+		const newMs = lo >= hi ? lo : chance.integer({ min: lo, max: hi });
+		const clone = { ...template, ...overrides };
+		writeTime(clone, newMs);
+		delete clone.insert_id;
+		events.push(clone);
+	}
+
+	return events;
+}
+