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

package/README.md

@@ -91,6 +91,11 @@ const result = await DUNGEON_MASTER({
 console.log(result.importResults);
 ```
 
+`token` imports event-shaped streams only: events, users, groups, ad spend, and
+`standaloneEvents`. `warehouseMetrics` does **not** import through this path.
+warehouse tables are materialized locally and need a separate warehouse deploy
+step after the run.
+
 ## dungeons
 
 a dungeon is a javascript file that exports a configuration object. it defines your entire data model: events, funnels, user properties, group analytics, SCDs, and a hook function that engineers discoverable patterns into the data.
@@ -155,7 +160,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 +437,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.
@@ -507,6 +542,8 @@ dungeon-master generates multiple data types that mirror a real analytics implem
 | SCDs | `scdProps` | slowly changing dimensions (subscription tier over time) |
 | lookup tables | `lookupTables` | dimension tables (product catalog, region mapping) |
 | ad spend | `hasAdSpend` | daily ad spend with impressions, clicks, cost metrics |
+| standalone events | `standaloneEvents` | identity-less metric snapshots on a cadence (infrastructure, finance, ops) |
+| warehouse metrics | `warehouseMetrics` | warehouse source tables derived from generated events, with a manifest for downstream deploy |
 | mirror datasets | `mirrorProps` | transformed copies of event data (A/B versions) |
 | organic text | `createTextGenerator` | reviews, support tickets, search queries, chat messages |
 
@@ -537,6 +574,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 +611,224 @@ 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.
+
+## standalone events (identity-less metric snapshots)
+
+`standaloneEvents` generates records that describe a **system, not a person**. they carry
+no `user_id` and no `device_id`. use them for infrastructure, finance, and ops telemetry:
+daily CDN egress per region, weekly billing rollups per plan tier, hourly queue depth per
+cluster. `hasAdSpend` is the same idea hard-coded to `$ad_spend`; this is the general form
+and it does not use a Mixpanel reserved event name.
+
+```javascript
+standaloneEvents: [
+  {
+    event: 'cdn_egress',
+    cadence: 'day',                                       // 'hour' | 'day' | 'week' (default 'day')
+    dimensions: { region: ['us-east', 'us-west', 'eu'] }, // cross-producted
+    distinctIdFrom: 'region',                             // synthetic id, never a person
+    properties: {
+      gb_out:   (ctx) => 400 + ctx.tickIndex * 3,         // shape a trend across the window
+      cost_usd: (ctx) => (400 + ctx.tickIndex * 3) * 0.085,
+      p95_ms:   [120, 140, 160],                          // same ValueValid forms as event props
+    },
+  },
+  {
+    event: 'billing_rollup',
+    cadence: 'week',
+    dimensions: { tier: ['free', 'pro', 'max'] },
+    properties: { mrr_usd: (ctx) => ..., churn_usd: (ctx) => ... },
+  },
+]
+```
+
+the engine emits **one record per cadence tick per dimension cross-product row**. the
+example above produces 3 records per day (`cdn_egress`) plus 3 records per week
+(`billing_rollup`). ticks start at the dataset start and step by the cadence; the last tick
+is the final one at or before the dataset end, so nothing lands in the future.
+
+each record carries `event`, `time`, `insert_id`, `distinct_id`, every dimension as a flat
+property, and every resolved entry in `properties`.
+
+| field | behavior |
+|---|---|
+| `event` | required, unique across `standaloneEvents` |
+| `cadence` | `'hour'`, `'day'`, or `'week'`. default `'day'` |
+| `dimensions` | object of non-empty arrays, cross-producted. omit for one record per tick |
+| `distinctIdFrom` | must name a declared dimension. omitted → `distinct_id` is the event name |
+| `properties` | keys may not collide with a dimension or with `event`/`time`/`insert_id`/`distinct_id`/`user_id`/`device_id` |
+
+property value functions receive a `StandaloneValueContext`: `{ time, config, dimensions,
+tickIndex, tickCount, cadence, event }`. `tickIndex / (tickCount - 1)` is window progress —
+use it to shape growth, a dip, or a spike, guarding `tickCount <= 1` before division.
+
+the stream lands in `result.standaloneEventData`, writes to its own `-STANDALONE` file
+shard, and imports to Mixpanel as its own event stream. hooks fire with type
+`"standalone"`; `meta.spec` carries the resolved config so a hook can tell streams apart.
+the hook runs before the user loop. return the record object or an array of records;
+returning `undefined` drops the record. it has no person metadata and never enters
+`everything`. warehouse hooks have a different contract: mutate the row in place;
+their return values are ignored.
+
+```javascript
+hook: (record, type, meta) => {
+  if (type === 'standalone' && meta.spec.event === 'cdn_egress' && record.region === 'us-east') {
+    record.p95_ms *= 40;
+  }
+  return record;
+}
+```
+
+validation throws rather than skipping. a malformed entry would silently drop a whole data
+stream, and you would not notice until the charts were wrong.
+
+## warehouse metrics (local source tables)
+
+`warehouseMetrics` materializes warehouse-ready tables from the run's own event
+stream after user generation completes. use it when you need a bookings table, a
+subscription level snapshot, or an ARR table that reads like a real warehouse
+source. these rows land in `result.warehouseMetricData`, write to
+`<name>-WAREHOUSE-<table>.csv|json`, and emit one manifest at
+`<name>-WAREHOUSE-MANIFEST.json`.
+
+they are **not** imported by `token`. that is deliberate. the live path is:
+
+1. run the dungeon
+2. review `/warehouse-metrics` in dry-run mode
+3. obtain explicit operator consent for live execution
+4. load the tables to bigquery and save the metrics there
+
+live deploy uses `bq load --replace`, so it overwrites the destination warehouse
+tables. the shipped script does not prompt on its own, so the operator or agent
+must obtain explicit consent before running it in live mode. if the
+warehouse CRUD docs route returns 404, the deploy still loads tables and connects
+the source, then writes `warehouse/GAPS.md` for manual metric creation.
+
+the manifest carries `recommendedAggregation: 'sum' | 'last value'`. the
+Mixpanel warehouse metric API spells that second value as `last_value`; the
+deploy flow maps it for you.
+
+there is one real preview trap: `previewWarehouseMetric` rejects raw SQL
+containing `DROP`, `DELETE`, `TRUNCATE`, `ALTER`, `CREATE`, `INSERT`, or
+`UPDATE` as plain substrings. `created_at` trips `CREATE`; `updated_at` trips
+`UPDATE`. aliasing only helps if the blocked text disappears from the query
+entirely.
+
+### canonical shapes
+
+additive daily bookings:
+
+```javascript
+warehouseMetrics: [{
+  name: 'daily_new_bookings',
+  source: {
+    event: 'new_booking',
+    measure: 'sum',
+    property: 'booking_value',
+  },
+  timeColumn: 'date',
+  valueColumn: 'bookings',
+}]
+```
+
+point-in-time daily active subscriptions:
+
+```javascript
+warehouseMetrics: [{
+  name: 'daily_active_subscriptions',
+  type: 'point-in-time',
+  source: {
+    event: 'subscription_started',
+    minus: 'subscription_cancelled',
+    measure: 'count',
+  },
+  baseline: 40,
+  timeColumn: 'date',
+  valueColumn: 'active_subscriptions',
+}]
+```
+
+sparse monthly ARR with backfill:
+
+```javascript
+warehouseMetrics: [{
+  name: 'monthly_arr_snapshot',
+  type: 'point-in-time',
+  grain: 'month',
+  sparse: true,
+  history: 18,
+  source: {
+    event: 'subscription_started',
+    minus: 'subscription_cancelled',
+    measure: 'sum',
+    property: 'monthly_value',
+  },
+  baseline: 24000,
+  scale: 12,
+  timeColumn: 'month',
+  valueColumn: 'arr_usd',
+}]
+```
+
+the shipped technical fixture uses a 60-day live window plus 18 monthly backfill
+buckets. sample row counts are illustrative only. `grain`, `history`, `sparse`,
+and `groupBy` all change how many rows a table emits.
+
+### config surface
+
+| key | default | range / contract |
+|---|---|---|
+| `name` | required | unique table / metric name, `/^[a-z][a-z0-9_]{0,63}$/` |
+| `type` | `'additive'` | `'additive'` or `'point-in-time'` |
+| `grain` | `'day'` | `'day'`, `'week'`, `'month'` |
+| `sparse` | `false` | boolean, valid only with `type: 'point-in-time'` |
+| `source.event` | required | string or string[] of declared source events |
+| `source.minus` | `[]` | string or string[] of declared subtractive events |
+| `source.measure` | `'count'` | `'count'`, `'sum'`, `'avg'`, `'dau'`, `'users'`; point-in-time forbids `'avg'` and `'dau'` |
+| `source.property` | `null` | required for `'sum'` and `'avg'`; must be declared on every source event or in `superProps` |
+| `source.where` | `null` | optional function over flat event rows |
+| `source.groupBy` | `[]` | up to 2 keys, each declared on every source event or in `superProps`; observed cardinality above 50 warns |
+| `timeColumn` | `'date'` | valid JS identifier; becomes the ordered time axis in rows and manifest |
+| `valueColumn` | `'value'` | valid JS identifier |
+| `baseline` | `0` | number `>= 0`; used only for point-in-time metrics, ignored on additive |
+| `scale` | `1` | finite number `> 0`, applied after bucket aggregation |
+| `noise` | `0` | finite number, clamped to `[0, 0.5]` with a warning |
+| `history` | `0` | integer `>= 0`; warns above roughly 3 years at each grain (`1095` day, `156` week, `36` month) |
+| `columns` | `{}` | extra declared output columns; keys must be valid identifiers and cannot collide with time/value/groupBy columns |
+| `format` | dungeon `format`, else `'csv'` | `'csv'` or `'json'` |
+
+materialized tables are deterministic at the same seed and do not perturb the
+event stream. the warehouse pass runs after the user loop, so seeded noise and
+derived columns never change generated events.
+
+### result and manifest
+
+```javascript
+const result = await DUNGEON_MASTER(config);
+
+result.warehouseMetricData.daily_new_bookings
+result.warehouseManifest.tables
+result.files
+```
+
+each manifest table includes:
+
+| field | meaning |
+|---|---|
+| `table` | warehouse table name |
+| `file` | file prefix without extension |
+| `format` | `'csv'` or `'json'` |
+| `grain` | bucket grain |
+| `type` | additive vs point-in-time |
+| `timeColumn` | date axis column |
+| `valueColumn` | numeric value column |
+| `dimensionColumns` | copied `groupBy` keys |
+| `columns` | ordered BigQuery schema (`DATE`, `FLOAT64`, `BOOL`, `STRING`) |
+| `recommendedAggregation` | `'sum'` or `'last value'` |
+| `sql` | `SELECT * FROM \`{{DATASET}}.<table>\` ORDER BY <timeColumn>` |
+| `refreshHint` | currently `'hourly'` |
+
 ## 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 +846,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:
@@ -605,8 +920,11 @@ result.userProfilesData  // user profiles
 result.scdTableData      // SCD mutations
 result.groupProfilesData // group profiles
 result.adSpendData       // ad spend data
+result.standaloneEventData // identity-less event snapshots
 result.lookupTableData   // lookup table entries
 result.mirrorEventData   // mirror dataset
+result.warehouseMetricData // warehouse tables keyed by metric name
+result.warehouseManifest // warehouse table manifest
 
 result.eventCount        // total event count
 result.userCount         // total user count
@@ -705,7 +1023,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 +1045,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,22 +1105,28 @@ 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 |
 | `hasLocation` | boolean | false | include geo properties |
 | `hasCampaigns` | boolean | false | include UTM properties |
 | `hasAdSpend` | boolean | false | generate ad spend data |
+| `standaloneEvents` | array | `[]` | identity-less cadence streams that import as events |
+| `warehouseMetrics` | array | `[]` | local warehouse source tables + manifest, derived from generated events |
 | `hasAnonIds` | boolean | false | generate anonymous IDs |
 | `hasSessionIds` | boolean | false | generate session IDs |
 | `alsoInferFunnels` | boolean | false | auto-generate funnels from events |

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
+```