@ak--47/dungeon-master 1.6.5 → 1.8.0

package/lib/core/config-validator.js

@@ -15,6 +15,47 @@ 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";
+import { validateStandaloneEvents } from "../generators/standalone.js";
+import { validateWarehouseMetrics } from "../generators/warehouse.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 +226,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 +305,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 +315,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 +435,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 +647,51 @@ 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.8.0 — identity-less metric snapshots. Throws on anything malformed;
+	// a silent skip would drop a whole data stream without the author noticing.
+	const standaloneEvents = validateStandaloneEvents(config.standaloneEvents);
+	const {
+		warehouseMetrics,
+		warnings: warehouseMetricWarnings,
+	} = validateWarehouseMetrics(config);
+	for (const reason of warehouseMetricWarnings) {
+		const key = String(reason).split(' ')[0] || 'warehouseMetrics';
+		warnings.push({
+			key,
+			reason,
+			severity: /clamp/i.test(reason) ? 'clamp' : 'warn',
+		});
+	}
+
+	// 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 +858,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 +877,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 +912,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 +929,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 +940,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 +951,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 +960,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 +980,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 +1104,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 +1138,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 +1163,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);
@@ -998,6 +1224,9 @@ export function validateDungeonConfig(config) {
 		groupKeys: normalizedGroupKeys,
 		groupProps,
 		lookupTables,
+		// v1.8.0 identity-less metric snapshots (normalized)
+		standaloneEvents,
+		warehouseMetrics,
 		hasAnonIds: hasAnonIdsResolved,
 		avgDevicePerUser,
 		hasSessionIds,
@@ -1021,6 +1250,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 +1427,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 +1465,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 {
@@ -275,7 +278,7 @@ export function validateDungeonShape(input) {
 		'events', 'numEvents', 'numUsers', 'numDays', 'funnels',
 		'userProps', 'superProps', 'hook', 'token', 'seed',
 		'scdProps', 'groupKeys', 'lookupTables', 'mirrorProps',
-		'hasAdSpend', 'soup', 'format', 'writeToDisk'
+		'hasAdSpend', 'standaloneEvents', 'warehouseMetrics', 'soup', 'format', 'writeToDisk'
 	];
 
 	const hasAnyDungeonKey = dungeonKeys.some(key => key in config);

package/lib/core/storage.js

@@ -91,15 +91,17 @@ export async function createHookArray(arr = [], opts) {
 		if (item === null || item === undefined) return false;
 		if (typeof item === 'object' && Object.keys(item).length === 0) return false;
 
+		const isWarehouse = type === "warehouse";
+
 		// Skip hook for types already hooked in generators/orchestrators to prevent double-firing
 		// Types hooked upstream: "event" (events.js), "user" (user-loop.js), "scd" (user-loop.js)
-		// Types only hooked here: "mirror", "ad-spend", "group", "lookup"
+		// Types only hooked here: "mirror", "ad-spend", "group", "lookup", "standalone"
 		const alreadyHooked = type === "event" || type === "user" || type === "scd";
 
 		// Performance optimization: skip hook overhead for passthrough hooks
 		// Only treat as passthrough if the function body is trivially simple (just returns its argument)
 		const hookStr = hook.toString();
-		const isPassthroughHook = hook.length === 1 || /^\s*function\s*\([^)]*\)\s*\{\s*return\s+\w+;?\s*\}\s*$/.test(hookStr) || /^\s*\(?[^)]*\)?\s*=>\s*\w+\s*$/.test(hookStr);
+		const isPassthroughHook = !isWarehouse && (hook.length === 1 || /^\s*function\s*\([^)]*\)\s*\{\s*return\s+\w+;?\s*\}\s*$/.test(hookStr) || /^\s*\(?[^)]*\)?\s*=>\s*\w+\s*$/.test(hookStr));
 
 		if (alreadyHooked || isPassthroughHook) {
 			// Fast path for passthrough hooks - no transformation needed
@@ -131,6 +133,10 @@ export async function createHookArray(arr = [], opts) {
 				for (const i of item) {
 					try {
 						const enriched = await hook(i, type, allMetaData);
+						if (isWarehouse) {
+							if (isValidEvent(i)) arr.push(i);
+							continue;
+						}
 						if (Array.isArray(enriched)) {
 							enriched.forEach(e => {
 								if (isValidEvent(e)) arr.push(e);
@@ -146,6 +152,10 @@ export async function createHookArray(arr = [], opts) {
 			} else {
 				try {
 					const enriched = await hook(item, type, allMetaData);
+					if (isWarehouse) {
+						if (isValidEvent(item)) arr.push(item);
+						return Promise.resolve(false);
+					}
 					if (Array.isArray(enriched)) {
 						enriched.forEach(e => {
 							if (isValidEvent(e)) arr.push(e);
@@ -161,7 +171,7 @@ export async function createHookArray(arr = [], opts) {
 		}
 
 		// Check batch size and handle writes synchronously to prevent race conditions
-		if (arr.length > BATCH_SIZE && !isWriting) {
+		if (!isWarehouse && arr.length > BATCH_SIZE && !isWriting) {
 			isWriting = true; // Lock to prevent concurrent writes
 			isBatchMode = true;
 			runtime.isBatchMode = true; // Update runtime state
@@ -200,6 +210,9 @@ export async function createHookArray(arr = [], opts) {
 		const streamOptions = {
 			gzip: config.gzip || false
 		};
+		if (type === "warehouse" && Array.isArray(rest.fixedColumns)) {
+			streamOptions.fixedColumns = rest.fixedColumns;
+		}
 
 		switch (format) {
 			case "csv":
@@ -253,6 +266,8 @@ export async function createHookArray(arr = [], opts) {
 	enrichedArray.getWriteDir = getWriteDir;
 	enrichedArray.getWritePath = getWritePath;
 	enrichedArray.getWrittenFiles = () => [...writtenFiles];
+	enrichedArray.type = type;
+	enrichedArray.format = format;
 
 	// Add additional properties from rest
 	for (const key in rest) {
@@ -309,9 +324,20 @@ export class StorageManager {
 				context: this.context
 			}),
 
+			// v1.8.0 — identity-less metric snapshots (`standaloneEvents`).
+			standaloneEventData: await createHookArray([], {
+				hook: config.hook,
+				type: "standalone",
+				filepath: `${config.name}-STANDALONE`,
+				format: config.format || "csv",
+				concurrency: config.concurrency || 1,
+				context: this.context
+			}),
+
 			scdTableData: [],
 			groupProfilesData: [],
 			lookupTableData: [],
+			warehouseMetricData: [],
 
 			mirrorEventData: await createHookArray([], {
 				hook: config.hook,
@@ -375,6 +401,28 @@ export class StorageManager {
 			}
 		}
 
+		if (config.warehouseMetrics && config.warehouseMetrics.length > 0) {
+			for (const warehouseMetric of config.warehouseMetrics) {
+				const fixedColumns = [
+					warehouseMetric.timeColumn,
+					...(warehouseMetric.source.groupBy || []),
+					warehouseMetric.valueColumn,
+					...Object.keys(warehouseMetric.columns || {}),
+				];
+				const warehouseArray = await createHookArray([], {
+					hook: config.hook,
+					type: "warehouse",
+					filepath: `${config.name}-WAREHOUSE-${warehouseMetric.name}`,
+					format: warehouseMetric.format || config.format || "csv",
+					concurrency: config.concurrency || 1,
+					context: this.context,
+					metricName: warehouseMetric.name,
+					fixedColumns,
+				});
+				storage.warehouseMetricData.push(warehouseArray);
+			}
+		}
+
 		return storage;
 	}