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

package/lib/hook-helpers/inject.js

@@ -0,0 +1,99 @@
+/**
+ * Hook helpers — injection atoms.
+ *
+ * Splice cloned events into a user's event stream. CRITICAL: per Phase 1 schema-first
+ * rules, `templateEvent` should be an existing event from the stream (not a
+ * fabricated one), so the injected event carries the dungeon's defined schema. Use
+ * `cloneEvent` from `mutate.js` if you want the override semantics explicit.
+ *
+ * Randomness uses the seeded `chance` instance from utils so dungeons stay reproducible.
+ */
+
+import { getChance } from '../utils/utils.js';
+import { toMs, writeTime } from './_internal.js';
+
+/**
+ * Splice a cloned event into `events` immediately after `sourceEvent`. Time is
+ * `sourceEvent.time + gapMs`; `overrides` are shallow-merged on top of `templateEvent`.
+ * If `sourceEvent` is not in `events` (caller passed a stale ref), the new event is
+ * pushed to the end instead. Returns the newly created event.
+ *
+ * @param {Array<Object>} events
+ * @param {{time: string|number}} sourceEvent
+ * @param {Object} templateEvent
+ * @param {number} gapMs
+ * @param {Object} [overrides]
+ * @returns {Object|null}
+ */
+export function injectAfterEvent(events, sourceEvent, templateEvent, gapMs, overrides = {}) {
+	if (!events || !sourceEvent || !templateEvent) return null;
+	const baseT = toMs(sourceEvent.time);
+	if (!Number.isFinite(baseT)) return null;
+	const newEv = { ...templateEvent, ...overrides };
+	writeTime(newEv, baseT + gapMs);
+	const idx = events.indexOf(sourceEvent);
+	if (idx >= 0) events.splice(idx + 1, 0, newEv);
+	else events.push(newEv);
+	return newEv;
+}
+
+/**
+ * Splice a cloned event between the first `eventA` and the first `eventB` after
+ * it (in time order), at the midpoint of the gap. Returns the new event, or null
+ * if either anchor is missing.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventA
+ * @param {string} eventB
+ * @param {Object} templateEvent
+ * @param {Object} [overrides]
+ * @returns {Object|null}
+ */
+export function injectBetween(events, eventA, eventB, templateEvent, overrides = {}) {
+	if (!events || !eventA || !eventB || !templateEvent) return null;
+	const sorted = events.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const aIdx = sorted.findIndex(e => e && e.event === eventA);
+	if (aIdx < 0) return null;
+	const a = sorted[aIdx];
+	const b = sorted.slice(aIdx + 1).find(e => e && e.event === eventB);
+	if (!b) return null;
+	const aT = toMs(a.time);
+	const bT = toMs(b.time);
+	if (!Number.isFinite(aT) || !Number.isFinite(bT)) return null;
+	const newEv = { ...templateEvent, ...overrides };
+	writeTime(newEv, (aT + bT) / 2);
+	const bIdxOrig = events.indexOf(b);
+	if (bIdxOrig >= 0) events.splice(bIdxOrig, 0, newEv);
+	else events.push(newEv);
+	return newEv;
+}
+
+/**
+ * Inject `count` clones of `templateEvent` into `events`, distributed uniformly at
+ * random within `[anchorTime - spreadMs, anchorTime + spreadMs]`. Uses the seeded
+ * RNG. Returns the array of newly created events.
+ *
+ * @param {Array<Object>} events
+ * @param {Object} templateEvent
+ * @param {number} count
+ * @param {string|number} anchorTime
+ * @param {number} spreadMs
+ * @param {Object} [overrides]
+ * @returns {Object[]}
+ */
+export function injectBurst(events, templateEvent, count, anchorTime, spreadMs, overrides = {}) {
+	if (!events || !templateEvent || count <= 0 || typeof spreadMs !== 'number') return [];
+	const anchorMs = toMs(anchorTime);
+	if (!Number.isFinite(anchorMs)) return [];
+	const chance = getChance();
+	const created = [];
+	for (let i = 0; i < count; i++) {
+		const offset = chance.floating({ min: -spreadMs, max: spreadMs });
+		const newEv = { ...templateEvent, ...overrides };
+		writeTime(newEv, anchorMs + offset);
+		events.push(newEv);
+		created.push(newEv);
+	}
+	return created;
+}
+

package/lib/hook-helpers/mutate.js

@@ -0,0 +1,151 @@
+/**
+ * Hook helpers — mutation atoms.
+ *
+ * In-place mutation primitives that hooks call to scale, drop, or modify events.
+ * These are deliberately tiny and composable so patterns built on top stay readable.
+ *
+ * Randomness uses the seeded `chance` instance from `lib/utils/utils.js` — never
+ * `Math.random()` — so dungeon runs stay reproducible.
+ */
+
+import { toMs } from './_internal.js';
+
+import { getChance } from '../utils/utils.js';
+
+/**
+ * Returns a new event object built from `template` with `overrides` shallow-merged
+ * on top. Mandatory replacement fields (time, user_id, etc.) belong in `overrides`.
+ * The schema-first hook rule still applies: only properties that already exist in
+ * the dungeon's event config should be set in `overrides`.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} template
+ * @param {Partial<T>} [overrides]
+ * @returns {T}
+ */
+export function cloneEvent(template, overrides = {}) {
+	if (!template) throw new Error('cloneEvent: template is required');
+	return /** @type {any} */ ({ ...template, ...overrides });
+}
+
+/**
+ * Drop events where `predicate(event, index)` is truthy. Mutates `events` in place.
+ *
+ * @param {Array<Object>} events
+ * @param {(event: Object, index: number) => boolean} predicate
+ * @returns {number} Number of events dropped.
+ */
+export function dropEventsWhere(events, predicate) {
+	if (!events || typeof predicate !== 'function') return 0;
+	let dropped = 0;
+	for (let i = events.length - 1; i >= 0; i--) {
+		if (predicate(events[i], i)) {
+			events.splice(i, 1);
+			dropped++;
+		}
+	}
+	return dropped;
+}
+
+/**
+ * Scale the count of events with name `eventName` in `events` by `factor`. Mutates
+ * `events` in place.
+ *
+ * - factor > 1: clones existing matches with small monotonic time offsets (1s steps)
+ *   so duplicates land just after their source. Returns positive integer = clones added.
+ * - factor < 1: drops matches at random using the seeded RNG. Returns negative
+ *   integer = -dropped.
+ * - factor === 1 or no matches: no-op, returns 0.
+ *
+ * Note: the `insert_id` of cloned events is removed so a downstream pass can
+ * regenerate it (otherwise Mixpanel will dedupe on import).
+ *
+ * @param {Array<{event:string,time:string|number,insert_id?:string}>} events
+ * @param {string} eventName
+ * @param {number} factor
+ * @returns {number}
+ */
+export function scaleEventCount(events, eventName, factor) {
+	if (!events || !eventName || typeof factor !== 'number' || factor === 1) return 0;
+	if (factor > 1) {
+		const matches = events.filter(e => e && e.event === eventName);
+		if (!matches.length) return 0;
+		const additionalNeeded = Math.round(matches.length * (factor - 1));
+		let added = 0;
+		for (let i = 0; i < additionalNeeded; i++) {
+			const src = matches[i % matches.length];
+			const baseMs = toMs(src.time);
+			const newTime = Number.isFinite(baseMs)
+				? new Date(baseMs + (i + 1) * 1000).toISOString()
+				: src.time;
+			const clone = { ...src, time: newTime };
+			delete clone.insert_id;
+			events.push(clone);
+			added++;
+		}
+		return added;
+	}
+	// factor < 1 → drop at random
+	const chance = getChance();
+	const dropProb = Math.max(0, Math.min(1, 1 - factor));
+	let dropped = 0;
+	for (let i = events.length - 1; i >= 0; i--) {
+		const ev = events[i];
+		if (ev && ev.event === eventName && chance.bool({ likelihood: dropProb * 100 })) {
+			events.splice(i, 1);
+			dropped++;
+		}
+	}
+	return -dropped;
+}
+
+/**
+ * For each event in `events` matching `predicate`, multiply the numeric value at
+ * `propertyName` by `factor`. Skips events where the property is missing or non-numeric.
+ *
+ * @param {Array<Object>} events
+ * @param {(event: Object) => boolean} predicate
+ * @param {string} propertyName
+ * @param {number} factor
+ * @returns {number} Number of events whose property was scaled.
+ */
+export function scalePropertyValue(events, predicate, propertyName, factor) {
+	if (!events || typeof predicate !== 'function' || !propertyName || typeof factor !== 'number') return 0;
+	let count = 0;
+	for (const ev of events) {
+		if (!ev || !predicate(ev)) continue;
+		const v = ev[propertyName];
+		if (typeof v === 'number') {
+			ev[propertyName] = v * factor;
+			count++;
+		}
+	}
+	return count;
+}
+
+/**
+ * Shift a single event's `time` by `deltaMs` milliseconds. Mutates the event in place.
+ * Accepts ISO string or numeric (unix ms / unix seconds) inputs and writes back in
+ * the original format.
+ *
+ * @param {{time: string|number}} event
+ * @param {number} deltaMs
+ * @returns {Object} The mutated event.
+ */
+export function shiftEventTime(event, deltaMs) {
+	if (!event || event.time === undefined || event.time === null) return event;
+	if (typeof event.time === 'string') {
+		const ms = Date.parse(event.time);
+		if (Number.isFinite(ms)) {
+			event.time = new Date(ms + deltaMs).toISOString();
+		}
+	} else if (typeof event.time === 'number') {
+		// Preserve scale (seconds vs ms).
+		if (event.time > 1e12) {
+			event.time = event.time + deltaMs;
+		} else {
+			event.time = event.time + deltaMs / 1000;
+		}
+	}
+	return event;
+}

package/lib/hook-helpers/timing.js

@@ -0,0 +1,99 @@
+/**
+ * Hook helpers — timing atoms.
+ *
+ * Adjust gaps between specific events (or the whole funnel TTC) and detect ordered
+ * sequences within a maximum gap. All times are normalized to unix milliseconds
+ * internally; ISO strings are written back when the source was a string.
+ */
+
+import { toMs, writeTime } from './_internal.js';
+
+/**
+ * Find the FIRST `eventA` in time order, then the FIRST `eventB` after it, then
+ * scale the time gap between them by `factor`. The B event is mutated to the new
+ * timestamp (the A event is unchanged). Returns true on success, false if either
+ * anchor is missing.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string} eventA
+ * @param {string} eventB
+ * @param {number} factor - 0.5 halves the gap, 2.0 doubles it.
+ * @returns {boolean}
+ */
+export function scaleTimingBetween(events, eventA, eventB, factor) {
+	if (!events || !eventA || !eventB || typeof factor !== 'number') return false;
+	const sorted = events.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const aIdx = sorted.findIndex(e => e && e.event === eventA);
+	if (aIdx < 0) return false;
+	const tail = sorted.slice(aIdx + 1);
+	const b = tail.find(e => e && e.event === eventB);
+	if (!b) return false;
+	const a = sorted[aIdx];
+	const aT = toMs(a.time);
+	const bT = toMs(b.time);
+	if (!Number.isFinite(aT) || !Number.isFinite(bT)) return false;
+	const newBT = aT + (bT - aT) * factor;
+	writeTime(b, newBT);
+	return true;
+}
+
+/**
+ * Scale the time-to-convert (TTC) of an entire funnel. Each event's offset from
+ * the funnel's first event is multiplied by `factor`. Mutates events in place.
+ *
+ * @param {Array<{event:string,time:string|number}>} funnelEvents
+ * @param {number} factor
+ * @returns {number} Count of events shifted (excludes the anchor).
+ */
+export function scaleFunnelTTC(funnelEvents, factor) {
+	if (!funnelEvents || !funnelEvents.length || typeof factor !== 'number') return 0;
+	const sorted = funnelEvents.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const baseT = toMs(sorted[0].time);
+	if (!Number.isFinite(baseT)) return 0;
+	let n = 0;
+	for (const ev of funnelEvents) {
+		if (ev === sorted[0]) continue;
+		const t = toMs(ev.time);
+		if (!Number.isFinite(t)) continue;
+		writeTime(ev, baseT + (t - baseT) * factor);
+		n++;
+	}
+	return n;
+}
+
+/**
+ * Detect the FIRST occurrence of an ordered sequence of event names within a
+ * maximum gap. Returns the matching events (in order) or `null` if no run satisfies
+ * the constraint. The gap is checked between *consecutive matched* events, not
+ * between any two events in the stream.
+ *
+ * @param {Array<{event:string,time:string|number}>} events
+ * @param {string[]} eventNames - Ordered sequence of event names to match.
+ * @param {number} maxGapMin - Maximum allowable gap between consecutive matched events, in minutes.
+ * @returns {Array<Object>|null}
+ */
+export function findFirstSequence(events, eventNames, maxGapMin) {
+	if (!events || !eventNames || !eventNames.length || typeof maxGapMin !== 'number') return null;
+	const sorted = events.slice().sort((x, y) => toMs(x && x.time) - toMs(y && y.time));
+	const maxGapMs = maxGapMin * 60 * 1000;
+	for (let i = 0; i < sorted.length; i++) {
+		const head = sorted[i];
+		if (!head || head.event !== eventNames[0]) continue;
+		const matched = [head];
+		let lastT = toMs(head.time);
+		let stepIdx = 1;
+		for (let j = i + 1; j < sorted.length && stepIdx < eventNames.length; j++) {
+			const cur = sorted[j];
+			if (!cur || cur.time === undefined) continue;
+			const t = toMs(cur.time);
+			if (!Number.isFinite(t) || t - lastT > maxGapMs) break;
+			if (cur.event === eventNames[stepIdx]) {
+				matched.push(cur);
+				lastT = t;
+				stepIdx++;
+			}
+		}
+		if (matched.length === eventNames.length) return matched;
+	}
+	return null;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Pattern: Aggregate per User, by cohort bin.
+ *
+ * Adjusts the average value of a numeric event property based on the user's
+ * 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.
+ */
+
+import { binUsersByEventCount } from '../hook-helpers/cohort.js';
+import { scalePropertyValue } from '../hook-helpers/mutate.js';
+
+/**
+ * @param {Array<Object>} events - User's event stream (mutated in place).
+ * @param {Object} _profile
+ * @param {Object} opts
+ * @param {string} opts.cohortEvent
+ * @param {Record<string, [number, number]>} opts.bins
+ * @param {string} opts.event - Event whose property is scaled.
+ * @param {string} opts.propertyName
+ * @param {Record<string, number>} opts.deltas - Bin name → multiplier (1 = no-op,
+ *   1.5 = 50% lift, 0.7 = 30% drop).
+ * @returns {{ bin: string|null, scaled: number }}
+ */
+export function applyAggregateByBin(events, _profile, { cohortEvent, bins, event, propertyName, deltas }) {
+	if (!events || !cohortEvent || !bins || !event || !propertyName || !deltas) {
+		return { bin: null, scaled: 0 };
+	}
+	const bin = binUsersByEventCount(events, cohortEvent, bins);
+	if (!bin) return { bin: null, scaled: 0 };
+	const factor = deltas[bin];
+	if (typeof factor !== 'number' || factor === 1) return { bin, scaled: 0 };
+	const scaled = scalePropertyValue(events, e => e && e.event === event, propertyName, factor);
+	return { bin, scaled };
+}

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 };
+}