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

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
@@ -302,10 +325,61 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	);
 
 	// Compute the auth-time of the actual stitch event in execution order, if any.
-	const authTimeMs = runAuthExecIdx >= 0 && finalEvents[runAuthExecIdx]
+	// Skip when the stitch event itself is _drop'd (e.g. born-late users whose auth
+	// event lands past FIXED_NOW and gets filtered out): the user has no real auth
+	// event, so userAuthTimeMs must stay null to keep downstream stamping consistent.
+	const authTimeMs = runAuthExecIdx >= 0 && finalEvents[runAuthExecIdx] && !finalEvents[runAuthExecIdx]._drop
 		? 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;
+}
+

package/lib/orchestrators/mixpanel-sender.js

@@ -110,10 +110,17 @@ export async function sendToMixpanel(context) {
 			const files = userProfilesData.getWrittenFiles();
 			if (files.length > 0) userProfilesToImport = files;
 		}
+		// v1.5.1: skip `_drop` profiles (anonymous non-converters — see user-loop.js).
+		// In-memory path: filter the array. Disk path: `transformFunc` filters
+		// per-record as mixpanel-import streams the files.
+		if (Array.isArray(userProfilesToImport)) {
+			userProfilesToImport = userProfilesToImport.filter(p => !p || !p._drop);
+		}
 		const userTotal = Array.isArray(userProfilesToImport) ? userProfilesToImport.length : 0;
 		const imported = await mp(creds, userProfilesToImport, {
 			recordType: "user",
 			...commonOpts,
+			transformFunc: (record) => (record && record._drop) ? {} : record,
 			progressCallback: makeProgressCallback(userTotal),
 		});
 		log(`  -> ${comma(imported.success)} user profiles sent\n`);