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

package/index.js

@@ -25,7 +25,8 @@ import { makeMirror } from './lib/generators/mirror.js';
 import { makeGroupProfile, makeProfile } from './lib/generators/profiles.js';
 
 // Utilities
-import { initChance, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
+import { initChance, initUserChance, resetUserChance, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
+import { runWithDataset } from './lib/utils/dataset-context.js';
 
 // External dependencies
 import dayjs from "dayjs";
@@ -130,6 +131,15 @@ async function runDungeon(config) {
 		if (config.seed) {
 			initChance(config.seed);
 		}
+		// v1.5.1: optional separate user-id RNG. Same userSeed across runs
+		// produces the same user pool, regardless of `seed`. When unset, reset
+		// any leftover state from a prior in-process run so getUserChance()
+		// falls back to the event chance (= pre-v1.5.1 behavior).
+		if (config.userSeed) {
+			initUserChance(config.userSeed);
+		} else {
+			resetUserChance();
+		}
 
 		// Step 1: Validate and enrich configuration (resolves dataset window)
 		validatedConfig = validateDungeonConfig(config);
@@ -140,11 +150,20 @@ async function runDungeon(config) {
 		const fixedBegin = /** @type {number} */ (validatedConfig.datasetStart);
 
 		// Anchor the wall-clock-free reference used by date()/day() helpers in
-		// dungeon configs. Without this, those factories produce values relative
-		// to process-start, which leaks wall-clock time into the output.
+		// dungeon configs. v1.5.1: ALS-scoped via `runWithDataset` below; the
+		// legacy `setDatasetNow` / `setDatasetBegin` setters still fire as a
+		// back-compat fallback for tests that haven't migrated to the new API.
 		setDatasetNow(fixedNow);
 		setDatasetBegin(fixedBegin);
 
+		// v1.5.1: wrap the entire pipeline in an ALS scope so factory thunks
+		// (`date`, `day`, `dateRange`, `TimeSoup`, `validTime`) inside dungeon
+		// configs resolve the dataset window per-`generate()`-call instead of
+		// reading clobberable module state. Concurrent in-process `generate()`
+		// calls now run safely with distinct windows. See
+		// `lib/utils/dataset-context.js`.
+		return await runWithDataset(fixedBegin, fixedNow, async () => {
+
 		// Step 2: Create context with validated config (pass time constants explicitly)
 		const context = createContext(validatedConfig, null, { fixedNow, fixedBegin });
 
@@ -222,10 +241,25 @@ async function runDungeon(config) {
 		// Now happens AFTER disk flush so batch files are available for import
 		let importResults;
 		if (validatedConfig.token) {
-			context.reportProgress({ phase: "step", step: "import", status: "start" });
-			const _t12 = Date.now();
-			importResults = await sendToMixpanel(context);
-			context.reportProgress({ phase: "step", step: "import", status: "complete", duration: Date.now() - _t12 });
+			// Defensive guard: real Mixpanel project tokens are 32-char hex.
+			// Placeholder strings ("your-mixpanel-token", "test-token", "hello token!", etc.)
+			// trigger mixpanel-import's infinite retry loop and hang the entire
+			// process — historically a brutal source of silent test timeouts.
+			// If the token doesn't look like a real project token, warn loudly and skip the send.
+			// Set MP_BYPASS_TOKEN_CHECK=1 to override (e.g., legitimate non-standard tokens).
+			const looksReal = /^[0-9a-f]{32}$/i.test(String(validatedConfig.token).trim());
+			if (looksReal || process.env.MP_BYPASS_TOKEN_CHECK === '1') {
+				context.reportProgress({ phase: "step", step: "import", status: "start" });
+				const _t12 = Date.now();
+				importResults = await sendToMixpanel(context);
+				context.reportProgress({ phase: "step", step: "import", status: "complete", duration: Date.now() - _t12 });
+			} else if (validatedConfig.verbose) {
+				console.warn(
+					`⚠️  Skipping Mixpanel import: token "${validatedConfig.token}" does not look like a real Mixpanel project token ` +
+					`(expected 32-char hex). Set a real token or pass empty string to skip. ` +
+					`Override with MP_BYPASS_TOKEN_CHECK=1 if your token is legitimately non-standard.`
+				);
+			}
 		}
 
 		// Step 13: Compile results
@@ -236,6 +270,12 @@ async function runDungeon(config) {
 
 		const progressSummary = context.getProgressSummary();
 
+		// v1.5.1: count of profiles that would be pushed to Mixpanel (non-`_drop`).
+		// Anonymous non-converters get `_drop: true` stamped in user-loop.js so
+		// mixpanel-sender skips them. `userProfilesData` still holds the full
+		// population for downstream tools.
+		const profilesPushed = countProfilesPushed(storage.userProfilesData);
+
 		return {
 			...extractedData,
 			importResults,
@@ -244,9 +284,12 @@ async function runDungeon(config) {
 			operations: context.getOperations(),
 			eventCount: context.getStoredEventCount(),
 			userCount: context.getUserCount(),
+			profilesPushed,
 			...(progressSummary.updates > 0 || progressSummary.errors > 0 ? { progress: progressSummary } : {})
 		};
 
+		}); // end runWithDataset
+
 	} catch (error) {
 		logger.error({ err: error }, `Error: ${error.message}`);
 		throw error;
@@ -520,6 +563,20 @@ function extractFileInfo(storage) {
 	return collectWrittenFiles(storage);
 }
 
+/**
+ * Count profiles that would be pushed to Mixpanel (anonymous non-converters carry
+ * `_drop: true` and are skipped by mixpanel-sender). v1.5.1.
+ * @param {any} profilesContainer
+ * @returns {number}
+ */
+function countProfilesPushed(profilesContainer) {
+	if (!profilesContainer) return 0;
+	const arr = Array.isArray(profilesContainer) ? profilesContainer : Array.from(profilesContainer);
+	let n = 0;
+	for (const p of arr) if (p && !p._drop) n++;
+	return n;
+}
+
 /**
  * Extract data from storage containers, preserving array structure for groups/lookups/SCDs
  * @param {import('./types').Storage} storage - Storage object

package/lib/core/config-validator.js

@@ -9,6 +9,8 @@
 /** @typedef {import('../../types.js').Funnel} Funnel */
 
 import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+dayjs.extend(utc);
 import { makeName } from "ak-tools";
 import * as u from "../utils/utils.js";
 import { resolveSoup } from "../templates/soup-presets.js";
@@ -42,8 +44,8 @@ function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays, verbose = f
 	}
 
 	if (hasStart && hasEnd) {
-		const startUnix = parseToUnix(datasetStart, 'datasetStart');
-		const endUnix = parseToUnix(datasetEnd, 'datasetEnd');
+		const startUnix = parseToUnix(datasetStart, 'datasetStart', false);
+		const endUnix = parseToUnix(datasetEnd, 'datasetEnd', true);
 		if (endUnix <= startUnix) {
 			throw new Error(`datasetEnd (${datasetEnd}) must be after datasetStart (${datasetStart}).`);
 		}
@@ -69,11 +71,22 @@ function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays, verbose = f
 /**
  * Parse a value (ISO string, unix seconds, dayjs-parseable) into unix seconds.
  * Throws if the value can't be parsed into a valid date.
+ *
+ * Bare-date convention (`YYYY-MM-DD` with no time component): pinned to UTC and
+ * interpreted as the user's intuitive intent — start of UTC day for the start
+ * boundary, end of UTC day for the end boundary. Without this rule, `dayjs()`
+ * would parse bare dates in the local timezone (cross-machine non-determinism)
+ * and treat both as start-of-day (datasetEnd would truncate ~16 hours).
+ *
+ * Full ISO strings with explicit time (`2026-05-10T23:59:59Z`,
+ * `2026-05-10T15:30:00-08:00`, etc.) are trusted as-is and parsed in UTC.
+ *
  * @param {*} value
  * @param {string} fieldName
+ * @param {boolean} [isEnd=false] - true treats bare-date strings as end-of-UTC-day
  * @returns {number}
  */
-function parseToUnix(value, fieldName) {
+function parseToUnix(value, fieldName, isEnd = false) {
 	// Treat numbers as unix seconds (or unix milliseconds if too large)
 	if (typeof value === 'number') {
 		if (!Number.isFinite(value) || value <= 0) {
@@ -82,7 +95,16 @@ function parseToUnix(value, fieldName) {
 		// Heuristic: > 10^12 means milliseconds, otherwise seconds
 		return value > 1e12 ? Math.floor(value / 1000) : Math.floor(value);
 	}
-	const parsed = dayjs(value);
+	// Bare YYYY-MM-DD → UTC start/end of day (intuitive convention)
+	if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+		const d = dayjs.utc(value);
+		if (!d.isValid()) {
+			throw new Error(`${fieldName} could not be parsed as a date (got ${JSON.stringify(value)}).`);
+		}
+		return (isEnd ? d.endOf('day') : d.startOf('day')).unix();
+	}
+	// Full ISO string (with time component) or other dayjs-parseable input — UTC parse
+	const parsed = dayjs.utc(value);
 	if (!parsed.isValid()) {
 		throw new Error(`${fieldName} could not be parsed as a date (got ${JSON.stringify(value)}).`);
 	}
@@ -152,6 +174,63 @@ function inferFunnels(events) {
  */
 const KILLED_CONFIG_KEYS = ['subscription', 'attribution', 'geo', 'features', 'anomalies'];
 
+// v1.5.1 (TODO #8): config restructure. Map sub-object → list of keys that can
+// live in that sub-object. Sub-object value wins ONLY when the top-level key
+// isn't set; if both are set, the top-level value wins and a verbose warning
+// fires (one per offending key). Old top-level keys remain functional through
+// v1.5.1 — migration is gradual.
+const CONFIG_SUBOBJECTS = {
+	credentials: ['token', 'region', 'serviceAccount', 'serviceSecret', 'projectId'],
+	switches: ['hasLocation', 'hasCampaigns', 'hasAdSpend', 'hasSessionIds', 'hasAvatar', 'hasIOSDevices', 'hasAndroidDevices', 'hasDesktopDevices', 'hasBrowser', 'isAnonymous', 'alsoInferFunnels', 'hasAttributionFlags'],
+	identity: ['avgDevicePerUser', 'sessionTimeout'],
+};
+
+/**
+ * v1.5.1 (TODO #8): merge `credentials` / `switches` / `identity` sub-objects
+ * into top-level keys. Returns a NEW config object — does not mutate input.
+ *
+ * Resolution semantics:
+ *   - sub-object key set, top-level NOT set     → use sub-object value
+ *   - sub-object key set, top-level set         → top-level wins + warn (verbose)
+ *   - sub-object missing, top-level set         → use top-level (back-compat)
+ *
+ * Special case: `identity.hasAnonIds` → deprecated. If present, maps to
+ * `avgDevicePerUser: 1` and emits a verbose warning. Top-level `hasAnonIds`
+ * preserved (legacy alias) and untouched here.
+ *
+ * @param {Partial<Dungeon>} config
+ * @returns {Partial<Dungeon>}
+ */
+function mergeConfigSubObjects(config) {
+	if (!config || typeof config !== 'object') return config;
+	const verbose = config.verbose === true;
+	const out = { ...config };
+	for (const [subKey, fields] of Object.entries(CONFIG_SUBOBJECTS)) {
+		const sub = out[subKey];
+		if (!sub || typeof sub !== 'object') continue;
+		for (const field of fields) {
+			if (sub[field] === undefined) continue;
+			if (out[field] === undefined) {
+				out[field] = sub[field];
+			} else if (verbose) {
+				console.warn(
+					`⚠️  config.${field} and config.${subKey}.${field} both set; ` +
+					`top-level wins. Drop config.${subKey}.${field} or remove the top-level value.`
+				);
+			}
+		}
+	}
+	// identity.hasAnonIds: deprecated alias.
+	if (out.identity && typeof out.identity === 'object' && out.identity.hasAnonIds !== undefined) {
+		if (verbose) console.warn(
+			`⚠️  identity.hasAnonIds is deprecated. Use identity.avgDevicePerUser: 1 instead. ` +
+			`Falling back to avgDevicePerUser=1 for v1.5.1.`
+		);
+		if (out.avgDevicePerUser === undefined) out.avgDevicePerUser = 1;
+	}
+	return out;
+}
+
 /**
  * Strip killed config keys in place, log one deprecation warning per dungeon.
  * @param {Partial<Dungeon>} config
@@ -168,6 +247,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, verbose = false) {
+	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));
+				if (verbose) 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, verbose = false) {
+	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 (verbose && 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).
@@ -253,6 +411,13 @@ function resolveDevicesPerUser(config) {
 export function validateDungeonConfig(config) {
 	const chance = u.getChance();
 
+	// v1.5.1 (TODO #8): merge `switches` / `identity` / `credentials`
+	// sub-objects into top-level keys. New shape is preferred; old top-level
+	// keys still honored for back-compat with a verbose-gated warning. The
+	// rest of the validator reads from flat keys, so this is a transparent
+	// normalization step.
+	config = mergeConfigSubObjects(config);
+
 	// Phase 1 — strip killed config keys before anything else reads them.
 	stripKilledConfigKeys(config);
 
@@ -373,6 +538,31 @@ 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.
+	// v1.5.1: each macro preset (except `flat`) ships a sensible default —
+	// applied only when the dungeon doesn't set the field explicitly.
+	const macroResolvedEarly = resolveMacro(config.macro);
+	const avgActiveDaysPerUser = (config.avgActiveDaysPerUser !== undefined && config.avgActiveDaysPerUser !== null)
+		? config.avgActiveDaysPerUser
+		: macroResolvedEarly.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 (verbose && 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.
@@ -390,20 +580,133 @@ export function validateDungeonConfig(config) {
 	// bornRecentBias / percentUsersBornInDataset / preExistingSpread on the
 	// dungeon config win over the macro preset's values, so existing dungeons
 	// that set these explicitly continue to render the same way.
-	// Resolve into local vars (do NOT mutate input config).
-	const macroResolved = resolveMacro(config.macro);
+	// Resolve into local vars (do NOT mutate input config). v1.5.1: reuse the
+	// early-resolved macro from the avgActiveDaysPerUser merge above.
+	const macroResolved = macroResolvedEarly;
 	let bornRecentBias = config.bornRecentBias !== undefined ? config.bornRecentBias : macroResolved.bornRecentBias;
 	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) {
+		if (verbose) console.warn(`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} clamped to 100. Values above 100 are not meaningful.`);
+		percentUsersBornInDataset = 100;
+	}
+	if (percentUsersBornInDataset < 0) {
+		if (verbose) 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) {
+			if (verbose) 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) {
+			if (verbose) 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) {
+			if (verbose) 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) {
+		if (verbose) 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) {
+		if (verbose) 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));
+		if (verbose) 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 (verbose && 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 +764,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;
+		if (verbose) 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 +817,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 +841,7 @@ export function validateDungeonConfig(config) {
 
 
 
-	// Event validation 
+	// Event validation
 	const validatedEvents = u.validateEventConfig(events);
 
 	// ── Validate and resolve advanced features ──
@@ -542,6 +873,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, verbose);
+
+	// v1.5.0: validate Funnel.exclusionEvents — entries must exist in events[].
+	validateExclusionEvents(funnels, validatedEvents, verbose);
+
 	// Normalize experiment configs: true → default 3-variant, object → validated.
 	normalizeExperiments(funnels, datasetEndUnix);
 
@@ -565,6 +902,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 +963,20 @@ 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.1 retention curve (`day1`/`day7`/`day30` etc. anchor weights). When
+		// set, `buildActiveDayPlan` biases day selection by the curve and the
+		// effective `avgActiveDaysPerUser` is derived from the curve's sum.
+		retentionCurve: (typeof config.retentionCurve === 'object' && config.retentionCurve !== null)
+			? config.retentionCurve
+			: 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,
@@ -669,7 +1030,7 @@ function transformSCDPropsWithoutCredentials(config) {
 	}
 
 	// UI job without credentials - convert SCD props to regular props
-	if (config.verbose !== false) console.log('\u26a0\ufe0f  Service account credentials missing - converting SCD properties to static properties');
+	if (config.verbose === true) console.log('\u26a0\ufe0f  Service account credentials missing - converting SCD properties to static properties');
 
 	// Ensure userProps and groupProps exist
 	if (!config.userProps) config.userProps = {};
@@ -688,20 +1049,20 @@ function transformSCDPropsWithoutCredentials(config) {
 		if (type === "user") {
 			// Add to userProps
 			config.userProps[propKey] = values;
-			if (config.verbose !== false) console.log(`  \u2713 Converted user SCD property: ${propKey}`);
+			if (config.verbose === true) console.log(`  \u2713 Converted user SCD property: ${propKey}`);
 		} else {
 			// Add to groupProps for the specific group type
 			if (!config.groupProps[type]) {
 				config.groupProps[type] = {};
 			}
 			config.groupProps[type][propKey] = values;
-			if (config.verbose !== false) console.log(`  \u2713 Converted group SCD property: ${propKey} (${type})`);
+			if (config.verbose === true) console.log(`  \u2713 Converted group SCD property: ${propKey} (${type})`);
 		}
 	}
 
 	// Clear out scdProps since we've converted everything
 	config.scdProps = {};
-	if (config.verbose !== false) console.log('\u2713 SCD properties converted to static properties\n');
+	if (config.verbose === true) console.log('\u2713 SCD properties converted to static properties\n');
 }
 
 // ── Advanced Feature Validation Functions ──