@ak--47/dungeon-master 1.6.4 → 1.7.0

package/lib/generators/funnels.js

@@ -92,12 +92,18 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 				if (hashVal < cumWeight) { chosenVariant = expCfg.variants[vi]; chosenIdx = vi; break; }
 			}
 			experimentVariant = chosenVariant.name;
-			funnel.conversionRate = Math.min(100, Math.max(1,
-				Math.round((funnel.conversionRate || 50) * chosenVariant.conversionMultiplier)));
+			funnel.conversionRate = saturateConversionRate(context, funnel,
+				Math.round((funnel.conversionRate || 50) * chosenVariant.conversionMultiplier), `experiment "${experimentName}" variant "${experimentVariant}"`, 1);
 			funnel.timeToConvert = Math.max(0.1,
 				(funnel.timeToConvert || 1) * chosenVariant.ttcMultiplier);
 			funnel._experimentName = experimentName;
 			funnel._experimentVariant = experimentVariant;
+			// v1.7.0 (P0-2): record the assignment so the user loop can stamp
+			// `Experiment: <name>` on the profile. Only when the bucketing is sticky
+			// (a re-rolled variant has no single per-user value) and stampProfile is on.
+			if (expCfg.sticky !== false && expCfg.stampProfile !== false && featureCtx && featureCtx.experimentAssignments) {
+				featureCtx.experimentAssignments.set(experimentName, experimentVariant);
+			}
 			funnel.sequence = ["$experiment_started", ...funnel.sequence];
 			experimentMeta = {
 				name: experimentName,
@@ -113,7 +119,13 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	// Apply persona and world-event modifiers to the funnel BEFORE the hook fires,
 	// so funnel-pre sees the effective rate and has final authority.
 	if (persona && persona.conversionModifier) {
-		funnel.conversionRate = Math.min(100, Math.max(0, Math.round((funnel.conversionRate || 50) * persona.conversionModifier)));
+		funnel.conversionRate = saturateConversionRate(context, funnel,
+			Math.round((funnel.conversionRate || 50) * persona.conversionModifier), `persona "${persona.name}" conversionModifier`, 0);
+	}
+	// v1.7.0 (P1-3): persona time-to-convert multiplier. Composes after the
+	// experiment ttcMultiplier, before the funnel-pre hook (hook keeps final say).
+	if (persona && Number.isFinite(persona.ttcModifier) && persona.ttcModifier !== 1) {
+		funnel.timeToConvert = Math.max(0.1, (funnel.timeToConvert || 1) * persona.ttcModifier);
 	}
 	const resolvedWorldEvents = /** @type {import('../../types').ResolvedWorldEvent[]} */ (config.worldEvents);
 	if (resolvedWorldEvents && firstEventTime) {
@@ -122,7 +134,8 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 				const seq = funnel.sequence || [];
 				const affects = we.affectsEvents;
 				if (affects === "*" || (Array.isArray(affects) && seq.some(s => affects.includes(s)))) {
-					funnel.conversionRate = Math.min(100, Math.max(0, Math.round((funnel.conversionRate || 50) * we.conversionModifier)));
+					funnel.conversionRate = saturateConversionRate(context, funnel,
+						Math.round((funnel.conversionRate || 50) * we.conversionModifier), `worldEvent "${we.name}" conversionModifier`, 0);
 				}
 			}
 		}
@@ -144,6 +157,16 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		experiment: experimentMeta,
 	});
 
+	// v1.7.0 (P2-4): a funnel-pre hook that leaves conversionRate above 100 is
+	// clamped downstream (processEventRepeats) — record the saturation so the
+	// author learns the asked-for lift did not land. The engine can only see its
+	// own clamp: a hook's own `Math.min(95, rate * 3)` never reaches here.
+	// Record only — the value itself is left for processEventRepeats to clamp exactly
+	// as before, so pre-1.7 output is unchanged.
+	if (Number.isFinite(funnel.conversionRate) && funnel.conversionRate > 100) {
+		saturateConversionRate(context, funnel, funnel.conversionRate, 'funnel-pre hook', 0);
+	}
+
 	// Extract funnel configuration (post-hook — hook's mutations are the final word)
 	let {
 		sequence,
@@ -160,18 +183,21 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	const { distinct_id, created, anonymousIds = [] } = user;
 	const { superProps = {}, groupKeys = [] } = config;
 
+	// v1.7.0 (P1-1): value context for funnel-level and step-level property thunks.
+	const valueCtx = { profile, config, time: Number.isFinite(firstEventTime) ? firstEventTime * 1000 : undefined };
+
 	// Choose properties for this funnel instance
 	const chosenFunnelProps = { ...props, ...superProps };
 	for (const key in props) {
 		try {
-			chosenFunnelProps[key] = u.choose(chosenFunnelProps[key]);
+			chosenFunnelProps[key] = u.choose(chosenFunnelProps[key], valueCtx);
 		} catch (e) {
 			logger.error({ err: e, key, funnel: funnel.sequence.join(" > ") }, `Error processing property ${key} in funnel`);
 		}
 	}
 
 	// Build event specifications for funnel steps
-	const funnelPossibleEvents = buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, expName, expVariant);
+	const funnelPossibleEvents = buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, expName, expVariant, valueCtx);
 
 	// Handle repeat logic and conversion rate adjustment
 	let { processedEvents, adjustedConversionRate } = processEventRepeats(
@@ -298,6 +324,9 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		persona: featureCtx.persona || persona || null,
 		userCampaign: featureCtx.userCampaign || null,
 		userLocation: featureCtx.userLocation || null,
+		// v1.7.0: value context + sticky event props flow through to makeEvent.
+		profile: featureCtx.profile || profile || null,
+		stickyValues: featureCtx.stickyValues || null,
 		worldEventsTimeline: featureCtx.worldEventsTimeline || context.config.worldEvents || null,
 		dataQuality: featureCtx.dataQuality || context.config.dataQuality || null,
 		latestTime: Number.isFinite(featureCtx.latestTime) ? featureCtx.latestTime : undefined,
@@ -399,7 +428,7 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 				// 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]); }
+						try { cloned[k] = u.choose(excConfig.properties[k], { ...valueCtx, event: cloned, time: Date.parse(cloned.time) }); }
 						catch (e) { cloned[k] = null; }
 					}
 				}
@@ -429,6 +458,33 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	return [finalEvents, doesUserConvert, authTimeMs];
 }
 
+/**
+ * v1.7.0 (P2-4): clamp a modified conversionRate into `[floor, 100]` and, when the
+ * requested value exceeded 100, record ONE aggregated warning per funnel+source on
+ * the context (never per user — this runs in the hot loop).
+ *
+ * @param {Context} context
+ * @param {Object} funnel
+ * @param {number} requested - pre-clamp rate
+ * @param {string} source - what produced the rate (persona / experiment / world event / hook)
+ * @param {number} floor - lower bound (experiments floor at 1, others at 0)
+ * @returns {number} clamped rate
+ */
+function saturateConversionRate(context, funnel, requested, source, floor) {
+	const applied = Math.min(100, Math.max(floor, requested));
+	if (requested > 100 && context && typeof context.addWarning === 'function') {
+		const label = funnel.name || (Array.isArray(funnel.sequence) ? funnel.sequence.filter(s => s !== '$experiment_started').join(' > ') : '?');
+		context.addWarning({
+			key: `funnels[${label}].conversionRate:${source}`,
+			requested,
+			applied: 100,
+			reason: `${source} pushed conversionRate above 100; saturated at 100, so the intended lift did not fully land. Lower the base conversionRate or the multiplier.`,
+			severity: 'clamp',
+		});
+	}
+	return applied;
+}
+
 /**
  * Builds event specifications for funnel steps
  * @param {Context} context - Context object
@@ -437,9 +493,10 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
  * @param {number} bindPropsIndex - Index at which to bind properties (if applicable)
  * @param {string} [experimentName] - Name of experiment (if experiment is enabled)
  * @param {string} [experimentVariant] - Variant name (A, B, or C)
+ * @param {Object} [valueCtx] - v1.7.0 value context for property thunks
  * @returns {Array} Array of event specifications
  */
-function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, experimentName, experimentVariant) {
+function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, experimentName, experimentVariant, valueCtx = undefined) {
 	const { config } = context;
 
 	return sequence.map((eventName, currentIndex) => {
@@ -463,10 +520,14 @@ function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex,
 			properties: { ...foundEvent.properties }
 		} : { event: eventName, properties: {} };
 
-		// Process event properties
+		// Process event properties.
+		// v1.7.0 (P1-1): context-aware thunks (`(ctx) => …`) are DEFERRED — left in
+		// place so makeEvent resolves them per step with the real `ctx.event` and
+		// `ctx.time`. Everything else resolves here exactly as before.
 		for (const key in eventSpec.properties) {
+			if (u.isContextAware(eventSpec.properties[key])) continue;
 			try {
-				eventSpec.properties[key] = u.choose(eventSpec.properties[key]);
+				eventSpec.properties[key] = u.choose(eventSpec.properties[key], valueCtx);
 			} catch (e) {
 				logger.error({ err: e, key, event: eventSpec.event }, `Error processing property ${key} in ${eventSpec.event} event`);
 			}
@@ -636,9 +697,22 @@ async function generateFunnelEvents(
 	const stampingByIndex = (identityArgs && identityArgs.stampingByIndex) || null;
 	const devicePool = (identityArgs && identityArgs.devicePool) || null;
 
+	// v1.7.0: step 0 reports its TimeSoup time through a synchronous side channel.
+	// Each map callback runs synchronously up to makeEvent's first `await` (the
+	// event hook), which is AFTER the time is set — so by the time callback i>0
+	// starts, `funnelStartMs` is known and the step's final time can be pinned
+	// before its properties resolve. RNG order is unchanged.
+	let funnelStartMs = null;
+
 	const finalEvents = await Promise.all(eventsWithTiming.map(async (event, index) => {
 		const stamping = stampingByIndex ? stampingByIndex[index] : 'both';
 		const identityCtx = (devicePool || stamping !== 'both') ? { stamping, devicePool } : null;
+		let stepFeatureCtx = featureCtx;
+		if (index === 0) {
+			stepFeatureCtx = { ...featureCtx, onTimeResolved: (ms) => { funnelStartMs = ms; } };
+		} else if (funnelStartMs !== null && Number.isFinite(event.relativeTimeMs)) {
+			stepFeatureCtx = { ...featureCtx, fixedTimeMs: funnelStartMs + event.relativeTimeMs };
+		}
 		const newEvent = await makeEvent(
 			context,
 			distinct_id,
@@ -649,7 +723,7 @@ async function generateFunnelEvents(
 			groupKeys,
 			false,
 			false,
-			featureCtx,
+			stepFeatureCtx,
 			identityCtx
 		);
 

package/lib/generators/profiles.js

@@ -18,19 +18,24 @@ import { dataLogger as logger } from "../utils/logger.js";
 export async function makeProfile(context, props = {}, defaults = {}) {
     // Update operation counter
     context.incrementOperations();
-    
+
     // Keys that should not be processed with the choose function
     const keysToNotChoose = ["anonymousIds", "sessionIds"];
 
     // Start with defaults
     const profile = { ...defaults };
 
+    // v1.7.0 (P1-1): value functions see the profile as it is being built.
+    // Keys resolve in insertion order, so a later key can read an earlier one
+    // (`revenue: (ctx) => ctx.profile.plan === 'pro' ? 100 : 10`).
+    const valueCtx = { profile, config: context.config };
+
     // Process default values first
     for (const key in profile) {
         if (keysToNotChoose.includes(key)) continue;
-        
+
         try {
-            profile[key] = u.choose(profile[key]);
+            profile[key] = u.choose(profile[key], valueCtx);
         } catch (e) {
             logger.error({ err: e, key }, `Error processing default property ${key}`);
             // Keep original value on error
@@ -40,7 +45,7 @@ export async function makeProfile(context, props = {}, defaults = {}) {
     // Process provided props (these override defaults)
     for (const key in props) {
         try {
-            profile[key] = u.choose(props[key]);
+            profile[key] = u.choose(props[key], valueCtx);
         } catch (e) {
             logger.error({ err: e, key }, `Error processing property ${key}`);
             // Keep original value on error

package/lib/orchestrators/mixpanel-sender.js

@@ -100,6 +100,7 @@ async function _sendToMixpanel(context) {
 	const commonOpts = {
 		region,
 		fixData: true,
+		matchMixpanelDefaults: true,
 		v2_compat: true,
 		verbose: false,
 		forceStream: true,
@@ -174,7 +175,18 @@ async function _sendToMixpanel(context) {
 			progressCallback: makeProgressCallback(userTotal),
 		});
 		log(`  -> ${comma(imported.success)} user profiles sent\n`);
-		importResults.users = imported;
+		// v1.7.0 (R2-5): make the receipt self-explanatory. `generated` counts every
+		// profile the engine pushed to storage (bots included); `dropped_anonymous`
+		// counts the `_drop`-flagged anonymous non-converters that never reach
+		// /engage. `generated - dropped_anonymous - failed === success` is checkable.
+		// Counters live on the context and tick at push time, so they hold in
+		// batch mode where the in-memory array has been flushed.
+		const generated = context.runtime.profilesGenerated;
+		const dropped_anonymous = context.runtime.profilesDropped;
+		importResults.users = { ...imported, generated, dropped_anonymous };
+		if (imported.success + (imported.failed || 0) + dropped_anonymous !== generated) {
+			log(`  !! profile receipt does not reconcile: ${comma(generated)} generated - ${comma(dropped_anonymous)} dropped anonymous - ${comma(imported.failed || 0)} failed != ${comma(imported.success)} success\n`);
+		}
 	}
 
 	// Import ad spend data

package/lib/orchestrators/user-loop.js

@@ -16,6 +16,11 @@ 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";
+import { matchConditions } from "../utils/conditions.js";
+
+// v1.7.0 (P0-1): matching moved to lib/utils/conditions.js (operator maps).
+// Re-exported here so existing imports keep working.
+export { matchConditions };
 
 /**
  * Main user generation loop that creates users, their profiles, events, and SCDs
@@ -69,6 +74,23 @@ export async function userLoop(context) {
 	// Track if we've already logged the strict event count message
 	let hasLoggedStrictCountReached = false;
 
+	// v1.7.0 (R2-3): strictEventCount bookkeeping. `strictBudgetSum` is the sum
+	// of per-user budgets handed out so far; with the STORED count it yields the
+	// realized events-per-budget ratio, which the controller below uses to scale
+	// the remaining users' budgets so the run lands on `numEvents` and the final
+	// trim makes it exact. Before 1.7.0 the flag stopped on the GENERATED count
+	// (which includes `_drop`'d events) and never topped up, so it delivered ~6%
+	// short with 4x headroom available.
+	let strictBudgetSum = 0;
+	let strictUsersBudgeted = 0;
+
+	// v1.7.0 run-level counters for aggregated warnings (P0-1 item 5, P1-5).
+	const anyConditionedFunnel = Array.isArray(funnels) && funnels.some(f => f && f.conditions);
+	let usersMatchingNoFunnel = 0;
+	let usersChurned = 0;
+	const personaMultipliersInPlay = Array.isArray(personas) && personas.some(p => p && Number.isFinite(p.eventMultiplier) && p.eventMultiplier !== 1);
+	const campaignKeys = ['utm_source', 'utm_campaign', 'utm_medium', 'utm_content', 'utm_term'];
+
 	// 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
@@ -87,8 +109,9 @@ export async function userLoop(context) {
 			// Bail out if cancelled
 			if (cancelled) return;
 
-			// Bail out early if strictEventCount is enabled and we've hit numEvents
-			if (strictEventCount && context.getEventCount() >= numEvents) {
+			// Bail out early if strictEventCount is enabled and we've hit numEvents.
+			// v1.7.0: compares the STORED count (post-drop), not the generated count.
+			if (strictEventCount && context.getStoredEventCount() >= numEvents) {
 				if (verbose && !hasLoggedStrictCountReached) {
 					console.log(`\n\u2713 Reached target of ${numEvents.toLocaleString()} events with strict event count enabled. Stopping user generation.`);
 					hasLoggedStrictCountReached = true;
@@ -213,17 +236,40 @@ export async function userLoop(context) {
 			// Feature 1: Merge persona properties into profile (before hook, so hook can override)
 			if (persona && persona.properties) {
 				for (const [key, value] of Object.entries(persona.properties)) {
-					profile[key] = u.choose(value);
+					profile[key] = u.choose(value, { profile, config });
 				}
 				profile._persona = persona.name;
 			}
 
+			// v1.7.0 (P1-4): one acquisition campaign per user. Draw a campaign
+			// template at birth and stamp its UTM keys on the profile. Any UTM key the
+			// profile already carries (persona `properties`) wins over the draw, so
+			// "the paid-search persona" is `properties: { utm_source: 'google' }`. The
+			// `user` hook runs after this and can override too; the touchpoint pass
+			// reads the FINAL profile values. Opt-in: no RNG draw unless enabled.
+			if (config.campaignPerUser && config.hasCampaigns) {
+				const template = u.pickRandom(defaults.campaigns());
+				if (template && typeof template === 'object') {
+					for (const key of campaignKeys) {
+						if (profile[key] !== undefined) continue;
+						if (template[key] === undefined) continue;
+						profile[key] = u.choose(template[key], { profile, config });
+					}
+				}
+			}
+
 			// Build feature context for event generation
 			const featureCtx = {
 				persona,
 				userLocation,
 				worldEventsTimeline: worldEvents,
 				dataQuality,
+				// v1.7.0: value context (P1-1), sticky event props (P1-2), per-user
+				// campaign (P1-4), experiment assignments collector (P0-2).
+				profile,
+				stickyValues: null,
+				userCampaign: null,
+				experimentAssignments: new Map(),
 			};
 
 			// Call user hook after profile creation (hooks override persona properties).
@@ -246,6 +292,32 @@ export async function userLoop(context) {
 				}
 			}
 
+			// v1.7.0 (P1-2): resolve sticky event props ONCE per user, after the user
+			// hook so hook overrides are honored. Keys declared in userProps / persona
+			// properties copy from the profile; keys declared only in superProps are
+			// resolved here once (instead of per event) and held constant.
+			if (Array.isArray(config.stickyEventProps) && config.stickyEventProps.length) {
+				const superOnly = new Set(config._stickySuperOnly || []);
+				const stickyValues = {};
+				for (const key of config.stickyEventProps) {
+					stickyValues[key] = superOnly.has(key)
+						? u.choose(config.superProps[key], { profile, config })
+						: profile[key];
+				}
+				featureCtx.stickyValues = stickyValues;
+			}
+
+			// v1.7.0 (P1-4): the user's campaign, read from the FINAL profile so persona
+			// properties and the user hook both flow into the touchpoint pass.
+			if (config.campaignPerUser && config.hasCampaigns) {
+				const userCampaign = {};
+				let any = false;
+				for (const key of campaignKeys) {
+					if (profile[key] !== undefined && profile[key] !== null) { userCampaign[key] = profile[key]; any = true; }
+				}
+				featureCtx.userCampaign = any ? userCampaign : null;
+			}
+
 			// SCD creation
 			// @ts-ignore
 			const scdUserTables = t.objFilter(scdProps, (scd) => scd.type === 'user' || !scd.type);
@@ -305,6 +377,31 @@ export async function userLoop(context) {
 			}
 			numEventsThisUserWillPreform = Math.round(numEventsThisUserWillPreform);
 
+			// v1.7.0 (R2-3): strictEventCount budget controller. Born-in-dataset users
+			// carry a pro-rated budget and `_drop`s thin the rest, so the raw budgets
+			// sum below `numEvents` by design (~6% measured). Scale this user's budget
+			// by (events still needed) / (events the remaining users would deliver at
+			// the realized yield), aiming 2% high so the final per-user trim has
+			// something to trim. Clamped to [0.25, 4] so no single user is distorted
+			// into a whale. Only fires under the flag — the default path is untouched.
+			if (strictEventCount && numEventsThisUserWillPreform > 0) {
+				const delivered = context.getStoredEventCount();
+				const remainingTarget = numEvents - delivered;
+				const remainingUsers = Math.max(1, numUsers - i);
+				const meanBudget = strictUsersBudgeted > 0 ? strictBudgetSum / strictUsersBudgeted : numEventsThisUserWillPreform;
+				const yieldRatio = strictBudgetSum > 0 ? delivered / strictBudgetSum : 1;
+				const expectedRemaining = meanBudget * yieldRatio * remainingUsers;
+				if (remainingTarget > 0 && expectedRemaining > 0) {
+					// Overshoot grows as the tail shrinks (last user aims 2x its share) so a
+					// low-yield final user cannot leave the run short; the trim removes excess.
+					const overshoot = 1.02 + 1 / remainingUsers;
+					const scale = Math.max(0.25, Math.min(4, (remainingTarget * overshoot) / expectedRemaining));
+					numEventsThisUserWillPreform = Math.max(1, Math.round(numEventsThisUserWillPreform * scale));
+				}
+				strictBudgetSum += numEventsThisUserWillPreform;
+				strictUsersBudgeted++;
+			}
+
 			let userFirstEventTime;
 
 			// ── v1.5 Active-day scheduling ──
@@ -354,6 +451,12 @@ export async function userLoop(context) {
 			const usageFunnels = funnels.filter((f) => !f.isFirstFunnel)
 				.filter((f) => !f.conditions || matchConditions(profile, f.conditions))
 				.reduce(weighFunnels, []);
+			// v1.7.0 (P0-1 item 5): with conditions in play, a user who matches no
+			// funnel at all silently falls through to standalone events. Counted here,
+			// reported once per run (see end of loop).
+			if (anyConditionedFunnel && firstFunnels.length === 0 && !usageFunnels.some(f => !f._catchAll)) {
+				usersMatchingNoFunnel++;
+			}
 
 			const secondsInDay = 86400;
 			const noise = () => chance.integer({ min: 0, max: secondsInDay });
@@ -627,6 +730,24 @@ export async function userLoop(context) {
 					return Number.isFinite(t) ? t <= userChurnTimeMs : true;
 				});
 			}
+			if (userChurned) usersChurned++;
+
+			// v1.7.0 (P0-3): world-event amplification. `volumeMultiplier > 1` clones
+			// affected in-window events (fresh insert_id, spread uniformly across the
+			// window) so daily volume reaches the stated multiple. Runs after the churn
+			// cut (no post-churn clones) and before decay / hooks, which see the clones.
+			const resolvedWorldEvents = /** @type {import('../../types').ResolvedWorldEvent[] | null} */ (worldEvents);
+			if (resolvedWorldEvents && usersEvents.length > 0 && worldEventsAmplify(resolvedWorldEvents)) {
+				usersEvents = amplifyWorldEvents(usersEvents, resolvedWorldEvents, chance, context.FIXED_NOW);
+			}
+
+			// v1.7.0 (P0-2): stamp sticky experiment assignments on the profile as
+			// `Experiment: <name>` before the everything hook, so hooks see it too.
+			if (featureCtx.experimentAssignments.size > 0) {
+				for (const [expName, variantName] of featureCtx.experimentAssignments) {
+					profile[`Experiment: ${expName}`] = variantName;
+				}
+			}
 
 			// Feature 3: Engagement decay — filter behavioral events
 			const userDecay = persona?.engagementDecay || globalEngagementDecay;
@@ -696,7 +817,7 @@ export async function userLoop(context) {
 			// 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);
+				applyTouchpointCap(usersEvents, config, defaults, chance, featureCtx.userCampaign);
 			}
 
 			// v1.5.1: anonymous non-converters never call $identify in production,
@@ -819,9 +940,25 @@ export async function userLoop(context) {
 				u.assignSessionIds(sortedView, sessionTimeout);
 			}
 
+			// v1.7.0 (R2-3): strict mode never exceeds numEvents. Trim this user's
+			// stream to the remaining room with a seeded uniform sample (keeps the
+			// time shape; preserves array order). Only under the flag.
+			if (strictEventCount && usersEvents.length > 0) {
+				const room = numEvents - context.getStoredEventCount();
+				if (room <= 0) {
+					usersEvents = [];
+				} else if (usersEvents.length > room) {
+					const keep = new Set(chance.pickset(usersEvents, room));
+					usersEvents = usersEvents.filter(e => keep.has(e));
+				}
+			}
+
 			// Store all user data (skip profile push when a hook returned null
 			// for type='user' — see dropUserProfile above).
 			if (!dropUserProfile) {
+				// v1.7.0 (R2-5): receipt counters tick at push time (batch-mode safe).
+				context.incrementProfilesGenerated();
+				if (profile._drop) context.incrementProfilesDropped();
 				await userProfilesData.hookPush(profile);
 			}
 
@@ -868,6 +1005,42 @@ export async function userLoop(context) {
 	if (dataQuality && dataQuality.botUsers > 0) {
 		await generateBotUsers(context, dataQuality, storage);
 	}
+
+	// ── v1.7.0 aggregated run-level warnings (surfaced as result.warnings) ──
+	if (typeof context.addWarning === 'function') {
+		if (usersMatchingNoFunnel > 0) {
+			context.addWarning({
+				key: 'funnels.conditions',
+				requested: numUsers,
+				applied: numUsers - usersMatchingNoFunnel,
+				reason: `${usersMatchingNoFunnel} of ${numUsers} users matched no funnel's conditions and generated standalone events only; check that the conditioned funnels cover every segment`,
+				severity: 'warn',
+				count: usersMatchingNoFunnel,
+			});
+		}
+		if (personaMultipliersInPlay && numUsers > 0 && usersChurned / numUsers > 0.5) {
+			context.addWarning({
+				key: 'personas.eventMultiplier',
+				requested: usersChurned,
+				applied: numUsers,
+				reason: `${usersChurned} of ${numUsers} users were ended by an isChurnEvent; churn caps every user's lifetime event count, so personas[].eventMultiplier cannot lift a persona past it (measured 1.04x for an asked 3x). Lower the churn event's weight, raise returnLikelihood, or drive churn from a hook.`,
+				severity: 'warn',
+				count: usersChurned,
+			});
+		}
+		if (strictEventCount) {
+			const stored = context.getStoredEventCount();
+			if (stored < numEvents) {
+				context.addWarning({
+					key: 'numEvents',
+					requested: numEvents,
+					applied: stored,
+					reason: `strictEventCount could not reach numEvents: the ${numUsers} users' capacity (rate × active days, minus drops) ran out ${numEvents - stored} events short. Raise numUsers, numDays, or avgEventsPerUserPerDay.`,
+					severity: 'warn',
+				});
+			}
+		}
+	}
 	} finally {
 		// Always remove the SIGINT listener — even if userLoop throws or is
 		// cancelled. Pre-fix this leaked across test runs and stalled workers.
@@ -884,11 +1057,61 @@ export function weighFunnels(acc, funnel) {
 	return acc;
 }
 
-export function matchConditions(profile, conditions) {
-	for (const [key, value] of Object.entries(conditions)) {
-		if (profile[key] !== value) return false;
+/**
+ * v1.7.0 (P0-3): true when any resolved world event asks for amplification.
+ * @param {import('../../types').ResolvedWorldEvent[]} worldEvents
+ */
+function worldEventsAmplify(worldEvents) {
+	return worldEvents.some(we => we && ((we.volumeMultiplier > 1) || (we.aftermath && we.aftermath.volumeMultiplier > 1)));
+}
+
+/**
+ * v1.7.0 (P0-3): clone affected events so volume inside a world-event window (or
+ * its aftermath) reaches `volumeMultiplier`× the baseline.
+ *
+ * For every event that falls inside an amplifying window and matches
+ * `affectsEvents`, add `floor(mult - 1)` clones plus one more with probability
+ * `frac(mult)` — so `2.5` means one guaranteed clone and a 50% second. Each clone
+ * gets a FRESH `insert_id` (Mixpanel dedupes on it — a spread that keeps the
+ * source id is silently dropped at ingest) and a timestamp drawn uniformly across
+ * the window, never past `fixedNow`, so the surge is spread over the window's
+ * days rather than stacked one second after its source. Mutates nothing; returns
+ * a new array. Deterministic under the seeded chance.
+ *
+ * @param {Object[]} events - the user's surviving events
+ * @param {import('../../types').ResolvedWorldEvent[]} worldEvents
+ * @param {Object} chance - seeded chance instance
+ * @param {number} fixedNow - dataset end (unix seconds)
+ * @returns {Object[]}
+ */
+export function amplifyWorldEvents(events, worldEvents, chance, fixedNow) {
+	const clones = [];
+	for (const ev of events) {
+		if (!ev || !ev.time) continue;
+		const evUnix = Math.floor(Date.parse(ev.time) / 1000);
+		if (!Number.isFinite(evUnix)) continue;
+		for (const we of worldEvents) {
+			if (!we) continue;
+			const inMain = evUnix >= we.startUnix && evUnix < we.endUnix;
+			const inAftermath = !!we.aftermathEndUnix && evUnix >= we.endUnix && evUnix < we.aftermathEndUnix;
+			if (!inMain && !inAftermath) continue;
+			const affects = we.affectsEvents;
+			if (!(affects === "*" || (Array.isArray(affects) && affects.includes(ev.event)))) continue;
+			const mult = inMain ? we.volumeMultiplier : (we.aftermath && we.aftermath.volumeMultiplier) || 1;
+			if (!(mult > 1)) continue;
+			const windowStart = inMain ? we.startUnix : we.endUnix;
+			const windowEnd = Math.min(inMain ? we.endUnix : we.aftermathEndUnix, fixedNow);
+			if (!(windowEnd > windowStart)) continue;
+			let copies = Math.floor(mult - 1);
+			const frac = mult - 1 - copies;
+			if (frac > 0 && chance.bool({ likelihood: frac * 100 })) copies++;
+			for (let c = 0; c < copies; c++) {
+				const t = chance.integer({ min: windowStart, max: windowEnd - 1 });
+				clones.push({ ...ev, time: dayjs.unix(t).toISOString(), insert_id: randomUUID() });
+			}
+		}
 	}
-	return true;
+	return clones.length ? events.concat(clones) : events;
 }
 
 // ── v1.5 Active-Day Plan Helpers ──
@@ -1058,8 +1281,11 @@ function buildActiveDayPlan({ adjustedCreated, fixedBegin, fixedNow, avgActiveDa
  * @param {Object} config - Validated dungeon config
  * @param {Object} defaults - Context.defaults (provides campaigns())
  * @param {Object} chance - Seeded chance instance
+ * @param {Object|null} [userCampaign] - v1.7.0 (P1-4): the user's resolved UTM values
+ *   (from the profile) when `campaignPerUser` is on. Stamped verbatim on every
+ *   sampled touchpoint instead of re-drawing a template per event.
  */
-function applyTouchpointCap(events, config, defaults, chance) {
+function applyTouchpointCap(events, config, defaults, chance, userCampaign = null) {
 	const cap = Number.isFinite(config.maxTouchpointsPerUser)
 		? config.maxTouchpointsPerUser
 		: 10;
@@ -1101,6 +1327,10 @@ function applyTouchpointCap(events, config, defaults, chance) {
 
 	// Stamp UTMs on each sampled event using a campaign template.
 	for (const ev of sample) {
+		if (userCampaign) {
+			for (const [k, v] of Object.entries(userCampaign)) ev[k] = v;
+			continue;
+		}
 		const campaignTemplate = u.pickRandom(defaults.campaigns());
 		if (!campaignTemplate || typeof campaignTemplate !== 'object') continue;
 		for (const [k, v] of Object.entries(campaignTemplate)) {