@ak--47/dungeon-master 1.5.1 → 1.5.3

package/.claude/skills/analyze-soup/SKILL.md

@@ -134,7 +134,12 @@ FROM (
 
 ## Step 3: Write Report
 
-Create `soup-analysis.md` in the project root with:
+Create `soup-analysis.md` with the structure below. For a user dungeon
+(`dungeons/user/<name>/<name>.js`) write it into the dungeon's folder
+(`dungeons/user/<name>/soup-analysis.md`) — everything about a dungeon lives in
+its folder. Otherwise write it to the project root. (The generated
+`./data/soup-analysis-EVENTS.json` is throwaway verification data — leave it in
+`./data/`.) Contents:
 
 1. **Config**: The soup parameters used (peaks, deviation, mean, numDays)
 2. **Summary stats**: Total events, event count, avg EPS

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

@@ -18,7 +18,7 @@ box. It does **NOT** engineer story trends or magic numbers — those are the
 should be:
 
 ```
-/write-hooks dungeons/user/<your-dungeon>.js "describe the trends to engineer"
+/write-hooks dungeons/user/<name>/<name>.js "describe the trends to engineer"
 ```
 
 In scope here:
@@ -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
 
@@ -54,63 +63,83 @@ Before writing any code, scan:
 - `lib/utils/utils.js` — `pickAWinner`, `weighNumRange`, `initChance`, `exhaust`,
   `takeSome` for property value distributions
 - `dungeons/vertical/sass.js` — B2B reference dungeon with full identity model
-- `dungeons/user/my-buddy.js` — consumer-app reference (gitignored)
+- `dungeons/user/my-buddy/my-buddy.js` — consumer-app reference (gitignored)
 - `dungeons/technical/identity-model-verify.js` — minimal identity-model fixture
 
 ## 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
@@ -431,9 +524,9 @@ userProps:  { Plan: PLANS, Region: REGIONS, Role: ROLES, ... },
 
 After writing the file:
 
-1. Smoke-test: `node scripts/verify-runner.mjs dungeons/user/<file>.js verify-<file> --small`. Confirm zero errors.
-2. Hand to the next skill: `/write-hooks dungeons/user/<file>.js "describe trends"`.
-3. After hooks land: `/verify-dungeon dungeons/user/<file>.js`.
+1. Smoke-test: `node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name> --small`. Confirm zero errors.
+2. Hand to the next skill: `/write-hooks dungeons/user/<name>/<name>.js "describe trends"`.
+3. After hooks land: `/verify-dungeon dungeons/user/<name>/<name>.js`.
 
 ## Property Type Reference
 
@@ -457,8 +550,20 @@ When designing event properties, always consider which Mixpanel type best repres
 
 ## Output
 
-Write the file to `dungeons/user/<descriptive-name>.js`. Do NOT inject hooks.
-Do NOT use `subscription`, `attribution`, `geo`, `features`, or `anomalies`
-(the engine will silently strip them and warn).
+**One folder per customer/dungeon.** Pick a short, kebab-case `<name>` from the
+app/customer, then **create `dungeons/user/<name>/` if it doesn't already exist**
+(`mkdir -p dungeons/user/<name>`) and write the dungeon to
+`dungeons/user/<name>/<name>.js` (e.g. `dungeons/user/acme/acme.js`). Folder and
+file share the name, matching `kodiak/kodiak.js`, `my-buddy/my-buddy.js`.
+
+This keeps `dungeons/user/` organized — EVERYTHING about this dungeon lives in
+the same folder: `hook-results.md` + `hook-query-log.txt` +
+`<name>-verifications.sql` (from `verify-dungeon`), `soup-analysis.md` (from
+`analyze-soup`), briefs, schema CSV/JSON, example data. The only thing kept
+outside is the throwaway verification data the runs write to `./data/` (cleaned
+after).
+
+Do NOT inject hooks. Do NOT use `subscription`, `attribution`, `geo`,
+`features`, or `anomalies` (the engine will silently strip them and warn).
 
 When done, tell the user the next skill to run.

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

@@ -102,13 +102,33 @@ For emulator details, identity-model dungeons (must pass `profiles`), and time-s
 - Experiment invariants (variant distribution, exposure timing, deterministic assignment) when any funnel uses `experiment:`
 - SuperProp consistency, SuperProp/UserProp mirror, Mixpanel default-property casing, funnel-pre dilution
 
-### Step 5: Stash query log (optional)
+### Artifact location
 
-If `./research/` exists locally, write every DuckDB query execution to `./research/hook-query-log.txt`. Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format). If `./research/` does not exist, skip — do not create the directory.
+**Everything about a dungeon lives in its folder.** When the dungeon being
+verified is a user dungeon at `dungeons/user/<name>/<name>.js`, write ALL
+generated artifacts into `dungeons/user/<name>/`:
+- `hook-results.md` (Step 6)
+- `hook-query-log.txt` (Step 5)
+- `<name>-verifications.sql` (Step 6b)
 
-### Step 6: Write `./research/hook-results.md`
+The ONLY exception is the throwaway verification data the run writes to
+`./data/` (`verify-*` event/user files) — that stays in `./data/` and is
+deleted in Step 7.
 
-Use the templates in [report-format.md](references/report-format.md):
+For non-user dungeons (technical/vertical) or batch runs across many dungeons,
+fall back to `./research/` for `hook-results.md` / `hook-query-log.txt`.
+
+### Step 5: Stash query log
+
+Write every DuckDB query execution to `hook-query-log.txt`:
+- **User dungeon:** always write to `dungeons/user/<name>/hook-query-log.txt`.
+- **Otherwise:** if `./research/` exists locally, write to `./research/hook-query-log.txt`; if it doesn't exist, skip — do not create the directory.
+
+Format and conventions: see [report-format.md "Query log format"](references/report-format.md#query-log-format).
+
+### Step 6: Write `hook-results.md`
+
+Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./research/hook-results.md`. Use the templates in [report-format.md](references/report-format.md):
 - Single-dungeon report structure
 - Multi-dungeon report structure (when batch mode)
 - Per-hook detail block
@@ -118,7 +138,7 @@ Use the templates in [report-format.md](references/report-format.md):
 
 ### Step 6b: Write verification SQL (mandatory for user dungeons)
 
-When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file at `dungeons/user/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
+When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. Vertical dungeons already have their SQL in `verification/verticals/`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
 
 ### Step 7: Cleanup
 
@@ -148,9 +168,9 @@ Return-value behavior:
 ## Final output
 
 Tell the user:
-1. Report path: `./research/hook-results.md`
-2. Verification SQL path (for user dungeons): `dungeons/user/<name>-verifications.sql`
-3. Query log path (if written): `./research/hook-query-log.txt`
+1. Report path: `dungeons/user/<name>/hook-results.md` (user dungeon) or `./research/hook-results.md`
+2. Verification SQL path (for user dungeons): `dungeons/user/<name>/<name>-verifications.sql`
+3. Query log path (if written): alongside the report (`dungeons/user/<name>/hook-query-log.txt`, else `./research/hook-query-log.txt`)
 4. Pass/weak/fail counts (per dungeon if batch mode)
 5. One-line summary of the most interesting finding
 

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/report-format.md

@@ -1,6 +1,6 @@
 # Report Format
 
-Templates and conventions for writing `./research/hook-results.md` and per-dungeon verification SQL.
+Templates and conventions for writing `hook-results.md` and per-dungeon verification SQL. For user dungeons these live in the dungeon's folder (`dungeons/user/<name>/`); otherwise in `./research/`. See [SKILL.md "Artifact location"](../SKILL.md).
 
 ## Verdict criteria (5-tier)
 
@@ -147,9 +147,7 @@ Each hook's detailed section follows this template (same for single and multi-du
 
 ## Query log format
 
-If `./research/` exists locally, write a plain-text log of every DuckDB query execution to `./research/hook-query-log.txt`. If `./research/` does not exist, skip this step entirely — do not create the directory.
-
-Check with: `ls -d ./research/ 2>/dev/null`
+Write a plain-text log of every DuckDB query execution to `hook-query-log.txt`. For a user dungeon, write it to the dungeon's folder (`dungeons/user/<name>/hook-query-log.txt`). Otherwise, only if `./research/` exists locally write `./research/hook-query-log.txt` — if it doesn't exist, skip this step entirely (don't create the directory; check with `ls -d ./research/ 2>/dev/null`).
 
 Use a consistent delimited format — one block per query, separated by a ruler line. DuckDB table output is preserved verbatim:
 
@@ -191,7 +189,7 @@ grep "^DUNGEON:" research/hook-query-log.txt           # list of dungeons querie
 
 ## Verification SQL file (mandatory for user dungeons)
 
-When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon at `dungeons/user/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
+When verifying a dungeon in `dungeons/user/`, write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. This file is the reproducible verification artifact — anyone can re-run it against fresh data.
 
 Follow the format in `verification/verticals/`:
 
@@ -200,8 +198,8 @@ Follow the format in `verification/verticals/`:
 -- <name>.js — Hook Verification SQL (N hooks)
 -- ============================================================================
 -- USAGE:
---   1. node scripts/verify-runner.mjs dungeons/user/<name>.js verify-<name>
---   2. duckdb < dungeons/user/<name>-verifications.sql
+--   1. node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name>
+--   2. duckdb < dungeons/user/<name>/<name>-verifications.sql
 --   3. rm -f verify-<name>-*
 -- ============================================================================
 

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: