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

package/.claude/skills/verify-dungeon/references/report-format.md

@@ -4,13 +4,17 @@ Templates and conventions for writing `hook-results.md` and per-dungeon verifica
 
 ## Verdict criteria (5-tier)
 
-- **NAILED** — Within 10% of expected value/ratio. Direction correct, magnitude precise. The story reads exactly as documented.
-- **STRONG** — Within 25% of expected. Direction correct, clearly visible. An analyst would find this pattern immediately.
-- **WEAK** — Within 50% of expected. Directionally correct but magnitude is off, OR sample size is too small to be conclusive.
-- **NONE** — No statistically meaningful difference between cohorts. The hook has no observable effect.
-- **INVERSE** — Effect goes the opposite direction from intended. The story is backwards.
+Verdicts are **mechanical** — computed by `scripts/verify-stories.mjs` from each story assertion's declared `target` / `floor` / `minCohort` (see the `StoryVerdict` typedef in `types.d.ts`), not eyeballed percentages:
 
-NAILED and STRONG are passing verdicts. WEAK, NONE, and INVERSE are failing verdicts that require investigation.
+- **NAILED** — observed within ±10% of `target`.
+- **STRONG** — passes `floor` (or `target` when no floor is declared).
+- **WEAK** — fails `floor` but effect direction is correct, **or** the selected cohort is smaller than `minCohort`. The population floor is a hard cap: a 12-user cohort can never score NAILED, no matter how clean its ratio.
+- **NONE** — no measurable effect, or the selection matched no rows.
+- **INVERSE** — effect direction is opposite the assertion.
+
+Story verdict = worst assertion verdict. NAILED and STRONG are passing; WEAK, NONE, and INVERSE fail and require investigation.
+
+Hand-assigned verdicts appear only in the legacy no-stories fallback and MUST follow the same definitions: derive a target from the hook's knob constants, compute the band the observed value lands in, and state the derivation in the detail block — never assign a tier by feel.
 
 ## Ordering: failures first
 
@@ -25,6 +29,8 @@ The summary table should also be sorted this way (INVERSE → NONE → WEAK →
 
 ## Single-dungeon report structure
 
+For story-backed dungeons, `hook-results.md` **renders the runner's JSON**: run `verify-stories.mjs --json` and build the Hook Summary table directly from its per-story records (story id, hook number, archetype, observed vs target per assertion, computed verdict). Do not recompute verdicts the runner already settled. Detailed Results blocks exist only for stories below STRONG, `duckdb`-type assertions, and legacy no-stories hooks.
+
 ```markdown
 # Dungeon Verification Report
 
@@ -191,7 +197,7 @@ grep "^DUNGEON:" research/hook-query-log.txt           # list of dungeons querie
 
 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/`:
+Follow the format in `dungeons/vertical/<name>/`:
 
 ```sql
 -- ============================================================================
@@ -211,4 +217,4 @@ Follow the format in `verification/verticals/`:
 
 Each query block includes the pattern description, observed result, and verdict as SQL comments. This makes the file self-documenting and grep-friendly.
 
-**This step is mandatory for user dungeons.** Vertical dungeons already have their SQL in `verification/verticals/`. User dungeons keep theirs co-located with the dungeon file.
+**This step is mandatory for user dungeons.** Vertical dungeons already have their SQL co-located at `dungeons/vertical/<name>/<name>.sql`. User dungeons keep theirs co-located with the dungeon file.

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

@@ -20,7 +20,11 @@ already complete (produced by `create-dungeon`). After writing, hand off to
 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
+  including a reference Mixpanel report block per pattern and the mandatory
+  EXPECTED METRICS SUMMARY table
+- The `stories` named export — one machine-checkable story per engineered
+  pattern (see "Stories export" below). A hook without stories is
+  unverifiable; this skill is not done until the stories exist.
 
 Out of scope:
 - Schema changes (events, properties, funnels, superProps, userProps).
@@ -29,6 +33,18 @@ Out of scope:
 - New top-level config knobs.
 - Removing the `hook: function...` body to start over with a new schema.
 
+**Before writing a hook, ask: is this trend structural?** Between-path
+comparisons (path X converts worse / slower than path Y, detour-takers drop
+off, mix shift drags the blended rate) are better architected as initial
+conditions — duplicate funnels with swapped steps/props/`conversionRate`/
+`timeToConvert`/`weight` (see the "Structural trend engineering" section in
+`create-dungeon`). If a story reduces to structure, recommend the funnel
+change back to the schema instead of writing a hook to fight the engine —
+the knob IS the expected value, which makes the story band knob-derivable
+(NAILED-capable) instead of confounded (STRONG-capped). Hooks are for
+within-cohort behavior: segments doing more/less of something over time,
+property values that differ by cohort, injected bursts, lifecycle waves.
+
 ## Reference reading
 
 - `lib/hook-helpers/index.js` — atoms (cohort, mutate, timing, inject,
@@ -36,8 +52,11 @@ Out of scope:
 - `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/my-buddy.js` — reference dungeon using a mix of atoms
-  and hand-rolled logic.
+- `lib/templates/story-spec.schema.json` + `DungeonStory` in `types.d.ts` —
+  the story-spec grammar the `stories` export must follow.
+- `dungeons/vertical/ecommerce/ecommerce.js` — reference dungeon using a mix
+  of atoms and hand-rolled logic, with the mandatory EXPECTED METRICS SUMMARY
+  table and a full `stories` export.
 - `dungeons/technical/pattern-*.js` — five minimal pattern fixtures, one per
   recipe.
 - `HOOKS.md` — encyclopedia of hook recipes organized by story pattern. Contains
@@ -134,6 +153,10 @@ if (type === 'funnel-post' && meta.experiment) {
 | 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 |
+| cohort | `hashCohort(id, pct)` | Deterministic pct% cohort (0–100 scale). **Use this first for hidden cohorts** — replaces ad-hoc `charCodeAt % N`. When one dungeon needs several NON-overlapping cohorts, gate on disjoint `hashFloat(uid)` bands instead (e.g. `[0, 0.45)`, `[0.45, 0.70)`) |
+| shape | `applyLifecycleWave(events, uid, opts)` | Dormancy window + resurrection burst for Lifecycle reports. When-to-use: the story is "users go quiet, then come back". Gap discipline: ONE stray value moment inside the window destroys the Resurrected read — size `dormantDays` to cover ≥2 whole lifecycle periods, keep the window inside the user's lifespan |
+| shape | `applyPathBias(events, uid, opts)` | Inject a Flows path after the user's FIRST anchor occurrence. When-to-use: the story is "X% of users take this route". `share` is a 0–1 FRACTION (not `hashCohort`'s pct scale); needs ~≥0.20–0.25 to survive Sankey top-3-per-level pruning; per-step gaps clamped ≥1s so ordering survives |
+| shape | `applySessionShape(events, uid, opts)` | Retime the whole stream into `sessionsPerWeek` clusters of `sessionMinutes`. When-to-use: session-duration/cadence stories (sessionMetrics reads). Retiming ONLY — no adds/drops; intra-session gaps stay <28min, inter-session >30min, no cluster crosses UTC midnight. Combine with `hashCohort` for per-role shapes; call BEFORE `applyPathBias` so injected paths keep their own tight gaps |
 
 ### Hook anti-patterns
 
@@ -214,17 +237,51 @@ on undeclared entries.
 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 |
+| Pattern | Mixpanel analysis | Hook type | Caveat (HOOKS.md) |
+|---------|-------------------|-----------|-------------------|
+| `applyFrequencyByFrequency` | Insights — count(A) by per-user count(B) | everything | `binBy` defaults to `'distinctDays'` (v1.6) — bins match Mixpanel's per-user distinct-day counting, not raw event totals |
+| `applyFunnelFrequencyBreakdown` | Funnels — completion by per-user count(X) | funnel-post | When funnels share a step prefix, restrict scaling to the target funnel — scaling every instance lets first-occurrence funnel evaluation assemble chains across unscaled instances and the ratio never reaches the report |
+| `applyAggregateByBin` | Insights — avg(prop X) by per-user count(B) | everything | Same `binBy: 'distinctDays'` default as above |
+| `applyTTCBySegmentV2` | Funnel TTC — broken down by user-property segment | everything | v1 (`applyTTCBySegment`, funnel-post) is **deprecated**: Mixpanel TTC reads each step's FIRST occurrence per user, so per-run gap scaling only reaches the report on `isFirstFunnel` runs. V2 finds the greedy first sequence (`findFirstSequence`) and scales that |
+| `applyAttributedBySource` | Conversions by Source (first/last touch) | everything | OVERWRITES the engine-stamped touch the chosen model reads; never stamps UTMs onto unstamped events (would blow the `maxTouchpointsPerUser` cap and land outside the last-10 lookback) |
 
 Use a pattern when the trend matches its analysis 1:1. Drop down to atoms when
 the trend is bespoke or composite.
 
+### New story archetypes (v1.6) — design rules per report family
+
+Four archetypes joined the story-spec enum in v1.6. Each has a
+non-negotiable design rule learned the hard way:
+
+- **`lifecycle-wave`** (`applyLifecycleWave`) — GAP DISCIPLINE. Mixpanel's
+  "dormant" state is an `EqualTo 0` filter over the whole period: one stray
+  value-moment event inside the dormancy window (including events OTHER hooks
+  injected earlier in the same `everything` pass) flips the user out of
+  Resurrected. Run the wave AFTER every injecting hook, size `dormantDays` to
+  ≥2 lifecycle periods, and keep `dormantFromDay + dormantDays` inside the
+  user's lifespan (the future-time guard eats bursts past dataset end).
+- **`path-share`** (`applyPathBias`) — FIRST-FLOW ANCHORING. Flows' unique
+  counting reads only each user's FIRST flow past the anchor, so the injected
+  path must follow the FIRST anchor occurrence (the atom does this; don't
+  hand-roll a later anchor). Sankey prunes to the top ~3 branches per level:
+  an engineered branch below ~20–25% share silently disappears from the
+  visualization even though the data is there. Label-only path reads can
+  INVERT when a busier cohort glues extra visible events between path steps —
+  assert the share on the cohort you engineered, not globally.
+- **`session-shape`** (`applySessionShape`) — 30-MIN STRADDLING + MIDNIGHT
+  RULE. Mixpanel derives sessions with a 30-min idle timeout and splits at
+  UTC midnight. Engineered cadences must keep intra-session gaps clearly
+  UNDER 30min and inter-session gaps clearly OVER it — a gap that straddles
+  the timeout makes session counts jitter across runs. Never let an
+  engineered session cross UTC midnight (the day split cuts it in two). The
+  atom guarantees all three; hand-rolled retiming must too.
+- **`composition-drift`** — the breakdown's SHARE of a segment moves over
+  time while totals stay flat (e.g. plan-mix shifts toward premium). Engineer
+  by flipping an existing property value on a date-gated cohort, never by
+  changing volumes — volume changes read as `temporal-inflection` instead.
+  Assert with a `timeBucket` breakdown comparing first-window vs last-window
+  share.
+
 ## Anti-flag-stamping rule (HARD WALL)
 
 Hooks MUST NOT add new properties to records. The schema (config) defines what
@@ -318,6 +375,71 @@ checks against and what consumers read to understand the dataset.
  *   Expected ratio: bin>=15 / bin<5 ≈ 3x (within ±15%)
 ```
 
+### EXPECTED METRICS SUMMARY table (MANDATORY)
+
+The doc block MUST end with an EXPECTED METRICS SUMMARY table — one row per
+verifiable read, with the DERIVATION of each expected number from the hook's
+knob constants (never a bare number someone has to trust). Follow the style
+in `dungeons/vertical/ecommerce/ecommerce.js`:
+
+```
+ * EXPECTED METRICS SUMMARY
+ * ============================================================================
+ *
+ * Hook | Metric                          | Derivation          | Expected | Measured (full)
+ * -----|---------------------------------|---------------------|----------|----------------
+ * H2   | avg watchTimeSec post/pre       | 1.52/0.48           | 3.17x    | 3.19x
+ * H6   | sweet/over avg cart item amount | SWEET_CART_BOOST    | 1.25x    | 1.233x
+ * H9   | dark/light checkouts per user   | 20/13 diluted       | ~1.48x   | 1.412x
+ * ============================================================================
+```
+
+Fill the Measured column from the verification run (a reduced-scale iteration
+number is fine if labeled). "Diluted" derivations must say WHAT dilutes
+(organic events, cohort mixing) — the Derivation column is the anchor
+`/verify-dungeon` uses when a read misses.
+
+## Stories export (MANDATORY — the machine contract)
+
+Every engineered pattern ships with one story in a `stories` named export —
+the machine-checkable form of the doc block. `scripts/verify-stories.mjs`
+evaluates them; `/verify-dungeon` runs it as step 1. Grammar:
+`lib/templates/story-spec.schema.json` and `DungeonStory` in `types.d.ts`.
+
+```js
+export const stories = [
+  {
+    id: "H1-power-buyers",
+    hook: "H1",
+    archetype: "frequency-sweet-spot",
+    narrative: "Users with 15+ browse days buy 3x as often as light browsers.",
+    mixpanelReport: { type: "Insights", event: "Purchase", breakdown: "per-user count of Browse" },
+    assertions: [{
+      breakdown: { type: "frequency", event: "Purchase", cohortEvent: "Browse", bins: [5, 15] },
+      select: { hi: { where: { bin: ">=15" } }, lo: { where: { bin: "<5" } } },
+      expect: { metric: "hi.avg / lo.avg", op: ">=", target: POWER_BUYER_MULT, floor: POWER_BUYER_MULT * 0.8 },
+      minCohort: 200,
+    }],
+  },
+];
+```
+
+Rules:
+
+- **Thresholds derive from the knob you just wrote.** Export the hook's knob
+  constants (`const POWER_BUYER_MULT = 3`) and compute `target` from them —
+  never paste the number twice. If the read is diluted (organic mixing),
+  derive the dilution too and say so in a comment.
+- `floor` must itself be derived (e.g. `target * 0.8`) — never hand-tuned to
+  a run. A missed assertion means fixing the hook or the derivation, never
+  relaxing the number to match output.
+- Set `minCohort` from the cohort math (share × numUsers × ~0.5 safety) so
+  reduced-scale runs cap at WEAK instead of passing on noise.
+- One story per pattern; story `hook` matches the doc-block numbering (`H3`).
+- The `assert` function escape hatch is discouraged — each use needs a
+  comment saying why the declarative `expect` grammar can't express it.
+- Stories are JS-dungeon-only (`dungeon-to-json` drops them).
+
 ## Hook Ordering Within `everything`
 
 The order of operations inside the everything hook matters when hooks interact:
@@ -466,22 +588,37 @@ cohort.
 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:
+3. **Calibrate thresholds against the real distribution.** Before choosing
+   any "N+ events" gate or cohort cutoff, generate a small run and query the
+   actual per-user distribution (see "Threshold Calibration" above for the
+   query). Set gates at ~the 80th percentile of what the data shows — a
+   threshold picked from intuition is the most common cause of empty cohorts.
+   ```bash
+   node scripts/verify-runner.mjs <dungeon> calib --small
+   ```
+4. 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:
+5. Write the `hook` function, importing atoms/patterns at the top of the
+   file. Finish the doc block with the EXPECTED METRICS SUMMARY table.
+6. Write the `stories` export — one story per pattern, `target`/`floor`
+   derived from the exported knob constants (see "Stories export" above).
+7. Smoke-test generation, then evaluate the stories:
    ```bash
    node scripts/verify-runner.mjs <dungeon> verify-dungeon --small
+   node scripts/verify-stories.mjs <dungeon> --data-prefix verify-dungeon
    ```
-   Confirm the run completes without errors.
-6. Hand off:
+   Reduced-scale runs legitimately cap at WEAK on `minCohort` guards; what
+   you're checking here is no NONE/INVERSE and no assertion errors.
+8. 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.
+   If verify-dungeon returns WEAK, NONE, or INVERSE on any pattern at full
+   fidelity, return to step 4 and refine — fix the hook or the derivation,
+   never relax a threshold to match output. Iterate until all patterns score
+   STRONG or NAILED.
 
 ## Stopping condition
 
@@ -492,5 +629,6 @@ 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.
+Add the documentation block (with EXPECTED METRICS SUMMARY) above the config.
+Add the `stories` export after the config. Do NOT modify any other file.
 Tell the user to run `/verify-dungeon <dungeon>` next.

package/CHANGELOG.md

@@ -2,6 +2,189 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.6.0 — 2026-07-04
+
+### Added
+
+- **Emulator: five new analysis types + retention completion**
+  (`emulateBreakdown`, all ARB-cited):
+  - `eventBreakdown` — Insights "Total" broken down by a property, with
+    Mixpanel's exact segment coercion (list fan-out, `$empty_list`,
+    `undefined` bucket, case-sensitive type-tagged segments, topN 250);
+    `countType: 'unique' | 'sessions'`, `firstTimeOnly` compose;
+    unrecognized `countType` values throw (same strict-option rule as
+    retention keys).
+  - `uniques` — per-interval independent dedup, rolling XAU windows,
+    cumulative running distinct; `countType: 'sessions'`, `firstTimeOnly`.
+  - `lifecycle` — Lifecycle Cohort Analysis board-template classification
+    (new / retained / resurrected / dormant) on a value-moment event, 7- or
+    30-day periods.
+  - `topPaths` — Flows: next-anchor-only matching, forward/reverse capacity
+    rings, per-level top-N pruning into `$mp_uncommon_flows_events`,
+    `hiddenEvents` / `visibleEvents`, `countType: 'general' | 'unique' |
+    'sessions'`.
+  - `distinctCount` — distinct values of a property + top-N value counts.
+  - `retention` completion — `compounded`, `birthCanRetain`,
+    `carryForward` / `carryBack` / `consecutiveForward`, `calendarStart`,
+    `cohortWindow`, `segmentOn: 'return'`, internal-event ignore list.
+- **Funnel evaluator upgrades**: session-count conversion windows,
+  `countMode: 'sessions'`, ARB-exact exclusion handling, any-order step
+  blocks, step-0-anchored trends under `timeBucket`.
+- **New verify primitives**: `sessionize()` (query-time sessions — 30-min
+  gap / 24h max / UTC-day triggers, synthetic `$session_start`/`$session_end`),
+  `filterFirstTimeEver()`, `evaluateFormula()` (ARB formula grammar),
+  `extractFlows` / `aggregateFlows`, breakdown-key coercion
+  (`lib/verify/coerce.js`), `frequencyHistogram`, null-aware avg/sum
+  `{ flatten: true }`, `attributedBy` per-conversion output.
+- **Hook atoms**: `hashCohort` (seed-stable cohort assignment),
+  `applyLifecycleWave`, `applyPathBias`, `applySessionShape`; pattern
+  `applyTTCBySegmentV2` (see Deprecated).
+- **Experiments: `sticky` knob** (`ExperimentConfig.sticky`, default
+  `true`). Sticky bucketing — the pre-1.6 per-user hash — is now explicit
+  and opt-out-able: `sticky: false` re-rolls the variant on every funnel
+  pass via the seeded RNG. Default preserves byte-identical output for
+  existing dungeons.
+- **Story layer**: `stories` named export on dungeons — one machine-checkable
+  story per hook (`DungeonStory` typedef,
+  `lib/templates/story-spec.schema.json`) — and the
+  `scripts/verify-stories.mjs` runner: mechanical five-tier verdicts
+  (NAILED / STRONG / WEAK / NONE / INVERSE), population floors (`minCohort`),
+  hook-coverage discipline, disk + in-memory modes, `--json`.
+- **Verticals**: `dungeons/vertical/` restructured to one folder per vertical
+  (`<name>/<name>.js` + `<name>.verify.mjs` + `<name>.sql`); `stories`
+  exports and rebuilt hooks across all verticals; two new showcase dungeons —
+  `streaming` (lifecycle) and `support-desk` (flows + sessions).
+- **Skills**: `/write-hooks` authors the stories export; `/verify-dungeon`
+  runs the story runner first and investigates only failures;
+  `/create-dungeon` designs analysis-friendly vocabularies (session
+  fan-out, value moment, hidden-event hygiene); `/analyze-soup` queries in
+  UTC; `/create-project` builds business context from the stories export.
+- **Docs**: HOOKS.md §2.12–2.17 (event breakdown coercion, uniques/XAU,
+  formulas, first-time-ever, lifecycle, flows, sessions), recipes 4.29–4.31,
+  atom/helper reference sections.
+
+### Behavior changes
+
+- **Retention option keys are strict** (P1.5). Unknown keys in a `retention`
+  emulator config now throw instead of being silently ignored — a typo'd
+  option previously ran with defaults and produced plausible-but-wrong
+  numbers. `carry_forward: true` is kept as a deprecated alias for
+  `unbounded: 'carryForward'`.
+- **Funnel exclusions no longer fire before step 0** (P1.6.4).
+  `evaluateFunnel`'s `exclusionSteps` previously defaulted `afterStep` to
+  −Infinity, so an exclusion event could condemn an attempt before the first
+  step was ever reached. ARB has no exclusion gaps before the first step: a
+  pre-step-0 exclusion event now only matters inside the 2-second grace rule
+  at step 0 (condemns with `excludedAtStep`), otherwise the attempt proceeds.
+- **Non-sequential funnel orders verify with full ARB semantics** (P1.6.6).
+  `first-fixed` / `last-fixed` / `first-and-last-fixed` / `outside-in` /
+  `random` previously verified via set-membership ("fired all step events,
+  any order", `verificationKind: 'partial'`); they now route through
+  any-order step blocks with full conversion-window / 2-second-rule /
+  exclusion / anchor-ordering semantics. Users that passed the loose check
+  but violate window or anchor ordering no longer convert. `middle-fixed`
+  keeps set-membership (its scrambled slots are non-contiguous).
+- **`sessionMetrics` defaults to query-time derived sessions** (P1.7.2). New
+  `source: 'derived' | 'stamped'` option, default `'derived'`: sessions are
+  re-derived from raw timestamps via `sessionize()` — what Mixpanel actually
+  computes — instead of reading the generator's pre-stamped `session_id`.
+  The stamped path remains via `source: 'stamped'`, and the per-row
+  `stampedDivergence` count audits the gap between the two.
+- **`$experiment_started` is pinned to funnel-pass start** (P4.2 engine fix,
+  pre-existing since 1.4.0). For experiment funnels with a non-`sequential`
+  `order` (`last-fixed`, `random`, `first-fixed`, ...), `applyOrderingStrategy`
+  shuffled the synthetic exposure event into the funnel body — the exposure
+  landed mid-pass at a uniform position, so exposure→conversion TTC read ~58%
+  of `timeToConvert`, and any exposure-anchored conversion measurement (the
+  Mixpanel Experiments report, ordered-funnel pairing from
+  `$experiment_started`) undercounted variant lift. The ordering strategy now
+  shuffles only the real steps; `$experiment_started` stays at execution index
+  0 (offset 0), and `first-fixed`/`first-and-last-fixed` pin the true first
+  step instead of the exposure marker. Output changes (event order + RNG
+  stream) for experiment funnels with shuffle orders; `sequential` experiment
+  funnels are unaffected.
+- **Session IDs are re-derived after the `everything` hook** (P2.1). The first
+  `assignSessionIds` pass still runs before hooks (hooks may read
+  `session_id`), but a second pass now relabels on the FINAL event set — after
+  the `everything` hook, auto-sort, and the future-time guard. Time-mutating
+  hooks (TTC scaling, injected bursts) previously left stale session ids that
+  disagreed with what Mixpanel derives from timestamps at query time. Session
+  ids hash from (user key + first event time of the session), so sessions
+  whose events did not move keep their exact ids. The per-session sticky-device
+  rewrite is NOT re-run — relabeling never mutates identity fields. Behavior
+  change only for dungeons whose hooks mutate event times; their stamped
+  `session_id` values now match query-time derivation
+  (`stampedDivergence === 0`).
+- **Churn is now a hard activity boundary** (P2.2). `isChurnEvent` broke the
+  budget loop (stopping generation), but already-generated events carry
+  independent timestamps — uniform TimeSoup draws on the legacy path, a
+  shuffled active-day plan under `avgActiveDaysPerUser`/`retentionCurve` — so
+  churned users kept events DATED after their churn event. Churned users'
+  events are now truncated at the churn event's timestamp (the churn event
+  itself survives). Affects only dungeons using `isChurnEvent`; users who
+  return (`returnLikelihood` roll succeeds) are untouched. `simplest.js` has
+  no churn events, so the engine-shape canary and sweep are unaffected.
+- **Bin-based patterns bin by distinct days by default** (P2.4).
+  `applyFrequencyByFrequency`, `applyFunnelFrequencyBreakdown`, and
+  `applyAggregateByBin` gain `binBy: 'events' | 'distinctDays'` (default
+  `'distinctDays'`, via `binByDistinctPeriods`). Mixpanel's frequency reports
+  — and the local emulator — bucket users by distinct calendar days, so the
+  old total-event-count axis could put a user in a different cohort than the
+  report bucket their data lands in, diluting engineered signal. Pass
+  `binBy: 'events'` to restore the pre-1.6 axis (also the right choice for
+  `applyFunnelFrequencyBreakdown`'s funnelEvents fallback, where one funnel
+  run rarely spans two days).
+- **`applyAttributedBySource` rewritten to overwrite engine-stamped touches**
+  (P2.4, HOOKS.md recipe 4.26 as code). New opts:
+  `{ weights, property = 'utm_source', model = 'firstTouch'|'lastTouch'|'both' }`;
+  returns `{ overwritten, touches }`. The old copy-source-to-conversion
+  mechanism stamped fresh values, which under the v1.5 touchpoint cap land
+  outside Mixpanel's lookback and never move the attribution report. The
+  pattern now overwrites the value on the touch the chosen model reads and
+  never adds the property to unstamped events.
+
+### Changed
+
+- **Shipped vertical dungeons: hook fixes that change generated output**
+  (P4.2 rebuild — same seeds, different data where noted):
+  - **media**: H10 applied the plan-tier factor to `watch_duration_min` in
+    two separate blocks — the engineered free/premium ratio compounded to
+    ~4.4x instead of the documented 2.09x. Single application now; the
+    duplicate block is deleted (no RNG-stream impact).
+  - **marketplace**: H9 funnel-post TTC scaling is restricted to the
+    Browse-to-Purchase funnel (it previously scaled all five; Buyer
+    Onboarding shares the search→view→cart prefix, so first-occurrence
+    funnel evaluation assembled chains across unscaled instances and the
+    engineered ratio never reached the report). H10 redesigned from a
+    windowed message-cohort purchase-drop to a total-message-count cohort
+    with property-only `offer_amount` effects.
+  - **sass**: H9 TTC scaling moved from one stitched whole-history
+    sequence (everything hook) to per-instance funnel-post gap scaling
+    gated on the `alert triggered` funnel — the old single scaled sequence
+    was diluted by the user's unscaled instances and never survived to the
+    funnel report.
+  - **crypto**: all hook day-boundary math converted from local-time dayjs
+    to UTC (dataset timestamps are UTC; boundaries previously shifted by
+    the host's UTC offset). H9 TTC scaling restricted to the onboarding
+    funnel (same cross-instance dilution class as marketplace). H6 churn
+    no longer erases a user's first 24 hours — the old absolute-day cutoff
+    shredded late-born users' signup/onboarding/auth events under the
+    growth macro.
+
+### Deprecated
+
+- **`applyTTCBySegment`** (P2.4) — the funnel-post variant scales one run's
+  internal gaps, but Mixpanel's TTC measures the FIRST occurrence of each
+  step per user, so the scaling only reaches the report for `isFirstFunnel`
+  runs. Still functional; warns once. Use **`applyTTCBySegmentV2`** (new,
+  `everything` hook) — finds the greedy first sequence via
+  `findFirstSequence` and scales it with `scaleFunnelTTC`.
+- **`Persona.churnRate`, `Persona.activeWindow`, `Persona.soupOverride`**
+  (P2.5) — declared config surface that was never implemented: nothing in
+  lib/ reads them after validation. Marked `@deprecated` in types.d.ts; the
+  validator warns once per process when a dungeon sets any of them. Not
+  removed (declared surface) and not implemented (config-shape freeze).
+
 ## 1.5.4 — 2026-06-04
 
 Patch. Import-phase progress now reaches `onProgress` consumers.