@ak--47/dungeon-master 1.5.4 → 1.6.0

package/lib/generators/funnels.js

@@ -59,7 +59,9 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 	funnel = { ...funnel };
 
 	// Experiment handling: resolved by config-validator into funnel._experiment.
-	// Variant assignment is deterministic per-user (hash of userId + experiment name).
+	// Sticky (default): variant is a deterministic per-user hash of
+	// userId + experiment name — same variant on every pass. sticky: false
+	// re-rolls the variant per funnel pass via the seeded RNG.
 	let experimentVariant = null;
 	let experimentName = null;
 	let experimentMeta = null;
@@ -79,7 +81,9 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 			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;
+			const hashVal = expCfg.sticky === false
+				? chance.integer({ min: 0, max: totalWeight - 1 })
+				: Number(u.quickHash(`${userId}:${experimentName}`)) % totalWeight;
 			let cumWeight = 0;
 			let chosenVariant = expCfg.variants[0];
 			let chosenIdx = 0;
@@ -234,13 +238,25 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		funnelStepsUserWillTake = processedEvents.slice(0, Math.max(0, numStepsUserWillTake));
 	}
 
-	// Apply ordering strategy
-	const funnelActualOrder = applyOrderingStrategy(
-		funnelStepsUserWillTake,
-		order,
-		config,
-		sequence
-	);
+	// Apply ordering strategy. When experiment mode prepended $experiment_started,
+	// shuffle only the real funnel steps: the exposure event must precede every
+	// step it governs (Mixpanel experiment semantics — variant lift is measured
+	// exposure → outcome), and strategies like first-fixed should pin the true
+	// first step, not the synthetic exposure marker. Pre-v1.6 the whole array was
+	// shuffled, which landed $experiment_started mid-funnel for non-sequential
+	// orders and truncated the measured exposure→conversion TTC.
+	let funnelActualOrder;
+	if (expName && funnelStepsUserWillTake.length > 1) {
+		const [exposureEvent, ...realSteps] = funnelStepsUserWillTake;
+		funnelActualOrder = [exposureEvent, ...applyOrderingStrategy(realSteps, order, config, sequence)];
+	} else {
+		funnelActualOrder = applyOrderingStrategy(
+			funnelStepsUserWillTake,
+			order,
+			config,
+			sequence
+		);
+	}
 
 	// Add timing offsets to events
 	const funnelEventsWithTiming = addTimingOffsets(
@@ -312,6 +328,17 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		}
 	}
 
+	// $experiment_started is a synthetic experiment-assignment marker, NOT a real
+	// pre-auth UI event. Mixpanel keys experiment exposure on the user (distinct_id),
+	// so it must carry user_id even when prepended to an isFirstFunnel (born-in,
+	// pre-auth) sequence — otherwise the exposure is device-only and shows zero
+	// users in experiment reports. Force `both` regardless of auth position.
+	if (expName) {
+		for (let i = 0; i < funnelEventsWithTiming.length; i++) {
+			if (funnelEventsWithTiming[i].event === "$experiment_started") stampingByIndex[i] = 'both';
+		}
+	}
+
 	// Generate actual events with timing
 	const finalEvents = await generateFunnelEvents(
 		context,

package/lib/hook-helpers/cohort.js

@@ -99,6 +99,59 @@ export function countEventsBetween(events, eventA, eventB) {
 	return n;
 }
 
+/**
+ * FNV-1a 32-bit hash of the FULL id string, mapped to [0, 1).
+ *
+ * The determinism primitive for hidden cohorts (v1.6). Hashing the whole id
+ * matters: the `uid.charCodeAt(0) % N` idiom taught in older recipes biases
+ * cohort rates because id alphabets don't cover charcode space uniformly —
+ * hex-ish first chars (0-9, a-f) reach only ~2 of 50 residues under `% 50`,
+ * so a "2% whale cohort" lands anywhere from 0% to ~12% depending on the id
+ * format. FNV-1a diffuses every character, so bucket shares track the target
+ * closely regardless of id alphabet.
+ *
+ * Published FNV-1a 32-bit vectors (draft-eastlake-fnv test suite):
+ * `''` → 0x811c9dc5, `'a'` → 0xe40c292c, `'foobar'` → 0xbf9cf968.
+ *
+ * Uniformity caveat: shares track the target tightly on high-entropy ids —
+ * engine-stamped GUIDs measure 5.0% / 19.7% for 5 / 20 targets at n=10k.
+ * Short SEQUENTIAL synthetic ids (`usr_1`, `usr_2`, …) can drift a few
+ * points (FNV-1a has weak avalanche on short correlated inputs); that's
+ * fine for hook use, where ids are GUIDs.
+ *
+ * @param {string|number} id - User id. Numbers are stringified; null/undefined hash as ''.
+ * @returns {number} Deterministic float in [0, 1).
+ */
+export function hashFloat(id) {
+	const s = String(id ?? '');
+	let h = 0x811c9dc5;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 0x01000193);
+	}
+	return (h >>> 0) / 4294967296; // 2^32 → [0, 1)
+}
+
+/**
+ * Deterministic percent-based cohort membership: true for ~`pct`% of ids.
+ * Same id + same pct always agree, and membership nests — every member of
+ * `hashCohort(id, 5)` is also a member of `hashCohort(id, 20)`, so tiered
+ * cohorts (whale ⊂ engaged) come free.
+ *
+ * @example
+ * // In an everything hook:
+ * const isWhale = hashCohort(uid, 2);        // ~2% of users
+ * if (isWhale && e.event === 'swap') e.trade_amount_usd *= 50;
+ *
+ * @param {string|number} id - User id.
+ * @param {number} pct - Cohort share as a PERCENTAGE in [0, 100].
+ * @returns {boolean}
+ */
+export function hashCohort(id, pct) {
+	if (typeof pct !== 'number' || !Number.isFinite(pct)) return false;
+	return hashFloat(id) * 100 < pct;
+}
+
 /**
  * Profile-based cohort check. Returns true if `profile[segmentKey]` matches one of
  * `segmentValues` (array) or equals the single value passed.

package/lib/hook-helpers/index.js

@@ -16,6 +16,8 @@ export {
 	binUsersByEventInRange,
 	countEventsBetween,
 	userInProfileSegment,
+	hashFloat,
+	hashCohort,
 } from './cohort.js';
 
 export {
@@ -43,3 +45,9 @@ export {
 	isPreAuthEvent,
 	splitByAuth,
 } from './identity.js';
+
+export {
+	applyLifecycleWave,
+	applyPathBias,
+	applySessionShape,
+} from './shape.js';

package/lib/hook-helpers/mutate.js

@@ -25,7 +25,7 @@ import { getChance } from '../utils/utils.js';
  */
 export function cloneEvent(template, overrides = {}) {
 	if (!template) throw new Error('cloneEvent: template is required');
-	return /** @type {any} */ ({ ...template, ...overrides });
+	return /** @type {T} */ ({ ...template, ...overrides });
 }
 
 /**

package/lib/hook-helpers/shape.js

@@ -0,0 +1,319 @@
+/**
+ * Hook helpers — analysis-shape atoms (v1.6).
+ *
+ * Higher-order atoms that sculpt a user's FULL event stream into the shapes
+ * specific Mixpanel analyses read: a lifecycle dormancy-resurrection wave
+ * (HOOKS.md §2.16), a biased Flows path branch (§2.17), and a deterministic
+ * session cadence (§2.13). All three are `everything`-hook-only — they need
+ * the whole stream — and obey the schema-first rules: clones only (spread
+ * from the user's own events, `insert_id` stripped), no fabricated events,
+ * seeded `chance` for all randomness. Timestamp rewrites are safe because
+ * the engine re-derives `session_id` on the final event set (v1.6 P2.1).
+ */
+
+import { getChance } from '../utils/utils.js';
+import { toMs, writeTime } from './_internal.js';
+import { hashFloat } from './cohort.js';
+
+const DAY_MS = 86400000;
+const WEEK_MS = 7 * DAY_MS;
+const MIN_MS = 60000;
+
+/**
+ * Engineer a clean dormancy gap + resurrection burst for one user.
+ *
+ * Drops the user's `valueMomentEvent` events (or ALL events with
+ * `dropAll: true`) inside the window
+ * `[birth + dormantFromDay days, birth + dormantFromDay + dormantDays days]`
+ * (both ends inclusive; birth = the user's earliest event time), then clones
+ * a burst of `resurrectBurst` value-moment events shortly after the window.
+ *
+ * Gap discipline is the whole point: Mixpanel's lifecycle "dormant" state is
+ * an `EqualTo 0` filter over the period (HOOKS.md §2.16) — ONE stray value
+ * moment inside the window destroys the Resurrected classification. The
+ * sweep therefore filters by TIMESTAMP over the array as passed, which
+ * includes events other hooks injected earlier in the same `everything`
+ * pass. Size `dormantDays` to cover at least two whole lifecycle periods so
+ * tiling can't clip the gap.
+ *
+ * Burst template: the surviving `valueMomentEvent` occurrence closest to the
+ * window (preferring one that carries `user_id`). No template → no burst
+ * (schema-first: never fabricate). Burst lands 1-3h after the window end
+ * with 1-10min gaps — one tight resurrection session. If the window extends
+ * past the dataset end, the engine's future-time guard will drop the clones;
+ * keep `dormantFromDay + dormantDays` inside the user's lifespan.
+ *
+ * @param {Array<Object>} events - Full user event array (everything hook).
+ * @param {string} uid - User id; stamped on clones that lack `user_id`.
+ * @param {Object} opts
+ * @param {number} opts.dormantFromDay - Window start, in days after birth.
+ * @param {number} opts.dormantDays - Window length in days.
+ * @param {number} [opts.resurrectBurst=3] - Clones in the post-gap burst.
+ * @param {string} opts.valueMomentEvent - Event name that marks value; the
+ *   drop target (unless `dropAll`) and the burst template.
+ * @param {boolean} [opts.dropAll=false] - Drop ALL events in the window,
+ *   not just value moments.
+ * @returns {Array<Object>} NEW array: filtered + burst clones appended.
+ */
+export function applyLifecycleWave(events, uid, opts) {
+	const { dormantFromDay, dormantDays, resurrectBurst = 3, valueMomentEvent, dropAll = false } = opts || {};
+	if (!Array.isArray(events) || !events.length) return events;
+	if (typeof dormantFromDay !== 'number' || typeof dormantDays !== 'number' || dormantDays <= 0) return events;
+	if (!valueMomentEvent && !dropAll) return events;
+
+	let birthMs = Infinity;
+	for (const ev of events) {
+		if (!ev) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t) && t < birthMs) birthMs = t;
+	}
+	if (!Number.isFinite(birthMs)) return events;
+
+	const windowStart = birthMs + dormantFromDay * DAY_MS;
+	const windowEnd = windowStart + dormantDays * DAY_MS;
+
+	const kept = events.filter(ev => {
+		if (!ev) return false;
+		const t = toMs(ev.time);
+		if (!Number.isFinite(t) || t < windowStart || t > windowEnd) return true;
+		return !(dropAll || ev.event === valueMomentEvent);
+	});
+
+	// Burst template: surviving value moment closest to the window.
+	let template = null;
+	let bestDist = Infinity;
+	for (const ev of kept) {
+		if (!ev || ev.event !== valueMomentEvent) continue;
+		const t = toMs(ev.time);
+		if (!Number.isFinite(t)) continue;
+		const dist = t < windowStart ? windowStart - t : t - windowEnd;
+		// Prefer a template with user_id at equal-or-better distance.
+		if (dist < bestDist || (dist === bestDist && !template?.user_id && ev.user_id)) {
+			bestDist = dist;
+			template = ev;
+		}
+	}
+	if (!template || resurrectBurst <= 0) return kept;
+
+	const chance = getChance();
+	let t = windowEnd + chance.integer({ min: 60 * MIN_MS, max: 180 * MIN_MS });
+	for (let i = 0; i < resurrectBurst; i++) {
+		const clone = { ...template };
+		writeTime(clone, t);
+		delete clone.insert_id;
+		if (!clone.user_id && uid) clone.user_id = uid;
+		kept.push(clone);
+		t += chance.integer({ min: MIN_MS, max: 10 * MIN_MS });
+	}
+	return kept;
+}
+
+/**
+ * Bias a share of users onto a specific Flows path after an anchor event.
+ *
+ * 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.
+ *
+ * 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
+ * clamped to ≥1s because sub-second jitter scrambles step order in the
+ * Sankey; and the engineered branch needs roughly ≥20-25% `share` to survive
+ * Sankey's top-3-per-level pruning. If the user lacks a source event for ANY
+ * path step, the user is skipped entirely — a partial path would pollute the
+ * engineered share.
+ *
+ * @param {Array<Object>} events - Full user event array (everything hook).
+ * @param {string} uid - User id (hashed for the share gate; stamped on
+ *   clones that lack `user_id`).
+ * @param {Object} opts
+ * @param {string} opts.anchor - Event name the path follows.
+ * @param {string[]} opts.path - Ordered event names to inject.
+ * @param {number} opts.share - FRACTION of users in [0, 1] (unlike
+ *   `hashCohort`'s 0-100 pct scale).
+ * @param {[number, number]} [opts.gapSeconds=[2,30]] - Per-step gap range in
+ *   seconds; lower bound clamped to ≥1.
+ * @returns {Array<Object>} The SAME array, augmented in place for selected
+ *   users (engine auto-sorts after the everything hook).
+ */
+export function applyPathBias(events, uid, opts) {
+	const { anchor, path, share, gapSeconds = [2, 30] } = opts || {};
+	if (!Array.isArray(events) || !events.length || !anchor) return events;
+	if (!Array.isArray(path) || !path.length || typeof share !== 'number') return events;
+	if (hashFloat(uid) >= share) return events;
+
+	// First anchor occurrence in TIME order.
+	let anchorMs = Infinity;
+	for (const ev of events) {
+		if (!ev || ev.event !== anchor) continue;
+		const t = toMs(ev.time);
+		if (Number.isFinite(t) && t < anchorMs) anchorMs = t;
+	}
+	if (!Number.isFinite(anchorMs)) return events;
+
+	// One template per path step, from the user's own stream. Any missing →
+	// skip the user entirely.
+	const templates = [];
+	for (const name of path) {
+		const tpl = events.find(e => e && e.event === name);
+		if (!tpl) return events;
+		templates.push(tpl);
+	}
+
+	const lo = Math.max(1, Number(gapSeconds[0]) || 1);
+	const hi = Math.max(lo, Number(gapSeconds[1]) || lo);
+	const chance = getChance();
+	let t = anchorMs;
+	for (const tpl of templates) {
+		t += chance.integer({ min: lo, max: hi }) * 1000;
+		const clone = { ...tpl };
+		writeTime(clone, t);
+		delete clone.insert_id;
+		if (!clone.user_id && uid) clone.user_id = uid;
+		events.push(clone);
+	}
+	return events;
+}
+
+/**
+ * Rewrite a user's event TIMESTAMPS into a deterministic session cadence:
+ * `sessionsPerWeek` clusters per week, each compressed into a
+ * `[start, start + sessionMinutes]` window.
+ *
+ * Retiming only — no events are added or dropped; the same objects are
+ * mutated in place. Session count = `min(sessionsPerWeek × weeks,
+ * ceil(N / eventsPerSession))` (weeks tile forward from the user's first
+ * event): plentiful streams get exactly `sessionsPerWeek` clusters per week
+ * with events split evenly; scarce streams get fewer, `eventsPerSession`-
+ * sized clusters spread across weeks. Session days prefer the user's
+ * ORIGINAL active days in each week, so the engine's day distribution
+ * survives where possible.
+ *
+ * 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);
+ * 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.
+ *
+ * @param {Array<Object>} events - Full user event array (everything hook).
+ * @param {string} uid - Unused for hashing here; kept for atom-signature
+ *   symmetry (cohort gating belongs to the caller — combine with
+ *   `hashCohort`).
+ * @param {Object} 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.
+ * @returns {Array<Object>} The SAME array, timestamps rewritten.
+ */
+export function applySessionShape(events, uid, opts) {
+	const { sessionsPerWeek, eventsPerSession, sessionMinutes } = opts || {};
+	if (!Array.isArray(events) || !events.length) return events;
+	if (!isPos(sessionsPerWeek) || !isPos(eventsPerSession) || !isPos(sessionMinutes)) return events;
+
+	const timed = events.filter(e => e && Number.isFinite(toMs(e.time)));
+	if (!timed.length) return events;
+	timed.sort((a, b) => toMs(a.time) - toMs(b.time));
+
+	const N = timed.length;
+	const firstMs = toMs(timed[0].time);
+	const lastMs = toMs(timed[N - 1].time);
+	const weeks = Math.max(1, Math.ceil((lastMs - firstMs + 1) / WEEK_MS));
+	const numSessions = Math.max(1, Math.min(
+		Math.floor(sessionsPerWeek) * weeks,
+		Math.ceil(N / Math.floor(eventsPerSession)),
+	));
+
+	// Sessions per week and events per session, distributed evenly with the
+	// remainder going to the EARLIEST weeks/sessions (chronological bias).
+	const sessionsInWeek = splitEvenly(numSessions, weeks);
+	const chunkSizes = splitEvenly(N, numSessions).filter(n => n > 0);
+
+	const chance = getChance();
+	const firstDay = Math.floor(firstMs / DAY_MS);
+	const lastDay = Math.floor(lastMs / DAY_MS);
+
+	// 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
+	// only reuse days when a week has more sessions than days.
+	const sessionDays = [];
+	for (let w = 0; w < weeks; w++) {
+		const need = sessionsInWeek[w];
+		if (!need) continue;
+		const weekStartMs = firstMs + w * WEEK_MS;
+		const dayLo = Math.max(firstDay, Math.floor(weekStartMs / DAY_MS));
+		const dayHi = Math.min(lastDay, Math.floor((weekStartMs + WEEK_MS - 1) / DAY_MS));
+		const originalDays = new Set();
+		for (const ev of timed) {
+			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 others = [];
+		for (let d = dayLo; d <= dayHi; d++) if (!originalDays.has(d)) 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
+		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);
+	const perDaySeen = new Map();
+	const sesMs = sessionMinutes * MIN_MS;
+
+	let cursor = 0;
+	for (let s = 0; s < chunkSizes.length; s++) {
+		const size = chunkSizes[s];
+		const chunk = timed.slice(cursor, cursor + size);
+		cursor += size;
+		const day = sessionDays[Math.min(s, sessionDays.length - 1)];
+		const m = perDayCount.get(day) || 1;
+		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 start = center + (q > 0 ? chance.integer({ min: -q, max: q }) : 0);
+
+		if (size === 1) {
+			writeTime(chunk[0], start);
+			continue;
+		}
+		// Even spacing capped at 20min so gap + jitter stays < 30min. Jitter is
+		// also bounded by the window slack so no event escapes [start, start+span].
+		const gap = Math.min(span / (size - 1), 20 * MIN_MS);
+		const slack = span - (size - 1) * gap;
+		const jitterMax = Math.floor(Math.max(0, Math.min(gap * 0.4, 5 * MIN_MS, slack)));
+		for (let i = 0; i < size; i++) {
+			const jitter = i > 0 && jitterMax > 0 ? chance.integer({ min: 0, max: jitterMax }) : 0;
+			writeTime(chunk[i], start + i * gap + jitter);
+		}
+	}
+	return events;
+}
+
+// ── internal helpers ──
+
+function isPos(n) {
+	return typeof n === 'number' && Number.isFinite(n) && n >= 1;
+}
+
+/** Split `total` into `parts` integers, remainder to the earliest parts. */
+function splitEvenly(total, parts) {
+	const base = Math.floor(total / parts);
+	const extra = total % parts;
+	const out = [];
+	for (let i = 0; i < parts; i++) out.push(base + (i < extra ? 1 : 0));
+	return out;
+}

package/lib/hook-patterns/aggregate-per-user-by-bin.js

@@ -5,12 +5,15 @@
  * cohort bin (derived from `count(cohortEvent)`). Used for "Avg Order Value by
  * per-user count of Sessions" Insights views — engaged users skew avg up.
  *
- * Mechanism: classify, then `scalePropertyValue` with `deltas[bin]` as the
- * multiplier. Property must already be defined on the event in the dungeon
- * schema and carry numeric values.
+ * Mechanism: classify — by distinct calendar days of `cohortEvent` by default
+ * (v1.6, matching Mixpanel's frequency axis; see `binByDistinctPeriods`), or
+ * total events with `binBy: 'events'` — then `scalePropertyValue` with
+ * `deltas[bin]` as the multiplier. Property must already be defined on the
+ * event in the dungeon schema and carry numeric values.
  */
 
 import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { binByDistinctPeriods } from '../verify/counting.js';
 import { scalePropertyValue } from '../hook-helpers/mutate.js';
 
 /**
@@ -23,13 +26,18 @@ import { scalePropertyValue } from '../hook-helpers/mutate.js';
  * @param {string} opts.propertyName
  * @param {Record<string, number>} opts.deltas - Bin name → multiplier (1 = no-op,
  *   1.5 = 50% lift, 0.7 = 30% drop).
+ * @param {('events'|'distinctDays')} [opts.binBy='distinctDays'] - Cohort axis.
+ *   `'distinctDays'` (default since v1.6) bins by distinct calendar days with
+ *   `cohortEvent`; `'events'` restores the pre-1.6 total-event-count axis.
  * @returns {{ bin: string|null, scaled: number }}
  */
-export function applyAggregateByBin(events, _profile, { cohortEvent, bins, event, propertyName, deltas }) {
+export function applyAggregateByBin(events, _profile, { cohortEvent, bins, event, propertyName, deltas, binBy = 'distinctDays' }) {
 	if (!events || !cohortEvent || !bins || !event || !propertyName || !deltas) {
 		return { bin: null, scaled: 0 };
 	}
-	const bin = binUsersByEventCount(events, cohortEvent, bins);
+	const bin = binBy === 'events'
+		? binUsersByEventCount(events, cohortEvent, bins)
+		: binByDistinctPeriods(events, cohortEvent, bins, 'day');
 	if (!bin) return { bin: null, scaled: 0 };
 	const factor = deltas[bin];
 	if (typeof factor !== 'number' || factor === 1) return { bin, scaled: 0 };

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

@@ -1,72 +1,74 @@
 /**
- * Pattern: Attribute conversions by source.
+ * Pattern: Bias attribution by overwriting engine-stamped touches.
  *
- * For each user, copy a property value from a "touch" event onto a downstream
- * "conversion" event so Mixpanel's "Conversions by Source" attribution analysis
- * shows the configured weighted distribution. The pattern doesn't invent the
- * source distribution — it preserves whatever the touch events already carry —
- * BUT it lets you bias the conversion completion rate per source via `weights`
- * (probability of stamping = weight ÷ max(weight) ).
+ * v1.6 rewrite (recipe 4.26 as code). Under v1.5+ the ENGINE stamps UTMs on
+ * up to `maxTouchpointsPerUser` events per user (default 10), sampled across
+ * the user's lifetime. Attribution hooks must therefore OVERWRITE the values
+ * on already-stamped events, not stamp fresh ones: FIRST/LAST attribution is
+ * UNCAPPED (hard LIMIT-1 statements, whoval/read.cpp:173-192 — the 10-cap
+ * only serves multi-touch list models), so a fresh stamp EARLIER than the
+ * engine's first touch silently WINS first-touch instead of biasing it, and
+ * fresh stamps change the user's total touch count (HOOKS.md principle 29).
  *
- * Mechanism: walk the user's event stream; when a `downstreamEvent` event fires,
- * look back at the most-recent (or first) `sourceEvent` and copy
- * `sourceEvent[sourceProperty]` onto the downstream event. Skip stamping
- * probabilistically per `weights[sourceValue]`.
+ * Mechanism: collect the user's engine-stamped touches (events where
+ * `property` is non-null), sort by time, and overwrite the touch the chosen
+ * attribution model reads — the FIRST touch for `firstTouch`, the LAST for
+ * `lastTouch`, or both — with a weighted pick from `weights` (seeded
+ * `chance.weighted`, reproducible per run).
  *
- * Identity & schema: the destination property must already exist on
- * `downstreamEvent` in the dungeon schema (we OVERWRITE the value, not invent it).
+ * Schema-first: only events the engine already stamped are touched; the
+ * pattern never adds `property` to an unstamped event, so total touch count
+ * is unchanged.
  */
 
+import { getChance } from '../utils/utils.js';
+
 /**
- * @param {Array<Object>} events - User's event stream (mutated in place).
+ * @param {Array<Object>} events - User's event stream (stamped touches
+ *   mutated in place). Call from the `everything` hook — the engine's UTM
+ *   stamping has already run by then.
  * @param {Object} _profile
  * @param {Object} opts
- * @param {string} opts.sourceEvent - Event whose property we copy from.
- * @param {string} opts.sourceProperty - Property on `sourceEvent` to copy.
- * @param {string} opts.downstreamEvent - Event whose property we overwrite.
- * @param {string} [opts.downstreamProperty] - Defaults to `sourceProperty`.
- * @param {Record<string, number>} opts.weights - Source value → relative weight
- *   (probability of stamping = weight / maxWeight; missing entries = 0).
- * @param {'firstTouch'|'lastTouch'} [opts.model] - Default 'firstTouch'.
- * @returns {{ stamped: number, skipped: number }}
+ * @param {Record<string, number>} opts.weights - Attribution value → relative
+ *   weight (e.g. `{ google: 10, facebook: 5, twitter: 1 }`). The overwrite
+ *   value is drawn with probability weight ÷ sum(weights).
+ * @param {string} [opts.property='utm_source'] - Engine-stamped property to
+ *   overwrite.
+ * @param {('firstTouch'|'lastTouch'|'both')} [opts.model='firstTouch'] -
+ *   Which stamped touch to overwrite: the one Mixpanel's first-touch model
+ *   reads, the last-touch one, or both.
+ *
+ *   CAVEAT (fix-round C16): `lastTouch`/`both` overwrite the user's
+ *   LIFETIME-last stamped touch, but Mixpanel's last-touch model reads the
+ *   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.
+ * @returns {{ overwritten: number, touches: number }} `touches` = stamped
+ *   events found; `overwritten` = touches whose value was replaced.
  */
 export function applyAttributedBySource(events, _profile, opts) {
-	const { sourceEvent, sourceProperty, downstreamEvent, downstreamProperty, weights, model = 'firstTouch' } = opts || {};
-	if (!events || !sourceEvent || !sourceProperty || !downstreamEvent || !weights) {
-		return { stamped: 0, skipped: 0 };
-	}
-	const destProp = downstreamProperty || sourceProperty;
-	const sorted = events.slice().sort((a, b) => Date.parse(a.time) - Date.parse(b.time));
-	const maxWeight = Math.max(...Object.values(weights), 0);
-	if (maxWeight <= 0) return { stamped: 0, skipped: 0 };
+	const { weights, property = 'utm_source', model = 'firstTouch' } = opts || {};
+	if (!events || !events.length || !weights) return { overwritten: 0, touches: 0 };
+	const values = Object.keys(weights).filter(k => typeof weights[k] === 'number' && weights[k] > 0);
+	if (!values.length) return { overwritten: 0, touches: 0 };
 
-	let stamped = 0;
-	let skipped = 0;
-	const touches = []; // accumulated source events in time order
-	for (const ev of sorted) {
-		if (!ev) continue;
-		if (ev.event === sourceEvent && ev[sourceProperty] !== undefined) {
-			touches.push(ev);
-			continue;
-		}
-		if (ev.event === downstreamEvent && touches.length) {
-			const touch = model === 'lastTouch' ? touches[touches.length - 1] : touches[0];
-			const val = touch[sourceProperty];
-			const w = weights[val] || 0;
-			const prob = w / maxWeight; // 0..1
-			// Deterministic per-user pseudo-RNG keyed on the downstream event's
-			// insert_id (or time fallback) — keeps verification reproducible.
-			const seed = ev.insert_id || ev.time || '';
-			const r = simpleHashFloat(String(seed));
-			if (r < prob) {
-				ev[destProp] = val;
-				stamped++;
-			} else {
-				skipped++;
-			}
-		}
+	const stamped = events
+		.filter(e => e && e[property] !== undefined && e[property] !== null)
+		.sort((a, b) => Date.parse(a.time) - Date.parse(b.time));
+	if (!stamped.length) return { overwritten: 0, touches: 0 };
+
+	const chance = getChance();
+	const targets = new Set();
+	if (model === 'firstTouch' || model === 'both') targets.add(stamped[0]);
+	if (model === 'lastTouch' || model === 'both') targets.add(stamped[stamped.length - 1]);
+
+	let overwritten = 0;
+	for (const touch of targets) {
+		touch[property] = chance.weighted(values, values.map(v => weights[v]));
+		overwritten++;
 	}
-	return { stamped, skipped };
+	return { overwritten, touches: stamped.length };
 }
-
-import { simpleHashFloat } from '../hook-helpers/_internal.js';