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

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

@@ -0,0 +1,468 @@
+---
+name: write-hooks
+description: Use when an existing dungeon needs engineered story trends or "magic number" patterns — writes the `hook` function using atom helpers and high-level patterns. Adds no new event flags; never mutates the schema.
+argument-hint: [path/to/dungeon.js] [free-text story / trend description]
+model: claude-opus-4-6
+effort: max
+---
+
+# Write Hooks
+
+Engineer story trends into the dungeon at `$ARGUMENTS` (first positional arg)
+based on the story description (remaining args).
+
+## Scope
+
+This skill writes the `hook` function ONLY. It assumes the dungeon's schema is
+already complete (produced by `create-dungeon`). After writing, hand off to
+`/verify-dungeon` to confirm the engineered patterns actually appear.
+
+In scope:
+- The `hook: function(record, type, meta) { ... }` body
+- Documentation comments above the hook explaining each engineered pattern,
+  including a reference Mixpanel report block per pattern
+
+Out of scope:
+- Schema changes (events, properties, funnels, superProps, userProps).
+  Only modify schema if the hook can't possibly work without a new field —
+  and even then, prefer changing the value enumeration over adding a new field.
+- New top-level config knobs.
+- Removing the `hook: function...` body to start over with a new schema.
+
+## Reference reading
+
+- `lib/hook-helpers/index.js` — atoms (cohort, mutate, timing, inject,
+  identity). One file per group; full JSDoc on each atom.
+- `lib/hook-patterns/index.js` — high-level recipes (one per Mixpanel
+  analysis type).
+- `lib/verify/emulate-breakdown.js` — what `verify-dungeon` will check.
+- `dungeons/user/my-buddy.js` — reference dungeon using a mix of atoms and
+  hand-rolled logic.
+- `dungeons/technical/pattern-*.js` — five minimal pattern fixtures, one per
+  recipe.
+- `HOOKS.md` — encyclopedia of hook recipes organized by story pattern. Contains
+  17+ worked examples with code snippets, Mixpanel report instructions, and
+  adaptation notes. **Start here** to find the right pattern for your story.
+
+## Hook execution model
+
+Hooks fire in this order per user (see `CLAUDE.md` for the canonical reference):
+
+1. `"user"` — profile created. Mutate in place; return ignored.
+2. `"scd-pre"` — SCD entries created. Mutate in place OR return new array.
+3. For each funnel: `"funnel-pre"` → `"event"` (per step) → `"funnel-post"`.
+
+**`funnel-pre` is now reliable for temporal patterns.** Usage funnels advance a
+cursor after each run, so successive `meta.firstEventTime` values spread across
+the user's active window. Persona and world-event modifiers apply BEFORE the
+hook — the hook has final authority on `conversionRate`, `timeToConvert`, and
+`props`.
+4. `"event"` — for non-funnel standalone events. Return value REPLACES the event.
+5. `"everything"` — array of ALL the user's events. Return array to replace.
+
+**Most engineered trends belong in `everything`.** It sees the full user stream,
+has access to `meta.profile` / `meta.scd` / `meta.authTime` / `meta.isPreAuth`,
+and you can mutate freely.
+
+Storage-only hooks (`ad-spend`, `group`, `mirror`, `lookup`) fire later in the
+pipeline and don't see the same `meta` shape.
+
+## Hook meta — identity context
+
+Inside `funnel-pre` and `funnel-post`:
+- `meta.isFirstFunnel: boolean`
+- `meta.isBorn: boolean` (user born inside dataset window)
+- `meta.attemptsConfig: { min, max, conversionRate? } | null`
+- `meta.attemptNumber, meta.totalAttempts, meta.isFinalAttempt`
+
+Inside `everything`:
+- `meta.authTime: number | null` — unix-ms of the stitch event, null if never authed
+- `meta.isPreAuth(event): boolean` — convenience predicate
+
+Pattern: gate trend logic on `meta.isFinalAttempt` so failed prior attempts
+don't get the same treatment as the converted attempt.
+
+Inside `funnel-pre` and `funnel-post` (when experiment is active):
+- `meta.experiment.name: string` — experiment name
+- `meta.experiment.variantName: string` — assigned variant
+- `meta.experiment.variantIndex: number` — 0-based index
+- `meta.experiment.conversionMultiplier: number`
+- `meta.experiment.ttcMultiplier: number`
+- `meta.experiment` is `null` when no experiment or funnel run is before start date
+
+Pattern: use `funnel-post` + `meta.experiment` to inject variant-specific
+downstream effects:
+
+```js
+if (type === 'funnel-post' && meta.experiment) {
+  if (meta.experiment.variantName === 'Variant B') {
+    // Winner variant: inject downstream engagement event
+    const last = record[record.length - 1];
+    record.push(cloneEvent(last, {
+      event: 'Agenda Generated',
+      time: dayjs(last.time).add(5, 'minutes').toISOString(),
+    }));
+  }
+}
+```
+
+## Atom + pattern catalog
+
+### Atoms (`@ak--47/dungeon-master/hook-helpers`)
+
+| File | Atom | Purpose |
+|------|------|---------|
+| cohort | `binUsersByEventCount(events, eventName, bins)` | Classify by per-user event count (Insights total events) |
+| cohort | `binUsersByEventInRange(events, eventName, start, end, bins)` | Same, time-windowed |
+| cohort | `countEventsBetween(events, eventA, eventB)` | Count between first A and first B |
+| cohort | `userInProfileSegment(profile, key, values)` | Profile-property cohort check |
+| mutate | `cloneEvent(template, overrides)` | Spread+override a template event |
+| mutate | `dropEventsWhere(events, predicate)` | In-place filter with count |
+| mutate | `scaleEventCount(events, eventName, factor)` | >1 clones, <1 drops. **Targets Insights Total reports.** For frequency-distribution movement use `injectOnNewDays` |
+| mutate | `scalePropertyValue(events, predicate, prop, factor)` | Multiply numeric prop |
+| mutate | `shiftEventTime(event, deltaMs)` | Shift one event's time |
+| timing | `scaleTimingBetween(events, A, B, factor)` | Scale gap between first A and next B |
+| timing | `scaleFunnelTTC(funnelEvents, factor)` | Scale all step offsets from anchor |
+| timing | `findFirstSequence(events, [names], maxGapMin)` | Detect ordered run within window |
+| inject | `injectAfterEvent(events, source, template, gapMs, overrides)` | Splice clone after source |
+| inject | `injectBetween(events, A, B, template, overrides)` | Splice at midpoint |
+| inject | `injectBurst(events, template, count, anchorTime, spreadMs, overrides)` | Burst around anchor |
+| inject | `injectOnNewDays(events, eventName, targetDistinctDays)` | **Cohort-only.** Spreads injections across previously-empty days. Use for cohort-conditional active-day boosts; for global active-day shape, use `Dungeon.avgActiveDaysPerUser` config knob. |
+| identity | `isPreAuthEvent(event, authTime)` | Standalone variant of meta.isPreAuth |
+| identity | `splitByAuth(events, authTime)` | { preAuth, postAuth, stitch } partition |
+
+### Hook anti-patterns
+
+- **DO NOT engineer global active-day distribution in hooks.** Use the
+  `Dungeon.avgActiveDaysPerUser` config knob — it's a concentrator that
+  preserves total event count while clustering events onto fewer days.
+  Hooks own cohort-conditional patterns ("premium users get 7+ days") only.
+
+### Intentional strict-bar deviation is OK
+
+The engine guarantees the no-hook baseline (`dungeons/technical/simplest.js`)
+satisfies the per-macro strict bar across the 194-combo sweep matrix
+(see [CLAUDE.md "Engine guarantees"](../../../CLAUDE.md#engine-guarantees)).
+**Hooks can intentionally violate the strict bar** for legitimate stories:
+
+- **Decline + churn cohort** (engagementDecay or `everything`-hook event-drop)
+  produces tail_ratio < 0.4 — well below the decline bar's 0.4 floor. This is
+  the design intent of a sunset story.
+- **Viral hook + persona-driven late-cohort lift** can push the spike above
+  the viral preset's 7.0 cap. Hockey-stick stories are louder than the engine
+  baseline.
+- **World-event spike** (e.g., a launch-day burst of 5x normal volume) creates
+  a single-day right-edge spike above the spike cap.
+
+When you write a hook that intentionally violates the strict bar, document the
+deviation in the dungeon's overview JSDoc + the hook's pattern documentation
+block. Engine-validation guarantees apply to **no-hook configs only**; hooks
+own their shape.
+- **DO NOT hand-sort `everything` hook output.** The engine auto-sorts events
+  ascending by time after `everything` returns (default ON; opt out via
+  `autoSortAfterEverything: false`). Cloned events with arbitrary timestamps
+  no longer need explicit sort calls.
+- **DO NOT stamp UTM properties from scratch in attribution hooks.** The
+  engine caps UTM stamping at `maxTouchpointsPerUser` (default 10) per user,
+  sampled across lifetime. Stamping fresh would push users past the cap; your
+  stamps would land outside Mixpanel's last-10 lookback window. OVERWRITE
+  engine-stamped values instead (e.g., `event.utm_source = "google"` on
+  already-stamped touches).
+
+### When to use the verifier primitives
+
+When designing a story, check if any of the new primitives match before
+writing a custom hook:
+
+- **Retention curves** ("70% retain at day 1, 30% at day 7") — verify with
+  `emulateBreakdown({ type: 'retention', cohortEvent, returnEvent, dayBuckets })`.
+  No special hook needed; engineer cohort behavior via `engagementDecay`,
+  `dropEventsWhere`, or per-user filtering in `everything`.
+- **Session metrics** ("avg session has 6 events, lasts 4 minutes") — verify
+  with `emulateBreakdown({ type: 'sessionMetrics' })`. Trust pre-stamped
+  `session_id`. Engineer via `avgEventsPerUserPerDay` + `engagementDecay`.
+- **Reentry funnels** ("power users complete the funnel 3+ times") — set
+  `Funnel.reentry: true` (verifier hint). Engineer multiple completions via
+  `funnel-post` injecting cloned funnel sequences for that cohort.
+- **Exclusion patterns** ("rage-clickers never convert") — declare an event
+  in `events[]` (e.g., `rage_click`), set `Funnel.exclusionEvents: ['rage_click']`.
+  The generator stamps it on non-converters; the verifier terminates the
+  attempt when it sees one.
+- **HPC / per-cart funnels** ("checkout completion per item type") — use
+  `evaluateFunnelHPC(events, steps, holdProperty)` directly (not auto-routed
+  through `funnelFrequency`).
+- **Step filters** ("only iOS users complete step 2") — set
+  `Funnel.stepFilters: { 1: { prop: 'platform', op: 'eq', value: 'iOS' }}`.
+- **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`.
+
+**Schema-first reminder:** exclusion events must be declared in `events[]`
+before referencing them as `Funnel.exclusionEvents` — the validator throws
+on undeclared entries.
+
+### Patterns (`@ak--47/dungeon-master/hook-patterns`)
+
+Higher-level recipes. Each maps to ONE Mixpanel analysis the verify-dungeon
+emulator can re-derive.
+
+| Pattern | Mixpanel analysis | Hook type |
+|---------|-------------------|-----------|
+| `applyFrequencyByFrequency` | Insights — count(A) by per-user count(B) | everything |
+| `applyFunnelFrequencyBreakdown` | Funnels — completion by per-user count(X) | funnel-post |
+| `applyAggregateByBin` | Insights — avg(prop X) by per-user count(B) | everything |
+| `applyTTCBySegment` | Funnel TTC — broken down by user-property segment | funnel-post |
+| `applyAttributedBySource` | Conversions by Source (first/last touch) | everything |
+
+Use a pattern when the trend matches its analysis 1:1. Drop down to atoms when
+the trend is bespoke or composite.
+
+## Anti-flag-stamping rule (HARD WALL)
+
+Hooks MUST NOT add new properties to records. The schema (config) defines what
+properties exist; hooks modify VALUES of existing properties or inject events
+cloned from existing ones.
+
+DO NOT WRITE:
+```js
+record.is_whale = true;          // ❌ flag-stamping
+record.cohort = "engaged";       // ❌ flag-stamping
+record.was_dropped = false;      // ❌ flag-stamping
+event.engineered_pattern_id = 5; // ❌ flag-stamping
+```
+
+DO WRITE:
+```js
+record.amount *= 3;                            // ✅ scale existing numeric prop
+record.payday = true;                          // ✅ ONLY if `payday: [false]` exists in event config
+const clone = cloneEvent(template, {time, user_id});  // ✅ clone existing event
+events.push(clone);                            // ✅ inject from template
+return events.filter(e => !shouldDrop(e));     // ✅ filter inside `everything`
+```
+
+If a trend genuinely needs a new property and the schema doesn't have it, add
+the property to the EVENT CONFIG with a default value (typically `[null]` or
+`[false]`), not via the hook.
+
+## Identity-aware hook patterns
+
+When a dungeon uses `isAuthEvent`, hooks can branch on auth state:
+
+```js
+hook: function(record, type, meta) {
+  if (type !== 'everything' || !Array.isArray(record)) return record;
+  // Drop pre-auth funnel attempts that fired errors — analytics cleanup
+  return record.filter(e => !(e.event === 'API Error' && meta.isPreAuth(e)));
+}
+```
+
+When a dungeon uses funnel `attempts`, hooks can reach into individual attempts
+via funnel-post meta:
+
+```js
+if (type === 'funnel-post' && meta.isFirstFunnel && !meta.isFinalAttempt) {
+  // Failed prior attempt — reduce its event count to model "abandoned quickly"
+  scaleEventCount(record, record[0].event, 0.5);
+}
+```
+
+## Pattern documentation block
+
+Above the `hook` function (or in the dataset overview comment), document each
+engineered pattern with a Mixpanel report block. This is what verify-dungeon
+checks against and what consumers read to understand the dataset.
+
+```
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. POWER USERS BUY 3X MORE (everything, applyFrequencyByFrequency)
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * PATTERN: Users with 15+ Browse events buy 3× as often as users with <5 Browse.
+ *
+ * MIXPANEL REPORT:
+ *   Type: Insights
+ *   Event: "Purchase"
+ *   Measure: Frequency Distribution
+ *   Breakdown: per-user count of "Browse"
+ *   Expected ratio: bin>=15 / bin<5 ≈ 3x (within ±15%)
+```
+
+## Hook Ordering Within `everything`
+
+The order of operations inside the everything hook matters when hooks interact:
+
+1. **SuperProp stamping** — stamp profile values onto events (always first)
+2. **Temporal value mutations that DON'T need cloned events** — e.g., version stamping
+3. **Behavioral detection + event cloning** — agentic detection, KYC clones, pro clones, magic number clones
+4. **Event filtering** — churn, retention, rate-limit drops
+5. **Temporal value mutations that NEED cloned events** — e.g., spring price boost, gas spike, outage errors (always LAST before sort)
+6. **Sort** — `userEvents.sort((a, b) => new Date(a.time) - new Date(b.time))`
+
+**Why:** If a temporal mutation runs before cloning, cloned events that land in
+the temporal window miss the mutation. Moving temporal value mutations to the
+end ensures ALL events in the window — original and cloned — receive the effect.
+
+## Deprecated Feature Replacement
+
+When a dungeon relied on deprecated config blocks (`subscription`, `attribution`,
+`features`, `geo`, `anomalies`) for properties that hooks depend on, those
+properties no longer appear in the data. Replace them:
+
+1. Add the property to `superProps` and `userProps` with default values
+2. Assign meaningful values in the `user` hook (based on hash, persona, or profile)
+3. Use the assigned values in `everything` to drive downstream effects
+
+Example: deprecated `subscription` → add `subscription_tier` to superProps/userProps,
+assign tiers by hash in user hook, gate conversion/feature effects on tier in everything.
+
+## Cohort Sizing Guidelines
+
+Cohort detection conditions must be selective enough to create a meaningful
+control group, but not so broad they catch everyone:
+
+| Detection | Problem | Fix |
+|-----------|---------|-----|
+| `events.some(e => e.event === X)` with common X | 90%+ of users qualify | Require 3+ events: `events.filter(...).length >= 3` |
+| `charCodeAt(0) % 50 === 0` | Only 2% of users | Increase modulus denominator or use `% 10` for 10% |
+| `profile.tier === "premium"` | Fixed by config distribution | Adjust userProps distribution if cohort too small |
+| `earlyEvents.length >= 5` for a low-weight event | 0% qualify (impossible threshold) | Check actual distribution first, set at ~80th percentile |
+
+Target: 10-30% of users in the affected cohort for clean signal at 10K users.
+
+### Threshold Calibration
+
+When a hook gates on "N+ events of type X in first Y days," check the actual
+distribution BEFORE choosing the threshold. With 200 event types and 2.5
+events/user/day, a weight-7 event might produce only ~0.2 per user per day.
+Setting threshold=5 for 7 days means ~0% of users qualify. Run this check
+in your smoke test:
+
+```sql
+SELECT n, COUNT(*) FROM (
+  SELECT user_id, COUNT(*) as n FROM events WHERE event = 'X' GROUP BY user_id
+) GROUP BY n ORDER BY n LIMIT 15;
+```
+
+Set the threshold at approximately the 80th percentile of the distribution.
+
+### Compounding Drop Hooks
+
+Use at most ONE drop-based retention hook per dungeon. Multiple hooks that
+each drop events after the same day threshold compound destructively:
+
+- Hook A: drop 40% after day 21 for non-loyal users
+- Hook B: drop 60% after day 21 for non-streak users
+- Combined: 76% drop for users in both groups (which is 95% of users)
+
+The control group barely exists. Fix: use boost-based patterns
+(`scaleEventCount(events, "X", 1.8)`) for positive cohorts instead of drops
+for negative cohorts. Boosts are additive and don't interact destructively.
+Reserve drops for a single churn/retention effect per dungeon.
+
+## Common Hook Pitfalls
+
+Apply these BEFORE handing off to `/verify-dungeon`. See HOOKS.md §9 for full recipes.
+
+### isStrictEvent: false is NOT optional for hook-read events
+
+If your hook reads `event === 'X'` and `X` is also a funnel-step event, the
+validator auto-promotes it to `isStrictEvent: true` and the engine
+won't emit standalone occurrences. Your cohort goes empty.
+
+```js
+// BAD — login is a funnel step + read by hook
+events: [{ event: 'login', weight: 4, properties: {...} }]
+// GOOD — explicit opt-out preserves standalone occurrences
+events: [{ event: 'login', weight: 4, isStrictEvent: false, properties: {...} }]
+```
+
+Audit: any event referenced in the `everything` hook by name AND appearing
+as a funnel step needs `isStrictEvent: false`.
+
+### Reentry on per-instance loops
+
+Funnels named "X loop" / "X cycle" / "session" / repeated user behaviors
+need `Funnel.reentry: true`. Without it, the engine produces ONE funnel
+sequence per user — no recurring loops. Examples that need it: workout
+loop, match flow, search-to-book, order fulfillment, engagement loop, tour
+funnel.
+
+### Hash-based cohorts produce textbook signals
+
+Cleanest hidden-cohort pattern. No flag, no schema mutation, easy to verify
+deterministically:
+
+```js
+// 2% whales with 50x trade amount → long-tail Insights distribution
+const isWhale = uid.charCodeAt(0) % 50 === 0;
+if (isWhale && e.event === 'swap') e.trade_amount_usd *= 50;
+```
+
+Use a large multiplier (≥10x, ideally 50x) so the signal beats soup noise.
+Use `% 50` for ~2% whales, `% 25` for ~4% bots, `% 10` for ~10% cohorts.
+
+### Hook ordering inside `everything`
+
+If hook A injects events that hook B mutates, B must run AFTER A in the
+same `everything` block — otherwise the injected events miss B's mutation.
+The existing "Hook Ordering Within `everything`" section above codifies
+this; the eval revealed it as the single most common subtle bug.
+
+### Avoid behavioral cohorts where the gating event IS the signal
+
+If hook says "users who did X often → reduce X count", the verifier sees
+inverted signal because users with high X naturally have higher absolute
+counts even after reduction. Either:
+- Use hash cohort for the same effect, OR
+- Verify by per-user post/pre ratio instead of raw counts
+
+### Don't reference profile.X unless X is a defined userProp
+
+```js
+// BAD — profile.level isn't in userProps; resolves to undefined
+if (meta.profile.level >= 50) e.gold_earned *= 3;
+// GOOD — verify by SPREAD instead, OR add level to userProps with weighted distribution
+```
+
+When the hook references a missing profile field, you can still get the
+data spread you want (gold range), but the cohort can't be analytically
+recovered. Either add the userProp or rewrite the hook to use a hash
+cohort.
+
+## Workflow
+
+1. Read the dungeon at `$ARGUMENTS[0]` and understand the existing schema.
+2. Translate the user's story description into 3–5 engineered patterns.
+   Consult `HOOKS.md` for recipe ideas that match the user's story. Each recipe
+   includes the hook type, code snippet, and Mixpanel report format.
+3. For each pattern:
+   - Pick a pattern from `lib/hook-patterns/` if it fits the analysis 1:1.
+   - Otherwise compose atoms from `lib/hook-helpers/`.
+   - Document the pattern in a comment block (Mixpanel report instructions).
+4. Write the `hook` function, importing atoms/patterns at the top of the file.
+5. Smoke-test:
+   ```bash
+   node scripts/verify-runner.mjs <dungeon> verify-dungeon --small
+   ```
+   Confirm the run completes without errors.
+6. Hand off:
+   ```
+   /verify-dungeon <dungeon>
+   ```
+   If verify-dungeon returns WEAK, NONE, or INVERSE on any pattern, return to
+   step 4 and refine. Iterate until all patterns score STRONG or NAILED.
+
+## Stopping condition
+
+Stop after `/verify-dungeon` reports all engineered patterns as STRONG or NAILED,
+OR after three iterations without convergence — at that point, document what's
+still off in the dungeon's overview comment and report the gap to the user.
+
+## Output
+
+Modify the dungeon file in place. Add the `hook` function. Add the imports.
+Add the documentation block above the config. Do NOT modify any other file.
+Tell the user to run `/verify-dungeon <dungeon>` next.

package/CHANGELOG.md

@@ -2,6 +2,153 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 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.
+
+### Generator changes
+
+#### Added
+- **`avgActiveDaysPerUser`** — Concentrates events onto fewer distinct UTC days per user. Uses weighted-without-replacement day picking from soup DOW weights. Events per active day scale naturally (`rate × remaining_days ÷ active_days`). Interacts correctly with `engagementDecay` (protects last event per picked day from being dropped).
+- **`conversionWindowDays`** on funnels — Explicit conversion window (default 30, hard cap 180). Validator auto-bumps when `timeToConvert` exceeds the default. Funnel generator caps step-to-step time to the window. Verifier and `emulateBreakdown` apply the same window.
+- **`maxTouchpointsPerUser`** — Per-user touchpoint cap (default 10) matching Mixpanel's `attributed_value_reader.cpp`. Engine samples eligible events across user lifetime using `chance.pickset`, stamps UTMs on the sample only. Replaces the old inline 25% UTM stamping in `events.js`.
+- **`autoSortAfterEverything`** — Auto-sorts user events by time after the `everything` hook (default `true`). Defends greedy funnel verification from out-of-order hook-injected events. Opt out with `autoSortAfterEverything: false`.
+- **`isStrictEvent` auto-promote** — Config validator detects events that appear in both `events[]` and `funnels[].sequence` and auto-promotes them to `isStrictEvent: true`. Prevents greedy engine corruption where standalone instances of funnel-step events confound conversion counting. Opt out per-event with `isStrictEvent: false`. Runs BEFORE catch-all funnel creation.
+- **`Funnel.exclusionEvents: string[]`** — events that terminate the funnel for non-converters. Generator stamps 1-2 cloned events bearing one of the listed names between the last completed step and where the next step would have been. Schema-first: validator throws on undeclared entries; cloned events copy ONLY identity + super props + group keys + props declared on the exclusion event's own config (no source-event prop pollution).
+- **`Funnel.reentry: boolean`** — verifier-only hint. Auto-applied by `verifyDungeon` to matching `funnelFrequency` / `timeToConvert` checks.
+- **`Funnel.stepFilters: Record<number, { prop, op, value }>`** — verifier-only hint. The verifier attaches `where`-clauses at the matching step index.
+- **Session day-boundary split** — `assignSessionIds` now ends a session at the UTC day boundary (matches Mixpanel `session_query.cpp:828-830, 911`). Three reset triggers: timeout gap > 30 min, max session > 24h, OR day-index change.
+- **`weightedSampleNoReplacement`** — Seeded weighted sampling utility for active-day picking and touchpoint selection.
+
+#### Changed
+- **`bunchIntoSessions` removed.** Was a wholesale timestamp overwrite that scrambled funnel ordering and destroyed TimeSoup's time distribution. Replaced by natural TimeSoup-driven timestamps + `assignSessionIds` (which was already running but had its work overwritten by `bunchIntoSessions`). Events now arrive in correct temporal order without post-hoc rewriting.
+- **Standalone events use `isFirstEvent: false`.** Previously all standalone events used `isFirstEvent: true`, pinning them to the same timestamp. The old `bunchIntoSessions` retimed them — now TimeSoup distributes them directly.
+- **UTM stamping moved to per-user pass.** Inline per-event UTM stamping in `events.js` replaced by `applyTouchpointCap` in `user-loop.js`. Runs after all events are generated, samples up to `maxTouchpointsPerUser` eligible events. Matches Mixpanel's attribution counting behavior.
+- **Funnel generator respects conversion window.** When a funnel's step-to-step span exceeds `conversionWindowDays`, the generator scales `relativeTimeMs` to fit.
+- **`funnelFeatureCtx` preserves `latestTime`.** Bug fix: was dropping `featureCtx.latestTime`, causing funnel first events to use the full `[earliest, FIXED_NOW]` range instead of the picked day's bounds in active-day mode.
+- **Empty event pool bail-out.** When all events are funnel steps (auto-promoted to strict) and there are no standalone events, the user loop skips standalone generation instead of crashing on `pick([])`.
+- **Future-event filter now logs in verbose mode.** Events past `FIXED_NOW` (from catch-all funnel TTC drift) are filtered with a verbose log showing count, user, and time range.
+- **`buildActiveDayPlan` returns `pickedDayBuckets`.** Shape changed from `number[] | null` to `{ plan, pickedDayBuckets } | null` so engagement decay can protect last events on active days.
+- **User loop wrapped in try/finally.** SIGINT cleanup (progress interval, user count reset) runs even on error.
+
+### Verifier changes
+
+The "verify like Mixpanel does" half. Adds counting primitives behind `emulateBreakdown` so engineered hook patterns can be verified against the same shapes Mixpanel computes.
+
+#### Added
+- **Identity resolution** — `buildIdentityMap(profiles)` inverts each profile's `device_ids` / `anonymousIds` (legacy field name supported) into a flat `Map<device_id, canonical_user_id>`. `resolveUserId(event, identityMap)` resolves a single event with priority: `event.distinct_id` → identity map → `event.user_id` → `event.device_id` (Mixpanel canonical post-merge id wins). `emulateBreakdown` auto-builds the map when `profiles` are passed (any breakdown type, hoisted above `timeBucket` recursion to avoid rebuild per partition).
+- **Funnel engine extensions** — `evaluateFunnel` accepts:
+  - `reentry: boolean` — re-runs state machine after each completion; `result.completions` reports total.
+  - `exclusionSteps: [{ event, afterStep?, beforeStep? }]` — events that terminate the current attempt. `afterStep`/`beforeStep` use the index of the step that must (have) been reached; defaults `afterStep=-Infinity`, `beforeStep=steps.length` (fires anywhere, used by simple `Funnel.exclusionEvents` shape). Cooperates with reentry.
+  - Step filters — steps may be `{ event, where: { prop, op, value } }`. Supported ops: eq, neq, gt, lt, gte, lte, contains, not_contains.
+  - `trackStepProperties: boolean | string[]` — captures matched event properties at each step into `result.stepProperties`.
+  - `countMode: 'uniques' | 'totals'` — totals mode returns `FunnelResult[]` (Mixpanel `funnel_query.cpp:2055-2100`). Includes incomplete attempts so per-step drop-off counts are preserved (`history_get_reached >= 0`, NOT "completed"). Without reentry: single-attempt array.
+  - `sessionScoped: boolean` — partition by `session_id`, run per session. Verifier-only convenience; Mixpanel's closest analog is `WINDOW_TYPE_SESSIONS` on the conversion window.
+- **HPC** — `evaluateFunnelHPC(events, steps, holdProperty, options)` runs parallel sub-funnels per unique value of the held property on the step-0 event. Returns `Map<value, FunnelResult | FunnelResult[]>`. NOT auto-routed through `funnelFrequency` (different report shape); call directly inside `verifyDungeon` checks.
+- **Segment modes** — `resolveFunnelSegment(result, 'first' | 'last' | { step: N })` picks property snapshot for FIRST_TOUCH / LAST_TOUCH / STEP modes.
+- **`emulateBreakdown({ type: 'sessionMetrics' })`** — group by user→session, emit `[{ metric, avg, median, p90, total_sessions }]` for count / duration / eventsPerSession. Trusts pre-stamped `session_id`. Optional `event` filter restricts to sessions containing a target event (verifier-only convenience).
+- **`emulateBreakdown({ type: 'retention' })`** — birth-anchored ms-delta bucketed retention (`retention_query.cpp:1227-1231`). A return 23h after birth lands in bucket 0; 25h lands in bucket 1. `birthCanRetain: false` default (`retention_query.cpp:1097-1109`). Inputs `cohortEvent`, `returnEvent`, `dayBuckets`. Optional `segmentBy` partitions cohort by birth event property (`segment_event=FIRST` mode); optional `carry_forward` marks once-retained users as retained on later buckets (CARRY_FORWARD unbounded mode).
+- **`emulateBreakdown({ timeBucket: 'day' | 'week' | 'month' })`** — cross-cutting wrapper on every breakdown type. Partitions events by UTC bucket, tags rows with `period: string` (`YYYY-MM-DD`, `YYYY-Www`, `YYYY-MM`). Optional `timeBucketRange: { from, to }` enumerates every bucket and emits `{ period, _empty: true }` markers for empty intervals (Mixpanel `normal_query.cpp:352-356` parity).
+- **`aggregatePerUser` cohort-level rollup** — `cohort_sum` / `cohort_min` / `cohort_max` field added when the per-user `agg` is `sum`/`count`/`min`/`max`. `avg_aggregate` always populated. Matches Mixpanel's "Aggregate per user" report column for the corresponding agg mode.
+- **`partitionByTimeBucket(events, bucket, options?)`** — exposed helper. Accepts `{ from, to }` for empty-bucket enumeration.
+- **`evaluateAnyOrderCompletion`** — Verifier function for `unordered`/`random` funnel modes. `emulateBreakdown` auto-dispatches based on `funnel.order`.
+
+#### Changed
+- **Identity resolver order** — `event.distinct_id` now wins over the merge map (Mixpanel canonical post-merge id; never demote).
+- **Sessions split on UTC day** — `session_query.cpp:828-830` parity (added to `assignSessionIds` AND `sessionMetrics`).
+
+### Documented divergences (intentional v1.5.0 scope gaps)
+
+- **HPC list-property values** — scalar only; Mixpanel `aggregate_hash_get_key_cursor` explodes list values into N sub-funnels per event.
+- **`sessionScoped` funnel** + **`sessionMetrics({ event })`** — verifier-only conveniences; not directly reproducible in Mixpanel UI.
+- **Retention COMPOUNDED, CARRY_BACK, CONSECUTIVE_FORWARD, CALENDAR_START, segment_event=SECOND, cohort window, week/month bucket units** — out of v1.5.0 scope.
+- **Timezone** — verifier uses UTC; Mixpanel uses query timezone (qtz).
+- **Percentiles** — linear interpolation (d3.quantile); Mixpanel uses TDigest.
+- **Selector grammar** — eq/neq/gt/lt/gte/lte/contains/not_contains only; no is_set/between/regex/contains_ci.
+
+### Backward Compatibility
+
+- **No breaking changes to the public API.** `DUNGEON_MASTER(config)` signature unchanged. All named exports unchanged.
+- Existing dungeons run without modification. New config fields are additive and optional.
+- `bunchIntoSessions` removal changes timestamp distribution for all dungeons. Events now follow TimeSoup's natural distribution instead of being rewritten into synthetic session clusters. This is more correct — funnels maintain temporal ordering.
+- `isStrictEvent` auto-promote may reduce standalone event variety for dungeons where funnel-step events overlap with `events[]`. Add `isStrictEvent: false` on specific events to preserve standalone instances.
+- Touchpoint cap (default 10) reduces UTM-stamped events from ~25% of all events to at most 10 per user. Attribution analysis produces more realistic distributions.
+- UTC day-boundary session split may produce more sessions per user than 1.4 (sessions crossing midnight now split). Session metrics shift accordingly.
+
+### Documentation
+
+- **`research/1.5.0-upgrade-guide.md`** — consumer upgrade guide with behavioral changes, new verifier capabilities, identity-aware verification requirement.
+- **CLAUDE.md** updated with `avgActiveDaysPerUser`, `conversionWindowDays`, `maxTouchpointsPerUser`, `autoSortAfterEverything`, active-day distribution section, 15-step execution order.
+- **HOOKS.md** — §2.4 touchpoint generation contract, §2.5 active-day distribution, §2.6–2.10 (sessions, retention, reentry, HPC, segment modes), §8 v1.5.0 verification recipes (8 patterns).
+- **Skill files** updated: `create-dungeon`, `write-hooks`, `verify-dungeon` with v1.5 considerations + new primitive table.
+
+### Engine validation + strict clamps (post-eval ship gate)
+
+Final 1.5.0 hardening pass — proves the engine produces clean, in-band charts across the param space and adds validator guards against the worst foot-guns. Methodology + sweep evidence: `plans/ENGINE-VALIDATION/FIX.md`.
+
+#### Engine
+
+- **`FUNNEL_DEAD_ZONE_CAP_SEC = 0`** (`lib/orchestrators/user-loop.js`). Earlier rounds reserved a 1-day "dead zone" before `FIXED_NOW` for funnel step-1 anchors to defend against a cursor-accumulation bug. Round 1 fixed the cursor accumulation directly, leaving the cap as defense-in-depth. The future-time guard at storage step 14 already drops any `time > FIXED_NOW`, so removing the cap is safe — funnels can now anchor right up to `FN`. Eliminates the last-day cliff for funnel-heavy dungeons. Verified across 194-combo sweep: `futureEvents == 0` everywhere.
+
+#### Validator strict clamps (`lib/core/config-validator.js`)
+
+Seven clamps with `console.warn` messages explaining what changed and why. All fire either unconditionally (sanity bounds) or only when the user explicitly overrides via top-level field OR `macro: { preset, ... }` object override (raw preset names exempt — preset values are designed to be safe).
+
+| # | Clamp | Trigger | Action |
+|---|-------|---------|--------|
+| 1 | `percentUsersBornInDataset` ∈ [0, 100] | Always | Clamp + warn |
+| 2 | Per-macro born cap (flat=12, steady=12, growth=30, viral=55, decline=5) | User-explicit `macro` AND user-explicit `percentUsersBornInDataset` | Clamp + warn |
+| 3 | `bornRecentBias` ∈ [-0.5, 0.5] | User-explicit (incl. macro-object override) | Clamp + warn |
+| 4 | Compound: `born > 60 && bias > 0.4` → bias=0.3 | User-explicit (either) | Clamp + warn |
+| 5 | `bornRecentBias` ∈ [-1, 1] (`Math.pow` guard) | Always | Clamp |
+| 6 | `avgEventsPerUserPerDay` > 50 → 50 | Always | Clamp + warn (recompute `numEvents`) |
+| 7 | `avgActiveDaysPerUser` > `numDays * 0.5` → `floor(numDays * 0.5)` | Always | Clamp + warn |
+
+Plus a warning-only check for `numDays < 14` (window may be pinned via `datasetStart`/`datasetEnd` upstream).
+
+#### Sweep harness (`scripts/sweep-engine.mjs`)
+
+Validates `dungeons/technical/simplest.js` (no-hook baseline) across a 194-combo cross-product matrix of macro × numDays × born × rate × activeDays. Per-macro strict bars match each preset's design intent (flat is stationary, viral is hockey-stick). Pinned to most-recent past Wednesday-EOD-UTC anchor for full calendar-day determinism — back-to-back runs produce zero metric drift. **194 / 194 PASS.**
+
+`tests/unit/engine-shape-canary.test.js` — 10-test ~5s canary (runs every commit) with fixed-date pinning (`datasetEnd = '2026-04-30T23:59:59Z'`).
+
+`tests/e2e/engine-shape-full-sweep.test.js` — gated by `RUN_FULL_SWEEP=1`, runs the full 194-combo matrix (~5.5 min). Pre-release acceptance gate.
+
+#### Hook compatibility
+
+Spot-checked 5 verticals post-fix: **56 / 56 hook checks PASS** (fitness 12, dating 13, ecommerce 10, sass 10, social 11). Hook magnitudes match prior eval within ±10%. Engine fix is hook-compatible at full fidelity. None of the 20 vertical dungeons set `percentUsersBornInDataset` / `bornRecentBias` / `avgEventsPerUserPerDay > 50` explicitly → validator clamps don't fire on existing dungeons.
+
+#### Documentation
+
+- **CLAUDE.md** — new "Tuning guidance — safe ranges and engine guarantees (v1.5)" section under "Trend Shape — Macro and Soup". Per-tunable safe-range table, 6 strict-bar conditions, per-macro bar values, known-engine-guarantees subsection.
+- **types.d.ts** — JSDoc `safe range` + clamp behavior on `numDays`, `percentUsersBornInDataset`, `bornRecentBias`, `avgEventsPerUserPerDay`, `avgActiveDaysPerUser`.
+- **`.claude/skills/create-dungeon/SKILL.md`** — macro × born% compatibility note + clamp warnings.
+- **`.claude/skills/write-hooks/SKILL.md`** — "intentional strict-bar deviation" pattern (decline + churn cohorts and viral-with-persona-lift can intentionally exceed bars).
+
+### Test Suite
+
+Full suite: **46 files, 1100+ tests** (was 960 in 1.4). Engine-validation pass adds 12 (10 canary + 2 clamp + 4 macro-object form, minus updates) → **1122 passed / 2 skipped**. Highlights:
+
+| File | Tests | Coverage |
+|------|-------|----------|
+| Generator: `active-days`, `conversion-window`, `order-mode-dispatch`, `touchpoint-cap`, `strict-event-autopromote`, `auto-sort`, `interrupt-funnel`, `datagen-determinism`, `decay-respects-active-days` | 41 | Engine changes |
+| `tests/unit/identity-resolution.test.js` | 14 | Map inversion, resolver fallback chain |
+| `tests/unit/funnel-engine.test.js` (extended) | 51 | Reentry, exclusion, HPC, step filters, step properties, segment modes, sessionScoped — 5+ ported fixtures from `test_qt_funnel.py` |
+| `tests/unit/session-metrics.test.js` | 11 | count/duration/eventsPerSession + day-boundary + ported `test_qt_sessions.py` fixture |
+| `tests/unit/retention.test.js` | 9 | ms-delta bucketing + birthCanRetain + carry_forward + segmentBy + ported `test_qt_retention.py` fixture |
+| `tests/unit/time-bucketed.test.js` | 11 | day/week/month + cross-cutting + empty backfill |
+| `tests/integration/identity-model.test.js` (extended) | +1 | `emulateBreakdown` profile-merge round-trip |
+| `tests/integration/hook-patterns-emulator.test.js` (extended) | +7 | Funnel options + new breakdown types + cohort SUM/MAX |
+| `tests/integration/features.test.js` (extended) | +4 | exclusionEvents validator + injection + schema-clean clone |
+
+## 1.4.5 — 2026-05-06
+
+### Added
+
+- **Progress callback.** Callers can pass `onProgress: (update) => void` on the dungeon config to receive throttled updates during generation, import, and pipeline step transitions. Update frequency is configurable via `progressInterval` (default 500ms). The callback is fault-tolerant — bad functions are caught and disabled after 3 failures, never breaking the job. Return value includes a `progress` summary with update count, error count, and disabled flag.
+- **Mixpanel import progress.** When `onProgress` is set and a Mixpanel token is provided, import progress from `mixpanel-import`'s `progressCallback` is surfaced through the same `onProgress` interface as `{ phase: "import" }` updates.
+- **Full TypeScript typings** for `ProgressUpdate` (discriminated union), `ProgressSummary`, `ProgressGeneration`, `ProgressImport`, and `ProgressStep`.
+
 ## 1.4.4 — 2026-05-06
 
 The "GCS imports actually work now" release.