@ak--47/dungeon-master 1.5.0 → 1.5.2

package/.claude/skills/create-dungeon/SKILL.md

@@ -28,9 +28,18 @@ In scope here:
   `isFirstFunnel`, `attempts`
 - Event flags: `isAuthEvent`, `isAttributionEvent`, `isFirstEvent`,
   `isStrictEvent`, `isChurnEvent`, `isSessionStartEvent`
-- Top-level: `datasetStart`, `datasetEnd`, `numUsers`, `avgEventsPerUserPerDay`,
-  `seed`, `format`, device flags, `avgDevicePerUser`, `hasLocation`,
-  `hasCampaigns`, `hasSessionIds`, `hasAvatar`, `macro`, `soup`
+- Top-level scale + data model: `datasetStart`, `datasetEnd`, `numUsers`,
+  `avgEventsPerUserPerDay`, `seed`, `userSeed`, `format`, `macro`, `soup`,
+  `retentionCurve`, `avgActiveDaysPerUser`, `maxTouchpointsPerUser`
+- **Sub-object API (v1.5+):** group related keys into:
+  - `credentials: { token, region, serviceAccount, serviceSecret, projectId }`
+  - `switches: { hasLocation, hasCampaigns, hasSessionIds, hasAvatar,
+    hasIOSDevices, hasAndroidDevices, hasDesktopDevices, hasBrowser,
+    isAnonymous, alsoInferFunnels, hasAdSpend, hasAttributionFlags }`
+  - `identity: { avgDevicePerUser, sessionTimeout }`
+
+  Old top-level keys keep working (verbose warn nudges migration), but new
+  dungeons should ship the sub-object shape.
 - Surviving advanced entities: `personas`, `worldEvents`, `engagementDecay`,
   `dataQuality` — use sparingly
 
@@ -59,58 +68,78 @@ Before writing any code, scan:
 
 ## File structure
 
-```javascript
-// ── TWEAK THESE ──
-const SEED = "dm4-VERTICAL";
-const num_days = 120;
-const num_users = 5_000;
-const avg_events_per_user_per_day = 1.2;
-let token = "your-mixpanel-token";
-if (process.env.MP_TOKEN) token = process.env.MP_TOKEN;
+Use the canonical layout — sections in this fixed order. Skip any section
+that doesn't apply (e.g., schema-only dungeons omit HOOK STORIES and KNOBS).
+Section delimiter: `// ── SECTION NAME ──` (box-drawing chars).
 
+```javascript
+// ── IMPORTS ──
 import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc.js";
+dayjs.extend(utc);
 import "dotenv/config";
 import * as u from "../../lib/utils/utils.js";
 import * as v from "ak-tools";
-
-const chance = u.initChance(SEED);
-
-/** @typedef  {import("../../types").Dungeon} Config */
-
-// Generate consistent IDs at module level
-const productIds = v.range(1, 200).map(n => `prod_${v.uid(8)}`);
-
-/**
- * ═══════════════════════════════════════════════════════════════
- * DATASET OVERVIEW
- * ═══════════════════════════════════════════════════════════════
+/** @typedef {import("../../types").Dungeon} Config */
+
+// ── OVERVIEW ──
+/*
+ * NAME:       <BrandName>
+ * APP:        <2-4 line description: what users do, core flow, monetization>
+ * SCALE:      <numUsers> users, ~<numEvents> events, <numDays> days (<start> → <end>)
+ * CORE LOOP:  <event1> → <event2> → <event3> → ...
  *
- * App Name — what it models, the core user loop, monetization.
- * - N users over M days, ~X events
- * - Key entities and relationships
- * - Why these events/properties were chosen
+ * EVENTS (N):
+ *   <event name (weight)> > ...   (sorted by weight desc)
  *
- * NO STORY TRENDS YET — schema only. Pass to /write-hooks for engineering.
+ * FUNNELS (N):
+ *   - <Funnel name>:  <step> → <step> (N%)
+ *
+ * USER PROPS:  <prop1, prop2, ...>
+ * SUPER PROPS: <prop1, prop2, ...>
+ * SCD PROPS:   <prop (values, freq, max)>
+ * GROUPS:      <key1, key2 | none>
  */
 
-/** @type {Config} */
-const config = {
-  token, seed: SEED,
-  numDays: num_days,
-  avgEventsPerUserPerDay: avg_events_per_user_per_day,
-  numUsers: num_users,
+// ── SCALE ──
+const SEED = "dm4-VERTICAL";
+const NUM_USERS = 5_000;
+const DATASET_START = "2026-01-01T00:00:00Z";
+const DATASET_END = "2026-05-01T23:59:59Z";
+const EVENTS_PER_DAY = 1.2;
+const token = process.env.MP_TOKEN || "your-mixpanel-token";
 
-  // Identity model — see "Identity guidelines" below
-  hasAnonIds: true,
-  avgDevicePerUser: 2,
-  hasSessionIds: true,
+const chance = u.initChance(SEED);
 
-  // I/O
-  format: "json", gzip: true, writeToDisk: false, concurrency: 1,
+// ── DATA ARRAYS ──   (omit if none)
+const productIds = v.range(1, 200).map(n => `prod_${v.uid(8)}`);
 
-  // Realistic platform
-  hasLocation: true, hasAndroidDevices: false, hasIOSDevices: false,
-  hasDesktopDevices: true, hasBrowser: true, hasAvatar: true,
+// ── CONFIG ──
+/** @type {Config} */
+const config = {
+  seed: SEED,
+  datasetStart: DATASET_START,
+  datasetEnd: DATASET_END,
+  numUsers: NUM_USERS,
+  avgEventsPerUserPerDay: EVENTS_PER_DAY,
+  format: "json",
+  gzip: true,
+  writeToDisk: false,
+  concurrency: 1,
+  macro: "flat",   // optional — see "Trend shape" below
+  soup: "growth",  // optional
+
+  credentials: { token },
+  switches: {
+    hasLocation: true,
+    hasAndroidDevices: false,
+    hasIOSDevices: false,
+    hasDesktopDevices: true,
+    hasBrowser: true,
+    hasAvatar: true,
+    hasSessionIds: true,
+  },
+  identity: { avgDevicePerUser: 2 },
 
   funnels: [ /* see "Funnels" below */ ],
   events: [ /* see "Events" below */ ],
@@ -125,6 +154,14 @@ const config = {
 export default config;
 ```
 
+When the dungeon has hooks (added later by `/write-hooks`), the layout
+extends with HOOK STORIES (full per-hook docs with Mixpanel report blocks),
+KNOBS (extracted tunable constants — timing, thresholds, multipliers),
+HOOK STATE (module-level Maps/Sets used across users), and HELPER FUNCTIONS
+(per-type handlers like `handleEventHooks`, `handleEverythingHooks`).
+`config.hook` becomes a thin dispatcher delegating to the helpers. See
+`dungeons/vertical/ecommerce.js` as the canonical exemplar.
+
 ## Required components
 
 ### 1. Events (~15–20)
@@ -234,7 +271,9 @@ If you absolutely need a stub for downstream stamping consistency, leave a
 
 The identity model has three knobs:
 
-### `avgDevicePerUser` (whole number, default 0)
+### `identity.avgDevicePerUser` (whole number, default 0)
+
+Place inside the `identity` sub-object: `identity: { avgDevicePerUser: 2 }`.
 
 | App type | Recommended | Why |
 |----------|-------------|-----|
@@ -243,7 +282,11 @@ The identity model has three knobs:
 | Multi-device-heavy product (streaming, fitness) | 2–3 | TV + phone + tablet sessions distinguishable |
 | Server / API-only product | 0 | No client device concept |
 
-`hasAnonIds: true` aliases to `avgDevicePerUser: 1`. Set both for clarity.
+**`hasAnonIds: true` is deprecated.** Use `identity.avgDevicePerUser: 1`
+directly. The deprecated alias still works through 1.5.x — when
+`hasAnonIds: true` is set without an explicit `avgDevicePerUser`, the
+validator promotes to `identity.avgDevicePerUser: 1` and emits a verbose
+warning.
 
 ### `isAuthEvent` placement
 
@@ -257,6 +300,15 @@ Flag the event that represents "user becomes identified". Put it in the
 The engine stamps user_id+device_id on this event; pre-auth funnel steps get
 device_id only; post-auth funnel steps get user_id only.
 
+**Anonymous non-converters get `_drop: true` on their profile (v1.5.1).**
+Born-in-dataset users who never reach an `isAuthEvent` step are anonymous —
+their events still flow (tied to `device_id`), but `mixpanel-sender` filters
+`_drop:true` profiles before `/engage` push. `result.profilesPushed` reports
+actual push count vs `result.userProfilesData.size` (full population). The
+`everything` hook can rescue a profile via `delete meta.profile._drop`.
+Pre-existing users (born outside window) are always considered identified
+and never get `_drop`.
+
 ### `attempts` (per-funnel, optional)
 
 ```js
@@ -406,13 +458,54 @@ skill handles this).
 ### `maxTouchpointsPerUser` (attribution cap)
 
 Top-level optional knob. Caps UTM stamping at this many events per user
-(default 10, matching Mixpanel `TOUCHPOINTS_LIMIT`). When `hasCampaigns: true`
+(default 10, matching Mixpanel `TOUCHPOINTS_LIMIT`). When `switches.hasCampaigns: true`
 and a user has more eligible events than the cap, the engine takes a
 uniform-random sample across the user's lifetime and stamps UTMs on the
 sampled events only. Sampling across lifetime (NOT first-N) preserves
 realistic touch shape — Mixpanel's last-10-window then gives meaningful
 first/last-touch attribution. Set to `Infinity` to disable the cap.
 
+**Generator/verifier asymmetry to know about:** the generator samples
+uniformly across user lifetime; the verifier (`emulateBreakdown` with
+`attributedBy`) and real Mixpanel attribution both read the **last N
+touchpoints before each conversion** (per `attributed_value_reader.cpp`).
+For users with ≤10 attribution-eligible events lifetime, no divergence
+(cap is a no-op). For users with >10 eligible events and multiple
+conversions, generator stamps may not align with Mixpanel's per-conversion
+last-10 window. Real-world impact: minor for first-touch, occasional
+divergence for last-touch in multi-conversion users. Tracked for 1.6.
+
+### `retentionCurve` (generator-side retention shape, v1.5+)
+
+Top-level optional knob. Shape retention via log-linear interpolation
+between waypoints. Independent of `engagementDecay`.
+
+```js
+retentionCurve: [
+  { day: 0,  retention: 1.0 },
+  { day: 1,  retention: 0.80 },
+  { day: 7,  retention: 0.50 },
+  { day: 30, retention: 0.20 },
+]
+```
+
+Each born-in-dataset user's events get filtered based on the interpolated
+retention at the event's age-from-first-event-day. Use when you want a
+declarative retention shape at config level (analytical-style D1/D7/D30
+targets) instead of writing hook logic.
+
+### `userSeed` (separate distinct_id RNG seed, v1.5+)
+
+Top-level optional knob. Separates the distinct_id RNG seed from the main
+`seed`. Lets you regenerate a dataset with a different event distribution
+while keeping the user pool stable across runs — useful for incremental
+data layering.
+
+```js
+seed: "v2",           // event-stream RNG (different distribution each version)
+userSeed: "users-v1", // user-pool RNG (stable across versions)
+```
+
 ## SuperProp consistency rule
 
 If `superProps` and `userProps` both define a property like `Plan`, the

package/.claude/skills/verify-dungeon/references/counting-semantics.md

@@ -7,10 +7,25 @@ Mixpanel does NOT count the way naive SQL does. The verifier (and any DuckDB que
 | Concept | Mixpanel rule | Wrong SQL → Right SQL |
 |---------|--------------|----------------------|
 | Frequency / cohort by event count | Distinct calendar days, NOT total events | `COUNT(*)` → `COUNT(DISTINCT date_trunc('day', time::TIMESTAMP))` |
-| Funnels | Greedy single-pass, strict order, 2-second grace | NEVER hand-roll funnel SQL — use `emulateBreakdown` |
-| AVG / SUM / MIN / MAX | Skip null and non-numeric from BOTH num and denom | Always wrap in `TRY_CAST(prop AS DOUBLE)` |
-| Attribution | Cap at 10 touchpoints in lookback | Use `emulateBreakdown` with `attributedBy` |
-| Conversion window | Strict `<` boundary | Read `Funnel.conversionWindowDays` and respect it |
+| Funnels | Greedy single-pass, strict order, 2-second grace (`history.cpp` `OUT_OF_ORDER_MILLISECONDS = 2000`) | NEVER hand-roll funnel SQL — use `emulateBreakdown` |
+| AVG / SUM / MIN / MAX | Skip null and non-numeric from BOTH num and denom (`normal_query.cpp:1718-1733`) | Always wrap in `TRY_CAST(prop AS DOUBLE)` |
+| Attribution | Cap at 10 touchpoints in lookback (`attributed_value_reader.cpp:16` `TOUCHPOINTS_LIMIT`) | Use `emulateBreakdown` with `attributedBy` |
+| Conversion window | Strict `<` boundary (`conversion_window.cpp:48` `t1 < t2 + 1000*len`) | Read `Funnel.conversionWindowDays` and respect it |
+| Sessions | 3-trigger split: timeout `>`, max duration `>`, day-idx change (`session_query.cpp:906-911`) | Trust pre-stamped `session_id`; group by `(user, session_id)` |
+| Retention | Birth-anchored, ms-strict gate (default `birth_can_retain=false` → `<`), bucketed by `floor((ret−birth)/unit)` (`retention_query.cpp:1097-1109,1228-1231`) | Use `emulateBreakdown` with `retention` |
+
+**Known divergences from Mixpanel C++** (1.5.1):
+- `countDistinctPeriods` default = `algorithm: 'calendar'` (UTC bucket).
+  Mixpanel C++ (`addiction_query.cpp:359`) uses ROLLING window. Pass
+  `algorithm: 'rolling'` for exact Frequency-Distribution parity.
+- COMPOUNDED retention is NOT implemented — verifier silently ignores
+  `compounded: true`. Use DuckDB or query Mixpanel directly for "DAU
+  coming back" reports.
+- Touchpoint sampling: generator stamps uniform-random across user
+  lifetime; verifier reads last-N before conversion (matches C++).
+  For users with ≤10 attribution events lifetime, no divergence.
+- List-typed property AVG/SUM: C++ auto-flattens lists per item; our
+  `nullAwareAvg` requires pre-flattened input.
 
 Full rules: see [HOOKS.md Section 2](../../../../HOOKS.md#2-how-mixpanel-counts-things).
 
@@ -63,7 +78,7 @@ For CI-style assertions, use `verifyDungeon` with a checks array; see `tests/e2e
 - **`Funnel.order` auto-dispatched.** For `sequential` / `interrupt` funnels, the emulator runs the greedy single-pass engine. For other order modes (`first-fixed`, `last-fixed`, `random`, etc.), it dispatches to `evaluateAnyOrderCompletion` (set-membership check). For `random` mode, results are `verificationKind: "informational"` — Mixpanel funnel shape doesn't apply; do not assert PASS/FAIL.
 - **Auto-sort means custom DuckDB queries can trust event order.** Per-user events arrive sorted ascending by time (default; opt out via `autoSortAfterEverything: false`). `LAG`/`LEAD` window functions work without explicit `ORDER BY time` in the partition.
 - **Auto-promote `isStrictEvent` is silent healing — not a regression.** If a stale dungeon's funnel-step events also live in `events[]`, the validator stamps `isStrictEvent: true` and warns. Verification of those dungeons may show CHANGED standalone-event counts vs older runs — that is correct behavior, not a bug to chase.
-- **Touchpoint cap = 10 enforced at generation.** `hasCampaigns: true` users get up to `maxTouchpointsPerUser` (default 10) UTM-stamped events, sampled across lifetime. Attribution checks via `attributedBy` should see realistic first/last-touch shapes, not all-stamps-at-birth.
+- **Touchpoint cap = 10 enforced at generation.** `switches.hasCampaigns: true` users get up to `maxTouchpointsPerUser` (default 10) UTM-stamped events, sampled across lifetime. Attribution checks via `attributedBy` should see realistic first/last-touch shapes, not all-stamps-at-birth. The verifier's `attributedBy` reads last-N before conversion (matches Mixpanel); the generator samples uniform across lifetime. For users with >10 attribution events lifetime, expect minor divergence on multi-conversion users.
 
 ## Hook awareness for verification
 
@@ -128,7 +143,17 @@ When the dungeon's `Funnel` config sets these fields, `verifyDungeon` auto-appli
 
 ## Identity-model dungeons — pass profiles
 
-When `avgDevicePerUser > 0` or `hasAnonIds: true`, ALWAYS pass `profiles` to `emulateBreakdown`. Without it, pre-auth `device_id` events bucket as separate "users" and your funnel/retention/attribution numbers all deflate.
+When `identity.avgDevicePerUser > 0` (or the deprecated `hasAnonIds: true`),
+ALWAYS pass `profiles` to `emulateBreakdown`. Without it, pre-auth
+`device_id` events bucket as separate "users" and your funnel/retention/
+attribution numbers all deflate.
+
+**v1.5.1 anonymous non-converter semantic:** born-in-dataset users who
+never reach an `isAuthEvent` get `_drop: true` on their profile.
+`result.profilesPushed` reports the actual push count;
+`result.userProfilesData.size` reports full population (including dropped).
+Don't be surprised if profile-count assertions show
+`profilesPushed < userProfilesData.size` — that's correct.
 
 ```js
 const events = Array.from(result.eventData);

package/.claude/skills/verify-dungeon/references/sql-recipes.md

@@ -36,14 +36,14 @@ The expected set of columns per event type is derived from config:
 | Source | Keys | Condition |
 |--------|------|-----------|
 | Core | `event`, `time`, `insert_id`, `user_id` | Always |
-| Identity | `device_id` | `avgDevicePerUser > 0` |
-| Identity | `session_id` | `hasSessionIds` |
+| Identity | `device_id` | `identity.avgDevicePerUser > 0` |
+| Identity | `session_id` | `switches.hasSessionIds` |
 | Event config | `events[i].properties` keys | Per event type |
 | Super props | `superProps` keys | All event types |
-| Location | `city`, `region`, `country`, `country_code` | `hasLocation` |
-| Browser | `browser` | `hasBrowser` |
-| Device | `model`, `screen_height`, `screen_width`, `os`, `Platform`, `carrier`, `radio` | `hasAndroidDevices`/`hasIOSDevices`/`hasDesktopDevices` |
-| Campaigns | `utm_source`, `utm_campaign`, `utm_medium`, `utm_content`, `utm_term` | `hasCampaigns` |
+| Location | `city`, `region`, `country`, `country_code` | `switches.hasLocation` |
+| Browser | `browser` | `switches.hasBrowser` |
+| Device | `model`, `screen_height`, `screen_width`, `os`, `carrier`, `radio` | `switches.hasAndroidDevices`/`hasIOSDevices`/`hasDesktopDevices`. **`Platform` removed in 1.5.1** — `os` covers the signal. Hooks/dungeons may opt back in by declaring `Platform` in event `properties`. |
+| Campaigns | `utm_source`, `utm_campaign`, `utm_medium`, `utm_content`, `utm_term` | `switches.hasCampaigns` |
 | Group keys | group key name | Per event type from `groupKeys[i][2]`, or all if empty |
 | Funnel props | `funnel.props` keys | Events in funnel sequence |
 | Experiment | `Experiment name`, `Variant name` | `$experiment_started` event |
@@ -60,7 +60,7 @@ If any event type has SCHEMA-FAIL, flag it prominently and include specific reme
 
 ## Standard identity-model invariants
 
-Run these for every dungeon that uses the identity model (`isAuthEvent` + `attempts` + `avgDevicePerUser`), BEFORE per-pattern checks:
+Run these for every dungeon that uses the identity model (`isAuthEvent` + `attempts` + `identity.avgDevicePerUser`), BEFORE per-pattern checks:
 
 ```sql
 -- Stitch event count must match converted-born count, exactly one per user.
@@ -420,7 +420,8 @@ When verifying `everything` hooks, you often MUST join events with user profiles
 
 ## Advanced feature verification
 
-Advanced features (personas, worldEvents, engagementDecay, dataQuality, subscription, attribution, geo, features, anomalies) produce data patterns alongside hooks. When verifying:
+Supported advanced features (still active in 1.5.x): `personas`,
+`worldEvents`, `engagementDecay`, `dataQuality`. When verifying:
 
 ```sql
 -- Personas: check distribution matches configured weights
@@ -432,27 +433,36 @@ SELECT promo, count(*) FROM read_json_auto('./data/verify-dungeon-EVENTS.json')
 -- Data Quality: verify bots, nulls, empty events
 SELECT 'bots' as metric, count(*) FROM read_json_auto('./data/verify-dungeon-USERS.json') WHERE is_bot = true
 UNION ALL SELECT 'null_props', count(*) FROM read_json_auto('./data/verify-dungeon-EVENTS.json') WHERE category IS NULL;
+```
 
--- Subscription: lifecycle events generated
-SELECT event, count(*) FROM read_json_auto('./data/verify-dungeon-EVENTS.json')
-WHERE event IN ('trial started','subscription started','plan upgraded','subscription cancelled') GROUP BY 1;
+Advanced feature patterns should ALWAYS be present (deterministic from config), unlike hooks which may have statistical variance.
 
--- Attribution: campaign sources on profiles
-SELECT utm_source, count(*) FROM read_json_auto('./data/verify-dungeon-USERS.json') WHERE utm_source IS NOT NULL GROUP BY 1;
+**Deprecated config blocks (silently stripped by validator since 1.4):**
+`subscription`, `attribution`, `geo`, `features`, `anomalies`. If a
+dungeon still references these, properties they used to generate
+(`subscription_plan`, `_region`, `theme`, `_anomaly`, etc.) will be
+missing from the output. Migration: add equivalents to `superProps` /
+`userProps` and drive downstream effects in `user` or `everything` hooks.
 
--- Geo: region distribution
-SELECT _region, count(*) FROM read_json_auto('./data/verify-dungeon-USERS.json') WHERE _region IS NOT NULL GROUP BY 1;
+## Standard verification checks (run for every dungeon)
 
--- Features: progressive adoption properties
-SELECT theme, count(*) FROM read_json_auto('./data/verify-dungeon-EVENTS.json') WHERE theme IS NOT NULL GROUP BY 1;
+### 0. Anonymous non-converter `_drop` audit (v1.5.1, identity-model dungeons)
 
--- Anomalies: burst/extreme events
-SELECT _anomaly, count(*) FROM read_json_auto('./data/verify-dungeon-EVENTS.json') WHERE _anomaly IS NOT NULL GROUP BY 1;
-```
+Born-in-dataset users who never reach an `isAuthEvent` get `_drop: true`
+stamped on their profile. Real Mixpanel `/engage` skips these — the
+verifier's profile-count assertions should mirror that. Quick check:
 
-Advanced feature patterns should ALWAYS be present (deterministic from config), unlike hooks which may have statistical variance.
+```sql
+SELECT
+  COUNT(*) AS total_profiles,
+  SUM(CASE WHEN _drop = true THEN 1 ELSE 0 END) AS dropped,
+  SUM(CASE WHEN _drop IS NULL OR _drop = false THEN 1 ELSE 0 END) AS would_push
+FROM read_json_auto('./data/verify-dungeon-USERS.json');
+```
 
-## Standard verification checks (run for every dungeon)
+`would_push` should equal `result.profilesPushed` from the run output.
+For pre-existing-only dungeons (`percentUsersBornInDataset: 0`) expect
+`dropped = 0`.
 
 ### 1. SuperProp Consistency
 Verify each user has exactly 1 value per superProp:
@@ -476,9 +486,18 @@ Verdict: **STRONG** ≥99% consistent, **WEAK** 90-99%, **FAIL** <90%.
 Every superProp key should also appear on user profiles. Compare the dungeon's `superProps` keys against columns in the USERS file. Any superProp not mirrored in `userProps` means the stamping fix is incomplete.
 
 ### 3. Mixpanel Default Property Casing Check
-The system generates device properties with Mixpanel's standard casing (`Platform` capital P, `os`, `model`, etc.) and location properties (`city`, `region`, `country`). If a dungeon defines a superProp with conflicting casing (e.g., lowercase `platform`), both properties appear on events — confusing in Mixpanel. Check for:
-- `platform` (lowercase) vs system `Platform` — verdict **FAIL** if dungeon uses lowercase
-- `City`, `Region`, `Country` vs system `city`, `region`, `country` — check casing matches
+The system generates device properties with Mixpanel's standard casing
+(`os`, `model`, `screen_height`, `screen_width`, `carrier`, `radio`,
+`browser`) and location properties (`city`, `region`, `country`,
+`country_code`). If a dungeon defines a superProp with conflicting casing
+(e.g., capitalized `City` vs system `city`), both properties appear on
+events — confusing in Mixpanel. Check for:
+- `City`, `Region`, `Country` (caps) vs system `city`, `region`, `country` — verdict **FAIL** if dungeon uses caps for these
+- `Browser` (caps) vs system `browser` — verdict **FAIL** if mismatched
+
+**Note:** `Platform` was REMOVED from default device props in 1.5.1.
+If a dungeon explicitly declares `Platform` in event `properties`, that's
+intentional opt-in — not a casing conflict.
 
 ### 4. funnel-pre Dilution Check
 For any dungeon with `funnel-pre` conversionRate modifications, verify the actual visible effect:

package/.claude/skills/write-hooks/SKILL.md

@@ -78,6 +78,10 @@ Inside `funnel-pre` and `funnel-post`:
 Inside `everything`:
 - `meta.authTime: number | null` — unix-ms of the stitch event, null if never authed
 - `meta.isPreAuth(event): boolean` — convenience predicate
+- `meta.profile` — full profile object. Mutate or rescue here.
+- `meta.userIsBornInDataset: boolean` — true when user was born inside the dataset window
+- `meta.scd: { <key>: SCDEntry[] }` — SCD entries per key
+- `meta.datasetStart, meta.datasetEnd: number` — unix-seconds bounds
 
 Pattern: gate trend logic on `meta.isFinalAttempt` so failed prior attempts
 don't get the same treatment as the converted attempt.
@@ -196,9 +200,10 @@ writing a custom hook:
 - **Time-series trends** ("conversion rises week over week") — wrap any
   breakdown with `timeBucket: 'week'`. Engineer via temporal-windowed hooks
   using `DATASET_START.add(N, 'days')`.
-- **Identity-model dungeons** — when `avgDevicePerUser > 0` or
-  `hasAnonIds: true`, ALWAYS pass `profiles` to verification. Auto-builds
-  identity map merging pre-auth `device_id` events with post-auth `user_id`.
+- **Identity-model dungeons** — when `identity.avgDevicePerUser > 0`
+  (or the deprecated `hasAnonIds: true`), ALWAYS pass `profiles` to
+  verification. Auto-builds identity map merging pre-auth `device_id`
+  events with post-auth `user_id`.
 
 **Schema-first reminder:** exclusion events must be declared in `events[]`
 before referencing them as `Funnel.exclusionEvents` — the validator throws
@@ -234,6 +239,10 @@ record.was_dropped = false;      // ❌ flag-stamping
 event.engineered_pattern_id = 5; // ❌ flag-stamping
 ```
 
+(One narrow exception: `meta.profile._drop` is engine-recognized — see
+the "Anonymous non-converter `_drop` rescue" section above. All OTHER
+flags must live in `userProps`/event `properties` with a declared default.)
+
 DO WRITE:
 ```js
 record.amount *= 3;                            // ✅ scale existing numeric prop
@@ -259,6 +268,25 @@ hook: function(record, type, meta) {
 }
 ```
 
+### Anonymous non-converter `_drop` rescue (v1.5.1)
+
+Born-in-dataset users who never reach an `isAuthEvent` step get
+`_drop: true` stamped on their profile BEFORE the `everything` hook fires.
+`mixpanel-sender` filters those before pushing to `/engage`. Hooks can
+rescue a profile by deleting the flag:
+
+```js
+if (type === 'everything' && meta.profile) {
+  // Rescue: keep some anonymous power-users in /engage even without sign_up.
+  const eventCount = record.length;
+  if (eventCount >= 20) delete meta.profile._drop;
+}
+```
+
+`_drop` is the ONE engine-recognized flag a hook may set/clear on a
+profile — every other property must be declared in `userProps` first per
+the anti-flag-stamping rule below.
+
 When a dungeon uses funnel `attempts`, hooks can reach into individual attempts
 via funnel-post meta:
 

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.5.2 — 2026-05-21
+
+Docs-only patch. Aligns the `.claude/skills/` authoring + verification
+guides with the 1.5.1 engine + config API. No runtime changes.
+
+### Changed
+
+- **`create-dungeon` skill** now emits the canonical dungeon layout
+  (IMPORTS / OVERVIEW / SCALE / DATA ARRAYS / CONFIG sections) and the
+  sub-object config API (`credentials` / `switches` / `identity`).
+  Removed the old `// ── TWEAK THESE ──` template + flat-key example.
+- **`create-dungeon` skill** documents `hasAnonIds` as deprecated; nudges
+  authors to write `identity.avgDevicePerUser: 1` directly.
+- **`create-dungeon` skill** adds sections for `retentionCurve`,
+  `userSeed`, anonymous-non-converter `_drop: true` semantics, and
+  flags the touchpoint-sampling generator/verifier asymmetry.
+- **`write-hooks` skill** documents the `meta.profile._drop` rescue
+  pattern (the one engine-recognized flag a hook may set/clear on a
+  profile). Expanded `meta` interface listing for the `everything` hook.
+- **`verify-dungeon/references/counting-semantics.md`** notes known
+  divergences from Mixpanel C++ (calendar vs rolling distinct-period
+  default, COMPOUNDED retention not implemented, touchpoint sampling
+  asymmetry, list-typed AVG/SUM no auto-flatten). All references to
+  `hasAnonIds: true` updated to the new `identity.avgDevicePerUser` shape.
+- **`verify-dungeon/references/sql-recipes.md`** drops `Platform` from
+  the expected device-keys table (removed in 1.5.1; `os` covers the
+  signal). Updates casing check to drop `Platform`-vs-`platform` rule.
+  Adds an anonymous-non-converter `_drop` audit query as standard check
+  #0 for identity-model dungeons. Updates "Advanced feature verification"
+  to list only currently-supported features (`personas`, `worldEvents`,
+  `engagementDecay`, `dataQuality`); calls out the deprecated config
+  blocks (`subscription`, `attribution`, `geo`, `features`, `anomalies`)
+  the validator silently strips.
+
+### Why
+
+Skills are how most dungeons get authored. Drifting between skill-emitted
+output and 1.5.1 engine behavior would silently produce stale-shape
+dungeons + missed coverage of new features (`retentionCurve`, `userSeed`,
+`_drop` semantics, sub-object API). Patch keeps skill output and engine
+behavior synchronized.
+
+## 1.5.1 — 2026-05-20
+
+Quality + ergonomics release. No new analytical capabilities — fixes accumulated rough edges around concurrency, accuracy, profiles, and config ergonomics that surfaced after 1.5.0 shipped. Adds a generator-side retention shaper, exposes a config sub-object API for cleaner dungeon files, and restructures all 48 shipped dungeons to a canonical layout. Top-level keys keep working for back-compat.
+
+### Added
+
+- **`credentials` / `switches` / `identity` config sub-objects.** New ergonomic shape for grouping related dungeon keys: `credentials: { token, region, serviceAccount, serviceSecret, projectId }`, `switches: { hasLocation, hasCampaigns, hasSessionIds, hasAvatar, isAnonymous, ... }`, `identity: { avgDevicePerUser, sessionTimeout }`. `mergeConfigSubObjects` hoists sub-object values into top-level keys at validation time; top-level still wins when both set (with a verbose warn). Old flat top-level keys keep working — back-compat suite in `tests/unit/config-restructure.test.js`.
+- **`retentionCurve` config knob.** Generator-side retention shaper. Accepts an array of `{day, retention}` waypoints; the engine interpolates log-linearly to drop late events per user based on first-event age. Independent of `engagementDecay`. Enables analytical-style retention shapes (D1 80% → D7 50% → D30 20%) at dungeon-config level instead of via hooks.
+- **Per-macro `avgActiveDaysPerUser` defaults.** When `avgActiveDaysPerUser` is unset, defaults derived per macro: steady=15, growth=10, viral=20, decline=5, flat=20 (numDays/4 cap). Removes the need to hand-tune for every macro.
+- **`COUNT_DISTINCT` aggregation in `emulateBreakdown`** (`type: 'distinctCount'`). Mirrors Mixpanel's count-distinct measure for cohort sizing / unique-user breakdowns.
+- **`userSeed` config knob.** Separate distinct_id seed from the main `seed`. Lets you regenerate a dataset with a different event distribution while keeping the user pool stable across runs — useful for incremental data layering.
+- **`result.profilesPushed`** count exposed on the `Result` object. Reports how many profiles actually got pushed to `/engage` after `_drop` filtering.
+- **`runWithDataset(begin, now, fn)`** API for explicit dataset-window scoping (rare — most callers don't need this; in-process `generate()` calls now auto-scope via AsyncLocalStorage).
+
+### Changed
+
+- **Anonymous non-converters get `_drop: true` stamped on their profile.** Real-world Mixpanel `$identify` semantics — profiles only exist for users who actually identified. Born-in-dataset users who never reach an `isAuthEvent` step in their first funnel are anonymous: events still flow (tied to `device_id`), but no profile is pushed to `/engage`. `userProfilesData` still contains every profile object; `mixpanel-sender` filters `_drop:true` before push. Pre-existing users are considered already-identified and never get `_drop`. The `everything` hook can rescue a profile by `delete meta.profile._drop`.
+- **`numEvents` more accurate.** Removed dice rolls + `0.714` magic dampening from per-user budget computation; replaced with a clean `chance.normal(mean=budget, dev=budget/3)`. Old behavior overshot the target by 1.6-2x; new behavior matches the configured rate within ±3% across all 5 macros at 50K target. **If you previously tuned `avgEventsPerUserPerDay` around the old overshoot, expect ~40-60% fewer events at the same rate.** Recompute targets.
+- **Default `Platform` device property removed.** 59 entries commented out in `lib/templates/defaults.js` (15 iOS + 15 Android + 29 Desktop). `os` already carries the platform signal. If a dungeon reads `Platform` in hooks or downstream, you'll see undefined — define `Platform` explicitly in your event properties to opt back in.
+- **`hasAnonIds` deprecated.** Use `identity.avgDevicePerUser: 1` instead. The deprecated alias still works through 1.5.x: when `hasAnonIds: true` is set without an explicit `avgDevicePerUser`, the validator promotes to `avgDevicePerUser: 1`.
+- **`DATASET_NOW` / `DATASET_BEGIN` scoped via AsyncLocalStorage.** No more module-level mutable globals. In-process concurrent `generate()` calls with different `datasetStart`/`datasetEnd` windows now produce isolated, in-window output. Legacy `setDatasetNow` / `setDatasetBegin` setters remain as back-compat shims.
+- **UTC bare-date parsing** for `datasetStart` / `datasetEnd`. `"2026-01-01"` parses as `2026-01-01T00:00:00Z`, not as local-midnight (which shifted the window by UTC offset).
+- **Quiet by default.** `verbose: false` (default) now gates all warnings, info logs, and dataset-context messages. Set `verbose: true` to opt back into the chatty output.
+- **GCS upload retry hardening.** 10 retries with exponential backoff, 10-minute total budget. Handles transient cloud upload failures without giving up.
+- **>64K user runs no longer crash V8.** Internal data structure swap (`Array` for sparse-keyed maps) eliminates V8 limit hit at high user counts.
+- **All 48 shipped dungeons restructured to canonical layout.** Sections in fixed order: IMPORTS → OVERVIEW → HOOK STORIES → SCALE → KNOBS → DATA ARRAYS → HOOK STATE → HELPER FUNCTIONS → CONFIG. Hook stories preserve full per-hook Mixpanel report docs; `config.hook` becomes a thin dispatcher delegating to per-type helpers (`handleEventHooks`, `handleEverythingHooks`, etc.). Zero behavioral changes — every dungeon's seed-pinned output is unchanged.
+- **All 49 dungeons + ~18 test fixtures migrated to the new sub-object API.** Cosmetic adoption only — `mergeConfigSubObjects` already supported both shapes since Phase 1.
+
+### Fixed
+
+- **Standalone events now stamp `config.superProps`.** Was silently `{}` before — masked by the validator's auto-funnel pre-fix in 1.5.0. Surfaced by the `numEvents` overshoot fix when the `useFunnel` gate started routing more users to the standalone path.
+- **Born-late funnel auth events past `FIXED_NOW` no longer set `userAuthTimeMs`.** Engine drops the event at storage time (`funnels.js:640`) but previously still recorded the auth-time, marking the user as authed without a real sign_up event. Fix gates `authTimeMs` on `!_drop` (`funnels.js:328`). Affected 1-2% of users in test runs.
+- **Pre-existing user events strict-clamp at `FIXED_BEGIN`.** Born-outside-window users no longer leak events into the pre-dataset window via TimeSoup's sub-window distribution.
+
+### Docs
+
+- **HOOKS.md targeted edits.** Recipe 4.25 (First-Touch Attribution Bias) gains a v1.5 note pointing to Recipe 4.26's OVERWRITE pattern when `hasCampaigns: true`. Atom catalog gains a footnote that `injectBetween` / `injectBurst` / `injectAfterEvent` / `injectOnNewDays` no longer require trailing `record.sort(...)` calls — covered by `autoSortAfterEverything: true` default since 1.5.0.
+- **`docs/guides/1.5.1-upgrade-guide.md`** — TL;DR + per-change action items for existing dungeon authors.
+
+### Infra
+
+- 95+ commits across the branch; 1269 vitest tests pass; engine canary 10/10; engine-shape full sweep 194/194; smoke test 20/20 verticals; 5-vertical hook verifier matches Sprint 1 baseline (ecommerce 10/10, fitness 12/12, sass 10/10, social 11/11, dating 11/13 pre-existing small-mode artifacts).
+
 ## 1.5.0 — 2026-05-08
 
 The "count and verify like Mixpanel does" release. Aligns BOTH the data generation engine AND the verifier with Mixpanel's actual counting semantics — greedy single-pass funnels, distinct-period frequency counting, null-aware aggregation, touchpoint-capped attribution, identity merge, retention, sessions, time-bucketed trends. Removes `bunchIntoSessions`, the root cause of funnel ordering corruption since 1.0.

package/HOOKS.md

@@ -1183,6 +1183,13 @@ first-touch result as stamping 10 — Mixpanel's attribution module
 (`attributed_value_reader.cpp`) only considers `TOUCHPOINTS_LIMIT = 10`. Aim
 for sparse, deterministic touches.
 
+**v1.5 with `hasCampaigns: true`:** when the engine has already stamped UTMs
+on up to `maxTouchpointsPerUser` events per user (default 10), DO NOT stamp
+fresh touches in your hook — they'd push the user past the cap and fall
+outside Mixpanel's last-10 window. Use [Recipe 4.26](#426-bias-engine-stamped-touches-v15)
+to OVERWRITE the engine's `utm_source` on the existing stamped events
+instead. See [§2.4](#24-attribution-caps-at-10-touchpoints).
+
 ---
 
 #### 4.26 Bias Engine-Stamped Touches (v1.5)
@@ -1326,6 +1333,12 @@ Import from `@ak--47/dungeon-master/hook-helpers`:
 | `isPreAuthEvent` | identity | `(event, authTime) -> boolean` | Check if before user's stitch |
 | `splitByAuth` | identity | `(events, authTime) -> { preAuth, postAuth, stitch }` | Partition by auth boundary |
 
+**Inject atoms + v1.5:** the engine auto-sorts events by time after the
+`everything` hook (`autoSortAfterEverything: true` default — see Principle
+26). Hooks using `injectBetween` / `injectBurst` / `injectAfterEvent` /
+`injectOnNewDays` no longer need a trailing `record.sort(...)` to keep the
+greedy funnel engine happy.
+
 Full JSDoc in [`lib/hook-helpers/*.js`](lib/hook-helpers/).
 
 ---