@ak--47/dungeon-master 1.3.0 → 1.4.0

package/lib/core/config-validator.js

@@ -14,8 +14,80 @@ import * as u from "../utils/utils.js";
 import { resolveSoup } from "../templates/soup-presets.js";
 import { resolveMacro } from "../templates/macro-presets.js";
 
-/** Fixed reference point for time calculations (2024-02-02) */
-const FIXED_NOW = dayjs('2024-02-02').unix();
+/**
+ * Resolve dataset window from config. Returns { datasetStartUnix, datasetEndUnix, numDays }.
+ * Three modes:
+ *   1. Both `datasetStart` AND `datasetEnd` provided → pin window. Recompute numDays from the
+ *      window (ignore any user-supplied numDays — warn on conflict). Bit-exact deterministic.
+ *   2. Neither provided → fall back to (today_start - numDays, today_start). Deterministic
+ *      within a single calendar day; slides across days. Warn once.
+ *   3. Exactly one provided → throw.
+ *
+ * Accepts ISO strings, unix seconds, or anything dayjs() can parse.
+ *
+ * @param {*} datasetStart
+ * @param {*} datasetEnd
+ * @param {number} [userNumDays]
+ * @returns {{ datasetStartUnix: number, datasetEndUnix: number, numDays: number }}
+ */
+function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays) {
+	const hasStart = datasetStart !== undefined && datasetStart !== null;
+	const hasEnd = datasetEnd !== undefined && datasetEnd !== null;
+
+	if (hasStart !== hasEnd) {
+		throw new Error(
+			`datasetStart and datasetEnd must be specified together (got datasetStart=${datasetStart}, datasetEnd=${datasetEnd}). ` +
+			`Provide both to pin the window, or neither to fall back to numDays.`
+		);
+	}
+
+	if (hasStart && hasEnd) {
+		const startUnix = parseToUnix(datasetStart, 'datasetStart');
+		const endUnix = parseToUnix(datasetEnd, 'datasetEnd');
+		if (endUnix <= startUnix) {
+			throw new Error(`datasetEnd (${datasetEnd}) must be after datasetStart (${datasetStart}).`);
+		}
+		const derivedNumDays = Math.max(1, Math.round((endUnix - startUnix) / 86400));
+		if (userNumDays !== undefined && userNumDays !== null && userNumDays !== derivedNumDays) {
+			console.warn(
+				`⚠️  datasetStart/datasetEnd take precedence; user-supplied numDays=${userNumDays} ignored, derived numDays=${derivedNumDays}.`
+			);
+		}
+		return { datasetStartUnix: startUnix, datasetEndUnix: endUnix, numDays: derivedNumDays };
+	}
+
+	// Fallback: anchor to today's start-of-day, walk back numDays
+	const fallbackNumDays = (typeof userNumDays === 'number' && userNumDays > 0) ? userNumDays : 30;
+	const todayStart = dayjs().startOf('day').unix();
+	const fallbackStart = todayStart - fallbackNumDays * 86400;
+	console.warn(
+		`⚠️  No 'datasetStart'/'datasetEnd' set — dataset window anchored to today's date and will shift across runs. Pin both for full determinism.`
+	);
+	return { datasetStartUnix: fallbackStart, datasetEndUnix: todayStart, numDays: fallbackNumDays };
+}
+
+/**
+ * Parse a value (ISO string, unix seconds, dayjs-parseable) into unix seconds.
+ * Throws if the value can't be parsed into a valid date.
+ * @param {*} value
+ * @param {string} fieldName
+ * @returns {number}
+ */
+function parseToUnix(value, fieldName) {
+	// Treat numbers as unix seconds (or unix milliseconds if too large)
+	if (typeof value === 'number') {
+		if (!Number.isFinite(value) || value <= 0) {
+			throw new Error(`${fieldName} must be a positive finite number (got ${value}).`);
+		}
+		// Heuristic: > 10^12 means milliseconds, otherwise seconds
+		return value > 1e12 ? Math.floor(value / 1000) : Math.floor(value);
+	}
+	const parsed = dayjs(value);
+	if (!parsed.isValid()) {
+		throw new Error(`${fieldName} could not be parsed as a date (got ${JSON.stringify(value)}).`);
+	}
+	return parsed.unix();
+}
 
 /**
  * Infers funnels from the provided events
@@ -73,6 +145,106 @@ function inferFunnels(events) {
 	return createdFunnels;
 }
 
+/**
+ * Config keys removed from the engine in 1.4. Silently stripped by
+ * `validateDungeonConfig` with a single warning per dungeon. To recreate any of these
+ * patterns, use hooks (see `lib/hook-patterns/*`).
+ */
+const KILLED_CONFIG_KEYS = ['subscription', 'attribution', 'geo', 'features', 'anomalies'];
+
+/**
+ * Strip killed config keys in place, log one deprecation warning per dungeon.
+ * @param {Partial<Dungeon>} config
+ */
+function stripKilledConfigKeys(config) {
+	const found = KILLED_CONFIG_KEYS.filter(k => config[k] !== undefined && config[k] !== null);
+	if (!found.length) return;
+	for (const k of found) delete config[k];
+	if (config.verbose !== false) {
+		console.warn(
+			`⚠️  dungeon-master 1.4 removed engine support for: ${found.join(', ')}. ` +
+			`These config keys are silently ignored. Recreate via hooks (see lib/hook-patterns/* once Phase 4 lands).`
+		);
+	}
+}
+
+/**
+ * Validate `Funnel.attempts` config in place. Coerces missing/invalid bounds so callers
+ * downstream don't have to re-defend. Throws on logically invalid configs (max < min).
+ * @param {import('../../types.js').Funnel[]} funnels
+ */
+function validateAttempts(funnels) {
+	for (const f of funnels) {
+		if (!f || !f.attempts) continue;
+		const a = f.attempts;
+		const min = Number.isFinite(a.min) ? Math.max(0, Math.floor(a.min)) : 0;
+		const max = Number.isFinite(a.max) ? Math.max(0, Math.floor(a.max)) : min;
+		if (max < min) {
+			throw new Error(`Funnel "${f.name || f.sequence?.join(' > ')}" attempts.max (${a.max}) must be >= attempts.min (${a.min})`);
+		}
+		a.min = min;
+		a.max = max;
+		if (a.conversionRate !== undefined) {
+			if (!Number.isFinite(a.conversionRate)) {
+				throw new Error(`Funnel "${f.name || f.sequence?.join(' > ')}" attempts.conversionRate must be a finite number 0-100`);
+			}
+			a.conversionRate = Math.max(0, Math.min(100, a.conversionRate));
+		}
+	}
+}
+
+/**
+ * Normalize `Funnel.experiment` in place. `true` → default 3-variant config.
+ * Object → validated and resolved. Stores `funnel._experiment` for downstream.
+ * @param {import('../../types.js').Funnel[]} funnels
+ * @param {number} datasetEndUnix
+ */
+function normalizeExperiments(funnels, datasetEndUnix) {
+	const DEFAULT_VARIANTS = [
+		{ name: 'Variant A', conversionMultiplier: 0.7, ttcMultiplier: 1.5, weight: 1 },
+		{ name: 'Variant B', conversionMultiplier: 1.3, ttcMultiplier: 0.7, weight: 1 },
+		{ name: 'Control', conversionMultiplier: 1.0, ttcMultiplier: 1.0, weight: 1 },
+	];
+	for (const f of funnels) {
+		if (!f || !f.experiment) continue;
+		const raw = f.experiment === true ? {} : f.experiment;
+		const name = raw.name || (f.name ? f.name + ' Experiment' : 'Unnamed Experiment');
+		const variants = (raw.variants && raw.variants.length)
+			? raw.variants.map(v => ({
+				name: v.name || 'Unnamed Variant',
+				conversionMultiplier: Number.isFinite(v.conversionMultiplier) ? Math.max(0.01, v.conversionMultiplier) : 1.0,
+				ttcMultiplier: Number.isFinite(v.ttcMultiplier) ? Math.max(0.01, v.ttcMultiplier) : 1.0,
+				weight: Number.isFinite(v.weight) && v.weight > 0 ? v.weight : 1,
+			}))
+			: DEFAULT_VARIANTS;
+		const startDays = Number.isFinite(raw.startDaysBeforeEnd) && raw.startDaysBeforeEnd > 0
+			? raw.startDaysBeforeEnd : 0;
+		const startUnix = startDays > 0 ? datasetEndUnix - startDays * 86400 : null;
+		f._experiment = { name, variants, startUnix };
+	}
+}
+
+/**
+ * Resolve `avgDevicePerUser` per Section 3.3 rules. Returns the integer device count
+ * the engine should use (0 = no device_id stamping at all, 1+ = pool size).
+ *
+ * @param {Partial<Dungeon>} config
+ * @returns {number}
+ */
+function resolveDevicesPerUser(config) {
+	const raw = config.avgDevicePerUser;
+	const hasAnon = config.hasAnonIds === true;
+	if (raw === undefined || raw === null) {
+		return hasAnon ? 1 : 0;
+	}
+	if (!Number.isFinite(raw)) {
+		return hasAnon ? 1 : 0;
+	}
+	const n = Math.round(raw);
+	if (n <= 0) return hasAnon ? 1 : 0;
+	return n;
+}
+
 /**
  * Validates and enriches a dungeon configuration object
  * @param {Partial<Dungeon>} config - Raw configuration object
@@ -81,6 +253,9 @@ function inferFunnels(events) {
 export function validateDungeonConfig(config) {
 	const chance = u.getChance();
 
+	// Phase 1 — strip killed config keys before anything else reads them.
+	stripKilledConfigKeys(config);
+
 	// Transform SCD props to regular props if credentials are missing
 	// This MUST happen BEFORE we extract values from the config
 	transformSCDPropsWithoutCredentials(config);
@@ -168,18 +343,18 @@ export function validateDungeonConfig(config) {
 		throw new Error(`numDays must be a positive number (got ${config.numDays})`);
 	}
 
-	// Setting up "TIME"
-	if (epochStart && !numDays) numDays = dayjs.unix(epochEnd).diff(dayjs.unix(epochStart), "day");
-	if (!epochStart && numDays) epochStart = dayjs.unix(epochEnd).subtract(numDays, "day").unix();
-	if (epochStart && numDays) { } // noop
-	if (!epochStart && !numDays) {
-		throw new Error("Either epochStart or numDays must be provided");
-	}
+	// ── Resolve dataset window ──
+	// Preferred path: explicit datasetStart + datasetEnd → pinned, deterministic window.
+	// Fallback: numDays only → today_start - numDays back (sliding, warn-emitted).
+	const windowResolution = resolveDatasetWindow(config.datasetStart, config.datasetEnd, config.numDays);
+	const datasetStartUnix = windowResolution.datasetStartUnix;
+	const datasetEndUnix = windowResolution.datasetEndUnix;
+	numDays = windowResolution.numDays;
 
-	// Final sanity check (e.g. epochStart/epochEnd produced a non-positive numDays).
-	if (!Number.isFinite(numDays) || numDays <= 0) {
-		throw new Error(`numDays must be a positive number (got ${numDays})`);
-	}
+	// Mirror window into legacy epoch* surface (still consumed by inferFunnels callers
+	// and any external code that read these from validated config).
+	epochStart = datasetStartUnix;
+	epochEnd = datasetEndUnix;
 
 	// Resolve event-rate primitive: avgEventsPerUserPerDay is the canonical knob.
 	// numEvents is supported as a fallback (legacy + total-volume target). Whichever
@@ -349,7 +524,7 @@ export function validateDungeonConfig(config) {
 	// Feature 2: World Events
 	let worldEvents = config.worldEvents || null;
 	if (worldEvents) {
-		worldEvents = resolveWorldEvents(worldEvents, numDays);
+		worldEvents = resolveWorldEvents(worldEvents, datasetStartUnix);
 	}
 
 	// Feature 3: Engagement Decay
@@ -364,35 +539,31 @@ export function validateDungeonConfig(config) {
 		dataQuality = validateDataQuality(dataQuality);
 	}
 
-	// Feature 5: Subscription
-	let subscription = config.subscription || null;
-	if (subscription) {
-		subscription = validateSubscription(subscription);
-	}
+	// Phase 1: validate Funnel.attempts on every funnel (additive — most have none).
+	validateAttempts(funnels);
 
-	// Feature 6: Attribution
-	let attribution = config.attribution || null;
-	if (attribution) {
-		attribution = validateAttribution(attribution, numDays);
-	}
+	// Normalize experiment configs: true → default 3-variant, object → validated.
+	normalizeExperiments(funnels, datasetEndUnix);
 
-	// Feature 7: Geo
-	let geo = config.geo || null;
-	if (geo) {
-		geo = validateGeo(geo);
-	}
+	// Phase 1: resolve multi-device config. `avgDevicePerUser` is the canonical knob;
+	// `hasAnonIds: true` aliases to 1. Default 0 = no device_id stamping (legacy).
+	const avgDevicePerUser = resolveDevicesPerUser(config);
+	// Keep hasAnonIds in sync — downstream code (utils.generateUser) still reads it.
+	// Setting it true here when avgDevicePerUser >= 1 lets the legacy device-pool
+	// generation in `person()` continue to allocate `anonymousIds[]` for the user.
+	const hasAnonIdsResolved = avgDevicePerUser >= 1;
 
-	// Feature 8: Features (progressive adoption)
-	let features = config.features || null;
-	if (features) {
-		features = resolveFeatures(features, numDays);
+	// Warn if isAuthEvent is set but avgDevicePerUser=0 — pre-auth device_only
+	// stamping degrades to user_id via the floor guard, defeating the identity model.
+	if (avgDevicePerUser === 0 && validatedEvents.some(e => e.isAuthEvent)) {
+		console.warn(
+			`⚠️  isAuthEvent requires avgDevicePerUser >= 1 to produce pre-auth anonymous events. ` +
+			`Set avgDevicePerUser or hasAnonIds: true.`
+		);
 	}
 
-	// Feature 9: Anomalies
-	let anomalies = config.anomalies || null;
-	if (anomalies) {
-		anomalies = resolveAnomalies(anomalies, numDays);
-	}
+	// Precompute whether any event has isAttributionEvent for UTM stamping logic.
+	const hasAttributionFlags = validatedEvents.some(e => e.isAttributionEvent);
 
 	// Build final config object
 	const validatedConfig = {
@@ -407,6 +578,8 @@ export function validateDungeonConfig(config) {
 		avgEventsPerUserPerDay,
 		epochStart,
 		epochEnd,
+		datasetStart: datasetStartUnix,
+		datasetEnd: datasetEndUnix,
 		events: validatedEvents,
 		superProps,
 		userProps,
@@ -415,7 +588,8 @@ export function validateDungeonConfig(config) {
 		groupKeys,
 		groupProps,
 		lookupTables,
-		hasAnonIds,
+		hasAnonIds: hasAnonIdsResolved,
+		avgDevicePerUser,
 		hasSessionIds,
 		sessionTimeout: (typeof sessionTimeout === 'number' && sessionTimeout > 0) ? sessionTimeout : 30,
 		format,
@@ -427,6 +601,7 @@ export function validateDungeonConfig(config) {
 		hook,
 		hasAdSpend,
 		hasCampaigns,
+		hasAttributionFlags,
 		hasLocation,
 		hasAvatar,
 		isAnonymous,
@@ -441,16 +616,17 @@ export function validateDungeonConfig(config) {
 		bornRecentBias,
 		percentUsersBornInDataset,
 		preExistingSpread,
-		// Advanced features
+		// Advanced features (kept after 1.4)
 		personas,
 		worldEvents,
 		engagementDecay,
 		dataQuality,
-		subscription,
-		attribution,
-		geo,
-		features,
-		anomalies
+		// Killed in 1.4 — set to null so hooks/external code that reads these get a falsy value.
+		subscription: null,
+		attribution: null,
+		geo: null,
+		features: null,
+		anomalies: null
 	};
 
 	return validatedConfig;
@@ -551,12 +727,11 @@ function validatePersonas(personas) {
 /**
  * Resolves world events to absolute timestamps
  * @param {import('../../types').WorldEvent[]} worldEvents
- * @param {number} numDays
+ * @param {number} beginUnix - Dataset start (unix seconds)
  * @returns {import('../../types').ResolvedWorldEvent[]}
  */
-function resolveWorldEvents(worldEvents, numDays) {
+function resolveWorldEvents(worldEvents, beginUnix) {
 	if (!Array.isArray(worldEvents) || worldEvents.length === 0) return null;
-	const beginUnix = dayjs.unix(FIXED_NOW).subtract(numDays, 'day').unix();
 
 	return worldEvents.map(we => {
 		const startUnix = beginUnix + (we.startDay * 86400);
@@ -616,132 +791,8 @@ function validateDataQuality(dq) {
 	return dq;
 }
 
-/**
- * Validates subscription config
- * @param {import('../../types').Subscription} sub
- * @returns {import('../../types').Subscription}
- */
-function validateSubscription(sub) {
-	if (!sub.plans || !Array.isArray(sub.plans) || sub.plans.length === 0) {
-		throw new Error('subscription.plans must be a non-empty array');
-	}
-	const hasDefault = sub.plans.some(p => p.default);
-	if (!hasDefault) sub.plans[0].default = true;
-	if (!sub.lifecycle) sub.lifecycle = {};
-	const lc = sub.lifecycle;
-	if (lc.trialToPayRate === undefined) lc.trialToPayRate = 0.3;
-	if (lc.upgradeRate === undefined) lc.upgradeRate = 0.1;
-	if (lc.downgradeRate === undefined) lc.downgradeRate = 0.03;
-	if (lc.churnRate === undefined) lc.churnRate = 0.05;
-	if (lc.winBackRate === undefined) lc.winBackRate = 0.1;
-	if (lc.winBackDelay === undefined) lc.winBackDelay = 30;
-	if (lc.paymentFailureRate === undefined) lc.paymentFailureRate = 0.02;
-	if (!sub.events) sub.events = {};
-	const ev = sub.events;
-	if (!ev.trialStarted) ev.trialStarted = "trial started";
-	if (!ev.subscribed) ev.subscribed = "subscription started";
-	if (!ev.upgraded) ev.upgraded = "plan upgraded";
-	if (!ev.downgraded) ev.downgraded = "plan downgraded";
-	if (!ev.renewed) ev.renewed = "subscription renewed";
-	if (!ev.cancelled) ev.cancelled = "subscription cancelled";
-	if (!ev.paymentFailed) ev.paymentFailed = "payment failed";
-	if (!ev.wonBack) ev.wonBack = "subscription reactivated";
-	return sub;
-}
-
-/**
- * Validates attribution config
- * @param {import('../../types').Attribution} attr
- * @param {number} numDays
- * @returns {import('../../types').Attribution}
- */
-function validateAttribution(attr, numDays) {
-	if (!attr.campaigns || !Array.isArray(attr.campaigns)) {
-		throw new Error('attribution.campaigns must be an array');
-	}
-	if (attr.model === undefined) attr.model = "last_touch";
-	if (attr.window === undefined) attr.window = 7;
-	if (attr.organicRate === undefined) attr.organicRate = 0.4;
-	for (const c of attr.campaigns) {
-		if (!c.name) throw new Error('Each attribution campaign must have a name');
-		if (!c.source) throw new Error(`Attribution campaign "${c.name}" must have a source`);
-		if (!c.activeDays) throw new Error(`Attribution campaign "${c.name}" must have activeDays [start, end]`);
-		if (!c.dailyBudget) c.dailyBudget = [50, 200];
-		if (c.acquisitionRate === undefined) c.acquisitionRate = 0.02;
-	}
-	return attr;
-}
-
-/**
- * Validates geo config
- * @param {import('../../types').GeoConfig} geo
- * @returns {import('../../types').GeoConfig}
- */
-function validateGeo(geo) {
-	if (geo.sticky === undefined) geo.sticky = false;
-	if (geo.regions && !Array.isArray(geo.regions)) throw new Error('geo.regions must be an array');
-	if (geo.regionalLaunches && !Array.isArray(geo.regionalLaunches)) throw new Error('geo.regionalLaunches must be an array');
-	return geo;
-}
-
-/**
- * Resolves feature configs with logistic curve parameters
- * @param {import('../../types').FeatureConfig[]} features
- * @param {number} numDays
- * @returns {import('../../types').FeatureConfig[]}
- */
-function resolveFeatures(features, numDays) {
-	if (!Array.isArray(features) || features.length === 0) return null;
-	const curvePresets = {
-		fast: { k: 0.3, midpoint: 7 },
-		slow: { k: 0.08, midpoint: 30 },
-		instant: { k: 10, midpoint: 0 }
-	};
-	return features.map(f => {
-		if (!f.name) throw new Error('Each feature must have a name');
-		if (f.launchDay === undefined) throw new Error(`Feature "${f.name}" must have a launchDay`);
-		if (!f.property) throw new Error(`Feature "${f.name}" must have a property`);
-		if (!f.values || !Array.isArray(f.values) || f.values.length === 0) {
-			throw new Error(`Feature "${f.name}" must have a non-empty values array`);
-		}
-		if (!f.affectsEvents) f.affectsEvents = "*";
-		if (!f.adoptionCurve) f.adoptionCurve = "slow";
-		if (typeof f.adoptionCurve === 'string') {
-			f._resolvedCurve = curvePresets[f.adoptionCurve] || curvePresets.slow;
-		} else {
-			f._resolvedCurve = f.adoptionCurve;
-		}
-		// Pre-compute adopted values to avoid array allocation in hot loop
-		f._adoptedValues = f.values.length > 1 ? f.values.slice(1) : f.values;
-		return f;
-	});
-}
-
-/**
- * Resolves anomaly configs with absolute timestamps
- * @param {import('../../types').AnomalyConfig[]} anomalies
- * @param {number} numDays
- * @returns {import('../../types').AnomalyConfig[]}
- */
-function resolveAnomalies(anomalies, numDays) {
-	if (!Array.isArray(anomalies) || anomalies.length === 0) return null;
-	const beginUnix = dayjs.unix(FIXED_NOW).subtract(numDays, 'day').unix();
-	return anomalies.map(a => {
-		if (!a.type) throw new Error('Each anomaly must have a type');
-		if (!a.event) throw new Error('Each anomaly must have an event name');
-		const resolved = { ...a };
-		if (a.day !== undefined) {
-			resolved._startUnix = beginUnix + (a.day * 86400);
-			if (a.duration) {
-				resolved._endUnix = resolved._startUnix + (a.duration * 86400);
-			} else if (a.window) {
-				resolved._endUnix = resolved._startUnix + (a.window * 86400);
-			} else {
-				resolved._endUnix = resolved._startUnix + 86400; // default 1 day
-			}
-		}
-		return resolved;
-	});
-}
+// validateSubscription / validateAttribution / validateGeo / resolveFeatures /
+// resolveAnomalies were removed in 1.4 along with their respective config keys.
+// `stripKilledConfigKeys` deletes the inputs before they reach the validator body.
 
 export { inferFunnels, transformSCDPropsWithoutCredentials };

package/lib/core/context.js

@@ -156,30 +156,16 @@ export function createContext(config, storage = null, timeConstants = {}) {
 			return runtime.isBatchMode;
 		},
 
-		// Time helper methods
-		getTimeShift() {
-			const actualNow = dayjs().subtract(1, "hour");
-			return actualNow.diff(dayjs.unix(this.FIXED_NOW), "seconds");
-		},
-
-		getDaysShift() {
-			const actualNow = dayjs().subtract(1, "hour");
-			return actualNow.diff(dayjs.unix(this.FIXED_NOW), "days");
-		},
-
-		// Time constants (passed explicitly from index.js; global fallback only for direct test usage)
-		FIXED_NOW: timeConstants.fixedNow || global.FIXED_NOW,
-		FIXED_BEGIN: timeConstants.fixedBegin || global.FIXED_BEGIN,
-
-		// PERFORMANCE: Pre-calculated time shift (instead of calculating per-event)
-		TIME_SHIFT_SECONDS: (() => {
-			const fixedNow = timeConstants.fixedNow || global.FIXED_NOW;
-			const actualNow = dayjs().subtract(1, "hour");
-			return actualNow.diff(dayjs.unix(fixedNow), "seconds");
-		})(),
-
-		// Max timestamp (unix seconds) — clamp here to prevent future events
-		MAX_TIME: dayjs().unix(),
+		// Dataset window anchors (resolved by config-validator). FIXED_BEGIN and
+		// FIXED_NOW are the authoritative window — events are generated directly
+		// inside this range, no time-shift step. DATASET_*_SECONDS are aliases
+		// kept for the existing `meta.datasetStart`/`meta.datasetEnd` hook surface.
+		// Resolution: explicit timeConstants override, otherwise pull from validated config.
+		// validateDungeonConfig always normalizes datasetStart/datasetEnd to unix seconds.
+		FIXED_NOW: /** @type {number} */ (timeConstants.fixedNow || config.datasetEnd),
+		FIXED_BEGIN: /** @type {number} */ (timeConstants.fixedBegin || config.datasetStart),
+		get DATASET_START_SECONDS() { return this.FIXED_BEGIN; },
+		get DATASET_END_SECONDS() { return this.FIXED_NOW; },
 	};
 
 	return context;

package/lib/core/storage.js

@@ -111,7 +111,12 @@ export async function createHookArray(arr = [], opts) {
 			}
 		} else {
 			// Slow path for actual transformation hooks
-			const allMetaData = { ...rest, ...meta };
+			const allMetaData = {
+				...rest,
+				...meta,
+				datasetStart: context?.DATASET_START_SECONDS,
+				datasetEnd: context?.DATASET_END_SECONDS
+			};
 
 			// Helper to validate events have required properties
 			// Note: event-type hooks are handled in the fast path (alreadyHooked),