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

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.4.0 — 2026-05-03
+
+The "identity model + hook verification" release. Users get multi-device identity, declarative experiments, and a complete hook authoring pipeline with verification. All 20 vertical dungeons upgraded and verified.
+
+### Added
+
+- **Identity model.** Three additive knobs for realistic user/device identity:
+  - `avgDevicePerUser: N` — per-user device pool sized by normal distribution; sessions are sticky to a device drawn from the pool.
+  - `EventConfig.isAuthEvent: true` — marks the sign-up/login event as the identity stitch point. Pre-auth funnel steps get `device_id` only; the stitch event gets both; post-auth gets `user_id` only.
+  - `Funnel.attempts: { min, max, conversionRate? }` — failed-prior-attempt retries before final conversion. Failed attempts truncate before `isAuthEvent`.
+  - `EventConfig.isAttributionEvent: true` — opt-in UTM stamping on specific events (replaces blanket 25% of all events).
+- **Declarative experiments.** `Funnel.experiment: { name, variants, startDaysBeforeEnd }` on any funnel. Engine handles variant assignment (deterministic hash), `$experiment_started` events, and conversion/TTC multipliers. Hooks read `meta.experiment` for variant-specific downstream effects.
+- **Hook helpers** (`@ak--47/dungeon-master/hook-helpers`). 14 composable atoms across 5 modules: cohort binning, event mutation, timing manipulation, event injection, and identity partitioning. Full JSDoc on each atom.
+- **Hook patterns** (`@ak--47/dungeon-master/hook-patterns`). 5 high-level recipes mapping 1:1 to Mixpanel analysis types: frequency-by-frequency, funnel-frequency breakdown, aggregate-by-bin, TTC-by-segment, attributed-by-source.
+- **Verification pipeline** (`@ak--47/dungeon-master/verify`). `emulateBreakdown` re-derives Mixpanel breakdown tables from raw events. `verifyDungeon` runs CI-style assertions with NAILED/STRONG/WEAK/NONE/INVERSE scoring.
+- **`HOOKS.md` encyclopedia.** 23 production-proven hook recipes with code, Mixpanel report instructions, and adaptation notes. 14 core principles. Phase 3/4 atom and pattern reference tables.
+- **`EmulateOptions` type.** Previously referenced but undefined in `types.d.ts`. Now fully typed with per-analysis-type field documentation.
+- **Skills pipeline.** `/create-dungeon` (schema only) → `/write-hooks` (engineer patterns) → `/verify-hooks` (DuckDB verification with 5-tier scoring). Each skill is self-contained with reference examples.
+
+### Changed
+
+- **Legacy 42% per-event `user_id` dice removed.** Every event now gets `user_id` by default (unless in a pre-auth funnel step). More correct for Mixpanel identity.
+- **`isStrictEvent` events excluded from standalone generation.** They appear only in explicitly-defined funnels — cleaner data for events like "application approved" that shouldn't exist outside funnel context.
+- **`insert_id` uses `crypto.randomUUID()`.** Eliminates hash collisions. Non-deterministic but irrelevant for analytics.
+- **Funnel-pre hooks have final authority.** Persona and world-event modifiers apply before the hook — hooks can override everything.
+- **Experiment variant assignment is deterministic per user** (hash-based, not random per funnel run).
+- **All 20 vertical dungeons upgraded to version 2.** Identity model adopted, dates standardized (120-day window), temporal hooks migrated to `everything`, deprecated features replaced in hooks, all hooks verified STRONG or NAILED.
+- **`types.d.ts` expanded.** JSDoc warnings on `HookMetaEvent` (temporal unreliability), hook ordering note on `HookMetaEverything`, `numDays` 3-mode resolution docs, `isStrictEvent` clarification.
+
+### Removed (silently ignored)
+
+- `subscription`, `attribution`, `geo`, `features`, `anomalies` config keys. Engine strips them with one deprecation warning per dungeon and continues. Recreate these patterns via hooks — see `HOOKS.md` recipes 3.22 (deprecated feature replacement) and the `write-hooks` skill.
+
+### Key Learnings from 20-Dungeon Eval
+
+These patterns are documented in `HOOKS.md` principles 7-14 and the skill REV 10 sections:
+
+1. **Temporal hooks belong in `everything`, not `event`.** The event hook's `meta.datasetStart`/`meta.datasetEnd` are in a different time frame than `record.time`. Move any day-in-dataset check to `everything`.
+2. **Temporal mutations run AFTER all cloning.** If Hook A clones events into a time window and Hook B mutates events in that window, B must run after A or clones miss the mutation.
+3. **Cohort detection must survive downstream filtering.** If a churn hook removes the marker events used to detect a cohort, require 3+ markers instead of 1+ so survivors still identify the group.
+4. **Deprecated feature replacement.** Add equivalent property assignments in `user`/`everything` hooks and `superProps`/`userProps`. See recipe 3.22.
+5. **Unseeded Chance breaks determinism.** Replace `new Chance()` with `initChance(SEED)`.
+
+### Documentation
+
+- **`research/FINALIZE-REPORT.md`** — full eval report: 19 dungeons, 191 hooks, all STRONG/NAILED.
+- **`research/1.4.0-upgrade-guide.md`** — migration checklist and hook-writing guide.
+- **`HOOKS.md`** — 23 recipes, 14 principles, atom/pattern reference.
+- **`.claude/skills/verify-hooks/SKILL.md`** — REV 10: clone dilution, cohort filtering, deprecated features, dynamic date window derivation.
+- **`.claude/skills/write-hooks/SKILL.md`** — REV 10: hook ordering within `everything`, deprecated feature replacement, cohort sizing guidelines.
+
+### Backward Compatibility
+
+- **No breaking changes to the public API.** `DUNGEON_MASTER(config)` signature unchanged. All named exports unchanged.
+- Existing dungeons run without modification. New features are opt-in.
+- Dungeons that relied on the legacy 42% `user_id` dice will see more consistent identity (every event gets `user_id`). This is more correct for Mixpanel.
+- `numDays`-only configs continue to work (window anchors to today). Pin `datasetStart`+`datasetEnd` for deterministic runs.
+
 ## 1.3.0 — 2026-04-28
 
 The "no more end-of-dataset blowup" release. Rewrote how per-user event budgets and big-picture trends are decided so the default chart looks flat with a weekly cycle, instead of meteoric ramp + cliff in the final ~14 days.

package/dungeons/technical/array-of-object-lookup.js

@@ -147,8 +147,6 @@ const config = {
 	}],
 	hook: function (record, type, meta) {
 
-		const NOW = dayjs();
-
 		if (type === "event") {
 			// Pattern 1: Checkouts with coupons get a discount_applied flag and adjusted total
 			if (record.event === "checkout" && record.coupon && record.coupon !== "none") {

package/dungeons/technical/hook-helpers-verify.js

@@ -0,0 +1,89 @@
+/**
+ * Phase 3 hook-helpers verification fixture.
+ *
+ * Exercises three atoms inside one `everything` hook:
+ *   1. `binUsersByEventCount` — classify users into "casual" / "engaged" / "power"
+ *      based on their count of `Browse` events.
+ *   2. `scalePropertyValue` — engaged users get 2x `amount` on Purchase events;
+ *      power users get 3x.
+ *   3. `injectBurst` — power users also get a burst of 5 cloned `Browse` events
+ *      around the midpoint of their stream.
+ *
+ * Verified by DuckDB queries against the events output (see
+ * scripts/verify-runner.mjs + the Phase 3 verification gate notes in the plan).
+ */
+
+import dayjs from 'dayjs';
+import {
+	binUsersByEventCount,
+	scalePropertyValue,
+	injectBurst,
+	cloneEvent,
+} from '../../lib/hook-helpers/index.js';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+const BINS = {
+	casual: [0, 5],
+	engaged: [5, 15],
+	power: [15, Infinity],
+};
+
+const SCALE_BY_BIN = { casual: 1, engaged: 2, power: 3 };
+const BURST_COUNT_BY_BIN = { casual: 0, engaged: 0, power: 5 };
+
+export default {
+	name: 'hook-helpers-verify',
+	seed: 'phase3-helpers-verify',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 4,
+	percentUsersBornInDataset: 30,
+	hasAnonIds: false,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	events: [
+		{ event: 'Browse', weight: 8, properties: { surface: ['home', 'category', 'search'] } },
+		{ event: 'Purchase', weight: 2, properties: { amount: [10, 20, 30, 40, 50] } },
+	],
+	hook: function (record, type, meta) {
+		if (type !== 'everything' || !Array.isArray(record)) return record;
+
+		// 1. Classify the user via cohort atom
+		const bin = binUsersByEventCount(record, 'Browse', BINS);
+		if (!bin) return record;
+
+		// Stamp the bin onto each Purchase so verification queries can group by it
+		// without re-deriving. Non-flag-stamping: this property is config-defined when
+		// dungeons add `cohort` to Purchase.properties; here we accept the small bend
+		// for the verification fixture so DuckDB queries are clean.
+		for (const ev of record) {
+			if (ev.event === 'Purchase') ev.cohort = bin;
+		}
+
+		// 2. Scale Purchase amounts via mutate atom (engaged 2x, power 3x)
+		const factor = SCALE_BY_BIN[bin] || 1;
+		if (factor !== 1) {
+			scalePropertyValue(record, e => e.event === 'Purchase', 'amount', factor);
+		}
+
+		// 3. Power users get a Browse burst clustered at the dataset midpoint
+		const burstCount = BURST_COUNT_BY_BIN[bin] || 0;
+		if (burstCount > 0 && record.length) {
+			const midUnixMs = (meta.datasetStart + (meta.datasetEnd - meta.datasetStart) / 2) * 1000;
+			// Use the user's first Browse as a clone template so we honor the schema.
+			const template = record.find(e => e.event === 'Browse');
+			if (template) {
+				const tpl = cloneEvent(template, { cohort: bin });
+				injectBurst(record, tpl, burstCount, midUnixMs, 60 * 60 * 1000); // ±1h spread
+			}
+		}
+
+		// Re-sort by time after burst injection so downstream pipeline sees ordered events.
+		record.sort((a, b) => (a.time < b.time ? -1 : a.time > b.time ? 1 : 0));
+		return record;
+	},
+};

package/dungeons/technical/identity-model-verify.js

@@ -0,0 +1,47 @@
+/**
+ * Phase 2 identity model — verification fixture (intentionally simple).
+ *
+ * 1K born-in-dataset users with isAuthEvent on `Sign Up` (the stitch step) and a
+ * 3-step first funnel. Dataset window pinned for determinism. avgDevicePerUser:2
+ * exercises the multi-device sticky-per-session model. Used by phase 2 verification
+ * gate (DuckDB queries against the events output).
+ */
+
+import dayjs from 'dayjs';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+export default {
+	name: 'identity-model-verify',
+	seed: 'phase2-identity-verify',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 3,
+	percentUsersBornInDataset: 100,
+	hasAnonIds: true,
+	avgDevicePerUser: 2,
+	hasSessionIds: true,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	events: [
+		{ event: 'Land', isFirstEvent: true, isStrictEvent: true },
+		{ event: 'View Pricing', isStrictEvent: true },
+		{ event: 'Sign Up', isAuthEvent: true, isStrictEvent: true },
+		{ event: 'Onboarding', isStrictEvent: true },
+		{ event: 'Browse', weight: 5 },
+		{ event: 'Save Item', weight: 2 },
+	],
+	funnels: [
+		{
+			name: 'Acquisition',
+			sequence: ['Land', 'View Pricing', 'Sign Up', 'Onboarding'],
+			conversionRate: 80,
+			isFirstFunnel: true,
+			timeToConvert: 2,
+			attempts: { min: 0, max: 2 },
+		},
+	],
+};

package/dungeons/technical/pattern-aggregate-by-bin.js

@@ -0,0 +1,41 @@
+/**
+ * Phase 4 reference dungeon — aggregate per user, by bin.
+ *
+ * Users in the high-Browse cohort have 4× higher Purchase amounts on average;
+ * mid cohort 2×; low cohort 1×. Verified via the aggregatePerUser emulator.
+ */
+
+import dayjs from 'dayjs';
+import { applyAggregateByBin } from '../../lib/hook-patterns/index.js';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+export default {
+	name: 'pattern-agg-by-bin',
+	seed: 'phase4-aggbybin',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 6,
+	percentUsersBornInDataset: 30,
+	hasAnonIds: false,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	events: [
+		{ event: 'Browse', weight: 6 },
+		{ event: 'Purchase', weight: 2, properties: { amount: [10, 20, 30] } },
+	],
+	hook: function (record, type) {
+		if (type !== 'everything' || !Array.isArray(record)) return record;
+		applyAggregateByBin(record, null, {
+			cohortEvent: 'Browse',
+			bins: { low: [0, 5], mid: [5, 15], high: [15, Infinity] },
+			event: 'Purchase',
+			propertyName: 'amount',
+			deltas: { low: 1, mid: 2, high: 4 },
+		});
+		return record;
+	},
+};

package/dungeons/technical/pattern-attributed-by-source.js

@@ -0,0 +1,42 @@
+/**
+ * Phase 4 reference dungeon — conversions attributed by source.
+ *
+ * Touch events carry one of three random sources; conversions are stamped with
+ * the user's first-touch source weighted google:facebook:twitter = 10:5:1.
+ * Verified via the attributedBy emulator.
+ */
+
+import dayjs from 'dayjs';
+import { applyAttributedBySource } from '../../lib/hook-patterns/index.js';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+export default {
+	name: 'pattern-attributed-by-source',
+	seed: 'phase4-attrib',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 4,
+	percentUsersBornInDataset: 50,
+	hasAnonIds: false,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	events: [
+		{ event: 'Touch', weight: 5, properties: { source: ['google', 'facebook', 'twitter'] } },
+		{ event: 'Convert', weight: 2, properties: { source: ['unknown'] } },
+	],
+	hook: function (record, type) {
+		if (type !== 'everything' || !Array.isArray(record)) return record;
+		applyAttributedBySource(record, null, {
+			sourceEvent: 'Touch',
+			sourceProperty: 'source',
+			downstreamEvent: 'Convert',
+			weights: { google: 10, facebook: 5, twitter: 1 },
+			model: 'firstTouch',
+		});
+		return record;
+	},
+};

package/dungeons/technical/pattern-frequency-by-frequency.js

@@ -0,0 +1,40 @@
+/**
+ * Phase 4 reference dungeon — frequency × frequency.
+ *
+ * Engages users into low / mid / high "Browse" cohorts; high-cohort users get 3×
+ * Purchase events. Verified by the Phase 4 patterns test + verify-runner.
+ */
+
+import dayjs from 'dayjs';
+import { applyFrequencyByFrequency } from '../../lib/hook-patterns/index.js';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+export default {
+	name: 'pattern-freq-by-freq',
+	seed: 'phase4-freqxfreq',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 6,
+	percentUsersBornInDataset: 30,
+	hasAnonIds: false,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	events: [
+		{ event: 'Browse', weight: 6 },
+		{ event: 'Purchase', weight: 2, properties: { amount: [10, 20, 30, 40, 50] } },
+	],
+	hook: function (record, type) {
+		if (type !== 'everything' || !Array.isArray(record)) return record;
+		applyFrequencyByFrequency(record, null, {
+			cohortEvent: 'Browse',
+			bins: { low: [0, 5], mid: [5, 15], high: [15, Infinity] },
+			targetEvent: 'Purchase',
+			multipliers: { low: 1, mid: 2, high: 3 },
+		});
+		return record;
+	},
+};

package/dungeons/technical/pattern-funnel-frequency.js

@@ -0,0 +1,54 @@
+/**
+ * Phase 4 reference dungeon — funnel frequency breakdown.
+ *
+ * Engaged-cohort users (high count of `Browse`) are 1.5× more likely to complete
+ * the activation funnel's last step than low-cohort users. Verified via the
+ * funnelFrequency emulator.
+ *
+ * Note: this pattern is funnel-post; it edits the funnel's own events. Combined
+ * with the per-user funnel attempts, the breakdown should show a stronger
+ * conversion-per-step lift in the high cohort.
+ */
+
+import dayjs from 'dayjs';
+import { applyFunnelFrequencyBreakdown } from '../../lib/hook-patterns/index.js';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+export default {
+	name: 'pattern-funnel-freq',
+	seed: 'phase4-funnel-freq',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 4,
+	percentUsersBornInDataset: 100,
+	hasAnonIds: false,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	events: [
+		{ event: 'Land', isFirstEvent: true, isStrictEvent: true },
+		{ event: 'Sign Up', isAuthEvent: true, isStrictEvent: true },
+		{ event: 'Activate', isStrictEvent: true },
+		{ event: 'Browse', weight: 5 },
+	],
+	funnels: [{
+		sequence: ['Land', 'Sign Up', 'Activate'],
+		conversionRate: 70, isFirstFunnel: true, timeToConvert: 4,
+	}],
+	hook: function (record, type, meta) {
+		if (type !== 'funnel-post' || !Array.isArray(record)) return;
+		if (!meta.isFirstFunnel) return;
+		// In funnel-post we don't have the user's full event stream — pattern accepts
+		// null for `allUserEvents` and falls back to counting cohortEvent inside the
+		// funnel-only events. Real dungeons usually wire this via `everything` instead.
+		applyFunnelFrequencyBreakdown(null, meta.profile || {}, record, {
+			cohortEvent: 'Browse',
+			bins: { low: [0, 3], high: [3, Infinity] },
+			dropMultipliers: { low: 0.5, high: 0.95 },
+			finalStep: 'Activate',
+		});
+	},
+};

package/dungeons/technical/pattern-ttc-by-segment.js

@@ -0,0 +1,45 @@
+/**
+ * Phase 4 reference dungeon — time to convert by segment.
+ *
+ * Trial users take 4× longer to complete the activation funnel than enterprise
+ * users (0.5× faster). Verified via the timeToConvert emulator.
+ */
+
+import dayjs from 'dayjs';
+import { applyTTCBySegment } from '../../lib/hook-patterns/index.js';
+
+const FIXED_NOW = dayjs('2024-02-02').unix();
+
+export default {
+	name: 'pattern-ttc-by-segment',
+	seed: 'phase4-ttc-seg',
+	datasetStart: FIXED_NOW - 30 * 86400,
+	datasetEnd: FIXED_NOW,
+	numUsers: 1_000,
+	avgEventsPerUserPerDay: 4,
+	percentUsersBornInDataset: 100,
+	hasAnonIds: false,
+	format: 'json',
+	concurrency: 1,
+	writeToDisk: true,
+	verbose: false,
+	userProps: { tier: ['trial', 'trial', 'enterprise'] },
+	events: [
+		{ event: 'Land', isFirstEvent: true, isStrictEvent: true },
+		{ event: 'Sign Up', isAuthEvent: true, isStrictEvent: true },
+		{ event: 'Activate', isStrictEvent: true },
+		{ event: 'Browse', weight: 5 },
+	],
+	funnels: [{
+		sequence: ['Land', 'Sign Up', 'Activate'],
+		conversionRate: 100, isFirstFunnel: true, timeToConvert: 4,
+	}],
+	hook: function (record, type, meta) {
+		if (type !== 'funnel-post' || !Array.isArray(record)) return;
+		if (!meta.isFirstFunnel) return;
+		applyTTCBySegment(record, meta.profile || {}, {
+			segmentKey: 'tier',
+			factors: { trial: 4, enterprise: 0.5 },
+		});
+	},
+};

package/dungeons/technical/simple.js

@@ -218,10 +218,9 @@ const config = {
 	lookupTables: [],
 	hook: function (record, type, meta) {
 
-		const NOW = dayjs();
-		// const DATE_HOMEGROWN_LAUNCH = NOW.subtract(25, 'day');
-		// const DATE_HOMEGROWN_IMPROVEMENT = NOW.subtract(10, 'day');
-		const OVER_THINGS_GET_BETTER = NOW.subtract(15, 'day');
+		// Anchor relative dates to the resolved dataset window — never wall-clock.
+		const datasetEnd = dayjs.unix(meta.datasetEnd);
+		const OVER_THINGS_GET_BETTER = datasetEnd.subtract(15, 'day');
 
 		if (type === "event") {
 			const EVENT_TIME = dayjs(record.time);

package/dungeons/technical/simplest-schema.json

@@ -622,6 +622,11 @@
     ]
   },
   "userProps": {
+    "theme": [
+      "light",
+      "dark",
+      "custom"
+    ],
     "title": {
       "$type": "string"
     },

package/dungeons/technical/text-generation.js

@@ -240,7 +240,7 @@ const socialTweetGen = createTextGenerator({
 	typoRate: 0.03,
 	sentimentDrift: 0.3,
 	min: 10,
-	max: 280, // Twitter character limit
+	max: 254, // capped at Mixpanel string property limit
 	includeMetadata: false
 });