@ak--47/dungeon-master 1.3.1 → 1.4.1

package/lib/generators/funnels.js

@@ -19,9 +19,17 @@ import { dataLogger as logger } from "../utils/logger.js";
  * @param {Object} profile - User profile object
  * @param {Object} scd - Slowly changing dimensions object
  * @param {Object} [persona] - User's assigned persona
- * @returns {Promise<[Array, boolean]>} Tuple of [events, didConvert]
+ * @param {Object} [featureCtx] - Persona / world-event / data-quality / etc. context.
+ * @param {Object} [attemptMeta] - Phase 2 multi-attempt + identity context. Shape:
+ *   `{ isFirstFunnel, isBorn, attemptsConfig, attemptNumber, totalAttempts, isFinalAttempt,
+ *      truncateBeforeAuth, devicePool }`. When omitted defaults to a single normal attempt
+ *   with no identity stamping overrides (legacy behavior).
+ * @returns {Promise<[Array, boolean, number|null]>} Tuple `[events, didConvert, authTimeMs]`
+ *   where `authTimeMs` is the unix-millisecond timestamp of the stitch event (the first
+ *   `isAuthEvent` step that actually fired in this funnel run), or null if the user did
+ *   not reach the stitch step in this run.
  */
-export async function makeFunnel(context, funnel, user, firstEventTime, profile = {}, scd = {}, persona = null, featureCtx = {}) {
+export async function makeFunnel(context, funnel, user, firstEventTime, profile = {}, scd = {}, persona = null, featureCtx = {}, attemptMeta = null) {
 	if (!funnel) throw new Error("no funnel");
 	if (!user) throw new Error("no user");
 
@@ -29,52 +37,110 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	const chance = u.getChance();
 	const { hook = async (a) => a } = config;
 
+	// ── Phase 2 attempt + identity context ──
+	// Resolve a defensive default so legacy callers that don't pass attemptMeta still
+	// get a complete shape downstream (hook meta, identity stamping logic).
+	const meta = attemptMeta || {};
+	const attemptInfo = {
+		isFirstFunnel: !!meta.isFirstFunnel,
+		isBorn: meta.isBorn === undefined ? false : !!meta.isBorn,
+		attemptsConfig: meta.attemptsConfig || null,
+		attemptNumber: meta.attemptNumber || 1,
+		totalAttempts: meta.totalAttempts || 1,
+		isFinalAttempt: meta.isFinalAttempt === undefined ? true : !!meta.isFinalAttempt,
+		truncateBeforeAuth: !!meta.truncateBeforeAuth,
+	};
+	const devicePool = meta.devicePool || null;
+
 	// Get session start events if configured
 	const sessionStartEvents = config.events?.filter(a => a.isSessionStartEvent) || [];
 
 	// Clone funnel to avoid mutating the original object
 	funnel = { ...funnel };
 
-	// Experiment handling: if funnel.experiment === true, create 3 variants
+	// Experiment handling: resolved by config-validator into funnel._experiment.
+	// Variant assignment is deterministic per-user (hash of userId + experiment name).
 	let experimentVariant = null;
 	let experimentName = null;
-
-	if (funnel.experiment) {
-		experimentName = funnel.name + ` Experiment` || "Unnamed Funnel";
-
-		// Evenly distribute across 3 variants (33.33% each) using seeded chance
-		const randomValue = chance.floating({ min: 0, max: 1 });
-		if (randomValue < 0.333) {
-			// Variant A: WORSE conversion, slower
-			funnel.conversionRate = Math.max(1, Math.floor(funnel.conversionRate * 0.7));
-			funnel.timeToConvert = Math.max(0.1, funnel.timeToConvert * 1.5);
-			experimentVariant = "A";
-		} else if (randomValue < 0.666) {
-			// Variant B: BETTER conversion, faster
-			funnel.conversionRate = Math.min(100, Math.ceil(funnel.conversionRate * 1.3));
-			funnel.timeToConvert = Math.max(0.1, funnel.timeToConvert * 0.7);
-			experimentVariant = "B";
-		} else {
-			// Variant C: CONTROL - original values (no changes)
-			experimentVariant = "C";
+	let experimentMeta = null;
+
+	let expCfg = funnel._experiment;
+	if (!expCfg && funnel.experiment) {
+		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 },
+		];
+		expCfg = { name: (funnel.name ? funnel.name + ' Experiment' : 'Unnamed Experiment'), variants: DEFAULT_VARIANTS, startUnix: null };
+	}
+	if (expCfg) {
+		const isActive = !expCfg.startUnix || firstEventTime >= expCfg.startUnix;
+		if (isActive) {
+			experimentName = expCfg.name;
+			const userId = user.distinct_id || '';
+			const totalWeight = expCfg.variants.reduce((s, v) => s + v.weight, 0);
+			const hashVal = Number(u.quickHash(`${userId}:${experimentName}`)) % totalWeight;
+			let cumWeight = 0;
+			let chosenVariant = expCfg.variants[0];
+			let chosenIdx = 0;
+			for (let vi = 0; vi < expCfg.variants.length; vi++) {
+				cumWeight += expCfg.variants[vi].weight;
+				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.timeToConvert = Math.max(0.1,
+				(funnel.timeToConvert || 1) * chosenVariant.ttcMultiplier);
+			funnel._experimentName = experimentName;
+			funnel._experimentVariant = experimentVariant;
+			funnel.sequence = ["$experiment_started", ...funnel.sequence];
+			experimentMeta = {
+				name: experimentName,
+				variantName: experimentVariant,
+				variantIndex: chosenIdx,
+				conversionMultiplier: chosenVariant.conversionMultiplier,
+				ttcMultiplier: chosenVariant.ttcMultiplier,
+				startDate: expCfg.startUnix,
+			};
 		}
+	}
 
-		// Mark that this funnel has experiment metadata (used later)
-		funnel._experimentName = experimentName;
-		funnel._experimentVariant = experimentVariant;
-
-		// Insert $experiment_started at beginning of sequence (clone array to avoid mutation)
-		funnel.sequence = ["$experiment_started", ...funnel.sequence];
+	// 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)));
+	}
+	const resolvedWorldEvents = /** @type {import('../../types').ResolvedWorldEvent[]} */ (config.worldEvents);
+	if (resolvedWorldEvents && firstEventTime) {
+		for (const we of resolvedWorldEvents) {
+			if (firstEventTime >= we.startUnix && firstEventTime < we.endUnix && we.conversionModifier !== 1.0) {
+				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)));
+				}
+			}
+		}
 	}
 
-	// Call pre-funnel hook
+	// funnel-pre hook fires AFTER modifiers — hook has final authority on conversionRate,
+	// props, timeToConvert, and sequence.
 	await hook(funnel, "funnel-pre", {
 		user, profile, scd, funnel, config, firstEventTime,
 		datasetStart: context.DATASET_START_SECONDS,
-		datasetEnd: context.DATASET_END_SECONDS
+		datasetEnd: context.DATASET_END_SECONDS,
+		isFirstFunnel: attemptInfo.isFirstFunnel,
+		isBorn: attemptInfo.isBorn,
+		attemptsConfig: attemptInfo.attemptsConfig,
+		attemptNumber: attemptInfo.attemptNumber,
+		totalAttempts: attemptInfo.totalAttempts,
+		isFinalAttempt: attemptInfo.isFinalAttempt,
+		persona,
+		experiment: experimentMeta,
 	});
 
-	// Extract funnel configuration
+	// Extract funnel configuration (post-hook — hook's mutations are the final word)
 	let {
 		sequence,
 		conversionRate = 50,
@@ -87,7 +153,7 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		bindPropsIndex = 0
 	} = funnel;
 
-	const { distinct_id, created, anonymousIds = [], sessionIds = [] } = user;
+	const { distinct_id, created, anonymousIds = [] } = user;
 	const { superProps = {}, groupKeys = [] } = config;
 
 	// Choose properties for this funnel instance
@@ -111,57 +177,61 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		chance
 	);
 
-	// Apply persona conversion modifier (before hook, so hook can override via funnel-pre)
-	if (persona && persona.conversionModifier) {
-		adjustedConversionRate = Math.min(100, Math.max(0, Math.round(adjustedConversionRate * persona.conversionModifier)));
-	}
-
-	// Apply world event conversion modifier if active at firstEventTime
-	const resolvedWorldEvents = /** @type {import('../../types').ResolvedWorldEvent[]} */ (config.worldEvents);
-	if (resolvedWorldEvents && firstEventTime) {
-		for (const we of resolvedWorldEvents) {
-			if (firstEventTime >= we.startUnix && firstEventTime < we.endUnix && we.conversionModifier !== 1.0) {
-				const affects = we.affectsEvents;
-				if (affects === "*" || (Array.isArray(affects) && sequence.some(s => affects.includes(s)))) {
-					adjustedConversionRate = Math.min(100, Math.max(0, Math.round(adjustedConversionRate * we.conversionModifier)));
-				}
-			}
-		}
-	}
-
-	// Apply feature conversion lifts
-	const resolvedFeatures = config.features;
-	if (resolvedFeatures && firstEventTime) {
-		const daysSinceBegin = (firstEventTime - context.FIXED_BEGIN) / 86400;
-		for (const feat of resolvedFeatures) {
-			if (feat.conversionLift && daysSinceBegin >= feat.launchDay) {
-				const daysSinceLaunch = daysSinceBegin - feat.launchDay;
-				const { k, midpoint } = feat._resolvedCurve || { k: 0.08, midpoint: 30 };
-				const adoptionProb = 1 / (1 + Math.exp(-k * (daysSinceLaunch - midpoint)));
-				if (chance.bool({ likelihood: Math.min(100, adoptionProb * 100) })) {
-					adjustedConversionRate = Math.min(100, Math.max(0, Math.round(adjustedConversionRate * feat.conversionLift)));
-				}
-			}
-		}
-	}
-
 	// Determine if user converts and how many steps they'll take
 	// When experiment mode is active, $experiment_started is prepended to sequence
 	// but should not count as a funnel step for conversion purposes
 	const conversionStepCount = expName ? sequence.length - 1 : sequence.length;
-	const { doesUserConvert, numStepsUserWillTake } = determineConversion(
+	let { doesUserConvert, numStepsUserWillTake } = determineConversion(
 		adjustedConversionRate,
 		conversionStepCount,
 		chance
 	);
 
+	// ── Phase 2 identity helpers ──
+	// `firstAuthSeqIdx` is the index in `sequence` (and processedEvents) of the first
+	// step whose event config has `isAuthEvent: true`. Used both for truncating failed
+	// prior attempts (cap before auth) and for picking per-step identity stamping mode
+	// inside isFirstFunnel runs. -1 if no step in this funnel is flagged.
+	const eventsByName = (() => {
+		const map = new Map();
+		for (const e of (config.events || [])) map.set(e.event, e);
+		return map;
+	})();
+	let firstAuthSeqIdx = -1;
+	for (let i = 0; i < sequence.length; i++) {
+		const ev = eventsByName.get(sequence[i]);
+		if (ev && ev.isAuthEvent) { firstAuthSeqIdx = i; break; }
+	}
+	// When experiment mode prepends $experiment_started, the auth index in
+	// `processedEvents` is shifted right by 1.
+	const firstAuthProcessedIdx = firstAuthSeqIdx === -1
+		? -1
+		: (expName ? firstAuthSeqIdx + 1 : firstAuthSeqIdx);
+
+	// Truncated pre-auth attempt: force the user to drop somewhere strictly before the
+	// stitch. If there is no auth step in this funnel, truncation is a no-op (default
+	// flow runs). When firstAuthSeqIdx === 0 there's no pre-auth room — force 0 steps
+	// (the attempt produces nothing for that user).
+	if (attemptInfo.truncateBeforeAuth && firstAuthSeqIdx >= 0 && conversionStepCount > 0) {
+		if (firstAuthSeqIdx === 0) {
+			numStepsUserWillTake = 0;
+		} else {
+			numStepsUserWillTake = chance.integer({ min: 1, max: firstAuthSeqIdx });
+		}
+		doesUserConvert = false;
+	}
+
 	// Get steps user will actually take
 	let funnelStepsUserWillTake;
-	if (expName) {
-		// $experiment_started always fires; conversion only applies to actual funnel steps
-		funnelStepsUserWillTake = [processedEvents[0], ...processedEvents.slice(1, 1 + numStepsUserWillTake)];
+	if (attemptInfo.truncateBeforeAuth && firstAuthSeqIdx === 0) {
+		// Pre-auth truncation with the stitch at index 0 leaves no room before it → no events.
+		funnelStepsUserWillTake = [];
+	} else if (expName) {
+		// $experiment_started always fires; conversion only applies to actual funnel steps.
+		// (Pre-Phase 2 behavior: even when numStepsUserWillTake===0, $experiment_started fires.)
+		funnelStepsUserWillTake = [processedEvents[0], ...processedEvents.slice(1, 1 + Math.max(0, numStepsUserWillTake))];
 	} else {
-		funnelStepsUserWillTake = processedEvents.slice(0, numStepsUserWillTake);
+		funnelStepsUserWillTake = processedEvents.slice(0, Math.max(0, numStepsUserWillTake));
 	}
 
 	// Apply ordering strategy
@@ -191,12 +261,34 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		userCampaign: featureCtx.userCampaign || null,
 		userLocation: featureCtx.userLocation || null,
 		worldEventsTimeline: featureCtx.worldEventsTimeline || context.config.worldEvents || null,
-		resolvedFeatures: featureCtx.resolvedFeatures || context.config.features || null,
-		resolvedAnomalies: featureCtx.resolvedAnomalies || context.config.anomalies || null,
 		dataQuality: featureCtx.dataQuality || context.config.dataQuality || null,
-		geo: featureCtx.geo || context.config.geo || null,
 	};
 
+	// 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
+	// the stitch event; events before it stamp `device_only`, events after stamp
+	// `user_only`. For everything else we stamp `both` (current default identity model).
+	const stampingByIndex = new Array(funnelEventsWithTiming.length).fill('both');
+	let runAuthExecIdx = -1;
+	if (attemptInfo.isFirstFunnel && attemptInfo.isBorn) {
+		for (let i = 0; i < funnelEventsWithTiming.length; i++) {
+			const evName = funnelEventsWithTiming[i].event;
+			const cfg = eventsByName.get(evName);
+			if (cfg && cfg.isAuthEvent) { runAuthExecIdx = i; break; }
+		}
+		for (let i = 0; i < funnelEventsWithTiming.length; i++) {
+			if (runAuthExecIdx === -1) {
+				stampingByIndex[i] = 'device_only';
+			} else if (i < runAuthExecIdx) {
+				stampingByIndex[i] = 'device_only';
+			} else if (i === runAuthExecIdx) {
+				stampingByIndex[i] = 'stitch';
+			} else {
+				stampingByIndex[i] = 'user_only';
+			}
+		}
+	}
+
 	// Generate actual events with timing
 	const finalEvents = await generateFunnelEvents(
 		context,
@@ -204,19 +296,33 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		distinct_id,
 		firstEventTime || dayjs(created).unix(),
 		anonymousIds,
-		sessionIds,
 		groupKeys,
-		funnelFeatureCtx
+		funnelFeatureCtx,
+		{ devicePool, stampingByIndex }
 	);
 
+	// Compute the auth-time of the actual stitch event in execution order, if any.
+	const authTimeMs = runAuthExecIdx >= 0 && finalEvents[runAuthExecIdx]
+		? Date.parse(finalEvents[runAuthExecIdx].time) || null
+		: null;
+
 	// Call post-funnel hook
 	await hook(finalEvents, "funnel-post", {
 		user, profile, scd, funnel, config,
+		firstEventTime,
 		datasetStart: context.DATASET_START_SECONDS,
-		datasetEnd: context.DATASET_END_SECONDS
+		datasetEnd: context.DATASET_END_SECONDS,
+		isFirstFunnel: attemptInfo.isFirstFunnel,
+		isBorn: attemptInfo.isBorn,
+		attemptsConfig: attemptInfo.attemptsConfig,
+		attemptNumber: attemptInfo.attemptNumber,
+		totalAttempts: attemptInfo.totalAttempts,
+		isFinalAttempt: attemptInfo.isFinalAttempt,
+		persona,
+		experiment: experimentMeta,
 	});
 
-	return [finalEvents, doesUserConvert];
+	return [finalEvents, doesUserConvert, authTimeMs];
 }
 
 /**
@@ -402,14 +508,15 @@ function addTimingOffsets(events, timeToConvert, numSteps) {
 
 /**
  * Generates actual events with proper timing
- * @param {Context} context - Context object
- * @param {Array} eventsWithTiming - Events with timing information
- * @param {string} distinct_id - User ID
- * @param {number} earliestTime - Base timestamp
- * @param {Array} anonymousIds - Anonymous IDs
- * @param {Array} sessionIds - Session IDs
- * @param {Array} groupKeys - Group keys
- * @returns {Promise<Array>} Generated events
+ * @param {Context} context
+ * @param {Array} eventsWithTiming
+ * @param {string} distinct_id
+ * @param {number} earliestTime
+ * @param {Array} anonymousIds
+ * @param {Array} groupKeys
+ * @param {Object} [featureCtx] - Feature context (persona, worldEvents, dataQuality)
+ * @param {Object} [identityArgs] - Phase 2 identity args ({ stampingByIndex, devicePool })
+ * @returns {Promise<Array>}
  */
 async function generateFunnelEvents(
 	context,
@@ -417,25 +524,29 @@ async function generateFunnelEvents(
 	distinct_id,
 	earliestTime,
 	anonymousIds,
-	sessionIds,
 	groupKeys,
-	featureCtx = {}
+	featureCtx = {},
+	identityArgs = null
 ) {
 	let funnelStartTime;
+	const stampingByIndex = (identityArgs && identityArgs.stampingByIndex) || null;
+	const devicePool = (identityArgs && identityArgs.devicePool) || 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;
 		const newEvent = await makeEvent(
 			context,
 			distinct_id,
 			earliestTime,
 			event,
 			anonymousIds,
-			sessionIds,
 			{},
 			groupKeys,
-			false,  // Let all funnel events use TimeSoup for proper time distribution
 			false,
-			featureCtx
+			false,
+			featureCtx,
+			identityCtx
 		);
 
 		if (index === 0) {

package/lib/hook-helpers/_internal.js

@@ -0,0 +1,23 @@
+export function toMs(t) {
+	if (typeof t === 'number') return t > 1e12 ? t : t > 1e9 ? t * 1000 : t;
+	return Date.parse(t);
+}
+
+export function writeTime(event, ms) {
+	if (typeof event.time === 'string' || event.time === undefined) {
+		event.time = new Date(ms).toISOString();
+	} else if (event.time > 1e12) {
+		event.time = ms;
+	} else {
+		event.time = ms / 1000;
+	}
+}
+
+export function simpleHashFloat(s) {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return ((h >>> 0) % 1000) / 1000;
+}

package/lib/hook-helpers/cohort.js

@@ -0,0 +1,124 @@
+/**
+ * Hook helpers — cohort atoms.
+ *
+ * Pure functions used inside `everything` / `event` hooks to classify users into
+ * behavioral cohorts. None of these mutate the input. They derive a label from a
+ * user's events or profile and return it; the caller decides what to do with the
+ * label (typically: feed into a `mutate` or `inject` atom).
+ */
+
+import { toMs } from './_internal.js';
+
+/**
+ * Classify a user into a named bin based on the count of a specific event in their stream.
+ * Bin definitions use inclusive lower bound, exclusive upper bound (`[lo, hi)`).
+ *
+ * @example
+ * const tier = binUsersByEventCount(events, 'Complete Action Item', {
+ *   low:   [0, 5],
+ *   sweet: [5, 20],
+ *   over:  [20, Infinity],
+ * });
+ *
+ * @param {Array<{event:string,time?:string|number}>} events - User's event stream.
+ * @param {string} eventName - Event to count.
+ * @param {Record<string, [number, number]>} bins - Map of bin name → [lo, hi).
+ * @returns {string|null} Matching bin name, or null if no bin matches.
+ */
+export function binUsersByEventCount(events, eventName, bins) {
+	if (!events || !eventName || !bins) return null;
+	let count = 0;
+	for (const ev of events) {
+		if (ev && ev.event === eventName) count++;
+	}
+	for (const [name, range] of Object.entries(bins)) {
+		if (!Array.isArray(range) || range.length !== 2) continue;
+		const [lo, hi] = range;
+		if (count >= lo && count < hi) return name;
+	}
+	return null;
+}
+
+/**
+ * Like `binUsersByEventCount` but only counts events whose timestamp falls inside
+ * `[startTime, endTime]` (inclusive). Times can be unix milliseconds, unix seconds,
+ * ISO strings, or anything `Date.parse` accepts.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventName
+ * @param {string|number} startTime
+ * @param {string|number} endTime
+ * @param {Record<string, [number, number]>} bins
+ * @returns {string|null}
+ */
+export function binUsersByEventInRange(events, eventName, startTime, endTime, bins) {
+	if (!events || !eventName || !bins) return null;
+	const startMs = toMs(startTime);
+	const endMs = toMs(endTime);
+	if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;
+	let count = 0;
+	for (const ev of events) {
+		if (!ev || ev.event !== eventName || ev.time === undefined) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t) && t >= startMs && t <= endMs) count++;
+	}
+	for (const [name, range] of Object.entries(bins)) {
+		if (!Array.isArray(range) || range.length !== 2) continue;
+		const [lo, hi] = range;
+		if (count >= lo && count < hi) return name;
+	}
+	return null;
+}
+
+/**
+ * Count events that occur strictly between the FIRST `eventA` and the FIRST `eventB`
+ * after it in the stream. Useful for "how many ${X} did the user do between landing
+ * and converting" measurements that hooks then condition on.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventA
+ * @param {string} eventB
+ * @returns {number} Count, or 0 if either anchor is missing.
+ */
+export function countEventsBetween(events, eventA, eventB) {
+	if (!events || !eventA || !eventB) return 0;
+	const sorted = sortByTime(events);
+	const a = sorted.find(e => e && e.event === eventA);
+	if (!a) return 0;
+	const aIdx = sorted.indexOf(a);
+	const b = sorted.slice(aIdx + 1).find(e => e && e.event === eventB);
+	if (!b) return 0;
+	const aT = toMs(a.time);
+	const bT = toMs(b.time);
+	let n = 0;
+	for (const ev of sorted) {
+		if (!ev || ev.time === undefined) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t) && t > aT && t < bT) n++;
+	}
+	return n;
+}
+
+/**
+ * Profile-based cohort check. Returns true if `profile[segmentKey]` matches one of
+ * `segmentValues` (array) or equals the single value passed.
+ *
+ * @param {Object} profile
+ * @param {string} segmentKey
+ * @param {*|Array<*>} segmentValues
+ * @returns {boolean}
+ */
+export function userInProfileSegment(profile, segmentKey, segmentValues) {
+	if (!profile || !segmentKey) return false;
+	const v = profile[segmentKey];
+	if (Array.isArray(segmentValues)) return segmentValues.includes(v);
+	return v === segmentValues;
+}
+
+// ── internal helpers ──
+
+function sortByTime(events) {
+	const copy = events.slice();
+	copy.sort((a, b) => toMs(a && a.time) - toMs(b && b.time));
+	return copy;
+}

package/lib/hook-helpers/identity.js

@@ -0,0 +1,56 @@
+/**
+ * Hook helpers — identity atoms.
+ *
+ * Wraps the Phase 2 identity primitives so hook authors can re-derive pre-auth /
+ * post-auth / stitch info without having to grovel inside `meta`. The `everything`
+ * hook already exposes `meta.authTime` and `meta.isPreAuth(event)`; these helpers
+ * cover callers that operate on stored events outside that hook.
+ */
+
+/**
+ * Returns true if the event happened strictly before the user's stitch event.
+ * - `authTime === null | undefined` is interpreted as "user never authed" → every
+ *   event is pre-auth (matches the `everything` hook's behavior for born-in-dataset
+ *   users that never converted).
+ * - Pre-existing users (already authed before the dataset window) won't have
+ *   `authTime` populated by the engine; callers wanting "always false" semantics
+ *   should pass `0` or `-Infinity`.
+ *
+ * @param {{time: string|number}} event
+ * @param {number|null|undefined} authTime - Unix milliseconds.
+ * @returns {boolean}
+ */
+export function isPreAuthEvent(event, authTime) {
+	if (!event || event.time === undefined || event.time === null) return false;
+	if (authTime === null || authTime === undefined) return true;
+	const t = typeof event.time === 'number'
+		? (event.time > 1e12 ? event.time : event.time * 1000)
+		: Date.parse(event.time);
+	return Number.isFinite(t) ? t < authTime : false;
+}
+
+/**
+ * Partition `events` into pre-auth / post-auth / stitch buckets relative to
+ * `authTime`. The stitch is the first post-auth event whose record carries BOTH
+ * `user_id` and `device_id` (the engine stamps this exactly once per converted
+ * born-in-dataset user). When no such event exists, `stitch` is `null`.
+ *
+ * @param {Array<{event:string,time:string|number,user_id?:string,device_id?:string}>} events
+ * @param {number|null|undefined} authTime - Unix milliseconds.
+ * @returns {{ preAuth: Object[], postAuth: Object[], stitch: Object|null }}
+ */
+export function splitByAuth(events, authTime) {
+	const result = { preAuth: [], postAuth: [], stitch: null };
+	if (!events) return result;
+	for (const ev of events) {
+		if (isPreAuthEvent(ev, authTime)) {
+			result.preAuth.push(ev);
+		} else {
+			result.postAuth.push(ev);
+			if (!result.stitch && ev && ev.user_id && ev.device_id) {
+				result.stitch = ev;
+			}
+		}
+	}
+	return result;
+}

package/lib/hook-helpers/index.js

@@ -0,0 +1,44 @@
+/**
+ * @ak--47/dungeon-master/hook-helpers — Phase 3 atom barrel export.
+ *
+ * Atoms are pure-ish primitives that hooks compose to build trends. The five
+ * sub-modules (cohort, mutate, timing, inject, identity) cover the moves Mixpanel
+ * analyses need: classify users into bins, scale event counts and property values,
+ * adjust timings, splice in cloned events, and reason about pre-auth state.
+ *
+ * Each atom carries full JSDoc on its definition; see the individual files for
+ * the contract details. Patterns (Phase 4, lib/hook-patterns) are higher-level
+ * recipes built on top of these atoms.
+ */
+
+export {
+	binUsersByEventCount,
+	binUsersByEventInRange,
+	countEventsBetween,
+	userInProfileSegment,
+} from './cohort.js';
+
+export {
+	cloneEvent,
+	dropEventsWhere,
+	scaleEventCount,
+	scalePropertyValue,
+	shiftEventTime,
+} from './mutate.js';
+
+export {
+	scaleTimingBetween,
+	scaleFunnelTTC,
+	findFirstSequence,
+} from './timing.js';
+
+export {
+	injectAfterEvent,
+	injectBetween,
+	injectBurst,
+} from './inject.js';
+
+export {
+	isPreAuthEvent,
+	splitByAuth,
+} from './identity.js';