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

package/index.js

@@ -27,7 +27,7 @@ import { makeMirror } from './lib/generators/mirror.js';
 import { makeGroupProfile, makeProfile } from './lib/generators/profiles.js';
 
 // Utilities
-import { initChance, initUserChance, resetUserChance, resetValueCaches, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
+import { initChance, initUserChance, resetUserChance, resetValueCaches, setAutoPowerLaw, setDatasetNow, setDatasetBegin, deleteFile } from './lib/utils/utils.js';
 import { runWithDataset } from './lib/utils/dataset-context.js';
 
 // External dependencies
@@ -150,6 +150,12 @@ async function runDungeon(config) {
 		// Step 1: Validate and enrich configuration (resolves dataset window)
 		validatedConfig = validateDungeonConfig(config);
 
+		// v1.7.0 (P2-1): `autoPowerLaw: false` turns off the implicit 45/25/15 draw on
+		// 3–19-item string arrays for this run. Module-level flag, like the seeded
+		// chance instance — `choose()` has no config access. resetValueCaches()
+		// above already restored the default (true) for this run.
+		setAutoPowerLaw(validatedConfig.autoPowerLaw !== false);
+
 		// validateDungeonConfig always resolves these to unix seconds, but the
 		// public Dungeon type accepts string | number on input. Narrow here.
 		const fixedNow = /** @type {number} */ (validatedConfig.datasetEnd);
@@ -282,9 +288,18 @@ async function runDungeon(config) {
 		// population for downstream tools.
 		const profilesPushed = countProfilesPushed(storage.userProfilesData);
 
+		// v1.7.0 (P2-2): every value the engine changed or flagged, validator
+		// clamps first, then aggregated runtime warnings (conversionRate saturation,
+		// users matching no funnel, …). Always present, even when empty.
+		const warnings = [
+			...(Array.isArray(validatedConfig._warnings) ? validatedConfig._warnings : []),
+			...context.getWarnings(),
+		];
+
 		return {
 			...extractedData,
 			importResults,
+			warnings,
 			files: extractFileInfo(storage),
 			time: { start, end, delta, human },
 			operations: context.getOperations(),

package/lib/core/config-validator.js

@@ -15,6 +15,45 @@ import { makeName } from "ak-tools";
 import * as u from "../utils/utils.js";
 import { resolveSoup } from "../templates/soup-presets.js";
 import { resolveMacro } from "../templates/macro-presets.js";
+import { locations as LOCATION_TEMPLATE } from "../templates/defaults.js";
+import { CONDITION_OPERATORS } from "../utils/conditions.js";
+
+/**
+ * v1.7.0 (P2-2): one entry per value the validator changed or flagged. Collected
+ * on `validatedConfig._warnings` and surfaced as `result.warnings` regardless of
+ * `verbose`. Console output stays `verbose`-gated; a config UI needs the data,
+ * not the log line.
+ *
+ * @typedef {import('../../types.js').EngineWarning} EngineWarning
+ */
+
+/**
+ * Resolve `singleCountry` to the canonical country name used by the location
+ * template. Accepts the full name (`"United States"`) or the ISO code (`"US"`),
+ * case-insensitive. Throws when nothing matches — an empty location pool
+ * silently deleted every geo property from events and profiles before 1.7.0.
+ *
+ * @param {unknown} singleCountry
+ * @returns {string | undefined} canonical `country` value, or undefined when unset
+ */
+export function resolveSingleCountry(singleCountry) {
+	if (singleCountry === undefined || singleCountry === null || singleCountry === '') return undefined;
+	if (typeof singleCountry !== 'string') {
+		throw new Error(`singleCountry must be a country name or ISO code string (got ${typeof singleCountry})`);
+	}
+	const needle = singleCountry.trim().toLowerCase();
+	const hit = LOCATION_TEMPLATE.find(l =>
+		String(l.country).toLowerCase() === needle || String(l.country_code).toLowerCase() === needle
+	);
+	if (!hit) {
+		const valid = [...new Map(LOCATION_TEMPLATE.map(l => [l.country_code, `${l.country_code} (${l.country})`])).values()];
+		throw new Error(
+			`singleCountry "${singleCountry}" matches no country in the location template, so the location pool would be empty ` +
+			`and every geo property would vanish. Valid values (name or code): ${valid.join(', ')}`
+		);
+	}
+	return String(hit.country);
+}
 
 /**
  * Resolve dataset window from config. Returns { datasetStartUnix, datasetEndUnix, numDays }.
@@ -185,7 +224,9 @@ const CONFIG_SUBOBJECTS = {
 	// settable — line ~942 unconditionally overwrites it with
 	// `validatedEvents.some(e => e.isAttributionEvent)`. Listing it here presented
 	// a knob that never did anything.
-	switches: ['hasLocation', 'hasCampaigns', 'hasAdSpend', 'hasSessionIds', 'hasAvatar', 'hasIOSDevices', 'hasAndroidDevices', 'hasDesktopDevices', 'hasBrowser', 'isAnonymous', 'alsoInferFunnels'],
+	// v1.7.0: `singleCountry`, `campaignPerUser` and `stickyEventProps` are data-shape
+	// knobs, so they hoist from `switches` like the booleans do.
+	switches: ['hasLocation', 'hasCampaigns', 'hasAdSpend', 'hasSessionIds', 'hasAvatar', 'hasIOSDevices', 'hasAndroidDevices', 'hasDesktopDevices', 'hasBrowser', 'isAnonymous', 'alsoInferFunnels', 'singleCountry', 'campaignPerUser', 'stickyEventProps'],
 	identity: ['avgDevicePerUser', 'sessionTimeout'],
 };
 
@@ -262,7 +303,7 @@ function stripKilledConfigKeys(config) {
  *
  * @param {import('../../types.js').Funnel[]} funnels
  */
-function validateConversionWindow(funnels, verbose = false) {
+function validateConversionWindow(funnels, verbose = false, warnings = []) {
 	const DEFAULT_WINDOW_DAYS = 30;
 	const MAX_WINDOW_DAYS = 180;
 	for (const f of funnels) {
@@ -272,6 +313,13 @@ function validateConversionWindow(funnels, verbose = false) {
 		if (f.conversionWindowDays === undefined || f.conversionWindowDays === null) {
 			if (ttcDays >= DEFAULT_WINDOW_DAYS) {
 				f.conversionWindowDays = Math.min(MAX_WINDOW_DAYS, Math.ceil(ttcDays * 1.5));
+				warnings.push({
+					key: `funnels[${f.name || (f.sequence && f.sequence.join(' > '))}].conversionWindowDays`,
+					requested: undefined,
+					applied: f.conversionWindowDays,
+					reason: `timeToConvert (${ttcDays.toFixed(1)}d) exceeds the default 30d conversion window; auto-set`,
+					severity: 'warn',
+				});
 				if (verbose) console.warn(
 					`⚠️  Funnel "${f.name || (f.sequence && f.sequence.join(' > '))}": ` +
 					`timeToConvert (${ttcDays.toFixed(1)}d) exceeds default 30d conversion window. ` +
@@ -385,8 +433,112 @@ function normalizeExperiments(funnels, datasetEndUnix) {
 		// Sticky bucketing defaults true — the per-user hash was the only pre-1.6
 		// behavior, so existing dungeons stay byte-identical.
 		const sticky = raw.sticky === undefined ? true : !!raw.sticky;
-		f._experiment = { name, variants, startUnix, sticky };
+		// v1.7.0 (P0-2): stamp the assigned variant on the user profile as
+		// `Experiment: <name>`. Default true; `stampProfile: false` opts out.
+		// Only meaningful when sticky — a re-rolled variant has no single value.
+		const stampProfile = raw.stampProfile === undefined ? true : !!raw.stampProfile;
+		f._experiment = { name, variants, startUnix, sticky, stampProfile };
+	}
+}
+
+/**
+ * v1.7.0 (P0-1): validate `Funnel.conditions` shapes at config time.
+ *
+ * Throws on shapes that can never match: function values, bare arrays (use
+ * `{ in: [...] }`), unknown operators, `in`/`nin` without an array, ordering
+ * operators without a number/string. Warns (into `warnings`) when a condition
+ * key is declared nowhere the profile is built from — `userProps`, any persona's
+ * `properties`, or `superProps` — because only a `user` hook could then supply it.
+ *
+ * @param {import('../../types.js').Funnel[]} funnels
+ * @param {Partial<Dungeon>} config
+ * @param {EngineWarning[]} warnings
+ */
+function validateFunnelConditions(funnels, config, warnings) {
+	if (!Array.isArray(funnels)) return;
+	const declared = new Set([
+		...Object.keys(config.userProps || {}),
+		...Object.keys(config.superProps || {}),
+		...(Array.isArray(config.personas) ? config.personas.flatMap(p => Object.keys((p && p.properties) || {})) : []),
+	]);
+	const undeclared = new Set();
+	for (const f of funnels) {
+		if (!f || !f.conditions) continue;
+		const label = `funnels[${f.name || (Array.isArray(f.sequence) ? f.sequence.join(' > ') : '?')}].conditions`;
+		if (typeof f.conditions !== 'object' || Array.isArray(f.conditions)) {
+			throw new Error(`${label} must be an object mapping profile keys to a scalar or an operator map`);
+		}
+		for (const [key, cond] of Object.entries(f.conditions)) {
+			if (typeof cond === 'function') {
+				throw new Error(`${label}.${key} is a function. Conditions compare against the resolved profile value; pass a scalar or an operator map such as { in: [...] }.`);
+			}
+			if (Array.isArray(cond)) {
+				throw new Error(`${label}.${key} is a bare array, which never matches (strict equality). Use { in: [${cond.map(v => JSON.stringify(v)).join(', ')}] }.`);
+			}
+			if (cond !== null && typeof cond === 'object' && !(cond instanceof Date)) {
+				const ops = Object.keys(cond);
+				if (!ops.length) throw new Error(`${label}.${key} is an empty operator map`);
+				for (const op of ops) {
+					if (!CONDITION_OPERATORS.includes(op)) {
+						throw new Error(`${label}.${key} uses unknown operator "${op}". Valid operators: ${CONDITION_OPERATORS.join(', ')}`);
+					}
+					const expected = cond[op];
+					if ((op === 'in' || op === 'nin') && !Array.isArray(expected)) {
+						throw new Error(`${label}.${key}.${op} requires an array (got ${typeof expected})`);
+					}
+					if ((op === 'gt' || op === 'gte' || op === 'lt' || op === 'lte') && typeof expected !== 'number' && typeof expected !== 'string') {
+						throw new Error(`${label}.${key}.${op} requires a number or string (got ${typeof expected})`);
+					}
+					if ((op === 'eq' || op === 'neq') && (typeof expected === 'function' || Array.isArray(expected))) {
+						throw new Error(`${label}.${key}.${op} requires a scalar`);
+					}
+				}
+			}
+			if (!declared.has(key)) undeclared.add(`${label}.${key}`);
+		}
+	}
+	for (const path of undeclared) {
+		warnings.push({
+			key: path,
+			requested: undefined,
+			applied: undefined,
+			reason: 'condition key is not declared in userProps, superProps, or any persona.properties — it can only match if a `user` hook sets it',
+			severity: 'warn',
+		});
+	}
+}
+
+/**
+ * v1.7.0 (P1-2): validate `stickyEventProps`. Every key must be declared in
+ * `userProps`, a persona's `properties`, or `superProps` (schema-first). Returns
+ * the normalized list plus the subset that lives only in `superProps` (those are
+ * resolved once per user rather than copied from the profile).
+ *
+ * @param {unknown} stickyEventProps
+ * @param {Partial<Dungeon>} config
+ * @returns {{ keys: string[], superOnly: Set<string> }}
+ */
+function validateStickyEventProps(stickyEventProps, config) {
+	if (stickyEventProps === undefined || stickyEventProps === null) return { keys: [], superOnly: new Set() };
+	if (!Array.isArray(stickyEventProps) || stickyEventProps.some(k => typeof k !== 'string' || !k)) {
+		throw new Error(`stickyEventProps must be an array of property-name strings (got ${JSON.stringify(stickyEventProps)})`);
+	}
+	const profileKeys = new Set([
+		...Object.keys(config.userProps || {}),
+		...(Array.isArray(config.personas) ? config.personas.flatMap(p => Object.keys((p && p.properties) || {})) : []),
+	]);
+	const superKeys = new Set(Object.keys(config.superProps || {}));
+	const superOnly = new Set();
+	const keys = [...new Set(stickyEventProps)];
+	for (const key of keys) {
+		if (profileKeys.has(key)) continue;
+		if (superKeys.has(key)) { superOnly.add(key); continue; }
+		throw new Error(
+			`stickyEventProps entry "${key}" is not declared in userProps, superProps, or any persona.properties. ` +
+			`Declare it first (schema-first) — hooks may not add new properties.`
+		);
 	}
+	return { keys, superOnly };
 }
 
 /**
@@ -493,9 +645,35 @@ export function validateDungeonConfig(config) {
 		name = "",
 		batchSize = 2_500_000,
 		concurrency = 1,
-		strictEventCount = false
+		strictEventCount = false,
+		autoPowerLaw = true,
+		campaignPerUser = false,
 	} = config;
 
+	/** @type {EngineWarning[]} */
+	const warnings = [];
+
+	// v1.7.0 (R2-2): resolve singleCountry to the template's canonical name (accepts
+	// ISO code or full name, case-insensitive) or throw. Before 1.7.0 a miss
+	// filtered the location pool to empty and silently deleted every geo property.
+	const singleCountry = resolveSingleCountry(config.singleCountry);
+
+	if (typeof autoPowerLaw !== 'boolean') {
+		throw new Error(`autoPowerLaw must be a boolean (got ${typeof autoPowerLaw})`);
+	}
+	if (typeof campaignPerUser !== 'boolean') {
+		throw new Error(`campaignPerUser must be a boolean (got ${typeof campaignPerUser})`);
+	}
+	if (campaignPerUser && !hasCampaigns) {
+		warnings.push({
+			key: 'campaignPerUser',
+			requested: true,
+			applied: false,
+			reason: 'campaignPerUser has no effect without hasCampaigns: true (no UTMs are stamped)',
+			severity: 'warn',
+		});
+	}
+
 	// Allow concurrency override from config (default is now 1)
 	if (config.concurrency === undefined || config.concurrency === null) {
 		concurrency = 1;
@@ -662,10 +840,12 @@ export function validateDungeonConfig(config) {
 	}
 	if (percentUsersBornInDataset > 100) {
 		if (verbose) console.warn(`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} clamped to 100. Values above 100 are not meaningful.`);
+		warnings.push({ key: 'percentUsersBornInDataset', requested: percentUsersBornInDataset, applied: 100, reason: 'values above 100 are not meaningful', severity: 'clamp' });
 		percentUsersBornInDataset = 100;
 	}
 	if (percentUsersBornInDataset < 0) {
 		if (verbose) console.warn(`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} clamped to 0. Negative values are not meaningful.`);
+		warnings.push({ key: 'percentUsersBornInDataset', requested: percentUsersBornInDataset, applied: 0, reason: 'negative values are not meaningful', severity: 'clamp' });
 		percentUsersBornInDataset = 0;
 	}
 
@@ -679,20 +859,32 @@ export function validateDungeonConfig(config) {
 	// 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).
+	//
+	// v1.7.0 (R2-1): the cap is keyed on the NAMED preset only. A macro object
+	// without `preset` (`macro: { bornRecentBias: 0.3, percentUsersBornInDataset: 50 }`)
+	// is a custom macro — the author owns the shape, so no preset contract applies
+	// and the overrides are honored as written. Before 1.7.0 the preset-less object
+	// fell back to the `flat` cap (12) and silently ignored its own born%.
 	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) {
+		: (macroAsObj !== null && typeof macroAsObj.preset === 'string') ? macroAsObj.preset : null;
+	if (userBornExplicit && macroKey !== null && 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.`
+				`right-edge explosion. Use macro="growth" or "viral" for genuinely high-born configs, ` +
+				`or drop \`preset\` for a custom macro with no cap.`
 			);
+			warnings.push({
+				key: 'percentUsersBornInDataset',
+				requested: percentUsersBornInDataset,
+				applied: cap,
+				reason: `macro preset "${macroKey}" caps percentUsersBornInDataset at ${cap} to keep its shape; use a higher-born preset or a custom macro object without \`preset\``,
+				severity: 'clamp',
+			});
 			percentUsersBornInDataset = cap;
 		}
 	}
@@ -702,10 +894,12 @@ export function validateDungeonConfig(config) {
 	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.`);
+			warnings.push({ key: 'bornRecentBias', requested: bornRecentBias, applied: 0.5, reason: 'above 0.5 produces unusable right-skew', severity: 'clamp' });
 			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.`);
+			warnings.push({ key: 'bornRecentBias', requested: bornRecentBias, applied: -0.5, reason: 'below -0.5 produces unusable left-skew', severity: 'clamp' });
 			bornRecentBias = -0.5;
 		}
 	}
@@ -717,6 +911,7 @@ export function validateDungeonConfig(config) {
 			`⚠️  percentUsersBornInDataset=${percentUsersBornInDataset} + bornRecentBias=${bornRecentBias} ` +
 			`compounds to right-edge explosion. Clamping bornRecentBias to 0.3. To suppress, fix the config.`
 		);
+		warnings.push({ key: 'bornRecentBias', requested: bornRecentBias, applied: 0.3, reason: `percentUsersBornInDataset=${percentUsersBornInDataset} with bornRecentBias > 0.4 compounds to a right-edge explosion`, severity: 'clamp' });
 		bornRecentBias = 0.3;
 	}
 
@@ -727,6 +922,7 @@ export function validateDungeonConfig(config) {
 	// 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.`);
+		warnings.push({ key: 'avgEventsPerUserPerDay', requested: avgEventsPerUserPerDay, applied: 50, reason: 'above 50 is unrealistic load and memory cost; numEvents recomputed from the clamped rate', severity: 'clamp' });
 		avgEventsPerUserPerDay = 50;
 		numEvents = Math.round(avgEventsPerUserPerDay * numUsers * numDays);
 	}
@@ -737,6 +933,7 @@ export function validateDungeonConfig(config) {
 	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.`);
+		warnings.push({ key: 'avgActiveDaysPerUser', requested: avgActiveDaysPerUser, applied: cap, reason: `above numDays/2 (${numDays}/2) defeats the concentrator purpose`, severity: 'clamp' });
 		avgActiveDaysClamped = cap;
 	}
 
@@ -745,8 +942,9 @@ export function validateDungeonConfig(config) {
 	// 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.`);
+	if (numDays < 14) {
+		if (verbose) console.warn(`⚠️  numDays=${numDays} < 14. Strict-bar engine-validation metrics use 14-day windows; results are noisy below 14 days. Consider increasing numDays.`);
+		warnings.push({ key: 'numDays', requested: numDays, applied: numDays, reason: 'below the 14-day safe range; trend shape is noisy and not clamped', severity: 'warn' });
 	}
 
 	// v1.6.4 (P3-9): warn when `avgActiveDaysPerUser` and `engagementDecay` are both
@@ -764,6 +962,7 @@ export function validateDungeonConfig(config) {
 			`Decay erodes the effective active-day count, so the realized value will be at or below ` +
 			`${avgActiveDaysPerUser}, never above. Prefer one knob or the other. See HOOKS.md §2.5.`
 		);
+		warnings.push({ key: 'avgActiveDaysPerUser', requested: avgActiveDaysPerUser, applied: avgActiveDaysPerUser, reason: 'set together with engagementDecay; decay erodes the realized active-day count below this value', severity: 'warn' });
 	}
 	// ──────────────────────────────────────────────────────────────────────
 
@@ -887,6 +1086,9 @@ export function validateDungeonConfig(config) {
 			// Explicit user-defined funnels keep their declared `timeToConvert`.
 			timeToConvert: 24,
 			requireRepeats: false,
+			// v1.7.0: marks the engine-synthesized catch-all so the "user matched no
+			// funnel" report (P0-1 item 5) counts only author-declared funnels.
+			_catchAll: true,
 		});
 	}
 
@@ -918,6 +1120,12 @@ export function validateDungeonConfig(config) {
 		worldEvents = resolveWorldEvents(worldEvents, datasetStartUnix);
 	}
 
+	// v1.7.0 (P0-1): reject condition shapes that can never match; warn on undeclared keys.
+	validateFunnelConditions(funnels, config, warnings);
+
+	// v1.7.0 (P1-2): schema-first check on stickyEventProps.
+	const sticky = validateStickyEventProps(config.stickyEventProps, config);
+
 	// Feature 3: Engagement Decay
 	let engagementDecay = config.engagementDecay || null;
 	if (engagementDecay) {
@@ -937,7 +1145,7 @@ export function validateDungeonConfig(config) {
 	validateAttempts(funnels);
 
 	// v1.5: default + auto-bump Funnel.conversionWindowDays.
-	validateConversionWindow(funnels, verbose);
+	validateConversionWindow(funnels, verbose, warnings);
 
 	// v1.5.0: validate Funnel.exclusionEvents — entries must exist in events[].
 	validateExclusionEvents(funnels, validatedEvents, verbose);
@@ -1021,6 +1229,15 @@ export function validateDungeonConfig(config) {
 		hasIOSDevices,
 		name,
 		strictEventCount,
+		// v1.7.0 knobs
+		singleCountry,
+		autoPowerLaw,
+		campaignPerUser,
+		stickyEventProps: sticky.keys,
+		/** @internal keys in stickyEventProps that live only in superProps (resolved once per user) */
+		_stickySuperOnly: [...sticky.superOnly],
+		/** @internal v1.7.0 (P2-2): validator clamps + warnings; surfaced as `result.warnings` */
+		_warnings: warnings,
 		// Macro trend (resolved from preset + per-dungeon overrides; clamped)
 		macro: config.macro,
 		bornRecentBias,
@@ -1189,7 +1406,11 @@ function validatePersonas(personas) {
 		}
 		if (p.eventMultiplier === undefined) p.eventMultiplier = 1.0;
 		if (p.conversionModifier === undefined) p.conversionModifier = 1.0;
-		if (p.churnRate === undefined) p.churnRate = 0;
+		// v1.7.0 (P1-3): time-to-convert multiplier, symmetrical with conversionModifier.
+		if (p.ttcModifier === undefined) p.ttcModifier = 1.0;
+		if (!Number.isFinite(p.ttcModifier) || p.ttcModifier <= 0) {
+			throw new Error(`Persona "${p.name}" ttcModifier must be a positive finite number (got ${p.ttcModifier})`);
+		}
 		if (p.properties === undefined) p.properties = {};
 	}
 	if (deadFieldsSet.size > 0 && !warnedDeadPersonaFields) {
@@ -1223,6 +1444,15 @@ function resolveWorldEvents(worldEvents, beginUnix) {
 		if (!we.affectsEvents) resolved.affectsEvents = "*";
 		if (!we.volumeMultiplier) resolved.volumeMultiplier = 1.0;
 		if (!we.conversionModifier) resolved.conversionModifier = 1.0;
+		// v1.7.0 (P0-3): amplification is now implemented, so the field must be a
+		// usable number. Above-1 values clone affected events across the window.
+		if (!Number.isFinite(resolved.volumeMultiplier) || resolved.volumeMultiplier < 0) {
+			throw new Error(`worldEvents["${we.name}"].volumeMultiplier must be a non-negative finite number (got ${we.volumeMultiplier})`);
+		}
+		if (resolved.aftermath && resolved.aftermath.volumeMultiplier !== undefined &&
+			(!Number.isFinite(resolved.aftermath.volumeMultiplier) || resolved.aftermath.volumeMultiplier < 0)) {
+			throw new Error(`worldEvents["${we.name}"].aftermath.volumeMultiplier must be a non-negative finite number (got ${resolved.aftermath.volumeMultiplier})`);
+		}
 		return resolved;
 	}).sort((a, b) => a.startUnix - b.startUnix || (a.name || '').localeCompare(b.name || ''));
 }

package/lib/core/context.js

@@ -75,6 +75,10 @@ function createRuntimeState() {
 		eventCount: 0,
 		storedEventCount: 0,
 		userCount: 0,
+		// v1.7.0 (R2-5): profile receipt counters, incremented at push time so
+		// they are correct in batch mode too (the in-memory array is flushed).
+		profilesGenerated: 0,
+		profilesDropped: 0,
 		isBatchMode: false,
 		verbose: false
 	};
@@ -157,6 +161,12 @@ export function createContext(config, storage = null, timeConstants = {}) {
 
 	const { reportProgress, getProgressSummary } = createProgressReporter(config);
 
+	// v1.7.0 (P2-2 / P2-4): runtime warning sink. Generators aggregate by `key`
+	// (one entry per funnel / knob, with a `count`) — never one entry per user,
+	// because the callers sit in the per-user hot loop.
+	/** @type {Map<string, import('../../types.js').EngineWarning>} */
+	const runtimeWarnings = new Map();
+
 	const context = {
 		config,
 		storage,
@@ -166,6 +176,35 @@ export function createContext(config, storage = null, timeConstants = {}) {
 		reportProgress,
 		getProgressSummary,
 
+		/**
+		 * Record (or bump) an aggregated runtime warning.
+		 * @param {import('../../types.js').EngineWarning} entry
+		 */
+		addWarning(entry) {
+			const existing = runtimeWarnings.get(entry.key);
+			if (existing) {
+				existing.count = (existing.count || 1) + 1;
+				if (typeof entry.requested === 'number' && typeof existing.requested === 'number') {
+					existing.requested = Math.max(existing.requested, entry.requested);
+				}
+				return;
+			}
+			runtimeWarnings.set(entry.key, { ...entry, count: entry.count || 1 });
+		},
+
+		/** @returns {import('../../types.js').EngineWarning[]} */
+		getWarnings() {
+			return [...runtimeWarnings.values()];
+		},
+
+		incrementProfilesGenerated() {
+			runtime.profilesGenerated++;
+		},
+
+		incrementProfilesDropped() {
+			runtime.profilesDropped++;
+		},
+
 		// Helper methods for updating state
 		incrementOperations() {
 			runtime.operations++;

package/lib/core/dungeon-loader.js

@@ -202,7 +202,10 @@ function reviveFunctionObject(obj) {
 			if (typeof fn === 'function') {
 				// Smoke-test: call it once to verify it doesn't reference other missing variables.
 				// If it throws (e.g., referencing `items` from a lost closure), discard it.
-				try { fn(); } catch { return null; }
+				// v1.7.0 (P1-1): context-aware bodies (`(ctx) => ctx.profile.plan`) get an
+				// empty ValueContext so the probe does not throw on `ctx` itself.
+				const probeCtx = { profile: {}, event: {}, time: 0, config: {} };
+				try { fn.length >= 1 ? fn(probeCtx) : fn(); } catch { return null; }
 				return fn;
 			}
 		} catch {

package/lib/generators/events.js

@@ -83,9 +83,15 @@ export async function makeEvent(
 
     let defaultProps = {};
 
-    // Add default properties based on configuration
+    // Add default properties based on configuration.
+    // v1.7.0 (P1-2 / B2): a user's events share the user's location. Before 1.7.0
+    // `featureCtx.userLocation` was computed per user and never read here, so every
+    // event drew a fresh random city — 0.8% of events matched their profile's city.
+    // The per-event draw remains only for callers that pass no user location.
     if (hasLocation) {
-        defaultProps.location = u.pickRandom(defaults.locationsEvents());
+        defaultProps.location = (featureCtx && featureCtx.userLocation)
+            ? featureCtx.userLocation
+            : u.pickRandom(defaults.locationsEvents());
     }
     
     if (hasBrowser) {
@@ -114,9 +120,25 @@ export async function makeEvent(
             const latestTime = (featureCtx && Number.isFinite(featureCtx.latestTime))
                 ? featureCtx.latestTime
                 : context.FIXED_NOW;
+            // TimeSoup ALWAYS runs (even when the caller pins the time below) so the
+            // seeded RNG stream is consumed identically to pre-1.7 — byte-identical
+            // output for existing dungeons.
             unixTime = u.TimeSoup(earliestTime, latestTime, peaks, deviation, mean, dayOfWeekWeights, hourOfDayWeights);
         }
-        eventTemplate.time = dayjs.unix(unixTime).toISOString();
+        // v1.7.0: funnel steps after the first know their final time up front
+        // (`fixedTimeMs` = step-0 time + timing offset), so property thunks see the
+        // real `ctx.time` / `ctx.event` and world-event windows test the real time.
+        // Before 1.7.0 the step's time was overwritten after properties resolved.
+        if (featureCtx && Number.isFinite(featureCtx.fixedTimeMs)) {
+            eventTemplate.time = new Date(featureCtx.fixedTimeMs).toISOString();
+        } else {
+            eventTemplate.time = dayjs.unix(unixTime).toISOString();
+        }
+        // Synchronous side channel: lets the funnel generator learn step 0's time
+        // before later steps start resolving (see generateFunnelEvents).
+        if (featureCtx && typeof featureCtx.onTimeResolved === 'function') {
+            featureCtx.onTimeResolved(Date.parse(eventTemplate.time));
+        }
     }
 
     // ── Phase 2 identity stamping ──
@@ -149,6 +171,17 @@ export async function makeEvent(
         eventTemplate.user_id = distinct_id;
     }
 
+    // v1.7.0 (P1-1): value context handed to every property thunk. `event` is the
+    // partially-built record (identity + time set; properties resolve in declaration
+    // order, so a later key can read an earlier one). `profile` is the user's
+    // resolved profile when the caller supplied it (user-loop / funnels do).
+    const valueCtx = {
+        profile: (featureCtx && featureCtx.profile) || undefined,
+        event: eventTemplate,
+        time: eventTemplate.time ? Date.parse(eventTemplate.time) : undefined,
+        config,
+    };
+
     // PERFORMANCE: Process properties directly without creating intermediate object
     // Add custom properties from event configuration
     if (chosenEvent.properties) {
@@ -156,21 +189,21 @@ export async function makeEvent(
         for (let i = 0; i < eventKeys.length; i++) {
             const key = eventKeys[i];
             try {
-                eventTemplate[key] = u.choose(chosenEvent.properties[key]);
+                eventTemplate[key] = u.choose(chosenEvent.properties[key], valueCtx);
             } catch (e) {
                 logger.error({ err: e, key, event: chosenEvent.event }, `Error processing property ${key} in ${chosenEvent.event} event`);
                 // Continue processing other properties
             }
         }
     }
-    
+
     // Add super properties (override event properties if needed)
     if (superProps) {
         const superKeys = Object.keys(superProps);
         for (let i = 0; i < superKeys.length; i++) {
             const key = superKeys[i];
             try {
-                eventTemplate[key] = u.choose(superProps[key]);
+                eventTemplate[key] = u.choose(superProps[key], valueCtx);
             } catch (e) {
                 logger.error({ err: e, key }, `Error processing super property ${key}`);
                 // Continue processing other properties
@@ -178,6 +211,16 @@ export async function makeEvent(
         }
     }
 
+    // v1.7.0 (P1-2): user-sticky event properties. Resolved once per user in the
+    // user loop (after the `user` hook, so hook overrides are honored) and copied
+    // onto every event AFTER superProps — a sticky key beats a per-event re-roll of
+    // the same name — and BEFORE the `event` hook, which stays the final authority.
+    if (featureCtx && featureCtx.stickyValues) {
+        for (const key in featureCtx.stickyValues) {
+            eventTemplate[key] = featureCtx.stickyValues[key];
+        }
+    }
+
     // Add default properties if not skipped
     if (!skipDefaults) {
         addDefaultProperties(eventTemplate, defaultProps);
@@ -211,7 +254,10 @@ export async function makeEvent(
                             eventTemplate[k] = v;
                         }
                     }
-                    // Volume modulation via accept/reject: if volumeMultiplier < 1, randomly drop
+                    // Volume modulation via accept/reject: if volumeMultiplier < 1, randomly drop.
+                    // v1.7.0 (P0-3): volumeMultiplier > 1 is handled per user in
+                    // user-loop.js `amplifyWorldEvents` — affected events are cloned
+                    // (fresh insert_id) and spread across the window.
                     const volMult = inAftermath ? (we.aftermath?.volumeMultiplier || 1.0) : we.volumeMultiplier;
                     if (volMult < 1.0 && !chance.bool({ likelihood: volMult * 100 })) {
                         eventTemplate._drop = true;