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

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

@@ -0,0 +1,72 @@
+/**
+ * Pattern: Attribute conversions by source.
+ *
+ * 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) ).
+ *
+ * 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]`.
+ *
+ * Identity & schema: the destination property must already exist on
+ * `downstreamEvent` in the dungeon schema (we OVERWRITE the value, not invent it).
+ */
+
+/**
+ * @param {Array<Object>} events - User's event stream (mutated in place).
+ * @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 }}
+ */
+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 };
+
+	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++;
+			}
+		}
+	}
+	return { stamped, skipped };
+}
+
+import { simpleHashFloat } from '../hook-helpers/_internal.js';

package/lib/hook-patterns/frequency-by-frequency.js

@@ -0,0 +1,46 @@
+/**
+ * Pattern: Frequency × Frequency.
+ *
+ * Engineers the joint distribution of `count(metricEvent)` × `count(cohortEvent)`
+ * per user, so Mixpanel's "Frequency Distribution of A by per-user count of B"
+ * Insights view shows a deliberate shape (e.g., users with 5–20 cohort events
+ * have 2x the metric event count of users with <5).
+ *
+ * Mechanism: classify the user into a bin based on their `cohortEvent` count,
+ * then `scaleEventCount(events, targetEvent, multipliers[bin])` to scale that
+ * user's count of the target event up or down.
+ *
+ * Identity & schema constraints:
+ * - Operates on the user's full event stream — call from the `everything` hook.
+ * - Does NOT add new properties; uses existing event names defined in the dungeon
+ *   schema.
+ * - Cloned events have their `insert_id` stripped (mutate.scaleEventCount handles
+ *   that), so the engine's batch writer can re-stamp them downstream.
+ */
+
+import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { scaleEventCount } from '../hook-helpers/mutate.js';
+
+/**
+ * @param {Array<Object>} events - User's event stream (mutated in place).
+ * @param {Object} _profile - User profile (unused, kept for API symmetry).
+ * @param {Object} opts
+ * @param {string} opts.cohortEvent - Event whose per-user count classifies the user.
+ * @param {Record<string, [number, number]>} opts.bins - Bin name → [lo, hi).
+ * @param {string} opts.targetEvent - Event whose count is scaled per bin.
+ * @param {Record<string, number>} opts.multipliers - Bin name → multiplier (1 = no-op,
+ *   2 = double, 0.5 = halve). Bins absent from this map use multiplier 1.
+ * @returns {{ bin: string|null, delta: number }} Bin assigned + signed delta from
+ *   scaleEventCount (positive = clones added; negative = events dropped).
+ */
+export function applyFrequencyByFrequency(events, _profile, { cohortEvent, bins, targetEvent, multipliers }) {
+	if (!events || !cohortEvent || !bins || !targetEvent || !multipliers) {
+		return { bin: null, delta: 0 };
+	}
+	const bin = binUsersByEventCount(events, cohortEvent, bins);
+	if (!bin) return { bin: null, delta: 0 };
+	const factor = multipliers[bin];
+	if (typeof factor !== 'number' || factor === 1) return { bin, delta: 0 };
+	const delta = scaleEventCount(events, targetEvent, factor);
+	return { bin, delta };
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Pattern: Funnel Frequency Breakdown.
+ *
+ * Inside a `funnel-post` hook, vary the user's completion of the funnel by their
+ * count of `cohortEvent` (anywhere in the dataset, not just the funnel). Used
+ * when you want Mixpanel's funnel report — broken down by per-user count of an
+ * activity event — to show e.g. "users who did 5+ X are 1.4x as likely to
+ * complete this funnel."
+ *
+ * Mechanism: for users in a "drop-prone" bin, drop the funnel's final step
+ * event(s) per the `dropMultipliers` config (1 = drop none, 0 = drop all).
+ *
+ * Schema-first: does not add new event properties or invent events. Operates on
+ * the funnelEvents array passed by the funnel-post hook.
+ */
+
+import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { dropEventsWhere } from '../hook-helpers/mutate.js';
+
+/**
+ * @param {Array<Object>} allUserEvents - Full per-user event history (read-only;
+ *   used to count `cohortEvent`). When called inside `funnel-post`, derive this
+ *   from `meta.profile` or pass the user's accumulated events from a closure.
+ *   When `null`, falls back to counting cohortEvent inside `funnelEvents`.
+ * @param {Object} _profile
+ * @param {Array<Object>} funnelEvents - Funnel events produced by `makeFunnel`
+ *   (mutated in place).
+ * @param {Object} opts
+ * @param {string} opts.cohortEvent
+ * @param {Record<string, [number, number]>} opts.bins
+ * @param {Record<string, number>} opts.dropMultipliers - Bin name → keep-rate (0..1)
+ *   for the FINAL step event. 1 = always keep, 0 = always drop.
+ * @param {string} [opts.finalStep] - Event name of the final step. Defaults to the
+ *   last event in `funnelEvents` (in time order).
+ * @returns {{ bin: string|null, droppedFinal: boolean }}
+ */
+export function applyFunnelFrequencyBreakdown(allUserEvents, _profile, funnelEvents, opts) {
+	const { cohortEvent, bins, dropMultipliers, finalStep } = opts || {};
+	if (!funnelEvents || !cohortEvent || !bins || !dropMultipliers) {
+		return { bin: null, droppedFinal: false };
+	}
+	const sourceForBin = allUserEvents || funnelEvents;
+	const bin = binUsersByEventCount(sourceForBin, cohortEvent, bins);
+	if (!bin) return { bin: null, droppedFinal: false };
+	const keepRate = dropMultipliers[bin];
+	if (typeof keepRate !== 'number' || keepRate >= 1) return { bin, droppedFinal: false };
+
+	// Identify the final step. If finalStep is named, use it; otherwise pick the
+	// latest-in-time event in the funnel as the final step.
+	let stepName = finalStep;
+	if (!stepName) {
+		const sorted = funnelEvents.slice().sort((a, b) => Date.parse(a.time) - Date.parse(b.time));
+		stepName = sorted.length ? sorted[sorted.length - 1].event : null;
+	}
+	if (!stepName) return { bin, droppedFinal: false };
+
+	// Coin-flip drop using a deterministic-ish heuristic — this is called from a
+	// non-RNG context (funnel-post), so use Math.random would break determinism.
+	// Instead, use a hash on the funnel's first event's insert_id (deterministic
+	// per-call) modulo 1000 / 1000 vs. (1 - keepRate). For simplicity we use
+	// chance from utils when available.
+	const dropProb = 1 - keepRate;
+	const seed = funnelEvents[0] && (funnelEvents[0].insert_id || funnelEvents[0].time) || '';
+	const det = simpleHashFloat(String(seed));
+	if (det < dropProb) {
+		const before = funnelEvents.length;
+		dropEventsWhere(funnelEvents, e => e && e.event === stepName);
+		return { bin, droppedFinal: funnelEvents.length < before };
+	}
+	return { bin, droppedFinal: false };
+}
+
+import { simpleHashFloat } from '../hook-helpers/_internal.js';

package/lib/hook-patterns/index.js

@@ -0,0 +1,14 @@
+/**
+ * @ak--47/dungeon-master/hook-patterns — Phase 4 pattern barrel.
+ *
+ * Patterns are higher-level recipes built on Phase 3 atoms. Each one engineers
+ * the kind of distribution / table shape Mixpanel surfaces in a specific report.
+ * Pair with `verifyDungeon` + `emulateBreakdown` from `../verify` to assert the
+ * pattern is producing what you expect.
+ */
+
+export { applyFrequencyByFrequency } from './frequency-by-frequency.js';
+export { applyFunnelFrequencyBreakdown } from './funnel-frequency-breakdown.js';
+export { applyAggregateByBin } from './aggregate-per-user-by-bin.js';
+export { applyTTCBySegment } from './time-to-convert-by-segment.js';
+export { applyAttributedBySource } from './attributed-by-source.js';

package/lib/hook-patterns/time-to-convert-by-segment.js

@@ -0,0 +1,41 @@
+/**
+ * Pattern: Time to Convert, broken down by user segment.
+ *
+ * Inside a `funnel-post` hook, scale the funnel's time-to-convert by a factor
+ * keyed off of a user-profile property value (e.g., trial users convert 3x
+ * slower than enterprise). Lets Mixpanel's TTC funnel report — broken down by
+ * a profile property — show a deliberate spread.
+ *
+ * Mechanism: read `profile[segmentKey]`, look up the multiplier in `factors`,
+ * and `scaleFunnelTTC(funnelEvents, factor)`. The first event's time is the
+ * anchor (unchanged); subsequent steps' offsets from it are scaled.
+ *
+ * Caveat: Mixpanel's "Time to Convert" funnel report uses the time between the
+ * FIRST event of step A and the FIRST event of step B per user, not the actual
+ * gap inside any one funnel run. The scaled funnel run will reflect in TTC only
+ * when this funnel is the user's first occurrence of those steps — which it is
+ * for an `isFirstFunnel`. For usage funnels, document this caveat to authors.
+ */
+
+import { scaleFunnelTTC } from '../hook-helpers/timing.js';
+
+/**
+ * @param {Array<Object>} funnelEvents - Mutated in place.
+ * @param {Object} profile - The user's profile (must contain `segmentKey`).
+ * @param {Object} opts
+ * @param {string} opts.segmentKey - Profile property name to look up.
+ * @param {Record<string, number>} opts.factors - Profile-value → TTC factor.
+ * @returns {{ segmentValue: any, factor: number, shifted: number }}
+ */
+export function applyTTCBySegment(funnelEvents, profile, { segmentKey, factors }) {
+	if (!funnelEvents || !funnelEvents.length || !profile || !segmentKey || !factors) {
+		return { segmentValue: null, factor: 1, shifted: 0 };
+	}
+	const segmentValue = profile[segmentKey];
+	const factor = factors[segmentValue];
+	if (typeof factor !== 'number' || factor === 1) {
+		return { segmentValue, factor: 1, shifted: 0 };
+	}
+	const shifted = scaleFunnelTTC(funnelEvents, factor);
+	return { segmentValue, factor, shifted };
+}