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

package/.claude/skills/headless-build/SKILL.md

@@ -81,6 +81,7 @@ dungeons/user/<name>/build/
 │   ├── 06..09_dash_<story>.py   # one board per engineered story
 │   ├── 10_annotations.py
 │   ├── 11_behaviors_metrics.py  # via power-tools; headless lacks these
+│   ├── 13_render_check.py       # saved params must be RENDERABLE, not just queryable
 │   └── 99_verify.py
 └── results/                # entities.json registry, window.json, verification_*.json
 ```
@@ -103,11 +104,75 @@ actually works. Verified on both NYC DCP and Peloton:
 - Insights `group_by` / `where` / saved-cohort filters: **work**.
 - Funnels `group_by`: **silently does not segment** — returns rows identical to
   ungrouped. Use one funnel per segment with a `where` filter instead.
-- Day-granularity queries reject ranges **over 366 days**.
+- Day-granularity queries reject ranges **over 366 days**. `unit="hour"` works
+  fine, including with `group_by` — that is how you read hour-of-day, since the
+  App API rejects `hour(A)` in a custom-property formula as an unknown function.
 - Valid `displayOptions.chartType`: `bar`, `column`, `frequency-curve`,
   `funnel-steps`, `funnel-top-paths`, `insights-metric`, `line`, `pie`,
   `retention-curve`, `table`. There is no `stacked-area` — the API rejects it.
 
+**Filters and breakdowns fail SILENTLY, returning 0 rather than erroring.** Probe
+every one before a board depends on it. Verified on Square:
+
+| Intent | Wrong (returns 0 / "undefined") | Right |
+|---|---|---|
+| Profile property | `Filter.equals("plan", "Pro")` | `Filter.equals("plan", "Pro", resource_type="people")` |
+| Profile property breakdown | `group_by="plan"` | not supported — one query per segment with a user-scoped `where` |
+| Numeric event property | `Filter.equals("depth", 3)` | `Filter.equals("depth", "3")` — as a **string** |
+| Boolean event property | `Filter.equals("flag", True)` | `Filter.is_true("flag")` / `Filter.is_false(...)` |
+| Custom-property breakdown | `group_by="Ticket Band"` | `GroupBy(CustomPropertyRef(<id>))` |
+| Sum of a property | `math="sum"` (raises) | `math="total"` **with** `math_property` |
+| Flows, split by property | `query_flow(where=[Filter.equals(...)])` (raises `Invalid filter type: resourceType`) | cohort filters only — `query_flow(where=[Filter.in_cohort(...)])` |
+
+**Querying successfully is NOT evidence that a report renders.** The single most
+expensive bug in the Square build: `Filter.equals(..., resource_type="user")`
+instead of `"people"`. The SDK's type is `Literal["events", "people"]`, but the
+value is not validated, the query endpoint accepts it, and it returns byte-identical
+numbers — so the build printed correct figures, `99_verify.py` re-measured the story
+live and called it a MATCH, `query_saved_report` executed the saved bookmark without
+complaint, and `get_dashboard_erf` reported `is_valid_for_erf: true`. Six dashboard
+cards nonetheless rendered **"The client has issued a malformed request."** The
+defect only existed in what was *persisted*: `sections.filter[0].resourceType`.
+
+Two rules follow:
+
+- **Never invent an enum value.** If the SDK declares a `Literal`, use one of its
+  members even when another string is accepted and works.
+- **Ship a render check.** `scripts/13_render_check.py` in the Square build walks
+  every saved bookmark on every registered board and fails on any `resourceType`
+  outside `{events, people, user_profiles, cohort}`. It runs as the first step of
+  the `verify` phase, before `99_verify`. Inspect persisted params, not query
+  results — every query-based check passed while the boards were visibly broken.
+
+**Build the new board BEFORE deleting the old one.** The obvious `replace_dashboard`
+(delete by title, then create) means any interruption — and a rate-limit wall
+partway through a board's queries is routine — leaves the project with no board at
+all. Capture the old ids first, create the replacement, then retire the old ones
+(`existing_dashboard_ids` → `publish(..., supersedes=...)` in the Square `_common.py`).
+
+**Budget the per-hour query cap across the whole session, not per run.** Probing,
+building, and verifying all draw on the same hourly allowance. Interactive probes
+early in a session can exhaust it and strand a rebuild hours later. Boards with
+many segment-per-query funnels are the expensive ones — the Square activation board
+alone fires ~30.
+
+**Retention: cohort maturity will eat your effect.** `query_retention` pools every
+cohort in the range, including ones a fortnight old that cannot yet have failed to
+return in week 4, and there is no server-side way to restrict the cohort window.
+On Square the same attach-retention gap read **1.71x pooled and 2.98x** over cohorts
+with a fully observed horizon. Aggregate the frame yourself: weight buckets by cohort
+size, require each bucket to be observed END TO END (`(b+1)*unit - 1` days of history,
+not `b*unit`), and cap the cohort date. Put both numbers on the board — the diluted
+one is what the chart shows, and naming why is a better demo than hiding it.
+
+**Time-to-convert is a MEAN, and means are tail-dominated.** Funnel frames carry
+`avg_time` and `avg_time_from_start` (seconds; not monotonic across steps — each is
+over that step's own survivors). A dungeon knob expressed as a median ratio will not
+reproduce: Square's designed 13x median gap measured 1.95x as a mean over a 30-day
+window. Use the **speed curve** instead — run the same funnel at 1/3/7/14-day
+conversion windows and read what share of each segment's eventual conversions had
+landed by then. Same effect, expressed in a statistic Mixpanel actually computes.
+
 ### 3. Auto-detect the data window
 
 Never hardcode dates. A regenerated dungeon lands on new ones and every chart
@@ -196,6 +261,11 @@ is accepted and applied, but every definition collapses to the same membership
 three different cohorts return byte-identical numbers instead of erroring. Create
 cohorts first, then filter by id: `Filter.in_cohort(<saved_id>, "<name>")`.
 
+**`getCohorts` can report `count: 0` for every cohort** even when they hold thousands
+of members and filter queries correctly. Do not use the listing's count as the
+membership check in `99_verify.py` — run one cheap query per cohort instead. This is
+the same call that warms them, so it costs nothing extra.
+
 **`create_cohort` via headless 500s** on some projects; `CreateCohortParams.definition`
 also wants `.to_dict()`, not the builder object. Use `/crud/createCohort` — see the
 `powertools` skill for the payload shape and its limits (behavioral counts yes;

package/CHANGELOG.md

@@ -2,6 +2,133 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.6.5 — 2026-09-02
+
+### Changed
+
+- **`matchMixpanelDefaults: true` on every live send to Mixpanel.** Set in
+  `commonOpts` in `lib/orchestrators/mixpanel-sender.js`, passed straight through
+  to `mixpanel-import`. Renames warehouse-style property keys to Mixpanel's
+  reserved names (e.g. `current_url` → `$current_url`, `_browser` → `$browser`)
+  as records stream out. Only affects the wire payload sent to Mixpanel's
+  ingestion API — generated events, profiles, and files on disk are unchanged.
+  Same seed, same config still produces byte-identical generated output.
+
+## 1.6.4 — 2026-09-01
+
+Answers the doc/type half of the DM4 v5 engine request
+(`dungeon-master-library-changes-requested.md`, 2026-09-01). Every claim in that
+document was checked against source; all were accurate except the three noted
+under "Already correct" below.
+
+This release is deliberately scoped to changes that cannot alter generated data:
+docs, types, one additive helper option, one additive config form, and one
+warning. The feature requests are tracked for 1.7.0 — see "Deferred to 1.7.0".
+
+No generated output changes. Verified: same seed, same config, `concurrency: 1`,
+pinned dataset window — 1.6.4 and 1.6.3 produce byte-identical events, user
+profiles, and group profiles.
+
+### Added
+
+- **`scaleEventCount(events, name, factor, { spreadDays })`.** Scatters clones
+  uniformly across the next N days instead of stepping 1 second at a time. The
+  default 1-second spread cannot create a new distinct active day and cannot open
+  a new session under Mixpanel's 30-minute gap rule, so a default call moves event
+  volume and nothing else — not active days, DAU, stickiness, sessions, frequency
+  bins, or retention. 33 dungeons in the DM4 corpus used the default and then
+  documented an active-day, session, frequency, or stickiness claim. All 33 were
+  wrong. The limitation is now stated in the helper's JSDoc, in HOOKS.md §2.1, and
+  in HOOKS.md gotcha #22. Clones that land past `FIXED_NOW` are still dropped by
+  the future-time guard. Default behavior is unchanged.
+- **Named-object form for `groupKeys`.** `{ key, cardinality, events? }` alongside
+  the positional tuple `[key, cardinality]` / `[key, cardinality, events]`. Both
+  forms may be mixed in one array. The validator normalizes to tuples, so hooks,
+  the generators, and the verifier still see exactly one shape. Added so a
+  form-driven config generator never has to emit an untyped positional tuple.
+  Bad input throws with the offending index.
+- **HOOKS.md §2.1.1 — "Cloned events MUST carry a fresh `insert_id`."** The
+  consequence was only in a source comment before. Four DM4 corpus files
+  hand-rolled `JSON.parse(JSON.stringify(e))` and had their entire engineered
+  surge deduped away by Mixpanel at ingest, with local verification still
+  reporting the surge as present. Includes the note that data generated this way
+  on 1.6.2 or earlier is wrong in-project and must be regenerated.
+- **README "one config surface, not two."** States that the `credentials` /
+  `switches` / `identity` sub-objects are the canonical form, that the flat
+  top-level keys are a back-compat alias, and that top-level wins when both are
+  set. Mirrored in CLAUDE.md and in the three sub-object JSDoc blocks.
+
+### Changed
+
+- **The `avgActiveDaysPerUser` + `engagementDecay` warning is no longer gated
+  behind `verbose`.** The combination silently returns an active-day count at or
+  below the configured value, never above. A config UI that shows the requested
+  number was lying about it. Documented in HOOKS.md §2.5 and in the
+  `avgActiveDaysPerUser` JSDoc.
+- **`retentionCurve` precedence is now documented.** When both `retentionCurve`
+  and `avgActiveDaysPerUser` are set, the curve wins and `avgActiveDaysPerUser` is
+  ignored entirely. Behavior is unchanged — only the docs were missing. Added to
+  the CLAUDE.md safe-range table, the README config table, HOOKS.md §2.5, and the
+  `avgActiveDaysPerUser` JSDoc.
+
+### Fixed (types and docs)
+
+- **`writeToDisk` doc was wrong.** It read "If true (default), writes output files
+  to ./data/". The runtime default is `false` (`config-validator.js`).
+- **`region` types disagreed.** Top-level `region` was `"US" | "EU"` while
+  `DungeonCredentials.region` allowed `"IN"`. Both now use a shared `Region` type
+  of `'US' | 'EU' | 'IN'`, which matches what `mixpanel-import` accepts.
+- **`hasAttributionFlags` was presented as a settable switch.** The validator
+  unconditionally overwrites it with `events.some(e => e.isAttributionEvent)`. It
+  is removed from `DungeonSwitches` and from the `switches` hoisting allowlist,
+  and marked `@internal` on `Dungeon`. Read it off `result.validatedConfig`;
+  setting it never did anything.
+- **`GroupEventConfig` / `config.groupEvents` removed from the public types.** A
+  declared-only stub — nothing in `lib/` ever read it, its own doc comment said
+  "not yet implemented", and no shipped dungeon set it. Removed from `types.d.ts`,
+  `lib/templates/abbreviated.d.ts`, `lib/templates/schema.d.ts`, and the `wrapFunc`
+  whitelist. To scope an event to a group, list it in that group key's `events`
+  array.
+
+- **The determinism claim was overstated.** README and CLAUDE.md both said "same
+  seed + same config + `concurrency: 1` = byte-identical output". That has been
+  false since 1.4.0: `insert_id` is a `randomUUID()`, so it differs on every run
+  by design — which is what keeps Mixpanel from deduping a re-import of the same
+  dataset. Found while verifying that this release changes no output. Everything
+  else is byte-identical; strip `insert_id` before diffing two runs. Both docs now
+  say so.
+
+### Already correct (no change needed)
+
+- `funnels[].reentry` and `funnels[].stepFilters` were reported as reading like
+  generation features. Their JSDoc already says "Verifier-only hint … Generator
+  behavior unchanged."
+- The dead persona fields (`churnRate`, `activeWindow`, `soupOverride`) were
+  reported as `verbose`-gated. Their warning already fires unconditionally, once
+  per process. They stay accepted and warned; removing them from the `Persona`
+  type is a 1.7.0 change because it is a type-level break.
+
+### Deferred to 1.7.0
+
+Everything below is new public surface or a behavior change, so none of it belongs
+in a patch. Per-item design lives in the maintainer's local `plans/1.7.0/SPEC.md`
+(the `plans/` tree is not published).
+
+| Request | Why not in 1.6.4 |
+|---|---|
+| `funnels[].conditions` operators (`in`, `gte`, `neq`, …) | New public surface. Also throws on function/array condition values, which is a break. |
+| Experiment variant stamped on the user profile | New profile property; needs a change to when variants resolve. |
+| `(ctx) => value` for property value functions | New signature. Requires an arity guard on the `choose` source-string cache first, or context-aware functions get frozen at their first evaluation. |
+| `stickyEventProps` | New surface. Also needs `lib/verify/schema-validator.js` taught about it, or `/verify-dungeon` reports every sticky prop as flag stamping. |
+| Stable per-user `location` under `hasLocation` | A real fix (`featureCtx.userLocation` is computed and never read), but it changes generated event geo. |
+| `personas[].ttcModifier` | New surface. |
+| Removing the three dead persona fields from the `Persona` type | Type-level break. |
+| `campaignPerUser` | New surface. |
+| `autoPowerLaw: false` and `{ __weights }` | New surface. |
+| `result.warnings[]` for clamps | New result surface. |
+| Ad spend derived from users acquired per campaign | Needs a new cross-user aggregate pass. Deferred past 1.7.0. |
+| Engine-side `conversionRate` saturation reporting | Depends on `result.warnings[]`. Note: the engine can report its own `Math.min(100, …)` clamps, but not a hook's own `Math.min(95, rate * 3)` — that cap belongs to the hook and the engine never sees the intended value. |
+
 ## 1.6.3 — 2026-08-17
 
 ### Fixed

package/HOOKS.md

@@ -88,6 +88,58 @@ users between frequency bins. Both `injectOnNewDays` and the default
 `countDistinctPeriods` algorithm use calendar-bucket math, so they agree
 at boundaries.
 
+One second is also below Mixpanel's 30-minute session gap, so the default
+spread cannot create a new session either. The full list of metrics a default
+`scaleEventCount` call **cannot** move: active days per user, DAU, stickiness
+(DAU÷MAU), sessions per user, frequency bins, and retention. It moves event
+volume, and nothing else.
+
+As of v1.6.4 you can pass `{ spreadDays: N }` to scatter the clones across the
+next N days instead:
+
+```js
+// volume only — same day, same session
+scaleEventCount(record, "commit pushed", 3);
+
+// volume AND active days AND sessions
+scaleEventCount(record, "commit pushed", 3, { spreadDays: 7 });
+```
+
+`injectOnNewDays` remains the better tool when you want a specific target
+day count rather than a multiplier.
+
+### 2.1.1 Cloned events MUST carry a fresh `insert_id`
+
+Mixpanel deduplicates on `insert_id` at ingest. A clone that keeps its source's
+`insert_id` is silently discarded — the surge you engineered never appears in the
+project, no error is raised, and local verification does not catch it because
+`emulateBreakdown` never inspects `insert_id`.
+
+Leaving `insert_id` blank is not safe either. The importer content-hashes events
+that lack one, so identical clones hash to the same value and collide the same way.
+
+```js
+// PREFERRED — cloneEvent stamps a fresh insert_id
+record.push(cloneEvent(sourceEvent, { time: newTime }));
+
+// ALSO FINE — the engine re-stamps the duplicate id
+record.push({ ...sourceEvent, time: newTime });
+
+// HISTORICALLY BROKEN — pre-1.6.3 this deduped the whole surge away
+const clone = JSON.parse(JSON.stringify(sourceEvent));
+clone.time = newTime;
+record.push(clone);
+```
+
+Since v1.6.3 the engine re-stamps any duplicate or missing `insert_id` across each
+user's final stream ([user-loop.js:753-776](lib/orchestrators/user-loop.js#L753-L776)),
+so all three shapes now survive ingest. Prefer
+[`cloneEvent`](lib/hook-helpers/mutate.js) anyway: the engine pass is a per-user
+last resort, and it cannot help a clone that a hook moves onto a different user.
+
+If you generated data with a hand-rolled deep-copy clone on **1.6.2 or earlier**,
+that data is wrong in the project. Regenerate and re-import.
+
 ### 2.2 Funnels are GREEDY single-pass with a 2-second grace
 
 Mixpanel processes events in chronological order, single pass. Each event is
@@ -217,6 +269,15 @@ count BELOW the configured target. Pick one. If you need both effects, set
 `avgActiveDaysPerUser` and write decay logic in an `everything` hook scoped
 to specific cohorts (gives explicit control over the interaction).
 
+As of v1.6.4 the validator warns **unconditionally** when both are set — the
+warning is not gated behind `verbose`, because the combination silently returns
+an active-day count the author did not ask for.
+
+**Precedence with `retentionCurve`:** when `retentionCurve` is set, it wins.
+The active-day planner runs from the curve and `avgActiveDaysPerUser` is ignored
+([user-loop.js:326-337](lib/orchestrators/user-loop.js#L326-L337)). Set one or
+the other, not both.
+
 ### 2.6 Sessions are query-time computed (30-min gap, 24h max, day-boundary split)
 
 Reference: `backend/arb/reader/queries/session_query.cpp:828-830, 905-928`.
@@ -666,10 +727,12 @@ Reference: `flows_query.cpp:988-994` (next-anchor-only), `flows.cpp:680-717`
     still correct.
 
 22. **`scaleEventCount` does not move users between frequency bins.** Cloning
-    Buy events at sub-second offsets places them on the same calendar day, so
-    the user's distinct-day count is unchanged. To shift frequency bins use
+    Buy events at sub-second offsets places them on the same calendar day and
+    inside the same 30-minute session window, so distinct days, sessions, DAU,
+    stickiness, and retention are all unchanged. It moves event volume only. To
+    shift any of the others, pass `{ spreadDays: N }` (v1.6.4) or use
     [`injectOnNewDays`](lib/hook-helpers/inject.js), which spreads injections
-    across previously empty days within the user's active window.
+    across previously empty days within the user's active window. See §2.1.
 
 23. **Out-of-order injected events get consumed by the funnel engine.** Adding
     a "step C" event before "step B" in the stream causes Mixpanel's greedy
@@ -1705,9 +1768,9 @@ Import from `@ak--47/dungeon-master/hook-helpers`:
 | `userInProfileSegment` | cohort | `(profile, key, values) -> boolean` | Profile property match |
 | **`hashFloat`** | cohort | `(id) -> number` | FNV-1a over the FULL id string → [0,1). Deterministic bucketing primitive (v1.6) — replaces `charCodeAt(0) % N` idioms, which bias cohort rates on hex-ish id alphabets |
 | **`hashCohort`** | cohort | `(id, pct) -> boolean` | True for ~`pct`% of ids (pct on a 0–100 scale). Membership nests: `pct=5` ⊂ `pct=20` |
-| `cloneEvent` | mutate | `(template, overrides?) -> event` | Shallow clone with overrides |
+| `cloneEvent` | mutate | `(template, overrides?) -> event` | Shallow clone with overrides **and a fresh `insert_id`** — never hand-roll this (see Section 2.1) |
 | `dropEventsWhere` | mutate | `(events, predicate) -> number` | Remove matching events in-place |
-| `scaleEventCount` | mutate | `(events, eventName, factor) -> number` | Scale total count via clones at sub-second offsets (does NOT move frequency-distribution bins — see Section 2.1) |
+| `scaleEventCount` | mutate | `(events, eventName, factor, options?) -> number` | Scale total count via clones. Default 1s offsets do NOT move frequency, session, active-day, or retention metrics — see Section 2.1. Pass `{ spreadDays: N }` (v1.6.4) or use `injectOnNewDays` |
 | `scalePropertyValue` | mutate | `(events, predicate, prop, factor) -> number` | Multiply numeric property; null-aware safe |
 | `shiftEventTime` | mutate | `(event, deltaMs) -> event` | Shift one timestamp |
 | `scaleTimingBetween` | timing | `(events, eventA, eventB, factor) -> boolean` | Scale gap between first A and first B |

package/README.md

@@ -584,6 +584,15 @@ all randomness is seeded. same seed + same config + concurrency=1 = identical ou
 }
 ```
 
+pin `datasetStart` and `datasetEnd` too, or the dataset window moves with the
+calendar and every timestamp shifts.
+
+**one exception: `insert_id`.** since 1.4.0 it is a `randomUUID()`, so it differs
+on every run by design — that is what keeps Mixpanel from deduping re-imports of
+the same dataset. strip `insert_id` before diffing two runs. everything else
+(event count, order, timestamps, every property, profiles, groups) is
+byte-identical.
+
 ## what gets generated
 
 the result object contains everything:
@@ -689,6 +698,53 @@ engine tests are NOT shipped in the npm package and NOT run as part of `npm test
 
 ## config reference
 
+### one config surface, not two
+
+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` |
+| `identity` | `avgDevicePerUser`, `sessionTimeout` |
+
+**the sub-object form is canonical.** the flat top-level keys are a back-compat
+alias and stay supported. emit one form or the other — never both. when a key is
+set in both places the **top-level value wins**, with a `verbose`-gated warning
+you will not see unless `verbose: true`.
+
+```javascript
+// canonical
+{ credentials: { token: process.env.MIXPANEL_TOKEN, region: 'US' },
+  switches:    { hasCampaigns: true, hasAdSpend: true },
+  identity:    { avgDevicePerUser: 2 } }
+
+// back-compat alias — still works
+{ token: process.env.MIXPANEL_TOKEN, region: 'US',
+  hasCampaigns: true, hasAdSpend: true, avgDevicePerUser: 2 }
+```
+
+`hasAttributionFlags` is **not** a switch. the validator derives it from
+`events[].isAttributionEvent`; setting it has no effect.
+
+### group keys
+
+`groupKeys` accepts a positional tuple or a named object. both normalize to the
+tuple internally, so hooks and the verifier see one shape:
+
+```javascript
+groupKeys: [
+  ['company_id', 50],                                  // tuple
+  ['team_id', 200, ['Deploy', 'Merge PR']],            // tuple + scoped events
+  { key: 'org_id', cardinality: 25 },                  // named (v1.6.4)
+  { key: 'workspace_id', cardinality: 80, events: ['Save'] },
+]
+```
+
+an omitted or empty `events` list means every event carries that group key.
+
+### commonly used properties
+
 see [types.d.ts](types.d.ts) for the complete `Dungeon` interface. here are the most commonly used properties:
 
 | property | type | default | description |
@@ -702,7 +758,7 @@ see [types.d.ts](types.d.ts) for the complete `Dungeon` interface. here are the
 | `seed` | string | random | RNG seed for reproducibility |
 | `format` | string | `'csv'` | output format (csv, json, parquet) |
 | `token` | string | null | mixpanel project token (triggers import) |
-| `region` | string | `'US'` | mixpanel data residency |
+| `region` | string | `'US'` | mixpanel data residency (`US` / `EU` / `IN`) |
 | `writeToDisk` | boolean/string | false | write files to ./data/ or a gs:// path |
 | `gzip` | boolean | false | compress output files |
 | `verbose` | boolean | false | print progress |
@@ -714,7 +770,8 @@ see [types.d.ts](types.d.ts) for the complete `Dungeon` interface. here are the
 | `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) |
 | `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) |
+| `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 |
 | `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/index.js

@@ -347,7 +347,10 @@ async function generateAdSpendData(context) {
  */
 async function generateGroupProfiles(context) {
 	const { config, storage } = context;
-	const { groupKeys, groupProps = {} } = config;
+	// `config` here is the VALIDATED config, so `normalizeGroupKeys` has already
+	// converted any `{ key, cardinality }` entries to positional tuples.
+	const groupKeys = /** @type {import('./types').GroupKeyTuple[]} */ (config.groupKeys);
+	const { groupProps = {} } = config;
 
 	if (config.verbose) {
 		logger.info('Generating group profiles...');
@@ -430,7 +433,9 @@ async function generateLookupTables(context) {
  */
 async function generateGroupSCDs(context) {
 	const { config, storage } = context;
-	const { scdProps, groupKeys } = config;
+	const { scdProps } = config;
+	// Validated config: `normalizeGroupKeys` has already flattened named entries.
+	const groupKeys = /** @type {import('./types').GroupKeyTuple[]} */ (config.groupKeys);
 
 	if (config.verbose) {
 		logger.info('Generating group SCDs...');

package/lib/core/config-validator.js

@@ -181,7 +181,11 @@ const KILLED_CONFIG_KEYS = ['subscription', 'attribution', 'geo', 'features', 'a
 // v1.5.1 — migration is gradual.
 const CONFIG_SUBOBJECTS = {
 	credentials: ['token', 'region', 'serviceAccount', 'serviceSecret', 'projectId'],
-	switches: ['hasLocation', 'hasCampaigns', 'hasAdSpend', 'hasSessionIds', 'hasAvatar', 'hasIOSDevices', 'hasAndroidDevices', 'hasDesktopDevices', 'hasBrowser', 'isAnonymous', 'alsoInferFunnels', 'hasAttributionFlags'],
+	// v1.6.4: `hasAttributionFlags` removed from this list. It is derived, not
+	// settable — line ~942 unconditionally overwrites it with
+	// `validatedEvents.some(e => e.isAttributionEvent)`. Listing it here presented
+	// a knob that never did anything.
+	switches: ['hasLocation', 'hasCampaigns', 'hasAdSpend', 'hasSessionIds', 'hasAvatar', 'hasIOSDevices', 'hasAndroidDevices', 'hasDesktopDevices', 'hasBrowser', 'isAnonymous', 'alsoInferFunnels'],
 	identity: ['avgDevicePerUser', 'sessionTimeout'],
 };
 
@@ -744,6 +748,23 @@ export function validateDungeonConfig(config) {
 	if (verbose && numDays < 14) {
 		console.warn(`⚠️  numDays=${numDays} < 14. Strict-bar engine-validation metrics use 14-day windows; results are noisy below 14 days. Consider increasing numDays.`);
 	}
+
+	// v1.6.4 (P3-9): warn when `avgActiveDaysPerUser` and `engagementDecay` are both
+	// set. The active-day planner picks a fixed number of distinct days; decay then
+	// filters events off the late ones. v1.5 Fix #1 protects the last surviving event
+	// on each picked day, so the loss is bounded — but the realized distinct-day count
+	// still lands at or below the configured value, never above. This warning is NOT
+	// verbose-gated: the combination quietly returns a number the author did not ask for.
+	if (
+		avgActiveDaysPerUser !== undefined && avgActiveDaysPerUser !== null &&
+		Number.isFinite(avgActiveDaysPerUser) && config.engagementDecay
+	) {
+		console.warn(
+			`⚠️  [dungeon-master] avgActiveDaysPerUser=${avgActiveDaysPerUser} is set together with engagementDecay. ` +
+			`Decay erodes the effective active-day count, so the realized value will be at or below ` +
+			`${avgActiveDaysPerUser}, never above. Prefer one knob or the other. See HOOKS.md §2.5.`
+		);
+	}
 	// ──────────────────────────────────────────────────────────────────────
 
 	// Use provided name if non-empty string, otherwise generate one
@@ -909,6 +930,9 @@ export function validateDungeonConfig(config) {
 		dataQuality = validateDataQuality(dataQuality);
 	}
 
+	// v1.6.4: accept the named-object groupKeys form alongside the legacy tuple.
+	const normalizedGroupKeys = normalizeGroupKeys(groupKeys);
+
 	// Phase 1: validate Funnel.attempts on every funnel (additive — most have none).
 	validateAttempts(funnels);
 
@@ -971,7 +995,7 @@ export function validateDungeonConfig(config) {
 		userProps,
 		scdProps,
 		mirrorProps,
-		groupKeys,
+		groupKeys: normalizedGroupKeys,
 		groupProps,
 		lookupTables,
 		hasAnonIds: hasAnonIdsResolved,
@@ -1104,6 +1128,43 @@ function transformSCDPropsWithoutCredentials(config) {
 	if (config.verbose === true) console.log('\u2713 SCD properties converted to static properties\n');
 }
 
+/**
+ * v1.6.4: normalize `groupKeys` to the positional tuple form the generators,
+ * hooks, and verifier all expect.
+ *
+ * Accepts either form, mixed freely in one array:
+ *   - `["company_id", 50]`                       → unchanged
+ *   - `["company_id", 50, ["Purchase"]]`         → unchanged
+ *   - `{ key: "company_id", cardinality: 50 }`   → `["company_id", 50]`
+ *   - `{ key, cardinality, events: [...] }`      → `[key, cardinality, events]`
+ *
+ * The named form exists so a form-driven generator never has to emit an untyped
+ * positional tuple. Nothing downstream needs to know which form the author used.
+ *
+ * @param {Array} groupKeys
+ * @returns {Array} tuple-form group keys
+ */
+function normalizeGroupKeys(groupKeys) {
+	if (!Array.isArray(groupKeys)) return [];
+	return groupKeys.map((entry, i) => {
+		if (Array.isArray(entry)) return entry;
+		if (entry && typeof entry === 'object') {
+			const { key, cardinality, events } = entry;
+			if (typeof key !== 'string' || !key) {
+				throw new Error(`groupKeys[${i}]: named form requires a non-empty string "key" (got ${JSON.stringify(key)})`);
+			}
+			if (!Number.isFinite(cardinality) || cardinality < 1) {
+				throw new Error(`groupKeys[${i}] ("${key}"): named form requires a "cardinality" >= 1 (got ${JSON.stringify(cardinality)})`);
+			}
+			if (events !== undefined && !Array.isArray(events)) {
+				throw new Error(`groupKeys[${i}] ("${key}"): "events" must be an array of event names when present (got ${typeof events})`);
+			}
+			return events && events.length ? [key, cardinality, events] : [key, cardinality];
+		}
+		throw new Error(`groupKeys[${i}]: expected a [key, cardinality] tuple or a { key, cardinality } object (got ${typeof entry})`);
+	});
+}
+
 // ── Advanced Feature Validation Functions ──
 
 // P2.5 (v1.6): churnRate / activeWindow / soupOverride are declared Persona

package/lib/generators/funnels.js

@@ -376,7 +376,10 @@ export async function makeFunnel(context, funnel, user, firstEventTime, profile
 		if (Number.isFinite(lastTimeMs)) {
 			const IDENTITY_KEYS = ['user_id', 'device_id', 'distinct_id', 'session_id', 'insert_id'];
 			const superPropKeys = Object.keys(superProps || {});
-			const groupKeyNames = (groupKeys || []).map(gk => Array.isArray(gk) ? gk[0] : gk).filter(Boolean);
+			// Validated config: group keys are always positional tuples here.
+			const groupKeyNames = /** @type {string[]} */ (
+				(groupKeys || []).map(gk => Array.isArray(gk) ? gk[0] : gk).filter(gk => typeof gk === 'string')
+			);
 			const numToInject = chance.integer({ min: 1, max: 2 });
 			for (let i = 0; i < numToInject; i++) {
 				const excName = chance.pickone(funnel.exclusionEvents);

package/lib/hook-helpers/mutate.js

@@ -53,12 +53,27 @@ export function dropEventsWhere(events, predicate) {
  * Scale the count of events with name `eventName` in `events` by `factor`. Mutates
  * `events` in place.
  *
- * - factor > 1: clones existing matches with small monotonic time offsets (1s steps)
- *   so duplicates land just after their source. Returns positive integer = clones added.
+ * - factor > 1: clones existing matches. Returns positive integer = clones added.
  * - factor < 1: drops matches at random using the seeded RNG. Returns negative
  *   integer = -dropped.
  * - factor === 1 or no matches: no-op, returns 0.
  *
+ * ## WARNING — the default spread cannot move frequency or session metrics
+ *
+ * By default clones land 1 second after their source (monotonic 1s steps). One
+ * second is not enough to create a new distinct active day, and not enough to
+ * open a new session under Mixpanel's 30-minute inactivity gap. So a default
+ * `scaleEventCount` call raises **event volume only**. It does NOT raise:
+ *
+ *   - active days per user / DAU / stickiness (DAU÷MAU)
+ *   - sessions per user or session count
+ *   - "days active" or frequency-of-use reports
+ *   - retention, which is computed on distinct days
+ *
+ * If your story claims any of those, pass `{ spreadDays: N }` to scatter clones
+ * across the following N days, or use `injectOnNewDays` — the helper built for
+ * exactly this.
+ *
  * Note: cloned events get a FRESH `insert_id` — they must not inherit the
  * source's, and leaving it blank is not safe either (the importer content-hashes
  * missing ids, so identical clones collide and Mixpanel dedupes them away).
@@ -66,21 +81,40 @@ export function dropEventsWhere(events, predicate) {
  * @param {Array<{event:string,time:string|number,insert_id?:string}>} events
  * @param {string} eventName
  * @param {number} factor
+ * @param {{spreadDays?: number}} [options] - `spreadDays`: scatter clones uniformly
+ *   over `[source_time, source_time + spreadDays]` instead of stepping 1s at a time.
+ *   Use this when the clones must land on new calendar days or in new sessions.
+ *   Clones that land past `FIXED_NOW` are dropped by the engine's future-time guard,
+ *   so a large `spreadDays` on late-window events yields fewer surviving clones than
+ *   the return value reports.
  * @returns {number}
  */
-export function scaleEventCount(events, eventName, factor) {
+export function scaleEventCount(events, eventName, factor, options = {}) {
 	if (!events || !eventName || typeof factor !== 'number' || factor === 1) return 0;
+	const { spreadDays } = options || {};
+	const spreadMs = (Number.isFinite(spreadDays) && spreadDays > 0)
+		? spreadDays * 86_400_000
+		: 0;
 	if (factor > 1) {
 		const matches = events.filter(e => e && e.event === eventName);
 		if (!matches.length) return 0;
 		const additionalNeeded = Math.round(matches.length * (factor - 1));
+		const chance = spreadMs ? getChance() : null;
 		let added = 0;
 		for (let i = 0; i < additionalNeeded; i++) {
 			const src = matches[i % matches.length];
 			const baseMs = toMs(src.time);
-			const newTime = Number.isFinite(baseMs)
-				? new Date(baseMs + (i + 1) * 1000).toISOString()
-				: src.time;
+			let newTime;
+			if (!Number.isFinite(baseMs)) {
+				newTime = src.time;
+			} else if (spreadMs) {
+				// Seeded uniform offset across the spread window. Floor at 1s so a
+				// clone never collides exactly with its source's timestamp.
+				const offset = Math.max(1000, Math.round(chance.floating({ min: 0, max: spreadMs })));
+				newTime = new Date(baseMs + offset).toISOString();
+			} else {
+				newTime = new Date(baseMs + (i + 1) * 1000).toISOString();
+			}
 			const clone = stampFreshInsertId({ ...src, time: newTime });
 			events.push(clone);
 			added++;

package/lib/orchestrators/mixpanel-sender.js

@@ -100,6 +100,7 @@ async function _sendToMixpanel(context) {
 	const commonOpts = {
 		region,
 		fixData: true,
+		matchMixpanelDefaults: true,
 		v2_compat: true,
 		verbose: false,
 		forceStream: true,

package/lib/templates/abbreviated.d.ts

@@ -37,15 +37,16 @@ export interface Dungeon {
     /** Properties that change for users or groups over time (Slowly Changing Dimensions). */
     scdProps?: Record<string, SCDProp>;
     
-    /** Defines group entities, like companies or teams, and how many of each to create. */
-    groupKeys?: [string, number, string[]?][]; // [key, numGroups, optional_events_for_group]
-    
+    /**
+     * Defines group entities, like companies or teams, and how many of each to create.
+     * Tuple form: `[key, numGroups]` or `[key, numGroups, [events]]`.
+     * Named form: `{ key, cardinality, events? }`. Both are accepted.
+     */
+    groupKeys?: ([string, number, string[]?] | { key: string; cardinality: number; events?: string[] })[];
+
     /** Properties that define the characteristics of the groups defined in groupKeys. */
     groupProps?: Record<string, Record<string, ValueValid>>;
 
-    /** Events that are attributed to a group entity rather than an individual user. */
-    groupEvents?: GroupEventConfig[];
-    
     /** Static data tables (e.g., product catalogs) that can be referenced in events. */
     lookupTables?: LookupTableSchema[];
 
@@ -134,25 +135,6 @@ interface SCDProp {
 }
 
 
-/**
- * Defines an event that is attributed to a group and occurs on a regular schedule.
- * (e.g., a monthly subscription charge for a company).
- */
-interface GroupEventConfig extends EventConfig {
-    /** How often the event occurs (in days). */
-    frequency: number; 
-    
-    /** The group key this event is associated with (e.g., "company_id"). */
-    group_key: string; 
-    
-    /** If true, a random user within the group is also associated with the event. */
-    attribute_to_user: boolean; 
-    
-    /** The number of entities in this group. */
-    group_size: number; 
-}
-
-
 /**
  * Defines the schema for a static lookup table, which can be used to enrich event data.
  * For example, a "products" table could hold details about product IDs.

package/lib/templates/schema.d.ts

@@ -17,7 +17,7 @@ type ValueValid = Primitives | Primitives[] | FunctionCall;
  * This is the high-level object you will be constructing.
  *
  * REQUIRED fields: events, funnels, superProps, userProps
- * OPTIONAL fields: scdProps, groupKeys, groupProps, groupEvents
+ * OPTIONAL fields: scdProps, groupKeys, groupProps
  */
 export interface Dungeon {
     /** REQUIRED: A list of all possible events that can occur in the simulation. */
@@ -35,14 +35,15 @@ export interface Dungeon {
     /** OPTIONAL: Properties that change for users or groups over time (Slowly Changing Dimensions). Only include when properties explicitly change over time. */
     scdProps?: Record<string, SCDProp>;
 
-    /** OPTIONAL: Defines group entities (companies, teams). Format: [["group_key", count], ...]. ONLY for B2B/SaaS scenarios. */
-    groupKeys?: [string, number][];
+    /**
+     * OPTIONAL: Defines group entities (companies, teams). ONLY for B2B/SaaS scenarios.
+     * Tuple form: `[["group_key", count], ...]`.
+     * Named form: `[{ key: "group_key", cardinality: count, events: [...] }, ...]`.
+     */
+    groupKeys?: ([string, number] | { key: string; cardinality: number; events?: string[] })[];
 
     /** OPTIONAL: Properties for groups defined in groupKeys. ONLY include if groupKeys is defined. */
     groupProps?: Record<string, Record<string, ValueValid>>;
-
-    /** OPTIONAL: Events attributed to groups on a schedule (e.g., monthly billing). Rarely needed. */
-    groupEvents?: GroupEventConfig[];
 }
 
 
@@ -146,28 +147,6 @@ interface SCDProp {
 }
 
 
-/**
- * Defines an event attributed to a group on a regular schedule.
- * Example: monthly subscription charges, weekly reports, etc.
- *
- * This is rarely needed - only use for B2B scenarios with recurring group-level events.
- */
-interface GroupEventConfig {
-    /** REQUIRED: The name of the event. */
-    event: string;
-
-    /** REQUIRED: How often the event occurs (in days). e.g., 30 for monthly. */
-    frequency: number;
-
-    /** REQUIRED: The group key this event belongs to (e.g., "company_id"). */
-    group_key: string;
-
-    /** OPTIONAL: If true, a random user in the group is also attributed to the event. */
-    attribute_to_user?: boolean;
-
-    /** OPTIONAL: Properties for this event. */
-    properties?: Record<string, ValueValid>;
-
-    /** OPTIONAL: Relative frequency of this event. */
-    weight?: number;
-}
+// v1.6.4 — `GroupEventConfig` removed. It was a declared-only stub that nothing in
+// `lib/` ever read. To scope an event to a group, list its name in that group key's
+// `events` array instead.

package/lib/utils/utils.js

@@ -1649,7 +1649,6 @@ function wrapFunc(obj, func, recursion = 0, parentKey = null, grandParentKey = n
 	"userProps",
 	"scdProps",
 	"mirrorProps",
-	"groupEvents",
 	"groupProps"
 ]) {
 	if (recursion === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.6.3",
+	"version": "1.6.5",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",

package/types.d.ts

@@ -13,22 +13,56 @@ type Primitives = string | number | boolean | Date | Record<string, any>;
 export type ValueValid = Primitives | ValueValid[] | (() => ValueValid);
 
 /**
- * v1.5.1 — credentials sub-object. Groups Mixpanel project credentials. Top-level
- * `token` / `region` / etc. remain functional as a back-compat alias; when both
- * are set, the top-level value wins with a verbose warning.
+ * Mixpanel data residency region. Matches the set `mixpanel-import` accepts.
+ */
+export type Region = 'US' | 'EU' | 'IN';
+
+/**
+ * v1.6.4 — named-object form of a group key. Equivalent to the positional tuple
+ * `[key, cardinality]` / `[key, cardinality, events]`, which stays supported.
+ * The validator normalizes this to the tuple form.
+ */
+export interface GroupKeyObject {
+    /** The group key property name (e.g. `"company_id"`). */
+    key: string;
+    /** How many distinct group entities to generate. */
+    cardinality: number;
+    /** Event names that carry this group key. Omit or leave empty for all events. */
+    events?: string[];
+}
+
+/**
+ * The normalized positional form of a group key. Everything downstream of
+ * `validateDungeonConfig` sees this shape — the validator converts
+ * `GroupKeyObject` entries for you.
+ */
+export type GroupKeyTuple = [string, number] | [string, number, string[]];
+
+/**
+ * A group analytics key as an author may write it: either the legacy tuple form
+ * or the named-object form. `result.validatedConfig.groupKeys` is always
+ * `GroupKeyTuple[]`.
+ */
+export type GroupKey = GroupKeyTuple | GroupKeyObject;
+
+/**
+ * v1.5.1 — credentials sub-object. **This is the canonical form.** Groups Mixpanel
+ * project credentials. Top-level `token` / `region` / etc. remain functional as a
+ * back-compat alias; when both are set, the top-level value wins with a verbose
+ * warning. Emit one form or the other, never both.
  */
 export interface DungeonCredentials {
     token?: string;
-    region?: 'US' | 'EU' | 'IN';
+    region?: Region;
     serviceAccount?: string;
     serviceSecret?: string;
     projectId?: string;
 }
 
 /**
- * v1.5.1 — switches sub-object. Groups data-shape booleans. Top-level keys
- * remain functional as a back-compat alias; same precedence rules as
- * `DungeonCredentials`.
+ * v1.5.1 — switches sub-object. **This is the canonical form.** Groups data-shape
+ * booleans. Top-level keys remain functional as a back-compat alias; same
+ * precedence rules as `DungeonCredentials`. Emit one form or the other, never both.
  */
 export interface DungeonSwitches {
     hasLocation?: boolean;
@@ -42,13 +76,13 @@ export interface DungeonSwitches {
     hasBrowser?: boolean;
     isAnonymous?: boolean;
     alsoInferFunnels?: boolean;
-    hasAttributionFlags?: boolean;
 }
 
 /**
- * v1.5.1 — identity sub-object. Groups identity-model knobs. Top-level
- * `avgDevicePerUser` / `sessionTimeout` remain functional as a back-compat
- * alias.
+ * v1.5.1 — identity sub-object. **This is the canonical form.** Groups
+ * identity-model knobs. Top-level `avgDevicePerUser` / `sessionTimeout` remain
+ * functional as a back-compat alias; when both are set, the top-level value wins
+ * with a verbose warning. Emit one form or the other, never both.
  *
  * `hasAnonIds` is DEPRECATED — when present here, it maps to
  * `avgDevicePerUser: 1` with a verbose warning. Use `avgDevicePerUser` instead.
@@ -143,8 +177,8 @@ export interface Dungeon {
     avgEventsPerUserPerDay?: number;
     /** Output format for files written to disk. */
     format?: "csv" | "json" | "parquet" | string;
-    /** Mixpanel data residency region. */
-    region?: "US" | "EU";
+    /** Mixpanel data residency region. Back-compat alias for `credentials.region`. */
+    region?: Region;
     /** User generation concurrency. Default: 1. Values > 1 break seed reproducibility and provide no performance benefit (CPU-bound). */
     concurrency?: number;
     /**
@@ -186,6 +220,12 @@ export interface Dungeon {
      * @see EventConfig.isAttributionEvent
      */
     hasCampaigns?: boolean;
+    /**
+     * @internal Derived, not settable. The validator unconditionally sets this to
+     * `events.some(e => e.isAttributionEvent)`. Read it off `result.validatedConfig`;
+     * setting it on an input config has no effect.
+     */
+    hasAttributionFlags?: boolean;
     /** If true, generates ad spend data (impressions, clicks, cost). */
     hasAdSpend?: boolean;
     /** If true, device pool includes iOS devices. */
@@ -196,7 +236,7 @@ export interface Dungeon {
     hasDesktopDevices?: boolean;
     /** If true, events include browser properties. */
     hasBrowser?: boolean;
-    /** If true (default), writes output files to ./data/. Can also be a directory path string or gs:// URI. */
+    /** If true, writes output files to ./data/. Can also be a directory path string or gs:// URI. Default: `false` — data is returned in memory only. */
     writeToDisk?: boolean | string;
     /** If true, deletes all written files (local and GCS) at end of run regardless of import success/failure. Default: false. */
     cleanup?: boolean;
@@ -289,12 +329,19 @@ export interface Dungeon {
     scdProps?: Record<string, SCDProp>;
     /** Mirror dataset definitions: create transformed copies of event data. */
     mirrorProps?: Record<string, MirrorProps>;
-    /** Group analytics keys. Format: [key, numGroups] or [key, numGroups, [associatedEvents]]. */
-    groupKeys?: [string, number][] | [string, number, string[]][];
+    /**
+     * Group analytics keys. Two interchangeable forms:
+     *
+     * - Tuple (legacy): `[key, numGroups]` or `[key, numGroups, [associatedEvents]]`
+     * - Named object (v1.6.4, preferred): `{ key, cardinality, events? }`
+     *
+     * The validator normalizes the named form to the tuple form, so hooks and the
+     * verifier always see tuples. Mixing both forms in one array is allowed.
+     * An empty or omitted `events` list means every event carries the group key.
+     */
+    groupKeys?: GroupKey[];
     /** Properties for each group key's entities. */
     groupProps?: Record<string, Record<string, ValueValid>>;
-    /** Group-level events (stub — not yet implemented). */
-    groupEvents?: GroupEventConfig[];
     /** Lookup table definitions for dimension tables. */
     lookupTables?: LookupTableSchema[];
     /** TimeSoup configuration: shapes intra-week and intra-day rhythm (peaks, deviation, DOW/HOD weights). Pair with `macro` for big-picture trend control. */
@@ -370,7 +417,11 @@ export interface Dungeon {
      * **Incompatibility with `engagementDecay`:** decay drops events from late picked days,
      * eroding the effective active-day count below the configured target. Use one or the
      * other; if you need both, write decay logic in an `everything` hook scoped to specific
-     * cohorts. See HOOKS.md §2.5.
+     * cohorts. See HOOKS.md §2.5. v1.6.4: the validator warns unconditionally (not gated
+     * behind `verbose`) when both are set.
+     *
+     * **Precedence with `retentionCurve`:** the curve WINS. When `retentionCurve` is set,
+     * the active-day plan is built from the curve and this value is ignored entirely.
      *
      * Safe range: `[1, numDays * 0.5]`. Above 50% of `numDays` defeats the concentrator
      * purpose; the v1.5 validator strict-clamps to `floor(numDays * 0.5)` with a warning.
@@ -928,12 +979,10 @@ export interface EventConfig {
     isAttributionEvent?: boolean;
 }
 
-export interface GroupEventConfig extends EventConfig {
-    frequency: number; //how often the event occurs (in days)
-    group_key: string; //the key that the group is based on
-    attribute_to_user: boolean; //if true, the event also goes to a user
-    group_size: number; //the number of users in the group
-}
+// v1.6.4 — `GroupEventConfig` and `Dungeon.groupEvents` were removed from the
+// public types. They were a declared-only stub: nothing in `lib/` ever read them,
+// and no shipped dungeon set them. Group-scoped events are modeled today by
+// listing the event name in a `groupKeys` entry's `events` array.
 
 /**
  * the generated event data