@ak--47/dungeon-master 1.6.5 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,195 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.7.0 — 2026-09-03
+
+The engine round for DM4 v5. Executes the 1.6.4 "Deferred to 1.7.0" table plus
+the five round-two items (`dm-engine-round-two.md`) and the three round-one items
+that table missed (P0-3, P1-5, P1-6). Every behavior change below carries the
+number that proved the gap and the number after the fix, both from real
+generation passes (400 users × 60 days unless stated; scripts in the session
+scratchpad, assertions pinned in `tests/integration/v170-engine-requests.test.js`).
+
+**Output compatibility.** Same seed, same config, `concurrency: 1`, pinned window:
+1.7.0 and 1.6.5 produce byte-identical **events** (modulo `insert_id`) on every
+technical fixture that does not set `hasLocation` — `simplest`, `datagen-v15-verify`,
+`experiments`, `group-analytics`, `mirror-strategies`, `ad-spend`, `anonymous-users`
+(the funnel-step time pin below still runs TimeSoup, so the RNG stream is
+unchanged). Profiles and groups are identical where the fixture is deterministic
+(`datagen-v15-verify`, `ad-spend`, `anonymous-users`); `simplest`, `experiments`,
+`group-analytics` and `scd` build some profile/group props from their own unseeded
+`new Chance()` and were never run-to-run stable. Three changes alter output on
+purpose, each gated on a feature you would know you are using — see **Behavior
+changes** (B1–B3). The 10-test engine-shape canary passes; `smoke-test-all` runs
+22/22 shipped dungeons clean. The full 194-combo strict-bar sweep
+(`RUN_FULL_SWEEP=1`, 2026-09-04, window pinned to Wednesday 2026-09-02) passes
+191/194. The 3 failures are one config three times — `growth/365d/r1.2` with
+born `-`/`30`/`100`, which the growth cap resolves to the same 30 — failing the
+last-day bar at ratio 0.66 vs 0.70. Running the same `long` tier on 1.6.5 (`main`)
+produces the identical 3 failures with identical numbers, so this is a
+pre-existing, calendar-window-dependent marginal dip on one 365-day config, not a
+1.7.0 regression. Tracked as a follow-up; not a release blocker.
+
+**For DM4: tripwires that now flip.** `tests/integration/v5-engine.test.js` pins
+several of the old behaviors; when these assertions fail on 1.7.0 that is the fix
+landing, and the workaround it guards can go:
+- the spike hook for The Moment (`volumeMultiplier` amplifies — P0-3)
+- the flat-only born-share restriction (`macro: { bornRecentBias, percentUsersBornInDataset }` with no `preset` is uncapped — R2-1)
+- the 19-country `SINGLE_COUNTRY_NAMES` enum in `tests/v5-render.test.js` (`singleCountry: 'US'` works; a miss throws — R2-2)
+- the `importResults.users.success` overwrite (the receipt reconciles — R2-5)
+- the repeated-value weighting idiom (`{ __weights }` — P2-1)
+- the "fewer than two non-funnel events" refusal on Persona Difference — its premise was wrong; see P1-5 below
+
+### Tier 1 — silent lies fixed
+
+- **R2-1 `MacroConfig` object overrides.** Measured before: `macro: { preset: 'flat',
+  percentUsersBornInDataset: 50 }` → 10.3% born; `macro: { percentUsersBornInDataset: 50 }`
+  (no preset) → 10.0%; only the top-level key with no `macro` at all gave 52.3%.
+  Cause: the born% cap keyed the preset-less object to `flat` (12) and the warning was
+  `verbose`-gated. Now: a NAMED preset (string or `{ preset }`) is a shape contract and
+  still clamps — 12.3% after, with the clamp in `result.warnings`
+  (`{ key: 'percentUsersBornInDataset', requested: 50, applied: 12 }`); an object
+  WITHOUT `preset` is a custom macro and is honored as written — 55.0% after for
+  `{ percentUsersBornInDataset: 50 }`, 48.8% for `{ bornRecentBias: 0.3, percentUsersBornInDataset: 50 }`.
+  Canonical spelling: `macro: { preset, ...overrides }`; the top-level keys are a legacy
+  alias that wins over the object. Documented in README, `MacroConfig` JSDoc, CLAUDE.md.
+- **R2-2 `singleCountry`.** Accepts the ISO code or the full name, case-insensitive
+  (`resolveSingleCountry`, also hoisted from `switches`). A value matching no country
+  THROWS with the list of valid values. Measured before: `'US'` and `'Narnia'` both
+  silently deleted every geo property from events and profiles; after: `'US'` → 100%
+  `country_code: US` on events and profiles.
+- **R2-3 `strictEventCount` is exact.** Before: stopped on the GENERATED count (drops
+  included) and never topped up — 4,987 of 5,000 with ~4x headroom (DM4 measured 4,705
+  on its config). Now: the bailout reads the STORED count; a per-user budget controller
+  scales the remaining users' budgets by (events still needed ÷ expected remaining
+  delivery at the realized yield), clamped to [0.25, 4], aiming slightly high; the
+  final user's stream is trimmed with a seeded uniform sample so the count never
+  exceeds the target. Measured: 5,000 of 5,000; 30,000 of 30,000; test pins 3,000 of
+  3,000. When capacity cannot reach the target (e.g. a churn event ends every user
+  early) the run stops short and `result.warnings` carries
+  `{ key: 'numEvents', requested, applied }`. User creation still stops once the target
+  is met (legacy). Only under the flag — the default path is untouched.
+- **R2-5 profile receipt.** `importResults.users` now carries `generated` (profiles the
+  engine pushed to storage, bots included) and `dropped_anonymous` (`_drop`-flagged
+  anonymous non-converters never sent to `/engage`) alongside mixpanel-import's
+  `success` / `failed`, so `generated - dropped_anonymous - failed === success` is
+  checkable. Counters tick at push time, so they hold in batch mode. The sender logs
+  a line when the receipt does not reconcile. DM4's "100 generated, 45 reported" is
+  now decidable from the result object.
+
+### Tier 2 — the deferred 1.7.0 feature set
+
+- **P0-1 `funnels[].conditions`: operators, validation, docs, tests.** Operator maps
+  `eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte` (AND within a key, AND across keys;
+  no `or`); the scalar shorthand is unchanged. Matching moved to
+  `lib/utils/conditions.js` (re-exported from user-loop). The validator THROWS on
+  shapes that silently never matched — function values, bare arrays (points at
+  `{ in: [...] }`), unknown operators, `in`/`nin` without an array — and warns into
+  `result.warnings` when a condition key is declared nowhere the profile is built from.
+  Users who satisfy none of the author's funnels (the engine catch-all excluded) are
+  counted and reported once per run (`key: 'funnels.conditions'`). Measured: iOS 80.2%
+  vs Android 39.8% purchased-per-viewed on the duplicate-funnel idiom; `{ gte: 10 }` 89.7%
+  vs `{ lt: 10 }` 20.0%. README "segmented funnels", typed `FunnelConditions`, 30 unit
+  cases + integration coverage of the filter branch that had none.
+- **P0-2 experiment variant on the profile.** Every exposed user carries
+  `"Experiment: <name>": "<variant>"`, stamped lazily at first exposure (so
+  `startDaysBeforeEnd` is respected and never-exposed users carry nothing), before the
+  `everything` hook. `experiment.stampProfile` (default `true`) opts out; `sticky: false`
+  implies off. Not stamped on step events (would be undeclared columns). Measured: 0
+  mismatches against `Variant name` on 13,005 exposure events.
+- **P1-1 `(ctx) => value`.** `choose(value, ctx)` passes
+  `{ profile?, event?, time?, config }` to every property function. Zero-arity functions
+  are untouched; a function that declares a parameter is context-aware and skips the
+  source-string cache (which would otherwise freeze its first result). Bound natives
+  (`chance.animal.bind(chance)`) are still called with no argument. Funnel steps after
+  the first now know their final time before properties resolve (`fixedTimeMs`, fed by
+  a synchronous side channel from step 0) — TimeSoup still runs so the RNG stream is
+  unchanged; context-aware step properties defer from `buildFunnelEvents` into
+  `makeEvent`. `json-evaluator` emits `(ctx) => body` for expression bodies and passes
+  whole-function bodies through unwrapped. Measured: 203 of 203 `pro` users got
+  `revenue: 100` from `(ctx) => ctx.profile.plan === 'pro' ? 100 : 0`; 0 events without
+  profile context.
+- **P1-2 `stickyEventProps` + stable location (B2).** `stickyEventProps: ['plan_tier']`
+  copies the profile value onto every event after `superProps`, before the `event`
+  hook; keys declared only in `superProps` resolve once per user. Schema-first: undeclared
+  keys throw; `lib/verify/schema-validator.js` treats sticky keys as legal on every event.
+  Measured: 67,355 of 67,355 events matched the profile. **B2:** with `hasLocation: true`
+  a user's events now share the user's location — `featureCtx.userLocation` was computed
+  and never read; measured 0.8% of events matched their profile city before, 100% after.
+- **P1-3 `personas[].ttcModifier`.** Multiplies `timeToConvert` after the experiment
+  `ttcMultiplier`, before `funnel-pre`. Measured median TTC 0.50h vs 1.96h for 0.25 vs 1.
+  **B3:** `churnRate`, `activeWindow`, `soupOverride` removed from the `Persona` type
+  (never implemented); the validator still accepts and warns on them, and no longer
+  defaults `churnRate`.
+- **P1-4 `campaignPerUser`.** One campaign template per user at birth; UTMs stamped on
+  the profile and reused on every touchpoint. Profile UTM keys already present (persona
+  `properties`, `user` hook) win over the draw, so a persona can own a channel. Measured:
+  0 of 399 users with more than one `utm_source` (400 of 400 before). Ad spend derived
+  from acquisitions is deferred to 1.8.0.
+- **P2-1 `{ __weights }` + `autoPowerLaw`.** `{ __weights: { free: 60, pro: 30,
+  enterprise: 10 } }` draws exactly those shares (measured 239/123/38 over 400 users);
+  `autoPowerLaw: false` turns the implicit 45/25/15 draw off for the run (module flag set
+  per run, reset with the value caches). Both round-trip through `dungeon-to-json`.
+- **P2-2 `result.warnings[]`.** Always present. Validator clamps (`percentUsersBornInDataset`,
+  `bornRecentBias`, compound bias, `avgEventsPerUserPerDay`, `avgActiveDaysPerUser`,
+  `numDays < 14`, `engagementDecay` + active days, auto-set `conversionWindowDays`) plus
+  runtime aggregates via `context.addWarning` (one entry per key with `count`). Console
+  output stays `verbose`-gated. `EngineWarning` type.
+- **P2-4 `conversionRate` saturation.** Every engine clamp of a modified rate above 100
+  — experiment variant, persona, world event, or whatever a `funnel-pre` hook left behind
+  — is reported once per funnel and source
+  (`funnels[Buy].conversionRate:persona "whale" conversionModifier`, requested 195,
+  applied 100). The engine cannot see a hook's own `Math.min(95, rate * 3)`; HOOKS.md
+  says so.
+
+### Tier 3 — open items outside the deferred table
+
+- **P0-3 `worldEvents[].volumeMultiplier > 1` amplifies.** New per-user pass
+  `amplifyWorldEvents` clones affected in-window events — `floor(m − 1)` copies plus one
+  with probability `frac(m)` — each with a fresh `insert_id` and a timestamp spread
+  uniformly across the window (never past the dataset end), after the churn cut and
+  before decay and hooks. Measured 3x on a 4-day window: **1.08x before, 3.06x after**,
+  all `insert_id`s unique, clones on every window day; 1.5x lands in [1.3, 1.7].
+  `aftermath.volumeMultiplier` follows the same rule. Validation rejects negative or
+  non-finite multipliers.
+- **P1-5 `eventMultiplier` and funnels — the premise was wrong.** The multiplier scales
+  the whole per-user budget, which drives funnel passes too: measured **3.19x / 2.96x**
+  for an asked 3x with every event a funnel step. DM4's 0.96x came from its fixture's
+  `isChurnEvent` (`Churned`, weight 1, `returnLikelihood: 0.15`): a churn event in the
+  standalone pool ends every user after roughly the same number of events regardless of
+  budget — measured **1.04x with the churn event, 2.90x without**, same config. The
+  engine now reports it (`key: 'personas.eventMultiplier'`) when more than half the
+  users churn while a persona multiplier is in play; `eventMultiplier` and `isChurnEvent`
+  docs state the cap. DM4 should replace its "fewer than two non-funnel events" check
+  with a churn-event check.
+- **P1-6 day-1 retention floor — documented (option 2).** `retentionCurve` picks session
+  days; retention counts events; birth-day funnels spill into day 1 regardless of the
+  day plan, so day 1 sits near 0.85 (DM4 measured 0.885 for an asked 0.15; days 7 and 30
+  follow the curve). Stated in the `retentionCurve` JSDoc, README config table, and
+  HOOKS.md §2.7. Verify from day 7 on.
+
+### Behavior changes (not purely additive)
+
+- **B1** — `conditions` values that are functions or bare arrays now THROW at validation.
+  Any dungeon relying on them was already producing an empty funnel.
+- **B2** — `hasLocation: true` now yields one stable location per user on events instead
+  of a fresh random city per event. Event geo distributions change; `scd.js` (the one
+  technical fixture with `hasLocation`) is the reference.
+- **B3** — `churnRate`, `activeWindow`, `soupOverride` are gone from the `Persona` type.
+  Runtime still accepts them with the existing once-per-process warning.
+- World-event windows on funnel steps after the first now test the step's FINAL time
+  (previously the pre-offset TimeSoup time). Only dungeons combining `worldEvents` with
+  multi-step funnels see different `_drop` / `injectProps` decisions; the fix is what the
+  docs always described.
+
+### Not built (by request)
+
+Session replay, per-funnel `soup`, `or` conditions, anything in `stories` / `verify` /
+`emulateBreakdown`, and ad spend derived from acquisitions (P1-4 item 3, 1.8.0). R2-4
+(the verticals as DM4 templates) is deferred to its own sprint per AK: each vertical
+should demonstrate a different declarative trend type so the template gallery doubles
+as a catalog demo; the R2-4 audit stands as that sprint's punch list.
+
 ## 1.6.5 — 2026-09-02
 
 ### Changed

package/HOOKS.md

@@ -38,6 +38,31 @@ double-fire mutations.
 - `everything`: return the (possibly modified) array. Filtered array removes events.
 - All other types: mutate `record` in-place. Return value is ignored.
 
+**What 1.7.0 changed for hooks.** No hook signature, `meta` field, or firing
+order changed, and the hook-helper atoms and patterns are untouched. What a hook
+SEES did change in five places:
+
+1. `event` hook on funnel steps after the first: `record.time` is now the step's
+   FINAL time. Before 1.7.0 it was the pre-offset TimeSoup time, overwritten after
+   the hook returned — a hook that derived a property from `record.time` on step 2+
+   was reading the wrong timestamp.
+2. `everything` hook: the array already contains world-event clones
+   (`volumeMultiplier > 1`), `stickyEventProps` values on every event, and one
+   stable location per user under `hasLocation`. `meta.profile` carries
+   `"Experiment: <name>"` for exposed users (stamped before `everything`, after `user`).
+3. `funnel-pre`: `record.timeToConvert` already includes the persona `ttcModifier`
+   (like `conversionModifier` today). The hook stays the final authority. A rate the
+   hook leaves above 100 is clamped downstream exactly as before and now shows up in
+   `result.warnings`.
+4. `user` hook: under `campaignPerUser` the profile already carries the drawn
+   `utm_*` keys; a hook that overwrites them wins, and the touchpoint pass reads the
+   final values. `stickyEventProps` values are read from the profile AFTER the hook.
+5. Hooks may not add properties (rule 1) — `stickyEventProps`, the experiment
+   profile key, and world-event clones are engine-stamped and declared, so the
+   schema validator accepts them. Prefer these declarative knobs over a hook when
+   they express the story (README "segmented funnels", "sticky event properties",
+   "campaigns per user").
+
 ---
 
 ## 2. How Mixpanel Counts Things
@@ -399,6 +424,17 @@ All items on the v1.5.0 "documented gaps" list closed in 1.6.0. Unrecognized
 retention option keys now THROW — kills the silent-ignore class of bug where a
 typo'd `compounded: true` was dropped without effect.
 
+**`retentionCurve` cannot move day 1 (v1.7.0 doc).** `buildActiveDayPlan`
+picks which UTC days a user gets a SESSION; retention counts EVENTS. A funnel
+opened on the birth day spills its later steps across the following
+`timeToConvert` hours regardless of the day plan, so day 1 sits on a floor
+near 0.85 for funnel-driven dungeons no matter what `day1` asks for. Measured
+(2,000 users, 60 days): `{ day1: 0.15, day7: 0.06, day30: 0.02 }` delivered
+day 1 = 0.885, day 7 = 0.151, day 30 = 0.060 — the curve governs from day 7
+on and over-delivers by a consistent ~2.5x there. Verify retention stories from
+day 7 onward. To lower day 1, shorten `timeToConvert` on the funnels users
+enter on birth, or drop next-day spill in an `everything` hook.
+
 ### 2.8 Funnel reentry: state machine resets after completion
 
 Reference: `history.cpp` (`last_step_starts_next_funnel`). With reentry
@@ -813,6 +849,19 @@ if (type === "funnel-pre") {
 Greedy funnel engine (Section 2.2) applies after — keep `conversionRate`
 adjustments modest (1.2x is comfortable; 3x can saturate at the 95% cap).
 
+**Saturation is reported, but only the engine's own clamp (v1.7.0, P2-4).** When a
+persona `conversionModifier`, an experiment variant, a world event, or the value a
+`funnel-pre` hook leaves behind pushes `conversionRate` above 100, the engine
+clamps to 100 and adds one aggregated entry per funnel and source to
+`result.warnings` (`funnels[Checkout].conversionRate:persona "whale"
+conversionModifier`, `requested: 195`, `applied: 100`). It cannot see a hook's own
+cap: `record.conversionRate = Math.min(95, rate * 3)` on a base of 65 yields 95 — a
+1.46x lift, not 3x — and the engine never learns the intended 195. To get a true
+multiple, read the base rate and solve for it, or lower the base rate so the multiple
+fits under the cap. For "one segment converts differently on one funnel" prefer the
+declarative `funnels[].conditions` (README "segmented funnels") over a `funnel-pre`
+hook — it needs no cap arithmetic.
+
 ---
 
 #### 4.2 Feature Launch Inflection

package/README.md

@@ -155,7 +155,33 @@ import { createTextGenerator, generateBatch } from '@ak--47/dungeon-master/text'
 
 these are the same functions used internally. `pickAWinner` creates weighted distributions, `weighNumRange` generates realistic numeric ranges with configurable skew, and the text generators produce organic-looking strings with sentiment analysis and keyword injection.
 
-**you usually don't need `pickAWinner`** — as of 1.6.1, any property value that is a plain array of 3–19 unique strings automatically gets a stable power-law distribution: one seed-deterministic winner per array per run (~45% winner / ~25% second / ~15% third / decaying tail). to opt out and get uniform draws, use exactly 2 values, 20+, or include one of the keywords `variant` / `group` / `experiment` / `population` in a value (experiment arms stay balanced). arrays with explicit duplicate entries (`["card", "card", "apple_pay"]`) skip the auto-weighting and honor the duplicates exactly.
+**you usually don't need `pickAWinner`** — as of 1.6.1, any property value that is a plain array of 3–19 unique strings automatically gets a stable power-law distribution: one seed-deterministic winner per array per run (~45% winner / ~25% second / ~15% third / decaying tail). to opt out and get uniform draws, use exactly 2 values, 20+, or include one of the keywords `variant` / `group` / `experiment` / `population` in a value (experiment arms stay balanced). arrays with explicit duplicate entries (`["card", "card", "apple_pay"]`) skip the auto-weighting and honor the duplicates exactly — **repeats are the weights** (that array is 2:1).
+
+**state the distribution instead (1.7.0):** `{ __weights: { free: 60, pro: 30, enterprise: 10 } }` draws exactly those shares — no power law, no per-run winner, zero-weight keys never draw. `autoPowerLaw: false` at the top level turns the automatic power law off for the whole run (uniform picks).
+
+```javascript
+userProps: {
+  plan_tier: { __weights: { free: 60, pro: 30, enterprise: 10 } },   // honest 60/30/10
+  platform:  ['iOS', 'Android', 'web'],                              // 45/25/15 power law (default)
+}
+```
+
+**value functions see context (1.7.0):** a property function may declare a `ctx` parameter and read `ctx.profile` (the user's resolved profile), `ctx.event` (the event being built), `ctx.time` (unix ms) and `ctx.config`. this is how one field correlates with another without a hook. zero-arity functions keep working untouched.
+
+```javascript
+userProps: {
+  plan:    ['free', 'pro'],
+  revenue: (ctx) => ctx.profile.plan === 'pro' ? 100 : 10,      // profile keys resolve in declaration order
+},
+events: [{ event: 'Purchased', properties: {
+  price:    () => integer(5, 500),
+  quantity: [1, 1, 1, 2, 3],
+  total:    (ctx) => ctx.event.price * ctx.event.quantity,       // event props resolve in declaration order
+}}],
+superProps: { plan_on_event: (ctx) => ctx.profile.plan },         // or: stickyEventProps: ['plan']
+```
+
+`ctx.profile` is undefined for group profiles, lookup tables, ad spend and mirror props. on funnel steps the step's final time is known before its properties resolve, so `ctx.time` is the real timestamp.
 
 ### named exports
 
@@ -406,10 +432,14 @@ mix and match. most dungeons want `macro: "flat"` (the chart doesn't blow up at
 ```javascript
 macro: 'flat'                                          // default
 macro: 'growth'                                        // preset string
-macro: { preset: 'growth', percentUsersBornInDataset: 40 }  // preset + override
-macro: { bornRecentBias: 0, percentUsersBornInDataset: 15, preExistingSpread: 'uniform' }  // fully custom
+macro: { preset: 'growth', percentUsersBornInDataset: 40 }  // preset + override (canonical object spelling)
+macro: { bornRecentBias: 0.3, percentUsersBornInDataset: 50 }  // custom macro — no preset, no cap
 ```
 
+**canonical spelling is the object with `preset`.** the top-level `bornRecentBias` / `percentUsersBornInDataset` / `preExistingSpread` keys are a legacy alias and win over the object when both are set.
+
+**a named preset is a shape contract.** its born% cap applies (flat 12, steady 12, growth 30, viral 55, decline 5) whether you spell it `macro: 'growth', percentUsersBornInDataset: 50` or `macro: { preset: 'growth', percentUsersBornInDataset: 50 }` — both clamp to 30 and report it in `result.warnings`. **an object without `preset` is a custom macro**: you own the shape, no cap applies, your numbers are used as written (missing fields fill from `flat`). before 1.7.0 the preset-less object was silently capped at 12.
+
 ## timesoup (intra-week / intra-day rhythm)
 
 timesoup controls the texture of events inside the macro trend. it uses gaussian cluster sampling layered with day-of-week and hour-of-day weighting derived from... i won't tell you. a prize goes to whoever can guess. the result is realistic temporal patterns: weekday peaks, weekend valleys, morning surges, afternoon dips.
@@ -537,6 +567,24 @@ funnels: [
 
 ordering strategies: `sequential`, `random`, `first-fixed`, `last-fixed`, `first-and-last-fixed`, `middle-fixed`, `interrupted`
 
+### segmented funnels (`conditions`)
+
+`conditions` is the only mechanism that makes **one segment convert differently on one funnel** — `personas[].conversionModifier` applies to every funnel. a funnel with `conditions` is offered only to users whose profile satisfies every key (AND across keys). the idiom is two funnels with the same `name` and `sequence`, different `conditions` and rates:
+
+```javascript
+userProps: { platform: ['iOS', 'Android'], seats: [1, 5, 10, 20] },
+funnels: [
+  { name: 'Checkout', sequence: ['Viewed Item', 'Purchased'], conditions: { platform: 'iOS' },     conversionRate: 80, timeToConvert: 0.5 },
+  { name: 'Checkout', sequence: ['Viewed Item', 'Purchased'], conditions: { platform: 'Android' }, conversionRate: 40, timeToConvert: 4 },
+  { name: 'Upgrade',  sequence: ['Viewed Plans', 'Upgraded'],
+    conditions: { seats: { gte: 10 }, plan_tier: { in: ['pro', 'enterprise'] }, country: { neq: 'US' } } },
+]
+```
+
+each value is a scalar (strict equality) or an operator map with any of `eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte` (1.7.0). operators within one key AND together; there is no `or`. measured: iOS 80.2% vs Android 39.8% purchased-per-viewed on the config above.
+
+the validator throws on shapes that can never match (a function, a bare array — use `{ in: [...] }`, an unknown operator, `in`/`nin` without an array). a condition key that is not declared in `userProps`, `superProps`, or a persona's `properties` lands in `result.warnings` — only a `user` hook could supply it. users who satisfy none of your funnels fall through to standalone events; the run reports how many under `result.warnings` (`key: 'funnels.conditions'`).
+
 ### experiments
 
 experiments are a property of funnels. any funnel with `experiment` set fires a `$experiment_started` event (with `Experiment name` / `Variant name` properties) at the start of every qualifying pass, and the assigned variant's `conversionMultiplier` / `ttcMultiplier` modify that pass:
@@ -556,6 +604,8 @@ experiment: {
 
 variant assignment is **sticky by default**: a deterministic hash of `user_id` + experiment name, so a user keeps their variant across every funnel pass (matches Mixpanel experiment SDK bucketing and makes variant lift verifiable). set `sticky: false` to re-roll the variant on each pass with the seeded RNG. hooks see the resolved variant on `meta.experiment` in `funnel-pre` / `funnel-post`.
 
+**the variant lands on the user profile (1.7.0).** every exposed user carries `"Experiment: <name>": "<variant>"` (e.g. `"Experiment: Checkout Redesign": "New Checkout"`), so the funnel breaks down by variant in Mixpanel with a user-property breakdown — no cohort built from the exposure event. stamped when the user is first exposed (respects `startDaysBeforeEnd`); never-exposed users carry nothing; the `user` hook fires before exposure and does not see it, the `everything` hook does. `stampProfile: false` turns it off; `sticky: false` implies off. measured: 0 mismatches between the profile value and the `Variant name` on 13,005 exposure events.
+
 ## user generation
 
 users are generated with configurable birth distributions, normally controlled via the `macro` preset (see "time shape" above). these three knobs can also be set directly on the dungeon config — they override the preset's values.
@@ -573,6 +623,48 @@ users are generated with configurable birth distributions, normally controlled v
 }
 ```
 
+### personas
+
+`personas` split users into behavioral segments. each persona carries a `weight` (share of users), `properties` merged into the profile, and three multipliers:
+
+| field | applies to | default |
+|---|---|---|
+| `eventMultiplier` | the whole per-user event budget — funnel passes AND standalone events. a 3x persona runs ~3x the funnel passes (measured 2.9–3.2x) | 1.0 |
+| `conversionModifier` | `conversionRate` on every funnel (for one segment on one funnel use `conditions`) | 1.0 |
+| `ttcModifier` | `timeToConvert` on every funnel (0.25 = converts four times faster; measured median 0.50h vs 1.96h) — 1.7.0 | 1.0 |
+
+**`isChurnEvent` caps `eventMultiplier`.** a churn event in the standalone pool is drawn by weight like any other event, so it ends every user after roughly the same number of events regardless of budget — the multiplier washes out (measured 1.04x for an asked 3x with a weight-1 churn event among 16 weight units; 2.90x without it). when more than half the users churn and a persona multiplier is in play, `result.warnings` says so (`key: 'personas.eventMultiplier'`). lower the churn event's weight, raise `returnLikelihood`, or drive churn from a hook.
+
+1.7.0 removed the never-implemented `churnRate`, `activeWindow` and `soupOverride` from the `Persona` type. the validator still accepts and warns on them. `engagementDecay` per persona IS implemented and stays.
+
+### sticky event properties
+
+`superProps` re-roll on every event. to put a **stable per-user value on events** — the property behind the most common mixpanel breakdown — name profile keys in `stickyEventProps` (1.7.0):
+
+```javascript
+userProps:  { plan_tier: ['free', 'pro', 'enterprise'], platform: ['iOS', 'Android'] },
+superProps: { app_version: ['1.0', '1.1', '2.0'] },
+switches:   { stickyEventProps: ['plan_tier', 'platform', 'app_version'] },   // or top-level
+```
+
+each key must be declared in `userProps`, a persona's `properties`, or `superProps` (schema-first; undeclared keys throw). profile keys copy the profile's value (after the `user` hook). keys declared only in `superProps` resolve once per user and hold constant. sticky values land after `superProps` and before the `event` hook. measured: 67,355 of 67,355 events matched their profile. `(ctx) => ctx.profile.plan_tier` on a super prop does the same thing one field at a time.
+
+with `hasLocation: true`, a user's events now share the user's city / region / country (1.7.0). before, every event drew a fresh random city — 0.8% of events matched their own profile.
+
+### campaigns per user
+
+`hasCampaigns: true` stamps UTMs on up to `maxTouchpointsPerUser` events per user, and before 1.7.0 every touchpoint drew a fresh random campaign — attribution data was uncorrelated noise. `campaignPerUser: true` (1.7.0) draws **one acquisition campaign per user** at birth, stamps its `utm_source` / `utm_campaign` / `utm_medium` / `utm_content` / `utm_term` on the profile, and every touchpoint carries those same values. any UTM key already on the profile wins over the draw, so a persona can own a channel:
+
+```javascript
+switches: { hasCampaigns: true, campaignPerUser: true },
+personas: [
+  { name: 'paid search', weight: 30, conversionModifier: 2.0, properties: { utm_source: 'google', utm_medium: 'cpc' } },
+  { name: 'everyone else', weight: 70 },
+]
+```
+
+"paid search converts 2x better than organic" is now declarative. measured: 0 of 399 users with more than one `utm_source`; 400 of 400 profiles carry it. ad spend is still independent of acquisitions (deferred to 1.8.0).
+
 ## seeded generation
 
 all randomness is seeded. same seed + same config + concurrency=1 = identical output every time:
@@ -705,7 +797,7 @@ three groups of keys accept both a nested sub-object and a flat top-level form:
 | sub-object | keys it groups |
 |---|---|
 | `credentials` | `token`, `region`, `serviceAccount`, `serviceSecret`, `projectId` |
-| `switches` | `hasLocation`, `hasCampaigns`, `hasAdSpend`, `hasSessionIds`, `hasAvatar`, `hasIOSDevices`, `hasAndroidDevices`, `hasDesktopDevices`, `hasBrowser`, `isAnonymous`, `alsoInferFunnels` |
+| `switches` | `hasLocation`, `hasCampaigns`, `hasAdSpend`, `hasSessionIds`, `hasAvatar`, `hasIOSDevices`, `hasAndroidDevices`, `hasDesktopDevices`, `hasBrowser`, `isAnonymous`, `alsoInferFunnels`, `singleCountry`, `campaignPerUser`, `stickyEventProps` |
 | `identity` | `avgDevicePerUser`, `sessionTimeout` |
 
 **the sub-object form is canonical.** the flat top-level keys are a back-compat
@@ -727,6 +819,31 @@ you will not see unless `verbose: true`.
 `hasAttributionFlags` is **not** a switch. the validator derives it from
 `events[].isAttributionEvent`; setting it has no effect.
 
+### `result.warnings` — what the engine changed
+
+every value the engine clamped or flagged comes back on the result, regardless of
+`verbose` (1.7.0). a config UI that shows the requested value can now show the
+applied one instead of lying:
+
+```javascript
+const { warnings } = await DUNGEON_MASTER({ macro: 'growth', percentUsersBornInDataset: 80, ... });
+// [{ key: 'percentUsersBornInDataset', requested: 80, applied: 30, severity: 'clamp',
+//    reason: 'macro preset "growth" caps percentUsersBornInDataset at 30 to keep its shape; ...' }]
+```
+
+validator clamps come first (`percentUsersBornInDataset`, `bornRecentBias`,
+`avgEventsPerUserPerDay`, `avgActiveDaysPerUser`, the `numDays < 14` and
+`engagementDecay` warnings, auto-set `conversionWindowDays`), then run-level
+aggregates with a `count`: `conversionRate` saturation per funnel and source
+(`funnels[Checkout].conversionRate:persona "whale" conversionModifier`, requested 195,
+applied 100), users matching no conditioned funnel (`funnels.conditions`), churn
+washing out a persona multiplier (`personas.eventMultiplier`), and a
+`strictEventCount` shortfall (`numEvents`). always an array, empty when nothing was
+touched. console output stays `verbose`-gated.
+
+the engine can only report its own clamps. a hook's own `Math.min(95, rate * 3)` never
+reaches it — that cap belongs to the hook. see HOOKS.md.
+
 ### group keys
 
 `groupKeys` accepts a positional tuple or a named object. both normalize to the
@@ -762,16 +879,20 @@ see [types.d.ts](types.d.ts) for the complete `Dungeon` interface. here are the
 | `writeToDisk` | boolean/string | false | write files to ./data/ or a gs:// path |
 | `gzip` | boolean | false | compress output files |
 | `verbose` | boolean | false | print progress |
-| `strictEventCount` | boolean | false | stop at exact numEvents |
+| `strictEventCount` | boolean | false | deliver exactly `numEvents` (forces `concurrency: 1`). 1.7.0: exact when capacity allows; a shortfall lands in `result.warnings` (`key: 'numEvents'`) |
+| `autoPowerLaw` | boolean | true | `false` turns off the automatic 45/25/15 draw on 3–19-item string arrays (uniform picks). prefer `{ __weights }` |
+| `stickyEventProps` | string[] | `[]` | profile keys copied onto every event of the user (schema-first: must be declared) |
+| `campaignPerUser` | boolean | false | one campaign per user; UTMs on the profile and on every touchpoint. needs `hasCampaigns` |
+| `singleCountry` | string | undefined | pin `hasLocation` geo to one country by ISO code or name (`'US'`, `'United States'`). a value that matches nothing throws |
 | `batchSize` | number | 2500000 | records before auto-flush |
 | `concurrency` | number | 1 | parallel user generation |
-| `macro` | string/object | `'flat'` | big-picture trend preset (flat/steady/growth/viral/decline) |
+| `macro` | string/object | `'flat'` | big-picture trend preset (flat/steady/growth/viral/decline). canonical object spelling `{ preset, ...overrides }`; an object without `preset` is a custom, uncapped macro |
 | `soup` | string/object | `'growth'` | intra-week / intra-day rhythm preset |
 | `bornRecentBias` | number | 0 (from macro `flat`) | user birth date skew (safe range [-0.5, 0.5]; user-explicit values outside the band are clamped) |
-| `percentUsersBornInDataset` | number | 12 (from macro `flat`) | % of users born in window (clamped per-macro when both `macro` and this field are explicit) |
+| `percentUsersBornInDataset` | number | 12 (from macro `flat`) | % of users born in window (clamped to the named preset's cap; every clamp lands in `result.warnings`) |
 | `preExistingSpread` | string | `'uniform'` (from macro `flat`) | placement of pre-existing users' first event |
 | `avgActiveDaysPerUser` | number | undefined | concentrate events onto N distinct UTC days per user (preserves total event count). ignored when `retentionCurve` is set; warns when combined with `engagementDecay` |
-| `retentionCurve` | object | undefined | per-day return probabilities. **wins over `avgActiveDaysPerUser`** when both are set |
+| `retentionCurve` | object | undefined | per-day return probabilities. **wins over `avgActiveDaysPerUser`** when both are set. **day 1 has a floor near 0.85 the curve cannot move** — funnel steps spill into the next day regardless of the day plan (measured 0.885 for an asked 0.15; days 7 and 30 follow the curve). verify from day 7 on |
 | `maxTouchpointsPerUser` | number | 10 | UTM stamping cap per user (Mixpanel `TOUCHPOINTS_LIMIT` parity) |
 | `autoSortAfterEverything` | boolean | true | sort events by time after `everything` hook (defends greedy funnel engine) |
 | `hook` | function/string | passthrough | data transformation function |

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

@@ -0,0 +1,154 @@
+# 1.7.0 Upgrade Guide
+
+**TL;DR: every 1.6.x dungeon runs unmodified, and produces byte-identical events
+unless it uses one of three features** — `hasLocation: true` (event geo becomes
+stable per user), `conditions` with a function or bare-array value (now throws;
+it never matched before), or a world event on a multi-step funnel (windows now
+test the step's real time). 1.7.0 is the **declarative-knobs release** for
+consumers that render configs without writing hooks: segmented funnels with
+operators, the experiment variant on the profile, context-aware property
+functions, sticky event properties, one campaign per user, declarative weights,
+world-event spikes, and a `result.warnings` array that says what the engine
+changed. Three type-level fields are removed from `Persona`.
+
+## What changed
+
+### 1. `result.warnings` (new, additive) — read this first
+
+Every value the validator clamped and every run-level aggregate now comes back on
+the result, regardless of `verbose`:
+
+```js
+const { warnings } = await DUNGEON_MASTER(config);
+// [{ key, requested, applied, reason, severity: 'clamp' | 'warn', count? }]
+```
+
+**Action**: if you display config values to a user, display `applied`, not what
+you sent. Keys you will see: `percentUsersBornInDataset`, `bornRecentBias`,
+`avgEventsPerUserPerDay`, `avgActiveDaysPerUser`, `numDays`,
+`funnels[<name>].conversionWindowDays`, `funnels[<name>].conversionRate:<source>`,
+`funnels.conditions`, `personas.eventMultiplier`, `numEvents`, `campaignPerUser`.
+
+### 2. `macro` object overrides apply (fix)
+
+Before 1.7.0 `macro: { percentUsersBornInDataset: 50 }` was silently capped at 12.
+Now an object **without** `preset` is a custom macro with no cap. An object or
+string **with** a named preset keeps that preset's cap (flat 12, steady 12, growth
+30, viral 55, decline 5) and reports the clamp in `warnings`.
+
+**Action**: if you worked around this by emitting the top-level key with no
+`macro`, you can switch to `macro: { bornRecentBias, percentUsersBornInDataset,
+preExistingSpread }` and combine born share with any bias you like.
+
+### 3. `singleCountry` accepts codes and throws on a miss (fix)
+
+`'US'`, `'us'`, `'United States'` all work. `'Narnia'` throws with the valid list.
+Before, a miss (including `'US'`) emptied the location pool and deleted every geo
+property. Also accepted inside `switches`.
+
+**Action**: if you validated against your own country list, drop it — the engine
+validates now.
+
+### 4. `strictEventCount` is exact (fix)
+
+Lands on `numEvents` exactly when the users' capacity allows (measured 5,000 of
+5,000; 30,000 of 30,000). If it cannot, the run stops short and `warnings` carries
+`{ key: 'numEvents', requested, applied }`. Only under the flag.
+
+### 5. `importResults.users` reconciles (fix)
+
+`{ ...mixpanelImportResult, generated, dropped_anonymous }` so
+`generated - dropped_anonymous - failed === success`.
+
+**Action**: stop overwriting `success` with your own user count.
+
+### 6. `funnels[].conditions` operators (new)
+
+```js
+conditions: {
+  platform:  'iOS',                          // scalar: strict equality (unchanged)
+  plan_tier: { in: ['pro', 'enterprise'] },
+  seats:     { gte: 10 },
+  country:   { neq: 'US' },
+}
+```
+
+`eq`, `neq`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`. **Breaking (B1)**: a function or
+bare-array condition value now throws at validation instead of silently never
+matching. Undeclared condition keys and users who match no funnel land in `warnings`.
+
+### 7. Experiment variant on the profile (new, default on)
+
+Exposed users carry `"Experiment: <name>": "<variant>"`. `experiment: { stampProfile:
+false }` opts out; `sticky: false` implies off. The `user` hook does not see it (it
+fires before exposure); `everything` does.
+
+### 8. `(ctx) => value` property functions (new)
+
+```js
+revenue: (ctx) => ctx.profile.plan === 'pro' ? 100 : 10,
+total:   (ctx) => ctx.event.price * ctx.event.quantity,
+```
+
+`ctx = { profile?, event?, time?, config }`. Zero-arity functions are untouched.
+A function that declares a parameter skips the source-string cache. Bound natives
+(`chance.x.bind(chance)`) are still called with no argument. JSON dungeons: the
+`arrow` form now emits `(ctx) => body`.
+
+### 9. `stickyEventProps` + stable location (new + fix B2)
+
+`stickyEventProps: ['plan_tier', 'platform']` copies profile keys onto every event
+(schema-first: undeclared keys throw). **B2**: with `hasLocation: true` each user's
+events now share the user's city / region / country. Event geo distributions
+change at the same seed; profiles do not.
+
+### 10. `personas[].ttcModifier` (new) and dead fields removed (B3)
+
+`ttcModifier: 0.5` halves `timeToConvert` for the persona. `churnRate`,
+`activeWindow`, `soupOverride` are removed from the `Persona` type — they never
+did anything. Runtime still accepts and warns on them. `churnRate` is no longer
+defaulted to `0` on the validated persona.
+
+### 11. `campaignPerUser` (new)
+
+One campaign per user at birth, UTMs on the profile and on every touchpoint.
+Persona `properties` that set `utm_*` win over the draw. Needs `hasCampaigns`.
+
+### 12. `{ __weights }` and `autoPowerLaw` (new)
+
+`{ __weights: { free: 60, pro: 30, enterprise: 10 } }` states a distribution.
+`autoPowerLaw: false` turns the implicit 45/25/15 draw on 3–19-item string arrays
+off for the run. Default behavior is unchanged.
+
+### 13. `worldEvents[].volumeMultiplier > 1` amplifies (fix)
+
+Affected in-window events are cloned (fresh `insert_id`, spread across the window)
+so volume reaches the stated multiple — measured 3.06x for an asked 3x (1.08x
+before). Fractional multipliers work. Windows on funnel steps after the first now
+test the step's real time.
+
+**Action**: delete any hook that cloned events to fake a spike.
+
+### 14. `eventMultiplier` and `isChurnEvent` (doc + warning)
+
+`eventMultiplier` does reach funnel passes (measured ~3x for 3x). What washes it
+out is an `isChurnEvent` in the standalone pool, which ends every user after about
+the same number of events. The run now warns (`personas.eventMultiplier`) when more
+than half the users churn while a persona multiplier is in play.
+
+**Action**: if you refused persona multipliers on funnel-heavy schemas, refuse them
+on churn-heavy schemas instead — or lower the churn event's weight.
+
+### 15. Day-1 retention floor (doc)
+
+`retentionCurve` cannot move day 1 below ~0.85 on funnel-driven dungeons; verify
+from day 7 on. Stated in the `retentionCurve` JSDoc, README, and HOOKS.md §2.7.
+
+## Verification
+
+```bash
+npx vitest run tests/unit tests/integration tests/e2e 2>&1 | tail -50   # 1967 tests pass
+npm run typecheck
+node tests/engine/smoke-test-all.mjs                                       # 22/22
+npx vitest run tests/integration/v170-engine-requests.test.js             # the measured claims
+```