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

package/README.md

@@ -51,9 +51,9 @@ const result = await DUNGEON_MASTER('./dungeons/technical/simple-schema.json');
 
 // run multiple dungeons
 const results = await DUNGEON_MASTER([
-  './dungeons/vertical/gaming.js',
-  './dungeons/vertical/media.js',
-  './dungeons/vertical/food-delivery.js'
+  './dungeons/vertical/gaming/gaming.js',
+  './dungeons/vertical/media/media.js',
+  './dungeons/vertical/food-delivery/food-delivery.js'
 ]);
 
 // pass raw javascript as a string
@@ -70,7 +70,7 @@ const result = await DUNGEON_MASTER(`
 `);
 
 // override any config when loading from files
-const result = await DUNGEON_MASTER('./dungeons/vertical/fintech.js', {
+const result = await DUNGEON_MASTER('./dungeons/vertical/fintech/fintech.js', {
   numUsers: 100,       // shrink for testing
   writeToDisk: true,
   verbose: true
@@ -95,9 +95,9 @@ console.log(result.importResults);
 
 a dungeon is a javascript file that exports a configuration object. it defines your entire data model: events, funnels, user properties, group analytics, SCDs, and a hook function that engineers discoverable patterns into the data.
 
-see `dungeons/vertical/` for customer-facing story dungeons (18 events, 8 hooks) and `dungeons/technical/` for feature-testing dungeons (mirrors, groups, scale, anonymous users).
+see `dungeons/vertical/` for customer-facing story dungeons (one folder per vertical, each with engineered hooks and machine-checkable stories) and `dungeons/technical/` for feature-testing dungeons (mirrors, groups, scale, anonymous users).
 
-every vertical dungeon ships with a verification proof at `verification/verticals/<name>.{verify.mjs,sql}` — a CI-runnable assertion that the dungeon's documented hooks actually appear in the generated data at full fidelity. 20 dungeons, 107 hooks, 107 checks. see [`verification/verticals/README.md`](verification/verticals/README.md).
+every vertical dungeon ships with a verification proof at `dungeons/vertical/<name>/<name>.{verify.mjs,sql}` plus a `stories` export evaluated mechanically by `scripts/verify-stories.mjs` — a CI-runnable assertion that the dungeon's documented hooks actually appear in the generated data at full fidelity. 22 dungeons, 212 machine-checkable stories. see [`dungeons/vertical/README.md`](dungeons/vertical/README.md).
 
 ```javascript
 // dungeons/my-app.js
@@ -173,7 +173,7 @@ import DUNGEON_MASTER, {
 `dungeonToJSON` accepts a config object, a file path, raw JS source, or an array of paths, and returns the `{ schema, hooks, timestamp, version }` wrapper format. it round-trips with `parseJSONDungeon`:
 
 ```javascript
-const json   = await dungeonToJSON('./dungeons/vertical/ecommerce.js');  // creds stripped by default
+const json   = await dungeonToJSON('./dungeons/vertical/ecommerce/ecommerce.js');  // creds stripped by default
 const config = parseJSONDungeon(json);                                   // back to a runnable dungeon
 ```
 
@@ -535,6 +535,25 @@ funnels: [
 
 ordering strategies: `sequential`, `random`, `first-fixed`, `last-fixed`, `first-and-last-fixed`, `middle-fixed`, `interrupted`
 
+### experiments
+
+experiments are a property of funnels. any funnel with `experiment` set fires a `$experiment_started` event (with `Experiment name` / `Variant name` properties) at the start of every qualifying pass, and the assigned variant's `conversionMultiplier` / `ttcMultiplier` modify that pass:
+
+```javascript
+experiment: true                    // shorthand: Variant A (worse) / Variant B (better) / Control
+experiment: {
+  name: 'Checkout Redesign',
+  startDaysBeforeEnd: 30,           // runs before this date skip the experiment entirely
+  sticky: true,                     // default — see below
+  variants: [
+    { name: 'Control' },
+    { name: 'New Checkout', conversionMultiplier: 1.25, ttcMultiplier: 0.8, weight: 1 },
+  ]
+}
+```
+
+variant assignment is **sticky by default**: a deterministic hash of `user_id` + experiment name, so a user keeps their variant across every funnel pass (matches Mixpanel experiment SDK bucketing and makes variant lift verifiable). set `sticky: false` to re-roll the variant on each pass with the seeded RNG. hooks see the resolved variant on `meta.experiment` in `funnel-pre` / `funnel-post`.
+
 ## user generation
 
 users are generated with configurable birth distributions, normally controlled via the `macro` preset (see "time shape" above). these three knobs can also be set directly on the dungeon config — they override the preset's values.
@@ -609,7 +628,7 @@ styles: `support`, `review`, `search`, `feedback`, `chat`, `email`, `forum`, `co
 ## scripts
 
 ```bash
-npm test                      # vitest test suite (~10s, 1122 tests)
+npm test                      # full vitest test suite
 npm run typecheck             # typescript check
 npm run dungeon:run           # run a dungeon file locally
 npm run dungeon:to-json       # convert JS dungeon to JSON (for UI import)
@@ -649,7 +668,7 @@ npx vitest run tests/integration/features.test.js          # single file
 npx vitest tests/unit                                       # watch mode
 ```
 
-`tests/e2e/sanity.test.js` is excluded by default (parked); run isolated with `npx vitest run tests/e2e/sanity.test.js`.
+`tests/e2e/engine-shape-full-sweep.test.js` skips itself unless `RUN_FULL_SWEEP=1` is set (it wraps the long-running 194-combo engine sweep).
 
 ### engine tests (direct-run, NOT vitest)
 

package/docs/guides/1.3.0-upgrade-guide.md

@@ -0,0 +1,262 @@
+# dungeon-master 1.3.0 — Upgrade Guide for Agents
+
+This is the guide for AI agents (Claude, Cursor, etc.) writing or modifying `dungeon-master` configurations and code on or after the 1.3.0 release. Read this if you've been trained on 1.2.x patterns; the API has changed in non-breaking but important ways.
+
+**TL;DR**:
+1. Use `avgEventsPerUserPerDay` instead of `numEvents` when writing new dungeon configs.
+2. Use `macro: "..."` for big-picture trend; `soup: "..."` is now intra-week / intra-day rhythm only.
+3. The default trend is **flat** (no growth ramp). If you want a growth narrative, set `macro: "growth"` explicitly.
+4. Hooks may not introduce events past `MAX_TIME` — the runtime drops them defensively, so plan around that.
+
+## Why 1.3.0 exists
+
+In 1.2.x and earlier, every dungeon's Mixpanel chart blew up at the right edge: a meteoric ramp in the final ~14 days that wasn't intentional. Three mechanisms compounded:
+
+1. `avgEvPerUser = numEvents / numUsers` was fixed regardless of birth time, so a user born day 80 of 90 stuffed their whole event budget into 10 days (9× the per-day density of a pre-existing user).
+2. The default `bornRecentBias = 0.3` (in old `growth` soup preset) skewed births toward recent.
+3. Pre-existing users all started at `FIXED_BEGIN`, front-loading the early window.
+
+1.3.0 fixes all three. The default behavior is now flat-with-weekly-cycle. Hooks layer the story on top.
+
+See [`end-bunchiness.md`](end-bunchiness.md) for the full diagnosis, experiments, and final regression numbers.
+
+## What changed at the API level
+
+### NEW: `avgEventsPerUserPerDay` (top-level config field)
+
+The canonical event-volume primitive. Each user's event budget is `rate × user_active_days`:
+- Pre-existing user (created before window): full `numDays` of activity → `rate × numDays` events.
+- Born-in-dataset user: from birth to now → `rate × remaining_days` events (floored at 1 day).
+
+Before:
+```javascript
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user = 120;          // per-user TOTAL
+
+const config = {
+  numDays: num_days,
+  numEvents: num_users * avg_events_per_user,
+  numUsers: num_users,
+  // ...
+};
+```
+
+After:
+```javascript
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user_per_day = 1.2;  // per-user-PER-DAY rate
+
+const config = {
+  numDays: num_days,
+  avgEventsPerUserPerDay: avg_events_per_user_per_day,
+  numUsers: num_users,
+  // ...
+};
+```
+
+`numEvents` still works as a **fallback**: if you only set `numEvents`, the validator derives `avgEventsPerUserPerDay = numEvents / numUsers / numDays`. Both fields end up populated in the resolved config. **Prefer the rate field in new dungeons** — it's the right unit for the proportional allocation.
+
+### NEW: `macro` preset system (top-level config field)
+
+Big-picture trend across the whole window. Default: `"flat"`.
+
+| preset | bornRecentBias | percentUsersBornInDataset | preExistingSpread | shape |
+|--------|----------------|---------------------------|-------------------|-------|
+| `flat` (default) | 0 | 15 | uniform | tail ≈ 1.0 |
+| `steady` | 0.1 | 10 | uniform | slight uptrend |
+| `growth` | 0.3 | 25 | pinned | mild uptrend |
+| `viral` | 0.6 | 50 | pinned | hockey-stick |
+| `decline` | -0.3 | 5 | uniform | downtrend (pair with churn hooks) |
+
+Three forms:
+```javascript
+macro: "growth"                                              // preset string
+macro: { preset: "growth", percentUsersBornInDataset: 40 }   // preset + override
+macro: { bornRecentBias: 0, percentUsersBornInDataset: 25, preExistingSpread: "uniform" }  // custom
+```
+
+Setting `bornRecentBias` / `percentUsersBornInDataset` / `preExistingSpread` directly on the dungeon config still works — those values **override** the macro preset. Migrating existing dungeons that used these fields directly does not require an explicit `macro` setting (the default `flat` is fine; the explicit overrides win).
+
+### NEW: `preExistingSpread` (top-level config field)
+
+How pre-existing users' first event time is placed:
+- `"uniform"` (default in `flat` macro): sample uniformly from `[FIXED_BEGIN - 30 days, FIXED_BEGIN]`. Pre-existing users have varied "born before dataset" timestamps.
+- `"pinned"` (legacy): all pre-existing users start exactly at `FIXED_BEGIN`. Used by `growth` and `viral` macros (intentional front-loading for those narratives).
+
+### CHANGED: soup presets are now intra-week / intra-day only
+
+Soup no longer carries `bornRecentBias` / `percentUsersBornInDataset`. Those fields moved to `macro`. Soup presets now only set `peaks`, `deviation`, `mean`, `dayOfWeekWeights`, `hourOfDayWeights`. The preset names (`growth`, `steady`, `spiky`, `seasonal`, `global`, `churny`, `chaotic`) are unchanged.
+
+If you write `soup: "growth"`, you get the same intra-week rhythm as before, but you do NOT get the old `bornRecentBias=0.3` / `percentUsersBornInDataset=15` defaults — those come from `macro: "flat"` (the new default). To recreate the legacy behavior, set both: `soup: "growth", macro: "growth"`.
+
+### NEW: future-event guard at end of user loop
+
+`lib/orchestrators/user-loop.js` now drops any event whose timestamp landed past `context.MAX_TIME` after the `everything` hook runs. This catches hook-injected duplicates that overflow into the future. **Plan around it**: hooks that duplicate events with positive time offsets near the right edge of the window will silently lose those duplicates. If you need them, clamp the time yourself in the hook.
+
+### RENAMED: `dungeons/vertical/questforge.js` → `dungeons/vertical/gaming.js`
+
+The file name follows the **vertical** convention (`gaming`, `dating`, `fintech`, etc.). The product/app name (QuestForge) lives inside the file's comments.
+
+## Migration checklist for an existing dungeon
+
+If you're updating a 1.2.x dungeon to 1.3.0:
+
+1. **Rename the local var**: `const avg_events_per_user = N` → `const avg_events_per_user_per_day = N / num_days` (rounded to 2 decimal places).
+2. **Update the config field**: `numEvents: num_users * avg_events_per_user` → `avgEventsPerUserPerDay: avg_events_per_user_per_day`.
+3. **Remove explicit `percentUsersBornInDataset` overrides** unless the dungeon needs a non-default value. The `flat` macro default (15%) is the new convention.
+4. **Optionally set `macro: "growth"` / `"viral"` / `"decline"`** if the dungeon has an intentional growth/decline narrative. Otherwise omit `macro` and let the default `flat` take over.
+5. **Audit hooks for time-injected events past `MAX_TIME`**: if your hook duplicates events with `time + N hours/days`, those duplicates may be silently dropped by the new guard. Clamp inside the hook if needed.
+6. **Run `npx vitest run tests/dungeons.test.js`** to confirm the dungeon still parses and validates.
+
+A bulk migration script lives at [`scripts/experiments/migrate-dungeons.mjs`](../scripts/experiments/migrate-dungeons.mjs). It's idempotent — safe to re-run.
+
+## Writing a new dungeon in 1.3.0
+
+Use this skeleton (from [`.claude/skills/create-dungeon/SKILL.md`](../.claude/skills/create-dungeon/SKILL.md)):
+
+```javascript
+// ── TWEAK THESE ──
+const SEED = "dm4-VERTICAL";
+const num_days = 100;
+const num_users = 5_000;
+const avg_events_per_user_per_day = 1.2;  // events per user per ACTIVE day
+let token = "your-mixpanel-token";
+
+// ... imports ...
+
+const config = {
+  token,
+  seed: SEED,
+  numDays: num_days,
+  avgEventsPerUserPerDay: avg_events_per_user_per_day,
+  numUsers: num_users,
+  // ... feature switches, scdProps, mirrorProps, lookupTables: [] ...
+
+  // Trend shape — leave both at default unless prompt asks otherwise.
+  // macro defaults to "flat"; soup defaults to "growth".
+  // macro: "flat",   // also: "steady" | "growth" | "viral" | "decline"
+  // soup: "growth",  // also: "steady" | "spiky" | "seasonal" | "global" | "churny" | "chaotic"
+
+  events: [ /* ... */ ],
+  funnels: [ /* ... */ ],
+  hook: function (record, type, meta) { /* ... */ return record; }
+};
+
+export default config;
+```
+
+**Key rules** (unchanged from 1.2.x):
+- Hooks shape data within the schema; they cannot invent properties not defined in `events` / `userProps` / `superProps`.
+- All event properties are FLAT (`record.amount`, not `record.properties.amount`).
+- Injected events must be cloned from existing events with `{...existingEvent, time: newTime}`.
+- Use `dayjs` for time math inside hooks. Use the seeded `chance` instance.
+
+**New rules in 1.3.0**:
+- Use `avgEventsPerUserPerDay` not `numEvents`.
+- Don't override `percentUsersBornInDataset` unless the dungeon has a specific narrative reason. Use `macro` instead.
+- If a hook duplicates events with a positive time offset and the source event is near the right edge, expect the duplicate to be dropped by the future-event guard.
+
+## Quick reference — config primitives
+
+| field | type | default | what it does |
+|-------|------|---------|--------------|
+| `avgEventsPerUserPerDay` | number | derived from `numEvents` | per-user-per-active-day rate (canonical) |
+| `numEvents` | number | 100_000 | legacy total target; populates `avgEventsPerUserPerDay` if unset |
+| `numUsers` | number | 1000 | total user count |
+| `numDays` | number | 30 | dataset window length |
+| `macro` | string \| object | `"flat"` | big-picture trend preset |
+| `soup` | string \| object | `"growth"` | intra-week / intra-day rhythm preset |
+| `bornRecentBias` | number | 0 (from `flat`) | birth-time skew, -1..1 |
+| `percentUsersBornInDataset` | number | 15 (from `flat`) | share of users born inside the window |
+| `preExistingSpread` | `"uniform"` \| `"pinned"` | `"uniform"` (from `flat`) | placement of pre-existing users' first event |
+
+## Where to look in the codebase
+
+- [`lib/core/config-validator.js`](../lib/core/config-validator.js) — resolves both primitives, applies macro defaults
+- [`lib/templates/macro-presets.js`](../lib/templates/macro-presets.js) — macro preset definitions + `resolveMacro`
+- [`lib/templates/soup-presets.js`](../lib/templates/soup-presets.js) — soup preset definitions (no birth fields)
+- [`lib/orchestrators/user-loop.js`](../lib/orchestrators/user-loop.js) — per-user-per-day allocation (search `userActiveDays`), pre-existing spread, future-event guard
+- [`tests/macro-and-rate.test.js`](../tests/macro-and-rate.test.js) — usage examples + invariants
+- [`research/end-bunchiness.md`](end-bunchiness.md) — full diagnosis + experiment data + before/after numbers
+
+## Hook-writing learnings (from the 1.3.0 verify-hooks pass)
+
+We re-verified every hook on every vertical dungeon at 1.3.0 (~160 hooks across 20 dungeons). The pass surfaced five recurring failure modes that aren't obvious from the hook API alone — codify them in any new dungeon you write.
+
+### Five rules that prevent ~all observed hook failures
+
+1. **Never read DOW / day-of-month from `record.time` inside an `event` hook when `hasSessionIds: true`.**
+   `bunchIntoSessions()` runs AFTER the event hook but BEFORE the everything hook. It reassigns timestamps to fit session windows, so any `dayjs(record.time).day()` you compute in the event hook becomes decorrelated from the actual stored timestamp. Move all DOW / day-of-month logic to the everything hook, where `e.time` is final.
+   ```js
+   // ❌ WRONG — event hook fires before sessionization
+   if (type === 'event' && dayjs(record.time).day() === 0) record.weekend_surge = true;
+
+   // ✅ RIGHT — everything hook fires after sessionization
+   if (type === 'everything') {
+     for (const e of record) {
+       if (new Date(e.time).getUTCDay() === 0) e.weekend_surge = true;
+     }
+   }
+   ```
+   Note: also use `getUTCDay()` (or `dayjs.utc()`), not `.day()`. TimeSoup distributes events using UTC DOW; local-time DOW will skew the result for users in non-UTC timezones.
+
+2. **Never read superProps inside an `event` hook — they aren't your user's value yet.**
+   At event-hook time, properties listed in `superProps` come from the random picker (one value per event). The everything hook later overwrites each event with the user's stamped value from `meta.profile`. So an event hook that branches on `record.account_tier` is making decisions on noise. Read `meta.profile.account_tier` in the everything hook instead.
+   ```js
+   // ❌ WRONG — record.account_tier is a fresh random pick
+   if (type === 'event' && record.account_tier === 'premium') record.reward *= 3;
+
+   // ✅ RIGHT — meta.profile is the authoritative user profile
+   if (type === 'everything') {
+     for (const e of record) {
+       if (meta.profile.account_tier === 'premium') e.reward *= 3;
+     }
+   }
+   ```
+
+3. **Use UTC consistently for relative-time windows.**
+   When you anchor a window like "days 20-27 of the dataset," compute both the anchor and the comparison in UTC. Mixing `dayjs()` (local) with timestamps from TimeSoup (UTC) shifts the window by the host's timezone offset.
+   ```js
+   const DATASET_START = dayjs.utc().subtract(num_days, 'day');
+   const launchDay = DATASET_START.add(45, 'day');
+   if (dayjs.utc(record.time).isAfter(launchDay)) { /* ... */ }
+   ```
+
+4. **Apply value scaling AFTER cloning.**
+   If you clone events in the everything hook to inject duplicates (weekend surge, viral spread, etc.) AND you also scale values in the event hook, the event-hook scaling never touches the clones. Move both the cloning and the scaling into the everything hook so the multiplier applies after the dataset's final shape exists.
+
+5. **Sanity-check thresholds at small scale.**
+   At 1K-user verification scale, hooks like "users with ≥5 errors in 7 days" or "sessions with <2 hours between events" frequently produce zero qualifying users. The hook works, but at small scale the threshold is too strict to register. Either:
+   - Relax the threshold so it passes verification (preferred for thresholds tuned on noise), OR
+   - Document in the dungeon comment that the hook needs production scale to fire (preferred for thresholds tied to real product semantics).
+
+### What goes where (decision matrix)
+
+| Logic type | event hook | everything hook |
+|-----------|:---------:|:---------------:|
+| Value scaling driven by an event property already on `record` | ✅ | ✅ |
+| Value scaling driven by user profile / superProp | ❌ | ✅ (`meta.profile.X`) |
+| DOW / day-of-month patterns (any dungeon) | ❌ | ✅ (`new Date(e.time).getUTCDay()`) |
+| Closure-state Maps that track per-user context across events | ✅ | — |
+| Relative-time windows (DATASET_START + N days) | ✅ (`dayjs.utc`) | ✅ |
+| Event cloning / injection (weekend surge, viral, etc.) | ❌ | ✅ |
+| Value scaling that must include cloned events | ❌ | ✅ |
+| Event filtering (churn, drop-off) | ❌ | ✅ (`return record.filter(...)`) |
+
+### Other things worth knowing
+
+- **Hooks cannot invent new properties.** Every property a hook sets must already exist in the config (in `events[].properties`, `userProps`, or `superProps`) with a default value. If you need a flag like `payday`, add `payday: [false]` to the event's properties; the hook flips it to `true`.
+- **Spliced/cloned events need `user_id` and `time`** — copy from the source: `{ ...source, time: newIso, user_id: source.user_id }`. Building events from scratch will fail validation.
+- **Future-event guard drops time-shifted clones.** If your hook clones an event near the right edge of the window with `time + N hours`, the future-event guard at the end of the user loop will silently drop the clone. Clamp inside the hook if you need it.
+- **Event property access is FLAT.** Use `record.amount`, never `record.properties.amount`.
+
+These rules + the verify-hooks skill (`/verify-hooks`) caught 13 silent hook failures across the vertical pack; running it after any non-trivial hook change is the cheapest insurance against shipping a flat-line story.
+
+## Backward compatibility
+
+- 1.2.x dungeons that set `numEvents` directly continue to work — the rate is derived. They will, however, render with the new `flat` macro defaults (no growth bias, uniform pre-existing spread). If a 1.2.x dungeon depended on the implicit `bornRecentBias=0.3` from the old `growth` soup preset, add `macro: "growth"` to restore that behavior.
+- 1.2.x dungeons that set `bornRecentBias` / `percentUsersBornInDataset` directly continue to work unchanged — those fields override the macro preset.
+- Soup preset names are unchanged. Hook semantics are unchanged. Output file naming is unchanged.
+- The `numEvents` config field is **not deprecated**. It remains the right primitive when you want a fixed total volume target rather than a per-day rate.