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

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;

package/lib/generators/funnels.js

@@ -92,12 +92,18 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 				if (hashVal < cumWeight) { chosenVariant = expCfg.variants[vi]; chosenIdx = vi; break; }
 			}
 			experimentVariant = chosenVariant.name;
-			funnel.conversionRate = Math.min(100, Math.max(1,
-				Math.round((funnel.conversionRate || 50) * chosenVariant.conversionMultiplier)));
+			funnel.conversionRate = saturateConversionRate(context, funnel,
+				Math.round((funnel.conversionRate || 50) * chosenVariant.conversionMultiplier), `experiment "${experimentName}" variant "${experimentVariant}"`, 1);
 			funnel.timeToConvert = Math.max(0.1,
 				(funnel.timeToConvert || 1) * chosenVariant.ttcMultiplier);
 			funnel._experimentName = experimentName;
 			funnel._experimentVariant = experimentVariant;
+			// v1.7.0 (P0-2): record the assignment so the user loop can stamp
+			// `Experiment: <name>` on the profile. Only when the bucketing is sticky
+			// (a re-rolled variant has no single per-user value) and stampProfile is on.
+			if (expCfg.sticky !== false && expCfg.stampProfile !== false && featureCtx && featureCtx.experimentAssignments) {
+				featureCtx.experimentAssignments.set(experimentName, experimentVariant);
+			}
 			funnel.sequence = ["$experiment_started", ...funnel.sequence];
 			experimentMeta = {
 				name: experimentName,
@@ -113,7 +119,13 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	// Apply persona and world-event modifiers to the funnel BEFORE the hook fires,
 	// so funnel-pre sees the effective rate and has final authority.
 	if (persona && persona.conversionModifier) {
-		funnel.conversionRate = Math.min(100, Math.max(0, Math.round((funnel.conversionRate || 50) * persona.conversionModifier)));
+		funnel.conversionRate = saturateConversionRate(context, funnel,
+			Math.round((funnel.conversionRate || 50) * persona.conversionModifier), `persona "${persona.name}" conversionModifier`, 0);
+	}
+	// v1.7.0 (P1-3): persona time-to-convert multiplier. Composes after the
+	// experiment ttcMultiplier, before the funnel-pre hook (hook keeps final say).
+	if (persona && Number.isFinite(persona.ttcModifier) && persona.ttcModifier !== 1) {
+		funnel.timeToConvert = Math.max(0.1, (funnel.timeToConvert || 1) * persona.ttcModifier);
 	}
 	const resolvedWorldEvents = /** @type {import('../../types').ResolvedWorldEvent[]} */ (config.worldEvents);
 	if (resolvedWorldEvents && firstEventTime) {
@@ -122,7 +134,8 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 				const seq = funnel.sequence || [];
 				const affects = we.affectsEvents;
 				if (affects === "*" || (Array.isArray(affects) && seq.some(s => affects.includes(s)))) {
-					funnel.conversionRate = Math.min(100, Math.max(0, Math.round((funnel.conversionRate || 50) * we.conversionModifier)));
+					funnel.conversionRate = saturateConversionRate(context, funnel,
+						Math.round((funnel.conversionRate || 50) * we.conversionModifier), `worldEvent "${we.name}" conversionModifier`, 0);
 				}
 			}
 		}
@@ -144,6 +157,16 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		experiment: experimentMeta,
 	});
 
+	// v1.7.0 (P2-4): a funnel-pre hook that leaves conversionRate above 100 is
+	// clamped downstream (processEventRepeats) — record the saturation so the
+	// author learns the asked-for lift did not land. The engine can only see its
+	// own clamp: a hook's own `Math.min(95, rate * 3)` never reaches here.
+	// Record only — the value itself is left for processEventRepeats to clamp exactly
+	// as before, so pre-1.7 output is unchanged.
+	if (Number.isFinite(funnel.conversionRate) && funnel.conversionRate > 100) {
+		saturateConversionRate(context, funnel, funnel.conversionRate, 'funnel-pre hook', 0);
+	}
+
 	// Extract funnel configuration (post-hook — hook's mutations are the final word)
 	let {
 		sequence,
@@ -160,18 +183,21 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	const { distinct_id, created, anonymousIds = [] } = user;
 	const { superProps = {}, groupKeys = [] } = config;
 
+	// v1.7.0 (P1-1): value context for funnel-level and step-level property thunks.
+	const valueCtx = { profile, config, time: Number.isFinite(firstEventTime) ? firstEventTime * 1000 : undefined };
+
 	// Choose properties for this funnel instance
 	const chosenFunnelProps = { ...props, ...superProps };
 	for (const key in props) {
 		try {
-			chosenFunnelProps[key] = u.choose(chosenFunnelProps[key]);
+			chosenFunnelProps[key] = u.choose(chosenFunnelProps[key], valueCtx);
 		} catch (e) {
 			logger.error({ err: e, key, funnel: funnel.sequence.join(" > ") }, `Error processing property ${key} in funnel`);
 		}
 	}
 
 	// Build event specifications for funnel steps
-	const funnelPossibleEvents = buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, expName, expVariant);
+	const funnelPossibleEvents = buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, expName, expVariant, valueCtx);
 
 	// Handle repeat logic and conversion rate adjustment
 	let { processedEvents, adjustedConversionRate } = processEventRepeats(
@@ -298,6 +324,9 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		persona: featureCtx.persona || persona || null,
 		userCampaign: featureCtx.userCampaign || null,
 		userLocation: featureCtx.userLocation || null,
+		// v1.7.0: value context + sticky event props flow through to makeEvent.
+		profile: featureCtx.profile || profile || null,
+		stickyValues: featureCtx.stickyValues || null,
 		worldEventsTimeline: featureCtx.worldEventsTimeline || context.config.worldEvents || null,
 		dataQuality: featureCtx.dataQuality || context.config.dataQuality || null,
 		latestTime: Number.isFinite(featureCtx.latestTime) ? featureCtx.latestTime : undefined,
@@ -399,7 +428,7 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 				// Resolve declared props on the exclusion event's config.
 				if (excConfig && excConfig.properties) {
 					for (const k of Object.keys(excConfig.properties)) {
-						try { cloned[k] = u.choose(excConfig.properties[k]); }
+						try { cloned[k] = u.choose(excConfig.properties[k], { ...valueCtx, event: cloned, time: Date.parse(cloned.time) }); }
 						catch (e) { cloned[k] = null; }
 					}
 				}
@@ -429,6 +458,33 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	return [finalEvents, doesUserConvert, authTimeMs];
 }
 
+/**
+ * v1.7.0 (P2-4): clamp a modified conversionRate into `[floor, 100]` and, when the
+ * requested value exceeded 100, record ONE aggregated warning per funnel+source on
+ * the context (never per user — this runs in the hot loop).
+ *
+ * @param {Context} context
+ * @param {Object} funnel
+ * @param {number} requested - pre-clamp rate
+ * @param {string} source - what produced the rate (persona / experiment / world event / hook)
+ * @param {number} floor - lower bound (experiments floor at 1, others at 0)
+ * @returns {number} clamped rate
+ */
+function saturateConversionRate(context, funnel, requested, source, floor) {
+	const applied = Math.min(100, Math.max(floor, requested));
+	if (requested > 100 && context && typeof context.addWarning === 'function') {
+		const label = funnel.name || (Array.isArray(funnel.sequence) ? funnel.sequence.filter(s => s !== '$experiment_started').join(' > ') : '?');
+		context.addWarning({
+			key: `funnels[${label}].conversionRate:${source}`,
+			requested,
+			applied: 100,
+			reason: `${source} pushed conversionRate above 100; saturated at 100, so the intended lift did not fully land. Lower the base conversionRate or the multiplier.`,
+			severity: 'clamp',
+		});
+	}
+	return applied;
+}
+
 /**
  * Builds event specifications for funnel steps
  * @param {Context} context - Context object
@@ -437,9 +493,10 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
  * @param {number} bindPropsIndex - Index at which to bind properties (if applicable)
  * @param {string} [experimentName] - Name of experiment (if experiment is enabled)
  * @param {string} [experimentVariant] - Variant name (A, B, or C)
+ * @param {Object} [valueCtx] - v1.7.0 value context for property thunks
  * @returns {Array} Array of event specifications
  */
-function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, experimentName, experimentVariant) {
+function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex, experimentName, experimentVariant, valueCtx = undefined) {
 	const { config } = context;
 
 	return sequence.map((eventName, currentIndex) => {
@@ -463,10 +520,14 @@ function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex,
 			properties: { ...foundEvent.properties }
 		} : { event: eventName, properties: {} };
 
-		// Process event properties
+		// Process event properties.
+		// v1.7.0 (P1-1): context-aware thunks (`(ctx) => …`) are DEFERRED — left in
+		// place so makeEvent resolves them per step with the real `ctx.event` and
+		// `ctx.time`. Everything else resolves here exactly as before.
 		for (const key in eventSpec.properties) {
+			if (u.isContextAware(eventSpec.properties[key])) continue;
 			try {
-				eventSpec.properties[key] = u.choose(eventSpec.properties[key]);
+				eventSpec.properties[key] = u.choose(eventSpec.properties[key], valueCtx);
 			} catch (e) {
 				logger.error({ err: e, key, event: eventSpec.event }, `Error processing property ${key} in ${eventSpec.event} event`);
 			}
@@ -636,9 +697,22 @@ async function generateFunnelEvents(
 	const stampingByIndex = (identityArgs && identityArgs.stampingByIndex) || null;
 	const devicePool = (identityArgs && identityArgs.devicePool) || null;
 
+	// v1.7.0: step 0 reports its TimeSoup time through a synchronous side channel.
+	// Each map callback runs synchronously up to makeEvent's first `await` (the
+	// event hook), which is AFTER the time is set — so by the time callback i>0
+	// starts, `funnelStartMs` is known and the step's final time can be pinned
+	// before its properties resolve. RNG order is unchanged.
+	let funnelStartMs = null;
+
 	const finalEvents = await Promise.all(eventsWithTiming.map(async (event, index) => {
 		const stamping = stampingByIndex ? stampingByIndex[index] : 'both';
 		const identityCtx = (devicePool || stamping !== 'both') ? { stamping, devicePool } : null;
+		let stepFeatureCtx = featureCtx;
+		if (index === 0) {
+			stepFeatureCtx = { ...featureCtx, onTimeResolved: (ms) => { funnelStartMs = ms; } };
+		} else if (funnelStartMs !== null && Number.isFinite(event.relativeTimeMs)) {
+			stepFeatureCtx = { ...featureCtx, fixedTimeMs: funnelStartMs + event.relativeTimeMs };
+		}
 		const newEvent = await makeEvent(
 			context,
 			distinct_id,
@@ -649,7 +723,7 @@ async function generateFunnelEvents(
 			groupKeys,
 			false,
 			false,
-			featureCtx,
+			stepFeatureCtx,
 			identityCtx
 		);
 

package/lib/generators/profiles.js

@@ -18,19 +18,24 @@ import { dataLogger as logger } from "../utils/logger.js";
 export async function makeProfile(context, props = {}, defaults = {}) {
     // Update operation counter
     context.incrementOperations();
-    
+
     // Keys that should not be processed with the choose function
     const keysToNotChoose = ["anonymousIds", "sessionIds"];
 
     // Start with defaults
     const profile = { ...defaults };
 
+    // v1.7.0 (P1-1): value functions see the profile as it is being built.
+    // Keys resolve in insertion order, so a later key can read an earlier one
+    // (`revenue: (ctx) => ctx.profile.plan === 'pro' ? 100 : 10`).
+    const valueCtx = { profile, config: context.config };
+
     // Process default values first
     for (const key in profile) {
         if (keysToNotChoose.includes(key)) continue;
-        
+
         try {
-            profile[key] = u.choose(profile[key]);
+            profile[key] = u.choose(profile[key], valueCtx);
         } catch (e) {
             logger.error({ err: e, key }, `Error processing default property ${key}`);
             // Keep original value on error
@@ -40,7 +45,7 @@ export async function makeProfile(context, props = {}, defaults = {}) {
     // Process provided props (these override defaults)
     for (const key in props) {
         try {
-            profile[key] = u.choose(props[key]);
+            profile[key] = u.choose(props[key], valueCtx);
         } catch (e) {
             logger.error({ err: e, key }, `Error processing property ${key}`);
             // Keep original value on error

package/lib/generators/standalone.js

@@ -0,0 +1,248 @@
+/**
+ * Standalone event generator module (v1.8.0)
+ *
+ * Standalone events are IDENTITY-LESS metric snapshots. They carry no `user_id`
+ * and no `device_id` — they describe a system, not a person. Think daily CDN
+ * egress per region, weekly billing rollups per plan tier, hourly queue depth
+ * per cluster. `$ad_spend` is the same idea, hard-coded; this is the general form.
+ *
+ * One record is emitted per cadence tick per dimension cross-product row:
+ *
+ *   cadence: 'day', dimensions: { region: ['us','eu'], tier: ['a','b'] }
+ *   → 4 records per day (us/a, us/b, eu/a, eu/b)
+ *
+ * `distinct_id` is synthetic. It is the value of the dimension named by
+ * `distinctIdFrom`, or the event name when no dimension is named. It exists only
+ * so Mixpanel accepts the record; it never maps to a person.
+ */
+
+/** @typedef {import('../../types').Context} Context */
+/** @typedef {import('../../types').StandaloneEventConfig} StandaloneEventConfig */
+/** @typedef {import('../../types').ResolvedStandaloneEventConfig} ResolvedStandaloneEventConfig */
+
+import { randomUUID } from "node:crypto";
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+import * as u from "../utils/utils.js";
+
+dayjs.extend(utc);
+
+/** Seconds per cadence tick. */
+const CADENCE_SECONDS = {
+	hour: 60 * 60,
+	day: 24 * 60 * 60,
+	week: 7 * 24 * 60 * 60,
+};
+
+/** Cadence names the validator accepts. */
+export const VALID_CADENCES = Object.freeze(Object.keys(CADENCE_SECONDS));
+
+/**
+ * Expands a `dimensions` map into every combination of its values.
+ * `{ a: [1,2], b: ['x'] }` → `[{a:1,b:'x'}, {a:2,b:'x'}]`.
+ * An empty/absent map yields a single empty row, so an undimensioned
+ * standalone event emits exactly one record per tick.
+ *
+ * @param {Record<string, any[]>} dimensions
+ * @returns {Record<string, any>[]}
+ */
+export function expandDimensions(dimensions) {
+	const keys = Object.keys(dimensions || {});
+	if (keys.length === 0) return [{}];
+
+	let rows = [{}];
+	for (const key of keys) {
+		const values = dimensions[key];
+		/** @type {Record<string, any>[]} */
+		const next = [];
+		for (const row of rows) {
+			for (const value of values) {
+				next.push({ ...row, [key]: value });
+			}
+		}
+		rows = next;
+	}
+	return rows;
+}
+
+/**
+ * Every tick timestamp for one standalone event across the dataset window.
+ *
+ * Ticks start at `datasetStart` and step by the cadence. The final tick is the
+ * last one that lands at or before `datasetEnd` — a standalone event never
+ * emits a record in the future, matching the engine-wide future-time guard.
+ *
+ * @param {number} datasetStart - unix seconds
+ * @param {number} datasetEnd - unix seconds
+ * @param {'hour'|'day'|'week'} cadence
+ * @returns {number[]} unix seconds, ascending
+ */
+export function buildTicks(datasetStart, datasetEnd, cadence) {
+	const step = CADENCE_SECONDS[cadence];
+	if (!step) throw new Error(`unknown cadence: ${cadence}`);
+
+	/** @type {number[]} */
+	const ticks = [];
+	for (let t = datasetStart; t <= datasetEnd; t += step) {
+		ticks.push(t);
+	}
+	return ticks;
+}
+
+/**
+ * Builds every record for a single standalone event config.
+ *
+ * @param {Context} context
+ * @param {ResolvedStandaloneEventConfig} spec
+ * @returns {Record<string, any>[]}
+ */
+export function makeStandaloneEvents(context, spec) {
+	const { config } = context;
+	const datasetStart = context.FIXED_BEGIN;
+	const datasetEnd = context.FIXED_NOW;
+
+	const ticks = buildTicks(datasetStart, datasetEnd, spec.cadence);
+	const rows = expandDimensions(spec.dimensions);
+	const propKeys = Object.keys(spec.properties);
+
+	/** @type {Record<string, any>[]} */
+	const records = [];
+
+	for (let tickIndex = 0; tickIndex < ticks.length; tickIndex++) {
+		const tickUnix = ticks[tickIndex];
+		const isoTime = dayjs.unix(tickUnix).utc().toISOString();
+
+		for (const dimensions of rows) {
+			context.incrementOperations();
+
+			// distinct_id is synthetic: the named dimension's value, else the
+			// event name. Never a person. Stable across the run so the record
+			// series groups cleanly in Mixpanel.
+			const distinctId = spec.distinctIdFrom
+				? String(dimensions[spec.distinctIdFrom])
+				: spec.event;
+
+			/** @type {Record<string, any>} */
+			const record = {
+				event: spec.event,
+				time: isoTime,
+				insert_id: randomUUID(),
+				distinct_id: distinctId,
+				...dimensions,
+			};
+
+			// The context handed to every property function. Shares the
+			// ValueContext members (`time`, `config`) so a function written for
+			// a normal event property still works here, plus the standalone-only
+			// members a snapshot needs to shape a trend.
+			const valueContext = {
+				time: tickUnix * 1000,
+				config,
+				dimensions,
+				tickIndex,
+				tickCount: ticks.length,
+				cadence: spec.cadence,
+				event: record,
+			};
+
+			for (const key of propKeys) {
+				record[key] = u.choose(spec.properties[key], valueContext);
+			}
+
+			records.push(record);
+		}
+	}
+
+	return records;
+}
+
+/**
+ * Validates and normalizes the `standaloneEvents` config array.
+ * Throws on anything malformed — a silent skip would hide a whole data stream.
+ *
+ * @param {unknown} standaloneEvents
+ * @returns {ResolvedStandaloneEventConfig[]}
+ */
+export function validateStandaloneEvents(standaloneEvents) {
+	if (standaloneEvents === undefined || standaloneEvents === null) return [];
+	if (!Array.isArray(standaloneEvents)) {
+		throw new Error("standaloneEvents must be an array");
+	}
+
+	const seen = new Set();
+
+	return standaloneEvents.map((spec, index) => {
+		const label = `standaloneEvents[${index}]`;
+
+		if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+			throw new Error(`${label} must be an object`);
+		}
+		if (typeof spec.event !== "string" || !spec.event.trim()) {
+			throw new Error(`${label}.event must be a non-empty string`);
+		}
+		if (seen.has(spec.event)) {
+			throw new Error(`${label}.event "${spec.event}" is declared more than once`);
+		}
+		seen.add(spec.event);
+
+		const cadence = spec.cadence || "day";
+		if (!CADENCE_SECONDS[cadence]) {
+			throw new Error(
+				`${label}.cadence must be one of ${VALID_CADENCES.join(", ")} (got "${cadence}")`
+			);
+		}
+
+		/** @type {Record<string, any[]>} */
+		const dimensions = {};
+		if (spec.dimensions !== undefined && spec.dimensions !== null) {
+			if (typeof spec.dimensions !== "object" || Array.isArray(spec.dimensions)) {
+				throw new Error(`${label}.dimensions must be an object of arrays`);
+			}
+			for (const [key, values] of Object.entries(spec.dimensions)) {
+				if (!Array.isArray(values) || values.length === 0) {
+					throw new Error(`${label}.dimensions.${key} must be a non-empty array`);
+				}
+				dimensions[key] = values;
+			}
+		}
+
+		if (spec.distinctIdFrom !== undefined && spec.distinctIdFrom !== null) {
+			if (typeof spec.distinctIdFrom !== "string") {
+				throw new Error(`${label}.distinctIdFrom must be a string`);
+			}
+			if (!(spec.distinctIdFrom in dimensions)) {
+				throw new Error(
+					`${label}.distinctIdFrom "${spec.distinctIdFrom}" is not a declared dimension`
+				);
+			}
+		}
+
+		if (spec.properties !== undefined && spec.properties !== null) {
+			if (typeof spec.properties !== "object" || Array.isArray(spec.properties)) {
+				throw new Error(`${label}.properties must be an object`);
+			}
+		}
+
+		// Schema-first: a property key must not collide with a dimension key or
+		// with a reserved record key. A collision would silently overwrite one
+		// of them and the author would never see it.
+		const properties = spec.properties || {};
+		const reserved = new Set(["event", "time", "insert_id", "distinct_id", "user_id", "device_id"]);
+		for (const key of Object.keys(properties)) {
+			if (reserved.has(key)) {
+				throw new Error(`${label}.properties.${key} collides with a reserved record key`);
+			}
+			if (key in dimensions) {
+				throw new Error(`${label}.properties.${key} collides with a dimension of the same name`);
+			}
+		}
+
+		return {
+			event: spec.event,
+			cadence,
+			dimensions,
+			distinctIdFrom: spec.distinctIdFrom || null,
+			properties,
+		};
+	});
+}