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

package/lib/orchestrators/mixpanel-sender.js

@@ -71,6 +71,7 @@ async function _sendToMixpanel(context) {
 	const { config, storage } = context;
 	const {
 		adSpendData,
+		standaloneEventData,
 		eventData,
 		groupProfilesData,
 		scdTableData,
@@ -175,7 +176,18 @@ async function _sendToMixpanel(context) {
 			progressCallback: makeProgressCallback(userTotal),
 		});
 		log(`  -> ${comma(imported.success)} user profiles sent\n`);
-		importResults.users = imported;
+		// v1.7.0 (R2-5): make the receipt self-explanatory. `generated` counts every
+		// profile the engine pushed to storage (bots included); `dropped_anonymous`
+		// counts the `_drop`-flagged anonymous non-converters that never reach
+		// /engage. `generated - dropped_anonymous - failed === success` is checkable.
+		// Counters live on the context and tick at push time, so they hold in
+		// batch mode where the in-memory array has been flushed.
+		const generated = context.runtime.profilesGenerated;
+		const dropped_anonymous = context.runtime.profilesDropped;
+		importResults.users = { ...imported, generated, dropped_anonymous };
+		if (imported.success + (imported.failed || 0) + dropped_anonymous !== generated) {
+			log(`  !! profile receipt does not reconcile: ${comma(generated)} generated - ${comma(dropped_anonymous)} dropped anonymous - ${comma(imported.failed || 0)} failed != ${comma(imported.success)} success\n`);
+		}
 	}
 
 	// Import ad spend data
@@ -197,6 +209,29 @@ async function _sendToMixpanel(context) {
 		importResults.adSpend = imported;
 	}
 
+	// Import standalone (identity-less) metric snapshots — v1.8.0.
+	// Same shape as the ad-spend path: its own stream, imported as events.
+	// Gated on the config so a batch-mode run without `standaloneEvents` does
+	// not attempt an empty file read.
+	const hasStandaloneConfig = Array.isArray(config.standaloneEvents) && config.standaloneEvents.length > 0;
+	if (hasStandaloneConfig && (standaloneEventData?.length > 0 || isBATCH_MODE)) {
+		log(`  Standalone Events`);
+		let standaloneToImport = u.deepClone(standaloneEventData);
+		const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && standaloneEventData && standaloneEventData.length === 0);
+		if (shouldReadFromFiles && standaloneEventData?.getWrittenFiles) {
+			const files = standaloneEventData.getWrittenFiles();
+			if (files.length > 0) standaloneToImport = files;
+		}
+		const standaloneTotal = Array.isArray(standaloneToImport) ? standaloneToImport.length : 0;
+		const imported = await mp(creds, standaloneToImport, {
+			recordType: "event",
+			...commonOpts,
+			progressCallback: makeProgressCallback(standaloneTotal),
+		});
+		log(`  -> ${comma(imported.success)} standalone events sent\n`);
+		importResults.standalone = imported;
+	}
+
 	// Import group profiles
 	if (groupProfilesData && Array.isArray(groupProfilesData) && groupProfilesData.length > 0) {
 		for (const groupEntity of groupProfilesData) {
@@ -392,11 +427,12 @@ function logProblems(problems) {
  */
 function collectWrittenFiles(storage) {
 	const files = [];
+	if (storage.warehouseManifestFile) files.push(storage.warehouseManifestFile);
 	for (const container of [storage.eventData, storage.userProfilesData, storage.adSpendData,
-		storage.mirrorEventData, storage.groupEventData]) {
+		storage.standaloneEventData, storage.mirrorEventData, storage.groupEventData]) {
 		if (container?.getWrittenFiles) files.push(...container.getWrittenFiles());
 	}
-	for (const arr of [storage.groupProfilesData, storage.scdTableData, storage.lookupTableData]) {
+	for (const arr of [storage.groupProfilesData, storage.scdTableData, storage.lookupTableData, storage.warehouseMetricData]) {
 		if (Array.isArray(arr)) {
 			for (const c of arr) {
 				if (c?.getWrittenFiles) files.push(...c.getWrittenFiles());

package/lib/orchestrators/user-loop.js

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

package/lib/templates/story-spec.schema.json

@@ -85,7 +85,6 @@
 						"properties": {
 							"where": {
 								"type": "object",
-								"minProperties": 1,
 								"description": "Column → value (equality) or { op, value } comparison. All clauses must match (AND).",
 								"additionalProperties": {
 									"oneOf": [
@@ -123,23 +122,49 @@
 			"properties": {
 				"type": { "type": "string", "minLength": 1 }
 			},
-			"if": {
-				"properties": { "type": { "const": "duckdb" } }
-			},
-			"then": {
-				"required": ["type", "sql"],
-				"properties": {
-					"type": { "const": "duckdb" },
-					"sql": {
-						"type": "string",
-						"minLength": 1,
-						"description": "DuckDB SQL escape hatch, for bespoke shapes only. The runner shells out to the `duckdb` CLI (no npm dep) and substitutes the literal token {{PREFIX}} with the run's data prefix path (e.g. data/verify-<name>), so globs read read_json_auto('{{PREFIX}}-EVENTS*.json'). Result rows feed select/expect like emulator rows. Disk mode only — skipped (with a warning) under --in-memory."
+			"allOf": [
+				{
+					"if": {
+						"properties": { "type": { "const": "duckdb" } }
+					},
+					"then": {
+						"required": ["type", "sql"],
+						"properties": {
+							"type": { "const": "duckdb" },
+							"sql": {
+								"type": "string",
+								"minLength": 1,
+								"description": "DuckDB SQL escape hatch, for bespoke shapes only. The runner shells out to the `duckdb` CLI (no npm dep) and substitutes the literal token {{PREFIX}} with the run's data prefix path (e.g. data/verify-<name>), so globs read read_json_auto('{{PREFIX}}-EVENTS*.json'). Result rows feed select/expect like emulator rows. Disk mode only — skipped (with a warning) under --in-memory."
+							}
+						}
+					}
+				},
+				{
+					"if": {
+						"properties": { "type": { "const": "warehouse" } }
+					},
+					"then": {
+						"required": ["type", "table"],
+						"properties": {
+							"type": { "const": "warehouse" },
+							"table": { "type": "string", "minLength": 1 }
+						}
+					}
+				},
+				{
+					"if": {
+						"properties": { "type": { "const": "warehouse-stats" } }
+					},
+					"then": {
+						"required": ["type", "table"],
+						"properties": {
+							"type": { "const": "warehouse-stats" },
+							"table": { "type": "string", "minLength": 1 }
+						}
 					}
 				}
-			},
-			"else": {
-				"description": "Anything other than 'duckdb' is passed byte-compatible to emulateBreakdown / verifyDungeon (frequencyByFrequency, funnelFrequency, aggregatePerUser, timeToConvert, attributedBy, sessionMetrics, retention, distinctCount, eventBreakdown, uniques, lifecycle, topPaths)."
-			}
+			],
+			"description": "Anything other than 'duckdb', 'warehouse', or 'warehouse-stats' is passed byte-compatible to emulateBreakdown / verifyDungeon (frequencyByFrequency, funnelFrequency, aggregatePerUser, timeToConvert, attributedBy, sessionMetrics, retention, distinctCount, eventBreakdown, uniques, lifecycle, topPaths)."
 		},
 		"expect": {
 			"type": "object",

package/lib/utils/conditions.js

@@ -0,0 +1,62 @@
+/**
+ * Funnel `conditions` matching (v1.7.0 — P0-1).
+ *
+ * A funnel with `conditions` is offered only to users whose profile satisfies
+ * every key (AND across keys). Each value is either:
+ *
+ *   - a scalar → strict equality (`profile[key] === value`), unchanged since 1.3
+ *   - an operator map → every operator in the map must hold (AND within a key)
+ *
+ * Operators: `eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`.
+ * `in` / `nin` take arrays; the rest take scalars. `gt`/`gte`/`lt`/`lte` use
+ * JavaScript's `<` / `>` so numbers and ISO date strings both compare.
+ *
+ * A missing profile key never satisfies `eq`, `in`, or an ordering operator;
+ * it does satisfy `neq` and `nin` (the value is not the excluded one).
+ *
+ * The validator (`validateFunnelConditions`) rejects functions, bare arrays,
+ * unknown operators, and `in`/`nin` without an array — those shapes used to
+ * silently never match and hand the author an empty funnel.
+ */
+
+export const CONDITION_OPERATORS = Object.freeze(['eq', 'neq', 'in', 'nin', 'gt', 'gte', 'lt', 'lte']);
+const OPERATOR_SET = new Set(CONDITION_OPERATORS);
+
+/**
+ * True when `value` is an operator map (plain object, not array/Date).
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isOperatorMap(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+}
+
+/**
+ * @param {Record<string, unknown>} profile
+ * @param {Record<string, unknown>} conditions
+ * @returns {boolean}
+ */
+export function matchConditions(profile, conditions) {
+	if (!conditions) return true;
+	for (const [key, cond] of Object.entries(conditions)) {
+		const actual = profile ? profile[key] : undefined;
+		if (!isOperatorMap(cond)) {
+			if (actual !== cond) return false;
+			continue;
+		}
+		for (const [op, expected] of Object.entries(cond)) {
+			if (!OPERATOR_SET.has(op)) return false; // validator throws earlier; defensive
+			switch (op) {
+				case 'eq': if (actual !== expected) return false; break;
+				case 'neq': if (actual === expected) return false; break;
+				case 'in': if (!Array.isArray(expected) || !expected.includes(actual)) return false; break;
+				case 'nin': if (Array.isArray(expected) && expected.includes(actual)) return false; break;
+				case 'gt': if (!(/** @type {any} */ (actual) > /** @type {any} */ (expected))) return false; break;
+				case 'gte': if (!(/** @type {any} */ (actual) >= /** @type {any} */ (expected))) return false; break;
+				case 'lt': if (!(/** @type {any} */ (actual) < /** @type {any} */ (expected))) return false; break;
+				case 'lte': if (!(/** @type {any} */ (actual) <= /** @type {any} */ (expected))) return false; break;
+			}
+		}
+	}
+	return true;
+}

package/lib/utils/json-evaluator.js

@@ -48,9 +48,19 @@ export function evaluateFunctionCall(funcCall) {
 
 	const { functionName, args, body } = funcCall;
 
-	// Special handling for arrow functions
+	// Special handling for arrow functions.
+	// v1.7.0 (P1-1): emit `(ctx) => body` so serialized dungeons can read the
+	// value context (`ctx.profile`, `ctx.event`, `ctx.time`, `ctx.config`).
+	// Bodies that ignore `ctx` behave exactly as before.
 	if (functionName === 'arrow') {
-		return `() => ${body}`;
+		// `dungeon-to-json` stores a whole function source as the body
+		// (`(ctx) => ctx.profile.plan`, `function () { … }`). Emit it as-is so the
+		// revived value is that function, not a thunk returning it.
+		const trimmed = String(body).trim();
+		const isWholeFunction = /^(async\s+)?function\b/.test(trimmed)
+			|| /^(async\s*)?\([^)]*\)\s*=>/.test(trimmed)
+			|| /^(async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed);
+		return isWholeFunction ? `(${trimmed})` : `(ctx) => ${body}`;
 	}
 
 	// Handle chance.* functions