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

package/lib/generators/funnels.js

@@ -331,6 +331,21 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		dataQuality: featureCtx.dataQuality || context.config.dataQuality || null,
 		latestTime: Number.isFinite(featureCtx.latestTime) ? featureCtx.latestTime : undefined,
 	};
+	if (attemptInfo.isFirstFunnel && attemptInfo.isBorn && funnelEventsWithTiming.length) {
+		const spanMs = Math.max(0, ...funnelEventsWithTiming.map(event => event.relativeTimeMs || 0));
+		const latestStart = Math.min(funnelFeatureCtx.latestTime ?? context.FIXED_NOW, context.FIXED_NOW - spanMs / 1000);
+		if (firstEventTime > latestStart) {
+			context.addWarning({
+				key: 'lifecycle.firstFunnelClipped',
+				requested: spanMs,
+				applied: Math.max(0, (context.FIXED_NOW - firstEventTime) * 1000),
+				reason: 'First-funnel timing exceeds the remaining dataset window; emit the in-window prefix and omit future steps without compressing configured TTC.',
+				severity: 'warn',
+			});
+		}
+		funnelFeatureCtx.latestTime = Math.max(firstEventTime, latestStart);
+		if (featureCtx.pinFirstTime) funnelFeatureCtx.fixedTimeMs = firstEventTime * 1000;
+	}
 
 	// Pre-compute per-step stamping modes for execution order. For isFirstFunnel + isBorn
 	// runs, the first event in execution order whose config has `isAuthEvent: true` is
@@ -505,6 +520,7 @@ function buildFunnelEvents(context, sequence, chosenFunnelProps, bindPropsIndex,
 			return {
 				event: "$experiment_started",
 				properties: {
+					...config.superProps,
 					"Experiment name": experimentName,
 					"Variant name": experimentVariant
 				}

package/lib/hook-helpers/shape.js

@@ -114,6 +114,9 @@ export function applyLifecycleWave(events, uid, opts) {
  * For users where `hashFloat(uid) < share`, injects the `path` sequence —
  * each step cloned from the user's OWN existing event of that name — right
  * after the user's FIRST `anchor` occurrence, with tight monotonic gaps.
+ * This is append-only: original traffic is never moved or removed. Events
+ * already between the anchor and clones can interrupt the immediate branch.
+ * `share` selects injection recipients, not the measured Flows branch share.
  *
  * Why these rules (HOOKS.md §2.17): Flows' unique mode reads only the FIRST
  * flow per user, so the injection anchors on the first occurrence; gaps are
@@ -192,12 +195,23 @@ export function applyPathBias(events, uid, opts) {
  * Boundary guarantees (what makes derived sessions deterministic against
  * jitter — HOOKS.md §2.13): intra-session gaps stay well under Mixpanel's
  * 30-min timeout (even spacing capped at 20min + bounded jitter, worst case
- * <28min); inter-session gaps stay well over it (sessions land on distinct
- * days when possible; same-day sessions are centered in equal partitions of
- * the day, spaced ≥¼ partition — guaranteed >30min up to 8 sessions/day);
+ * <28min); with explicit bounds, inter-session gaps stay strictly over it (sessions land on distinct
+ * days when possible; same-day slots reserve at least 30min + 1ms between
+ * clusters, compressing their spans when necessary);
  * and no engineered session crosses UTC midnight (a day-boundary split would
  * cut it — `session_query.cpp` daySplit). Valid precisely because of P2.1:
  * session_ids are re-derived after the everything hook.
+ * With both bounds omitted, placement keeps the legacy full-UTC-day slots
+ * between the user's first and last active days. Overfull legacy requests
+ * still run, but their clusters can merge under the 30-minute timeout.
+ * Optional bounds are additive: supply known dataset limits to constrain
+ * placement; the helper cannot infer datasetEnd from a user's last event.
+ * An omitted side defaults to the corresponding full UTC day edge. Partial
+ * days compress clusters, including zero-span clusters. Only explicit-bound
+ * mode throws for insufficient per-week capacity, before any record changes.
+ * The helper never silently reduces the cluster target or drops events;
+ * legacy full-day placement can exceed an unknown dataset end and be clipped
+ * later by the engine. Pass metadata bounds to prevent that clipping.
  *
  * @param {Array<Object>} events - Full user event array (everything hook).
  * @param {string} uid - Unused for hashing here; kept for atom-signature
@@ -207,10 +221,15 @@ export function applyPathBias(events, uid, opts) {
  * @param {number} opts.sessionsPerWeek - Target clusters per week (≥1).
  * @param {number} opts.eventsPerSession - Target events per cluster (≥1).
  * @param {number} opts.sessionMinutes - Max cluster span in minutes.
+ * @param {string|number} [opts.datasetStart] - Inclusive lower bound (ISO,
+ *   unix seconds, or unix milliseconds); accepts meta.datasetStart directly.
+ * @param {string|number} [opts.datasetEnd] - Inclusive upper bound (same units);
+ *   accepts meta.datasetEnd directly.
+ * @throws {RangeError} Invalid explicit bounds or insufficient bounded 30-minute-session capacity.
  * @returns {Array<Object>} The SAME array, timestamps rewritten.
  */
 export function applySessionShape(events, uid, opts) {
-	const { sessionsPerWeek, eventsPerSession, sessionMinutes } = opts || {};
+	const { sessionsPerWeek, eventsPerSession, sessionMinutes, datasetStart, datasetEnd } = opts || {};
 	if (!Array.isArray(events) || !events.length) return events;
 	if (!isPos(sessionsPerWeek) || !isPos(eventsPerSession) || !isPos(sessionMinutes)) return events;
 
@@ -221,6 +240,13 @@ export function applySessionShape(events, uid, opts) {
 	const N = timed.length;
 	const firstMs = toMs(timed[0].time);
 	const lastMs = toMs(timed[N - 1].time);
+	const bounded = datasetStart !== undefined || datasetEnd !== undefined;
+	const lowerMs = datasetStart === undefined ? Math.floor(firstMs / DAY_MS) * DAY_MS : toMs(datasetStart);
+	const upperMs = datasetEnd === undefined ? (Math.floor(lastMs / DAY_MS) + 1) * DAY_MS - 1 : toMs(datasetEnd);
+	if (!Number.isFinite(lowerMs) || !Number.isFinite(upperMs) || lowerMs > upperMs ||
+		Math.abs(lowerMs) > 8.64e15 || Math.abs(upperMs) > 8.64e15) {
+		throw new RangeError('applySessionShape: invalid dataset bounds');
+	}
 	const weeks = Math.max(1, Math.ceil((lastMs - firstMs + 1) / WEEK_MS));
 	const numSessions = Math.max(1, Math.min(
 		Math.floor(sessionsPerWeek) * weeks,
@@ -235,6 +261,15 @@ export function applySessionShape(events, uid, opts) {
 	const chance = getChance();
 	const firstDay = Math.floor(firstMs / DAY_MS);
 	const lastDay = Math.floor(lastMs / DAY_MS);
+	const separationMs = 30 * MIN_MS + 1;
+	const perDayCount = new Map();
+	const dayBounds = day => [Math.ceil(Math.max(day * DAY_MS, lowerMs)),
+		Math.floor(Math.min((day + 1) * DAY_MS - 1, upperMs))];
+	const remainingCapacity = day => {
+		if (!bounded) return Infinity;
+		const [start, end] = dayBounds(day);
+		return (end >= start ? Math.floor((end - start) / separationMs) + 1 : 0) - (perDayCount.get(day) || 0);
+	};
 
 	// Pick one day per session, week by week: prefer the user's original
 	// active days in the week, fill from the rest of the week's days, and
@@ -251,22 +286,38 @@ export function applySessionShape(events, uid, opts) {
 			const t = toMs(ev.time);
 			if (t >= weekStartMs && t < weekStartMs + WEEK_MS) originalDays.add(Math.floor(t / DAY_MS));
 		}
-		const pool = [...originalDays].filter(d => d >= dayLo && d <= dayHi);
+		const pool = [...originalDays].filter(d => d >= dayLo && d <= dayHi && remainingCapacity(d) > 0);
 		const others = [];
-		for (let d = dayLo; d <= dayHi; d++) if (!originalDays.has(d)) others.push(d);
+		for (let d = dayLo; d <= dayHi; d++) if (!originalDays.has(d) && remainingCapacity(d) > 0) others.push(d);
 		const picked = chance.pickset(pool, Math.min(need, pool.length));
 		if (picked.length < need) picked.push(...chance.pickset(others, Math.min(need - picked.length, others.length)));
-		let i = 0;
-		while (picked.length < need) picked.push(picked[i++ % Math.max(1, picked.length)]); // reuse days: > days/week sessions
+		for (const day of picked) perDayCount.set(day, (perDayCount.get(day) || 0) + 1);
+		const candidates = [...pool, ...others];
+		while (picked.length < need) {
+			if (!bounded) {
+				let reuseIndex = 0;
+				while (picked.length < need) {
+					const day = picked[reuseIndex++ % Math.max(1, picked.length)];
+					picked.push(day);
+					perDayCount.set(day, (perDayCount.get(day) || 0) + 1);
+				}
+				break;
+			}
+			const available = candidates.filter(day => remainingCapacity(day) > 0);
+			if (!available.length) {
+				throw new RangeError(`applySessionShape: insufficient session capacity in week ${w + 1} for ${need} clusters`);
+			}
+			for (const day of available) {
+				picked.push(day);
+				perDayCount.set(day, (perDayCount.get(day) || 0) + 1);
+				if (picked.length === need) break;
+			}
+		}
 		picked.sort((a, b) => a - b);
 		sessionDays.push(...picked);
 	}
 
-	// Place sessions within days. Same-day sessions get equal partitions of
-	// the day; the session is centered in its partition with bounded jitter,
-	// which guarantees the inter-session and midnight invariants above.
-	const perDayCount = new Map();
-	for (const d of sessionDays) perDayCount.set(d, (perDayCount.get(d) || 0) + 1);
+	// Bound each day's slots and reserve the strict timeout gap between them.
 	const perDaySeen = new Map();
 	const sesMs = sessionMinutes * MIN_MS;
 
@@ -280,10 +331,15 @@ export function applySessionShape(events, uid, opts) {
 		const j = perDaySeen.get(day) || 0;
 		perDaySeen.set(day, j + 1);
 
-		const seg = DAY_MS / m;
-		const span = Math.min(sesMs, seg * 0.5);
-		const center = day * DAY_MS + j * seg + (seg - span) / 2;
-		const q = Math.floor((seg - span) / 4);
+		const [dayStart, dayEnd] = dayBounds(day);
+		const seg = (dayEnd - dayStart - (m - 1) * separationMs) / m;
+		const slotStart = Math.floor(dayStart + j * (seg + separationMs));
+		const slotEnd = Math.floor(dayStart + (j + 1) * seg + j * separationMs);
+		const slotWidth = bounded ? slotEnd - slotStart : DAY_MS / m;
+		const span = bounded ? Math.floor(Math.min(sesMs, slotWidth * 0.5)) : Math.min(sesMs, slotWidth * 0.5);
+		const center = bounded ? slotStart + Math.floor((slotWidth - span) / 2)
+			: day * DAY_MS + j * slotWidth + (slotWidth - span) / 2;
+		const q = Math.floor((slotWidth - span) / 4);
 		const start = center + (q > 0 ? chance.integer({ min: -q, max: q }) : 0);
 
 		if (size === 1) {

package/lib/hook-patterns/attributed-by-source.js

@@ -43,9 +43,10 @@ import { getChance } from '../utils/utils.js';
  *   last touch BEFORE THE CONVERSION EVENT (lookback bounded by the
  *   conversion timestamp — get_last_value, whoval/read.cpp:643-655). If the
  *   user has stamped touches AFTER their conversion, the touch this pattern
- *   biases is not the one the report reads. `firstTouch` (the default) has
- *   no such gap: the lifetime-first touch is exactly what FIRST reads.
- *   Conversion-aware target selection is planned for 1.6.1.
+ *   biases is not the one the report reads. `firstTouch` also requires the
+ *   lifetime-first touch to remain inside the report's lookback. Callers must
+ *   select eligible history when a conversion-bounded report is intended.
+ *   Equal-time conflicting values have no stable cross-ingestion ordering.
  * @returns {{ overwritten: number, touches: number }} `touches` = stamped
  *   events found; `overwritten` = touches whose value was replaced.
  */

package/lib/hook-patterns/funnel-frequency-breakdown.js

@@ -66,14 +66,11 @@ export function applyFunnelFrequencyBreakdown(allUserEvents, _profile, funnelEve
 	}
 	if (!stepName) return { bin, droppedFinal: false };
 
-	// Deterministic drop decision without consuming the seeded RNG stream:
-	// hash the funnel's first insert_id (fallback: time) through
-	// simpleHashFloat — FNV-1a over the full string, quantized to 1/1000 —
-	// and drop when the hash lands under (1 - keepRate). Per-funnel stable,
-	// so reruns with the same seed drop the same funnels.
 	const dropProb = 1 - keepRate;
-	const seed = funnelEvents[0] && (funnelEvents[0].insert_id || funnelEvents[0].time) || '';
-	const det = simpleHashFloat(String(seed));
+	const anchor = funnelEvents[0] || {};
+	const seed = JSON.stringify([anchor.user_id || anchor.device_id || anchor.distinct_id || '',
+		anchor.event || '', anchor.time || '', stepName]);
+	const det = simpleHashFloat(seed);
 	if (det < dropProb) {
 		const before = funnelEvents.length;
 		dropEventsWhere(funnelEvents, e => e && e.event === stepName);

package/lib/orchestrators/user-loop.js

@@ -11,7 +11,7 @@ import pLimit from 'p-limit';
 import os from 'os';
 import * as u from "../utils/utils.js";
 import * as t from 'ak-tools';
-import { makeEvent } from "../generators/events.js";
+import { makeEvent, engineIdentity } from "../generators/events.js";
 import { makeFunnel } from "../generators/funnels.js";
 import { makeUserProfile } from "../generators/profiles.js";
 import { makeSCD } from "../generators/scd.js";
@@ -403,6 +403,8 @@ export async function userLoop(context) {
 			}
 
 			let userFirstEventTime;
+			let userUsageStartTime = context.FIXED_BEGIN;
+			const promisedAttemptEntries = new Set();
 
 			// ── v1.5 Active-day scheduling ──
 			// When `avgActiveDaysPerUser` is set, build a per-user day plan: a list
@@ -493,13 +495,9 @@ export async function userLoop(context) {
 				// Active-day mode: anchor the first funnel on a picked day so the user's
 				// signup lands within their planned active window. Legacy mode: anchor at
 				// adjustedCreated minus a noise offset.
-				let cursor;
-				if (dayPlan) {
-					const bounds = nextDayBounds();
-					cursor = bounds ? bounds.earliest : adjustedCreated.subtract(noise(), 'seconds').unix();
-				} else {
-					cursor = adjustedCreated.subtract(noise(), 'seconds').unix();
-				}
+				const lifecycleStart = Math.max(adjustedCreated.valueOf() / 1000, context.FIXED_BEGIN);
+				const firstDayBounds = dayPlan && !hasRetentionCurve ? nextDayBounds() : null;
+				let cursor = Math.max(lifecycleStart, firstDayBounds?.earliest ?? lifecycleStart);
 
 				// Resolve attempts plan. `attempts.{min,max}` count FAILED PRIORS; total
 				// passes = failedPriors + 1.  Validator coerced bounds; default both 0.
@@ -509,6 +507,7 @@ export async function userLoop(context) {
 				const failedPriors = (maxA > 0) ? chance.integer({ min: minA, max: maxA }) : 0;
 				const totalAttempts = failedPriors + 1;
 				let firstAttemptFirstEventTime = null;
+				if (failedPriors > 0) cursor = lifecycleStart;
 
 				for (let attemptNum = 1; attemptNum <= totalAttempts; attemptNum++) {
 					const isFinal = attemptNum === totalAttempts;
@@ -528,16 +527,23 @@ export async function userLoop(context) {
 						truncateBeforeAuth: !isFinal,
 						devicePool: userDevicePool,
 					};
+					const firstFeatureCtx = {
+						...featureCtx,
+						latestTime: firstDayBounds && failedPriors === 0 ? firstDayBounds.latest : context.FIXED_NOW,
+						pinFirstTime: hasRetentionCurve || failedPriors > 0,
+					};
 					const [data, converted, authMs] = await makeFunnel(
-						context, funnelToRun, user, cursor, profile, userSCD, persona, featureCtx, attemptMeta
+						context, funnelToRun, user, cursor, profile, userSCD, persona, firstFeatureCtx, attemptMeta
 					);
 					if (isFinal) userConverted = converted;
 					if (data && data.length) {
+						if (failedPriors > 0) promisedAttemptEntries.add(data[0].insert_id);
 						if (firstAttemptFirstEventTime === null) {
 							firstAttemptFirstEventTime = dayjs(data[0].time).unix();
 						}
 						// Advance the cursor for the next attempt by a small abandon-and-retry gap.
-						const lastTime = dayjs(data[data.length - 1].time).unix();
+						const lastTime = Math.max(...data.map(event => Date.parse(event.time))) / 1000;
+						userUsageStartTime = Math.max(userUsageStartTime, lastTime + 0.001);
 						cursor = lastTime + chance.integer({ min: 60, max: 30 * 60 }); // 1–30 min later
 						numEventsPreformed += data.length;
 						usersEvents = usersEvents.concat(data);
@@ -547,6 +553,13 @@ export async function userLoop(context) {
 						if (userAuthTimeMs === null) userAuthTimeMs = authMs;
 						userAuthed = true;
 					}
+					if (!isFinal && !data.length && config.events.find(event => event.event === firstFunnel.sequence[0])?.isAuthEvent) {
+						context.addWarning({
+							key: 'lifecycle.emptyPreAuthAttempt',
+							requested: 1, applied: 0, severity: 'warn',
+							reason: 'A failed prior has no pre-auth step because auth starts the funnel; the prior emits no rows and the final attempt still runs.',
+						});
+					}
 				}
 
 				userFirstEventTime = firstAttemptFirstEventTime !== null
@@ -614,6 +627,8 @@ export async function userLoop(context) {
 				// gets re-anchored to the picked day's start (subsequent funnel steps
 				// spill within `timeToConvert` hours; this is intentional).
 				const dayBounds = dayPlan ? nextDayBounds() : null;
+				const usageEarliest = Math.max(dayBounds?.earliest ?? userFirstEventTime, userUsageStartTime);
+				if (usageEarliest > (dayBounds?.latest ?? context.FIXED_NOW)) continue;
 				// Compute step1's `latestTime` so the funnel's relative span fits before
 				// FIXED_NOW. Without this, born-late users + long-ttc funnels generate
 				// large numbers of `_drop`'d events that consume budget cycles. The
@@ -639,7 +654,7 @@ export async function userLoop(context) {
 					const ttcSec = (currentFunnel.timeToConvert || 0) * 3600;
 					// Anchor cursor at picked day's start when active-day mode is on,
 					// otherwise pass userFirstEventTime (constant). NO cursor accumulation.
-					const funnelCursor = dayBounds ? dayBounds.earliest : userFirstEventTime;
+					const funnelCursor = usageEarliest;
 					// Constrain funnel step1's TimeSoup latestTime so the full funnel fits in
 					// window. Without this, late steps spill past FIXED_NOW and get `_drop`'d.
 					//
@@ -683,7 +698,7 @@ export async function userLoop(context) {
 					// — passing `true` here would pin every standalone event to the same
 					// `earliestTime`, which the now-deleted bunchIntoSessions used to paper
 					// over. With bunchIntoSessions removed, TimeSoup is the time source.
-					const standaloneEarliest = dayBounds ? dayBounds.earliest : userFirstEventTime;
+					const standaloneEarliest = usageEarliest;
 					// v1.5.1: pass `config.superProps` so standalone events get super-property
 					// stamping. Pre-1.5.1, standalone events received `{}` here, but the
 					// validator's auto-funnel (catch-all) consumed all non-strict events so
@@ -763,6 +778,8 @@ export async function userLoop(context) {
 					for (const ev of usersEvents) {
 						if (chance.bool({ likelihood: dataQuality.duplicateRate * 100 })) {
 							const dupe = { ...ev };
+							const identityDescriptor = Object.getOwnPropertyDescriptor(ev, engineIdentity);
+							if (identityDescriptor) Object.defineProperty(dupe, engineIdentity, identityDescriptor);
 							dupe.time = dayjs(ev.time).add(chance.integer({ min: 1, max: 60 }), 'seconds').toISOString();
 							dupe.insert_id = randomUUID();
 							dupes.push(dupe);
@@ -828,6 +845,13 @@ export async function userLoop(context) {
 				profile._drop = true;
 			}
 
+			const identityBeforeEverything = new Map(usersEvents.map(event => [event.insert_id, {
+				user_id: event.user_id, device_id: event.device_id,
+				original: event[engineIdentity],
+			}]));
+			const profileDropBeforeEverything = profile._drop;
+			let profileDropOverridden = false;
+
 			// Hook for processing all user events (hooks override everything)
 			if (config.hook) {
 				// `meta.isPreAuth(event)` predicate bound to this user's auth state.
@@ -843,7 +867,16 @@ export async function userLoop(context) {
 					return Number.isFinite(t) ? t < userAuthTimeMsLocal : false;
 				};
 				const newEvents = await config.hook(usersEvents, "everything", {
-					profile,
+					profile: new Proxy(profile, {
+						deleteProperty(target, key) {
+							if (key === '_drop') profileDropOverridden = true;
+							return Reflect.deleteProperty(target, key);
+						},
+						set(target, key, value) {
+							if (key === '_drop') profileDropOverridden = true;
+							return Reflect.set(target, key, value);
+						},
+					}),
 					scd: userSCD,
 					config,
 					userIsBornInDataset,
@@ -944,13 +977,44 @@ export async function userLoop(context) {
 			// 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 promisedEntries = usersEvents.filter(event => promisedAttemptEntries.has(event.insert_id));
 				const room = numEvents - context.getStoredEventCount();
 				if (room <= 0) {
 					usersEvents = [];
 				} else if (usersEvents.length > room) {
-					const keep = new Set(chance.pickset(usersEvents, room));
+					const reserved = promisedEntries.slice(0, room);
+					const others = usersEvents.filter(event => !promisedAttemptEntries.has(event.insert_id));
+					const keep = new Set([...reserved, ...chance.pickset(others, Math.max(0, room - reserved.length))]);
 					usersEvents = usersEvents.filter(e => keep.has(e));
 				}
+				if (promisedEntries.some(event => !usersEvents.includes(event))) {
+					context.addWarning({
+						key: 'lifecycle.strictAttemptBudget',
+						requested: promisedEntries.length, applied: Math.max(0, room), severity: 'warn',
+						reason: 'The remaining strict event budget is smaller than the surviving first-funnel attempt entries; strictEventCount takes precedence and later entries are omitted.',
+					});
+				}
+			}
+
+			if (userIsBornInDataset && userDevicePool?.length) {
+				const authNames = new Set(config.events.filter(event => event.isAuthEvent).map(event => event.event));
+				const stitches = usersEvents.filter(event => authNames.has(event.event) && event.user_id && event.device_id);
+				const emittedAuthTime = stitches.length ? Math.min(...stitches.map(event => Date.parse(event.time))) : null;
+				for (const event of usersEvents) {
+					if (event.event === '$experiment_started') continue;
+					if (emittedAuthTime === null || Date.parse(event.time) < emittedAuthTime) {
+						const before = identityBeforeEverything.get(event.insert_id);
+						const original = event[engineIdentity] || before?.original;
+						if (!original) continue;
+						const explicitUser = event.user_id !== original.user_id;
+						const explicitDevice = before
+							? event.device_id !== before.device_id || (!before.device_id && !!original.device_id)
+							: event.device_id !== original.device_id;
+						if (!explicitUser) delete event.user_id;
+						if (!explicitUser && !explicitDevice) event.device_id ||= userDevicePool[0];
+					}
+				}
+				if (emittedAuthTime === null && !profileDropOverridden && profile._drop === profileDropBeforeEverything) profile._drop = true;
 			}
 
 			// Store all user data (skip profile push when a hook returned null
@@ -1108,7 +1172,10 @@ export function amplifyWorldEvents(events, worldEvents, chance, fixedNow) {
 			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() });
+				const clone = { ...ev, time: dayjs.unix(t).toISOString(), insert_id: randomUUID() };
+				const identityDescriptor = Object.getOwnPropertyDescriptor(ev, engineIdentity);
+				if (identityDescriptor) Object.defineProperty(clone, engineIdentity, identityDescriptor);
+				clones.push(clone);
 			}
 		}
 	}

package/lib/verify/counting.js

@@ -12,7 +12,7 @@
 
 import { toMs } from '../hook-helpers/_internal.js';
 import { matchesWhere } from './coerce.js';
-import { buildIdentityMap, resolveUserId } from './identity.js';
+import { buildEventIdentityMap, resolveUserId } from './identity.js';
 
 const SECONDS_PER_UNIT = {
 	hour: 3600,
@@ -27,8 +27,8 @@ const SECONDS_PER_UNIT = {
  * them for what they are:
  *
  * 1. **`'ui-bucket'`** (default): `COUNT(DISTINCT date_trunc(unit, time))`
- *    in UTC — calendar-bucket counting, the shape the Mixpanel UI presents
- *    in frequency distribution charts.
+ *    in UTC. This measures calendar activity and remains the compatibility
+ *    default; raw-count histograms and rolling frequency use other rules.
  *
  * 2. **`'mixpanel-rolling'`**: the addiction_query.cpp rule,
  *    `qtz_time >= interval->last_counted + seconds_for_unit(unit)`
@@ -39,8 +39,7 @@ const SECONDS_PER_UNIT = {
  *    calendar days.
  *
  * **The default does NOT match addiction_query.cpp's rolling rule.** It is
- * kept because it matches what users see in report buckets, and because it
- * aligns with `injectOnNewDays` (which classifies days by
+ * retained for compatibility with `injectOnNewDays` (which classifies days by
  * `Math.floor(t / DAY_MS)`); mixing the two algorithms makes the atom and
  * verifier disagree at boundaries. For the actual Frequency report output
  * shape (per-interval rolling counters + histogram), use
@@ -69,8 +68,6 @@ export function countDistinctPeriods(events, eventName, unit = 'day', options =
 	const unitMs = seconds * 1000;
 
 	if (algorithm === 'ui-bucket') {
-		// Calendar bucket — UTC floor by unit. Matches what Mixpanel's UI
-		// shows and what `injectOnNewDays` uses internally.
 		const buckets = new Set();
 		for (const t of matches) buckets.add(Math.floor(t / unitMs));
 		return buckets.size;
@@ -500,13 +497,13 @@ export function binByDistinctPeriods(events, eventName, bins, unit = 'day', opti
  * @param {string} [options.event] - Event name to count. Required at runtime — throws if missing.
  * @param {('hour'|'day'|'week')} [options.unit='day'] - Rolling unit.
  * @param {number} [options.intervalDays] - Report interval length in days (positive integer). Required at runtime.
- * @param {Object[]} [options.profiles] - Profiles for device→user identity resolution.
+ * @param {Object[]} [options.profiles] - Accepted for compatibility; identity uses emitted both-ID events.
  * @returns {Array<{ interval: string, histogram: number[] }>} One row per
  *   interval (label = ISO date of the interval start); `histogram[i]` =
  *   number of users with rolling count `i + 1` in that interval.
  */
 export function frequencyHistogram(events, options = {}) {
-	const { event, unit = 'day', intervalDays, profiles } = options;
+	const { event, unit = 'day', intervalDays } = options;
 	if (typeof event !== 'string' || !event) {
 		throw new Error('frequencyHistogram: event is required');
 	}
@@ -517,7 +514,7 @@ export function frequencyHistogram(events, options = {}) {
 	}
 	if (!Array.isArray(events) || !events.length) return [];
 
-	const identityMap = profiles ? buildIdentityMap(profiles) : undefined;
+	const identityMap = buildEventIdentityMap(events);
 	let minMs = Infinity, maxMs = -Infinity;
 	const matches = [];
 	for (const e of events) {

package/lib/verify/emulate-breakdown.js

@@ -23,7 +23,7 @@
 
 import { toMs } from '../hook-helpers/_internal.js';
 import { evaluateFunnel, evaluateFunnelHPC, evaluateAnyOrderCompletion } from './funnel-engine.js';
-import { buildIdentityMap, resolveUserId } from './identity.js';
+import { buildEventIdentityMap, resolveUserId } from './identity.js';
 import { coerceToBreakdownKey, breakdownSegmentKey, matchesWhere } from './coerce.js';
 import { filterFirstTimeEver } from './first-time.js';
 import { sessionize } from './sessionize.js';
@@ -277,18 +277,7 @@ export function emulateBreakdown(events, config) {
 	if (!Array.isArray(events)) throw new Error('emulateBreakdown: events must be an array');
 	if (!config || !config.type) throw new Error('emulateBreakdown: config.type is required');
 
-	// Auto-build identity map ONCE when profiles supplied. Threads through every
-	// breakdown type AND every time-bucket recursive call so pre-auth (device_id
-	// only) events resolve to the same canonical user as post-auth (user_id)
-	// events. Hoisted above the timeBucket dispatch to avoid rebuilding the
-	// map per-bucket on large datasets.
-	const identityMap = config.identityMap
-		|| (Array.isArray(config.profiles)
-			&& config.profiles.some(p =>
-				p && ((Array.isArray(p.device_ids) && p.device_ids.length)
-					|| (Array.isArray(p.anonymousIds) && p.anonymousIds.length)))
-			? buildIdentityMap(config.profiles)
-			: undefined);
+	const identityMap = config.identityMap || buildEventIdentityMap(events);
 
 	// v1.5: time-bucketed wrapper. Partition events by UTC bucket, run the
 	// underlying breakdown per partition, tag rows with `period`.
@@ -318,12 +307,35 @@ export function emulateBreakdown(events, config) {
 			throw new Error('emulateBreakdown: type "topPaths" does not compose with timeBucket — flows aggregate one path universe over the range');
 		}
 		const range = config.timeBucketRange || {};
-		const buckets = partitionByTimeBucket(events, config.timeBucket, range);
+		const bucketEvents = config.type === 'attributedBy'
+			? events.filter(event => event && event.event === config.conversionEvent)
+			: events;
+		const buckets = partitionByTimeBucket(bucketEvents, config.timeBucket, range);
 		// Pass the pre-built identityMap into recursive calls so the auto-build
 		// branch above is a no-op per bucket (would otherwise rebuild N times).
 		const inner = { ...config, timeBucket: undefined, timeBucketRange: undefined, identityMap };
 		const out = [];
 
+		if (config.type === 'attributedBy') {
+			attributedBy([], {
+				conversionEvent: config.conversionEvent,
+				attributionEvent: config.attributionEvent,
+				attributionProperty: config.attributionProperty,
+				model: config.model,
+				perConversion: config.perConversion,
+				identityMap,
+			});
+			for (const { period } of buckets) {
+				const rows = attributedBy(events, /** @type {*} */ (inner), bucketBoundsMs(period, config.timeBucket));
+				if (rows.length) {
+					for (const row of rows) out.push({ period, ...row });
+				} else {
+					out.push({ period, _empty: true });
+				}
+			}
+			return out;
+		}
+
 		// v1.6.0 (P1.6.5): step-0-anchored trend types. Mixpanel evaluates each
 		// trend interval as "step 0 in [start, stop); steps 1+ in
 		// [start, stop + conversion window)" (funnel_query.cpp:1398-1401), and
@@ -483,13 +495,6 @@ function funnelFrequency(events, { steps, breakdownByFrequencyOf, conversionWind
 	if ((isTotalsMode || holdPropertyConstant) && !isSequentialOrder) {
 		throw new Error(`funnelFrequency: countMode '${countMode}' / holdPropertyConstant require a sequential funnel order (got '${funnelOrder}')`);
 	}
-	// HPC buckets events by property value BEFORE evaluation (evaluateFunnelHPC),
-	// but Mixpanel derives session boundaries from the user's FULL event stream —
-	// sessionizing each bucket independently would merge across the gaps left by
-	// removed events and produce wrong ordinals. Refuse rather than mis-count.
-	if (holdPropertyConstant && (countMode === 'sessions' || conversionWindow)) {
-		throw new Error('funnelFrequency: holdPropertyConstant cannot combine with session-count conversion windows — session boundaries derive from the full event stream, but HPC evaluates per-property-value event subsets');
-	}
 
 	const userEvents = groupByUser(events, identityMap);
 	const result = [];
@@ -787,29 +792,43 @@ function attributedBy(events, {
 	model = 'firstTouch',
 	perConversion = 'first',
 	identityMap,
-}) {
+}, conversionRange = null) {
 	if (!conversionEvent || !attributionEvent || !attributionProperty) {
 		throw new Error('attributedBy requires conversionEvent, attributionEvent, attributionProperty');
 	}
 	if (perConversion !== 'first' && perConversion !== 'all') {
 		throw new Error(`attributedBy: unknown perConversion "${perConversion}" — use 'first' or 'all'`);
 	}
+	// Attribution is unbounded over supplied history; this API has no finite
+	// lookback. The private bucket interval limits conversions, never touches.
+	// Backend transitions also compress case-insensitive equal values within
+	// 30 minutes (value/transitions.cpp, whoval/util.cpp). This raw-value model
+	// does not emulate that compression, which can retain earlier string casing.
 	const userEvents = groupByUser(events, identityMap);
 	const counts = new Map();
 	for (const [, evs] of userEvents) {
 		const sorted = sortByTime(evs);
+		const inRange = sorted.filter(event => {
+			if (!event || event.event !== conversionEvent) return false;
+			const time = toMs(event.time);
+			return !conversionRange || (time >= conversionRange.startMs && time < conversionRange.endMs);
+		});
 		const conversions = perConversion === 'all'
-			? sorted.filter(e => e && e.event === conversionEvent)
-			: sorted.filter(e => e && e.event === conversionEvent).slice(0, 1);
+			? inRange
+			: inRange.slice(0, 1);
 		for (const conversion of conversions) {
 			const conversionTime = toMs(conversion.time);
-			const allTouches = sorted.filter(e =>
-				e && e.event === attributionEvent && toMs(e.time) <= conversionTime
+			// attribution.py's defined-property filter excludes null and undefined;
+			// whoval/read.cpp first/last include the conversion timestamp.
+			const allTouches = sorted.filter(event =>
+				event && event.event === attributionEvent && event[attributionProperty] != null
+					&& toMs(event.time) <= conversionTime
 			);
-			if (!allTouches.length) continue;
 			const touch = model === 'lastTouch' ? allTouches[allTouches.length - 1] : allTouches[0];
-			const v = touch[attributionProperty] ?? 'unknown';
-			counts.set(v, (counts.get(v) || 0) + 1);
+			// Backend missing attribution is undefined. Preserve this API's existing
+			// 'unknown' label, not coerceToBreakdownKey's general 'undefined' label.
+			const value = touch?.[attributionProperty] ?? 'unknown';
+			counts.set(value, (counts.get(value) || 0) + 1);
 		}
 	}
 	return [...counts.entries()].map(([source, count]) => ({